contrib/mdocml/mandocd.8

   1 .\"     $Id: mandocd.8,v 1.2 2017/03/18 19:56:01 schwarze Exp $
   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: March 18 2017 $
  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.