1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_TIMEOUT
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_CONNECTTIMEOUT (3)
9  - CURLOPT_LOW_SPEED_LIMIT (3)
10  - CURLOPT_TCP_KEEPALIVE (3)
11  - CURLOPT_TIMEOUT_MS (3)
12---
13
14# NAME
15
16CURLOPT_TIMEOUT - maximum time the transfer is allowed to complete
17
18# SYNOPSIS
19
20~~~c
21#include <curl/curl.h>
22
23CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT, long timeout);
24~~~
25
26# DESCRIPTION
27
28Pass a long as parameter containing *timeout* - the maximum time in
29seconds that you allow the entire transfer operation to take. The whole thing,
30from start to end. Normally, name lookups can take a considerable time and
31limiting operations risk aborting perfectly normal operations.
32
33CURLOPT_TIMEOUT_MS(3) is the same function but set in milliseconds.
34
35If both CURLOPT_TIMEOUT(3) and CURLOPT_TIMEOUT_MS(3) are set, the
36value set last is used.
37
38Since this option puts a hard limit on how long time a request is allowed to
39take, it has limited use in dynamic use cases with varying transfer
40times. That is especially apparent when using the multi interface, which may
41queue the transfer, and that time is included. You are advised to explore
42CURLOPT_LOW_SPEED_LIMIT(3), CURLOPT_LOW_SPEED_TIME(3) or using
43CURLOPT_PROGRESSFUNCTION(3) to implement your own timeout logic.
44
45The connection timeout set with CURLOPT_CONNECTTIMEOUT(3) is included in
46this general all-covering timeout.
47
48With CURLOPT_CONNECTTIMEOUT(3) set to 3 and CURLOPT_TIMEOUT(3) set
49to 5, the operation can never last longer than 5 seconds.
50
51With CURLOPT_CONNECTTIMEOUT(3) set to 4 and CURLOPT_TIMEOUT(3) set
52to 2, the operation can never last longer than 2 seconds.
53
54This option may cause libcurl to use the SIGALRM signal to timeout system
55calls on builds not using asynch DNS. In unix-like systems, this might cause
56signals to be used unless CURLOPT_NOSIGNAL(3) is set.
57
58# DEFAULT
59
60Default timeout is 0 (zero) which means it never times out during transfer.
61
62# PROTOCOLS
63
64All
65
66# EXAMPLE
67
68~~~c
69int main(void)
70{
71  CURL *curl = curl_easy_init();
72  if(curl) {
73    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
74
75    /* complete within 20 seconds */
76    curl_easy_setopt(curl, CURLOPT_TIMEOUT, 20L);
77
78    curl_easy_perform(curl);
79  }
80}
81~~~
82
83# AVAILABILITY
84
85Always
86
87# RETURN VALUE
88
89Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative
90value or a value that when converted to milliseconds is too large.
91