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_CONNECTTIMEOUT_MS (3)
9  - CURLOPT_LOW_SPEED_LIMIT (3)
10  - CURLOPT_MAX_RECV_SPEED_LARGE (3)
11  - CURLOPT_TIMEOUT (3)
12Protocol:
13  - All
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 should contain the maximum time in seconds that you allow the
31connection phase to the server to take. This timeout only limits the
32connection phase, it has no impact once it has connected. Set to zero to
33switch to the default built-in connection timeout - 300 seconds. See also the
34CURLOPT_TIMEOUT(3) option.
35
36CURLOPT_CONNECTTIMEOUT_MS(3) is the same function but set in milliseconds.
37
38If both CURLOPT_CONNECTTIMEOUT(3) and CURLOPT_CONNECTTIMEOUT_MS(3)
39are set, the value set last is used.
40
41The "connection phase" is considered complete when the requested TCP, TLS or
42QUIC handshakes are done.
43
44The connection timeout set with CURLOPT_CONNECTTIMEOUT(3) is included in
45the general all-covering CURLOPT_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# EXAMPLE
64
65~~~c
66int main(void)
67{
68  CURL *curl = curl_easy_init();
69  if(curl) {
70    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
71
72    /* complete connection within 10 seconds */
73    curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 10L);
74
75    curl_easy_perform(curl);
76  }
77}
78~~~
79
80# AVAILABILITY
81
82Always
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