One of the hardest parts of unix for beginners is finding documentation. When you hear the system comes with an online manual, it usually causes a sigh of relief. What you don't know is that manual pages are technical references. While that may sound really bad -- its not! Once you learn the basics of man pages, you will come to appreciate how they are written. If you need information, and don't have time to waste, the man command is who you turn to.
This document attempts to teach you how to read the unix manual -- commonly refered to as the man pages.
Before we jump into our first man page, lets take a look at some common symbols used in them. These symbols are sometimes refered to as quotes.
The primary use of a man page is to lookup parameters for a program. Since most parameters are optional, they will be enclosed in square brackets.
[optional] [-abcgln]
Some options will have a limited list of choices. A list of choices will be comma seperated and put between braces.
{choice1,choice2}
{yes,no}
Many sources of help documentation enclose manditory parameters
between less-than/greater-than symbols.
<manditory> <program_name>
While the above manditory quotes aren't usually used in man pages, its a good thing to know.
Here is how we start the man program:
man [section] topic
Man pages are seperated into sections. Sections are typically numeric values. You can think of each section as a seperate book. There is a section for commands, programming functions, configuration file syntaxes, et cetera.
The topic is the commandname or function name you are trying to lookup.
A common way to refer to a topic in a specific setion of the manual is to put section in parentesis after the topic name. Here are some examples:
ls(1) printf(3) lilo.conf(5)By default, the man program will search the sections in numerical order starting with section 1 and return the first match.
We start by issuing the man command on our topic.
man man
And this is what we see:
man(1) man(1)
Man pages are designed to be printed on a (plain text) printer. The command name and section is printed at the top of each page.
NAME
man - format and display the on-line manual pages
manpath - determine user's search path for man pages
This is the name of the executable and a one line description of the command. Some programs, such as man, will share a manual page with a very similar command. In this case the manual page describes both the man and manpath commands.
SYNOPSIS
man [-acdfhkKtwW] [-m system] [-p string] [-C config_file] [-M path]
[-P pager] [-S section_list] [section] name ...
Synopsis is another name for the usage of the command. This shows all the possible options the man command can take.
DESCRIPTION
man formats and displays the on-line manual pages. This version
knows about the MANPATH and (MAN)PAGER environment variables, so you
can have your own set(s) of personal man pages and choose whatever
program you like to display the formatted pages. If section is spec-
ified, man only looks in that section of the manual. You may also
specify the order to search the sections for entries and which pre-
processors to run on the source files via command line options or
environment variables. If name contains a / then it is first tried
as a filename, so that you can do man ./foo.5 or even man
/cd/foo/bar.1.gz.
The description section will be one of the most useful sections of the document. It attempts to describe the command in plain english.
OPTIONS
Now we are getting into the meat of the program. This part describes all of the options from the synopsis.
I'll just include a couple options for this example.
-P pager
Specify which pager to use. This option overrides the MAN-
PAGER environment variable, which in turn overrides the PAGER
variable. By default, man uses /usr/bin/less-is.
Some options will take an addition parameter. In this case its the pager name. A pager, in this context, is the program which shows text one screenfull at a time.
-h Print a one-line help message and exit.
-k Equivalent to apropos.
Other options won't need additional parameters.
At this point, man pages will tend to vary a little bit.
CAT PAGES
Man will try to save the formatted man pages, in order to save for-
matting time the next time these pages are needed. Traditionally,
formatted versions of pages in DIR/manX are saved in DIR/catX, but
other mappings from man dir to cat dir can be specified in
/etc/man.config. No cat pages are saved when the required cat direc-
tory does not exist.
Cat pages are a specific topic to man pages. Man page authors will go into great specifics of the program or maybe just refer you to another source of documentation (or say nothing at all). The casual user can usually skip over this part.
Towards the end, the man pages will standarize again.
ENVIRONMENT
MANPATH
If MANPATH is set, its value is used as the path to search for
manual pages.
The environment refers to environmental variables you may have set. The environment is inheirited from your shell.
SEE ALSO
apropos(1), whatis(1), less(1), groff(1).
See Also is a very valuable part of the man page. Sometimes I will load a man page of a command I know just to lookup related commands.
Hint: Press G to jump to the bottom of the text
BUGS
The -t option only works if a troff-like program is installed.
If you see blinking \255 or instead of hyphens, put `LESS-
CHARSET=latin1' in your environment.
It is standard for authors to list known bugs that may cause the program to act unexpectedly. Usually only the most glaring bugs get listed.
The man command supports a simple search of the manual. You can do this with the "apropos" command or "man -k". Both do the same thing.
apropos topic man -k topic
If apropos complains about not having a whatis database, run /usr/sbin/makewhatis -w as root. Some systems, like Red Hat, will run this command as a weekly cron job to keep the database up to date.
If I want to see commands related to rpm, I could do the following.
man -k rpmHere are the results:
glint (8) - Graphical Linux Installation Tool for RPM based systems rpm (8) - Red Hat Package Manager rpm2cpio (8) - Converts Red Hat Packge (RPM) to cpio archive
The output shows the command name, the manual section, and a short description taken from the NAME section.
1: user commands 2: system calls 3: library functions 4: special files 5: config files 6: games 7: miscellany 8: administration and privilaged commands 9: kernel (not on linux)