Using the Unix Manual

Every Unix command is supposed to have an associated man page that describes the command and the options available for using it. You read man pages using the man command.

Unix man pages are arranged into eight or nine sections, depending on which flavor of Unix you are using. Mac OS X uses the nine sections shown in Table 3.1 . (These are the nine standard sections from BSD Unix, plus a section for the Tcl/Tk programming language.) Look in the various subdirectories of /usr/share/man to see all the man pages that come with Mac OS X.

Table 3.1. Sections of the Mac OS X/BSD Unix Manual

S ECTION	C ONTENTS
1	General Commands	Commands you use most frequently, such as man and grep .
2	System Calls	Commands (actually functions ) provided by the operating system for use in programming, mostly in the C language, such as getlogin and setuid .
3	Library Functions	Tools for programmers that are available in a variety of languages (C, Perl, Tcl, and others), such as opendir and Text::Soundex .
4	Kernel Interfaces Manual	More-advanced tools for programmers, mostly in the C language, such as stdout and urandom .
5	System File Formats	Man pages for the most important system-configuration files, describing their use for system administration, such as appletalk.cfg and launchd.conf.
6	Games	This covers games, but Mac OS X comes with only one command-line game, banner . If you have a printer connected, try banner -w 80 "Unix" lp .
7	Miscellaneous Information	Character-set definitions; file types; filesystem information, such as hier , which shows the filesystem hierarchy; and ascii , which describes the ASCII character set.
8	System Manager's Manual	Servers and system-administration commands, such as halt (to shut down the system) and httpd (the Apache Web server).
9	Kernel Developer's Manual Tcl and Tk Built-in Command	The Tcl/Tk programming language gets its own section of the Unix manual, describing all of the Tcl functions and libraries available, such as lindex and tk_messageBox . See man tclsh for an interactive Tcl shell.
Look in the various subdirectories of /usr/share/man to see all man pages that come with Mac OS X.

Wherever you see a Unix command name followed by a number in parenthesesfor example, date(1) the number refers to the section of the manual with which the command is associated. Thus, chown(2) refers to the chown documented in section 2 of the manual, while chown(8) refers to the chown documented in section 8 of the manual.

Throughout this book we use the Unix convention of referring to a manual entry by saying "see man enTRy. " entry is usually a command namefor example, we might say "see man ls " to look at the manual entry of the ls command. entry can also represent anything else the manual covers; some system-configuration files have manual entries.

To display a man page:

1.

The short answer is: man command For example, man man shows you the man page for the man command. Figure 3.1 is a code listing showing the beginning of the Unix man page for the man command. It is probably rather confusing at this point, which is why we have this chapter to explain Unix man pages. Figure 3.1. Typing man man lets you see the man page for the man command itself (this is partial output). [localhost:~] vanilla% man man man(1) man(1) NAME man - format and display the on-line manual pages SYNOPSIS man [ -acdfFhkKtwW ] [ --path ] [ -m system] [ -p string] [ -C config_file] [ -M pathlist] [ -P pager] [ -S section_list] [section] name ... DESCRIPTION man formats and displays the on-line manual pages. If you specify sec- tion , man only looks in that section of the manual. name is normally the name of the manual page, which is typically the name of a command, function, or file. However, if name contains a slash ( / ) then man interprets it as a file specification, so that you can do man ./foo.5 or even man /cd/foo/bar.1.gz . See below for a description of where man looks for the manual page files. OPTIONS -C config_file Specify the configuration file to use; the default is /usr/share/misc/man.conf . (See man.conf (5).) -M path Specify the list of directories to search for man pages. Sepa- rate the directories with colons. An empty list is the same as not specifying -M at all. See SEARCH PATH FOR MANUAL PAGES . -P pager Specify which pager to use. This option overrides the MANPAGER environment variable, which in turn overrides the PAGER vari- able. By default, man uses /usr/bin/less -is .

2.

