From: Daniel Stenberg Date: Fri, 8 Sep 2023 12:32:29 +0000 (+0200) Subject: cmdline-docs: use present tense, not future X-Git-Tag: curl-8_3_0~14 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4600bd3993619048feb513fb1ada8aad40e9b557;p=thirdparty%2Fcurl.git cmdline-docs: use present tense, not future + some smaller cleanups Closes #11821 --- diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words index 4308c90f2d..11be5ba76e 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -634,6 +634,7 @@ Relatedly repo reprioritized resending +resends RETR retransmit retrigger diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index 541d7806bf..6de32dab94 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -45,19 +45,19 @@ Each file has a set of meta-data and a body of text. ### Body The body of the description. Only refer to options with their long form option -version, like `--verbose`. The output generator will replace such with the +version, like `--verbose`. The output generator replaces such option with the correct markup that shows both short and long version. -Text written within `*asterisks*` will get shown using italics. Text within -two `**asterisks**` will get shown using bold. +Text written within `*asterisks*` is shown using italics. Text within two +`**asterisks**` is shown using bold. -Text that is prefixed with a space will be treated like an "example" and will -be output in monospace. +Text that is prefixed with a space is treated like an "example" and gets +output in monospace. ## Header and footer -`page-header` is the file that will be output before the generated options -output for the master man page. +`page-header` is the file that is output before the generated options output +for the master man page. `page-footer` is appended after all the individual options. diff --git a/docs/cmdline-opts/alt-svc.d b/docs/cmdline-opts/alt-svc.d index b505311e23..276ac1b669 100644 --- a/docs/cmdline-opts/alt-svc.d +++ b/docs/cmdline-opts/alt-svc.d @@ -11,11 +11,11 @@ Example: --alt-svc svc.txt $URL Multi: append --- This option enables the alt-svc parser in curl. If the file name points to an -existing alt-svc cache file, that will be used. After a completed transfer, -the cache will be saved to the file name again if it has been modified. +existing alt-svc cache file, that gets used. After a completed transfer, the +cache is saved to the file name again if it has been modified. Specify a "" file name (zero length) to avoid loading/saving and make curl just handle the cache in memory. -If this option is used several times, curl will load contents from all the -files but the last one will be used for saving. +If this option is used several times, curl loads contents from all the +files but the last one is used for saving. diff --git a/docs/cmdline-opts/anyauth.d b/docs/cmdline-opts/anyauth.d index 1d0c3956b7..2498bdcd84 100644 --- a/docs/cmdline-opts/anyauth.d +++ b/docs/cmdline-opts/anyauth.d @@ -17,7 +17,6 @@ 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. +the need should arise when uploading from stdin, the upload operation fails. Used together with --user. diff --git a/docs/cmdline-opts/append.d b/docs/cmdline-opts/append.d index d478aaceaf..7561c951c5 100644 --- a/docs/cmdline-opts/append.d +++ b/docs/cmdline-opts/append.d @@ -10,6 +10,7 @@ Example: --upload-file local --append ftp://example.com/ Added: 4.8 Multi: boolean --- -When used in an upload, this makes curl append to the target file instead of -overwriting it. If the remote file does not exist, it will be created. Note -that this flag is ignored by some SFTP servers (including OpenSSH). +When used in an upload, this option makes curl append to the target file +instead of overwriting it. If the remote file does not exist, it is +created. Note that this flag is ignored by some SFTP servers (including +OpenSSH). diff --git a/docs/cmdline-opts/ca-native.d b/docs/cmdline-opts/ca-native.d index 30b068a32a..51e36918aa 100644 --- a/docs/cmdline-opts/ca-native.d +++ b/docs/cmdline-opts/ca-native.d @@ -10,10 +10,12 @@ Added: 8.2.0 Multi: boolean --- Tells curl to use the CA store from the native operating system to verify the -peer. By default, curl will otherwise use a CA store provided in a single file -or directory, but when using this option it will interface the operating -system's own vault. +peer. By default, curl otherwise uses a CA store provided in a single file or +directory, but when using this option it interfaces the operating system's +own vault. This option only works for curl on Windows when built to use OpenSSL. When curl on Windows is built to use Schannel, this feature is implied and curl then only uses the native CA store. + +curl built with wolfSSL also supports this option (added in 8.3.0). diff --git a/docs/cmdline-opts/cacert.d b/docs/cmdline-opts/cacert.d index 8a54b2e243..5e4e74901e 100644 --- a/docs/cmdline-opts/cacert.d +++ b/docs/cmdline-opts/cacert.d @@ -19,15 +19,15 @@ 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 +The windows version of curl automatically looks 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. (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. +should not be set. If the option is not set, then curl uses the certificates +in the system and user Keychain to verify the peer, which is the preferred +method of verifying the peer's certificate chain. (Schannel only) This option is supported for Schannel in Windows 7 or later (added in 7.60.0). This option is supported for backward compatibility with diff --git a/docs/cmdline-opts/capath.d b/docs/cmdline-opts/capath.d index a6753adab8..75e9f2e400 100644 --- a/docs/cmdline-opts/capath.d +++ b/docs/cmdline-opts/capath.d @@ -18,4 +18,4 @@ 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. +If this option is set, the default capath value is ignored. diff --git a/docs/cmdline-opts/cert.d b/docs/cmdline-opts/cert.d index d5493900de..56d0df7fdf 100644 --- a/docs/cmdline-opts/cert.d +++ b/docs/cmdline-opts/cert.d @@ -14,7 +14,7 @@ Multi: single 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 is not specified, it will be queried for on +engine. If the optional password is not specified, it is 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. @@ -26,10 +26,10 @@ escape character. If curl is built against OpenSSL library, and the engine pkcs11 is available, then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in -a PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a -PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option will be set -as "pkcs11" if none was provided and the --cert-type option will be set as -"ENG" if none was provided. +a PKCS#11 device. A string beginning with "pkcs11:" is interpreted as a +PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option is set as +"pkcs11" if none was provided and the --cert-type option is set as "ENG" if +none was provided. (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 diff --git a/docs/cmdline-opts/compressed.d b/docs/cmdline-opts/compressed.d index 7dadf1401d..bb1d3baa74 100644 --- a/docs/cmdline-opts/compressed.d +++ b/docs/cmdline-opts/compressed.d @@ -16,6 +16,6 @@ Response headers are not modified when saved, so if they are "interpreted" separately again at a later point they might appear to be saying that the content is (still) compressed; while in fact it has already been decompressed. -If this option is used and the server sends an unsupported encoding, curl will -report an error. This is a request, not an order; the server may or may not +If this option is used and the server sends an unsupported encoding, curl +reports an error. This is a request, not an order; the server may or may not deliver data compressed. diff --git a/docs/cmdline-opts/config.d b/docs/cmdline-opts/config.d index 0ea920f325..c22a827f61 100644 --- a/docs/cmdline-opts/config.d +++ b/docs/cmdline-opts/config.d @@ -11,7 +11,7 @@ See-also: disable Multi: append --- Specify a text file to read curl arguments from. The command line arguments -found in the text file will be used as if they were provided on the command +found in the text file are used as if they were provided on the command line. Options and their parameters must be specified on the same line in the file, @@ -27,7 +27,7 @@ quotes the following escape sequences are available: \\\\, \\", \\t, \\n, \\r and \\v. A backslash preceding any other letter is ignored. If the first non-blank column of a config line is a '#' character, that line -will be treated as a comment. +is treated as a comment. Only write one option per physical line in the config file. A single line is required to be no more than 10 megabytes (since 8.2.0). diff --git a/docs/cmdline-opts/connect-timeout.d b/docs/cmdline-opts/connect-timeout.d index bfeb19068b..b3d19b3c33 100644 --- a/docs/cmdline-opts/connect-timeout.d +++ b/docs/cmdline-opts/connect-timeout.d @@ -12,7 +12,7 @@ Multi: single --- 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. +continues - if not it exits. This option accepts decimal values (added in 7.32.0). The decimal value needs to be provided using a dot (.) as decimal separator - not the local version diff --git a/docs/cmdline-opts/continue-at.d b/docs/cmdline-opts/continue-at.d index 9f91c44c80..a4fc1a9695 100644 --- a/docs/cmdline-opts/continue-at.d +++ b/docs/cmdline-opts/continue-at.d @@ -12,9 +12,9 @@ Added: 4.8 Multi: single --- 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 +is the exact number of bytes that are 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. +uploads, the FTP server command SIZE is not 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. diff --git a/docs/cmdline-opts/cookie-jar.d b/docs/cmdline-opts/cookie-jar.d index 1dfd10a159..28738cac94 100644 --- a/docs/cmdline-opts/cookie-jar.d +++ b/docs/cmdline-opts/cookie-jar.d @@ -14,19 +14,18 @@ Multi: single --- Specify to which file you want curl to write all cookies after a completed operation. Curl writes all cookies from its in-memory cookie storage to the -given file at the end of operations. If no cookies are known, no data will be -written. The file will be written using the Netscape cookie file format. If -you set the file name to a single dash, "-", the cookies will be written to -stdout. +given file at the end of operations. If no cookies are known, no data is +written. The file is created using the Netscape cookie file format. If you set +the file name to a single dash, "-", the cookies are written to stdout. -The file specified with --cookie-jar is only used for output. No cookies will -be read from the file. To read cookies, use the --cookie option. Both options +The file specified with --cookie-jar is only used for output. No cookies are +read from the file. To read cookies, use the --cookie option. Both options can specify the same file. -This command line option will activate the cookie engine that makes curl -record and use cookies. The --cookie option also activates it. +This command line option activates the cookie engine that makes curl record +and use cookies. The --cookie option also activates it. If the cookie jar cannot be created or written to, the whole curl operation -will not fail or even report an error clearly. Using --verbose will get a -warning displayed, but that is the only visible feedback you get about this -possibly lethal situation. +does not fail or even report an error clearly. Using --verbose gets a warning +displayed, but that is the only visible feedback you get about this possibly +lethal situation. diff --git a/docs/cmdline-opts/cookie.d b/docs/cmdline-opts/cookie.d index 47d105be55..0f858d6613 100644 --- a/docs/cmdline-opts/cookie.d +++ b/docs/cmdline-opts/cookie.d @@ -17,25 +17,25 @@ data previously received from the server in a "Set-Cookie:" line. The data should be in the format "NAME1=VALUE1; NAME2=VALUE2". This makes curl use the cookie header with this content explicitly in all outgoing request(s). If multiple requests are done due to authentication, followed redirects or -similar, they will all get this cookie passed on. +similar, they all get this cookie passed on. If no '=' symbol is used in the argument, it is instead treated as a filename to read previously stored cookie from. This option also activates the cookie -engine which will make curl record incoming cookies, which may be handy if -you are using this in combination with the --location option or do multiple URL +engine which makes curl record incoming cookies, which may be handy if you are +using this in combination with the --location option or do multiple URL transfers on the same invoke. If the file name is exactly a minus ("-"), curl -will instead read the contents from stdin. +instead reads the contents from stdin. The file format of the file to read cookies from should be plain HTTP headers (Set-Cookie style) or the Netscape/Mozilla cookie file format. -The file specified with --cookie is only used as input. No cookies will be -written to the file. To store cookies, use the --cookie-jar option. +The file specified with --cookie is only used as input. No cookies are written +to the file. To store cookies, use the --cookie-jar option. If you use the Set-Cookie file format and do not specify a domain then the -cookie is not sent since the domain will never match. To address this, set a -domain in Set-Cookie line (doing that will include subdomains) or preferably: -use the Netscape format. +cookie is not sent since the domain never matches. To address this, set a +domain in Set-Cookie line (doing that includes subdomains) or preferably: use +the Netscape format. Users often want to both read cookies from a file and write updated cookies back to a file, so using both --cookie and --cookie-jar in the same command diff --git a/docs/cmdline-opts/create-dirs.d b/docs/cmdline-opts/create-dirs.d index 06962b5652..f137e7d10d 100644 --- a/docs/cmdline-opts/create-dirs.d +++ b/docs/cmdline-opts/create-dirs.d @@ -8,11 +8,11 @@ Added: 7.10.3 See-also: ftp-create-dirs output-dir Multi: boolean --- -When used in conjunction with the --output option, curl will create the -necessary local directory hierarchy as needed. This option creates the -directories mentioned with the --output option, nothing else. If the --output -file name uses no directory, or if the directories it mentions already exist, -no directories will be created. +When used in conjunction with the --output option, curl creates the necessary +local directory hierarchy as needed. This option creates the directories +mentioned with the --output option, nothing else. If the --output file name +uses no directory, or if the directories it mentions already exist, no +directories are created. Created directories are made with mode 0750 on unix style file systems. diff --git a/docs/cmdline-opts/curves.d b/docs/cmdline-opts/curves.d index ffc83ab288..58d472d20d 100644 --- a/docs/cmdline-opts/curves.d +++ b/docs/cmdline-opts/curves.d @@ -19,5 +19,4 @@ in the "openssl s_client/s_server" utilities. the (EC) curve requested by the client, avoiding nontransparent client/server negotiations. -If this option is set, the default curves list built into OpenSSL will be -ignored. +If this option is set, the default curves list built into OpenSSL are ignored. diff --git a/docs/cmdline-opts/data-binary.d b/docs/cmdline-opts/data-binary.d index e966501800..2cedda97b0 100644 --- a/docs/cmdline-opts/data-binary.d +++ b/docs/cmdline-opts/data-binary.d @@ -21,5 +21,5 @@ application/x-www-form-urlencoded. If you want the data to be treated as arbitrary binary data by the server then set the content-type to octet-stream: -H "Content-Type: application/octet-stream". -If this option is used several times, the ones following the first will append +If this option is used several times, the ones following the first append data as described in --data. diff --git a/docs/cmdline-opts/data-urlencode.d b/docs/cmdline-opts/data-urlencode.d index c1bc735f75..3c436b26b1 100644 --- a/docs/cmdline-opts/data-urlencode.d +++ b/docs/cmdline-opts/data-urlencode.d @@ -21,20 +21,20 @@ by a separator and a content specification. The 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 does not contain any = or @ symbols, as that will then make +This makes curl URL-encode the content and pass that on. Just be careful +so that the content does not contain any = or @ symbols, as that makes 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 = +This makes 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 +This makes 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), +This makes 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), +This makes 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 *name=urlencoded-file-content*. Note that the name is expected to be URL-encoded already. diff --git a/docs/cmdline-opts/data.d b/docs/cmdline-opts/data.d index ff8a3b0b62..f1d67b9506 100644 --- a/docs/cmdline-opts/data.d +++ b/docs/cmdline-opts/data.d @@ -16,7 +16,7 @@ Multi: append --- 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 +submit button. This makes curl 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 @@ -25,7 +25,7 @@ the @ character. To post data purely binary, you should instead use the --data-urlencode. If any of these options is used more than once on the same command line, the -data pieces specified will be merged with a separating &-symbol. Thus, using +data pieces specified are merged with a separating &-symbol. Thus, using '-d name=daniel -d skill=lousy' would generate a post chunk that looks like 'name=daniel&skill=lousy'. @@ -33,9 +33,9 @@ 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. Posting data from a file named 'foobar' would thus be done with --data @foobar. When --data is told to read from a file like that, carriage returns and newlines -will be stripped out. If you do not want the @ character to have a special +are stripped out. If you do not want the @ character to have a special interpretation use --data-raw instead. The data for this option is passed on to the server exactly as provided on the -command line. curl will not convert it, change it or improve it. It is up to -the user to provide the data in the correct form. +command line. curl does not convert, change or improve it. It is up to the +user to provide the data in the correct form. diff --git a/docs/cmdline-opts/disable-eprt.d b/docs/cmdline-opts/disable-eprt.d index 4863d9d244..b6d382bafa 100644 --- a/docs/cmdline-opts/disable-eprt.d +++ b/docs/cmdline-opts/disable-eprt.d @@ -10,17 +10,16 @@ See-also: disable-epsv ftp-port Multi: boolean --- 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. +FTP transfers. Curl normally first attempts to use EPRT before using PORT, but +with this option, it uses PORT right away. EPRT is an extension to the +original FTP protocol, and does not work on all servers, but enables 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. +If the server is accessed using IPv6, this option has 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/disable-epsv.d b/docs/cmdline-opts/disable-epsv.d index bcc38db33f..f02df763da 100644 --- a/docs/cmdline-opts/disable-epsv.d +++ b/docs/cmdline-opts/disable-epsv.d @@ -10,14 +10,14 @@ See-also: disable-eprt ftp-port Multi: boolean --- 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. +transfers. Curl normally first attempts to use EPSV before PASV, but with this +option, it does not try 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. +If the server is an IPv6 host, this option has 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/disable.d b/docs/cmdline-opts/disable.d index 8d8ac54df5..979c039915 100644 --- a/docs/cmdline-opts/disable.d +++ b/docs/cmdline-opts/disable.d @@ -10,8 +10,8 @@ See-also: config Multi: boolean --- If used as the **first** parameter on the command line, the *curlrc* config -file will not be read and used. See the --config for details on the default -config file search path. +file is not read or used. See the --config for details on the default config +file search path. Prior to 7.50.0 curl supported the short option name *q* but not the long option name *disable*. diff --git a/docs/cmdline-opts/doh-url.d b/docs/cmdline-opts/doh-url.d index 6809ccf743..6d0dd1605e 100644 --- a/docs/cmdline-opts/doh-url.d +++ b/docs/cmdline-opts/doh-url.d @@ -12,10 +12,10 @@ Multi: single Specifies which DNS-over-HTTPS (DoH) server to use to resolve hostnames, instead of using the default name resolver mechanism. The URL must be HTTPS. -Some SSL options that you set for your transfer will apply to DoH since the +Some SSL options that you set for your transfer also applies to DoH since the name lookups take place over SSL. However, the certificate verification -settings are not inherited and can be controlled separately via ---doh-insecure and --doh-cert-status. +settings are not inherited but are controlled separately via --doh-insecure +and --doh-cert-status. This option is unset if an empty string "" is used as the URL. (Added in 7.85.0) diff --git a/docs/cmdline-opts/dump-header.d b/docs/cmdline-opts/dump-header.d index 657abcd4ef..42a79e7ddf 100644 --- a/docs/cmdline-opts/dump-header.d +++ b/docs/cmdline-opts/dump-header.d @@ -12,10 +12,10 @@ Added: 5.7 Multi: single --- Write the received protocol headers to the specified file. If no headers are -received, the use of this option will create an empty file. +received, the use of this option creates an empty file. When used in FTP, the FTP server response lines are considered being "headers" and thus are saved there. Having multiple transfers in one set of operations (i.e. the URLs in one ---next clause), will append them to the same file, separated by a blank line. +--next clause), appends them to the same file, separated by a blank line. diff --git a/docs/cmdline-opts/expect100-timeout.d b/docs/cmdline-opts/expect100-timeout.d index f68165800b..f9a119bd97 100644 --- a/docs/cmdline-opts/expect100-timeout.d +++ b/docs/cmdline-opts/expect100-timeout.d @@ -12,8 +12,8 @@ Multi: single --- 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. +default curl waits one second. This option accepts decimal values! When +curl stops waiting, it continues as if the response has been received. The decimal value needs to provided using a dot (.) as decimal separator - not the local version even if it might be using another separator. diff --git a/docs/cmdline-opts/fail-early.d b/docs/cmdline-opts/fail-early.d index 975f346271..36b3309996 100644 --- a/docs/cmdline-opts/fail-early.d +++ b/docs/cmdline-opts/fail-early.d @@ -11,14 +11,13 @@ Scope: global --- Fail and exit on the first detected transfer 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. +When curl is used to do multiple transfers on the command line, it attempts to +operate on each given URL, one by one. By default, it ignores errors if there +are more URLs given and the last URL's success determines the error code curl +returns. So early failures are "hidden" by subsequent successful transfers. -Using this option, curl will instead return an error on the first transfer -that fails, independent of the amount of URLs that are given on the command +Using this option, curl instead returns an error on the first transfer that +fails, independent of the amount of URLs that are given on the command line. This way, no transfer failures go undetected by scripts and similar. This option does not imply --fail, which causes transfers to fail due to the diff --git a/docs/cmdline-opts/fail-with-body.d b/docs/cmdline-opts/fail-with-body.d index 192b5e8b31..dddb86e229 100644 --- a/docs/cmdline-opts/fail-with-body.d +++ b/docs/cmdline-opts/fail-with-body.d @@ -5,7 +5,7 @@ Protocols: HTTP Help: Fail on HTTP errors but save the body Category: http output Added: 7.76.0 -See-also: fail +See-also: fail fail-early Mutexed: fail Example: --fail-with-body $URL Multi: boolean @@ -13,8 +13,8 @@ Multi: boolean Return an error on server errors where the HTTP response code is 400 or greater). 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 still allow curl to output and save that content but -also to return error 22. +more). This flag allows curl to output and save that content but also to +return error 22. This is an alternative option to --fail which makes curl fail for the same circumstances but without saving the content. diff --git a/docs/cmdline-opts/fail.d b/docs/cmdline-opts/fail.d index d16d110198..8196a908de 100644 --- a/docs/cmdline-opts/fail.d +++ b/docs/cmdline-opts/fail.d @@ -4,7 +4,7 @@ Long: fail Short: f Protocols: HTTP Help: Fail fast with no output on HTTP errors -See-also: fail-with-body +See-also: fail-with-body fail-early Category: important http Example: --fail $URL Mutexed: fail-with-body @@ -14,9 +14,9 @@ Multi: boolean Fail fast with no output at all on server errors. This is useful to enable scripts and users 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 +so (which often also describes why and more). This flag prevents 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 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 index fd99d9df67..73240492b9 100644 --- a/docs/cmdline-opts/false-start.d +++ b/docs/cmdline-opts/false-start.d @@ -10,7 +10,7 @@ See-also: tcp-fastopen Multi: boolean --- 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 +where a TLS client starts sending application data before verifying the server's Finished message, thus saving a round trip when performing a full handshake. diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d index 092041bd97..e53e93ae0d 100644 --- a/docs/cmdline-opts/form.d +++ b/docs/cmdline-opts/form.d @@ -29,14 +29,13 @@ file. Tell curl to read content from stdin instead of a file by using - as filename. This goes for both @ and < constructs. When stdin is used, the contents is buffered in memory first by curl to determine its size and allow a -possible resend. Defining a part's data from a named non-regular file (such -as a named pipe or similar) is unfortunately not subject to buffering and will -be effectively read at transmission time; since the full size is unknown -before the transfer starts, such data is sent as chunks by HTTP and rejected -by IMAP. +possible resend. Defining a part's data from a named non-regular file (such as +a named pipe or similar) is not subject to buffering and is instead read at +transmission time; since the full size is unknown before the transfer starts, +such data is sent as chunks by HTTP and rejected by IMAP. Example: send an image to an HTTP server, where 'profile' is the name of the -form-field to which the file **portrait.jpg** will be the input: +form-field to which the file **portrait.jpg** is the input: curl -F profile=@portrait.jpg https://example.com/upload.cgi diff --git a/docs/cmdline-opts/ftp-alternative-to-user.d b/docs/cmdline-opts/ftp-alternative-to-user.d index 06f29fc006..f030bcf598 100644 --- a/docs/cmdline-opts/ftp-alternative-to-user.d +++ b/docs/cmdline-opts/ftp-alternative-to-user.d @@ -12,5 +12,5 @@ Multi: single --- 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 +client certificate, using "SITE AUTH" tells 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 index 03f340ce4a..7c64f0e21c 100644 --- a/docs/cmdline-opts/ftp-create-dirs.d +++ b/docs/cmdline-opts/ftp-create-dirs.d @@ -11,4 +11,4 @@ Multi: boolean --- When an FTP or SFTP URL/operation uses a path that does not currently exist on the server, the standard behavior of curl is to fail. Using this option, curl -will instead attempt to create missing directories. +instead attempts to create missing directories. diff --git a/docs/cmdline-opts/ftp-method.d b/docs/cmdline-opts/ftp-method.d index 212e1caed9..8061d2b682 100644 --- a/docs/cmdline-opts/ftp-method.d +++ b/docs/cmdline-opts/ftp-method.d @@ -20,7 +20,7 @@ curl does a single CWD operation for each path part in the given URL. For deep hierarchies this means 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 +curl does no CWD at all. curl does 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 diff --git a/docs/cmdline-opts/ftp-pasv.d b/docs/cmdline-opts/ftp-pasv.d index 599493b1c8..c43bf2beea 100644 --- a/docs/cmdline-opts/ftp-pasv.d +++ b/docs/cmdline-opts/ftp-pasv.d @@ -16,5 +16,5 @@ option. Reversing an enforced passive really is not 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, +Passive mode means that curl tries the EPSV command first and then PASV, unless --disable-epsv is used. diff --git a/docs/cmdline-opts/ftp-skip-pasv-ip.d b/docs/cmdline-opts/ftp-skip-pasv-ip.d index 4382af46e5..3af9c6de4f 100644 --- a/docs/cmdline-opts/ftp-skip-pasv-ip.d +++ b/docs/cmdline-opts/ftp-skip-pasv-ip.d @@ -10,8 +10,8 @@ Example: --ftp-skip-pasv-ip ftp://example.com/ Multi: boolean --- 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 -reuse the same IP address it already uses for the control connection. +curl's PASV command when curl connects the data connection. Instead curl +reuses the same IP address it already uses for the control connection. This option is enabled by default (added in 7.74.0). diff --git a/docs/cmdline-opts/ftp-ssl-ccc-mode.d b/docs/cmdline-opts/ftp-ssl-ccc-mode.d index 6f446e6b01..ae9af9429d 100644 --- a/docs/cmdline-opts/ftp-ssl-ccc-mode.d +++ b/docs/cmdline-opts/ftp-ssl-ccc-mode.d @@ -10,7 +10,7 @@ Category: ftp tls Example: --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/ Multi: boolean --- -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 +Sets the CCC mode. The passive mode does not initiate the shutdown, but +instead waits for the server to do it, and does 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 index 6b7d61f186..33ae83b1c9 100644 --- a/docs/cmdline-opts/ftp-ssl-ccc.d +++ b/docs/cmdline-opts/ftp-ssl-ccc.d @@ -10,6 +10,6 @@ Example: --ftp-ssl-ccc ftps://example.com/ Multi: boolean --- Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after -authenticating. The rest of the control channel communication will be +authenticating. The rest of the control channel communication is be unencrypted. This allows NAT routers to follow the FTP transaction. The default mode is passive. diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index 303da2f531..8b9b98bb2d 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -371,7 +371,7 @@ sub single { my @extra; if($multi eq "single") { push @extra, "\nIf --$long is provided several times, the last set ". - "value will be used.\n"; + "value is used.\n"; } elsif($multi eq "append") { push @extra, "\n--$long can be used several times in a command line\n"; diff --git a/docs/cmdline-opts/get.d b/docs/cmdline-opts/get.d index 8b34d10af5..2e03a255bc 100644 --- a/docs/cmdline-opts/get.d +++ b/docs/cmdline-opts/get.d @@ -11,10 +11,10 @@ Added: 7.8.1 See-also: data request Multi: boolean --- -When used, this option will make all data specified with --data, --data-binary +When used, this option makes 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 +request that otherwise would be used. The data is 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 used in combination with --head, the POST data is instead appended to the +URL with a HEAD request. diff --git a/docs/cmdline-opts/haproxy-clientip.d b/docs/cmdline-opts/haproxy-clientip.d index 53901d01cb..25cb7e6236 100644 --- a/docs/cmdline-opts/haproxy-clientip.d +++ b/docs/cmdline-opts/haproxy-clientip.d @@ -21,7 +21,7 @@ digits (upper or lower case) delimited by colons between each other, with the acceptance of one double colon sequence to replace the largest acceptable range of consecutive zeroes. The total number of decoded bits must exactly be 128. -Otherwise, any string can be accepted for the client IP and will be sent. +Otherwise, any string can be accepted for the client IP and get sent. It replaces --haproxy-protocol if used, it is not necessary to specify both flags. diff --git a/docs/cmdline-opts/header.d b/docs/cmdline-opts/header.d index 2a95c52a9c..f5b7685524 100644 --- a/docs/cmdline-opts/header.d +++ b/docs/cmdline-opts/header.d @@ -23,22 +23,22 @@ global level. It does not affect raw uploaded mails (Added in 7.56.0). 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 are 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 +use, your externally set header is 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 are +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 makes sure that each header you add/replace is sent with the proper end-of-line marker, you should thus **not** add that as a part of the header -content: do not add newlines or carriage returns, they will only mess things -up for you. +content: do not add newlines or carriage returns, they only mess things up for +you. This option can take an argument in @filename style, which then adds a header -for each line in the input file. Using @- will make curl read the header file -from stdin. Added in 7.55.0. +for each line in the input file. Using @- makes curl read the header file from +stdin. Added in 7.55.0. Please note that most anti-spam utilities check the presence and value of several MIME mail headers: these are "From:", "To:", "Date:" and "Subject:" @@ -48,10 +48,9 @@ You need --proxy-header to send custom headers intended for an HTTP proxy. Added in 7.37.0. Passing on a "Transfer-Encoding: chunked" header when doing an HTTP request -with a request body, will make curl send the data using chunked encoding. +with a request body, makes curl send the data using chunked encoding. -**WARNING**: headers set with this option will be set in all HTTP requests -- even 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. +**WARNING**: headers set with this option are set in all HTTP requests - even +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. diff --git a/docs/cmdline-opts/hostpubmd5.d b/docs/cmdline-opts/hostpubmd5.d index 391b896f37..e9db23db08 100644 --- a/docs/cmdline-opts/hostpubmd5.d +++ b/docs/cmdline-opts/hostpubmd5.d @@ -11,5 +11,5 @@ See-also: hostpubsha256 Multi: single --- 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 +be the 128 bit MD5 checksum of the remote host's public key, curl refuses the connection with the host unless the md5sums match. diff --git a/docs/cmdline-opts/hostpubsha256.d b/docs/cmdline-opts/hostpubsha256.d index ba33318f9c..b33f338bdd 100644 --- a/docs/cmdline-opts/hostpubsha256.d +++ b/docs/cmdline-opts/hostpubsha256.d @@ -10,9 +10,8 @@ Example: --hostpubsha256 NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ= sftp://exa See-also: hostpubmd5 Multi: single --- -Pass a string containing a Base64-encoded SHA256 hash of the remote -host's public key. Curl will refuse the connection with the host -unless the hashes match. +Pass a string containing a Base64-encoded SHA256 hash of the remote host's +public key. Curl refuses the connection with the host unless the hashes match. This feature requires libcurl to be built with libssh2 and does not work with other SSH backends. diff --git a/docs/cmdline-opts/hsts.d b/docs/cmdline-opts/hsts.d index 173ed0acb0..e30d3b419d 100644 --- a/docs/cmdline-opts/hsts.d +++ b/docs/cmdline-opts/hsts.d @@ -11,8 +11,8 @@ See-also: proto Multi: append --- This option enables HSTS for the transfer. If the file name points to an -existing HSTS cache file, that will be used. After a completed transfer, the -cache will be saved to the file name again if it has been modified. +existing HSTS cache file, that is used. After a completed transfer, the +cache is saved to the file name again if it has been modified. If curl is told to use HTTP:// for a transfer involving a host name that exists in the HSTS cache, it upgrades the transfer to use HTTPS. Each HSTS @@ -22,5 +22,5 @@ performed. Specify a "" file name (zero length) to avoid loading/saving and make curl just handle HSTS in memory. -If this option is used several times, curl will load contents from all the -files but the last one will be used for saving. +If this option is used several times, curl loads contents from all the +files but the last one is used for saving. diff --git a/docs/cmdline-opts/http0.9.d b/docs/cmdline-opts/http0.9.d index d6a520bf22..3dd14a05ce 100644 --- a/docs/cmdline-opts/http0.9.d +++ b/docs/cmdline-opts/http0.9.d @@ -13,7 +13,7 @@ Multi: boolean Tells curl to be fine with HTTP version 0.9 response. HTTP/0.9 is a response without headers and therefore you can also connect with -this to non-HTTP servers and still get a response since curl will simply -transparently downgrade - if allowed. +this to non-HTTP servers and still get a response since curl simply +transparently downgrades - if allowed. HTTP/0.9 is disabled by default (added in 7.66.0) diff --git a/docs/cmdline-opts/http2-prior-knowledge.d b/docs/cmdline-opts/http2-prior-knowledge.d index 8224e8055e..7d7cabfd86 100644 --- a/docs/cmdline-opts/http2-prior-knowledge.d +++ b/docs/cmdline-opts/http2-prior-knowledge.d @@ -14,5 +14,5 @@ Multi: boolean --- Tells curl to issue its non-TLS HTTP requests using HTTP/2 without HTTP/1.1 Upgrade. It requires prior knowledge that the server supports HTTP/2 straight -away. HTTPS requests will still do HTTP/2 the standard way with negotiated -protocol version in the TLS handshake. +away. HTTPS requests still do HTTP/2 the standard way with negotiated protocol +version in the TLS handshake. diff --git a/docs/cmdline-opts/http2.d b/docs/cmdline-opts/http2.d index 17264b02a6..af5f3c4f5a 100644 --- a/docs/cmdline-opts/http2.d +++ b/docs/cmdline-opts/http2.d @@ -14,11 +14,11 @@ Multi: mutex --- Tells curl to use HTTP version 2. -For HTTPS, this means curl will attempt to negotiate HTTP/2 in the TLS -handshake. curl does this by default. +For HTTPS, this means curl negotiates HTTP/2 in the TLS handshake. curl does +this by default. -For HTTP, this means curl will attempt to upgrade the request to HTTP/2 using -the Upgrade: request header. +For HTTP, this means curl attempts to upgrade the request to HTTP/2 using the +Upgrade: request header. When curl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or higher even though that is required by the specification. A user can add this diff --git a/docs/cmdline-opts/http3-only.d b/docs/cmdline-opts/http3-only.d index a1d7db91d6..c3f0f31aa1 100644 --- a/docs/cmdline-opts/http3-only.d +++ b/docs/cmdline-opts/http3-only.d @@ -15,11 +15,11 @@ Experimental: yes --- Instructs curl to use HTTP/3 to the host in the URL, with no fallback to earlier HTTP versions. HTTP/3 can only be used for HTTPS and not for HTTP -URLs. For HTTP, this option will trigger an error. +URLs. For HTTP, this option triggers an error. This option allows a user to avoid using the Alt-Svc method of upgrading to HTTP/3 when you know that the target speaks HTTP/3 on the given host and port. -This option will make curl fail if a QUIC connection cannot be established, it -will not attempt any other HTTP version on its own. Use --http3 for similar +This option makes curl fail if a QUIC connection cannot be established, it +does not attempt any other HTTP versions on its own. Use --http3 for similar functionality *with* a fallback. diff --git a/docs/cmdline-opts/http3.d b/docs/cmdline-opts/http3.d index 89aedd6894..a8258c4d31 100644 --- a/docs/cmdline-opts/http3.d +++ b/docs/cmdline-opts/http3.d @@ -20,8 +20,8 @@ available for HTTPS and not for HTTP URLs. This option allows a user to avoid using the Alt-Svc method of upgrading to HTTP/3 when you know that the target speaks HTTP/3 on the given host and port. -When asked to use HTTP/3, curl will issue a separate attempt to use older HTTP +When asked to use HTTP/3, curl issues a separate attempt to use older HTTP versions with a slight delay, so if the HTTP/3 transfer fails or is slow, curl -will still try to proceed with an older HTTP version. +still tries to proceed with an older HTTP version. Use --http3-only for similar functionality *without* a fallback. diff --git a/docs/cmdline-opts/ignore-content-length.d b/docs/cmdline-opts/ignore-content-length.d index 344ac9a9ce..505c04c18b 100644 --- a/docs/cmdline-opts/ignore-content-length.d +++ b/docs/cmdline-opts/ignore-content-length.d @@ -10,7 +10,7 @@ See-also: ftp-skip-pasv-ip Multi: boolean --- For HTTP, Ignore the Content-Length header. This is particularly useful for -servers running Apache 1.x, which will report incorrect Content-Length for +servers running Apache 1.x, which reports incorrect Content-Length for files larger than 2 gigabytes. For FTP, this makes curl skip the SIZE command to figure out the size before diff --git a/docs/cmdline-opts/json.d b/docs/cmdline-opts/json.d index 4414ac5cc3..aa3b49de2f 100644 --- a/docs/cmdline-opts/json.d +++ b/docs/cmdline-opts/json.d @@ -30,6 +30,6 @@ from stdin. Posting data from a file named 'foobar' would thus be done with --json @foobar and to instead read the data from stdin, use --json @-. If this option is used more than once on the same command line, the additional -data pieces will be concatenated to the previous before sending. +data pieces are concatenated to the previous before sending. The headers this option sets can be overridden with --header as usual. diff --git a/docs/cmdline-opts/junk-session-cookies.d b/docs/cmdline-opts/junk-session-cookies.d index c33781913a..daea7840ad 100644 --- a/docs/cmdline-opts/junk-session-cookies.d +++ b/docs/cmdline-opts/junk-session-cookies.d @@ -10,7 +10,6 @@ Example: --junk-session-cookies -b cookies.txt $URL Added: 7.9.7 Multi: boolean --- -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 are closed down. +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 +started. Typical browsers discard session cookies when they are closed down. diff --git a/docs/cmdline-opts/key.d b/docs/cmdline-opts/key.d index 3b90100003..4236218c9d 100644 --- a/docs/cmdline-opts/key.d +++ b/docs/cmdline-opts/key.d @@ -15,11 +15,11 @@ file. For SSH, if not specified, curl tries the following candidates in order: '~/.ssh/id_rsa', '~/.ssh/id_dsa', './id_rsa', './id_dsa'. If curl is built against OpenSSL library, and the engine pkcs11 is available, -then a PKCS#11 URI (RFC 7512) can be used to specify a private key located in a -PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a -PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option will be set -as "pkcs11" if none was provided and the --key-type option will be set as -"ENG" if none was provided. +then a PKCS#11 URI (RFC 7512) can be used to specify a private key located in +a PKCS#11 device. A string beginning with "pkcs11:" is interpreted as a +PKCS#11 URI. If a PKCS#11 URI is provided, then the --engine option is set as +"pkcs11" if none was provided and the --key-type option is set as "ENG" if +none was provided. If curl is built against Secure Transport or Schannel then this option is ignored for TLS protocols (HTTPS, etc). Those backends expect the private key diff --git a/docs/cmdline-opts/krb.d b/docs/cmdline-opts/krb.d index b4b96e4fd9..42aa67ada4 100644 --- a/docs/cmdline-opts/krb.d +++ b/docs/cmdline-opts/krb.d @@ -13,4 +13,4 @@ Multi: single --- 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. +level that is not one of these, 'private' is used. diff --git a/docs/cmdline-opts/libcurl.d b/docs/cmdline-opts/libcurl.d index 0f5d5826c6..52e252f3b9 100644 --- a/docs/cmdline-opts/libcurl.d +++ b/docs/cmdline-opts/libcurl.d @@ -10,6 +10,6 @@ See-also: verbose Multi: single Scope: global --- -Append this option to any ordinary curl command line, and you will get -libcurl-using C source code written to the file that does the equivalent -of what your command-line operation does! +Append this option to any ordinary curl command line, and you get +libcurl-using C source code written to the file that does the equivalent of +what your command-line operation does! diff --git a/docs/cmdline-opts/limit-rate.d b/docs/cmdline-opts/limit-rate.d index 2a43c4acf0..43ebf2c233 100644 --- a/docs/cmdline-opts/limit-rate.d +++ b/docs/cmdline-opts/limit-rate.d @@ -17,13 +17,13 @@ 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 +Appending 'k' or 'K' counts the number as kilobytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it gigabytes. The suffixes (k, M, G, T, P) are 1024 based. For example 1k is 1024. Examples: 200K, 3m and 1G. The rate limiting logic works on averaging the transfer speed to no more than the set threshold over a period of multiple seconds. -If you also use the --speed-limit option, that option will take precedence and +If you also use the --speed-limit option, that option takes precedence and might cripple the rate-limiting slightly, to help keeping the speed-limit logic working. diff --git a/docs/cmdline-opts/local-port.d b/docs/cmdline-opts/local-port.d index 71af9bed00..d6949b7ee3 100644 --- a/docs/cmdline-opts/local-port.d +++ b/docs/cmdline-opts/local-port.d @@ -11,5 +11,5 @@ Multi: single --- 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. +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 index d801cb61f7..9f83d0ef0e 100644 --- a/docs/cmdline-opts/location-trusted.d +++ b/docs/cmdline-opts/location-trusted.d @@ -9,7 +9,7 @@ Example: --location-trusted -u user:password $URL Added: 7.10.4 Multi: boolean --- -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 will send your authentication -info (which is plaintext in the case of HTTP Basic authentication). +Like --location, but allows 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 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 index fcd28675ab..9a99a05133 100644 --- a/docs/cmdline-opts/location.d +++ b/docs/cmdline-opts/location.d @@ -12,18 +12,19 @@ Multi: boolean --- 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 will not 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. +option makes curl redo the request on the new place. If used together with +--include or --head, headers from all requested pages are shown. -When curl follows a redirect and if the request is a POST, it will send the +When authentication is used, curl only sends its credentials to the initial +host. If a redirect takes curl to a different host, it does not get the +user+password pass on. See also --location-trusted on how to change this. + +Limit the amount of redirects to follow by using the --max-redirs option. + +When curl follows a redirect and if the request is a POST, it sends 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. +response code was any other 3xx code, curl resends the following request using +the same unmodified method. You can tell curl to not change POST requests 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 index 05436a88ce..c67be90f87 100644 --- a/docs/cmdline-opts/login-options.d +++ b/docs/cmdline-opts/login-options.d @@ -19,7 +19,7 @@ RFC 5092 and the IETF draft https://datatracker.ietf.org/doc/html/draft-earhart-url-smtp-00. Since 8.2.0, IMAP supports the login option "AUTH=+LOGIN". With this option, -curl uses the plain (not SASL) LOGIN IMAP command even if the server advertises -SASL authentication. Care should be taken in using this option, as it will send -out your password in plain text. This will not work if the IMAP server disables -the plain LOGIN (e.g. to prevent password snooping). +curl uses the plain (not SASL) LOGIN IMAP command even if the server +advertises SASL authentication. Care should be taken in using this option, as +it sends your password over the network in plain text. This does not work if +the IMAP server disables the plain LOGIN (e.g. to prevent password snooping). diff --git a/docs/cmdline-opts/mail-auth.d b/docs/cmdline-opts/mail-auth.d index 5e3f3f26b3..45ceebd99f 100644 --- a/docs/cmdline-opts/mail-auth.d +++ b/docs/cmdline-opts/mail-auth.d @@ -10,6 +10,5 @@ Category: smtp Example: --mail-auth user@example.come -T mail smtp://example.com/ Multi: single --- -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. +Specify a single address. This is 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-rcpt-allowfails.d b/docs/cmdline-opts/mail-rcpt-allowfails.d index 2837ed0bb5..d2a5f39d3b 100644 --- a/docs/cmdline-opts/mail-rcpt-allowfails.d +++ b/docs/cmdline-opts/mail-rcpt-allowfails.d @@ -9,14 +9,14 @@ Example: --mail-rcpt-allowfails --mail-rcpt dest@example.com smtp://example.com See-also: mail-rcpt Multi: boolean --- -When sending data to multiple recipients, by default curl will abort SMTP +When sending data to multiple recipients, by default curl aborts SMTP conversation if at least one of the recipients causes RCPT TO command to return an error. The default behavior can be changed by passing --mail-rcpt-allowfails -command-line option which will make curl ignore errors and proceed with the +command-line option which makes curl ignore errors and proceed with the remaining valid recipients. If all recipients trigger RCPT TO failures and this flag is specified, curl -will still abort the SMTP conversation and return the error received from to -the last RCPT TO command. +still aborts the SMTP conversation and returns the error received from to the +last RCPT TO command. diff --git a/docs/cmdline-opts/max-filesize.d b/docs/cmdline-opts/max-filesize.d index 847369d834..ada730d926 100644 --- a/docs/cmdline-opts/max-filesize.d +++ b/docs/cmdline-opts/max-filesize.d @@ -11,10 +11,10 @@ Added: 7.10.8 Multi: single --- 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. +requested is larger than this value, the transfer does not start and curl +returns with exit code 63. -A size modifier may be used. For example, Appending 'k' or 'K' will count the +A size modifier may be used. For example, Appending 'k' or 'K' counts the number as kilobytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G. (Added in 7.58.0) diff --git a/docs/cmdline-opts/netrc-file.d b/docs/cmdline-opts/netrc-file.d index 7e8572130b..7b1a214da2 100644 --- a/docs/cmdline-opts/netrc-file.d +++ b/docs/cmdline-opts/netrc-file.d @@ -14,4 +14,4 @@ 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. -It will abide by --netrc-optional if specified. +It abides by --netrc-optional if specified. diff --git a/docs/cmdline-opts/netrc.d b/docs/cmdline-opts/netrc.d index dd9af012ba..46e8778fa0 100644 --- a/docs/cmdline-opts/netrc.d +++ b/docs/cmdline-opts/netrc.d @@ -12,11 +12,11 @@ Multi: boolean --- Makes curl scan the *.netrc* (*_netrc* 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 -*netrc(5)* and *ftp(1)* for details on the file format. Curl will not -complain if that file does not have the right permissions (it should be -neither world- nor group-readable). The environment variable "HOME" is used -to find the home directory. +Unix. If used with HTTP, curl enables user authentication. See *netrc(5)* and +*ftp(1)* for details on the file format. Curl does not complain if that file +does not have the right permissions (it should be neither world- nor +group-readable). The environment variable "HOME" is used to find the home +directory. A quick and simple example of how to setup a *.netrc* to allow curl to FTP to the machine host.domain.com with user name 'myself' and password 'secret' diff --git a/docs/cmdline-opts/next.d b/docs/cmdline-opts/next.d index 778b3f30f9..93c9c45b38 100644 --- a/docs/cmdline-opts/next.d +++ b/docs/cmdline-opts/next.d @@ -18,9 +18,9 @@ options. This allows you to send several URL requests, each with their own specific options, for example, such as different user names or custom requests for each. ---next will reset all local options and only global ones will have their -values survive over to the operation following the --next instruction. Global -options include --verbose, --trace, --trace-ascii and --fail-early. +--next resets all local options and only global ones have their values survive +over to the operation following the --next instruction. Global options include +--verbose, --trace, --trace-ascii and --fail-early. For example, you can do both a GET and a POST in a single command line: diff --git a/docs/cmdline-opts/no-buffer.d b/docs/cmdline-opts/no-buffer.d index 7dc4bc534f..33f6fbc5bf 100644 --- a/docs/cmdline-opts/no-buffer.d +++ b/docs/cmdline-opts/no-buffer.d @@ -10,9 +10,9 @@ See-also: progress-bar Multi: boolean --- 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. +uses a standard buffered output stream that has the effect that it outputs the +data in chunks, not necessarily exactly when the data arrives. Using this +option disables that buffering. Note that this is the negated option name documented. You can use --buffer to enable buffering again. diff --git a/docs/cmdline-opts/no-clobber.d b/docs/cmdline-opts/no-clobber.d index 15f4ed3a41..9325558da6 100644 --- a/docs/cmdline-opts/no-clobber.d +++ b/docs/cmdline-opts/no-clobber.d @@ -10,8 +10,8 @@ Multi: boolean --- When used in conjunction with the --output, --remote-header-name, --remote-name, or --remote-name-all options, curl avoids overwriting files -that already exist. Instead, a dot and a number gets appended to the name -of the file that would be created, up to filename.100 after which it will not +that already exist. Instead, a dot and a number gets appended to the name of +the file that would be created, up to filename.100 after which it does not create any file. Note that this is the negated option name documented. You can thus use diff --git a/docs/cmdline-opts/output-dir.d b/docs/cmdline-opts/output-dir.d index eb6274facd..803b2948bb 100644 --- a/docs/cmdline-opts/output-dir.d +++ b/docs/cmdline-opts/output-dir.d @@ -15,5 +15,5 @@ This option specifies the directory in which files should be stored, when The given output directory is used for all URLs and output options on the command line, up until the first --next. -If the specified target directory does not exist, the operation will fail -unless --create-dirs is also used. +If the specified target directory does not exist, the operation fails unless +--create-dirs is also used. diff --git a/docs/cmdline-opts/output.d b/docs/cmdline-opts/output.d index 4f4a8a453d..067151091d 100644 --- a/docs/cmdline-opts/output.d +++ b/docs/cmdline-opts/output.d @@ -15,7 +15,7 @@ Multi: append --- Write output to instead of stdout. If you are using {} or [] to fetch multiple documents, you should quote the URL and you can use '#' followed by a -number in the specifier. That variable will be replaced with the current +number in the specifier. That variable is replaced with the current string for the URL being fetched. Like in: curl "http://{one,two}.example.com" -o "file_#1.txt" @@ -37,8 +37,8 @@ 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. +dynamically. Specifying the output as '-' (a single dash) passes the output to +stdout. To suppress response bodies, you can redirect output to /dev/null: diff --git a/docs/cmdline-opts/page-footer b/docs/cmdline-opts/page-footer index e676febb53..beae49ac12 100644 --- a/docs/cmdline-opts/page-footer +++ b/docs/cmdline-opts/page-footer @@ -45,11 +45,11 @@ addresses starting with "192.168". On Windows, this variable is used when trying to find the home directory. If the primary home variable are all unset. .IP "COLUMNS " -If set, the specified number of characters will be used as the terminal width -when the alternative progress-bar is shown. If not set, curl will try to -figure it out using other ways. +If set, the specified number of characters is used as the terminal width when +the alternative progress-bar is shown. If not set, curl tries to figure it out +using other ways. .IP "CURL_CA_BUNDLE " -If set, will be used as the --cacert value. +If set, it is used as the --cacert value. .IP "CURL_HOME " If set, is the first variable curl checks when trying to find its home directory. If not set, it continues to check *XDG_CONFIG_HOME* @@ -57,8 +57,8 @@ directory. If not set, it continues to check *XDG_CONFIG_HOME* If curl was built with support for "MultiSSL", meaning that it has built-in support for more than one TLS backend, this environment variable can be set to the case insensitive name of the particular backend to use when curl is -invoked. Setting a name that is not a built-in alternative will make curl -stay with the default. +invoked. Setting a name that is not a built-in alternative makes curl stay +with the default. SSL backend names (case-insensitive): **bearssl**, **gnutls**, **mbedtls**, **openssl**, **rustls**, **schannel**, **secure-transport**, **wolfssl** @@ -68,24 +68,24 @@ looking for the default .curlrc. *CURL_HOME* and *XDG_CONFIG_HOME* have preference. .IP "QLOGDIR " If curl was built with HTTP/3 support, setting this environment variable to a -local directory will make curl produce **qlogs** in that directory, using file +local directory makes curl produce **qlogs** in that directory, using file names named after the destination connection id (in hex). Do note that these files can become rather large. Works with the ngtcp2 and quiche QUIC backends. .IP SHELL Used on VMS when trying to detect if using a **DCL** or a **unix** shell. .IP "SSL_CERT_DIR " -If set, will be used as the --capath value. +If set, it is used as the --capath value. .IP "SSL_CERT_FILE " -If set, will be used as the --cacert value. +If set, it is used as the --cacert value. .IP "SSLKEYLOGFILE " -If you set this environment variable to a file name, curl will store TLS -secrets from its connections in that file when invoked to enable you to -analyze the TLS traffic in real time using network analyzing tools such as -Wireshark. This works with the following TLS backends: OpenSSL, libressl, -BoringSSL, GnuTLS and wolfSSL. +If you set this environment variable to a file name, curl stores TLS secrets +from its connections in that file when invoked to enable you to analyze the +TLS traffic in real time using network analyzing tools such as Wireshark. This +works with the following TLS backends: OpenSSL, libressl, BoringSSL, GnuTLS +and wolfSSL. .IP "USERPROFILE " On Windows, this variable is used when trying to find the home directory. If -the other, primary, variable are all unset. If set, curl will use the path +the other, primary, variable are all unset. If set, curl uses the path **"$USERPROFILE\\Application Data"**. .IP "XDG_CONFIG_HOME " If *CURL_HOME* is not set, this variable is checked when looking for a @@ -94,8 +94,8 @@ default .curlrc file. The proxy string may be specified with a protocol:// prefix to specify alternative proxy protocols. (Added in 7.21.7) -If no protocol is specified in the proxy string or if the string does not match -a supported one, the proxy will be treated as an HTTP proxy. +If no protocol is specified in the proxy string or if the string does not +match a supported one, the proxy is treated as an HTTP proxy. The supported proxy protocol prefixes are as follows: .IP "http://" @@ -283,7 +283,7 @@ Unable to parse FTP file list. .IP 88 FTP chunk callback reported error. .IP 89 -No connection available, the session will be queued. +No connection available, the session is queued. .IP 90 SSL public key does not matched pinned public key. .IP 91 @@ -307,8 +307,8 @@ A client-side certificate is required to complete the TLS handshake. .IP 99 Poll or select returned fatal error. .IP XX -More error codes will appear here in future releases. The existing ones -are meant to never change. +More error codes might appear here in future releases. The existing ones are +meant to never change. .SH BUGS If you experience any problems with curl, submit an issue in the project's bug tracker on GitHub: https://github.com/curl/curl/issues diff --git a/docs/cmdline-opts/page-header b/docs/cmdline-opts/page-header index 69bb463301..7d14f4c452 100644 --- a/docs/cmdline-opts/page-header +++ b/docs/cmdline-opts/page-header @@ -46,10 +46,10 @@ what protocol you want. It then defaults to HTTP but assumes others based on often-used host name prefixes. For example, for host names starting with "ftp." curl assumes you want FTP. -You can specify any amount of URLs on the command line. They will be fetched -in a sequential manner in the specified order unless you use --parallel. You -can specify command line options and URLs mixed and in any order on the -command line. +You can specify any amount of URLs on the command line. They are fetched in a +sequential manner in the specified order unless you use --parallel. You can +specify command line options and URLs mixed and in any order on the command +line. curl attempts to reuse connections when doing multiple transfers, so that getting many files from the same server do not use multiple connects and setup @@ -127,7 +127,7 @@ white space with *trim*, it can output the contents as a JSON quoted string with *json*, URL encode the string with *url* or base64 encode it with *b64*. You apply function to a variable expansion, add them colon separated to the right side of the variable. Variable content holding null bytes that are -not encoded when expanded, will cause error. +not encoded when expanded cause error. Example: get the contents of a file called $HOME/.secret into a variable called "fix". Make sure that the content is trimmed and percent-encoded sent @@ -156,7 +156,7 @@ Lets you lookup words using online dictionaries. .IP FILE Read or write local files. curl does not support accessing file:// URL remotely, but when running on Microsoft Windows using the native UNC approach -will work. +works. .IP FTP(S) curl supports the File Transfer Protocol with a lot of tweaks and levers. With or without using TLS. @@ -252,7 +252,7 @@ prefix it with "no-". However, in this list we mostly only list and show the When --next is used, it resets the parser state and you start again with a clean option state, except for the options that are "global". Global options -will retain their values and meaning even after --next. +retain their values and meaning even after --next. The following options are global: %GLOBALS. diff --git a/docs/cmdline-opts/parallel-immediate.d b/docs/cmdline-opts/parallel-immediate.d index da15d62771..b534dd5122 100644 --- a/docs/cmdline-opts/parallel-immediate.d +++ b/docs/cmdline-opts/parallel-immediate.d @@ -9,7 +9,7 @@ Example: --parallel-immediate -Z $URL -o file1 $URL -o file2 Multi: boolean Scope: global --- -When doing parallel transfers, this option will instruct curl that it should +When doing parallel transfers, this option instructs curl that it should rather prefer opening up more connections in parallel at once rather than waiting to see if new transfers can be added as multiplexed streams on another connection. diff --git a/docs/cmdline-opts/path-as-is.d b/docs/cmdline-opts/path-as-is.d index c079c5905a..9897d882f6 100644 --- a/docs/cmdline-opts/path-as-is.d +++ b/docs/cmdline-opts/path-as-is.d @@ -9,5 +9,5 @@ See-also: request-target Multi: boolean --- 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 +path. Normally curl squashes or merges them according to standards but with this option set you tell it not to do that. diff --git a/docs/cmdline-opts/pinnedpubkey.d b/docs/cmdline-opts/pinnedpubkey.d index f3a25cd8d6..48b96dfc5a 100644 --- a/docs/cmdline-opts/pinnedpubkey.d +++ b/docs/cmdline-opts/pinnedpubkey.d @@ -18,8 +18,8 @@ or DER format, or any number of base64 encoded sha256 hashes preceded 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. +if it does not exactly match the public key provided to this option, curl +aborts the connection before sending or receiving any data. PEM/DER support: diff --git a/docs/cmdline-opts/preproxy.d b/docs/cmdline-opts/preproxy.d index 643179edeb..b55c1d47a2 100644 --- a/docs/cmdline-opts/preproxy.d +++ b/docs/cmdline-opts/preproxy.d @@ -16,7 +16,7 @@ SOCKS) to the HTTP or HTTPS proxy. Hence pre proxy. The pre proxy string should be specified with a protocol:// prefix to specify alternative proxy protocols. Use socks4://, socks4a://, socks5:// or socks5h:// to request the specific SOCKS version to be used. No protocol -specified will make curl default to SOCKS4. +specified makes curl default to SOCKS4. If the port number is not specified in the proxy string, it is assumed to be 1080. diff --git a/docs/cmdline-opts/progress-bar.d b/docs/cmdline-opts/progress-bar.d index a6cc8f50e3..fee170979d 100644 --- a/docs/cmdline-opts/progress-bar.d +++ b/docs/cmdline-opts/progress-bar.d @@ -15,6 +15,6 @@ standard, more informational, meter. This progress bar draws a single line of '#' characters across the screen and shows a percentage if the transfer size is known. For transfers without a -known size, there will be space ship (-=o=-) that moves back and forth but -only while data is being transferred, with a set of flying hash sign symbols on +known size, there is a space ship (-=o=-) that moves back and forth but only +while data is being transferred, with a set of flying hash sign symbols on top. diff --git a/docs/cmdline-opts/proto-redir.d b/docs/cmdline-opts/proto-redir.d index ff29081bd2..dec8716144 100644 --- a/docs/cmdline-opts/proto-redir.d +++ b/docs/cmdline-opts/proto-redir.d @@ -17,6 +17,6 @@ Example, allow only HTTP and HTTPS on redirect: curl --proto-redir -all,http,https http://example.com -By default curl will only allow HTTP, HTTPS, FTP and FTPS on redirect -(added in 7.65.2). Specifying *all* or *+all* enables all protocols on -redirects, which is not good for security. +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 redirects, which +is not good for security. diff --git a/docs/cmdline-opts/proxy-ca-native.d b/docs/cmdline-opts/proxy-ca-native.d index 1498947768..aab4fcabc2 100644 --- a/docs/cmdline-opts/proxy-ca-native.d +++ b/docs/cmdline-opts/proxy-ca-native.d @@ -10,10 +10,12 @@ Added: 8.2.0 Multi: boolean --- Tells curl to use the CA store from the native operating system to verify the -HTTPS proxy. By default, curl will otherwise use a CA store provided in a -single file or directory, but when using this option it will interface the -operating system's own vault. +HTTPS proxy. By default, curl uses a CA store provided in a single file or +directory, but when using this option it interfaces the operating system's own +vault. This option only works for curl on Windows when built to use OpenSSL. When curl on Windows is built to use Schannel, this feature is implied and curl then only uses the native CA store. + +curl built with wolfSSL also supports this option (added in 8.3.0). diff --git a/docs/cmdline-opts/proxy-header.d b/docs/cmdline-opts/proxy-header.d index 86bf22e929..06ae3bcbaa 100644 --- a/docs/cmdline-opts/proxy-header.d +++ b/docs/cmdline-opts/proxy-header.d @@ -17,16 +17,16 @@ 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 +curl makes sure that each header you add/replace is sent with the proper end-of-line marker, you should thus **not** add that as a part of the header -content: do not add newlines or carriage returns, they will only mess things -up for you. +content: do not add newlines or carriage returns, they 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. +Headers specified with this option are not included in requests that curl +knows are not be sent to a proxy. This option can take an argument in @filename style, which then adds a header -for each line in the input file (added in 7.55.0). Using @- will make curl -read the header file from stdin. +for each line in the input file (added in 7.55.0). Using @- makes curl read +the headers from stdin. This option can be used multiple times to add/replace/remove multiple headers. diff --git a/docs/cmdline-opts/proxy-http2.d b/docs/cmdline-opts/proxy-http2.d index 0865300d2c..58f55e74dd 100644 --- a/docs/cmdline-opts/proxy-http2.d +++ b/docs/cmdline-opts/proxy-http2.d @@ -13,6 +13,6 @@ Example: --proxy-http2 -x proxy $URL Multi: boolean --- Tells curl to try negotiate HTTP version 2 with an HTTPS proxy. The proxy might -still only offer HTTP/1 and then curl will stick to using that version. +still only offer HTTP/1 and then curl sticks to using that version. This has no effect for any other kinds of proxies. diff --git a/docs/cmdline-opts/proxy-pinnedpubkey.d b/docs/cmdline-opts/proxy-pinnedpubkey.d index 72f0cd1f07..7bf99d8c5b 100644 --- a/docs/cmdline-opts/proxy-pinnedpubkey.d +++ b/docs/cmdline-opts/proxy-pinnedpubkey.d @@ -18,5 +18,5 @@ or DER format, or any number of base64 encoded sha256 hashes preceded 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. +if it does not exactly match the public key provided to this option, curl +aborts the connection before sending or receiving any data. diff --git a/docs/cmdline-opts/proxy-user.d b/docs/cmdline-opts/proxy-user.d index 5001ebb0e9..df30de2d92 100644 --- a/docs/cmdline-opts/proxy-user.d +++ b/docs/cmdline-opts/proxy-user.d @@ -16,8 +16,8 @@ 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 :". -On systems where it works, curl will hide the given option argument from -process listings. This is not enough to protect credentials from possibly -getting seen by other users on the same system as they will still be visible -for a moment before cleared. Such sensitive data should be retrieved from a -file instead or similar and never used in clear text in a command line. +On systems where it works, curl hides the given option argument from process +listings. This is not enough to protect credentials from possibly getting seen +by other users on the same system as they still are visible for a moment +before cleared. Such sensitive data should be retrieved from a file instead or +similar and never used in clear text in a command line. diff --git a/docs/cmdline-opts/proxy.d b/docs/cmdline-opts/proxy.d index 3c013da3ef..b7d550a110 100644 --- a/docs/cmdline-opts/proxy.d +++ b/docs/cmdline-opts/proxy.d @@ -13,9 +13,9 @@ Multi: single Use the specified proxy. The proxy string can be specified with a protocol:// prefix. No protocol -specified or http:// will be treated as HTTP proxy. Use socks4://, socks4a://, -socks5:// or socks5h:// to request a specific SOCKS version to be used. -(Added in 7.21.7) +specified or http:// it is treated as an HTTP proxy. Use socks4://, +socks4a://, socks5:// or socks5h:// to request a specific SOCKS version to be +used. (Added in 7.21.7) Unix domain sockets are supported for socks proxy. Set localhost for the host part. e.g. socks5h://localhost/path/to/socket.sock @@ -34,7 +34,7 @@ This option overrides existing environment variables that set the proxy to use. If there is 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 +All operations that are performed over an HTTP proxy are transparently 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. diff --git a/docs/cmdline-opts/proxy1.0.d b/docs/cmdline-opts/proxy1.0.d index 53a8decb98..0657a9519d 100644 --- a/docs/cmdline-opts/proxy1.0.d +++ b/docs/cmdline-opts/proxy1.0.d @@ -13,5 +13,5 @@ Use the specified HTTP 1.0 proxy. If the port number is not specified, it is assumed at port 1080. The only difference between this and the HTTP proxy option --proxy, is that -attempts to use CONNECT through the proxy will specify an HTTP 1.0 protocol +attempts to use CONNECT through the proxy specifies an HTTP 1.0 protocol instead of the default HTTP 1.1. diff --git a/docs/cmdline-opts/proxytunnel.d b/docs/cmdline-opts/proxytunnel.d index f389406c49..51457870b2 100644 --- a/docs/cmdline-opts/proxytunnel.d +++ b/docs/cmdline-opts/proxytunnel.d @@ -9,10 +9,10 @@ Example: --proxytunnel -x http://proxy $URL Added: 7.3 Multi: boolean --- -When an HTTP proxy is used --proxy, this option will make curl tunnel through -the proxy. 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. +When an HTTP proxy is used --proxy, this option makes curl tunnel the traffic +through the proxy. 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. To suppress proxy CONNECT response headers when curl is set to output headers use --suppress-connect-headers. diff --git a/docs/cmdline-opts/quote.d b/docs/cmdline-opts/quote.d index f4ee92d883..5008d49321 100644 --- a/docs/cmdline-opts/quote.d +++ b/docs/cmdline-opts/quote.d @@ -22,9 +22,9 @@ directory, just before the file transfer command(s), prefix the command with a You may specify any number of commands. -By default curl will stop at first failure. To make curl continue even if the +By default curl stops at first failure. To make curl continue even if the command fails, prefix the command with an asterisk (*). Otherwise, if the -server returns failure for one of the commands, the entire operation will be +server returns failure for one of the commands, the entire operation is aborted. You must send syntactically correct FTP commands as RFC 959 defines to FTP diff --git a/docs/cmdline-opts/random-file.d b/docs/cmdline-opts/random-file.d index eb6b6f3c4d..aa076de7fc 100644 --- a/docs/cmdline-opts/random-file.d +++ b/docs/cmdline-opts/random-file.d @@ -12,5 +12,5 @@ Multi: single Deprecated option. This option is ignored (added in 7.84.0). Prior to that it only had an effect on curl if built to use old versions of OpenSSL. -Specify the path name to file containing what will be considered as random -data. The data may be used to seed the random engine for SSL connections. +Specify the path name to file containing random data. The data may be used to +seed the random engine for SSL connections. diff --git a/docs/cmdline-opts/range.d b/docs/cmdline-opts/range.d index 7fe19ca058..eba7220e1e 100644 --- a/docs/cmdline-opts/range.d +++ b/docs/cmdline-opts/range.d @@ -34,18 +34,16 @@ specifies the first and last byte only(*)(HTTP) specifies two separate 100-byte ranges(*) (HTTP) .RE .IP -(*) = NOTE that this will cause the server to reply with a multipart -response, which will be returned as-is by curl! Parsing or otherwise -transforming this response is the responsibility of the caller. +(*) = NOTE that this causes the server to reply with a multipart response, +which is returned as-is by curl! Parsing or otherwise transforming this +response is the responsibility of the caller. Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the -'start-stop' range syntax. If a non-digit character is given in the range, -the server's response will be unspecified, depending on the server's -configuration. +'start-stop' range syntax. If a non-digit character is given in the range, the +server's response is unspecified, depending on the server's configuration. -You should also be aware that many HTTP/1.1 servers do not have this feature -enabled, so that when you attempt to get a range, you will instead get the -whole document. +Many HTTP/1.1 servers do not have this feature enabled, so that when you +attempt to get a range, curl instead gets the whole document. FTP and SFTP range downloads only support the simple 'start-stop' syntax (optionally with one of the numbers omitted). FTP use depends on the extended diff --git a/docs/cmdline-opts/rate.d b/docs/cmdline-opts/rate.d index 232106a607..d3cbd2849d 100644 --- a/docs/cmdline-opts/rate.d +++ b/docs/cmdline-opts/rate.d @@ -14,10 +14,10 @@ Scope: global --- Specify the maximum transfer frequency you allow curl to use - in number of transfer starts per time unit (sometimes called request rate). Without this -option, curl will start the next transfer as fast as possible. +option, curl starts the next transfer as fast as possible. If given several URLs and a transfer completes faster than the allowed rate, -curl will wait until the next transfer is started to maintain the requested +curl waits until the next transfer is started to maintain the requested rate. This option has no effect when --parallel is used. The request rate is provided as "N/U" where N is an integer number and U is a @@ -25,11 +25,11 @@ time unit. Supported units are 's' (second), 'm' (minute), 'h' (hour) and 'd' /(day, as in a 24 hour unit). The default time unit, if no "/U" is provided, is number of transfers per hour. -If curl is told to allow 10 requests per minute, it will not start the next +If curl is told to allow 10 requests per minute, it does not start the next request until 6 seconds have elapsed since the previous transfer was started. This function uses millisecond resolution. If the allowed frequency is set -more than 1000 per second, it will instead run unrestricted. +more than 1000 per second, it instead runs unrestricted. When retrying transfers, enabled with --retry, the separate retry delay logic is used and not this setting. diff --git a/docs/cmdline-opts/remote-header-name.d b/docs/cmdline-opts/remote-header-name.d index 14fd8a2942..917fe7abf2 100644 --- a/docs/cmdline-opts/remote-header-name.d +++ b/docs/cmdline-opts/remote-header-name.d @@ -12,16 +12,16 @@ Multi: boolean --- 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-provided file name contains a path, that will be stripped off -before the file name is used. +the server-provided file name contains a path, that is stripped off before the +file name is used. The file is saved in the current directory, or in the directory specified with --output-dir. If the server specifies a file name and a file with that name already exists -in the destination directory, it will not be overwritten and an error will -occur - unless you allow it by using the --clobber option. If the server does -not specify a file name then this option has no effect. +in the destination directory, it is not overwritten and an error occurs - +unless you allow it by using the --clobber option. If the server does not +specify a file name then this option has no effect. There is no attempt to decode %-sequences (yet) in the provided file name, so this option may provide you with rather unexpected file names. diff --git a/docs/cmdline-opts/remote-name.d b/docs/cmdline-opts/remote-name.d index 8a4a9bc3ed..215cf72deb 100644 --- a/docs/cmdline-opts/remote-name.d +++ b/docs/cmdline-opts/remote-name.d @@ -12,17 +12,17 @@ Multi: append 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 or use --output-dir. +The file is 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 or use --output-dir. 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 +nothing else, and if it already exists it is 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. +that name already exists it is not 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. +encoded parts of the name, they end up as-is as file name. You may use this option as many times as the number of URLs you have. diff --git a/docs/cmdline-opts/remote-time.d b/docs/cmdline-opts/remote-time.d index a8161c56cc..6dfb26c491 100644 --- a/docs/cmdline-opts/remote-time.d +++ b/docs/cmdline-opts/remote-time.d @@ -9,6 +9,6 @@ Added: 7.9 See-also: remote-name time-cond Multi: boolean --- -When used, this will make curl attempt to figure out the timestamp of the -remote file, and if that is available make the local file get that same +Makes curl attempt to figure out the timestamp of the remote file that is +getting downloaded, and if that is available make the local file get that same timestamp. diff --git a/docs/cmdline-opts/request.d b/docs/cmdline-opts/request.d index 5c01c6b4d6..0020babf91 100644 --- a/docs/cmdline-opts/request.d +++ b/docs/cmdline-opts/request.d @@ -15,21 +15,21 @@ Change the method to use when starting the transfer. .RS .TP 15 **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. +Specifies a custom request method to use when communicating with the HTTP +server. The specified request method is 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 do not 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. +request, using -X HEAD does not suffice. You need to use the --head option. -The method string you set with --request will be used for all requests, which +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. diff --git a/docs/cmdline-opts/resolve.d b/docs/cmdline-opts/resolve.d index bfecb147eb..31dd099a2f 100644 --- a/docs/cmdline-opts/resolve.d +++ b/docs/cmdline-opts/resolve.d @@ -13,22 +13,22 @@ Provide a custom address for a specific host and port pair. Using this, you can make the curl requests(s) use a specified address and prevent the otherwise normally resolved address to be used. Consider it a sort of /etc/hosts alternative provided on the command line. The port number should be -the number used for the specific protocol the host will be used for. It means +the number used for the specific protocol the host is used for. It means you need several entries if you want to provide address for the same host but different ports. By specifying '*' as host you can tell curl to resolve any host and specific port pair to the specified address. Wildcard is resolved last so any --resolve -with a specific host and port will be used first. +with a specific host and port is used first. -The provided address set by this option will be used even if --ipv4 or --ipv6 -is set to make curl use another IP version. +The provided address set by this option is used even if --ipv4 or --ipv6 is +set to make curl use another IP version. By prefixing the host with a '+' you can make the entry time out after curl's -default timeout (1 minute). Note that this will only make sense for long -running parallel transfers with a lot of files. In such cases, if this option -is used curl will try to resolve the host as it normally would once the -timeout has expired. +default timeout (1 minute). Note that this only makes sense for long running +parallel transfers with a lot of files. In such cases, if this option is used +curl tries to resolve the host as it normally would once the timeout has +expired. Support for providing the IP address within [brackets] was added in 7.57.0. diff --git a/docs/cmdline-opts/retry-all-errors.d b/docs/cmdline-opts/retry-all-errors.d index e0240d4bbe..1190d6a3ae 100644 --- a/docs/cmdline-opts/retry-all-errors.d +++ b/docs/cmdline-opts/retry-all-errors.d @@ -25,10 +25,10 @@ file, which are not reset. We strongly suggest you do not parse or record output via redirect in combination with this option, since you may receive duplicate data. -By default curl will not error on an HTTP response code that indicates an HTTP -error, if the transfer was successful. For example, if a server replies 404 -Not Found and the reply is fully received then that is not an error. When ---retry is used then curl will retry on some HTTP response codes that indicate -transient HTTP errors, but that does not include most 4xx response codes such -as 404. If you want to retry on all response codes that indicate HTTP errors -(4xx and 5xx) then combine with --fail. +By default curl does not return error for transfers with an HTTP response code +that indicates an HTTP error, if the transfer was successful. For example, if +a server replies 404 Not Found and the reply is fully received then that is +not an error. When --retry is used then curl retries on some HTTP response +codes that indicate transient HTTP errors, but that does not include most 4xx +response codes such as 404. If you want to retry on all response codes that +indicate HTTP errors (4xx and 5xx) then combine with --fail. diff --git a/docs/cmdline-opts/retry-delay.d b/docs/cmdline-opts/retry-delay.d index 5f5489772f..686a0d8ba4 100644 --- a/docs/cmdline-opts/retry-delay.d +++ b/docs/cmdline-opts/retry-delay.d @@ -12,4 +12,4 @@ Multi: single Make curl sleep this amount of time before each retry when a transfer has failed with a transient error (it changes the default backoff time algorithm between retries). This option is only interesting if --retry is also -used. Setting this delay to zero will make curl use the default backoff time. +used. Setting this delay to zero makes curl use the default backoff time. diff --git a/docs/cmdline-opts/retry-max-time.d b/docs/cmdline-opts/retry-max-time.d index a919dcae28..de2aff9a80 100644 --- a/docs/cmdline-opts/retry-max-time.d +++ b/docs/cmdline-opts/retry-max-time.d @@ -9,9 +9,9 @@ Example: --retry-max-time 30 --retry 10 $URL See-also: retry Multi: single --- -The retry timer is reset before the first transfer attempt. Retries will be -done as usual (see --retry) as long as the timer has not reached this given -limit. Notice that if the timer has not reached the limit, the request will be +The retry timer is reset before the first transfer attempt. Retries are done +as usual (see --retry) as long as the timer has not reached this given +limit. Notice that if the timer has not reached the limit, the request is made and while performing, it may take longer than this given time period. To -limit a single request's maximum time, use --max-time. Set this option to -zero to not timeout retries. +limit a single request's maximum time, use --max-time. Set this option to zero +to not timeout retries. diff --git a/docs/cmdline-opts/sasl-authzid.d b/docs/cmdline-opts/sasl-authzid.d index acccf680e8..872818df77 100644 --- a/docs/cmdline-opts/sasl-authzid.d +++ b/docs/cmdline-opts/sasl-authzid.d @@ -13,7 +13,7 @@ Use this authorization identity (**authzid**), during SASL PLAIN authentication, in addition to the authentication identity (**authcid**) as specified by --user. -If the option is not specified, the server will derive the **authzid** from -the **authcid**, but if specified, and depending on the server implementation, it +If the option is not specified, the server derives the **authzid** from the +**authcid**, but if specified, and depending on the server implementation, it may be used to access another user's inbox, that the user has been granted access to, or a shared mailbox for example. diff --git a/docs/cmdline-opts/silent.d b/docs/cmdline-opts/silent.d index 8742061734..74bb299cc2 100644 --- a/docs/cmdline-opts/silent.d +++ b/docs/cmdline-opts/silent.d @@ -10,7 +10,7 @@ Added: 4.0 Multi: boolean --- Silent or quiet mode. Do not show progress meter or error messages. Makes Curl -mute. It will still output the data you ask for, potentially even to the +mute. It still outputs the data you ask for, potentially even to the terminal/stdout unless you redirect it. Use --show-error in addition to this option to disable progress meter but diff --git a/docs/cmdline-opts/speed-time.d b/docs/cmdline-opts/speed-time.d index fe92b97f11..4a8860660a 100644 --- a/docs/cmdline-opts/speed-time.d +++ b/docs/cmdline-opts/speed-time.d @@ -10,9 +10,9 @@ Added: 4.7 See-also: speed-limit limit-rate Multi: single --- -If a transfer runs slower than speed-limit bytes per second during a speed-time -period, the transfer is aborted. If speed-time is used, the default -speed-limit will be 1 unless set with --speed-limit. +If a transfer runs slower than speed-limit bytes per second during a +speed-time period, the transfer is aborted. If speed-time is used, the default +speed-limit is 1 unless set with --speed-limit. -This option controls transfers (in both directions) but will not affect slow +This option controls transfers (in both directions) but does not affect slow connects etc. If this is a concern for you, try the --connect-timeout option. diff --git a/docs/cmdline-opts/ssl-reqd.d b/docs/cmdline-opts/ssl-reqd.d index 1f33c7dcf6..8a5b8577e0 100644 --- a/docs/cmdline-opts/ssl-reqd.d +++ b/docs/cmdline-opts/ssl-reqd.d @@ -18,6 +18,6 @@ required. This option is unnecessary if you use a URL scheme that in itself implies immediate and implicit use of TLS, like for FTPS, IMAPS, POP3S, SMTPS and -LDAPS. Such transfers will always fail if the TLS handshake does not work. +LDAPS. Such a transfer always fails if the TLS handshake does not work. This option was formerly known as --ftp-ssl-reqd. diff --git a/docs/cmdline-opts/ssl.d b/docs/cmdline-opts/ssl.d index 59c505cbcb..b8fd22a9ca 100644 --- a/docs/cmdline-opts/ssl.d +++ b/docs/cmdline-opts/ssl.d @@ -23,4 +23,4 @@ Please note that a server may close the connection if the negotiation does not succeed. This option was formerly known as --ftp-ssl (added in 7.11.0). That option -name can still be used but will be removed in a future version. +name can still be used but might be removed in a future version. diff --git a/docs/cmdline-opts/sslv3.d b/docs/cmdline-opts/sslv3.d index cccf00889e..409afc610f 100644 --- a/docs/cmdline-opts/sslv3.d +++ b/docs/cmdline-opts/sslv3.d @@ -13,6 +13,5 @@ Category: tls Example: --sslv3 $URL Multi: mutex --- - This option previously asked curl to use SSLv3, but is now ignored (added in 7.77.0). SSLv3 is widely considered insecure (see RFC 7568). diff --git a/docs/cmdline-opts/tftp-blksize.d b/docs/cmdline-opts/tftp-blksize.d index 289ce7542b..76c7ee4b13 100644 --- a/docs/cmdline-opts/tftp-blksize.d +++ b/docs/cmdline-opts/tftp-blksize.d @@ -11,5 +11,5 @@ See-also: tftp-no-options Multi: single --- Set the 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. +curl tries to use when transferring data to or from a TFTP server. By +default 512 bytes are used. diff --git a/docs/cmdline-opts/trace-config.d b/docs/cmdline-opts/trace-config.d index 636e96b0d4..06d6d77b92 100644 --- a/docs/cmdline-opts/trace-config.d +++ b/docs/cmdline-opts/trace-config.d @@ -11,8 +11,8 @@ See-also: verbose trace Multi: append Scope: global --- -Set configuration for trace output. A comma-separated list of components -where detailed output will be made available from. Names are case-insensitive. +Set configuration for trace output. A comma-separated list of components where +detailed output can be made available from. Names are case-insensitive. Specify 'all' to enable all trace components. In addition to trace component names, specify "ids" and "time" to diff --git a/docs/cmdline-opts/upload-file.d b/docs/cmdline-opts/upload-file.d index b6cbef1067..e89390ab8c 100644 --- a/docs/cmdline-opts/upload-file.d +++ b/docs/cmdline-opts/upload-file.d @@ -12,12 +12,13 @@ Added: 4.0 See-also: get head Multi: append --- -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. +This transfers the specified local file to the remote URL. + +If there is no file part in the specified URL, curl appends the local file +name to the end of the URL before the operation starts. You must use a +trailing slash (/) on the last directory to prove to curl that there is no +file name or curl thinks that your last directory name is the remote file name +to use. If this is used on an HTTP(S) server, the PUT command is 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 @@ -32,5 +33,5 @@ in the URL. 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 +formatted correctly by the user as curl does not transcode nor encode it further in any way. diff --git a/docs/cmdline-opts/url.d b/docs/cmdline-opts/url.d index 5e0a60b268..fa0421e08b 100644 --- a/docs/cmdline-opts/url.d +++ b/docs/cmdline-opts/url.d @@ -13,10 +13,11 @@ 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 subdomain name -matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be used, -otherwise HTTP will be used. Guessing can be disabled by setting a default -protocol (added in 7.45.0), see --proto-default for details. +then curl makes a guess based on the host. If the outermost subdomain name +matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol is used, +otherwise HTTP is used. Guessing can be avoided by providing a full URL +including the scheme, or disabled by setting a default protocol (added in +7.45.0), see --proto-default for details. To control where this URL is written, use the --output or the --remote-name options. diff --git a/docs/cmdline-opts/user-agent.d b/docs/cmdline-opts/user-agent.d index 33cbe210be..1681b7e8b6 100644 --- a/docs/cmdline-opts/user-agent.d +++ b/docs/cmdline-opts/user-agent.d @@ -15,6 +15,6 @@ 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 header can also be set with the --header or the --proxy-header options. -If you give an empty argument to --user-agent (""), it will remove the header +If you give an empty argument to --user-agent (""), it removes the header completely from the request. If you prefer a blank header, you can set it to a single space (" "). diff --git a/docs/cmdline-opts/user.d b/docs/cmdline-opts/user.d index 63ca4c5420..f776ab7ae4 100644 --- a/docs/cmdline-opts/user.d +++ b/docs/cmdline-opts/user.d @@ -13,17 +13,17 @@ Multi: single 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. +If you simply specify the user name, curl prompts 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. -On systems where it works, curl will hide the given option argument from -process listings. This is not enough to protect credentials from possibly -getting seen by other users on the same system as they will still be visible -for a moment before cleared. Such sensitive data should be retrieved from a -file instead or similar and never used in clear text in a command line. +On systems where it works, curl hides the given option argument from process +listings. This is not enough to protect credentials from possibly getting seen +by other users on the same system as they still are visible for a brief moment +before cleared. Such sensitive data should be retrieved from a file instead or +similar and never used in clear text in a command line. 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 diff --git a/docs/cmdline-opts/variable.d b/docs/cmdline-opts/variable.d index 03c1321203..d7d773edab 100644 --- a/docs/cmdline-opts/variable.d +++ b/docs/cmdline-opts/variable.d @@ -14,8 +14,7 @@ if set to a single dash (-)). The name is a case sensitive identifier that must consist of no other letters than a-z, A-Z, 0-9 or underscore. The specified content is then associated with this identifier. -Setting the same variable name again will overwrite the old contents with the -new. +Setting the same variable name again overwrites the old contents with the new. The contents of a variable can be referenced in a later command line option when that option name is prefixed with "--expand-", and the name is used as @@ -35,7 +34,7 @@ When expanding variables, curl supports a set of functions that can make the variable contents more convenient to use. You apply a function to a variable expansion by adding a colon and then list the desired functions in a comma-separated list that is evaluated in a left-to-right order. Variable -content holding null bytes that are not encoded when expanded, will cause +content holding null bytes that are not encoded when expanded, causes an error. Available functions: diff --git a/docs/cmdline-opts/write-out.d b/docs/cmdline-opts/write-out.d index febbd35279..b2ac2ec060 100644 --- a/docs/cmdline-opts/write-out.d +++ b/docs/cmdline-opts/write-out.d @@ -16,14 +16,14 @@ 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 +The variables present in the output format are 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. -The output will be written to standard output, but this can be switched to -standard error by using %{stderr}. +The output is by default written to standard output, but can be changed with +%{stderr} and %output{}. Output HTTP headers from the most recent request by using *%header{name}* where *name* is the case insensitive name of the header (without the trailing @@ -128,7 +128,7 @@ requested. 0 means the verification was successful. (Added in 7.52.0) .TP **redirect_url** When an HTTP request was made without --location to follow redirects (or when ---max-redirs is met), this variable will show the actual URL a redirect +--max-redirs is met), this variable shows the actual URL a redirect *would* have gone to. (Added in 7.18.2) .TP **referer** @@ -175,11 +175,11 @@ The result of the SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.19.0) .TP **stderr** -From this point on, the --write-out output will be written to standard +From this point on, the --write-out output is written to standard error. (Added in 7.63.0) .TP **stdout** -From this point on, the --write-out output will be written to standard output. +From this point on, the --write-out output is written to standard output. This is the default, but can be used to switch back after switching to stderr. (Added in 7.63.0) .TP