groff -mdoc file ...
     A complete reference for writing UNIX manual pages with the -mdoc macro
     package; a content-based and domain-based formatting package for GNU
     troff(1).  Its predecessor, the -man(7) package, addressed page layout
     leaving the manipulation of fonts and other typesetting details to the
     individual author.  In -mdoc, page layout macros make up the page
     structure domain which consists of macros for titles, section headers,
     displays and lists - essentially items which affect the physical position
     of text on a formatted page.  In addition to the page structure domain,
     there are two more domains, the manual domain and the general text do
     main.  The general text domain is defined as macros which perform tasks
     such as quoting or emphasizing pieces of text.  The manual domain is de
     fined as macros that are a subset of the day to day informal language
     used to describe commands, routines and related UNIX files.  Macros in
     the manual domain handle command names, command line arguments and op
     tions, function names, function parameters, pathnames, variables, cross
     references to other manual pages, and so on.  These domain items have
     value for both the author and the future user of the manual page.  It is
     hoped the consistency gained across the manual set will provide easier
     translation to future documentation tools.
     Throughout the UNIX manual pages, a manual entry is simply referred to as
     a man page, regardless of actual length and without sexist intention.
     The material presented in the remainder of this document is outlined as
     follows:
           1.   TROFF IDIOSYNCRASIES
                Macro Usage
                Passing Space Characters in an Argument
                Trailing Blank Space Characters
                Escaping Special Characters
                Other Possible Pitfalls
           2.   A MANUAL PAGE TEMPLATE
           3.   CONVENTIONS
           4.   TITLE MACROS
           5.   INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS
                What's in a Name...
                General Syntax
           6.   MANUAL DOMAIN
                Addresses
                Author Name
                Arguments
                Configuration Declarations (Section Four Only)
                Command Modifiers
                Defined Variables
                Errno's
                Environment Variables
                Literals
                Names
                Options
                Pathnames
                Standards
                Variable Types
                Variables
                Manual Page Cross References
           7.   GENERAL TEXT DOMAIN
                AT&T Macro
                BSD Macro
                NetBSD Macro
                FreeBSD Macro
                OpenBSD Macro
                BSD/OS Macro
                UNIX Macro
                Emphasis Macro
                Font Mode
                Enclosure and Quoting Macros
                No-Op or Normal Text Macro
                No-Space Macro
                Section Cross References
                Symbolics
                Mathematical Symbols
                References and Citations
                Trade Names (or Acronyms and Type Names)
                Extended Arguments
           8.   PAGE STRUCTURE DOMAIN
                Section Headers
                Subsection Headers
                Paragraphs and Line Spacing
                Keeps
                Examples and Displays
                Lists and Columns
           9.   MISCELLANEOUS MACROS
           10.  PREDEFINED STRINGS
           11.  DIAGNOSTICS
           12.  FORMATTING WITH GROFF, TROFF, AND NROFF
           13.  FILES
           14.  SEE ALSO
           15.  BUGS
     The -mdoc package attempts to simplify the process of writing a man page.
     Theoretically, one should not have to learn the dirty details of GNU
     troff(1) to use -mdoc; however, there are a few limitations which are un
     avoidable and best gotten out of the way.  And, too, be forewarned, this
     more) characters as a macro name.  A single starting dot followed by
     nothing is ignored.  To place a `.' (dot character) at the beginning of
     an input line in some context other than a macro invocation, precede the
     `.' (dot) with the `\&' escape sequence.  The `\&' translates literally
     to a zero-width space, and is never displayed in the output.
     In general, GNU troff(1) macros accept an unlimited number of arguments
     (contrary to other versions of troff which can't handle more than nine
     arguments).  In limited cases, arguments may be continued or extended on
     the next line (See Extended Arguments below).  Almost all macros handle
     quoted arguments (see Passing Space Characters in an Argument below).
     Most of the -mdoc general text domain and manual domain macros are spe
     cial in that their argument lists are parsed for callable macro names.
     This means an argument on the argument list which matches a general text
     or manual domain macro name and is determined to be callable will be exe
     cuted or called when it is processed.  In this case the argument, al
     though the name of a macro, is not preceded by a `.' (dot).  It is in
     this manner that many macros are nested; for example the option macro,
     `.Op', may call the flag and argument macros, `Fl' and `Ar', to specify
     an optional flag with an argument:
           [-s bytes]
             is produced by `.Op Fl s Ar bytes'
     To prevent a string from being interpreted as a macro name, precede the
     string with the escape sequence `\&':
           [Fl s Ar bytes]
             is produced by `.Op \&Fl s \&Ar bytes'
     Here the strings `Fl' and `Ar' are not interpreted as macros.  Macros
     whose argument lists are parsed for callable arguments are referred to as
     parsed and macros which may be called from an argument list are referred
     to as callable throughout this document.  This is a technical faux pas as
     almost all of the macros in -mdoc are parsed, but as it was cumbersome to
     constantly refer to macros as being callable and being able to call other
     macros, the term parsed has been used.
   Passing Space Characters in an Argument
     Sometimes it is desirable to give as an argument a string containing one
     or more blank space characters.  This may be necessary to specify argu
     ments to macros which expect particular arrangement of items in the argu
     ment list.  Additionally, it makes -mdoc working faster.  For example,
     the function macro `.Fn' expects the first argument to be the name of a
     function and any remaining arguments to be function parameters.  As
     ANSI C stipulates the declaration of function parameters in the parenthe
     sized parameter list, each parameter is guaranteed to be at minimum a two
     word string.  For example, int foo.
     There are two possible ways to pass an argument which contains an embed
     ded space.  One way of passing a string containing blank spaces is to use
     the hard or unpaddable space character `\ ', that is, a blank space pre
     ceded by the escape character `\'. This method may be used with any macro
     but has the side effect of interfering with the adjustment of text over
     the length of a line.  Troff sees the hard space as if it were any other
             is created by `.Fn fetch char\ *str'
                   fetch(char *str)
                     can also be created by `.Fn fetch "char *str"'
             If the `\' before the space resp. the double quotes were omitted,
             `.Fn' would see three arguments, and the result would be:
                   fetch(char, *str)
           Trailing Blank Space Characters
             Troff can be confused by blank space characters at the end of a
             line.  It is a wise preventive measure to globally remove all
             blank spaces from <blank-space><end-of-line> character sequences.
             Should the need arise to force a blank character at the end of a
             line, it may be forced with an unpaddable space and the `\&' es
             cape character.  For example, `string\ \&'.
           Escaping Special Characters
             Special characters like the newline character `\n' are handled by
             replacing the `\' with `\e' (e.g. `\en') to preserve the back
             slash.
           Other Possible Pitfalls
             A warning is emitted when an empty input line is found outside of
             displays (see below).  Use `.sp' instead.  (Well, it is even bet
             ter to use -mdoc macros to avoid the usage of low-level com
             mands.)
             Leading spaces will cause a break and are output directly.  Avoid
             this behaviour if possible.  Similarly, do not use more than one
             space character between words in an ordinary text line; contrary
             to other text formatters, they are not replaced with a single
             space.
             You can't pass `"' directly as an argument.  Use `\*[q]' (or
             `\*q') instead.
             By default, troff(1) inserts two space characters after a punctu
             ation mark closing a sentence; characters like `)' or `'' are
             treated transparently, not influencing the sentence-ending be
             haviour.  To change this, insert `\&' before or after the dot:
                   The
                   .Ql .
                   character.
                   .Pp
                   The
                   .Ql \&.
                   character.
                   .Pp
                   .No test .
                   test
                   .Pp
                   .No test.
                   test
                   test. test
             As can be seen in the first and third line, -mdoc handles punctu
             ation characters specially in macro arguments.  This will be ex
             plained in section General Syntax below.  In the same way, you
             have to protect trailing full stops of abbreviations with a
             trailing zero-width space: `e.g.\&'.
             A comment in the source file of a man page can be either started
             with `.\"' on a single line, `\"' after some input, or `\#' any
             where (the latter is a GNU troff(1) extension); the rest of such
             a line is ignored.
     The body of a man page is easily constructed from a basic template:
           .\" The following requests are required for all man pages.
           .Dd Month day, year
           .Os [OPERATING_SYSTEM] [version/release]
           .Dt DOCUMENT_TITLE [section number] [architecture/volume]
           .Sh NAME
           .Nm name
           .Nd one line description of name
           .\" This next request is for sections 2 and 3 only.
           .\" .Sh LIBRARY
           .Sh SYNOPSIS
           .Sh DESCRIPTION
           .\" The following requests should be uncommented and
           .\" used where appropriate.
           .\" .Sh IMPLEMENTATION NOTES
           .\" This next request is for sections 2, 3 and 9 function
           .\" return values only.
           .\" .Sh RETURN VALUES
           .\" This next request is for sections 1, 6, 7 and 8 only.
           .\" .Sh ENVIRONMENT
           .\" .Sh FILES
           .\" .Sh EXAMPLES
           .\" This next request is for sections 1, 6, 7, 8 and 9 only
           .\"     (command return values (to shell) and
           .\"     fprintf/stderr type diagnostics).
           .\" .Sh DIAGNOSTICS
           .\" .Sh COMPATIBILITY
           .\" This next request is for sections 2, 3 and 9 error
           .\"     and signal handling only.
           .\" .Sh ERRORS
           .\" .Sh SEE ALSO
           .\" .Sh STANDARDS
           .\" .Sh HISTORY
           .\" .Sh AUTHORS
           .\" .Sh BUGS
     The first items in the template are the macros `.Dd', `.Os', and `.Dt';
     the document date, the operating system the man page or subject source is
     developed or modified for, and the man page title (in upper case) along
     with the section of the manual the page belongs in.  These macros identi
     fy the page and are discussed below in TITLE MACROS.
     brackets.  An ellipsis (`...') represents zero or more additional argu
     ments.  Alternative values for a parameter are separated with `|'. If
     there are alternative values for a mandatory parameter, braces are used
     (together with `|') to enclose the value set.  Meta-variables are speci
     fied within angles.
     Example:
           .Xx <foo> [-test1 [-test2 | -test3]] ...
     Except stated explicitly, all macros are parsed and callable.
     Most macros have a default width value which can be used to specify a la
     bel width (-width) or offset (-offset) for the `.Bl' and `.Bd' macros.
     It is recommended not to use this rather obscure feature to avoid depen
     dencies on local modifications of the -mdoc package.
     The title macros are part of the page structure domain but are presented
     first and separately for someone who wishes to start writing a man page
     yesterday.  Three header macros designate the document title or manual
     page title, the operating system, and the date of authorship.  These
     macros are called once at the very beginning of the document and are used
     to construct headers and footers only.
     .Dt [<document title>] [<section number>] [<volume>]
             The document title is the subject of the man page and must be in
             CAPITALS due to troff limitations.  If omitted, `UNTITLED' is
             used.  The section number may be a number in the range 1, ..., 9
             or `unass', `draft', or `paper'. If it is specified, and no vol
             ume name is given, a default volume name is used.
             Under , the following sections are defined:
                   1
                   2
                   3
                   4
                   5
                   6
                   7
                   8
                   9
             A volume name may be arbitrary or one of the following:
                   USD
                   PS1
                   AMD
                   SMM
                   URM
                   PRM
                   KM
                   IND
                   LOCAL
                   CON
                   luna68k, m68k mmeye, mvme68k, news68k, newsmips, next68k
                   powerpc, prep, sgimips, sh3, sparc x68k
             In the following examples, the left (which is identical to the
             right) and the middle part of the manual page header strings are
             shown.
                   .Dt FOO 7
                     `FOO(7)' `System Reference Manual'
                   .Dt FOO 2 mac68k
                     `FOO(2)' `System Programmer's Manual (mac68k
                     Architecture)'
                   .Dt FOO "" bar
                     `FOO' `bar'
             Local, OS-specific additions might be found in the file
             mdoc.local; look for strings named `volume-ds-XXX' (for the for
             mer type) and `volume-as-XXX' (for the latter type); `XXX' then
             denotes the keyword to be used with the `.Dt' macro.
             This macro is neither callable nor parsed.
     .Os [<operating system>] [<release>]
             If the first parameter is empty, the default `' is used.  This
             may be overridden in the local configuration file, mdoc.local. In
             general, the name of the operating system should be the common
             acronym, e.g. BSD or ATT. The release should be the standard re
             lease nomenclature for the system specified.  In the following
             table, the possible second arguments for some predefined operat
             ing systems are listed.  Similar to `.Dt', local additions might
             be defined in mdoc.local; look for strings named `operating-
             system-XXX-YYY', where `XXX' is the acronym for the operating
             system and `YYY' the release ID.
                   ATT
                     7th, 7, III, 3, V, V.2, V.3, V.4
                   BSD
                     3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r, 4.3R, 4.4
                   NetBSD
                     0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2, 1.2a, 1.2b,
                     1.2c, 1.2d, 1.2e, 1.3, 1.3a, 1.4, 1.5
                   FreeBSD
                     1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1, 2.1.5, 2.1.6,
                     2.1.7, 2.2, 2.2.1, 2.2.2, 2.2.5, 2.2.6, 2.2.7, 2.2.8,
                     3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 4.0, 4.1, 4.2, 5.0
             For ATT, an unknown second parameter will be replaced with the
             string UNIX; for the other predefined acronyms it will be ignored
             and a warning message emitted.  Unrecognized arguments are dis
             played as given in the page footer.  For instance, a typical
             footer might be:
                   .Os BSD 4.3
             This macro is neither callable nor parsed.
     .Dd [<month> <day>, <year>]
             If `Dd' has no arguments, `Epoch' is used for the date string.
             If it has exactly three arguments, they are concatenated, sepa
             rated with unbreakable space:
                   .Dd January 25, 2001
             Otherwise, the current date is used, ignoring the parameters.
             This macro is neither callable nor parsed.
   What's in a Name Ns ...
     The manual domain macro names are derived from the day to day informal
     language used to describe commands, subroutines and related files.
     Slightly different variations of this language are used to describe the
     three different aspects of writing a man page.  First, there is the de
     scription of -mdoc macro request usage.  Second is the description of a
     UNIX command with -mdoc macros, and third, the description of a command
     to a user in the verbal sense; that is, discussion of a command in the
     text of a man page.
     In the first case, troff(1) macros are themselves a type of command; the
     general syntax for a troff command is:
           .Xx argument1 argument2 ...
     `.Xx' is a macro command or request, and anything following it are argu
     ments to be processed.  In the second case, the description of a UNIX
     command using the content macros is a bit more involved; a typical
     SYNOPSIS command line might be displayed as:
           filter [-flag] <infile><outfile>
     Here, filter is the command name and the bracketed string -flag is a flag
     argument designated as optional by the option brackets.  In -mdoc terms,
     <infile> and <outfile> are called meta arguments; in this example, the
     user has to replace the meta expressions given in angle brackets with re
     al file names.  Note that in this document meta arguments are used to de
     scribe -mdoc commands; in most man pages, meta variables are not specifi
     cally written with angle brackets.  The macros which formatted the above
     example:
           .Nm filter
           .Op Fl flag
           .Ao Ar infile Ac Ao Ar outfile Ac
     In the third case, discussion of commands and command syntax includes
     both examples above, but may add more detail.  The arguments <infile> and
     <outfile> from the example above might be referred to as operands or file
     arguments. Some command line argument lists are quite long:
           make
           .Nm make
           .Op Fl eiknqrstv
           .Op Fl D Ar variable
           .Op Fl d Ar flags
           .Op Fl f Ar makefile
           .Op Fl I Ar directory
           .Op Fl j Ar max_jobs
           .Op Ar variable Ns = Ns Ar value
           .Bk
           .Op Ar target ...
           .Ek
     The `.Bk' and `.Ek' macros are explained in Keeps.
   General Syntax
     The manual domain and general text domain macros share a similar syntax
     with a few minor deviations; most notably, `.Ar', `.Fl', `.Nm', and `.Pa'
     differ only when called without arguments; and `.Fn' and `.Xr' impose an
     order on their argument lists.  All content macros are capable of recog
     nizing and properly handling punctuation, provided each punctuation char
     acter is separated by a leading space.  If a request is given:
           .Ar sptr, ptr),
     The result is:
           sptr, ptr),
     The punctuation is not recognized and all is output in the font used by
     `.Ar'. If the punctuation is separated by a leading white space:
           .Ar sptr , ptr ) ,
     The result is:
           sptr, ptr),
     The punctuation is now recognized and output in the default font distin
     guishing it from the argument strings.  To remove the special meaning
     from a punctuation character escape it with `\&'.
     Troff is limited as a macro language, and has difficulty when presented
     with a string containing a member of the mathematical, logical or quota
     tion set:
                 {+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
     The problem is that troff may assume it is supposed to actually perform
     the operation or evaluation suggested by the characters.  To prevent the
     accidental evaluation of these characters, escape them with `\&'. Typical
     syntax is shown in the first content macro displayed below, `.Ad'.
   Addresses
     The address macro identifies an address construct.
                                                                       .Ad f1
                                                                         , f2
                                                                         , f3
                                                                         :
                                                                         f1,
                                                                         f2,
                                                                         f3:
                                                                                        .Ad
                                                                                          ad
                                                                                          dr
                                                                                          )
                                                                                          )
                                                                                          ,
                                                                                          addr)),
                                                                         The
                                                                         de
                                                                         fault
                                                                         width
                                                                         is
                                                                         12n.
                                                                       Author
                                                                         Name
                                                                         The
                                                                         `.An'
                                                                         macro
                                                                         is
                                                                         used
                                                                         to
                                                                         spec
                                                                         ify
                                                                         the
                                                                         name
                                                                         of
                                                                         the
                                                                         au
                                                                         thor
                                                                         of
                                                                         the
                                                                         item
                                                                         being
                                                                         docu
                                                                         ment
                                                                         ed,
                                                                         or
                                                                         the
                                                                         name
                                                                         of
                                                                         the
                                                                         au
                                                                         thor
                                                                         of
                                                                         the
                                                                               ...
                                                                                        .An
                                                                                          "Joe
                                                                                          Au
                                                                                          thor"
                                                                                          Joe
                                                                                          Author
                                                                                        .An
                                                                                          "Joe
                                                                                          Au
                                                                                          thor"
                                                                                          ,
                                                                                          Joe
                                                                                          Author,
                                                                                        .An
                                                                                          "Joe
                                                                                          Au
                                                                                          thor"
                                                                                          Aq
                                                                                          no
                                                                                          body@FreeB
                                                                                          SD.org
                                                                                          Joe
                                                                                          Author
                                                                                          <nobody@FreeBSD.org>
                                                                                        .An
                                                                                          "Joe
                                                                                          Au
                                                                                          thor"
                                                                                          )
                                                                                          )
                                                                                          ,
                                                                                          Joe
                                                                                          Author)),
                                                                         The
                                                                         de
                                                                         fault
                                                                         width
                                                                         is
                                                                         12n.
                                                                         In
                                                                         the
                                                                         AUTHORS
                                                                         sec
                                                                         tion,
                                                                         the
                                                                         `.An'
                                                                         re
                                                                         quest
                                                                         caus
                                                                         ap
                                                                         pear
                                                                         on
                                                                         its
                                                                         own
                                                                         line.
                                                                         If
                                                                         this
                                                                         is
                                                                         not
                                                                         de
                                                                         sir
                                                                         able,
                                                                               .An -nosplit
                                                                         call
                                                                         will
                                                                         turn
                                                                         this
                                                                         off.
                                                                         To
                                                                         turn
                                                                         split
                                                                         ting
                                                                         back
                                                                         on,
                                                                         write
                                                                               .An -split
                                                                       Argu
                                                                         ments
                                                                         The
                                                                         .Ar
                                                                         argu
                                                                         ment
                                                                         macro
                                                                         may
                                                                         be
                                                                         used
                                                                         when
                                                                         ever
                                                                         an
                                                                         argu
                                                                         ment
                                                                         is
                                                                         ref
                                                                         er
                                                                         enced.
                                                                         If
                                                                         called
                                                                         with
                                                                         out
                                                                               .Ar
                                                                               [<argument>]
                                                                               ...
                                                                                        .Ar
                                                                                          file ...
                                                                                        .Ar
                                                                                          file1
                                                                                          file1
                                                                                        .Ar
                                                                                          file1
                                                                                          .
                                                                                          file1.
                                                                                        .Ar
                                                                                          file1
                                                                                          file2
                                                                                          file1
                                                                                          file2
                                                                                        .Ar
                                                                                          f1
                                                                                          f2
                                                                                          f3
                                                                                          :
                                                                                          f1
                                                                                          f2
                                                                                          f3:
                                                                                        .Ar
                                                                                          file
                                                                                          )
                                                                                          )
                                                                                          ,
                                                                                          file)),
                                                                         The
                                                                         de
                                                                         fault
                                                                         width
                                                                         is
                                                                         12n.
                                                                       Config
                                                                         ura
                                                                         tion
                                                                         Dec
                                                                         lara
                                                                         tion
                                                                         (Sec
                                                                         tion
                                                                         Four
                                                                         Only)
                                                                         The
                                                                         `.Cd'
                                                                         macro
                                                                         is
                                                                         for a
                                                                         de
                                                                         vice
                                                                         in
                                                                         ter
                                                                         face
                                                                         in a
                                                                         sec
                                                                         tion
                                                                         four
                                                                         manu
                                                                         al.
                                                                               Usage:
                                                                               .Cd
                                                                               <argument>
                                                                               ...
                                                                                        .Cd
                                                                                          "de
                                                                                          vice
                                                                                          le0
                                                                                          at
                                                                                          scode?"
                                                                                          device
                                                                                          le0
                                                                                          at
                                                                                          scode?
                                                                         In
                                                                         the
                                                                         SYNOPSIS
                                                                         sec
                                                                         tion
                                                                         a
                                                                         `.Cd'
                                                                         re
                                                                         quest
                                                                         caus
                                                                         es a
                                                                         line
                                                                         break
                                                                         be
                                                                         fore
                                                                         and
                                                                         after
                                                                         its
                                                                         argu
                                                                         ments
                                                                         are
                                                                         print
                                                                         ed.
                                                                         The
                                                                         de
                                                                         fault
                                                                         com
                                                                         mand
                                                                         modi
                                                                         fier
                                                                         is
                                                                         iden
                                                                         tical
                                                                         to
                                                                         the
                                                                         `.Fl'
                                                                         (flag)
                                                                         com
                                                                         mand
                                                                         with
                                                                         the
                                                                         ex
                                                                         cep
                                                                         tion
                                                                         that
                                                                         the
                                                                         `.Cm'
                                                                         macro
                                                                         does
                                                                         not
                                                                         as
                                                                         sert
                                                                         a
                                                                         dash
                                                                         in
                                                                         front
                                                                         of
                                                                         every
                                                                         argu
                                                                         ment.
                                                                         Tra
                                                                         di
                                                                         tion
                                                                         ally
                                                                         flags
                                                                         are
                                                                         marked
                                                                         by
                                                                         the
                                                                         pre
                                                                         ced
                                                                         ing
                                                                         dash,
                                                                         how
                                                                         ever,
                                                                         some
                                                                         com
                                                                         mands
                                                                         or
                                                                         sub
                                                                         sets
                                                                         of
                                                                         may
                                                                         also
                                                                         be
                                                                         spec
                                                                         ified
                                                                         in
                                                                         con
                                                                         junc
                                                                         tion
                                                                         with
                                                                         in
                                                                         ter
                                                                         ac
                                                                         tive
                                                                         com
                                                                         mands
                                                                         such
                                                                         as
                                                                         edi
                                                                         tor
                                                                         com
                                                                         mands.
                                                                         See
                                                                         Flags.
                                                                         The
                                                                         de
                                                                         fault
                                                                         width
                                                                         is
                                                                         10n.
                                                                       Defined
                                                                         Vari
                                                                         ables
                                                                         A
                                                                         vari
                                                                         able
                                                                         (or
                                                                         con
                                                                         stant)
                                                                         which
                                                                         is
                                                                         de
                                                                         fined
                                                                         in an
                                                                         in
                                                                         clude
                                                                         file
                                                                         is
                                                                         spec
                                                                         ified
                                                                         by
                                                                         the
                                                                                          MAX
                                                                                          HOST
                                                                                          NAME
                                                                                          LEN
                                                                                          MAXHOSTNAMELEN
                                                                                        .Dv
                                                                                          TI
                                                                                          OCGP
                                                                                          GRP
                                                                                          )
                                                                                          TIOCGPGRP)
                                                                         The
                                                                         de
                                                                         fault
                                                                         width
                                                                         is
                                                                         12n.
                                                                       Errno's
                                                                         The
                                                                         `.Er'
                                                                         errno
                                                                         macro
                                                                         spec
                                                                         ifies
                                                                         the
                                                                         error
                                                                         re
                                                                         turn
                                                                         value
                                                                         for
                                                                         sec
                                                                         tion
                                                                         2, 3,
                                                                         and 9
                                                                         li
                                                                         brary
                                                                         rou
                                                                         tines.
                                                                         The
                                                                         sec
                                                                         ond
                                                                         exam
                                                                         ple
                                                                         below
                                                                         shows
                                                                         `.Er'
                                                                         used
                                                                         with
                                                                         the
                                                                         `.Bq'
                                                                         gen
                                                                         eral
                                                                         tion
                                                                         two
                                                                         manu
                                                                         al
                                                                         page.
                                                                               Usage:
                                                                               .Er
                                                                               <errno
                                                                               type>
                                                                               ...
                                                                                        .Er
                                                                                          ENOENT
                                                                                          ENOENT
                                                                                        .Er
                                                                                          ENOENT
                                                                                          )
                                                                                          ;
                                                                                          ENOENT);
                                                                                        .Bq
                                                                                          Er
                                                                                          ENOT
                                                                                          DIR
                                                                                          [ENOTDIR]
                                                                         The
                                                                         de
                                                                         fault
                                                                         width
                                                                         is
                                                                         17n.
                                                                       Envi
                                                                         ron
                                                                         ment
                                                                         Vari
                                                                         ables
                                                                         The
                                                                         `.Ev'
                                                                         macro
                                                                         spec
                                                                         ifies
                                                                         an
                                                                         envi
                                                                         ron
                                                                         ment
                                                                         vari
                                                                         able.
                                                                               Usage:
                                                                               .Ev
                                                                               <argument>
                                                                               ...
                                                                                          PATH.
                                                                                        .Ev
                                                                                          PRINT
                                                                                          ER
                                                                                          )
                                                                                          )
                                                                                          ,
                                                                                          PRINTER)),
                                                                         The
                                                                         de
                                                                         fault
                                                                         width
                                                                         is
                                                                         15n.
                                                                       Flags
                                                                         The
                                                                         `.Fl'
                                                                         macro
                                                                         han
                                                                         dles
                                                                         com
                                                                         mand
                                                                         line
                                                                         flags.
                                                                         It
                                                                         prepends
                                                                         a
                                                                         dash,
                                                                         `-',
                                                                         to
                                                                         the
                                                                         flag.
                                                                         For
                                                                         in
                                                                         ter
                                                                         ac
                                                                         tive
                                                                         com
                                                                         mand
                                                                         flags,
                                                                         which
                                                                         are
                                                                         not
                                                                         prepend
                                                                         ed
                                                                         with
                                                                         a
                                                                         dash,
                                                                         the
                                                                         `.Cm'
                                                                         (com
                                                                         mand
                                                                         the
                                                                         dash.
                                                                               Usage:
                                                                               .Fl
                                                                               <argument>
                                                                               ...
                                                                                        .Fl
                                                                                          -
                                                                                        .Fl
                                                                                          cfv
                                                                                          -cfv
                                                                                        .Fl
                                                                                          cfv
                                                                                          .
                                                                                          -cfv.
                                                                                        .Cm
                                                                                          cfv
                                                                                          .
                                                                                          cfv.
                                                                                        .Fl
                                                                                          s
                                                                                          v
                                                                                          t
                                                                                          -s
                                                                                          -v
                                                                                          -t
                                                                                        .Fl
                                                                                          -
                                                                                          ,
                                                                                          --,
                                                                                        .Fl
                                                                                          xyz
                                                                                          )
                                                                                          ,
                                                                                          -xyz),
                                                                                        .Fl
                                                                                          |
                                                                                          |
                                                                         The
                                                                         `.Fl'
                                                                         macro
                                                                         with
                                                                         out
                                                                         any
                                                                         argu
                                                                         ments
                                                                         re
                                                                         sults
                                                                         in a
                                                                         dash
                                                                         rep
                                                                         re
                                                                         sent
                                                                         gle
                                                                         dash
                                                                         will
                                                                         re
                                                                         sult
                                                                         in
                                                                         two
                                                                         dash
                                                                         es.
                                                                         The
                                                                         de
                                                                         fault
                                                                         width
                                                                         is
                                                                         12n.
                                                                       Func
                                                                         tion
                                                                         Dec
                                                                         lara
                                                                         tions
                                                                         The
                                                                         `.Fd'
                                                                         macro
                                                                         is
                                                                         used
                                                                         in
                                                                         the
                                                                         SYNOPSIS
                                                                         sec
                                                                         tion
                                                                         with
                                                                         sec
                                                                         tion
                                                                         two
                                                                         or
                                                                         three
                                                                         func
                                                                         tions.
                                                                         It is
                                                                         nei
                                                                         ther
                                                                         callable
                                                                         nor
                                                                         parsed.
                                                                               Usage:
                                                                               .Fd
                                                                               <argument>
                                                                               ...
                                                                                        .Fd
                                                                                          "#in
                                                                         tion
                                                                         a
                                                                         `.Fd'
                                                                         re
                                                                         quest
                                                                         caus
                                                                         es a
                                                                         line
                                                                         break
                                                                         if a
                                                                         func
                                                                         tion
                                                                         has
                                                                         al
                                                                         ready
                                                                         been
                                                                         pre
                                                                         sent
                                                                         ed
                                                                         and a
                                                                         break
                                                                         has
                                                                         not
                                                                         oc
                                                                         curred.
                                                                         This
                                                                         leaves
                                                                         a
                                                                         nice
                                                                         ver
                                                                         tical
                                                                         space
                                                                         in
                                                                         be
                                                                         tween
                                                                         the
                                                                         pre
                                                                         vious
                                                                         func
                                                                         tion
                                                                         call
                                                                         and
                                                                         the
                                                                         dec
                                                                         lara
                                                                         tion
                                                                         for
                                                                         the
                                                                         next
                                                                         func
                                                                         tion.
                                                                         The
                                                                         `.In'
                                                                         (#include
                                                                         state
                                                                         ple.
                                                                         It
                                                                         spec
                                                                         ifies
                                                                         the
                                                                         C head
                                                                         er
                                                                         file
                                                                         as
                                                                         being
                                                                         in
                                                                         clud
                                                                         ed in
                                                                         a
                                                                         C pro
                                                                         gram.
                                                                         It
                                                                         also
                                                                         caus
                                                                         es a
                                                                         line
                                                                         break,
                                                                         and
                                                                         is
                                                                         nei
                                                                         ther
                                                                         callable
                                                                         nor
                                                                         parsed.
                                                                               Usage:
                                                                               .In
                                                                               <header
                                                                               file>
                                                                                        .In
                                                                                          stdio.h
                                                                       Func
                                                                         tion
                                                                         Types
                                                                         This
                                                                         macro
                                                                         is
                                                                         in
                                                                         tend
                                                                         ed
                                                                         for
                                                                         the
                                                                         SYNOPSIS
                                                                         sec
                                                                         tion.
                                                                         It
                                                                         may
                                                                         out
                                                                         prob
                                                                         lems,
                                                                         but
                                                                         its
                                                                         main
                                                                         pur
                                                                         pose
                                                                         is to
                                                                         pre
                                                                         sent
                                                                         the
                                                                         func
                                                                         tion
                                                                         type
                                                                         in
                                                                         ker
                                                                         nel
                                                                         nor
                                                                         mal
                                                                         form
                                                                         for
                                                                         the
                                                                         SYNOPSIS
                                                                         of
                                                                         sec
                                                                         tions
                                                                         two
                                                                         and
                                                                         three
                                                                         (it
                                                                         caus
                                                                         es a
                                                                         line
                                                                         break,
                                                                         al
                                                                         low
                                                                         ing
                                                                         the
                                                                         func
                                                                         tion
                                                                         name
                                                                         to
                                                                         ap
                                                                         pear
                                                                         on
                                                                         the
                                                                         next
                                                                         line).
                                                                               Usage:
                                                                               .Ft
                                                                               <type>
                                                                               ...
                                                                                        .Ft
                                                                         tines)
                                                                         The
                                                                         `.Fn'
                                                                         macro
                                                                         is
                                                                         mod
                                                                         eled
                                                                         on
                                                                         ANSI C
                                                                         con
                                                                         ven
                                                                         tions.