Seth Woolley's Man Viewer

Manual for man - man 7 man

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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



NAME
       man(1,5,7) - macros to format man(1,5,7) pages

SYNOPSIS
       groff(1,7) -Tascii -man file(1,n) ...

       groff(1,7) -Tps -man file(1,n) ...

       man(1,5,7) [section] title

DESCRIPTION
       This manual page explains the groff(1,7) tmac.an macro package (often called
       the man(1,5,7) macro package) and  related  conventions  for  creating  manual
       (man(1,5,7))  pages.   This  macro  package  should be used by developers when
       writing or porting man(1,5,7) pages for Linux.  It is fairly  compatible  with
       other  versions  of this macro package, so porting man(1,5,7) pages should not
       be a major problem (exceptions include the  NET-2  BSD  release,  which
       uses a totally different macro package called mdoc; see mdoc(7)).

       Note  that  NET-2  BSD  mdoc man(1,5,7) pages can be used with groff(1,7) simply by
       specifying the -mdoc option instead of  the  -man  option.   Using  the
       -mandoc  option is, however, recommended, since this will automatically
       detect which macro package is in(1,8) use.

PREAMBLE
       The first command in(1,8) a man(1,5,7) page (after comment lines) should be

              .TH title section date source manual,

       where:

              title     The title of the man(1,5,7) page (e.g., MAN).

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

              date      The date of the last revision--remember to change this
                        every time(1,2,n) a change is made to  the  man(1,5,7)  page,  since
                        this is the most general way of doing version(1,3,5) control.

              source    The source of the command.

                        For binaries, use something like: GNU, NET-2, SLS Dis-
                        tribution, MCC Distribution.

                        For  system  calls, use the version(1,3,5) of the kernel that
                        you are currently looking at: Linux 0.99.11.

                        For library calls, use the  source  of  the  function:
                        GNU, BSD 4.3, Linux DLL 4.4.1.

              manual    The title of the manual (e.g., Linux Programmer's Man-
                        ual).

       Note that BSD mdoc-formatted pages begin with the Dd command,  not  the
       TH command.

       The manual sections are traditionally defined as follows:

              1 Commands
                        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, such as qsort(3).

              4 Special files
                        Files found in(1,8) /dev.

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

              6 Games

              7 Conventions and miscellaneous
                        A description of the standard file(1,n) system layout, net-
                        work  protocols, ASCII and other character codes, this
                        man(1,5,7) page, and other things.

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

              9 Kernel routines
                        This  is  an  obsolete  manual  section.   Once it was
                        thought a good idea to document the Linux kernel here,
                        but  in(1,8)  fact very little has been documented, and the
                        documentation that exists is outdated  already.  There
                        are  better sources of information for kernel develop-
                        ers.

