man - Manual Pages

1. Introduction

The man command is an indispensable utility in Linux and Unix-like operating systems, serving as the primary interface to the system’s manual pages (often called “man pages”). These manual pages are comprehensive pieces of documentation for commands, system calls, library functions, configuration files, and other system components.

man stands for manual. Learning to effectively use man is a fundamental skill for any Linux user, as it provides authoritative and detailed information directly on the system, often more specific to your installed versions than generic online documentation.

2. Basic Syntax

The basic syntax for the man command is:

# Basic syntax of the man command
$ man [OPTION]... [SECTION] NAME...

• [OPTION]...: Optional flags that modify how man searches for and displays manual pages. These can range from simple display tweaks to complex search modifications.
• [SECTION]: An optional number (1-9, plus extensions like 3pm, n) specifying which section of the manual to search within. If omitted, man searches all sections in a predefined order, typically starting with section 1.
• NAME...: The name of the command, function, configuration file, or concept for which you want to view the manual page. You can specify multiple names, and man will display them sequentially.

When man NAME is executed, man searches for the manual page associated with NAME, formats it using tools like nroff or groff, and then typically displays it using a “pager” program like less (which allows scrolling and searching within the page). This process ensures that the documentation is readily accessible in a formatted, readable form directly in your terminal.

3. Core Use Cases with Examples

The man command itself doesn’t modify the filesystem, so we don’t need a specific file/directory setup for its core examples. The examples below focus on how to access different types of documentation, with distinct commands to avoid overlap with the “Key Options Explained” section.

3.1 Viewing the Manual Page for a Command

This is the most common use: getting help for a specific command.

# Display the manual page for the 'ls' command, a staple for listing directory contents
$ man ls

Output:

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 ..
... (many more options and details follow) ...

Navigation within man (using less):

• Scroll Down: Down Arrow, Page Down, Spacebar
• Scroll Up: Up Arrow, Page Up, b (back one screen)
• Search Forward: / followed by your search term, then Enter (e.g., /--recursive). Press n for next match, N for previous.
• Search Backward: ? followed by your search term, then Enter.
• Quit: q

3.2 Viewing the Manual Page for a System Call

System calls are functions provided by the kernel, typically documented in Section 2.

# Display the manual page for the 'read' system call, used to read from file descriptors
$ man 2 read

Output:

READ(2)                  Linux Programmer's Manual                 READ(2)

NAME
       read - read from a file descriptor

SYNOPSIS
       #include <unistd.h>

       ssize_t read(int fd, void *buf, size_t count);

DESCRIPTION
       read() attempts to read up to count bytes from file descriptor fd
       into the buffer starting at buf.
... (details on parameters, return values, and errors continue) ...

3.3 Viewing the Manual Page for a Library Function

Standard C library functions are often in Section 3.

# Display the manual page for the 'printf' library function, crucial for formatted output in C
$ man 3 printf

Output:

PRINTF(3)                Linux Programmer's Manual               PRINTF(3)

NAME
       printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf,
       vsnprintf - formatted output conversion

SYNOPSIS
       #include <stdio.h>

       int printf(const char *restrict format, ...);
       int fprintf(FILE *restrict stream,
                   const char *restrict format, ...);
... (extensive details on usage and variants follow) ...

3.4 Viewing the Manual Page for a Configuration File

Configuration file formats and details are often in Section 5.

# Display the manual page for the 'fstab' configuration file, which defines filesystem mounts
$ man 5 fstab

Output:

FSTAB(5)                     File Formats Manual                    FSTAB(5)

NAME
       fstab - static information about the filesystems

SYNOPSIS
       /etc/fstab

DESCRIPTION
       The file fstab contains descriptive information about the various
       file systems.  fstab is only read by programs, and not written; it
       is the duty of the system administrator to properly create and
       maintain this file.  Each filesystem is described on a separate
       line; fields on each line are separated by tabs or spaces.
... (details on fields and options continue) ...

3.5 Searching for Manual Pages by Keyword (-k or apropos)

If you don’t know the exact name of a command or page but know a keyword related to what you want to do.

# Search for manual pages related to "copy files" to find relevant commands
$ man -k "copy files"
# This is often equivalent to the 'apropos' command:
# $ apropos "copy files"

Output (example, varies by system):

