- server process to format manual pages in batch mode
[ -I os=name] [ -T output]
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.
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
utility exits 0 on success, and >0 if an
A zero-byte message or a closed socket_fd
is considered success. Possible
- 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)
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.
mandoc(1), mandoc(3), catman(8)
utility appeared in version 1.14.1 or the mandoc
The concept was designed and implemented by Michael Stapelberg <
>. The mandoc(3) glue needed to make it a
stand-alone process was added by Ingo Schwarze <
If the parsed manual pages contain roff(7) . so
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.