diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2021-08-30 19:11:44 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska@appnovation.com> | 2021-08-30 19:11:44 +0000 |
| commit | 691c69e626e4ceb85567a5288348bd04378fd410 (patch) | |
| tree | 9ae1c3f2c2984aafa2b9caf7987fe0011fcf6828 /doc/libs6/s6-fdholder.html | |
| parent | 1719a60278cf36558b568349c0c9f9b5eb91c999 (diff) | |
| download | s6-691c69e626e4ceb85567a5288348bd04378fd410.tar.xz | |
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 <ska@appnovation.com>
Diffstat (limited to 'doc/libs6/s6-fdholder.html')
| -rw-r--r-- | doc/libs6/s6-fdholder.html | 229 |
1 files changed, 0 insertions, 229 deletions
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 @@ -<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>s6-fdholder</tt> library interface </h1> - -<p> - The <tt>s6-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/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> |