s6: the s6-fdholder-getdump program
Keywords: s6 s6-fdholder fd-holding fd-holder fd dump retrieval unix socket activation

s6
Software
skarnet.org

# The `s6-fdholder-getdump` program

`s6-fdholder-getdump` connects to a fd-holding daemon listening on a Unix domain socket, and retrieves its entire state: file descriptors with their identifiers and expiration dates. It then executes a program with those file descriptors still open, and the state stored in the environment.

## Interface

         s6-fdholder-getdump [ -t timeout ] path prog...

- s6-fdholder-getdump executes into `s6-ipcclient path s6-fdholder-getdumpc 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-getdumpc program gets the server's state over the socket.
- It executes into prog... with as many more open file descriptors as there were in the daemon, and information about those file descriptors in the environment.

## Options

- `-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-getdump /service/fdholderd/s s6-fdholder-setdump /service/fdholderd-2/s

will get the state of the s6-fdholderd daemon listening on the `/service/fdholderd/s` socket, and transmit it to the other s6-fdholderd daemon listening on the `/service/fdholderd-2/s` socket. Note that in this precise case, the s6-fdholder-transferdump program does the same thing more efficiently.

## Notes

- s6-fdholder-getdump really executes into `s6-ipcclient s6-fdholder-getdumpc 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-getdumpc` manually.
- The exact format of the environment given to prog... is described in the s6-fdholder-getdumpc page.
- Getting the whole state of a s6-fdholderd daemon requires specific privileges. Make sure you properly configure the s6-fdholderd access rights so your client can perform that operation.