cp (1)               - copy files and directories
cpgr (1)             - copy with progress
dd (1)               - convert and copy a file
install (1)          - copy files and set attributes
scp (1)              - secure copy (remote file copy program)
rsync (1)            - a fast, versatile, remote (and local) file-copying tool
...

This lists man pages whose name or short description contains “copy files”, along with their section number.

3.6 Viewing the Manual Page for a System Administration Command

System administration commands are typically in Section 8, often requiring elevated privileges.

# Display the manual page for the 'shutdown' command, used to power off or reboot the system
$ man 8 shutdown

Output:

SHUTDOWN(8)              System Manager's Manual              SHUTDOWN(8)

NAME
       shutdown - halt, power-off or reboot the machine

SYNOPSIS
       shutdown [OPTIONS...] [TIME] [WALL_MESSAGE]

DESCRIPTION
       shutdown may be used to halt, power-off or reboot the machine.
... (details on options and usage follow) ...

This example broadens the scope to include administrative tools, a common use case for system administrators.

4. Key Options Explained (with Examples)

Many options control how man searches for and displays pages. Examples here use different commands from those in “Core Use Cases” (e.g., avoiding ls, read, printf, fstab, shutdown) to prevent duplication.

4.1 -S LIST, -s LIST, —sections=LIST

Purpose: Restrict the search to a colon-separated LIST of manual sections.

Syntax:

# Syntax for restricting man to specific sections
$ man -s SECTION_LIST NAME

Use Case: When you know a command or function exists in multiple sections and you want a specific one, or want to search only within certain types of documentation.

Example:

# Search only in section 1 for 'grep' to get the command, not other contexts
$ man -s 1 grep
# Or, more commonly written as:
$ man 1 grep

Output:

GREP(1)                  General Commands Manual                 GREP(1)

NAME
       grep - print lines that match patterns
...

# Search for 'mount' only in sections 2 and 8 (system calls and admin commands)
$ man -s 2:8 mount

Output (depends on order and availability):

MOUNT(2)                 Linux Programmer's Manual                MOUNT(2)

NAME
       mount - mount filesystem
...

This ensures you target specific documentation types efficiently.

4.1.1 Advanced Section Restriction

You can combine multiple sections to narrow your search further.

# Look for 'kill' in sections 1 (commands) and 2 (system calls) only
$ man -s 1:2 kill

Output (first match, typically section 1):

KILL(1)                  User Commands                          KILL(1)

NAME
       kill - send a signal to a process
...

4.2 -f, —whatis

Purpose: Equivalent to the whatis command. Displays a very short, one-line description of the NAME from its manual page header(s). It searches the whatis database, which is pre-generated.

Syntax:

# Syntax for getting a quick description
$ man -f NAME

Use Case: Quickly find out the purpose of a command without reading the full man page.

Example:

# Get a one-line description of 'cat', a basic file concatenation tool
$ man -f cat

Output:

cat (1)              - concatenate files and print on the standard output

4.3 -k, —apropos

Purpose: Equivalent to the apropos command. Searches the short descriptions (summaries) of manual pages for occurrences of KEYWORD(s). Useful when you don’t know the exact command name.

Syntax:

# Syntax for keyword search across man page summaries
$ man -k KEYWORD

Use Case: Finding commands related to a specific task or concept.

Example:

# Search for man pages related to "network interface" to explore networking tools
$ man -k "network interface"

Output (varies by system):

ifconfig (8)         - configure a network interface
ip (8)               - show / manipulate routing, network devices, interfaces and tunnels
netdevice (7)        - low level access to network devices
ifup (8)             - bring a network interface up
...

4.4 -K, —global-apropos

Purpose: Search for text in all manual pages (full text search). This can be very slow as it reads through the content of many files.

Syntax:

# Syntax for full-text search across all man pages
$ man -K KEYWORD

Use Case: When -k (which only searches summaries) doesn’t find what you need, and you want to perform a more exhaustive search through the entire content of all man pages.

Example:

# Search for the exact phrase "default gateway" in all man pages
$ man -K "default gateway"

Output Behavior:
It opens the first matching page in the pager (e.g., less). Press q to quit that page, and man will prompt you to view the next match, continuing until all matches are exhausted or you stop. For example, the options in ubuntu are: [ view (return) | skip (Ctrl-D) | quit (Ctrl-C) ]

