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 +++++++++++++++++++++++++++++++++++++++++++ doc/libs6/index.html | 4 +- doc/libs6/lock.html | 239 +++++++++++++++++++++++++++++++++++++++++++++ doc/libs6/s6-fdholder.html | 229 ------------------------------------------- doc/libs6/s6lock.html | 239 --------------------------------------------- 5 files changed, 470 insertions(+), 470 deletions(-) create mode 100644 doc/libs6/fdholder.html create mode 100644 doc/libs6/lock.html delete mode 100644 doc/libs6/s6-fdholder.html delete mode 100644 doc/libs6/s6lock.html (limited to 'doc/libs6') 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. +

+ + + diff --git a/doc/libs6/index.html b/doc/libs6/index.html index 2f93493..1db2e5e 100644 --- a/doc/libs6/index.html +++ b/doc/libs6/index.html @@ -65,9 +65,9 @@ provides functions to check credentials against configuration files. functions to subscribe to fifodirs and be notified of events.
  • The s6/ftrigw.h header provides functions to manage fifodirs and send notifications to them.
    • -
  • The s6/s6lock.h header provides +
  • The s6/lock.h header provides functions to acquire locks with a timeout.
    • -
  • The s6/s6-fdholder.h header provides +
  • The s6/fdholder.h header provides functions to communicate with a s6-fdholderd server and exchange file descriptors with it.
    • diff --git a/doc/libs6/lock.html b/doc/libs6/lock.html new file mode 100644 index 0000000..1cc896d --- /dev/null +++ b/doc/libs6/lock.html @@ -0,0 +1,239 @@ + + + + + + s6: the s6lock library interface + + + + + + +

    +libs6
    +s6
    +Software
    +skarnet.org +

    + +

    The s6lock library interface

    + +

    General information

    + +

    + s6lock is a C interface to timed locks. Unix natively provides +locks, but the locking primitives are synchronous, so either they are +unbounded in execution time or they require polling. s6lock provides +poll-free locks that can timeout during attempted acquisition. +

    + +

    Programming

    + + + +

    Starting and ending a session

    + +
    +s6lock_t a = S6LOCK_ZERO ;
+tain_t deadline ;
+
+tain_now_g() ;
+tain_addsec_g(&deadline, 2)
+
+char const *path = S6LOCK_IPCPATH ;
+s6lock_start_g(&a, path, &deadline) ;
+// char const *lockdir = "/tmp/lock" ;
+// s6lock_startf_g(&a, lockdir, &deadline) ;
+
    + +

    +s6lock_start_g starts a session by connecting to an s6lockd service +listening on path. The working directory is set by the administrator +of the service.
    +s6lock_startf_g starts a session with an s6lockd process as a child, +using lockdir as its working directory. +
    +a is an s6lock_t structure that must be declared in the stack and +initialized to S6LOCK_ZERO. +If the session initialization fails, the function returns 0 and errno is set; +else the function returns 1. +

    +

    +If the absolute time deadline is reached and the function +has not returned yet, it immediately returns 0 with errno set to ETIMEDOUT. + +Only local interprocess communications are involved; unless your system is +heavily overloaded, the function should return near-instantly. One or two +seconds of delay between the current time and deadline should be +enough: if the function takes more than that to return, then there is a +problem with the underlying processes. +

    + +

    + You can have more than one session open in parallel, by declaring +several distinct s6lock_t structures and calling +s6lock_startf_g (or s6lock_start_g) more than once. +However, one single session can handle +virtually as many concurrent locks as your application needs, so +opening several sessions is only useful if you need to acquire locks +in various distinct lock directories. +

    + +
    +s6lock_end(&a) ;
+
    + +

    +s6lock_end frees all the resources used by the session. The +a structure is then reusable for another session. +

    + +

    Acquiring and releasing locks

    + +
    +uint16_t id ;
