man
Read the manual pages, and find the one you need
man displays the manual page for a command, a file format, a system call or a configuration
file. apropos searches the one-line descriptions of every page installed. People skip that
half, then spend an afternoon searching the web for something already on the machine.
Those descriptions live in an index rather than in the pages themselves. whatis and man -f are
exact-match lookups against it, apropos and man -k are substring searches, and all four answer
"nothing appropriate" when the index has not been built rather than when the page is absent.
The number in brackets is a section
ls(1) and crontab(5) are not decoration. A name can appear in several sections, and the
number picks which one you get:
| Section | What is in it |
|---|---|
| 1 | Commands you run at a prompt |
| 2 | System calls, the kernel's own interface |
| 3 | Library functions, mostly the C library |
| 4 | Device files under /dev |
| 5 | File formats and configuration files |
| 6 | Games |
| 7 | Conventions, protocols and other overviews |
| 8 | Commands for administering the system |
man passwd gives you section 1, the command that changes a password. man 5 passwd gives you
/etc/passwd, the file it writes to. Without the number you get the lowest-numbered section that
has a page, so the file formats are the ones people miss.
On Debian, section 2 and section 3 are not installed with the tools. They come from
manpages-dev, which is why a fresh machine answers No manual entry for printf in section 3
while man 1 printf works.
Reading a synopsis
ls [OPTION]... [FILE]...Square brackets mean optional, ... means the thing before it may be repeated, and a | between
two items means one or the other. Anything not in brackets is required. That line says ls takes
any number of options and any number of files, and needs neither.
Getting around a page
man hands the formatted page to a pager, which on Debian is less unless
$PAGER says otherwise. The keys are less's keys: / to search, n for the next match, q to
quit. Piping man into anything else turns the pager off, so the examples below print rather than
waiting for a keypress.
Reading a page
man sends its output to a pager when it has a terminal and prints plain text when it does not, so every example here pipes it somewhere. At a prompt you would leave the pipe off and let less hold the page.
Open the manual for a command
man ls | head -8Every page opens the same way: a header naming the page and its section, then NAME with a one-line summary, then SYNOPSIS with the calling convention. The head is only here because a page is long.
Show output
LS(1) User Commands LS(1)
NAME
ls - list directory contents
SYNOPSIS
ls [OPTION]... [FILE]...
Read just the synopsis
man ls | sed -n "/^SYNOPSIS/,/^DESCRIPTION/p" | head -5Section headings sit in the first column and everything else is indented, so sed can cut between two of them. Square brackets mean optional and ... means repeatable, so this line says ls needs neither an option nor a filename.
Show output
SYNOPSIS
ls [OPTION]... [FILE]...
DESCRIPTION
See who wrote the page and when
man ls | tail -3The footer names the project and the version the page was written for. Worth a glance when a documented flag does not work: the page in front of you belongs to a particular release.
Show output
Your output will differ: the version and the date belong to the package installed on your machine
There is NO WARRANTY, to the extent permitted by law.
GNU coreutils 9.7 June 2025 LS(1)
Choose the pager yourself
man -P cat ls | head -4-P names the program the page is handed to. cat prints it and exits, so a page can go into a file or a pipe even where $PAGER has been set to something interactive.
Show output
LS(1) User Commands LS(1)
NAME
ls - list directory contents
Read the manual for man itself
man man | head -5man has more options than anyone expects, and the page describes the search path and the section order it uses to resolve a name.
Show output
MAN(1) Manual pager utils MAN(1)
NAME
man - an interface to the system reference manuals
Get the option summary without the page
man --help | head -6--help is a different thing from the manual page, and usually a shorter one. For a command you half-remember it is the faster of the two, and type says whether the name is a program at all.
Show output
Usage: man [OPTION...] [SECTION] PAGE...
-C, --config-file=FILE use this user configuration file
-d, --debug emit debugging messages
-D, --default reset all options to their default values
--warnings[=WARNINGS] enable warnings from groff
Format a page file directly
man --local-file /usr/share/man/man1/ls.1.gz | head -4Takes a path rather than a name, so it works on a page that is not on the search path: one you have just downloaded, or one inside a package you have unpacked but not installed.
Show output
LS(1) User Commands LS(1)
NAME
ls - list directory contents
Set the width the page is formatted to
MANWIDTH=60 man ls | head -3man wraps to the terminal width, or to 80 columns when it has no terminal to ask. MANWIDTH overrides both, so output headed for a file somebody else will read gets a width you picked.
Show output
LS(1) User Commands LS(1)
NAME
Read a page from section 6
man 6 cowsay | head -4Section 6 is games, and on most machines it holds almost nothing. cowsay is one of the few things that puts a page there.
Show output
COWSAY(6) Games Manual COWSAY(6)
NAME
cowsay/cowthink - configurable speaking/thinking cow (and a bit more)
Check which man is installed
man --versionDebian's man comes from man-db. Another implementation, mandoc, is common on the BSDs and takes different options, so a script that runs man on more than one system cannot assume Debian's.
Show output
Your output will differ: the version is whichever man-db your release ships
man 2.13.1
Sections, and why the number matters
The number in ls(1) selects which manual a name is looked up in. Give man a number before the name and it looks only there; give it none and it takes the lowest-numbered section that has a page.
See every section a name appears in
whatis passwdThe word names three different things: the command that changes a password, an OpenSSL subcommand, and the file the first one writes to. man passwd gives you only the first.
Show output
passwd (1) - change user password
passwd (1ssl) - OpenSSL application commands
passwd (5) - the password file
Read the command
man 1 passwd | head -6Section 1 is commands you run. The header repeats the section as PASSWD(1) and names the manual beside it, so a glance confirms you landed where you meant to.
Show output
PASSWD(1) User Commands PASSWD(1)
NAME
passwd - change user password
SYNOPSIS
Read the file format of the same name
man 5 passwd | head -6Section 5 is file formats, so this is /etc/passwd rather than the command. Every configuration file worth editing has a page here.
Show output
PASSWD(5) File Formats and Configuration PASSWD(5)
NAME
passwd - the password file
DESCRIPTION
Read an administration command
man 8 cron | head -5Section 8 holds the commands that administer the system, the ones that usually want root. cron the daemon lives here while crontab the command lives in section 1.
Show output
CRON(8) cron User Manual CRON(8)
NAME
cron - daemon to execute scheduled commands (Vixie Cron)
Ask for one section of a name that has several
whatis -s 1 crontab-s narrows the lookup to a section. Useful when a name is in four manuals and you want the summary of one of them.
Show output
crontab (1) - maintain crontab files for individual users (Vixie Cron)
Change which section wins
MANSECT=5:1 man -w passwd
man -w passwdMANSECT is the order the sections are searched in, and the first hit wins. Putting 5 in front of 1 makes the unqualified lookup answer with the file rather than the command, which is the rule from the top of this page written down where you can change it.
Show output
/usr/share/man/man5/passwd.5.gz
/usr/share/man/man1/passwd.1.gz
Watch a section that is not installed
man 3 printfSection 3 is the C library, and Debian ships it in manpages-dev rather than with the tools. printf the shell command is section 1 and present; printf(3), the C function, arrives with that package.
Show output
No manual entry for printf in section 3
Find where each section of a name lives
man -aw crontab-a means all matches rather than the first, and -w prints paths instead of pages. Together they answer "how many manuals mention this name, and where are they" in one line each.
Show output
/usr/share/man/man1/crontab.1.gz
/usr/share/man/man5/crontab.5.gz
Ask for the path of one section
man -w 5 passwdThe section argument works the same way with -w as without it. Use this form in a script: it fails loudly when the page is not installed.
Show output
/usr/share/man/man5/passwd.5.gz
Read the shell command rather than the C function
man 1 printf | head -5printf is a shell command and a C library function, documented in sections 1 and 3. Naming the section is how a C programmer avoids the shell page and how everyone else avoids the other one.
Show output
PRINTF(1) User Commands PRINTF(1)
NAME
printf - format and print data
Count how many manuals document a name
man -a crontab 2>/dev/null | grep -c "^CRONTAB"-a concatenates every matching page instead of stopping at the first, so counting the headers counts the manuals. At a prompt -a shows them one after another and asks before each.
Show output
2
Read a page that complains while it formats
man 5 crontab 2>/dev/null | head -4This page uses characters the installed fonts do not have, and groff says so on stderr every time it is opened. The warnings are not an error and the page is fine, so discarding stderr loses nothing.
Show output
CRONTAB(5) crontab User Manual CRONTAB(5)
NAME
crontab - tables for driving cron
Finding the page when you know what you want, not what it is called
apropos searches the one-line descriptions rather than the pages. It is the same index whatis reads, searched by substring instead of by exact name, and man -k is another spelling of it.
Search the descriptions for a phrase
apropos -s 1 "directory contents"dir and vdir are ls with different defaults, so all three describe themselves the same way. -s 1 keeps the answer to commands rather than including library functions with similar summaries.
Show output
dir (1) - list directory contents
ls (1) - list directory contents
vdir (1) - list directory contents
Spell the exact lookup as a man option
man -f crontabman -f is whatis, the same way man -k is apropos. Both spellings appear in scripts, and knowing they are pairs saves looking up two more commands.
Show output
crontab (1) - maintain crontab files for individual users (Vixie Cron)
crontab (5) - tables for driving cron
Search for whole words only
apropos -e ls-e matches the search term as a whole word, so ls no longer matches every description containing those two letters. Without it this search returns most of the manual.
Show output
dircolors (1) - color setup for ls
ls (1) - list directory contents
Anchor an apropos search to a whole name
apropos -s 1 "^ls$"The regular expression is matched against the name as well as the description, so anchoring both ends finds the page named ls and nothing that merely mentions it.
Show output
ls (1) - list directory contents
Restrict a search to configuration files
man -k -s 5 cronSection 5 and a keyword together narrow a search to configuration files. When you know a program is configured by a file somewhere and not what the file is called, this finds it.
Show output
crontab (5) - tables for driving cron
Search the pages themselves, not their descriptions
apropos -s 1 gzip | wc -l
man -K -w -s 1 gzip | wc -l-K greps the body of every page rather than the one-line summaries, so it finds the commands that merely mention gzip as well as the ones that are about it. It is slower and much less precise, and it is what to try when apropos comes back empty.
Show output
Your output will differ: both counts depend on which packages are installed
2
27
Count the pages this machine has
man -k . | wc -l. matches every description, so this counts the index. A container has a fraction of what a desktop has, and installing a package usually adds to it.
Show output
Your output will differ: the total depends on which packages are installed
1453
See how wide an unanchored search casts
man -k passwd | head -4The passwd command is in none of the first four: these are pages whose descriptions merely mention passwords. Sort the answer by section, or anchor the pattern, before assuming the first hit is the one.
Show output
chgpasswd (8) - update group passwords in batch mode
chpasswd (8) - update passwords in batch mode
gpasswd (1) - administer /etc/group and /etc/gshadow
openssl-passwd (1ssl) - compute password hashes
Look up a name that is also a C function
man -f printfSection 3 is not installed, so only the shell command comes back. On a machine with manpages-dev the same command returns two, and the difference is a good check of what a build environment has.
Show output
printf (1) - format and print data
Where a page came from
A manual page is a file shipped by a package, and Debian's tools can go from one to the other in either direction. That makes man a way into the packaging rather than a dead end.
Print the path instead of the page
man -w ls-w answers "which file would you open". The .gz is not a complication: pages are stored compressed and man decompresses them on the way to the pager.
Show output
/usr/share/man/man1/ls.1.gz
Find the package that shipped a page
dpkg -S $(man -w ls)man -w gives the path and dpkg -S says which package owns it. The answer names what to reinstall when a page is missing or to read further in.
Show output
coreutils: /usr/share/man/man1/ls.1.gz
Look at the source of a page
zcat /usr/share/man/man1/ls.1.gz | head -5A manual page is a text file in a markup language called roff. .TH carries the name, the section, the date and the version, which is where the header and the footer of the formatted page come from, and .SH opens each section.
Show output
Your output will differ: the version and the date belong to the package installed on your machine
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.50.1.
.TH LS "1" "June 2025" "GNU coreutils 9.7" "User Commands"
.SH NAME
ls \- list directory contents
.SH SYNOPSIS
See where man looks
man --pathThe directories are searched in the order printed. /usr/local/share/man is where a program you compiled yourself should install its pages, which is why it is ahead of the packaged ones.
Show output
/usr/local/man:/usr/local/share/man:/usr/share/man
Override the search path for one command
MANPATH=/usr/share/man man -w lsSetting MANPATH for a single command restricts the search to what you name. Set it in a shell and you replace the path rather than adding to it, which is the usual way to lose access to half the manual.
Show output
/usr/share/man/man1/ls.1.gz
Count the pages in each section
man -k . | awk "{print \$2}" | sort | uniq -c | sort -rn | head -5Section 8 leads on a server, which says something about what a machine is for. 1ssl and 7ssl are OpenSSL's own sections, and a package is free to invent one.
Show output
Your output will differ: the counts depend on which packages are installed
463 (8)
456 (1)
241 (7ssl)
125 (5)
112 (1ssl)
Searching inside a page
At a prompt you would press / and let the pager search. In a pipe the page is text like any other, so the usual tools apply.
Pull out what one option does
man ls | grep -A3 "^ -a, --all"Options are indented seven spaces and their descriptions more, so anchoring on the indentation finds the entry rather than every mention of -a in the page.
Show output
-a, --all
do not ignore entries starting with .
-A, --almost-all
Print an option and its description only
man ls | sed -n "/^ -R, --recursive/,+1p"sed with +1 takes the matched line and the one after it, which for a short entry is the whole thing. Quicker than paging to the right place when you only need reminding.
Show output
-R, --recursive
list subdirectories recursively
Read a section of a file-format page
man 5 passwd | sed -n "/^ /,+3p" | head -5Subsection headings are indented three spaces where section headings are not indented at all, so the two can be told apart by a pattern. Handy on a long format page where DESCRIPTION runs for pages.
Show output
passwd - the password file
DESCRIPTION
/etc/passwd contains one line for each user account, with seven fields
delimited by colons (":"). These fields are:
When there is no page
A missing page and a mis-addressed one are different failures with different fixes, and man words them differently enough to tell apart.
Ask for a command that does not exist
man nosuchcommandNo section named, so man looked in all of them and found nothing. Either the name is wrong or nothing on this machine provides it.
Show output
No manual entry for nosuchcommand
Ask for a page in the wrong section
man 7 man-pagesThe wording changes once a section is named: the page may well exist elsewhere. Try it again without the number.
Show output
No manual entry for man-pages in section 7
Check for a page without printing it
man -w intro-w exits non-zero and says the same thing when nothing matches, so a script can test it without printing a page. Debian ships intro(1) in manpages, absent here.
Show output
No manual entry for intro