.TH "MANDOCD" "8" "February 6, 2017" "Debian" "System Manager's Manual"
.nh
.if n .ad l
.SH "NAME"
\fBmandocd\fR
\- server process to format manual pages in batch mode
.SH "SYNOPSIS"
.HP 8n
\fBmandocd\fR
[\fB\-I\fR\ \fBos\fR=\fIname\fR]
[\fB\-T\fR\ \fIoutput\fR]
\fIsocket_fd\fR
.SH "DESCRIPTION"
The
\fBmandocd\fR
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.
.PP
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
\fBmandocd\fR.
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.
.PP
\fBmandocd\fR
loops reading one-byte messages with
recvmsg(2)
from the file descriptor number
\fIsocket_fd\fR.
It ignores the byte read and only uses the out-of-band auxiliary
\fIstruct cmsghdr\fR
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.
.PP
The options are as follows:
.TP 8n
\fB\-I\fR \fBos\fR=\fIname\fR
Override the default operating system
\fIname\fR
for the
mdoc(7)
\fBOs\fR
and for the
man(7)
\fBTH\fR
macro.
.TP 8n
\fB\-T\fR \fIoutput\fR
Output format.
The
\fIoutput\fR
argument can be
\fBascii\fR,
\fButf8\fR,
or
\fBhtml\fR;
see
mandoc(1).
In
\fBhtml\fR
output mode, the
\fBfragment\fR
output option is implied.
Other output options are not supported.
.PP
After exhausting one input file descriptor, all three file descriptors
are closed before reading the next dummy byte and control message.
.PP
When a zero-byte message is read, when the
\fIsocket_fd\fR
is closed by the parent process,
or when an error occurs,
\fBmandocd\fR
exits.
.SH "EXIT STATUS"
.br
The \fBmandocd\fR utility exits\~0 on success, and\~>0 if an error occurs.
.PP
A zero-byte message or a closed
\fIsocket_fd\fR
is considered success.
Possible errors include:
.TP 4n
\fB\(bu\fR
missing, invalid, or excessive
exec(3)
arguments
.TP 4n
\fB\(bu\fR
recvmsg(2)
failure, for example due to
\fREMSGSIZE\fR
.TP 4n
\fB\(bu\fR
missing or unexpected control data, in particular a
\fIcmsg_level\fR
in the
\fIstruct cmsghdr\fR
that differs from
\fRSOL_SOCKET\fR,
a
\fIcmsg_type\fR
that differs from
\fRSCM_RIGHTS\fR,
or a
\fIcmsg_len\fR
that is not three times the size of an
\fIint\fR
.TP 4n
\fB\(bu\fR
invalid file descriptors passed in the
CMSG_DATA(3)
.TP 4n
\fB\(bu\fR
resource exhaustion, in particular
dup(2)
or
malloc(3)
failure
.PP
Except for memory exhaustion and similar system-level failures,
parsing and formatting errors do not cause
\fBmandocd\fR
to return an error exit status.
Even after severe parsing errors,
\fBmandocd\fR
will simply accept and process the next input file descriptor.
.SH "SEE ALSO"
mandoc(1),
mandoc(3),
catman(8)
.SH "HISTORY"
The
\fBmandocd\fR
utility appeared in version 1.14.1 or the
\fBmandoc\fR
toolkit.
.SH "AUTHORS"
The concept was designed and implemented by
Michael Stapelberg <\fIstapelberg@debian.org\fR>.
The
mandoc(3)
glue needed to make it a stand-alone process was added by
Ingo Schwarze <\fIschwarze@openbsd.org\fR>.
.SH "CAVEATS"
If the parsed manual pages contain
roff(7)
\&.\fBso\fR
requests,
\fBmandocd\fR
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.