SECTIONS
       Sections are started with .SH followed by the  heading  name.   If  the
       name  contains  spaces  and appears on the same line as .SH, then place
       the heading  in(1,8)  double  quotes.   Traditional  or  suggested  headings
       include:  NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, EXIT STATUS, ERROR
       HANDLING, ERRORS, OPTIONS, USAGE, EXAMPLES, FILES,  ENVIRONMENT,  DIAG-
       NOSTICS,  SECURITY,  CONFORMING  TO, NOTES, BUGS, AUTHOR, and SEE ALSO.
       Where a traditional heading would apply, please use it;  this  kind  of
       consistency  can  make  the information easier to understand.  However,
       feel free to create your own headings if(3,n) they  make  things  easier  to
       understand.   The  only  required  heading is NAME, which should be the
       first section and be followed on the next line by a one  line  descrip-
       tion of the program:

              .SH NAME
              chess \- the game of chess

       It  is extremely important that this format is followed, and that there
       is a backslash before the single dash which follows the  command  name.
       This  syntax  is used by the makewhatis(8) program to create a database
       of short command descriptions for the  whatis(1)  and  apropos(1)  com-
       mands.

       Some other traditional sections have the following contents:

       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.

       DESCRIPTION   gives  an  explanation  of what the command, 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
                     options  use  the OPTIONS section.  If there is some kind
                     of input grammar or complex set(7,n,1 builtins) of subcommands,  consider
                     describing  them  in(1,8)  a  separate USAGE section (and just
                     place an overview in(1,8) the DESCRIPTION section).

       RETURN VALUE  gives a list of  the  values  the  library  routine  will
                     return  to the caller and the conditions that cause these
                     values to be returned.

       EXIT STATUS   lists the possible exit(3,n,1 builtins) status values or  a  program  and
                     the conditions that cause these values to be returned.

       OPTIONS       describes  the  options  accepted  by the program and how
                     they change its behavior.

       USAGE         describes the grammar of any sublanguage this implements.

       EXAMPLES      provides  one  or more examples describing how this func-
                     tion, file(1,n) or command is used.

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

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

       DIAGNOSTICS   gives an overview of the most common error(8,n)  messages  and
                     how  to cope with them.  You don't need to explain system
                     error(8,n) messages or fatal signals that  can  appear  during
                     execution  of  any program unless they're special in(1,8) some
                     way to your program.

       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(3,n)  they aren't obvious.  Discussing security
                     in(1,8) a separate section isn't necessary; if(3,n) it's easier  to
                     understand,  place security information in(1,8) the other sec-
                     tions (such as the DESCRIPTION or USAGE  section).   How-
                     ever, please include security information somewhere!

       CONFORMING TO describes any standards or conventions this implements.

       NOTES         provides miscellaneous notes.

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

       AUTHOR        lists authors of the documentation or program so you  can
                     mail(1,8) in(1,8) bug reports.

       SEE ALSO      lists  related  man(1,5,7) pages in(1,8) alphabetical order, possibly
                     followed by other related pages  or  documents.   Conven-
                     tionally this is the last section.

