S6-FDHOLDER-RETRIEVE(8)

NAME
s6-fdholder-retrieve - connect to an s6-fdholderd(8) daemon listening on a Unix domain socket, retrieve a file descriptor from this daemon, then execute a program with this file descriptor as the program's standard input

SYNOPSIS
s6-fdholder-retrieve [-D] [-t timeout] path id prog...

DESCRIPTION
s6-fdholder-retrieve connects to an s6-fdholderd(8) server process listening on path.

It attempts to retrieve a copy of the file descriptor that has been stored into that daemon under identifier id.

It then executes into prog..., with the retrieved file descriptor as standard input.

To execute prog with the newly retrieved file descriptor as number n while preserving stdin, use the following construct:

    fdmove n 0 s6-fdholder-retrieve path id fdswap 0 n prog....

OPTIONS

-D  Delete the file descriptor from the server's storage after retrieval. This option requires writing rights over the given identifier as well as reading rights: check the server's configuration. Refer to s6-fdholder(7) for details.

-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 STATUS
On success, the program doesn't exit; instead, it execs into prog....

1   The server denied the operation. The meanings of the error messages are explained in s6-fdholder-error-codes(7).

100 Wrong usage.

111 System call failed - this includes attempting to connect to a nonexistent socket, or one where no s6-fdholderd(8) daemon is listening.

EXAMPLES
    s6-fdholder-retrieve /service/fdholderd/s MYSOCKET s6-ipcserverd cat

will retrieve a file descriptor stored under the ‘MYSOCKET’ identifier in the s6-fdholderd(8) daemon listening on the /service/fdholderd/s socket, and execute into ‘s6-ipcserverd cat’ with this file descriptor as stdin. In this case, if ‘MYSOCKET’ referred to a Unix domain socket, s6-ipcserverd(8) will then accept client connections on it and spawn a ‘cat’ program for every connection.

SEE ALSO
s6-fdholder-daemon(8), s6-fdholder-delete(8), s6-fdholder-getdump(8), s6-fdholder-list(8), s6-fdholder-setdump(8), s6-fdholder-store(8), s6-fdholder-transferdump(8), s6-fdholderd(8)

This man page is ported from the authoritative documentation at: https://skarnet.org/software/s6/s6-fdholder-retrieve.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)