Reading Man Pages
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
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 SYNOPSIS logout DESCRIPTION Terminates the current login shell and ends the associated session. SEE ALSO login(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.