Beginners Guide to man Pages

Introduction

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.

Common Quotes

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.

The man Command

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.

Breaking Down a man Page

The best way to learn how to read a man page is by looking at an example. I will break down the manual page for the man program itself.

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.

Apropos

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 rpm
Here 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.

Man Sections

This document wouldn't be complete without a list of the major sections from the manual. If you forget what a section is, you can read the intro(x) page, where x is the section number.
  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)

Written by Brian Murphy
Last updated: 12.31.98
Email: tfug-web@azstarnet.com