quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

curl_multi_fdset.md (4010B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: curl_multi_fdset
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - curl_multi_cleanup (3)
      9   - curl_multi_init (3)
     10   - curl_multi_perform (3)
     11   - curl_multi_timeout (3)
     12   - curl_multi_wait (3)
     13   - curl_multi_waitfds (3)
     14   - select (2)
     15 Protocol:
     16   - All
     17 Added-in: 7.9.6
     18 ---
     19 
     20 # NAME
     21 
     22 curl_multi_fdset - extract file descriptor information from a multi handle
     23 
     24 # SYNOPSIS
     25 
     26 ~~~c
     27 #include <curl/curl.h>
     28 
     29 CURLMcode curl_multi_fdset(CURLM *multi_handle,
     30                            fd_set *read_fd_set,
     31                            fd_set *write_fd_set,
     32                            fd_set *exc_fd_set,
     33                            int *max_fd);
     34 ~~~
     35 
     36 # DESCRIPTION
     37 
     38 This function extracts file descriptor information from a given multi_handle.
     39 libcurl returns its *fd_set* sets. The application can use these to
     40 select() on, but be sure to *FD_ZERO* them before calling this function as
     41 curl_multi_fdset(3) only adds its own descriptors, it does not zero or
     42 otherwise remove any others. The curl_multi_perform(3) function should
     43 be called as soon as one of them is ready to be read from or written to.
     44 
     45 The *read_fd_set* argument should point to an object of type **fd_set**
     46 that on returns specifies the file descriptors to be checked for being ready
     47 to read.
     48 
     49 The *write_fd_set* argument should point to an object of type **fd_set**
     50 that on return specifies the file descriptors to be checked for being ready to
     51 write.
     52 
     53 The *exc_fd_set* argument should point to an object of type **fd_set**
     54 that on return specifies the file descriptors to be checked for error
     55 conditions.
     56 
     57 If no file descriptors are set by libcurl, *max_fd* contain -1 when this
     58 function returns. Otherwise it contains the highest descriptor number libcurl
     59 set. When libcurl returns -1 in *max_fd*, it is because libcurl currently
     60 does something that is not possible for your application to monitor with a
     61 socket and unfortunately you can then not know exactly when the current action
     62 is completed using select(). You then need to wait a while before you proceed
     63 and call curl_multi_perform(3) anyway. How long to wait? Unless
     64 curl_multi_timeout(3) gives you a lower number, we suggest 100
     65 milliseconds or so, but you may want to test it out in your own particular
     66 conditions to find a suitable value.
     67 
     68 When doing select(), you should use curl_multi_timeout(3) to figure out
     69 how long to wait for action. Call curl_multi_perform(3) even if no
     70 activity has been seen on the **fd_sets** after the timeout expires as
     71 otherwise internal retries and timeouts may not work as you would think and
     72 want.
     73 
     74 If one of the sockets used by libcurl happens to be larger than what can be
     75 set in an **fd_set**, which on POSIX systems means that the file descriptor
     76 is larger than **FD_SETSIZE**, then libcurl tries to not set it. Setting a
     77 too large file descriptor in an **fd_set** implies an out of bounds write
     78 which can cause crashes, or worse. The effect of NOT storing it might possibly
     79 save you from the crash, but makes your program NOT wait for sockets it should
     80 wait for...
     81 
     82 # %PROTOCOLS%
     83 
     84 # EXAMPLE
     85 
     86 ~~~c
     87 int main(void)
     88 {
     89   fd_set fdread;
     90   fd_set fdwrite;
     91   fd_set fdexcep;
     92   int maxfd;
     93   int rc;
     94   CURLMcode mc;
     95   struct timeval timeout = {1, 0};
     96 
     97   CURLM *multi = curl_multi_init();
     98 
     99   do {
    100 
    101     /* call curl_multi_perform() */
    102 
    103     FD_ZERO(&fdread);
    104     FD_ZERO(&fdwrite);
    105     FD_ZERO(&fdexcep);
    106 
    107     /* get file descriptors from the transfers */
    108     mc = curl_multi_fdset(multi, &fdread, &fdwrite, &fdexcep, &maxfd);
    109 
    110     if(mc != CURLM_OK) {
    111       fprintf(stderr, "curl_multi_fdset() failed, code %d.\n", mc);
    112       break;
    113     }
    114 
    115     /* wait for activity on one of the sockets */
    116     rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout);
    117 
    118   } while(!mc);
    119 }
    120 ~~~
    121 
    122 # %AVAILABILITY%
    123 
    124 # RETURN VALUE
    125 
    126 This function returns a CURLMcode indicating success or error.
    127 
    128 CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
    129 libcurl-errors(3).