How to Read Man Pages

Reading On-line Man Pages

What are "man pages"?

On-line manual pages, called "man pages", have for a long time been the only available documentation on Unix systems. Man pages have a long-standing reputation for being hard to read, confusing, and in general inadequate for beginners, because they are designed as a reference rather than an instruction manual. However, even today they represent the most complete documentation available.

This document will familiarize you with various conventions in man pages that should make them a little easier to deal with.

Accessing man pages

Most of our man pages are available through this help system (click here). All are available through unix commands.

The command for accessing man pages is "man". In general you will type "man topic", but only if you already know the exact topic name. (Almost) all unix commands are topics, so for instance "man ls" provides information on using the ls command.

Of course, if you want to find the command to perform some specific task, you can see that this isn't too useful. You can hunt for subjects using "man -k subject". For instance, "man -k permission" will show you a listing of just a few man pages, including one for chmod (which is the command used to change file permissions). Frequently though, this results in a list which is either too long or doesn't contain what you want (or sometimes both).

Sections

The man pages are divided into different sections. Here's a brief description of each (more detailed descriptions later):

  Section 1     User commands
  Section 2     System calls  (for C programming)
  Section 3     Library calls (for C and Fortran programming)
  Section 4     Devices, special files
  Section 5     File formats
  Section 6     Games
  Section 7     Miscellaneous
  Section 8     Administrative commands

Typically, when referring to a man page, the section is shown in parenthesis after the command, e.g. chmod(1). This is included to help you find the man page, because some things occur in more than one section. For instance, there is a chmod C function, as well as a user command. The C function is referred to as chmod(2), since its man page is found in section 2. Note that in some instances the number may be followed by an additional letter indicating a subsection.

Since man pages with the same name can occur in different sections, you may need to specify the section when using the man command. For instance, to get the C function chmod, you would need to say "man 2 chmod", otherwise you'd always get the chmod in section 1. The man command will search all sections (not in order but usually starting with 1) until it finds a match, so if you wanted the man page for fork(2), you could just say "man fork", since there is no fork in section 1.

General Format

There are certain conventions which are usually followed in man pages. One of them discussed above is inclusion of the section number in parentheses for all references to other man pages or commands which have man pages.

Most man pages are divided into sections (don't confuse this with the sections discussed above, and please let me mix my terminology a bit), some of which are pretty standard. They all have a NAME section, which gives the name of the topic along with a very brief description. The DESCRIPTION section contains a detailed description of the topic. There is usually a SYNOPSIS section, which describes how to use the command. The SEE ALSO section tells you what other man pages (and sometimes other references) to check for information. The FILES section lists what files might be related to that command. If you're lucky there will be an EXAMPLES section.

The order of these sections is pretty standard. Here's a list of most commonly occuring sections, in the order they are likely to occur:

  NAME
  SYNOPSIS
  DESCRIPTION
  OPTIONS
  EXAMPLES
  RETURN VALUES
  ERRORS
  FILES
  SEE ALSO
  NOTES
  WARNINGS
  BUGS
  AUTHOR

Section 1

This section contains user commands - things you'll be typing on the command line or using in shell scripts.

The SYNOPSIS section tells you how to use the command, in a somewhat cryptic fashion. Optional parameters are displayed in square brackets. An elipsis indicates that a parameter can be repeated several times. For example the chmod(1) SYNOPSIS is

    chmod [ -fR ] mode filename ...

Which means that you would type at least "chmod mode filename" but possibly "chmod -f -R mode file1 file2 file3". Man pages don't alway follow these conventions exactly, but it's a start.

Frequently man pages in section 1 have an OPTIONS section which describes what each option does.

Section 2

This section contains the C functions which are system calls - requests made directly to the kernel.

The SYNOPSIS section shows you any include files that are required to use the call, and shows the declaration of the function. This declaration is how the function itself is declared. Don't confuse this with how you have to declare the variables you pass to the function, as they will frequently be different in the case of pointers.

There are usually RETURN VALUES and ERRORS sections which indicate what the call will return, and what sort of system errors it can encounter.

Section 3

This section contains the C and Fortran Library routines; slightly higher level stuff than the system calls. The format is the same as section 2.

Section 4

This section contains the man pages for all of the device drivers on the system.

The CONFIG section(s) contains information on how to compile that device driver into the kernel.

The DIAGNOSTICS section lists the sort of error messages that might be spit out due to problems with the device driver.

Section 5

File formats. This is where formats of lots of different files are find, including both system and user files, a.out format, core file format, and lots of others.

Section 6

This is where the man pages for the games live. In general, most games we have don't have man pages.

Section 7

A small number of miscellaneous things. Check the introduction to section 7 (see below).

Section 8

This section contains various system administration programs.

Introduction

Every section of the man pages will also have an introduction. For instance "man 6 intro" gives an introduction to the games section of the man pages. These introductions typically contain a list of the system-shipped man pages in that section, and may include other information. The section 2 introduction, provides a much too brief description of the inner workings of UNIX, together with a list of system calls, and system error codes.

Last Update: 1/10/94 JGW

Original author: TAF