1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_CONNECT_ONLY
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_HTTPPROXYTUNNEL (3)
9  - CURLOPT_VERBOSE (3)
10  - curl_easy_recv (3)
11  - curl_easy_send (3)
12Protocol:
13  - All
14---
15
16# NAME
17
18CURLOPT_CONNECT_ONLY - stop when connected to target server
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_ONLY, long only);
26~~~
27
28# DESCRIPTION
29
30Pass a long. If the parameter equals 1, it tells the library to perform all
31the required proxy authentication and connection setup, but no data transfer,
32and then return.
33
34The option can be used to simply test a connection to a server, but is more
35useful when used with the CURLINFO_ACTIVESOCKET(3) option to
36curl_easy_getinfo(3) as the library can set up the connection and then
37the application can obtain the most recently used socket for special data
38transfers.
39
40Since 7.86.0, this option can be set to '2' and if HTTP or WebSocket are used,
41libcurl performs the request and reads all response headers before handing
42over control to the application.
43
44Transfers marked connect only do not reuse any existing connections and
45connections marked connect only are not allowed to get reused.
46
47If the connect only transfer is done using the multi interface, the particular
48easy handle must remain added to the multi handle for as long as the
49application wants to use it. Once it has been removed with
50curl_multi_remove_handle(3), curl_easy_send(3) and
51curl_easy_recv(3) do not function.
52
53# DEFAULT
54
550
56
57# EXAMPLE
58
59~~~c
60int main(void)
61{
62  CURL *curl = curl_easy_init();
63  if(curl) {
64    CURLcode ret;
65    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
66    curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L);
67    ret = curl_easy_perform(curl);
68    if(ret == CURLE_OK) {
69      /* only connected! */
70    }
71  }
72}
73~~~
74
75# AVAILABILITY
76
77Added in 7.15.2. WS and WSS support added in 7.86.0.
78
79# RETURN VALUE
80
81Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
82