Find, Read and Search Manual Pages with man

You know printf exists in both a shell built-in and a C library, and man opens the wrong one unless you tell it which section you mean. This guide covers finding the page you actually need, reading a given section, searching descriptions, listing every match, checking a local draft, and formatting output for a script. Examples target man-db 2.12.0.

Prerequisites: a shell and the man-db package. Reading pages needs no elevated privileges. Allow about 10 minutes for the basic workflow, longer if you are chasing a broken manual installation. Every command here only inspects pages; none changes system configuration.

1. Confirm which man you are running

Check the executable and its version:

command -v man
man --version

Expect /usr/bin/man and a line such as man 2.12.0. man is the pager, not the manuals themselves: pages live below a manual path, commonly /usr/share/man.

2. Read a command page, and pick the right section

Open the page for a command whose behaviour you need to check:

man ls

• man searches sections in a configured order and shows the first match. Press q to leave the pager.
• The section number in the heading is the clue. Section 1 is executables and shell commands, section 5 is file formats and conventions, section 8 is system administration.

A page name can exist in more than one section: printf has both a command page and a library page. Give the section explicitly when the default is not what you meant:

man 1 printf
man 3 printf

If you are copying a cross-reference from another page, the parenthesised form works too, quoted so the shell does not eat the brackets:

man 'printf(3)'

3. Treat the section number as meaning, not decoration

• 1: commands and executable programs
• 2: system calls provided by the kernel
• 3: library calls
• 4: special files, often under /dev
• 5: file formats and conventions
• 7: miscellaneous conventions and macro packages
• 8: system administration commands

Section names can carry extensions. If two packages ship similarly named pages, -e narrows the search to a sub-extension, something you only tend to need when a page explicitly names a package-specific form such as exit(3tcl).

4. Search before guessing the page name

Search short names and descriptions for a keyword:

man -k printf
man --apropos 'network.*socket'

-k treats its argument as a regular expression, roughly the same operation as apropos. Quote the pattern so the shell does not expand it. Anchor it for an exact-looking name search:

man -k '^printf$'

To check whether a named page exists and see its one-line description, use -f:

man -f ls

ls (1)               - list directory contents

A search hit is not proof it is the right page. Read NAME, SYNOPSIS, OPTIONS and EXIT STATUS, and check the version or distribution where behaviour actually matters.

5. List every matching page before choosing

Display every duplicate before you pick one:

man -aw printf

-a shows every matching page in succession; -w prints their source locations instead of opening them. On this installation, a single match looks like:

/usr/share/man/man1/printf.1.gz

The default section order can be changed by MANSECT, by -s or -S, and by system configuration. If a familiar command suddenly opens the wrong page, check the environment and reset command-line options inherited from MANOPT:

printf '%s\n' "MANSECT=$MANSECT"
printf '%s\n' "MANOPT=$MANOPT"
man -D -w man

-D has to be the first option when you want man to forget what MANOPT supplied. It resets man's option state; it does not repair a bad manual database.

6. Inspect a local manual file

Use local mode when the page is a file you are editing or reviewing, not something installed:

man -l ./example.1

-l treats the argument as an nroff manual source file. Compressed files it supports are decompressed automatically, and a hyphen reads source from standard input. A path with a slash in it also triggers local-file handling even without -l, but stating -l makes the intent obvious.

Local mode does not add the page to the system collection and does not create a cat page, which makes it the right way to check a draft. Keep the file readable by your own user; reach for elevated privileges only if the file itself is protected, and prefer copying a draft somewhere temporary over changing its permissions.

7. Save or transform output without breaking the pipe

For scripts and diagnostics, pick a non-interactive pager. MANPAGER overrides PAGER, and man falls back to pager or cat when neither is usable:

MANPAGER=cat man ls
MANPAGER=cat man -f ls

Warning: do not put a pipe inside the pager value. man accepts a command and its arguments, not a pipeline. Format to standard output instead, or wrap it in a small script whose behaviour you control.

To capture the formatted terminal version for machine reading, redirect a non-interactive run:

MANPAGER=cat man ls > /tmp/ls-man.txt
sed -n '1,25p' /tmp/ls-man.txt

For typeset output, -t sends groff output to standard output; a device option such as -T implies -t too. Write to a new temporary path and inspect it before renaming, since redirecting formatted output can overwrite an existing file you meant to keep.

Common traps

• No manual entry: try man -k keyword, check the section, and inspect MANPATH. The page might be in a package you have not installed.
• Several plausible pages: run man -aw name, then choose a section explicitly. Pairs of names can also be read as subpages, so use --no-subpages when testing that.
• Stale or missing results: man -u updates man's caches, but the man page itself calls this rare and points to mandb(8) instead. Updating the database can need write access to system cache directories, so ask an administrator rather than reaching for sudo automatically.
• Unreadable terminal formatting: try MANPAGER=cat man page, or --ascii on a terminal that cannot render the usual character set.
• Unexpected language: LC_MESSAGES and LANG decide which translation you get. Use man -L C page for a reproducible check in the C locale.

Most failures leave a useful exit status: 0 is success, 1 is a usage or configuration error, 2 is an operational error, 3 means a child process failed, and 16 means at least one requested page, file or search term was not found.

Done means

• You confirmed the installed man-db version.
• You can pick a section deliberately, such as man 1 name versus man 3 name.
• You can search with -k and verify with -f.
• You can list sources with -w and review every match with -a.
• You can check a draft with -l and capture output without an interactive pager.