Understanding the Linux Man Pages: Your Built-in Documentation

Linux man pages (manual pages) are the built-in documentation system that describes every command, system call, configuration file, and library function on your system. Access them by typing man command — for example, man ls opens the manual page for the ls command. Inside a man page, use the arrow keys or Page Up/Down to scroll, /searchterm to search, and q to quit. Man pages are organized into numbered sections — section 1 covers user commands, section 5 covers configuration files, and section 8 covers system administration commands.

The Most Underused Resource on Every Linux System

Every Linux system ships with a comprehensive documentation library covering every installed command, system call, configuration file format, and library function. This documentation is not a website you have to search for or a PDF you have to download — it is built into the system itself, accessible instantly from any terminal, describing the exact version of every tool installed on your machine.

This is the man page system, and it is one of Linux’s most powerful and most underused features.

New Linux users often reach for a web search when they cannot remember a command’s options or syntax. Experienced Linux users type man command and get the answer in seconds — accurate for their exact system, comprehensive, and immediately at hand. The difference is not experience with Linux per se; it is knowing how to read and navigate man pages effectively.

Man pages have a reputation for being dense and difficult. That reputation is partially earned — the terse, structured format is not casual reading. But once you understand that structure and know how to navigate it efficiently, man pages become invaluable. They are always complete (every option is documented), always accurate (they ship with the software itself), and always available (no internet required, no version mismatch).

This article teaches you everything you need to get real value from man pages: how the system is organized, how to navigate a man page efficiently, how to search for documentation when you do not know the command name, how to read the often-cryptic command synopsis, and what alternatives exist for when man pages are not enough.

The History of Man Pages

Man pages descend directly from the original Unix documentation system created at Bell Labs in the early 1970s. The first edition of the Unix Programmer’s Manual was published in November 1971 — and the essential structure of that documentation has persisted largely unchanged for over fifty years.

The man command itself was created to make this documentation accessible interactively. Rather than consulting a printed manual (which is what “manual page” refers to — a page from a printed manual), users could type man command and read the documentation on screen. This was revolutionary in an era when most computer documentation existed only in expensive printed binders.

The persistence of man pages across five decades reflects a design that has proven genuinely good. The format is structured enough to be consistent and searchable, flexible enough to accommodate any subject, plain-text based so it works anywhere, and concise enough to describe most commands in a single page.

Accessing Man Pages: The man Command

Basic Usage

$ man ls

Opens the manual page for the ls command. The man page opens in a pager program (usually less) that allows you to scroll through the content.

$ man grep
$ man bash
$ man ssh
$ man find

Every installed command on a Linux system has a corresponding man page.

Navigating Within a Man Page

Man pages open in less by default, using the same navigation keys:

The most important navigation actions for everyday use: Space to page down, b to page back, / to search, n to jump between matches, and q to quit.

Searching Within a Man Page

The search function is the key to efficiently using man pages rather than reading them linearly. When you want to know about a specific option:

1. Open the man page: man command
2. Press / to start a search
3. Type the option or keyword: --recursive or -r or recursive
4. Press Enter to jump to the first match
5. Press n to jump to subsequent matches

For example, looking up the recursive option in the cp man page:

$ man cp
/recursive

The cursor jumps to where -R, --recursive is documented, showing the explanation immediately.

The Structure of a Man Page

Man pages follow a consistent structure. Once you know what each section contains, you can navigate directly to the information you need.

Standard Man Page Sections

NAME The command name and a one-line description. This is what whatis and apropos index.

NAME
       ls - list directory contents

SYNOPSIS The command’s syntax showing all available options and arguments. This section is often cryptic at first glance but follows consistent conventions explained below.

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

DESCRIPTION A narrative explanation of what the command does, followed by documentation of each option. This is the main body of the man page and usually the longest section.

OPTIONS On many man pages, the options are listed in a separate section rather than embedded in DESCRIPTION. Each option is shown with its short form (-r) and long form (--recursive) where both exist, followed by an explanation.

EXAMPLES Not all man pages include this, but many do. When present, EXAMPLES shows practical usage that can be copied directly.

FILES Lists files the command reads from or writes to — configuration files, data files, log files.

FILES
       /etc/passwd    User account information
       ~/.bashrc      Per-user bash configuration

ENVIRONMENT Lists environment variables the command recognizes and how they affect behavior.

EXIT STATUS Documents the exit codes the command returns (0 usually means success, non-zero means error of some kind). Important for script writing.

BUGS Known issues, limitations, or unexpected behaviors.

SEE ALSO References to related man pages — invaluable for discovering related commands or finding more information.

SEE ALSO
       chmod(1), chown(1), find(1), ln(1), mkdir(1), mv(1), rm(1), touch(1)

AUTHOR Who wrote the program and/or its documentation.

Reading the SYNOPSIS Section

The SYNOPSIS section is notoriously difficult to read until you know its conventions. Once you learn them, you can decode the syntax of any command at a glance.

Synopsis Conventions

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

[OPTION] — square brackets mean optional. [OPTION] means you can provide options but do not have to.

... — ellipsis means the preceding item can be repeated. [OPTION]... means zero or more options. [FILE]... means zero or more files.

