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