mandocd — server process to format manual pages in batch mode

       The  concept  was  designed and implemented by Michael Stapelberg <stapelberg@debian.org>.  The mandoc(3)
       glue needed to make it a stand-alone process was added by Ingo Schwarze <schwarze@openbsd.org>.

       If the parsed manual pages contain roff(7) .so requests, mandocd needs to be  started  with  the  current
       working directory set to the root of the manual page tree.  Avoid starting it in directories that contain
       secret files in any subdirectories, in particular in the user starting it has read access to these secret
       files.

Debian                                           March 18, 2017                                       MANDOCD(8)

       The  mandocd utility formats many manual pages without requiring fork(2) and exec(3) overhead in between.
       It does not require listing all the manuals to be formatted on the command line, and it supports  writing
       each formatted manual to its own file descriptor.

       This  server  requires  that  a  connected  UNIX  domain  socket(2)  is  already present at exec(3) time.
       Consequently, it cannot be started from the sh(1) command line because the shell  cannot  supply  such  a
       socket.   Typically,  the  socket  is  created  by  the parent process using socketpair(2) before calling
       fork(2) and exec(3) on mandocd.  The parent process will pass the file descriptor number as  an  argument
       to  exec(3), formatted as a decimal ASCII-encoded integer.  See catman(8) for a typical implementation of
       a parent process.

       mandocd loops reading one-byte messages with recvmsg(2) from the file descriptor  number  socket_fd.   It
       ignores  the  byte  read  and  only uses the out-of-band auxiliary structcmsghdr control data, typically
       supplied by the calling process using CMSG_FIRSTHDR(3).  The parent process is  expected  to  pass  three
       file descriptors with each dummy byte.  The first one is used for mdoc(7) or man(7) input, the second one
       for formatted output, and the third one for error output.

       The options are as follows:

       -Ios=name
               Override the default operating system name for the mdoc(7) Os and for the man(7) TH macro.

       -Toutput
               Output  format.   The output argument can be ascii, utf8, or html; see mandoc(1).  In html output
               mode, the fragment output option is implied.  Other output options are not supported.

       After exhausting one input file descriptor, all three file descriptors are closed before reading the next
       dummy byte and control message.

       When a zero-byte message is read, when the socket_fd is closed by the parent process, or  when  an  error
       occurs, mandocd exits.

       The mandocd utility exits 0 on success, and >0 if an error occurs.

       A zero-byte message or a closed socket_fd is considered success.  Possible errors include:

       •   missing, invalid, or excessive exec(3) arguments

       •recvmsg(2) failure, for example due to EMSGSIZE

       •   missing  or  unexpected  control  data, in particular a cmsg_level in the structcmsghdr that differs
           from SOL_SOCKET, a cmsg_type that differs from SCM_RIGHTS, or a cmsg_len that is not three times  the
           size of an int•   invalid file descriptors passed in the CMSG_DATA(3)

       •   resource exhaustion, in particular dup(2) or malloc(3) failure

       Except  for  memory  exhaustion  and  similar system-level failures, parsing and formatting errors do not
       cause mandocd to return an error exit status.  Even after severe  parsing  errors,  mandocd  will  simply
       accept and process the next input file descriptor.

       The mandocd utility appeared in version 1.14.1 or the mandoc toolkit.

       mandocd — server process to format manual pages in batch mode

mandoc(1), mandoc(3), catman(8)

mandocd [-Ios=name] [-Toutput] socket_fd