+char const *file = "lockfile" ;
+tain_t limit ;
+tain_t deadline ;
+
+int r = s6lock_acquire_sh_g (&a, &id, file, &limit, &deadline) ;
+/* int r = s6lock_acquire_ex_g (&a, &id, file, &limit, &deadline) ; */
+r = s6lock_release_g(&a, id, &deadline) ;
+
    + +

    +s6lock_acquire_sh_g instructs the +s6lockd daemon, related to the open +session represented by the a handle, to try and acquire a +shared lock on the +file file located under that daemon's working directory +(typically /var/lock). file will be interpreted as +relative to the daemon's working directory even if it starts with a +slash; however, slashes in the middle of file are likely to +result in an error. +

    + +

    +limit and deadline are two absolute dates. +deadline is a deadline for the execution of the +function: if by deadline the function has not returned, +then it instantly returns 0 and sets errno to ETIMEDOUT. The +function is normally near-instantaneous, so deadline can +be very close in the future and serves only as a protection against +malicious servers. limit is the acquisition deadline: if +by limit the daemon still has not been able to acquire a lock +on file, then it will report a timeout to the client. +

    + +

    +The function returns 1 in case of success, or 0 if an error occurs, +with errno set to a suitable value. If it succeeds, then a 16-bit +number is stored into *id; this number serves as an identifier +for this lock. +

    + +

    +s6lock_acquire_ex_g works just like s6lock_acquire_sh_g, +except that the daemon tries to acquire an exclusive lock. +

    + +

    +s6lock_release_g releases the lock identified by id. +It normally returns 1. It can return 0 with errno set to a suitable +value if it fails. id is not valid after the corresponding +lock has been released. The function normally returns instantly, with +deadline as a safeguard. +

    + +

    Asynchronously waiting for locks

    + +

    + (from now on, the functions are listed with their prototypes instead +of usage examples.) +

    + +
    +int s6lock_fd (s6lock_t const *a)
+
    + +

    + Returns a file descriptor to select on for reading. Do not +read() it though. +

    + +
    +int s6lock_update (s6lock_t *a)
+
    + +

    + Call this function whenever the fd checks readability: it will +update a's internal structures with information from the +s6lockd daemon. It returns -1 if an error +occurs; in case of success, it returns the number of identifiers for +which something happened. +

    + +

    + When s6lock_update returns, +genalloc_s(uint16_t, &a->list) points to an array of +genalloc_len(uint16_t, &a->list) 16-bit unsigned +integers. Those integers are ids waiting to be passed to +s6lock_check. +

    + +
    +int s6lock_check (s6lock_t *a, uint16_t id, char *what)
+
    + +

    + Checks whether the lock identified by id has +been acquired. Use after a call to s6lock_update(). +

    + + + +

    Synchronously waiting for locks

    + +

    + int s6lock_wait_or_g (s6lock_t *a, uint16_t const *idlist, unsigned int n, tain_t const *deadline)
    +Synchronously waits for one of the locks represented by the array pointed to +by idlist of length n to be acquired. Returns -1 if it fails, +or a nonnegative number on success, which is the index in idlist of the +acquired lock's id. If no result has been obtained by deadline, the +function returns -1 ETIMEDOUT. +

    + +

    + int s6lock_wait_and_g (s6lock_t *a, uint16_t const *idlist, unsigned int n, tain_t const *deadline)
    +Synchronously waits for all of the locks represented by the array pointed to +by idlist of length n to be acquired. Returns -1 if it fails and +0 if it succeeds. If no result has been obtained by deadline, the +function returns -1 ETIMEDOUT. +

    + + + 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. -

    - - - diff --git a/doc/libs6/s6lock.html b/doc/libs6/s6lock.html deleted file mode 100644 index 049ed44..0000000 --- a/doc/libs6/s6lock.html +++ /dev/null @@ -1,239 +0,0 @@ - - - - - - s6: the s6lock library interface - - - - - - -

    -libs6
    -s6
    -Software
    -skarnet.org -

    - -

    The s6lock library interface

    - -

    General information

    - -

    - s6lock is a C interface to timed locks. Unix natively provides -locks, but the locking primitives are synchronous, so either they are -unbounded in execution time or they require polling. s6lock provides -poll-free locks that can timeout during attempted acquisition. -

    - -

    Programming

    - - - -

    Starting and ending a session

    - -
    -s6lock_t a = S6LOCK_ZERO ;
-tain_t deadline ;
-
-tain_now_g() ;
-tain_addsec_g(&deadline, 2)
-
-char const *path = S6LOCK_IPCPATH ;
-s6lock_start_g(&a, path, &deadline) ;
-// char const *lockdir = "/tmp/lock" ;
-// s6lock_startf_g(&a, lockdir, &deadline) ;
-
    - -

    -s6lock_start_g starts a session by connecting to an s6lockd service -listening on path. The working directory is set by the administrator -of the service.
    -s6lock_startf_g starts a session with an s6lockd process as a child, -using lockdir as its working directory. -
    -a is an s6lock_t structure that must be declared in the stack and -initialized to S6LOCK_ZERO. -If the session initialization fails, the function returns 0 and errno is set; -else the function returns 1. -

    -

    -If the absolute time deadline is reached and the function -has not returned yet, it immediately returns 0 with errno set to ETIMEDOUT. - -Only local interprocess communications are involved; unless your system is -heavily overloaded, the function should return near-instantly. One or two -seconds of delay between the current time and deadline should be -enough: if the function takes more than that to return, then there is a -problem with the underlying processes. -

    - -

    - You can have more than one session open in parallel, by declaring -several distinct s6lock_t structures and calling -s6lock_startf_g (or s6lock_start_g) more than once. -However, one single session can handle -virtually as many concurrent locks as your application needs, so -opening several sessions is only useful if you need to acquire locks -in various distinct lock directories. -

    - -
    -s6lock_end(&a) ;
