"man pages" is short for "manual pages", and is one of the oldest forms of help documentation. To see help on a specific topic, just enter "man" followed by the name of the topic. For example, you can get help on the "man" utility itself by entering:
man man
man(1) man(1)
NAME
man - format and display the on-line manual pages
SYNOPSIS
man [-acdfFhkKtwW] [--path] [-m system] [-p string] [-C config_file] [-M pathlist] [-P
pager] [-S section_list] [section] name ...
DESCRIPTION
man formats and displays the on-line manual pages. If you specify section, man only
looks in that section of the manual. name is normally the name of the manual page,
which is typically the name of a command, function, or file. However, if name contains
a slash (/) then man interprets it as a file specification, so that you can do man
./foo.5 or even man /cd/foo/bar.1.gz.
See below for a description of where man looks for the manual page files.
OPTIONS
-C config_file
Specify the configuration file to use; the default is /etc/man.config. (See
man.config(5).)
-M path
Specify the list of directories to search for man pages. Separate the directo-
ries with colons. An empty list is the same as not specifying -M at all. See
SEARCH PATH FOR MANUAL PAGES.
In this example, you can see how a typical man page is set up.
First, there's the heading. This consists of the name of the command or system file, followed by the man page "section" to which this document belongs. (More on "sections" in a moment.)
Next, comes the name of the command or system file, followed by any related commands or files that may be described on the same page.
The third item consists of a synopsis of any applicable options and/or parameters.
Next up is a short description of the command.
Finally, you have detailed explanations of each of the options.
Many man pages will also have other sections, such as on how to report bugs, a list of man pages for other related commands or files, etc.
Location
Most of the time, you'll see man pages stored as compressed text files in the /usr/share/man directory. Some pages may also be stored in /usr/local/share/man. (Other locations are possible, if they've been defined in the "man" configuration file. More on that later.)
[donnie@localhost man]$ pwd
/usr/share/man
[donnie@localhost man]$ ls
bg de en fi hu ja man0p man2 man4 man7 mann pt ru sv
cs de.UTF-8 en_GB fr id jp man1 man3 man5 man8 nl pt_BR sk
da el es hr it ko man1p man3p man6 man9 pl ro sl
[donnie@localhost man]$ cd man1
[donnie@localhost man1]$ ls
:.1.gz jw.1.gz pnmsplit.1.gz
[.1.gz jwhois.1.gz pnmstitch.1.gz
411toppm.1.gz kbd_mode.1.gz pnmtile.1.gz
a2p.1.gz keychain.1.gz pnmtoddif.1.gz
a2ps.1.gz keyctl.1.gz pnmtofiasco.1.gz
a52dec.1.gz keytool.1.gz pnmtofits.1.gz
aafire.1.gz kill.1.gz pnmtojpeg.1.gz
aaxine.1.gz killall.1.gz pnmtopalm.1.gz
ab.1.gz kinit.1.gz pnmtopclxl.1.gz
ac.1.gz klist.1.gz pnmtoplainpnm.1.gz
access.1.gz knock.1.gz pnmtopng.1.gz
aconnect.1.gz knockd.1.gz pnmtopnm.1.gz
acyclic.1.gz kpsepath.1.gz pnmtops.1.gz
adcfw-log.1.gz kpsestat.1.gz pnmtorast.1.gz
addftinfo.1.gz kpsetool.1.gz pnmtorle.1.gz
. . .
. . .
Man Page Sections
There are nine categories, or sections, of man pages in common use. (You may also, at times, see other more specialized sections.)
Section Number
Description
1
Executable user programs and shell commands.
2
Kernel functions or system calls.
3
Library calls that are provided by program libraries.
4
Information on device files. (Mostly, this will cover files found in the /dev directory.
5
Descriptions of file formats. (This can include Message of the Day files, configuration files, keymap files, etc.
6
Games. (Of course, most newer games come with built-in help as part of the graphical interface.)
System administration utilities. (Most of these will require root privileges. Examples: fsck, fdisk, mount, renice, rpm, dpkg.)
9
Linux kernel documentation.
Some topics will have man pages in more than one section. If you enter the "man" command without also entering a section number, you'll see the page in the lowest-number section. To illustrate, let's take a look at the man pages for "passwd".
If you don't enter a section number, you'll get the man page for the "passwd" command.
man passwd
PASSWD(1) User utilities PASSWD(1)
NAME
passwd - update a user’s authentication tokens(s)
SYNOPSIS
passwd [-k] [-l] [-u [-f]] [-d] [-n mindays] [-x maxdays] [-w warndays] [-i inactive-
days] [-S] [--stdin] [username]
DESCRIPTION
Passwd is used to update a user’s authentication token(s).
. . .
. . .
There's also another "passwd" man page in the file format section.
man 5 passwd
PASSWD(5) Linux Programmer’s Manual PASSWD(5)
NAME
passwd - password file
DESCRIPTION
Passwd is a text file, that contains a list of the system’s accounts, giving for each
account some useful information like user ID, group ID, home directory, shell, etc.
Often, it also contains the encrypted passwords for each account. It should have gen-
eral read permission (many utilities, like ls(1) use it to map user IDs to user names),
but write access only for the superuser.
. . .
. . .
To see all of the man pages for a particular topic, use the "-a" option. You'll see the lowest-number man page first. When you exit that page, the next man page will appear.
man -a passwd
The "-aw" option will show you a list of all available man pages for a given topic. Here's an example that includes two of the specialized sections that we mentioned earlier. (i.e., the "3p" section and the "lp" section.)
You can view a specialized man page in the same manner that you'd view a regular man page.
man lp printf
By default, the "man" utility on modern Linux distros will pipe its output through the "less" utility. This way, you can page through the display and use all of the "less" search functions.
"less" Search Functions
/
Forward search
?
Backward search
n
Repeat previous search
Other options are available for more complex searches. See the "less" man page for more information.
Search Commands
These search commands will help you find which man page you need to look at for a particular topic.
"whatis" or "man -f"
These two commands are equivalent. Both will search for the name that you specify, and return the information from the "Name" portion of all of the appropriate man pages.
[donnie@localhost ~]$ whatis man
man (1) - format and display the on-line manual pages
man (1p) - display system documentation
man (7) - macros to format man pages
man [manpath] (1) - format and display the on-line manual pages
man.conf [man] (5) - configuration data for man
[donnie@localhost ~]$ man -f man
man (1) - format and display the on-line manual pages
man (1p) - display system documentation
man (7) - macros to format man pages
man [manpath] (1) - format and display the on-line manual pages
man.conf [man] (5) - configuration data for man
[donnie@localhost ~]$
Most Linux systems store information for these commands in a database file. This makes searches much faster than they would otherwise be. To update the database on a Red Hat-type system, use the "makewhatis" utility.
On a Debian/Ubuntu system, use the "mandb" command.
donnie@donnie-dual866:~$ sudo mandb
Purging old database entries in /usr/share/man...
Processing manual pages under /usr/share/man...
Purging old database entries in /usr/local/man...
mandb: can't update index cache /var/cache/man/oldlocal/index.db: No such file or directory
Processing manual pages under /usr/local/man...
Purging old database entries in /usr/local/share/man...
mandb: can't update index cache /var/cache/man/local/index.db: No such file or directory
Processing manual pages under /usr/local/share/man...
0 man subdirectories contained newer manual pages.
0 manual pages were added.
0 stray cats were added.
0 old database entries were purged.
donnie@donnie-dual866:~$
Note, though, that some Linux distros don't use a "whatis" database, and won't have a "makewhatis" or "mandb" utility, either.
"apropos" or "man -k"
These commands are also equivalent. They search through both the "Name" and "Description" sections of the man page database, making for a more thorough search than "whatis" and "man -f" can do.
These can be tricky to use, since a poorly-defined search can yield way more information than you can use. For example, if you enter. . .
apropos man
or man -k man
. . .you'll see man page listings for any man page that contains the string "man" in its name section. So, you'll see results for "management", "command", "manipulate", etc. You may need to combine these utilities with other tools, such as "grep", to help narrow your searches. The use of regular expressions can also help narrow your search. (The topic of regular expressions is rather complex, however, and is beyond the scope of this learning objective.)
"man" Configuration
Red Hat and Red Hat Derivatives
The configuration file for "man" is /etc/man.config. This file sets several different environment variables. (There are more, but these variables are the most important ones for you to know.)
Variable
Purpose
MANPATH
Defines the directory locations where man should look for man page files.
NOCACHE
Normally, when man load a man page for the first time, it will make a cache file of that page so that it will load faster the next time. The "NOCACHE" option turns this behavior off.
PAGER
This defines which pager man would use to display man pages. Normally, it would be the "less" pager.
CMP
When set, this tries to reduce duplicate search returns.
COMPRESS and COMPRESS_EXT
These variables determine which programs will decompress compressed man page files.
MANSECT
This will set the order in which man will search man page sections. Without this, searches would always start with the lowest number sections.
Here's a man.config file from a CentOS 5.1 system. (CentOS is a Red Hat derivative.)
# /var/cache/man/.../[locale/]catx/page.x.
# The keyword FHS will cause this behaviour (and overrides FSSTND).
# Explicitly given catdirs override.
#
# FSSTND
FHS
#
# This file is also read by man in order to find how to call nroff, less, etc.,
# and to determine the correspondence between extensions and decompressors.
#
# MANBIN /usr/local/bin/man
#
# Every automatically generated MANPATH includes these fields
#
MANPATH /usr/man
MANPATH /usr/share/man
MANPATH /usr/local/man
MANPATH /usr/local/share/man
MANPATH /usr/X11R6/man
#
# Uncomment if you want to include one of these by default
#
# MANPATH /opt/*/man
# MANPATH /usr/lib/*/man
# MANPATH /usr/share/*/man
# MANPATH /usr/kerberos/man
#
# Set up PATH to MANPATH mapping
#
# If people ask for "man foo" and have "/dir/bin/foo" in their PATH
# and the docs are found in "/dir/man", then no mapping is required.
#
# The below mappings are superfluous when the right hand side is
# in the mandatory manpath already, but will keep man from statting
# lots of other nearby files and directories.
#
MANPATH_MAP /bin /usr/share/man
MANPATH_MAP /sbin /usr/share/man
MANPATH_MAP /usr/bin /usr/share/man
MANPATH_MAP /usr/sbin /usr/share/man
MANPATH_MAP /usr/local/bin /usr/local/share/man
MANPATH_MAP /usr/local/sbin /usr/local/share/man
MANPATH_MAP /usr/X11R6/bin /usr/X11R6/man
MANPATH_MAP /usr/bin/X11 /usr/X11R6/man
MANPATH_MAP /usr/bin/mh /usr/share/man
#
# NOAUTOPATH keeps man from automatically adding directories that look like
# manual page directories to the path.
#
#NOAUTOPATH
#
# NOCACHE keeps man from creating cache pages ("cat pages")
# (generally one enables/disable cat page creation by creating/deleting
# the directory they would live in - man never does mkdir)
#
#NOCACHE
#
# Useful paths - note that COL should not be defined when
# NROFF is defined as "groff -Tascii" or "groff -Tlatin1";
# not only is it superfluous, but it actually damages the output.
# For use with utf-8, NROFF should be "nroff -mandoc" without -T option.
# (Maybe - but today I need -Tlatin1 to prevent double conversion to utf8.)
#
# If you have a new troff (version 1.18.1?) and its colored output
# causes problems, add the -c option to TROFF, NROFF.
#
TROFF /usr/bin/groff -Tps -mandoc
NROFF /usr/bin/nroff -c --legacy NROFF_OLD_CHARSET -mandoc 2>/dev/null
EQN /usr/bin/geqn -Tps
NEQN /usr/bin/geqn -Tutf8
TBL /usr/bin/gtbl
# COL /usr/bin/col
REFER /usr/bin/grefer
PIC /usr/bin/gpic
VGRIND
GRAP
PAGER /usr/bin/less -is
BROWSER /usr/bin/less -is
HTMLPAGER /bin/cat
CAT /bin/cat
#
# The command "man -a xyzzy" will show all man pages for xyzzy.
# When CMP is defined man will try to avoid showing the same
# text twice. (But compressed pages compare unequal.)
#
CMP /usr/bin/cmp -s
#
# Compress cat pages
#
COMPRESS /usr/bin/bzip2
COMPRESS_EXT .bz2
#
# Default manual sections (and order) to search if -S is not specified
# and the MANSECT environment variable is not set (1x-8x sections are used by
# xorg packages).
#
MANSECT 1:1p:8:2:3:3p:4:5:6:7:9:0p:n:l:p:o:1x:2x:3x:4x:5x:6x:7x:8x
#
# Default options to use when man is invoked without options
# This is mainly for the benefit of those that think -a should be the default
# Note that some systems have /usr/man/allman, causing pages to be shown twice.
#
#MANDEFOPTIONS -a
#
# Decompress with given decompressor when input file has given extension
# The command given must act as a filter.
#
.gz /usr/bin/gunzip -c
.bz2 /usr/bin/bzip2 -c -d
.z
.Z /bin/zcat
.F
.Y
Debian and Ubuntu Systems
The man configuration file for Debian and Ubuntu systems is /etc/manpath.config. This is set up differently from the configuration file on Red Hat-type systems, but it serves the same purpose.
The MANPATH statements that you saw in the Red Hat file are replaced by MANDATORY_MANPATH, MANPATH_MAP, and MANDB_MAP statements. Section search order is defined by a SECTION statement. Everything else is defined by a series of DEFINE statements.
Here's a "manpath.config" file from a Debian 4.0 system:
# manpath.config
#
# This file is used by the man-db package to configure the man and cat paths.
# It is also used to provide a manpath for those without one by examining
# their PATH environment variable. For details see the manpath(5) man page.
#
# Lines beginning with `#' are comments and are ignored. Any combination of
# tabs or spaces may be used as `whitespace' separators.
#
# There are three mappings allowed in this file:
# --------------------------------------------------------
# MANDATORY_MANPATH manpath_element
# MANPATH_MAP path_element manpath_element
# MANDB_MAP global_manpath [relative_catpath]
#---------------------------------------------------------
# every automatically generated MANPATH includes these fields
#
#MANDATORY_MANPATH /usr/src/pvm3/man
#
MANDATORY_MANPATH /usr/man
MANDATORY_MANPATH /usr/share/man
MANDATORY_MANPATH /usr/X11R6/man
MANDATORY_MANPATH /usr/local/man
#---------------------------------------------------------
# set up PATH to MANPATH mapping
# ie. what man tree holds man pages for what binary directory.
#
# *PATH* -> *MANPATH*
#
MANPATH_MAP /bin /usr/share/man
MANPATH_MAP /usr/bin /usr/share/man
MANPATH_MAP /sbin /usr/share/man
MANPATH_MAP /usr/sbin /usr/share/man
MANPATH_MAP /usr/local/bin /usr/local/man
MANPATH_MAP /usr/local/bin /usr/local/share/man
MANPATH_MAP /usr/local/sbin /usr/local/man
MANPATH_MAP /usr/local/sbin /usr/local/share/man
MANPATH_MAP /usr/X11R6/bin /usr/X11R6/man
MANPATH_MAP /usr/bin/X11 /usr/X11R6/man
MANPATH_MAP /usr/games /usr/share/man
MANPATH_MAP /opt/bin /opt/man
MANPATH_MAP /opt/sbin /opt/man
#---------------------------------------------------------
# For a manpath element to be treated as a system manpath (as most of those
# above should normally be), it must be mentioned below. Each line may have
# an optional extra string indicating the catpath associated with the
# manpath. If no catpath string is used, the catpath will default to the
# given manpath.
#
# You *must* provide all system manpaths, including manpaths for alternate
# operating systems, locale specific manpaths, and combinations of both, if
# they exist, otherwise the permissions of the user running man/mandb will
# be used to manipulate the manual pages. Also, mandb will not initialise
# the database cache for any manpaths not mentioned below unless explicitly
# requested to do so.
#
# In a per-user configuration file, this directive only controls the
# location of catpaths and the creation of database caches; it has no effect
# on privileges.
#
# Any manpaths that are subdirectories of other manpaths must be mentioned
# *before* the containing manpath. E.g. /usr/man/preformat must be listed
# before /usr/man.
#
# *MANPATH* -> *CATPATH*
#
MANDB_MAP /usr/man /var/cache/man/fsstnd
MANDB_MAP /usr/share/man /var/cache/man
MANDB_MAP /usr/local/man /var/cache/man/oldlocal
MANDB_MAP /usr/local/share/man /var/cache/man/local
MANDB_MAP /usr/X11R6/man /var/cache/man/X11R6
MANDB_MAP /opt/man /var/cache/man/opt
#
#---------------------------------------------------------
# Program definitions. These are commented out by default as the value
# of the definition is already the default. To change: uncomment a
# definition and modify it.
#
#DEFINE pager /usr/bin/pager -s
#DEFINE cat /bin/cat
#DEFINE tr /usr/bin/tr '\255\267\264\327' '\055\157\047\170'
#DEFINE grep /bin/grep
#DEFINE troff /usr/bin/groff -mandoc
#DEFINE nroff /usr/bin/nroff -mandoc
#DEFINE eqn /usr/bin/eqn
#DEFINE neqn /usr/bin/neqn
#DEFINE tbl /usr/bin/tbl
#DEFINE col /usr/bin/col
#DEFINE vgrind /usr/bin/vgrind
#DEFINE refer /usr/bin/refer
#DEFINE grap /usr/bin/grap
#DEFINE pic /usr/bin/pic -S
#
#DEFINE decompressor /bin/gzip -dc
#DEFINE compressor /bin/gzip -c7
#---------------------------------------------------------
# Misc definitions: same as program definitions above.
#
#DEFINE whatis_grep_flags -i
#DEFINE apropos_grep_flags -iEw
#DEFINE apropos_regex_grep_flags -iE
#---------------------------------------------------------
# Section names. Manual sections will be searched in the order listed here;
# the default is 1, n, l, 8, 3, 2, 5, 4, 9, 6, 7. Multiple SECTION
# directives may be given for clarity, and will be concatenated together in
# the expected way.
# If a particular extension is not in this list (say, 1mh), it will be
# displayed with the rest of the section it belongs to. The effect of this
# is that you only need to explicitly list extensions if you want to force a
# particular order. Sections with extensions should usually be adjacent to
# their main section (e.g. "1 1mh 8 ...").
SECTION 1 n l 8 3 2 3posix 3pm 3perl 5 4 9 6 7
About the Author:
Donnie is certified LPI Level 2, and is a course developer and instructor for SpiderTools.com and BeginLinux.com.
