Understanding Manual Pages

SYNOPSIS

Nearly every aspect of the UNIX operating system is described in online documentation called "manual pages". But finding the information you need and making sense out of it can be difficult tasks, even for experienced UNIX users. This page offers a basic explanation of how to search for, find, and use manual pages.

ORGANIZATION

The manual pages are typically grouped into eight numbered sections and several lettered sections. The numbered sections are the same on most UNIX systems, but the lettered ones vary. Sections may be further subdivided by appending a letter after the section. For example section 3f might contain Fortran library routines.

1 User Commands: Programs and applications useful to the average user. There is usually one entry for each command and/or group of related commands.
2 System Calls: Programming interfaces to the operating system itself. These are C calls that control the allocation and use of system resources. The introduction to this section usually contains a good overview of how the operating system works and defines many important terms used in UNIX. "man 2 intro" is required reading for all UNIX programmers.
3 Libraries: Programming subroutines. Every C library function from standards like printf through the most obscure X Windows call belongs here. If other languages are installed, their library functions should also be listed in this section.
4 Devices and Special Files: System resources such as memory, hard disks, graphics displays, etc., are referred to as devices. Their control, allocation, and use at the operating system level is described here. System programmers need to refer to this section often.
5 File Formats: This section primarily describes the formats of operating system related files. Formats for application data files, when given, are ususally found in the pages for the application.
6 Games: Manual pages for most games, demonstrations, and other "non-productive" programs are usually listed here. Note that some games do not have manual pages or may be listed in other sections.
7 Miscellaneous: A few random bits that don't go anywhere else. Mostly text processing macro sets.
8 System Administration: These pages describe all of the various programs, utilities, daemons, and a few of the concepts that make the system run. These are good pages to look through to get an idea of day to day system maintenance.
l Local: Manual pages about the local system. Descriptions of usage policies, administrative contacts, special local software, and other information unique to the particular installation should be in this section. The page you are reading is derived from a local section manual page on my machine.
n New: Newly installed software. New packages are sometimes listed in this section for some period of time before being moved to their permanent section. But very few systems (none that I know of) follow this practice.
o Old: Obsolete documentation or documentation for obsolete programs. Documentation is often available for features or programs no longer supported by the current system. Bored sysadmins may choose to move such pages to this section, but few do.

The only guaranteed way to get a complete list of the manual pages is to go to the directories in which they are stored. Most systems keep their manual pages in /usr/man, /usr/share/man, /usr/local/man, or /usr/local/share/man. There may also be separate directories for large software packages, e.g. /usr/X11/man, or /opt/apache/man. Looking in these directories, you will notice that there is one subdirectory for each section and therein one file for each manual entry. The directories searched by the man program can be changed by setting the MANPATH environment variable.

USAGE

The basic form for the man command is

man topic

The man program searches through manual pages and displays the first page whose name matches topic. Note that there are likely to be multiple man directories and there may be more than one section with an entry matching topic.

To see a listing of all the sections in which topic appears, use the whatis command:

whatis topic

Some systems use man -f to perform this function:

man -f topic

Usually man page names are followed by a number or letter in parenthesis. That symbol denotes the section of the page. To specify the section in which you wish man to search, add the section symbol to the command line before the topic:

man [section] command

For example

man 7 man

will show you the section 7 page which describes how to create manual pages. Without the section designation, you would get the section 1 page which describes the man command itself.

Each page has a summary line as well as a name. If you aren't sure of the name, you can search those summary lines for a keyword. This is the first step to finding a page whose name you don't know. To do a keyword search, use the -k option:

man -k keyword

There is no way to directly tell man how to resolve the ambiguity of a name which appears in the same section in two different directories. It will simply take whichever one appears first in the MANPATH environment variable or its own internal search path. This situation usually occurs when there is a local installation superceding a standard command. For example, my site runs a perl version of the man program which has its manual page in /usr/local/man/man1 while the page for the standard program is in /usr/man/man1. For more information on how man decides which page to show, see the man (1) manual page.

Movement

Once man finds and formats the manual page you specified, it passes the result to a paging program which actually displays it. Most systems default to using the more command. Within more, the space bar will move you forward one page. You can search for a keyword by typing a slash "/" followed by the keyword. The "n" key repeats the last search. See the more manual page for more information. More enlightened systems use the less command for paging, which has many extra features including the ability to scroll up and down the page. Check for a less man page if your system supports its use. If you are on an X Windows compatible display, you can also look for xman or tkman for graphical interfaces.

FORMAT

Now that you know what manual pages are, there is the all important matter of understanding how to read them. This can be a tricky task and many people give up in frustration. The most important thing to remember about manual pages is don't give up. Even if you don't understand most of what is being said, at least skim through the whole thing. As you will see on my sample manual page, the most useful information often appears at the end of the page.

BUGS

If you are unfortunate enough to be using Solaris 2.x you will find that the manual pages are organized differently and that the man command works differently. Most notably, many of the sections are physically divided into subsections by one letter extensions. You must specify a page's exact subsection in order to find it (Solaris 2.x does not allow you to cover an entire section).

The man command itself requires a "-s" switch to specify the section:

man -s section topic

For example,

man -s 3r nanosleep

Finds the nanosleep function of the realtime library.