Understanding Manual Pages
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.
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
- 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
- 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.
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
- 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.
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.
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.
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
- man -s 3r nanosleep
finds the nanosleep function of the realtime library.