How to Read a Man page, Part 1

Experience Level: Beginner and up

Prerequisites: Curiosity and knowing how to type a command in LXTerminal.

Follow this tutorial with: “How to Read a Man page, Part 2” and “How to Read an Info page”

Linux distributions follow the Unix tradition of including self-help documentation in their operating system. These documents fall into two different yet similar categories: man pages and info pages.

Man (short for manual) pages are the original form of Unix assistance. Two decades before the appearance of Linux itself, man pages were an evolutionary step in help documents.

Info pages are the GNU Project's interpretation of man pages. The tutorial “How to Read an Info page” goes into the details of using info.

The first lesson in learning how to navigate man pages is that context rules. Over the course of using Bodhi or any other Linux distribution, at some time you will access the same man page for different reasons. The exception is if you never use them but count only on the kindness of strangers to solve your problems.

man pages were originally written for programmers by programmers. Among average users, they have the reputation of being “densely” written because people often mistake a man page as informal reading. Once you view a man page as a tool more like a dictionary or encyclopedia, man pages become easier to understand.

man pages follow a template, making it easier to find relevant information once you become familiar with the sections of a man page. But first, you have to know how to access one.

You access a man page by typing at the LXTerminal prompt $ man {name} For example, man less displays the manual page for the command less. man adduser displays the manual page for the command adduser.

A man page is always longer than the terminal window itself. To see beyond the last line of the terminal window, you can press the Enter key once to have the next line come into view or press Enter several times to display several new lines at once.

The same number of lines at the top of the terminal window scroll out of view. You can use the terminal's scroll bar to look at those lines again. What the scroll bar will not do is continue the page beyond the bottom line of the terminal window.

You can also press the spacebar to view the next block of lines to replace the current block of lines. As with the Enter key, you can use the scroll bar to look at the previous block of text.

This method is recommended since a single man page can span the length of as little as 66 lines for man printf to over a thousand lines for many other man pages.

A man page is divided into a number of common sections. Some pages do not require every section, but they appear in the following order:
NAME
SYNOPSIS
CONFIGURATION
DESCRIPTION
OPTIONS
EXIT STATUS
RETURN VALUE
ERRORS
ENVIRONMENT
FILES
VERSIONS
CONFORMING TO
NOTES
BUGS
EXAMPLE
AUTHORS
SEE ALSO

There are optional sub-categories for several sections, but these are always context-dependent. This tutorial is not qualifing every variation on a theme for reasons of length.

The sections to look at first are NAME, DESCRIPTION, OPTIONS, FILES and SEE ALSO. Other than perhaps EXAMPLE, most of the remaining sections are concerned with any error that may occur from using the command and its options or using its options incorrectly.

Let's look at the man page for adduser as an example.

$ man adduser

The very first line has the program name, ADDUSER and an (8) in parentheses. The (8) refers to the category and man page directory number where the adduser command can be found.

It is not necessary to append the (8) to any man page search, but some commands and utilities do have an entry in more than one category. This is the way in which that piece of information is presented to you. We will cover the use of the man page directory number (there are 9 man page directories) near the end of the tutorial.

The man pages have 9 sections, divided into the following categories. Each individual man directory is transparent to you as a user when you simply use man {page name}.

1 Executable programs or shell commands
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 eg /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)
9 Kernel routines [Non standard]

adduser belongs to section 8, which is for System Administration Commands. You can also see that the commands in section 8 are usually for the root user, who is commonly referred to as the system administrator.

Bodhi Linux, being based on Ubuntu, does not enable a root user by default. Instead, the users on the computer use the command sudo, which enables any user who is in the /etc/sudoers file to be able to take on the role of system administrator temporarily.

(The intricacies of using sudo are in the tutorial “Beyond Bash Basics.” The basics of using sudo are in the tutorial “Using the LXTerminal and Bash, Part 1”)

Now that you know how man pages are categorized, we pause here so you can see how to find the “9 section” reference quoted above. After all, it also came from a man page. But which one?

To quote Kahn Noonian Singh in Star Trek II: The Wrath of Kahn, “Don't insult my intelligence…”

The listing for the 9 sections came from the beginning of the man page: man man. That the manual pages would have a manual page about the manual pages is not only appropriate, but another essential clue in the way unixy-thinking works…and the man pages are classical unixy-thinking.

Type at the command prompt man man and look at the man page for a moment. It isn't requisite to read the page in its entirety. That's why we're dissecting the man page sections.

If you've been wondering, “But how do I know what man pages exist?” this part is for you.

There's the classical way, which uses the command apropos. It searches man pages and their descriptions based on typing a keyword after apropos when you aren't sure which man page to look for.

As a user new to Linux and man pages, one flaw exists: apropos returns a lot of information. Being new to man pages, it is overwhelming to see a result on your terminal 1,000 possibilities for a single query.

So we will delay walking through using apropos and go directly to the “lazy” way of finding information. “Lazy” not as a perjorative but rather as a synonym for “clever.” Again, it is a classical unixy way of interpreting the word. To be considered “lazy” is a badge of honor.

With the terminal if you use the command whereis and append man to it like so:

whereis man

You are given several places where man exists:

/usr/bin/man
/usr/local/man
/usr/share/man
/usr/share/man/man7.man.7.gz
/usr/share/man/man1/man.1.gz

