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
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
| 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
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
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
- Press Space to scroll down
- Press q to quit
- Type /keyword and press Enter to search
- Press n to go to next search result
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): 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
- passwd, crontab, time, stat, kill, signal
- When in doubt, use
man -f topicto see all sections
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
# Search for network-related commands
man -k network | head -10
# Search for commands about disk usage
man -k "disk usage"
-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
man -k returns "nothing appropriate", you may need to rebuild the man page database: sudo mandb
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
# Check multiple commands at once
whatis grep sed awk cut
# See all sections with their descriptions
whatis passwd
-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
#!/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
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.
-a option displays all matching manual pages in sequence. After viewing one page:
- Press
qto quit current page and view next one - Press
Ctrl+Dto skip to next page - Press
Ctrl+Cto quit completely
This is useful for comparing documentation across sections or learning all aspects of a topic.
# List all available sections first
man -f passwd
# Then view specific ones
man 1 passwd
man 5 passwd
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
# Show locations of all passwd man pages
man -aw passwd
# 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
-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.
# 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)
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
-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.
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.
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
- 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/"
- Create offline documentation collections
- Print reference materials
- Share documentation with others
- Read on devices without man command
- Archive documentation for specific versions
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
- .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)
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
- 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
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
- 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
- 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
- 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
# 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
- "No manual entry": Package may not be installed or mandb needs update
- "Nothing appropriate": Run
sudo mandbto rebuild database - Garbled output: Check TERM variable, try
export TERM=xterm - Missing sections: Some packages don't include man pages
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
- 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) |