Man Pages

man-pages(7) - phpMan man-pages(7) - phpMan

Command: man perldoc info search(apropos)  


MAN-PAGES(7)               Linux Programmer's Manual              MAN-PAGES(7)



NAME
       man-pages - conventions for writing Linux man pages

SYNOPSIS
       man [section] title

DESCRIPTION
       This  page  describes  the  conventions  that should be employed when writing man pages for the Linux man-pages
       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.

   Sections of the Manual Pages
       The manual Sections are traditionally defined as follows:

       1 Commands (Programs)
                 Those commands that can be executed by the user from within a shell.

       2 System calls
                 Those functions which must be performed by the kernel.

       3 Library calls
                 Most of the libc functions.

       4 Special files (devices)
                 Files found in /dev.

       5 File formats and conventions
                 The format for /etc/passwd and other human-readable files.

       6 Games

       7 Conventions and miscellaneous
                 Overviews  of  various  topics, conventions and protocols, character set standards, and miscellaneous
                 other things.

       8 System management commands
                 Commands like mount(8), many of which only root can execute.

   Macro package
       New manual pages should be marked up using the groff an.tmac package  described  in  man(7).   This  choice  is
       mainly for consistency: the vast majority of existing Linux manual pages are marked up using these macros.

   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.

   Title line
       The first command in a man page should be a TH command:

              .TH title section date source manual

       where:

              title     The title of the man page, written in all caps (e.g., MAN-PAGES).

              section   The section number in which the man page should be placed (e.g., 7).

              date      The date of the last revision -- 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.

              source    The source of the command, function, or system call.

                        For those few man-pages pages in Sections 1 and 8, probably you just want to write GNU.

                        For  system  calls, just write 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
                        GNU C Library, GNU, or an empty string.

                        For Section 4 pages, use Linux.

                        In cases of doubt, just write Linux, or GNU.

              manual    The  title  of the manual (e.g., for Section 2 and 3 pages in the man-pages package, use Linux
                        Programmer's Manual).

   Sections within a manual page
       The list below shows conventional or suggested sections.  Most manual pages should include at least  the  high-
       lighted sections.  Arrange a new manual page so that sections are placed in the order shown in the list.

            NAME
            SYNOPSIS
            CONFIGURATION      [Normally only in Section 4]
            DESCRIPTION
            OPTIONS            [Normally only in Sections 1, 8]
            EXIT STATUS        [Normally only in Sections 1, 8]
            RETURN VALUE       [Normally only in Sections 2, 3]
            ERRORS             [Typically only in Sections 2, 3]
            ENVIRONMENT
            FILES
            VERSIONS           [Normally only in Sections 2, 3]
            CONFORMING TO
            NOTES
            BUGS
            EXAMPLE
            SEE ALSO

       Where  a traditional heading would apply, please use it; this kind of consistency can make the information eas-
       ier 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 (.SS) within those sections.

       The following list elaborates on the contents of each of the above sections.

       NAME          The name of this manual page.  See man(7) for important details of the line(s) that should follow
                     the .SH NAME command.

       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 #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  fea-
                     ture_test_macros(7).

       CONFIGURATION Configuration details for a device.  This section normally only appears in Section 4 pages.

       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  OPTIONS
                     section.

       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.

       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.

       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.

       ERRORS        For Section 2 and 3 manual pages, this is a list of the values that may be placed in errno in the
                     event  of  an error, along with information about the cause of the errors.  The error list should
                     be in alphabetical order.

       ENVIRONMENT   lists all environment variables that affect the program or function and how they affect it.

       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  /usr/local,  so  your  base  manual page should use
                     /usr/local as the base.

       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.  As a general rule, every new interface
                     should include a VERSIONS section in its manual page.  Unfortunately, many existing manual  pages
                     don't  include  this  information  (since  there  was no policy to do so when they were written).
                     Patches to remedy this are welcome, but, from the perspective of programmers  writing  new  code,
                     this  information  probably only matters in the case of kernel interfaces that have been added in
                     Linux 2.4 or later (i.e., changes since kernel 2.2), and library functions that have  been  added
                     to glibc since version 2.1 (i.e., changes since glibc 2.0).

                     The syscalls(2) manual page also provides information about kernel versions in which various sys-
                     tem calls first appeared.

       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
                     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.

                     If this section consists of just a list of standards (which it commonly does), terminate the list
                     with a period ('.').

       NOTES         provides  miscellaneous  notes.   For Section 2 and 3 man pages you may find it useful to include
                     subsections (SS) named Linux Notes and Glibc Notes.

       BUGS          lists limitations, known defects or inconveniences, and other questionable activities.

       EXAMPLE       provides one or more examples describing how this function, file or command is used.  For details
                     on writing example programs, see Example Programs below.

       AUTHORS       lists  authors  of  the documentation or program.  Use of an AUTHORS section is strongly discour-
                     aged.  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 com-
                     ment 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.

       SEE ALSO      provides  a  comma-separated list of related man pages, ordered by section number and then alpha-
                     betically by name, possibly followed by other related pages or documents.  Do not terminate  this
                     with a period.

   Font conventions
       For  functions,  the arguments are always specified using italics, even in the SYNOPSIS section, where the rest
       of the function is specified in bold:

           int myfunction(int argc, char **argv);

       Variable names should, like argument names, be specified in italics.

       Filenames (whether pathnames, or references to files in the  /usr/include  directory)  are  always  in  italics
       (e.g., <stdio.h>), except in the SYNOPSIS section, where included files are in bold (e.g., #include <stdio.h>).
       When referring to a standard include file under /usr/include, specify  the  header  file  surrounded  by  angle
       brackets, in the usual C way (e.g., <stdio.h>).

       Special macros, which are usually in upper case, are in bold (e.g., MAXINT).  Exception: don't boldface NULL.

       When enumerating a list of error codes, the codes are in bold (this list usually uses the .TP macro).

       Complete commands should, if long, be written as in an indented line on their own, for example

           man 7 man-pages

       If  the command is short, then it can be included inline in the text, in italic format, for example, man 7 man-
       pages.  In this case, it may be worth using non-breaking spaces ("\ ") at suitable places in the command.  Com-
       mand options should be written in italics, e.g., -l.

       Expressions,  if  not  written  on a separate indented line, should be specified in italics.  Again, the use of
       non-breaking spaces may be appropriate if the expression is inlined with normal text.

       Any reference to the subject of the current manual page should be written with the name in bold.  If  the  sub-
       ject  is a function (i.e., this is a Section 2 or 3 page), then the name should be followed by a pair of paren-
       theses in Roman (normal) font.  For example, in the fcntl(2) man page, references to the subject  of  the  page
       would be written as: fcntl().  The preferred way to write this in the source file is:

           .BR fcntl ()

       (Using  this  format,  rather  than the use of "\fB...\fP()" makes it easier to write tools that parse man page
       source files.)

       Any reference to another man page should be written with the name in bold, always followed by the section  num-
       ber,  formatted  in  Roman (normal) font, without any separating spaces (e.g., intro(2)).  The preferred way to
       write this in the source file is:

           .BR intro (2)

       (Including the section number in cross references lets  tools  like  man2html(1)  create  properly  hyperlinked
       pages.)

   Spelling
       Starting  with  release  2.59,  man-pages follows American spelling conventions; please write all new pages and
       patches according to these conventions.

   Example Programs and Shell Sessions
       Manual pages can include example programs demonstrating how to use a system call or library function.  However,
       note the following:

       *  Example programs should be written in C.

       *  An  example program is only necessary and useful if it demonstrates something beyond what can easily be pro-
          vided in a textual description of the interface.  An example program that does nothing other  than  call  an
          interface usually serves little purpose.

       *  Example programs should be fairly short (preferably less than 100 lines; ideally less than 50 lines).

       *  Example programs should do error checking after system calls and library function calls.

       *  Example programs should be complete, and compile without warnings when compiled with cc -Wall.

       *  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).

       *  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!)

       For some examples of what example programs should look like, see wait(2) and pipe(2).

       If  you  include  a shell session demonstrating the use of a program or other system feature, boldface the user
       input text, to distinguish it from output produced by the system.

   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 .in +4n and .in).

EXAMPLE
       For canonical examples of how man pages in the man-pages package should look, see pipe(2) and fcntl(2).

SEE ALSO
       man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)

COLOPHON
       This  page  is part of release 3.22 of the Linux man-pages project.  A description of the project, and informa-
       tion about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                             2008-10-28                      MAN-PAGES(7)