Using "man" Pages
| Using "man" Pages |
| Desktop Training - Linux Newbie | ||||||||||||||||||||||||||||||||||||||||||
|
Using "man" Pages by Donnie Tevault "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.)
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.)
[donnie@localhost ~]$ man -aw printf /usr/share/man/man1/printf.1.gz /usr/share/man/man3p/printf.3p.gz /usr/share/man/man3/printf.3.gz /usr/share/man/man1p/printf.1p.gz [donnie@localhost ~]$
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.
Other options are available for more complex searches. See the "less" man page for more information.
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.
[donnie@localhost ~]$ sudo makewhatis Password: [donnie@localhost ~]$
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.)
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 |
||||||||||||||||||||||||||||||||||||||||||
