mandb

Purge and process manual pages

$ mandb

$ mandb --filename [path/to/file]

$ mandb --create

$ mandb --user-db

$ mandb --no-purge

$ mandb --test

mandb [OPTIONS] [manpath...]

-d, --debug
    Emits verbose debugging messages to standard error, useful for troubleshooting.

-h, --help
    Displays a help message with usage information and exits.

-q, --quiet
    Suppresses warnings and non-error messages during operation, providing a cleaner output.

-U, --system
    Updates the system-wide man page cache. This is the default action if no specific manpath is provided as an argument.

-c, --create
    Forces the creation of caches even if they do not exist. This behavior is often implicitly handled when needed.

--rebuild
    Forces a complete rebuild of the caches, even if they appear to be up-to-date. This is useful for resolving potential inconsistencies or corruption.

--no-rebuild
    Prevents the rebuilding of caches that are already up-to-date. This can speed up operations if only new paths are being added or existing ones are already current.

-u user-id, --user-id=user-id
    Runs as the specified user ID, primarily used for testing purposes or for updating caches for a specific user's man path.

--version
    Displays the version information of the mandb utility and exits.

manpath...
    One or more colon-separated man paths to be processed. If omitted, mandb processes all system man paths as defined in configuration files.

mandb is a utility used to create or update the indexes (also known as whatis databases) required by the man, apropos, and whatis commands. These indexes contain a short description of each manual page, extracted from its NAME section. By maintaining these databases, mandb enables quick and efficient searches for man pages based on keywords, vastly improving the usability of the man page system.

When executed, mandb scans the manual page hierarchies defined in the system's man path configuration (typically from man.conf or manpath.conf). It intelligently detects newly installed or removed man pages, compressed pages, and symbolic links, ensuring the indexes accurately reflect the current state of the man page collection. While it can be run manually, mandb is commonly scheduled to run periodically via a cron job to keep the man page databases up-to-date. This ensures that keyword searches always yield accurate and comprehensive results.

Running mandb on very large man page collections can be time-consuming and resource-intensive, especially with the --rebuild option. It typically requires write permissions to the cache directories, which often means running it as root or via sudo for system-wide updates.

mandb operates by scanning the designated man page directories. For each man page found, it extracts the content from the NAME section (which typically provides a single-line summary of the command or function). This extracted information, along with the path to the man page, is then compiled into a plain-text whatis database file (historically called whatis.db or man.idx, now often managed by specific utilities like catman or embedded within a GDBM database). These databases allow commands like apropos and whatis to perform fast keyword lookups without having to read and parse every man page individually.

For mandb to successfully update system-wide man page caches, it requires appropriate write permissions to the cache directories. These directories are typically located within the man page hierarchy itself (e.g., /var/cache/man/ or within each manX directory). For this reason, mandb is frequently run with superuser privileges (e.g., using sudo) when performing system-wide updates.

To ensure that the man page indexes remain current as software is installed or removed, mandb is commonly integrated into system maintenance routines. Many Linux distributions configure a daily or weekly cron job (e.g., via /etc/cron.daily/man-db) to automatically run mandb, thereby keeping the whatis databases synchronized with the actual man page collection.

mandb is a core component of the man-db package, which serves as the standard man page utility suite on most modern Linux distributions. Developed to improve upon older man page implementations, man-db (and thus mandb) introduced significant enhancements in search efficiency and database management by implementing the whatis database system. Its design facilitates rapid keyword searching through a pre-indexed collection of man pages, making the documentation system much more usable and dynamic compared to systems that relied solely on sequential scanning.

man(1), apropos(1), whatis(1), catman(8), manpath(1)