Linux command: man

Every Linux system ships with a complete reference manual, installed on disk, available without a network connection, and written by the same people who wrote the software. Most users walk past it. They search the web for a flag that is documented three lines into a page they already have on their own machine. The command that opens that manual is man.

2. Where the Name Comes From

The name man is short for manual. Nothing more clever than that.

man       =  MANual
whatis    =  "what is this command?"
apropos   =  an English word borrowed from French, "with regard to"
mandb     =  MANual DataBase

The full name of the original document was the Unix Programmer's Manual, and a "man page" is literally one page out of it. The manual was numbered in parts, and that numbering survives today as the manual sections you meet in section 5 of this article.

You will constantly see documentation written in the form ls(1), passwd(5), signal(7). This is not decoration. It is a precise citation: the page named ls, in manual section 1. When a manual page says "see chmod(2)", it is telling you that the interesting page is the system call in section 2, not the command in section 1. Learn to read that notation and half of the confusion around man disappears.

4. Simple Use Cases

4.1 Opening a Page and Moving Around It

The simplest possible use is the command name on its own:

$ man cp

You are now inside less, the same pager you get from less somefile.txt. At the bottom of the screen man sets a prompt that tells you exactly which page you landed on:

Manual page cp(1) line 1

That line is worth reading before anything else. It confirms both the name and the section, so you know whether you got the page you meant. These are the keys you need:

Everything you already know about less applies here, because it is less. If the keys behave differently on your system, your pager is a different program; section 6.3 explains how to change it.

4.2 The Parts of a Manual Page

Manual pages are not free-form documents. The headings are conventional, they appear in a fixed order, and the convention itself is documented in man 7 man-pages. These are the ones you will meet:

Because the headings sit at the left margin, you can jump straight to one with a pager search anchored to the start of the line:

$ man rsync
/^EXAMPLES        # then press Enter, and n for the next hit
/^EXIT STATUS
/^ENVIRONMENT

This is the habit that turns manual pages from a wall of text into a reference you can actually use. Do not scroll. Jump.

4.3 How to Read a SYNOPSIS

The SYNOPSIS is a compressed grammar of the command. It uses a notation that nobody ever explains, which is why many people skip it. Here is the whole notation:

Now read a real one. This is the whole of ls:

$ man ls
SYNOPSIS
       ls [OPTION]... [FILE]...

Both parts are optional and both may repeat. So ls, ls -l, ls -l -a /etc /var are all valid, and so is ls /etc /var with no options at all. That single line told you the complete calling convention.

Now one with real structure:

$ man cp
SYNOPSIS
       cp [OPTION]... [-T] SOURCE DEST
       cp [OPTION]... SOURCE... DIRECTORY
       cp [OPTION]... -t DIRECTORY SOURCE...

Three lines means three modes. Line one copies exactly one thing to one destination. Line two copies one or more sources into a directory, and note that SOURCE... repeats while DIRECTORY does not, so the last argument is the target. Line three does the same thing with the target named up front by -t, which is what you use when the source list comes from a pipe. The entire behaviour of cp that trips people up is stated in those three lines.

Pages in sections 2 and 3 look different, because they document C functions rather than commands:

$ man 3 printf
SYNOPSIS
       #include <stdio.h>

       int printf(const char *restrict format, ...);
       int fprintf(FILE *restrict stream,
                   const char *restrict format, ...);

Here the SYNOPSIS gives you the header file to include and the exact prototypes. Same idea, different audience: it is still "how do I call this thing".

4.4 The Page You Want Is Often Not the One You Typed

One command name can have several manual pages. man gives you one of them, and it decides which without telling you. Try this:

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

Three different pages, all called passwd. Plain man passwd gives you the command in section 1. If what you actually wanted was the format of /etc/passwd, you have to ask for the section explicitly. That is the whole answer to the question "why does man 5 passwd exist", and section 5 is about exactly that.

6. Advanced Use Cases

6.1 Choosing the Section Yourself: -S and MANSECT

