Publishers of technology books, eBooks, and videos for creative people

Home > Articles

Getting Help and Using the Unix Manual

  • Print
  • + Share This
  • 💬 Discuss
This chapter is from the book

There are four ways to get help when using Unix: from external documentation such as this book, Web sites, and other similar materials; from the extensive Unix reference manuals that come with every version of Unix, including Mac OS X; from the built-in help that comes with most commands; and from other people via online discussion systems, e-mail, user groups, and, yes, calling your friends on the telephone. You are already taking the first approach, so this chapter concentrates on the other three.

The Unix reference manual is a collection of files called man pages, which are specially formatted files intended to be viewed with the man command. Unix man pages are written for an audience of experienced programmers, not for novice users, so to understand Unix man pages, you need to understand the conventions used in them.

Mac OS X comes with almost 3000 Unix man pages. Most of these are copied from the FreeBSD version of Unix, the one used to create Mac OS X's Darwin layer. Some of these pages come from Apple itself, and some come from the software that Apple acquired when it bought NeXT. As of this writing (summer 2005), Apple has made progress updating the man pages to be Darwin specific, but the job is not yet done. Fortunately, most of the man pages do not require updating; unfortunately, there is no easy way to know which ones do require it.

Command-line programs almost always provide a minimal level of built-in help—usually just enough to show you the options and arguments the command expects. Still, that is often enough to remind you of the proper way to use the command.

Help from other people is the most valuable kind, and it's available from a variety of sources. At the end of this chapter is a list of the best places to look.

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

SECTION

CONTENTS

 

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 parentheses—for 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 name—for 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.

    Example 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
    
                rightarrow.jpg
              system] [-p string] [-C config_file]
    
                rightarrow.jpg
              [-M pathlist] [-P pager] [-S
    
                rightarrow.jpg
              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.
    03fig02.jpg

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

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:

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

    Example 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$
  • + Share This
  • 🔖 Save To Your Account

Discussions

comments powered by Disqus