The OpenBSD BASED Challenge Day 6

by Root BSD

Learning the man(1) page system, and apropos(1)!

A funny joke I've heard about retail is that in the United States, the customer is always right. In France, the customer is king. In Japan, the customer is god! Well, when a unhappy patron to a French shop complained about the service, they reminded the store owner that in France the customer is king! The owner then replied, “Madame, this is Paris. We have cut off the heads of our kings!”

The manual pages in OpenBSD are definitely king, and they're always right. If not, it is considered a bug. So I wanted to make sure I knew more about the manual system, and how I could make it more useful to me in my quest to learn the OpenBSD base system.

What's great is in OpenBSD the manpages have their own manpage!

$ man man

This will give you a rundown of how to use the manual page system. Pages may be viewed by category (section) or machine architecture (subsection). You are first met with a group of command line options for specific use cases and queries. For example

$ man -c cat | col -b > cat

Will pipe the standard output of cat(1) to col(1), which will remove it's markup and save it to a plain text file called cat. The command man -f is the same as whatis(1)

man -f pkg_add pkg_add(1) - install or update software packages whatis pkg_add pkg_add(1) - install or update software packages

The -h option will display the SYNOPSIS section of the page only. The -k option is the same as apropos(1). man -k pkg will display a list of every manual page that has “pkg” in it's title, apropos will do the same exact thing with apropos pkg

The manual pages are broken up in sections, numbered 1-9

1 General commands (tools and utilities). 2 System calls and error numbers. 3 Library functions. 3p perl(1) programmer's reference guide. 4 Device drivers. 5 File formats. 6 Games. 7 Miscellaneous information. 8 System maintenance and operation commands. 9 Kernel internals.

The -s option specifies a section to look at for man page listing. For example the -k option I discussed earlier can be combined with -s. man -k -s 3p pkg will only look in the perl(1) programmer's reference guide for pages with “pkg” in the title.

Another cool thing I learned is the MANPAGER environment variable. By default, less(1) is used for the manuals pagination (how it's displayed). But you can specify any program and use the -T option (defined in the mandoc(1) manpage) to format the manual to something that be understood by your desired MANPAGER. For example, MANPAGER=links man -T html ls will display the manual page for the ls(1) command in html on the links terminal web browser.

The following output formats are supported, ascii, html, the default of locale, man, markdown, pdf, ps, tree, and utf8. Yes, that's right, you can view your manual pages in you favorite pdf viewer!

man -T ascii -O width=65 pledge | col -b

This will ignore any UTF-8 characters, remove markup and change the width of the text body. This can be useful for quoting manpage entries in emails, blogs, etc.

Now on to apropos(1), pronounced a-pruh-pow. A manpage database is generated by makewhatis(8), apropos(1) and whatis(1) will query that database to help you search and list manual pages by section and description. For example,

apropos -s 1 . | grep "files" | less

This command will display the titles and descriptions of every manual page in section 1 (general commands (tools and utilities)) that have the word “files” in their descriptions and pipe the list into less for easy browsing. This would be a fantastic way to really explore and learn about all the different commands and utilities that are in the OpenBSD base system, as I don't know them all!

apropos(1) command line options are very similar to the man(1) command line options, however apropos(1) can even search using expressions and macros, a use case a little too advanced for my current needs, but really cool none the less, like this example from the apropos(1) manpage,

“Search for manuals in the library section mentioning both the “optind” and the “optarg” variables:”

$ apropos -s 3 Va=optind -a Va=optarg getopt(3) - get option character from command line argument list getopt_long, getopt_long_only(3) - get long options from command line argument list

Well that's enough for today. I definitely learned a lot about using OpenBSD's manual pages system and the apropos(1) command. This is a good foundation for digging deeper into the base system and all that it has to offer. As always, I hoped you learned something new. Happy hacking in OpenBSD!


An example usage of the apropos(1) command piped to grep(1).