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 29The 30.Nm 31utility formats many manual pages without requiring 32.Xr fork 2 33and 34.Xr exec 3 35overhead in between. 36It does not require listing all the manuals to be formatted on the 37command line, and it supports writing each formatted manual to its 38own file descriptor. 39.Pp 40This server requires that a connected UNIX domain 41.Xr socket 2 42is already present at 43.Xr exec 3 44time. 45Consequently, it cannot be started from the 46.Xr sh 1 47command line because the shell cannot supply such a socket. 48Typically, the socket is created by the parent process using 49.Xr socketpair 2 50before calling 51.Xr fork 2 52and 53.Xr exec 3 54on 55.Nm . 56The parent process will pass the file descriptor number as an argument to 57.Xr exec 3 , 58formatted as a decimal ASCII-encoded integer. 59See 60.Xr catman 8 61for a typical implementation of a parent process. 62.Pp 63.Nm 64loops reading one-byte messages with 65.Xr recvmsg 2 66from the file descriptor number 67.Ar socket_fd . 68It ignores the byte read and only uses the out-of-band auxiliary 69.Vt struct cmsghdr 70control data, typically supplied by the calling process using 71.Xr CMSG_FIRSTHDR 3 . 72The parent process is expected to pass three file descriptors 73with each dummy byte. 74The first one is used for 75.Xr mdoc 7 76or 77.Xr man 7 78input, the second one for formatted output, and the third one 79for error output. 80.Pp 81The options are as follows: 82.Bl -tag -width Ds 83.It Fl I Cm os Ns = Ns Ar name 84Override the default operating system 85.Ar name 86for the 87.Xr mdoc 7 88.Ic \&Os 89and for the 90.Xr man 7 91.Ic TH 92macro. 93.It Fl T Ar output 94Output format. 95The 96.Ar output 97argument can be 98.Cm ascii , 99.Cm utf8 , 100or 101.Cm html ; 102see 103.Xr mandoc 1 . 104In 105.Cm html 106output mode, the 107.Cm fragment 108output option is implied. 109Other output options are not supported. 110.El 111.Pp 112After exhausting one input file descriptor, all three file descriptors 113are closed before reading the next dummy byte and control message. 114.Pp 115When a zero-byte message is read, when the 116.Ar socket_fd 117is closed by the parent process, 118or when an error occurs, 119.Nm 120exits. 121.Sh EXIT STATUS 122.Ex -std 123.Pp 124A zero-byte message or a closed 125.Ar socket_fd 126is considered success. 127Possible errors include: 128.Bl -bullet 129.It 130missing, invalid, or excessive 131.Xr exec 3 132arguments 133.It 134.Xr recvmsg 2 135failure, for example due to 136.Er EMSGSIZE 137.It 138missing or unexpected control data, in particular a 139.Fa cmsg_level 140in the 141.Vt struct cmsghdr 142that differs from 143.Dv SOL_SOCKET , 144a 145.Fa cmsg_type 146that differs from 147.Dv SCM_RIGHTS , 148or a 149.Fa cmsg_len 150that is not three times the size of an 151.Vt int 152.It 153invalid file descriptors passed in the 154.Xr CMSG_DATA 3 155.It 156resource exhaustion, in particular 157.Xr dup 2 158or 159.Xr malloc 3 160failure 161.El 162.Pp 163Except for memory exhaustion and similar system-level failures, 164parsing and formatting errors do not cause 165.Nm 166to return an error exit status. 167Even after severe parsing errors, 168.Nm 169will 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 175The 176.Nm 177utility appeared in version 1.14.1 or the 178.Sy mandoc 179toolkit. 180.Sh AUTHORS 181.An -nosplit 182The concept was designed and implemented by 183.An Michael Stapelberg Aq Mt stapelberg@debian.org . 184The 185.Xr mandoc 3 186glue needed to make it a stand-alone process was added by 187.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 188.Sh CAVEATS 189If the parsed manual pages contain 190.Xr roff 7 191.Pf . Ic so 192requests, 193.Nm 194needs to be started with the current working directory set to the 195root of the manual page tree. 196Avoid starting it in directories that contain secret files in any 197subdirectories, in particular in the user starting it has read 198access to these secret files. 199