s6: the s6-fdholder library interface
Keywords: s6 fdholder file descriptor fd holding fd-passing library interface

libs6
s6
Software
skarnet.org

# The `fdholder` library interface

The `fdholder` library provides an API for clients wanting to communicate with a s6-fdholderd daemon.

## Programming

Check the `s6/fdholder.h` header for the exact function prototypes.

### A programming example

The `src/fdholder/s6-fdholder-*.c` files in the s6 package, for instance, illustrate how to use the fdholder library.

### Synchronous functions with a specified maximum execution time

The explanation given there applies here too: the functions documented in this page are synchronous, but can return early if the deadline is reached, in which case the connection to the server should be closed immediately because no protocol consistency is guaranteed.

The s6-fdholderd server should be very quick to answer queries, so this mechanism is provided as a simple security against programming errors - for instance, connecting to the wrong daemon.

### Starting and ending a session

    s6_fdholder_t a = S6_FDHOLDER_ZERO ;
    int fd = 6 ;

    tain_now_g() ;

    s6_fdholder_init(&a, fd) ;
    (...)
    s6_fdholder_free(&a) ;

`s6_fdholder_init` assumes that fd is a socket already connected to an s6-fdholderd daemon. The a structure must be initialized to `S6_FDHOLDER_ZERO` before use.

tain_now_g() initializes a global variable that keeps track of the current time, for use with later functions.

`s6_fdholder_free` frees the resources occupied by a. It does not, however, close fd. You should manually close it to end the connection to the server. Note that if your program has been started by s6-ipcclient, both fds 6 and 7 are open (and refer to the same socket), so you should close both.

Alternatively, if your connection to s6-fdholderd has not been created yet, you can use the following functions:

#### `int s6_fdholder_start (s6_fdholder_t *a, char const *path, tain_t const *deadline, tain_t *stamp)`

Starts a session with a s6-fdholderd instance listening on path. a must be initialized to S6_FDHOLDER_ZERO before calling this function. On success, returns nonzero and a can be used as a handle for the next `s6_fdholder_*` function calls. On failure, returns 0, and sets errno.

#### `void s6_fdholder_end (s6_fdholder_t *a)`

Ends the current session and frees all allocated resources. If needed, a is immediately reusable for another `s6_fdholder_start` call.

### Storing a fd

    int r ;
    int fd ;
    tain_t limit = TAIN_INFINITE ;
    char const *id = "my_identifier" ;
    r = s6_fdholder_store_g(&a, fd, id, &limit, &deadline) ;

`s6_fdholder_store` (and its variant `s6_fdholder_store_g` that uses the global timestamp variable) attempts to store a copy of descriptor fd into s6-fdholderd, using identifier id, with an expiration date of limit. In this example, limit is TAIN_INFINITE, which means no expiration date. The operation should return before deadline, else it will automatically return 0 ETIMEDOUT. The result is 1 on success and 0 on failure, with an appropriate errno code.

### Deleting a fd

    fd = s6_fdholder_delete_g(&a, id, &deadline) ;

`s6_fdholder_delete` attempts to delete the file descriptor identified by id. It returns 1 on success and 0 on failure, with an appropriate errno code.

### Retrieving a fd

    fd = s6_fdholder_retrieve_g(&a, id, &deadline) ;

`s6_fdholder_retrieve` attempts to retrieve the file descriptor identified by id. It returns a valid fd number on success, and -1 on failure, with an appropriate errno code.

`s6_fdholder_retrieve_delete()` performs a retrieval and a deletion at the same time, if the client is authorized to do so.

### Listing the identifiers held by the server

    stralloc list = STRALLOC_ZERO ;
    int n ;
    n = s6_fdholder_list_g(&a, &list, &deadline) ;

`s6_fdholder_list` gets the list of all identifiers currently held by the server. It stores it into the stralloc list, as a series of null-terminated strings, one after the other. There are n such strings. The function returns n on success, or -1 on failure, with an appropriate errno code.

### Reading a dump

    genalloc dump = GENALLOC_ZERO ;
    r = s6_fdholder_getdump_g(&a, &dump, &deadline) ;

`s6_fdholder_getdump` attempts to retrieve the whole set of descriptors from the server. It returns 1 on success, and 0 on failure, with an appropriate errno code. The set is stored into the genalloc dump, which is to be interpreted as a stralloc containing an array of `s6_fdholder_fd_t`.

`genalloc_s(s6_fdholder_fd_t, &dump)` is a pointer to this array, and `genalloc_len(s6_fdholder_fd_t, &dump)` is the number of elements in the array. A `s6_fdholder_fd_t` contains at least a descriptor number, an identifier, and an expiration date, see the `s6/fdholder.h` header file.

### Writing a dump

    unsigned int dumplen ;
    s6_fdholder_fd_t const *dumparray ;
    r = s6_fdholder_setdump_g(&a, &dumparray, dumplen, &deadline) ;

`s6_fdholder_setdump` attempts to send a set of descriptors to the server. The descriptors are contained in the array dumparray of length dumplen. The function returns 1 on success, and 0 on failure, with an appropriate errno code.