1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_multi_wait 5Section: 3 6Source: libcurl 7See-also: 8 - curl_multi_fdset (3) 9 - curl_multi_perform (3) 10 - curl_multi_poll (3) 11Protocol: 12 - All 13--- 14 15# NAME 16 17curl_multi_wait - polls on all easy handles in a multi handle 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24CURLMcode curl_multi_wait(CURLM *multi_handle, 25 struct curl_waitfd extra_fds[], 26 unsigned int extra_nfds, 27 int timeout_ms, 28 int *numfds); 29~~~ 30 31# DESCRIPTION 32 33curl_multi_wait(3) polls all file descriptors used by the curl easy 34handles contained in the given multi handle set. It blocks until activity is 35detected on at least one of the handles or *timeout_ms* has passed. 36Alternatively, if the multi handle has a pending internal timeout that has a 37shorter expiry time than *timeout_ms*, that shorter time is be used 38instead to make sure timeout accuracy is reasonably kept. 39 40The calling application may pass additional *curl_waitfd* structures which 41are similar to *poll(2)*'s *pollfd* structure to be waited on in the 42same call. 43 44On completion, if *numfds* is non-NULL, it gets populated with the total 45number of file descriptors on which interesting events occurred. This number 46can include both libcurl internal descriptors as well as descriptors provided 47in *extra_fds*. 48 49If no extra file descriptors are provided and libcurl has no file descriptor 50to offer to wait for, this function returns immediately. (Consider using 51curl_multi_poll(3) to avoid this behavior.) 52 53This function is encouraged to be used instead of select(3) when using the 54multi interface to allow applications to easier circumvent the common problem 55with 1024 maximum file descriptors. 56 57# curl_waitfd 58 59~~~c 60struct curl_waitfd { 61 curl_socket_t fd; 62 short events; 63 short revents; 64}; 65~~~ 66 67## CURL_WAIT_POLLIN 68 69Bit flag to *curl_waitfd.events* indicating the socket should poll on read 70events such as new data received. 71 72## CURL_WAIT_POLLPRI 73 74Bit flag to *curl_waitfd.events* indicating the socket should poll on high 75priority read events such as out of band data. 76 77## CURL_WAIT_POLLOUT 78 79Bit flag to *curl_waitfd.events* indicating the socket should poll on 80write events such as the socket being clear to write without blocking. 81 82# EXAMPLE 83 84~~~c 85int main(void) 86{ 87 CURL *easy; 88 CURLM *multi = curl_multi_init(); 89 int still_running; 90 91 /* add the individual easy handle */ 92 curl_multi_add_handle(multi, easy); 93 94 do { 95 CURLMcode mc; 96 int numfds; 97 98 mc = curl_multi_perform(multi, &still_running); 99 100 if(mc == CURLM_OK) { 101 /* wait for activity, timeout or "nothing" */ 102 mc = curl_multi_wait(multi, NULL, 0, 1000, &numfds); 103 } 104 105 if(mc != CURLM_OK) { 106 fprintf(stderr, "curl_multi failed, code %d.\n", mc); 107 break; 108 } 109 110 } while(still_running); 111 112 curl_multi_remove_handle(multi, easy); 113} 114~~~ 115 116# AVAILABILITY 117 118This function was added in libcurl 7.28.0. 119 120# RETURN VALUE 121 122CURLMcode type, general libcurl multi interface error code. See 123libcurl-errors(3) 124