You already know that a bare section number in front of the name picks a section:

$ man 5 passwd

The longer form takes a list, in the order you want them tried:

$ man -S 5,1 passwd       # try section 5 first, fall back to 1
$ man --sections=8,1 mount

If you always want a different preference, set MANSECT instead of typing it every time. An administrator who lives in configuration files might well prefer section 5 and 8 to come before section 1:

$ export MANSECT=8:5:1:7:2:3

6.2 How man Decides Where to Look

Manual pages live in a manual path, a colon-separated list of directories much like PATH. Ask for yours:

$ manpath
/usr/share/man:/home/peter/.local/share/man:/usr/local/man:/usr/local/share/man

$ man --path            # the same thing, from man itself

That list is not hard-coded. It is built from /etc/manpath.config, which contains two interesting kinds of line:

MANDATORY_MANPATH       /usr/share/man
MANDATORY_MANPATH       /usr/local/share/man
MANPATH_MAP  /usr/bin        /usr/share/man
MANPATH_MAP  /usr/local/bin  /usr/local/share/man
MANPATH_MAP  /opt/bin        /opt/man

The MANPATH_MAP lines are the clever part. They say: "for every directory in the user's PATH, add the matching manual directory". So when you install a program into /opt/bin and put that in your PATH, its manual pages in /opt/man become findable automatically. The manual path follows the executable path.

You can override the whole thing with the MANPATH environment variable, but there is a trap: setting it replaces the computed list instead of adding to it. That is why a leading or trailing colon matters, because an empty entry means "insert the default list here":

$ MANPATH=/opt/mytool/man man --path
/opt/mytool/man                                  # ONLY this. Everything else is gone.

$ MANPATH=/opt/mytool/man: man --path
/opt/mytool/man:/usr/share/man:/home/peter/.local/share/man:/usr/local/share/man

For a single command, prefer -M over exporting anything:

$ man -M /opt/mytool/man mytool

6.3 Making man Comfortable

man reads a handful of environment variables. These four are worth knowing:

Two of them solve real annoyances. On a very wide terminal, a manual page becomes hard to read because the lines run on forever; MANWIDTH pins it to a comfortable measure:

$ export MANWIDTH=80

And MANOPT lets you make a preference permanent without an alias. This one turns off hyphenation and justification for every page you ever open, for the reason explained in section 7.1:

$ export MANOPT="--no-hyphenation --no-justification"

Dumping a page as plain text is easy, because man notices when its output is not a terminal and drops all formatting automatically:

$ man ls > ls.txt              # plain text, no control characters
$ man -P cat ls                # same, forcing the pager to cat
$ MANPAGER=cat man ls          # same, through the environment

That makes a manual page just another text stream, so the rest of the Unix toolbox works on it:

$ man cp | grep -A2 -- '-l, --link'
       -l, --link
              hard link files instead of copying

$ man ls | wc -l               # how long is this page really?

6.4 Full-Text Search: man -K

apropos only looks at the NAME line. The -K flag (short for global apropos) searches the body of every manual page on the system. It is slow, because it decompresses and scans thousands of files, but it finds things nothing else will:

$ man -wK -S 5 'MANPATH_MAP'
/usr/share/man/man5/manpath.5.gz

Two habits make it usable. Restrict the sections with -S, and add -w so you get a list of paths instead of being dropped into each matching page in turn.

There is one subtlety that its own manual page is honest about: -K searches the roff source of each page, not the rendered text, because rendering everything would be far slower. So it can produce false positives from comments in the source, and false negatives when the source writes something differently from the way it appears on screen. A minus sign written \- in the source is the classic example, which is why searching for a flag with -K sometimes finds nothing.

Even so, this is the tool for the question "which configuration file is this obscure setting in?". Note that -K is a man-db extension and is not available everywhere.

6.5 Other Ways to Render a Page

Because formatting is a separate step in the pipeline, you can redirect it. A manual page you have downloaded, or one you are writing, is opened with -l (short for local file):

