be read from cover to cover, like a good C. S. Lewis novel, but is intended to be a resource guide—a place to go to find specific answers to specific questions. The following sections discuss the places you can turn to get help.

Man Pages

The man pages are like the Marines. They are your first lines of defense. Man pages contain the online version of the Red Hat UNIX reference manuals. They provide definitions and explanations of commands. In addition, they provide optional parameters for commands to perform specific functions. After all of the explanations are examples, and finally, other commands that are similar or relate to the command you looked up.

The format of the man pages is as follows:

• NAME
• SYNOPSIS
• DESCRIPTION
• COMMAND-LINE OPTIONS
• SEE ALSO
• BUGS

Over time, especially in Linux, people have customized the man pages to include other optional fields. Some of these fields are AUTHOR, SORT KEYS, UPDATING, and NOTES. The additions have been added to enhance the pages. For example, the AUTHOR section many times includes an e-mail address of the author. This is good if the command is not working as you expected it to. (Remember, none of Linux was taken from AT&T's UNIX, so small differences do exist, even in the "standard" commands.)

Probably the one thing to point out to new man page users is the syntax used for showing the SYNOPSIS of the command. There are several standards that are followed in writing commands that are used in the man pages. Here's the SYNOPSIS for the ps command:

SYNOPSIS

       ps  [-]  [lujsvmaxScewhrnu]  [txx]  [O[+|-]k1[[+|-]k2...]] [pids]

Anything in square brackets ([]) is optional. Note that the only thing not optional in this command is the command itself. Therefore, you can issue the ps command without any options, and you will receive a snapshot of the current processes.

The [-] means that the - is an optional argument. Many commercial versions of UNIX require a dash to indicate that what follows are arguments. This is not true for the Red Hat Linux version of the ps command. The next set of characters (between the next set of square brackets) indicates that any of these parameters can be added to the ps command. For example, a common set of parameters to add to the ps command is -la, which will display a long listing of all (including hidden) files.

The man pages are not a singular file or directory of Linux manuals. Instead, the man pages are a set of directories, each containing a section of the man pages. These directories contain the raw data for the man pages. In Red Hat Linux, there are eight sections of man pages. In addition, each section has corresponding catn subdirectories that store processed versions of the man pages. When a man page is accessed, the program that formats the man pages saves a copy of the formatted man page in the catn (/etc/catn) directories. This saves time in the future because the next time a user requests a man page for a specific subject, if that subject had been accessed before, then the formatting does not have to be repeated, but can be displayed from the previously formatted page. The following shows what information is found within each section:

The man command searches the sections in a predefined order: 1, 6, 8, 2, 3, 4, 5, and 7. It checks for commands first, followed by system calls and library functions, and then the other sections.

There is a special way of accessing the man pages so that all pages listing a certain piece of data are displayed. This is the keyword search for man pages (man -k). In order to use this searching capability, the command catman -w must be issued first. This command (which takes a little while) indexes the man pages so that the keyword search will work.

One of the benefits of man pages is that you can add your own local man pages. A friend of mine did not know how to do this, so he wrote a Perl program called man.pl that performed a similar function. It was a shame that he didn't have this book to tell him it could be done! Adding man pages is a wonderful way of documenting tools that you write for use at your site. Two directories are left blank for that purpose. They are the mann directory and the cat directory (/usr/man/mann and /usr/man/cat).

The simplest way of making a man page is to place some text in a file describing the command or topic. However, it is fairly easy to make a more elaborate page that looks like a normal man page. Man pages are designed for the nroff text formatter, and have text and nroff directives intermingled.

The best way to figure out what the different directives do is to look at a man page and see how it is laid out. To do this with Linux, you must first gunzip the file. Once gunzipped, the file can be looked at with a text editor. All the different directives begin with a period (or dot). Table 15.1 lists many of the nroff directives and an explanation of what they do.

Table 15.1. nroff directives.

When testing the man page, you can simulate an actual man page call to the file with the following command:

$ nroff -man <file> | more

The man pages are not the only place that a resourceful system administrator can turn for answers. There is also the Internet. Within the Internet there are e-mail, Web pages describing how to do things, and newsgroups.

E-mail

With e-mail, you can send questions to people that you know who are doing similar work. For example, when I get stuck writing Perl scripts, I send a note off to Rich. He drops everything and responds immediately to my questions (yeah, right!). The point is, there are those that you associate with who can assist you with your problems or point you on your way to success. If you don't know anyone who is working with Red Hat Linux, you can do two things. First, find new friends—obviously the ones you have are holding you back; and secondly, you can e-mail newsgroups.