📖 The man Command

Access the Manual Pages - Your Complete Linux Documentation

man [OPTION]... [SECTION] PAGE

Overview

The man (manual) command is your primary interface to the Linux manual pages - comprehensive documentation for commands, system calls, library functions, configuration files, and more. Learning to use man effectively is one of the most important skills for any Linux user or administrator.

What are Manual Pages?

  • Comprehensive documentation built into the system
  • Organized into sections by topic (commands, system calls, etc.)
  • Formatted in roff/troff markup language
  • Displayed using a pager (usually less)
  • Available offline - no internet needed
  • Constantly updated with system packages

Manual Page Sections:

  • Section 1: User commands (ls, cat, bash, etc.)
  • Section 2: System calls (open, read, write, etc.)
  • Section 3: Library functions (printf, malloc, etc.)
  • Section 4: Special files (/dev devices)
  • Section 5: File formats (passwd, fstab, etc.)
  • Section 6: Games and screensavers
  • Section 7: Miscellaneous (man, regex, ascii, etc.)
  • Section 8: System administration (mount, iptables, etc.)

Key Capabilities:

  • Read documentation for any command
  • Search man pages by keyword
  • Access specific sections
  • Find related commands
  • Export to text or PDF
  • Navigate with powerful search
Man Page Format:

Manual pages follow a standard structure: NAME (brief description), SYNOPSIS (usage syntax), DESCRIPTION (detailed explanation), OPTIONS (command-line flags), EXAMPLES (usage examples), SEE ALSO (related commands), and BUGS (known issues). This consistent format makes it easy to find information quickly.

Common Options

Option Description
-k keyword Search for keyword in man page descriptions (apropos)
-f command Display short description (whatis)
-a Display all matching manual pages
-w Show location of man page file
-K keyword Search for keyword in full text of all pages (slow)
-S section Search only in specified section
-P pager Use specified pager instead of default
-t Format page for printing with groff

Navigation Within Man Pages

Essential Navigation Keys (in less pager):
Space / f Forward one screen
b Backward one screen
d / u Forward/backward half screen
↓ / ↑ Down/up one line
g / G Go to top / bottom
/pattern Search forward for pattern
?pattern Search backward for pattern
n / N Next/previous search match
h Help (shows all commands)
q Quit

Detailed Examples

Example 1

Basic Manual Page Access

Reading documentation for common commands.

# View manual page for ls command man ls # View manual page for grep man grep # View manual page for man itself man man
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 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 .. [... continues with more options and examples ...]
Explanation: When you type man command, the system searches for a manual page for that command and displays it in a pager (usually less). The page includes:
  • NAME: Command name and brief description
  • SYNOPSIS: How to use the command
  • DESCRIPTION: Detailed explanation
  • OPTIONS: All available flags and parameters
  • EXAMPLES: Common usage patterns (if provided)
  • SEE ALSO: Related commands
First-Time Tips:
  • Press Space to scroll down
  • Press q to quit
  • Type /keyword and press Enter to search
  • Press n to go to next search result
Example 2

Accessing Specific Manual Sections

Many topics have entries in multiple sections - specify which one you want.

# The passwd command exists in multiple sections # Section 1: the passwd command (user command) man 1 passwd # Section 5: the passwd file format man 5 passwd # Without section, gets first match (usually section 1) man passwd
PASSWD(1) User Commands PASSWD(1) NAME passwd - change user password [...] PASSWD(5) File Formats and Conversions PASSWD(5) NAME passwd - the password file DESCRIPTION /etc/passwd contains one line for each user account, with seven fields delimited by colons (":"). These fields are: - login name - optional encrypted password - numerical user ID [...]
Explanation: Some topics appear in multiple sections:
  • passwd(1): The passwd command for changing passwords
  • passwd(5): Documentation of the /etc/passwd file format
  • printf(1): The shell printf command
  • printf(3): The C library printf function

Use the section number to specify which one you want.

