mirror of https://github.com/mkerrisk/man-pages
502 lines
16 KiB
Groff
502 lines
16 KiB
Groff
.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
|
|
.\" (faith@cs.unc.edu and dwheeler@ida.org)
|
|
.\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" 2007-05-30 created by mtk, using text from old man.7 plus
|
|
.\" rewrites and additional text.
|
|
.\"
|
|
.TH MAN-PAGES 7 2007-12-29 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
man-pages \- conventions for writing Linux man pages
|
|
.SH SYNOPSIS
|
|
.B man
|
|
.RI [ section ]
|
|
.I title
|
|
.SH DESCRIPTION
|
|
This page describes the conventions that should be employed
|
|
when writing man pages for the Linux \fIman-pages\fP project,
|
|
which comprises Sections 2, 3, 4, 5, and 7 of the Linux manual pages.
|
|
The conventions described on this page may also be useful
|
|
for authors writing man pages for other projects.
|
|
.SS Sections of the Manual Pages
|
|
.PP
|
|
The manual Sections are traditionally defined as follows:
|
|
.TP 10
|
|
.B 1 Commands (Programs)
|
|
Those commands that can be executed by the user from within
|
|
a shell.
|
|
.TP
|
|
.B 2 System calls
|
|
Those functions which must be performed by the kernel.
|
|
.TP
|
|
.B 3 Library calls
|
|
Most of the
|
|
.I libc
|
|
functions.
|
|
.TP
|
|
.B 4 Special files (devices)
|
|
Files found in
|
|
.IR /dev .
|
|
.TP
|
|
.B 5 File formats and conventions
|
|
The format for
|
|
.I /etc/passwd
|
|
and other human-readable files.
|
|
.TP
|
|
.B 6 Games
|
|
.TP
|
|
.B 7 Conventions and miscellaneous
|
|
Overviews of various topics, conventions and protocols,
|
|
character set standards, and miscellaneous other things.
|
|
.TP
|
|
.B 8 System management commands
|
|
Commands like
|
|
.BR mount (8),
|
|
many of which only root can execute.
|
|
.\" .TP
|
|
.\" .B 9 Kernel routines
|
|
.\" This is an obsolete manual section.
|
|
.\" Once it was thought a good idea to document the Linux kernel here,
|
|
.\" but in fact very little has been documented, and the documentation
|
|
.\" that exists is outdated already.
|
|
.\" There are better sources of
|
|
.\" information for kernel developers.
|
|
.SS Macro package
|
|
New manual pages should be marked up using the
|
|
.B groff an.tmac
|
|
package described in
|
|
.BR man (7).
|
|
This choice is mainly for consistency: the vast majority of
|
|
existing Linux manual pages are marked up using these macros.
|
|
.SS Conventions for source file layout
|
|
Please limit source code line length to no more than about 75 characters
|
|
wherever possible.
|
|
This helps avoid line-wrapping in some mail clients when patches are
|
|
submitted inline.
|
|
|
|
New sentences should be started on new lines.
|
|
This makes it easier to see the effect of patches,
|
|
which often operate at the level of individual sentences.
|
|
.SS Title line
|
|
The first command in a man page should be a \fBTH\fP command:
|
|
.RS
|
|
.sp
|
|
.B \&.TH
|
|
.I "title section date source manual"
|
|
.sp
|
|
.RE
|
|
where:
|
|
.RS
|
|
.TP 10
|
|
.I title
|
|
The title of the man page, written in all caps (e.g.,
|
|
.IR MAN-PAGES ).
|
|
.TP
|
|
.I section
|
|
The section number in which the man page should be placed (e.g.,
|
|
.IR 7 ).
|
|
.TP
|
|
.I date
|
|
The date of the last revision \(em remember to change this every time a
|
|
change is made to the man page,
|
|
since this is the most general way of doing version control.
|
|
Dates should be written in the form YYYY-MM-DD.
|
|
.TP
|
|
.I source
|
|
The source of the command, function, or system call.
|
|
|
|
For those few \fIman-pages\fP pages in Sections 1 and 8,
|
|
probably you just want to write
|
|
.IR GNU .
|
|
|
|
For system calls, just write
|
|
.IR "Linux" .
|
|
(An earlier practice was to write the version number
|
|
of the kernel from which the manual page was being written/checked.
|
|
However, this was never done consistently, and so was
|
|
probably worse than including no version number.
|
|
Henceforth, avoid including a version number.)
|
|
|
|
For library calls that are part of glibc or one of the
|
|
other common GNU libraries, just use
|
|
.IR "GNU C Library" ", " GNU ,
|
|
or an empty string.
|
|
|
|
For Section 4 pages, use
|
|
.IR "Linux" .
|
|
|
|
In cases of doubt, just write
|
|
.IR Linux ", or " GNU .
|
|
.TP
|
|
.I manual
|
|
The title of the manual (e.g., for Section 2 and 3 pages in
|
|
the \fIman-pages\fP package, use
|
|
.IR "Linux Programmer's Manual" ).
|
|
.RE
|
|
.SS Sections within a manual page
|
|
The list below shows conventional or suggested sections.
|
|
Most manual pages should include at least the
|
|
.B highlighted
|
|
sections.
|
|
Arrange a new manual page so that sections
|
|
are placed in the order shown in the list.
|
|
.in +0.5i
|
|
.nf
|
|
|
|
\fBNAME\fP
|
|
\fBSYNOPSIS\fP
|
|
\fBCONFIGURATION\fP [Normally only in Section 4]
|
|
\fBDESCRIPTION\fP
|
|
OPTIONS [Normally only in Sections 1, 8]
|
|
EXIT STATUS [Normally only in Sections 1, 8]
|
|
RETURN VALUE [Normally only in Sections 2, 3]
|
|
.\" May 07: Few current man pages have an ERROR HANDLING section,,,
|
|
.\" ERROR HANDLING,
|
|
ERRORS [Typically only in Sections 2, 3]
|
|
.\" May 07: Almost no current man pages have a USAGE section,,,
|
|
.\" USAGE,
|
|
.\" DIAGNOSTICS,
|
|
.\" May 07: Almost no current man pages have a SECURITY section,,,
|
|
.\" SECURITY,
|
|
ENVIRONMENT
|
|
FILES
|
|
VERSIONS [Normally only in Sections 2, 3]
|
|
CONFORMING TO
|
|
NOTES
|
|
BUGS
|
|
EXAMPLE
|
|
.\" AUTHORS sections are discouraged
|
|
.\" AUTHORS [Discouraged]
|
|
\fBSEE ALSO\fP
|
|
|
|
.fi
|
|
.in
|
|
.IR "Where a traditional heading would apply" ", " "please use it" ;
|
|
this kind of consistency can make the information easier to understand.
|
|
If you must, you can create your own
|
|
headings if they make things easier to understand (this can
|
|
be especially useful for pages in Sections 4 and 5).
|
|
However, before doing this, consider whether you could use the
|
|
traditional headings, with some subsections (\fI.SS\fP) within
|
|
those sections.
|
|
|
|
The following list elaborates on the contents of each of
|
|
the above sections.
|
|
.TP 14
|
|
.B NAME
|
|
The name of this manual page.
|
|
See
|
|
.BR man (7)
|
|
for important details of the line(s) that should follow the
|
|
\fB.SH NAME\fP command.
|
|
.TP
|
|
.B SYNOPSIS
|
|
briefly describes the command or function's interface.
|
|
For commands, this shows the syntax of the command and its arguments
|
|
(including options);
|
|
boldface is used for as-is text and italics are used to
|
|
indicate replaceable arguments.
|
|
Brackets ([]) surround optional arguments, vertical bars (|)
|
|
separate choices, and ellipses (\&...) can be repeated.
|
|
For functions, it shows any required data declarations or
|
|
.B #include
|
|
directives, followed by the function declaration.
|
|
|
|
Where a feature test macro must be defined in order to obtain
|
|
the declaration of a function (or a variable) from a header file,
|
|
then the SYNOPSIS should indicate this, as described in
|
|
.BR feature_test_macros (7).
|
|
.\" FIXME . Say something here about compiler options
|
|
.TP
|
|
.B CONFIGURATION
|
|
Configuration details for a device.
|
|
This section normally only appears in Section 4 pages.
|
|
.TP
|
|
.B DESCRIPTION
|
|
gives an explanation of what the program, function, or format does.
|
|
Discuss how it interacts with files and standard input, and what it
|
|
produces on standard output or standard error.
|
|
Omit internals and implementation details unless they're critical for
|
|
understanding the interface.
|
|
Describe the usual case;
|
|
for information on command-line options of a program use the
|
|
.B OPTIONS
|
|
section.
|
|
.\" If there is some kind of input grammar or complex set of subcommands,
|
|
.\" consider describing them in a separate
|
|
.\" .B USAGE
|
|
.\" section (and just place an overview in the
|
|
.\" .B DESCRIPTION
|
|
.\" section).
|
|
.TP
|
|
.B OPTIONS
|
|
describes the command-line options accepted by a
|
|
program and how they change its behavior.
|
|
This section should only appear for Section 1 and 8 manual pages.
|
|
.\" .TP
|
|
.\" .B USAGE
|
|
.\" describes the grammar of any sublanguage this implements.
|
|
.TP
|
|
.B EXIT STATUS
|
|
lists the possible exit status values of a program and
|
|
the conditions that cause these values to be returned.
|
|
This section should only appear for Section 1 and 8 manual pages.
|
|
.TP
|
|
.B RETURN VALUE
|
|
For Section 2 and 3 pages, this section gives a
|
|
list of the values the library routine will return to the caller
|
|
and the conditions that cause these values to be returned.
|
|
.TP
|
|
.B ERRORS
|
|
For Section 2 and 3 manual pages, this is a list of the
|
|
values that may be placed in
|
|
.I errno
|
|
in the event of an error, along with information about the cause
|
|
of the errors.
|
|
.IR "The error list should be in alphabetical order" .
|
|
.TP
|
|
.B ENVIRONMENT
|
|
lists all environment variables that affect the program or function
|
|
and how they affect it.
|
|
.TP
|
|
.B FILES
|
|
lists the files the program or function uses, such as
|
|
configuration files, startup files,
|
|
and files the program directly operates on.
|
|
Give the full pathname of these files, and use the installation
|
|
process to modify the directory part to match user preferences.
|
|
For many programs, the default installation location is in
|
|
.IR /usr/local ,
|
|
so your base manual page should use
|
|
.I /usr/local
|
|
as the base.
|
|
.\" May 07: Almost no current man pages have a DIAGNOSTICS section;
|
|
.\" "RETURN VALUE" or "EXIT STATUS" is preferred.
|
|
.\" .TP
|
|
.\" .B DIAGNOSTICS
|
|
.\" gives an overview of the most common error messages and how to
|
|
.\" cope with them.
|
|
.\" You don't need to explain system error messages
|
|
.\" or fatal signals that can appear during execution of any program
|
|
.\" unless they're special in some way to the program.
|
|
.\"
|
|
.\" May 07: Almost no current man pages have a SECURITY section.
|
|
.\".TP
|
|
.\".B SECURITY
|
|
.\"discusses security issues and implications.
|
|
.\"Warn about configurations or environments that should be avoided,
|
|
.\"commands that may have security implications, and so on, especially
|
|
.\"if they aren't obvious.
|
|
.\"Discussing security in a separate section isn't necessary;
|
|
.\"if it's easier to understand, place security information in the
|
|
.\"other sections (such as the
|
|
.\" .B DESCRIPTION
|
|
.\" or
|
|
.\" .B USAGE
|
|
.\" section).
|
|
.\" However, please include security information somewhere!
|
|
.TP
|
|
.B VERSIONS
|
|
A brief summary of the Linux kernel or glibc versions where a
|
|
system call or library function appeared,
|
|
or changed significantly in its operation.
|
|
.TP
|
|
.B CONFORMING TO
|
|
describes any standards or conventions that relate to the function
|
|
or command described by the manual page.
|
|
For a page in Section 2 or 3,
|
|
this section should note the POSIX.1
|
|
version(s) that the call conforms to,
|
|
and also whether the call is specified in C99.
|
|
(Don't worry too much about other standards like SUS, SUSv2, and XPG,
|
|
or the SVr4 and 4.xBSD implementation standards,
|
|
unless the call was specified in those standards,
|
|
but isn't in the current version of POSIX.1.)
|
|
(See
|
|
.BR standards (7).)
|
|
|
|
If the call is not governed by any standards but commonly
|
|
exists on other systems, note them.
|
|
If the call is Linux-specific, note this.
|
|
.TP
|
|
.B NOTES
|
|
provides miscellaneous notes.
|
|
For Section 2 and 3 man pages you may find it useful to include
|
|
subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP.
|
|
.TP
|
|
.B BUGS
|
|
lists limitations, known defects or inconveniences,
|
|
and other questionable activities.
|
|
.TP
|
|
.B EXAMPLE
|
|
provides one or more examples describing how this function, file or
|
|
command is used.
|
|
For details on writing example programs,
|
|
see \fIExample Programs\fP below.
|
|
.TP
|
|
.B AUTHORS
|
|
lists authors of the documentation or program.
|
|
\fBUse of an AUTHORS section is strongly discouraged\fP.
|
|
Generally, it is better not to clutter every page with a list
|
|
of (over time potentially numerous) authors;
|
|
if you write or significantly amend a page,
|
|
add a copyright notice as a comment in the source file.
|
|
If you are the author of a device driver and want to include
|
|
an address for reporting bugs, place this under the BUGS section.
|
|
.TP
|
|
.B SEE ALSO
|
|
lists related man pages, ordered by section number and
|
|
then alphabetically by name, possibly followed by
|
|
other related pages or documents.
|
|
.SS Font conventions
|
|
.PP
|
|
For functions, the arguments are always specified using italics,
|
|
.IR "even in the SYNOPSIS section" ,
|
|
where the rest of the function is specified in bold:
|
|
.PP
|
|
.BI " int myfunction(int " argc ", char **" argv );
|
|
.PP
|
|
Filenames (whether pathnames, or references to files in the
|
|
.I /usr/include
|
|
directory)
|
|
are always in italics (e.g.,
|
|
.IR <stdio.h> ),
|
|
except in the SYNOPSIS section, where included files are in bold (e.g.,
|
|
.BR "#include <stdio.h>" ).
|
|
When referring to a standard include file under
|
|
.IR /usr/include ,
|
|
specify the header file surrounded by angle brackets,
|
|
in the usual C way (e.g.,
|
|
.IR <stdio.h> ).
|
|
|
|
.PP
|
|
Special macros, which are usually in upper case, are in bold (e.g.,
|
|
.BR MAXINT ).
|
|
Exception: don't boldface NULL.
|
|
.PP
|
|
When enumerating a list of error codes, the codes are in bold (this list
|
|
usually uses the
|
|
.B \&.TP
|
|
macro).
|
|
.PP
|
|
Any reference to the subject of the current manual page
|
|
should be written with the name in bold.
|
|
If the subject is a function (i.e., this is a Section 2 or 3 page),
|
|
then the name should be followed by a pair of parentheses
|
|
in Roman (normal) font.
|
|
For example, in the
|
|
.BR fcntl (2)
|
|
man page, references to the subject of the page would be written as:
|
|
.BR fcntl ().
|
|
The preferred way to write this in the source file is:
|
|
.nf
|
|
|
|
.BR fcntl ()
|
|
|
|
.fi
|
|
(Using this format, rather than the use of "\\fB...\\fP()"
|
|
makes it easier to write tools that parse man page source files.)
|
|
.PP
|
|
Any reference to another man page
|
|
should be written with the name in bold,
|
|
\fIalways\fP followed by the section number,
|
|
formatted in Roman (normal) font, without any
|
|
separating spaces (e.g.,
|
|
.BR intro (2)).
|
|
The preferred way to write this in the source file is:
|
|
.nf
|
|
|
|
.BR intro (2)
|
|
|
|
.fi
|
|
(Including the section number in cross references lets tools like
|
|
.BR man2html (1)
|
|
create properly hyperlinked pages.)
|
|
.SS Spelling
|
|
Starting with release 2.59,
|
|
.I man-pages
|
|
follows American spelling conventions;
|
|
please write all new pages and patches according to these conventions.
|
|
.SS Example Programs
|
|
Manual pages can include example programs demonstrating how to
|
|
use a system call or library function.
|
|
However, note the following:
|
|
.TP 3
|
|
*
|
|
Example programs should be written in C.
|
|
.TP
|
|
*
|
|
An example program is only necessary and useful if it demonstrates
|
|
something beyond what can easily be provided in a textual
|
|
description of the interface.
|
|
An example program that does nothing
|
|
other than call an interface usually serves little purpose.
|
|
.TP
|
|
*
|
|
Example programs should be fairly short (preferably < 100 lines;
|
|
ideally < 50 lines).
|
|
.TP
|
|
*
|
|
Example programs should do error checking after system calls and
|
|
library function calls.
|
|
.TP
|
|
*
|
|
Example programs should be complete, and compile without
|
|
warnings when compiled with \fIcc -Wall\fP.
|
|
.TP
|
|
*
|
|
Where possible and appropriate, example programs should allow
|
|
experimentation, by varying their behavior based on inputs
|
|
(ideally from command-line arguments, or alternatively, via
|
|
input read by the program).
|
|
.TP
|
|
*
|
|
Example programs should be laid out according to Kernighan and
|
|
Ritchie style, with 4-space indents.
|
|
(Avoid the use of TAB characters in source code!)
|
|
.PP
|
|
For some examples of what example programs should look like, see
|
|
.BR wait (2)
|
|
and
|
|
.BR pipe (2).
|
|
.SS Indentation of structure definitions, shell session logs, etc.
|
|
When structure definitions, shell session logs, etc. are included
|
|
in running text, indent them by 4 spaces (i.e., a block enclosed by
|
|
.I ".in\ +4n"
|
|
and
|
|
.IR ".in" ).
|
|
.SH EXAMPLE
|
|
For canonical examples of how man pages in the
|
|
.I man-pages
|
|
package should look, see
|
|
.BR pipe (2)
|
|
and
|
|
.BR fcntl (2).
|
|
.SH SEE ALSO
|
|
.BR man (1),
|
|
.BR man2html (1),
|
|
.BR groff (7),
|
|
.BR groff_man (7),
|
|
.BR man (7),
|
|
.BR mdoc (7)
|