diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile.am | 7 | ||||
| -rw-r--r-- | docs/cmdline-opts/Makefile.am | 16 | ||||
| -rw-r--r-- | docs/curl.1 | 2697 |
3 files changed, 17 insertions, 2703 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am index a1e64b6ad..ee8f60718 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -5,7 +5,7 @@ # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # -# Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +# Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms @@ -31,7 +31,7 @@ HTMLPAGES = $(GENHTMLPAGES) index.html SUBDIRS = examples libcurl cmdline-opts -CLEANFILES = $(GENHTMLPAGES) $(PDFPAGES) +CLEANFILES = $(GENHTMLPAGES) $(PDFPAGES) curl.1 EXTRA_DIST = MANUAL BUGS CONTRIBUTE.md FAQ FEATURES INTERNALS.md SSLCERTS.md \ README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS VERSIONS KNOWN_BUGS \ @@ -44,6 +44,9 @@ MAN2HTML= roffit $< >$@ SUFFIXES = .1 .html .pdf +curl.1: + cd cmdline-opts && make + html: $(HTMLPAGES) cd libcurl && make html diff --git a/docs/cmdline-opts/Makefile.am b/docs/cmdline-opts/Makefile.am index 4a10b9e5c..3467de156 100644 --- a/docs/cmdline-opts/Makefile.am +++ b/docs/cmdline-opts/Makefile.am @@ -5,7 +5,7 @@ # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # -# Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +# Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms @@ -22,8 +22,9 @@ AUTOMAKE_OPTIONS = foreign no-dependencies -DPAGES = abstract-unix-socket.d anyauth.d \ - append.d basic.d cacert.d capath.d cert.d \ +MANPAGE = $(top_builddir)/docs/curl.1 + +DPAGES = abstract-unix-socket.d anyauth.d append.d basic.d cacert.d capath.d cert.d \ cert-status.d cert-type.d ciphers.d compressed.d config.d \ connect-timeout.d connect-to.d continue-at.d cookie.d cookie-jar.d \ create-dirs.d crlf.d crlfile.d data-ascii.d data-binary.d data.d \ @@ -65,4 +66,11 @@ DPAGES = abstract-unix-socket.d anyauth.d \ unix-socket.d upload-file.d url.d use-ascii.d user-agent.d user.d \ verbose.d version.d write-out.d xattr.d -EXTRA_DIST = $(DPAGES) MANPAGE.md gen.pl page-footer page-header +OTHERPAGES = page-footer page-header + +EXTRA_DIST = $(DPAGES) MANPAGE.md gen.pl $(OTHERPAGES) + +all: $(MANPAGE) + +$(MANPAGE): $(DPAGES) $(OTHERPAGES) + @PERL@ gen.pl mainpage > $(MANPAGE) diff --git a/docs/curl.1 b/docs/curl.1 deleted file mode 100644 index dfee670e9..000000000 --- a/docs/curl.1 +++ /dev/null @@ -1,2697 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. -.\" * -.\" * This software is licensed as described in the file COPYING, which -.\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. -.\" * -.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell -.\" * copies of the Software, and permit persons to whom the Software is -.\" * furnished to do so, under the terms of the COPYING file. -.\" * -.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY -.\" * KIND, either express or implied. -.\" * -.\" ************************************************************************** -.\" -.\" DO NOT EDIT. Generated by the curl project gen.pl man page generator. -.\" -.TH curl 1 "16 Dec 2016" "Curl 7.52.0" "Curl Manual" -.SH NAME -curl \- transfer a URL -.SH SYNOPSIS -.B curl [options] -.I [URL...] -.SH DESCRIPTION -.B curl -is a tool to transfer data from or to a server, using one of the supported -protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, -LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET -and TFTP). The command is designed to work without user interaction. - -curl offers a busload of useful tricks like proxy support, user -authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer -resume, Metalink, and more. As you will see below, the number of features will -make your head spin! - -curl is powered by libcurl for all transfer-related features. See -\fIlibcurl(3)\fP for details. -.SH URL -The URL syntax is protocol-dependent. You'll find a detailed description in -RFC 3986. - -You can specify multiple URLs or parts of URLs by writing part sets within -braces as in: - - http://site.{one,two,three}.com - -or you can get sequences of alphanumeric series by using [] as in: - - ftp://ftp.example.com/file[1-100].txt - - ftp://ftp.example.com/file[001-100].txt (with leading zeros) - - ftp://ftp.example.com/file[a-z].txt - -Nested sequences are not supported, but you can use several ones next to each -other: - - http://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html - -You can specify any amount of URLs on the command line. They will be fetched -in a sequential manner in the specified order. - -You can specify a step counter for the ranges to get every Nth number or -letter: - - http://example.com/file[1-100:10].txt - - http://example.com/file[a-z:2].txt - -When using [] or {} sequences when invoked from a command line prompt, you -probably have to put the full URL within double quotes to avoid the shell from -interfering with it. This also goes for other characters treated special, like -for example '&', '?' and '*'. - -Provide the IPv6 zone index in the URL with an escaped percentage sign and the -interface name. Like in - - http://[fe80::3%25eth0]/ - -If you specify URL without protocol:// prefix, curl will attempt to guess what -protocol you might want. It will then default to HTTP but try other protocols -based on often-used host name prefixes. For example, for host names starting -with "ftp." curl will assume you want to speak FTP. - -curl will do its best to use what you pass to it as a URL. It is not trying to -validate it as a syntactically correct URL by any means but is instead -\fBvery\fP liberal with what it accepts. - -curl will attempt to re-use connections for multiple file transfers, so that -getting many files from the same server will not do multiple connects / -handshakes. This improves speed. Of course this is only done on files -specified on a single command line and cannot be used between separate curl -invokes. -.SH "PROGRESS METER" -curl normally displays a progress meter during operations, indicating the -amount of transferred data, transfer speeds and estimated time left, etc. The -progress meter displays number of bytes and the speeds are in bytes per -second. The suffixes (k, M, G, T, P) are 1024 based. For example 1k is 1024 -bytes. 1M is 1048576 bytes. - -curl displays this data to the terminal by default, so if you invoke curl to -do an operation and it is about to write data to the terminal, it -\fIdisables\fP the progress meter as otherwise it would mess up the output -mixing progress meter and response data. - -If you want a progress meter for HTTP POST or PUT requests, you need to -redirect the response output to a file, using shell redirect (>), \fI-o, --output\fP or -similar. - -It is not the same case for FTP upload as that operation does not spit out -any response data to the terminal. - -If you prefer a progress "bar" instead of the regular meter, \fI-#, --progress-bar\fP is -your friend. You can also disable the progress meter completely with the -\fI-s, --silent\fP option. -.SH OPTIONS -Options start with one or two dashes. Many of the options require an -additional value next to them. - -The short "single-dash" form of the options, -d for example, may be used with -or without a space between it and its value, although a space is a recommended -separator. The long "double-dash" form, \fI-d, --data\fP for example, requires a space -between it and its value. - -Short version options that don't need any additional values can be used -immediately next to each other, like for example you can specify all the -options -O, -L and -v at once as -OLv. - -In general, all boolean options are enabled with --\fBoption\fP and yet again -disabled with --\fBno-\fPoption. That is, you use the exact same option name -but prefix it with "no-". However, in this list we mostly only list and show -the --option version of them. (This concept with --no options was added in -7.19.0. Previously most options were toggled on/off on repeated use of the -same command line option.) -.IP "--abstract-unix-socket <path>" -(HTTP) Connect through an abstract Unix domain socket, instead of using the network. -Note: netstat shows the path of an abstract socket prefixed with '@', however -the <path> argument should not have this leading character. - -Added in 7.53.0. -.IP "--anyauth" -(HTTP) Tells curl to figure out authentication method by itself, and use the most -secure one the remote site claims to support. This is done by first doing a -request and checking the response-headers, thus possibly inducing an extra -network round-trip. This is used instead of setting a specific authentication -method, which you can do with \fI--basic\fP, \fI--digest\fP, \fI--ntlm\fP, and \fI--negotiate\fP. - -Using \fI--anyauth\fP is not recommended if you do uploads from stdin, since it may -require data to be sent twice and then the client must be able to rewind. If -the need should arise when uploading from stdin, the upload operation will -fail. - -Used together with \fI-u, --user\fP. - -See also \fI--proxy-anyauth\fP and \fI--basic\fP and \fI--digest\fP. -.IP "-a, --append" -(FTP SFTP) When used in an upload, this makes curl append to the target file instead of -overwriting it. If the remote file doesn't exist, it will be created. Note -that this flag is ignored by some SFTP servers (including OpenSSH). -.IP "--basic" -(HTTP) Tells curl to use HTTP Basic authentication with the remote host. This is the -default and this option is usually pointless, unless you use it to override a -previously set option that sets a different authentication method (such as -\fI--ntlm\fP, \fI--digest\fP, or \fI--negotiate\fP). - -Used together with \fI-u, --user\fP. - -See also \fI--proxy-basic\fP. -.IP "--cacert <CA certificate>" -(TLS) Tells curl to use the specified certificate file to verify the peer. The file -may contain multiple CA certificates. The certificate(s) must be in PEM -format. Normally curl is built to use a default file for this, so this option -is typically used to alter that default file. - -curl recognizes the environment variable named 'CURL_CA_BUNDLE' if it is -set, and uses the given path as a path to a CA cert bundle. This option -overrides that variable. - -The windows version of curl will automatically look for a CA certs file named -\'curl-ca-bundle.crt\', either in the same directory as curl.exe, or in the -Current Working Directory, or in any folder along your PATH. - -If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module -(libnsspem.so) needs to be available for this option to work properly. - -(iOS and macOS only) If curl is built against Secure Transport, then this -option is supported for backward compatibility with other SSL engines, but it -should not be set. If the option is not set, then curl will use the -certificates in the system and user Keychain to verify the peer, which is the -preferred method of verifying the peer's certificate chain. - -If this option is used several times, the last one will be used. -.IP "--capath <dir>" -(TLS) Tells curl to use the specified certificate directory to verify the -peer. Multiple paths can be provided by separating them with ":" (e.g. -\&"path1:path2:path3"). The certificates must be in PEM format, and if curl is -built against OpenSSL, the directory must have been processed using the -c_rehash utility supplied with OpenSSL. Using \fI--capath\fP can allow -OpenSSL-powered curl to make SSL-connections much more efficiently than using -\fI--cacert\fP if the --cacert file contains many CA certificates. - -If this option is set, the default capath value will be ignored, and if it is -used several times, the last one will be used. -.IP "--cert-status" -(TLS) Tells curl to verify the status of the server certificate by using the -Certificate Status Request (aka. OCSP stapling) TLS extension. - -If this option is enabled and the server sends an invalid (e.g. expired) -response, if the response suggests that the server certificate has been revoked, -or no response at all is received, the verification fails. - -This is currently only implemented in the OpenSSL, GnuTLS and NSS backends. - -Added in 7.41.0. -.IP "--cert-type <type>" -(TLS) Tells curl what certificate type the provided certificate is in. PEM, DER and -ENG are recognized types. If not specified, PEM is assumed. - -If this option is used several times, the last one will be used. - -See also \fI-E, --cert\fP and \fI--key\fP and \fI--key-type\fP. -.IP "-E, --cert <certificate[:password]>" -(TLS) Tells curl to use the specified client certificate file when getting a file -with HTTPS, FTPS or another SSL-based protocol. The certificate must be in -PKCS#12 format if using Secure Transport, or PEM format if using any other -engine. If the optional password isn't specified, it will be queried for on -the terminal. Note that this option assumes a \&"certificate" file that is the -private key and the client certificate concatenated! See \fI-E, --cert\fP and \fI--key\fP to -specify them independently. - -If curl is built against the NSS SSL library then this option can tell -curl the nickname of the certificate to use within the NSS database defined -by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the -NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be -loaded. If you want to use a file from the current directory, please precede -it with "./" prefix, in order to avoid confusion with a nickname. If the -nickname contains ":", it needs to be preceded by "\\" so that it is not -recognized as password delimiter. If the nickname contains "\\", it needs to -be escaped as "\\\\" so that it is not recognized as an escape character. - -(iOS and macOS only) If curl is built against Secure Transport, then the -certificate string can either be the name of a certificate/private key in the -system or user keychain, or the path to a PKCS#12-encoded certificate and -private key. If you want to use a file from the current directory, please -precede it with "./" prefix, in order to avoid confusion with a nickname. - -If this option is used several times, the last one will be used. - -See also \fI--cert-type\fP and \fI--key\fP and \fI--key-type\fP. -.IP "--ciphers <list of ciphers>" -(TLS) Specifies which ciphers to use in the connection. The list of ciphers must -specify valid ciphers. Read up on SSL cipher list details on this URL: - - https://curl.haxx.se/docs/ssl-ciphers.html - -If this option is used several times, the last one will be used. -.IP "--compressed" -(HTTP) Request a compressed response using one of the algorithms curl supports, and -save the uncompressed document. If this option is used and the server sends -an unsupported encoding, curl will report an error. -.IP "-K, --config <file>" -Specify which config file to read curl arguments from. The config file is a -text file in which command line arguments can be written which then will be -used as if they were written on the actual command line. - -Options and their parameters must be specified on the same config file line, -separated by whitespace, colon, or the equals sign. Long option names can -optionally be given in the config file without the initial double dashes and -if so, the colon or equals characters can be used as separators. If the option -is specified with one or two dashes, there can be no colon or equals character -between the option and its parameter. - -If the parameter is to contain whitespace, the parameter must be enclosed -within quotes. Within double quotes, the following escape sequences are -available: \\\\, \\", \\t, \\n, \\r and \\v. A backslash preceding any other -letter is ignored. If the first column of a config line is a '#' character, -the rest of the line will be treated as a comment. Only write one option per -physical line in the config file. - -Specify the filename to \fI-K, --config\fP as '-' to make curl read the file from stdin. - -Note that to be able to specify a URL in the config file, you need to specify -it using the \fI--url\fP option, and not by simply writing the URL on its own -line. So, it could look similar to this: - -url = "https://curl.haxx.se/docs/" - -When curl is invoked, it always (unless \fI-q, --disable\fP is used) checks for a -default config file and uses it if found. The default config file is checked -for in the following places in this order: - -1) curl tries to find the "home dir": It first checks for the CURL_HOME and -then the HOME environment variables. Failing that, it uses getpwuid() on -Unix-like systems (which returns the home dir given the current user in your -system). On Windows, it then checks for the APPDATA variable, or as a last -resort the '%USERPROFILE%\\Application Data'. - -2) On windows, if there is no _curlrc file in the home dir, it checks for one -in the same dir the curl executable is placed. On Unix-like systems, it will -simply try to load .curlrc from the determined home dir. - -.nf -# --- Example file --- -# this is a comment -url = "example.com" -output = "curlhere.html" -user-agent = "superagent/1.0" - -# and fetch another URL too -url = "example.com/docs/manpage.html" --O -referer = "http://nowhereatall.example.com/" -# --- End of example file --- -.fi - -This option can be used multiple times to load multiple config files. -.IP "--connect-timeout <seconds>" -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. - -If this option is used several times, the last one will be used. - -See also \fI-m, --max-time\fP. -.IP "--connect-to <HOST1:PORT1:HOST2:PORT2>" - -For a request to the given HOST:PORT pair, connect to -CONNECT-TO-HOST:CONNECT-TO-PORT instead. This option is suitable to direct -requests at a specific server, e.g. at a specific cluster node in a cluster of -servers. This option is only used to establish the network connection. It -does NOT affect the hostname/port that is used for TLS/SSL (e.g. SNI, -certificate verification) or for the application protocols. "host" and "port" -may be the empty string, meaning "any host/port". "connect-to-host" and -"connect-to-port" may also be the empty string, meaning "use the request's -original host/port". - -This option can be used many times to add many connect rules. - -See also \fI--resolve\fP and \fI-H, --header\fP. Added in 7.49.0. -.IP "-C, --continue-at <offset>" -Continue/Resume a previous file transfer at the given offset. The given offset -is the exact number of bytes that will be skipped, counting from the beginning -of the source file before it is transferred to the destination. If used with -uploads, the FTP server command SIZE will not be used by curl. - -Use "-C -" to tell curl to automatically find out where/how to resume the -transfer. It then uses the given output/input files to figure that out. - -If this option is used several times, the last one will be used. - -See also \fI-r, --range\fP. -.IP "-c, --cookie-jar <filename>" -(HTTP) Specify to which file you want curl to write all cookies after a completed -operation. Curl writes all cookies from its in-memory cookie storage to the -given file at the end of operations. If no cookies are known, no data will be -written. The file will be written using the Netscape cookie file format. If -you set the file name to a single dash, "-", the cookies will be written to -stdout. - -This command line option will activate the cookie engine that makes curl -record and use cookies. Another way to activate it is to use the \fI-b, --cookie\fP -option. - -If the cookie jar can't be created or written to, the whole curl operation -won't fail or even report an error clearly. Using \fI-v, --verbose\fP will get a warning -displayed, but that is the only visible feedback you get about this possibly -lethal situation. - -If this option is used several times, the last specified file name will be -used. -.IP "-b, --cookie <data>" -(HTTP) Pass the data to the HTTP server in the Cookie header. It is supposedly -the data previously received from the server in a "Set-Cookie:" line. The -data should be in the format "NAME1=VALUE1; NAME2=VALUE2". - -If no '=' symbol is used in the argument, it is instead treated as a filename -to read previously stored cookie from. This option also activates the cookie -engine which will make curl record incoming cookies, which may be handy if -you're using this in combination with the \fI-L, --location\fP option or do multiple URL -transfers on the same invoke. - -The file format of the file to read cookies from should be plain HTTP headers -(Set-Cookie style) or the Netscape/Mozilla cookie file format. - -The file specified with \fI-b, --cookie\fP is only used as input. No cookies will be -written to the file. To store cookies, use the \fI-c, --cookie-jar\fP option. - -Exercise caution if you are using this option and multiple transfers may -occur. If you use the NAME1=VALUE1; format, or in a file use the Set-Cookie -format and don't specify a domain, then the cookie is sent for any domain -(even after redirects are followed) and cannot be modified by a server-set -cookie. If the cookie engine is enabled and a server sets a cookie of the same -name then both will be sent on a future transfer to that server, likely not -what you intended. To address these issues set a domain in Set-Cookie (doing -that will include sub domains) or use the Netscape format. - -If this option is used several times, the last one will be used. - -Users very often want to both read cookies from a file and write updated -cookies back to a file, so using both \fI-b, --cookie\fP and \fI-c, --cookie-jar\fP in the same -command line is common. -.IP "--create-dirs" -When used in conjunction with the \fI-o, --output\fP option, curl will create the -necessary local directory hierarchy as needed. This option creates the dirs -mentioned with the \fI-o, --output\fP option, nothing else. If the --output file name -uses no dir or if the dirs it mentions already exist, no dir will be created. - -To create remote directories when using FTP or SFTP, try \fI--ftp-create-dirs\fP. -.IP "--crlf" -(FTP SMTP) Convert LF to CRLF in upload. Useful for MVS (OS/390). - -(SMTP added in 7.40.0) -.IP "--crlfile <file>" -(TLS) Provide a file using PEM format with a Certificate Revocation List that may -specify peer certificates that are to be considered revoked. - -If this option is used several times, the last one will be used. - -Added in 7.19.7. -.IP "--data-ascii <data>" -(HTTP) This is just an alias for \fI-d, --data\fP. -.IP "--data-binary <data>" -(HTTP) This posts data exactly as specified with no extra processing whatsoever. - -If you start the data with the letter @, the rest should be a filename. Data -is posted in a similar manner as \fI-d, --data\fP does, except that newlines and -carriage returns are preserved and conversions are never done. - -If this option is used several times, the ones following the first will append -data as described in \fI-d, --data\fP. -.IP "--data-raw <data>" -(HTTP) This posts data similarly to \fI-d, --data\fP but without the special -interpretation of the @ character. - -See also \fI-d, --data\fP. Added in 7.43.0. -.IP "--data-urlencode <data>" -(HTTP) This posts data, similar to the other \fI-d, --data\fP options with the exception -that this performs URL-encoding. - -To be CGI-compliant, the <data> part should begin with a \fIname\fP followed -by a separator and a content specification. The <data> part can be passed to -curl using one of the following syntaxes: -.RS -.IP "content" -This will make curl URL-encode the content and pass that on. Just be careful -so that the content doesn't contain any = or @ symbols, as that will then make -the syntax match one of the other cases below! -.IP "=content" -This will make curl URL-encode the content and pass that on. The preceding = -symbol is not included in the data. -.IP "name=content" -This will make curl URL-encode the content part and pass that on. Note that -the name part is expected to be URL-encoded already. -.IP "@filename" -This will make curl load data from the given file (including any newlines), -URL-encode that data and pass it on in the POST. -.IP "name@filename" -This will make curl load data from the given file (including any newlines), -URL-encode that data and pass it on in the POST. The name part gets an equal -sign appended, resulting in \fIname=urlencoded-file-content\fP. Note that the -name is expected to be URL-encoded already. -.RE - -See also \fI-d, --data\fP and \fI--data-raw\fP. Added in 7.18.0. -.IP "-d, --data <data>" -(HTTP) Sends the specified data in a POST request to the HTTP server, in the same way -that a browser does when a user has filled in an HTML form and presses the -submit button. This will cause curl to pass the data to the server using the -content-type application/x-www-form-urlencoded. Compare to \fI-F, --form\fP. - -\fI--data-raw\fP is almost the same but does not have a special interpretation of -the @ character. To post data purely binary, you should instead use the -\fI--data-binary\fP option. To URL-encode the value of a form field you may use -\fI--data-urlencode\fP. - -If any of these options is used more than once on the same command line, the -data pieces specified will be merged together with a separating -&-symbol. Thus, using '-d name=daniel -d skill=lousy' would generate a post -chunk that looks like \&'name=daniel&skill=lousy'. - -If you start the data with the letter @, the rest should be a file name to -read the data from, or - if you want curl to read the data from -stdin. Multiple files can also be specified. Posting data from a file named -'foobar' would thus be done with \fI-d, --data\fP @foobar. When --data is told to read -from a file like that, carriage returns and newlines will be stripped out. If -you don't want the @ character to have a special interpretation use \fI--data-raw\fP -instead. - -See also \fI--data-binary\fP and \fI--data-urlencode\fP and \fI--data-raw\fP. This option overrides \fI-F, --form\fP and \fI-I, --head\fP and \fI--upload\fP. -.IP "--delegation <LEVEL>" -(GSS/kerberos) Set LEVEL to tell the server what it is allowed to delegate when it -comes to user credentials. -.RS -.IP "none" -Don't allow any delegation. -.IP "policy" -Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos -service ticket, which is a matter of realm policy. -.IP "always" -Unconditionally allow the server to delegate. -.RE -.IP "--digest" -(HTTP) Enables HTTP Digest authentication. This is an authentication scheme that -prevents the password from being sent over the wire in clear text. Use this in -combination with the normal \fI-u, --user\fP option to set user name and password. - -If this option is used several times, only the first one is used. - -See also \fI-u, --user\fP and \fI--proxy-digest\fP and \fI--anyauth\fP. This option overrides \fI--basic\fP and \fI--ntlm\fP and \fI--negotiate\fP. -.IP "--disable-eprt" -(FTP) Tell curl to disable the use of the EPRT and LPRT commands when doing active -FTP transfers. Curl will normally always first attempt to use EPRT, then LPRT -before using PORT, but with this option, it will use PORT right away. EPRT and -LPRT are extensions to the original FTP protocol, and may not work on all -servers, but they enable more functionality in a better way than the -traditional PORT command. - ---eprt can be used to explicitly enable EPRT again and --no-eprt is an alias -for \fI--disable-eprt\fP. - -If the server is accessed using IPv6, this option will have no effect as EPRT -is necessary then. - -Disabling EPRT only changes the active behavior. If you want to switch to -passive mode you need to not use \fI-P, --ftp-port\fP or force it with \fI--ftp-pasv\fP. -.IP "--disable-epsv" -(FTP) (FTP) Tell curl to disable the use of the EPSV command when doing passive FTP -transfers. Curl will normally always first attempt to use EPSV before PASV, -but with this option, it will not try using EPSV. - ---epsv can be used to explicitly enable EPSV again and --no-epsv is an alias -for \fI--disable-epsv\fP. - -If the server is an IPv6 host, this option will have no effect as EPSV is -necessary then. - -Disabling EPSV only changes the passive behavior. If you want to switch to -active mode you need to use \fI-P, --ftp-port\fP. -.IP "-q, --disable" -If used as the first parameter on the command line, the \fIcurlrc\fP config -file will not be read and used. See the \fI-K, --config\fP for details on the default -config file search path. -.IP "--dns-interface <interface>" -(DNS) Tell curl to send outgoing DNS requests through <interface>. This option is a -counterpart to \fI--interface\fP (which does not affect DNS). The supplied string -must be an interface name (not an address). - -See also \fI--dns-ipv4-addr\fP and \fI--dns-ipv6-addr\fP. \fI--dns-interface\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0. -.IP "--dns-ipv4-addr <address>" -(DNS) Tell curl to bind to <ip-address> when making IPv4 DNS requests, so that -the DNS requests originate from this address. The argument should be a -single IPv4 address. - -See also \fI--dns-interface\fP and \fI--dns-ipv6-addr\fP. \fI--dns-ipv4-addr\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0. -.IP "--dns-ipv6-addr <address>" -(DNS) Tell curl to bind to <ip-address> when making IPv6 DNS requests, so that -the DNS requests originate from this address. The argument should be a -single IPv6 address. - -See also \fI--dns-interface\fP and \fI--dns-ipv4-addr\fP. \fI--dns-ipv6-addr\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0. -.IP "--dns-servers <addresses>" -Set the list of DNS servers to be used instead of the system default. -The list of IP addresses should be separated with commas. Port numbers -may also optionally be given as \fI:<port-number>\fP after each IP -address. - -\fI--dns-servers\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0. -.IP "-D, --dump-header <filename>" -(HTTP FTP) Write the received protocol headers to the specified file. - -This option is handy to use when you want to store the headers that an HTTP -site sends to you. Cookies from the headers could then be read in a second -curl invocation by using the \fI-b, --cookie\fP option! The \fI-c, --cookie-jar\fP option is a -better way to store cookies. - -When used in FTP, the FTP server response lines are considered being "headers" -and thus are saved there. - -If this option is used several times, the last one will be used. - -See also \fI-o, --output\fP. -.IP "--egd-file <file>" -(TLS) Specify the path name to the Entropy Gathering Daemon socket. The socket is -used to seed the random engine for SSL connections. - -See also \fI--random-file\fP. -.IP "--engine <name>" -(TLS) Select the OpenSSL crypto engine to use for cipher operations. Use \fI--engine\fP -list to print a list of build-time supported engines. Note that not all (or -none) of the engines may be available at run-time. -.IP "--environment" -Sets a range of environment variables, using the names the \fI-w, --write-out\fP option -supports, to allow easier extraction of useful information after having run -curl. - -\fI--environment\fP requires that the underlying libcurl was built to support RISC OS. -.IP "--expect100-timeout <seconds>" -(HTTP) Maximum time in seconds that you allow curl to wait for a 100-continue -response when curl emits an Expects: 100-continue header in its request. By -default curl will wait one second. This option accepts decimal values! When -curl stops waiting, it will continue as if the response has been received. - -See also \fI--connect-timeout\fP. Added in 7.47.0. -.IP "--fail-early" -Fail and exit on first detected error. - -When curl is used to do multiple transfers on the command line, it will -attempt to operate on each given URL, one by one. By default, it will ignore -errors if there are more URLs given and the last URL's success will determine -the error code curl returns. So early failures will be "hidden" by subsequent -successful transfers. - -Using this option, curl will instead return an error on the first transfers -that fails, independent on the amount of more URLs that are given on the -command line. This way, no transfer failures go undetected by scripts and -similar. - -This option will apply for all given URLs even if you use \fI-:, --next\fP. - -Added in 7.52.0. -.IP "-f, --fail" -(HTTP) Fail silently (no output at all) on server errors. This is mostly done to -better enable scripts etc to better deal with failed attempts. In normal cases -when an HTTP server fails to deliver a document, it returns an HTML document -stating so (which often also describes why and more). This flag will prevent -curl from outputting that and return error 22. - -This method is not fail-safe and there are occasions where non-successful -response codes will slip through, especially when authentication is involved -(response codes 401 and 407). -.IP "--false-start" -(TLS) Tells curl to use false start during the TLS handshake. False start is a mode -where a TLS client will start sending application data before verifying the -server's Finished message, thus saving a round trip when performing a full -handshake. - -This is currently only implemented in the NSS and Secure Transport (on iOS 7.0 -or later, or OS X 10.9 or later) backends. - -Added in 7.42.0. -.IP "--form-string <name=string>" -(HTTP) Similar to \fI-F, --form\fP except that the value string for the named parameter is used -literally. Leading \&'@' and \&'<' characters, and the \&';type=' string in -the value have no special meaning. Use this in preference to \fI-F, --form\fP if -there's any possibility that the string value may accidentally trigger the -\&'@' or \&'<' features of \fI-F, --form\fP. - -See also \fI-F, --form\fP. -.IP "-F, --form <name=content>" -(HTTP) This lets curl emulate a filled-in form in which a user has pressed the submit -button. This causes curl to POST data using the Content-Type -multipart/form-data according to RFC 2388. This enables uploading of binary -files etc. To force the 'content' part to be a file, prefix the file name with -an @ sign. To just get the content part from a file, prefix the file name with -the symbol <. The difference between @ and < is then that @ makes a file get -attached in the post as a file upload, while the < makes a text field and just -get the contents for that text field from a file. - -Example: to send an image to a server, where \&'profile' is the name of the -form-field to which portrait.jpg will be the input: - - curl -F profile=@portrait.jpg https://example.com/upload.cgi - -To read content from stdin instead of a file, use - as the filename. This goes -for both @ and < constructs. Unfortunately it does not support reading the -file from a named pipe or similar, as it needs the full size before the -transfer starts. - -You can also tell curl what Content-Type to use by using 'type=', in a manner -similar to: - - curl -F "web=@index.html;type=text/html" example.com - -or - - curl -F "name=daniel;type=text/foo" example.com - -You can also explicitly change the name field of a file upload part by setting -filename=, like this: - - curl -F "file=@localfile;filename=nameinpost" example.com - -If filename/path contains ',' or ';', it must be quoted by double-quotes like: - - curl -F "file=@\\"localfile\\";filename=\\"nameinpost\\"" example.com - -or - - curl -F 'file=@"localfile";filename="nameinpost"' example.com - -Note that if a filename/path is quoted by double-quotes, any double-quote -or backslash within the filename must be escaped by backslash. - -See further examples and details in the MANUAL. - -This option can be used multiple times. - -This option overrides \fI-d, --data\fP and \fI-I, --head\fP and \fI--upload\fP. -.IP "--ftp-account <data>" -(FTP) When an FTP server asks for "account data" after user name and password has -been provided, this data is sent off using the ACCT command. - -If this option is used several times, the last one will be used. - -Added in 7.13.0. -.IP "--ftp-alternative-to-user <command>" -(FTP) If authenticating with the USER and PASS commands fails, send this command. -When connecting to Tumbleweed's Secure Transport server over FTPS using a -client certificate, using "SITE AUTH" will tell the server to retrieve the -username from the certificate. - -Added in 7.15.5. -.IP "--ftp-create-dirs" -(FTP SFTP) When an FTP or SFTP URL/operation uses a path that doesn't currently exist on -the server, the standard behavior of curl is to fail. Using this option, curl -will instead attempt to create missing directories. - -See also \fI--create-dirs\fP. -.IP "--ftp-method <method>" -(FTP) Control what method curl should use to reach a file on an FTP(S) -server. The method argument should be one of the following alternatives: -.RS -.IP multicwd -curl does a single CWD operation for each path part in the given URL. For deep -hierarchies this means very many commands. This is how RFC 1738 says it should -be done. This is the default but the slowest behavior. -.IP nocwd -curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a full -path to the server for all these commands. This is the fastest behavior. -.IP singlecwd -curl does one CWD with the full target directory and then operates on the file -\&"normally" (like in the multicwd case). This is somewhat more standards -compliant than 'nocwd' but without the full penalty of 'multicwd'. -.RE - -Added in 7.15.1. -.IP "--ftp-pasv" -(FTP) Use passive mode for the data connection. Passive is the internal default -behavior, but using this option can be used to override a previous \fI-P, --ftp-port\fP -option. - -If this option is used several times, only the first one is used. Undoing an -enforced passive really isn't doable but you must then instead enforce the -correct \fI-P, --ftp-port\fP again. - -Passive mode means that curl will try the EPSV command first and then PASV, -unless \fI--disable-epsv\fP is used. - -See also \fI--disable-epsv\fP. Added in 7.11.0. -.IP "-P, --ftp-port <address>" -(FTP) Reverses the default initiator/listener roles when connecting with FTP. This -option makes curl use active mode. curl then tells the server to connect back -to the client's specified address and port, while passive mode asks the server -to setup an IP address and port for it to connect to. <address> should be one -of: -.RS -.IP interface -i.e "eth0" to specify which interface's IP address you want to use (Unix only) -.IP "IP address" -i.e "192.168.10.1" to specify the exact IP address -.IP "host name" -i.e "my.host.domain" to specify the machine -.IP "-" -make curl pick the same IP address that is already used for the control -connection -.RE - -If this option is used several times, the last one will be used. Disable the -use of PORT with \fI--ftp-pasv\fP. Disable the attempt to use the EPRT command -instead of PORT by using \fI--disable-eprt\fP. EPRT is really PORT++. - -Since 7.19.5, you can append \&":[start]-[end]\&" to the right of the address, -to tell curl what TCP port range to use. That means you specify a port range, -from a lower to a higher number. A single number works as well, but do note -that it increases the risk of failure since the port may not be available. - -See also \fI--ftp-pasv\fP and \fI--disable-eprt\fP. -.IP "--ftp-pret" -(FTP) Tell curl to send a PRET command before PASV (and EPSV). Certain FTP servers, -mainly drftpd, require this non-standard command for directory listings as -well as up and downloads in PASV mode. - -Added in 7.20.0. -.IP "--ftp-skip-pasv-ip" -(FTP) Tell curl to not use the IP address the server suggests in its response -to curl's PASV command when curl connects the data connection. Instead curl -will re-use the same IP address it already uses for the control -connection. - -This option has no effect if PORT, EPRT or EPSV is used instead of PASV. - -See also \fI--ftp-pasv\fP. Added in 7.14.2. -.IP "--ftp-ssl-ccc-mode <active/passive>" -(FTP) Sets the CCC mode. The passive mode will not initiate the shutdown, but -instead wait for the server to do it, and will not reply to the shutdown from -the server. The active mode initiates the shutdown and waits for a reply from -the server. - -See also \fI--ftp-ssl-ccc\fP. Added in 7.16.2. -.IP "--ftp-ssl-ccc" -(FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after -authenticating. The rest of the control channel communication will be -unencrypted. This allows NAT routers to follow the FTP transaction. The -default mode is passive. - -See also \fI--ssl\fP and \fI--ftp-ssl-ccc-mode\fP. Added in 7.16.1. -.IP "--ftp-ssl-control" -(FTP) Require SSL/TLS for the FTP login, clear for transfer. Allows secure -authentication, but non-encrypted data transfers for efficiency. Fails the -transfer if the server doesn't support SSL/TLS. - -Added in 7.16.0. -.IP "-G, --get" -When used, this option will make all data specified with \fI-d, --data\fP, \fI--data-binary\fP -or \fI--data-urlencode\fP to be used in an HTTP GET request instead of the POST -request that otherwise would be used. The data will be appended to the URL -with a '?' separator. - -If used in combination with \fI-I, --head\fP, the POST data will instead be appended to -the URL with a HEAD request. - -If this option is used several times, only the first one is used. This is -because undoing a GET doesn't make sense, but you should then instead enforce -the alternative method you prefer. -.IP "-g, --globoff" -This option switches off the "URL globbing parser". When you set this option, -you can specify URLs that contain the letters {}[] without having them being -interpreted by curl itself. Note that these letters are not normal legal URL -contents but they should be encoded according to the URI standard. -.IP "-I, --head" -(HTTP FTP FILE) Fetch the headers only! HTTP-servers feature the command HEAD which this uses -to get nothing but the header of a document. When used on an FTP or FILE file, -curl displays the file size and last modification time only. -.IP "-H, --header <header>" -(HTTP) -Extra header to include in the request when sending HTTP to a server. You may -specify any number of extra headers. Note that if you should add a custom -header that has the same name as one of the internal ones curl would use, your -externally set header will be used instead of the internal one. This allows -you to make even trickier stuff than curl would normally do. You should not -replace internally set headers without knowing perfectly well what you're -doing. Remove an internal header by giving a replacement without content on -the right side of the colon, as in: -H \&"Host:". If you send the custom -header with no-value then its header must be terminated with a semicolon, such -as \-H \&"X-Custom-Header;" to send "X-Custom-Header:". - -curl will make sure that each header you add/replace is sent with the proper -end-of-line marker, you should thus \fBnot\fP add that as a part of the header -content: do not add newlines or carriage returns, they will only mess things up -for you. - -See also the \fI-A, --user-agent\fP and \fI-e, --referer\fP options. - -Starting in 7.37.0, you need \fI--proxy-header\fP to send custom headers intended -for a proxy. - -Example: - - curl -H "X-First-Name: Joe" http://example.com/ - -\fBWARNING\fP: headers set with this option will be set in all requests - even -after redirects are followed, like when told with \fI-L, --location\fP. This can lead to -the header being sent to other hosts than the original host, so sensitive -headers should be used with caution combined with following redirects. - -This option can be used multiple times to add/replace/remove multiple headers. -.IP "-h, --help" -Usage help. This lists all current command line options with a short -description. -.IP "--hostpubmd5 <md5>" -(SFTP SCP) Pass a string containing 32 hexadecimal digits. The string should -be the 128 bit MD5 checksum of the remote host's public key, curl will refuse -the connection with the host unless the md5sums match. - -Added in 7.17.1. -.IP "-0, --http1.0" -(HTTP) Tells curl to use HTTP version 1.0 instead of using its internally preferred -HTTP version. - -This option overrides \fI--http1.1\fP and \fI--http2\fP. -.IP "--http1.1" -(HTTP) Tells curl to use HTTP version 1.1. - -This option overrides \fI-0, --http1.0\fP and \fI--http2\fP. Added in 7.33.0. -.IP "--http2-prior-knowledge" -(HTTP) Tells curl to issue its non-TLS HTTP requests using HTTP/2 without HTTP/1.1 -Upgrade. It requires prior knowledge that the server supports HTTP/2 straight -away. HTTPS requests will still do HTTP/2 the standard way with negotiated -protocol version in the TLS handshake. - -\fI--http2-prior-knowledge\fP requires that the underlying libcurl was built to support HTTP/2. This option overrides \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2\fP. Added in 7.49.0. -.IP "--http2" -(HTTP) Tells curl to use HTTP version 2. - -See also \fI--no-alpn\fP. \fI--http2\fP requires that the underlying libcurl was built to support HTTP/2. This option overrides \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2-prior-knowledge\fP. Added in 7.33.0. -.IP "--ignore-content-length" -(FTP HTTP) For HTTP, Ignore the Content-Length header. This is particularly useful for -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. -.IP "-i, --include" -Include the HTTP-header in the output. The HTTP-header includes things like -server-name, date of the document, HTTP-version and more... - -See also \fI-v, --verbose\fP. -.IP "-k, --insecure" -(TLS) This option explicitly allows curl to perform "insecure" SSL connections and -transfers. All SSL connections are attempted to be made secure by using the CA -certificate bundle installed by default. This makes all connections considered -\&"insecure" fail unless \fI-k, --insecure\fP is used. - -See this online resource for further details: - https://curl.haxx.se/docs/sslcerts.html -.IP "--interface <name>" - -Perform an operation using a specified interface. You can enter interface -name, IP address or host name. An example could look like: - - curl --interface eth0:1 https://www.example.com/ - -If this option is used several times, the last one will be used. - -See also \fI--dns-interface\fP. -.IP "-4, --ipv4" -This option tells curl to resolve names to IPv4 addresses only, and not for -example try IPv6. - -See also \fI--http1.1\fP and \fI--http2\fP. This option overrides \fI-6, --ipv6\fP. -.IP "-6, --ipv6" -This option tells curl to resolve names to IPv6 addresses only, and not for -example try IPv4. - -See also \fI--http1.1\fP and \fI--http2\fP. This option overrides \fI-6, --ipv6\fP. -.IP "-j, --junk-session-cookies" -(HTTP) When curl is told to read cookies from a given file, this option will make it -discard all "session cookies". This will basically have the same effect as if -a new session is started. Typical browsers always discard session cookies when -they're closed down. - -See also \fI-b, --cookie\fP and \fI-c, --cookie-jar\fP. -.IP "--keepalive-time <seconds>" -This option sets the time a connection needs to remain idle before sending -keepalive probes and the time between individual keepalive probes. It is -currently effective on operating systems offering the TCP_KEEPIDLE and -TCP_KEEPINTVL socket options (meaning Linux, recent AIX, HP-UX and more). This -option has no effect if \fI--no-keepalive\fP is used. - -If this option is used several times, the last one will be used. If -unspecified, the option defaults to 60 seconds. - -Added in 7.18.0. -.IP "--key-type <type>" -(TLS) Private key file type. Specify which type your \fI--key\fP provided private key -is. DER, PEM, and ENG are supported. If not specified, PEM is assumed. - -If this option is used several times, the last one will be used. -.IP "--key <key>" -(TLS SSH) Private key file name. Allows you to provide your private key in this separate -file. For SSH, if not specified, curl tries the following candidates in order: -'~/.ssh/id_rsa', '~/.ssh/id_dsa', './id_rsa', './id_dsa'. - -If this option is used several times, the last one will be used. -.IP "--krb <level>" -(FTP) Enable Kerberos authentication and use. The level must be entered and should -be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a -level that is not one of these, 'private' will instead be used. - -If this option is used several times, the last one will be used. - -\fI--krb\fP requires that the underlying libcurl was built to support Kerberos. -.IP "--libcurl <file>" -Append this option to any ordinary curl command line, and you will get a -libcurl-using C source code written to the file that does the equivalent -of what your command-line operation does! - -If this option is used several times, the last given file name will be -used. - -Added in 7.16.1. -.IP "--limit-rate <speed>" -Specify the maximum transfer rate you want curl to use - for both downloads -and uploads. This feature is useful if you have a limited pipe and you'd like -your transfer not to use your entire bandwidth. To make it slower than it -otherwise would be. - -The given speed is measured in bytes/second, unless a suffix is appended. -Appending 'k' or 'K' will count the number as kilobytes, 'm' or M' makes it -megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G. - -If you also use the \fI-Y, --speed-limit\fP option, that option will take precedence and -might cripple the rate-limiting slightly, to help keeping the speed-limit -logic working. - -If this option is used several times, the last one will be used. -.IP "-l, --list-only" -(FTP POP3) (FTP) -When listing an FTP directory, this switch forces a name-only view. This is -especially useful if the user wants to machine-parse the contents of an FTP -directory since the normal directory view doesn't use a standard look or -format. When used like this, the option causes a NLST command to be sent to -the server instead of LIST. - -Note: Some FTP servers list only files in their response to NLST; they do not -include sub-directories and symbolic links. - -(POP3) -When retrieving a specific email from POP3, this switch forces a LIST command -to be performed instead of RETR. This is particularly useful if the user wants -to see if a specific message id exists on the server and what size it is. - -Note: When combined with \fI-X, --request\fP, this option can be used to send an UIDL -command instead, so the user may use the email's unique identifier rather than -it's message id to make the request. - -Added in 7.21.5. -.IP "--local-port <num/range>" -Set a preferred single number or range (FROM-TO) of local port numbers to use -for the connection(s). Note that port numbers by nature are a scarce resource -that will be busy at times so setting this range to something too narrow might -cause unnecessary connection setup failures. - -Added in 7.15.2. -.IP "--location-trusted" -(HTTP) Like \fI-L, --location\fP, but will allow sending the name + password to all hosts that -the site may redirect to. This may or may not introduce a security breach if -the site redirects you to a site to which you'll send your authentication info -(which is plaintext in the case of HTTP Basic authentication). - -See also \fI-u, --user\fP. -.IP "-L, --location" -(HTTP) If the server reports that the requested page has moved to a different -location (indicated with a Location: header and a 3XX response code), this -option will make curl redo the request on the new place. If used together with -\fI-i, --include\fP or \fI-I, --head\fP, headers from all requested pages will be shown. When -authentication is used, curl only sends its credentials to the initial -host. If a redirect takes curl to a different host, it won't be able to -intercept the user+password. See also \fI--location-trusted\fP on how to change -this. You can limit the amount of redirects to follow by using the -\fI--max-redirs\fP option. - -When curl follows a redirect and the request is not a plain GET (for example -POST or PUT), it will do the following request with a GET if the HTTP response -was 301, 302, or 303. If the response code was any other 3xx code, curl will -re-send the following request using the same unmodified method. - -You can tell curl to not change the non-GET request method to GET after a 30x -response by using the dedicated options for that: \fI--post301\fP, \fI--post302\fP and -\fI--post303\fP. -.IP "--login-options <options>" -(IMAP POP3 SMTP) Specify the login options to use during server authentication. - -You can use the login options to specify protocol specific options that may -be used during authentication. At present only IMAP, POP3 and SMTP support -login options. For more information about the login options please see -RFC 2384, RFC 5092 and IETF draft draft-earhart-url-smtp-00.txt - -If this option is used several times, the last one will be used. - -Added in 7.34.0. -.IP "--mail-auth <address>" -(SMTP) Specify a single address. This will be used to specify the authentication -address (identity) of a submitted message that is being relayed to another -server. - -See also \fI--mail-rcpt\fP and \fI--mail-from\fP. Added in 7.25.0. -.IP "--mail-from <address>" -(SMTP) Specify a single address that the given mail should get sent from. - -See also \fI--mail-rcpt\fP and \fI--mail-auth\fP. Added in 7.20.0. -.IP "--mail-rcpt <address>" -(SMTP) Specify a single address, user name or mailing list name. Repeat this -option several times to send to multiple recipients. - -When performing a mail transfer, the recipient should specify a valid email -address to send the mail to. - -When performing an address verification (VRFY command), the recipient should be -specified as the user name or user name and domain (as per Section 3.5 of -RFC5321). (Added in 7.34.0) - -When performing a mailing list expand (EXPN command), the recipient should be -specified using the mailing list name, such as "Friends" or "London-Office". -(Added in 7.34.0) - -Added in 7.20.0. -.IP "-M, --manual" -Manual. Display the huge help text. -.IP "--max-filesize <bytes>" -Specify the maximum size (in bytes) of a file to download. If the file -requested is larger than this value, the transfer will not start and curl will -return with exit code 63. - -\fBNOTE:\fP The file size is not always known prior to download, and for such -files this option has no effect even if the file transfer ends up being larger -than this given limit. This concerns both FTP and HTTP transfers. - -See also \fI--limit-rate\fP. -.IP "--max-redirs <num>" -(HTTP) Set maximum number of redirection-followings allowed. When \fI-L, --location\fP is used, -is used to prevent curl from following redirections \&"in absurdum". By -default, the limit is set to 50 redirections. Set this option to -1 to make it -unlimited. - -If this option is used several times, the last one will be used. -.IP "-m, --max-time <time>" -Maximum time in seconds that you allow the whole operation 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. - -If this option is used several times, the last one will be used. - -See also \fI--connect-timeout\fP. -.IP "--metalink" -This option can tell curl to parse and process a given URI as Metalink file -(both version 3 and 4 (RFC 5854) are supported) and make use of the mirrors -listed within for failover if there are errors (such as the file or server not -being available). It will also verify the hash of the file after the download -completes. The Metalink file itself is downloaded and processed in memory and -not stored in the local file system. - -Example to use a remote Metalink file: - - curl --metalink http://www.example.com/example.metalink - -To use a Metalink file in the local file system, use FILE protocol (file://): - - curl --metalink file://example.metalink - -Please note that if FILE protocol is disabled, there is no way to use a local -Metalink file at the time of this writing. Also note that if \fI--metalink\fP and -\fI-i, --include\fP are used together, --include will be ignored. This is because -including headers in the response will break Metalink parser and if the -headers are included in the file described in Metalink file, hash check will -fail. - - -\fI--metalink\fP requires that the underlying libcurl was built to support metalink. Added in 7.27.0. -.IP "--negotiate" -(HTTP) Enables Negotiate (SPNEGO) authentication. - -This option requires a library built with GSS-API or SSPI support. Use -\fI-V, --version\fP to see if your curl supports GSS-API/SSPI or SPNEGO. - -When using this option, you must also provide a fake \fI-u, --user\fP option to activate -the authentication code properly. Sending a '-u :' is enough as the user name -and password from the \fI-u, --user\fP option aren't actually used. - -If this option is used several times, only the first one is used. - -See also \fI--basic\fP and \fI--ntlm\fP and \fI--anyauth\fP and \fI--proxy-negotiate\fP. -.IP "--netrc-file <filemame>" -This option is similar to \fI-n, --netrc\fP, except that you provide the path (absolute -or relative) to the netrc file that Curl should use. You can only specify one -netrc file per invocation. If several \fI--netrc-file\fP options are provided, -the last one will be used. - -It will abide by \fI--netrc-optional\fP if specified. - -This option overrides \fI-n, --netrc\fP. Added in 7.21.5. -.IP "--netrc-optional" -Very similar to \fI-n, --netrc\fP, but this option makes the .netrc usage \fBoptional\fP -and not mandatory as the \fI-n, --netrc\fP option does. - -See also \fI--netrc-file\fP. This option overrides \fI-n, --netrc\fP. -.IP "-n, --netrc" -Makes curl scan the \fI.netrc\fP (\fI_netrc\fP on Windows) file in the user's -home directory for login name and password. This is typically used for FTP on -Unix. If used with HTTP, curl will enable user authentication. See -\fInetrc(5)\fP \fIftp(1)\fP for details on the file format. Curl will not -complain if that file doesn't have the right permissions (it should not be -either world- or group-readable). The environment variable "HOME" is used to -find the home directory. - -A quick and very simple example of how to setup a \fI.netrc\fP to allow curl -to FTP to the machine host.domain.com with user name \&'myself' and password -\&'secret' should look similar to: - -.B "machine host.domain.com login myself password secret" -.IP "-:, --next" -Tells curl to use a separate operation for the following URL and associated -options. This allows you to send several URL requests, each with their own -specific options, for example, such as different user names or custom requests -for each. - -\fI-:, --next\fP will reset all local options and only global ones will have their -values survive over to the operation following the \fI-:, --next\fP instruction. Global -options include \fI-v, --verbose\fP, \fI--trace\fP, \fI--trace-ascii\fP and \fI--fail-early\fP. - -For example, you can do both a GET and a POST in a single command line: - - curl www1.example.com --next -d postthis www2.example.com - -Added in 7.36.0. -.IP "--no-alpn" -(HTTPS) Disable the ALPN TLS extension. ALPN is enabled by default if libcurl was built -with an SSL library that supports ALPN. ALPN is used by a libcurl that supports -HTTP/2 to negotiate HTTP/2 support with the server during https sessions. - -See also \fI--no-npn\fP and \fI--http2\fP. \fI--no-alpn\fP requires that the underlying libcurl was built to support TLS. Added in 7.36.0. -.IP "-N, --no-buffer" -Disables the buffering of the output stream. In normal work situations, curl -will use a standard buffered output stream that will have the effect that it -will output the data in chunks, not necessarily exactly when the data arrives. -Using this option will disable that buffering. - -Note that this is the negated option name documented. You can thus use ---buffer to enforce the buffering. -.IP "--no-keepalive" -Disables the use of keepalive messages on the TCP connection. curl otherwis -enables them by default. - -Note that this is the negated option name documented. You can thus use ---keepalive to enforce keepalive. -.IP "--no-npn" -(HTTPS) 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 -HTTP/2 to negotiate HTTP/2 support with the server during https sessions. - -See also \fI--no-alpn\fP and \fI--http2\fP. \fI--no-npn\fP requires that the underlying libcurl was built to support TLS. Added in 7.36.0. -.IP "--no-sessionid" -(TLS) Disable curl's use of SSL session-ID caching. By default all transfers are -done using the cache. Note that while nothing should ever get hurt by -attempting to reuse SSL session-IDs, there seem to be broken SSL -implementations in the wild that may require you to disable this in order for -you to succeed. - -Note that this is the negated option name documented. You can thus use ---sessionid to enforce session-ID caching. - -Added in 7.16.0. -.IP "--noproxy <no-proxy-list>" -Comma-separated list of hosts which do not use a proxy, if one is specified. -The only wildcard is a single * character, which matches all hosts, and -effectively disables the proxy. Each name in this list is matched as either -a domain which contains the hostname, or the hostname itself. For 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. If there's an environment variable disabling a proxy, you can set -noproxy list to \&"" to override it. - -Added in 7.19.4. -.IP "--ntlm-wb" -(HTTP) Enables NTLM much in the style \fI--ntlm\fP does, but hand over the authentication -to the separate binary ntlmauth application that is executed when needed. - -See also \fI--ntlm\fP and \fI--proxy-ntlm\fP. -.IP "--ntlm" -(HTTP) Enables NTLM authentication. The NTLM authentication method was designed by -Microsoft and is used by IIS web servers. It is a proprietary protocol, -reverse-engineered by clever people and implemented in curl based on their -efforts. This kind of behavior should not be endorsed, you should encourage -everyone who uses NTLM to switch to a public and documented authentication -method instead, such as Digest. - -If you want to enable NTLM for your proxy authentication, then use -\fI--proxy-ntlm\fP. - -If this option is used several times, only the first one is used. - -See also \fI--proxy-ntlm\fP. \fI--ntlm\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI--basic\fP and \fI--negotiated\fP and \fI--digest\fP and \fI--anyauth\fP. -.IP "--oauth2-bearer" -(IMAP POP3 SMTP) Specify the Bearer Token for OAUTH 2.0 server authentication. The Bearer Token -is used in conjunction with the user name which can be specified as part of -the \fI--url\fP or \fI-u, --user\fP options. - -The Bearer Token and user name are formatted according to RFC 6750. - -If this option is used several times, the last one will be used. -.IP "-o, --output <file>" -Write output to <file> instead of stdout. If you are using {} or [] to fetch -multiple documents, you can use '#' followed by a number in the <file> -specifier. That variable will be replaced with the current string for the URL -being fetched. Like in: - - curl http://{one,two}.example.com -o "file_#1.txt" - -or use several variables like: - - curl http://{site,host}.host[1-5].com -o "#1_#2" - -You may use this option as many times as the number of URLs you have. For -example, if you specify two URLs on the same command line, you can use it like -this: - - curl -o aa example.com -o bb example.net - -and the order of the -o options and the URLs doesn't matter, just that the -first -o is for the first URL and so on, so the above command line can also be -written as - - curl example.com example.net -o aa -o bb - -See also the \fI--create-dirs\fP option to create the local directories -dynamically. Specifying the output as '-' (a single dash) will force the -output to be done to stdout. - -See also \fI-O, --remote-name\fP and \fI--remote-name-all\fP and \fI-J, --remote-header-name\fP. -.IP "--pass <phrase>" -(SSH TLS) Passphrase for the private key - -If this option is used several times, the last one will be used. -.IP "--path-as-is" -Tell curl to not handle sequences of /../ or /./ in the given URL -path. Normally curl will squash or merge them according to standards but with -this option set you tell it not to do that. - -Added in 7.42.0. -.IP "--pinnedpubkey <hashes>" -(TLS) Tells curl to use the specified public key file (or hashes) to verify the -peer. This can be a path to a file which contains a single public key in PEM -or DER format, or any number of base64 encoded sha256 hashes preceded by -\'sha256//\' and separated by \';\' - -When negotiating a TLS or SSL connection, the server sends a certificate -indicating its identity. A public key is extracted from this certificate and -if it does not exactly match the public key provided to this option, curl will -abort the connection before sending or receiving any data. - -PEM/DER support: - 7.39.0: OpenSSL, GnuTLS and GSKit - 7.43.0: NSS and wolfSSL/CyaSSL - 7.47.0: mbedtls - 7.49.0: PolarSSL -sha256 support: - 7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL/CyaSSL. - 7.47.0: mbedtls - 7.49.0: PolarSSL -Other SSL backends not supported. - -If this option is used several times, the last one will be used. -.IP "--post301" -(HTTP) Tells curl to respect RFC 7231/6.4.2 and not convert POST requests into GET -requests when following a 301 redirection. The non-RFC behaviour is ubiquitous -in web browsers, so curl does the conversion by default to maintain -consistency. However, a server may require a POST to remain a POST after such -a redirection. This option is meaningful only when using \fI-L, --location\fP. - -See also \fI--post302\fP and \fI--post303\fP and \fI-L, --location\fP. Added in 7.17.1. -.IP "--post302" -(HTTP) Tells curl to respect RFC 7231/6.4.3 and not convert POST requests into GET -requests when following a 302 redirection. The non-RFC behaviour is ubiquitous -in web browsers, so curl does the conversion by default to maintain -consistency. However, a server may require a POST to remain a POST after such -a redirection. This option is meaningful only when using \fI-L, --location\fP. - -See also \fI--post301\fP and \fI--post303\fP and \fI-L, --location\fP. Added in 7.19.1. -.IP "--post303" -(HTTP) Tells curl to respect RFC 7231/6.4.4 and not convert POST requests into GET -requests when following a 303 redirection. The non-RFC behaviour is ubiquitous -in web browsers, so curl does the conversion by default to maintain -consistency. However, a server may require a POST to remain a POST after such -a redirection. This option is meaningful only when using \fI-L, --location\fP. - -See also \fI--post302\fP and \fI--post301\fP and \fI-L, --location\fP. Added in 7.26.0. -.IP "--preproxy [protocol://]host[:port]" -Use the specified proxy before connecting to the ordinary proxy. Hence pre -proxy. A pre proxy must be a SOCKS speaking proxy. - -The pre proxy string should be specified with a protocol:// prefix to specify -alternative proxy protocols. Use socks4://, socks4a://, socks5:// or -socks5h:// to request the specific SOCKS version to be used. No protocol -specified will make curl default to SOCKS4. - -If the port number is not specified in the proxy string, it is assumed to be -1080. - -User and password that might be provided in the proxy string are URL decoded -by curl. This allows you to pass in special characters such as @ by using %40 -or pass in a colon with %3a. - -If this option is used several times, the last one will be used. - -Added in 7.52.0. -.IP "-#, --progress-bar" -Make curl display transfer progress as a simple progress bar instead of the -standard, more informational, meter. - -This progress bar draws a single line of '#' characters across the screen and -shows a percentage if the transfer size is known. For transfers without a -known size, it will instead output one '#' character for every 1024 bytes -transferred. -.IP "--proto-default <protocol>" -Tells curl to use \fIprotocol\fP for any URL missing a scheme name. - -Example: - - curl --proto-default https ftp.mozilla.org - -An unknown or unsupported protocol causes error -\fICURLE_UNSUPPORTED_PROTOCOL\fP (1). - -This option does not change the default proxy protocol (http). - -Without this option curl would make a guess based on the host, see \fI--url\fP for -details. - -Added in 7.45.0. -.IP "--proto-redir <protocols>" -Tells curl to limit what protocols it may use on redirect. Protocols denied by -\fI--proto\fP are not overridden by this option. See --proto for how protocols are -represented. - -Example, allow only HTTP and HTTPS on redirect: - - curl --proto-redir -all,http,https http://example.com - -By default curl will allow all protocols on redirect except several disabled -for security reasons: Since 7.19.4 FILE and SCP are disabled, and since 7.40.0 -SMB and SMBS are also disabled. Specifying \fIall\fP or \fI+all\fP enables all -protocols on redirect, including those disabled for security. - -Added in 7.20.2. -.IP "--proto <protocols>" -Tells curl to limit what protocols it may use in the transfer. Protocols are -evaluated left to right, are comma separated, and are each a protocol name or -'all', optionally prefixed by zero or more modifiers. Available modifiers are: -.RS -.TP 3 -.B + -Permit this protocol in addition to protocols already permitted (this is -the default if no modifier is used). -.TP -.B - -Deny this protocol, removing it from the list of protocols already permitted. -.TP -.B = -Permit only this protocol (ignoring the list already permitted), though -subject to later modification by subsequent entries in the comma separated -list. -.RE -.IP -For example: -.RS -.TP 15 -.B \fI--proto\fP -ftps -uses the default protocols, but disables ftps -.TP -.B \fI--proto\fP -all,https,+http -only enables http and https -.TP -.B \fI--proto\fP =http,https -also only enables http and https -.RE - -Unknown protocols produce a warning. This allows scripts to safely rely on -being able to disable potentially dangerous protocols, without relying upon -support for that protocol being built into curl to avoid an error. - -This option can be used multiple times, in which case the effect is the same -as concatenating the protocols into one instance of the option. - -See also \fI--proto-redir\fP and \fI--proto-default\fP. Added in 7.20.2. -.IP "--proxy-anyauth" -Tells curl to pick a suitable authentication method when communicating with -the given HTTP proxy. This might cause an extra request/response round-trip. - -See also \fI-x, --proxy\fP and \fI--proxy-basic\fP and \fI--proxy-digest\fP. Added in 7.13.2. -.IP "--proxy-basic" -Tells curl to use HTTP Basic authentication when communicating with the given -proxy. Use \fI--basic\fP for enabling HTTP Basic with a remote host. Basic is the -default authentication method curl uses with proxies. - -See also \fI-x, --proxy\fP and \fI--proxy-anyauth\fP and \fI--proxy-digest\fP. -.IP "--proxy-cacert <file>" -Same as \fI--cacert\fP but used in HTTPS proxy context. - -See also \fI--proxy-capath\fP and \fI--cacert\fP and \fI--capath\fP and \fI-x, --proxy\fP. Added in 7.52.0. -.IP "--proxy-capath <dir>" -Same as \fI--capath\fP but used in HTTPS proxy context. - -See also \fI--proxy-cacert\fP and \fI-x, --proxy\fP and \fI--capath\fP. Added in 7.52.0. -.IP "--proxy-cert-type <type>" -Same as \fI--cert-type\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-cert <cert[:passwd]>" -Same as \fI-E, --cert\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-ciphers <list>" -Same as \fI--ciphers\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-crlfile <file>" -Same as \fI--crlfile\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-digest" -Tells curl to use HTTP Digest authentication when communicating with the given -proxy. Use \fI--digest\fP for enabling HTTP Digest with a remote host. - -See also \fI-x, --proxy\fP and \fI--proxy-anyauth\fP and \fI--proxy-basic\fP. -.IP "--proxy-header <header>" -(HTTP) Extra header to include in the request when sending HTTP to a proxy. You may -specify any number of extra headers. This is the equivalent option to \fI-H, --header\fP -but is for proxy communication only like in CONNECT requests when you want a -separate header sent to the proxy to what is sent to the actual remote host. - -curl will make sure that each header you add/replace is sent with the proper -end-of-line marker, you should thus \fBnot\fP add that as a part of the header -content: do not add newlines or carriage returns, they will only mess things -up for you. - -Headers specified with this option will not be included in requests that curl -knows will not be sent to a proxy. - -This option can be used multiple times to add/replace/remove multiple headers. - -Added in 7.37.0. -.IP "--proxy-insecure" -Same as \fI-k, --insecure\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-key-type <type>" -Same as \fI--key-type\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-key <key>" -Same as \fI--key\fP but used in HTTPS proxy context. -.IP "--proxy-negotiate" -Tells curl to use HTTP Negotiate (SPNEGO) authentication when communicating -with the given proxy. Use \fI--negotiate\fP for enabling HTTP Negotiate (SPNEGO) -with a remote host. - -See also \fI--proxy-anyauth\fP and \fI--proxy-basic\fP. Added in 7.17.1. -.IP "--proxy-ntlm" -Tells curl to use HTTP NTLM authentication when communicating with the given -proxy. Use \fI--ntlm\fP for enabling NTLM with a remote host. - -See also \fI--proxy-negotiate\fP and \fI--proxy-anyauth\fP. -.IP "--proxy-pass <phrase>" -Same as \fI--pass\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-service-name <name>" -This option allows you to change the service name for proxy negotiation. - -Added in 7.43.0. -.IP "--proxy-ssl-allow-beast" -Same as \fI--ssl-allow-beast\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-tlsauthtype <type>" -Same as \fI--tlsauthtype\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-tlspassword <string>" -Same as \fI--tlspassword\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-tlsuser <name>" -Same as \fI--tlsuser\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "--proxy-tlsv1" -Same as \fI-1, --tlsv1\fP but used in HTTPS proxy context. - -Added in 7.52.0. -.IP "-U, --proxy-user <user:password>" -Specify the user name and password to use for proxy authentication. - -If you use a Windows SSPI-enabled curl binary and do either Negotiate or NTLM -authentication then you can tell curl to select the user name and password -from your environment by specifying a single colon with this option: "-U :". - -If this option is used several times, the last one will be used. -.IP "-x, --proxy [protocol://]host[:port]" -Use the specified proxy. - -The proxy string can be specified with a protocol:// prefix to specify -alternative proxy protocols. Use socks4://, socks4a://, socks5:// or -socks5h:// to request the specific SOCKS version to be used. No protocol -specified, http:// and all others will be treated as HTTP proxies. (The -protocol support was added in curl 7.21.7) - -If the port number is not specified in the proxy string, it is assumed to be -1080. - -This option overrides existing environment variables that set the proxy to -use. If there's an environment variable setting a proxy, you can set proxy to -\&"" to override it. - -All operations that are performed over an HTTP proxy will transparently be -converted to HTTP. It means that certain protocol specific operations might -not be available. This is not the case if you can tunnel through the proxy, as -one with the \fI-p, --proxytunnel\fP option. - -User and password that might be provided in the proxy string are URL decoded -by curl. This allows you to pass in special characters such as @ by using %40 -or pass in a colon with %3a. - -The proxy host can be specified the exact same way as the proxy environment -variables, including the protocol prefix (http://) and the embedded user + -password. - -If this option is used several times, the last one will be used. -.IP "--proxy1.0 <host[:port]>" -Use the specified HTTP 1.0 proxy. If the port number is not specified, it is -assumed at port 1080. - -The only difference between this and the HTTP proxy option \fI-x, --proxy\fP, is that -attempts to use CONNECT through the proxy will specify an HTTP 1.0 protocol -instead of the default HTTP 1.1. -.IP "-p, --proxytunnel" -When an HTTP proxy is used \fI-x, --proxy\fP, this option will cause non-HTTP protocols -to attempt to tunnel through the proxy instead of merely using it to do -HTTP-like operations. The tunnel approach is made with the HTTP proxy CONNECT -request and requires that the proxy allows direct connect to the remote port -number curl wants to tunnel through to. - -See also \fI-x, --proxy\fP. -.IP "--pubkey <key>" -(SFTP SCP) Public key file name. Allows you to provide your public key in this separate -file. - -If this option is used several times, the last one will be used. - -(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.) -.IP "-Q, --quote" -(FTP SFTP) -Send an arbitrary command to the remote FTP or SFTP server. Quote commands are -sent BEFORE the transfer takes place (just after the initial PWD command in an -FTP transfer, to be exact). To make commands take place after a successful -transfer, prefix them with a dash '-'. To make commands be sent after curl -has changed the working directory, just before the transfer command(s), prefix -the command with a '+' (this is only supported for FTP). You may specify any -number of commands. - -If the server returns failure for one of the commands, the entire operation -will be aborted. You must send syntactically correct FTP commands as RFC 959 -defines to FTP servers, or one of the commands listed below to SFTP servers. - -This option can be used multiple times. When speaking to an FTP server, prefix -the command with an asterisk (*) to make curl continue even if the command -fails as by default curl will stop at first failure. - -SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands -itself before sending them to the server. File names may be quoted -shell-style to embed spaces or special characters. Following is the list of -all supported SFTP quote commands: -.RS -.IP "chgrp group file" -The chgrp command sets the group ID of the file named by the file operand to -the group ID specified by the group operand. The group operand is a decimal -integer group ID. -.IP "chmod mode file" -The chmod command modifies the file mode bits of the specified file. The -mode operand is an octal integer mode number. -.IP "chown user file" -The chown command sets the owner of the file named by the file operand to the -user ID specified by the user operand. The user operand is a decimal -integer user ID. -.IP "ln source_file target_file" -The ln and symlink commands create a symbolic link at the target_file location -pointing to the source_file location. -.IP "mkdir directory_name" -The mkdir command creates the directory named by the directory_name operand. -.IP "pwd" -The pwd command returns the absolute pathname of the current working directory. -.IP "rename source target" -The rename command renames the file or directory named by the source -operand to the destination path named by the target operand. -.IP "rm file" -The rm command removes the file specified by the file operand. -.IP "rmdir directory" -The rmdir command removes the directory entry specified by the directory -operand, provided it is empty. -.IP "symlink source_file target_file" -See ln. -.RE -.IP "--random-file <file>" -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. See -also the \fI--egd-file\fP option. -.IP "-r, --range <range>" -(HTTP FTP SFTP FILE) Retrieve a byte range (i.e a partial document) from a HTTP/1.1, FTP or SFTP -server or a local FILE. Ranges can be specified in a number of ways. -.RS -.TP 10 -.B 0-499 -specifies the first 500 bytes -.TP -.B 500-999 -specifies the second 500 bytes -.TP -.B -500 -specifies the last 500 bytes -.TP -.B 9500- -specifies the bytes from offset 9500 and forward -.TP -.B 0-0,-1 -specifies the first and last byte only(*)(HTTP) -.TP -.B 100-199,500-599 -specifies two separate 100-byte ranges(*) (HTTP) -.RE -.IP -(*) = NOTE that this will cause the server to reply with a multipart -response! - -Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the -\&'start-stop' range syntax. If a non-digit character is given in the range, -the server's response will be unspecified, depending on the server's -configuration. - -You should also be aware that many HTTP/1.1 servers do not have this feature -enabled, so that when you attempt to get a range, you'll instead get the whole -document. - -FTP and SFTP range downloads only support the simple 'start-stop' syntax -(optionally with one of the numbers omitted). FTP use depends on the extended -FTP command SIZE. - -If this option is used several times, the last one will be used. -.IP "--raw" -(HTTP) When used, it disables all internal HTTP decoding of content or transfer -encodings and instead makes them passed on unaltered, raw. - -Added in 7.16.2. -.IP "-e, --referer <URL>" -(HTTP) Sends the "Referrer Page" information to the HTTP server. This can also be set -with the \fI-H, --header\fP flag of course. When used with \fI-L, --location\fP you can append -";auto" to the \fI-e, --referer\fP URL to make curl automatically set the previous URL -when it follows a Location: header. The \&";auto" string can be used alone, -even if you don't set an initial \fI-e, --referer\fP. - -If this option is used several times, the last one will be used. - -See also \fI-A, --user-agent\fP and \fI-H, --header\fP. -.IP "-J, --remote-header-name" -(HTTP) This option tells the \fI-O, --remote-name\fP option to use the server-specified -Content-Disposition filename instead of extracting a filename from the URL. - -If the server specifies a file name and a file with that name already exists -in the current working directory it will not be overwritten and an error will -occur. If the server doesn't specify a file name then this option has no -effect. - -There's no attempt to decode %-sequences (yet) in the provided file name, so -this option may provide you with rather unexpected file names. - -\fBWARNING\fP: Exercise judicious use of this option, especially on Windows. A -rogue server could send you the name of a DLL or other file that could possibly -be loaded automatically by Windows or some third party software. -.IP "--remote-name-all" -This option changes the default action for all given URLs to be dealt with as -if \fI-O, --remote-name\fP were used for each one. So if you want to disable that for a -specific URL after \fI--remote-name-all\fP has been used, you must use "-o -" or ---no-remote-name. - -Added in 7.19.0. -.IP "-O, --remote-name" -Write output to a local file named like the remote file we get. (Only the file -part of the remote file is used, the path is cut off.) - -The file will be saved in the current working directory. If you want the file -saved in a different directory, make sure you change the current working -directory before invoking curl with this option. - -The remote file name to use for saving is extracted from the given URL, -nothing else, and if it already exists it will be overwritten. If you want the -server to be able to choose the file name refer to \fI-J, --remote-header-name\fP which -can be used in addition to this option. If the server chooses a file name and -that name already exists it will not be overwritten. - -There is no URL decoding done on the file name. If it has %20 or other URL -encoded parts of the name, they will end up as-is as file name. - -You may use this option as many times as the number of URLs you have. -.IP "-R, --remote-time" -When used, this will make curl attempt to figure out the timestamp of the -remote file, and if that is available make the local file get that same -timestamp. -.IP "-X, --request <command>" -(HTTP) Specifies a custom request method to use when communicating with the -HTTP server. The specified request method will be used instead of the method -otherwise used (which defaults to GET). Read the HTTP 1.1 specification for -details and explanations. Common additional HTTP requests include PUT and -DELETE, but related technologies like WebDAV offers PROPFIND, COPY, MOVE and -more. - -Normally you don't need this option. All sorts of GET, HEAD, POST and PUT -requests are rather invoked by using dedicated command line options. - -This option only changes the actual word used in the HTTP request, it does not -alter the way curl behaves. So for example if you want to make a proper HEAD -request, using -X HEAD will not suffice. You need to use the \fI-I, --head\fP option. - -The method string you set with \fI-X, --request\fP will be used for all requests, which -if you for example use \fI-L, --location\fP may cause unintended side-effects when curl -doesn't change request method according to the HTTP 30x response codes - and -similar. - -(FTP) -Specifies a custom FTP command to use instead of LIST when doing file lists -with FTP. - -(POP3) -Specifies a custom POP3 command to use instead of LIST or RETR. (Added in -7.26.0) - -(IMAP) -Specifies a custom IMAP command to use instead of LIST. (Added in 7.30.0) - -(SMTP) -Specifies a custom SMTP command to use instead of HELP or VRFY. (Added in 7.34.0) - -If this option is used several times, the last one will be used. -.IP "--resolve <host:port:address>" -Provide a custom address for a specific host and port pair. Using this, you -can make the curl requests(s) use a specified address and prevent the -otherwise normally resolved address to be used. Consider it a sort of -/etc/hosts alternative provided on the command line. The port number should be -the number used for the specific protocol the host will be used for. It means -you need several entries if you want to provide address for the same host but -different ports. - -The provided address set by this option will be used even if \fI-4, --ipv4\fP or \fI-6, --ipv6\fP -is set to make curl use another IP version. - -This option can be used many times to add many host names to resolve. - -Added in 7.21.3. -.IP "--retry-connrefused" -In addition to the other conditions, consider ECONNREFUSED as a transient -error too for \fI--retry\fP. This option is used together with --retry. - -Added in 7.52.0. -.IP "--retry-delay <seconds>" -Make curl sleep this amount of time before each retry when a transfer has -failed with a transient error (it changes the default backoff time algorithm -between retries). This option is only interesting if \fI--retry\fP is also -used. Setting this delay to zero will make curl use the default backoff time. - -If this option is used several times, the last one will be used. - -Added in 7.12.3. -.IP "--retry-max-time <seconds>" -The retry timer is reset before the first transfer attempt. Retries will be -done as usual (see \fI--retry\fP) as long as the timer hasn't reached this given -limit. Notice that if the timer hasn't reached the limit, the request will be -made and while performing, it may take longer than this given time period. To -limit a single request\'s maximum time, use \fI-m, --max-time\fP. Set this option to -zero to not timeout retries. - -If this option is used several times, the last one will be used. - -Added in 7.12.3. -.IP "--retry <num>" -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 -makes curl do no retries (which is the default). Transient error means either: -a timeout, an FTP 4xx response code or an HTTP 5xx 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 \fI--retry-delay\fP you disable this exponential backoff algorithm. See also -\fI--retry-max-time\fP to limit the total time allowed for retries. - -If this option is used several times, the last one will be used. - -Added in 7.12.3. -.IP "--sasl-ir" -Enable initial response in SASL authentication. - -Added in 7.31.0. -.IP "--service-name <name>" -This option allows you to change the service name for SPNEGO. - -Examples: \fI--negotiate\fP \fI--service-name\fP sockd would use sockd/server-name. - -Added in 7.43.0. -.IP "-S, --show-error" -When used with \fI-s, --silent\fP, it makes curl show an error message if it fails. -.IP "-s, --silent" -Silent or quiet mode. Don't show progress meter or error messages. Makes Curl -mute. It will still output the data you ask for, potentially even to the -terminal/stdout unless you redirect it. - -Use \fI-S, --show-error\fP in addition to this option to disable progress meter but -still show error messages. - -See also \fI-v, --verbose\fP and \fI--stderr\fP. -.IP "--socks4 <host[:port]>" -Use the specified SOCKS4 proxy. If the port number is not specified, it is -assumed at port 1080. - -This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually -exclusive. - -Since 7.21.7, this option is superfluous since you can specify a socks4 proxy -with \fI-x, --proxy\fP using a socks4:// protocol prefix. - -If this option is used several times, the last one will be used. - -Added in 7.15.2. -.IP "--socks4a <host[:port]>" -Use the specified SOCKS4a proxy. If the port number is not specified, it is -assumed at port 1080. - -This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually -exclusive. - -Since 7.21.7, this option is superfluous since you can specify a socks4a proxy -with \fI-x, --proxy\fP using a socks4a:// protocol prefix. - -If this option is used several times, the last one will be used. - -Added in 7.18.0. -.IP "--socks5-gssapi-nec" -As part of the GSS-API negotiation a protection mode is negotiated. RFC 1961 -says in section 4.3/4.4 it should be protected, but the NEC reference -implementation does not. The option \fI--socks5-gssapi-nec\fP allows the -unprotected exchange of the protection mode negotiation. - -Added in 7.19.4. -.IP "--socks5-gssapi-service <name>" -The default service name for a socks server is rcmd/server-fqdn. This option -allows you to change it. - -Examples: \fI--socks5\fP proxy-name \fI--socks5-gssapi-service\fP sockd would use -sockd/proxy-name \fI--socks5\fP proxy-name \fI--socks5-gssapi-service\fP sockd/real-name -would use sockd/real-name for cases where the proxy-name does not match the -principal name. - -Added in 7.19.4. -.IP "--socks5-hostname <host[:port]>" -Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If -the port number is not specified, it is assumed at port 1080. - -This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually -exclusive. - -Since 7.21.7, this option is superfluous since you can specify a socks5 -hostname proxy with \fI-x, --proxy\fP using a socks5h:// protocol prefix. - -If this option is used several times, the last one will be used. - -Added in 7.18.0. -.IP "--socks5 <host[:port]>" -Use the specified SOCKS5 proxy - but resolve the host name locally. If the -port number is not specified, it is assumed at port 1080. - -This option overrides any previous use of \fI-x, --proxy\fP, as they are mutually -exclusive. - -Since 7.21.7, this option is superfluous since you can specify a socks5 proxy -with \fI-x, --proxy\fP using a socks5:// protocol prefix. - -If this option is used several times, the last one will be used. - -This option (as well as \fI--socks4\fP) does not work with IPV6, FTPS or LDAP. - -Added in 7.18.0. -.IP "-Y, --speed-limit <speed>" -If a download is slower than this given speed (in bytes per second) for -speed-time seconds it gets aborted. speed-time is set with \fI-y, --speed-time\fP and is -30 if not set. - -If this option is used several times, the last one will be used. -.IP "-y, --speed-time <seconds>" -If a download is slower than speed-limit bytes per second during a speed-time -period, the download gets aborted. If speed-time is used, the default -speed-limit will be 1 unless set with \fI-Y, --speed-limit\fP. - -This option controls transfers and thus will not affect slow connects etc. If -this is a concern for you, try the \fI--connect-timeout\fP option. - -If this option is used several times, the last one will be used. -.IP "--ssl-allow-beast" -This option tells curl to not work around a security flaw in the SSL3 and -TLS1.0 protocols known as BEAST. If this option isn't used, the SSL layer may -use workarounds known to cause interoperability problems with some older SSL -implementations. WARNING: this option loosens the SSL security, and by using -this flag you ask for exactly that. - -Added in 7.25.0. -.IP "--ssl-no-revoke" -(WinSSL) This option tells curl to disable certificate revocation checks. -WARNING: this option loosens the SSL security, and by using this flag you ask -for exactly that. - -Added in 7.44.0. -.IP "--ssl-reqd" -(FTP IMAP POP3 SMTP) Require SSL/TLS for the connection. Terminates the connection if the server -doesn't support SSL/TLS. - -This option was formerly known as --ftp-ssl-reqd. - -Added in 7.20.0. -.IP "--ssl" -(FTP IMAP POP3 SMTP) -Try to use SSL/TLS for the connection. Reverts to a non-secure connection if -the server doesn't support SSL/TLS. See also \fI--ftp-ssl-control\fP and \fI--ssl-reqd\fP -for different levels of encryption required. - -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. - -Added in 7.20.0. -.IP "-2, --sslv2" -(SSL) Forces curl to use SSL version 2 when negotiating with a remote SSL -server. Sometimes curl is built without SSLv2 support. SSLv2 is widely -considered insecure (see RFC 6176). - -See also \fI--http1.1\fP and \fI--http2\fP. \fI-2, --sslv2\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI-3, --sslv3\fP and \fI-1, --tlsv1\fP and \fI--tlsv1.1\fP and \fI--tlsv1.2\fP. -.IP "-3, --sslv3" -(SSL) Forces curl to use SSL version 3 when negotiating with a remote SSL -server. Sometimes curl is built without SSLv3 support. SSLv3 is widely -considered insecure (see RFC 7568). - -See also \fI--http1.1\fP and \fI--http2\fP. \fI-3, --sslv3\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI-2, --sslv2\fP and \fI-1, --tlsv1\fP and \fI--tlsv1.1\fP and \fI--tlsv1.2\fP. -.IP "--stderr" -Redirect all writes to stderr to the specified file instead. If the file name -is a plain '-', it is instead written to stdout. - -If this option is used several times, the last one will be used. - -See also \fI-v, --verbose\fP and \fI-s, --silent\fP. -.IP "--tcp-fastopen" -Enable use of TCP Fast Open (RFC7413). - -Added in 7.49.0. -.IP "--tcp-nodelay" -Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man page for -details about this option. - -Since 7.50.2, curl sets this option by default and you need to explictitly -switch it off if you don't want it on. - -Added in 7.11.2. -.IP "-t, --telnet-option <opt=val>" -Pass options to the telnet protocol. Supported options are: - -TTYPE=<term> Sets the terminal type. - -XDISPLOC=<X display> Sets the X display location. - -NEW_ENV=<var,val> Sets an environment variable. -.IP "--tftp-blksize <value>" -(TFTP) Set TFTP BLKSIZE option (must be >512). This is the block size that curl will -try to use when transferring data to or from a TFTP server. By default 512 -bytes will be used. - -If this option is used several times, the last one will be used. - -Added in 7.20.0. -.IP "--tftp-no-options" -(TFTP) Tells curl not to send TFTP options requests. - -This option improves interop with some legacy servers that do not acknowledge -or properly implement TFTP options. When this option is used \fI--tftp-blksize\fP is -ignored. - -Added in 7.48.0. -.IP "-z, --time-cond <time>" -(HTTP FTP) Request a file that has been modified later than the given time and date, or -one that has been modified before that time. The <date expression> can be all -sorts of date strings or if it doesn't match any internal ones, it is taken as -a filename and tries to get the modification date (mtime) from <file> -instead. See the \fIcurl_getdate(3)\fP man pages for date expression details. - -Start the date expression with a dash (-) to make it request for a document -that is older than the given date/time, default is a document that is newer -than the specified date/time. - -If this option is used several times, the last one will be used. -.IP "--tlsauthtype <type>" -Set TLS authentication type. Currently, the only supported option is "SRP", -for TLS-SRP (RFC 5054). If \fI--tlsuser\fP and \fI--tlspassword\fP are specified but -\fI--tlsauthtype\fP is not, then this option defaults to "SRP". - -Added in 7.21.4. -.IP "--tlspassword" -Set password for use with the TLS authentication method specified with -\fI--tlsauthtype\fP. Requires that \fI--tlsuser\fP also be set. - -Added in 7.21.4. -.IP "--tlsuser <name>" -Set username for use with the TLS authentication method specified with -\fI--tlsauthtype\fP. Requires that \fI--tlspassword\fP also is set. - -Added in 7.21.4. -.IP "--tlsv1.0" -(TLS) Forces curl to use TLS version 1.0 when connecting to a remote TLS server. - -Added in 7.34.0. -.IP "--tlsv1.1" -(TLS) Forces curl to use TLS version 1.1 when connecting to a remote TLS server. - -Added in 7.34.0. -.IP "--tlsv1.2" -(TLS) Forces curl to use TLS version 1.2 when connecting to a remote TLS server. - -Added in 7.34.0. -.IP "--tlsv1.3" -(TLS) Forces curl to use TLS version 1.3 when connecting to a remote TLS server. - -Note that TLS 1.3 is only supported by a subset of TLS backends. At the time -of writing this, those are BoringSSL and NSS only. - -Added in 7.52.0. -.IP "-1, --tlsv1" -(SSL) Tells curl to use TLS version 1.x when negotiating with a remote TLS -server. That means TLS version 1.0, 1.1 or 1.2. - -See also \fI--http1.1\fP and \fI--http2\fP. \fI-1, --tlsv1\fP requires that the underlying libcurl was built to support TLS. This option overrides \fI--tlsv1.1\fP and \fI--tlsv1.2\fP and \fI--tlsv1.3\fP. -.IP "--tr-encoding" -(HTTP) Request a compressed Transfer-Encoding response using one of the algorithms -curl supports, and uncompress the data while receiving it. - -Added in 7.21.6. -.IP "--trace-ascii <file>" -Enables a full trace dump of all incoming and outgoing data, including -descriptive information, to the given output file. Use "-" as filename to have -the output sent to stdout. - -This is very similar to \fI--trace\fP, but leaves out the hex part and only shows -the ASCII part of the dump. It makes smaller output that might be easier to -read for untrained humans. - -If this option is used several times, the last one will be used. - -This option overrides \fI--trace\fP and \fI-v, --verbose\fP. -.IP "--trace-time" -Prepends a time stamp to each trace or verbose line that curl displays. - -Added in 7.14.0. -.IP "--trace <file>" -Enables a full trace dump of all incoming and outgoing data, including -descriptive information, to the given output file. Use "-" as filename to have -the output sent to stdout. Use "%" as filename to have the output sent to -stderr. - -If this option is used several times, the last one will be used. - -This option overrides \fI-v, --verbose\fP and \fI--trace-ascii\fP. -.IP "--unix-socket <path>" -(HTTP) Connect through this Unix domain socket, instead of using the network. - -Added in 7.40.0. -.IP "-T, --upload-file <file>" -This transfers the specified local file to the remote URL. If there is no file -part in the specified URL, curl will append the local file name. NOTE that you -must use a trailing / on the last directory to really prove to Curl that there -is no file name or curl will think that your last directory name is the remote -file name to use. That will most likely cause the upload operation to fail. If -this is used on an HTTP(S) server, the PUT command will be used. - -Use the file name "-" (a single dash) to use stdin instead of a given file. -Alternately, the file name "." (a single period) may be specified instead -of "-" to use stdin in non-blocking mode to allow reading server output -while stdin is being uploaded. - -You can specify one \fI-T, --upload-file\fP for each URL on the command line. Each -\fI-T, --upload-file\fP + URL pair specifies what to upload and to where. curl also -supports "globbing" of the \fI-T, --upload-file\fP argument, meaning that you can upload -multiple files to a single URL by using the same URL globbing style supported -in the URL, like this: - - curl --upload-file "{file1,file2}" http://www.example.com - -or even - - curl -T "img[1-1000].png" ftp://ftp.example.com/upload/ - -When uploading to an SMTP server: the uploaded data is assumed to be RFC 5322 -formatted. It has to feature the necessary set of headers and mail body -formatted correctly by the user as curl will not transcode nor encode it -further in any way. -.IP "--url <url>" -Specify a URL to fetch. This option is mostly handy when you want to specify -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 sub-domain -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 \fI--proto-default\fP for details. - -This option may be used any number of times. To control where this URL is -written, use the \fI-o, --output\fP or the \fI-O, --remote-name\fP options. -.IP "-B, --use-ascii" -(FTP LDAP) Enable ASCII transfer. For FTP, this can also be enforced by using an URL that -ends with ";type=A". This option causes data sent to stdout to be in text mode -for win32 systems. -.IP "-A, --user-agent <name>" -(HTTP) -Specify the User-Agent string to send to the HTTP server. To encode blanks in -the string, surround the string with single quote marks. This can also be set -with the \fI-H, --header\fP option of course. - -If this option is used several times, the last one will be used. -.IP "-u, --user <user:password>" -Specify the user name and password to use for server authentication. Overrides -\fI-n, --netrc\fP and \fI--netrc-optional\fP. - -If you simply specify the user name, curl will prompt for a password. - -The user name and passwords are split up on the first colon, which makes it -impossible to use a colon in the user name with this option. The password can, -still. - -When using Kerberos V5 with a Windows based server you should include the -Windows domain name in the user name, in order for the server to successfully -obtain a Kerberos Ticket. If you don't then the initial authentication -handshake may fail. - -When using NTLM, the user name can be specified simply as the user name, -without the domain, if there is a single domain and forest in your setup -for example. - -To specify the domain name use either Down-Level Logon Name or UPN (User -Principal Name) formats. For example, EXAMPLE\\user and user@example.com -respectively. - -If you use a Windows SSPI-enabled curl binary and perform Kerberos V5, -Negotiate, NTLM or Digest authentication then you can tell curl to select -the user name and password from your environment by specifying a single colon -with this option: "-u :". - -If this option is used several times, the last one will be used. -.IP "-v, --verbose" -Makes curl verbose during the operation. Useful for debugging and seeing -what's going on "under the hood". A line starting with '>' means "header data" -sent by curl, '<' means "header data" received by curl that is hidden in -normal cases, and a line starting with '*' means additional info provided by -curl. - -If you only want HTTP headers in the output, \fI-i, --include\fP might be the option -you're looking for. - -If you think this option still doesn't give you enough details, consider using -\fI--trace\fP or \fI--trace-ascii\fP instead. - -Use \fI-s, --silent\fP to make curl really quiet. - -See also \fI-i, --include\fP. This option overrides \fI--trace\fP and \fI--trace-ascii\fP. -.IP "-V, --version" -Displays information about curl and the libcurl version it uses. - -The first line includes the full version of curl, libcurl and other 3rd party -libraries linked with the executable. - -The second line (starts with "Protocols:") shows all protocols that libcurl -reports to support. - -The third line (starts with "Features:") shows specific features libcurl -reports to offer. Available features include: -.RS -.IP "IPv6" -You can use IPv6 with this. -.IP "krb4" -Krb4 for FTP is supported. -.IP "SSL" -SSL versions of various protocols are supported, such as HTTPS, FTPS, POP3S -and so on. -.IP "libz" -Automatic decompression of compressed files over HTTP is supported. -.IP "NTLM" -NTLM authentication is supported. -.IP "Debug" -This curl uses a libcurl built with Debug. This enables more error-tracking -and memory debugging etc. For curl-developers only! -.IP "AsynchDNS" -This curl uses asynchronous name resolves. Asynchronous name resolves can be -done using either the c-ares or the threaded resolver backends. -.IP "SPNEGO" -SPNEGO authentication is supported. -.IP "Largefile" -This curl supports transfers of large files, files larger than 2GB. -.IP "IDN" -This curl supports IDN - international domain names. -.IP "GSS-API" -GSS-API is supported. -.IP "SSPI" -SSPI is supported. -.IP "TLS-SRP" -SRP (Secure Remote Password) authentication is supported for TLS. -.IP "HTTP2" -HTTP/2 support has been built-in. -.IP "UnixSockets" -Unix sockets support is provided. -.IP "HTTPS-proxy" -This curl is built to support HTTPS proxy. -.IP "Metalink" -This curl supports Metalink (both version 3 and 4 (RFC 5854)), which -describes mirrors and hashes. curl will use mirrors for failover if -there are errors (such as the file or server not being available). -.IP "PSL" -PSL is short for Public Suffix List and means that this curl has been built -with knowledge about "public suffixes". -.RE -.IP "-w, --write-out <format>" -Make curl display information on stdout after a completed transfer. The format -is a string that may contain plain text mixed with any number of -variables. The format can be specified as a literal "string", or you can have -curl read the format from a file with "@filename" and to tell curl to read the -format from stdin you write "@-". - -The variables present in the output format will be substituted by the value or -text that curl thinks fit, as described below. All variables are specified as -%{variable_name} and to output a normal % you just write them as %%. You can -output a newline by using \\n, a carriage return with \\r and a tab space with -\\t. - -.B NOTE: -The %-symbol is a special symbol in the win32-environment, where all -occurrences of % must be doubled when using this option. - -The variables available are: -.RS -.TP 15 -.B content_type -The Content-Type of the requested document, if there was any. -.TP -.B filename_effective -The ultimate filename that curl writes out to. This is only meaningful if curl -is told to write to a file with the \fI-O, --remote-name\fP or \fI-o, --output\fP -option. It's most useful in combination with the \fI-J, --remote-header-name\fP -option. (Added in 7.26.0) -.TP -.B ftp_entry_path -The initial path curl ended up in when logging on to the remote FTP -server. (Added in 7.15.4) -.TP -.B http_code -The numerical response code that was found in the last retrieved HTTP(S) or -FTP(s) transfer. In 7.18.2 the alias \fBresponse_code\fP was added to show the -same info. -.TP -.B http_connect -The numerical code that was found in the last response (from a proxy) to a -curl CONNECT request. (Added in 7.12.4) -.TP -.B http_version -The http version that was effectively used. (Added in 7.50.0) -.TP -.B local_ip -The IP address of the local end of the most recently done connection - can be -either IPv4 or IPv6 (Added in 7.29.0) -.TP -.B local_port -The local port number of the most recently done connection (Added in 7.29.0) -.TP -.B num_connects -Number of new connects made in the recent transfer. (Added in 7.12.3) -.TP -.B num_redirects -Number of redirects that were followed in the request. (Added in 7.12.3) -.TP -.B redirect_url -When an HTTP request was made without -L to follow redirects, this variable -will show the actual URL a redirect \fIwould\fP take you to. (Added in 7.18.2) -.TP -.B remote_ip -The remote IP address of the most recently done connection - can be either -IPv4 or IPv6 (Added in 7.29.0) -.TP -.B remote_port -The remote port number of the most recently done connection (Added in 7.29.0) -.TP -.B scheme -The URL scheme (sometimes called protocol) that was effectively used (Added in 7.52.0) -.TP -.B size_download -The total amount of bytes that were downloaded. -.TP -.B size_header -The total amount of bytes of the downloaded headers. -.TP -.B size_request -The total amount of bytes that were sent in the HTTP request. -.TP -.B size_upload -The total amount of bytes that were uploaded. -.TP -.B speed_download -The average download speed that curl measured for the complete download. Bytes -per second. -.TP -.B speed_upload -The average upload speed that curl measured for the complete upload. Bytes per -second. -.TP -.B ssl_verify_result -The result of the SSL peer certificate verification that was requested. 0 -means the verification was successful. (Added in 7.19.0) -.TP -.B time_appconnect -The time, in seconds, it took from the start until the SSL/SSH/etc -connect/handshake to the remote host was completed. (Added in 7.19.0) -.TP -.B time_connect -The time, in seconds, it took from the start until the TCP connect to the -remote host (or proxy) was completed. -.TP -.B time_namelookup -The time, in seconds, it took from the start until the name resolving was -completed. -.TP -.B time_pretransfer -The time, in seconds, it took from the start until the file transfer was just -about to begin. This includes all pre-transfer commands and negotiations that -are specific to the particular protocol(s) involved. -.TP -.B time_redirect -The time, in seconds, it took for all redirection steps include name lookup, -connect, pretransfer and transfer before the final transaction was -started. time_redirect shows the complete execution time for multiple -redirections. (Added in 7.12.3) -.TP -.B time_starttransfer -The time, in seconds, it took from the start until the first byte was just -about to be transferred. This includes time_pretransfer and also the time the -server needed to calculate the result. -.TP -.B time_total -The total time, in seconds, that the full operation lasted. -.TP -.B url_effective -The URL that was fetched last. This is most meaningful if you've told curl -to follow location: headers. -.RE -.IP -If this option is used several times, the last one will be used. -.IP "--xattr" -When saving output to a file, this option tells curl to store certain file -metadata in extended file attributes. Currently, the URL is stored in the -xdg.origin.url attribute and, for HTTP, the content type is stored in -the mime_type attribute. If the file system does not support extended -attributes, a warning is issued. -.SH FILES -.I ~/.curlrc -.RS -Default config file, see \fI-K, --config\fP for details. -.SH ENVIRONMENT -The environment variables can be specified in lower case or upper case. The -lower case version has precedence. http_proxy is an exception as it is only -available in lower case. - -Using an environment variable to set the proxy has the same effect as using -the \fI-x, --proxy\fP option. - -.IP "http_proxy [protocol://]<host>[:port]" -Sets the proxy server to use for HTTP. -.IP "HTTPS_PROXY [protocol://]<host>[:port]" -Sets the proxy server to use for HTTPS. -.IP "[url-protocol]_PROXY [protocol://]<host>[:port]" -Sets the proxy server to use for [url-protocol], where the protocol is a -protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP, -SMTP, LDAP etc. -.IP "ALL_PROXY [protocol://]<host>[:port]" -Sets the proxy server to use if no protocol-specific proxy is set. -.IP "NO_PROXY <comma-separated list of hosts>" -list of host names that shouldn't go through any proxy. If set to a asterisk -\&'*' only, it matches all hosts. - -Since 7.53.0, this environment variable disable the proxy even if specify -\fI-x, --proxy\fP option. That is -.B NO_PROXY=direct.example.com curl -x http://proxy.example.com -.B http://direct.example.com -accesses the target URL directly, and -.B NO_PROXY=direct.example.com curl -x http://proxy.example.com -.B http://somewhere.example.com -accesses the target URL through proxy. - -.SH "PROXY PROTOCOL PREFIXES" -Since curl version 7.21.7, the proxy string may be specified with a -protocol:// prefix to specify alternative proxy protocols. - -If no protocol is specified in the proxy string or if the string doesn't match -a supported one, the proxy will be treated as an HTTP proxy. - -The supported proxy protocol prefixes are as follows: -.IP "socks4://" -Makes it the equivalent of \fI--socks4\fP -.IP "socks4a://" -Makes it the equivalent of \fI--socks4a\fP -.IP "socks5://" -Makes it the equivalent of \fI--socks5\fP -.IP "socks5h://" -Makes it the equivalent of \fI--socks5-hostname\fP -.SH EXIT CODES -There are a bunch of different error codes and their corresponding error -messages that may appear during bad conditions. At the time of this writing, -the exit codes are: -.IP 1 -Unsupported protocol. This build of curl has no support for this protocol. -.IP 2 -Failed to initialize. -.IP 3 -URL malformed. The syntax was not correct. -.IP 4 -A feature or option that was needed to perform the desired request was not -enabled or was explicitly disabled at build-time. To make curl able to do -this, you probably need another build of libcurl! -.IP 5 -Couldn't resolve proxy. The given proxy host could not be resolved. -.IP 6 -Couldn't resolve host. The given remote host was not resolved. -.IP 7 -Failed to connect to host. -.IP 8 -Weird server reply. The server sent data curl couldn't parse. -.IP 9 -FTP access denied. The server denied login or denied access to the particular -resource or directory you wanted to reach. Most often you tried to change to a -directory that doesn't exist on the server. -.IP 10 -FTP accept failed. While waiting for the server to connect back when an active -FTP session is used, an error code was sent over the control connection or -similar. -.IP 11 -FTP weird PASS reply. Curl couldn't parse the reply sent to the PASS request. -.IP 12 -During an active FTP session while waiting for the server to connect back to -curl, the timeout expired. -.IP 13 -FTP weird PASV reply, Curl couldn't parse the reply sent to the PASV request. -.IP 14 -FTP weird 227 format. Curl couldn't parse the 227-line the server sent. -.IP 15 -FTP can't get host. Couldn't resolve the host IP we got in the 227-line. -.IP 16 -HTTP/2 error. A problem was detected in the HTTP2 framing layer. This is -somewhat generic and can be one out of several problems, see the error message -for details. -.IP 17 -FTP couldn't set binary. Couldn't change transfer method to binary. -.IP 18 -Partial file. Only a part of the file was transferred. -.IP 19 -FTP couldn't download/access the given file, the RETR (or similar) command -failed. -.IP 21 -FTP quote error. A quote command returned error from the server. -.IP 22 -HTTP page not retrieved. The requested url was not found or returned another -error with the HTTP error code being 400 or above. This return code only -appears if \fI-f, --fail\fP is used. -.IP 23 -Write error. Curl couldn't write data to a local filesystem or similar. -.IP 25 -FTP couldn't STOR file. The server denied the STOR operation, used for FTP -uploading. -.IP 26 -Read error. Various reading problems. -.IP 27 -Out of memory. A memory allocation request failed. -.IP 28 -Operation timeout. The specified time-out period was reached according to the -conditions. -.IP 30 -FTP PORT failed. The PORT command failed. Not all FTP servers support the PORT -command, try doing a transfer using PASV instead! -.IP 31 -FTP couldn't use REST. The REST command failed. This command is used for -resumed FTP transfers. -.IP 33 -HTTP range error. The range "command" didn't work. -.IP 34 -HTTP post error. Internal post-request generation error. -.IP 35 -SSL connect error. The SSL handshaking failed. -.IP 36 -Bad download resume. Couldn't continue an earlier aborted download. -.IP 37 -FILE couldn't read file. Failed to open the file. Permissions? -.IP 38 -LDAP cannot bind. LDAP bind operation failed. -.IP 39 -LDAP search failed. -.IP 41 -Function not found. A required LDAP function was not found. -.IP 42 -Aborted by callback. An application told curl to abort the operation. -.IP 43 -Internal error. A function was called with a bad parameter. -.IP 45 -Interface error. A specified outgoing interface could not be used. -.IP 47 -Too many redirects. When following redirects, curl hit the maximum amount. -.IP 48 -Unknown option specified to libcurl. This indicates that you passed a weird -option to curl that was passed on to libcurl and rejected. Read up in the -manual! -.IP 49 -Malformed telnet option. -.IP 51 -The peer's SSL certificate or SSH MD5 fingerprint was not OK. -.IP 52 -The server didn't reply anything, which here is considered an error. -.IP 53 -SSL crypto engine not found. -.IP 54 -Cannot set SSL crypto engine as default. -.IP 55 -Failed sending network data. -.IP 56 -Failure in receiving network data. -.IP 58 -Problem with the local certificate. -.IP 59 -Couldn't use specified SSL cipher. -.IP 60 -Peer certificate cannot be authenticated with known CA certificates. -.IP 61 -Unrecognized transfer encoding. -.IP 62 -Invalid LDAP URL. -.IP 63 -Maximum file size exceeded. -.IP 64 -Requested FTP SSL level failed. -.IP 65 -Sending the data requires a rewind that failed. -.IP 66 -Failed to initialise SSL Engine. -.IP 67 -The user name, password, or similar was not accepted and curl failed to log in. -.IP 68 -File not found on TFTP server. -.IP 69 -Permission problem on TFTP server. -.IP 70 -Out of disk space on TFTP server. -.IP 71 -Illegal TFTP operation. -.IP 72 -Unknown TFTP transfer ID. -.IP 73 -File already exists (TFTP). -.IP 74 -No such user (TFTP). -.IP 75 -Character conversion failed. -.IP 76 -Character conversion functions required. -.IP 77 -Problem with reading the SSL CA cert (path? access rights?). -.IP 78 -The resource referenced in the URL does not exist. -.IP 79 -An unspecified error occurred during the SSH session. -.IP 80 -Failed to shut down the SSL connection. -.IP 82 -Could not load CRL file, missing or wrong format (added in 7.19.0). -.IP 83 -Issuer check failed (added in 7.19.0). -.IP 84 -The FTP PRET command failed -.IP 85 -RTSP: mismatch of CSeq numbers -.IP 86 -RTSP: mismatch of Session Identifiers -.IP 87 -unable to parse FTP file list -.IP 88 -FTP chunk callback reported error -.IP 89 -No connection available, the session will be queued -.IP 90 -SSL public key does not matched pinned public key -.IP XX -More error codes will appear here in future releases. The existing ones -are meant to never change. -.SH AUTHORS / CONTRIBUTORS -Daniel Stenberg is the main author, but the whole list of contributors is -found in the separate THANKS file. -.SH WWW -https://curl.haxx.se -.SH FTP -ftp://ftp.sunet.se/pub/www/utilities/curl/ -.SH "SEE ALSO" -.BR ftp (1), -.BR wget (1) |