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