s6
Software
skarnet.org

The s6-fdholder-retrieve program

s6-fdholder-retrieve connects to a fd-holding daemon listening on a Unix domain socket, and retrieves a file descriptor from that daemon, then executes a program with that file descriptor as the program's standard input.

Interface

     s6-fdholder-retrieve [ -D ] [ -t timeout ] path id prog...

• s6-fdholder-retrieve executes into s6-ipcclient path s6-fdholder-retrievec id prog.... It does nothing else: it is just a convenience program. The s6-ipcclient program connects to a Unix socket at path, and the s6-fdholder-retrievec program gets the file descriptor identified by id over the socket.
• It should be used to connect to a s6-fdholderd daemon, which will pass the file descriptor to the client over the path socket.
• It executes into prog... with the retrieved file descriptor as prog...'s standard input.

Options

• -D : delete the file descriptor from the server's storage after retrieval. This option requires writing rights over the given identifier as well as reading rights: check the server's configuration.
• -t timeout : if the operation cannot be processed in timeout milliseconds, then fail with an error message. Communications with the server should be near-instant, so this option is only here to protect users against programming errors (connecting to the wrong socket, for instance).

Usage example

   s6-fdholder-store /service/fdholderd/s MYSOCKET s6-ipcserverd cat

will retrieve a file descriptor stored under the MYSOCKET identifier in the s6-fdholderd daemon listening on the /service/fdholderd/s socket, and execute into s6-ipcserverd cat with that file descriptor as stdin. In this case, if MYSOCKET referred to a Unix domain socket, s6-ipcserverd will then accept client connections on it and spawn a cat program for every connection.

Notes

• s6-fdholder-retrieve really executes into s6-ipcclient s6-fdholder-retrievec fdclose 6 fdclose 7 prog..., so that prog... does not have a connection with the fd-holding daemon anymore. If you want to keep the server connection open for prog..., use s6-ipcclient s6-fdholder-retrievec manually.
• To execute prog with the newly retrieved file descriptor as number n while preserving stdin, use the following construct: fdmove n 0 s6-fdholder-retrieve path id fdswap 0 n prog.... Be aware that n cannot be 6 or 7, internally used by s6-fdholder-retrieve.