Understanding Man Pages

Understanding Man Pages

Understanding Man Pages are essential to working with Linux. The man pages are your guide to the commands that you can use to make the operating system do what you want. They were first introduced in 1971 and quickly became the standard for online help.

When you first look at man pages they look very cryptic because of their structure. Even if you never write a man page yourself knowing the structure is important. Man pages are organized into sections (think of them as chapters in a book).

Man Page Sections

Here are the section numbers and the subjects:

 	1. User Commands 
 	2. System Calls 
 	3. Library Functions 
 	4. Devices 
 	5. Files in /dev, configuration files, and drivers 
 	6. Games & Screensavers 
 	7. Miscellaneous 
 	8. System Administrative Commands 
 	9. Kernel Routines & Daemons 
        0. New Commands - Not Categorized yet

Most man pages are stored in /usr/share/man or /usr/man. Some applications have their own man pages in other directories and you can create a MANPATH to include them.

I picked out the command “date” as you can see it is gzipped.

Man Page Structure

• Name
• Synopsis
• Configuration
• Description
• Options
• Exit Status
• Return Value
• Errors
• Environment
• Files
• Versions
• Conforming to
• Notes
• Bugs
• Examples
• Authors
• See Also

You don’t have to have all of the section headings to compile a man page. The ones that are highlighted in red are the ones that most man pages do include.

Man Page Markup

Man pages are text-based and are written with a simple markup using nroff/groff macros. See the chart for the format.

Let’s go back to the man page that we picked: “date” and see what it looks like.

The makeup to get this looks like this: (Red highlighting added this is only the first page of the code)

Code behind a man page

Decoding the man page

Compiling Man Pages

Man pages are stored as gzip (or bzip) files. There are several scripts that you can use to compile man pages. One of them is pod2man written in pearl.

As you write check your work with the following command:

When you are done enter:

Compress the output file with gzip and place it in the directory. To access it add it to the database.

Reading a Man Page

I hope that this has helped a bit in reading a man page. Seeing what goes into writing one usually helps because the pieces are broken down.

Now you can type in

And you will get the result you are looking for. Try looking at man man to find out more about the various things hidden there.

Man pages are here to stay

For about fifty years man pages have been a go to thing in Unix and lately Linux and they are not going away anytime soon. They continue to provide useful information on a daily basis. They have changed very little over time. Understanding man pages will give you a big boost in your confidence as you navigate through your Linux experience.