man Command: Usage and Options, Section Numbers, and man -k Search

To check how a command or a configuration file is used on a Linux server, open its manual page with the man command, and when you don't know the name, search the short descriptions with man -k. Looking up the passwd page on AlmaLinux 9 and Debian 12 servers showed that Debian 12 had both a section 1 command page and a section 5 file format page, while AlmaLinux 9 had no section 5 page.

The output below was produced on an AlmaLinux 9.8 server under the root account and on a Debian 12 server under a regular account. The host name and connection address in the simulator are example values.

1️⃣ Basic Usage of the man Command

Type a command name after man and the manual page for that command opens. man hands the page to a pager program that shows one screen at a time, so it does not return to the prompt right after it runs. The pager is set with the MANPAGER or PAGER environment variable, and less is used when both are empty.

Piping the output prints plain text without the pager. Taking the first 12 lines of [man ls] with head showed LS(1) on the first line, followed by the NAME, SYNOPSIS, and DESCRIPTION sections in order.

man ls | head -n 12

LS(1)                            User Commands                           LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List  information  about  the FILEs (the current directory by default).
       Sort entries alphabetically if none of -cftuvSUX nor --sort  is  speci-
       fied.

The number 1 in the parentheses of LS(1) on the first line is the number of the section that holds this page.

Inside a page, [Space] shows the next screen, and [/word] followed by Enter searches for a word. [n] moves to the next place where the same word appears, and [q] quits man.

Typing a name that does not exist gives the [No manual entry for] error, and the exit code was 16.

man no-such-cmd9

No manual entry for no-such-cmd9

echo $?

16

The EXIT STATUS section of the man page describes 16 as the value for when at least one of the pages, files, or keywords was not found. A usage error is 1, so a script can handle the two cases separately.

2️⃣ man Section Numbers

When pages with the same name exist in several sections, man searches the sections in a set order and opens only the first page it finds. Sections run from 1 to 9, and the ones opened most often in server work are section 1 for commands, section 5 for file formats, and section 8 for administration commands.

crontab has pages in two sections because the command and the configuration file format share the same name. Checking with [man -f crontab] printed the section 1 and section 5 lines together.

man -f crontab

crontab (1)          - maintains crontab files for individual users
crontab (5)          - files used to schedule the execution of programs

Running [man crontab] without a section number opens the crontab command page in section 1. To see the format of the job schedule file, put 5 before the name.

man 5 crontab | head -n 4

CRONTAB(5)                       File Formats                       CRONTAB(5)

NAME
       crontab - files used to schedule the execution of programs

The first line changed to CRONTAB(5) and File Formats, and the NAME line showed the description of the job schedule file instead of the command description.

If the given section has no page with that name, an error appears. Running [man 5 passwd] on the AlmaLinux 9.8 server to see the /etc/passwd file format gave an error saying there was no page in section 5.

man 5 passwd

No manual entry for passwd in section 5

On the Debian 12 server, [man -f passwd] also printed the section 5 passwd line. Which sections have a page depends on the manuals installed on the server, so check with [man -f] first before adding a section number.

man -f passwd

passwd (1)           - change user password
passwd (1ssl)        - OpenSSL application commands
passwd (5)           - the password file

Section 8 holds administration commands that are run mainly by the root account, such as useradd, which creates accounts.

man -f useradd

useradd (8)          - create a new user or update default new user information

3️⃣ man Command Options and -k, -f Search

[man -f] prints the one-line descriptions of pages with a matching name and works the same as whatis. Running [man -f passwd] and [whatis passwd] on the AlmaLinux 9.8 server printed the same two lines.

man -f passwd

passwd (1)           - update user's authentication tokens
passwd (1ossl)       - OpenSSL application commands

The 1ossl line is the page of an OpenSSL command that shares the name passwd.

When you don't know the name, search page names and short descriptions with [man -k]. It works the same as apropos, and the keyword is read as a regular expression.

man -k '^passwd'

passwd (1)           - update user's authentication tokens
passwd (1ossl)       - OpenSSL application commands

^ means the start of a line, so only the lines starting with passwd were printed. A word in the description also works, and [man -k 'directory contents'] found the dir and vdir pages along with ls.

man -k 'directory contents'

dir (1)              - list directory contents
ls (1)               - list directory contents
vdir (1)             - list directory contents

[man -k] searches only the short descriptions in the NAME section, so it cannot find a page by an option name or a word in the body. [man -K], which searches the body too, reads every page one by one and takes a long time.

When the keyword is not found, [nothing appropriate] is printed, and the exit code was 16.

man -k no-such-word9

no-such-word9: nothing appropriate.

echo $?

16

[man -w] prints only the location of the source file without opening the page.

man -w ls

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

man -w 5 crontab

/usr/share/man/man5/crontab.5.gz

The two files were in the man1 and man5 folders under /usr/share/man, and the number in the folder name matched the section number. The 1ossl page file found with [man -w 1ossl passwd] was also in the man1 folder, the same as section 1.

The options are gathered in the two tabs below.

🔲 man Command Simulator

In the simulator below, open a page with [man ls] and move through the screens with the [Space], [/list], [n], and [q] chips. On the same virtual server, you can add a section number as in [man 5 crontab] or type [man -f], [man -k], and [man -w].

4️⃣ Structure of a man Page

A man page is divided into sections with uppercase headings. Pulling out only the headings with grep and comparing them showed that the ls page had its option descriptions inside DESCRIPTION, while the crontab page had a separate OPTIONS section.

man ls | grep -E '^[A-Z]+( [A-Z]+)*$'

NAME
SYNOPSIS
DESCRIPTION
AUTHOR
REPORTING BUGS
COPYRIGHT
SEE ALSO

man crontab | grep -E '^[A-Z]+( [A-Z]+)*$'

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CAVEATS
SEE ALSO
FILES
STANDARDS
DIAGNOSTICS
AUTHOR

Section names differ a little from page to page, and the common ones are listed below.

The symbols in SYNOPSIS follow rules set by the man page. Anything inside square brackets can be omitted. Options separated by a vertical bar (|) cannot be used together, and an argument followed by three dots (...) can be given more than once.

The SYNOPSIS of ls is ls [OPTION]... [FILE]..., so both command options and command-line arguments such as file names can be omitted or given several times.

[--help] is a usage summary printed by the program itself, so it goes straight to the terminal without a pager. The Usage on the first line of [ls --help] had the same form as SYNOPSIS, and at 121 lines the whole output was shorter than the 245 lines of [man ls].

ls --help | head -n 3

Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.

A man page has more sections that [--help] lacks, such as AUTHOR and SEE ALSO. Use [--help] to check a single option quickly, and open man when you need a description split into sections, such as a configuration file format or exit codes.

🔢 FAQ & Recommended Content

🔗 Recommended Reading

Pager · less How to use the Linux less command This post covers in detail the keys for turning pages and searching for words on the less screen where man pages open. Read post →

Scheduling Linux: crontab Setup How to schedule server jobs to run at set times with the crontab command. Finding locations Linux which, whereis, locate: 3 Commands to Find a File's Location (Path) Commands for finding the path of a command's executable file and manual file. Passing output along Linux Redirection The flow of standard input and standard output that sends a command's output to a file or another command.

ℹ️ Affiliate Disclosure
This site's content contains affiliate links. When a visitor buys a product or service through one of them, the site receives a commission from the seller. The amount the buyer pays^{(it goes down during event discounts ↓)}does not go up. Posted prices, discounts, and stock reflect the time of writing and may differ, so confirm with the seller before buying. Products are chosen and reviewed by our own standards, and commissions do not affect the order or content of reviews.