Sample Output:

--Man-- next: systemd-resolved.service(8) [ view (return) | skip (Ctrl-D) | quit (Ctrl-C) ]

--Man-- next: systemd.network(5) [ view (return) | skip (Ctrl-D) | quit (Ctrl-C) ]

--Man-- next: netplan(5) [ view (return) | skip (Ctrl-D) | quit (Ctrl-C) ]

--Man-- next: nm-settings-nmcli(5) [ view (return) | skip (Ctrl-D) | quit (Ctrl-C) ]
--Man-- next: nm-settings(5) [ view (return) | skip (Ctrl-D) | quit (Ctrl-C) ]
...

4.5 -a, —all

Purpose: Display all matching manual pages in succession, instead of just the first one found. Useful when a name exists in multiple sections and you want to see all of them.

Syntax:

# Syntax to view all instances of a name across sections
$ man -a NAME

Use Case: Viewing documentation for a term that is both a command and a library function.

Example:

# Display all man pages for 'sleep', which has entries in sections 1 and 3
$ man -a sleep

Output Behavior:
First shows sleep(1) (the command), then after quitting with q, shows sleep(3) (the C library function).

4.6 -w, —where, —path

Purpose: Do not display the manual page, but instead print the location(s) of the pre-formatted manual page file(s) that man would display.

Syntax:

# Syntax to locate man page files
$ man -w [SECTION] NAME

Use Case: Finding the actual man page source file on disk, useful for debugging or processing the file directly.

Example:

# Show the path to the 'grep' man page
$ man -w grep

Output (path varies):

/usr/share/man/man1/grep.1.gz

4.7 -W, —where-cat, —location-cat

Purpose: Similar to -w, but prints the location(s) of the unformatted (cat) source manual page files, typically in nroff/troff format before formatting.

Syntax:

# Syntax to locate unformatted man page source files
$ man -W [SECTION] NAME

Use Case: Finding the raw source of a man page for editing or analysis.

Example:

# Show the path to the unformatted source for 'cat'
$ man -W cat

Output (path varies):

/usr/share/man/man1/cat.1

4.8 -l, —local-file

Purpose: Interpret NAME as a local filename and display it as a man page. man will try to format it if it’s in nroff/troff format.

Syntax:

# Syntax to view a local man page file
$ man -l ./my_custom_manual.1

Use Case: Viewing or testing a man page you are writing or one not installed in standard directories.

Example:

# Create a simple nroff-like file for demonstration
$ echo ".TH MYCMD 1 "May 2025" "1.0" "My Command Manual"" > my_manual.1
$ echo ".SH NAME" >> my_manual.1
$ echo "mycmd - an example command" >> my_manual.1
# Display it using -l to test the custom man page
$ man -l ./my_manual.1

Output:

MYCMD(1)                My Command Manual                MYCMD(1)

NAME
       mycmd - an example command
...

4.9 -P PAGER, —pager=PAGER

Purpose: Specify which pager program to use for displaying the man page. The default is usually less.

Syntax:

# Syntax to specify a custom pager
$ man -P PAGER_COMMAND NAME

Use Case: Using a different pager like more, or cat (to send to stdout without paging), or a custom script.

Example:

# Display 'grep' man page using 'more' instead of the default 'less'
$ man -P more grep

Output Behavior:
The grep man page is displayed using more, with its own navigation (space to scroll, no backward scrolling by default).

4.10 -C FILE, —config-file=FILE

Purpose: Use a custom man configuration file instead of the default (e.g., /etc/man_db.conf).

Syntax:

# Syntax to use a custom configuration file
$ man -C ./my_man.conf NAME

Use Case: Testing different man configurations or environments.

Example:

# Use a custom config file to display the 'who' man page
$ man -C ./my_man.conf who

4.11 -d, —debug

Purpose: Print debugging information instead of displaying the man page, useful for troubleshooting man itself.

Syntax:

# Syntax to enable debug output
$ man -d NAME

Example:

# Debug the process for finding the 'who' man page
$ man -d who

Output (example, varies):

Reading config file /etc/man_db.conf
Using section list: 1:n:l:8:3:2:5:4:9:6:7:p:o
Checking path /usr/share/man/man1/who.1.gz
...

