Reading Man Pages

Man pages (short for manual) provide documentation for many Unix topics and commands. They are often a good reference for beginners, but they are written and maintained by programmers so they vary widely in how useful they can be. Jon Lasser takes you on a handy trip through the peaks and valleys of perusing man pages.

From the author of

From the author of

Man pages (man is short for manual, of course) are the standard
for Unix documentation. They are available online on any Unix system, and some
systems even include paper copies of them. While other forms of documentation
have begun to supplant man pages, even these substitutes hew fairly close to
the same syntax and style. To understand man pages, you have to see them first.
In its simplest form, you can display a man page by typing man ManPageIWantToRead
at your prompt.

One of the most important commands to learn is logout, because if you
don't sign off of the system when you are finished, anybody else can read your
files and send mail as you. This is a common problem on multiuser machines,
especially at shared workstations or in computer labs at universities. Often,
malicious people will send embarrassing or insulting mail from a machine where
the legitimate user has forgotten to log out. This, obviously, won't do, so
pretend you logged in to a Unix box and typed the one command your guru told
you: man logout. Something quite like the following might come up on
your screen:1

LOGOUT(1) Unix Users Guide
NAME
logout - exit from a login shell
SYNOPSISlogout
DESCRIPTION
Terminates the current login shell and ends the associated session.
SEE ALSOlogin(1)

The first thing to notice about this man page is its header. You should note
that it includes the name of the program, a number in parentheses after the
program name (the manual section), and the name of the notional manual that
"contains" the page. (Of course, man pages aren't real pages bound
in a real book, so in reality no manual physically contains the page.)

Below this header, you should notice that the man page is divided into several
elements. Some of these segments, such as the name, the synopsis, and the description,
should be present in every man page. Others, such as see also might not be present
on a given page.

The name segment contains not only the name of the command, as one would assume,
but also a very brief description of the purpose of the command. This is because
the name is easily searchable, as you'll soon see. The description provided
here might not be helpful to beginning users (or at all!), but any search capabilities
are better than none.

Although it's not obvious in this case, the synopsis is the most critical portion
of the man page: It shows all the modifiers that can be applied to the command.
In the case of logout, there are no modifiers: The only thing you can
do is type logout. The synopsis has a special, well-defined syntax
that I will examine more closely.

The description might or might not be useful. Remember that these pages were
written by programmers, who generally can't remember what it was like to be
a novice even when they try. In this case, between the name of the command and
both the short and long descriptions, it should be possible to puzzle out what
the command does.

The name, synopsis, and description are present on nearly every man page. Other
common parts include a files portion, which lists files used or referenced by
the command, and an authors field, which lists the names and often the email
addresses of the responsible parties. Sometimes you'll see a bugs section, which
lists known problems with the command. Occasionally there will be a history,
which might explain why things were done the way they were done or perhaps describe
how this command is different from the older version of the command.

The man page for logout also contains a see also segment, which points
at the page for login. Note that, as in the header, there is a parenthesized
number. Man pages are grouped into numbered sections, each with its own purpose.

Manual Sections

The Unix manual is divided into ten sections. These are numbered one through
nine, plus a section named "n." For non-programmers, the important
sections are one and six. Section one contains what are broadly defined as user
commands, such as logout, login, and passwd. Section
five provides the documentation for a number of games. (In fact, many
games have their man pages in the first manual section, but this is one of the
many instances of sloppy documentation I warned you about earlier.) Section
four or five, depending on what flavor of Unix you have installed, contains
descriptions of configuration file formats, such as mail reader configurations.
You might find these useful when you want to know how to configure a particular
application or service.

Programmers might be interested in sections two and three of the manual, which
contain system calls and subroutines, respectively. Other manual
sections differ between Unix flavors but are generally reserved for system-level
commands and information.