Previous Section  < Day Day Up >  Next Section

Recipe 1.2. Understanding man Pages

1.2.1 Problem

You're trying to use some programs (for example, everyone's favorite, grep; the name tells you so much) and you can't make them them do what you want. So, heeding the standard "RTFM" (read the fine man page) advice, you dig up the relevant man pages. But they don't make a lot of sense—now what?

1.2.2 Solution

Learn how man pages are organized, and familiarize yourself with their conventions for teaching command syntax and options, and you'll find that man pages really are helpful.

1.2.3 Discussion

Linux sees all the man pages on a system as part of a single manual. This manual is divided into sections:

1 Executable programs or shell commands
2 System calls
3 Library calls
4 Special files (usually found in /dev)
5 File formats and conventions
6 Games
7 Miscellaneous
8 System administration commands
9 Nonstandard kernel routines
n New documentation, which may be moved later
l Local documentation, specific to your system

Each individual program, utility, or function has its own page in this manual, like a page in a book. Finding the man page for a program or command is usually as easy as typing man foo, where foo is the name of the program.

You've probably seen references to numbered man pages, like grep(1). This is referring to man grep in section 1. Call it up this way:

$ man 1 grep

Some man pages are in more than one section. man foo will only display the first one. You can list all of them with the -f switch:

$ man -f man

man (1)   an interface to the online reference manuals

man (7)   macros to format man pages

Each man page is divided into sections. The section names vary, but you'll usually see these: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, EXAMPLES, SEE ALSO, BUGS, and AUTHOR.

Here's the notation used to show command syntax, found in the Synopsis of the man pages:

command-name [optional flags] any-other-required-elements

Command flags are shown this way:


bold text

Type this exactly as it is shown.


italic text

Italic text indicates an argument, which means you replace it with your desired value. Depending on the viewer you are using, you may not see italics, but rather underlines or bold text.


[-abc]

Everything inside square brackets is optional and can be combined.


[-a|-b|-c]

Options separated by the pipe | (Shift-backslash) cannot be combined.


argument...

The ellipsis indicates that several arguments can be listed. Watch out for delimiters—usually they are spaces, but sometimes commas are used.


[expression] ...

The ellipsis indicates that several expressions can be listed.

Short options can be typed two ways:

-abc

or:

-a -b -c

Long options must be individually hyphenated, and they use double hyphens:

--option1 --option2 --option3

Long options are especially useful in scripts, so you can remember what the script does.

The bulk of most man pages is a list of the options available.

1.2.4 See Also

  • man(1)

    Previous Section  < Day Day Up >  Next Section