Help Resources

The previous lesson used the mkdir -p option and explained what it does in the text. That is not a sustainable way to learn: dozens of options across hundreds of commands cannot be memorized.

The system does not require it. Every command’s documentation is installed along with the command itself, and the documentation follows a consistent structure. This lesson introduces that structure; for the rest of the course, some options will be left for the reader to look up rather than explained in the text.

Manual Pages

A manual page is the reference document for a command, file format, or system call. It is displayed with the man command:

$ man 1 ls | sed -n '1,13p'
LS(1)                            User Commands                           LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List  information  about  the FILEs (the current directory by default).
       Sort entries alphabetically if none of -cftuvSUX nor --sort  is  speci-
       fied.

Only the page’s first lines are taken in this example; typing man ls directly opens the page in a pager program, navigated with the arrow keys and exited with q. Searching inside the pager is done with /.

Manual pages carry standard subheadings. The most commonly used, in order:

• NAME — the command’s name and a one-line description
• SYNOPSIS — the usage summary
• DESCRIPTION — detailed behavior and the option list
• EXIT STATUS — which exit code is returned under which condition
• FILES — the files the command reads or writes
• SEE ALSO — related pages

To quickly confirm a command’s behavior, NAME and SYNOPSIS are read in that order; for detail, DESCRIPTION. When investigating the cause of an error, the EXIT STATUS and FILES sections often answer directly.

Reading the Usage Synopsis

The SYNOPSIS line uses a notation, and that notation is the same across every manual page:

Notation	Meaning
plain text	Written exactly as shown
[...]	Contents in brackets are optional
...	The preceding item can repeat
a|b	One of the alternatives
UPPERCASE	A placeholder to be replaced with a value

Accordingly, the line ls [OPTION]... [FILE]... says: ls takes zero or more options and zero or more filenames; neither is required. ls can run with no arguments at all; this is consistent with the phrase “the current directory by default” in DESCRIPTION.

For comparison, another command’s synopsis:

$ mkdir --help | head -9
Usage: mkdir [OPTION]... DIRECTORY...
Create the DIRECTORY(ies), if they do not already exist.

Mandatory arguments to long options are mandatory for short options too.
  -m, --mode=MODE   set file mode (as in chmod), not a=rwx - umask
  -p, --parents     no error if existing, make parent directories as needed,
                    with their file modes unaffected by any -m option.
  -v, --verbose     print a message for each created directory
  -Z                   set SELinux security context of each created directory

DIRECTORY... is not in brackets: at least one directory name is required. The two separate functions of the -p option used in the previous lesson are both written here — creating missing parent directories and not erroring on an existing one.

The --help option does not substitute for the manual page; on most commands it gives only the option list. On the other hand, it is always fast and is the only source on systems where manual pages are not installed.

Section Numbers

The manual is not a single set but is divided into numbered sections. The same name can appear in more than one section and describe different things.

Section	Contents
1	User commands
2	System calls
3	Library functions
4	Special files and devices
5	File formats and configuration files
6	Games
7	Miscellaneous: conventions, notations, concepts
8	System administration commands

What the section division is for can be shown with a single name:

$ whatis passwd
passwd (1)           - change user password
passwd (1ssl)        - OpenSSL application commands
passwd (5)           - the password file

passwd is both a command and a file format. The entries in the list depend on the packages installed on the system; a page for software that is not installed does not appear. Suffixed section names like 1ssl in the middle line come from a piece of software keeping its own pages in a separate subsection.

man passwd shows only the first one found — section 1. To see the file format, the section is given explicitly:

$ man 5 passwd | sed -n '1,10p'
PASSWD(5)               File Formats and Configuration               PASSWD(5)

NAME
       passwd - the password file

DESCRIPTION
       /etc/passwd contains one line for each user account, with seven fields
       delimited by colons (":"). These fields are:

       o   login name

The PASSWD(5) notation in the page header repeats which section you are in, on every line. Documentation carries notations like printf(3) or open(2); the number in parentheses is the section number, and it identifies which printf is meant — a shell command or a library function.

This section’s definition of the user account file will be used directly in the Users and Permissions topic.

Searching When the Name Is Unknown

The manual is useful once a command’s name is known. If the name is not known, the descriptions are searched:

$ man -k 'list directory' | head -3
dir (1)              - list directory contents
ls (1)               - list directory contents
vdir (1)             - list directory contents

man -k (equivalent to apropos) searches the NAME lines of every manual page. man -f (equivalent to whatis) searches for an exact name match. Both look at a prebuilt index; if the index hasn’t been built, the result comes back empty.

The search scans only the one-line descriptions, not entire pages. This is why the result set is narrow, and the search term should be kept general.

Documentation for Builtins

The previous lesson showed that builtins are not separate programs. This has a consequence for documentation: builtins have no separate manual page, because there is no separate program. Their documentation is in the shell’s own page and in the shell’s help builtin.

$ help type | sed -n '1,6p'
type: type [-afptP] name [name ...]
    Display information about command type.

    For each NAME, indicate how it would be interpreted if used as a
    command name.

To choose the right source, the name’s type is determined first:

$ type -t ls cd if
file
builtin
keyword

The -t option prints only the type. The three answers correspond to three separate help sources: man for file, help for builtin, the shell’s manual page for keyword. if is not a command but a keyword belonging to the shell’s grammar; control structures are the subject of the Shell Programming course.

The Limits of Documentation

Manual pages are reference documents, not tutorials. They enumerate a command’s every option completely but mostly do not say when to use which one. The documentation also belongs to the version on that system: if an option is not in the manual, it genuinely is not on that system — its existing on another system changes nothing.

These two limits determine what the manual is used for. The manual answers “what does this command do”; it usually does not answer “which command do I use for this job.” The second question is this course’s subject.

Summary

• Manual pages carry standard subheadings such as NAME, SYNOPSIS, DESCRIPTION, EXIT STATUS, FILES, and SEE ALSO.
• In a usage synopsis, brackets show optionality, ellipsis shows repeatability, and uppercase names show placeholders.
• The manual is divided into numbered sections; the same name describes different things in different sections, and the name(section) notation states which one is meant.
• man -k searches description lines; it is the way to find a command whose name is unknown.
• Builtins have no separate manual page; they are documented with help, and the right source is determined with type -t.

Next Step

The type command performs a specific search to find what a name resolves to, and in the previous lesson, that same search failed when a command gave a “not found” error. The next lesson unpacks the rule behind that search: which directories the shell searches for an executable, in what order, how that order is changed, and why the current directory is not added to that list.