Manual Pages

You’ve seen that the man command will give you a description of a program and its options. The man command also provides information about C/C++ system calls and standard library functions. Often, UNIX commands (such as printf) have the same name as library functions. You can see all listings associated with a given name with man -a.

You can also create your own man pages. man pages are text documents that use special formatting via nroff/troff macros (see the companion web site for more information about troff and nroff). An example man page for a command called widget might look something like this:

 . \" An example comment .TH WIDGET 1 "July 2006" .SH NAME widget \- run a shell widget

 .SH SYNOPSIS .B widget [ .I \-options ] [ .I arguments \&...] .SH DESCRIPTION This is a description of what the widget does. .SH SEE ALSO WidgetFactory is a related command. .RS .B WidgetFactory .RE

If you type this into a file called widget.1 and run the command

 $ man ./widget.1

then man will display a page like Figure 24–1. You can also save man pages in compressed files (e.g., widget.1.gz).

Figure 24–1: Sample man page

If you want to install your man page so that any user can find information about your application, you must place your file in a directory that man searches. On many systems, man pages are stored in /usr/man or /usr/share/man. You can list the paths that man searches by typing

 $ man --path

These directories contain subdirectories such as man1, man2, etc. These subdirectories each store a section, which groups together man pages of a similar type. For example, most user commands belong in section 1, in the directory man1. (For a description of the man page sections, see http://en.wikipedia.org/wiki/Man_page.) The name of your man page file should also indicate which section it belongs to. For example, since widget belongs in section 1, it is called widget.1 and goes in the directory /usr/man/man1. Once you have placed it there, you can view the page with the command

 $ man widget