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