RTFM! How to Read (and Understand) the Fantastic Man Pages in Linux
The man pages, short for reference manual pages, are your keys to Linux. Everything you want to know is there – take it all in an run with it. The collection of documents will never win a Pulitzer prize, but the set is quite accurate and complete. The man pages are the primary source and that authority is well-known.
While they are the “go to” source, they aren’t the most pleasant to read. Once, in a long past philosophy class, I was told that reading Aristotle was the most boring read around. I disagreed: when it comes to dry reading, Aristotle comes in at a distant second to man pages.
At first glance, the pages may look incomplete but, believe it or not, the man pages aren’t designed to hide information from you – it’s just that there is so much information that the pages have to be structured and information is given in the most brief form possible. The explanations are rather spartan and they will take some getting used to, but once you get the hang of using them, you’ll see how useful they actually are.
Getting Started with the man Pages in Linux
The pages are viewed through a utility called,
man, and the command to use it is rather easy. In the simplest form, to use
man, you type
man on the command line, followed by a
space and the command that you want to look up, such as
cp, like so:
man opens the manual page of the
You can move up and down with the arrow keys and press
q to quit viewing the man page. Usually, the man pages are opened with less so the keyboard shortcuts for less command work in man as well.
For example, you can search for a specific text using /search_term and so on.
There is an introduction to the man pages and it’s important that you read this one. It spells out, in great detail, how the man pages are laid out and organized.
To see this page, open a terminal and type:
Before you begin to look at man pages much deeper, it will be helpful to know that man pages have a set page layout and a filing scheme. This can be confusing to a newcomer since I can say: “Look at the NAME section of the man page for
ls.” I can also say, “Look at the man page for
passwd in section 5.”
I italicized the word, section to try to show a source of confusion. The word, section is being used in two different ways, but the difference isn’t always explained to newcomers.
I am not sure why this confusion sets in, but I have seen it happen a few times back when I trained new users and entry-level sysadmins. I think it might be tunnel vision. Focusing on one thing can make a person forget about another. It’s a lot like not being able to see the forest because the trees are in the way.
To those who know the difference already, you can skip this sub-section. This part is directed to the people new to man pages.
Here is the difference:
The man page
Individual man pages are made to show blocks of information. For example, every man page has a NAME section to show the name of the command along with a brief description. There will be another block of information, called SYNOPSIS to show how the command is used, and so on.
Every man page will have these, and other headings. These sections, or headings, on individual man pages, helps keep things consistent and information compartmentalized.
The use of section, as in “Look at the man page for
passwd in section 5” speaks of the manual as a whole. When we look at only one page, it can be easy to overlook that, but the man page for
passwd is part of the same manual that has a man page for
cal, and others.
The entire Linux manual is huge; it has thousands of pages. Some of those pages have specialized information. Some pages have information that programmers need, while others have information unique to networking, and others that system administrators would be interested in.
These pages are grouped according to their unique purpose. Think of splitting the entire manual into several chapters – each chapter having a specific topic. There are 9 or so chapters (very large ones at that). It just so happens that these chapters are called sections.
To sum this up:
- Sections of a single page of the manual (what we call the man page) are blocks of information defined by the headings and
- Sections of the manual-at-large (the collection of all of the pages) are chapters which happen to be called sections.
Now you know the difference and, hopefully, the rest of this article will be easier to follow.
man Page Sections
You will be looking at different man pages so let’s study the individual page layout first.
Manual pages are split into several headings and they may vary from vendor to vendor, but they will be similar. The general breakdown is as follows:
- SEE ALSO
- HISTORY WARNING (or Bugs)
NAME – Under this heading is the command name and a brief description of the command.
SYNOPSIS – Shows how the command is used. For instance, here is a synopsis of the
cal [Month] [Year]
The synopsis begins with the name of the command, with a list of options following. The synopsis takes the general form of a command line; it shows what you can type and the order of the arguments. Arguments in square brackets (
) are optional; you can leave these arguments out and the command will still work correctly. Items not in brackets must be used.
Take note that brackets are for readability only. They should not be typed when you enter a command.
DESCRIPTION – Describes the command or utility as to what it does and how you can use it. This section usually starts off with an explanation of the synopsis as well as telling what happens if you omit any of the optional arguments. This section may be subdivided for long or complex commands.
EXAMPLES – Some man pages provide examples of how the command or utility can be used. If this section is present, the page tries to give a few simple usage examples, as well as more complex examples to show how complex tasks can be completed.
DIAGNOSTICS – This section lists status or error messages returned by the command or utility. Self-explanatory error and status messages aren’t usually shown. Messages that may be hard to understand are usually listed.
FILES This section contains a list of supplementary files used by UNIX to run this specific command. Here, supplementary files are files not specified on the command line. For example, if you were looking at a man page for the
passwd command, you may find
/etc/passwd listed in this section since that is where UNIX stores password information.
LIMITS – This section describes any limitations of a utility. Operating system and hardware limitations are usually not listed as they are outside of the utility’s control.
PORTABILITY – Lists other systems where the utility is available, along with how other versions of the utility may differ.
SEE ALSO – lists related man pages that contain relevant information.
HISTORY – Gives a brief history of the command such as when it first appeared.
WARNING – If this section is present, it contains important advice for users.
NOTES – Not as severe as a warning, but important information.
Again, not all man pages use the exact headings listed above, but they’re close enough to follow.
The Manual’s Sections
The entire Linux manual collection of pages are traditionally divided into numbered sections:
- Section 1 : Shell commands and applications
- Section 2 : Basic kernel services – system calls and error codes
- Section 3 : Library information for programmers
- Section 4 : Network services – if TCP/IP or NFS is installed Device drivers and network protocols
- Section 5 : Standard file formats – for example: shows what a tar archive looks like.
- Section 6 : Games
- Section 7 : Miscellaneous files and documents
- Section 8 : System administration and maintenance commands
- Section 9 : Obscure kernel specs and interfaces
The grouping of pages into these groups makes for more efficient searching. I sometimes do a little programming where I work, so I spend a little time look at section 3 man pages. I also do a little work in networking, so I’ve been known to wade through the networking section, and as a system administrator of several experimental machines, I spend a good deal of time in section 8.
Grouping pages into specific (chapters) sections make searching for information easier – both for the human needing it, and for the machine doing the searching.
You can tell which page belongs to which section by the number next to the name. For example, if you’re looking at a man page for
ls and the very top of the page says this:
LS(1), you are viewing the
ls page in section 1, which contains the pages about shell commands and applications.
Here is another example. If you’re looking at a man page for
passwd and the top of the page shows:
PASSWD(1), you are reading the page from section 1 that describes how the
passwd command changes passwords for user accounts. If you see
PASSWD(5), you are reading about the the password file and how it is made up.
passwd happens to be be two different things: it is the name of a command and a name of a file. Again, section 1 describes the command, while section 5 covers file formats.
The number in the parenthesis is the big clue – that number tells you what section that the page you’re reading, came from.
Searching for a Specific Section
The basic command:
will search for the man page identified by name in every section, displaying them one at a time, in numerical order. To limit your search to a specific section, use an argument with the
man command, like so:
man 1 name
This command will only search section 1, of the man pages, for name. Using our
passwd example earlier, this means that we can keep the search targeted. If I want to read about the
passwd command, I can type this in the terminal:
man 1 passwd
man utility will only search through section 1 for
passwd and display it. It will not look through any other section for
An alternative method for this command is to type:
Using man -k to Search all man Pages Containing a Certain Keyword
The man command, with the k option (often called a flag or switch) can come in handy if you want a listing of man pages containing a certain keyword. For example, if you want to see a list of man pages that deal with, say,
ftp, you can get this list by typing:
man -k ftp
From the listing that will follow, you’ll be able to pick a specific man page to read:
On some systems, before
man -k will work, the system administrator will need to run a utility called
Using whatis and whereis Commands to Know the Manual’s Sections
There are two nifty utilities that can be helpful in your search for information: whatis and whereis.
There are times when we can quite get the information we need. Chances are great that the information we need is available – finding it can be a small problem.
For example, if I want to look at the man page about the
passwd file, and I type this on the terminal:
I would see the page that tells me all about the
passwd command, but nothing about the
passwd file. I know that
passwd is a command and there’s also a
passwd file, but sometimes, I might forget that. It’s then that I realize that file structures are in a different section in the man pages, so I type:
man 4 passwd
and I get this reply:
No manual entry for passwd in section 4 See 'man 7 undocumented' for help when manual pages are not available.
Another lapse of forgetfulness. File structures are in section 4 of System V UNIX pages. Years ago, when I built files, I used
man 4... a lot; it’s still a habit with me. So where is it in the Linux manual?
It’s time to call
whatis to straighten me out. To do this, I type this in my terminal:
and I see the following:
passwd (1) - change user password passwd (1ssl) - compute password hashes passwd (5) - the password file
Ah! the page for the
passwd file is in section 5. Now I am set straight and can access the information I want:
man 5 passwd
and I am brought to the man page that has the information I need.
whatis is handy utility that can tell you, in a brief one-liner, what a command does. Imagine that you want to know what
cal does without having to view the man page. Just type this at the command prompt:
and you will see this in response:
cal (1) - displays a calendar and the date of Easter
Now that you know about the
whatis command, I can let you in on a secret – there is a
man command equivalent. To get this, we use the
man -f ...
Try it out. Type:
whatis cal at a terminal prompt. Once that executes, type:
man -f cal. The output of both commands will be identical.
The very name of the
whereis command explains itself – it tells you where a program is within the filesystem. It will also tell you where the man page is stored too. Using
cal as an example again, I type this at the prompt:
I will see this:
Look carefully at the reply. The answer is on one line, but it tells me two things:
/usr/bin/cal is where the
cal program is and
/usr/share/man/man1/cal.1.gz is where the man page resides (I’m also clued into the fact that the man page is compressed, but not to worry – the man command knows how to decompress it on the fly)
whereis is PATH dependent; it can only tell you where files are if they are in your PATH environment.
You may be wondering if there is an equivalent
man command for
whereis. There isn’t one that will tell you where the executable file is, but there is a switch you can use that will tell you where the man page is. Using the
date command in this example, if we type:
at a terminal prompt, we will see:
We see that the
date program is in the
/usr/bin/ directory and the name and location of its man page is:
The closest we can get man to act like
whereis is to use the
-w switch. We won’t get the location of the program, but we can at least get the location of the man page, like this:
man -w date
and we will see this returned:
You know about
whereis as well as a method to get the
man command to do the same (or close) thing. I showed both ways for a couple of different reasons.
For years, I used
whereis since they were in my training manuals. I didn’t learn about
man -f ... and
man -w ... until fairly recently. I’m sure I looked at the man page for
man hundreds of times, but I never noticed the
-w switches. I was always looking at the man page for something else (i.e.
man -k ...). I concentrated only on what I needed to find and ignored the rest. Once I found the information I needed, I would leave the page and get the work done, not paying attention to some of the other gems the command had to offer.
This is okay since this is partly what the man pages are for: to help you get work done.
It wasn’t until I was recently showing someone how to use man pages, that I took the time to just read – “to see what else was possible” – and we took real notice of the information about what the
-w flags can do.
No matter how long you have been using Linux, or how experienced, there is always something new to learn.
The man pages will tell you what you may need to know to work through a certain task – but they also hold a lot more – enough to make you look like a magician – but only if you take the time to read.
If you spend some time and effort with the man pages, you will come out on top. Your proficiency of the man pages, will play a huge part in your mastery over Linux.