Annotation of mandoc/mandocd.8, Revision 1.1
1.1 ! schwarze 1: .\" $Id$
! 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: .\"
! 17: .Dd $Mdocdate$
! 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
! 88: .Ic Os
! 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
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mandocd.8 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc