VMware ESXi and vSphere Cluster Management

Using Linux Manual Pages (man)

Learn how to find, read, search, and navigate Linux manual pages with man, less, apropos, whatis, and section-qualified lookups.

Linux includes local documentation called manual pages, or man pages. A man page is a reference document for a command, program, system call, library function, configuration file, file format, or another system interface.

Manual pages help you discover command syntax, options, arguments, behavior, exit status, related files, and further documentation. You do not need to memorize every Linux command: you can consult the documentation directly from the terminal.

Opening a Known Manual Page

The general form is:

man name

For example, to read about the ls utility:

man ls

This opens the manual page for ls. The man command itself has a manual page, so you can learn about it with:

man man

Manual pages are normally displayed in a pager. A pager is a program that shows text one screen at a time and provides scrolling and searching. The pager commonly used for man pages is less.

Understanding the Structure of a Man Page

Manual pages are organized into named sections. Not every page contains every section, but the following sections are common:

• NAME: the page name and a short summary.
• SYNOPSIS: the command's usage grammar, including options and arguments.
• DESCRIPTION: a fuller explanation of what the command or interface does.
• OPTIONS: available command-line flags and what they control.
• EXAMPLES: sample uses, when the author has included them.
• EXIT STATUS: meanings of return or exit codes, when documented.
• FILES: files used by or related to the command.
• SEE ALSO: related commands, interfaces, and manual pages.
• AUTHORS or COPYRIGHT: attribution and legal information.
• BUGS: known limitations or issues.

Reading NAME and SYNOPSIS

The NAME section gives a quick answer to the question “What is this?” Read it first to check that you opened the relevant page.

The SYNOPSIS section describes the command's syntax. For example, a synopsis might look conceptually like this:

tool [OPTION]... [FILE]...

• Square brackets, such as [OPTION], usually indicate an optional part.
• An ellipsis, written as ..., usually means that an item can be repeated or that multiple items can be supplied.
• A vertical bar, such as one|two, indicates alternatives.
• An uppercase placeholder such as FILE represents a value you provide, such as a filename or path.

These conventions describe syntax rather than literal input. If a synopsis contains FILE, you normally replace it with an actual file name.

Navigating a Man Page with less

When a page is open, use these common less keys:

For example, while reading a page, you can press Space to move down, type /option-name and press Enter to search, press n to find the next match, press g to return to the top, and press q to exit.

man man
/section

The second line is entered while the man man page is displayed. Search text is not a shell command in this context; it is a pager instruction.

Searching for an Unknown Command

Sometimes you know the task but not the command name. A keyword search searches the manual-page index for names and short descriptions.

man -k delete

The same search is available through apropos:

apropos delete

For a task such as deleting or removing a directory, you might search with terms such as delete, remove, or directory:

man -k remove
apropos directory

Do not assume that every result is the correct command or that every matching command is safe. Read the summaries, open promising pages, and check the description, options, arguments, and warnings before running a command.

Understanding Keyword Search Results

Search output generally contains three useful parts:

• A page name, usually the command or interface name.
• A manual section number.
• A short description of the page.

Multiple matches are normal. A keyword may occur in several commands, libraries, system calls, configuration topics, or other documentation. Compare both the short descriptions and the section numbers before selecting a page.

After choosing a result, open it by name:

man selected-name

If the same name exists in more than one manual section, specify the section explicitly, for example:

man 1 name
man 5 name

Manual Page Sections

A manual section is a numbered category that distinguishes types of documentation. The exact contents can vary by operating system, but these standard categories are widely used:

The same name can refer to different pages in different sections. For example, a name might identify a user command in section 1 and a configuration-file format in section 5. Use man 1 name or man 5 name to select the intended page.

Other Lookup and Discovery Features

The SEE ALSO section is especially useful after you understand one command. It lists related commands and interfaces that can help you expand your search or compare alternatives.

When a Manual Page Is Missing

A command can exist even when its manual page is not installed. “No manual entry” does not necessarily mean “unknown command.” The command may be a shell builtin, may have been installed without its documentation package, or may use another documentation system.

For example, cd is commonly provided by the shell rather than as an external executable. If a man page is unavailable, try:

command -v name
name --help
help name

Replace name with the command you are investigating. The first command checks whether the shell can find it. The other commands try program-specific or shell-builtin help as appropriate.

Local documentation varies with the installed packages and Linux distribution. Keyword searches depend on an index, and some systems may not have the index generated or may need indexing support installed. If man -k returns no results or reports an unavailable database, install the appropriate man-page support and rebuild the index with the distribution's supported maintenance command, commonly:

mandb

Troubleshooting Common Problems

You do not know the command name

Search descriptive terms, inspect the result summaries, and then read candidate pages:

man -k remove
apropos directory

Several results may be relevant, so verify the command's purpose and safety before using it.

No manual entry is found

Check for a spelling mistake. Then determine whether the command exists, whether it is a shell builtin, and whether its documentation package is installed:

command -v name
name --help
help name

If the command exists but documentation is missing, install the relevant package documentation according to your distribution.

The search database is unavailable

The keyword index may not have been generated or may be outdated. Install the required indexing support and run the system's supported database maintenance command, often mandb.

The wrong page is displayed

The name may exist in several manual sections. Select one explicitly or inspect every match:

man 1 name
man 5 name
man -a name

You cannot exit the documentation screen

The page is probably open in the less pager. Press q to return to the shell prompt.

An in-page search does not work

While the page is displayed, type a slash, the search text, and Enter. Use n for the next match and N for the previous match:

/pattern
n
N

A Practical Man-Page Workflow

1. Identify the command if you already know its name, then run man name.
2. Read the NAME section to confirm that the page matches your task.
3. Read the SYNOPSIS to understand the required arguments and optional parts.
4. Review the DESCRIPTION and relevant OPTIONS.
5. Search within the page for a particular option, argument, file, or example.
6. Check EXIT STATUS, warnings, and related sections when the task has consequences.
7. Use SEE ALSO or man -k to discover related documentation.
8. Exit with q and only then run the command you have understood.

For further study, see Linux manual pages and practice by opening a known command, searching inside it, and using a keyword search to discover an unfamiliar command.