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` connects to a s6-fdholderd server process listening on path.
- It retrieves a copy of the whole set of file descriptors stored in this daemon, including their identifiers and expiration dates.
- It then executes into prog... with the additional open descriptors and the additional environment variables.

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

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

## Environment format

prog... is executed with the following environment variables set:

- `S6_FD#` : contains the number n of file descriptors retrieved from the server.
- Then, for every i between 0 and n-1 inclusive:
  - `S6_FD_i` : contains the number of the ith open file descriptor.
  - `S6_FDID_i` : contains the identifier of the ith open file descriptor.
  - `S6_FDLIMIT_i` : contains the expiration date of the ith open file descriptor, if applicable. This date is stored in external TAI64N format.
    If the file descriptor is not supposed to expire, this environment variable is not defined.

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

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