DEV Community

Cover image for 🧭 Understanding the `man` Command in Linux
Farhad Rahimi Klie
Farhad Rahimi Klie

Posted on • Edited on

🧭 Understanding the `man` Command in Linux

#linux #cli #linuxcommand #opensource

The man command is one of the most fundamental, powerful, and misunderstood tools in Linux and Unix-like operating systems. It is not just a help command — it is a documentation system, database, formatter, and pager working together.

1. What Is the man Command?

man stands for manual.

It is a command-line interface to the Linux manual pages, which are structured documentation files describing:

  • Commands
  • System calls
  • Library functions
  • Configuration files
  • File formats
  • Kernel interfaces

Basic usage 

man ls
Enter fullscreen mode Exit fullscreen mode

This opens the official documentation for the ls command.

2. High-Level Architecture of man

The man system is not a single program.

It consists of multiple components:

User
 ↓
man command
 ↓
man-db / man-pages
 ↓
Formatter (groff / troff)
 ↓
Pager (less)
 ↓
Terminal
Enter fullscreen mode Exit fullscreen mode

Key components

Component Purpose
man Front-end command
man-db Manual page database & index
man-pages Actual documentation content
groff Formats documents
less Displays formatted output

3. Where Are Man Pages Stored?

Man pages live in predefined directories:

/usr/share/man/
/usr/local/share/man/
Enter fullscreen mode Exit fullscreen mode

Each directory contains section subdirectories:

man1/
man2/
man3/
man4/
man5/
man6/
man7/
man8/
Enter fullscreen mode Exit fullscreen mode

Example:

/usr/share/man/man1/ls.1.gz
Enter fullscreen mode Exit fullscreen mode

4. Man Page Sections (VERY IMPORTANT)

Every man page belongs to a section.

Complete section list

Section Description
1 User commands
2 System calls
3 C library functions
4 Special files (devices)
5 File formats
6 Games
7 Miscellaneous
8 System administration

Example 

man 2 open
man 3 printf
man 5 passwd
Enter fullscreen mode Exit fullscreen mode

5. How man Finds a Page (Internal Logic)

When you run:

man ls
Enter fullscreen mode Exit fullscreen mode

Internally, man:

  1. Reads configuration from /etc/manpath.config
  2. Determines search paths
  3. Checks the man database
  4. Searches sections in priority order
  5. Selects best match
  6. Decompresses .gz
  7. Formats content
  8. Pipes output to pager

6. Man Page Compression

Man pages are usually compressed:

ls.1.gz
Enter fullscreen mode Exit fullscreen mode

man automatically handles:

  • gzip (.gz)
  • bzip2 (.bz2)
  • xz (.xz)

You never decompress manually.

7. Full Syntax of man 

man [OPTIONS] [SECTION] PAGE
Enter fullscreen mode Exit fullscreen mode

Examples 

man ls
man 5 passwd
man -k printf
Enter fullscreen mode Exit fullscreen mode

8. Essential man Options (Complete List)

Display options 

man -a ls      # Show all matching pages
man -f ls      # Short description (whatis)
man -k socket  # Search keyword
Enter fullscreen mode Exit fullscreen mode

Formatting options 

man -P less
man -T pdf ls
man -T html ls
Enter fullscreen mode Exit fullscreen mode

Path options 

man -w ls      # Show file location
man -W ls      # All matching locations
Enter fullscreen mode Exit fullscreen mode

Locale & encoding 

man -L en ls
man --encoding=UTF-8 ls
Enter fullscreen mode Exit fullscreen mode

9. Searching Inside Man Pages

Using pager search

Inside man:

/word
n (next)
N (previous)
Enter fullscreen mode Exit fullscreen mode

Keyword search 

man -k network
Enter fullscreen mode Exit fullscreen mode

This uses the man database index.

10. The whatis and apropos System

These commands are wrappers around man indexing.

