UNIX: The Complete Reference (2007)

Appendix-How to Use the Man (Manual) Pages

Overview

In this appendix, you will learn about the ultimate UNIX reference material, the man (manual) pages. UNIX manual pages are the ultimate reference for how UNIX commands work. They succinctly present a wealth of information about commands using a particular format. Consequently every serious UNIX user needs to know how to use manual pages. This appendix teaches you how to use manual pages and describes the information you can obtain by reading them. The manual pages for UNIX commands are distributed in CD-ROM (or DVD) format along with the operating system software for all major UNIX variants, and they are available in hard-copy documents for some of these variants. The manual pages for some variants may also be found on web sites. Finally, the manual pages are included as online documentation with many variants.

Manual pages for UNIX commands may be accessed via the man command (for manual), also described here. If you want to find out whether you have the man pages for your system, typing

$ man man

should display information about the man command itself. If you see a message saying that the man command is not found, see your system administrator; you will need to have the man package loaded separately

This appendix also describes how manual pages are indexed according to the type of function they perform, and describe the general layout of a manual page.

Finally, it describes the permuted index, a feature available with some UNIX variants, which are alphabetical lists of words taken from the NAMES section of manual pages, to find commands that perform tasks to solve your problems. It also shows you how to create your own permuted index. If you create any new UNIX programs, you might want to create your own manual pages following the conventions described here.

Using the Manual Pages

The definitive reference for UNIX commands is the manual pages for your variant. The commands and their descriptions follow the format of a physical reference manual, such as a User’s Reference Manual that has traditionally been included in printed form for each variant.

Manual pages provide detailed information on all standard commands and features. Besides manual pages on commands, there are manual pages for programmers and system administrators on special files, standard subroutines, and system calls. You can use the manual pages to find out exactly what a command does, how to use it, what options and arguments it takes, and which other commands are commonly used with it or are related to it. With the help of permuted indexes, which are indexes that list the function of a command (such as delete) or a word in the descriptive title of the command (such as editor), you can use manual pages to discover which command to use to solve a particular problem, and you can browse through it to discover useful commands you didn’t know about.

Although manual pages can be extremely helpful, they are sometimes not simple to use. At first glance, and even at second glance, a manual page may appear intimidating. Manual pages are reference material, not tutorials in how to use commands. Manual pages were originally written by and for experts-the people who created the UNIX system and developed the commands. Manual pages are designed to provide complete, precise, and detailed information in a concise form. As a result, although complete, they are terse-sometimes so terse that even experts have to read an entry, reread it, and then read it once again before they completely understand it. (As a perhaps extreme example, entire books have been devoted to explaining the awk command and language, yet only two manual pages are devoted to the awkcommand and language.)

Despite their complexity the manual pages are indispensable tools. Learning to read and use manual pages will greatly increase your ability to use UNIX. You will find that they provide the fastest way, and sometimes the only way, to get the information you need. The next section shows you how to read and use manual pages so that, with a little practice, they will become a familiar and useful tool.

The man Command

On most UNIX systems, manual pages are available for online use. In some cases, they are loaded onto your hard disk as part of the installation process. In other cases, they are available on a separate CD-ROM that can be mounted on your system and read as though they were on your hard disk. These commands are usually located in the directory /usr/ share/man.

If your system has manual pages available, you can use the man command to display a page on your screen or to print it. The format of the man command is man command. For example, to get the manual page for the grep command, type

$ man grep

This displays the same information in the printed manual page on your screen. Because manual pages are usually more than one screen length, it’s a good idea to send the man output to a pager (displaying one screen at a time) such as more, for example

$ man grep | more

If you want to save the output to a file you can redirect it to a file, for example savefile, by typing

$ man grep > savefile

If you want to save the output to savefile for printing later-or to copy to another machine that has a printer connected to it-you can create a printable format by using the col command, discussed in Chapter 19, as follows:

$ man grep col -b > savefile

The command col -b in this example removes hard-to-print highlighting that works well in on-screen displays (but not on printed media) such as underscoring and reverse highlighting, and prepares it for nroff-style printing.

You can also send the output directly to a printer by piping the output of the man command to lp:

$ man grep lp

or for some variants, piping it to lpr:

$ man grep lpr

If you are using a display terminal, in order to format the output for that particular terminal, you may need to use the -T option. For instance,

$ man -Tvt100 grep more

