SENDFD(1)

✨ sendfd — The sendfd program ✨

okay so bestie, welcome to the manual page for The sendfd program — header has that lil () after it, and that's the vibe. the actual command is sendfd, and she is here to hand off file descriptors like an absolute queen. 💅

🌀 SYNOPSIS 🌀

sendfd socket fd [...] [: command arg ...]

💖 DESCRIPTION 💖

okay so sendfd passes one or more inherited file descriptors over a Unix-domain socket. the sockets in question can be ones opened with s6-ipcclient (https://skarnet.org/software/s6/s6-ipcclient.html), s6-ipcserver (https://skarnet.org/software/s6/s6-ipcserver.html), or ucspi-unix (https://untroubled.org/ucspi-unix/) — yes bestie, those exact links, keep them. 🦋

another process that has a descriptor for the other end of the socket can receive the descriptors using the fd_xfer_recv(), fd_xfer_child(), or fd_xfer_ucspi() library functions. 💌

ngl, this part is crucial: the received descriptors will not necessarily have the same numeric values, but they will refer to the same open file handles, as if by dup(). so the numbers can change; the actual open file handle energy does not. periodt. ✨

after passing the descriptors, sendfd execs the given command, if any. and yes — a colon separates the file descriptors from the command. : is the divider, the little boundary line, the "fds on this side, command on that side" moment. 🎀

💫 why would you use this? 💫

this is useful, for example, in network clients that want to use UCSPI client programs to establish connections, but which can't have all connections opened at startup. highkey a whole mood. 😭

when the client is ready to open a new connection, it can create a socket using socketpair(), and then spawn tcpclient (or any other UCSPI client), with sendfd given to tcpclient as a subcommand to pass the new connection descriptor back to the original process over the socketpair() socket. literally the group chat of file descriptors — the new connection gets passed back home. 🫶

💖 footer check: The sendfd program() — that's the footer this page ends on, and no separate source/version/date is listed, so that's the whole page, bestie. no cap, slay. 🎀✨