whatis ls
apropos socket
Enter fullscreen mode Exit fullscreen mode

Internally:

man -f
man -k
Enter fullscreen mode Exit fullscreen mode

11. Man Page Database (mandb)

Man pages are indexed for fast lookup.

Rebuild database 

sudo mandb
Enter fullscreen mode Exit fullscreen mode

Database location 

/var/cache/man/
Enter fullscreen mode Exit fullscreen mode

12. Man Page Output Pipeline (Deep Internals) 

man
 ↓
zcat / bzcat
 ↓
groff -Tutf8 -man
 ↓
less
Enter fullscreen mode Exit fullscreen mode

Formatter 

groff
Enter fullscreen mode Exit fullscreen mode

Pager 

less
Enter fullscreen mode Exit fullscreen mode

You can override pager:

MANPAGER=cat man ls
Enter fullscreen mode Exit fullscreen mode

13. Man Page Structure (Standard Layout)

Every man page follows a strict format:

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
RETURN VALUE
ERRORS
FILES
EXAMPLES
SEE ALSO
Enter fullscreen mode Exit fullscreen mode

Example 

man open
Enter fullscreen mode Exit fullscreen mode

14. Viewing Raw Man Source 

man -l /usr/share/man/man1/ls.1.gz
Enter fullscreen mode Exit fullscreen mode

Or:

zcat ls.1.gz
Enter fullscreen mode Exit fullscreen mode

15. Writing Your Own Man Page (FULL)

File name 

mycmd.1
Enter fullscreen mode Exit fullscreen mode

Basic structure 

.TH MYCMD 1
.SH NAME
mycmd \- example command
.SH SYNOPSIS
mycmd [OPTIONS]
.SH DESCRIPTION
This is a test command.
Enter fullscreen mode Exit fullscreen mode

Install it 

sudo cp mycmd.1 /usr/share/man/man1/
sudo mandb
Enter fullscreen mode Exit fullscreen mode

View 

man mycmd
Enter fullscreen mode Exit fullscreen mode

16. Man Page Macros (IMPORTANT)

Man pages use troff macros:

Macro Meaning
.TH Title
.SH Section header
.B Bold
.I Italic
.TP Tagged paragraph

Example:

.B -h
Show help
Enter fullscreen mode Exit fullscreen mode

17. Exporting Man Pages

PDF 

man -Tpdf ls > ls.pdf
Enter fullscreen mode Exit fullscreen mode

HTML 

man -Thtml ls > ls.html
Enter fullscreen mode Exit fullscreen mode

18. Debugging Man Pages 

man -d ls
Enter fullscreen mode Exit fullscreen mode

Shows:

  • Paths searched
  • Sections matched
  • Format pipeline

19. Configuration Files

Global config 

/etc/manpath.config
Enter fullscreen mode Exit fullscreen mode

Controls:

  • Search paths
  • Section order
  • Locale behavior

20. Environment Variables Used by man

Variable Purpose
MANPATH Override search paths
MANPAGER Custom pager
LESS Pager behavior
LANG Localization

Example:

export MANPAGER="less -R"
Enter fullscreen mode Exit fullscreen mode

21. Common Problems & Solutions

Man page not found 

sudo mandb
Enter fullscreen mode Exit fullscreen mode

Wrong section shown 

man 2 open
Enter fullscreen mode Exit fullscreen mode

Pager issues 

export MANPAGER=cat
Enter fullscreen mode Exit fullscreen mode

22. Why man Still Matters

  • Always available (offline)
  • Official documentation
  • Exact system behavior
  • Matches installed version
  • No external dependency

If you master man, you master Linux documentation.

23. Final Thoughts

The man command is:

  • A documentation framework
  • A searchable database
  • A formatting pipeline
  • A learning system

It is not beginner-friendly by accident — it is precise by design.

If you understand man, you understand how Unix systems document themselves.

Author

Farhad Rahimi Klie

Top comments (0)