1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_multi_timeout 5Section: 3 6Source: libcurl 7See-also: 8 - curl_multi_fdset (3) 9 - curl_multi_info_read (3) 10 - curl_multi_setopt (3) 11 - curl_multi_socket (3) 12Protocol: 13 - All 14Added-in: 7.15.4 15--- 16 17# NAME 18 19curl_multi_timeout - how long to wait for action before proceeding 20 21# SYNOPSIS 22 23~~~c 24#include <curl/curl.h> 25 26CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout); 27~~~ 28 29# DESCRIPTION 30 31An application using the libcurl multi interface should call 32curl_multi_timeout(3) to figure out how long it should wait for socket 33actions - at most - before proceeding. 34 35Proceeding means either doing the socket-style timeout action: call the 36curl_multi_socket_action(3) function with the **sockfd** argument set 37to CURL_SOCKET_TIMEOUT, or call curl_multi_perform(3) if you are using 38the simpler and older multi interface approach. 39 40The timeout value returned in the long **timeout** points to, is in number 41of milliseconds at this moment. If 0, it means you should proceed immediately 42without waiting for anything. If it returns -1, there is no timeout at all set. 43 44An application that uses the *multi_socket* API should not use this function. 45It should instead use the CURLMOPT_TIMERFUNCTION(3) option for proper and 46desired behavior. 47 48Note: if libcurl returns a -1 timeout here, it just means that libcurl 49currently has no stored timeout value. You must not wait too long (more than a 50few seconds perhaps) before you call curl_multi_perform(3) again. 51 52# %PROTOCOLS% 53 54# EXAMPLE 55 56~~~c 57int main(void) 58{ 59 struct timeval timeout; 60 long timeo; 61 fd_set fdread; 62 fd_set fdwrite; 63 fd_set fdexcep; 64 int maxfd; 65 CURLM *multi = curl_multi_init(); 66 67 curl_multi_timeout(multi, &timeo); 68 if(timeo < 0) 69 /* no set timeout, use a default */ 70 timeo = 980; 71 72 timeout.tv_sec = timeo / 1000; 73 timeout.tv_usec = (timeo % 1000) * 1000; 74 75 /* wait for activities no longer than the set timeout */ 76 select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout); 77} 78~~~ 79 80# TYPICAL USAGE 81 82Call curl_multi_timeout(3), then wait for action on the sockets. Figure 83out which sockets to wait for by calling curl_multi_fdset(3). 84 85When there is activity or timeout, call curl_multi_perform(3) and then 86loop - until all transfers are complete. 87 88# %AVAILABILITY% 89 90# RETURN VALUE 91 92The standard CURLMcode for multi interface error codes. 93
