1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_CONNECTTIMEOUT
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_CONNECTTIMEOUT_MS (3)
9  - CURLOPT_LOW_SPEED_LIMIT (3)
10  - CURLOPT_MAX_RECV_SPEED_LARGE (3)
11  - CURLOPT_TIMEOUT (3)
12---
13
14# NAME
15
16CURLOPT_CONNECTTIMEOUT - timeout for the connect phase
17
18# SYNOPSIS
19
20~~~c
21#include <curl/curl.h>
22
23CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT, long timeout);
24~~~
25
26# DESCRIPTION
27
28Pass a long. It should contain the maximum time in seconds that you allow the
29connection phase to the server to take. This timeout only limits the
30connection phase, it has no impact once it has connected. Set to zero to
31switch to the default built-in connection timeout - 300 seconds. See also the
32CURLOPT_TIMEOUT(3) option.
33
34CURLOPT_CONNECTTIMEOUT_MS(3) is the same function but set in milliseconds.
35
36If both CURLOPT_CONNECTTIMEOUT(3) and CURLOPT_CONNECTTIMEOUT_MS(3)
37are set, the value set last is used.
38
39The "connection phase" is considered complete when the requested TCP, TLS or
40QUIC handshakes are done.
41
42The connection timeout set with CURLOPT_CONNECTTIMEOUT(3) is included in
43the general all-covering CURLOPT_TIMEOUT(3).
44
45With CURLOPT_CONNECTTIMEOUT(3) set to 3 and CURLOPT_TIMEOUT(3) set
46to 5, the operation can never last longer than 5 seconds, and the connection
47phase cannot last longer than 3 seconds.
48
49With CURLOPT_CONNECTTIMEOUT(3) set to 4 and CURLOPT_TIMEOUT(3) set
50to 2, the operation can never last longer than 2 seconds. Including the
51connection phase.
52
53This option may cause libcurl to use the SIGALRM signal to timeout system
54calls on builds not using asynch DNS. In unix-like systems, this might cause
55signals to be used unless CURLOPT_NOSIGNAL(3) is set.
56
57# DEFAULT
58
59300
60
61# PROTOCOLS
62
63All
64
65# EXAMPLE
66
67~~~c
68int main(void)
69{
70  CURL *curl = curl_easy_init();
71  if(curl) {
72    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
73
74    /* complete connection within 10 seconds */
75    curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 10L);
76
77    curl_easy_perform(curl);
78  }
79}
80~~~
81
82# AVAILABILITY
83
84Always
85
86# RETURN VALUE
87
88Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative
89value or a value that when converted to milliseconds is too large.
90