-.\" $Id: mdoc.7,v 1.223 2013/12/25 14:09:32 schwarze Exp $
+.\" $Id: mdoc.7,v 1.230 2014/06/24 21:43:08 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: December 25 2013 $
+.Dd $Mdocdate: June 24 2014 $
.Dt MDOC 7
.Os
.Sh NAME
\&.Nm progname
\&.Nd one line about what it does
\&.\e\(dq .Sh LIBRARY
-\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq For sections 2, 3, and 9 only.
\&.\e\(dq Not used in OpenBSD.
\&.Sh SYNOPSIS
\&.Nm progname
The
\&.Nm
utility processes files ...
+\&.\e\(dq .Sh CONTEXT
+\&.\e\(dq For section 9 functions only.
\&.\e\(dq .Sh IMPLEMENTATION NOTES
\&.\e\(dq Not used in OpenBSD.
\&.\e\(dq .Sh RETURN VALUES
-\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq For sections 2, 3, and 9 function return values only.
\&.\e\(dq .Sh ENVIRONMENT
-\&.\e\(dq For sections 1, 6, 7, & 8 only.
+\&.\e\(dq For sections 1, 6, 7, and 8 only.
\&.\e\(dq .Sh FILES
\&.\e\(dq .Sh EXIT STATUS
-\&.\e\(dq For sections 1, 6, & 8 only.
+\&.\e\(dq For sections 1, 6, and 8 only.
\&.\e\(dq .Sh EXAMPLES
\&.\e\(dq .Sh DIAGNOSTICS
-\&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
+\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
\&.\e\(dq .Sh ERRORS
-\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
\&.\e\(dq .Sh SEE ALSO
\&.\e\(dq .Xr foobar 1
\&.\e\(dq .Sh STANDARDS
several subsections, like in the present
.Nm
manual.
+.It Em CONTEXT
+This section lists the contexts in which functions can be called in section 9.
+The contexts are autoconf, process, or interrupt.
.It Em IMPLEMENTATION NOTES
Implementation-specific notes should be kept here.
This is useful when implementing standard functions that may have side
This often contains snippets of well-formed, well-tested invocations.
Make sure that examples work properly!
.It Em DIAGNOSTICS
-Documents error conditions.
-This is most useful in section 4 manuals.
+Documents error messages.
+In section 4 and 9 manuals, these are usually messages printed by the
+kernel to the console and to the kernel log.
+In section 1, 6, 7, and 8, these are usually messages printed by
+userland programs to the standard error output.
+.Pp
Historically, this section was used in place of
.Em EXIT STATUS
for manuals in sections 1, 6, and 8; however, this practise is
.Sx \&Bl
.Fl diag .
.It Em ERRORS
-Documents error handling in sections 2, 3, and 9.
+Documents
+.Xr errno 2
+settings in sections 2, 3, 4, and 9.
.Pp
See
.Sx \&Er .
.It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
.It Sx \&Ad Ta memory address (>0 arguments)
.It Sx \&Ms Ta mathematical symbol (>0 arguments)
-.It Sx \&Tn Ta tradename (>0 arguments)
.El
.Ss Physical markup
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
.It Sx \&St Ta reference to a standards document (one argument)
-.It Sx \&Ux Ta Ux
.It Sx \&At Ta At
.It Sx \&Bx Ta Bx
.It Sx \&Bsx Ta Bsx
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Bc
Close a
.Sx \&Bo
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Bt
+Supported only for compatibility, do not use this in new manuals.
Prints
.Dq is currently in beta test.
.Ss \&Bx
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Cd
Kernel configuration declaration.
This denotes strings accepted by
.It Ar section
The manual section.
This may be one of
-.Ar 1
+.Cm 1
.Pq utilities ,
-.Ar 2
+.Cm 2
.Pq system calls ,
-.Ar 3
+.Cm 3
.Pq libraries ,
-.Ar 3p
+.Cm 3p
.Pq Perl libraries ,
-.Ar 4
+.Cm 4
.Pq devices ,
-.Ar 5
+.Cm 5
.Pq file formats ,
-.Ar 6
+.Cm 6
.Pq games ,
-.Ar 7
+.Cm 7
.Pq miscellaneous ,
-.Ar 8
+.Cm 8
.Pq system utilities ,
-.Ar 9
+.Cm 9
.Pq kernel functions ,
-.Ar X11
+.Cm X11
.Pq X Window System ,
-.Ar X11R6
+.Cm X11R6
.Pq X Window System ,
-.Ar unass
+.Cm unass
.Pq unassociated ,
-.Ar local
+.Cm local
.Pq local system ,
-.Ar draft
+.Cm draft
.Pq draft manual ,
or
-.Ar paper
+.Cm paper
.Pq paper .
It should correspond to the manual's filename suffix and defaults to
-.Dq 1
+.Cm 1
if unspecified.
.It Ar volume
This overrides the volume inferred from
.Ar section .
This field is optional, and if specified, must be one of
-.Ar USD
+.Cm USD
.Pq users' supplementary documents ,
-.Ar PS1
+.Cm PS1
.Pq programmers' supplementary documents ,
-.Ar AMD
+.Cm AMD
.Pq administrators' supplementary documents ,
-.Ar SMM
+.Cm SMM
.Pq system managers' manuals ,
-.Ar URM
+.Cm URM
.Pq users' reference manuals ,
-.Ar PRM
+.Cm PRM
.Pq programmers' reference manuals ,
-.Ar KM
+.Cm KM
.Pq kernel manuals ,
-.Ar IND
+.Cm IND
.Pq master index ,
-.Ar MMI
+.Cm MMI
.Pq master index ,
-.Ar LOCAL
+.Cm LOCAL
.Pq local manuals ,
-.Ar LOC
+.Cm LOC
.Pq local manuals ,
or
-.Ar CON
+.Cm CON
.Pq contributed manuals .
.It Ar arch
This specifies the machine architecture a manual page applies to,
.Sx \&Bx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Ec
Close a scope started by
.Sx \&Eo .
and
.Sx \&Sy .
.Ss \&En
-This macro is obsolete and not implemented in
+This macro is obsolete and ignored by
.Xr mandoc 1 .
.Ss \&Eo
An arbitrary enclosure.
.Sx \&Dv
for general constants.
.Ss \&Es
-This macro is obsolete and not implemented.
+This macro is obsolete and ignored by
+.Xr mandoc 1 .
.Ss \&Ev
Environmental variables such as those specified in
.Xr environ 7 .
and
.Sx \&Ft .
.Ss \&Fr
-This macro is obsolete and not implemented in
+This macro is obsolete and ignored by
.Xr mandoc 1 .
.Pp
It was used to show function return values.
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Hf
This macro is not implemented in
.Xr mandoc 1 .
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Oc
Close multi-line
.Sx \&Oo
and
.Sx \&Dt .
.Ss \&Ot
-This macro is obsolete and not implemented in
+This macro is obsolete and ignored by
.Xr mandoc 1 .
.Pp
Historical
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
-.Sx \&Nx ,
and
-.Sx \&Ux .
+.Sx \&Nx .
.Ss \&Pa
An absolute or relative file system path, or a file or directory name.
If an argument is not provided, the character
.Sx \&Sx .
.Ss \&St
Replace an abbreviation for a standard with the full form.
-The following standards are recognised:
-.Pp
-.Bl -tag -width "-p1003.1g-2000X" -compact
-.It \-p1003.1-88
-.St -p1003.1-88
-.It \-p1003.1-90
-.St -p1003.1-90
-.It \-p1003.1-96
-.St -p1003.1-96
-.It \-p1003.1-2001
-.St -p1003.1-2001
-.It \-p1003.1-2004
-.St -p1003.1-2004
-.It \-p1003.1-2008
-.St -p1003.1-2008
-.It \-p1003.1
-.St -p1003.1
-.It \-p1003.1b
-.St -p1003.1b
-.It \-p1003.1b-93
-.St -p1003.1b-93
-.It \-p1003.1c-95
-.St -p1003.1c-95
-.It \-p1003.1d-99
-.St -p1003.1d-99
-.It \-p1003.1g-2000
-.St -p1003.1g-2000
-.It \-p1003.1i-95
-.St -p1003.1i-95
-.It \-p1003.1j-2000
-.St -p1003.1j-2000
-.It \-p1003.1q-2000
-.St -p1003.1q-2000
-.It \-p1003.2
-.St -p1003.2
-.It \-p1003.2-92
-.St -p1003.2-92
-.It \-p1003.2a-92
-.St -p1003.2a-92
-.It \-p1387.2
-.St -p1387.2
-.It \-p1387.2-95
-.St -p1387.2-95
+The following standards are recognised.
+Where multiple lines are given without a blank line in between,
+they all refer to the same standard, and using the first form
+is recommended.
+.Bl -tag -width 1n
+.It C language standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-ansiC
+.St -ansiC
+.It \-ansiC-89
+.St -ansiC-89
.It \-isoC
.St -isoC
.It \-isoC-90
.St -isoC-90
+.br
+The original C standard.
+.Pp
.It \-isoC-amd1
.St -isoC-amd1
+.Pp
.It \-isoC-tcor1
.St -isoC-tcor1
+.Pp
.It \-isoC-tcor2
.St -isoC-tcor2
+.Pp
.It \-isoC-99
.St -isoC-99
+.It \-ansiC-99
+.St -ansiC-99
+.br
+The second major version of the C language standard.
+.Pp
.It \-isoC-2011
.St -isoC-2011
+.br
+The third major version of the C language standard.
+.El
+.It POSIX.1 before the Single UNIX Specification
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-p1003.1-88
+.St -p1003.1-88
+.It \-p1003.1
+.St -p1003.1
+.br
+The original POSIX standard, based on ANSI C.
+.Pp
+.It \-p1003.1-90
+.St -p1003.1-90
.It \-iso9945-1-90
.St -iso9945-1-90
+.br
+The first update of POSIX.1.
+.Pp
+.It \-p1003.1b-93
+.St -p1003.1b-93
+.It \-p1003.1b
+.St -p1003.1b
+.br
+Real-time extensions.
+.Pp
+.It \-p1003.1c-95
+.St -p1003.1c-95
+.br
+POSIX thread interfaces.
+.Pp
+.It \-p1003.1i-95
+.St -p1003.1i-95
+.br
+Technical Corrigendum.
+.Pp
+.It \-p1003.1-96
+.St -p1003.1-96
.It \-iso9945-1-96
.St -iso9945-1-96
-.It \-iso9945-2-93
-.St -iso9945-2-93
-.It \-ansiC
-.St -ansiC
-.It \-ansiC-89
-.St -ansiC-89
-.It \-ansiC-99
-.St -ansiC-99
-.It \-ieee754
-.St -ieee754
-.It \-iso8802-3
-.St -iso8802-3
-.It \-iso8601
-.St -iso8601
-.It \-ieee1275-94
-.St -ieee1275-94
+.br
+Includes POSIX.1-1990, 1b, 1c, and 1i.
+.El
+.It X/Open Portability Guide version 4 and related standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
.It \-xpg3
.St -xpg3
+.br
+An XPG4 precursor, published in 1989.
+.Pp
+.It \-p1003.2
+.St -p1003.2
+.It \-p1003.2-92
+.St -p1003.2-92
+.It \-iso9945-2-93
+.St -iso9945-2-93
+.br
+An XCU4 precursor.
+.Pp
+.It \-p1003.2a-92
+.St -p1003.2a-92
+.br
+Updates to POSIX.2.
+.Pp
.It \-xpg4
.St -xpg4
+.br
+Based on POSIX.1 and POSIX.2, published in 1992.
+.El
+.It Single UNIX Specification version 1 and related standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
.It \-xpg4.2
.St -xpg4.2
+.br
+This standard was published in 1994 and is also called SUSv1.
+It was used as the basis for UNIX 95 certification.
+The following three refer to parts of it.
+.Pp
+.It \-xsh4.2
+.St -xsh4.2
+.Pp
+.It \-xcurses4.2
+.St -xcurses4.2
+.Pp
+.It \-p1003.1g-2000
+.St -p1003.1g-2000
+.br
+Networking APIs, including sockets.
+.Pp
.It \-xpg4.3
.St -xpg4.3
+.Pp
+.It \-svid4
+.St -svid4 ,
+.br
+Published in 1995.
+.El
+.It Single UNIX Specification version 2 and related standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-susv2
+.St -susv2
+This Standard was published in 1997
+and is also called X/Open Portability Guide version 5.
+It was used as the basis for UNIX 98 certification.
+The following refer to parts of it.
+.Pp
.It \-xbd5
.St -xbd5
-.It \-xcu5
-.St -xcu5
-.It \-xsh4.2
-.St -xsh4.2
+.Pp
.It \-xsh5
.St -xsh5
+.Pp
+.It \-xcu5
+.St -xcu5
+.Pp
.It \-xns5
.St -xns5
-.It \-xns5.2
-.St -xns5.2
.It \-xns5.2d2.0
.St -xns5.2d2.0
-.It \-xcurses4.2
-.St -xcurses4.2
-.It \-susv2
-.St -susv2
+.It \-xns5.2
+.St -xns5.2
+.Pp
+.It \-p1387.2
+.St -p1387.2
+.It \-p1387.2-95
+.St -p1387.2-95
+.br
+POSIX software administration.
+.El
+.It Single UNIX Specification version 3 and related standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000X" -compact
+.It \-p1003.1d-99
+.St -p1003.1d-99
+.br
+Additional real-time extensions.
+.Pp
+.It \-p1003.1j-2000
+.St -p1003.1j-2000
+.br
+Advanced real-time extensions.
+.Pp
+.It \-p1003.1q-2000
+.St -p1003.1q-2000
+.br
+Amendment 7: Tracing [C Language].
+.Pp
+.It \-p1003.1-2001
+.St -p1003.1-2001
.It \-susv3
.St -susv3
-.It \-svid4
-.St -svid4
+.br
+This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j.
+It is also called X/Open Portability Guide version 6.
+It is used as the basis for UNIX 03 certification.
+.Pp
+.It \-p1003.1-2004
+.St -p1003.1-2004
+.br
+The second and last Technical Corrigendum.
+.El
+.It Single UNIX Specification version 4
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-p1003.1-2008
+.St -p1003.1-2008
+.br
+This standard is also called SUSv4 and
+X/Open Portability Guide version 7.
+.Pp
+.It \-p1003.1-2013
+.St -p1003.1-2013
+.br
+This is the first Technical Corrigendum.
+.El
+.It Other standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-ieee754
+.St -ieee754
+.br
+Floating-point arithmetic.
+.Pp
+.It \-iso8601
+.St -iso8601
+.br
+Representation of dates and times, published in 1988.
+.Pp
+.It \-iso8802-3
+.St -iso8802-3
+.br
+Ethernet local area networks.
+.Pp
+.It \-ieee1275-94
+.St -ieee1275-94
+.El
.El
.Ss \&Sx
Reference a section or subsection in the same manual page.
lists; can only be used below
.Sx \&It .
.Ss \&Tn
-Format a tradename.
-.Pp
-Since this macro is often implemented to use a small caps font,
-it has historically been used for acronyms (like ASCII) as well.
-Such usage is not recommended because it would use the same macro
-sometimes for semantical annotation, sometimes for physical formatting.
-.Pp
-Examples:
-.Dl \&.Tn IBM
+Supported only for compatibility, do not use this in new manuals.
+Even though the macro name
+.Pq Dq tradename
+suggests a semantic function, historic usage is inconsistent, mostly
+using it as a presentation-level macro to request a small caps font.
.Ss \&Ud
+Supported only for compatibility, do not use this in new manuals.
Prints out
.Dq currently under development.
.Ss \&Ux
-Format the
-.Ux
-name.
-Accepts no argument.
-.Pp
-Examples:
-.Dl \&.Ux
-.Pp
-See also
-.Sx \&At ,
-.Sx \&Bsx ,
-.Sx \&Bx ,
-.Sx \&Dx ,
-.Sx \&Fx ,
-.Sx \&Nx ,
-and
-.Sx \&Ox .
+Supported only for compatibility, do not use this in new manuals.
+Prints out
+.Dq Ux .
.Ss \&Va
A variable name.
.Pp
.Ql \ef
font escape sequences is never required.
.Sh COMPATIBILITY
-This section documents compatibility between mandoc and other
-troff implementations, at this time limited to GNU troff
+This section provides an incomplete list of compatibility issues
+between mandoc and other troff implementations, at this time limited
+to GNU troff
.Pq Qq groff .
The term
.Qq historic groff
can only be called by other macros, but not at the beginning of a line.
.It
.Sx \&%C
-is not implemented.
+is not implemented (up to and including groff-1.22.2).
.It
Historic groff only allows up to eight or nine arguments per macro input
line, depending on the exact situation.
.Sq \ef
.Pq font face
and
-.Sq \ef
+.Sq \eF
.Pq font family face
.Sx Text Decoration
escapes behave irregularly when specified within line-macro scopes.
.Fl file Ar file .
.It
.Sx \&Bd
-.Fl offset Ar center
+.Fl offset Cm center
and
-.Fl offset Ar right .
+.Fl offset Cm right .
Groff does not implement centred and flush-right rendering either,
but produces large indentations.
-.It
-The
-.Sq \eh
-.Pq horizontal position ,
-.Sq \ev
-.Pq vertical position ,
-.Sq \em
-.Pq text colour ,
-.Sq \eM
-.Pq text filling colour ,
-.Sq \ez
-.Pq zero-length character ,
-.Sq \ew
-.Pq string length ,
-.Sq \ek
-.Pq horizontal position marker ,
-.Sq \eo
-.Pq text overstrike ,
-and
-.Sq \es
-.Pq text size
-escape sequences are all discarded in mandoc.
-.It
-The
-.Sq \ef
-scaling unit is accepted by mandoc, but rendered as the default unit.
-.It
-In quoted literals, groff allows pairwise double-quotes to produce a
-standalone double-quote in formatted output.
-This is not supported by mandoc.
.El
.Sh SEE ALSO
.Xr man 1 ,
git.ckatri.com / mandoc.git / blobdiff