Project3.Get the Most from the Unix Manual

Project 3. Get the Most from the Unix Manual

This project introduces the Unix manualthe system of "help files" that explains Unix commands. It shows how the manual works, how to use it most effectively to learn commands, and how to discover new ones.

Tip

The man command itself has a manual page!

Without the visual clues afforded by a graphical interface, Unix commands can be difficult to use. Fortunately, all (almost all) commands include documentation on what they do, the options they provide, and how to use them. When a Unix command is installed, a manual page is installed too. All manual pages are accessible via the command man. If you are not sure how to use a command, read its manual page. Let's have a look at the man page for ls.

$ man ls LS(1)         BSD General Commands Manual        LS(1) NAME      ls -- list directory contents SYNOPSIS      ls [-ABCFGHLPRTWZabcdefghiklmnopqrstuwx1] [file ...] DESCRIPTION      For each operand that names a file of a type ...      -A      List all entries except for . and ... ...

A manual page is displayed a screenful at a time. Press Return to scroll line by line, the spacebar to scroll screen by screen, and q to quit. The style of manual pages is more reference than tutorial. The pages do not make light reading, but the necessary information is there. Almost all man pages have the same basic format:

• SYNOPSIS. Lists the available options followed by mandatory and optional arguments. Items enclosed in [square brackets] are optional, and those followed by an ellipsis (...) can be repeated any number of times.

• DESCRIPTION. Includes a list of options that may be given to the command. This is probably the most useful part of the man page.

• EXAMPLES. Useful but generally underused. If the rest of the man page is hard going, refer to this section.

• SEE ALSO. If the command does not quite hit the spot, check this section for related commands.

• FILES. Where a command reads system files, perhaps for configuration information, this section will name them.

Tip

The job of displaying man pages is given to the command less. Refer to Project 2 for more information on using less. Alternatively, just type man less. To save scrolling through the manual looking for a particular section, use search. Type /SEE ALSO; then press Return to jump straight to the SEE ALSO section. Because man uses less to display its results, you are able to search a manual page by typing /searchterm and then pressing Return.

Note

The results you see from running man -k and whatis may vary if you have not installed Apple's Developer Tools or X11.

Search by Keyword

You may want to perform a certain task but cannot think of a suitable Unix command that might do so. You might flip through this book looking for a suitable project. Alternatively, man provides a search option -k to locate a suitable command by keyword lookup. There's also a command called apropos that's equivalent to man -k; either can be used.

As an example, locate commands to change the owner of a file thus.

$ man -k owner Tk_OwnSelection(3tcl) - make a window the owner of ... chown(2), fchown(2), lchown(2) - change owner and g... chown(8)                 - change file owner and gr... XSetSelectionOwner(3), XGetSelectionOwner(3), Xconv... XtOwnSelection(3), XtDisownSe... - set selection owner

You'll notice that each command name has a bracketed number after it. The number is the manual section in which the command is documented. Manual sections are covered later; for now, consider just commands from sections 1 and 8. The command we want is chown, but chown(8), not chown(2). Look up the chown variant from Section 8 by specifying the section number.

$ man 8 chown

Note

In versions of Mac OS X prior to 10.4 (Tiger), whatis searches the entire synopsis line like apropos but matches only whole words.

When you request a keyword search, man searches the synopsis line of every manual page, attempting to match the keyword. The match is not case sensitive, and the keyword may match either a complete word or a partial word. Try searching for own instead of owner, and you'll get a lot more matches.

makewhatis.local

There's also a command called makewhatis .local that operates only on locally mounted file systems. It's not prudent to rebuild the databases on another machine.

whatis

The command man -f or its equivalent, whatis, displays the synopsis line of the given command, making for a quick reminder as to what the command does.

$ whatis chown chown(2), fchown(2), lchown(2) - change owner and grou... chown(8)                 - change file owner and group

Whereas apropos matches a complete or partial word across the entire synopsis line, whatis matches only complete command names.

