Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CURLOPT_CONNECT_TO(3)	   curl_easy_setopt options	 CURLOPT_CONNECT_TO(3)

NAME
       CURLOPT_CONNECT_TO - Connect to a specific host and port	instead	of the
       URL's host and port

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"  informa-
       tion  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:CON-
       NECT-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	host  name  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 will always match (the request's host	or port	is ig-
       nored).	When CONNECT-TO-HOST or	CONNECT-TO-PORT	is empty, the "connect
       to"  feature  will  be disabled for the host or port, and the request's
       host or port will be 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  re-
       quests'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-tun-
       nel) mode.

       When this option	is passed to  curl_easy_setopt(3),  libcurl  will  not
       copy the	entire 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
       All

EXAMPLE
       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, "http://example.com");

	 curl_easy_perform(curl);

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

       curl_slist_free_all(connect_to);

AVAILABILITY
       Added in	7.49.0

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

SEE ALSO
       CURLOPT_URL(3),	CURLOPT_RESOLVE(3),  CURLOPT_FOLLOWLOCATION(3),	  CUR-
       LOPT_HTTPPROXYTUNNEL(3),

libcurl	5.5.5			 May 20, 2016		 CURLOPT_CONNECT_TO(3)

NAME | SYNOPSIS | DESCRIPTION | DEFAULT | PROTOCOLS | EXAMPLE | AVAILABILITY | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CURLOPT_CONNECT_TO&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help