Man Pages

Man pages, short for "manual," are the original way of presenting UNIX documentation. While man pages have a reputation for being obtuse, difficult to read, or incomplete, the OpenBSD manual pages are quite informative.

The OpenBSD team considers man pages to be the final word in system documentation. They are expected to be correct. Errors in man pages are considered serious bugs and are dealt with as quickly as possible and as forcefully as necessary. As such, you can expect that the man page will be correct and complete. Man pages should be your first line of attack in learning how something works.

A man page is not a tutorial. It explains how something works, not what to type to make particular effects happen. You need to be able to assemble the pieces given by the man page into the tool that you want. If you want a tutorial you need to look at the FAQ, articles on third-party websites, and this book. If you find a tutorial that does exactly what you want, be sure to understand what you're doing as well as what you're typing; otherwise, you'll be stuck when something breaks.

Manual Sections

The OpenBSD manual is divided into nine sections. Each man page appears in only one section. These sections are sometimes called volumes, a relic of the day when the manual was small enough to realistically be printed and distributed. Roughly speaking, these sections are:

1	General Commands
2	System Calls and Error Numbers
3	C Libraries
3p	Perl Libraries
4	Devices and Device Drivers
5	File Formats and Configuration Files
6	Game Instructions
7	Miscellaneous Information
8	System Maintenance Commands
9	Kernel Internals

When reading man pages, you'll usually see the section number in parenthesis after the command, like this: panic(9). This represents both the name of the command, library, or interface (panic) and the section where the man page for that can be found (9). When you see something in this format, you can check the man page for detailed information. Almost every topic has a man page. Some commands or topics have multiple man pages of the same name, in different sections.

You can view man pages with man(1). If you know the section number, give it and then the name of the program. For example, to see the manual page for the standard network utility ping(8), enter:

 # man ping 

In response, you should see something like this:

 PING(8)         OpenBSD System Manager's Manual      PING(8) NAME    ping - send ICMP ECHO_REQUEST packets to network hosts SYNOPSIS    ping [-DdfLnqRrv] [-c count] [-I ifaddr] [-i wait] [-l preload] [-p      pattern] [-s packetsize] [-t ttl] [-w maxwait] host DESCRIPTION  ping uses the ICMP protocol's mandatory ECHO_REQUEST datagram to elicit  an ICMP ECHO_REPLY from a host or gateway. ECHO_REQUEST datagrams  (``pings'') have an IP and ICMP header, followed by a ``struct timeval''  and then an arbitrary number of ``pad'' bytes used to fill out the pack-  et. The options are as follows:  -c count      Stop after sending count ECHO_REQUEST packets.  -D   Set the Don't Fragment bit.  -d   Set the SO_DEBUG option on the socket being used. 

You can now learn huge amounts about pinging hosts on the Internet, just by understanding this document. If you need more information, you can look at some of the other man pages referenced by ping(8) to build an in-depth picture of the system.

Navigating Man Pages

Once you're in a man page, hitting the space bar will take you forward one full screen. If you don't want to go that far, hitting the ENTER key will scroll down one line. If you go to far, and want to back up, hitting "b" will take you back one screen. To search within a man page for a word, type / followed by the word. You'll jump down to the first appearance of that word. Typing n subsequently will jump you to the next occurrence of that word.

This assumes that you're using the default OpenBSD pager, more(1). If you're using a different pager, you'll have to use the syntax that pager requires. If you don't know what a pager is, then don't worry about it.

Finding Man Pages

One frequent complaint about man pages is that it's difficult to find a man page that covers a topic you're interested in. There's certainly truth to this — many OpenBSD questions can be answered by a simple "read man such-and-such." The problem is finding the correct such-and-such for what you want to know. You can perform basic keyword searches with apropos(1) and whatis(1). Apropos(1) searches for any man page name or description that includes the word you're interested in. Whatis(1) only matches whole words. For example, if you are interested in the ping command, you might try:

 # apropos ping Net::Ping (3p) - check a remote host for reachability Text::Wrap (3p) - line wrapping to form simple paragraphs boot (8/Alpha) - Alpha system bootstrapping procedures boot (8/Amiga) - amiga-specific system bootstrapping procedures ... 

Well, the first command looks somewhat like the standard ping command, but it's in section 3p of the manual — it's a Perl library! The next three matches have nothing to do with ping, but if you examine them closely you'll see that the letters "ping" appear in each of them, encapsulated within the words "wrapping" and "bootstrapping." Depending on the term you're looking for, apropos can give you far too much irrelevant information.

A similar search with whatis(1) gives the following.

 # whatis ping ping (8) - send ICMP ECHO_REQUEST packets to network hosts # 

That's more like it! You may find that such a narrow search isn't enough for some terms, however. Experiment with apropos(1) and whatis(1) until you're comfortable with them, and you should be able to find just about any topic you like. Between the search functions, and the SEE ALSO sections within man pages (see "Man Page Contents"), you can generally find the information you need.

Note

The apropos command is the same as "man -k" (for "keyword search"), and the whatis command is the same as "man -f" (for "full word search").

Section Numbers and Man

You might find cases where the man page you want has the same name as a man page in some other section of the manual, especially as you add additional software to your OpenBSD machines. In those cases, specifying the section number is the only way to get the exact page you want. Without giving a section number, you'll get the man page of that name with the lowest section number. You can specify a section number before the name of the command, i.e.:

 # man 8 ping 

While this example is rather trivial (a "ping" man page only appears in one section of the manual), we'll look in some other cases where it isn't.

Man Page Contents

Man pages have a variety of section headers. While just about any subsection can appear in a man page, several are standard. (See mdoc(7) for a partial list of standard section names, as well as other man page standards.) Like book authors, man page authors try to arrange their content in a manner that makes sense for the program they're describing. Still, you will see some standard headings.

• NAME tells you the names of a program or utility. Some programs have multiple names — for example, the vi(1) text editor is also available as view(1) or ex(1). The man page lists all of these names.

• SYNOPSIS lists the possible command-line options and their arguments, or how a library call is accessed. Frequently, you'll find that this header is enough to spark your memory and remind you of a flag you've used before that caused the program to behave appropriately.

• DESCRIPTION contains a brief synopsis of the program or feature. The contents of this section vary depending on the topic, as programs, files, and interfaces all have very different documentation requirements.

• OPTIONS describes a program's command-line options and their effects.

• BUGS describes known failure conditions, weird behavior, and how to make the program fail in general. This is a great time-saver. Many times I've had a problem with a command only to find that behavior, and sometimes a workaround, listed in the BUGS section. Honesty is a wonderful thing in computing products.

• SEE ALSO is traditionally the last section in a man page. OpenBSD is an interrelated whole; every command has ties to other commands. In an ideal world you would read every man page and be able to hold an integrated image of the system in your head. Because most of us cannot do that, this section provides directions to related man pages.

You now know what you need to navigate the integrated help system. Now let's look at some information resources elsewhere than your computer.

Man Pages on the Web

The manual pages are also available on www.OpenBSD.org and its mirrors. While your system has only the man pages for your release and architecture of OpenBSD, the manual available on the website includes all previous versions of OpenBSD and all architectures. If you want to see differences in the boot process between i386 and Alpha platforms, you can easily compare the manual pages on the website. Similarly, you can see which release certain commands were first documented in and how those commands have changed over time.