CURLOPT_CONNECT_TO(3)

1CURLOPT_CONNECT_TO(3)      curl_easy_setopt options      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
34       ignored).  When CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the  "con‐
35       nect  to"  feature  will  be  disabled  for  the  host or port, and the
36       request's host or port will be used to establish  the  network  connec‐
37       tion.
38
39       This  option  is  suitable  to direct the request at a specific server,
40       e.g. at a specific cluster node in a cluster of servers.
41
42       The "connect to" host and port are only used to establish  the  network
43       connection.  They  do  NOT  affect  the host and port that are used for
44       TLS/SSL (e.g. SNI, certificate verification)  or  for  the  application
45       protocols.
46
47       In  contrast  to  CURLOPT_RESOLVE(3),  the option CURLOPT_CONNECT_TO(3)
48       does not pre-populate the DNS cache and therefore it  does  not  affect
49       future transfers of other easy handles that have been added to the same
50       multi handle.
51
52       The "connect to" host and port are ignored if they  are  equal  to  the
53       host  and  the  port in the request URL, because connecting to the host
54       and the port in the request URL is the default behavior.
55
56       If an HTTP proxy is used for a request having a  special  "connect  to"
57       host  or  port,  and  the  "connect  to"  host or port differs from the
58       request's host and port, the HTTP proxy is  automatically  switched  to
59       tunnel  mode for this specific request. This is necessary because it is
60       not possible to connect to a specific host or port in normal  (non-tun‐
61       nel) mode.
62
63       When  this  option  is  passed to curl_easy_setopt(3), libcurl will not
64       copy the entire list so you must keep it around until you no longer use
65       this  handle  for  a transfer before you call curl_slist_free_all(3) on
66       the list.
67
68

DEFAULT

70       NULL
71

PROTOCOLS

73       All
74

EXAMPLE

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

AVAILABILITY

94       Added in 7.49.0
95

RETURN VALUE

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