s6: the s6-fdholder-store program
Keywords: s6 s6-fdholder fd-holding fd-holder fd storage unix socket activation

s6
Software
skarnet.org

# The `s6-fdholder-store` program

`s6-fdholder-store` connects to a fd-holding daemon listening on a Unix domain socket, and gives it a copy of one of its open file descriptors for the daemon to hold.

## Interface

         s6-fdholder-store [ -d fd ] [ -T fdtimeout ] [ -t timeout ] path id

- s6-fdholder-store executes into `s6-ipcclient path s6-fdholder-storec id`. 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-storec program transmits the desired file descriptor over the socket.
- It should be used to connect to a s6-fdholderd daemon, which will store the file descriptor given by the user.

## Options

- `-d fd` : store descriptor number fd. By default, fd is 0 (i.e. the program's stdin will be stored). s6-fdholder-store replaces its stdin with fd before executing into `s6-ipcclient s6-fdholder-storec`.
- `-T fdtimeout` : the descriptor is stored with an expiration time of fdtimeout milliseconds, which means the s6-fdholderd daemon will close and get rid of the descriptor after that time. By default, fdtimeout is 0, which means infinite - no expiration time.
- `-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-ipcserver-socketbinder /tmp/mysocket s6-fdholder-store /service/fdholderd/s MYSOCKET

will open a Unix domain socket, bind it to `/tmp/mysocket` and listen to incoming connections, then give it to a s6-fdholderd instance listening on `/service/fdholderd/s`, with no expiration date, with the "MYSOCKET" identifier. Another program will be able to retrieve the socket later, using s6-fdholder-retrieve.