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.