Find Help with Man Pages

What you will be able to do

• Identify whether a command name resolves to a Bash builtin, alias, function, or executable.
• Read synopsis, options, exit status, files, environment, and cross-references in a manual page.
• Choose a manual section and search the local manual database by name or task.
• Verify that documentation matches the installed command and preserve a reproducible reference.

01

Identify the command before choosing its documentation

A name typed in Bash can be an alias, function, builtin, or executable file. `type -a name` shows the interpretations available in the current shell, and `command -v name` shows the command Bash would select. This prevents an operator from reading documentation for `/usr/bin/name` while an alias or function is actually running.

$ type -a printf
printf is a shell builtin
printf is /usr/bin/printf
$ command -v printf
printf

The first command reveals two implementations, while the second shows that Bash selects its builtin.

Use `help printf` for the behavior of the selected builtin; `man 1 printf` documents the separate external program.

Use `help name` for Bash builtins. `cd`, for example, changes the current shell and is documented by Bash itself. For an external executable, begin with its installed manual page or its documented `--help` output.

Record the resolved command and version when behavior is part of an incident. Documentation is useful only when it describes the program and release that received the arguments.

02

Use the narrowest trustworthy help source

Use `command --help` for a quick option reminder when the installed program provides it. Use `man command` when you need semantics, files, environment variables, exit status, examples, or related pages. Use `help builtin` when the shell itself implements the command.

Project documentation and distribution notes may be necessary for features not covered by a local page, but start locally because it is more likely to match the installed package. An online answer can still help form a question; it should not silently replace version-specific documentation.

Do not run an unfamiliar example merely to discover what it does. Read the synopsis, identify every option and operand, substitute a safe test target, and use a disposable environment when the command can change state.

03

Turn manual-page sections into an operating checklist

Start with NAME to confirm purpose and SYNOPSIS to see the accepted shape of the command. DESCRIPTION and OPTIONS explain behavior. Brackets normally mark optional syntax, alternatives are separated according to the page's notation, and an ellipsis means an item can repeat; these marks describe syntax and are not automatically characters to type.

Read EXIT STATUS when automation must distinguish success, no result, and operational failure. Read FILES and ENVIRONMENT when behavior depends on configuration paths or variables. Use NOTES, CAVEATS, BUGS, and SECURITY sections when present rather than assuming the synopsis captures every boundary.

Finish with SEE ALSO. Related pages often separate the user command, file format, library interface, and administrative database that share one concept.

04

Select the section when one name has several meanings

Manual sections distinguish kinds of interfaces. Common Linux conventions include user commands in section 1, system calls in section 2, library functions in section 3, device interfaces in section 4, and file formats in section 5; later sections cover games, conventions, administration, and kernel routines.

`man passwd` follows the configured search order and may open the command page. `man 5 passwd` requests the password-file format explicitly, while `man 1 passwd` requests the user command. Use `man -a name` when you need to review every available page for that name.

Include the section in a runbook citation, such as `sshd_config(5)`. It removes ambiguity and makes the reference useful on another host.

$ man -f passwd
passwd (1)           - change user password
passwd (5)           - the password file

The installed manual database has two pages named `passwd`: a user command in section 1 and a file format in section 5. Wording can differ by distribution, but the section numbers remove the ambiguity.

Choose `man 1 passwd` for the command or `man 5 passwd` for the file format instead of trusting the default search order.

05

Search the manual database instead of guessing command names

Use `whatis name` or `man -f name` when you know a page name and need its one-line description. Use `apropos keyword` or `man -k keyword` when you know the task but not the command. Apropos searches page names and short descriptions, normally treating the keyword as a regular expression.

Narrow a broad search with `apropos -s 8 keyword` for administrative pages or `apropos -e name` for an exact name. Quote a pattern that contains shell metacharacters so Bash does not transform it before apropos receives it.

The search depends on the local manual index. If a newly installed page is absent, confirm the package and page path before asking an administrator to refresh the database with `mandb`; do not use a database rebuild as the first response to every empty search.

06

Search inside the page without losing context

Man normally displays a page through a pager. In the common less pager, `/pattern` searches forward, `n` repeats the search, `N` reverses it, and `q` exits. Pager choice and keys can vary, so check the status line or local pager help when those bindings do not apply.

Search for the exact option, configuration filename, exit status, or environment variable involved in the task. Reading only the first screen often misses the conditions and side effects described later.

For a handoff, record the page name, section, relevant heading, and installed version. Avoid copying a long block when a precise reference and a short paraphrase preserve the decision more clearly.

07

Match the page to the installed program and host

A manual page can be missing, stale, translated differently, or supplied by another package version. Use `man -w name` to locate the selected page, identify the command with `command -v` or `type -a`, and obtain the program version through its supported version output or package manager.

Do not conclude that an option exists because a current website documents it. The host may run an older release or a distribution-specific build. Conversely, an online page can lag behind a newer local package. Test a read-only invocation when the difference affects production work.

If documentation and behavior disagree, preserve both pieces of evidence: resolved executable, version, page path, exact invocation, output, and exit status. That makes the discrepancy diagnosable instead of becoming an undocumented workaround.

$ man -w 1 passwd
/usr/share/man/man1/passwd.1.gz
$ man -w 5 passwd
/usr/share/man/man5/passwd.5.gz

Each command resolves the exact local page selected for that section. The paths and compression format may differ on another distribution.

Record the selected section and local page path when documentation must match the software installed on the host.

08

Use the correct page during a configuration incident

An SSH server rejects a directive in `/etc/ssh/sshd_config`. Begin with `type -a sshd` and the installed server version, then open `man 5 sshd_config`. The client page `ssh_config(5)` and the server daemon page `sshd(8)` answer related but different questions.

Search inside the page for the directive, read its accepted values and scope, and check any version conditions. Use the daemon's supported configuration test before restart when available; reading the page is preparation, not verification of the edited file.

Record the host version, `sshd_config(5)` heading, validated change, test output, and service result. This connects documentation to the exact configuration and observed behavior without treating a web snippet as authority.

09

Close the documentation trail with reproducible evidence

Identify what Bash will execute with `type -a` and `command -v`. Use Bash `help` for builtins and installed program documentation for external commands.

Read NAME and SYNOPSIS for identity and shape, then inspect OPTIONS, EXIT STATUS, FILES, ENVIRONMENT, caveats, and SEE ALSO according to the task.

Specify a manual section when a name is ambiguous. A command page and a configuration-file page can share a name while documenting different interfaces.

Use `whatis` when you know the page name and `apropos` when you know the task. Narrow broad results by exact name or section before selecting a page.

Match documentation to the resolved executable and installed version. Record the page, section, heading, version, invocation, output, and exit status needed to reproduce the decision.