Linux online course

Using Linux Manual Pages with man

Learn how to use man and less to read Linux documentation, understand manual-page sections, search by keyword, and verify command syntax safely.

Linux includes built-in reference documentation for commands, utilities, system calls, configuration files, and other system components. These documents are called manual pages, or man pages.

A manual page is useful when you know what you want to do but cannot remember a command's syntax, available options, or the correct tool for the task. The man command is the standard interface for locating and displaying this documentation.

This lesson assumes that you can open a terminal, run shell commands, and recognize the difference between a command, an option, and an argument. For related shell fundamentals, see Bourne Again Shell Bash.

Opening a manual page

The basic pattern is:

man item

Replace item with the command or component whose documentation you want to read. For example:

man ls

This opens the manual page for ls, the command commonly used to list directory contents. The page normally includes the command's purpose, invocation format, options, and related reference details.

Manual pages are displayed interactively rather than printed all at once. The program commonly used to display them is less. A pager is a program that lets you read text one screen at a time, move through it, and search it.

Reading a page with less

When man ls opens, you are inside the less pager. The pager accepts single-key controls. These controls do not usually require you to press Enter.

Open a manual page — man ls — Display the documentation for ls.

Search manual-page names and summaries — man -k delete — Search the manual-page database for a keyword.

Move forward one screen — Space — Show the next screen of text.

Move backward one screen — b — Show the previous screen.

Search within the current page — /pattern — Type a search pattern after the slash and press Enter.

Repeat an in-page search — n — Move to the next match for the current search.

Quit the viewer — q — Leave less and return to the shell.

For example, after opening a page, type /option and press Enter to find occurrences of the word “option.” Press n to continue to the next match. You can search for a command name, an option, or a section heading such as EXAMPLES.

Use g to move to the beginning of a page and G to move to its end. These are common less controls when you want to inspect the introduction or jump to the final sections.

Common manual-page sections

NAME — The item's name and a concise statement of its purpose.

SYNOPSIS — The command's invocation syntax and argument structure.

DESCRIPTION — A fuller explanation of what the command or component does.

OPTIONS — Flags and modifiers that change the command's behavior.

EXAMPLES — Demonstrations of common usage, when provided.

EXIT STATUS — Values or meanings that describe how the command reports success or failure.

FILES — Files used by or related to the command, when relevant.

SEE ALSO — Related commands and manual pages.

AUTHORS or COPYRIGHT — Attribution, licensing, or copyright information, when included.

Understanding SYNOPSIS notation

The SYNOPSIS section is a compact description of how to invoke a command. It is a syntax guide, not always a command that can be copied without adjustment.

  • Text in square brackets, such as [OPTION], is usually optional.
  • Uppercase words such as FILE, DIRECTORY, or USER are placeholders. Replace them with an actual value.
  • A vertical bar, such as one | two, commonly indicates alternatives. Choose one of the alternatives.
  • An ellipsis or notation indicating repetition means that more than one argument may be supplied, depending on the command.
  • Literal lowercase command text and option forms show the parts you normally type, while placeholders show values you must provide.

For instance, a synopsis resembling tool [-a] FILE... indicates that -a is optional, at least one file may be expected, and the file argument can potentially be repeated. Read the accompanying DESCRIPTION and OPTIONS sections to confirm the exact behavior.

Searching for a command by keyword

Sometimes the task is clear but the command name is not. The -k option performs a keyword search:

man -k keyword

For example, to investigate commands related to deleting something, run:

man -k delete

This searches the manual-page database: an indexed collection of manual-page names and their short descriptions. It does not search the complete text of every manual page.

The output may contain several commands and manual-page entries. A result might concern deleting files, removing directories, deleting lines, or another related operation. Compare each command name with its short summary, then open promising candidates individually:

man command-name

For a directory-removal task, do not select a command based only on the word “delete.” Read the candidate page to verify its syntax, options, and safety implications before running it. A keyword search often suggests possibilities rather than identifying one exact solution.

apropos is a commonly available command with the same general purpose:

apropos delete

Use alternative keywords if the first search is too narrow. For file and directory topics, terms such as “remove,” “directory,” or “file” may produce different useful results.

Getting help about man itself

The manual-page tool documents itself:

man man

This page explains additional ways to select, format, and search manual pages. It also demonstrates an important command-line principle: tools often provide documentation for the tools used to access them.

Using search results safely and effectively

  1. Describe the task in a few keywords.
  2. Run man -k or apropos with one of those keywords.
  3. Compare the names and short summaries in the results.
  4. Open each plausible result with man.
  5. Read NAME, SYNOPSIS, DESCRIPTION, and OPTIONS.
  6. Look for EXAMPLES, warnings, affected files, and related entries in SEE ALSO.
  7. Confirm every placeholder and option before executing the command.

Pay particular attention to options that modify, overwrite, remove, or recursively process data. The manual page explains what an option does, but it cannot know whether a particular path or argument is safe in your situation.

Troubleshooting

The task is known, but the command name is unknown

Use task-related keywords with man -k. Review the summaries, then inspect likely entries with man. Try synonyms if the first search does not identify a useful result.

The page is long and an option is hard to find

Do not read only from top to bottom. Use /option-name, /OPTIONS, or another relevant search term inside less. Press n to move through matches.

man -k returns no matches or incomplete results

The keyword may be too specific, or the local manual-page search index may be unavailable or stale. Try related keywords and apropos. If the index remains unusable, consult the system's documentation-maintenance process for rebuilding it or use another installed documentation tool.

A manual page is missing

The command or its documentation package may not be installed. First confirm that the command exists. If it does not, install the appropriate software or documentation package using your distribution's package manager. Some GNU programs also provide documentation in the separate info format, which complements rather than replaces manual pages.

You cannot leave the displayed page

The page is probably open in less. Press q to quit and return to the shell.

Related command-line habits

Your shell's command-line history records previously entered commands. It can help you reuse or edit an earlier query such as man -k delete. See Bash for shell concepts.

Manual pages are one source of help. A command may also support a form such as command --help, and some GNU software uses info. When you need to identify an installed executable before reading its documentation, see Show the Full Path Of Shell Commands. For filesystem-related commands, File Structure In Linux provides useful background.