From: Daniel Stenberg Date: Mon, 15 Sep 2025 08:33:19 +0000 (+0200) Subject: cmdline-docs: extended, clarified, refreshed X-Git-Tag: rc-8_17_0-1~386 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8de37b8cda7342e54615a9a840c076def155b023;p=thirdparty%2Fcurl.git cmdline-docs: extended, clarified, refreshed Closes #18550 --- diff --git a/docs/cmdline-opts/abstract-unix-socket.md b/docs/cmdline-opts/abstract-unix-socket.md index 7078e642fd..b1b6100e16 100644 --- a/docs/cmdline-opts/abstract-unix-socket.md +++ b/docs/cmdline-opts/abstract-unix-socket.md @@ -16,6 +16,6 @@ Example: # `--abstract-unix-socket` -Connect through an abstract Unix domain socket, instead of using the network. -Note: netstat shows the path of an abstract socket prefixed with `@`, however -the \ argument should not have this leading character. +Connect to the server through an abstract Unix domain socket, instead of using +the network. Note: netstat shows the path of an abstract socket prefixed with +`@`, however the \ argument should not have this leading character. diff --git a/docs/cmdline-opts/compressed-ssh.md b/docs/cmdline-opts/compressed-ssh.md index 955c59c2b7..07d3981b48 100644 --- a/docs/cmdline-opts/compressed-ssh.md +++ b/docs/cmdline-opts/compressed-ssh.md @@ -16,4 +16,5 @@ Example: # `--compressed-ssh` Enable SSH compression. This is a request, not an order; the server may or may -not do it. +not do it. This allows the data to be sent compressed over the wire, and +automatically decompressed in the receiving end, to save bandwidth. diff --git a/docs/cmdline-opts/disallow-username-in-url.md b/docs/cmdline-opts/disallow-username-in-url.md index 012f2d0dc8..0507f531cc 100644 --- a/docs/cmdline-opts/disallow-username-in-url.md +++ b/docs/cmdline-opts/disallow-username-in-url.md @@ -16,3 +16,6 @@ Example: Exit with error if passed a URL containing a username. Probably most useful when the URL is being provided at runtime or similar. + +Accepting and using credentials in a URL is normally considered a security +hazard as they are easily leaked that way. diff --git a/docs/cmdline-opts/engine.md b/docs/cmdline-opts/engine.md index 511190023e..cde6949b86 100644 --- a/docs/cmdline-opts/engine.md +++ b/docs/cmdline-opts/engine.md @@ -17,6 +17,9 @@ Example: # `--engine` -Select the OpenSSL crypto engine to use for cipher operations. Use --engine -list to print a list of build-time supported engines. Note that not all (and +Select the OpenSSL crypto engine to use for cipher operations. Use `--engine +list` to print a list of build-time supported engines. Note that not all (and possibly none) of the engines may be available at runtime. + +The OpenSSL concept "engines" has been superseded by "providers" in OpenSSL 3, +and this option should work fine to specify such as well. diff --git a/docs/cmdline-opts/follow.md b/docs/cmdline-opts/follow.md index 9d4225ab35..47d9128441 100644 --- a/docs/cmdline-opts/follow.md +++ b/docs/cmdline-opts/follow.md @@ -9,6 +9,8 @@ Multi: boolean See-also: - request - location + - proto-redir + - max-redirs Example: - -X POST --follow $URL --- @@ -23,3 +25,5 @@ status codes 307 or 308, but may be reset to GET for 301, 302 and 303. This is subtly different than --location, as that option always set the custom method in all subsequent requests independent of response code. + +Restrict which protocols a redirect is accepted to follow with --proto-redir. diff --git a/docs/cmdline-opts/globoff.md b/docs/cmdline-opts/globoff.md index 3c8c341439..5ef4b2ae88 100644 --- a/docs/cmdline-opts/globoff.md +++ b/docs/cmdline-opts/globoff.md @@ -20,3 +20,6 @@ Switch off the URL globbing function. When you set this option, you can specify URLs that contain the letters {}[] without having curl itself interpret them. Note that these letters are not normal legal URL contents but they should be encoded according to the URI standard. + +curl detects numerical IPv6 addresses when used in URLs and excludes them from +the treatment, so they can still be used without having to disable globbing. diff --git a/docs/cmdline-opts/http2.md b/docs/cmdline-opts/http2.md index ae4d26974c..f5180be2b5 100644 --- a/docs/cmdline-opts/http2.md +++ b/docs/cmdline-opts/http2.md @@ -14,6 +14,7 @@ See-also: - http1.1 - http3 - no-alpn + - proxy-http2 Example: - --http2 $URL --- diff --git a/docs/cmdline-opts/http3.md b/docs/cmdline-opts/http3.md index a66d797829..e4dfeef075 100644 --- a/docs/cmdline-opts/http3.md +++ b/docs/cmdline-opts/http3.md @@ -33,3 +33,5 @@ still tries to proceed with an older HTTP version. The fallback performs the regular negotiation between HTTP/1 and HTTP/2. Use --http3-only for similar functionality *without* a fallback. + +curl cannot do HTTP/3 over any proxy. diff --git a/docs/cmdline-opts/junk-session-cookies.md b/docs/cmdline-opts/junk-session-cookies.md index 63971050c0..668dfce2d6 100644 --- a/docs/cmdline-opts/junk-session-cookies.md +++ b/docs/cmdline-opts/junk-session-cookies.md @@ -18,5 +18,8 @@ Example: # `--junk-session-cookies` When curl is told to read cookies from a given file, this option makes it -discard all "session cookies". This has the same effect as if a new session is +discard all session cookies. This has the same effect as if a new session is started. Typical browsers discard session cookies when they are closed down. + +Session cookies are cookies without a set expiry time. They are meant to only +last for "a session". diff --git a/docs/cmdline-opts/location.md b/docs/cmdline-opts/location.md index 86ae7e3580..56950c2dfc 100644 --- a/docs/cmdline-opts/location.md +++ b/docs/cmdline-opts/location.md @@ -12,6 +12,8 @@ See-also: - resolve - alt-svc - follow + - proto-redir + - max-redirs Example: - -L $URL --- @@ -40,3 +42,5 @@ using the dedicated options for that: --post301, --post302 and --post303. The method set with --request overrides the method curl would otherwise select to use. + +Restrict which protocols a redirect is accepted to follow with --proto-redir. diff --git a/docs/cmdline-opts/max-redirs.md b/docs/cmdline-opts/max-redirs.md index 7c9f193d2c..02bdfaa7fb 100644 --- a/docs/cmdline-opts/max-redirs.md +++ b/docs/cmdline-opts/max-redirs.md @@ -10,12 +10,14 @@ Added: 7.5 Multi: single See-also: - location + - follow Example: - --max-redirs 3 --location $URL --- # `--max-redirs` -Set the maximum number of redirections to follow. When --location is used, to -prevent curl from following too many redirects, by default, the limit is -set to 50 redirects. Set this option to -1 to make it unlimited. +Set the maximum number of redirections to follow. When --location or --follow +are used, this option prevents curl from following too many redirects. By +default the limit is set to 50 redirects. Set this option to -1 to make it +unlimited. diff --git a/docs/cmdline-opts/proto-redir.md b/docs/cmdline-opts/proto-redir.md index 337aa93cb6..1f75bfdfd6 100644 --- a/docs/cmdline-opts/proto-redir.md +++ b/docs/cmdline-opts/proto-redir.md @@ -9,8 +9,9 @@ Category: connection curl Multi: single See-also: - proto + - follow Example: - - --proto-redir =http,https $URL + - --proto-redir =http,https --follow $URL --- # `--proto-redir` @@ -20,7 +21,7 @@ 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 + curl --proto-redir -all,http,https --follow http://example.com By default curl only allows HTTP, HTTPS, FTP and FTPS on redirects (added in 7.65.2). Specifying *all* or *+all* enables all protocols on diff --git a/docs/cmdline-opts/proxy.md b/docs/cmdline-opts/proxy.md index 1ed503c108..6cd456169d 100644 --- a/docs/cmdline-opts/proxy.md +++ b/docs/cmdline-opts/proxy.md @@ -31,8 +31,7 @@ HTTPS proxy support works with the https:// protocol prefix for OpenSSL and GnuTLS (added in 7.52.0). It also works for mbedTLS, Rustls, Schannel and wolfSSL (added in 7.87.0). -Unrecognized and unsupported proxy protocols cause an error (added in 7.52.0). -Ancient curl versions ignored unknown schemes and used http:// instead. +Unrecognized and unsupported proxy protocol schemes cause an error. If the port number is not specified in the proxy string, it is assumed to be 1080. diff --git a/docs/cmdline-opts/request.md b/docs/cmdline-opts/request.md index 86cf10deaf..2c9d7776e5 100644 --- a/docs/cmdline-opts/request.md +++ b/docs/cmdline-opts/request.md @@ -10,8 +10,9 @@ Added: 6.0 Multi: single See-also: - request-target + - follow Example: - - -X "DELETE" $URL + - --request "DELETE" $URL - -X NLST ftp://example.com/ --- @@ -37,10 +38,10 @@ This option only changes the actual word used in the HTTP request, it does not alter the way curl behaves. For example if you want to make a proper HEAD request, using -X HEAD does not suffice. You need to use the --head option. -The method string you set with --request is used for all requests, which -if you for example use --location may cause unintended side-effects when curl -does not change request method according to the HTTP 30x response codes - and -similar. +If --location is used, the method string you set with --request is used for +all requests, which may cause unintended side-effects when curl does not +change request method according to the HTTP 30x response codes - and similar. +Consider using --follow instead in combination with --request. ## FTP Specifies a custom FTP command to use instead of *LIST* when doing file lists diff --git a/docs/cmdline-opts/retry-connrefused.md b/docs/cmdline-opts/retry-connrefused.md index 22345cd881..2e6ba80686 100644 --- a/docs/cmdline-opts/retry-connrefused.md +++ b/docs/cmdline-opts/retry-connrefused.md @@ -15,5 +15,7 @@ Example: # `--retry-connrefused` -In addition to the other conditions, consider ECONNREFUSED as a transient -error too for --retry. This option is used together with --retry. +In addition to the other conditions, also consider ECONNREFUSED as a transient +error for --retry. This option is used together with --retry. Normally, a +confused connection is not considered a transient error and therefore thus not +otherwise trigger a retry. diff --git a/docs/cmdline-opts/retry.md b/docs/cmdline-opts/retry.md index 2176e8f43d..f55d8edcca 100644 --- a/docs/cmdline-opts/retry.md +++ b/docs/cmdline-opts/retry.md @@ -9,6 +9,8 @@ Category: curl Multi: single See-also: - retry-max-time + - retry-connrefused + - retry-delay Example: - --retry 7 $URL --- @@ -16,16 +18,17 @@ Example: # `--retry` If a transient error is returned when curl tries to perform a transfer, it -retries this number of times before giving up. Setting the number to 0 -makes curl do no retries (which is the default). Transient error means either: -a timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504 +retries this number of times before giving up. Setting the number to 0 makes +curl do no retries (which is the default). Transient error means either: a +timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504 response code. When curl is about to retry a transfer, it first waits one second and then for all forthcoming retries it doubles the waiting time until it reaches 10 minutes, which then remains the set fixed delay time between the rest of the -retries. By using --retry-delay you disable this exponential backoff algorithm. -See also --retry-max-time to limit the total time allowed for retries. +retries. By using --retry-delay you disable this exponential backoff +algorithm. See also --retry-max-time to limit the total time allowed for +retries. curl complies with the Retry-After: response header if one was present to know when to issue the next retry (added in 7.66.0). diff --git a/docs/cmdline-opts/sasl-ir.md b/docs/cmdline-opts/sasl-ir.md index b11137df0a..0f759c6d10 100644 --- a/docs/cmdline-opts/sasl-ir.md +++ b/docs/cmdline-opts/sasl-ir.md @@ -14,4 +14,6 @@ Example: # `--sasl-ir` -Enable initial response in SASL authentication. +Enable initial response in SASL authentication. Such an "initial response" is +a message sent by the client to the server after the client selects an +authentication mechanism. diff --git a/docs/cmdline-opts/tr-encoding.md b/docs/cmdline-opts/tr-encoding.md index cdd8f02d67..c364c07d4b 100644 --- a/docs/cmdline-opts/tr-encoding.md +++ b/docs/cmdline-opts/tr-encoding.md @@ -17,3 +17,8 @@ Example: Request a compressed Transfer-Encoding response using one of the algorithms curl supports, and uncompress the data while receiving it. + +This method was once intended to be the way to do automatic data compression +for HTTP but for all practical purposes using Content-Encoding as done with +--compressed has superseded transfer encoding. The --tr-encoding option is +therefore often not be one you want. diff --git a/docs/cmdline-opts/trace-ids.md b/docs/cmdline-opts/trace-ids.md index b9a6222600..302631d844 100644 --- a/docs/cmdline-opts/trace-ids.md +++ b/docs/cmdline-opts/trace-ids.md @@ -18,3 +18,7 @@ Example: Prepend the transfer and connection identifiers to each trace or verbose line that curl displays. + +The identifiers are unique numbers assigned to each connection and transfer to +allow a user to better understand which transfer and connection each verbose +output line refers to. diff --git a/docs/cmdline-opts/unix-socket.md b/docs/cmdline-opts/unix-socket.md index 582f32dc50..34cc714f79 100644 --- a/docs/cmdline-opts/unix-socket.md +++ b/docs/cmdline-opts/unix-socket.md @@ -16,4 +16,7 @@ Example: # `--unix-socket` -Connect through this Unix domain socket, instead of using the network. +Connect to the server through this Unix domain socket, instead of using the +network. + +To connect to a proxy over Unix domain socket, see --proxy.