Find the Right Manual Page with whatis

You half remember a command's name, but man needs the exact one, so whatis searches page names and one-line descriptions instead. The examples use whatis 2.12.0 from man-db 2.12.0-4build2 on this machine.

Allow about ten minutes. You need a shell and the man-db utilities. Everything here is read-only: no root privileges are needed, and none of the commands edits a manual page or rebuilds the index.

1. Check the installed command

Confirm that your shell will run the expected executable and record its version:

$ command -v whatis
/usr/bin/whatis
$ whatis --version
whatis 2.12.0

Your version may differ, so keep it in mind when comparing output with another host. This guide describes the options documented by the installed 2.12.0 manual page, not whatever another operating system happens to ship.

Checkpoint: if command -v whatis prints nothing, stop here. Install the package through your normal distribution process, or use the full path to an existing installation. Do not respond to a missing command by changing PATH blindly.

2. Run the exact-name search

Give whatis one or more names as ordinary arguments. With no search mode selected, it looks up matching manual page names and prints their short descriptions:

$ whatis whatis
whatis (1)           - display one-line manual page descriptions

The number in parentheses is the manual section, and the description comes from the page's NAME entry. A successful lookup normally exits with status 0:

$ whatis whatis > /tmp/whatis-check.txt
$ printf 'exit status: %s\n' "$?"
exit status: 0

The redirection is only a convenient way to inspect the exit status without losing the output. It creates a harmless file under /tmp; remove it later if you do not need it.

Tip: names are not shell commands. whatis tar searches for pages named tar, it does not run tar, inspect its binary, or open the page. Once you have a likely name, use man to read the full manual.

3. Search several names at once

Pass multiple names when you are comparing related interfaces:

$ whatis whatis apropos man
apropos (1)          - search the manual page names and descriptions
man (1)              - an interface to the system reference manuals
whatis (1)           - display one-line manual page descriptions

Output order and spacing depend on the installed index and terminal width. Treat the lines as candidates, not a guarantee that the pages are installed in every section on every host.

4. Limit the search to a manual section

Use -s, or its long form --sections, when the same name exists in several parts of the manual. A simple section such as 1 includes extensions such as 1perl and 1x; a section with an extension selects that exact part:

$ whatis -s 1 whatis
whatis (1)           - display one-line manual page descriptions
$ whatis --sections=1,8 mount
mount (8)            - mount a filesystem

The section list is comma- or colon-separated. Numbers are conventions, not a promise that every distribution uses identical contents: on a typical system, section 1 holds commands and section 8 holds administration commands, but inspect the result and then use man 1 name or man 8 name to pick the page explicitly.

Tip: adding -s does not make a missing page appear, it only narrows the set searched. If the unqualified search finds nothing, check the spelling and installation first, then investigate the search path.

5. Use shell-style wildcards deliberately

With -w or --wildcard, the name is a shell-style pattern that must match the entire manual page name. Quote the pattern so your shell does not expand it against ordinary files in the current directory:

$ whatis -w 'what*'
whatis (1)           - display one-line manual page descriptions

Without the quotes, the shell may replace what* before whatis ever sees it, producing an unrelated search or a confusing error. Wildcard matching is also slower than a plain name lookup, because the database has more work to do.

6. Use a regular expression for a broader name search

Use -r or --regex when a regular expression suits the job better than shell wildcards. The expression can match part of a page name; quote it for the same shell-safety reason:

$ whatis -r '^what'
whatis (1)           - display one-line manual page descriptions

Regular expressions and wildcards are easy to confuse. ^what means a name beginning with what in regular-expression syntax; the wildcard equivalent is generally 'what*', where the asterisk means any sequence of characters. Neither mode searches the prose of every manual page: whatis only searches indexed page names and their short descriptions.

7. Make long descriptions easier to inspect

By default, output is trimmed to the terminal width. That avoids untidy lines from poorly formed NAME sections, but it can hide the end of a description. Use -l or --long when the complete line matters:

$ whatis --long whatis
whatis (1)           - display one-line manual page descriptions

The visible difference may only show up for a page with a long description or a narrow terminal. MANWIDTH also controls the width whatis uses. For a reproducible inspection, set it for one command rather than editing a shell profile:

$ MANWIDTH=120 whatis --long whatis

8. Diagnose a result that is not found

A normal miss is not a crash. The command reports nothing appropriate and exits with status 16:

$ whatis definitely-no-such-page
definitely-no-such-page: nothing appropriate.
$ printf 'exit status: %s\n' "$?"
exit status: 16

Status 16 means no indexed entry matched the criteria, which matters in scripts where a no-match result must not be mistaken for success. Status 1 means a usage, syntax, or configuration-file error; status 2 means an operational error.

Check these causes in order:

  1. Confirm the spelling and try the exact command or package name.
  2. Try a quoted wildcard or regular expression if you only know part of the name.
  3. Check that the relevant manual package is installed and that its files are in a manual hierarchy.
  4. Check MANPATH if this host uses a custom manual location.

whatis searches index databases, not a fresh scan of every file for each invocation. Those indexes are updated by mandb, and on some installations a periodic job keeps them current; after installing manual pages, a stale index can explain a miss.

Warning: do not run mandb as a reflex. Rebuilding a system-wide index changes files under locations such as /var/cache/man and may require elevated privileges. First establish that the page really exists and that the manual hierarchy is meant to be indexed. If you administer the host and decide an index refresh is needed, follow your distribution's package-management procedure and check the resulting files before relying on the new index.

9. Check the search path without changing it

Inspect the current value of MANPATH without exporting a replacement:

$ printf 'MANPATH=%s\n' "${MANPATH-}"
MANPATH=

An empty or unset MANPATH is not automatically an error: the installed manual says whatis can determine an appropriate path from PATH in that case. If a custom value is set, it is read as a colon-delimited list of manual hierarchies and overrides that default.

For a one-off test, supply an explicit hierarchy with -M rather than editing a profile:

$ whatis -M /usr/share/man whatis
whatis (1)           - display one-line manual page descriptions

This does not repair a missing database, it only tells this invocation where to search. The same principle applies to locale: -L C can make a one-off result predictable, while the environment and configured locale remain unchanged.

Done means