FONTS
       Although there are many arbitrary conventions for man(1,5,7) pages in(1,8) the UNIX
       world, the  existence  of  several  hundred  Linux-specific  man(1,5,7)  pages
       defines our font standards:

              For functions, the arguments are always specified using italics,
              even in(1,8) the SYNOPSIS section, where the rest of the function  is
              specified in(1,8) bold:
              int myfunction(int argc, char **argv);

              Filenames  are  always  in(1,8) italics (e.g., /usr/include/stdio.h),
              except in(1,8) the SYNOPSIS section, where included files are in(1,8) bold
              (e.g., #include <stdio.h>).

              Special  macros,  which  are  usually in(1,8) upper case, are in(1,8) bold
              (e.g., MAXINT).

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

              Any reference to another man(1,5,7) page (or to the subject of the cur-
              rent man(1,5,7) page) is in(1,8) bold.  If  the  manual  section  number  is
              given,  it  is  given in(1,8) Roman (normal) font, without any spaces
              (e.g., man(1,5,7)(7)).

       The commands to select(2,7,2 select_tut) the type face are:

       .B  Bold

       .BI Bold alternating with italics (especially useful for function spec-
           ifications)

       .BR Bold  alternating  with  Roman  (especially useful for referring to
           other manual pages)

       .I  Italics

       .IB Italics alternating with bold

       .IR Italics alternating with Roman

       .RB Roman alternating with bold

       .RI Roman alternating with italics

       .SB Small alternating with bold

       .SM Small (useful for acronyms)

       Traditionally, each command can have up to six arguments, but  the  GNU
       implementation  removes  this limitation (you might still want to limit
       yourself to 6 arguments for portability's sake).  Arguments are  delim-
       ited by spaces.  Double quotes can be used to specify an argument which
       contains spaces.  All of the arguments will be  printed  next  to  each
       other  without  intervening spaces, so that the .BR command can be used
       to specify a word in(1,8) bold followed by a mark of punctuation  in(1,8)  Roman.
       If no arguments are given, the command is applied to the following line
       of text.

OTHER MACROS AND STRINGS
       Below are other relevant macros and predefined strings.   Unless  noted
       otherwise,  all  macros  cause  a break (end the current line of text).
       Many of these macros set(7,n,1 builtins) or use the "prevailing indent."  The "prevail-
       ing  indent"  value  is  set(7,n,1 builtins)  by  any macro with the parameter i below;
       macros may omit i in(1,8) which case the current prevailing indent  will  be
       used.   As  a  result,  successive indented paragraphs can use the same
       indent without re-specifying the indent value.  A normal (non-indented)
       paragraph  resets the prevailing indent value to its default value (0.5
       inches).  By default a given indent is measured in(1,8) ens; try to  ens  or
       ems as units(1,7) for indents, since these will automatically adjust to font
       size changes.  The other key macro definitions are:

   Normal Paragraphs
       .LP      Same as .PP (begin a new paragraph).

       .P       Same as .PP (begin a new paragraph).

       .PP      Begin a new paragraph and reset(1,7,1 tput) prevailing indent.

   Relative Margin Indent
       .RS i    Start relative margin indent - moves the left margin i to  the
                right  (if(3,n) i is omitted, the prevailing indent value is used).
                A new prevailing indent is set(7,n,1 builtins) to 0.5 inches.   As  a  result,
                all  following  paragraph(s) will be indented until the corre-
                sponding .RE.

       .RE      End relative margin indent and restores the previous value  of
                the prevailing indent.

   Indented Paragraph Macros
       .HP i    Begin  paragraph  with a hanging indent (the first line of the
                paragraph is at the left margin of normal paragraphs, and  the
                rest of the paragraph's lines are indented).

       .IP x i  Indented paragraph with optional hanging tag.  If the tag x is
                omitted, the entire following paragraph is indented by i.   If
                the  tag  x  is provided, it is hung at the left margin before
                the following indented paragraph (this is just like .TP except
                the  tag  is included with the command instead of being on the
                following line).  If the tag is too long, the text  after  the
                tag will be moved down to the next line (text will not be lost
                or garbled).  For bulleted lists, use  this  macro  with  \(bu
                (bullet) or \(em (em dash) as the tag, and for numbered lists,
                use the number or letter followed by a period as the tag; this
                simplifies translation to other formats.

       .TP i    Begin  paragraph  with  hanging  tag.  The tag is given on the
                next line, but its results are like those of the .IP  command.

   Hypertext Link Macros
       (Feature  supported  with  groff(1,7) only.)  In order to use hypertext link(1,2)
       macros, it is necessary to load(7,n) the www.tmac macro  package.   Use  the
       request .mso www.tmac to do this.

       .URL url link(1,2) trailer
                Inserts  a  hypertext  link(1,2) to the URI (URL) url, with link(1,2) as
                the text of the link.  The trailer will be printed immediately
                afterwards.   When  generating HTML this should translate into
                the HTML command <A HREF="url">link(1,2)</A>trailer.

                This and other related macros are new, and many tools won't do
                anything  with  them,  but  since many tools (including troff)
                will simply ignore undefined macros (or at worst insert  their
                text) these are safe to insert.

       A number of other link(1,2) macros are available.  See groff_www(7) for more
       details.

   Miscellaneous Macros
       .DT      Reset tabs to default tab values (every 0.5 inches); does  not
                cause a break.

       .PD d    Set  inter-paragraph  vertical  distance  to  d  (if(3,n)  omitted,
                d=0.4v); does not cause a break.

       .SS t    Subheading t (like .SH, but used for  a  subsection  inside  a
                section).

   Predefined Strings
       The man(1,5,7) package has the following predefined strings:

       \*R    Registration Symbol: 

       \*S    Change to default font size

       \*(Tm  Trademark Symbol: tm

       \*(lq  Left angled doublequote: "

       \*(rq  Right angled doublequote: "

SAFE SUBSET
       Although  technically  man(1,5,7) is a troff macro package, in(1,8) reality a large
       number of other tools process man(1,5,7) page files that don't  implement  all
       of  troff's  abilities.   Thus, it's best to avoid some of troff's more
       exotic abilities where possible to permit these  other  tools  to  work
       correctly.   Avoid  using the various troff preprocessors (if(3,n) you must,
       go ahead and use tbl(1), but try to use the IP and TP commands  instead
       for  two-column  tables).   Avoid  using computations; most other tools
       can't process them.  Use simple commands that are easy to translate  to
       other  formats.   The  following  troff  macros are believed to be safe
       (though in(1,8) many cases they will be ignored by translators): \", .,  ad,
       bp, br, ce, de, ds, el, ie, if(3,n), fi, ft, hy, ig, in(1,8), na, ne, nf, nh, ps,
       so, sp, ti, tr.

       You may also use many troff escape sequences (those sequences beginning
       with  \).   When  you need to include the backslash character as normal
       text, use \e.  Other sequences you may use, where x or xx are any char-
       acters and N is any digit, include: \', \`, \-, \., \", \%, \*x, \*(xx,
       \(xx, \$N,  \nx,  \n(xx,  \fx,  and  \f(xx.   Avoid  using  the  escape
       sequences for drawing graphics.

       Do  not use the optional parameter for bp (break page).  Use only posi-
       tive values for sp (vertical space).  Don't define a  macro  (de)  with
       the  same name as a macro in(1,8) this or the mdoc macro package with a dif-
       ferent meaning; it's likely that such redefinitions  will  be  ignored.
       Every  positive  indent  (in(1,8)) should be paired with a matching negative
       indent (although you should be using the RS  and  RE  macros  instead).
       The  condition  test  (if(3,n),ie) should only have 't' or 'n' as the condi-
       tion.  Only translations (tr) that can be ignored should be used.  Font
       changes  (ft and the \f escape sequence) should only have the values 1,
       2, 3, 4, R, I, B, P, or CW (the ft command may  also  have  no  parame-
       ters).

       If  you  use  capabilities beyond these, check the results carefully on
       several tools.  Once you've confirmed that the additional capability is
       safe,  let  the maintainer of this document know about the safe command
       or sequence that should be added to this list.

NOTES
       By all means include full URLs (or URIs) in(1,8) the text itself; some tools
       such  as  man2html(1) can automatically turn them into hypertext links.
       You can also use the new URL macro to identify links to related  infor-
       mation.   If you include URLs, use the full URL (e.g., <http://www.ker-
       nelnotes.org>) to ensure that tools can automatically find the URLs.

       Tools processing these files should open(2,3,n) the file(1,n) and examine the first
       non-whitespace  character.  A  period  (.)  or  single quote (') at the
       beginning of a line indicates a troff-based file(1,n) (such as man(1,5,7) or mdoc).
       A left angle bracket (<) indicates an SGML/XML-based file(1,n) (such as HTML
       or Docbook). Anything else suggests simple ASCII text (e.g., a "catman"
       result).

       Many man(1,5,7) pages begin with '\" followed by a space and a list of charac-
       ters, indicating how the page is to be preprocessed.  For portability's
       sake  to  non-troff  translators we recommend that you avoid using any-
       thing other than tbl(1), and Linux can detect that automatically.  How-
       ever,  you  might want to include this information so your man(1,5,7) page can
       be handled by other (less(1,3) capable) systems.  Here are  the  definitions
       of the preprocessors invoked by these characters:

       e  eqn(1)

       g  grap(1)

       p  pic(1)

       r  refer(1)

       t  tbl(1)

       v  vgrind(1)

FILES
       /usr/share/groff(1,7)/[*/]tmac/tmac.an
       /usr/man(1,5,7)/whatis

BUGS
       Most  of  the  macros describe formatting (e.g., font type and spacing)
       instead of marking semantic content (e.g., this text is a reference  to
       another page), compared to formats like mdoc and DocBook (even HTML has
       more semantic markings).  This situation makes it harder  to  vary  the
       man(1,5,7) format for different media, to make the formatting consistent for a
       given media, and to automatically insert cross-references.  By sticking
       to  the  safe  subset  described above, it should be easier to automate
       transitioning to a different reference page format in(1,8) the future.

       The Sun macro TX is not implemented.

AUTHORS
       -- James Clark (jjc@jclark.com) wrote the implementation of  the  macro
          package.

       -- Rickard  E.  Faith  (faith@cs.unc.edu)  wrote the initial version(1,3,5) of
          this manual page.

       -- Jens Schweikhardt (schweikh@noc.fdn.de)  wrote  the  Linux  Man-Page
          Mini-HOWTO (which influenced this manual page).

       -- David  A.  Wheeler  (dwheeler@ida.org)  heavily modified this manual
          page, such as adding detailed information on sections and macros.

SEE ALSO
       apropos(1), groff(1,7)(1), man(1,5,7)(1),  man2html(1),  mdoc(7),  mdoc.samples(7),
       groff_www(7), whatis(1)



Linux                             2004-07-27                            MAN(7)

References for this manual (incoming links)