formats the output for a vt100 terminal. If you don’t use -T with a terminal option, man will format the output according to the terminal information in your TERM environment variable. This will normally be fine, if you are using a display that you have defined in TERM.

If you want to see a list of all of the commands that have a certain string in them, you can use the -k option, (for keyword), to produce a screen display as follows. For instance, to display all of the commands with the keyword irc in them could result in a display similar to this:

$ man -k irc

circle plot (3plot) - graphics interface

dircmp dircmp(1) - directory comparison

ircII ircII(1) - interface to the Internet Relay Chat System

Note that the -k option will display back all commands on your system that have the string-in this case irc-in them, no matter where the string appears in the command or in the description part of the display This is because the search mechanism for the string is grep, which will find the pattern anywhere on the man page-including the descriptive narrative. Therefore, it you had a command called round on your system, whose description was “a circle drawing utility” it would also show up in the listing just shown, since the word circle contains the letters irc.

Note also that the section in which the command appears is listed next to the command. The dircmp command is in Section 1 of the man pages (see later on for more information about this feature).

While using the -k option is useful when you don’t know a particular command, it may list unwanted results if the keyword that is supplied is too short or not descriptive enough. You might consider using the apropos command (see later on) in this case.

Command Categories

The manual pages of commands are organized into categories based on the type of function the particular commands perform. This structure is fairly uniform across UNIX variants. All UNIX variants use sections, and some further split sections using letters to designate subsections. For example, 1C is the common designation for all user-level commands used to communicate with other systems. Table A-1display the section categories used by some of the major version of UNIX including Solaris, Linux, and HP-UX. You will notice that not all versions of UNIX use all subsections.

The categories break commands into logical groups that we will briefly explain. Section 1 contains manual pages of user-level commands. For example, it contains the descriptions of ls and sh. This is the part of the manual pages you will use most often and the part discussed in most detail here. Section 1C contains information on the networking commands such as dialing up another computer with cu, and of the UUCP System, such as uuto. Section 1F contains comments used in the Forms Management Language (character user) Interface. Section 1M contains commands used for system administration; this section is extremely important if you need to perform administrative functions. Many of these commands require special permission.

Sections 2 and 3, as well as their subsections, contain information about subroutines of interest mostly to software developers. Section 4 describes the formats of system files such as /etc/passwd (Linux sometimes uses Section 5 for this).

As its name, “Miscellaneous,” suggests, Section 5 contains information that does not fit into the other sections. This is where you will find the list of ASCII character codes, for example. Section 6 is the traditional place in the manual pages for information about game programs. Games are often (but not always) found on computers running UNIX. Also included are demos on many newer versions of UNIX, including multimedia software demos. Like Sections 2 and 3, Section 7 is of interest mainly to software developers. It contains information about special files and devices in the /deυ directory Section 8 describes procedures that system administrators need to use to maintain and administer their systems. Section 9 is primarily intended to be used by systems programmers who work with the UNIX kernel.

Within each section, the entries are arranged in alphabetical order. For instance, Section 1 (User Commands) begins with the acctcom command and continues to the xargs command.

Finding Commands in a Particular Section

If you want to find a command in a particular section, you can do so by specifying the section in which the command is found. Although this format varies across UNIX implementations, the concept is to use the man command, followed by the command you want to find, followed by the complete section information. For example, in Solaris, the command

$ man cu.1c | pg

displays information one screenful at a time about the cu command found in section 1C of the Solaris online manual pages.

This feature comes in handy when multiple versions of a particular command exist. For instance, the passwd command is both a user command in Section 1 and a systems administrator command in Section 4. By default, the man command with no section options displays the first occurrence of the command in all of the sections. If you are a systems administrator and want to learn more about passwd in Section 4, you must type

$ man passwd.4

to get the correct display The passwd manual page in Section 4 describes some additional options and files that only systems administrators need to know about. If you mistakenly type

$ man passwd

you will see the display for the manual page for passwd in Section 1. Hopefully-if you are a good systems administrator-you will notice this, since each manual page shows the section to which the command applies as part of the display

Finding Command Using the intro Page

To make things even easier, each section has a special manual page called intro. You may view all of the commands in a given section by using intro with the appropriate section number. For example, typing

$ man intro.6

on a Solaris machine will produce a list of all of the games and demo commands in Section 6 that are available on your system. Other variants use similar formats for identifying sections and subsections. If you want to see how your particular variant uses the man command, including options, simply type

