Refresh Linux Manual Page Caches with catman

A man page printing raw troff instead of formatted text is usually a stale cat page, and catman is the tool that rebuilds it. It creates or updates the pre-formatted cache Linux keeps for manual pages, and this guide keeps that refresh separate in your head from actually editing a manual.

Allow about fifteen minutes. You need the man-db package and a shell. Reading the configuration and checking the command is normally unprivileged; refreshing system-wide caches usually needs elevated privileges because the configured cache is owned by the system. These examples use man-db version 2.12.0-4build2, whose installed command reports catman 2.12.0.

1. Confirm the installed command

Start with read-only checks. None of these create or update a cat page:

$ command -v catman
/usr/bin/catman
$ catman --version
catman 2.12.0
$ dpkg-query -W -f='${Package} ${Version}\n' man-db
man-db 2.12.0-4build2

If your package manager or distribution differs, treat the local catman --help and man catman output as the authority: option names and defaults move between man-db releases.

Checkpoint: the command must be available and its package must be man-db. If command -v finds nothing, stop and install the distribution package through your normal change process before continuing.

2. See which cache the system uses

catman does not pick a random output directory. It reads the hierarchies and cat paths straight from the man-db configuration:

$ grep -E '^(MANDB_MAP|SECTION|NOCACHE)' /etc/manpath.config
MANDB_MAP       /usr/man                /var/cache/man/fsstnd
MANDB_MAP       /usr/share/man          /var/cache/man
MANDB_MAP       /usr/local/man          /var/cache/man/oldlocal
MANDB_MAP       /usr/local/share/man    /var/cache/man/local
SECTION         1 n l 8 3 0 3type 3posix 3pm 3perl 3am 5 4 9 6 7

Do not edit /etc/manpath.config just to make one refresh work: it affects other users and every future man and mandb run. For a one-off test configuration, point at a separate file with -C instead.

3. Choose the sections to refresh

With no section argument, catman uses the colon-delimited sections in MANSECT if that is set, otherwise the compiled-in list or the SECTION line in /etc/manpath.config. That means an inherited shell environment can quietly change what an identical-looking command scans.

For a focused refresh, pass whitespace-delimited section names explicitly. This asks for section 8, system administration commands:

$ printf 'MANSECT=%s\n' "${MANSECT-(not set)}"
MANSECT=(not set)
$ catman 8

This updates the configured cat pages for section 8. It may print nothing when the cache is already current, or take longer and report formatting errors when source pages have changed. Supplying 8 overrides the default selection for this one run only; it does not touch MANSECT or the configuration file.

Refresh more than one section by giving separate arguments:

$ catman 5 8

Use section names exactly as your installation recognises them: extensions such as 3posix are section names, not shell glob patterns. Skip an unreviewed, broad refresh on a busy machine if a narrow one will do.

4. Refresh system caches with the required privilege

On a normal install, the system cat path under /var/cache/man is not writable by an ordinary user. Run the focused operation with sudo only when the permission check actually demands it:

$ sudo catman 8

This changes generated cache files and index data. It does not edit the source files under directories such as /usr/share/man, and it does not enable or disable any manual page. Treat it as a maintenance operation: check the section and manpath before you accept a privilege prompt.

Warning: do not add -M with an arbitrary path copied from an untrusted source. It changes the manual hierarchy search path for the run, and an unexpected path can make you format pages you never meant to touch. Do not use sudo catman -M /path/to/test-tree unless that tree and its cache mapping are part of a planned test.

There is no application-level undo for a cache refresh, but there is also nothing to fear: the source manuals stay intact, and a later catman run regenerates current cat pages. If a cache genuinely needs discarding, use your distribution's package and man-db maintenance procedure rather than deleting a broad directory under /var/cache/man by hand, which can affect every user on the box.

5. Verify the refreshed manual

Ask man for the page you meant to refresh. This reads the normal manual search path:

$ man -w catman
/usr/share/man/man8/catman.8.gz
$ man 8 catman

The first command prints the source page man selects; the second opens it in the pager. A successful refresh does not have to change the source path or print a success message, so treat this as a content and lookup check, not a transcript to match character for character.

To see whether a cat page actually exists in the configured cache, check the directory you identified in step 2:

$ find /var/cache/man -type f -name 'catman.8*' -print 2>/dev/null
/var/cache/man/cat8/catman.8.gz

The exact filename and directory can differ by man-db configuration, compression policy and locale. An empty result is not automatically a failure: the system may run with NOCACHE, store a differently named compressed page, or use a different hierarchy. Recheck MANDB_MAP before touching permissions or creating directories.

6. Diagnose a surprising result

Reach for debug output when you need to see the paths and files being selected:

$ catman --debug 8

Debug output is for diagnosis and can be verbose. It is not a dry run: if the command has permission to write, it still updates caches. Never treat --debug as a safety substitute for reviewing the arguments first.

If you hit a permission error, check the target path before reaching for elevated access:

$ ls -ld /var/cache/man
$ test -w /var/cache/man && echo writable || echo 'not writable'
$ sudo catman 8

If pages are missing, check MANPATH and the configured mappings. The -M option accepts a colon-delimited manual hierarchy search path, and the MANPATH environment variable supplies a similar per-process override. Keep both explicit in scripts, so an inherited interactive shell setting cannot silently change what gets scanned.

If a source page is malformed or a formatter fails, capture the diagnostic and inspect that one page separately with man. Do not fix a single formatting failure by wiping the whole cache: a partial refresh is easier to investigate and cheaper to repeat than a broad removal.

Done means