Making the Most of man pages in Linux
Though extremely useful, man pages in Linux can be daunting and intimidating at first. This article aims to make it a bit easier to peruse manuals and quickly get the help one needs.
In the *nix world, the manual pages, aka man pages, are considered the absolute reference for advanced users. There is also the occasional pedantry of RTFM rudely insisting its importance. The man command is even part of the POSIX specification – the basis for most modern implementations of *nix systems. So is this notion justifiable after all?
Advantages of manual pages
- Do not require an internet connection
- Written by the developers/maintainers enabling extensive information and accuracy
- Are self-contained without needing external resources
- Always apply to the installed version of the app and the current distribution
However, even if they may be useful, man pages are daunting at first. This article aims to make it a bit easier to peruse manuals and quickly get the help you need.
What are manual pages?
Born in the days of Unix, man – short for manual – pages were the primary source of user documentation. They were written by the developers of the software and shipped with it.
Today, in Linux distributions, when one installs a package through the package manager – apt, dnf, pacman, or others, the manuals are installed to the /usr/share/man directory.
Picking one of those files and using cat to view it… has unintended effects
$ cat /usr/share/man/man1/man.1.gz
�[ks�F���_�Ś�IS$m�Ig&��2��b=V��I�6%�
@�F����߾�>��$e�nmR�C��}��}{n�`�3M2Ŀ�
���X�Ϋ;k�����Tm�0˪άi�i*3�f]�u]eֹ��{��
YZ�uzm�q�JK��7N��C�_�4�����|�U����
... # truncated output
It must be because the file is compressed. Let's try zcat
$ zcat /usr/share/man/man1/man.1.gz
'\" t
.\" ** The above line should force tbl to be a preprocessor **
.\" Man page for man
.\"
.\" Copyright (C) 1994, 1995, Graeme W. Wilford. (Wilf.)
.\" Copyright (C) 2001-2019 Colin Watson.
.\"
.\" You may distribute under the terms of the GNU General Public
... # truncated output
Okay, that gives text. But it's still filled with weird syntaxes; also so long that it fills up the entire terminal.
Let's move from adventuring and view the man page as intended—with the man command.
$ man man
When a man page is accessed using the man command, it still fills the terminal window. But now it's easier to read. Additionally, there is a lot of formatting: headings, bold text, italic text or underlined text.
How are man pages are rendered?
Man pages are markup files written using a descendant of the roff syntax such as groff from the GNU Project. The syntax is a typesetting system that establishes the structure and formatting of the manual pages. This is similar to semantic HTML for webpages.
man finds the raw roff file in the filesystem and processes it to generate output suited for the current terminal. The processing involves setting the page width, text encoding, font weights and styles according to terminal support. The output is then displayed using a pager.
The man command in Linux is part of the man-db suite of packages. There are packages in the collection to handle the various processes and also maintain an index of the installed manuals.
In most BSD systems, the mandoc project project is used instead. And it differs from man-db in various aspects. The rest of the article will focus only on man-db and its features and options.
The man program
As established earlier, to access a manual page, we use the man command. The simplest invocation of the command is man followed by the name of the page you want to access. So to access the manual for ssh
$ man ssh
The elements of the man-db suite maintain a shared database of all manual pages that are installed on the system. This database, most likely located at /var/cache/man/index.db, acts as a cached index of manual pages. It also provides the information needed by other the other tools in man-db. If there is no page in the index with the name ssh, the man command searches through a list of directories defined in /etc/manpath.config or by the environment variable $MANPATH.
Navigation
Navigation in a man page is handled entirely by the pager that is being used. By default, man uses the pager command. And in most modern Linux systems pager is a symbolic link to less.
To close the manual at any time, simply press q on your keyboard. This quits the pager and returns to the shell.
Scrolling
In most pagers, including less it is very easy to scroll through the page using the scroll wheel, scroll gestures and also arrow keys. Home and End are also supported.
Users familiar with Vim can also use the standard keybindings for motions to navigate through the pager. Holding down the j key scrolls down and k scrolls up one line at a time. g and G can be used for the beginning and end of the page respectively.
It is also possible to scroll more at a time using the keyboard, but it often makes reading difficult. But if you wish, you can press the h key to bring up less's help screen for all the keybindings.
Being comfortable with scrolling is the first step to using documentation to find information. But even so it would not be easy going through it line by line. That is where the pager's search functionality comes into play.
Searching
The quickest way to find a particular feature or option in a man page is to search for the word. To initiate a search in the manual press the (forward slash)/ key, type the pattern (regular expressions are supported!) and press Enter
This is useful when you are looking for an approximate "topic." For example, you could open the manual page for rsync and search for the word partial to quickly jump to the first occurrence of the word. You can then press the n key to move to the next instance or N (shift + n) to go back to the previous one. Using ? you can also search backward.
By default, the case (upper or lower) of the pattern is ignored. But if there is an uppercase letter, the pattern is treated with case sensitivity. This behavior makes it impossible to search for a fully lowercase pattern. And so it is sometimes useful to enable case-sensitive searches. This can be done by pressing the hyphen-i sequence - i to toggle the feature.
Cycling through the instances of the search pattern and scrolling up and down around them is a neat way to get information on a particular topic.
Another good use of the search function is with flags. Performing a search for the pattern that begins the line with spaces and a pattern is useful to jump to the flag.
/^\s+--compress
This would also be useful when auditing commands from the internet before running them. Jumping to the flag and verifying what it does. Search can also be used to quickly scroll down to a particular section of the man page.
Sections of a man page
The manuals are typically divided into multiple sections indicated by the headings displayed in BOLD UPPERCASE text. There is a list of sections that are found in most pages. But the common and important ones are name, synopsis, environment and files.
NAME
This section has the name of the application (or manual topic) and a short description. A summary of sorts.
SYNOPSIS
The synopsis section is a quick start guide. For applications, it is a description of the command line syntax.
It is useful to know the conventions used in the synopsis section that illustrates how the command may be used.
command [--optional-flag] [-a -b] [ -c argument ] [-A|-B] filename ...
- The first word is the name of the command
- Arguments that are surrounded by
[ ]are optional - Flags or options with
|between them cannot be used together - Arguments followed by
...can repeated - Arguments without
[ ]are required
With the sample above, command /etc/passwd and command /etc/passwd /etc/group are the simplest valid invocations having all the required elements.
All the flags listed are optional, but -A cannot be used with -B. Only one of the two may be used.
Also note that -c argument means that argument is required if the -c flag is used. And only one argument may be passed to -c.
ENVIRONMENT
Environment variables are useful for controlling the behaviour of an application. The environment section of a man page lists the variables that affect a given command and also their effect. The variables that are set by the software for use by other apps are also listed.
You can read more about using environment variables in our guide on the export command
FILES
The files section of a man page lists and describes paths in the filesystem that are relevant to the software. The paths are typically those of configuration files. The manual page for bash lists the initialization files that are parsed by the shell.
^ENV or ^SYN to quickly scroll to sections without typing the full word!man sections
The sections within a manual are not to be confused with the different sections of man pages.
Essentially all the manuals available on a system are categorized under sections numbered 1 through 8. And are installed to their respective folders, man1 - man8. As you can see in the screenshot below, the ls command is in section 1.
Sometimes a few additional sections also exist. The best description of each section is in the man page for man itself.
| Section | Name | Description |
|---|---|---|
| 1 | Executable programs or shell commands | general commands. e.g. cat, man, ssh, cp |
| 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, e.g. man(7), groff(7) |
| 8 | System administration commands | usually only for root |
In most cases, it would not be necessary to specify the section. man automatically goes through all the sections in a predefined order. But it is possible to specify the section.
man 5 ssh_config
man rsync.1
man "passwd(5)"
All the above are valid syntaxes of the command. And the last one – passwd(5) refers to the man page for /etc/passwd. On the other hand, passwd(1) would to the application to change a user's password. In cases like these, it is useful to specify the section.
Often manuals direct the user to refer other related manuals. These references are written in the name(section number) format and can be easily copied and pasted into a terminal. But need to be wraped in quotes to prevent the shell from interpreting them.
Using man command with additional options
While the simplest invocation of man is man name, it is also possible to use flags to get different results.
The -f flag for short descriptions
man -f name is an alias to whatis name, another command available as part of the man-db suite. The whatis command prints the short description from the manual page's NAME section. The descriptions are extracted and cached in the database that is shared by all man-db utilities.
$ man -f whatis
whatis (1) - display one-line manual page descriptions
$ whatis whatis
whatis (1) - display one-line manual page descriptions
The -k flag to search topics
Similarly, man -k name is an alias to apropos name. The command searches for name in the man-db database of descriptions and prints those that have a match. As it searches name and description of each manual, this flag would be useful to find all manuals on a topic.
$ man -k apropos
apropos (1) - search the manual page names and descriptions
$ apropos apropos
apropos (1) - search the manual page names and descriptions
$ man -k password
chage (1) - change user password expiry information
chgpasswd (8) - update group passwords in batch mode
chpasswd (8) - update passwords in batch mode
... #truncated
View with --html
$ man --html
The --html flag can be used to generate html output! man will even open the browser and display the html version of the manual. Note that this depends on the $BROWSER environment variable being valid.
There are other CLI options that are listed in man(1) and they can be viewed using the command man man. 😉
Alternative documentation
Despite its utility, man is not always the answer. Sometimes grepping the help prompt for a term is all one needs.
$ command --help | grep -i 'term'
Most programs have a help prompt accessible using the --help flag. However, man remains the best way to get in-depth information.
But man is not the only answer. There have been various competing standards for software documentation. GNU's texinfo, web-only documentation that is published on websites or on GitHub are not uncommon.
Despite it all man has stood the tests of time and persists today. Its flexibility and availability play a large role. The depth of information has an equally big role. Hopefully, this article has guided you to embrace it. And next time, maybe you too will reach for the man pages before a search engine.
This article has been contributed by Kevin Samuel.
LHB Community is made of readers like you who share their expertise by writing helpful tutorials. Contact us if you would like to contribute.