diff options
Diffstat (limited to 'doc/libs6/fdholder.html')
| -rw-r--r-- | doc/libs6/fdholder.html | 229 |
1 files changed, 229 insertions, 0 deletions
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 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-fdholder library interface</title> + <meta name="Description" content="s6: the s6-fdholder library interface" /> + <meta name="Keywords" content="s6 fdholder file descriptor fd holding fd-passing library interface" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">libs6</a><br /> +<a href="../">s6</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>fdholder</tt> library interface </h1> + +<p> + The <tt>fdholder</tt> library provides an API for clients +wanting to communicate with a +<a href="../s6-fdholderd.html">s6-fdholderd</a> daemon. +</p> + +<h2> Programming </h2> + +<p> + Check the <tt>s6/fdholder.h</tt> header for the +exact function prototypes. +</p> + +<h3> A programming example </h3> + +<p> + The <tt>src/fdholder/s6-fdholder-*.c</tt> files in the s6 package, +for instance, illustrate how to use the s6-fdholder library. +</p> + +<h3> Synchronous functions with a specified maximum execution time </h3> + +<p> + The explanation given +<a href="ftrigr.html#synctimed">there</a> 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. +</p> + +<p> + The <a href="../s6-fdholderd.html">s6-fdholderd</a> 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. +</p> + +<h3> Starting and ending a session </h3> + +<pre> +s6_fdholder_t a = S6_FDHOLDER_ZERO ; +int fd = 6 ; + +tain_now_g() ; + +s6_fdholder_init(&a, fd) ; +(...) +s6_fdholder_free(&a) ; +</pre> + +<p> +<tt>s6_fdholder_init</tt> assumes that <em>fd</em> is a socket already +connected to an s6-fdholderd daemon. The <em>a</em> structure must be +initialized to <tt>S6_FDHOLDER_ZERO</tt> before use. +</p> + +<p> +<a href="//skarnet.org/software/skalibs/libstddjb/tai.html">tain_now_g()</a> +initializes a global variable that keeps track of the current time, for +use with later functions. +</p> + +<p> +<tt>s6_fdholder_free</tt> frees the resources occupied by <em>a</em>. +It does not, however, close <em>fd</em>. You should manually close it +to end the connection to the server. Note that if your program has been +started by <a href="../s6-ipcclient.html">s6-ipcclient</a>, both fds 6 +and 7 are open (and refer to the same socket), so you should close both. +</p> + +<p> + Alternatively, if your connection to s6-fdholderd has not been created yet, +you can use the following functions: +</p> + +<h4> <code> int s6_fdholder_start (s6_fdholder_t *a, char const *path, tain_t const *deadline, tain_t *stamp) </code> </h4> + +<p> + Starts a session with a <a href="../s6-fdholderd.html">s6-fdholderd</a> +instance listening on <em>path</em>. <em>a</em> must be initialized to +S6_FDHOLDER_ZERO before calling this function. On success, returns nonzero +and <em>a</em> can be used as a handle for the next <tt>s6_fdholder_*</tt> +function calls. On failure, returns 0, and sets errno. +</p> + +<h4> <code> void s6_fdholder_end (s6_fdholder_t *a) </code> </h4> + +<p> + Ends the current session and frees all allocated resources. If needed, +<em>a</em> is immediately reusable for another <tt>s6_fdholder_start</tt> call. +</p> + +<h3> Storing a fd </h3> + +<pre> +int r ; +int fd ; +tain_t limit = TAIN_INFINITE ; +char const *id = "my_identifier" ; +r = s6_fdholder_store_g(&a, fd, id, &limit, &deadline) ; +</pre> + +<p> +<tt>s6_fdholder_store</tt> (and its variant <tt>s6_fdholder_store_g</tt> +that uses the global timestamp variable) attempts to store a copy of +descriptor <em>fd</em> into s6-fdholderd, using identifier <em>id</em>, +with an expiration date of <em>limit</em>. In this example, <em>limit</em> +is TAIN_INFINITE, which means no expiration date. The operation should +return before <em>deadline</em>, else it will automatically return +0 ETIMEDOUT. The result is 1 on success and 0 on failure, with an +<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code. +</p> + +<h3> Deleting a fd </h3> + +<pre> +fd = s6_fdholder_delete_g(&a, id, &deadline) ; +</pre> + +<p> +<tt>s6_fdholder_delete</tt> attempts to delete the file descriptor +identified by <em>id</em>. It returns 1 on success and 0 on failure, +with an +<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code. +</p> + +<h3> Retrieving a fd </h3> + +<pre> +fd = s6_fdholder_retrieve_g(&a, id, &deadline) ; +</pre> + +<p> +<tt>s6_fdholder_retrieve</tt> attempts to retrieve the file descriptor +identified by <em>id</em>. It returns a valid fd number on success, and +-1 on failure, with an +<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code. +</p> + +<p> + <tt>s6_fdholder_retrieve_delete()</tt> performs a retrieval and a +deletion at the same time, if the client is authorized to do so. +</p> + +<h3> Listing the identifiers held by the server </h3> + +<pre> +stralloc list = STRALLOC_ZERO ; +int n ; +n = s6_fdholder_list_g(&a, &list, &deadline) ; +</pre> + +<p> +<tt>s6_fdholder_list</tt> gets the list of all identifiers currently +held by the server. It stores it into the +<a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">stralloc</a> +<em>list</em>, as a series of null-terminated strings, one after the other. +There are <em>n</em> such strings. The function returns <em>n</em> on +success, or -1 on failure, with an +<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code. +</p> + + +<h3> Reading a dump </h3> + +<pre> +genalloc dump = GENALLOC_ZERO ; +r = s6_fdholder_getdump_g(&a, &dump, &deadline) ; +</pre> + +<p> +<tt>s6_fdholder_getdump</tt> attempts to retrieve the whole set of +descriptors from the server. +It returns 1 on success, and 0 on failure, with an +<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code. +The set is stored into the +<a href="//skarnet.org/software/skalibs/libstddjb/genalloc.html">genalloc</a> +<em>dump</em>, which is to be interpreted as a stralloc containing an array +of <tt>s6_fdholder_fd_t</tt>. +</p> + +<p> +<tt>genalloc_s(s6_fdholder_fd_t, &dump)</tt> is a pointer to this array, and +<tt>genalloc_len(s6_fdholder_fd_t, &dump)</tt> is the number of elements +in the array. A <tt>s6_fdholder_fd_t</tt> contains at least a descriptor +number, an identifier, and an expiration date, see the +<tt>s6/s6-fdholder.h</tt> header file. +</p> + +<h3> Writing a dump </h3> + +<pre> +unsigned int dumplen ; +s6_fdholder_fd_t const *dumparray ; +r = s6_fdholder_setdump_g(&a, &dumparray, dumplen, &deadline) ; +</pre> + +<p> +<tt>s6_fdholder_setdump</tt> attempts to send a set of descriptors to the +server. The descriptors are contained in the array <em>dumparray</em> of +length <em>dumplen</em>. The function +returns 1 on success, and 0 on failure, with an +<a href="../s6-fdholder-errorcodes.html">appropriate</a> errno code. +</p> + +</body> +</html> |