MANDOCD(8)

🎀 MANDOCD 🎀

okay bestie, welcome to mandocd from the System Manager's Manual section 8 (that's the system administration girlies 💅) — she's a server process, and she's here to format manual pages in batch mode, no cap.

---

✨ SYNOPSIS ✨

mandocd [-I os=name] [-T output] socket_fd

periodt. that's the whole summoning ritual.

---

🦋 DESCRIPTION 🦋

so mandocd formats so many manual pages for you, and the iconic part is she does it without needing fork(2) and exec(3) overhead in between every single one. main character efficiency honestly. she also does not need you to list all the manuals to be formatted on the command line, and she supports writing each formatted manual to its own file descriptor. queen behavior 🔥

big caveat alert: this server requires that a connected UNIX domain socket(2) is already present at exec(3) time.

and because of that, she literally cannot be started from the sh(1) command line — the shell just can't supply a socket like that. sorry bestie 😭

so how do people do it? typically the parent process creates the socket using socketpair(2) before calling fork(2) and exec(3) on mandocd. the parent then passes the file descriptor number as an argument to exec(3), formatted as a decimal ASCII-encoded integer. that's your socket_fd ✨ if you want to see a typical implementation of a parent process, go look at catman(8). iykyk.

here's the loop she lives in, and it's honestly such a vibe:

• mandocd loops reading one-byte messages with recvmsg(2) from the file descriptor number socket_fd.
• she ignores the byte read entirely (not her business, she's above it 🌸) 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:
  1. the first one is used for mdoc(7) or man(7) input,
  2. the second one for formatted output,
  3. and the third one for error output.

the options are as follows (yes we're doing the whole list, obsessed):

• -I os=name — override the default operating system name for the mdoc(7) Os macro 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. so clean. so tidy. we stan a girl who cleans up after herself 🧚

and then — when a zero-byte message is read, when the socket_fd is closed by the parent process, or when an error occurs — mandocd exits. bye bestie 👑

---

💀 EXIT STATUS 💀

• mandocd exits 0 on success, and >0 if an error occurs.

a zero-byte message or a closed socket_fd is considered success 💚. a win is a win.

possible errors include (get comfy, this is the vibe check):

• 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

but here's the part that lowkey changes your whole day: 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. she is unbothered. she is booked and busy. she moves on 🙈

---

🌈 SEE ALSO 🌈

• mandoc(1)
• mandoc(3)
• catman(8)

---

⭐ HISTORY ⭐

the mandocd utility appeared in version 1.14.1 or the mandoc toolkit. (that's literally what the page says, bestie, "or" and all — i just deliver the facts 💅)

---

👑 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 🔥

read this one fr fr, it's giving security warning:

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. 🌳

and avoid starting it in directories that contain secret files in any subdirectories — in particular when the user starting it has read access to these secret files. like, don't do it. protect the secrets. 🚫💀

---

kisses, this was MANDOCD(8) from the System Manager's Manual, brought to you by Debian on March 18, 2017 — slay, stay formatted, and never leave your socket unpaired 💖🎀🦋