This may appear overwhelming but it is far less information than what apropos returns. For apropos man you are presented with 1,616 entries.

5 possible places to search are far more convenient than 1,616.

Do this yourself. Type apropos man and view the result. Then type whereis man and view that result.

(For the curious wondering how to discover there are 1,616 entries in the result of apropos man without counting them manually, I refer you to the final paragraph of “Practical Exercise #3: Using a Pipe” in the tutorial “Explaining the LXTerminal and Bash.”)

In looking at the places to search for man, we can narrow the search down quickly. “bin” files are binary files, so we won't look there. It seems that two entries are too specific, namely: /usr/share/man/man7.man.7.gz and /usr/share/man/man1/man.1.gz so we won't look there.

This leaves us with /usr/local/man and /usr/share/man.

At the command prompt, cd /usr/local/man Then type in the command ls

The terminal reports that the man directory is empty.

This leaves your decision to choosing /usr/share/man

(As is often the case with Unix-like systems, this is not the end of the story for /usr/local/man but only the beginning. The complete story is revealed in “Using the LXTerminal and Bash, Part 2.”)

Now with the decision made to investigate /usr/share/man, all that remains is to cd into the directory from which you are at in the terminal prompt.

Now at the prompt, type: ls

Of the 26 entries, 9 are man directories, numbered man1 through man9. Only because of the section of this tutorial titled “The Parts of a Man page” do you know that these directories represent: Executable programs or shell commands, System calls, Library calls, Special files, File formats, Games, Miscellaneous, System administration commands and Kernel routines.

We remain with the question “But how do I know what man pages exist?” At this point we know how to access man pages, have discovered where man pages exist, but are still unaware of their names. We want to learn how to read a man page effectively so we can use the commands built into our Linux distributions, whether it's Bodhi or Debian or Fedora or openSuSE or…well, you get the point.

Otherwise, all of the effort spent on creating this documentation is wasted on us.

At the terminal prompt type: cd man1

Type: ls | less

Displayed in the terminal is the first screen of file names in man1. Notice on the last line the character :

By pressing the Enter key once, you achieve the same effect as you did in “Viewing man pages, Part 1.” Likewise, using the spacebar keeps its use as well by scrolling up the next block of text.

The structure of these man files is: {filename} {man section number} {compressed-with-gz}, as in: alsamixer.1.gz

“But how do I read a compressed file?” you ask.

The answer is that you don't read it directly by uncompressing the gzipped file and reading it in the terminal or with Leafpad, but through the man utility.

To read the alsamixer.1.gz file, simply enter at the command prompt: man alsamixer

On the first line you see that the page is about ALSAMIXER(1).

On the second line, NAME you read: alsamixer - soundcard mixer for ALSA soundcard driver, with ncurses interface

If you press the spacebar a few times, you quickly come to the end of the file. One of the last sections of the man page is SEE ALSO where there are cross-references to the man pages for amixer, aplay and arecord.

You may have some need to reference those pages now or not, but in man pages, every page leads somewhere. Simply because a page may not be relevant at the moment doesn't mean it may not become relevant someday.

Another thing is that unlike many operating systems, Linux is very straightforward about the possibility of bugs. (There are many different types of bugs – some important and others impossibly minor – and that is the subject of the tutorial “The Importance of Bugs.”)

Near the end of a man page is a section titled BUGS. Some man pages will not have any bugs to report while others will. In the case of alsamixer, the BUG report reads in its entirety as follows:

“Some terminal emulators (e.g. nxterm) may not work quite right with ncurses, but that's their own damn fault. Plain old xterm seems to be fine.”

You won't see that kind of straightforward talk in official documentation meant for public consumption in many other operating systems.

Not only that, but credit for a command or a system call or a file format is given its proper due in the section AUTHOR as well as the person responsible for the man page itself and the date it was written.

You may now continue to “How to Read a Man page, Part 2” immediately. There has been a lot of information given to you all at once. But there is one additional tip which you should know in order to effectively navigate through the man pages with the knowledge you do have.

The man page section number given after each page's name represents not only where the page can be found, but where it can be found in multiple man pages.

While it appears redundant, it isn't because a man page for man{foo}(1) is not identical to an exactly named man page in man{foo}(5) because the man1 pages are about shell commands while the man5 pages are about file formats.

For example, typing man tar will bring up the TAR(1) page. Under NAME it says, “The GNU version of the tar archiving utility.”

Paging to the end of the file with the spacebar reveals under SEE ALSO that there is a tar(5) man page.

At the command prompt, if you type man tar(5) you will be greeted with the message:
bash: syntax error near unexpected token `('

which means something was typed incorrectly.

The structure to accessing a man page in a specific man directory is the number of the man directory preceeding the page's name.

To access tar(5) you type: man 5 tar and discover that under NAME it says, tar - format of tape archive files

If you only read the DESCRIPTION of tar(1) and tar(5), you will begin to understand the reason for the separation of man pages into multiple directories.

“How to Read a Man page, Part 2” is a shorter tutorial than “How to Read a Man page, Part 1.”

If you would like to comment or make further suggestions, please leave a note on our Comments page (you will have to Create an Account if you haven't already).