groff -mdoc file ...


DESCRIPTION

     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.


GETTING STARTED

     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


TROFF IDIOSYNCRASIES

     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.


A MANUAL PAGE TEMPLATE

     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.


TITLE MACROS

     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.


INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS

   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'.


MANUAL DOMAIN

   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.


Man(1) output converted with man2html