Introduction

The command-line program man is used for displaying Unix and Linux manual pages (usually called manpages). Manpages are self-contained reference documents stored on the machine's hard drive. They are usually short, but can be quite long. Ubuntu's manpage system has a reference for every command-line program, and in many cases it is the only source of information.

Man displays the data using a pager, a type of program that shows files on text-based terminals one screen at a time. On Ubuntu, less is the pager that is used.

The manpage system has been a part of Unix and Unix-like systems since the early 1980s, and although it is primitive by today's standards, it is nevertheless a useful resource. It offers a quick reference to the switches and and options available in terminal-based commands and programs such as ls, find, less, and of course, man itself. In addition, it also contains information on almost all of the GUI based programs on your system, such as gimp and firefox.

This page describes how to use man at the command line, and gives an overview of the manpage system. It does not cover the tools apropos or whatis, both of which are used for searching parts of the manpage data, and both of which have equivalents in man using the -k and -f switches. The -k and -f switches are covered here.

Using Man

When you know the name of the command or program you want information about, then you can type man <command-name>, as in the example below which shows how to look at the manpage for less, the tool used by the man system to display its data.

When the manpage opens, use the up and down arrow keys and the Page Up and Page Down keys to navigate through the file. Press the Q key to quit and return to the command line.

You can search forward within the file using less's "/" command, and backward with the "?" command. More information on using less is in the manpage for less.

In the above example, the message Reformatting less(1), please wait... appears briefly while the manpage is being converted into a format suitable for display.

Manpages are grouped into nine main sections, numbered from 1 to 9. The "(1)" part of the message in the example above indicates that the manpage being displayed is located in section 1. A brief description of the various manpage sections is at the end of this page.

It's possible for a manpage to exist in more than one section. For example, two pages exist for man itself; one is in section 1 and the other is in section 7. When you type man man, the page in section 1 is displayed. If you want to view the page in section 7, then type man 7 man, as demonstrated in the samples below.

Finding Man Pages

Use man's -k and -f switches to find manpages. You can also use apropos and whatis, which are stand-alone equivalents of man -k and man -f.

The search mechanism goes through each manpage on your system and looks at only one line in each. The line it looks at is in the NAME part of the manpage. Manpages are divided into several parts, the first of which is always the NAME part. It contains the name of the manpage and a brief one-line description of the topic it covers. If your search term is not in the NAME part of any manpage, then your search will return zero results.

Figure 1 shows an example of the first few lines of a typical manpage showing the NAME and SYNOPSIS parts, and the beginning of a DESCRIPTION part.

man -k

When you search for manpages with man's -k switch, the entire NAME line of every manpage is searched and the results (if any) are displayed. For example, if you type man -k find, you will get a list similar to that shown below:

Remember, only the NAME part of the manpage is searched; if your search term is not in the NAME part of any manpage, then your search will return zero results.

man -f

When you search with man's -f switch, only the manpage names are searched. For example, if you type man -f find, you will get the results shown below:

Manpage Sections

Manpages are grouped into sections, numbered from 1 to 9. The sections are described in Figure 2.

In addition to the numbered sections, three deprecated sections exist. They are the letters n, o, and l. Deprecated sections are not used for new manpages, but you might encounter them from time-to-time in existing documentation, and in the path configuration file for man, /etc/manpath.config.

Manpages can also be grouped into subsections with the use of "extensions." Subsections are of interest primarily to developers and manpage authors; you will quite likely never have to worry about them, but you can find more information in the manpage for man.

Resources

• Browse and search the man pages online:

  • http://manpages.ubuntu.com/

  • http://www.linuxmanpages.com/

• Write your own man page: http://tldp.org/HOWTO/Man-Page/

• Wikipedia article on man pages: http://en.wikipedia.org/wiki/Unix_manual

• The man page for man: Type man man at the command line.

UserDocumentation