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.

Note

To scroll back and forth in the manual page, you can use Space or Enter, Page Up/Page Down and Up/Down.

To quit a man page and return to the shell, press q.

You can also easily search a man page by first hitting / followed by the text and then Enter. Repeating the same search can be done by simply pressing n.

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.29

Find the BUGS section of the bash manual page to see what the authors think the biggest problem with it is. Tip: use / to start a word search.

According to the manual, which four of the following are part of bash’s biggest problems?

It leaks memory during long-running sessions.
It’s too big and too slow.
There are some subtle differences between bash and traditional versions of sh, mostly because of the POSIX specification.
Bash cannot run any POSIX-compliant shell scripts.
Aliases cannot be used interactively, only in scripts.
Aliases are confusing in some uses.
Stopping a process in a command list terminates the entire shell session.
Array variables may not (yet) be exported.
Bash does not support command substitution.

Exercise 2.30

According to the ncal manual page, when did the Gregorian Reformation occur in The Netherlands?

Note

For this exercise, you may need to install ncal first! In a terminal, type the following:

sudo apt install ncal

You will be asked to enter your password (the one you created for your Linux account), and then the ncal tool, and its manual, will be available in your terminal.

Find in the ncal manual the switch that lists the calendar switching dates for all country codes. Use that switch to let ncal report the date where The Netherlands transitioned from the Julian to the Gregorian calendar. Note that this command switch is only accepted by the ncal variant of the command, not cal!

2.4.5.1. Manual sections#

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:

User commands
System calls
Subroutines
Devices
File formats
Games
Miscellaneous
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.

Exercise 2.31

What does man 5 passwd show, compared to man passwd?

The same thing; section numbers do not change the output.
The passwd command for changing your password (section 5 is for user commands).
The file format of /etc/passwd, not the passwd command.
An error, because passwd only exists in one manual section.

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.32

How can you find out more about the man command itself? (Select all that apply.)

2.4.5.2. `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.33

Use whatis to find a short description of what the file command does. Then, try using apropos to list commands related to file operations.

{
  "checks": [
    { "type": "commandEvent", "eventType": "builtin.whatis",
      "match": { "names": { "$equals": ["file"] } },
      "desc": "run whatis file" },
    { "type": "commandEvent", "eventType": "builtin.apropos",
      "match": { "keyword": "file" },
      "desc": "run apropos file" }
  ]
}

The manual pages

Contents

2.4.5. The manual pages#

2.4.5.1. Manual sections#

2.4.5.2. whatis and apropos#

2.4.5.2. `whatis` and `apropos`#