NAME

       mandocd - server process to format manual pages in batch mode

SYNOPSIS

       mandocd [-I os=name] [-T output] socket_fd

DESCRIPTION

       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 struct
       cmsghdr 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:

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

       -T output
               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.

EXIT STATUS

       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 struct cmsghdr
           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.

SEE ALSO

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

HISTORY

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

AUTHORS

       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>.

CAVEATS

       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.