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