CURLOPT_PROXY(3)

CURLOPT_PROXY(3)    curl_easy_setopt options     CURLOPT_PROXY(3)

NAME

     CURLOPT_PROXY - set proxy to use

SYNOPSIS

     #include <curl/curl.h>

     CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY,  char
     *proxy);

DESCRIPTION

     Set the proxy to use for the upcoming request. The parameter
     should  be  a char * to a zero terminated string holding the
     host name or dotted numerical IP address. A  numerical  IPv6
     address must be written within [brackets].

     To specify port number in this string, append :[port] to the
     end of the host name. The proxy's port number may optionally
     be specified with the separate option  CURLOPT_PROXYPORT(3).
     If  not  specified,  libcurl will default to using port 1080
     for proxies.

     The proxy string may be prefixed with [scheme]:// to specify
     which kind of proxy is used.

          http://
               HTTP Proxy. Default when no scheme or  proxy  type
               is specified.

          https://
               HTTPS Proxy. (Added in 7.52.0 for OpenSSL,  GnuTLS
               and NSS)

          socks4://
               SOCKS4 Proxy.

          socks4a://
               SOCKS4a Proxy. Proxy resolves URL hostname.

          socks5://
               SOCKS5 Proxy.

          socks5h://
               SOCKS5 Proxy. Proxy resolves URL hostname.

     Without a scheme prefix, CURLOPT_PROXYTYPE(3) can be used to
     specify which kind of proxy the string identifies.

     When you tell the library to use a HTTP proxy, libcurl  will
     transparently convert operations to HTTP even if you specify
     an FTP URL etc. This  may  have  an  impact  on  what  other
     features   of   the   library   you   can   use,   such   as

libcurl 7.58.0   Last change: September 24, 2017                1

CURLOPT_PROXY(3)    curl_easy_setopt options     CURLOPT_PROXY(3)

     CURLOPT_QUOTE(3) and similar FTP specifics that  don't  work
     unless  you tunnel through the HTTP proxy. Such tunneling is
     activated with CURLOPT_HTTPPROXYTUNNEL(3).

     Setting the proxy string to "" (an empty string) will expli-
     citly  disable  the  use  of  a  proxy,  even if there is an
     environment variable set for it.

     A  proxy  host  string  can  also  include  protocol  scheme
     (http://) and embedded user + password.

     The application does not have  to  keep  the  string  around
     after setting this option.

Environment variables

     libcurl  respects  the  proxy  environment  variables  named
     http_proxy,  ftp_proxy, sftp_proxy etc. If set, libcurl will
     use the specified proxy  for  that  URL  scheme.  So  for  a
     "FTP://" URL, the ftp_proxy is considered. all_proxy is used
     if no protocol specific proxy was set.

     If no_proxy (or NO_PROXY) is set, it can specify a  list  of
     host names to not use a proxy for (even if one of the previ-
     ous mention variables are set). That is the exact equivalent
     of setting the CURLOPT_NOPROXY(3) option.

     The CURLOPT_PROXY(3) and CURLOPT_NOPROXY(3) options override
     environment variables.

DEFAULT

     Default is NULL, meaning no proxy is used.

     When you set a host name to use, do not assume that  there's
     any  particular  single port number used widely for proxies.
     Specify it!

PROTOCOLS

     All except file://. Note that some protocols don't  do  very
     well over proxy.

EXAMPLE

     CURL *curl = curl_easy_init();
     if(curl) {
       curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/file.txt");
       curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
       curl_easy_perform(curl);
     }

AVAILABILITY

     Since  7.14.1  the  proxy  environment  variable  names  can
     include the protocol scheme.

libcurl 7.58.0   Last change: September 24, 2017                2

CURLOPT_PROXY(3)    curl_easy_setopt options     CURLOPT_PROXY(3)

     Since 7.21.7 the proxy string supports the  socks  protocols
     as "schemes".

     Since 7.50.2, unsupported schemes  in  proxy  strings  cause
     libcurl to return error.

RETURN VALUE

     Returns    CURLE_OK    if     proxies     are     supported,
     CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there
     was insufficient heap space.

SEE ALSO

     CURLOPT_PROXYPORT(3),            CURLOPT_HTTPPROXYTUNNEL(3),
     CURLOPT_PROXYTYPE(3)

libcurl 7.58.0   Last change: September 24, 2017                3