man VARIATIONS, apropos, whatis

If you know the command you’d like to look up, use man -f, or whatis, followed by the command name.

For example, to print a summary for the date command, type:

>man -f date
date (1)             - print or set the system date and time
END

A short description of what date does is returned. Press q to return to the command line.

If you’re not quite sure what you’re looking for, man -f and whatis search the description of each available command for matching keywords. If you experience any errors while running these commands it might be because the whatis database has been removed from your system, or has not been created. You’ll need to contact your system administrator and ask her or him to use makewhatis to generate the database files necessary to use whatis. Because this is a function that affects protected areas of the system, it is not available to most users.

Now, try running whatis on the subject time. This turns up several relevant entries.

>whatis time
time (2)             - get time in seconds
time (n)             - Time the execution of a script
Time::Local (3)      - efficiently compute time from local and
                       GMT time
Time::gmtime (3)     - by-name interface to Perl's built-in
                       gmtime() function
Time::localtime (3)  - by-name interface to Perl's built-in
                       localtime() function
Time::tm (3)         - internal object used by Time::gmtime and
                       Time::localtime
END

You can see that the time keyword has turned up six different entries in the whatis database. To return to the command prompt, you’ll need to press q.

---

Tip:  
What do the Letters and Numbers Mean?  You’ve probably noticed that some commands are followed by a letter or numeral; this is the section number for that command. For instance, time is followed by both n and 2. This means that there are two separate uses for the time command. To learn information about each of the variations, use man followed by the section number or letter and the command. For example, man n time or man 2 time.

---

If you’re entirely unsure of what you want and a keyword search does not return anything useful, try the apropos or man -k command. This searches the descriptions much like whatis does, but also displays partial matches to the string you specify.

Try running apropos on time and compare your results with the results from the similar whatis time command:

>apropos time
clock (3)            - Determine processor time
clock (n)            - Obtain and manipulate time
convdate (1)         - convert time/date strings and numbers
date (1)             - print or set the system date and time
difftime (3)         - calculate time difference
ftime (3)            - return date and time
ftpshut (8)          - close down the ftp servers at a given
                       time
kbdrate (8)          - reset the keyboard repeat rate and delay
                       time
ldconfig (8)         - determine run-time link bindings
metamail (1)         - infrastructure for mailcap-based
                       multimedia mail handling
nanosleep (2)        - pause execution for a specified time
nwfstime (1)         - Display / Set a NetWare server's date
                       and time
parsedate (3)        - convert time and date string to number
...

This command actually turned up more than 70 matches on my system, far more than whatis time displayed. Try to be as specific as possible when you use apropos or man -k, or you might spend a great deal of time wading through extraneous information. Don’t forget, the ... means there’s more information to be accessed by pressing the spacebar. As before, pressing q returns you to the command prompt.

Built-in Help

Many of the common UNIX commands have a built-in help that isn’t as verbose as the man pages—and it can be brought up in a jiffy. If you find that you’re constantly using the man pages to find the options that are available for a specific command, you might want to see if it has its own help summary page. If you’ve spent much time using the compression or archiving utilities, you’ll know what I mean. For many commands --help provides the information you need. In some cases, it might be as simple as -h or -?. If the first one doesn’t work, try again. It’s quite possible that built-in help is not available, so don’t be surprised if you run into cases where this doesn’t work as you had hoped.

To view the built-in help for the date command, type:

>date --help
Usage: date [OPTION]... [+FORMAT]
  or:  date [OPTION] [MMDDhhmm[[CC]YY][.ss]]
Display the current time in the given FORMAT, or set the system
date.

  -d, --date=STRING        display time described by STRING,
                           not `now'
  -f, --file=DATEFILE      like --date once for each line of
                           DATEFILE
  -r, --reference=FILE     display the last modification time
                           of FILE
  -R, --rfc-822            output RFC-822 compliant date string
  -s, --set=STRING         set time described by STRING
  -u, --utc, --universal   print or set Coordinated Universal
                           Time
      --help               display this help and exit
      --version            output version information and exit
...

Although not as descriptive as the man pages, the information is useful and to the point.

Depending on the resources that are available, your system administrator might have chosen to forgo the installation of man pages on your UNIX system. The amount of disk space used by the manual pages is not trivial, and in these cases you’ll learn to appreciate the built-in help feature provided by many applications.