<manpage>
<docdate>April 26, 2007</docdate>
<doctitle>MANUAL PAGES</doctitle>
<os>Mac OS</os>
<osversion>X</osversion>
<section>5</section>
<names><name>manpages<desc>An introduction to manual pages</desc></name></names>
<description>
<p>Manual pages (often shortened to "man pages") are a means of
providing documentation on the command line. Most manual pages
describe low-level programming interfaces, command-line tools,
and file formats.</p>
<p>This manual page is intended to help you learn about manual
pages, their purpose, their style, and their overall layout
so that you can better take advantage of the content that they
provide.</p>
</description>
<topic><name>MANUAL PAGE STYLE</name>
<p>Because manual pages are written by software engineers from
many different companies and organizations around the world,
the format of these manual pages varies somewhat from page to page,
as does the style.</p>
<p>In general, however, manual pages are written to be as concise
as possible. While this makes them a somewhat difficult place to
start as a new programmer, this is intentional. They are not
intended to replace conceptual documentation such as books on
programming. They are intended primarily to provide a quick
reference for people who are already somewhat familiar with the
subject.</p>
<p>Some manual pages provide links to outside websites. You can
often find more thorough conceptual documentation, sample code,
and other useful information at these websites.</p>
</topic>
<topic><name>MANUAL PAGE SECTIONS</name>
<p>The manual is divided into sections. Each section
covers a particular subject area. The major manual page
sections are:</p>
<dl>
<dt>1</dt><dd>General User Commands</dd>
<dt>2</dt><dd>System Calls</dd>
<dt>3</dt><dd>Library Routines (*)</dd>
<dt>4</dt><dd>Special Files and Sockets</dd>
<dt>5</dt><dd>File formats and Conventions</dd>
<dt>6</dt><dd>Games and Fun Stuff</dd>
<dt>7</dt><dd>Miscellaneous Documentation</dd>
<dt>8</dt><dd>System Administration</dd>
<dt>9</dt><dd>Kernel and Programming Style</dd>
<dt>n</dt><dd>Tcl/Tk</dd>
</dl>
<p></p>
<p>(*) Excludes library routines that merely wrap system calls.
Those routines are covered in section 2.</p>
<p>The majority of commonly used commands appear in sections 1
and 8 of the manual, while most programming information is
found in sections 2 and 3.</p>
<p>These subject areas may be further subdivided. For example,
manual section 3 was originally intended to hold documentation
in the standard C library but has been expanded to include
functions in other C language libraries, such as section 3ssl
(OpenSSL functions).</p>
<p>Section 3 has even been expanded to include other programming
languages. For example, section 3pm contains documentation for
Perl modules).</p>
<p>It is common to have multiple manual pages with the same name
but different section numbers. This usually occurs when a command
shares a name with a C function or system call that does something
very similar. To avoid any confusion, manual pages are commonly
referred to in the form name(number), in which the number is the
section number.</p>
</topic>
<topic><name>MANUAL PAGE TOOLS</name>
<p>You can read manual pages in a number of ways. The most common way
to read manual pages is with the <manpage>man<section>1</section></manpage>
tool from the command line. For example, typing "man man" displays
the manual page for the man tool.</p>
<p>If there are multiple manual pages with the same name but different
section numbers (for example, open(1) and open(2)), you can specify a
section number when requesting the page. For example, the command "man 2 open"
displays the manual page for the "open" system call from section 2 of
the manual.</p>
<p>You can also read manual pages from within Xcode by choosing the
"Open man page..." option in the Help menu, or within your choice of
web browsers by going to <url>http://developer.apple.com/documentation/Darwin/Reference/ManPages/</url>.</p>
<p>In addition to searching for manual pages on the web, the manual page
architecture also provides two useful command-line tools for
searching the manual pages: whatis and apropos.</p>
<p>The <manpage>whatis<section>1</section></manpage> command searches the
manual page headings (command and function names) for a word. If that word
appears in its entirety, it shows the matching name and abstract.
For example, typing "whatis man" returns results for man and man.conf.
This is mostly of interest if you want to read an abstract for
a particular command.</p>
<p>The <manpage>apropos<section>1</section></manpage> command is a much
more user-friendly version of whatis. It searches the same database, but
searches the manual page abstracts as well as the titles. Unlike the
whatis command, apropos returns results for partial word matches.</p>
<p>NOTE: Both apropos and whatis depend on a database to provide
information. This database is updated periodically. On fresh
installations, however, it may not be present. If apropos and whatis
are not working correctly, you should run the following command as
an admin user:</p>
<blockquote><p>sudo /usr/libexec/makewhatis</p></blockquote>
<p>This will rebuild the database. Enter your admin password
when prompted.</p>
</topic>
<topic><name>MANUAL PAGE STRUCTURE</name>
<p>Manual pages do not have a fixed structure. However, most
manual pages do follow certain conventions.</p>
<p>Manual pages typically begin with a <b>NAME</b> section,
which contains the name of a command or function and
a short abstract.</p>
<p>Next, manual pages typically include a <b>SYNOPSIS</b>
section, which describes how to use the command or
function. For functions, the syntax generally contains
the necessary include directives, followed by the function
declarations themselves. For commands, the syntax is
explained in <b>MANUAL PAGE SYNTAX</b>.</p>
<p>After the <b>SYNOPSIS</b> section, you will generally find
a <b>DESCRIPTION</b> section, followed by an <b>OPTIONS</b>
section (which explains the flags from the <b>SYNOPSIS</b> section.</p>
<p>You may find sections such as <b>ENVIRONMENT</b>
<b>HISTORY</b>, <b>BUGS</b>, <b>CONFORMING TO</b>, <b>AUTHOR</b>,
and <b>COPYRIGHT</b>.</p>
<p>Finally, most manual pages end with a section called <b>SEE ALSO</b>,
which includes the names and section numbers of related manual pages.</p>
</topic>
<topic><name>MANUAL PAGE SYNTAX</name>
<p>In manual page syntax, anything in a normal text font is
required text. Anything in a <b>boldface</b> font is a flag
or a subcommand. Anything <u>underlined</u> is a user-specified
argument such as a filename.</p>
<p>Any argument surrounded by brackets is considered to be
optional. For example, [<u>filename</u>] would indicate an optional
filename argument.</p>
<p>Flags, arguments, or subcommands separated by a vertical
separator (|) are mutually exclusive. For example, if -a turns
on an option and -b turns off the option, the syntax for this
command might be <b>-a</b> | <b>-b</b>.</p>
<p>In some cases, you may even see entire groups of arguments
wrapped with brackets and separated by a vertical separator.
This is one way of showing that a command has more than one
valid syntax. In other manual pages, this is expressed by
having multiple lines in the synopsis, each of which begins
with the command name. The separated format is more common
(and more readable), but is not always possible for commands
with particularly complex syntax.</p>
<p>Finally, the most important notational convention is the
use of the ellipsis (...). This indicates that additional
arguments may be added at this point. Depending on the author,
you may see this written in one of two ways:</p>
<p><u>argument</u> [<u>argument</u>...]<br />
<u>argument</u>...
</p>
</topic>
<seealso>
<p>For more information on manual pages, see
<manpage>man<section>1</section>,</manpage>
<manpage>intro<section>1</section>,</manpage>
<manpage>intro<section>2</section>,</manpage>
<manpage>intro<section>3</section>,</manpage>
<manpage>intro<section>5</section>,</manpage>
<manpage>intro<section>7</section>,</manpage>
<manpage>intro<section>8</section>,</manpage>
<manpage>intro<section>9</section>,</manpage>
and the developer documentation website at <url>http://developer.apple.com/documentation/Darwin/Reference/ManPages/</url>.
</p>
</seealso>
</manpage>