How to Read a Man Page

 

A man page is composed (in general) of 5 parts:

Name

Name followed by a short description.

Synopsis

Cryptic description of how to use the command.

Description

Longer description of what the command does, what switches are available and what options; and sometimes includes examples.

Files

What files are associated with the command.

See Also

List of related commands.

Some man pages are considerably longer than 1 page. In order to get used to using the man pages, two things are necessary. First, you should run the man program asking for the man page of the man program. I.e.:

 man man

Second, you need to be aware of the following rules:

• Items enclosed with square brackets ``[]'' are optional switches or arguments. These can be nested.

   [arg1 [arg2]]

  This means that while both arg1 and arg2 are optional, if arg2 is given arg1 MUST be given.
• Items enclosed by braces ``{}'' are required.
• Pairs of items separated by a ``|'' mean either the first argument OR the second argument.
• Ellipses ``...'' means one or more of the preceeding arguments.

As mentioned above, the ``-k'' (for keyword) option is by far the most useful switch for the new user. Groups of switches are often bundled together.

For example:

 chgrp [-fR] GROUP {File ... | Directory ...}

In this example, either the -f or -R switches are optional (or both), the GROUP must be given, and some list of files or directories must be given.

In addition, the name of the command (or sometimes file) also gives some information as to what kind of man page is being presented. The pages are roughly divided into 10 sections:

1

User level commands and utilities.

2

System calls.

3

Subroutines or functions from libraries.

4

Special files.

5

File formats.

6

Games (if present on system).

7

Miscellaneous (macro packages, etc.).

8

System maintenance (administration and privileged) commands.

9

Kernel interface.

n

New. This looks to be a catch-all for everything else.

Usually, man pages from section 1 have (1) in the header of the man page, and likewise for the other sections. Occasionally, the header will have something like (1x) or (1qt), which is meant to give some indication as to the origin (in this case X11 or the QT library).

An introduction to each section can be found by entering:

 man N intro

where N is replaced by 1, 2, ...9. Section ``n'' usually has no introduction. It is NOT unusual to have man pages with the same name in different sections.