Ubuntu Manpage: CURLOPT_CONNECT_TO - connect to another host and port instead

name
synopsis
description
default
protocols
example
availability
return value
see also

Provided by: libcurl4-doc_8.9.1-2ubuntu2.2_all

NAME

       CURLOPT_CONNECT_TO - connect to another host and port instead

SYNOPSIS

       #include <curl/curl.h>

       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_TO,
                                 struct curl_slist *connect_to);

DESCRIPTION

Pass a pointer to a linked list of strings with "connect to" information to use for establishing network
connections with this handle. The linked list should be a fully valid list of struct curl_slist structs
properly filled in. Use curl_slist_append(3) to create the list and curl_slist_free_all(3) to clean up an
entire list.

Each single string should be written using the format HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT where
HOST is the host of the request, PORT is the port of the request, CONNECT-TO-HOST is the hostname to
connect to, and CONNECT-TO-PORT is the port to connect to.

The first string that matches the request's host and port is used.

Dotted numerical IP addresses are supported for HOST and CONNECT-TO-HOST. A numerical IPv6 address must
be written within [brackets].

Any of the four values may be empty. When the HOST or PORT is empty, the host or port always match (the
request's host or port is ignored). When CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to"
feature is disabled for the host or port, and the request's host or port are used to establish the
network connection.

This option is suitable to direct the request at a specific server, e.g. at a specific cluster node in a
cluster of servers.

The "connect to" host and port are only used to establish the network connection. They do NOT affect the
host and port that are used for TLS/SSL (e.g. SNI, certificate verification) or for the application
protocols.

In contrast to CURLOPT_RESOLVE(3), the option CURLOPT_CONNECT_TO(3) does not pre-populate the DNS cache
and therefore it does not affect future transfers of other easy handles that have been added to the same
multi handle.

The "connect to" host and port are ignored if they are equal to the host and the port in the request URL,
because connecting to the host and the port in the request URL is the default behavior.

If an HTTP proxy is used for a request having a special "connect to" host or port, and the "connect to"
host or port differs from the request's host and port, the HTTP proxy is automatically switched to tunnel
mode for this specific request. This is necessary because it is not possible to connect to a specific
host or port in normal (non-tunnel) mode.

When this option is passed to curl_easy_setopt(3), libcurl does not copy the list so you must keep it
around until you no longer use this handle for a transfer before you call curl_slist_free_all(3) on the
list.

DEFAULT

       NULL

PROTOCOLS

       This functionality affects all supported protocols

EXAMPLE

       int main(void)
       {
         CURL *curl;
         struct curl_slist *connect_to = NULL;
         connect_to = curl_slist_append(NULL, "example.com::server1.example.com:");

         curl = curl_easy_init();
         if(curl) {
           curl_easy_setopt(curl, CURLOPT_CONNECT_TO, connect_to);
           curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");

           curl_easy_perform(curl);

           /* always cleanup */
           curl_easy_cleanup(curl);
         }

         curl_slist_free_all(connect_to);
       }

AVAILABILITY

       Added in curl 7.49.0

RETURN VALUE

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