diff options
Diffstat (limited to 'docs')
83 files changed, 1151 insertions, 0 deletions
diff --git a/docs/cmdline-opts/anyauth.d b/docs/cmdline-opts/anyauth.d new file mode 100644 index 000000000..c32d1ed5e --- /dev/null +++ b/docs/cmdline-opts/anyauth.d @@ -0,0 +1,17 @@ +Long: anyauth +Help: Pick any authentication method +Protocols: HTTP +See-also: proxy-anyauth basic digest +--- +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 --basic, --digest, --ntlm, and --negotiate. + +Using --anyauth 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 --user. diff --git a/docs/cmdline-opts/append.d b/docs/cmdline-opts/append.d new file mode 100644 index 000000000..f001b1239 --- /dev/null +++ b/docs/cmdline-opts/append.d @@ -0,0 +1,8 @@ +Short: a +Long: append +Help: Append to target file when uploading +Protocols: 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). diff --git a/docs/cmdline-opts/basic.d b/docs/cmdline-opts/basic.d new file mode 100644 index 000000000..09d42af9d --- /dev/null +++ b/docs/cmdline-opts/basic.d @@ -0,0 +1,11 @@ +Long: basic +Help: Use HTTP Basic Authentication +See-also: proxy-basic +Protocols: 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 +--ntlm, --digest, or --negotiate). + +Used together with --user. diff --git a/docs/cmdline-opts/cacert.d b/docs/cmdline-opts/cacert.d new file mode 100644 index 000000000..04e113980 --- /dev/null +++ b/docs/cmdline-opts/cacert.d @@ -0,0 +1,28 @@ +Long: cacert +Arg: <CA certificate> +Help: CA certificate to verify peer against +Protocols: 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. diff --git a/docs/cmdline-opts/capath.d b/docs/cmdline-opts/capath.d new file mode 100644 index 000000000..0763f7a0d --- /dev/null +++ b/docs/cmdline-opts/capath.d @@ -0,0 +1,15 @@ +Long: capath +Arg: <dir> +Help: CA directory to verify peer against +Protocols: 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 --capath can allow +OpenSSL-powered curl to make SSL-connections much more efficiently than using +--cacert 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. diff --git a/docs/cmdline-opts/cert-status.d b/docs/cmdline-opts/cert-status.d new file mode 100644 index 000000000..f1aaa2174 --- /dev/null +++ b/docs/cmdline-opts/cert-status.d @@ -0,0 +1,13 @@ +Long: cert-status +Protocols: TLS +Added: 7.41.0 +Help: Verify the status of the server certificate +--- +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. diff --git a/docs/cmdline-opts/cert-type.d b/docs/cmdline-opts/cert-type.d new file mode 100644 index 000000000..a04bdce5d --- /dev/null +++ b/docs/cmdline-opts/cert-type.d @@ -0,0 +1,10 @@ +Long: cert-type +Protocols: TLS +Arg: <type> +Help: Certificate file type (DER/PEM/ENG) +See-also: cert key key-type +--- +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. diff --git a/docs/cmdline-opts/cert.d b/docs/cmdline-opts/cert.d new file mode 100644 index 000000000..0cd5d535f --- /dev/null +++ b/docs/cmdline-opts/cert.d @@ -0,0 +1,32 @@ +Short: E +Long: cert +Arg: <certificate[:password]> +Help: Client certificate file and password +Protocols: TLS +See-also: cert-type key key-type +--- +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 --cert and --key 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. diff --git a/docs/cmdline-opts/ciphers.d b/docs/cmdline-opts/ciphers.d new file mode 100644 index 000000000..b1e5ac9a3 --- /dev/null +++ b/docs/cmdline-opts/ciphers.d @@ -0,0 +1,16 @@ +Long: ciphers +Arg: <list of ciphers> +help: SSL ciphers to use +Protocols: 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://www.openssl.org/docs/apps/ciphers.html + +NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of NSS +ciphers is in the NSSCipherSuite entry at this URL: + + https://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/compressed.d b/docs/cmdline-opts/compressed.d new file mode 100644 index 000000000..dc130c1f0 --- /dev/null +++ b/docs/cmdline-opts/compressed.d @@ -0,0 +1,7 @@ +Long: compressed +Help: Request compressed response +Protocols: 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. diff --git a/docs/cmdline-opts/config.d b/docs/cmdline-opts/config.d new file mode 100644 index 000000000..4a3251275 --- /dev/null +++ b/docs/cmdline-opts/config.d @@ -0,0 +1,60 @@ +Long: config +Arg: <file> +Help: Read config from a file +Short: K +--- +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 --config 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 --url 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 --disable 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. diff --git a/docs/cmdline-opts/connect-timeout.d b/docs/cmdline-opts/connect-timeout.d new file mode 100644 index 000000000..3a32d8685 --- /dev/null +++ b/docs/cmdline-opts/connect-timeout.d @@ -0,0 +1,11 @@ +Long: connect-timeout +Arg: <seconds> +Help: Maximum time allowed for connection +See-also: max-time +--- +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. diff --git a/docs/cmdline-opts/continue-at.d b/docs/cmdline-opts/continue-at.d new file mode 100644 index 000000000..733f4941e --- /dev/null +++ b/docs/cmdline-opts/continue-at.d @@ -0,0 +1,15 @@ +Short: C +Long: continue-at +Arg: <offset> +Help: Resumed transfer offset +See-also: range +--- +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. diff --git a/docs/cmdline-opts/create-dirs.d b/docs/cmdline-opts/create-dirs.d new file mode 100644 index 000000000..49e22e75a --- /dev/null +++ b/docs/cmdline-opts/create-dirs.d @@ -0,0 +1,9 @@ +Long: create-dirs +Help: Create necessary local directory hierarchy +--- +When used in conjunction with the --output option, curl will create the +necessary local directory hierarchy as needed. This option creates the dirs +mentioned with the --output 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 --ftp-create-dirs. diff --git a/docs/cmdline-opts/crlf.d b/docs/cmdline-opts/crlf.d new file mode 100644 index 000000000..f6694b654 --- /dev/null +++ b/docs/cmdline-opts/crlf.d @@ -0,0 +1,7 @@ +Long: crlf +Help: Convert LF to CRLF in upload +Protocols: FTP SMTP +--- +Convert LF to CRLF in upload. Useful for MVS (OS/390). + +(SMTP added in 7.40.0) diff --git a/docs/cmdline-opts/crlfile.d b/docs/cmdline-opts/crlfile.d new file mode 100644 index 000000000..ae216b9e5 --- /dev/null +++ b/docs/cmdline-opts/crlfile.d @@ -0,0 +1,10 @@ +Long: crfile +Arg: <file> +Protocols: TLS +Help: Get a CRL list in PEM format from the given file +Added: 7.19.7 +--- +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. diff --git a/docs/cmdline-opts/data-ascii.d b/docs/cmdline-opts/data-ascii.d new file mode 100644 index 000000000..52f80312c --- /dev/null +++ b/docs/cmdline-opts/data-ascii.d @@ -0,0 +1,5 @@ +Long: data-ascii +Arg: <data> +Help: HTTP POST ASCII data +Protocols: HTTP +Redirect: data diff --git a/docs/cmdline-opts/data-binary.d b/docs/cmdline-opts/data-binary.d new file mode 100644 index 000000000..c6721c641 --- /dev/null +++ b/docs/cmdline-opts/data-binary.d @@ -0,0 +1,13 @@ +Long: data-binary +Arg: <data> +Help: HTTP POST binary data +Protocols: 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 --data 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 --data. diff --git a/docs/cmdline-opts/data-raw.d b/docs/cmdline-opts/data-raw.d new file mode 100644 index 000000000..7669b4abf --- /dev/null +++ b/docs/cmdline-opts/data-raw.d @@ -0,0 +1,9 @@ +Long: data-raw +Arg: <data> +Protocols: HTTP +Help: HTTP POST data, '@' allowed +Added: 7.43.0 +See-also: data +--- +This posts data similarly to --data but without the special +interpretation of the @ character. diff --git a/docs/cmdline-opts/data-urlencode.d b/docs/cmdline-opts/data-urlencode.d new file mode 100644 index 000000000..9873f3356 --- /dev/null +++ b/docs/cmdline-opts/data-urlencode.d @@ -0,0 +1,33 @@ +Long: data-urlencode +Arg: <data> +Help: HTTP POST data url encoded +Protocols: HTTP +See-also: data data-raw +Added: 7.18.0 +--- +This posts data, similar to the other --data 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 diff --git a/docs/cmdline-opts/data.d b/docs/cmdline-opts/data.d new file mode 100644 index 000000000..353b41f21 --- /dev/null +++ b/docs/cmdline-opts/data.d @@ -0,0 +1,30 @@ +Long: data +Short: d +Arg: <data> +Help: HTTP POST data +Protocols: HTTP +See-also: data-binary data-urlencode data-raw +Mutexed: form head upload +--- +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 --form. + +--data-raw is almost the same but does not have a special interpretation of +the @ character. To post data purely binary, you should instead use the +--data-binary option. To URL-encode the value of a form field you may use +--data-urlencode. + +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--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 +--data-raw instead. diff --git a/docs/cmdline-opts/delegation.d b/docs/cmdline-opts/delegation.d new file mode 100644 index 000000000..138d82333 --- /dev/null +++ b/docs/cmdline-opts/delegation.d @@ -0,0 +1,16 @@ +Long: delegation +Arg: <LEVEL> +Help: GSS-API delegation permission +Protocols: 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 diff --git a/docs/cmdline-opts/digest.d b/docs/cmdline-opts/digest.d new file mode 100644 index 000000000..5cdd9258a --- /dev/null +++ b/docs/cmdline-opts/digest.d @@ -0,0 +1,11 @@ +Long: digest +Help: Use HTTP Digest Authentication +Protocols: HTTP +Mutexed: basic ntlm negotiate +See-also: user proxy-digest anyauth +--- +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 --user option to set user name and password. + +If this option is used several times, only the first one is used. diff --git a/docs/cmdline-opts/disable-eprt.d b/docs/cmdline-opts/disable-eprt.d new file mode 100644 index 000000000..a1e53c0bd --- /dev/null +++ b/docs/cmdline-opts/disable-eprt.d @@ -0,0 +1,19 @@ +Long: disable-eprt +Help: Inhibit using EPRT or LPRT +Protocols: 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 --disable-eprt. + +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 --ftp-port or force it with --ftp-pasv. diff --git a/docs/cmdline-opts/dns-interface.d b/docs/cmdline-opts/dns-interface.d new file mode 100644 index 000000000..45e5af263 --- /dev/null +++ b/docs/cmdline-opts/dns-interface.d @@ -0,0 +1,11 @@ +Long: dns-interface +Arg: <interface> +Help: Interface to use for DNS requests +Protocols: DNS +See-also: dns-ipv4-addr dns-ipv6-addr +Added: 7.33.0 +Requires: c-ares +--- +Tell curl to send outgoing DNS requests through <interface>. This option is a +counterpart to --interface (which does not affect DNS). The supplied string +must be an interface name (not an address). diff --git a/docs/cmdline-opts/dns-ipv4-addr.d b/docs/cmdline-opts/dns-ipv4-addr.d new file mode 100644 index 000000000..597b85884 --- /dev/null +++ b/docs/cmdline-opts/dns-ipv4-addr.d @@ -0,0 +1,11 @@ +Long: dns-ipv4-addr +Arg: <address> +Help: IPv4 address to use for DNS requests +Protocols: DNS +See-also: dns-interface dns-ipv6-addr +Added: 7.33.0 +Requires: c-ares +--- +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. diff --git a/docs/cmdline-opts/dns-ipv6-addr.d b/docs/cmdline-opts/dns-ipv6-addr.d new file mode 100644 index 000000000..581f01953 --- /dev/null +++ b/docs/cmdline-opts/dns-ipv6-addr.d @@ -0,0 +1,11 @@ +Long: dns-ipv6-addr +Arg: <address> +Help: IPv6 address to use for DNS requests +Protocols: DNS +See-also: dns-interface dns-ipv4-addr +Added: 7.33.0 +Requires: c-ares +--- +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. diff --git a/docs/cmdline-opts/dns-servers.d b/docs/cmdline-opts/dns-servers.d new file mode 100644 index 000000000..a98fd07d8 --- /dev/null +++ b/docs/cmdline-opts/dns-servers.d @@ -0,0 +1,10 @@ +Long: dns-servers +Arg: <addresses> +Help: DNS server addrs to use +Requires: c-ares +Added: 7.33.0 +--- +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. diff --git a/docs/cmdline-opts/dump-header.d b/docs/cmdline-opts/dump-header.d new file mode 100644 index 000000000..05c10affd --- /dev/null +++ b/docs/cmdline-opts/dump-header.d @@ -0,0 +1,18 @@ +Long: dump-header +Short: D +Arg: <filename> +Help: Write the received headers to <filename> +Protocols: HTTP FTP +See-also: output +--- +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 --cookie option! The --cookie-jar 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. diff --git a/docs/cmdline-opts/egd-file.d b/docs/cmdline-opts/egd-file.d new file mode 100644 index 000000000..2ee6d34d7 --- /dev/null +++ b/docs/cmdline-opts/egd-file.d @@ -0,0 +1,7 @@ +Long: egd-file +Help: EGD socket path for random data +Protocols: TLS +See-also: random-file +--- +Specify the path name to the Entropy Gathering Daemon socket. The socket is +used to seed the random engine for SSL connections. diff --git a/docs/cmdline-opts/engine.d b/docs/cmdline-opts/engine.d new file mode 100644 index 000000000..53b7c333c --- /dev/null +++ b/docs/cmdline-opts/engine.d @@ -0,0 +1,8 @@ +Long: engine +Arg: <name> +Help: Crypto engine to use +Protocols: TLS +--- +Select the OpenSSL crypto engine to use for cipher operations. Use \fI--engine +list\fP to print a list of build-time supported engines. Note that not all (or +none) of the engines may be available at run-time. diff --git a/docs/cmdline-opts/environment.d b/docs/cmdline-opts/environment.d new file mode 100644 index 000000000..6289e53d4 --- /dev/null +++ b/docs/cmdline-opts/environment.d @@ -0,0 +1,7 @@ +Long: environment +Help: Write results to environment variables +Requires: RISC OS +--- +Sets a range of environment variables, using the names the --write-out option +supports, to allow easier extraction of useful information after having run +curl. diff --git a/docs/cmdline-opts/expect100-timeout.d b/docs/cmdline-opts/expect100-timeout.d new file mode 100644 index 000000000..c88f0b84f --- /dev/null +++ b/docs/cmdline-opts/expect100-timeout.d @@ -0,0 +1,11 @@ +Long: expect100-timeout +Arg: <seconds> +Help: How long to wait for 100-continue +Protocols: HTTP +Added: 7.47.0 +See-also: connect-timeout +--- +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. diff --git a/docs/cmdline-opts/fail-early.d b/docs/cmdline-opts/fail-early.d new file mode 100644 index 000000000..4489b4fc4 --- /dev/null +++ b/docs/cmdline-opts/fail-early.d @@ -0,0 +1,18 @@ +Long: fail-early +Help: Fail on first transfer error, do not continue +Added: 7.52.0 +--- +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 --next. diff --git a/docs/cmdline-opts/fail.d b/docs/cmdline-opts/fail.d new file mode 100644 index 000000000..c46c571bf --- /dev/null +++ b/docs/cmdline-opts/fail.d @@ -0,0 +1,14 @@ +Long: fail +Short: f +Protocols: HTTP +Help: Fail silently (no output at all) on HTTP errors +--- +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). diff --git a/docs/cmdline-opts/false-start.d b/docs/cmdline-opts/false-start.d new file mode 100644 index 000000000..65a8afb8f --- /dev/null +++ b/docs/cmdline-opts/false-start.d @@ -0,0 +1,12 @@ +Long: false-start +Help: Enable TLS False Start +Protocols: TLS +Added: 7.42.0 +--- +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. diff --git a/docs/cmdline-opts/form-string.d b/docs/cmdline-opts/form-string.d new file mode 100644 index 000000000..db1856b4f --- /dev/null +++ b/docs/cmdline-opts/form-string.d @@ -0,0 +1,10 @@ +Long: form-string +Help: Specify HTTP multipart POST data +Protocols: HTTP +See-also: form +--- +Similar to --form 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 --form\fP if +there's any possibility that the string value may accidentally trigger the +\&'@' or \&'<' features of --form. diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d new file mode 100644 index 000000000..87a7d0766 --- /dev/null +++ b/docs/cmdline-opts/form.d @@ -0,0 +1,54 @@ +Long: form +Short: F +Arg: <name=content> +Help: Specify HTTP multipart POST data +Protocols: HTTP +Mutexed: data head upload +--- +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. diff --git a/docs/cmdline-opts/ftp-account.d b/docs/cmdline-opts/ftp-account.d new file mode 100644 index 000000000..013c4f37b --- /dev/null +++ b/docs/cmdline-opts/ftp-account.d @@ -0,0 +1,10 @@ +Long: ftp-account +Arg: <data> +Help: Account data string +Protocols: FTP +Added: 7.13.0 +--- +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. diff --git a/docs/cmdline-opts/ftp-alternative-to-user.d b/docs/cmdline-opts/ftp-alternative-to-user.d new file mode 100644 index 000000000..8982ba8b8 --- /dev/null +++ b/docs/cmdline-opts/ftp-alternative-to-user.d @@ -0,0 +1,10 @@ +Long: ftp-alternative-to-user +Arg: <command> +Help: String to replace USER [name] +Protocols: FTP +Added: 7.15.5 +--- +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. diff --git a/docs/cmdline-opts/ftp-create-dirs.d b/docs/cmdline-opts/ftp-create-dirs.d new file mode 100644 index 000000000..ede57100d --- /dev/null +++ b/docs/cmdline-opts/ftp-create-dirs.d @@ -0,0 +1,8 @@ +Long: ftp-create-dirs +Protocols: FTP SFTP +Help: Create the remote dirs if not present +See-also: create-dirs +--- +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. diff --git a/docs/cmdline-opts/ftp-method.d b/docs/cmdline-opts/ftp-method.d new file mode 100644 index 000000000..95aa522e8 --- /dev/null +++ b/docs/cmdline-opts/ftp-method.d @@ -0,0 +1,21 @@ +Long: ftp-method +Arg: <method> +Help: Control CWD usage +Protocols: FTP +Added: 7.15.1 +--- +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 diff --git a/docs/cmdline-opts/ftp-pasv.d b/docs/cmdline-opts/ftp-pasv.d new file mode 100644 index 000000000..44103e21a --- /dev/null +++ b/docs/cmdline-opts/ftp-pasv.d @@ -0,0 +1,16 @@ +Long: ftp-pasv +Help: Use PASV/EPSV instead of PORT +Protocols: FTP +Added: 7.11.0 +See-also: disable-epsv +--- +Use passive mode for the data connection. Passive is the internal default +behavior, but using this option can be used to override a previous --ftp-port +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 --ftp-port again. + +Passive mode means that curl will try the EPSV command first and then PASV, +unless --disable-epsv is used. diff --git a/docs/cmdline-opts/ftp-pret.d b/docs/cmdline-opts/ftp-pret.d new file mode 100644 index 000000000..dac4c3531 --- /dev/null +++ b/docs/cmdline-opts/ftp-pret.d @@ -0,0 +1,8 @@ +Long: ftp-pret +Help: Send PRET before PASV +Protocols: FTP +Added: 7.20.0 +--- +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. diff --git a/docs/cmdline-opts/ftp-skip-pasv-ip.d b/docs/cmdline-opts/ftp-skip-pasv-ip.d new file mode 100644 index 000000000..da6ab11fc --- /dev/null +++ b/docs/cmdline-opts/ftp-skip-pasv-ip.d @@ -0,0 +1,12 @@ +Long: ftp-skip-pasv-ip +Help: Skip the IP address for PASV +Protocols: FTP +Added: 7.14.2 +See-also: ftp-pasv +--- +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. diff --git a/docs/cmdline-opts/ftp-ssl-ccc-mode.d b/docs/cmdline-opts/ftp-ssl-ccc-mode.d new file mode 100644 index 000000000..be1029498 --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl-ccc-mode.d @@ -0,0 +1,11 @@ +Long: ftp-ssl-ccc-mode +Arg: <active/passive> +Help: Set CCC mode +Protocols: FTP +Added: 7.16.2 +See-also: ftp-ssl-ccc +--- +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. diff --git a/docs/cmdline-opts/ftp-ssl-ccc.d b/docs/cmdline-opts/ftp-ssl-ccc.d new file mode 100644 index 000000000..c6edc5b39 --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl-ccc.d @@ -0,0 +1,10 @@ +Long: ftp-ssl-ccc +Help: Send CCC after authenticating +Protocols: FTP +See-also: ssl ftp-ssl-ccc-mode +Added: 7.16.1 +--- +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. diff --git a/docs/cmdline-opts/ftp-ssl-control.d b/docs/cmdline-opts/ftp-ssl-control.d new file mode 100644 index 000000000..87a822531 --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl-control.d @@ -0,0 +1,8 @@ +Long: ftp-ssl-control +Help: Require SSL/TLS for FTP login, clear for transfer +Protocols: FTP +Added: 7.16.0 +--- +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. diff --git a/docs/cmdline-opts/ftp-ssl-reqd.d b/docs/cmdline-opts/ftp-ssl-reqd.d new file mode 100644 index 000000000..2f8048463 --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl-reqd.d @@ -0,0 +1,3 @@ +Long: ftp-ssl-reqd +Help: Require SSL/TLS +Redirect: ssl-reqd diff --git a/docs/cmdline-opts/ftp-ssl.d b/docs/cmdline-opts/ftp-ssl.d new file mode 100644 index 000000000..aee48a1cb --- /dev/null +++ b/docs/cmdline-opts/ftp-ssl.d @@ -0,0 +1,3 @@ +Long: ftp-ssl +Help: Try SSL/TLS +Redirect: ssl diff --git a/docs/cmdline-opts/get.d b/docs/cmdline-opts/get.d new file mode 100644 index 000000000..be7cb25f0 --- /dev/null +++ b/docs/cmdline-opts/get.d @@ -0,0 +1,15 @@ +Long: get +Short: G +Help: Put the post data in the URL and use GET +--- +When used, this option will make all data specified with --data, --data-binary +or --data-urlencode 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 --head, 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. diff --git a/docs/cmdline-opts/globoff.d b/docs/cmdline-opts/globoff.d new file mode 100644 index 000000000..fff6516b6 --- /dev/null +++ b/docs/cmdline-opts/globoff.d @@ -0,0 +1,8 @@ +Long: globoff +Short: g +Help: Disable URL sequences and ranges using {} and [] +--- +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. diff --git a/docs/cmdline-opts/head.d b/docs/cmdline-opts/head.d new file mode 100644 index 000000000..350a100f6 --- /dev/null +++ b/docs/cmdline-opts/head.d @@ -0,0 +1,8 @@ +Long: head +Short: I +Help: Show document info only +Protocols: 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. diff --git a/docs/cmdline-opts/header.d b/docs/cmdline-opts/header.d new file mode 100644 index 000000000..762334fe4 --- /dev/null +++ b/docs/cmdline-opts/header.d @@ -0,0 +1,39 @@ +Long: header +Short: H +Arg: <header> +Help: Pass custom header LINE to server +Protocols: 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 --user-agent and --referer options. + +Starting in 7.37.0, you need --proxy-header 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 \fB-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. diff --git a/docs/cmdline-opts/hostpubmd5.d b/docs/cmdline-opts/hostpubmd5.d new file mode 100644 index 000000000..a85115803 --- /dev/null +++ b/docs/cmdline-opts/hostpubmd5.d @@ -0,0 +1,9 @@ +Long: hostpubmd5 +Arg: <md5> +Help: Acceptable MD5 hash of the host public key +Protocols: SFTP SCP +Added: 7.17.1 +--- +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. diff --git a/docs/cmdline-opts/ignore-content-length.d b/docs/cmdline-opts/ignore-content-length.d new file mode 100644 index 000000000..53524f518 --- /dev/null +++ b/docs/cmdline-opts/ignore-content-length.d @@ -0,0 +1,10 @@ +Long: ignore-content-length +Help: Ignore the size of the remote resource +Protocols: 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. diff --git a/docs/cmdline-opts/include.d b/docs/cmdline-opts/include.d new file mode 100644 index 000000000..e55d51638 --- /dev/null +++ b/docs/cmdline-opts/include.d @@ -0,0 +1,7 @@ +Long: include +Short: i +Help: Include protocol headers in the output +See-also: verbose +--- +Include the HTTP-header in the output. The HTTP-header includes things like +server-name, date of the document, HTTP-version and more... diff --git a/docs/cmdline-opts/insecure.d b/docs/cmdline-opts/insecure.d new file mode 100644 index 000000000..1dd0fa8c0 --- /dev/null +++ b/docs/cmdline-opts/insecure.d @@ -0,0 +1,12 @@ +Long: insecure +Short: k +Help: Allow insecure connections when using SSL +Protocols: 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 --insecure is used. + +See this online resource for further details: + https://curl.haxx.se/docs/sslcerts.html diff --git a/docs/cmdline-opts/interface.d b/docs/cmdline-opts/interface.d new file mode 100644 index 000000000..da84cd2b6 --- /dev/null +++ b/docs/cmdline-opts/interface.d @@ -0,0 +1,12 @@ +Long: interface +Arg: <name> +Help: Use network INTERFACE (or address) +See-also: dns-interface +--- + +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. diff --git a/docs/cmdline-opts/ipv4.d b/docs/cmdline-opts/ipv4.d new file mode 100644 index 000000000..9c40c8c3e --- /dev/null +++ b/docs/cmdline-opts/ipv4.d @@ -0,0 +1,12 @@ +Short: 4 +Long: ipv4 +Tags: Versions +Protocols: +Added: +Mutexed: ipv6 +Requires: +See-also: http1.1 http2 +Help: Resolve names to IPv4 addresses +--- +This option tells curl to resolve names to IPv4 addresses only, and not for +example try IPv6. diff --git a/docs/cmdline-opts/ipv6.d b/docs/cmdline-opts/ipv6.d new file mode 100644 index 000000000..c2392e771 --- /dev/null +++ b/docs/cmdline-opts/ipv6.d @@ -0,0 +1,12 @@ +Short: 6 +Long: ipv6 +Tags: Versions +Protocols: +Added: +Mutexed: ipv6 +Requires: +See-also: http1.1 http2 +Help: Resolve names to IPv6 addresses +--- +This option tells curl to resolve names to IPv6 addresses only, and not for +example try IPv4. diff --git a/docs/cmdline-opts/junk-session-cookies.d b/docs/cmdline-opts/junk-session-cookies.d new file mode 100644 index 000000000..40ccd9c2d --- /dev/null +++ b/docs/cmdline-opts/junk-session-cookies.d @@ -0,0 +1,10 @@ +Long: junk-session-cookies +Short: j +Help: Ignore session cookies read from file +Protocols: HTTP +See-also: cookie cookie-jar +--- +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. diff --git a/docs/cmdline-opts/keepalive-time.d b/docs/cmdline-opts/keepalive-time.d new file mode 100644 index 000000000..c816e13ff --- /dev/null +++ b/docs/cmdline-opts/keepalive-time.d @@ -0,0 +1,13 @@ +Long: keepalive-time +Arg: <seconds> +Help: Interval time for keepalive probes +Added: 7.18.0 +--- +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 --no-keepalive is used. + +If this option is used several times, the last one will be used. If +unspecified, the option defaults to 60 seconds. diff --git a/docs/cmdline-opts/key-type.d b/docs/cmdline-opts/key-type.d new file mode 100644 index 000000000..bf39bcd35 --- /dev/null +++ b/docs/cmdline-opts/key-type.d @@ -0,0 +1,9 @@ +Long: key-type +Arg: <type> +Help: Private key file type (DER/PEM/ENG) +Protocols: TLS +--- +Private key file type. Specify which type your --key 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. diff --git a/docs/cmdline-opts/key.d b/docs/cmdline-opts/key.d new file mode 100644 index 000000000..fbf583af0 --- /dev/null +++ b/docs/cmdline-opts/key.d @@ -0,0 +1,10 @@ +Long: key +Arg: <key> +Protocols: TLS SSH +Help: Private key file name +--- +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. diff --git a/docs/cmdline-opts/krb.d b/docs/cmdline-opts/krb.d new file mode 100644 index 000000000..19547af08 --- /dev/null +++ b/docs/cmdline-opts/krb.d @@ -0,0 +1,11 @@ +Long: krb +Arg: <level> +Help: Enable Kerberos with security <level> +Protocols: FTP +Requires: Kerberos +--- +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. diff --git a/docs/cmdline-opts/krb4.d b/docs/cmdline-opts/krb4.d new file mode 100644 index 000000000..79bab81b9 --- /dev/null +++ b/docs/cmdline-opts/krb4.d @@ -0,0 +1,2 @@ +Long: krb4 +Redirect: krb diff --git a/docs/cmdline-opts/libcurl.d b/docs/cmdline-opts/libcurl.d new file mode 100644 index 000000000..ef132fe74 --- /dev/null +++ b/docs/cmdline-opts/libcurl.d @@ -0,0 +1,11 @@ +Long: libcurl +Arg: <file> +Help: Dump libcurl equivalent code of this command line +Added: 7.16.1 +--- +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. diff --git a/docs/cmdline-opts/limit-rate.d b/docs/cmdline-opts/limit-rate.d new file mode 100644 index 000000000..8784a84d3 --- /dev/null +++ b/docs/cmdline-opts/limit-rate.d @@ -0,0 +1,18 @@ +Long: limit-rate +Arg: <speed> +Help: Limit transfer speed to RATE +--- +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 --speed-limit 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. diff --git a/docs/cmdline-opts/list-only.d b/docs/cmdline-opts/list-only.d new file mode 100644 index 000000000..4c56304a0 --- /dev/null +++ b/docs/cmdline-opts/list-only.d @@ -0,0 +1,24 @@ +Long: list-only +Short: l +Protocols: FTP POP3 +Help: List only mode +Added: 7.21.5 +--- +(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 --request, 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. diff --git a/docs/cmdline-opts/local-port.d b/docs/cmdline-opts/local-port.d new file mode 100644 index 000000000..d96b46eb8 --- /dev/null +++ b/docs/cmdline-opts/local-port.d @@ -0,0 +1,9 @@ +Long: local-port +Arg: <num/range> +Help: Force use of RANGE for local port numbers +Added: 7.15.2 +--- +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. diff --git a/docs/cmdline-opts/location-trusted.d b/docs/cmdline-opts/location-trusted.d new file mode 100644 index 000000000..995a8718a --- /dev/null +++ b/docs/cmdline-opts/location-trusted.d @@ -0,0 +1,9 @@ +Long: location-trusted +Help: Like --location, and send auth to other hosts +Protocols: HTTP +See-also: user +--- +Like --location, 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). diff --git a/docs/cmdline-opts/location.d b/docs/cmdline-opts/location.d new file mode 100644 index 000000000..7c70e6981 --- /dev/null +++ b/docs/cmdline-opts/location.d @@ -0,0 +1,23 @@ +Long: location +Short: L +Help: Follow redirects +Protocols: 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 +--include or --head, 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 --location-trusted on how to change +this. You can limit the amount of redirects to follow by using the +--max-redirs 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: --post301, --post302 and +--post303. diff --git a/docs/cmdline-opts/login-options.d b/docs/cmdline-opts/login-options.d new file mode 100644 index 000000000..ea2af082d --- /dev/null +++ b/docs/cmdline-opts/login-options.d @@ -0,0 +1,13 @@ +Long: login-options +Arg: <options> +Protocols: IMAP POP3 SMTP +Added: 7.34.0 +--- +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. diff --git a/docs/cmdline-opts/max-time.d b/docs/cmdline-opts/max-time.d new file mode 100644 index 000000000..c22343d32 --- /dev/null +++ b/docs/cmdline-opts/max-time.d @@ -0,0 +1,13 @@ +Long: max-time +Short: m +Arg: <time> +Help: Maximum time allowed for the transfer +See-also: connect-timeout +--- +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. diff --git a/docs/cmdline-opts/pinnedpubkey.d b/docs/cmdline-opts/pinnedpubkey.d new file mode 100644 index 000000000..0657e6e79 --- /dev/null +++ b/docs/cmdline-opts/pinnedpubkey.d @@ -0,0 +1,27 @@ +Long: pinnedpubkey +Arg: <hashes> +Help: FILE/HASHES Public key to verify peer against +Protocols: 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. diff --git a/docs/cmdline-opts/referer.d b/docs/cmdline-opts/referer.d new file mode 100644 index 000000000..dbecd785d --- /dev/null +++ b/docs/cmdline-opts/referer.d @@ -0,0 +1,12 @@ +Long: referer +Protocols: HTTP +Help: Referer URL +See-also: user-agent header +--- +Sends the "Referrer Page" information to the HTTP server. This can also be set +with the --header flag of course. When used with --location you can append +";auto" to the --referer 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 --referer. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/remote-header-name.d b/docs/cmdline-opts/remote-header-name.d new file mode 100644 index 000000000..771b6d469 --- /dev/null +++ b/docs/cmdline-opts/remote-header-name.d @@ -0,0 +1,19 @@ +Long: remote-header-name +Short: J +Protocols: HTTP +Help: Use the header-provided filename +--- +This option tells the --remote-name 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. diff --git a/docs/cmdline-opts/sslv2.d b/docs/cmdline-opts/sslv2.d new file mode 100644 index 000000000..67d2b8506 --- /dev/null +++ b/docs/cmdline-opts/sslv2.d @@ -0,0 +1,13 @@ +Short: 2 +Long: sslv2 +Tags: Versions +Protocols: SSL +Added: +Mutexed: sslv3 tlsv1 tlsv1.1 tlsv1.2 +Requires: TLS +See-also: http1.1 http2 +Help: Use SSLv2 +--- +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). diff --git a/docs/cmdline-opts/sslv3.d b/docs/cmdline-opts/sslv3.d new file mode 100644 index 000000000..101ad1004 --- /dev/null +++ b/docs/cmdline-opts/sslv3.d @@ -0,0 +1,13 @@ +Short: 3 +Long: sslv3 +Tags: Versions +Protocols: SSL +Added: +Mutexed: sslv2 tlsv1 tlsv1.1 tlsv1.2 +Requires: TLS +See-also: http1.1 http2 +Help: Use SSLv3 +--- +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). diff --git a/docs/cmdline-opts/use-ascii.d b/docs/cmdline-opts/use-ascii.d new file mode 100644 index 000000000..da307dc4d --- /dev/null +++ b/docs/cmdline-opts/use-ascii.d @@ -0,0 +1,8 @@ +Short: B +Long: use-ascii +Help: Use ASCII/text transfer +Protocols: 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. diff --git a/docs/cmdline-opts/user-agent.d b/docs/cmdline-opts/user-agent.d new file mode 100644 index 000000000..c98619d7d --- /dev/null +++ b/docs/cmdline-opts/user-agent.d @@ -0,0 +1,12 @@ +Short: A +Long: user-agent +Arg: <name> +Help: Send User-Agent <name> to server +Protocols: 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 --header option of course. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/verbose.d b/docs/cmdline-opts/verbose.d index 640c5a782..5d3352183 100644 --- a/docs/cmdline-opts/verbose.d +++ b/docs/cmdline-opts/verbose.d @@ -2,6 +2,7 @@ Short: v Long: verbose Mutexed: trace trace-ascii Help: Make the operation more talkative +See-also: include --- 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" |