Learn More

Project 72 tells you more about periodic maintenance, and Projects 70 and 71 cover execution of scheduled commands.

Tip

The keyword given to apropos and whatis is treated as a regular expression, so you can realize more selective searches by using a (quoted) regular expression instead of a plain word. Project 77 covers regular expressions.

The whatis Database

To speed searching, man, apropos, and whatis do not read man pages directly, but rely on a prebuilt database containing all synopsis lines. The database is rebuilt automatically each week, but only when your Mac is switched on during the early hours of Saturday. If this is not the case, or if you have recently added new commands, you may have to build or update the whatis database manually.

You will most likely have whatis databases in the following directories:

• /usr/share/man for standard OS X commands

• /usr/local/man for commands you have installed yourself

• /usr/X11R6/man for X11 commands

Rebuild any or all of the above databases with the command makewhatis. To rebuild /usr/share/man/whatis (/usr/share/man/whatis.db pre 10.4, or Tiger), use the following command, typing your administrator password when prompted.

$ sudo /usr/libexec/makewhatis /usr/share/man Password: $

The Nine Manual Sections

The Unix manual is divided into nine sections, and the manual page for a command is listed in the section most appropriate to the command's function. These are the sections, listed in order of general usefulness:

• Section (1) user commands

• Section (8) system commands

• Section (5) configuration file formats

• Sections (6), (7) miscellaneous

• Sections (2), (3), (4) library calls for programmers

• Section (9) kernel developer's manual

Tip

Generate a list all the commands in a particular section by clever use of apropos. To list the commands in section (1), sorting them in order, type

$ apropos "(1)" | ¬    sort -df

The command man searches for a command section by section and returns the first entry it finds. Therefore, if a command of the same name lies in more than one section, man will display only the first one it finds. Although the command chown appears in sections (2) and (8), only the variant from section (8) is displayed. The command man searches sections in order of general usefulness, which may or may not correspond to the order given above. Unless you are a developer looking for library calls, man will return the command you want. If necessary, tell man to consider a specific section by specifying the section number or to return results from all sections by specifying option -a.

$ man 2 chown $ man -a chown

Find out more about a manual section with

$ man <section number> intro

Example of man Use

Here's a brief example of using the manual to answer the question "How do I mount a file system?" First, use apropos on the term mount.

The Man Pager

Pager refers to the command used to display man pages on the Terminal. By default, it's the command less -is (or the command more on Mac OS X 10.2 and earlier). Set the environment variable MANPAGER to change it. To use the vim editor, for example, set MANPAGER as follows.

$ declare -x MANPAGER="    col -b | vim -"

Refer to Project 4 if you wish to learn more about environment variables.

In pre-10.4 versions of Mac OS X, set PAGER instead of MANPAGER.

Learn More

Project 6 tells you all about redirection and pipelining.

$ apropos mount ... mount(8)         - mount file systems

The most appropriate candidate is mount from section (8). Next, read the man page for mount.

$ man 8 mount MOUNT(8)     BSD System Manager's Manual     MOUNT(8) ... DESCRIPTION      The mount command ..... If either special or node...      the information is taken from the fstab(5) file. ... FILES      /etc/fstab file system table SEE ALSO      mount(2), fstab(5), mount_afp(8), mount_cd9660(8)... ...

Tip

Some useful man entries are

$ man hier $ man ascii $ man re_format $ man samba

Many commands have entries in the GNU info system. Try the following:

$ info ls

$ info info

The DESCRIPTION section refers to the file fstab(5), and you'll also see a reference to this in the SEE ALSO section. The reference includes (5); this is a clue saying that more information on the format of fstab can be found by issuing the command man 5 fstab. Looking at the FILES section also tells us the absolute pathname of fstab.

$ man 5 fstab FSTAB(5)     BSD File Formats Manual      FSTAB(5) NAME      fstab -- static information about the filesystems ...