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  consis-
                        tently,  and  so was probably worse than including no version num-
                        ber.  Henceforth, avoid including a version number.)

                        For library calls that are part of glibc or one of the other  com-
                        mon  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  sec-
       tions 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 must, you  can  create  your
       own  headings if they make things easier to understand (this can be especially use-
       ful 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 informa-
                     tion 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  pro-
                     cess  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 pol-
                     icy 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  inter-
                     faces 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  con-
                     forms  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 speci-
                     fied 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 com-
                     monly 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  ques-
                     tionable activities.

       EXAMPLE       provides  one  or more examples describing how this function, file or
                     command is used.  For details on writing example programs, see  Exam-
                     ple 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 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.

       SEE ALSO      provides a comma-separated list of related man pages, ordered by sec-
                     tion number and then alphabetically 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 SYNOP-
       SIS 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 stan-
       dard 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 for-
       mat,  for example, man 7 man-pages.  In this case, it may be worth using non-break-
       ing spaces ("\ ") at suitable places in the command.   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 non-breaking spaces may be appropriate if  the  expres-
       sion 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 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 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 number, formatted in Roman (normal) font, without any sepa-
       rating 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) cre-
       ate 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 provided 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  func-
          tion 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 information about reporting bugs, can be found at http://www.ker-
       nel.org/doc/man-pages/.



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

Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2018-01-24 07:32 @127.0.0.1 CrawledBy CCBot/2.0 (http://commoncrawl.org/faq/)
Valid XHTML 1.0!Valid CSS!