4.12 -L LOCALE, —locale=LOCALE

Purpose: Temporarily override the system’s locale to display man pages in a specific language, if available.

Syntax:

# Syntax to specify a locale
$ man -L LOCALE NAME

Example:

# Attempt to show the 'who' man page in French (if French man pages are installed)
$ man -L fr who

Output (if available):

WHO(1)                   Manuel des commandes                  WHO(1)

NOM
       who - affiche les utilisateurs actuellement connectés
...

4.13 -m system[,…], —systems=system[,…]

Purpose: Access manual pages from other operating systems if available on the system. This allows viewing documentation for commands specific to different OSes.

Syntax:

# Syntax to specify a system for man pages
$ man -m system[,...] NAME

Use Case: When working on a system that has man pages from multiple OSes installed, you can specify which system’s man pages to use.

Example:

# View the 'ls' man page from the NewOS system (if installed)
$ man -m NewOS ls

Output:
Displays the ls man page specific to NewOS, if available.

4.14 -e sub-extension, —extension=sub-extension

Purpose: Restrict the search to manual pages with a specific sub-extension, useful for packages like Tcl that use extensions like 3tcl.

Syntax:

# Syntax to specify a sub-extension
$ man -e sub-extension NAME

Use Case: When multiple packages have man pages with the same name but different extensions, this option helps select the correct one.

Example:

# View the 'exit' man page specifically for Tcl (extension 'tcl')
$ man -e tcl exit

Output:
Displays exit(3tcl) instead of the standard exit(3).

4.15 —regex

Purpose: Show all pages where the name or description matches the regular expression provided as the page argument.

Syntax:

# Syntax for regex search
$ man --regex REGEX

Use Case: Searching for man pages using complex patterns, especially when combined with -k or -K.

Example:

# Find all man pages with "print" in their name or description using regex
$ man -k --regex 'print'

Output:
Lists man pages matching the regex pattern.

4.16 —wildcard

Purpose: Similar to --regex, but uses shell-style wildcards for matching page names or descriptions.

Syntax:

# Syntax for wildcard search
$ man --wildcard WILDCARD

Use Case: Easier pattern matching for users familiar with shell wildcards.

Example:

# Find man pages with names starting with 'ls'
$ man --wildcard 'ls*'

Output:
Lists man pages like ls(1), lsb_release(1), etc.

4.17 —names-only

Purpose: When used with --regex or --wildcard, match only the page names, not descriptions.

Syntax:

# Syntax to match only names
$ man --names-only --regex REGEX

Use Case: Narrowing down searches to specific command names.

Example:

# Find man pages with names matching 'ls' using regex, ignoring descriptions
$ man --names-only --regex '^ls$'

Output:
Only ls(1) is listed, not other pages mentioning “ls” in descriptions.

4.18 -u, —update

Purpose: Update the man database caches of installed manual pages. Typically, mandb is used instead.

Syntax:

# Syntax to update man database
$ man -u

Use Case: Manually refreshing the whatis database, though mandb is preferred.

Example:

# Update the man database
$ man -u

Output:
No output if successful; the database is updated in the background.

4.19 —no-subpages

Purpose: Disable the interpretation of hyphenated names as subcommands (e.g., git-diff as git diff).

Syntax:

# Syntax to disable subpage interpretation
$ man --no-subpages NAME

Use Case: When you want to view man pages for commands with hyphens without treating them as subcommands.

Example:

# View man pages for 'git' and 'diff' separately, not as 'git-diff'
$ man -aw --no-subpages git diff

Output:

/usr/share/man/man1/git.1.gz
/usr/share/man/man1/diff.1.gz

4.20 -R encoding, —recode=encoding

Purpose: Output the manual page source converted to the specified encoding.

Syntax:

# Syntax to recode man page source
$ man -R encoding NAME

Use Case: Converting man pages to a different character encoding for compatibility or further processing.

Example:

# Recode 'ls' man page to UTF-8
$ man -R UTF-8 ls > ls_man.utf8

Output:
The source of the ls man page in UTF-8 encoding is saved to ls_man.utf8.

4.21 -t, —troff

Purpose: Use groff -mandoc to format the manual page to stdout, useful for further processing or conversion.

Syntax:

# Syntax to format with troff
$ man -t NAME

Use Case: Generating formatted output for printing or conversion to other formats like PDF.