# See which sections have a man page for a topic man -f printf
printf (1) - format and print data printf (3) - formatted output conversion
Common Multi-Section Topics:
  • passwd, crontab, time, stat, kill, signal
  • When in doubt, use man -f topic to see all sections
Example 3

Searching Man Pages by Keyword (-k option)

Find relevant commands when you don't know the exact name.

# Search for commands related to "compress" man -k compress
bzip2 (1) - a block-sorting file compressor compress (1) - compress and expand data gzip (1) - compress or expand files tar (1) - an archiving utility xz (1) - Compress or decompress .xz and .lzma files zip (1) - package and compress (archive) files zcat (1) - compress or expand files
# Search for network-related commands man -k network | head -10
arp (8) - manipulate the system ARP cache ifconfig (8) - configure a network interface ip (8) - show / manipulate routing, devices netstat (8) - Print network connections, routing tables ping (8) - send ICMP ECHO_REQUEST to network hosts route (8) - show / manipulate the IP routing table ssh (1) - OpenSSH SSH client tcpdump (8) - dump traffic on a network telnet (1) - user interface to the TELNET protocol wget (1) - The non-interactive network downloader
# Search for commands about disk usage man -k "disk usage"
df (1) - report file system disk space usage du (1) - estimate file space usage quota (1) - display disk usage and limits
Explanation: The -k option (equivalent to the apropos command) searches the NAME section of all man pages for the keyword. This is incredibly useful when:
  • You know what you want to do but not the command name
  • Discovering commands related to a topic
  • Learning what tools are available for a task
Note: If man -k returns "nothing appropriate", you may need to rebuild the man page database: sudo mandb
Example 4

Getting Quick Descriptions (whatis / -f option)

Get a one-line summary without opening the full man page.

# Get brief description of a command man -f ls # Using the whatis command (equivalent) whatis ls
ls (1) - list directory contents
# Check multiple commands at once whatis grep sed awk cut
grep (1) - print lines that match patterns sed (1) - stream editor for filtering and transforming text awk (1) - pattern scanning and processing language cut (1) - remove sections from each line of files
# See all sections with their descriptions whatis passwd
passwd (1) - change user password passwd (5) - the password file passwd (1ssl) - OpenSSL application commands
Explanation: The -f option (or whatis command) displays just the NAME section of the man page - a one-line description. This is perfect for:
  • Quick refresher on what a command does
  • Checking if a command exists
  • Seeing all available sections for a topic
  • Verifying command purpose before opening full man page
Quick Reference Script:
#!/bin/bash # quick-help.sh - Quick command reference echo "Quick Command Reference" echo "=======================" for cmd in ls cd pwd cp mv rm mkdir cat grep find; do printf "%-10s: %s\n" "$cmd" "$(whatis $cmd 2>/dev/null | head -1 | cut -d'-' -f2-)" done
Example 5

Viewing All Matching Pages (-a option)

Display all man pages that match, across all sections.

# View all man pages for printf (section 1 and 3) man -a printf # This will display: # 1. First, the printf(1) page (shell command) # 2. After you quit that, printf(3) page (C function) # View all pages for passwd man -a passwd # Shows passwd(1), then passwd(5), etc.
--Man-- next: printf(3) [ view (return) | skip (Ctrl-D) | quit (Ctrl-C) ]
Explanation: The -a option displays all matching manual pages in sequence. After viewing one page:
  • Press q to quit current page and view next one
  • Press Ctrl+D to skip to next page
  • Press Ctrl+C to quit completely

This is useful for comparing documentation across sections or learning all aspects of a topic.

Alternative Approach:
# List all available sections first man -f passwd # Then view specific ones man 1 passwd man 5 passwd
Example 6

Finding Man Page File Locations (-w option)

Discover where man pages are stored and verify their existence.

