diff options
Diffstat (limited to 'docs')
51 files changed, 625 insertions, 31 deletions
diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index d9f550f51..1ba00c83c 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -26,7 +26,6 @@ Each file has a set of meta-data and a body of text. Mutexed: (space separated list of options this overrides) Requires: (space separated list of features this option requires) See-also: (space separated list of related options) - Redirect: (option name to use instead) Help: (short text for the --help output for this option) --- (end of meta-data) diff --git a/docs/cmdline-opts/crlfile.d b/docs/cmdline-opts/crlfile.d index ae216b9e5..0fcc63c85 100644 --- a/docs/cmdline-opts/crlfile.d +++ b/docs/cmdline-opts/crlfile.d @@ -1,4 +1,4 @@ -Long: crfile +Long: crlfile Arg: <file> Protocols: TLS Help: Get a CRL list in PEM format from the given file diff --git a/docs/cmdline-opts/data-ascii.d b/docs/cmdline-opts/data-ascii.d index 52f80312c..bda4abc3d 100644 --- a/docs/cmdline-opts/data-ascii.d +++ b/docs/cmdline-opts/data-ascii.d @@ -2,4 +2,5 @@ Long: data-ascii Arg: <data> Help: HTTP POST ASCII data Protocols: HTTP -Redirect: data +--- +This is just an alias for --data. diff --git a/docs/cmdline-opts/disable-epsv.d b/docs/cmdline-opts/disable-epsv.d new file mode 100644 index 000000000..6d2cb7089 --- /dev/null +++ b/docs/cmdline-opts/disable-epsv.d @@ -0,0 +1,16 @@ +Long: disable-epsv +Help: Inhibit using EPSV +Protocols: 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 --disable-epsv. + +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 --ftp-port. diff --git a/docs/cmdline-opts/ftp-ssl-reqd.d b/docs/cmdline-opts/ftp-ssl-reqd.d deleted file mode 100644 index 2f8048463..000000000 --- a/docs/cmdline-opts/ftp-ssl-reqd.d +++ /dev/null @@ -1,3 +0,0 @@ -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 deleted file mode 100644 index aee48a1cb..000000000 --- a/docs/cmdline-opts/ftp-ssl.d +++ /dev/null @@ -1,3 +0,0 @@ -Long: ftp-ssl -Help: Try SSL/TLS -Redirect: ssl diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index ea6d7adf9..6fe24be1e 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -95,7 +95,6 @@ sub single { my $arg; my $mutexed; my $requires; - my $redirect; my $seealso; my $magic; # cmdline special option while(<F>) { @@ -129,9 +128,6 @@ sub single { elsif(/^Requires: *(.*)/i) { $requires=$1; } - elsif(/^Redirect: *(.*)/i) { - $redirect=$1; - } elsif(/^Help: *(.*)/i) { ; } @@ -174,14 +170,8 @@ sub single { else { print ".IP \"$opt\"\n"; } - if($redirect) { - my $l = manpageify($redirect); - print "Use $l instead!\n"; - } - else { - if($protocols) { - print protocols($standalone, $protocols); - } + if($protocols) { + print protocols($standalone, $protocols); } if($standalone) { diff --git a/docs/cmdline-opts/header.d b/docs/cmdline-opts/header.d index 762334fe4..90af7359e 100644 --- a/docs/cmdline-opts/header.d +++ b/docs/cmdline-opts/header.d @@ -31,9 +31,8 @@ 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. +after redirects are followed, like when told with --location. 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/help.d b/docs/cmdline-opts/help.d new file mode 100644 index 000000000..64aa696d4 --- /dev/null +++ b/docs/cmdline-opts/help.d @@ -0,0 +1,6 @@ +Long: help +Short: h +Help: This help text +--- +Usage help. This lists all current command line options with a short +description. diff --git a/docs/cmdline-opts/krb4.d b/docs/cmdline-opts/krb4.d deleted file mode 100644 index 79bab81b9..000000000 --- a/docs/cmdline-opts/krb4.d +++ /dev/null @@ -1,2 +0,0 @@ -Long: krb4 -Redirect: krb diff --git a/docs/cmdline-opts/login-options.d b/docs/cmdline-opts/login-options.d index ea2af082d..8bad0511d 100644 --- a/docs/cmdline-opts/login-options.d +++ b/docs/cmdline-opts/login-options.d @@ -1,6 +1,7 @@ Long: login-options Arg: <options> Protocols: IMAP POP3 SMTP +Help: Server login options Added: 7.34.0 --- Specify the login options to use during server authentication. diff --git a/docs/cmdline-opts/manual.d b/docs/cmdline-opts/manual.d new file mode 100644 index 000000000..a9dbb0c78 --- /dev/null +++ b/docs/cmdline-opts/manual.d @@ -0,0 +1,5 @@ +Long: manual +Short: M +Help: Display the full manual +--- +Manual. Display the huge help text. diff --git a/docs/cmdline-opts/progress-bar.d b/docs/cmdline-opts/progress-bar.d index 360690c17..11e95b45e 100644 --- a/docs/cmdline-opts/progress-bar.d +++ b/docs/cmdline-opts/progress-bar.d @@ -1,6 +1,6 @@ Short: # Long: progress-bar -Help: Disable the ALPN TLS extension +Help: Display transfer progress as a bar --- Make curl display transfer progress as a simple progress bar instead of the standard, more informational, meter. diff --git a/docs/cmdline-opts/proxy-cert-type.d b/docs/cmdline-opts/proxy-cert-type.d new file mode 100644 index 000000000..8c9e7889b --- /dev/null +++ b/docs/cmdline-opts/proxy-cert-type.d @@ -0,0 +1,6 @@ +Long: proxy-cert-type +Arg: <type> +Added: 7.52.0 +Help: Client certificate type for HTTS proxy +--- +Same as --cert-type but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-cert.d b/docs/cmdline-opts/proxy-cert.d index 495296b14..43acd3950 100644 --- a/docs/cmdline-opts/proxy-cert.d +++ b/docs/cmdline-opts/proxy-cert.d @@ -1,6 +1,6 @@ Long: proxy-cert Arg: <cert[:passwd]> -Help: Client certificate file and password for proxy +Help: Set client certificate for proxy Added: 7.52.0 --- Same as --cert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-ssl-allow-beast.d b/docs/cmdline-opts/proxy-ssl-allow-beast.d index 6b25892f5..de96b8436 100644 --- a/docs/cmdline-opts/proxy-ssl-allow-beast.d +++ b/docs/cmdline-opts/proxy-ssl-allow-beast.d @@ -1,5 +1,5 @@ Long: proxy-ssl-allow-beast -Help: Allow security flaw to improve interop for HTTPS proxy +Help: Allow security flaw for interop for HTTPS proxy Added: 7.52.0 --- Same as --ssl-allow-beast but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-user.d b/docs/cmdline-opts/proxy-user.d new file mode 100644 index 000000000..b1f6f6e03 --- /dev/null +++ b/docs/cmdline-opts/proxy-user.d @@ -0,0 +1,12 @@ +Long: proxy-user +Short: U +Arg: <user:password> +Help: Proxy user and 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. diff --git a/docs/cmdline-opts/proxy.d b/docs/cmdline-opts/proxy.d new file mode 100644 index 000000000..377a51aab --- /dev/null +++ b/docs/cmdline-opts/proxy.d @@ -0,0 +1,34 @@ +Long: proxy +Short: x +Arg: [protocol://]host[:port] +Help: Use this proxy +--- +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 --proxytunnel 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. diff --git a/docs/cmdline-opts/proxytunnel.d b/docs/cmdline-opts/proxytunnel.d index 3328dab69..09855ed34 100644 --- a/docs/cmdline-opts/proxytunnel.d +++ b/docs/cmdline-opts/proxytunnel.d @@ -1,4 +1,5 @@ Long: proxytunnel +Short: p Help: Operate through a HTTP proxy tunnel (using CONNECT) See-also: proxy --- diff --git a/docs/cmdline-opts/referer.d b/docs/cmdline-opts/referer.d index dbecd785d..fe6557a25 100644 --- a/docs/cmdline-opts/referer.d +++ b/docs/cmdline-opts/referer.d @@ -1,4 +1,5 @@ Long: referer +Short: e Protocols: HTTP Help: Referer URL See-also: user-agent header diff --git a/docs/cmdline-opts/request.d b/docs/cmdline-opts/request.d new file mode 100644 index 000000000..3919d426a --- /dev/null +++ b/docs/cmdline-opts/request.d @@ -0,0 +1,39 @@ +Long: request +Short: X +Arg: <command> +Help: Specify request command to use +--- +(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 --head option. + +The method string you set with --request will be used for all requests, which +if you for example use --location 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. diff --git a/docs/cmdline-opts/show-error.d b/docs/cmdline-opts/show-error.d index fdc595681..ede174b7d 100644 --- a/docs/cmdline-opts/show-error.d +++ b/docs/cmdline-opts/show-error.d @@ -1,5 +1,5 @@ long: show-error Short: S -Help: Show error. With -s, make curl show errors when they occur +Help: Show error even when -s is used --- When used with --silent, it makes curl show an error message if it fails. diff --git a/docs/cmdline-opts/socks5-gssapi-nec.d b/docs/cmdline-opts/socks5-gssapi-nec.d new file mode 100644 index 000000000..477e218e3 --- /dev/null +++ b/docs/cmdline-opts/socks5-gssapi-nec.d @@ -0,0 +1,8 @@ +Long: socks5-gssapi-nec +Help: Compatibility with NEC SOCKS5 server +Added: 7.19.4 +--- +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 --socks5-gssapi-nec allows the +unprotected exchange of the protection mode negotiation. diff --git a/docs/cmdline-opts/socks5-gssapi-service.d b/docs/cmdline-opts/socks5-gssapi-service.d new file mode 100644 index 000000000..eb3b2407b --- /dev/null +++ b/docs/cmdline-opts/socks5-gssapi-service.d @@ -0,0 +1,12 @@ +Long: socks5-gssapi-service +Arg: <name> +Help: SOCKS5 proxy service name for GSS-API +Added: 7.19.4 +--- +The default service name for a socks server is rcmd/server-fqdn. This option +allows you to change it. + +Examples: --socks5 proxy-name --socks5-gssapi-service sockd would use +sockd/proxy-name --socks5 proxy-name --socks5-gssapi-service sockd/real-name +would use sockd/real-name for cases where the proxy-name does not match the +principal name. diff --git a/docs/cmdline-opts/speed-limit.d b/docs/cmdline-opts/speed-limit.d new file mode 100644 index 000000000..e2b81c79a --- /dev/null +++ b/docs/cmdline-opts/speed-limit.d @@ -0,0 +1,10 @@ +Long: speed-limit +Short: Y +Arg: <speed> +Help: Stop transfers slower than this +--- +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 --speed-time and is +30 if not set. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/speed-time.d b/docs/cmdline-opts/speed-time.d new file mode 100644 index 000000000..98d6ae13c --- /dev/null +++ b/docs/cmdline-opts/speed-time.d @@ -0,0 +1,13 @@ +Long: speed-time +Short: y +Arg: <seconds> +Help: Trigger 'speed-limit' abort after this time +--- +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 --speed-limit. + +This option controls transfers and thus will not affect slow connects etc. If +this is a concern for you, try the --connect-timeout option. + +If this option is used several times, the last one will be used. diff --git a/docs/cmdline-opts/stderr.d b/docs/cmdline-opts/stderr.d new file mode 100644 index 000000000..e8cf7ba68 --- /dev/null +++ b/docs/cmdline-opts/stderr.d @@ -0,0 +1,8 @@ +Long: stderr +Help: Where to redirect stderr +See-also: verbose silent +--- +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. diff --git a/docs/cmdline-opts/tcp-fastopen.d b/docs/cmdline-opts/tcp-fastopen.d new file mode 100644 index 000000000..08e141df7 --- /dev/null +++ b/docs/cmdline-opts/tcp-fastopen.d @@ -0,0 +1,5 @@ +Long: tcp-fastopen +Added: 7.49.0 +Help: Use TCP Fast Open +--- +Enable use of TCP Fast Open (RFC7413). diff --git a/docs/cmdline-opts/tcp-nodelay.d b/docs/cmdline-opts/tcp-nodelay.d new file mode 100644 index 000000000..0c0ddd068 --- /dev/null +++ b/docs/cmdline-opts/tcp-nodelay.d @@ -0,0 +1,9 @@ +Long: tcp-nodelay +Help: Use the TCP_NODELAY option +Added: 7.11.2 +--- +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. diff --git a/docs/cmdline-opts/telnet-option.d b/docs/cmdline-opts/telnet-option.d new file mode 100644 index 000000000..a67cb627b --- /dev/null +++ b/docs/cmdline-opts/telnet-option.d @@ -0,0 +1,12 @@ +Long: telnet-option +Short: t +Arg: <opt=val> +Help: Set telnet option +--- +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. diff --git a/docs/cmdline-opts/tftp-blksize.d b/docs/cmdline-opts/tftp-blksize.d new file mode 100644 index 000000000..04c6c53b6 --- /dev/null +++ b/docs/cmdline-opts/tftp-blksize.d @@ -0,0 +1,11 @@ +Long: tftp-blksize +Arg: <value> +help: Set TFTP BLKSIZE option +Protocols: TFTP +Added: 7.20.0 +--- +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. diff --git a/docs/cmdline-opts/tftp-no-options.d b/docs/cmdline-opts/tftp-no-options.d new file mode 100644 index 000000000..e2a4dacd5 --- /dev/null +++ b/docs/cmdline-opts/tftp-no-options.d @@ -0,0 +1,10 @@ +Long: tftp-no-options +Help: Do not send any TFTP options +Protocols: TFTP +Added: 7.48.0 +--- +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 --tftp-blksize is +ignored. diff --git a/docs/cmdline-opts/time-cond.d b/docs/cmdline-opts/time-cond.d new file mode 100644 index 000000000..830b4e1a2 --- /dev/null +++ b/docs/cmdline-opts/time-cond.d @@ -0,0 +1,17 @@ +Long: time-cond +Short: z +Arg: <time> +Help: Transfer based on a time condition +Protocols: 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. diff --git a/docs/cmdline-opts/tlsauthtype.d b/docs/cmdline-opts/tlsauthtype.d new file mode 100644 index 000000000..1b1481ffe --- /dev/null +++ b/docs/cmdline-opts/tlsauthtype.d @@ -0,0 +1,8 @@ +Long: tlsauthtype +Arg: <type> +Help: TLS authentication type +Added: 7.21.4 +--- +Set TLS authentication type. Currently, the only supported option is "SRP", +for TLS-SRP (RFC 5054). If --tlsuser and --tlspassword are specified but +--tlsauthtype is not, then this option defaults to "SRP". diff --git a/docs/cmdline-opts/tlspassword.d b/docs/cmdline-opts/tlspassword.d new file mode 100644 index 000000000..234a1168c --- /dev/null +++ b/docs/cmdline-opts/tlspassword.d @@ -0,0 +1,6 @@ +Long: tlspassword +Help: TLS password +Added: 7.21.4 +--- +Set password for use with the TLS authentication method specified with +--tlsauthtype. Requires that --tlsuser also be set. diff --git a/docs/cmdline-opts/tlsuser.d b/docs/cmdline-opts/tlsuser.d new file mode 100644 index 000000000..72f1e1667 --- /dev/null +++ b/docs/cmdline-opts/tlsuser.d @@ -0,0 +1,7 @@ +Long: tlsuser +Arg: <name> +Help: TLS user name +Added: 7.21.4 +--- +Set username for use with the TLS authentication method specified with +--tlsauthtype. Requires that --tlspassword also is set. diff --git a/docs/cmdline-opts/tlsv1.0.d b/docs/cmdline-opts/tlsv1.0.d new file mode 100644 index 000000000..8789025e0 --- /dev/null +++ b/docs/cmdline-opts/tlsv1.0.d @@ -0,0 +1,6 @@ +Long: tlsv1.0 +Help: Use TLSv1.0 +Protocols: TLS +Added: 7.34.0 +--- +Forces curl to use TLS version 1.0 when connecting to a remote TLS server. diff --git a/docs/cmdline-opts/tlsv1.1.d b/docs/cmdline-opts/tlsv1.1.d new file mode 100644 index 000000000..9bfdc3536 --- /dev/null +++ b/docs/cmdline-opts/tlsv1.1.d @@ -0,0 +1,6 @@ +Long: tlsv1.1 +Help: Use TLSv1.1 +Protocols: TLS +Added: 7.34.0 +--- +Forces curl to use TLS version 1.1 when connecting to a remote TLS server. diff --git a/docs/cmdline-opts/tlsv1.2.d b/docs/cmdline-opts/tlsv1.2.d new file mode 100644 index 000000000..6db94dc8d --- /dev/null +++ b/docs/cmdline-opts/tlsv1.2.d @@ -0,0 +1,6 @@ +Long: tlsv1.2 +Help: Use TLSv1.2 +Protocols: TLS +Added: 7.34.0 +--- +Forces curl to use TLS version 1.2 when connecting to a remote TLS server. diff --git a/docs/cmdline-opts/tlsv1.3.d b/docs/cmdline-opts/tlsv1.3.d new file mode 100644 index 000000000..7d9640e71 --- /dev/null +++ b/docs/cmdline-opts/tlsv1.3.d @@ -0,0 +1,9 @@ +Long: tlsv1.3 +Help: Use TLSv1.3 +Protocols: TLS +Added: 7.52.0 +--- +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. diff --git a/docs/cmdline-opts/tr-encoding.d b/docs/cmdline-opts/tr-encoding.d new file mode 100644 index 000000000..01bb62bb3 --- /dev/null +++ b/docs/cmdline-opts/tr-encoding.d @@ -0,0 +1,7 @@ +Long: tr-encoding +Added: 7.21.6 +Help: Request compressed transfer encoding +Protocols: HTTP +--- +Request a compressed Transfer-Encoding response using one of the algorithms +curl supports, and uncompress the data while receiving it. diff --git a/docs/cmdline-opts/trace-ascii.d b/docs/cmdline-opts/trace-ascii.d new file mode 100644 index 000000000..fceaa7126 --- /dev/null +++ b/docs/cmdline-opts/trace-ascii.d @@ -0,0 +1,14 @@ +Long: trace-ascii +Arg: <file> +Help: Like --trace, but without hex output +Mutexed: trace verbose +--- +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 --trace, 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. diff --git a/docs/cmdline-opts/trace-time.d b/docs/cmdline-opts/trace-time.d new file mode 100644 index 000000000..27dcc42cf --- /dev/null +++ b/docs/cmdline-opts/trace-time.d @@ -0,0 +1,5 @@ +Long: trace-time +Help: Add time stamps to trace/verbose output +Added: 7.14.0 +--- +Prepends a time stamp to each trace or verbose line that curl displays. diff --git a/docs/cmdline-opts/trace.d b/docs/cmdline-opts/trace.d new file mode 100644 index 000000000..334ea5ad6 --- /dev/null +++ b/docs/cmdline-opts/trace.d @@ -0,0 +1,11 @@ +Long: trace +Arg: <file> +Help: Write a debug trace to FILE +Mutexed: verbose trace-ascii +--- +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. diff --git a/docs/cmdline-opts/unix-socket.d b/docs/cmdline-opts/unix-socket.d new file mode 100644 index 000000000..812d20f3b --- /dev/null +++ b/docs/cmdline-opts/unix-socket.d @@ -0,0 +1,7 @@ +Long: unix-socket +Arg: <path> +Help: Connect through this Unix domain socket +Added: 7.40.0 +Protocols: HTTP +--- +Connect through this Unix domain socket, instead of using the network. diff --git a/docs/cmdline-opts/upload-file.d b/docs/cmdline-opts/upload-file.d new file mode 100644 index 000000000..6f01dbf35 --- /dev/null +++ b/docs/cmdline-opts/upload-file.d @@ -0,0 +1,33 @@ +Long: upload-file +Short: T +Arg: <file> +Help: Transfer local FILE to destination +--- +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 --upload-file for each URL on the command line. Each +--upload-file + URL pair specifies what to upload and to where. curl also +supports "globbing" of the --upload-file 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. diff --git a/docs/cmdline-opts/url.d b/docs/cmdline-opts/url.d new file mode 100644 index 000000000..c54e1ea85 --- /dev/null +++ b/docs/cmdline-opts/url.d @@ -0,0 +1,15 @@ +long: url +Arg: <url> +Help: URL to work with +--- +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 --proto-default for details. + +This option may be used any number of times. To control where this URL is +written, use the --output or the --remote-name options. diff --git a/docs/cmdline-opts/user.d b/docs/cmdline-opts/user.d new file mode 100644 index 000000000..439def348 --- /dev/null +++ b/docs/cmdline-opts/user.d @@ -0,0 +1,33 @@ +Long: user +Short: u +Arg: <user:password> +Help: Server user and password +--- +Specify the user name and password to use for server authentication. Overrides +--netrc and --netrc-optional. + +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. diff --git a/docs/cmdline-opts/version.d b/docs/cmdline-opts/version.d new file mode 100644 index 000000000..196a4a9f5 --- /dev/null +++ b/docs/cmdline-opts/version.d @@ -0,0 +1,58 @@ +Long: version +Short: V +Help: Show version number and quit +--- +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 diff --git a/docs/cmdline-opts/write-out.d b/docs/cmdline-opts/write-out.d new file mode 100644 index 000000000..bc0c3bbef --- /dev/null +++ b/docs/cmdline-opts/write-out.d @@ -0,0 +1,138 @@ +Long: write-out +Short: w +Arg: <format> +Help: Use output FORMAT after completion +--- +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--remote-name\fP or \fI--output\fP +option. It's most useful in combination with the \fI--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. The time will be +displayed with millisecond resolution. +.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. diff --git a/docs/cmdline-opts/xattr.d b/docs/cmdline-opts/xattr.d new file mode 100644 index 000000000..b7553daeb --- /dev/null +++ b/docs/cmdline-opts/xattr.d @@ -0,0 +1,8 @@ +Long: xattr +Help: Store metadata in extended file attributes +--- +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. |