From 8bffa1c19fd05f4f04dad4b5b98f85b94f23113c Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 26 Jan 2015 22:26:57 +0000 Subject: - added s6-fdholder-delete(c) - small s6-fdholder-* fixes - s6-fdholder documentation (in review) - s6_svstatus_* bugfix (thanks Olivier Brunel) --- doc/libs6/ftrigr.html | 3 +- doc/libs6/index.html | 6 +- doc/libs6/s6-fdholder.html | 207 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 214 insertions(+), 2 deletions(-) create mode 100644 doc/libs6/s6-fdholder.html (limited to 'doc/libs6') diff --git a/doc/libs6/ftrigr.html b/doc/libs6/ftrigr.html index 2c9bf88..0a83534 100644 --- a/doc/libs6/ftrigr.html +++ b/doc/libs6/ftrigr.html @@ -55,8 +55,9 @@ children, consider using a ftrigrd service. for instance, illustrate how to use the ftrigr library.

- +

Synchronous functions with a specified maximum execution time

+ diff --git a/doc/libs6/s6-fdholder.html b/doc/libs6/s6-fdholder.html new file mode 100644 index 0000000..79c4725 --- /dev/null +++ b/doc/libs6/s6-fdholder.html @@ -0,0 +1,207 @@ + + + + + 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.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 a 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. +

+ +

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