MANDOCD(8)		    System Manager's Manual		    MANDOCD(8)

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.

Debian				March 18, 2017				Debian