s6: the s6-fdholder-retrieve program

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 this daemon, then executes a program with this file descriptor as the program's standard input.

Interface

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

s6-fdholder-retrieve connects to a s6-fdholderd server process listening on path.
It attempts to retrieve a copy of the file descriptor that has been stored into that daemon under identifier id.
It then executes into prog..., with the retrieved file descriptor as 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).

Exit codes

On success, the program doesn't exit; instead, it execs into prog....
1: the server denied the operation. The meaning of the error messages is explained here.
100: wrong usage.
111: system call failed - this includes attempting to connect to a nonexistent socket, or one where no s6-fdholderd daemon is listening.

Usage example

   s6-fdholder-retrieve /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 this 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