The manual pages

2.4.5. The manual pages#

Youā€™ve already encountered one way of finding out what arguments a command takes: by specifying --help. However, not all programs understand this command. Instead, in Unix thereā€™s an online collection of manuals. Each command has its own manual page, which you can call up with the command man.

When using the man command to find out what the cal command does and what arguments it takes, you will see something like this:

$ man cal
CAL(1)             BSD General Commands Manual             CAL(1)

NAME
     cal, ncal ā€” displays a calendar and the date of Easter

SYNOPSIS
     cal [-hjy] [[month] year]
     cal [-hj] -m month [year]
     ncal [-hjJpwy3] [-s country_code] [[month] year]
     ncal [-hJeo] [year]

DESCRIPTION
     The cal utility displays a simple calendar in traditional
     format and ncal offers an alternative layout, more options

and so on. To scroll back and forth in the manual page, you can use Space or Enter, Page Up/Page Down and Up/Down. To leave the man page, press q. You can also easily search through it by first hitting / followed by the text and then Enter. Repeating the same search can be done by simply pressing n.

Exercise 2.27

According to the manual page, when did the Gregorian Reformation occur in Great Britain? Find the option that prints the switching dates for other countries to see when this was done in the Netherlands. Note that this option is only accepted by the ncal variant of the command!

Manual pages often tell you the name of the command, how to use it (synopsis), a detailed description of what it is, when the command was made and by whom, where to find more information or related commands, and the copyright. Sometimes, the man page is so brutally honest that it even gives information on the bugs still left in the command.

The SYNOPSIS section details different ways of calling the command, each with different options. Parts of the command line that must be typed as written are in bold, while placeholder arguments (like month in the cal example) are underlined. These are often detailed in the DESCRIPTION section. As said before, required arguments are given as is, while optional ones are enclosed in [brackets]. When keystrokes are given, Ctrl-C is shortened to ^C[1].

Exercise 2.28

Find the BUGS section of the bash manual page to see what the authors think the biggest problem with it is.

Note that in the cal man page, the top line says CAL(1). This means that cal is found in Section 1 of the online manual. In total, there are 8 main manual sections:

  1. User commands

  2. System calls

  3. Subroutines

  4. Devices

  5. File formats

  6. Games

  7. Miscellaneous

  8. System administration

Fortunately, you donā€™t have to know which section a manual page is in; it will be found automatically by man. You will only have to specify the section (using man n [term], where n is the section number) if thereā€™s more than one entry for the term youā€™re looking for.

Manual pages are among the most important things you need to learn about Unix . From now on, as little explicit help on commands will be given as possible; you know where to find more information if you need toā€¦

Exercise 2.29

Find out more about the man command.

2.4.5.1. whatis and apropos#

Two other useful manual commands are whatis and apropos. With whatis, you get a one-line description of a command; the argument must match the command exactly. The apropos command also shows descriptions of commands which match your argument partially, which makes it easy to search for a command of which you donā€™t exactly know the name.

Exercise 2.30

Find out in which sections manual pages reside on passwd, using whatis. Look at both sections 1 and 5 of the passwd man pages; what is the difference? Now use apropos on the term passwd. What do you notice?

Contents