How to Use the man command in Linux

This tutorial explains what the manual pages are and how the man command categorizes them in sections. Learn man command syntax and options through practical examples.

What are the man or manual pages?

When we install a package, the package automatically installs pages that provide a detailed description of the contents and functionalities of that package.

For example, if a package provides a command, the pages of the package explain how to use the command. Or if a package provides a service, the pages of the package describe what configuration files the service uses and how to configure them.

You can use these pages as an authoritative resource to get information about a command's functions and options, directives of a configuration file, installation paths, etc. You can also find how-to-use examples in these pages. In short, these pages contain all the information that you need when you use their respective programs.

Almost all software packages/commands/services install their respective pages. Depending on the installed packages, the number of pages can be in thousands. Typically, to save disk space, packages compress their pages before installing them.

You may think, due to the number of pages and the format in which they are stored, obtaining the necessary information from these pages might be a difficult task. Yes, that's true if you have to search the required information in these pages on our own.

But fortunately, you never have to access these pages directly when you need some information form these pages. Linux offers two commands that can search any information from these pages. These commands are the man command and the info command.

Technically, packages prepare their pages for one of these commands. If a package prepares and installs its pages for the man command, the pages are known as the manual pages. Or if the package prepares and installs its pages for the info command, the pages are known as the text-info pages.

In this tutorial, we will understand how to access and use the manual pages. We will understand the text-info pages in the next part of this article.

How are manual pages organized?

A manual page usually consists of the following sections: name, synopsis, configuration, description, options, exit status, return value, errors, environment, files, versions, conforming to, notes, bugs, example, authors, and see also.

The man command groups similar types of manual pages and assigns a unique value to each group. These groups are known as sections.

Sections of manual pages allow us to limit the results or the output of the man command. By specifying the section number, we can instruct the man command to find the specified keyword only in particular types of manual pages.

For example, if you are looking for a command or a configuration file, you can instruct the man command to search the specified keyword only in man pages that provide information about that command or about that configuration file, respectively.

The following table lists the most common and relevant sections of manual pages.

Although both terms: sections of a manual page and sections of manual pages sound similar, but both terms refer to different things. Sections of a manual page refer to the information available into a single manual page while sections of manual pages refer to a scheme that the man command uses to categorize all available manual pages on the system.

The following image shows the difference between both terms.

The man command syntax and options

The man command uses the following syntax.

$man [option] [section] keyword

The following table lists some common options of the man command.

Using the man command

By default, the man command searches the specified keyword only in the title of man pages. So if you know the name of the command or configuration file, you can search its manual page by specifying its name as an argument to the man command.

For example, the following command searches and displays the man page of the chgrp command.

The following command searches and displays the man page of the yum.conf configuration file.

What if multiple manual pages of the same title exist?

Without any options, the man command searches the specified keyword in the title of manual pages of all sections in ascending order until a match is found.

Once a match is found, the man command stops the search process and displays the manual page whose title matches the specified keyword.

Since the sections are searched in ascending order, if the specified keyword matches several man pages of different sections, the man page of the first-matched section will be displayed.

Let's understand it through a simple example. In Linux, we have a command and a configuration file named passwd.

The passwd command is used to manage a password from the command line.

The passwd configuration is used to store local users' passwords and other related information.

Both the passwd command and the passwd configuration file install their separate man pages. The man command assigns the section 1 and 5 to the man page of the passwd command and to the man page of the passwd configuration file, respectively.

If you specify the keyword passwd to the man command without any option as shown in the following image, the man command will always return the man page of the passwd command because it is available in section 1 and the section 1 is always searched before the section 5 where the man page of the passwd configuration file is located.

You can override the default behavior by specifying the section number. If the section number is specified, the man command searches the specified keyword only in the specified section. For example, to view the man page of the passwd configuration file, you can use the following command.

#man 5 passwd

In this command, since we have specified the section number, the man command will only search for the keyword 'passwd' in the title of the man pages arranged in section 5. The following image shows the sample output of this command.

What if I don't know the name of the command or configuration file?

If you don't know the name of the command or configuration file, you can search a keyword that describes your requirement in the short description section of manual pages.

For example, if you want to create a new user account but don't know which command is used to add a new user, in this case, you can search the keyword 'user' in the short description section of manual pages.

To search the string in the short description section of manual pages, use the option -k.

The following command prints the title and short description of all manual pages that have the keyword 'user' in their short description section.

Depending on the uniqueness of the specified keyword, you may get a lot of results. If that happens, you can search for a text string instead of a keyword.

To find a text string, put the string in quotes. For example, you can search a text string 'create a new user' instead of the keyword 'user'.

#man -k 'create a new user'.

The following image shows the sample output of the above command.

Caching of manual pages

To search the required information faster, the man command uses the index database caches. These caches contain information such as where each manual page can be found on the file-system and what it contains.

The man command also maintains a cache of formatted pages in the directory /var/cache/man or /usr/share/man. When we search a man page, the man command, instead of performing a full search, search the specified man page in the cache directory.

If a cached version of the requested man page is available, the man command immediately displays the cached version of the requested man page. If the cached version of the requested man page is not available, the man command performs a full search of the requested man page at the available locations in the index database.

Since the man command searches the specified keyword within the database cache, if a package has been installed recently, the man command will not be able to display the manual pages of this package until their location is added to the index database.

By default, the Linux automatically updates the index database on the specified time in the cron file. But if required, such as in the exam, you can also update this database manually. To update the index database manually, use the following command.

#mandb

The following image shows the sample output of this command.

That's all for this tutorial. If you like this tutorial, please don't forget to share it with friends through your favorite social network.