# Show location of ls man page man -w ls
/usr/share/man/man1/ls.1.gz
# Show locations of all passwd man pages man -aw passwd
/usr/share/man/man1/passwd.1.gz /usr/share/man/man5/passwd.5.gz
# Check if a man page exists before trying to view it if man -w docker >/dev/null 2>&1; then echo "Docker man page exists" man docker else echo "No man page for docker - check online docs" fi
Explanation: The -w option shows the file path without opening the page. Man pages are typically stored in:
  • /usr/share/man/ - System man pages
  • /usr/local/share/man/ - Locally installed software
  • /opt/*/man/ - Optional software packages

Files are usually gzipped (.gz) to save space.

Advanced Uses:
# Read man page directly with zless zless $(man -w ls) # Extract man page to text file man ls | col -b > ls_manual.txt # View raw man page source zcat $(man -w ls) | less # Check man page modification date ls -l $(man -w bash)
Example 7

Searching Full Text of Man Pages (-K option)

Search within the content of all man pages, not just descriptions.

# Search for "regular expression" in all man pages # Warning: This is slow as it searches full text man -K "regular expression" | head -20
grep(1) sed(1) regex(7) awk(1) perl(1) vim(1) less(1) [... and more ...]
Explanation: The -K (capital K) option searches the full text of every man page on the system. This is different from -k which only searches descriptions.
  • -k: Fast, searches NAME section only
  • -K: Slow, searches entire content of all pages

Use -K when you're looking for specific technical terms or concepts that might be buried in documentation.

Performance Note: man -K can take several minutes to complete as it decompresses and searches every man page. Use it sparingly, and consider combining with section restrictions: man -K -S 1 "pattern" to search only section 1.
Example 8

Exporting Man Pages to Text or PDF

Convert man pages to different formats for offline reading or printing.

# Export to plain text man ls | col -b > ls_manual.txt # Alternative method (cleaner formatting) man ls | col -bx > ls_manual.txt # Export to PDF using ps2pdf man -t ls | ps2pdf - ls_manual.pdf # Export to PostScript first (then can convert) man -t grep > grep_manual.ps ps2pdf grep_manual.ps grep_manual.pdf
Explanation: Man pages can be exported to various formats:
  • col -b: Removes backspaces/formatting for clean text
  • man -t: Outputs in troff/PostScript format
  • ps2pdf: Converts PostScript to PDF
# Create a complete command reference book #!/bin/bash # create-command-ref.sh COMMANDS="ls cd pwd cp mv rm mkdir cat grep find sed awk" OUTPUT_DIR="command_reference" mkdir -p "$OUTPUT_DIR" for cmd in $COMMANDS; do echo "Exporting $cmd..." man "$cmd" | col -bx > "$OUTPUT_DIR/${cmd}.txt" man -t "$cmd" | ps2pdf - "$OUTPUT_DIR/${cmd}.pdf" done echo "Complete! Reference saved to $OUTPUT_DIR/"
Why Export Man Pages:
  • Create offline documentation collections
  • Print reference materials
  • Share documentation with others
  • Read on devices without man command
  • Archive documentation for specific versions
Example 9

Creating Custom Man Pages

Write and install your own man pages for scripts and tools.

# Create a simple man page for your script cat > my-backup-tool.1 <<'EOF' .TH MY-BACKUP-TOOL 1 "January 2025" "Version 1.0" "User Commands" .SH NAME my-backup-tool \- automated backup utility .SH SYNOPSIS .B my-backup-tool [\fB\-d\fR \fIDIRECTORY\fR] [\fB\-o\fR \fIOUTPUT\fR] [\fB\-v\fR] .SH DESCRIPTION .B my-backup-tool is a simple backup utility that creates compressed archives of specified directories. .SH OPTIONS .TP .BR \-d ", " \-\-directory " " \fIDIRECTORY\fR Specify the directory to backup (default: current directory) .TP .BR \-o ", " \-\-output " " \fIOUTPUT\fR Specify output file name (default: backup_DATE.tar.gz) .TP .BR \-v ", " \-\-verbose Enable verbose output .TP .BR \-h ", " \-\-help Display help message and exit .SH EXAMPLES .TP Backup current directory: .B my-backup-tool .TP Backup specific directory: .B my-backup-tool \-d /home/user/documents .TP Backup with custom output name: .B my-backup-tool \-d /etc \-o system-config-backup.tar.gz .SH AUTHOR Written by Craig (craig@example.com) .SH SEE ALSO .BR tar (1), .BR gzip (1), .BR rsync (1) EOF # Preview the man page man ./my-backup-tool.1 # Install to local man directory sudo mkdir -p /usr/local/share/man/man1 sudo cp my-backup-tool.1 /usr/local/share/man/man1/ sudo mandb # Now accessible system-wide man my-backup-tool
Explanation: Man pages are written in roff/troff markup language. Key elements:
  • .TH: Title header (name, section, date, version, category)
  • .SH: Section header (NAME, SYNOPSIS, DESCRIPTION, etc.)
  • .B: Bold text
  • .BR: Bold then roman (for options)
  • .TP: Tagged paragraph (for options lists)
  • \fB, \fR, \fI: Font changes (bold, roman, italic)
Man Page Sections:

Standard sections in order: NAME (required), SYNOPSIS, DESCRIPTION, OPTIONS, EXIT STATUS, RETURN VALUE, ERRORS, ENVIRONMENT, FILES, VERSIONS, CONFORMING TO, NOTES, BUGS, EXAMPLES, AUTHORS, SEE ALSO

Tools for Creating Man Pages:
  • help2man: Generate man page from --help output
  • ronn: Write man pages in Markdown
  • pod2man: Convert Perl POD to man page
  • pandoc: Convert various formats to man pages
Example 10

Complete Man Page Navigation and Search Utility

A comprehensive script for efficient man page discovery and navigation.

#!/bin/bash # manhelp - Enhanced man page utility set -euo pipefail # Colors RED='\033[0;31m' GREEN='\033[0;32m' YELLOW='\033[1;33m' BLUE='\033[0;34m' CYAN='\033[0;36m' NC='\033[0m' log_info() { echo -e "${BLUE}[INFO]${NC} $*"; } log_success() { echo -e "${GREEN}[✓]${NC} $*"; } log_warn() { echo -e "${YELLOW}[!]${NC} $*"; } log_error() { echo -e "${RED}[✗]${NC} $*"; } # Show quick summary quick_info() { local topic="$1" echo "" log_info "Quick summary for: $topic" echo "" whatis "$topic" 2>/dev/null || log_error "No man page found for: $topic" } # Search by keyword search_keyword() { local keyword="$1" echo "" log_info "Searching for: $keyword" echo "" local results=$(man -k "$keyword" 2>/dev/null) if [ -z "$results" ]; then log_error "No results found for: $keyword" log_info "Try rebuilding man database: sudo mandb" return 1 fi echo "$results" | while read line; do cmd=$(echo "$line" | awk '{print $1}') section=$(echo "$line" | grep -oP '\(\K[^)]+' || echo "") desc=$(echo "$line" | cut -d'-' -f2-) echo -e "${CYAN}$cmd${NC}($section) -$desc" done } # Show all sections for a topic show_sections() { local topic="$1" echo "" log_info "All manual sections for: $topic" echo "" man -f "$topic" 2>/dev/null | while read line; do cmd=$(echo "$line" | awk '{print $1}') section=$(echo "$line" | grep -oP '\(\K[^)]+' || echo "") desc=$(echo "$line" | cut -d'-' -f2-) echo -e "${GREEN}$cmd${NC}(${YELLOW}$section${NC}) -$desc" done } # View man page with syntax highlighting view_page() { local topic="$1" local section="${2:-}" echo "" log_info "Opening man page for: $topic${section:+ (section $section)}" echo "" if [ -n "$section" ]; then man "$section" "$topic" else man "$topic" fi } # Export to PDF export_pdf() { local topic="$1" local section="${2:-}" local output="${3:-${topic}_manual.pdf}" echo "" log_info "Exporting $topic to PDF: $output" if [ -n "$section" ]; then man -t "$section" "$topic" | ps2pdf - "$output" else man -t "$topic" | ps2pdf - "$output" fi if [ -f "$output" ]; then log_success "PDF created: $output" log_info "Size: $(du -h "$output" | cut -f1)" else log_error "Failed to create PDF" return 1 fi } # Show man page location show_location() { local topic="$1" echo "" log_info "Man page locations for: $topic" echo "" man -aw "$topic" 2>/dev/null | while read path; do size=$(du -h "$path" | cut -f1) echo -e " ${CYAN}$path${NC} (${size})" done } # Compare two man pages side by side compare_pages() { local topic1="$1" local topic2="$2" echo "" log_info "Comparing: $topic1 vs $topic2" echo "" # Export to temp files local temp1=$(mktemp) local temp2=$(mktemp) man "$topic1" | col -bx > "$temp1" man "$topic2" | col -bx > "$temp2" # Show differences diff -y --width=160 "$temp1" "$temp2" | less rm -f "$temp1" "$temp2" } # Interactive search interactive_search() { echo "" echo "========================================" echo "Interactive Man Page Search" echo "========================================" echo "" while true; do read -p "Enter keyword (or 'quit'): " keyword [ "$keyword" = "quit" ] && break [ -z "$keyword" ] && continue results=$(man -k "$keyword" 2>/dev/null) if [ -z "$results" ]; then log_error "No results found" continue fi echo "" echo "Results:" echo "$results" | nl echo "" read -p "View page number (or Enter to skip): " num if [ -n "$num" ] && [ "$num" -gt 0 ] 2>/dev/null; then page=$(echo "$results" | sed -n "${num}p" | awk '{print $1}') if [ -n "$page" ]; then man "$page" fi fi echo "" done } # Create cheat sheet create_cheatsheet() { local output="${1:-command_cheatsheet.txt}" local commands="${2:-ls cd pwd cp mv rm mkdir grep find sed awk}" echo "" log_info "Creating cheat sheet: $output" echo "" { echo "=========================================" echo "COMMAND CHEAT SHEET" echo "Generated: $(date)" echo "=========================================" echo "" for cmd in $commands; do echo "----------------------------------------" echo "COMMAND: $cmd" echo "----------------------------------------" whatis "$cmd" 2>/dev/null || echo "No description available" echo "" # Extract SYNOPSIS if available man "$cmd" 2>/dev/null | \ sed -n '/SYNOPSIS/,/DESCRIPTION/p' | \ head -20 | \ grep -v "DESCRIPTION" echo "" done } > "$output" log_success "Cheat sheet created: $output" } # Show help show_help() { cat <<EOF Usage: $0 COMMAND [OPTIONS] Enhanced man page utility with search and export features. COMMANDS: quick TOPIC - Show brief description search KEYWORD - Search by keyword sections TOPIC - Show all available sections view TOPIC [SECTION] - View man page export TOPIC [SECTION] [OUTPUT] - Export to PDF location TOPIC - Show file location compare TOPIC1 TOPIC2 - Compare two pages interactive - Interactive search mode cheatsheet [OUTPUT] [COMMANDS] - Create command cheat sheet EXAMPLES: $0 quick ls $0 search network $0 sections passwd $0 view passwd 5 $0 export bash bash_manual.pdf $0 location grep $0 compare cp mv $0 interactive $0 cheatsheet mycommands.txt "ls cp mv rm" EOF } # Main if [ $# -eq 0 ]; then show_help exit 0 fi case "$1" in quick) [ $# -lt 2 ] && { log_error "Usage: $0 quick TOPIC"; exit 1; } quick_info "$2" ;; search) [ $# -lt 2 ] && { log_error "Usage: $0 search KEYWORD"; exit 1; } search_keyword "$2" ;; sections) [ $# -lt 2 ] && { log_error "Usage: $0 sections TOPIC"; exit 1; } show_sections "$2" ;; view) [ $# -lt 2 ] && { log_error "Usage: $0 view TOPIC [SECTION]"; exit 1; } view_page "$2" "${3:-}" ;; export) [ $# -lt 2 ] && { log_error "Usage: $0 export TOPIC [SECTION] [OUTPUT]"; exit 1; } export_pdf "$2" "${3:-}" "${4:-}" ;; location) [ $# -lt 2 ] && { log_error "Usage: $0 location TOPIC"; exit 1; } show_location "$2" ;; compare) [ $# -lt 3 ] && { log_error "Usage: $0 compare TOPIC1 TOPIC2"; exit 1; } compare_pages "$2" "$3" ;; interactive) interactive_search ;; cheatsheet) create_cheatsheet "${2:-}" "${3:-}" ;; help|--help|-h) show_help ;; *) log_error "Unknown command: $1" show_help exit 1 ;; esac
$ ./manhelp search compress [INFO] Searching for: compress bzip2(1) - a block-sorting file compressor compress(1) - compress and expand data gzip(1) - compress or expand files xz(1) - Compress or decompress .xz and .lzma files zip(1) - package and compress (archive) files $ ./manhelp sections passwd [INFO] All manual sections for: passwd passwd(1) - change user password passwd(5) - the password file $ ./manhelp export bash bash_guide.pdf [INFO] Exporting bash to PDF: bash_guide.pdf [✓] PDF created: bash_guide.pdf [INFO] Size: 156K
Explanation: This comprehensive utility provides:
  • Quick summaries with whatis
  • Keyword searching with formatted output
  • Section listing with color coding
  • PDF export functionality
  • File location discovery
  • Side-by-side comparison
  • Interactive search mode
  • Automated cheat sheet generation
  • Error handling and validation
Production Uses:
  • Training new system administrators
  • Creating documentation libraries
  • Quick command reference during troubleshooting
  • Building custom documentation sets
  • Offline documentation preparation

Manual Page Sections Reference

Section Description Examples
1 User commands ls, cat, grep, bash, vim
2 System calls open, read, write, fork, exec
3 Library functions printf, malloc, strlen, sqrt
4 Special files (devices) null, zero, random, tty
5 File formats passwd, fstab, hosts, crontab
6 Games fortune, cowsay, tetris
7 Miscellaneous man, regex, ascii, signal, hier
8 System administration mount, iptables, useradd, systemctl
9 Kernel routines (non-standard) Kernel internal APIs

Additional Information

Pro Tips for Man Pages:
  • Read the EXAMPLES section first - it's often the most useful
  • Use / to search within the man page
  • Check SEE ALSO section for related commands
  • SYNOPSIS uses conventions: [] = optional, ... = repeatable, | = choice
  • Set MANPAGER environment variable for custom pager
Useful Man Page Combinations:
# Search and open in one command man $(man -k network | fzf | awk '{print $1}') # Read man page as HTML man -H bash # Export all man pages for a command man -a -w passwd | xargs -I{} cp {} /backup/manpages/ # Create quick reference card man ls | grep -A 2 "^\s*-" | head -50 # Find recently updated man pages find /usr/share/man -name "*.gz" -mtime -30
Common Issues:
  • "No manual entry": Package may not be installed or mandb needs update
  • "Nothing appropriate": Run sudo mandb to rebuild database
  • Garbled output: Check TERM variable, try export TERM=xterm
  • Missing sections: Some packages don't include man pages
Man Page Locations:

Man pages are searched in directories specified by MANPATH environment variable:

# View current MANPATH manpath # Common locations: /usr/share/man /usr/local/share/man /opt/*/man ~/.local/share/man
Alternatives to Man Pages:
  • info: GNU info pages (more detailed, hyperlinked)
  • help: Built-in bash help for shell builtins
  • tldr: Community-driven simplified examples
  • cheat.sh: Interactive cheat sheets
  • --help: Built-in command help (quick reference)

Quick Reference

Task Command
View man page man command
Specific section man 5 passwd
Search by keyword man -k keyword
Brief description man -f command or whatis command
All sections man -a command
File location man -w command
Export to text man command | col -b > file.txt
Export to PDF man -t command | ps2pdf - file.pdf
Rebuild database sudo mandb
Search within page /keyword (then n for next)