sample - An annotated example of manual page layout for commands and calls.
The name, or list of names, by which the command is called, followed by a dash and then a one-line summary of the action performed. This line is used to generate the whatis (1) database.
- The syntax of the command and its arguments, as typed on the command line. Boldface words are literals which must by typed exactly as printed. Words in italics or underlined describe values which you must supply. References to bold or italicized items are not capitalized in other sections, even when they begin a sentence.
Syntactic symbols appear in roman face:
- [ ]
- An argument, when surrounded by brackets is optional.
Arguments separated by a vertical bar are exclusive.
- You can supply only one item from such a list.
- Arguments followed by an ellipsis can be repeated.
When an ellipsis follows a bracketed set, the expression within the
brackets can be repeated.
- If required, the data declaration, or #include directive, is shown first, followed by the function declaration. If libraries are required, they may also be listed. Otherwise, just the function declaration is shown.
A narrative overview of the command or function's external behavior.
This includes how it interacts with files or data, and how it
handles the standard input, standard output and standard error.
Internals and implementation details are normally omitted.
This section attempts to provide a succinct overview in answer to the
question, "what does it do?"
Literal text from the synopsis appears in boldface, as do literal
filenames and references to items that appear elsewhere in the page.
Arguments are italicized or underlined.
This part can sometimes get extremely technical and in some sections
assumes a strong familiarity with the operating system or software
package being discussed. Thus, if you find parts you don't understand
just skim past them until you find something useful.
A list of the command line options and arguments which may be used to
alter the behavior of the command. This is the most frequently useful
section of the manual page. Refer to the synopsis for the exact
syntax for using options. Look for whether an option must be preceded
by a dash, whether some options can be grouped together after one
dash, whether an option has an agrument and if so whether there must
be a space between the argument and the option name.
If a command has an interactive interface or interprets an input
grammar, details of its use are described in this section.
Also known as ERRORS, this explains what happens when something
goes wrong and often gives valuable ideas for fixing them. If you
can't get a program to work, this is the first place to look. Note
that it usually appears very near the end of the manual page and thus
is often overlooked by those who get frustrated with the DESCRIPTION
A list of files associated with the command or function. This
is a good section to look at to see what kind of external effects
the command might have or to find resource files which you might
use to alter its behavior.
This is the most important section of any manual page, especially for
begining users. It is a comma-separated list of related manual pages,
followed by references to other published materials. If a keyword
search (using man -k keyword) doesn't turn up the page
you want, look in the SEE ALSO sections of some of the pages that
are returned. They are likely to lead you to the right place or at
least give you some ideas for better keywords to try. This is
nearly the last part of the page but it is essential that you do not
A description of limitations, known defects, and possible problems
associated with the command or function. It's a good idea to read
this before you try to use the command.