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

s6
Software
skarnet.org

# The `s6-fdholder-getdumpc` program

`s6-fdholder-getdumpc` talks to a fd-holding daemon on its open descriptors 6 and 7, and retrieves its whole state, then executes a program with as many more file descriptors open as were given by the daemon, plus a modified environment to describe the retrieved state.

## Interface

         s6-fdholder-getdumpc [ -t timeout ] prog...

- s6-fdholder-getdumpc expects to talk to a listening s6-fdholderd program on its descriptors 6 and 7.
- It retrieves a copy of the whole set of file descriptors stored in that daemon, including their identifiers and expiration dates.
- It then executes into prog... with the additional descriptors and 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.

## 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. That date is stored in external TAI64N format.
  If the file descriptor is not supposed to expire, that environment variable is not defined.

## Notes

- s6-fdholder-getdumpc is the "internal" version of s6-fdholder-getdump. It simply expects to be run as a UCSPI client, i.e. talking to the server over descriptors 6 and 7, instead of connecting to the server itself.
- 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.
- The error messages for the s6-fdholder suite are explained here.