new manual pages for catman(8) and mandocd(8)

1 files changed, 198 insertions, 0 deletions

diff --git a/mandocd.8 b/mandocd.8
new file mode 100644
index 00000000..36b423c6
--- /dev/null
+++ b/mandocd.8
@@ -0,0 +1,198 @@
+.\"	$Id$
+.\"
+.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt MANDOCD 8
+.Os
+.Sh NAME
+.Nm mandocd
+.Nd server process to format manual pages in batch mode
+.Sh SYNOPSIS
+.Nm mandocd
+.Op Fl I Cm os Ns = Ns Ar name
+.Op Fl T Ar output
+.Ar socket_fd
+.Sh DESCRIPTION
+The
+.Nm
+utility formats many manual pages without requiring
+.Xr fork 2
+and
+.Xr 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
+.Xr socket 2
+is already present at
+.Xr exec 3
+time.
+Consequently, it cannot be started from the
+.Xr sh 1
+command line because the shell cannot supply such a socket.
+Typically, the socket is created by the parent process using
+.Xr socketpair 2
+before calling
+.Xr fork 2
+and
+.Xr exec 3
+on
+.Nm .
+The parent process will pass the file descriptor number as an argument to
+.Xr exec 3 ,
+formatted as a decimal ASCII-encoded integer.
+See
+.Xr catman 8
+for a typical implementation of a parent process.
+.Pp
+.Nm
+loops reading one-byte messages with
+.Xr recvmsg 2
+from the file descriptor number
+.Ar socket_fd .
+It ignores the byte read and only uses the out-of-band auxiliary
+.Vt struct cmsghdr
+control data, typically supplied by the calling process using
+.Xr CMSG_FIRSTHDR 3 .
+The parent process is expected to pass three file descriptors
+with each dummy byte.
+The first one is used for
+.Xr mdoc 7
+or
+.Xr man 7
+input, the second one for formatted output, and the third one
+for error output.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl I Cm os Ns = Ns Ar name
+Override the default operating system
+.Ar name
+for the
+.Xr mdoc 7
+.Ic Os
+and for the
+.Xr man 7
+.Ic TH
+macro.
+.It Fl T Ar output
+Output format.
+The
+.Ar output
+argument can be
+.Cm ascii ,
+.Cm utf8 ,
+or
+.Cm html ;
+see
+.Xr mandoc 1 .
+In
+.Cm html
+output mode, the
+.Cm fragment
+output option is implied.
+Other output options are not supported.
+.El
+.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
+.Ar socket_fd
+is closed by the parent process,
+or when an error occurs,
+.Nm
+exits.
+.Sh EXIT STATUS
+.Ex -std
+.Pp
+A zero-byte message or a closed
+.Ar socket_fd
+is considered success.
+Possible errors include:
+.Bl -bullet
+.It
+missing, invalid, or excessive
+.Xr exec 3
+arguments
+.It
+.Xr recvmsg 2
+failure, for example due to
+.Er EMSGSIZE
+.It
+missing or unexpected control data, in particular a
+.Fa cmsg_level
+in the
+.Vt struct cmsghdr
+that differs from
+.Dv SOL_SOCKET ,
+a
+.Fa cmsg_type
+that differs from
+.Dv SCM_RIGHTS ,
+or a
+.Fa cmsg_len
+that is not three times the size of an
+.Vt int
+.It
+invalid file descriptors passed in the
+.Xr CMSG_DATA 3
+.It
+resource exhaustion, in particular
+.Xr dup 2
+or
+.Xr malloc 3
+failure
+.El
+.Pp
+Except for memory exhaustion and similar system-level failures,
+parsing and formatting errors do not cause
+.Nm
+to return an error exit status.
+Even after severe parsing errors,
+.Nm
+will simply accept and process the next input file descriptor.
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr mandoc 3 ,
+.Xr catman 8
+.Sh HISTORY
+The
+.Nm
+utility appeared in version 1.14.1 or the
+.Sy mandoc
+toolkit.
+.Sh AUTHORS
+.An -nosplit
+The concept was designed and implemented by
+.An Michael Stapelberg Aq Mt stapelberg@debian.org .
+The
+.Xr mandoc 3
+glue needed to make it a stand-alone process was added by
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
+.Sh CAVEATS
+If the parsed manual pages contain
+.Xr roff 7
+.Pf . Ic so
+requests,
+.Nm
+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.