apropos, whatis and makewhatis

This month's column looks at three very useful and related commands, apropos, whatis and makewhatis. To understand why these commands are so valuable, it helps to grasp the underlying philosophy that continues to guide evolving versions of Unix, including Linux. That philosophy remains one of creating small, portable, specialized programs that perform one task well, and that can receive input from, and redirect output to, other programs.

This philosophy has created a proliferation of small, powerful, but extremely limited programs. Just do a directory listing of /usr/bin, and you'll see what I mean. And that's not all of them. You could sit down and run every one of them to see what they do. Or you could begin reading the hundreds of man pages available describing these commands. No matter which method you use to learn the commands, in the end, you'd still probably forget most of them due to the sheer volume. So how do you know which of the hundreds of programs available can do the job for you? Or which of the commands will be best suited to your particular needs? apropos and whatis come to the rescue.

Apropos, as defined by the dictionary, means “apt; relevant; suited to the occasion, though not strictly belonging to the subject under consideration.” These definitions, particularly the last one, are totally apropos. apropos will list programs with a one line synopsis of each program based on a keyword search. whatis is similar, but even more constrained; i.e., the actual command is given as the argument, rather than a keyword, so there is less output.

Before we look at how apropos can help us, we need to ensure that the database apropos uses exists and is up-to-date. Enter makewhatis. This command creates the whatis database files used by both apropos and whatis. They are located in each ../man directory and catalog the manual files in each of the individual cat? and man? subdirectories.

To create the whatis database files, you need to invoke makewhatis as the root user. Non-privileged users normally do not have write permission in the ../man directories to create the whatis database files. A second clue to the nature of makewhatis is its location. makewhatis is usually found in the /usr/sbin subdirectory, indicating its classification as a system administration program. Ordinarily only root's PATH environment variable contains the sbin directories. makewhatis may be invoked by root's crontab file and run on a recurring basis, and you may wish to include it if it isn't already there. But that is beyond the scope of this article. If you can log in only as a non-privileged user, or are sure your whatis database files exist, you may want to skip ahead to the next section. If you begin to see <keyword>: nothing appropriate, you'll need to have your system administrator run makewhatis.

Running makewhatis for the first time will take several minutes, so be patient (go have a cup of coffee). Run by itself, makewhatis will create the whatis database file in /usr/man. To ensure that all the man locations are cataloged, use the -w switch. This will read the file /etc/man.config and use the man paths it specifies. Or you may add paths following the -w switch and they will be used as well. If you are want to know which paths will be cataloged, type man --path, and you will see where /etc/man.config believes your manuals are. If you have other paths, they should be added to your man.config file.

Another makewhatis option is -c. This switch, when used alone, will catalog only the ../man/cat entries listed in man.config. Other cat subdirectories may be added following the -c switch, and they will also be cataloged.

You may, however, want only to update the whatis databases with newly added commands. Use the -u switch to update the database files. This switch reads the time of the whatis database file and adds those manual pages created or updated since.

If you want to know what makewhatis is doing, add the -v switch, and you will see each man directory entered and each command as it is added to the list. Each switch used with makewhatis should be separated by a space and preceded by a hyphen; the switches cannot be combined. makewhatis does have one weakness: if your system does not have sufficient RAM and virtual memory, makewhatis will fail. If you get an error message—and you are running makewhatis as root—add more swap space and try again.

To search the whatis database on your system, just type:

apropos \keyword

inserting your criteria as the keyword for the search. Let's try one out. I've never used my CD-ROM player for anything more than mounting a data disk and accessing files, but I'd like to play some music while I'm working (or playing xtetris because it doesn't have music accompaniment, etc.). So I type:

apropos cdrom

and I see:

xplaycd (1)          - X based audio cd player for cdrom drives (END)

apropos uses the less pager unless your PAGER environment variable says otherwise. To exit this screen, press q. To scroll, use the up and down arrow keys, or the space bar to go down a screen at a time.

Now I'm not sure, but I believe other programs for accessing the CD exist on my system. Yes, this will work, but how about a choice? Let's try again. This time, I'll try with just CD:

apropos cd

survey says:

Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete
(3) - handle asynchronous events
cd (3)              - Change working directory
curs_window: newwin, delwin, mvwin, subwin, derwin, mvderwin,
dupwin, wsyncup, syncok, wcursyncup, wsyncdown (3) - create curses
windows
eject (1)           - eject CD-ROM disc from drive
mcd (1)             - change MSDOS directory
rexecd (8)          - remote execution server
termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush,
tcflow, cfgetospeed, cfget
ispeed, cfsetispeed, cfsetospeed, tcgetpgrp, tcsetpgrp (2)
               - get and set terminal attrib
utes, line control, get and set baud rate, get and set terminal
foreground process group ID
tin, rtin, cdtin, tind (1) - A Netnews reader
cda (1)              Compact disc digital audio player utility
wm2xmcd (1)         - workman-to-xmcd CD database file converter
xmcd (1)            - CD digital audio player utility for X11/Motif
xplaycd (1)         - X based audio cd player for cdrom drives

Now we have a problem. We can be overwhelmed with inappropriate items. If this didn't give you a long listing, try giving cat as a keyword for apropos. You'll get pages of output. (Read on to find out why.)

If you look, you can see that we got what we wanted, and a whole lot more. How can we narrow it down? Can we put two keywords on the apropos command line? Yes. Unfortunately, the keywords are logical ORed and not ANDed together, making the output even longer. But if we scan the listing, it appears most of the commands we're interested in contain the term audio. We could try "apropos audio". But let's search the previous list instead. Type:

apropos cd | grep -i audio

Our reward:

cda (1)  - Compact disc digital audio player
utility xmcd (1 - CD digital audio player utility
for X11/Motif xplaycd (1)     - X based audio cd
player for cdrom drives

Now, that's more like it! We can try these programs to see which we like best. And we know they have manual pages to help us out.

A good exercise for the reader might be to use “mail” as a keyword (this will return a very long list), then grep the list for audio to see which programs might help you e-mail sound files.

A slightly less obvious, but identical command for apropos exists. The command man -k <keyword> is synonymous, though not as mnemonic.

Finally, let's take a look at whatis. We've been accessing the whatis database files during the apropos (aka man -k) searches. Let's try our cd search using whatis instead.

whatis cd

Now we get:

cd (3)               - Change working directory

So what's the difference? Why only one entry? Think of the whatis database as columnar and containing two columns. The left column contains the program name (the command used to invoke the program) and the right side contains the first line of the manual's program synopsis. apropos searches both columns using the keyword as a regular expression to find all occurrences of the keyword. These occurrences may be embedded in the command word or the words of the synopsis. For example, apropos cat returns lines containing the word catalog, category, duplicate, application, etc. whatis, on the other hand, searches only the left hand column, which contains only the program name. This feature is helpful if you know the name of a command, but not its function.

These commands do have limitations. If a command has no corresponding manual page, it will not be listed in the database. makewhatis does not include a manual page, at least not on the author's system. If a synopsis does not contain a keyword you have chosen to search on, it will not show up. As with all tools, you may need to compare the results of several different searches or grep long search results to find the best program for your needs.

Now you have the tools to help find commands you may not use often, but are worthwhile knowing. Using apropos and whatis sure beats reading through all the manual pages. A newbie to Linux will find a lot of directory manipulation help with the dir keyword. So put apropos to work and search and learn!