-
    - -

    -s6lock_end frees all the resources used by the session. The -a structure is then reusable for another session. -

    - -

    Acquiring and releasing locks

    - -
    -uint16_t id ;
-char const *file = "lockfile" ;
-tain_t limit ;
-tain_t deadline ;
-
-int r = s6lock_acquire_sh_g (&a, &id, file, &limit, &deadline) ;
-/* int r = s6lock_acquire_ex_g (&a, &id, file, &limit, &deadline) ; */
-r = s6lock_release_g(&a, id, &deadline) ;
-
    - -

    -s6lock_acquire_sh_g instructs the -s6lockd daemon, related to the open -session represented by the a handle, to try and acquire a -shared lock on the -file file located under that daemon's working directory -(typically /var/lock). file will be interpreted as -relative to the daemon's working directory even if it starts with a -slash; however, slashes in the middle of file are likely to -result in an error. -

    - -

    -limit and deadline are two absolute dates. -deadline is a deadline for the execution of the -function: if by deadline the function has not returned, -then it instantly returns 0 and sets errno to ETIMEDOUT. The -function is normally near-instantaneous, so deadline can -be very close in the future and serves only as a protection against -malicious servers. limit is the acquisition deadline: if -by limit the daemon still has not been able to acquire a lock -on file, then it will report a timeout to the client. -

    - -

    -The function returns 1 in case of success, or 0 if an error occurs, -with errno set to a suitable value. If it succeeds, then a 16-bit -number is stored into *id; this number serves as an identifier -for this lock. -

    - -

    -s6lock_acquire_ex_g works just like s6lock_acquire_sh_g, -except that the daemon tries to acquire an exclusive lock. -

    - -

    -s6lock_release_g releases the lock identified by id. -It normally returns 1. It can return 0 with errno set to a suitable -value if it fails. id is not valid after the corresponding -lock has been released. The function normally returns instantly, with -deadline as a safeguard. -

    - -

    Asynchronously waiting for locks

    - -

    - (from now on, the functions are listed with their prototypes instead -of usage examples.) -

    - -
    -int s6lock_fd (s6lock_t const *a)
-
    - -

    - Returns a file descriptor to select on for reading. Do not -read() it though. -

    - -
    -int s6lock_update (s6lock_t *a)
-
    - -

    - Call this function whenever the fd checks readability: it will -update a's internal structures with information from the -s6lockd daemon. It returns -1 if an error -occurs; in case of success, it returns the number of identifiers for -which something happened. -

    - -

    - When s6lock_update returns, -genalloc_s(uint16_t, &a->list) points to an array of -genalloc_len(uint16_t, &a->list) 16-bit unsigned -integers. Those integers are ids waiting to be passed to -s6lock_check. -

    - -
    -int s6lock_check (s6lock_t *a, uint16_t id, char *what)
-
    - -

    - Checks whether the lock identified by id has -been acquired. Use after a call to s6lock_update(). -

    - - - -

    Synchronously waiting for locks

    - -

    - int s6lock_wait_or_g (s6lock_t *a, uint16_t const *idlist, unsigned int n, tain_t const *deadline)
    -Synchronously waits for one of the locks represented by the array pointed to -by idlist of length n to be acquired. Returns -1 if it fails, -or a nonnegative number on success, which is the index in idlist of the -acquired lock's id. If no result has been obtained by deadline, the -function returns -1 ETIMEDOUT. -

    - -

    - int s6lock_wait_and_g (s6lock_t *a, uint16_t const *idlist, unsigned int n, tain_t const *deadline)
    -Synchronously waits for all of the locks represented by the array pointed to -by idlist of length n to be acquired. Returns -1 if it fails and -0 if it succeeds. If no result has been obtained by deadline, the -function returns -1 ETIMEDOUT. -

    - - - -- cgit v1.2.3