$ man man

The man command itself has a manual page that describes how to use man on your system.

The apropos Command

When you don’t know the exact name of a command but know its function, you can use the apropos command, available on most variants of UNIX. This command is used to find commands that have a certain word in their title (more accurately, the title field in their manual page description). For instance, if you are looking for a command that has the word editor in the title, your output might look something like this:

$apropos editor

ed

sed

vi

This makes sense because ed is a line editor, sed is a string editor, and vi is a visual screen editor.

Xman

If you use the X Window System, you can view manual pages using the xman utility To see how to use xman, go to the web page at http://www.xfree86.org/current/xman.1.html. To download this manual page viewer, go to ftp://ftp.x.org/pub/individual/app/.

The Structure of a Manual Page

UNIX manual pages have a fairly standard format. They contain some or all of the following sections in the order listed:

§ Title

§ Name

§ Synopsis

§ Description

§ Examples

§ Files

§ Exit codes

§ Notes

§ See also

§ Diagnostics

§ Warnings

§ Bugs

Several other kinds of information also may be provided, depending on whether the information is relevant to a particular command. Figure A-1 illustrates the manual page for the cp command.

Figure A–1: A sample manual page for the cp command

It contains some, but not all, of these sections. (Manual pages for utilities provided by many vendors do not include additional information such as the author[s] of the commands.)

Let’s look at each part of a manual page. At the top of each manual page is a TITLE, which contains the name of the command followed by a number, or a number and a letter, in parentheses. Then the name of the utility package that the command is part of is given (within parentheses). For example, the title of the cp page is typically displayed as

· User Commands cp(1) or Essential Utilities cp(1)

The (1) shows that this is a Section 1 entry This is useful because in a few cases the same name is used for a command (Section 1) and a system call (Section 2) or subroutine (Section 3). Some commands have a letter after the section number. For example, the title of the page for the uucp command is

· Communications Commands uucp(1C)

The (1C) shows that this is a Section 1C entry

NAME gives the command name and a short description of its function. Sometimes more than one command is listed, such as on the manual page for the compress command, which lists compress, uncompress, and zcat. The second and third commands listed do not have their own manual pages.

SYNOPSIS provides a one-line summary of how to invoke or enter the command. The synopsis is like a model or template-it shows the command name, and it indicates schematically the options and arguments it can accept and where they should be entered if you use them. The synopsis template uses a few conventions that you need to know. When more than one command appears on a page, each command is listed in the NAME section and then a synopsis for each command is listed in the SYNOPSIS section.

A constant-width font is used for literals that are to be typed just as they appear, such as many command names. In Figure A-1, cp and its available options, -i, -p, and -r, are all printed in a constant-width font. Substitutable arguments (and commands), such as filenames shown as schematic examples, are printed in italics (or shown as underlined or reverse video, when displayed on character terminals). In Figure A-1, the substitutable arguments file1, file2, and target, which represent filenames, are printed in italics. If a word in the synopsis is enclosed in brackets, that part of the command is optional; otherwise, it is required. An ellipsis (a string of three dots, like this…) means that there can be more of the preceding arguments. The synopsis of cp shows that it requires two filename arguments, shown by file1 and target, and that you can give it additional filenames, as shown by “[file2...].”

DESCRIPTION tells how the command is used and what it does. It explains the effects of each of the possible options and any restrictions on the command’s input or output. This section sometimes packs so much information into a few short paragraphs that you have to read it several times. Some command descriptions in the manual-for example, those for the commands xargs and tr-are (or deserve to be) legendary for the way they pack a lot of complex information into a short summary.

EXAMPLES provides one or more examples of command lines that use some of the more complex options, or that illustrate how to use a command with other commands.

FILES lists system files that the command uses. For example, the manual page for the chown command, used to change the name of the owner of a file, refers to the /etc/passwd and /etc/group files.

EXIT CODES describes the values set when the command terminates.

NOTES gives information that may be useful under the particular circumstances that are described.

SEE ALSO directs you to related commands and entries in other parts of the manual, and sometimes to other reference documents.

DIAGNOSTICS explains the meaning of error messages that the command generates.

WARNINGS describes limits or boundaries of the command that may limit its use.

BUGS describes peculiarities in the command that have not been fixed. Sometimes a short-term remedy is given. (Developers have a tendency to describe features they have no intention of implementing as bugs.)

Permuted Indexes