$ man -l ./mytool.1
$ man -l /tmp/downloaded.8.gz

Without -l, man would treat that path as a page name and fail.

The typesetting heritage is still live. -t (short for troff) formats the page for print instead of for a terminal:

$ man -t ls | head -2
%!PS-Adobe-3.0
%%Creator: groff version 1.23.0

$ man -t ls > ls.ps            # PostScript
$ man -t ls | ps2pdf - ls.pdf  # a printable PDF of the manual page

There is also -H, which renders a page to HTML and opens it in a browser. Be aware that on Debian and Ubuntu only groff-base is installed by default, which can produce PostScript but not HTML; man -H fails there until you install the full groff package.

6.6 Sections 2 and 3: The Programmer's Manual

Sections 2 and 3 are a different manual for a different reader, and they are the part of the system almost nobody discovers by accident. Section 2 documents the system calls, the interface between your program and the kernel. Section 3 documents library functions, which run in your own process and usually call system calls underneath.

$ man 2 open          # the kernel system call
$ man 3 fopen         # the C library function built on top of it
$ man 2 read          $ man 3 malloc
$ man 2 fork          $ man 3 pthread_create

That pairing is the whole point of the split. open() is a request to the kernel; fopen() is a wrapper around it that adds buffering and bookkeeping in user space. The section number tells you which side of that boundary you are standing on.

These pages use their own headings. A command has EXIT STATUS; a function has RETURN VALUE and ERRORS:

$ man 2 open
RETURN VALUE
       On success, open(), openat(), and creat() return  the  new  file  de-
       scriptor (a nonnegative integer).  On error, -1 is returned and errno
       is set to indicate the error.

ERRORS
       EACCES The  requested  access  to  the file is not allowed ...

The ERRORS section is the reason to open these pages at all. It lists every errno value the call can produce and what each one means, which no web search summarises correctly.

One trap has its own answer in the SYNOPSIS. Some functions are only declared when you define a feature-test macro first, and the page tells you which one:

$ man 3 asprintf
SYNOPSIS
       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <stdio.h>

       int asprintf(char **restrict strp, const char *restrict fmt, ...);

If you skip that first line, the compiler reports that asprintf is undeclared even though the manual page clearly documents it. The page even points at the overview: man 7 feature_test_macros explains _GNU_SOURCE, _POSIX_C_SOURCE and the rest. This is a case where reading the SYNOPSIS literally, including the comment, saves an afternoon.

Section 2 and 3 pages also carry a STANDARDS section, which tells you whether an interface is POSIX, a BSD inheritance, or Linux only. That is the difference between code that ports and code that does not. If these pages are missing on your machine, see section 7.7.

6.7 Manual Pages in Your Own Language

Manual pages can be translated, and the manual hierarchy has a subdirectory per locale next to the numbered ones:

$ ls /usr/share/man/ | grep -v '^man[1-9]$' | tr '\n' ' '
ca ca@valencia cs da de de.UTF-8 es fi fr fr.ISO8859-1 fr.UTF-8 hr hu id it
ja ja.UTF-8 ko nl pl pt pt_BR ro ru sk sl sr sv tr uk zh zh_CN zh_TW

Your LANG and LC_MESSAGES settings decide which one man prefers. You can also ask for a language directly with -L:

$ man -L nl apropos
APROPOS(1)               Hulpprogramma's paginaopmaker              APROPOS(1)

NAAM
       apropos - namen en beschrijvingen van de man-pagina's doorzoeken

SAMENVATTING

Two practical notes. First, coverage is thin. This machine has 105 Dutch pages against 9761 English ones, and they come almost entirely from apt, dpkg and man-db itself. For anything else you get English regardless of your locale.

Second, a translation can lag behind the original, because the English page ships with the software and the translation ships with a language pack. When you follow English documentation, compare notes with a colleague, or report a problem, force the original:

