1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_CONNECTTIMEOUT
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_LOW_SPEED_LIMIT (3)
9  - CURLOPT_MAX_RECV_SPEED_LARGE (3)
10  - CURLOPT_TIMEOUT (3)
11Protocol:
12  - All
13Added-in: 7.7
14---
15
16# NAME
17
18CURLOPT_CONNECTTIMEOUT - timeout for the connect phase
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT, long timeout);
26~~~
27
28# DESCRIPTION
29
30Pass a long. It sets the maximum time in seconds that you allow the connection
31phase to take. This timeout only limits the connection phase, it has no impact
32once libcurl has connected. The connection phase includes the name resolve
33(DNS) and all protocol handshakes and negotiations until there is an
34established connection with the remote side.
35
36Set this option to zero to switch to the default built-in connection timeout -
37300 seconds. See also the CURLOPT_TIMEOUT(3) option.
38
39CURLOPT_CONNECTTIMEOUT_MS(3) is the same function but set in milliseconds.
40
41If both CURLOPT_CONNECTTIMEOUT(3) and CURLOPT_CONNECTTIMEOUT_MS(3)
42are set, the value set last is used.
43
44The connection timeout is included in the general all-covering
45CURLOPT_TIMEOUT(3):
46
47With CURLOPT_CONNECTTIMEOUT(3) set to 3 and CURLOPT_TIMEOUT(3) set
48to 5, the operation can never last longer than 5 seconds, and the connection
49phase cannot last longer than 3 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. Including the
53connection phase.
54
55This option may cause libcurl to use the SIGALRM signal to timeout system
56calls on builds not using asynch DNS. In Unix-like systems, this might cause
57signals to be used unless CURLOPT_NOSIGNAL(3) is set.
58
59# DEFAULT
60
61300
62
63# %PROTOCOLS%
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
84# RETURN VALUE
85
86Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative
87value or a value that when converted to milliseconds is too large.
88