With so many commands available, it is difficult to know where to find an appropriate command for a particular task. It is impractical to look through manual pages for hundreds of commands to find one that might be useful. Instead, a particularly useful tool called the permuted index can help you find commands you need. The permuted index included with the manual pages for a particular version of the UNIX System (when it exists) provides an extremely complete and powerful way to find commands that do what you want. Check if permuted indexes are available for your particular version of UNIX.

The permuted index is a valuable tool for browsing. You can scan it to look for information on new commands, or you can look for suggestions about using commands you already know about in ways you might not have considered. You can also find commands that do not have their own manual page, but instead are described with other related commands.

The permuted index is based on the descriptions in the NAME sections of the pages for the individual commands. For each of the descriptions, it creates several entries in the index-one for each significant keyword in the NAME description.

Figure A-2 shows a typical page from a permuted index. Notice that there are three parts to each line: left, center, and right.

Figure A–2: A typical permuted index page

The center part of each line begins with a keyword from a manual page entry The permuted index is arranged so that these words are listed in alphabetical order. If you were looking for a command to list files, but you didn’t know that the name for this command is ls, you could look for “list” in the center column of the index. You would find several entries beginning with “list.”

The right-hand column tells you the manual page that this summary comes from. The left-hand column contains the text of the NAME entry that precedes the keyword. For the ls example, it is simply “ls.” If a keyword is the first line in the description, nothing appears in the left-hand column (for example, notice the blank area preceding the “ln link files” entry). Also, if there isn’t enough room in the center column for all of the text following the keyword, whatever doesn’t fit is “folded” over and placed at the beginning of the left-hand column. An example of this is the entry for the keywords “list of service grades that are.”

To use the permuted index, begin by looking in the center column for words of interest. Then read the complete phrase of any entry that catches your interest, beginning with the name of the command, which may appear in the left or center column. You will need some practice to become comfortable using a permuted index. But if you learn to use it, you will find that it soon becomes easy to find the information you are looking for, and that it can point you toward all sorts of interesting commands that you might otherwise never have found.

Creating Your Own Permuted Index

You can create a permuted index of the commands on your system by using the ptx (or gptx) command. (gptx, or Gnu ptx is just an enhanced version of ptx, with some slightly different options. ptx is more readily available on the web.) ptx is part of the coreutils package. The actual man page for the ptx command can be found on the web site at: http://linuxcommand.org/man_pages/ptx1.html. The format of the ptx (and gptx) command is

$ ptx [OPTION]... [INPUT]... (without -G)

or

$ ptx -G [OPTION]... [INPUT [OUTPUT]]

The -G option refers to disabling GNU extensions, and formatting the output in the traditional UNIX System V format. If you want to use this option, it must appear as the first option to ptx. The input consists of a file (or files) containing the words you wish to use as keywords in the permuted index. The output is a file or printout of the results.

If you have the info and ptx packages installed on your system, you can see the complete ptx manual-in Texinfo format-by issuing the command

$ info coreutils ptx

Since there are many options to ptx that affect how the output is generated and displayed, you probably should read this manual prior to attempting to use ptx to create a permuted index.

To find out more about ptx, go to the web site at http://www.gnu.org/software/ptx/ptx.html. Since the ptx command has been added-along with a number of other text utilities-to the coreutils package, you can get it from the coreutils page at http://www.gnu.org/software/coreutils/. For information about gptx, see http://www.muth.utah.edu/docs/info/gptx x_toc.html#SEC1.

Online Manual Pages on the Web

You can find web sites that contain manual pages for many versions of UNIX. For example, one of the most complete Linux man page collections can be found on the Wiki web site at http://man-wiki.net/. A complete list of HP-UX man pages can be found on the web site at: http://docs.hp.com/en/hpuxman_pages.html. A complete list of Solaris man pages can be found at: http://developers.sun.com/solaris/articles/man_pages.html. For Mac OS X users, you should go to the web site at http://www.hmug.org/man/.

If you are looking for a specific command, you may even try entering the phrase “man command” (where command is replaced by the command you are looking for) into your favorite search engine (e.g., Google). Most search engines are so richly indexed that this technique will almost always return at least a few hits. Just make sure that the resulting hits refer to your particular variant. While a number of commands work across the variants with the same options and are in the same directory structures, many either use slightly different options or are located in a different directory than other variants. If possible, you should use the online man pages that come with your variant’s distribution.