$ man -L C apropos     # the untranslated page
$ man -L C -w apropos
/usr/share/man/man1/apropos.1.gz

That is also the fastest way to check whether a heading you cannot find is missing or merely translated.

6.8 The Odd Section Names: 1ssl, 3perl, 3avr

Look again at the output of whatis and you will see sections that are not plain numbers:

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

The letters after the number are a sub-extension. They let one project claim its own space inside a section so that OpenSSL's passwd does not fight with the system's passwd. You will meet 1ssl, 3perl, 3pm, 3posix, and others. Ask for one with -e:

$ man -e ssl passwd            # the OpenSSL page
$ man 1ssl passwd              # the same, written the short way

6.9 Writing a Manual Page for Your Own Script

If you write scripts that other people (or future you) will run on a server, giving them a manual page costs about ten minutes and makes them look installed rather than improvised. The format is plain roff. This is a complete, working page:

.TH DEPLOY 1 "August 2026" "1.0" "Site tools"
.SH NAME
deploy \- push the website to production
.SH SYNOPSIS
.B deploy
[\fB\-n\fR] \fISITE\fR
.SH DESCRIPTION
Pushes the checked-out site to the production server.

The .TH line takes five fields: the name in capitals, the section, the date, the version, and the manual title shown in the header. .SH starts a section heading, .B makes the following line bold, and \fB ... \fR and \fI ... \fR switch to bold and italic inside a line.

Install it into the local hierarchy and rebuild the index:

$ sudo cp deploy.1 /usr/local/share/man/man1/
$ sudo mandb
1 man subdirectory contained newer manual pages.
1 manual page was added.

$ man deploy
DEPLOY(1)                         Site tools                        DEPLOY(1)

NAME
       deploy - push the website to production

SYNOPSIS
       deploy [-n] SITE

Before installing, preview it straight from the working directory with man -l deploy.1. Note the escaped hyphen in deploy \- push: in roff a bare - is a typographic hyphen, and \- is the literal minus sign. Getting that wrong is why some manual pages give you a character you cannot paste back into a shell.

8. Best Practices

• Read the prompt line at the bottom. Manual page cp(1) line 1 tells you the name and the section you actually landed on. Half of all "the manual is wrong" moments are really "I am reading a different page than I think".
• Jump, do not scroll. Inside the pager, search for a heading anchored to the line start: /^EXAMPLES, /^EXIT STATUS, /^ENVIRONMENT. Use n to walk through the hits.
• Learn to read a SYNOPSIS. Square brackets mean optional, three dots mean repeatable, italic means "your value here", and several lines mean several modes. Two minutes there beats twenty minutes of trial and error.
• Check which pages exist before you read one. whatis name takes a second and prevents you from reading the C function when you wanted the command.
• Remember section 5 for configuration files. When you are editing a file rather than running a command, the page you want is almost always man 5 something.
• Browse section 7 once, deliberately. man 7 hier, man 7 signal and man 7 glob each teach a piece of Linux that most people pick up slowly and incorrectly.
• Turn off hyphenation permanently. Put export MANOPT="--no-hyphenation --no-justification" in your shell profile so that what you copy is what you typed.
• Install the documentation packages on a working machine. On Debian and Ubuntu, manpages and manpages-dev bring the system calls, the library functions and most of the section 7 overviews. They are not there by default on a server.
• Force the original when it matters. A translated page can lag behind the software. Use man -L C name when you follow English documentation or discuss a page with someone else.
• Rebuild the index after installing things by hand. If apropos finds nothing but man works, run sudo mandb.
• Give your own scripts a manual page. Anything that lives in /usr/local/bin on a server you maintain for someone else deserves eight lines of roff in /usr/local/share/man/man1.
• Use the whole documentation set, not only man. The manual page is the reference, --help is the reminder that always matches the installed binary, help is the only source for shell builtins, info is the GNU tutorial, and /usr/share/doc holds what none of them carry.