Here is a longer, more useful answer. The generalized syntax of how to display a Unix man page is this: man [-acdfFhkKtwW] [path] [-m system] [-p string] [-C config_file] [-M pathlist] [-P pager] [-S section_list] [section] name ... What does that mean? It is the technical way in which Unix command syntax is described. This format, though daunting at first, is a concise and accurate way of showing how a command should be used, and you will see this format constantly in Unix documentation. The man pages for commands all begin with a synopsis of the command using the format shown above. It is well worth your time to learn this syntax. Figure 3.2 shows an element-by-element translation of the specification for the man command itself. Figure 3.2. The man pages for commands all begin with a synopsis of the command using this format. According to the specification, the only required argument to the man command is the name of the manual entry you want (it is the only argument not inside square brackets), but there are many available options. You must read the man page itself to learn what the options mean. Here are the meanings for the options you are most likely to use:

-a	Displays all the man pages that match the command name you supply (the final argument to the man command). Normally the man command shows only the first match (searching the manual starting from section 1).
-d	Displays debugging information instead of the actual manual page(s).
-k	Finds a list of the manual pages that contain the entry in their one-line description. (The entry is the final, and required, argument to the man command.) man -k string is the same as apropros string . See "To search for a man page," below.
-K	Similar to the -k (lowercase) option, but searches the full text of all man pages for the string. Can be slow but is very useful.
-h	Displays a help message for the man command.
-t	Produces PostScript output by passing the output of the man command through another program (called troff ). If you use this option, you will almost certainly want to save the output in a file or pipe it to a program that understands PostScript. (See "Printing man Pages," later in this chapter, and "Redirecting stdout " and "Creating Pipelines of Commands," in Chapter 2, "Using the Command Line.")
-w	Shows the locations of the actual man page files instead of showing the pages themselves . Try combining this with -a .
-M	You must supply a list of one or more directories (separated by colons) right after this option. The directories are searched for man pages instead of the default locations (which are all in /usr/share/man ).

Tips

• Print a pretty version of a man page with

  man -t name lp

• Use the man command to read about each new command in this book. Many commands have options that go beyond what we're covering.

• In some cases, man pages in two sections of the manual have the same name. Using the -a switch displays all the entries for a given name.

• Look at the ends of most man pages for a "SEE ALSO" section that lists related commands. A related command might be more useful than the one you first thought to use.

Sometimes you may not be sure which command you want. The apropos command can be used to search the title lines of all the manual pages.

To search for a man page:

• apropos keyword
  
  For example, if you were looking for commands related to appletalk , you would try
  
  apropos appletalk
  
  Figure 3.3 shows the result (reformatted slightly for print). Each entry lists the name of a man page, the section it belongs to, and usually a one-line description of the man entry.
  
  

  Figure 3.3. The apropos command can be used to search the title lines of all the manual pages.

   user-vc8f9gd:~ vanilla$  apropos appletalk  appleping(1)     -    exercises the AppleTalk network by sending packets to a named host appletalk(8)     -    enables you to configure and display AppleTalk network interfaces at_cho_prn(8)    -    allows you to choose a default printer on the AppleTalk internet atlookup(1)      -    looks up network-visible entities (NVEs) registered on the                       AppleTalk network system atprint(1)       -    transfer data to a printer using AppleTalk protocols atstatus(1)      -    displays status information from an AppleTalk device user-vc8f9gd:~ vanilla$ 

  
  

Tips

• Of course, you can try man apropos to learn more about the apropos command.

• On many Unix systems (including Mac OS X), man -k is the same as apropos .

• You can also search for man pages by looking in the directories inside /usr/share/man and /usr/local/man .

• The apropos command searches the "whatis" database, which is updated every Sunday morning starting at 3:15 a.m. as long as your Mac is on at that time. You can manually update the database with the following command:

  sudo /usr/libexec/makewhatis.local

  You will be prompted for your password, and the command will take a while to run. (See "Running Regularly Scheduled Commands" in Chapter 11, "Introduction to System Administration.")