CURLOPT_CONNECT_TO(3)

1CURLOPT_CONNECT_TO(3)               libcurl              CURLOPT_CONNECT_TO(3)
2
3
4

NAME

6       CURLOPT_CONNECT_TO - connect to a specific host and port instead of the
7       URL's host and port
8

SYNOPSIS

10       #include <curl/curl.h>
11
12       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_TO,
13                                 struct curl_slist *connect_to);
14

DESCRIPTION

16       Pass a pointer to a linked list of strings with "connect  to"  informa‐
17       tion  to use for establishing network connections with this handle. The
18       linked list should be a fully valid list of struct  curl_slist  structs
19       properly  filled  in.  Use  curl_slist_append(3) to create the list and
20       curl_slist_free_all(3) to clean up an entire list.
21
22       Each single string should be written using  the  format  HOST:PORT:CON‐
23       NECT-TO-HOST:CONNECT-TO-PORT  where  HOST  is  the host of the request,
24       PORT is the port of the request, CONNECT-TO-HOST is the  host  name  to
25       connect to, and CONNECT-TO-PORT is the port to connect to.
26
27       The first string that matches the request's host and port is used.
28
29       Dotted  numerical  IP  addresses are supported for HOST and CONNECT-TO-
30       HOST.  A numerical IPv6 address must be written within [brackets].
31
32       Any of the four values may be empty. When the HOST or  PORT  is  empty,
33       the  host  or port will always match (the request's host or port is ig‐
34       nored).  When CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect
35       to"  feature  will  be disabled for the host or port, and the request's
36       host or port will be used to establish the network connection.
37
38       This option is suitable to direct the request  at  a  specific  server,
39       e.g. at a specific cluster node in a cluster of servers.
40
41       The  "connect  to" host and port are only used to establish the network
42       connection. They do NOT affect the host and  port  that  are  used  for
43       TLS/SSL  (e.g.  SNI,  certificate  verification) or for the application
44       protocols.
45
46       In contrast to  CURLOPT_RESOLVE(3),  the  option  CURLOPT_CONNECT_TO(3)
47       does  not  pre-populate  the DNS cache and therefore it does not affect
48       future transfers of other easy handles that have been added to the same
49       multi handle.
50
51       The  "connect  to"  host  and port are ignored if they are equal to the
52       host and the port in the request URL, because connecting  to  the  host
53       and the port in the request URL is the default behavior.
54
55       If  an  HTTP  proxy is used for a request having a special "connect to"
56       host or port, and the "connect to" host or port differs  from  the  re‐
57       quest's host and port, the HTTP proxy is automatically switched to tun‐
58       nel mode for this specific request. This is necessary because it is not
59       possible  to  connect to a specific host or port in normal (non-tunnel)
60       mode.
61
62       When this option is passed to  curl_easy_setopt(3),  libcurl  will  not
63       copy the entire list so you must keep it around until you no longer use
64       this handle for a transfer before you  call  curl_slist_free_all(3)  on
65       the list.
66
67

DEFAULT

69       NULL
70

PROTOCOLS

72       All
73

EXAMPLE

75       CURL *curl;
76       struct curl_slist *connect_to = NULL;
77       connect_to = curl_slist_append(NULL, "example.com::server1.example.com:");
78
79       curl = curl_easy_init();
80       if(curl) {
81         curl_easy_setopt(curl, CURLOPT_CONNECT_TO, connect_to);
82         curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
83
84         curl_easy_perform(curl);
85
86         /* always cleanup */
87         curl_easy_cleanup(curl);
88       }
89
90       curl_slist_free_all(connect_to);
91

AVAILABILITY

93       Added in 7.49.0
94

RETURN VALUE

96       Returns  CURLE_OK  if the option is supported, and CURLE_UNKNOWN_OPTION
97       if not.
98