This section covers material for topic 1.108.1 for the Junior Level Administration (LPIC-1) exam 102. The topic has a weight of 4.
In this section, learn how to:
- Find relevant man pages
- Search man page sections
- Find commands and man pages related to them
- Configure access to man sources and the man system
- Prepare man pages for printouts
- Use the system documentation stored in /usr/share/doc/ and determine what documentation to keep in /usr/share/doc/
The primary (and traditional) source of documentation is the manual
pages, which you can access using the
command. Ideally, you can look up the man page for any command, configuration
file, or library routine. In practice, Linux is free software, and some pages
haven't been written or are showing their age. Nonetheless, man pages are the
first place to look when you need help. Figure 1 illustrates the manual page for
man command itself. Use the command
man man to display this information.
Figure 1. Man page for the man command
Figure 1 shows some typical items in man pages:
- A heading with the name of the command followed by its section number in parentheses
- The name of the command and any related commands that are described on the same man page
- A synopsis of the options and parameters applicable to the command
- A short description of the command
- Detailed information on each of the options
You may find other sections on usage, how to report bugs, author
information, and a list of any related commands. For example, the man page for
man tells us that related commands (and their manual
apropos(1), whatis(1), less(1), groff(1), and man.conf(5).
Man pages are displayed using a pager, which is usually the
less command on Linux systems. You can set this using
the $PAGER environment variable, or by using the
--pager option, along with another pager name, on
the man command. The pager will receive its input on stdin, so something like an
editor that expects a file to manipulate does not work as a pager.
There are eight common manual page sections. Manual pages are usually installed when you install a package, so if you do not have a package installed, you probably won't have a manual page for it. Similarly, some of your manual sections may be empty or nearly empty. The common manual sections, with some example contents are:
- User commands (env, ls, echo, mkdir, tty)
- System calls or kernel functions (link, sethostname, mkdir)
- Library routines (acosh, asctime, btree, locale, XML::Parser)
- Device-related information (isdn_audio, mouse, tty, zero)
- File format descriptions (keymaps, motd, wvdial.conf)
- Games (note that many games are now graphical and have graphical help outside the man page system)
- Miscellaneous (arp, boot, regex, unix utf8)
- System administration (debugfs, fdisk, fsck, mount, renice, rpm)
Other man page sections that you might find include 9 for Linux kernel documentation, n for new documentation, o for old documentation, and l for local documentation.
Some entries appear in multiple sections. Our examples show mkdir in sections 1 and 2, and tty in sections 1 and 4.
In addition to the standard manual pages, the Free Software Foundation has
created a number of info files that are processed with the
info program. These provide extensive navigation
facilities including the ability to jump to other sections. Try
man info or
info info for
more information. Not all commands are documented with info, so you will find
yourself using both man and info if you become an info user. You can also start
at the top of the info tree by using
parameters as shown in Listing 1.
Listing 1. The info command
File: dir, Node: Top This is the top of the INFO tree This (the Directory node) gives a menu of major topics. Typing "q" exits, "?" lists all Info commands, "d" returns here, "h" gives a primer for first-timers, "mEmacs<Return>" visits the Emacs manual, etc. In Emacs, you can click mouse button 2 on a menu item or cross reference to select it. * Menu: Utilities * Bash: (bash). The GNU Bourne-Again SHell. * Enscript: (enscript). GNU Enscript * Gzip: (gzip). The gzip command for compressing files. * ZSH: (zsh). The Z Shell Manual. Libraries * AA-lib: (aalib). An ASCII-art graphics library * History: (history). The GNU history library API * Libxmi: (libxmi). The GNU libxmi 2-D rasterization library. * Readline: (readline). The GNU readline library API Texinfo documentation system * Info: (info). Documentation browsing system. -----Info: (dir)Top, 2104 lines --Top------------------------------------------- Welcome to Info version 4.6. Type ? for help, m for menu item.
In addition to the standard
man command, which uses a
terminal window and a pager, your system may also have one or more graphical
interfaces to manual pages, such as
xman (from the
XFree86 Project) and
yelp (the Gnome help browser).
When you start
xman, you will see a small window
with three buttons. Click the Manual Page button to open a
larger window where you can navigate through manual pages or search for
information. Figure 2 shows an example of both windows.
Figure 2. Using xman
yelp browser usually looks somewhat
different from system to system. Figure 3 shows an example on Ubuntu 6.06. You
can access either the man pages or the info pages using the Command Line
Help item at the bottom of the display.
Figure 3. Using yelp on Ubuntu
If you know that a topic occurs in a particular section, you can specify the
section. For example,
man 4 tty or
man 2 mkdir. An alternative is to use the
-a option to display all applicable manual sections.
If you specify
-a, you will be prompted after quitting
the page for each section. You may skip the next page, view it, or quit
As you saw earlier, some topics exist in more than one section. If you don't
want to search through each section, you can use the
-aw options of
man to get
a list of all available man pages for a topic. Listing 2 shows an example for
printf. If you were writing a portable shell script, you might be interested in
man 1p printf to learn about the POSIX
version of the printf command. On the other hand, if you were writing a C or C++
program, you would be more interested in man 3 printf, which would
show you the documentation for the printf, fprintf, sprintf, snprintf, vprintf,
vfprintf, vsprintf, and vsnprintf library functions.
Listing 2. Available man pages for printf
ian@lyrebird:~> man -aw printf /usr/share/man/man1/printf.1.gz /usr/share/man/man1p/printf.1p.gz /usr/share/man/man3/printf.3.gz
man command pages output onto your display using
a paging program. On most Linux systems, this is likely to be the
less program. Another choice might be the older
The less pager has several commands that help you search for strings within the
displayed output. These are similar to
man less to find out more about
/ (search forwards),
(search backwards), and
n (repeat last search), among
many other commands.
info command comes from the makers of
emacs, so the searching commands are more like emacs
commands. For example,
ctrl-s searches forwards and
ctrl-r searches backwards using an incremental
search. You can also move around with the arrow keys, follow links (indicated
with a star) using the Enter key, and quit using
--vi-keys option with
info if you'd prefer similar key bindings to those
Two important commands related to
whatis command searches man pages for the name you
give and displays the name information from the appropriate manual pages. The
apropos command does a keyword search of manual pages
and lists ones containing your keyword. Listing 3 illustrates these commands.
Listing 3. Whatis and apropos examples
[ian@lyrebird ian]$ whatis man man (1) - format and display the on-line manual pages 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 [ian@lyrebird ian]$ whatis mkdir mkdir (1) - make directories mkdir (2) - create a directory [ian@lyrebird ian]$ apropos mkdir mkdir (1) - make directories mkdir (2) - create a directory mkdirhier (1x) - makes a directory hierarchy
By the way, if you cannot find the manual page for man.conf, try running
man man.config instead, which works on some
apropos command can produce a lot of output, so
you may need to use more complex regular expressions rather than simple
keywords. Alternatively, you may wish to filter the output through
grep or another filter to reduce the output to
something more of interest. As a practical example, you can use the e2label to
display or change the label on an ext2 or ext3 filesystem, but you have to use
another command to change the label on a ReiserFS filesystem. Suppose you run
mount to display the mounted ResiserFS filesystems as
shown in Listing 4.
Listing 4. Mounted ReiserFS filesystems
ian@lyrebird:~> mount -t reiserfs LABEL=SLES9 on / type reiserfs (rw,acl,user_xattr)
Now you'd like to know what partition corresponds to the label SLES9, but you
can't remember the command. Using
apropos label might get you a couple of dozen
responses, which isn't too bad to sift through. But wait. This command must have
something to do with a filesystem of a volume. So you try the regular
expressions shown in Listing 5.
Listing 5. Using apropos with regular expressions
ian@lyrebird:~> apropos "label.*file" e2label (8) - Change the label on an ext2/ext3 filesystem ntfslabel (8) - display/change the label on an ntfs file system ian@lyrebird:~> apropos "label.*volume" label.*volume: nothing appropriate.
Not exactly what you were looking for. You could try reversing the order of the
terms in the regular expressions, or you could try filtering through
egrep as shown in
Listing 6. Filtering the output of apropos
ian@lyrebird:~> apropos label | grep -E "file|volume" e2label (8) - Change the label on an ext2/ext3 filesystem mlabel (1) - make an MSDOS volume label ntfslabel (8) - display/change the label on an ntfs file system findfs (8) - Find a filesystem by label or UUID
And there's the command that we need,
it as shown in Listing 7 shows that the filesystem is on /dev/hda10 on this
Listing 7. Finding the device for a mounted filesystem label
ian@lyrebird:~> /sbin/findfs LABEL=SLES9 /dev/hda10
Note that non-root users will usually have to give the full path to the
As you can find out in the man page for the
command, you can also use
man -k instead of
whatis. Since these call the
under the covers, there is probably little point in so doing.
Manual pages may be in many locations on your system. You can determine the
current search path using the
manpath command. If the
MANPATH environment variable is set, this will be used for searching for manual
pages; otherwise, a path will be built automatically using information from a
configuration file that we'll discuss in a moment. If the MANPATH environment
variable is set, the
manpath command will issue a
warning message to this effect before displaying the path.
Listing 8. Displaying your MANPATH
[ian@echidna ian]$ manpath /usr/local/share/man:/usr/share/man:/usr/X11R6/man:/usr/local/man ian@lyrebird:~> manpath manpath: warning: $MANPATH set, ignoring /etc/manpath.config /usr/local/man:/usr/share/man:/usr/X11R6/man:/opt/gnome/share/man
Depending on your system, configuration information for the man system is stored in /etc/man.config or /etc/manpath.confg. Older systems use /etc/man.conf. A current man.config file contains a list of directories (MANPATHs) that will be searched for manual pages, such as those shown in Listing 9.
Listing 9. MANPATH entries from /etc/man.config
MANPATH /usr/share/man MANPATH /usr/man MANPATH /usr/local/share/man MANPATH /usr/local/man MANPATH /usr/X11R6/man
In a manpath.config file, these entries will be MANDATORY_MANPATH entries, rather than MANPATH entries.
Besides these entries, you will also find entries giving a mapping between paths where executables may be found, and paths where the corresponding man pages might be, as shown in Listing 10.
Listing 10. MANPATH_MAP entries from /etc/man.config
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
man command uses a complicated method for
searching for man pages, and setting these values will result in less wasted
effort when searching for pages.
Another entry in the configuration file defines the search order for manual pages. Recall that the default is to display the first page found, so this ordering is important. Look near the bottom of man.config for a MANSECT line, or near the bottom of manpath.config for a SECTION line. Examine the configuration file on your system to see what other things can be configured.
You may have noticed that the
whatis commands ran quickly. This is because they do
not actually search the individual manual pages. Rather, they use a database
created by the
makewhatis command. This is usually
run by the system either daily or weekly as a cron job.
Listing 11. Running makewhatis
[root@echidna root]# makewhatis
The command completes normally without any output message, but the whatis
database is refreshed. This is usually stored in a location such as
/var/cache/man/whatis. Note that some SUSE systems do not use the whatis
database and therefore do not have a
If you wish to print the page, specify the
to format the page for printing using the
troff program. This will format the page for the
default printer and send the output to stdout. Listing 12 shows how to format
the man page for the
ls command and save the output
in a file, ls.ps. Figure 4 shows the formatted output.
Listing 12. Formatting the ls manpage for printing
ian@pinguino:~$ man -t ls > ls.ps
Figure 4. Formatted ls man page
If you need to format the page for a different device type, use the
-T options with a device type, such as dvi or ps. See
the man page for
man for additional information.
In addition to the manual pages and info pages that you have already seen, your Linux system probably includes a lot more documentation. The customary place to store this is in /usr/share/doc, or /usr/doc on older systems. This additional documentation may be in any of several formats, such as text, PDF, PostScript, or HTML.
Searching through this documentation can often reveal gems that aren't available as man pages or info pages, such as tutorials or additional technical documentation. As Listing 13 shows, there can be a large number of files in /usr/share/doc, so you have plenty of reading resources.
Listing 13. Files in /usr/share/doc
ian@pinguino:~$ find /usr/share/doc -type f | wc -l 10144
Figure 5 shows an example of the HTML help for the Texinfo system that is used
info command that you saw earlier.
Figure 5. Texinfo HTML help from /usr/share/doc
Sometimes, a man page will direct you to another source for documentation. For
example, the man page for the
pngtopnm command is
shown in Listing 14. It directs you to a local copy in HTML format at
/usr/share/doc/packages/netpbm/doc/pngtopnm.html, or to an online version if you
do not have the local copy.
Listing 14. Pointer man page for pngtopnm
pngtopnm(1) Netpbm pointer man pages pngtopnm(1) pngtopnm is part of the Netpbm package. Netpbm documentation is kept in HTML format. Please refer to <http://netpbm.sourceforge.net/doc//pngtopnm.html>. If that doesn't work, also try <http://netpbm.sourceforge.net> and emailing Bryan Henderson, email@example.com. Local copy of the page is here: /usr/share/doc/packages/netpbm/doc/pngtopnm.html
Finally, if you can't find help for a command, try running the command with the
--? option. This may provide the command's help, or
it may tell you how to get the help you need. Listing 15 shows an example for
kdesu command, which is usually present on systems with a KDE desktop.
Listing 15. Getting help for kdesu command
ian@lyrebird:~> man kdesu No manual entry for kdesu ian@lyrebird:~> kdesu --help Usage: kdesu [Qt-options] [KDE-options] command Runs a program with elevated privileges. Generic options: --help Show help about options --help-qt Show Qt specific options --help-kde Show KDE specific options --help-all Show all options --author Show author information -v, --version Show version information --license Show license information -- End of options Arguments: command Specifies the command to run. Options: -c <command> Specifies the command to run. 
The next section covers online resources for help with Linux.