Example:

# Format 'ls' man page and pipe to a printer
$ man -t ls | lpr

Output:
The formatted ls man page is sent to the printer.

4.22 -T[device], —troff-device[=device]

Purpose: Change the output device for groff, allowing output in formats like PDF, PostScript, etc.

Syntax:

# Syntax to specify troff device
$ man -T device NAME

Use Case: Generating man pages in different formats for various needs.

Example:

# Generate 'ls' man page in PDF format
$ man -T pdf ls > ls.pdf

Output:
A PDF file ls.pdf containing the formatted man page.

4.23 -H[browser], —html[=browser]

Purpose: Produce HTML output and display it in a web browser.

Syntax:

# Syntax to generate and view HTML
$ man -H[browser] NAME

Use Case: Viewing man pages in a browser for easier navigation or sharing.

Example:

# Open 'ls' man page in the default browser
$ man -H ls

Output:
The ls man page is displayed in HTML in the specified or default browser.

4.24 -Z, —ditroff

Purpose: Use troff and a post-processor to produce output for the chosen device, suppressing groff’s default behavior.

Syntax:

# Syntax to use ditroff
$ man -Z NAME

Use Case: Advanced formatting control, typically for specific output devices.

Example:

# Format 'ls' using ditroff
$ man -Z ls

Output:
Formatted output suitable for the chosen device.

4.25 —no-hyphenation, —nh

Purpose: Disable automatic hyphenation in the formatted output.

Syntax:

# Syntax to disable hyphenation
$ man --no-hyphenation NAME

Use Case: Preventing hyphenation in words, which can be useful for certain display preferences.

Example:

# View 'ls' man page without hyphenation
$ man --no-hyphenation ls

Output:
The ls man page is displayed without automatic hyphenation.

4.26 —no-justification, —nj

Purpose: Disable full justification, leaving text left-aligned.

Syntax:

# Syntax to disable justification
$ man --no-justification NAME

Use Case: Preferring ragged-right text for easier reading or specific formatting needs.

Example:

# View 'ls' man page with left-aligned text
$ man --no-justification ls

Output:
The ls man page is displayed with text aligned to the left margin only.

4.27 -p string, —preprocessor=string

Purpose: Specify preprocessors to run before nroff or troff, such as eqn, tbl, etc.

Syntax:

# Syntax to specify preprocessors
$ man -p string NAME

Use Case: Handling man pages that require specific preprocessing for equations, tables, etc.

Example:

# Use 'tbl' preprocessor for a man page with tables
$ man -p t NAME

Output:
The man page is processed with the specified preprocessors before formatting.

4.28 -7, —ascii

Purpose: Display the man page using pure ASCII characters, useful for terminals that don’t support extended character sets.

Syntax:

# Syntax to force ASCII output
$ man -7 NAME

Use Case: Ensuring compatibility with older or limited terminals.

Example:

# View 'ls' man page in ASCII
$ man -7 ls

Output:
The ls man page is displayed using only ASCII characters, with approximations for special characters.

4.29 -D, —default

Purpose: Reset man’s behavior to its default settings, typically used as the first option. This clears any options set via the $MANOPT environment variable, allowing subsequent options to take effect normally.

Syntax:

# Syntax to reset man to default behavior
$ man -D [OTHER_OPTIONS] NAME

Use Case: Ensuring a clean slate for man’s operation, especially when $MANOPT might have unexpected settings.

Example:

# Reset to defaults and then display 'who' man page
$ man -D who

Output Behavior:
Displays the who man page using default settings, ignoring any prior $MANOPT configurations.

4.30 —warnings[=warnings]

Purpose: Enable warnings from groff during formatting to check the source text of manual pages for issues (e.g., typographical errors). You can specify a comma-separated list of warning categories; default is “mac”.

Syntax:

# Syntax to enable groff warnings
$ man --warnings[=WARNINGS] NAME

Use Case: Debugging or validating man page source files during development.

Example:

# Display 'who' man page with groff warnings enabled for 'mac' category
$ man --warnings who

Output Behavior:
Displays the who man page, with any groff warnings (e.g., about macro usage) printed to stderr.

4.31 -c, —catman

Purpose: Used by the catman program to reformat man pages into pre-formatted “cat” pages for faster display. Not intended for general user use.

