Annotation of mandoc/mandocd.8, Revision 1.2
1.2 ! schwarze 1: .\" $Id: mandocd.8,v 1.1 2017/02/06 19:04:21 schwarze Exp $
1.1 schwarze 2: .\"
3: .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.2 ! schwarze 17: .Dd $Mdocdate: February 6 2017 $
1.1 schwarze 18: .Dt MANDOCD 8
19: .Os
20: .Sh NAME
21: .Nm mandocd
22: .Nd server process to format manual pages in batch mode
23: .Sh SYNOPSIS
24: .Nm mandocd
25: .Op Fl I Cm os Ns = Ns Ar name
26: .Op Fl T Ar output
27: .Ar socket_fd
28: .Sh DESCRIPTION
29: The
30: .Nm
31: utility formats many manual pages without requiring
32: .Xr fork 2
33: and
34: .Xr exec 3
35: overhead in between.
36: It does not require listing all the manuals to be formatted on the
37: command line, and it supports writing each formatted manual to its
38: own file descriptor.
39: .Pp
40: This server requires that a connected UNIX domain
41: .Xr socket 2
42: is already present at
43: .Xr exec 3
44: time.
45: Consequently, it cannot be started from the
46: .Xr sh 1
47: command line because the shell cannot supply such a socket.
48: Typically, the socket is created by the parent process using
49: .Xr socketpair 2
50: before calling
51: .Xr fork 2
52: and
53: .Xr exec 3
54: on
55: .Nm .
56: The parent process will pass the file descriptor number as an argument to
57: .Xr exec 3 ,
58: formatted as a decimal ASCII-encoded integer.
59: See
60: .Xr catman 8
61: for a typical implementation of a parent process.
62: .Pp
63: .Nm
64: loops reading one-byte messages with
65: .Xr recvmsg 2
66: from the file descriptor number
67: .Ar socket_fd .
68: It ignores the byte read and only uses the out-of-band auxiliary
69: .Vt struct cmsghdr
70: control data, typically supplied by the calling process using
71: .Xr CMSG_FIRSTHDR 3 .
72: The parent process is expected to pass three file descriptors
73: with each dummy byte.
74: The first one is used for
75: .Xr mdoc 7
76: or
77: .Xr man 7
78: input, the second one for formatted output, and the third one
79: for error output.
80: .Pp
81: The options are as follows:
82: .Bl -tag -width Ds
83: .It Fl I Cm os Ns = Ns Ar name
84: Override the default operating system
85: .Ar name
86: for the
87: .Xr mdoc 7
1.2 ! schwarze 88: .Ic \&Os
1.1 schwarze 89: and for the
90: .Xr man 7
91: .Ic TH
92: macro.
93: .It Fl T Ar output
94: Output format.
95: The
96: .Ar output
97: argument can be
98: .Cm ascii ,
99: .Cm utf8 ,
100: or
101: .Cm html ;
102: see
103: .Xr mandoc 1 .
104: In
105: .Cm html
106: output mode, the
107: .Cm fragment
108: output option is implied.
109: Other output options are not supported.
110: .El
111: .Pp
112: After exhausting one input file descriptor, all three file descriptors
113: are closed before reading the next dummy byte and control message.
114: .Pp
115: When a zero-byte message is read, when the
116: .Ar socket_fd
117: is closed by the parent process,
118: or when an error occurs,
119: .Nm
120: exits.
121: .Sh EXIT STATUS
122: .Ex -std
123: .Pp
124: A zero-byte message or a closed
125: .Ar socket_fd
126: is considered success.
127: Possible errors include:
128: .Bl -bullet
129: .It
130: missing, invalid, or excessive
131: .Xr exec 3
132: arguments
133: .It
134: .Xr recvmsg 2
135: failure, for example due to
136: .Er EMSGSIZE
137: .It
138: missing or unexpected control data, in particular a
139: .Fa cmsg_level
140: in the
141: .Vt struct cmsghdr
142: that differs from
143: .Dv SOL_SOCKET ,
144: a
145: .Fa cmsg_type
146: that differs from
147: .Dv SCM_RIGHTS ,
148: or a
149: .Fa cmsg_len
150: that is not three times the size of an
151: .Vt int
152: .It
153: invalid file descriptors passed in the
154: .Xr CMSG_DATA 3
155: .It
156: resource exhaustion, in particular
157: .Xr dup 2
158: or
159: .Xr malloc 3
160: failure
161: .El
162: .Pp
163: Except for memory exhaustion and similar system-level failures,
164: parsing and formatting errors do not cause
165: .Nm
166: to return an error exit status.
167: Even after severe parsing errors,
168: .Nm
169: will simply accept and process the next input file descriptor.
170: .Sh SEE ALSO
171: .Xr mandoc 1 ,
172: .Xr mandoc 3 ,
173: .Xr catman 8
174: .Sh HISTORY
175: The
176: .Nm
177: utility appeared in version 1.14.1 or the
178: .Sy mandoc
179: toolkit.
180: .Sh AUTHORS
181: .An -nosplit
182: The concept was designed and implemented by
183: .An Michael Stapelberg Aq Mt stapelberg@debian.org .
184: The
185: .Xr mandoc 3
186: glue needed to make it a stand-alone process was added by
187: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
188: .Sh CAVEATS
189: If the parsed manual pages contain
190: .Xr roff 7
191: .Pf . Ic so
192: requests,
193: .Nm
194: needs to be started with the current working directory set to the
195: root of the manual page tree.
196: Avoid starting it in directories that contain secret files in any
197: subdirectories, in particular in the user starting it has read
198: access to these secret files.
CVSweb