1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_CONNECTTIMEOUT_MS
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_LOW_SPEED_LIMIT (3)
9  - CURLOPT_MAX_RECV_SPEED_LARGE (3)
10  - CURLOPT_TIMEOUT_MS (3)
11Protocol:
12  - All
13---
14
15# NAME
16
17CURLOPT_CONNECTTIMEOUT_MS - timeout for the connect phase
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT_MS,
25                          long timeout);
26~~~
27
28# DESCRIPTION
29
30Pass a long. It sets the maximum time in milliseconds that you allow the
31connection phase to take. This timeout only limits the connection phase, it
32has no impact once libcurl has connected. The connection phase includes the
33name resolve (DNS) and all protocol handshakes and negotiations until there is
34an established 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_MS(3) option.
38
39CURLOPT_CONNECTTIMEOUT(3) is the same function but set in seconds.
40
41If both CURLOPT_CONNECTTIMEOUT(3) and CURLOPT_CONNECTTIMEOUT_MS(3) are set,
42the value set last is used.
43
44The connection timeout is included in the general all-covering
45CURLOPT_TIMEOUT_MS(3):
46
47With CURLOPT_CONNECTTIMEOUT_MS(3) set to 3000 and CURLOPT_TIMEOUT_MS(3) set to
485000, the operation can never last longer than 5000 milliseconds, and the
49connection phase cannot last longer than 3000 milliseconds.
50
51With CURLOPT_CONNECTTIMEOUT_MS(3) set to 4000 and CURLOPT_TIMEOUT_MS(3) set to
522000, the operation can never last longer than 2000 milliseconds. Including
53the connection 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
61300000
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 10000 milliseconds */
73    curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, 10000L);
74
75    curl_easy_perform(curl);
76  }
77}
78~~~
79
80# AVAILABILITY
81
82Always
83
84# RETURN VALUE
85
86Returns CURLE_OK
87