preferred method of verifying the peer's certificate chain.
(Schannel only) This option is supported for Schannel in Windows 7 or later
-with libcurl 7.60 or later. This option is supported for backward
-compatibility with other SSL engines; instead it is recommended to use
-Windows' store of root certificates (the default for Schannel).
+(added in 7.60.0). This option is supported for backward compatibility with
+other SSL engines; instead it is recommended to use Windows' store of root
+certificates (the default for Schannel).
---
Maximum time in seconds that you allow curl's connection to take. This only
limits the connection phase, so if curl connects within the given period it
-will continue - if not it will exit. Since version 7.32.0, this option
-accepts decimal values.
+will continue - if not it will exit.
-The "connection phase" is considered complete when the DNS lookup and
-requested TCP, TLS or QUIC handshakes are done.
+This option accepts decimal values (added in 7.32.0). The decimal value needs
+to be provided using a dot (.) as decimal separator - not the local version
+even if it might be using another separator.
-The decimal value needs to provided using a dot (.) as decimal separator - not
-the local version even if it might be using another separator.
+The connection phase is considered complete when the DNS lookup and requested
+TCP, TLS or QUIC handshakes are done.
settings are not inherited and can be controlled separately via
--doh-insecure and --doh-cert-status.
-This option is unset if an empty string "" is used as the URL. (Added in
-7.85.0)
+This option is unset if an empty string "" is used as the URL.
+(Added in 7.85.0)
Added: 7.7
Multi: single
---
-Deprecated option. This option is ignored by curl since 7.84.0. Prior to that
-it only had an effect on curl if built to use old versions of OpenSSL.
+Deprecated option (added in 7.84.0). Prior to that it only had an effect on
+curl if built to use old versions of OpenSSL.
Specify the path name to the Entropy Gathering Daemon socket. The socket is
used to seed the random engine for SSL connections.
curl's PASV command when curl connects the data connection. Instead curl will
reuse the same IP address it already uses for the control connection.
-Since curl 7.74.0 this option is enabled by default.
+This option is enabled by default (added in 7.74.0).
This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
this to non-HTTP servers and still get a response since curl will simply
transparently downgrade - if allowed.
-Since curl 7.66.0, HTTP/0.9 is disabled by default.
+HTTP/0.9 is disabled by default (added in 7.66.0)
servers running Apache 1.x, which will report incorrect Content-Length for
files larger than 2 gigabytes.
-For FTP (since 7.46.0), skip the RETR command to figure out the size before
-downloading a file.
+For FTP, this makes curl skip the SIZE command to figure out the size before
+downloading a file (added in 7.46.0).
This option does not work for HTTP if libcurl was built to use hyper.
Added: 4.0
Multi: single
---
-Maximum time in seconds that you allow each transfer to take. This is
-useful for preventing your batch jobs from hanging for hours due to slow
-networks or links going down. Since 7.32.0, this option accepts decimal
-values, but the actual timeout will decrease in accuracy as the specified
-timeout increases in decimal precision.
+Maximum time in seconds that you allow each transfer to take. This is useful
+for preventing your batch jobs from hanging for hours due to slow networks or
+links going down. This option accepts decimal values (added in 7.32.0).
If you enable retrying the transfer (--retry) then the maximum time counter is
reset each time the transfer is retried. You can use --retry-max-time to limit
Multi: single
---
This option was previously used to specify a Metalink resource. Metalink
-support has been disabled in curl since 7.78.0 for security reasons.
+support is disabled in curl for security reasons (added in 7.78.0).
Example: --no-npn $URL
Multi: boolean
---
-In curl 7.86.0 and later, curl never uses NPN.
+curl never uses NPN, this option has no effect (added in 7.86.0).
Disable the NPN TLS extension. NPN is enabled by default if libcurl was built
with an SSL library that supports NPN. NPN is used by a libcurl that supports
example, local.com would match local.com, local.com:80, and www.local.com, but
not www.notlocal.com.
-Since 7.53.0, This option overrides the environment variables that disable the
-proxy ('no_proxy' and 'NO_PROXY'). If there is an environment variable
-disabling a proxy, you can set the no proxy list to "" to override it.
+This option overrides the environment variables that disable the proxy
+('no_proxy' and 'NO_PROXY') (added in 7.53.0). If there is an environment
+variable disabling a proxy, you can set the no proxy list to "" to override
+it.
-Since 7.86.0, IP addresses specified to this option can be provided using CIDR
-notation: an appended slash and number specifies the number of "network bits"
-out of the address to use in the comparison. For example "192.168.0.0/16"
-would match all addresses starting with "192.168".
+IP addresses specified to this option can be provided using CIDR notation
+(added in 7.86.0): an appended slash and number specifies the number of
+"network bits" out of the address to use in the comparison. For example
+"192.168.0.0/16" would match all addresses starting with "192.168".
The list of host names can also be include numerical IP addresses, and IPv6
versions should then be given without enclosing brackets.
-Since 7.86.0, IP addresses can be specified using CIDR notation: an appended
-slash and number specifies the number of "network bits" out of the address to
-use in the comparison. For example "192.168.0.0/16" would match all addresses
-starting with "192.168".
+IP addresses can be specified using CIDR notation: an appended slash and
+number specifies the number of "network bits" out of the address to use in the
+comparison (added in 7.86.0). For example "192.168.0.0/16" would match all
+addresses starting with "192.168".
.IP "APPDATA <dir>"
On Windows, this variable is used when trying to find the home directory. If
the primary home variable are all unset.
Switch off globbing with --globoff.
.SH VARIABLES
-Starting in curl 8.3.0, curl supports command line variables. Set variables
-with --variable name=content or --variable name@file (where "file" can be
-stdin if set to a single dash (-)).
+curl supports command line variables (added in 8.3.0). Set variables with
+--variable name=content or --variable name@file (where "file" can be stdin if
+set to a single dash (-)).
Variable contents can expanded in option parameters using "{{name}}" (without
the quotes) if the option name is prefixed with "--expand-". This gets the
PEM/DER support:
-7.39.0: OpenSSL and GnuTLS
-
-7.43.0: wolfSSL
-
-7.47.0: mbedTLS
+OpenSSL and GnuTLS (added in 7.39.0), wolfSSL (added in 7.43.0), mbedTLS (added in 7.47.0)
sha256 support:
-7.44.0: OpenSSL, GnuTLS and wolfSSL
-
-7.47.0: mbedTLS
+OpenSSL, GnuTLS and wolfSSL (added in 7.44.0), mbedTLS (added in 7.47.0)
Other SSL backends not supported.
curl --proto-redir -all,http,https http://example.com
-By default curl will only allow HTTP, HTTPS, FTP and FTPS on redirect (since
-7.65.2). Specifying *all* or *+all* enables all protocols on redirects, which
-is not good for security.
+By default curl will only allow HTTP, HTTPS, FTP and FTPS on redirect
+(added in 7.65.2). Specifying *all* or *+all* enables all protocols on
+redirects, which is not good for security.
Headers specified with this option will not be included in requests that curl
knows will not be sent to a proxy.
-Starting in 7.55.0, this option can take an argument in @filename style, which
-then adds a header for each line in the input file. Using @- will make curl
+This option can take an argument in @filename style, which then adds a header
+for each line in the input file (added in 7.55.0). Using @- will make curl
read the header file from stdin.
This option can be used multiple times to add/replace/remove multiple headers.
Unix domain sockets are supported for socks proxy. Set localhost for the host
part. e.g. socks5h://localhost/path/to/socket.sock
-HTTPS proxy support via https:// protocol prefix was added in 7.52.0 for
-OpenSSL and GnuTLS. Since 7.87.0, it also works for BearSSL, mbedTLS,
-rustls, Schannel, Secure Transport and wolfSSL.
+HTTPS proxy support works set with the https:// protocol prefix for OpenSSL
+and GnuTLS (added in 7.52.0). It also works for BearSSL, mbedTLS, rustls,
+Schannel, Secure Transport and wolfSSL (added in 7.87.0).
-Unrecognized and unsupported proxy protocols cause an error since 7.52.0.
-Prior versions may ignore the protocol and use http:// instead.
+Unrecognized and unsupported proxy protocols cause an error (added in 7.52.0).
+Ancient curl versions ignored unknown schemes and used http:// instead.
If the port number is not specified in the proxy string, it is assumed to be
1080.
Public key file name. Allows you to provide your public key in this separate
file.
-(As of 7.39.0, curl attempts to automatically extract the public key from the
-private key file, so passing this option is generally not required. Note that
-this public key extraction requires libcurl to be linked against a copy of
-libssh2 1.2.8 or higher that is itself linked against OpenSSL.)
+curl attempts to automatically extract the public key from the private key
+file, so passing this option is generally not required. Note that this public
+key extraction requires libcurl to be linked against a copy of libssh2 1.2.8
+or higher that is itself linked against OpenSSL. (Added in 7.39.0.)
See-also: egd-file
Multi: single
---
-Deprecated option. This option is ignored by curl since 7.84.0. Prior to that
-it only had an effect on curl if built to use old versions of OpenSSL.
+Deprecated option. This option is ignored (added in 7.84.0). Prior to that it
+only had an effect on curl if built to use old versions of OpenSSL.
Specify the path name to file containing what will be considered as random
data. The data may be used to seed the random engine for SSL connections.
Multi: single
---
If a transient error is returned when curl tries to perform a transfer, it
-will retry this number of times before giving up. Setting the number to 0
+retries this number of times before giving up. Setting the number to 0
makes curl do no retries (which is the default). Transient error means either:
a timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504
response code.
-When curl is about to retry a transfer, it will first wait one second and then
-for all forthcoming retries it will double the waiting time until it reaches
-10 minutes which then will be the delay between the rest of the retries. By
-using --retry-delay you disable this exponential backoff algorithm. See also
+When curl is about to retry a transfer, it first waits one second and then for
+all forthcoming retries it doubles the waiting time until it reaches 10
+minutes which then remains delay between the rest of the retries. By using
+--retry-delay you disable this exponential backoff algorithm. See also
--retry-max-time to limit the total time allowed for retries.
-Since curl 7.66.0, curl will comply with the Retry-After: response header if
-one was present to know when to issue the next retry.
+curl complies with the Retry-After: response header if one was present to know
+when to issue the next retry (added in 7.66.0).
This option is superfluous since you can specify a socks4 proxy with --proxy
using a socks4:// protocol prefix. (Added in 7.21.7)
-Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at the same time
---proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to
-the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
+--preproxy can be used to specify a SOCKS proxy at the same time proxy is used
+with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first
+connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or
+HTTPS proxy.
This option is superfluous since you can specify a socks4a proxy with --proxy
using a socks4a:// protocol prefix. (Added in 7.21.7)
-Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at the same time
---proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to
-the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
+--preproxy can be used to specify a SOCKS proxy at the same time --proxy is
+used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first
+connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or
+HTTPS proxy.
This option is superfluous since you can specify a socks5 hostname proxy with
--proxy using a socks5h:// protocol prefix. (Added in 7.21.7)
-Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at the same time
---proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to
-the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
+--preproxy can be used to specify a SOCKS proxy at the same time --proxy is
+used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first
+connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or
+HTTPS proxy.
This option is superfluous since you can specify a socks5 proxy with --proxy
using a socks5:// protocol prefix. (Added in 7.21.7)
-Since 7.52.0, --preproxy can be used to specify a SOCKS proxy at the same time
---proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to
-the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
+--preproxy can be used to specify a SOCKS proxy at the same time --proxy is
+used with an HTTP/HTTPS proxy (added in 7.52.0). In such a case, curl first
+connects to the SOCKS proxy and then connects (through SOCKS) to the HTTP or
+HTTPS proxy.
This option (as well as --socks4) does not work with IPV6, FTPS or LDAP.
Multi: boolean
---
(Schannel) Tell libcurl to automatically locate and use a client certificate
-for authentication, when requested by the server. Prior to 7.77.0 this was the
-default behavior in libcurl with Schannel. Since the server can request any
-certificate that supports client authentication in the OS certificate store it
-could be a privacy violation and unexpected.
+for authentication, when requested by the server. Since the server can request
+any certificate that supports client authentication in the OS certificate
+store it could be a privacy violation and unexpected.
Require SSL/TLS for the connection. Terminates the connection if the transfer
cannot be upgraded to use SSL/TLS.
-This option is handled in LDAP since version 7.81.0. It is fully supported
-by the OpenLDAP backend and rejected by the generic ldap backend if explicit
-TLS is required.
+This option is handled in LDAP (added in 7.81.0). It is fully supported by the
+OpenLDAP backend and rejected by the generic ldap backend if explicit TLS is
+required.
This option is unnecessary if you use a URL scheme that in itself implies
immediate and implicit use of TLS, like for FTPS, IMAPS, POP3S, SMTPS and
the server does not support SSL/TLS. See also --ftp-ssl-control and --ssl-reqd
for different levels of encryption required.
-This option is handled in LDAP since version 7.81.0. It is fully supported
-by the OpenLDAP backend and ignored by the generic ldap backend.
+This option is handled in LDAP (added in 7.81.0). It is fully supported by the
+OpenLDAP backend and ignored by the generic ldap backend.
Please note that a server may close the connection if the negotiation does
not succeed.
-This option was formerly known as --ftp-ssl (Added in 7.11.0). That option
+This option was formerly known as --ftp-ssl (added in 7.11.0). That option
name can still be used but will be removed in a future version.
Example: --sslv2 $URL
Multi: mutex
---
-This option previously asked curl to use SSLv2, but starting in curl 7.77.0
-this instruction is ignored. SSLv2 is widely considered insecure (see RFC
-6176).
+This option previously asked curl to use SSLv2, but is now ignored
+(added in 7.77.0). SSLv2 is widely considered insecure (see RFC 6176).
Example: --sslv3 $URL
Multi: mutex
---
-This option previously asked curl to use SSLv3, but starting in curl 7.77.0
-this instruction is ignored. SSLv3 is widely considered insecure (see RFC
-7568).
+
+This option previously asked curl to use SSLv3, but is now ignored
+(added in 7.77.0). SSLv3 is widely considered insecure (see RFC 7568).
Turn on the TCP_NODELAY option. See the *curl_easy_setopt(3)* man page for
details about this option.
-Since 7.50.2, curl sets this option by default and you need to explicitly
-switch it off if you do not want it on.
+curl sets this option by default and you need to explicitly switch it off if
+you do not want it on (added in 7.50.2).
URL(s) in a config file.
If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
-then curl will make a guess based on the host. If the outermost subdomain
-name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be
-used, otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by
-setting a default protocol, see --proto-default for details.
+then curl will make a guess based on the host. If the outermost subdomain name
+matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be used,
+otherwise HTTP will be used. Guessing can be disabled by setting a default
+protocol (added in 7.45.0), see --proto-default for details.
To control where this URL is written, use the --output or the --remote-name
options.
Output HTTP headers from the most recent request by using *%header{name}*
where *name* is the case insensitive name of the header (without the trailing
colon). The header contents are exactly as sent over the network, with leading
-and trailing whitespace trimmed. Added in curl 7.84.0.
+and trailing whitespace trimmed (added in 7.84.0).
Select a specific target destination file to write the output to, by using
-*%output{name}* where *name* is the full file name. The output following that
-instruction is then written to that file. More than one *%output{}* instruction
-can be specified in the same write-out argument. If the file name cannot be
-created, curl will leave the output to the one used prior to the *%output{}*
-instruction. Use *%output{>>name}* to append data to an existing file. Added in
-curl 8.3.0.
+*%output{name}* (added in curl 8.3.0) where *name* is the full file name. The
+output following that instruction is then written to that file. More than one
+*%output{}* instruction can be specified in the same write-out argument. If
+the file name cannot be created, curl leaves the output destination to the one
+used prior to the *%output{}* instruction. Use *%output{>>name}* to append
+data to an existing file.
**NOTE:**
In Windows the %-symbol is a special symbol used to expand environment
.TP
**num_certs**
Number of server certificates received in the TLS handshake. Supported only by
-the OpenSSL, GnuTLS, Schannel and Secure Transport backends. (Added
-in 7.88.0)
+the OpenSSL, GnuTLS, Schannel and Secure Transport backends.
+(Added in 7.88.0)
.TP
**num_connects**
Number of new connects made in the recent transfer. (Added in 7.12.3)
projects / thirdparty / curl.git / commitdiff
