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

s6
Software
skarnet.org

# The `s6-fdholder-setdump` program

`s6-fdholder-setdump` connects to a fd-holding daemon listening on a Unix domain socket, and dumps a set of file descriptors into that daemon.

## Interface

         s6-fdholder-setdump [ -t timeout ] path

- `s6-fdholder-setdump` connects to a s6-fdholderd server process listening on path.
- It attempts to pass a complete state - i.e. a set of file descriptors with identifiers and expiration dates - to the server.

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

## Exit codes

- 0: success.
- 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.

## Notes

- The file descriptors to transmit to the server should of course be already open in the `s6-fdholder-setdump` program; also, `s6-fdholder-setdump` should have certain environment variables that describe that set of file descriptors. The format of the environment is the same as the one set by s6-fdholder-getdump.
- Setting the whole state of an s6-fdholderd daemon requires specific privileges. Make sure you properly configure the s6-fdholderd access rights so your client can perform that operation.
- Previously held fds will still be kept by the server (so, "setting" the state is more like "adding to" the state), unless there is an identifier collision, in which case the fd in the transmitted set takes precedence and the previously held fd is overwritten.