Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_PROXY.3, revision 1.1
1.1 ! misho 1: .\" **************************************************************************
! 2: .\" * _ _ ____ _
! 3: .\" * Project ___| | | | _ \| |
! 4: .\" * / __| | | | |_) | |
! 5: .\" * | (__| |_| | _ <| |___
! 6: .\" * \___|\___/|_| \_\_____|
! 7: .\" *
! 8: .\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
! 9: .\" *
! 10: .\" * This software is licensed as described in the file COPYING, which
! 11: .\" * you should have received as part of this distribution. The terms
! 12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
! 13: .\" *
! 14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
! 15: .\" * copies of the Software, and permit persons to whom the Software is
! 16: .\" * furnished to do so, under the terms of the COPYING file.
! 17: .\" *
! 18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
! 19: .\" * KIND, either express or implied.
! 20: .\" *
! 21: .\" **************************************************************************
! 22: .\"
! 23: .TH CURLOPT_PROXY 3 "August 24, 2018" "libcurl 7.70.0" "curl_easy_setopt options"
! 24:
! 25: .SH NAME
! 26: CURLOPT_PROXY \- set proxy to use
! 27: .SH SYNOPSIS
! 28: #include <curl/curl.h>
! 29:
! 30: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy);
! 31: .SH DESCRIPTION
! 32: Set the \fIproxy\fP to use for the upcoming request. The parameter should be a
! 33: char * to a zero terminated string holding the host name or dotted numerical
! 34: IP address. A numerical IPv6 address must be written within [brackets].
! 35:
! 36: To specify port number in this string, append :[port] to the end of the host
! 37: name. The proxy's port number may optionally be specified with the separate
! 38: option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl will default to
! 39: using port 1080 for proxies.
! 40:
! 41: The proxy string may be prefixed with [scheme]:// to specify which kind of
! 42: proxy is used.
! 43:
! 44: .RS
! 45: .IP http://
! 46: HTTP Proxy. Default when no scheme or proxy type is specified.
! 47: .IP https://
! 48: HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS)
! 49: .IP socks4://
! 50: SOCKS4 Proxy.
! 51: .IP socks4a://
! 52: SOCKS4a Proxy. Proxy resolves URL hostname.
! 53: .IP socks5://
! 54: SOCKS5 Proxy.
! 55: .IP socks5h://
! 56: SOCKS5 Proxy. Proxy resolves URL hostname.
! 57: .RE
! 58:
! 59: Without a scheme prefix, \fICURLOPT_PROXYTYPE(3)\fP can be used to specify
! 60: which kind of proxy the string identifies.
! 61:
! 62: When you tell the library to use an HTTP proxy, libcurl will transparently
! 63: convert operations to HTTP even if you specify an FTP URL etc. This may have
! 64: an impact on what other features of the library you can use, such as
! 65: \fICURLOPT_QUOTE(3)\fP and similar FTP specifics that don't work unless you
! 66: tunnel through the HTTP proxy. Such tunneling is activated with
! 67: \fICURLOPT_HTTPPROXYTUNNEL(3)\fP.
! 68:
! 69: Setting the proxy string to "" (an empty string) will explicitly disable the
! 70: use of a proxy, even if there is an environment variable set for it.
! 71:
! 72: A proxy host string can also include protocol scheme (http://) and embedded
! 73: user + password.
! 74:
! 75: The application does not have to keep the string around after setting this
! 76: option.
! 77: .SH "Environment variables"
! 78: libcurl respects the proxy environment variables named \fBhttp_proxy\fP,
! 79: \fBftp_proxy\fP, \fBsftp_proxy\fP etc. If set, libcurl will use the specified
! 80: proxy for that URL scheme. So for a "FTP://" URL, the \fBftp_proxy\fP is
! 81: considered. \fBall_proxy\fP is used if no protocol specific proxy was set.
! 82:
! 83: If \fBno_proxy\fP (or \fBNO_PROXY\fP) is set, it is the exact equivalent of
! 84: setting the \fICURLOPT_NOPROXY(3)\fP option.
! 85:
! 86: The \fICURLOPT_PROXY(3)\fP and \fICURLOPT_NOPROXY(3)\fP options override
! 87: environment variables.
! 88: .SH DEFAULT
! 89: Default is NULL, meaning no proxy is used.
! 90:
! 91: When you set a host name to use, do not assume that there's any particular
! 92: single port number used widely for proxies. Specify it!
! 93: .SH PROTOCOLS
! 94: All except file://. Note that some protocols don't do very well over proxy.
! 95: .SH EXAMPLE
! 96: .nf
! 97: CURL *curl = curl_easy_init();
! 98: if(curl) {
! 99: curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/file.txt");
! 100: curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
! 101: curl_easy_perform(curl);
! 102: }
! 103: .fi
! 104: .SH AVAILABILITY
! 105: Since 7.14.1 the proxy environment variable names can include the protocol
! 106: scheme.
! 107:
! 108: Since 7.21.7 the proxy string supports the socks protocols as "schemes".
! 109:
! 110: Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return
! 111: error.
! 112: .SH RETURN VALUE
! 113: Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or
! 114: CURLE_OUT_OF_MEMORY if there was insufficient heap space.
! 115: .SH "SEE ALSO"
! 116: .BR CURLOPT_PROXYPORT "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), "
! 117: .BR CURLOPT_PROXYTYPE "(3)"
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>