.\" -*- nroff -*-
.\"
.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. [Deleted.  See
.\"     ftp://ftp.cs.berkeley.edu/pub/4bsd/README.Impt.License.Change]
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)doc	8.1 (Berkeley) 06/08/93
.\"
.\" Modified by jjc@jclark.com as follows: the doc-* files are assumed to be
.\" installed as mdoc/doc-* rather than tmac.doc-* (the filename
.\" `tmac.doc-common' would be too long); when using groff, the doc-* files
.\" are loaded using the `mso' request.
.\"
.\" Modified by
.\"
.\"   Werner LEMBERG <wl@gnu.org>      and
.\"   Ruslan Ermilov <ru@freebsd.org>
.\"
.\" to make it more readable: using long names and many groff features,
.\" updating and extending documentation, etc.
.\"
.if !\n(.g \
.ab This version of mdoc can be run with GNU troff only!
.do if d Dd .nx
.cp 0
.if (\n[.x]\n[.y] < 118) \
.ab You need GNU troff version 1.18 or higher to run this version of mdoc!
.ie t \
.mso mdoc/doc-ditroff
.el \
.mso mdoc/doc-nroff
.mso mdoc/doc-common
.mso mdoc/doc-syms
.eo
.ds macro-name
.als arg0 macro-name
.nr arg-limit 0
.nr num-args 0
.nr arg-ptr 0
.ds arg1
.nr type1 0
.ds space1
.de parse-args
.if !\n[arg-limit] \
.set-spacing-1
.nr have-space 0
.if !\n[.$] \
.return
.nr arg-limit +1
.ie        "\$1"|" \
.ds arg\n[arg-limit] \f[R]|\f[]
.el \{ .ie "\$1"..." \
.ds arg\n[arg-limit] \|.\|.\|.
.el \
.ds arg\n[arg-limit] "\$1
.\}
.get-arg-type* \n[arg-limit]
.nr type\n[arg-limit] \n[arg-type]
.set-spacing-\n[arg-type]
.ie (\n[.$] == 1) \
.nr arg-ptr 0
.el \{\
.shift
.parse-args \$@
.\}
.nh
..
.de parse-arg-vector
.if !\n[arg-limit] \
.set-spacing-1
.nr arg-limit +1
.ie        "\*[arg\n[arg-limit]]"|" \
.ds arg\n[arg-limit] \f[R]|\f[]
.el \{ .if "\*[arg\n[arg-limit]]"..." \
.ds arg\n[arg-limit] \|.\|.\|.
.\}
.get-arg-type* \n[arg-limit]
.nr type\n[arg-limit] \n[arg-type]
.set-spacing-\n[arg-type]
.ie (\n[num-args] == 1) \{\
.nr arg-ptr 0
.nr num-args 0
.\}
.el \{\
.nr num-args -1
.parse-arg-vector
.\}
.nh
..
.de parse-space-vector
.nr arg-limit +1
.set-spacing-\n[type\n[arg-limit]]
.ie (\n[num-args] == 1) \
.nr num-args 0
.el \{\
.nr num-args -1
.parse-space-vector
.\}
..
.de remaining-args
.nr arg-ptr +1
.nop \)\*[arg\n[arg-ptr]]\c
.ie (\n[num-args] == 1) \{\
.nr arg-ptr 0
.nr num-args 0
.\}
.el \{\
.nop \)\*[space]\c
.nr num-args -1
.remaining-args
.\}
..
.de append-arg
.nr arg-limit +1
.ds arg\n[arg-limit] "\$1
.nr type\n[arg-limit] \$2
.set-spacing-\$2
..
.de print-and-reset
.if \n[space-mode] \
.nop \)
.reset-args
..
.de reset-args
.nr arg-limit 0
.nr arg-ptr 0
.nr have-slot 0
.hy \n[hyphen-flags]
..
.ec
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
.eo
.de Fl
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
.nop \*[Fl-font]\c
.if !\n[arg-limit] \{\
.ds macro-name Fl
.parse-args \$@
.if !\n[.$] \
.nop \|\-\|\f[]\s[0]
.\}
.if !\n[arg-limit] \
.return
.nr arg-ptr +1
.ie (\n[arg-limit] < \n[arg-ptr]) \{\
.nop \|\-\f[]\s[0]\c
.print-and-reset
.\}
.el \{\
.ie (\n[type\n[arg-ptr]] == 1) \{\
.nop \|\-\f[]\s[0]\c
.\*[arg\n[arg-ptr]]
.\}
.el \{\
.if (\n[type\n[arg-ptr]] == 3) \
.nop \|\-\|\c
.nr reg-Fl 1
.flag-recursion
.\}\}
..
.de flag-recursion
.nr reg-dfr1 \n[type\n[arg-ptr]]
.ds str-dfr "\*[arg\n[arg-ptr]]
.ie (\n[reg-dfr1] == 1) \{\
.nop \f[]\s[0]\c
.\*[str-dfr]
.\}
.el \{\
.nr reg-dfr \n[arg-ptr]
.ie (\n[reg-dfr1] == 2) \{\
.ie "\*[str-dfr]"\*[Ba]" \{\
.if \n[reg-Fl] \
.nop \|\-\*[space]\c
.nop \)\*[Ba]\c
.\}
.el \{\
.ie "\*[str-dfr]"\f[R]|\f[]" \{\
.if \n[reg-Fl] \
.nop \|\-\*[space]\c
.nop \f[R]|\f[]\c
.\}
.el \{\
.ie "\*[str-dfr]"-" \
.nop \|\-\^\-\|\c
.el \
.nop \|\%\-\*[str-dfr]\&\c
.\}\}\}
.el \{\
.nop \f[\n[curr-font]]\s[\n[curr-size]u]\c
.nop \)\*[str-dfr]\f[]\s[0]\c
.\}
.ie (\n[arg-limit] == \n[arg-ptr]) \{\
.if (\n[reg-dfr1] == 4) \
.nop \|\-\c
.nop \f[\n[curr-font]]\s[\n[curr-size]u]\c
.print-and-reset
.\}
.el \{\
.nr arg-ptr +1
.ie (\n[type\n[arg-ptr]] == 3) \{\
.ie (\n[type\n[reg-dfr]] == 4) \
.nop \|\-\c
.el \
.nop \)\*[space\n[reg-dfr]]\c
.\}
.el \
.nop \)\*[space\n[reg-dfr]]\c
.shift
.nr reg-Fl 0
.flag-recursion \$@
.\}\}
..
.de print-recursive
.nr reg-dpr1 \n[type\n[arg-ptr]]
.ds str-dpr "\*[arg\n[arg-ptr]]
.ie (\n[reg-dpr1] == 1) \{\
.nop \f[\n[curr-font]]\s[\n[curr-size]u]\c
.\*[str-dpr]
.\}
.el \{\
.nr reg-dpr \n[arg-ptr]
.ie (\n[reg-dpr1] == 2) \
.nop \%\*[str-dpr]\&\c
.el \{\
.nop \f[\n[curr-font]]\s[\n[curr-size]u]\c
.nop \)\*[str-dpr]\f[]\s[0]\c
.\}
.nr arg-ptr +1
.ie (\n[arg-limit] < \n[arg-ptr]) \{\
.nop \f[\n[curr-font]]\s[\n[curr-size]u]\c
.print-and-reset
.\}
.el \{\
.nop \)\*[space\n[reg-dpr]]\c
.print-recursive
.\}\}
..
.de print-prefixes
.while (\n[arg-limit] >= \n[arg-ptr]) \{\
.if !(\n[type\n[arg-ptr]] == 4) \
.break
.nop \f[\n[curr-font]]\s[\n[curr-size]u]\c
.nop \)\*[arg\n[arg-ptr]]\f[]\s[0]\c
.nr arg-ptr +1
.\}
..
.de generic-macro
.if !\n[arg-limit] \{\
.ie \n[.$] \{\
.ds macro-name \$0
.parse-args \$@
.\}
.el \
.tm Usage: .\$0 \*[\$0-usage] ... (#\n[.c])
.\}
.if !\n[arg-limit] \
.return
.nr arg-ptr +1
.ie (\n[arg-limit] >= \n[arg-ptr]) \{\
.if (\n[type\n[arg-ptr]] == 1) \{\
.tmc mdoc warning: Using a macro as first argument
.tm1 " cancels effect of .\$0 (#\n[.c])
.\}
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
.nop \*[\$0-font]\c
.print-recursive
.\}
.el \{\
.tm Usage: .\$0 \*[\$0-usage] ... (#\n[.c])
.reset-args
.\}
..
.ds str-Ar-default "file\ .\|.\|.
.de Ar
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
.nop \*[Ar-font]\c
.if !\n[arg-limit] \{\
.ds macro-name Ar
.parse-args \$@
.if !\n[.$] \
.nop \)\*[str-Ar-default]\&\f[]\s[0]
.\}
.if !\n[arg-limit] \
.return
.nr arg-ptr +1
.print-prefixes
.ie (\n[arg-limit] < \n[arg-ptr]) \{\
.nop \)\*[str-Ar-default]\&\f[]\s[0]\c
.print-and-reset
.\}
.el \{\
.if !(\n[type\n[arg-ptr]] == 2) \{\
.nr arg-ptr -1
.ds arg\n[arg-ptr] "\*[str-Ar-default]
.nr type\n[arg-ptr] 2
.ds space\n[arg-ptr] "\*[space]
.nr num-args (\n[arg-limit] - \n[arg-ptr])
.nr arg-limit \n[arg-ptr]
.parse-space-vector
.\}
.print-recursive
.\}
..
.als Ad generic-macro
.ds Ad-usage address
.nr indent-synopsis 0
.nr indent-synopsis-active 0
.de Cd
.if !\n[arg-limit] \{\
.ie \n[.$] \{\
.ds macro-name Cd
.parse-args \$@
.\}
.el \
.tm Usage: .Cd configuration_file_declaration ... (#\n[.c])
.\}
.if !\n[arg-limit] \
.return
.nr arg-ptr +1
.ie (\n[arg-limit] >= \n[arg-ptr]) \{\
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
.ie \n[in-synopsis-section] \{\
.ie "\*[macro-name]"Cd" \{\
.br
.if !\n[indent-synopsis] \
.nr indent-synopsis \n[display-indent]u
.if !\n[indent-synopsis-active] \
.in +\n[indent-synopsis]u
.ti -\n[indent-synopsis]u
.nop \*[Nm-font]\c
.print-recursive
.if !\n[indent-synopsis-active] \
.in -\n[indent-synopsis]u
.\}
.el \{\
.nop \*[Nm-font]\c
.print-recursive
.\}\}
.el \{\
.nop \*[Nm-font]\c
.print-recursive
.\}\}
.el \{\
.tm Usage: .Cd configuration_file_declaration ... (#\n[.c])
.reset-args
.\}
..
.als Cm generic-macro
.ds Cm-usage interactive_command_modifier
.als Dv generic-macro
.ds Dv-usage defined_variable
.als Dv-font Er-font
.als Em generic-macro
.ds Em-usage text
.als Er generic-macro
.ds Er-usage text
.als Ev generic-macro
.ds Ev-usage text
.nr have-decl 0
.nr have-var 0
.de do-func-decl
.if \n[in-synopsis-section] \{\
.if \n[have-var] \{\
.paragraph
.nr have-var 0
.\}
.if \n[have-func] \{\
.ie \n[have-decl] \
.br
.el \
.paragraph
.\}
.nr have-decl 1
.\}
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
..
.de Fd
.ie ((\n[.$] >= 1) & (\n[arg-limit] == 0)) \{\
.do-func-decl
.nop \*[Fd-font]\$*
.br
.ft \n[curr-font]
.ps \n[curr-size]u
.\}
.el \{\
.tm Usage: .Fd function_declaration -- Fd is not callable (#\n[.c])
.reset-args
.\}
..
.de In
.if !\n[arg-limit] \{\
.ie \n[.$] \{\
.ds macro-name In
.parse-args \$@
.\}
.el \
.tm Usage: .In include_file ... (#\n[.c])
.\}
.if !\n[arg-limit] \
.return
.nr arg-ptr +1
.print-prefixes
.ie ((\n[arg-limit] >= \n[arg-ptr]) & (\n[type\n[arg-ptr]] == 2)) \{\
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
.ie \n[in-synopsis-section] \{\
.ie "\*[macro-name]"In" \{\
.do-func-decl
.nop \*[Fd-font]#include <\*[arg\n[arg-ptr]]>
.ft \n[curr-font]
.ps \n[curr-size]u
.br
.nr arg-ptr +1
.ie (\n[arg-limit] >= \n[arg-ptr]) \
.print-recursive
.el \
.reset-args
.\}
.el \{\
.ds arg\n[arg-ptr] "<\*[Pa-font]\*[arg\n[arg-ptr]]
.as arg\n[arg-ptr] \f[\n[curr-font]]\s[\n[curr-size]u]>
.print-recursive
.\}\}
.el \{\
.ds arg\n[arg-ptr] "<\*[Pa-font]\*[arg\n[arg-ptr]]
.as arg\n[arg-ptr] \f[\n[curr-font]]\s[\n[curr-size]u]>
.print-recursive
.\}\}
.el \{\
.tm Usage: .In include_file ... (#\n[.c])
.reset-args
.\}
..
.als Fr generic-macro
.ds Fr-usage function_return_value
.als Fr-font Ar-font
.als Ic generic-macro
.ds Ic-usage interactive_command
.als Li generic-macro
.ds Li-usage argument
.als Ms generic-macro
.ds Ms-usage math_symbol
.als Ms-font Sy-font
.ds command-name
.de Nm
.if !\n[arg-limit] \{\
.ds macro-name Nm
.ie \n[.$] \
.parse-args \$@
.el \{\
.ie "\*[command-name]"" \
.tm Usage: .Nm name ... (#\n[.c])
.el \
.parse-args \*[command-name]
.\}\}
.if !\n[arg-limit] \
.return
.nr arg-ptr +1
.print-prefixes
.ie (\n[arg-limit] < \n[arg-ptr]) \{\
.ie "\*[command-name]"" \{\
.tm Usage: .Nm name ... (#\n[.c])
.reset-args
.\}
.el \{\
.nop \*[Nm-font]\*[command-name]\f[]\s[0]\c
.print-and-reset
.\}\}
.el \{\
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
.ie !(\n[type\n[arg-ptr]] == 2) \{\
.ie "\*[command-name]"" \
.tm Usage: .Nm name ... (#\n[.c])
.el \{\
.nr arg-ptr -1
.ds arg\n[arg-ptr] "\*[Nm-font]\*[command-name]\f[]\s[0]
.nr type\n[arg-ptr] 2
.ds space\n[arg-ptr] "\*[space]
.nr num-args (\n[arg-limit] - \n[arg-ptr])
.nr arg-limit \n[arg-ptr]
.parse-space-vector
.\}\}
.el \{\
.if \n[in-synopsis-section] \{\
.if "\*[macro-name]"Nm" \{\
.br
.if !\n[indent-synopsis] \{\
.get-width "\*[arg\n[arg-ptr]]"
.nr indent-synopsis ((\n[width]u + 1u) * \n[fixed-width]u)
.\}
.if !\n[indent-synopsis-active] \{\
.in +\n[indent-synopsis]u
.nr indent-synopsis-active 1
.\}
.ti -\n[indent-synopsis]u
.\}\}
.if "\*[command-name]"" \
.ds command-name "\*[arg\n[arg-ptr]]
.nop \*[Nm-font]\c
.\}
.print-recursive
.\}
..
.de Pa
.if !\n[arg-limit] \{\
.ds macro-name Pa
.parse-args \$@
.if !\n[.$] \
.nop \*[Pa-font]~\f[]\s[0]
.\}
.if !\n[arg-limit] \
.return
.nr arg-ptr +1
.print-prefixes
.ie (\n[arg-limit] >= \n[arg-ptr]) \{\
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
.nop \*[Pa-font]\c
.if !(\n[type\n[arg-ptr]] == 2) \{\
.nr arg-ptr -1
.ds arg\n[arg-ptr] ~
.nr type\n[arg-ptr] 2
.ds space\n[arg-ptr] "\*[space]
.nr num-args (\n[arg-limit] - \n[arg-ptr])
.nr arg-limit \n[arg-ptr]
.parse-space-vector
.\}
.print-recursive
.\}
.el \{\
.nop \*[Pa-font]~\f[]\s[0]\c
.print-and-reset
.\}
..
.als Sy generic-macro
.ds Sy-usage symbolic_text
.als Me generic-macro
.ds Me-usage menu_entry
.de Tn
.if !\n[arg-limit] \{\
.ie \n[.$] \{\
.ds macro-name Tn
.parse-args \$@
.\}
.el \
.tm Usage: .Tn trade_name ... (#\n[.c])
.\}
.if !\n[arg-limit] \
.return
.nr arg-ptr +1
.ie (\n[arg-limit] >= \n[arg-ptr]) \{\
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
.nop \)\*[Tn-font-size]\c
.ie !\n[is-reference] \{\
.nop \)\*[Tn-font-shape]\c
.print-recursive
.\}
.el \
.do-references
.\}
.el \{\
.tm Usage: .Tn trade_name ... (#\n[.c])
.reset-args
.\}
..
.als Va generic-macro
.ds Va-usage variable_name
.als No generic-macro
.ds No-usage normal_text
.ds quote-left
.ds quote-right
.de Op
.if !\n[arg-limit] \
.ds macro-name Op
.ds quote-left "\*[left-bracket]
.ds quote-right "\*[right-bracket]
.enclose-string \$@
..
.de Aq
.if !\n[arg-limit] \
.ds macro-name Aq
.ie "\*[macro-name]"An" \{\
.ds quote-left <
.ds quote-right >
.\}
.el \{\
.ds quote-left \[la]
.ds quote-right \[ra]
.\}
.enclose-string \$@
..
.de Bq
.if !\n[arg-limit] \
.ds macro-name Bq
.ds quote-left "\*[left-bracket]
.ds quote-right "\*[right-bracket]
.enclose-string \$@
..
.de Brq
.if !\n[arg-limit] \
.ds macro-name Brq
.ds quote-left {
.ds quote-right }
.enclose-string \$@
..
.de Dq
.if !\n[arg-limit] \
.ds macro-name Dq
.ds quote-left "\*[Lq]
.ds quote-right "\*[Rq]
.enclose-string \$@
..
.de Eq
.if !\n[arg-limit] \
.ds macro-name Eq
.ds quote-left "\$1
.ds quote-right "\$2
.shift 2
.enclose-string \$@
..
.de Pq
.if !\n[arg-limit] \
.ds macro-name Pq
.ds quote-left "\*[left-parenthesis]
.ds quote-right "\*[right-parenthesis]
.enclose-string \$@
..
.de Qq
.if !\n[arg-limit] \
.ds macro-name Qq
.ds quote-left "\*[q]
.ds quote-right "\*[q]
.enclose-string \$@
..
.de Sq
.if !\n[arg-limit] \
.ds macro-name Sq
.ds quote-left "\*[left-singlequote]
.ds quote-right "\*[right-singlequote]
.enclose-string \$@
..
.de Es
.if !\n[arg-limit] \{\
.ie (\n[.$] > 2) \{\
.ds macro-name Es
.parse-args \$@
.\}
.el \{\
.ds quote-left "\$1
.ds quote-right "\$2
.\}\}
.if !\n[arg-limit] \
.return
.nr arg-ptr +1
.ds quote-left "\*[arg\n[arg-ptr]]
.nr arg-ptr +1
.ds quote-right "\*[arg\n[arg-ptr]]
.nr arg-ptr +1
.ie (\n[arg-limit] >= \n[arg-ptr]) \
.do-\n[type\n[arg-ptr]]
.el \
.print-and-reset
..
.nr have-slot 0
.de enclose-string
.if \n[in-synopsis-section] \
.set-hard-space
.if !\n[arg-limit] \{\
.ie \n[.$] \
.parse-args \$@
.el \{\
.nop \)\*[quote-left]\*[quote-right]
.\}\}
.if !\n[arg-limit] \
.return
.nr curr-font \n[.f]
.nr curr-size \n[.ps]
.nr arg-ptr +1
.print-prefixes
.nop \)\*[quote-left]\)\c
.ie (\n[arg-limit] < \n[arg-ptr]) \{\
.nop \)\*[quote-right]\)\c
.print-and-reset
.\}
.el \{\
.ie (\n[type\n[arg-limit]] == 3) \{\
.nr reg-des (\n[arg-limit] - 1)
.while (\n[type\n[reg-des]] == 3) \
.nr reg-des -1
.nr reg-des +1
.ds arg\n[reg-des] "\*[quote-right]\)\*[arg\n[reg-des]]
.\}
.el \{\
.nr reg-des \n[arg-limit]
.while (\n[reg-des] >= \n[arg-ptr]) \{\
.if !\A