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