{a|b} — curly braces with vertical bar means choose one of the alternatives.

UPPER_CASE — uppercase words (like FILE, DIR, N, STRING) represent placeholders for values you supply.

-r, --recursive — short option and its long equivalent, separated by comma.

Bold text — must be typed exactly as shown.

Italic text — replace with an actual value.

A more complex example:

find [-H] [-L] [-P] [-D debugopts] [-Olevel] [starting-point...] [expression]

This means:

• -H, -L, -P are all optional flags (each independent)
• -D debugopts is optional; if provided, debugopts is replaced with actual debug options
• -Olevel is optional; level is replaced with a number
• starting-point... is optional, repeatable; replaced with actual directory paths
• expression is optional; replaced with the search expression

Another example showing mandatory vs optional:

cp [OPTION]... SOURCE DEST
cp [OPTION]... SOURCE... DIRECTORY

Two forms are shown (multiple synopsis lines are common):

• First form: copy one SOURCE file to DEST
• Second form: copy multiple SOURCE files into DIRECTORY

SOURCE and DEST have no brackets — they are required. [OPTION]... is optional.

Man Page Sections: The Numbering System

Man pages are divided into numbered sections. The section number tells you what category of documentation you are reading. This matters when multiple man pages exist with the same name — for example, passwd is both a command (section 1) and a file format (section 5).

The Eight Standard Sections

Specifying a Section

To open a man page from a specific section, provide the section number before the command name:

$ man 1 passwd     # The passwd command (section 1)
$ man 5 passwd     # The /etc/passwd file format (section 5)
$ man 1 printf     # The printf command (shell utility)
$ man 3 printf     # The printf() C library function (for programmers)
$ man 5 crontab    # The crontab file format
$ man 8 useradd    # The useradd system administration command

When you type man passwd without a section number, man displays the lowest-numbered section that matches — in this case section 1 (the command). To see the file format documentation, you must specify section 5 explicitly.

Finding Which Sections Cover a Topic

$ man -k passwd | grep "^passwd"
passwd (1)           - change user password
passwd (5)           - the password file

The (1) and (5) show which sections have a passwd man page.

Searching for Man Pages: apropos and whatis

What do you do when you cannot remember the command name but know what you want to do? The apropos command searches man page descriptions for keywords.

apropos: Search by Description

$ apropos compress
bzip2 (1)            - a block-sorting file compressor
gzip (1)             - compress or expand files
lz4 (1)              - ultra fast compression algorithm
tar (1)              - an archiving utility
xz (1)               - compress or decompress .xz files
zip (1)              - package and compress (archive) files
zstd (1)             - zst compression/decompression utility

apropos searches the NAME section of every man page for the keyword and returns all matches. This is the right tool when you know what you want to do but not which command does it.

More examples:

$ apropos "network interface"
ip (8)               - show / manipulate routing, network devices, ...
ifconfig (8)         - configure a network interface

$ apropos "disk usage"
df (1)               - report file system disk space usage
du (1)               - estimate file space usage
ncdu (1)             - NCurses Disk Usage

$ apropos user | grep -i add
adduser (8)          - add a user or group to the system
useradd (8)          - create a new user or update default new user information

apropos is equivalent to man -k — both do the same keyword search:

$ man -k compress    # Same as apropos compress

whatis: One-Line Description

whatis shows the one-line description from the NAME section — quickly telling you what a command does without opening the full man page:

$ whatis ls
ls (1)               - list directory contents

$ whatis grep
grep (1)             - print lines that match patterns

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

whatis is useful for quickly checking what an unfamiliar command does before opening its full man page.

Updating the apropos/whatis Database

apropos and whatis search a database built from man page NAME sections. This database needs to be updated when new packages are installed:

$ sudo mandb

This command scans all man pages and rebuilds the search database. On most distributions, mandb runs automatically when packages are installed. If apropos returns no results for something you know is installed, running sudo mandb first usually fixes it.

The –help Flag: Quick Option Reference

Before opening a full man page, the --help flag (or -h for many commands) provides a quick summary of options:

$ ls --help
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.

Mandatory arguments to long options are mandatory for short options too.
  -a, --all                  do not ignore entries starting with .
  -A, --almost-all           do not list implied . and ..
      --author               with -l, print the author of each file
  -b, --escape               print C-style escapes for nongraphic characters
      --block-size=SIZE      with -l, scale sizes by SIZE; e.g., '--block-size=M'
...

--help output is typically shorter and more scannable than a full man page — good for quickly finding an option you almost remember. Man pages provide more complete documentation including examples, related commands, and detailed behavior descriptions.

Choosing between –help and man:

• Use --help when you just need to find the right flag quickly
• Use man when you want to understand the command fully, find examples, or understand edge cases

info: The GNU Alternative to Man Pages

GNU programs (gcc, bash, coreutils like ls/cp/mv) often have documentation in the info format in addition to or instead of man pages. The info system was created as a hyperlinked documentation system more capable than man pages.

$ info ls
$ info bash
$ info coreutils

Navigating info Pages

The info pager uses different navigation keys from man:

