[BACK]Return to mandocd.8 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mandocd.8, Revision 1.2

1.2     ! schwarze    1: .\"    $Id: mandocd.8,v 1.1 2017/02/06 19:04:21 schwarze Exp $
1.1       schwarze    2: .\"
                      3: .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
                      4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
                      6: .\" purpose with or without fee is hereby granted, provided that the above
                      7: .\" copyright notice and this permission notice appear in all copies.
                      8: .\"
                      9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     16: .\"
1.2     ! schwarze   17: .Dd $Mdocdate: February 6 2017 $
1.1       schwarze   18: .Dt MANDOCD 8
                     19: .Os
                     20: .Sh NAME
                     21: .Nm mandocd
                     22: .Nd server process to format manual pages in batch mode
                     23: .Sh SYNOPSIS
                     24: .Nm mandocd
                     25: .Op Fl I Cm os Ns = Ns Ar name
                     26: .Op Fl T Ar output
                     27: .Ar socket_fd
                     28: .Sh DESCRIPTION
                     29: The
                     30: .Nm
                     31: utility formats many manual pages without requiring
                     32: .Xr fork 2
                     33: and
                     34: .Xr exec 3
                     35: overhead in between.
                     36: It does not require listing all the manuals to be formatted on the
                     37: command line, and it supports writing each formatted manual to its
                     38: own file descriptor.
                     39: .Pp
                     40: This server requires that a connected UNIX domain
                     41: .Xr socket 2
                     42: is already present at
                     43: .Xr exec 3
                     44: time.
                     45: Consequently, it cannot be started from the
                     46: .Xr sh 1
                     47: command line because the shell cannot supply such a socket.
                     48: Typically, the socket is created by the parent process using
                     49: .Xr socketpair 2
                     50: before calling
                     51: .Xr fork 2
                     52: and
                     53: .Xr exec 3
                     54: on
                     55: .Nm .
                     56: The parent process will pass the file descriptor number as an argument to
                     57: .Xr exec 3 ,
                     58: formatted as a decimal ASCII-encoded integer.
                     59: See
                     60: .Xr catman 8
                     61: for a typical implementation of a parent process.
                     62: .Pp
                     63: .Nm
                     64: loops reading one-byte messages with
                     65: .Xr recvmsg 2
                     66: from the file descriptor number
                     67: .Ar socket_fd .
                     68: It ignores the byte read and only uses the out-of-band auxiliary
                     69: .Vt struct cmsghdr
                     70: control data, typically supplied by the calling process using
                     71: .Xr CMSG_FIRSTHDR 3 .
                     72: The parent process is expected to pass three file descriptors
                     73: with each dummy byte.
                     74: The first one is used for
                     75: .Xr mdoc 7
                     76: or
                     77: .Xr man 7
                     78: input, the second one for formatted output, and the third one
                     79: for error output.
                     80: .Pp
                     81: The options are as follows:
                     82: .Bl -tag -width Ds
                     83: .It Fl I Cm os Ns = Ns Ar name
                     84: Override the default operating system
                     85: .Ar name
                     86: for the
                     87: .Xr mdoc 7
1.2     ! schwarze   88: .Ic \&Os
1.1       schwarze   89: and for the
                     90: .Xr man 7
                     91: .Ic TH
                     92: macro.
                     93: .It Fl T Ar output
                     94: Output format.
                     95: The
                     96: .Ar output
                     97: argument can be
                     98: .Cm ascii ,
                     99: .Cm utf8 ,
                    100: or
                    101: .Cm html ;
                    102: see
                    103: .Xr mandoc 1 .
                    104: In
                    105: .Cm html
                    106: output mode, the
                    107: .Cm fragment
                    108: output option is implied.
                    109: Other output options are not supported.
                    110: .El
                    111: .Pp
                    112: After exhausting one input file descriptor, all three file descriptors
                    113: are closed before reading the next dummy byte and control message.
                    114: .Pp
                    115: When a zero-byte message is read, when the
                    116: .Ar socket_fd
                    117: is closed by the parent process,
                    118: or when an error occurs,
                    119: .Nm
                    120: exits.
                    121: .Sh EXIT STATUS
                    122: .Ex -std
                    123: .Pp
                    124: A zero-byte message or a closed
                    125: .Ar socket_fd
                    126: is considered success.
                    127: Possible errors include:
                    128: .Bl -bullet
                    129: .It
                    130: missing, invalid, or excessive
                    131: .Xr exec 3
                    132: arguments
                    133: .It
                    134: .Xr recvmsg 2
                    135: failure, for example due to
                    136: .Er EMSGSIZE
                    137: .It
                    138: missing or unexpected control data, in particular a
                    139: .Fa cmsg_level
                    140: in the
                    141: .Vt struct cmsghdr
                    142: that differs from
                    143: .Dv SOL_SOCKET ,
                    144: a
                    145: .Fa cmsg_type
                    146: that differs from
                    147: .Dv SCM_RIGHTS ,
                    148: or a
                    149: .Fa cmsg_len
                    150: that is not three times the size of an
                    151: .Vt int
                    152: .It
                    153: invalid file descriptors passed in the
                    154: .Xr CMSG_DATA 3
                    155: .It
                    156: resource exhaustion, in particular
                    157: .Xr dup 2
                    158: or
                    159: .Xr malloc 3
                    160: failure
                    161: .El
                    162: .Pp
                    163: Except for memory exhaustion and similar system-level failures,
                    164: parsing and formatting errors do not cause
                    165: .Nm
                    166: to return an error exit status.
                    167: Even after severe parsing errors,
                    168: .Nm
                    169: will simply accept and process the next input file descriptor.
                    170: .Sh SEE ALSO
                    171: .Xr mandoc 1 ,
                    172: .Xr mandoc 3 ,
                    173: .Xr catman 8
                    174: .Sh HISTORY
                    175: The
                    176: .Nm
                    177: utility appeared in version 1.14.1 or the
                    178: .Sy mandoc
                    179: toolkit.
                    180: .Sh AUTHORS
                    181: .An -nosplit
                    182: The concept was designed and implemented by
                    183: .An Michael Stapelberg Aq Mt stapelberg@debian.org .
                    184: The
                    185: .Xr mandoc 3
                    186: glue needed to make it a stand-alone process was added by
                    187: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
                    188: .Sh CAVEATS
                    189: If the parsed manual pages contain
                    190: .Xr roff 7
                    191: .Pf . Ic so
                    192: requests,
                    193: .Nm
                    194: needs to be started with the current working directory set to the
                    195: root of the manual page tree.
                    196: Avoid starting it in directories that contain secret files in any
                    197: subdirectories, in particular in the user starting it has read
                    198: access to these secret files.

CVSweb