Syntax:

# Syntax for catman usage (not typical for end users)
$ man -c NAME

Use Case: System maintenance tasks involving man page caching.

Example:

# Typically used internally by catman, not directly by users
$ man -c who

Output Behavior:
Formats the who man page as a cat page, but this is generally handled by system scripts.

4.32 -r prompt, —prompt=prompt

Purpose: Customize the prompt string for the less pager when viewing man pages. The string can include $MAN_PN for the page name and section.

Syntax:

# Syntax to set a custom prompt for less
$ man -r "PROMPT_STRING" NAME

Use Case: Personalizing the pager display for better context while reading man pages.

Example:

# Set a custom prompt for 'who' man page
$ man -r "Manual $MAN_PN line %lt" who

Output Behavior:
Displays the who man page in less with a prompt like “Manual who(1) line 1”.

4.33 -X[dpi], —gxditview[=dpi]

Purpose: Display the formatted man page in a graphical window using gxditview, with options for dots-per-inch (dpi) settings like 75 or 100.

Syntax:

# Syntax to display in a graphical window
$ man -X[dpi] NAME

Use Case: Viewing man pages graphically instead of in the terminal.

Example:

# Display 'who' man page in gxditview at 100 dpi
$ man -X100 who

Output Behavior:
Opens a graphical window showing the who man page at 100 dpi resolution.

4.34 —usage

Purpose: Print a short usage message for the man command and exit, providing a quick syntax overview.

Syntax:

# Syntax to display usage message
$ man --usage

Use Case: Quick reminder of man’s command-line syntax without full help.

Example:

# Show usage message
$ man --usage

Output (example):

man [man options] [[section] page ...] ...

5. Combining Options

You can combine multiple options to achieve more specific results.

5.1 Combining -a and -w

Show all paths for a name across sections.

# Show all paths for 'sleep' man pages
$ man -aw sleep

Output (varies):

/usr/share/man/man1/sleep.1.gz
/usr/share/man/man3/sleep.3.gz

5.2 Combining -k and -s

Search for a keyword within specific sections.

# Search for "disk" only in sections 1 and 8
$ man -k -s 1:8 disk

Output (example):

df (1)               - report file system disk space usage
fdisk (8)            - manipulate disk partition table
...

5.3 Combining -l and -P

View a local man page with a specific pager.

# View a local man page without paging using 'cat'
$ man -l -P cat ./my_manual.1

Output:

MYCMD(1)                My Command Manual                MYCMD(1)

NAME
       mycmd - an example command
...

6. Handling Special Cases

The original outline mentions filenames with hyphens, spaces, permissions, and directories, but these are less relevant to man than to file manipulation commands. Below are adapted special cases pertinent to man.

6.1 Man Pages with Unusual Names

While rare, some man pages might have unconventional names (e.g., Perl modules).

# Display the man page for 'perlpod', a Perl documentation format
$ man perlpod

Output:

PERLPOD(1)               Perl Programmers Reference Guide         PERLPOD(1)

NAME
       perlpod - the Plain Old Documentation format for Perl
...

6.2 Man Pages for Aliases or Symlinks

Commands that are aliases or symlinks share man pages.

# 'egrep' often links to 'grep'; view its man page
$ man egrep

Output:

GREP(1)                  General Commands Manual                 GREP(1)

NAME
       grep, egrep, fgrep - print lines that match patterns
...

The man page notes aliases like egrep.

6.3 Permissions and Man Pages

Man pages are typically readable by all, but custom pages might have restricted access.

# Attempt to view a man page in a restricted directory (e.g., root-only)
$ man -M /root/private/man mycmd

Output (if no permission):

No manual entry for mycmd

Solution: Adjust permissions or use sudo if appropriate.

6.4 Directories and Custom Man Pages

Use -M or MANPATH for custom man page directories.

# View a man page from a custom directory
$ man -M /opt/mycmd/man mycmd

Output (if present):

MYCMD(1)                 Custom Command Manual                 MYCMD(1)

NAME
       mycmd - a custom command
...

7. Frequently Asked Questions (FAQ)

7.1 What is a “man page”?

A manual page is a piece of on-system documentation for a command, system call, library function, configuration file, or other system component. They are the traditional form of documentation on Unix-like systems.

7.2 How do I search within a man page?