Info pages have a hierarchical node structure — topics and subtopics you navigate between, similar to a web page with hyperlinks. For complex subjects like bash, the info documentation is often more comprehensive and better organized than the man page.

Many users find info navigation unintuitive. A practical alternative: use pinfo (a more user-friendly info reader) or simply read the info documentation through a text browser:

$ pinfo ls    # More accessible info reader
$ sudo apt install pinfo

Alternative Documentation Sources

Man pages and info pages are not the only documentation sources on a Linux system.

/usr/share/doc: Package Documentation

Many packages install additional documentation in /usr/share/doc/packagename/:

$ ls /usr/share/doc/
adduser  apt  base-files  bash  bind9  ...

$ ls /usr/share/doc/bash/
CHANGES  COMPAT  COPYING  FAQ  INTRO  README  changelog.Debian.gz  changelog.gz

Package documentation directories may contain READMEs, changelogs, example configuration files, and extended guides that go beyond what fits in a man page.

Command-Specific Help Systems

Some large, complex programs have their own help systems accessed differently:

$ git help commit        # Git's help for a specific subcommand
$ git commit --help      # Same, opens in browser or man
$ vim --help             # Vim's brief help
$ :help              " Inside vim, the comprehensive help system

Built-in Shell Documentation

Bash has built-in commands that do not have man pages (because they are part of the shell itself, not separate programs). Use help for these:

$ help cd
$ help echo
$ help for
$ help if
$ help while
$ help          # Lists all bash built-ins

Alternatively, bash built-ins are documented in the bash man page itself:

$ man bash
/^SHELL BUILTIN COMMANDS

Search for the “SHELL BUILTIN COMMANDS” section in the bash man page for comprehensive documentation of all built-in commands.

Advanced man Usage

Opening a Man Page to a Specific Section

Jump directly to a specific section of a man page using pattern matching:

$ man ls | less +/'^EXAMPLES'

This opens the ls man page with the pager positioned at the EXAMPLES section.

Displaying Man Pages in Different Formats

Output man page as plain text (useful for searching or saving):

$ man ls | col -b > ls_manual.txt

Output as PostScript or PDF:

$ man -t ls | ps2pdf - ls_manual.pdf

Display in a specific pager:

$ MANPAGER=less man ls
$ MANPAGER="vim -" man ls    # Open in vim

Finding Where a Man Page File Lives

$ man -w ls
/usr/share/man/man1/ls.1.gz

Man page files are stored in /usr/share/man/ organized by section (man1/ for section 1, man5/ for section 5, etc.) and compressed with gzip.

Read the compressed man page file directly:

$ zcat /usr/share/man/man1/ls.1.gz | less

List all available man pages:

$ man -k . | wc -l
3847

On a typical Ubuntu system, nearly 4,000 man pages are available.

Using man with Multiple Languages

If your system has documentation installed in multiple languages, specify the locale:

$ LANG=fr_FR.UTF-8 man ls    # French man page (if installed)
$ LANG=de_DE.UTF-8 man ls    # German man page (if installed)

Practical Workflows with Man Pages

Workflow 1: Learning a New Command

You want to learn how to use rsync:

1. Get a one-line summary: whatis rsync
2. Open the man page: man rsync
3. Read the DESCRIPTION section for overview
4. Search for specific options: /--delete to find the delete option
5. Check the EXAMPLES section if present
6. Note the SEE ALSO section for related tools

Workflow 2: Finding the Right Command

You need to find which command manages firewall rules:

1. Search broadly: apropos firewall
2. Narrow with grep: apropos firewall | grep -i rule
3. Check the results: whatis iptables, whatis ufw, whatis firewalld
4. Open the relevant man page: man ufw

Workflow 3: Decoding a Configuration File

You found a configuration file and want to understand its format:

1. Try section 5: man 5 filename (e.g., man 5 crontab, man 5 fstab, man 5 sudoers)
2. If not found directly, search: apropos configuration | grep relevant-keyword
3. Read the FILES section of related command man pages

Workflow 4: Script Writing Reference

You are writing a bash script and need to know tar’s exit codes:

$ man tar
/^EXIT STATUS

Search for EXIT STATUS to find what return codes tar uses and what they mean.

Common Man Pages Every Linux User Should Know

Quick Reference: Man Page Commands

Conclusion: The Documentation That Is Always There

The man page system represents something rare and valuable: comprehensive, accurate, immediately accessible documentation that ships with every Linux system and covers everything installed on it. No internet connection required. No version mismatch between the documentation and the software. No searching through multiple sources. The documentation for every command is exactly one man command away.

The investment in learning to use man pages efficiently pays dividends throughout your Linux life. When you hit man find and search /^EXAMPLES to jump straight to usage examples, when you type man 5 crontab to decode a scheduling format, when apropos archive | grep compress reveals a tool you did not know existed — these are moments when the man page system demonstrates its value clearly.

The goal is not to memorize commands but to know where their complete documentation lives and how to find what you need within it quickly. With man, apropos, whatis, and --help, the full documentation of your Linux system is always within reach — comprehensive, accurate, and waiting for you to use it.