From 691c69e626e4ceb85567a5288348bd04378fd410 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 30 Aug 2021 19:11:44 +0000 Subject: s6-svlink, s6-svunlink, .h changes Renamed from s6-svdir-(un)link. Doc added. Full functionality added. Still need to be tested. Unrelated: .h names simplified. Signed-off-by: Laurent Bercot --- doc/libs6/fdholder.html | 229 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 doc/libs6/fdholder.html (limited to 'doc/libs6/fdholder.html') diff --git a/doc/libs6/fdholder.html b/doc/libs6/fdholder.html new file mode 100644 index 0000000..c874805 --- /dev/null +++ b/doc/libs6/fdholder.html @@ -0,0 +1,229 @@ + + + + + + s6: the s6-fdholder 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 s6-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/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. +

+ + + -- cgit v1.2.3