Once the man page is open (usually in less), type / followed by your search term and press Enter (e.g., /--verbose). Press n for the next match and N (Shift+n) for the previous match. Use ? for backward search.

7.3 How do I quit a man page?

Press q.

7.4 What do the numbers in parentheses after command names mean (e.g., ls(1), printf(3))?

They indicate the manual page section the entry belongs to. ls(1) is a user command, printf(3) is a C library function. This helps differentiate when a name exists in multiple contexts.

7.5 man says “No manual entry for ‘command’“. What do I do?

• Check Spelling: Ensure the command name is correct.
• Installation: The command or its man page might not be installed. Use your package manager (e.g., apt, yum, dnf) to install it, possibly in a -doc package (e.g., coreutils-doc).
• man-db: Ensure the man-db package is installed.
• Keyword Search: Use man -k keyword or apropos keyword.
• Shell Built-in: For built-ins like cd, use help cd or man bash.

7.6 How can I find all man pages related to a topic?

# Search for "backup" related man pages
$ man -k "backup"

Output (example):

tar (1)              - an archiving utility
rsync (1)            - a fast, versatile, remote (and local) file-copying tool
...

For full-text search:

$ man -K "backup"

7.7 Can I read man pages online?

Yes, but the man command on your system is tailored to your installed software versions, making it more accurate for your environment.

7.8 How are man pages created and formatted?

They are written in nroff or groff markup, using macro packages like man or mdoc. man formats these for display.

7.9 What if man output looks strange or uses weird characters?

• Check TERM (e.g., export TERM=xterm).
• Set PAGER to less (e.g., export PAGER=less).
• Rarely, the man page source might have encoding issues.

7.10 How do I update the whatis database used by man -f and man -k?

# Update the whatis database manually
$ sudo mandb

Output (example):

Processing manual pages under /usr/share/man...
Updating index cache...

7.11 Can I get man to output in HTML or PDF?

• HTML:

# Save 'who' man page as HTML
$ man --html who > who.html

• PDF:

# Convert 'who' man page to PDF via PostScript
$ man -t who | ps2pdf - who.pdf

Requires groff and ghostscript.

7.12 What are the “SEE ALSO”, “BUGS”, “AUTHOR” sections in a man page?

• SEE ALSO: Related commands or files.
• BUGS: Known issues or limitations.
• AUTHOR: Credits the creators.

7.13 How can I print a man page?

# Print the 'cut' man page directly
$ man -t cut | lpr

Requires a printer setup.

7.14 How can I save a man page to a text file?

# Save 'cut' man page as plain text
$ man -P cat cut > cut_man.txt

Or:

# Remove control characters for cleaner text
$ man cut | col -b > cut_man.txt

7.15 How can I view man pages for shell built-ins?

# Use 'help' for Bash built-ins like 'echo'
$ help echo

Output:

echo: echo [-neE] [arg ...]
    Write arguments to the standard output.
...

Or:

# Search within 'bash' man page
$ man bash

Then type /echo to find built-in details.

7.16 Why is the man page in the wrong language?

Check your locale (echo $LANG). Use -L to override:

# Force English for 'who'
$ man -L en_US who

7.17 How do I view older versions of man pages?

If older software is installed elsewhere, use -M:

# View man page from an older system path
$ man -M /old_system/usr/share/man ls

8. Conclusion

The man command is your gateway to a wealth of detailed, system-specific documentation directly available on your Linux system. Learning to navigate its sections, use search options like -k, and understand how to specify particular pages (e.g., man 3 printf) will greatly enhance your ability to learn about commands, system calls, and configurations without solely relying on external web searches. It’s a fundamental skill that empowers users to understand and utilize their Linux system more effectively by providing access to the authoritative “manual.” Regular exploration of man pages can reveal hidden features and deepen your mastery of the system.

9. man Command: Reference Table of Key Options

10. Manual Page Sections

Manual pages are organized into sections to categorize different types of information. Knowing the sections helps you find the right page when a name exists in multiple sections (e.g., printf command vs. printf C function).

When you type man NAME, it searches sections in a predefined order (typically 1, n, l, 8, 3, 2, 5, 4, 9, 6, 7, p, o). If NAME exists in multiple sections, the first one found is displayed. To specify a section, use man SECTION NAME.