$ man man                        # the manual for the manual
$ man 7 man-pages                # how manual pages are structured
$ man 1 intro                    # what section 1 is for (also 2 to 8)
$ man --help                     # the flag summary
$ info info                      # how to drive the info reader

10. Summary

The manual is the most complete Linux documentation you will ever have, it is already installed, and it works with no network connection at three in the morning.

• man is short for manual. It does not hold documentation itself: it finds a roff file, formats it with groff, and pipes it into a pager.
• Manual pages date from the Unix Programmer's Manual of 1971, and the headings you read today (NAME, SYNOPSIS, DESCRIPTION, BUGS, SEE ALSO) come straight from it.
• The manual is split into numbered sections by kind: 1 commands, 2 system calls, 3 library functions, 4 devices, 5 file formats, 6 games, 7 overviews, 8 administration.
• Section 5 is the one most people never discover. man 5 crontab and man 5 sshd_config document the files, not the commands.
• The notation ls(1) is a citation: page name plus section. Read it, and write it.
• Learn the SYNOPSIS notation once: [ ] optional, ... repeatable, italic means your own value, several lines mean several modes.
• Inside the pager, jump with /^EXAMPLES instead of scrolling.
• whatis shows which pages exist, apropos searches their one-line summaries, and man -K searches the full text.
• Sections 2 and 3 are the programmer's manual: system calls versus library functions, with ERRORS and RETURN VALUE instead of EXIT STATUS, and the feature-test macro your compiler needs written into the SYNOPSIS.
• Pages can be translated. man -L nl name asks for Dutch, man -L C name forces the original, and coverage outside English is thin.
• A missing page often means a missing package, not missing documentation. On Debian and Ubuntu, manpages and manpages-dev hold most of sections 2, 3 and 7.
• apropos reads a cached index. After installing a page by hand, run sudo mandb.
• The section search order comes from /etc/manpath.config and is not 1, 2, 3. That explains man printf and man passwd.
• Turn hyphenation off with MANOPT, or the flags you copy will contain a character your shell does not understand.
• A missing page exits with 16, not 1. Shell builtins have no page at all: use help cd.
• Know where man stops, and note that the four documentation commands differ by source: --help comes from the binary, man from a documentation package, help from the shell itself, and info from the GNU project's own manual.

This is the quick reference worth keeping:

man NAME                     open the manual page
man 5 NAME                   open it in a specific section
man -a NAME                  show every matching page in turn
man -f NAME                  which pages exist (same as whatis)
man -k WORD                  search the one-line summaries (same as apropos)
man -wK -S 5 WORD            full-text search, section 5, list the files
man -w NAME                  print the path of the page
man -l ./page.1              open a page file directly
man -L C NAME                the original page, not a translation
man -t NAME > page.ps        typeset for print instead of terminal
man -P cat NAME              no pager, straight to stdout
man NAME | grep -A2 -- -x    pipe it like any other text

apropos -s 1 'copy files'    find a command by what it does
whatis -w 'ls*'              wildcard search on page names
mandb                        rebuild the apropos/whatis index
manpath                      show where man looks for pages

/^EXAMPLES                   inside the pager: jump to a heading
n  N                         next / previous match
g  G  q                      top, bottom, quit

export MANWIDTH=80                                  readable width
export MANSECT=8:5:1:7:2:3                          your own section order
export MANOPT="--no-hyphenation --no-justification" copy-paste safe pages

apt install manpages manpages-dev    sections 2, 3 and most of 7 (Debian)
dpkg -S /usr/share/man/...   which package a page came from

help cd                      shell builtins, which have no manual page
help -s cd                   just the synopsis of a builtin
cmd --help                   the version you are actually running
info coreutils 'ls invocation'   the full GNU manual (n p u Enter q)

Reading the manual well is one of those quiet skills that separates someone who guesses at a server from someone who knows what it is doing. If your Linux server needs someone who reads the documentation before changing the configuration, and who leaves behind notes the next person can follow, that is exactly the kind of work I enjoy helping with.