From 342aa4797edfabba78755e798d23a5b6d288d50b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 16 Nov 2016 14:20:36 +0100 Subject: cmdline-docs: more conversion --- docs/cmdline-opts/connect-to.d | 18 +++++++++++++ docs/cmdline-opts/ftp-port.d | 32 +++++++++++++++++++++++ docs/cmdline-opts/http1.1.d | 1 - docs/cmdline-opts/http2-prior-knowledge.d | 1 - docs/cmdline-opts/http2.d | 1 - docs/cmdline-opts/mail-auth.d | 10 +++++++ docs/cmdline-opts/mail-from.d | 8 ++++++ docs/cmdline-opts/mail-rcpt.d | 19 ++++++++++++++ docs/cmdline-opts/max-filesize.d | 12 +++++++++ docs/cmdline-opts/max-redirs.d | 11 ++++++++ docs/cmdline-opts/metalink.d | 27 +++++++++++++++++++ docs/cmdline-opts/negotiate.d | 15 +++++++++++ docs/cmdline-opts/netrc-file.d | 12 +++++++++ docs/cmdline-opts/netrc-optional.d | 7 +++++ docs/cmdline-opts/netrc.d | 17 ++++++++++++ docs/cmdline-opts/no-alpn.d | 4 +-- docs/cmdline-opts/no-buffer.d | 11 ++++++++ docs/cmdline-opts/no-keepalive.d | 8 ++++++ docs/cmdline-opts/no-npn.d | 3 +-- docs/cmdline-opts/no-sessionid.d | 13 ++++++++++ docs/cmdline-opts/noproxy.d | 11 ++++++++ docs/cmdline-opts/ntlm-wb.d | 7 +++++ docs/cmdline-opts/ntlm.d | 18 +++++++++++++ docs/cmdline-opts/oauth2-bearer.d | 11 ++++++++ docs/cmdline-opts/output.d | 32 +++++++++++++++++++++++ docs/cmdline-opts/pass.d | 8 ++++++ docs/cmdline-opts/path-as-is.d | 7 +++++ docs/cmdline-opts/post301.d | 11 ++++++++ docs/cmdline-opts/post302.d | 11 ++++++++ docs/cmdline-opts/post303.d | 11 ++++++++ docs/cmdline-opts/proto-default.d | 18 +++++++++++++ docs/cmdline-opts/proto-redir.d | 17 ++++++++++++ docs/cmdline-opts/proto.d | 43 +++++++++++++++++++++++++++++++ docs/cmdline-opts/proxy-header.d | 20 ++++++++++++++ docs/cmdline-opts/proxytunnel.d | 9 +++++++ docs/cmdline-opts/remote-name.d | 21 +++++++++++++++ 36 files changed, 477 insertions(+), 8 deletions(-) create mode 100644 docs/cmdline-opts/connect-to.d create mode 100644 docs/cmdline-opts/ftp-port.d create mode 100644 docs/cmdline-opts/mail-auth.d create mode 100644 docs/cmdline-opts/mail-from.d create mode 100644 docs/cmdline-opts/mail-rcpt.d create mode 100644 docs/cmdline-opts/max-filesize.d create mode 100644 docs/cmdline-opts/max-redirs.d create mode 100644 docs/cmdline-opts/metalink.d create mode 100644 docs/cmdline-opts/negotiate.d create mode 100644 docs/cmdline-opts/netrc-file.d create mode 100644 docs/cmdline-opts/netrc-optional.d create mode 100644 docs/cmdline-opts/netrc.d create mode 100644 docs/cmdline-opts/no-buffer.d create mode 100644 docs/cmdline-opts/no-keepalive.d create mode 100644 docs/cmdline-opts/no-sessionid.d create mode 100644 docs/cmdline-opts/noproxy.d create mode 100644 docs/cmdline-opts/ntlm-wb.d create mode 100644 docs/cmdline-opts/ntlm.d create mode 100644 docs/cmdline-opts/oauth2-bearer.d create mode 100644 docs/cmdline-opts/output.d create mode 100644 docs/cmdline-opts/pass.d create mode 100644 docs/cmdline-opts/path-as-is.d create mode 100644 docs/cmdline-opts/post301.d create mode 100644 docs/cmdline-opts/post302.d create mode 100644 docs/cmdline-opts/post303.d create mode 100644 docs/cmdline-opts/proto-default.d create mode 100644 docs/cmdline-opts/proto-redir.d create mode 100644 docs/cmdline-opts/proto.d create mode 100644 docs/cmdline-opts/proxy-header.d create mode 100644 docs/cmdline-opts/proxytunnel.d create mode 100644 docs/cmdline-opts/remote-name.d (limited to 'docs/cmdline-opts') diff --git a/docs/cmdline-opts/connect-to.d b/docs/cmdline-opts/connect-to.d new file mode 100644 index 000000000..3fa0568a6 --- /dev/null +++ b/docs/cmdline-opts/connect-to.d @@ -0,0 +1,18 @@ +Long: connect-to +Arg: +Help: Connect to host +Added: 7.49.0 +See-also: resolve header +--- + +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. diff --git a/docs/cmdline-opts/ftp-port.d b/docs/cmdline-opts/ftp-port.d new file mode 100644 index 000000000..a852e9054 --- /dev/null +++ b/docs/cmdline-opts/ftp-port.d @@ -0,0 +1,32 @@ +Long: ftp-port +Arg:
+Help: Use PORT instead of PASV +Short: P +Protocols: FTP +See-also: ftp-pasv disable-eprt +--- +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.
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 --ftp-pasv. Disable the attempt to use the EPRT command +instead of PORT by using --disable-eprt. 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. diff --git a/docs/cmdline-opts/http1.1.d b/docs/cmdline-opts/http1.1.d index fea1ada95..f1e6b5c3b 100644 --- a/docs/cmdline-opts/http1.1.d +++ b/docs/cmdline-opts/http1.1.d @@ -1,4 +1,3 @@ -Short: Long: http1.1 Tags: Versions Protocols: HTTP diff --git a/docs/cmdline-opts/http2-prior-knowledge.d b/docs/cmdline-opts/http2-prior-knowledge.d index 5ae95684c..f793f775d 100644 --- a/docs/cmdline-opts/http2-prior-knowledge.d +++ b/docs/cmdline-opts/http2-prior-knowledge.d @@ -1,4 +1,3 @@ -Short: Long: http2-prior-knowledge Tags: Versions Protocols: HTTP diff --git a/docs/cmdline-opts/http2.d b/docs/cmdline-opts/http2.d index 4d1bb2a3f..04cff00a4 100644 --- a/docs/cmdline-opts/http2.d +++ b/docs/cmdline-opts/http2.d @@ -1,4 +1,3 @@ -Short: Long: http2 Tags: Versions Protocols: HTTP diff --git a/docs/cmdline-opts/mail-auth.d b/docs/cmdline-opts/mail-auth.d new file mode 100644 index 000000000..70cf0eda4 --- /dev/null +++ b/docs/cmdline-opts/mail-auth.d @@ -0,0 +1,10 @@ +Long: mail-auth +Arg:
+Protocols: SMTP +Help: Originator address of the original email +Added: 7.25.0 +See-also: mail-rcpt mail-from +--- +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. diff --git a/docs/cmdline-opts/mail-from.d b/docs/cmdline-opts/mail-from.d new file mode 100644 index 000000000..1d932344c --- /dev/null +++ b/docs/cmdline-opts/mail-from.d @@ -0,0 +1,8 @@ +Long: mail-from +Arg:
+Help: Mail from this address +Protocols: SMTP +Added: 7.20.0 +See-also: mail-rcpt mail-auth +--- +Specify a single address that the given mail should get sent from. diff --git a/docs/cmdline-opts/mail-rcpt.d b/docs/cmdline-opts/mail-rcpt.d new file mode 100644 index 000000000..d747ceabf --- /dev/null +++ b/docs/cmdline-opts/mail-rcpt.d @@ -0,0 +1,19 @@ +Long: mail-rcpt +Arg:
+Help: Mail from this address +Protocols: SMTP +Added: 7.20.0 +--- +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) diff --git a/docs/cmdline-opts/max-filesize.d b/docs/cmdline-opts/max-filesize.d new file mode 100644 index 000000000..e92ef5837 --- /dev/null +++ b/docs/cmdline-opts/max-filesize.d @@ -0,0 +1,12 @@ +Long: max-filesize +Arg: +Help: Maximum file size to download +See-also: limit-rate +--- +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. diff --git a/docs/cmdline-opts/max-redirs.d b/docs/cmdline-opts/max-redirs.d new file mode 100644 index 000000000..04b824bd2 --- /dev/null +++ b/docs/cmdline-opts/max-redirs.d @@ -0,0 +1,11 @@ +Long: max-redirs +Arg: +Help: Maximum number of redirects allowed +Protocols: HTTP +--- +Set maximum number of redirection-followings allowed. When --location 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. diff --git a/docs/cmdline-opts/metalink.d b/docs/cmdline-opts/metalink.d new file mode 100644 index 000000000..8047e9f51 --- /dev/null +++ b/docs/cmdline-opts/metalink.d @@ -0,0 +1,27 @@ +Long: metalink +Help: Process given URLs as metalink XML file +Added: 7.27.0 +Requires: 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 --metalink and +--include 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. + diff --git a/docs/cmdline-opts/negotiate.d b/docs/cmdline-opts/negotiate.d new file mode 100644 index 000000000..69a6b9170 --- /dev/null +++ b/docs/cmdline-opts/negotiate.d @@ -0,0 +1,15 @@ +Long: negotiate +Help: Use HTTP Negotiate (SPNEGO) authentication +Protocols: HTTP +See-also: basic ntlm anyauth proxy-negotiate +--- +Enables Negotiate (SPNEGO) authentication. + +This option requires a library built with GSS-API or SSPI support. Use +--version to see if your curl supports GSS-API/SSPI or SPNEGO. + +When using this option, you must also provide a fake --user option to activate +the authentication code properly. Sending a '-u :' is enough as the user name +and password from the --user option aren't actually used. + +If this option is used several times, only the first one is used. diff --git a/docs/cmdline-opts/netrc-file.d b/docs/cmdline-opts/netrc-file.d new file mode 100644 index 000000000..4118b4dba --- /dev/null +++ b/docs/cmdline-opts/netrc-file.d @@ -0,0 +1,12 @@ +Long: netrc-file +Help: Specify FILE for netrc +Arg: +Added: 7.21.5 +Mutexed: netrc +--- +This option is similar to --netrc, 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 --netrc-file options are provided, +the last one will be used. + +It will abide by --netrc-optional if specified. diff --git a/docs/cmdline-opts/netrc-optional.d b/docs/cmdline-opts/netrc-optional.d new file mode 100644 index 000000000..c28540309 --- /dev/null +++ b/docs/cmdline-opts/netrc-optional.d @@ -0,0 +1,7 @@ +Long: netrc-optional +Help: Use either .netrc or URL +Mutexed: netrc +See-also: netrc-file +--- +Very similar to --netrc, but this option makes the .netrc usage \fBoptional\fP +and not mandatory as the --netrc option does. diff --git a/docs/cmdline-opts/netrc.d b/docs/cmdline-opts/netrc.d new file mode 100644 index 000000000..2df26782c --- /dev/null +++ b/docs/cmdline-opts/netrc.d @@ -0,0 +1,17 @@ +Long: netrc +Short: n +Help: Must read .netrc for user name and password +--- +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" diff --git a/docs/cmdline-opts/no-alpn.d b/docs/cmdline-opts/no-alpn.d index 46cd68bc0..88abb8368 100644 --- a/docs/cmdline-opts/no-alpn.d +++ b/docs/cmdline-opts/no-alpn.d @@ -1,9 +1,7 @@ -Short: Long: no-alpn -Tags: +Tags: HTTP/2 Protocols: HTTPS Added: 7.36.0 -Mutexed: See-also: no-npn http2 Requires: TLS Help: Disable the ALPN TLS extension diff --git a/docs/cmdline-opts/no-buffer.d b/docs/cmdline-opts/no-buffer.d new file mode 100644 index 000000000..65a6282f6 --- /dev/null +++ b/docs/cmdline-opts/no-buffer.d @@ -0,0 +1,11 @@ +Long: no-buffer +Short: N +Help: Disable buffering of the output stream +--- +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. diff --git a/docs/cmdline-opts/no-keepalive.d b/docs/cmdline-opts/no-keepalive.d new file mode 100644 index 000000000..7eb3d639c --- /dev/null +++ b/docs/cmdline-opts/no-keepalive.d @@ -0,0 +1,8 @@ +Long: no-keepalive +Help: Disable TCP keepalive on the connection +--- +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. diff --git a/docs/cmdline-opts/no-npn.d b/docs/cmdline-opts/no-npn.d index 5ccfe33a9..ab0f6de2e 100644 --- a/docs/cmdline-opts/no-npn.d +++ b/docs/cmdline-opts/no-npn.d @@ -1,6 +1,5 @@ -Short: Long: no-npn -Tags: Versions +Tags: Versions HTTP/2 Protocols: HTTPS Added: 7.36.0 Mutexed: diff --git a/docs/cmdline-opts/no-sessionid.d b/docs/cmdline-opts/no-sessionid.d new file mode 100644 index 000000000..397a15869 --- /dev/null +++ b/docs/cmdline-opts/no-sessionid.d @@ -0,0 +1,13 @@ +Long: no-sessionid +Help: Disable SSL session-ID reusing +Protocols: TLS +Added: 7.16.0 +--- +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. diff --git a/docs/cmdline-opts/noproxy.d b/docs/cmdline-opts/noproxy.d new file mode 100644 index 000000000..4f06d9f5d --- /dev/null +++ b/docs/cmdline-opts/noproxy.d @@ -0,0 +1,11 @@ +Long: noproxy +Arg: +Help: List of hosts which do not use proxy +Added: 7.19.4 +--- +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. diff --git a/docs/cmdline-opts/ntlm-wb.d b/docs/cmdline-opts/ntlm-wb.d new file mode 100644 index 000000000..7b9338408 --- /dev/null +++ b/docs/cmdline-opts/ntlm-wb.d @@ -0,0 +1,7 @@ +Long: ntlm-wb +Help: Use HTTP NTLM authentication with winbind +Protocols: HTTP +See-also: ntlm proxy-ntlm +--- +Enables NTLM much in the style --ntlm does, but hand over the authentication +to the separate binary ntlmauth application that is executed when needed. diff --git a/docs/cmdline-opts/ntlm.d b/docs/cmdline-opts/ntlm.d new file mode 100644 index 000000000..d71cd43fe --- /dev/null +++ b/docs/cmdline-opts/ntlm.d @@ -0,0 +1,18 @@ +Long: ntlm +Help: Use HTTP NTLM authentication +Mutexed: basic negotiated digest anyauth +See-also: proxy-ntlm +Protocols: HTTP +Requires: TLS +--- +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 +--proxy-ntlm. + +If this option is used several times, only the first one is used. diff --git a/docs/cmdline-opts/oauth2-bearer.d b/docs/cmdline-opts/oauth2-bearer.d new file mode 100644 index 000000000..adad532c7 --- /dev/null +++ b/docs/cmdline-opts/oauth2-bearer.d @@ -0,0 +1,11 @@ +Long: oauth2-bearer +Help: OAuth 2 Bearer Token +Protocols: 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 --url or --user 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. diff --git a/docs/cmdline-opts/output.d b/docs/cmdline-opts/output.d new file mode 100644 index 000000000..35f52a213 --- /dev/null +++ b/docs/cmdline-opts/output.d @@ -0,0 +1,32 @@ +Long: output +Arg: +Short: o +Help: Write to file instead of stdout +See-also: remote-name remote-name-all remote-header-name +--- +Write output to instead of stdout. If you are using {} or [] to fetch +multiple documents, you can use '#' followed by a number in the +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 --create-dirs option to create the local directories +dynamically. Specifying the output as '-' (a single dash) will force the +output to be done to stdout. diff --git a/docs/cmdline-opts/pass.d b/docs/cmdline-opts/pass.d new file mode 100644 index 000000000..2639cb9d0 --- /dev/null +++ b/docs/cmdline-opts/pass.d @@ -0,0 +1,8 @@ +Long: pass +Arg: +Help: Pass phrase for the private key +Protocols: SSH TLS +--- +Passphrase for the private key + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/path-as-is.d b/docs/cmdline-opts/path-as-is.d new file mode 100644 index 000000000..946e2f07a --- /dev/null +++ b/docs/cmdline-opts/path-as-is.d @@ -0,0 +1,7 @@ +Long: path-as-is +Help: Do not squash .. sequences in URL path +Added: 7.42.0 +--- +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. diff --git a/docs/cmdline-opts/post301.d b/docs/cmdline-opts/post301.d new file mode 100644 index 000000000..edcaf8755 --- /dev/null +++ b/docs/cmdline-opts/post301.d @@ -0,0 +1,11 @@ +Long: post301 +Help: Do not switch to GET after following a 301 +Protocols: HTTP +See-also: post302 post303 location +Added: 7.17.1 +--- +Tells curl to respect RFC 7230/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 --location. diff --git a/docs/cmdline-opts/post302.d b/docs/cmdline-opts/post302.d new file mode 100644 index 000000000..6ea5f09bb --- /dev/null +++ b/docs/cmdline-opts/post302.d @@ -0,0 +1,11 @@ +Long: post302 +Help: Do not switch to GET after following a 302 +Protocols: HTTP +See-also: post301 post303 location +Added: 7.19.1 +--- +Tells curl to respect RFC 7230/6.4.2 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 --location. diff --git a/docs/cmdline-opts/post303.d b/docs/cmdline-opts/post303.d new file mode 100644 index 000000000..8b36c8211 --- /dev/null +++ b/docs/cmdline-opts/post303.d @@ -0,0 +1,11 @@ +Long: post303 +Help: Do not switch to GET after following a 303 +Protocols: HTTP +See-also: post302 post301 location +Added: 7.26.0 +--- +Tells curl to respect RFC 7230/6.4.2 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 --location. diff --git a/docs/cmdline-opts/proto-default.d b/docs/cmdline-opts/proto-default.d new file mode 100644 index 000000000..ccc3b85f3 --- /dev/null +++ b/docs/cmdline-opts/proto-default.d @@ -0,0 +1,18 @@ +Long: proto-default +Help: Use PROTOCOL for any URL missing a scheme +Arg: +Added: 7.45.0 +--- +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 --url for +details. diff --git a/docs/cmdline-opts/proto-redir.d b/docs/cmdline-opts/proto-redir.d new file mode 100644 index 000000000..c9eeeab1d --- /dev/null +++ b/docs/cmdline-opts/proto-redir.d @@ -0,0 +1,17 @@ +Long: proto-redir +Arg: +Help: Enable/disable PROTOCOLS on redirect +Added: 7.20.2 +--- +Tells curl to limit what protocols it may use on redirect. Protocols denied by +--proto 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. diff --git a/docs/cmdline-opts/proto.d b/docs/cmdline-opts/proto.d new file mode 100644 index 000000000..1513fdc05 --- /dev/null +++ b/docs/cmdline-opts/proto.d @@ -0,0 +1,43 @@ +Long: proto +Arg: +Help: Enable/disable PROTOCOLS +See-also: proto-redir proto-default +Added: 7.20.2 +--- +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 --proto -ftps +uses the default protocols, but disables ftps +.TP +.B --proto -all,https,+http +only enables http and https +.TP +.B --proto =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. diff --git a/docs/cmdline-opts/proxy-header.d b/docs/cmdline-opts/proxy-header.d new file mode 100644 index 000000000..1ef696bc7 --- /dev/null +++ b/docs/cmdline-opts/proxy-header.d @@ -0,0 +1,20 @@ +Long: proxy-header +Arg:
+Help: Pass custom header LINE to proxy +Protocols: HTTP +Added: 7.37.0 +--- +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 --header +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. diff --git a/docs/cmdline-opts/proxytunnel.d b/docs/cmdline-opts/proxytunnel.d new file mode 100644 index 000000000..3328dab69 --- /dev/null +++ b/docs/cmdline-opts/proxytunnel.d @@ -0,0 +1,9 @@ +Long: proxytunnel +Help: Operate through a HTTP proxy tunnel (using CONNECT) +See-also: proxy +--- +When an HTTP proxy is used --proxy, 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. diff --git a/docs/cmdline-opts/remote-name.d b/docs/cmdline-opts/remote-name.d new file mode 100644 index 000000000..9fed64bf4 --- /dev/null +++ b/docs/cmdline-opts/remote-name.d @@ -0,0 +1,21 @@ +Long: remote-name +Short: O +Help: Write output to a file named as the remote file +--- +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 --remote-header-name 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. -- cgit v1.2.3