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/s6-fdholder.html | 229 --------------------------------------------- 1 file changed, 229 deletions(-) delete mode 100644 doc/libs6/s6-fdholder.html (limited to 'doc/libs6/s6-fdholder.html') diff --git a/doc/libs6/s6-fdholder.html b/doc/libs6/s6-fdholder.html deleted file mode 100644 index 4a2fb25..0000000 --- a/doc/libs6/s6-fdholder.html +++ /dev/null @@ -1,229 +0,0 @@ - - - - - - s6: the s6-fdholder library interface - - - - - - -

-libs6
-s6
-Software
-skarnet.org -

- -

The s6-fdholder library interface

- -

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

- -

Programming

- -

- Check the s6/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