Introduction to man
The man command (short for "manual") is one of the most essential tools in Unix/Linux systems. It provides access to the system's manual pages, offering comprehensive documentation for commands, system calls, library functions, configuration files, and more. Understanding how to effectively use man is crucial for any user or administrator.
Key Concepts
- Manual Sections: Organized documentation divided into numbered sections
- Man Pages: Individual documentation entries for specific topics
- Pager Navigation: Using
lessor other pagers to browse content - Search Functionality: Finding relevant documentation quickly
- Cross-References: Related topics and see-also sections
1. Basic Usage
Simple man Commands
# View manual for a command man ls man cp man mv # View manual for a system function man printf man malloc # View manual for a configuration file man passwd man fstab # Quick help (not as detailed as man) command --help command -h
Navigating Man Pages
# Once inside a man page, use these keys: # Space or f - scroll forward one page # b - scroll back one page # Enter or Down - scroll forward one line # Up - scroll back one line # g - go to beginning # G - go to end # /pattern - search forward for pattern # ?pattern - search backward for pattern # n - repeat search forward # N - repeat search backward # q - quit # Example: Search for "option" in ls man page man ls # Then type: /option
2. Manual Sections
Understanding Sections
# Manual sections (1-9): # 1 - Executable programs or shell commands # 2 - System calls (functions provided by the kernel) # 3 - Library calls (functions within program libraries) # 4 - Special files (usually found in /dev) # 5 - File formats and conventions (e.g., /etc/passwd) # 6 - Games # 7 - Miscellaneous (including macro packages and conventions) # 8 - System administration commands (usually only for root) # 9 - Kernel routines # Specify section number man 1 ls # Command documentation man 3 printf # Library function man 5 passwd # File format man 8 fdisk # System administration
Finding Which Section
# Find what sections contain a topic man -f printf # or whatis printf # Show all matches across sections man -a printf # Shows all printf man pages sequentially # List all available sections for a command man -k printf | grep '^printf'
Common Section Examples
# Section 1: User Commands man 1 ls man 1 grep man 1 bash # Section 2: System Calls man 2 open man 2 read man 2 fork # Section 3: Library Functions man 3 strcpy man 3 malloc man 3 printf # Section 4: Special Files man 4 null man 4 zero man 4 tty # Section 5: File Formats man 5 crontab man 5 resolv.conf man 5 passwd # Section 7: Miscellaneous man 7 man man 7 regex man 7 signal # Section 8: System Administration man 8 fdisk man 8 mount man 8 useradd
3. Search and Navigation
Keyword Search
# Search man pages by keyword (apropos) man -k "copy file" # or apropos "copy file" # Search with regex man -k '^pri.*' # Search in specific section man -k -s 1 "network" # Find commands related to a topic man -k network | grep -i configure # Search for all man pages containing word man -K "configuration" # Searches ALL man pages (slow!)
Advanced Search Examples
#!/bin/bash
# Find all man pages about compression
find_compression_commands() {
man -k compress | grep -E 'compress|uncompress|gzip|gunzip|tar'
}
# Find system calls related to files
find_file_syscalls() {
man -k -s 2 | grep -E 'open|read|write|close|stat'
}
# Search within specific section with pattern
search_in_section() {
local section="$1"
local pattern="$2"
man -k -s "$section" . | grep -i "$pattern"
}
# Create a function to search and display
quick_man() {
local cmd="$1"
if man -f "$cmd" >/dev/null 2>&1; then
man "$cmd"
else
echo "No man page for $cmd. Searching..."
man -k "$cmd" | head -10
fi
}
Navigating Long Man Pages
# Jump to specific section by name
man ls
# Then press: /OPTIONS (jump to OPTIONS section)
# Use less features for navigation
man ls | less -p "OPTIONS" # Open directly at OPTIONS
# Extract specific section
man ls | sed -n '/^DESCRIPTION/,/^[A-Z]/p' | less
# View with line numbers
man ls | cat -n | less
# Create bookmark for common man pages
view_man_section() {
local cmd="$1"
local section="$2"
man "$cmd" | less -p "^$section"
}
# Usage: view_man_section ls OPTIONS
4. Formatting and Output Control
Output Formatting
# Save man page to file man ls > ls_manual.txt man ls | col -b > ls_clean.txt # Remove backspaces # Convert to plain text man ls | col -b | cat -s > ls_manual.txt # Convert to PDF man -t ls | ps2pdf - ls_manual.pdf # Convert to HTML man2html ls > ls_manual.html # View in different format GROFF_NO_SGR=1 man ls # Disable bold formatting MAN_KEEP_FORMATTING=1 man ls | less -R # Keep formatting
Environment Variables
# Set man page width export MANWIDTH=80 man ls # Now formatted for 80 columns # Set man page path export MANPATH=/usr/local/man:/usr/share/man # Set pager export MANPAGER="less -X" export PAGER="most" # Set default options export MANOPT="--regex" # Language settings export LANG=fr_FR.UTF-8 # French man pages if available export LC_ALL=C # Default English
Customizing Man Display
#!/bin/bash
# Create custom man function with color
cman() {
env \
LESS_TERMCAP_mb=$'\e[1;31m' \
LESS_TERMCAP_md=$'\e[1;34m' \
LESS_TERMCAP_me=$'\e[0m' \
LESS_TERMCAP_se=$'\e[0m' \
LESS_TERMCAP_so=$'\e[1;44;33m' \
LESS_TERMCAP_ue=$'\e[0m' \
LESS_TERMCAP_us=$'\e[1;32m' \
man "$@"
}
# Man page with line numbers
lnman() {
man "$@" | cat -n | less
}
# Man page with syntax highlighting
highlight_man() {
man "$1" | pygmentize -l man | less -R
}
# Man page summary (just description)
mansum() {
whatis "$1"
echo "---"
man "$1" | grep -A5 "^DESCRIPTION"
}
5. Advanced Features
Cross-Referencing
# Show related commands man -k ls | grep -E '^[a-z]+ ' # Follow "SEE ALSO" references man ls | sed -n '/SEE ALSO/,/^[A-Z]/p' # Find functions in specific library man -k -s 3 | grep GLIBC # Find all man pages that reference a concept man -k signal | grep -E ' [27] ' # Signal in sections 2 and 7
Multiple Man Pages
# View all man pages for a topic
man -a printf
# Press 'q' between pages to see next
# Compare different sections
diff <(man 1 printf | col -b) <(man 3 printf | col -b) | less
# Search across all sections for a pattern
find_all_refs() {
local pattern="$1"
for s in {1..8}; do
if man -s "$s" -k "$pattern" 2>/dev/null | grep -q .; then
echo "=== Section $s ==="
man -s "$s" -k "$pattern"
fi
done
}
Local Man Pages
# Add custom man pages
export MANPATH="$HOME/man:$MANPATH"
# Create custom man page directory
mkdir -p ~/man/man1
mkdir -p ~/man/man3
# Install custom man page
cp myprogram.1 ~/man/man1/
mandb ~/man # Update database
# View custom man page
man -M ~/man myprogram
# Create simple custom man page
create_custom_man() {
local cmd="$1"
cat > ~/man/man1/"$cmd".1 << EOF
.TH $cmd 1 "$(date)" "Version 1.0" "User Commands"
.SH NAME
$cmd \- my custom command
.SH SYNOPSIS
$cmd [OPTIONS]
.SH DESCRIPTION
This is my custom command.
.SH OPTIONS
.TP
.B \-h, \-\-help
Show this help message
.SH AUTHOR
Your Name
.SH SEE ALSO
bash(1), man(1)
EOF
mandb ~/man
}
6. Practical Examples
Script to Search and View Man Pages
#!/bin/bash
# Enhanced man page viewer
smart_man() {
local query="$1"
local section="${2:-}"
# Check if exact match exists
if [ -n "$section" ]; then
if man -s "$section" "$query" 2>/dev/null; then
return 0
fi
elif man -w "$query" 2>/dev/null; then
man "$query"
return 0
fi
# Search for related pages
echo "No exact match found. Searching for related pages..."
local results=$(man -k "$query" 2>/dev/null | head -20)
if [ -z "$results" ]; then
echo "No man pages found for '$query'"
return 1
fi
echo "$results" | nl -w2 -s': '
echo -n "Select page number (or 0 to quit): "
read -r choice
if [ "$choice" -gt 0 ] 2>/dev/null; then
local selected=$(echo "$results" | sed -n "${choice}p" | cut -d' ' -f1)
if [ -n "$selected" ]; then
man "$selected"
fi
fi
}
# Usage
# smart_man printf
# smart_man open 2
Man Page Browser
#!/bin/bash
# Interactive man page browser
man_browser() {
local sections="1:User Commands
2:System Calls
3:Library Functions
4:Special Files
5:File Formats
6:Games
7:Miscellaneous
8:System Admin
9:Kernel"
echo "Man Page Browser"
echo "================"
# Select section
echo "$sections" | nl -w2 -s': '
echo -n "Select section (1-9): "
read -r section
if [ -z "$section" ] || [ "$section" -lt 1 ] || [ "$section" -gt 9 ]; then
echo "Invalid section"
return 1
fi
# List pages in section
echo "Pages in section $section:"
man -k -s "$section" . 2>/dev/null | cut -d' ' -f1 | sort | less
echo -n "Enter page name (or 'q' to quit): "
read -r page
if [ "$page" != "q" ] && [ -n "$page" ]; then
man "$section" "$page"
fi
}
# Quick reference by category
man_category() {
local category="$1"
case "$category" in
file)
man -k -s 1 | grep -E 'ls|cp|mv|rm|cat|less|more|head|tail'
;;
network)
man -k -s 1 | grep -E 'ping|ssh|scp|ftp|wget|curl|netstat'
;;
process)
man -k -s 1 | grep -E 'ps|top|kill|nice|renice|jobs|fg|bg'
;;
system)
man -k -s 8 | head -50
;;
*)
echo "Categories: file, network, process, system"
;;
esac
}
Man Page Documentation Generator
#!/bin/bash
# Generate documentation from man pages
extract_man_docs() {
local cmd="$1"
local output_dir="${2:-./docs}"
mkdir -p "$output_dir"
# Extract different sections
for section in NAME SYNOPSIS DESCRIPTION OPTIONS EXAMPLES "SEE ALSO"; do
man "$cmd" | sed -n "/^$section/,/^[A-Z]/p" > "$output_dir/${section}.txt"
done
# Generate summary
{
echo "=== $cmd Manual ==="
echo "Generated: $(date)"
echo "=================="
echo
for file in "$output_dir"/*.txt; do
echo "--- $(basename "$file" .txt) ---"
cat "$file"
echo
done
} > "$output_dir/complete.txt"
echo "Documentation generated in $output_dir"
}
# Create cheat sheet from man page
man_cheatsheet() {
local cmd="$1"
local outfile="${2:-${cmd}_cheatsheet.txt}"
{
echo "=== $cmd Cheat Sheet ==="
echo
echo "SYNOPSIS:"
man "$cmd" | sed -n '/^SYNOPSIS/,/^[A-Z]/p' | grep -v "^[A-Z]" | head -5
echo
echo "COMMON OPTIONS:"
man "$cmd" | sed -n '/^OPTIONS/,/^[A-Z]/p' | head -20
echo
echo "EXAMPLES:"
man "$cmd" | sed -n '/^EXAMPLES/,/^[A-Z]/p' | head -10
} > "$outfile"
echo "Cheat sheet saved to $outfile"
}
7. Integration with Other Tools
With grep and sed
# Search for specific option in man page
man ls | grep -A5 "\-l"
# Extract all options
man ls | grep -o '\-[a-zA-Z]' | sort -u
# Find examples in man pages
find_examples() {
local cmd="$1"
man "$cmd" | sed -n '/^EXAMPLES/,/^[A-Z]/p' | grep -v "^[A-Z]"
}
# Count occurrences of word in man page
word_freq() {
local cmd="$1"
local word="$2"
man "$cmd" | tr '[:space:]' '\n' | grep -ic "$word"
}
# List all commands with man pages
list_all_commands() {
echo "User Commands:"
ls -1 /usr/bin | while read cmd; do
if man -w "$cmd" 2>/dev/null; then
echo " $cmd"
fi
done | head -20
}
With vim/editor
# View man page in vim
vman() {
local cmd="$1"
man "$cmd" | col -b | vim -R -c 'set ft=man' -
}
# Edit man page (for custom modifications)
eman() {
local cmd="$1"
local temp=$(mktemp)
man "$cmd" | col -b > "$temp"
vim "$temp"
# Optionally save modifications
}
# Create annotated man page
annotate_man() {
local cmd="$1"
local notes="$2"
man "$cmd" | col -b | awk -v notes="$notes" '
BEGIN {print "=== " cmd " with notes ==="}
{print}
/^OPTIONS/ {print "\nNOTES:\n" notes "\n"}
' | less
}
With fzf for interactive selection
# Interactive man page selector with fzf
fman() {
local cmd
cmd=$(man -k . | fzf --prompt="Select man page: " | cut -d' ' -f1)
if [ -n "$cmd" ]; then
man "$cmd"
fi
}
# Search and view with preview
fman_preview() {
man -k . | fzf --preview='echo {} | cut -d" " -f1 | xargs man' | cut -d' ' -f1 | xargs man
}
# Browse by category
fman_category() {
local category="$1"
man -k -s "${category:-1}" . | fzf --preview='echo {}' | cut -d' ' -f1 | xargs man
}
8. Troubleshooting and Tips
Common Issues
# Man page not found # Check if man pages are installed dpkg -l | grep man-db # Debian/Ubuntu rpm -qa | grep man # RHEL/CentOS # Install man pages sudo apt install man-db manpages manpages-dev # Debian/Ubuntu sudo yum install man man-pages # RHEL/CentOS # Update man database sudo mandb # Check man path echo $MANPATH manpath # Find where man pages are stored man -w ls # /usr/share/man/man1/ls.1.gz
Debugging Man Pages
# Check if man page exists test -f /usr/share/man/man1/ls.1.gz && echo "Exists" # View raw man page source zcat /usr/share/man/man1/ls.1.gz | head -50 # Check troff formatting man -l /usr/share/man/man1/ls.1.gz # Verify man page syntax man --warnings -l mypage.1 >/dev/null # Trace man command strace -e open man ls 2>&1 | grep '\.gz' # Debug man search path MAN_DEBUG=1 man ls 2>&1 | grep path
Performance Tips
# Cache man pages for faster access
export MAN_CACHE=~/.man_cache
mkdir -p "$MAN_CACHE"
# Pre-generate formatted man pages
precache_man() {
local cmd="$1"
local cache_file="$MAN_CACHE/${cmd}.txt"
if [ ! -f "$cache_file" ]; then
man "$cmd" | col -b > "$cache_file"
fi
less "$cache_file"
}
# Batch precache common commands
for cmd in ls cp mv rm cat less more; do
precache_man "$cmd" &
done
wait
9. Man Page Structure
Anatomy of a Man Page
# Standard man page sections
# NAME - Name of command and brief description
# SYNOPSIS - Command syntax and options
# DESCRIPTION - Detailed description
# OPTIONS - Explanation of command options
# EXIT STATUS - Return values
# RETURN VALUE - For library functions
# ERRORS - Error conditions
# ENVIRONMENT - Environment variables
# FILES - Files used by command
# EXAMPLES - Usage examples
# SEE ALSO - Related commands/man pages
# BUGS - Known issues
# AUTHOR - Who wrote it
# COPYRIGHT - Legal information
# Example: Create minimal man page template
create_man_template() {
local cmd="$1"
cat << EOF
.TH $cmd 1 "$(date)" "Version 1.0" "User Commands"
.SH NAME
$cmd \- brief description
.SH SYNOPSIS
\fB$cmd\fR [\fIOPTIONS\fR] \fIFILE\fR...
.SH DESCRIPTION
\fB$cmd\fR is a command that...
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
Display this help message.
.TP
\fB\-v\fR, \fB\-\-version\fR
Display version information.
.SH EXAMPLES
.TP
Basic usage:
$cmd file.txt
.SH SEE ALSO
bash(1), man(1)
.SH AUTHOR
Your Name <[email protected]>
EOF
}
10. Creating Custom Man Pages
Writing Your Own Man Pages
#!/bin/bash
# Create a man page for a custom script
create_script_man() {
local script_name="$1"
local description="$2"
local output="${3:-$script_name.1}"
cat > "$output" << EOF
.TH $script_name 1 "$(date)" "Version 1.0" "User Commands"
.SH NAME
$script_name \- $description
.SH SYNOPSIS
\fB$script_name\fR [\fIOPTIONS\fR] [\fIFILE\fR...]
.SH DESCRIPTION
\fB$script_name\fR is a custom script that...
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
Show this help message.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Increase output verbosity.
.TP
\fB\-c\fR, \fB\-\-config\fR \fIFILE\fR
Specify configuration file.
.SH EXAMPLES
.TP
Basic usage:
$script_name input.txt
.TP
With options:
$script_name -v -c config.ini data.txt
.SH EXIT STATUS
.TP
0
Successful completion.
.TP
1
General error.
.TP
2
Invalid arguments.
.SH FILES
.TP
/etc/$script_name.conf
System-wide configuration file.
.TP
~/.$script_name.conf
User-specific configuration.
.SH SEE ALSO
bash(1), man(1)
.SH AUTHOR
Your Name <[email protected]>
.SH COPYRIGHT
Copyright (C) $(date +%Y) Your Name
EOF
echo "Man page created: $output"
# Optionally compress and install
if [ -d /usr/local/man/man1 ]; then
gzip -c "$output" | sudo tee /usr/local/man/man1/"$script_name.1.gz" >/dev/null
sudo mandb /usr/local/man
echo "Installed to /usr/local/man/man1/"
fi
}
# Create man page for a shell function
create_function_man() {
local func_name="$1"
local output="${func_name}.3"
cat > "$output" << EOF
.TH $func_name 3 "$(date)" "Version 1.0" "Library Functions"
.SH NAME
$func_name \- shell function description
.SH SYNOPSIS
.nf
\fB$func_name\fR [\fIarg1\fR [\fIarg2\fR...]]
.fi
.SH DESCRIPTION
This shell function...
.SH RETURN VALUE
Returns 0 on success, non-zero on error.
.SH EXAMPLE
.nf
$ func_name arg1 arg2
.fi
.SH SEE ALSO
bash(1)
EOF
}
Installing Custom Man Pages
#!/bin/bash
# Install custom man pages
install_man_page() {
local man_file="$1"
local section="${2:-1}"
local target_dir="/usr/local/man/man$section"
# Create directory if needed
sudo mkdir -p "$target_dir"
# Compress and install
gzip -c "$man_file" | sudo tee "$target_dir/$(basename "$man_file").gz" >/dev/null
# Update man database
sudo mandb "$target_dir"
echo "Installed to $target_dir"
}
# Uninstall man page
uninstall_man_page() {
local name="$1"
local section="${2:-1}"
local target_dir="/usr/local/man/man$section"
sudo rm -f "$target_dir/$name.$section.gz"
sudo mandb "$target_dir"
echo "Removed $name from $target_dir"
}
# Create man page repository
init_man_repo() {
local repo_dir="$HOME/man_repo"
mkdir -p "$repo_dir"/{man1,man2,man3,man4,man5,man6,man7,man8}
cat > "$repo_dir/README" << EOF
Custom Man Page Repository
==========================
Location: $repo_dir
To use, add to your .bashrc:
export MANPATH="$repo_dir:\$MANPATH"
Sections:
- man1: User commands
- man2: System calls
- man3: Library functions
- man5: File formats
- man8: System administration
EOF
echo "Man page repository created at $repo_dir"
}
11. Man Page Translation
Working with Translated Man Pages
# View man page in different language
LANG=fr_FR.UTF-8 man ls
LANG=de_DE.UTF-8 man ls
LANG=es_ES.UTF-8 man ls
# Install language packs
sudo apt install manpages-fr manpages-de manpages-es # Debian/Ubuntu
# List available languages
ls /usr/share/man/ | grep -E '^[a-z][a-z]_[A-Z][A-Z]'
# Create script to cycle through languages
cycle_lang() {
local cmd="$1"
local langs="C en fr de es it pt ru ja ko zh"
for lang in $langs; do
echo "=== $lang ==="
LANG="${lang}_${lang^^}.UTF-8" man "$cmd" 2>/dev/null | head -5
echo
done
}
12. Man Page Alternatives and Complements
Alternative Documentation Tools
# info pages (GNU hypertext documentation) info ls info coreutils # help builtin (for shell builtins) help cd help for # whatis - one-line description whatis ls whatis cp # apropos - search by keyword apropos directory # tldr - simplified man pages (community-driven) tldr ls tldr tar # cheat - community-driven cheat sheets cheat tar cheat find # Installing alternatives # For tldr: npm install -g tldr # or: apt install tldr # For cheat: pip install cheat
Comparison Tool
#!/bin/bash
# Compare different documentation sources
doc_compare() {
local cmd="$1"
echo "=== $cmd Documentation ==="
echo
echo "--- man page ---"
man -f "$cmd" 2>/dev/null || echo "No man page"
man "$cmd" 2>/dev/null | head -10
echo
echo "--- info page ---"
info "$cmd" 2>/dev/null | head -10 || echo "No info page"
echo
echo "--- help option ---"
"$cmd" --help 2>/dev/null | head -10 || echo "No --help option"
echo
echo "--- whatis ---"
whatis "$cmd" 2>/dev/null || echo "No whatis entry"
}
# Usage
# doc_compare ls
13. Man Page Statistics
Analyzing Man Pages
#!/bin/bash
# Count total man pages
count_man_pages() {
local total=0
for section in {1..8}; do
count=$(ls -1 /usr/share/man/man$section/*.gz 2>/dev/null | wc -l)
echo "Section $section: $count pages"
total=$((total + count))
done
echo "Total: $total man pages"
}
# Find largest man pages
largest_man_pages() {
find /usr/share/man -name "*.gz" -exec ls -lh {} \; 2>/dev/null |
sort -k5 -rh | head -20 |
while read line; do
file=$(echo "$line" | awk '{print $9}')
name=$(basename "$file" .gz)
echo "$line" | awk '{printf "%s %s %s %s ", $5, $6, $7, $8}'
echo "$name"
done
}
# Most referenced commands
most_referenced() {
local temp=$(mktemp)
find /usr/share/man -name "*.gz" -exec zcat {} \; 2>/dev/null |
grep -o '\b[a-zA-Z][a-zA-Z]*([1-8])' |
sort | uniq -c | sort -rn > "$temp"
head -20 "$temp"
rm "$temp"
}
# Man page size trends
man_trends() {
echo "Man Page Statistics"
echo "=================="
echo
local total_size=$(du -sh /usr/share/man | cut -f1)
echo "Total size: $total_size"
local total_pages=$(find /usr/share/man -name "*.gz" | wc -l)
echo "Total pages: $total_pages"
echo
echo "Size by section:"
for section in {1..8}; do
if [ -d "/usr/share/man/man$section" ]; then
size=$(du -sh "/usr/share/man/man$section" 2>/dev/null | cut -f1)
count=$(ls -1 "/usr/share/man/man$section"/*.gz 2>/dev/null | wc -l)
printf "Section %d: %s (%d pages)\n" "$section" "$size" "$count"
fi
done
}
Conclusion
The man command is an indispensable tool for Unix/Linux users:
Key Takeaways
- Comprehensive Documentation: Access to complete system documentation
- Organized Structure: Well-organized manual sections (1-9)
- Powerful Navigation: Search, cross-reference, and quick access
- Extensible: Add custom man pages for your own tools
- Portable: Available on virtually all Unix-like systems
Quick Reference
| Command | Description |
|---|---|
man command | View manual for command |
man -k keyword | Search man pages by keyword |
man -f command | Show brief description |
man -a command | Show all matching man pages |
man -s section command | View specific section |
man -w command | Show location of man page |
Best Practices
- Use
manfirst when learning new commands - Check different sections for comprehensive info
- Utilize search (
/pattern) to find specific content - Create custom man pages for your own tools
- Keep man database updated with
mandb - Explore SEE ALSO section for related commands
- Use environment variables to customize viewing
The man command embodies the Unix philosophy of providing comprehensive, accessible documentation directly in the system. Mastering its use is essential for effective system administration and development.