man


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.

jeffsch@mandela:~ man less

Reformatting less(1), please wait...

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.

jeffsch@mandela:~ man man

Reformatting man(1), please wait...

jeffsch@mandela:~ man 7 man

Reformatting man(7), please wait...

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.

Figure 1: Top portion of the man page for the ls command.

LS(1)                                                          LS(1)

NAME

       ls - list directory contents

SYNOPSIS

       ls [OPTION]... [FILE]...

DESCRIPTION

(Rest of page not shown.)

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:

jeffsch@mandela:~$ man -k find

bogotune (1)         - find optimum parameter settings for bogofilter

chkdupexe (1)        - find duplicate executables

FcConfigFilename (3) - Find a config file

find (1)             - search for files in a directory hierarchy

find2perl (1)        - translate find command lines to Perl code

findfs (8)           - Find a filesystem by label or UUID

gst-typefind-0.10 (1) - print MIME type of file

gst-typefind-0.8 (1) - print MIME type of file

mysql_find_rows (1)  - MySQL shell skript for searching in update logs.

pidof (8)            - find the process ID of a running program.

runlevel (8)         - find the previous and current system runlevel.

sane-find-scanner (1) - find SCSI and USB scanners and their device files

XFindContext (3)     - associative look-up routines

XtFindFile (3)       - search for a file using substitutions in the path list

jeffsch@mandela:~$

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:

jeffsch@mandela:~$ man -f find

find (1)             - search for files in a directory hierarchy

jeffsch@mandela:~$

Manpage Sections

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

Figure 2: Manpage sections.

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  conven-
    tions), e.g. man(7), groff(7)

8 - System administration commands (usually only for root)

9 - Kernel routines [Non standard]

Source: The man(1) manpage.

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

UserDocumentation

man (last edited 2009-04-24 13:46:44 by gatoguan-os)