curl_multi_timeout.md (2528B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: curl_multi_timeout 5 Section: 3 6 Source: libcurl 7 See-also: 8 - curl_multi_fdset (3) 9 - curl_multi_info_read (3) 10 - curl_multi_setopt (3) 11 - curl_multi_socket (3) 12 Protocol: 13 - All 14 Added-in: 7.15.4 15 --- 16 17 # NAME 18 19 curl_multi_timeout - how long to wait for action before proceeding 20 21 # SYNOPSIS 22 23 ~~~c 24 #include <curl/curl.h> 25 26 CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout); 27 ~~~ 28 29 # DESCRIPTION 30 31 An application using the libcurl multi interface should call 32 curl_multi_timeout(3) to figure out how long it should wait for socket 33 actions - at most - before proceeding. 34 35 Proceeding means either doing the socket-style timeout action: call the 36 curl_multi_socket_action(3) function with the **sockfd** argument set 37 to CURL_SOCKET_TIMEOUT, or call curl_multi_perform(3) if you are using 38 the simpler and older multi interface approach. 39 40 The timeout value returned in the long **timeout** points to, is in number 41 of milliseconds at this moment. If 0, it means you should proceed immediately 42 without waiting for anything. If it returns -1, there is no timeout at all set. 43 44 An application that uses the *multi_socket* API should not use this function. 45 It should instead use the CURLMOPT_TIMERFUNCTION(3) option for proper and 46 desired behavior. 47 48 Note: if libcurl returns a -1 timeout here, it just means that libcurl 49 currently has no stored timeout value. You must not wait too long (more than a 50 few seconds perhaps) before you call curl_multi_perform(3) again. 51 52 # %PROTOCOLS% 53 54 # EXAMPLE 55 56 ~~~c 57 int 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 = 2; 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 82 Call curl_multi_timeout(3), then wait for action on the sockets. Figure 83 out which sockets to wait for by calling curl_multi_fdset(3). 84 85 When there is activity or timeout, call curl_multi_perform(3) and then 86 loop - until all transfers are complete. 87 88 # %AVAILABILITY% 89 90 # RETURN VALUE 91 92 This function returns a CURLMcode indicating success or error. 93 94 CURLM_OK (0) means everything was OK, non-zero means an error occurred, see 95 libcurl-errors(3).