man-pages


SYNOPSIS
       man [section] title

DESCRIPTION
       This  page describes the conventions that should be employed when writ-
       ing 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, char-
                 acter 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  charac-
       ters  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 individ-
       ual sentences.


              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 prac-
                        tice  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 highlighted 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  easier  to  understand.   If  you

       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 feature_test_macros(7).

       CONFIGURATION Configuration  details  for  a device.  This section nor-
                     mally 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  sec-
                     tion.

       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 man-
                     ual 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
                     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 system 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  func-
                     tion,  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 discouraged.  Generally, it
                     is better not to clutter every page with a list of  (over
                     time  potentially numerous) authors; if you write or sig-
                     nificantly 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  report-
                     ing bugs, place this under the BUGS section.

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

       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 nonbreaking spaces ("\ ") at suitable places  in  the  com-
       mand.  Command 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  nonbreaking  spaces  may  be
       appropriate if the expression is inlined with normal text.

       Any reference to the subject of the current manual page should be writ-
       ten 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  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  eas-
       ier 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 number, formatted in  Roman  (nor-
       mal)  font,  without  any separating spaces (e.g., intro(2)).  The pre-
       ferred 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 conven-
       tions; please write all new pages and patches according to  these  con-
       ventions.

   Example Programs and Shell Sessions
       Manual  pages  can  include example programs demonstrating how to use a
       *  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 exper-
          imentation,  by varying their behavior based on inputs (ideally from
          command-line arguments, or alternatively, via input read by the pro-
          gram).

       *  Example  programs  should  be  laid  out  according to Kernighan and
          Ritchie style, with 4-space indents.  (Avoid the use of TAB  charac-
          ters 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.35 of the Linux man-pages project.  A
       description of the project, and information about reporting  bugs,  can
       be found at http://man7.org/linux/man-pages/.



Linux                             2008-10-28                      MAN-PAGES(7)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.