LinuxGuruz
  • Last 5 Forum Topics
    Replies
    Views
    Last post


The Web Only This Site
  • BOOKMARK

  • ADD TO FAVORITES

  • REFERENCES


  • MARC

    Mailing list ARChives
    - Search by -
     Subjects
     Authors
     Bodies





    FOLDOC

    Computing Dictionary




  • Text Link Ads






  • LINUX man pages
  • Linux Man Page Viewer


    The following form allows you to view linux man pages.

    Command:

    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  documents  the
           user-space API provided by the Linux kernel and the GNU C library.  The
           project thus provides most of the pages in Section 2, as well  as  many
           of the pages that appear in Sections 3, 4, 5, and 7 of the man pages on
           a Linux system.  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 Overview, 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
                            placed (e.g., 7).
    
                  date      The  date of the last revision--remember to change this
                            every time a nontrivial change  is  made  to  the  man
                            page.  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]
                ATTRIBUTES         [Normally only in Sections 2, 3]
                CONFORMING TO
                NOTES
                BUGS
                EXAMPLE
                SEE ALSO
                         command.  All words in  this  line  (including  the  word
                         immediately  following  the "\-") should be in lowercase,
                         except where English or technical terminological  conven-
                         tion dictates otherwise.
    
           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 appears only 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.
    
                         When describing new behavior or new flags  for  a  system
                         call  or  library function, be careful to note the kernel
                         or C library version that  introduced  the  change.   The
                         preferred  method of noting this information for flags is
                         as part of a .TP list, in the following form (here, for a
                         new system call flag):
    
                                 XYZ_FLAG (since Linux 3.7)
                                        Description of flag...
    
                         Including  version  information  is  especially useful to
                         users who are constrained to  using  older  kernel  or  C
                         library  versions  (which is typical in embedded systems,
                         for example).
    
           OPTIONS       describes the command-line options accepted by a  program
                         and  how  they  change its behavior.  This section should
                         appear only for Section 1 and 8 manual pages.
    
           EXIT STATUS   lists the possible exit status values of  a  program  and
           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 pro-
                         grams,  the   default   installation   location   is   in
                         /usr/local,   so   your   base  manual  page  should  use
                         /usr/local as the base.
    
           ATTRIBUTES    A summary of various attributes of the function(s)  docu-
                         mented  on  this page, broken into subsections.  The fol-
                         lowing subsections are defined:
    
                         Multithreading (see pthreads(7))
                                This subsection notes attributes relating to  mul-
                                tithreaded applications:
    
                                *  Whether the function is thread-safe.
    
                                *  Whether the function is a cancellation point.
    
                                *  Whether the function is async-cancel-safe.
    
                                Details  of  these  attributes  can  be  found  in
                                pthreads(7).
    
           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 sec-
                         tion 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
                         matters  only  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.   The
                         preferred  terms  to  use  for  the various standards are
                         (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.
    
                         Where the SEE ALSO list contains many  long  manual  page
                         names, to improve the visual result of the output, it may
                         be useful to employ the .ad l (don't right  justify)  and
                         .nh  (don't  hyphenate) directives.  Hyphenation of indi-
                         vidual page names can be  prevented  by  preceding  words
                         with the string "\%".
    
    
    

    STYLE GUIDE

           The  following  subsections  describe  the preferred style for the man-
           pages project.  For details not covered below, the  Chicago  Manual  of
           Style is usually a good source; try also grepping for preexisting usage
           in the project source tree.
    
       Use of gender-neutral language
           As far as possible, use gender-neutral language  in  the  text  of  man
           pages.  Use of "they" ("them", "themself", "their") as a gender-neutral
           singular pronoun is acceptable.
    
       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);
    
           Complete commands should, if long, be written as an  indented  line  on
           their own, with a blank line before and after the command, 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.)
    
           Control characters should be written in bold face, with no quotes;  for
           example, ^X.
    
       Spelling
           Starting with release 2.59, man-pages follows American spelling conven-
           tions (previously, there was a  random  mix  of  British  and  American
           spellings);  please  write all new pages and patches according to these
           conventions.
    
           Aside from the well-known spelling differences, there are a  few  other
           subtleties to watch for:
    
           *  American  English  tends  to  use  the  forms  "backward", "upward",
              "toward", and so on  rather  than  the  British  forms  "backwards",
              "upwards", "towards", and so on.
    
       Indentation of structure definitions, shell session logs, and so on
           When structure definitions, shell session logs, and so on are  included
           in  running  text,  indent  them by 4 spaces (i.e., a block enclosed by
           .in +4n and .in).
    
       Preferred terms
           The following table lists some preferred terms to  use  in  man  pages,
           mainly to ensure consistency across pages.
    
           Term                 Avoid using              Notes
           ------------------------------------------------------------------
    
           bit mask             bitmask
           built-in             builtin
           Epoch                epoch                    For  the UNIX Epoch
                                                         (00:00:00,  1   Jan
                                                         1970 UTC)
           filename             file name
           filesystem           file system
           hostname             host name
           inode                i-node
           lowercase            lower case, lower-case
           pathname             path name
           pseudoterminal       pseudo-terminal
           privileged port      reserved  port, system
                                port
           real-time            realtime, real time
           run time             runtime
           saved set-group-ID   saved group ID,  saved
                                set-GID
           saved set-user-ID    saved  user  ID, saved
                                set-UID
           set-group-ID         set-GID, setgid
           set-user-ID          set-UID, setuid
           superuser            super user, super-user
           superblock           super   block,  super-
                                block
           timestamp            time stamp
           timezone             time zone
           uppercase            upper case, upper-case
           usable               useable
           user space           userspace
           username             user name
           zeros                zeroes
    
           See also the discussion Hyphenation of attributive compounds below.
    
       Terms to avoid
           The following table lists some terms to avoid using in man pages, along
           with  some  suggested alternatives, mainly to ensure consistency across
           pages.
    
                             page
           minus infinity    negative infinity
           non-root          unprivileged user
           non-superuser     unprivileged user
           nonprivileged     unprivileged
           OS                operating system
           plus infinity     positive infinity
           pty               pseudoterminal
           tty               terminal
           Unices            UNIX systems
           Unixes            UNIX systems
    
       Trademarks
           Use  the  correct spelling and case for trademarks.  The following is a
           list of the correct spellings of various relevant trademarks  that  are
           sometimes misspelled:
    
                DG/UX
                HP-UX
                UNIX
                UnixWare
    
       NULL, NUL, null pointer, and null character
           A  null  pointer  is  a pointer that points to nothing, and is normally
           indicated by the constant NULL.  On the other hand,  NUL  is  the  null
           byte,  a byte with the value 0, represented in C via the character con-
           stant '\0'.
    
           The preferred term for the pointer is "null pointer" or simply  "NULL";
           avoid writing "NULL pointer".
    
           The  preferred  term for the byte is "null byte".  Avoid writing "NUL",
           since it is too easily confused with  "NULL".   Avoid  also  the  terms
           "zero  byte" and "null character".  The byte that terminates a C string
           should be described as "the terminating  null  byte";  strings  may  be
           described  as "null-terminated", but avoid the use of "NUL-terminated".
    
       Hyperlinks
           For hyperlinks, use the .UR/.UE macro pair  (see  groff_man(7)).   This
           produces proper hyperlinks that can be used in a web browser, when ren-
           dering a page with, say:
    
                BROWSER=firefox man -H pagename
    
       Use of e.g., i.e., etc., a.k.a., and similar
           In general, the use of abbreviations such as  "e.g.",  "i.e.",  "etc.",
           "a.k.a."   should  be avoided, in favor of suitable full wordings ("for
           example", "that is", "and so on", "also known as").
    
           The only place where such abbreviations may be acceptable is  in  short
           parenthetical asides (e.g., like this one).
    
               32-bit value
               command-line argument
               floating-point number
               run-time check
               user-space function
               wide-character string
    
       Hyphenation with multi, non, pre, re, sub, and so on
           The  general  tendency in modern English is not to hyphenate after pre-
           fixes such as "multi", "non", "pre", "re", "sub", and  so  on.   Manual
           pages should generally follow this rule when these prefixes are used in
           natural English constructions with simple suffixes.  The following list
           gives some examples of the preferred forms:
    
               interprocess
               multithreaded
               multiprocess
               nonblocking
               nondefault
               nonempty
               noninteractive
               nonnegative
               nonportable
               nonzero
               preallocated
               precreate
               prerecorded
               reestablished
               reinitialize
               rearm
               reread
               subcomponent
               subdirectory
               subsystem
    
           Hyphens  should  be  retained when the prefixes are used in nonstandard
           English words, with trademarks, proper  nouns,  acronyms,  or  compound
           terms.  Some examples:
    
               non-ASCII
               non-English
               non-NULL
               non-real-time
    
           Finally,  note that "re-create" and "recreate" are two different verbs,
           and the former is probably what you want.
    
       Real minus character
           Where a real minus character is required (e.g., for numbers such as -1,
           or  when  writing  options that have a leading dash, such as in ls -l),
           use the following form in the man page source:
    
           Manual pages may 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 necessary and useful only if it demonstrates
              something beyond what can easily be provided in a  textual  descrip-
              tion  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 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 consistency, all example programs should terminate using  either
              of:
    
                   exit(EXIT_SUCCESS);
                   exit(EXIT_FAILURE);
    
              Avoid using the following forms to terminate a program:
    
                  exit(0);
                  exit(1);
                  return n;
    
           *  If  there  is  extensive  explanatory text before the program source
              code, mark off the source code with a  susbsection  heading  Program
              source, as in:
    
                  .SS Program source
    
              Always do this if the explanatory text includes a shell session log.
    
           If you include a shell session log demonstrating the use of  a  program
           or other system feature:
    
           *  Place the session log above the source code listing
           man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)
    
    
    

    Linux 2014-03-16 MAN-PAGES(7)

    
    
  • MORE RESOURCE


  • Linux

    The Distributions





    Linux

    The Software





    Linux

    The News



  • MARKETING






  • Toll Free

webmaster@linuxguruz.com
Copyright © 1999 - 2016 by LinuxGuruz