diff --git a/docs/CHECKSRC.md b/docs/CHECKSRC.md index 0406a7f6b8..476df262a1 100644 --- a/docs/CHECKSRC.md +++ b/docs/CHECKSRC.md @@ -41,7 +41,7 @@ warnings are: more appropriate `char *name` style. The asterisk should sit right next to the name without a space in between. -- `BADCOMMAND`: There's a bad `checksrc` instruction in the code. See the +- `BADCOMMAND`: There is a bad `checksrc` instruction in the code. See the **Ignore certain warnings** section below for details. - `BANNEDFUNC`: A banned function was used. The functions sprintf, vsprintf, diff --git a/docs/CODE_STYLE.md b/docs/CODE_STYLE.md index 6712de00dd..9cdf0d17e4 100644 --- a/docs/CODE_STYLE.md +++ b/docs/CODE_STYLE.md @@ -60,7 +60,7 @@ Source code in curl may never be wider than 79 columns and there are two reasons for maintaining this even in the modern era of large and high resolution screens: -1. Narrower columns are easier to read than wide ones. There's a reason +1. Narrower columns are easier to read than wide ones. There is a reason newspapers have used columns for decades or centuries. 2. Narrower columns allow developers to easier show multiple pieces of code diff --git a/docs/CONTRIBUTE.md b/docs/CONTRIBUTE.md index 16c126bad5..72d3190019 100644 --- a/docs/CONTRIBUTE.md +++ b/docs/CONTRIBUTE.md @@ -206,11 +206,11 @@ A short guide to how to write git commit messages in the curl project. [Bug: URL to the source of the report or more related discussion; use Fixes for GitHub issues instead when that is appropriate] [Approved-by: John Doe - credit someone who approved the PR; if you are - committing this for someone else using --author=... you don't need this + committing this for someone else using --author=... you do not need this as you are implicitly approving it by committing] [Authored-by: John Doe - credit the original author of the code; only use - this if you can't use "git commit --author=..."] - [Signed-off-by: John Doe - we don't use this, but don't bother removing it] + this if you cannot use "git commit --author=..."] + [Signed-off-by: John Doe - we do not use this, but do not bother removing it] [whatever-else-by: credit all helpers, finders, doers; try to use one of the following keywords if at all possible, for consistency: Acked-by:, Assisted-by:, Co-authored-by:, Found-by:, Reported-by:, @@ -232,7 +232,7 @@ The first line is a succinct description of the change: - no period (.) at the end The `[area]` in the first line can be `http2`, `cookies`, `openssl` or -similar. There's no fixed list to select from but using the same "area" as +similar. There is no fixed list to select from but using the same "area" as other related changes could make sense. Do not forget to use commit --author=... if you commit someone else's work, and @@ -240,9 +240,9 @@ make sure that you have your own user and email setup correctly in git before you commit. Add whichever header lines as appropriate, with one line per person if more -than one person was involved. There's no need to credit yourself unless you are -using --author=... which hides your identity. Don't include people's e-mail -addresses in headers to avoid spam, unless they're already public from a +than one person was involved. There is no need to credit yourself unless you are +using --author=... which hides your identity. Do not include people's e-mail +addresses in headers to avoid spam, unless they are already public from a previous commit; saying `{userid} on github` is OK. ### Write Access to git Repository diff --git a/docs/DYNBUF.md b/docs/DYNBUF.md index b0d39296ba..c3a4b76679 100644 --- a/docs/DYNBUF.md +++ b/docs/DYNBUF.md @@ -27,7 +27,7 @@ void Curl_dyn_free(struct dynbuf *s); ``` Free the associated memory and clean up. After a free, the `dynbuf` struct can -be re-used to start appending new data to. +be reused to start appending new data to. ## `Curl_dyn_addn` diff --git a/docs/EARLY-RELEASE.md b/docs/EARLY-RELEASE.md index 989a20799c..6d5a5e25b4 100644 --- a/docs/EARLY-RELEASE.md +++ b/docs/EARLY-RELEASE.md @@ -49,7 +49,7 @@ the three ones above are all 'no'. - Is there a (decent) workaround? - Is it a regression? Is the bug introduced in this release? - Can the bug be fixed "easily" by applying a patch? - - Does the bug break the build? Most users don't build curl themselves. + - Does the bug break the build? Most users do not build curl themselves. - How long is it until the already scheduled next release? - Can affected users safely rather revert to a former release until the next scheduled release? diff --git a/docs/FAQ b/docs/FAQ index aacf48615e..78a238832a 100644 --- a/docs/FAQ +++ b/docs/FAQ @@ -1498,7 +1498,7 @@ FAQ unknown to me). After a transfer, you just set new options in the handle and make another - transfer. This will make libcurl re-use the same connection if it can. + transfer. This will make libcurl reuse the same connection if it can. 7.4 Does PHP/CURL have dependencies? diff --git a/docs/HELP-US.md b/docs/HELP-US.md index 03a4e3acb9..90c9724b21 100644 --- a/docs/HELP-US.md +++ b/docs/HELP-US.md @@ -38,7 +38,7 @@ even maybe not a terribly experienced developer, here's our advice: In the issue tracker we occasionally mark bugs with [help wanted](https://github.com/curl/curl/labels/help%20wanted), as a sign that the -bug is acknowledged to exist and that there's nobody known to work on this +bug is acknowledged to exist and that there is nobody known to work on this issue for the moment. Those are bugs that are fine to "grab" and provide a pull request for. The complexity level of these will of course vary, so pick one that piques your interest. diff --git a/docs/HISTORY.md b/docs/HISTORY.md index 867139e3c8..f39c45ea12 100644 --- a/docs/HISTORY.md +++ b/docs/HISTORY.md @@ -161,7 +161,7 @@ Starting with 7.10, curl verifies SSL server certificates by default. January: Started working on the distributed curl tests. The autobuilds. February: the curl site averages at 20000 visits weekly. At any given moment, -there's an average of 3 people browsing the website. +there is an average of 3 people browsing the website. Multiple new authentication schemes are supported: Digest (May), NTLM (June) and Negotiate (June). diff --git a/docs/HTTP2.md b/docs/HTTP2.md index 938560226e..5b4028349c 100644 --- a/docs/HTTP2.md +++ b/docs/HTTP2.md @@ -55,14 +55,14 @@ connection. To take advantage of multiplexing, you need to use the multi interface and set `CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl will -attempt to re-use existing HTTP/2 connections and just add a new stream over +attempt to reuse existing HTTP/2 connections and just add a new stream over that when doing subsequent parallel requests. While libcurl sets up a connection to an HTTP server there is a period during which it does not know if it can pipeline or do multiplexing and if you add new transfers in that period, libcurl will default to start new connections for those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), -you can ask that a transfer should rather wait and see in case there's a +you can ask that a transfer should rather wait and see in case there is a connection for the same host in progress that might end up being possible to multiplex on. It favors keeping the number of connections low to the cost of slightly longer time to first byte transferred. diff --git a/docs/HTTP3.md b/docs/HTTP3.md index 2ee77c9415..5b1832f695 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -340,7 +340,7 @@ should be either in your PATH or your current directory. Create a `Caddyfile` with the following content: ~~~ localhost:7443 { - respond "Hello, world! You're using {http.request.proto}" + respond "Hello, world! you are using {http.request.proto}" } ~~~ diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index 02a6fcf617..a33976f014 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -101,8 +101,8 @@ problems may have been fixed or changed somewhat since this was written. 15.13 CMake build with MIT Kerberos does not work 16. aws-sigv4 - 16.1 aws-sigv4 doesn't sign requests with * correctly - 16.2 aws-sigv4 doesn't sign requests with valueless queries correctly + 16.1 aws-sigv4 does not sign requests with * correctly + 16.2 aws-sigv4 does not sign requests with valueless queries correctly 16.3 aws-sigv4 is missing the amz-content-sha256 header 16.4 aws-sigv4 does not sort query string parameters before signing 16.5 aws-sigv4 does not sign requests with empty URL query correctly @@ -516,8 +516,8 @@ problems may have been fixed or changed somewhat since this was written. 13.2 Trying local ports fails on Windows - This makes '--local-port [range]' to not work since curl can't properly - detect if a port is already in use, so it'll try the first port, use that and + This makes '--local-port [range]' to not work since curl cannot properly + detect if a port is already in use, so it will try the first port, use that and then subsequently fail anyway if that was actually in use. https://github.com/curl/curl/issues/8112 @@ -581,11 +581,11 @@ problems may have been fixed or changed somewhat since this was written. 16. aws-sigv4 -16.1 aws-sigv4 doesn't sign requests with * correctly +16.1 aws-sigv4 does not sign requests with * correctly https://github.com/curl/curl/issues/7559 -16.2 aws-sigv4 doesn't sign requests with valueless queries correctly +16.2 aws-sigv4 does not sign requests with valueless queries correctly https://github.com/curl/curl/issues/8107 diff --git a/docs/MAIL-ETIQUETTE b/docs/MAIL-ETIQUETTE index ccd3e01f9c..2dcf9cb896 100644 --- a/docs/MAIL-ETIQUETTE +++ b/docs/MAIL-ETIQUETTE @@ -120,7 +120,7 @@ MAIL ETIQUETTE your email address and password and press the unsubscribe button. Also, the instructions to unsubscribe are included in the headers of every - mail that is sent out to all curl related mailing lists and there's a footer + mail that is sent out to all curl related mailing lists and there is a footer in each mail that links to the "admin" page on which you can unsubscribe and change other options. diff --git a/docs/THANKS-filter b/docs/THANKS-filter index 4292f64ba8..6571e430c4 100644 --- a/docs/THANKS-filter +++ b/docs/THANKS-filter @@ -26,7 +26,7 @@ # appropriately in THANKS. This list contains variations of their names and # their "canonical" name. This file is used for scripting purposes to avoid # duplicate entries and will not be included in release tarballs. -# When removing dupes that aren't identical names from THANKS, add a line +# When removing dupes that are not identical names from THANKS, add a line # here! # # Used-by: contributors.sh diff --git a/docs/TODO b/docs/TODO index b7530dc3f1..a8e090c168 100644 --- a/docs/TODO +++ b/docs/TODO @@ -685,7 +685,7 @@ 6.4 exit immediately upon connection if stdin is /dev/null - If it did, curl could be used to probe if there's an server there listening + If it did, curl could be used to probe if there is an server there listening on a specific port. That is, the following command would exit immediately after the connection is established with exit code 0: @@ -819,9 +819,9 @@ request as well, when they should only be necessary once per SSL context (or once per handle)". The major improvement we can rather easily do is to make sure we do not create and kill a new SSL "context" for every request, but - instead make one for every connection and re-use that SSL context in the same - style connections are re-used. It will make us use slightly more memory but - it will libcurl do less creations and deletions of SSL contexts. + instead make one for every connection and reuse that SSL context in the same + style connections are reused. It will make us use slightly more memory but it + will libcurl do less creations and deletions of SSL contexts. Technically, the "caching" is probably best implemented by getting added to the share interface so that easy handles who want to and can reuse the @@ -841,7 +841,7 @@ OpenSSL supports a callback for customised verification of the peer certificate, but this does not seem to be exposed in the libcurl APIs. Could - it be? There's so much that could be done if it were. + it be? There is so much that could be done if it were. 13.7 Less memory massaging with Schannel @@ -1101,7 +1101,7 @@ 18.13 Ratelimit or wait between serial requests Consider a command line option that can make curl do multiple serial requests - slow, potentially with a (random) wait between transfers. There's also a + slow, potentially with a (random) wait between transfers. There is also a proposed set of standard HTTP headers to let servers let the client adapt to its rate limits: https://www.ietf.org/id/draft-polli-ratelimit-headers-02.html @@ -1139,7 +1139,7 @@ URL, the file name is not extracted and used from the newly redirected-to URL even if the new URL may have a much more sensible file name. - This is clearly documented and helps for security since there's no surprise + This is clearly documented and helps for security since there is no surprise to users which file name that might get overwritten. But maybe a new option could allow for this or maybe -J should imply such a treatment as well as -J already allows for the server to decide what file name to use so it already @@ -1341,9 +1341,9 @@ 20.5 Add support for concurrent connections - Tests 836, 882 and 938 were designed to verify that separate connections - are not used when using different login credentials in protocols that - should not re-use a connection under such circumstances. + Tests 836, 882 and 938 were designed to verify that separate connections are + not used when using different login credentials in protocols that should not + reuse a connection under such circumstances. Unfortunately, ftpserver.pl does not appear to support multiple concurrent connections. The read while() loop seems to loop until it receives a diff --git a/docs/URL-SYNTAX.md b/docs/URL-SYNTAX.md index 384aa4a269..adb431457b 100644 --- a/docs/URL-SYNTAX.md +++ b/docs/URL-SYNTAX.md @@ -197,7 +197,7 @@ of Windows. ## Port number -If there's a colon after the hostname, that should be followed by the port +If there is a colon after the hostname, that should be followed by the port number to use. 1 - 65535. curl also supports a blank port number field - but only if the URL starts with a scheme. @@ -379,7 +379,7 @@ The default smtp port is 25. Some servers use port 587 as an alternative. ## RTMP -There's no official URL spec for RTMP so libcurl uses the URL syntax supported +There is no official URL spec for RTMP so libcurl uses the URL syntax supported by the underlying librtmp library. It has a syntax where it wants a traditional URL, followed by a space and a series of space-separated `name=value` pairs. diff --git a/docs/cmdline-opts/form-string.d b/docs/cmdline-opts/form-string.d index 32baab0f50..6d7a500a44 100644 --- a/docs/cmdline-opts/form-string.d +++ b/docs/cmdline-opts/form-string.d @@ -13,5 +13,5 @@ Multi: append Similar to --form except that the value string for the named parameter is used literally. Leading '@' and '<' characters, and the ';type=' string in the value have no special meaning. Use this in preference to --form if -there's any possibility that the string value may accidentally trigger the +there is any possibility that the string value may accidentally trigger the '@' or '<' features of --form. diff --git a/docs/cmdline-opts/ftp-skip-pasv-ip.d b/docs/cmdline-opts/ftp-skip-pasv-ip.d index 4b38f9f9b6..c6155ebecd 100644 --- a/docs/cmdline-opts/ftp-skip-pasv-ip.d +++ b/docs/cmdline-opts/ftp-skip-pasv-ip.d @@ -9,10 +9,9 @@ Category: ftp 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 re-use the same IP address it already uses for the control -connection. +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. Since curl 7.74.0 this option is enabled by default. diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index 82196c2176..303da2f531 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -33,7 +33,7 @@ Dev notes: We open *input* files in :crlf translation (a no-op on many platforms) in case we have CRLF line endings in Windows but a perl that defaults to LF. -Unfortunately it seems some perls like msysgit can't handle a global input-only +Unfortunately it seems some perls like msysgit cannot handle a global input-only :crlf so it has to be specified on each file open for text input. =end comment @@ -183,7 +183,7 @@ sub too_old { sub added { my ($standalone, $data)=@_; if(too_old($data)) { - # don't mention ancient additions + # do not mention ancient additions return ""; } if($standalone) { diff --git a/docs/cmdline-opts/noproxy.d b/docs/cmdline-opts/noproxy.d index d4c34a7fab..62948ab44f 100644 --- a/docs/cmdline-opts/noproxy.d +++ b/docs/cmdline-opts/noproxy.d @@ -17,7 +17,7 @@ example, local.com would match local.com, local.com:80, and www.local.com, but not www.notlocal.com. Since 7.53.0, This option overrides the environment variables that disable the -proxy ('no_proxy' and 'NO_PROXY'). If there's an environment variable +proxy ('no_proxy' and 'NO_PROXY'). If there is an environment variable disabling a proxy, you can set the no proxy list to "" to override it. Since 7.86.0, IP addresses specified to this option can be provided using CIDR diff --git a/docs/cmdline-opts/page-header b/docs/cmdline-opts/page-header index 008dcf67c7..3ea99f7d3c 100644 --- a/docs/cmdline-opts/page-header +++ b/docs/cmdline-opts/page-header @@ -51,9 +51,9 @@ 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 re-use connections when doing multiple transfers, so that +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 -handshakes. This improves speed. Connection re-use can only be done for URLs +handshakes. This improves speed. Connection reuse can only be done for URLs specified for a single command line invocation and cannot be performed between separate curl runs. diff --git a/docs/cmdline-opts/proxy.d b/docs/cmdline-opts/proxy.d index ce622f4ec5..7097140ec0 100644 --- a/docs/cmdline-opts/proxy.d +++ b/docs/cmdline-opts/proxy.d @@ -31,7 +31,7 @@ If the port number is not specified in the proxy string, it is assumed to be 1080. This option overrides existing environment variables that set the proxy to -use. If there's an environment variable setting a proxy, you can set proxy to +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 diff --git a/docs/cmdline-opts/remote-header-name.d b/docs/cmdline-opts/remote-header-name.d index 8705b3b889..14fd8a2942 100644 --- a/docs/cmdline-opts/remote-header-name.d +++ b/docs/cmdline-opts/remote-header-name.d @@ -23,7 +23,7 @@ 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. -There's no attempt to decode %-sequences (yet) in the provided file name, so +There is no attempt to decode %-sequences (yet) in the provided file name, so this option may provide you with rather unexpected file names. This feature uses the name from the "filename" field, it does not yet support diff --git a/docs/examples/Makefile.example b/docs/examples/Makefile.example index cde00468d6..b10cdecf57 100644 --- a/docs/examples/Makefile.example +++ b/docs/examples/Makefile.example @@ -34,7 +34,7 @@ CC = gcc # Compiler flags, -g for debug, -c to make an object file CFLAGS = -c -g -# This should point to a directory that holds libcurl, if it isn't +# This should point to a directory that holds libcurl, if it is not # in the system's standard lib dir # We also set a -L to include the directory where we have the openssl # libraries diff --git a/docs/examples/Makefile.inc b/docs/examples/Makefile.inc index 68313659f8..60a006ca92 100644 --- a/docs/examples/Makefile.inc +++ b/docs/examples/Makefile.inc @@ -129,7 +129,7 @@ check_PROGRAMS = \ websocket-cb # These examples require external dependencies that may not be commonly -# available on POSIX systems, so don't bother attempting to compile them here. +# available on POSIX systems, so do not bother attempting to compile them here. COMPLICATED_EXAMPLES = \ cacertinmem.c \ crawler.c \ diff --git a/docs/examples/anyauthput.c b/docs/examples/anyauthput.c index ff09d83f0c..8b979515a6 100644 --- a/docs/examples/anyauthput.c +++ b/docs/examples/anyauthput.c @@ -60,7 +60,7 @@ static int my_seek(void *userp, curl_off_t offset, int origin) FILE *fp = (FILE *) userp; if(-1 == fseek(fp, (long) offset, origin)) - /* couldn't seek */ + /* could not seek */ return CURL_SEEKFUNC_CANTSEEK; return CURL_SEEKFUNC_OK; /* success! */ diff --git a/docs/examples/ftpget.c b/docs/examples/ftpget.c index b25e6680ae..94609fe0db 100644 --- a/docs/examples/ftpget.c +++ b/docs/examples/ftpget.c @@ -66,7 +66,7 @@ int main(void) */ curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/curl/curl-7.9.2.tar.gz"); - /* Define our callback to get called when there's data to be written */ + /* Define our callback to get called when there is data to be written */ curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, my_fwrite); /* Set a pointer to our struct to pass to the callback */ curl_easy_setopt(curl, CURLOPT_WRITEDATA, &ftpfile); diff --git a/docs/examples/ftpsget.c b/docs/examples/ftpsget.c index 88ba0023cd..dbe7d14bf7 100644 --- a/docs/examples/ftpsget.c +++ b/docs/examples/ftpsget.c @@ -70,7 +70,7 @@ int main(void) */ curl_easy_setopt(curl, CURLOPT_URL, "ftp://user@server/home/user/file.txt"); - /* Define our callback to get called when there's data to be written */ + /* Define our callback to get called when there is data to be written */ curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, my_fwrite); /* Set a pointer to our struct to pass to the callback */ curl_easy_setopt(curl, CURLOPT_WRITEDATA, &ftpfile); diff --git a/docs/examples/http2-pushinmemory.c b/docs/examples/http2-pushinmemory.c index c982bd5c51..74c64e0a69 100644 --- a/docs/examples/http2-pushinmemory.c +++ b/docs/examples/http2-pushinmemory.c @@ -92,7 +92,7 @@ static void setup(CURL *hnd) curl_easy_setopt(hnd, CURLOPT_PIPEWAIT, 1L); } -/* called when there's an incoming push */ +/* called when there is an incoming push */ static int server_push_callback(CURL *parent, CURL *easy, size_t num_headers, diff --git a/docs/examples/http2-serverpush.c b/docs/examples/http2-serverpush.c index 7524c62890..b5ebe2eb9a 100644 --- a/docs/examples/http2-serverpush.c +++ b/docs/examples/http2-serverpush.c @@ -161,7 +161,7 @@ static int setup(CURL *hnd, const char *url) return 0; /* all is good */ } -/* called when there's an incoming push */ +/* called when there is an incoming push */ static int server_push_callback(CURL *parent, CURL *easy, size_t num_headers, diff --git a/docs/examples/persistent.c b/docs/examples/persistent.c index 2b6eb46456..51bd8c352c 100644 --- a/docs/examples/persistent.c +++ b/docs/examples/persistent.c @@ -22,7 +22,7 @@ * ***************************************************************************/ /* - * re-using handles to do HTTP persistent connections + * reusing handles to do HTTP persistent connections * */ #include diff --git a/docs/examples/sftpget.c b/docs/examples/sftpget.c index ac2c879a77..6f0cb2ad4f 100644 --- a/docs/examples/sftpget.c +++ b/docs/examples/sftpget.c @@ -77,7 +77,7 @@ int main(void) */ curl_easy_setopt(curl, CURLOPT_URL, "sftp://user@server/home/user/file.txt"); - /* Define our callback to get called when there's data to be written */ + /* Define our callback to get called when there is data to be written */ curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, my_fwrite); /* Set a pointer to our struct to pass to the callback */ curl_easy_setopt(curl, CURLOPT_WRITEDATA, &ftpfile); diff --git a/docs/examples/smtp-authzid.c b/docs/examples/smtp-authzid.c index 3425d9a214..f13d6113d3 100644 --- a/docs/examples/smtp-authzid.c +++ b/docs/examples/smtp-authzid.c @@ -148,7 +148,7 @@ int main(void) curl_slist_free_all(recipients); /* curl will not send the QUIT command until you call cleanup, so you - * should be able to re-use this connection for additional messages + * should be able to reuse this connection for additional messages * (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and * calling curl_easy_perform() again. It may not be a good idea to keep * the connection open for a very long time though (more than a few diff --git a/docs/examples/smtp-expn.c b/docs/examples/smtp-expn.c index e8ba530ad9..6d896d42dd 100644 --- a/docs/examples/smtp-expn.c +++ b/docs/examples/smtp-expn.c @@ -69,7 +69,7 @@ int main(void) curl_slist_free_all(recipients); /* curl will not send the QUIT command until you call cleanup, so you - * should be able to re-use this connection for additional requests. It + * should be able to reuse this connection for additional requests. It * may not be a good idea to keep the connection open for a very long time * though (more than a few minutes may result in the server timing out the * connection) and you do want to clean up in the end. diff --git a/docs/examples/smtp-mail.c b/docs/examples/smtp-mail.c index 6d53770a9e..1ad178b9f0 100644 --- a/docs/examples/smtp-mail.c +++ b/docs/examples/smtp-mail.c @@ -136,7 +136,7 @@ int main(void) curl_slist_free_all(recipients); /* curl will not send the QUIT command until you call cleanup, so you - * should be able to re-use this connection for additional messages + * should be able to reuse this connection for additional messages * (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and * calling curl_easy_perform() again. It may not be a good idea to keep * the connection open for a very long time though (more than a few diff --git a/docs/examples/smtp-mime.c b/docs/examples/smtp-mime.c index 8e19e7e2ee..9c46fe901c 100644 --- a/docs/examples/smtp-mime.c +++ b/docs/examples/smtp-mime.c @@ -151,7 +151,7 @@ int main(void) curl_slist_free_all(headers); /* curl will not send the QUIT command until you call cleanup, so you - * should be able to re-use this connection for additional messages + * should be able to reuse this connection for additional messages * (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and * calling curl_easy_perform() again. It may not be a good idea to keep * the connection open for a very long time though (more than a few diff --git a/docs/examples/smtp-vrfy.c b/docs/examples/smtp-vrfy.c index 64d931095c..4396e0fdb8 100644 --- a/docs/examples/smtp-vrfy.c +++ b/docs/examples/smtp-vrfy.c @@ -69,7 +69,7 @@ int main(void) curl_slist_free_all(recipients); /* curl will not send the QUIT command until you call cleanup, so you - * should be able to re-use this connection for additional requests. It + * should be able to reuse this connection for additional requests. It * may not be a good idea to keep the connection open for a very long time * though (more than a few minutes may result in the server timing out the * connection) and you do want to clean up in the end. diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 index 3ddafad833..251bc90d19 100644 --- a/docs/libcurl/curl_easy_cleanup.3 +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -32,14 +32,13 @@ curl_easy_cleanup - End a libcurl easy handle void curl_easy_cleanup(CURL *handle); .fi .SH DESCRIPTION -This function must be the last function to call for an easy session. It is the -opposite of the \fIcurl_easy_init(3)\fP function and must be called with the -same \fIhandle\fP as input that a \fIcurl_easy_init(3)\fP call returned. +This function is the opposite of \fIcurl_easy_init(3)\fP. It closes down and +frees all resources previously associated with this easy handle. -This might close all connections this handle has used and possibly has kept -open until now - unless it was attached to a multi handle while doing the -transfers. Do not call this function if you intend to transfer more files, -re-using handles is a key to good performance with libcurl. +This call closes all connections this handle has used and possibly has kept +open until now unless the easy handle was attached to a multi handle while +doing the transfers. Do not call this function if you intend to transfer more +files, reusing handles is a key to good performance with libcurl. Occasionally you may get your progress callback or header callback called from within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using @@ -47,15 +46,14 @@ within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using connection and the protocol is of a kind that requires a command/response sequence before disconnect. Examples of such protocols are FTP, POP3 and IMAP. -Any use of the \fBhandle\fP after this function has been called and have -returned, is illegal. \fIcurl_easy_cleanup(3)\fP kills the handle and all -memory associated with it! +Any use of the easy \fBhandle\fP after this function has been called and have +returned, is illegal. To close an easy handle that has been used with the multi interface, make sure -to call \fIcurl_multi_remove_handle(3)\fP first to remove it from the multi +to first call \fIcurl_multi_remove_handle(3)\fP to remove it from the multi handle before it is closed. -Passing in a NULL pointer in \fIhandle\fP will make this function return +Passing in a NULL pointer in \fIhandle\fP makes this function return immediately with no action. .SH EXAMPLE .nf diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3 index af97729705..e9676488cf 100644 --- a/docs/libcurl/curl_easy_duphandle.3 +++ b/docs/libcurl/curl_easy_duphandle.3 @@ -31,20 +31,19 @@ curl_easy_duphandle - Clone a libcurl session handle CURL *curl_easy_duphandle(CURL *handle); .fi .SH DESCRIPTION -This function will return a new curl handle, a duplicate, using all the -options previously set in the input curl \fIhandle\fP. Both handles can -subsequently be used independently and they must both be freed with +This function returns a new curl handle, a duplicate, using all the options +previously set in the input curl \fIhandle\fP. Both handles can subsequently +be used independently and they must both be freed with \fIcurl_easy_cleanup(3)\fP. -All strings that the input handle has been told to point to (as opposed to -copy) with previous calls to \fIcurl_easy_setopt(3)\fP using char * inputs, -will be pointed to by the new handle as well. You must therefore make sure to -keep the data around until both handles have been cleaned up. +Any options that the input handle has been told to point to (as opposed to +copy) with previous calls to \fIcurl_easy_setopt(3)\fP, are pointed to by the +new handle as well. You must therefore make sure to keep the data around until +both handles have been cleaned up. -The new handle will \fBnot\fP inherit any state information, no connections, -no SSL sessions and no cookies. It also will not inherit any share object -states or options (it will be made as if \fICURLOPT_SHARE(3)\fP was set to -NULL). +The new handle does \fBnot\fP inherit any state information, no connections, +no SSL sessions and no cookies. It also does not inherit any share object +states or options (created as if \fICURLOPT_SHARE(3)\fP was set to NULL). In multi-threaded programs, this function must be called in a synchronous way, the input handle may not be in use when cloned. diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index e684a859e6..2553f16dec 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -32,12 +32,12 @@ curl_easy_getinfo - extract information from a curl handle CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... ); .fi .SH DESCRIPTION -Request internal information from the curl session with this function. The -third argument \fBMUST\fP be pointing to the specific type of the used option -which is documented in each man page of the option. The data pointed-to will -be filled in accordingly and can be relied upon only if the function returns -CURLE_OK. Use this function AFTER a performed transfer if you want to get -transfer related data. +Get the \fIinfo\fP kept in the \fIcurl\fP handle. The third argument +\fBMUST\fP be pointing to the specific type of the used option which is +documented in each man page of the \fIinfo\fP option. The data is stored +accordingly and can be relied upon only if this function returns CURLE_OK. Use +this function after a performed transfer if you want to get transfer related +data. You should not free the memory returned by this function unless it is explicitly mentioned below. @@ -233,10 +233,10 @@ See \fICURLINFO_CONDITION_UNMET(3)\fP RTSP session ID. See \fICURLINFO_RTSP_SESSION_ID(3)\fP .IP CURLINFO_RTSP_CLIENT_CSEQ -RTSP CSeq that will next be used. +The RTSP client CSeq that is expected next. See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP .IP CURLINFO_RTSP_SERVER_CSEQ -RTSP CSeq that will next be expected. +The RTSP server CSeq that is expected next. See \fICURLINFO_RTSP_SERVER_CSEQ(3)\fP .IP CURLINFO_RTSP_CSEQ_RECV RTSP CSeq last received. @@ -320,6 +320,6 @@ transaction was started. So, this is zero if no redirection took place. Added in 7.4.1 .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an -appropriate error code will be returned. +appropriate error code is returned. .SH "SEE ALSO" .BR curl_easy_setopt "(3)" diff --git a/docs/libcurl/curl_easy_header.3 b/docs/libcurl/curl_easy_header.3 index 145564861a..55b9513ce9 100644 --- a/docs/libcurl/curl_easy_header.3 +++ b/docs/libcurl/curl_easy_header.3 @@ -60,23 +60,23 @@ amount of requests used. libcurl stores and provides the actually used "correct" headers. If for example two headers with the same name arrive and the latter overrides the -former, then only the latter will be provided. If the first header survives -the second, then only the first one will be provided. An application using -this API does not have to bother about multiple headers used wrongly. +former, then only the latter is provided. If the first header survives the +second, then only the first one is provided. An application using this API +does not have to bother about multiple headers used wrongly. The memory for the returned struct is associated with the easy handle and -subsequent calls to \fIcurl_easy_header(3)\fP will clobber the struct used in -the previous calls for the same easy handle. Applications need to copy the -data if it wants to keep it around. The memory used for the struct gets freed -with calling \fIcurl_easy_cleanup(3)\fP of the easy handle. +subsequent calls to \fIcurl_easy_header(3)\fP clobbers the struct used in the +previous calls for the same easy handle. Applications need to copy the data if +it wants to keep it around. The memory used for the struct gets freed with +calling \fIcurl_easy_cleanup(3)\fP of the easy handle. The first line in an HTTP response is called the status line. It is not considered a header by this function. Headers are the "name: value" lines following the status. This function can be used before (all) headers have been received and is fine -to call from within libcurl callbacks. It will always return the state of the -headers at the time it is called. +to call from within libcurl callbacks. It returns the state of the headers at +the time it is called. .SH "The header struct" .nf struct curl_header { @@ -89,8 +89,8 @@ struct curl_header { }; .fi -The data \fBname\fP field points to, will be the same as the requested name -but it might have a different case. +The data \fBname\fP field points to, is the same as the requested name, but +might have a different case. The data \fBvalue\fP field points to, comes exactly as delivered over the network but with leading and trailing whitespace and newlines stripped diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index 457ebc719d..dc4487fe07 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -31,20 +31,30 @@ curl_easy_init - Start a libcurl easy session CURL *curl_easy_init(); .fi .SH DESCRIPTION -This function must be the first function to call, and it returns a CURL easy -handle that you must use as input to other functions in the easy -interface. This call \fBMUST\fP have a corresponding call to -\fIcurl_easy_cleanup(3)\fP when the operation is complete. +This function allocates and returns a CURL easy handle. Such a handle is used +as input to other functions in the easy interface. This call must have a +corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is +complete. -If you did not already call \fIcurl_global_init(3)\fP, \fIcurl_easy_init(3)\fP -does it automatically. This may be lethal in multi-threaded cases, since -\fIcurl_global_init(3)\fP is not thread-safe, and it may result in resource -problems because there is no corresponding cleanup. +The easy handle is used to hold and control a single network transfer. It is +encouraged to reuse easy handles for repeated transfers. + +An alternative way to get a new easy handle is to duplicate an already +existing one with \fIcurl_easy_duphandle(3)\fP, which has the upside that it +gets all the options that were set in the source handle set in the new copy as +well. + +If you did not already call \fIcurl_global_init(3)\fP before calling this +function, \fIcurl_easy_init(3)\fP does it automatically. This may be lethal in +multi-threaded cases, if \fIcurl_global_init(3)\fP is not thread-safe in your +system, and it may then result in resource problems because there is no +corresponding cleanup. You are strongly advised to not allow this automatic behavior, by calling \fIcurl_global_init(3)\fP yourself properly. See the description in \fBlibcurl\fP(3) of global environment requirements for details of how to use this function. + .SH EXAMPLE .nf CURL *curl = curl_easy_init(); @@ -62,4 +72,5 @@ If this function returns NULL, something went wrong and you cannot use the other curl functions. .SH "SEE ALSO" .BR curl_easy_cleanup "(3), " curl_global_init "(3), " curl_easy_reset "(3), " -.BR curl_easy_perform "(3) " +.BR curl_easy_perform "(3), " curl_easy_duphandle "(3), " +.BR curl_multi_init "(3), " diff --git a/docs/libcurl/curl_easy_option_by_id.3 b/docs/libcurl/curl_easy_option_by_id.3 index 373e7866f1..65be339a8c 100644 --- a/docs/libcurl/curl_easy_option_by_id.3 +++ b/docs/libcurl/curl_easy_option_by_id.3 @@ -35,8 +35,8 @@ Given a \fICURLoption\fP \fBid\fP, this function returns a pointer to the \fIcurl_easyoption\fP struct, holding information about the \fIcurl_easy_setopt(3)\fP option using that id. The option id is the CURLOPT_ prefix ones provided in the standard curl/curl.h header file. This function -will return the non-aliases version for the cases where there is an alias -function as well. +returns the non-alias version of the cases where there is an alias function as +well. If libcurl has no option with the given id, this function returns NULL. .SH EXAMPLE diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.3 index 822b81c572..62f1dba107 100644 --- a/docs/libcurl/curl_easy_pause.3 +++ b/docs/libcurl/curl_easy_pause.3 @@ -38,8 +38,8 @@ A connection can be paused by using this function or by letting the read or the write callbacks return the proper magic return code (\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback that returns pause signals to the library that it could not take care of any -data at all, and that data will then be delivered again to the callback when -the transfer is unpaused. +data at all, and that data is then delivered again to the callback when the +transfer is unpaused. While it may feel tempting, take care and notice that you cannot call this function from another thread. To unpause, you may for example call it from the @@ -47,27 +47,27 @@ progress callback (\fICURLOPT_PROGRESSFUNCTION(3)\fP). When this function is called to unpause receiving, the write callback might get called before this function returns to deliver cached content. When -libcurl delivers such cached data to the write callback, it will be delivered -as fast as possible, which may overstep the boundary set in +libcurl delivers such cached data to the write callback, it is delivered as +fast as possible, which may overstep the boundary set in \fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP etc. The \fBhandle\fP argument identifies the transfer you want to pause or unpause. A paused transfer is excluded from low speed cancels via the -\fICURLOPT_LOW_SPEED_LIMIT(3)\fP option and unpausing a transfer will reset -the time period required for the low speed limit to be met. +\fICURLOPT_LOW_SPEED_LIMIT(3)\fP option and unpausing a transfer resets the +time period required for the low speed limit to be met. The \fBbitmask\fP argument is a set of bits that sets the new state of the connection. The following bits can be used: .IP CURLPAUSE_RECV -Pause receiving data. There will be no data received on this connection until -this function is called again without this bit set. Thus, the write callback -(\fICURLOPT_WRITEFUNCTION(3)\fP) will not be called. +Pause receiving data. There is no data received on this connection until this +function is called again without this bit set. Thus, the write callback +(\fICURLOPT_WRITEFUNCTION(3)\fP) is not called. .IP CURLPAUSE_SEND -Pause sending data. There will be no data sent on this connection until this +Pause sending data. There is no data sent on this connection until this function is called again without this bit set. Thus, the read callback -(\fICURLOPT_READFUNCTION(3)\fP) will not be called. +(\fICURLOPT_READFUNCTION(3)\fP) is not called. .IP CURLPAUSE_ALL Convenience define that pauses both directions. .IP CURLPAUSE_CONT @@ -75,37 +75,37 @@ Convenience define that unpauses both directions. .SH LIMITATIONS The pausing of transfers does not work with protocols that work without network connectivity, like FILE://. Trying to pause such a transfer, in any -direction, will cause problems in the worst case or an error in the best case. +direction, might cause problems or error. .SH MULTIPLEXED When a connection is used multiplexed, like for HTTP/2, and one of the transfers over the connection is paused and the others continue flowing, libcurl might end up buffering contents for the paused transfer. It has to do this because it needs to drain the socket for the other transfers and the -already announced window size for the paused transfer will allow the server to +already announced window size for the paused transfer allows the server to continue sending data up to that window size amount. By default, libcurl announces a 32 megabyte window size, which thus can make libcurl end up buffering 32 megabyte of data for a paused stream. -When such a paused stream is unpaused again, any buffered data will be -delivered first. +When such a paused stream is unpaused again, any buffered data is delivered +first. .SH EXAMPLE .nf /* pause a transfer in both directions */ curl_easy_pause(curl, CURL_READFUNC_PAUSE | CURL_WRITEFUNC_PAUSE); .fi .SH "MEMORY USE" -When pausing a read by returning the magic return code from a write callback, -the read data is already in libcurl's internal buffers so it will have to keep -it in an allocated buffer until the receiving is again unpaused using this -function. +When pausing a download transfer by returning the magic return code from a +write callback, the read data is already in libcurl's internal buffers so it +has to keep it in an allocated buffer until the receiving is again unpaused +using this function. If the downloaded data is compressed and is asked to get uncompressed -automatically on download, libcurl will continue to uncompress the entire -downloaded chunk and it will cache the data uncompressed. This has the side- +automatically on download, libcurl continues to uncompress the entire +downloaded chunk and it caches the data uncompressed. This has the side- effect that if you download something that is compressed a lot, it can result in a large data amount needing to be allocated to save the data during the -pause. This said, you should probably consider not using paused receiving if -you allow libcurl to uncompress data automatically. +pause. consider not using paused receiving if you allow libcurl to uncompress +data automatically. .SH AVAILABILITY Added in 7.18.0. .SH RETURN VALUE diff --git a/docs/libcurl/curl_easy_perform.3 b/docs/libcurl/curl_easy_perform.3 index f6857903cc..923bfbdcc7 100644 --- a/docs/libcurl/curl_easy_perform.3 +++ b/docs/libcurl/curl_easy_perform.3 @@ -31,22 +31,22 @@ curl_easy_perform - perform a blocking file transfer CURLcode curl_easy_perform(CURL *easy_handle); .fi .SH DESCRIPTION +\fIcurl_easy_perform(3)\fP performs a network transfer in a blocking manner +and returns when done, or earlier if it fails. For non-blocking behavior, see +\fIcurl_multi_perform(3)\fP. + Invoke this function after \fIcurl_easy_init(3)\fP and all the \fIcurl_easy_setopt(3)\fP calls are made, and it performs the transfer as described in the options. It must be called with the same \fBeasy_handle\fP as input as the \fIcurl_easy_init(3)\fP call returned. -\fIcurl_easy_perform(3)\fP performs the entire request in a blocking manner -and returns when done, or earlier if it fails. For non-blocking behavior, see -\fIcurl_multi_perform(3)\fP. - You can do any amount of calls to \fIcurl_easy_perform(3)\fP while using the same \fBeasy_handle\fP. If you intend to transfer more than one file, you are -even encouraged to do so. libcurl will then attempt to re-use the same -connection for the following transfers, thus making the operations faster, -less CPU intense and using less network resources. Just note that you will -have to use \fIcurl_easy_setopt(3)\fP between the invokes to set options for -the following curl_easy_perform. +even encouraged to do so. libcurl attempts to reuse existing connections for +the following transfers, thus making the operations faster, less CPU intense +and using less network resources. You probably want to use +\fIcurl_easy_setopt(3)\fP between the invokes to set options for the following +curl_easy_perform call. You must never call this function simultaneously from two places using the same \fBeasy_handle\fP. Let the function return first before invoking it @@ -77,7 +77,7 @@ Always CURLE_OK (0) means everything was OK, non-zero means an error occurred as .I defines - see \fIlibcurl-errors(3)\fP. If the \fICURLOPT_ERRORBUFFER(3)\fP was -set with \fIcurl_easy_setopt(3)\fP there will be a readable error message in +set with \fIcurl_easy_setopt(3)\fP there is a readable error message stored in the error buffer when non-zero is returned. .SH "SEE ALSO" .BR curl_easy_init "(3), " curl_easy_setopt "(3), " diff --git a/docs/libcurl/curl_easy_recv.3 b/docs/libcurl/curl_easy_recv.3 index 2abb494897..2f6a148c3d 100644 --- a/docs/libcurl/curl_easy_recv.3 +++ b/docs/libcurl/curl_easy_recv.3 @@ -35,23 +35,22 @@ CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n); This function receives raw data from the established connection. You may use it together with \fIcurl_easy_send(3)\fP to implement custom protocols using libcurl. This functionality can be particularly useful if you use proxies -and/or SSL encryption: libcurl will take care of proxy negotiation and -connection setup. +and/or SSL encryption: libcurl takes care of proxy negotiation and connection +setup. -\fBbuffer\fP is a pointer to your buffer that will get the received -data. \fBbuflen\fP is the maximum amount of data you can get in that -buffer. The variable \fBn\fP points to will receive the number of received -bytes. +\fBbuffer\fP is a pointer to your buffer memory that gets populated by the +received data. \fBbuflen\fP is the maximum amount of data you can get in that +buffer. The variable \fBn\fP points to receives the number of received bytes. To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that \fIcurl_easy_recv(3)\fP does not work on connections that were created without this option. -The call will return \fBCURLE_AGAIN\fP if there is no data to read - the -socket is used in non-blocking mode internally. When \fBCURLE_AGAIN\fP is -returned, use your operating system facilities like \fIselect(2)\fP to wait -for data. The socket may be obtained using \fIcurl_easy_getinfo(3)\fP with +The call returns \fBCURLE_AGAIN\fP if there is no data to read - the socket is +used in non-blocking mode internally. When \fBCURLE_AGAIN\fP is returned, use +your operating system facilities like \fIselect(2)\fP to wait for data. The +socket may be obtained using \fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP. Wait on the socket only if \fIcurl_easy_recv(3)\fP returns \fBCURLE_AGAIN\fP. @@ -70,8 +69,7 @@ read was for internal SSL processing, and no other data is available. res = curl_easy_perform(curl); if(res == CURLE_OK) { - /* Extract the socket from the curl handle - - we will need it for waiting. */ + /* Extract the socket from the curl handle - we need it for waiting. */ res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); /* read data */ @@ -91,7 +89,7 @@ system facilities to wait until data can be read, and retry. Reading exactly 0 bytes indicates a closed connection. -If there's no socket available to use from the previous transfer, this function +If there is no socket available to use from the previous transfer, this function returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP. .SH "SEE ALSO" .BR curl_easy_setopt "(3), " curl_easy_perform "(3), " diff --git a/docs/libcurl/curl_easy_send.3 b/docs/libcurl/curl_easy_send.3 index 91e71908fa..467edc554f 100644 --- a/docs/libcurl/curl_easy_send.3 +++ b/docs/libcurl/curl_easy_send.3 @@ -36,22 +36,22 @@ CURLcode curl_easy_send(CURL *curl, const void *buffer, This function sends arbitrary data over the established connection. You may use it together with \fIcurl_easy_recv(3)\fP to implement custom protocols using libcurl. This functionality can be particularly useful if you use -proxies and/or SSL encryption: libcurl will take care of proxy negotiation and +proxies and/or SSL encryption: libcurl takes care of proxy negotiation and connection setup. -\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want sent. -The variable \fBn\fP points to will receive the number of sent bytes. +\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want +sent. The variable \fBn\fP points to receives the number of sent bytes. To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that -\fIcurl_easy_send(3)\fP will not work on connections that were created without +\fIcurl_easy_send(3)\fP does not work on connections that were created without this option. -The call will return \fBCURLE_AGAIN\fP if it's not possible to send data right -now - the socket is used in non-blocking mode internally. When -\fBCURLE_AGAIN\fP is returned, use your operating system facilities like -\fIselect(2)\fP to wait until the socket is writable. The socket may be -obtained using \fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP. +The call returns \fBCURLE_AGAIN\fP if it's not possible to send data right now +- the socket is used in non-blocking mode internally. When \fBCURLE_AGAIN\fP +is returned, use your operating system facilities like \fIselect(2)\fP to wait +until the socket is writable. The socket may be obtained using +\fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP. Furthermore if you wait on the socket and it tells you it's writable, \fIcurl_easy_send(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was @@ -64,8 +64,7 @@ sent was for internal SSL processing, and no other data could be sent. res = curl_easy_perform(curl); if(res == CURLE_OK) { - /* Extract the socket from the curl handle - - we will need it for waiting. */ + /* Extract the socket from the curl handle - we need it for waiting. */ res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); /* send data */ @@ -84,7 +83,7 @@ On failure, returns the appropriate error code. This function may return \fBCURLE_AGAIN\fP. In this case, use your operating system facilities to wait until the socket is writable, and retry. -If there's no socket available to use from the previous transfer, this function +If there is no socket available to use from the previous transfer, this function returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP. .SH "SEE ALSO" .BR curl_easy_setopt "(3), " curl_easy_perform "(3), " curl_easy_getinfo "(3), " diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 784495d6ec..949af6d35b 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -513,7 +513,7 @@ Maximum number of connections in the connection pool. See \fICURLOPT_MAXCONNECTS .IP CURLOPT_FRESH_CONNECT Use a new connection. \fICURLOPT_FRESH_CONNECT(3)\fP .IP CURLOPT_FORBID_REUSE -Prevent subsequent connections from re-using this. See \fICURLOPT_FORBID_REUSE(3)\fP +Prevent subsequent connections from reusing this. See \fICURLOPT_FORBID_REUSE(3)\fP .IP CURLOPT_MAXAGE_CONN Limit the age (idle time) of connections for reuse. See \fICURLOPT_MAXAGE_CONN(3)\fP .IP CURLOPT_MAXLIFETIME_CONN @@ -733,9 +733,8 @@ is invalid, like perhaps out of range. If you try to set an option that libcurl does not know about, perhaps because the library is too old to support it or the option was removed in a recent -version, this function will return \fICURLE_UNKNOWN_OPTION\fP. If support for -the option was disabled at compile-time, it will return -\fICURLE_NOT_BUILT_IN\fP. +version, this function returns \fICURLE_UNKNOWN_OPTION\fP. If support for the +option was disabled at compile-time, it returns \fICURLE_NOT_BUILT_IN\fP. .SH "SEE ALSO" .BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3), " .BR curl_easy_getinfo "(3), " curl_multi_setopt "(3), " diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3 index a80a1998f1..1e2a844e09 100644 --- a/docs/libcurl/curl_easy_strerror.3 +++ b/docs/libcurl/curl_easy_strerror.3 @@ -38,7 +38,7 @@ Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more specific error descriptions generated at runtime. .SH EXAMPLE .nf - /* Perform the request, res will get the return code */ + /* Perform the entire transfer */ res = curl_easy_perform(curl); /* Check for errors */ if(res != CURLE_OK) diff --git a/docs/libcurl/curl_easy_unescape.3 b/docs/libcurl/curl_easy_unescape.3 index c6033f56a6..9be1a95454 100644 --- a/docs/libcurl/curl_easy_unescape.3 +++ b/docs/libcurl/curl_easy_unescape.3 @@ -39,13 +39,13 @@ encoded (%XX where XX is a two-digit hexadecimal number) are converted to their binary versions. If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP -will use strlen() on \fBinput\fP to find out the size. +uses strlen() on \fBinput\fP to find out the size. -If \fBoutlength\fP is non-NULL, the function will write the length of the -returned string in the integer it points to. This allows proper handling even -for strings containing %00. Since this is a pointer to an \fIint\fP type, it -can only return a value up to \fIINT_MAX\fP so no longer string can be -returned in this parameter. +If \fBoutlength\fP is non-NULL, the function writes the length of the returned +string in the integer it points to. This allows proper handling even for +strings containing %00. Since this is a pointer to an \fIint\fP type, it can +only return a value up to \fIINT_MAX\fP so no longer string can be returned in +this parameter. Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was per-handle character conversion support for some very old operating systems diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index 1b29c8e70f..b749b5cf2f 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -33,13 +33,13 @@ char *curl_escape(const char *string, int length); .SH DESCRIPTION Obsolete function. Use \fIcurl_easy_escape(3)\fP instead! -This function will convert the given input \fBstring\fP to a URL encoded string +This function converts the given input \fBstring\fP to a URL encoded string and return that as a new allocated string. All input characters that are not -a-z, A-Z or 0-9 will be converted to their "URL escaped" version (\fB%NN\fP -where \fBNN\fP is a two-digit hexadecimal number). +a-z, A-Z or 0-9 are converted to their "URL escaped" version (\fB%NN\fP where +\fBNN\fP is a two-digit hexadecimal number). -If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP will use -strlen() on \fBstring\fP to find out the size. +If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP uses strlen() +on \fBstring\fP to find out the size. You must \fIcurl_free(3)\fP the returned string when you are done with it. .SH EXAMPLE @@ -51,8 +51,8 @@ if(output) { } .fi .SH AVAILABILITY -Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function will -be removed in a future release. +Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function might be +removed in a future release. .SH RETURN VALUE A pointer to a null-terminated string or NULL if it failed. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 280ffadf71..f176a13c84 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -44,9 +44,9 @@ allow repeated invokes to find the end of the list faster. After the \fIlastitem\fP pointer follow the real arguments. The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to -NULL in the first call to this function. All list-data will be allocated by -the function itself. You must call \fIcurl_formfree(3)\fP on the -\fIfirstitem\fP after the form post has been done to free the resources. +NULL in the first call to this function. All list-data is allocated by the +function itself. You must call \fIcurl_formfree(3)\fP on the \fIfirstitem\fP +after the form post has been done to free the resources. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. @@ -54,8 +54,8 @@ You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. First, there are some basics you need to understand about multipart form posts. Each part consists of at least a NAME and a CONTENTS part. If the part is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME. -Below, we will discuss what options you use to set these properties in the -parts you want to add to your post. +Below, we discuss what options you use to set these properties in the parts +you want to add to your post. The options listed first are for making normal parts. The options from \fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload @@ -66,34 +66,33 @@ followed by a string which provides the \fIname\fP of this part. libcurl copies the string so your application does not need to keep it around after this function call. If the name is not null-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to -contain zero-valued bytes. The copied data will be freed by -\fIcurl_formfree(3)\fP. +contain zero-valued bytes. The copied data is freed by \fIcurl_formfree(3)\fP. .IP CURLFORM_PTRNAME -followed by a string which provides the \fIname\fP of this part. libcurl -will use the pointer and refer to the data in your application, so you -must make sure it remains until curl no longer needs it. If the name -is not null-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP. -The \fIname\fP is not allowed to contain zero-valued bytes. +followed by a string which provides the \fIname\fP of this part. libcurl uses +the pointer and refer to the data in your application, so you must make sure +it remains until curl no longer needs it. If the name is not null-terminated, +you must set its length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not +allowed to contain zero-valued bytes. .IP CURLFORM_COPYCONTENTS -followed by a pointer to the contents of this part, the actual data -to send away. libcurl copies the provided data, so your application does not -need to keep it around after this function call. If the data is not null -terminated, or if you would like it to contain zero bytes, you must -set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied -data will be freed by \fIcurl_formfree(3)\fP. +followed by a pointer to the contents of this part, the actual data to send +away. libcurl copies the provided data, so your application does not need to +keep it around after this function call. If the data is not null terminated, +or if you would like it to contain zero bytes, you must set the length of the +name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied data is freed by +\fIcurl_formfree(3)\fP. .IP CURLFORM_PTRCONTENTS followed by a pointer to the contents of this part, the actual data to send -away. libcurl will use the pointer and refer to the data in your application, -so you must make sure it remains until curl no longer needs it. If the data -is not null-terminated, or if you would like it to contain zero bytes, you -must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. +away. libcurl uses the pointer and refer to the data in your application, so +you must make sure it remains until curl no longer needs it. If the data is +not null-terminated, or if you would like it to contain zero bytes, you must +set its length with \fBCURLFORM_CONTENTSLENGTH\fP. .IP CURLFORM_CONTENTLEN followed by a curl_off_t value giving the length of the contents. Note that for \fICURLFORM_STREAM\fP contents, this option is mandatory. -If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on -the contents to figure out the size. If you really want to send a zero byte -content then you must make sure strlen() on the data pointer returns zero. +If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents +to figure out the size. If you really want to send a zero byte content then +you must make sure strlen() on the data pointer returns zero. (Option added in 7.46.0) .IP CURLFORM_CONTENTSLENGTH @@ -102,9 +101,9 @@ content then you must make sure strlen() on the data pointer returns zero. followed by a long giving the length of the contents. Note that for \fICURLFORM_STREAM\fP contents, this option is mandatory. -If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on -the contents to figure out the size. If you really want to send a zero byte -content then you must make sure strlen() on the data pointer returns zero. +If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents +to figure out the size. If you really want to send a zero byte content then +you must make sure strlen() on the data pointer returns zero. .IP CURLFORM_FILECONTENT followed by a filename, causes that file to be read and its contents used as data in this part. This part does \fInot\fP automatically become a file diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index 83e768ed24..aa154a978f 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -44,8 +44,8 @@ the \fIcurl_formadd(3)\fP invoke(s). \fBform\fP is the pointer as returned from a previous call to \fIcurl_formadd(3)\fP and may be NULL. -Passing in a NULL pointer in \fIform\fP will make this function return -immediately with no action. +Passing in a NULL pointer in \fIform\fP makes this function return immediately +with no action. .SH EXAMPLE .nf /* Fill in a file upload field */ diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index d8687e0d0f..87e2d8de3a 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -33,19 +33,20 @@ int curl_formget(struct curl_httppost * form, void *userp, .SH DESCRIPTION curl_formget() is used to serialize data previously built/appended with \fIcurl_formadd(3)\fP. Accepts a void pointer as second argument named -\fIuserp\fP which will be passed as the first argument to the -curl_formget_callback function. +\fIuserp\fP which is passed as the first argument to the curl_formget_callback +function. .BI "typedef size_t (*curl_formget_callback)(void *" userp, " const char *" buf, .BI " size_t " len ");" -The curl_formget_callback will be executed for each part of the HTTP POST -chain. The character buffer passed to the callback must not be freed. The -callback should return the buffer length passed to it on success. +The curl_formget_callback is invoked for each part of the HTTP POST chain. The +character buffer passed to the callback must not be freed. The callback should +return the buffer length passed to it on success. -If the \fBCURLFORM_STREAM\fP option is used in the formpost, it will prevent +If the \fBCURLFORM_STREAM\fP option is used in the formpost, it prevents \fIcurl_formget(3)\fP from working until you have performed the actual HTTP -request as only then will libcurl get the actual read callback to use! +request. This, because first then does libcurl known which actual read +callback to use! .SH EXAMPLE .nf size_t print_httppost_callback(void *arg, const char *buf, size_t len) diff --git a/docs/libcurl/curl_free.3 b/docs/libcurl/curl_free.3 index 361749f822..389d505395 100644 --- a/docs/libcurl/curl_free.3 +++ b/docs/libcurl/curl_free.3 @@ -35,8 +35,8 @@ curl_free reclaims memory that has been obtained through a libcurl call. Use \fIcurl_free(3)\fP instead of free() to avoid anomalies that can result from differences in memory management between your application and libcurl. -Passing in a NULL pointer in \fIptr\fP will make this function return -immediately with no action. +Passing in a NULL pointer in \fIptr\fP makes this function return immediately +with no action. .SH EXAMPLE .nf char *width = curl_getenv("COLUMNS"); diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 43d46f95e0..d665f8801c 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -51,8 +51,8 @@ digits. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6. .TP .B time of the day items This string specifies the time on a given day. You must specify it with 6 -digits with two colons: HH:MM:SS. To not include the time in a date string, -will make the function assume 00:00:00. Example: 18:19:21. +digits with two colons: HH:MM:SS. If there is no time given in a provided date +string, 00:00:00 is assumed. Example: 18:19:21. .TP .B time zone items Specifies international time zone. There are a few acronyms supported, but in @@ -107,13 +107,13 @@ This function returns -1 when it fails to parse the date string. Otherwise it returns the number of seconds as described. On systems with a signed 32 bit time_t: if the year is larger than 2037 or -less than 1903, this function will return -1. +less than 1903, this function returns -1. On systems with an unsigned 32 bit time_t: if the year is larger than 2106 or -less than 1970, this function will return -1. +less than 1970, this function returns -1. On systems with 64 bit time_t: if the year is less than 1583, this function -will return -1. (The Gregorian calendar was first introduced 1582 so no "real" +returns -1. (The Gregorian calendar was first introduced 1582 so no "real" dates in this way of doing dates existed before then.) .SH "SEE ALSO" .BR curl_easy_escape "(3), " curl_easy_unescape "(3), " diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 index de50a807e7..2813bc90a9 100644 --- a/docs/libcurl/curl_getenv.3 +++ b/docs/libcurl/curl_getenv.3 @@ -51,8 +51,7 @@ A pointer to a null-terminated string or NULL if it failed to find the specified name. .SH NOTE Under unix operating systems, there is no point in returning an allocated -memory, although other systems will not work properly if this is not done. The -unix implementation thus has to suffer slightly from the drawbacks of other -systems. +memory, although other systems does not work properly if this is not done. The +unix implementation thus suffers slightly from the drawbacks of other systems. .SH "SEE ALSO" .BR getenv "(3C), " diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index 2ce0e753ae..c30ed3c859 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -87,18 +87,18 @@ Initialize the Win32 socket libraries. The implication here is that if this bit is not set, the initialization of winsock has to be done by the application or you risk getting undefined behaviors. This option exists for when the initialization is handled outside -of libcurl so there's no need for libcurl to do it again. +of libcurl so there is no need for libcurl to do it again. .IP CURL_GLOBAL_NOTHING Initialize nothing extra. This sets no bit. .IP CURL_GLOBAL_DEFAULT -A sensible default. It will init both SSL and Win32. Right now, this equals +A sensible default. It initializes both SSL and Win32. Right now, this equals the functionality of the \fBCURL_GLOBAL_ALL\fP mask. .IP CURL_GLOBAL_ACK_EINTR This bit has no point since 7.69.0 but its behavior is instead the default. -Before 7.69.0: when this flag is set, curl will acknowledge EINTR condition -when connecting or when waiting for data. Otherwise, curl waits until full -timeout elapses. (Added in 7.30.0) +Before 7.69.0: when this flag is set, curl acknowledges EINTR condition when +connecting or when waiting for data. Otherwise, curl waits until full timeout +elapses. (Added in 7.30.0) .SH EXAMPLE .nf curl_global_init(CURL_GLOBAL_DEFAULT); diff --git a/docs/libcurl/curl_global_sslset.3 b/docs/libcurl/curl_global_sslset.3 index c856906650..b0ff930df2 100644 --- a/docs/libcurl/curl_global_sslset.3 +++ b/docs/libcurl/curl_global_sslset.3 @@ -62,15 +62,15 @@ must be called \fBbefore\fP \fIcurl_global_init(3)\fP. The backend can be identified by the \fIid\fP (e.g. \fBCURLSSLBACKEND_OPENSSL\fP). The backend can also be specified via the \fIname\fP parameter for a case insensitive match (passing -1 as \fIid\fP). If -both \fIid\fP and \fIname\fP are specified, the \fIname\fP will be ignored. +both \fIid\fP and \fIname\fP are specified, the \fIname\fP is ignored. -If neither \fIid\fP nor \fPname\fP are specified, the function will fail with +If neither \fIid\fP nor \fPname\fP are specified, the function fails with \fBCURLSSLSET_UNKNOWN_BACKEND\fP and set the \fIavail\fP pointer to the NULL-terminated list of available backends. The available backends are those that this particular build of libcurl supports. -Since libcurl 7.60.0, the \fIavail\fP pointer will always be set to the list -of alternatives if non-NULL. +Since libcurl 7.60.0, the \fIavail\fP pointer is always set to the list of +alternatives if non-NULL. Upon success, the function returns \fBCURLSSLSET_OK\fP. @@ -80,7 +80,7 @@ NULL-terminated list of available SSL backends. In this case, you may call the function again to try to select a different backend. The SSL backend can be set only once. If it has already been set, a subsequent -attempt to change it will result in a \fBCURLSSLSET_TOO_LATE\fP. +attempt to change it results in a \fBCURLSSLSET_TOO_LATE\fP getting returned. This function is thread-safe since libcurl 7.84.0 if \fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set diff --git a/docs/libcurl/curl_global_trace.3 b/docs/libcurl/curl_global_trace.3 index b6e36abf99..c1cc1a3442 100644 --- a/docs/libcurl/curl_global_trace.3 +++ b/docs/libcurl/curl_global_trace.3 @@ -61,11 +61,11 @@ are case-insensitive and unknown names are ignored. The special name "all" applies to all components. Names may be prefixed with '+' or '-' to enable or disable detailed logging for a component. -The list of component names is not part of curl's public API. Names may -be added or disappear in future versions of libcurl. Since unknown names -are silently ignored, outdated log configurations will not error when -upgrading libcurl. Given that, some names can be expected to be fairly -stable and are listed below for easy reference. +The list of component names is not part of curl's public API. Names may be +added or disappear in future versions of libcurl. Since unknown names are +silently ignored, outdated log configurations does not cause errors when +upgrading libcurl. Given that, some names can be expected to be fairly stable +and are listed below for easy reference. Note that log configuration applies only to transfers where debug logging is enabled. See \fICURLOPT_VERBOSE(3)\fP or \fICURLOPT_DEBUGFUNCTION(3)\fP @@ -85,9 +85,9 @@ Involved when transfers are tunneled through a HTTP proxy. "h1-proxy" or "h2-proxy" are also involved, depending on the HTTP version negotiated with the proxy. -In order to find out all components involved in -a transfer, run it with "all" configured. You will then see all names -involved in your libcurl version in the trace. +In order to find out all components involved in a transfer, run it with "all" +configured. You can then see all names involved in your libcurl version in the +trace. .SH EXAMPLE .nf diff --git a/docs/libcurl/curl_mime_data_cb.3 b/docs/libcurl/curl_mime_data_cb.3 index 260eafcdc0..c89c68442a 100644 --- a/docs/libcurl/curl_mime_data_cb.3 +++ b/docs/libcurl/curl_mime_data_cb.3 @@ -49,13 +49,13 @@ from a data read callback function. as shown by the above prototype. It may not be set to NULL. \fIseekfunc\fP is a pointer to a seek callback function, with a signature as -shown by the above prototype. This function will be used upon resending data -(i.e.: after a redirect); this pointer may be set to NULL, in which case a -resend is not possible. +shown by the above prototype. This function is used when resending data (i.e.: +after a redirect); this pointer may be set to NULL, in which case a resend +might not be not possible. \fIfreefunc\fP is a pointer to a user resource freeing callback function, with a signature as shown by the above prototype. If no resource is to be freed, it -may safely be set to NULL. This function will be called upon mime structure +may safely be set to NULL. This function is called upon mime structure freeing. \fIarg\fP is a user defined argument to callback functions. @@ -67,13 +67,13 @@ should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes by your function. Your read function must then return the actual number of bytes that it stored -in that memory area. Returning 0 will signal end-of-file to the library and -cause it to stop the current transfer. +in that memory area. Returning 0 signals end-of-file to the library and cause +it to stop the current transfer. -If you stop the current transfer by returning 0 "pre-maturely" (i.e. before the -server expected it, like when you have said you will upload N bytes and you -upload less than N bytes), you may experience that the server "hangs" waiting -for the rest of the data that will not come. +If you stop the current transfer by returning 0 "pre-maturely" (i.e. before +the server expected it, like when you have said you intend to upload N bytes +and yet you upload less than N bytes), you may experience that the server +"hangs" waiting for the rest of the data that does not come. The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error @@ -95,14 +95,14 @@ done by instead reading from the input or similar. Care must be taken if the part is bound to a curl easy handle that is later duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in -the pointed item to be shared between the original and the copied handle. -In particular, special attention should be given to the \fIfreefunc\fP -procedure code since it will be called twice with the same argument. +the pointed item to be shared between the original and the copied handle. In +particular, special attention should be given to the \fIfreefunc\fP procedure +code since it then gets called twice with the same argument. .SH EXAMPLE -Sending a huge data string will cause the same amount of memory to be -allocated: to avoid overhead resources consumption, one might want to use a -callback source to avoid data duplication. In this case, original data -must be retained until after the transfer terminates. +Sending a huge data string causes the same amount of memory to be allocated: +to avoid overhead resources consumption, one might want to use a callback +source to avoid data duplication. In this case, original data must be retained +until after the transfer terminates. .nf char hugedata[512000]; diff --git a/docs/libcurl/curl_mime_filedata.3 b/docs/libcurl/curl_mime_filedata.3 index 0ef8725029..0559329925 100644 --- a/docs/libcurl/curl_mime_filedata.3 +++ b/docs/libcurl/curl_mime_filedata.3 @@ -51,8 +51,8 @@ manner to allow huge files to get transferred without using much memory. It therefore requires that the file is kept intact during the entire request. If the file size cannot be determined before actually reading it (such as for -a device or named pipe), the whole mime structure containing the part -will be transferred as chunks by HTTP and rejected by IMAP. +a character device or named pipe), the whole mime structure containing the +part is transferred using chunks by HTTP but is rejected by IMAP. Setting a part's contents multiple times is valid: only the value set by the last call is retained. diff --git a/docs/libcurl/curl_mime_free.3 b/docs/libcurl/curl_mime_free.3 index b3be926798..039e9c9b2b 100644 --- a/docs/libcurl/curl_mime_free.3 +++ b/docs/libcurl/curl_mime_free.3 @@ -43,8 +43,8 @@ are by the top structure freeing. \fBmime\fP is the handle as returned from a previous call to \fIcurl_mime_init(3)\fP and may be NULL. -Passing in a NULL pointer in \fImime\fP will make this function return -immediately with no action. +Passing in a NULL pointer in \fImime\fP makes this function return immediately +with no action. .SH EXAMPLE .nf /* Build the mime message. */ diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index 720632ed8c..c7e0a35ddb 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -136,7 +136,7 @@ overrides a space if both are used. .SH "Field width" An optional decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the -field width, it will be padded with spaces on the left (or right, if the +field width, it gets padded with spaces on the left (or right, if the left-adjustment flag has been given). Instead of a decimal digit string one may write "*" or "*m$" (for some decimal integer m) to specify that the field width is given in the next argument, or in the \fIm-th\fP argument, @@ -241,7 +241,7 @@ A '%' is written. No argument is converted. curl_mprintf("Pi is almost %f\\n", 25/8); .fi .SH AVAILABILITY -These functions will be removed from the public libcurl API in the future. Do +These functions might be removed from the public libcurl API in the future. Do not use them in new programs or projects. .SH RETURN VALUE The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 index 685cf536de..fd778ad864 100644 --- a/docs/libcurl/curl_multi_add_handle.3 +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -31,32 +31,30 @@ curl_multi_add_handle - add an easy handle to a multi session CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); .fi .SH DESCRIPTION -Adds a standard easy handle to the multi stack. This function call will make -this \fImulti_handle\fP control the specified \fIeasy_handle\fP. +Adds the \fIeasy handle\fP to the \fImulti_handle\fP. While an easy handle is added to a multi stack, you cannot and you must not use \fIcurl_easy_perform(3)\fP on that handle. After having removed the easy handle from the multi stack again, it is perfectly fine to use it with the easy interface again. -If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) or -global DNS cache (\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP), it will be made to -use the DNS cache that is shared between all easy handles within the multi -handle when \fIcurl_multi_add_handle(3)\fP is called. +If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) cache, +it is made to use a DNS cache that is shared between all easy handles within +the multi handle when \fIcurl_multi_add_handle(3)\fP is called. -When an easy interface is added to a multi handle, it will use a shared +When an easy interface is added to a multi handle, it is set to use a shared connection cache owned by the multi handle. Removing and adding new easy -handles will not affect the pool of connections or the ability to do -connection re-use. +handles does not affect the pool of connections or the ability to do +connection reuse. -If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (and you -really should if you are working event-based with -\fIcurl_multi_socket_action(3)\fP and friends), that callback will be called -from within this function to ask for an updated timer so that your main event -loop will get the activity on this handle to get started. +If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (as you +should if you are working event-based with \fIcurl_multi_socket_action(3)\fP +and friends), that callback is called from within this function to ask for an +updated timer so that your main event loop gets the activity on this handle to +get started. -The easy handle will remain added to the multi handle until you remove it -again with \fIcurl_multi_remove_handle(3)\fP - even when a transfer with that +The easy handle remains added to the multi handle until you remove it again +with \fIcurl_multi_remove_handle(3)\fP - even when a transfer with that specific easy handle is completed. You should remove the easy handle from the multi stack before you terminate diff --git a/docs/libcurl/curl_multi_assign.3 b/docs/libcurl/curl_multi_assign.3 index 0544dc5e41..352fb50376 100644 --- a/docs/libcurl/curl_multi_assign.3 +++ b/docs/libcurl/curl_multi_assign.3 @@ -36,20 +36,20 @@ This function creates an association in the multi handle between the given socket and a private pointer of the application. This is designed for \fIcurl_multi_socket_action(3)\fP uses. -When set, the \fIsockptr\fP pointer will be passed to all future socket -callbacks for the specific \fIsockfd\fP socket. +When set, the \fIsockptr\fP pointer is passed to all future socket callbacks +for the specific \fIsockfd\fP socket. -If the given \fIsockfd\fP is not already in use by libcurl, this function will -return an error. +If the given \fIsockfd\fP is not already in use by libcurl, this function +returns an error. libcurl only keeps one single pointer associated with a socket, so calling -this function several times for the same socket will make the last set pointer -get used. +this function several times for the same socket makes the last set pointer get +used. The idea here being that this association (socket to private pointer) is -something that just about every application that uses this API will need and -then libcurl can just as well do it since it already has an internal hash -table lookup for this. +something that just about every application that uses this API needs and then +libcurl can just as well do it since it already has the necessary +functionality. It is acceptable to call this function from your multi callback functions. .SH EXAMPLE diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3 index 91e205b06c..81098f4ef8 100644 --- a/docs/libcurl/curl_multi_cleanup.3 +++ b/docs/libcurl/curl_multi_cleanup.3 @@ -44,7 +44,7 @@ handle is no longer connected to the multi handle 3 - \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are removed -Passing in a NULL pointer in \fImulti_handle\fP will make this function return +Passing in a NULL pointer in \fImulti_handle\fP makes this function return CURLM_BAD_HANDLE immediately with no other action. .SH EXAMPLE .nf diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index c0eb575e57..d6b8a311fe 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -54,13 +54,13 @@ If the \fIexc_fd_set\fP argument is not a null pointer, it points to an object of type \fBfd_set\fP that on return specifies the file descriptors to be checked for error conditions pending. -If no file descriptors are set by libcurl, \fImax_fd\fP will contain -1 when -this function returns. Otherwise it will contain the highest descriptor number -libcurl set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl -currently does something that is not possible for your application to monitor -with a socket and unfortunately you can then not know exactly when the current -action is completed using select(). You then need to wait a while before you -proceed and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless +If no file descriptors are set by libcurl, \fImax_fd\fP contain -1 when this +function returns. Otherwise it contains the highest descriptor number libcurl +set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl currently +does something that is not possible for your application to monitor with a +socket and unfortunately you can then not know exactly when the current action +is completed using select(). You then need to wait a while before you proceed +and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless \fIcurl_multi_timeout(3)\fP gives you a lower number, we suggest 100 milliseconds or so, but you may want to test it out in your own particular conditions to find a suitable value. @@ -73,11 +73,11 @@ want. If one of the sockets used by libcurl happens to be larger than what can be set in an \fBfd_set\fP, which on POSIX systems means that the file descriptor -is larger than \fBFD_SETSIZE\fP, then libcurl will try to not set it. Setting -a too large file descriptor in an \fBfd_set\fP implies an out of bounds write -which can cause crashes, or worse. The effect of NOT storing it will possibly -save you from the crash, but will make your program NOT wait for sockets it -should wait for... +is larger than \fBFD_SETSIZE\fP, then libcurl tries to not set it. Setting a +too large file descriptor in an \fBfd_set\fP implies an out of bounds write +which can cause crashes, or worse. The effect of NOT storing it might possibly +save you from the crash, but makes your program NOT wait for sockets it should +wait for... .SH EXAMPLE .nf /* get file descriptors from the transfers */ diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index dbdae138e3..d3212f5ab5 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -36,17 +36,17 @@ transfers. Messages may include information such as an error code from the transfer or just the fact that a transfer is completed. More details on these should be written down as well. -Repeated calls to this function will return a new struct each time, until a -NULL is returned as a signal that there is no more to get at this point. The -integer pointed to with \fImsgs_in_queue\fP will contain the number of -remaining messages after this function was called. +Repeated calls to this function returns a new struct each time, until a NULL +is returned as a signal that there is no more to get at this point. The +integer pointed to with \fImsgs_in_queue\fP contains the number of remaining +messages after this function was called. When you fetch a message using this function, it is removed from the internal -queue so calling this function again will not return the same message -again. It will instead return new messages at each new invoke until the queue -is emptied. +queue so calling this function again does not return the same message +again. It instead returns new messages at each new invoke until the queue is +emptied. -\fBWARNING:\fP The data the returned pointer points to will not survive +\fBWARNING:\fP The data the returned pointer points to does not survive calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or \fIcurl_easy_cleanup(3)\fP. diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index adf735f4e9..97471a4caf 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -35,13 +35,13 @@ This function performs transfers on all the added handles that need attention in a non-blocking fashion. The easy handles have previously been added to the multi handle with \fIcurl_multi_add_handle(3)\fP. -When an application has found out there's data available for the multi_handle +When an application has found out there is data available for the multi_handle or a timeout has elapsed, the application should call this function to read/write whatever there is to read or write right now etc. \fIcurl_multi_perform(3)\fP returns as soon as the reads/writes are done. This function does not require that there actually is any data available for -reading or that data can be written, it can be called just in case. It will -store the number of handles that still transfer data in the second argument's +reading or that data can be written, it can be called just in case. It stores +the number of handles that still transfer data in the second argument's integer-pointer. If the amount of \fIrunning_handles\fP is changed from the previous call (or @@ -88,7 +88,7 @@ individual transfers may have occurred even when this function returns \fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure out how individual transfers did. .SH "TYPICAL USAGE" -Most applications will use \fIcurl_multi_poll(3)\fP to make libcurl wait for +Most applications use \fIcurl_multi_poll(3)\fP to make libcurl wait for activity on any of the ongoing transfers. As soon as one or more file descriptor has activity or the function times out, the application calls \fIcurl_multi_perform(3)\fP. diff --git a/docs/libcurl/curl_multi_poll.3 b/docs/libcurl/curl_multi_poll.3 index 618cdef8a0..f515487ae4 100644 --- a/docs/libcurl/curl_multi_poll.3 +++ b/docs/libcurl/curl_multi_poll.3 @@ -36,20 +36,20 @@ CURLMcode curl_multi_poll(CURLM *multi_handle, .ad .SH DESCRIPTION \fIcurl_multi_poll(3)\fP polls all file descriptors used by the curl easy -handles contained in the given multi handle set. It will block until activity -is detected on at least one of the handles or \fItimeout_ms\fP has passed. +handles contained in the given multi handle set. It blocks until activity is +detected on at least one of the handles or \fItimeout_ms\fP has passed. Alternatively, if the multi handle has a pending internal timeout that has a -shorter expiry time than \fItimeout_ms\fP, that shorter time will be used -instead to make sure timeout accuracy is reasonably kept. +shorter expiry time than \fItimeout_ms\fP, that shorter time is used instead +to make sure timeout accuracy is reasonably kept. The calling application may pass additional curl_waitfd structures which are similar to \fIpoll(2)\fP's \fIpollfd\fP structure to be waited on in the same call. -On completion, if \fInumfds\fP is non-NULL, it will be populated with the -total number of file descriptors on which interesting events occurred. This -number can include both libcurl internal descriptors as well as descriptors -provided in \fIextra_fds\fP. +On completion, if \fInumfds\fP is non-NULL, it gets populated with the total +number of file descriptors on which interesting events occurred. This number +can include both libcurl internal descriptors as well as descriptors provided +in \fIextra_fds\fP. The \fIcurl_multi_wakeup(3)\fP function can be used from another thread to wake up this function and return faster. This is one of the details @@ -57,10 +57,9 @@ that makes this function different than \fIcurl_multi_wait(3)\fP which cannot be woken up this way. If no extra file descriptors are provided and libcurl has no file descriptor -to offer to wait for, this function will instead wait during \fItimeout_ms\fP -milliseconds (or shorter if an internal timer indicates so). This is the -other detail that makes this function different than -\fIcurl_multi_wait(3)\fP. +to offer to wait for, this function instead waits during \fItimeout_ms\fP +milliseconds (or shorter if an internal timer indicates so). This is the other +detail that makes this function different than \fIcurl_multi_wait(3)\fP. This function is encouraged to be used instead of select(3) when using the multi interface to allow applications to easier circumvent the common problem diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3 index 7d135e6d24..c9205479af 100644 --- a/docs/libcurl/curl_multi_remove_handle.3 +++ b/docs/libcurl/curl_multi_remove_handle.3 @@ -31,15 +31,15 @@ curl_multi_remove_handle - remove an easy handle from a multi session CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle); .fi .SH DESCRIPTION -Removes a given \fIeasy_handle\fP from the \fImulti_handle\fP. This will make -the specified easy handle be removed from this multi handle's control. +Removes a given \fIeasy_handle\fP from the \fImulti_handle\fP. This makes the +specified easy handle be removed from this multi handle's control. When the easy handle has been removed from a multi stack, it is again perfectly legal to invoke \fIcurl_easy_perform(3)\fP on this easy handle. -Removing an easy handle while being used is perfectly legal and will -effectively halt the transfer in progress involving that easy handle. All -other easy handles and transfers will remain unaffected. +Removing an easy handle while being in use is perfectly legal and effectively +halts the transfer in progress involving that easy handle. All other easy +handles and transfers remain unaffected. It is fine to remove a handle at any time during a transfer, just not from within any libcurl callback function. diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 7cc6b2999d..3cfabe1726 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -37,9 +37,9 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle, These functions are deprecated. Do not use. See \fIcurl_multi_socket_action(3)\fP instead. -At return, the integer \fBrunning_handles\fP points to will contain the number -of still running easy handles within the multi handle. When this number -reaches zero, all transfers are complete/done. Note that when you call +At return, the integer \fBrunning_handles\fP points to contains the number of +still running easy handles within the multi handle. When this number reaches +zero, all transfers are complete/done. Note that when you call \fIcurl_multi_socket_action(3)\fP on a specific socket and the counter decreases by one, it DOES NOT necessarily mean that this exact socket/transfer is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out @@ -53,7 +53,7 @@ update the status with changes since the previous time the callback was called. Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option -with \fIcurl_multi_setopt(3)\fP. Your application will then get called with +with \fIcurl_multi_setopt(3)\fP. Your application then gets called with information on how long to wait for socket actions at most before doing the timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 index 5391f49cb0..54164c57f9 100644 --- a/docs/libcurl/curl_multi_socket_action.3 +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -41,7 +41,7 @@ can be passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and -libcurl will test the descriptor internally. It is also permissible to pass +libcurl tests the descriptor internally. It is also permissible to pass CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the whole process or when a timeout occurs. @@ -60,7 +60,7 @@ update the status with changes since the previous time the callback was called. Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option -with \fIcurl_multi_setopt(3)\fP. Your application will then get called with +with \fIcurl_multi_setopt(3)\fP. Your application then gets called with information on how long to wait for socket actions at most before doing the timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 index a9c364b1ba..3931409d9b 100644 --- a/docs/libcurl/curl_multi_timeout.3 +++ b/docs/libcurl/curl_multi_timeout.3 @@ -43,7 +43,7 @@ the simpler and older multi interface approach. The timeout value returned in the long \fBtimeout\fP points to, is in number of milliseconds at this moment. If 0, it means you should proceed immediately -without waiting for anything. If it returns -1, there's no timeout at all set. +without waiting for anything. If it returns -1, there is no timeout at all set. An application that uses the multi_socket API SHOULD NOT use this function, but SHOULD instead use the \fICURLMOPT_TIMERFUNCTION(3)\fP option for proper diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 index b145022386..7490cfd3b4 100644 --- a/docs/libcurl/curl_multi_wait.3 +++ b/docs/libcurl/curl_multi_wait.3 @@ -36,24 +36,24 @@ CURLMcode curl_multi_wait(CURLM *multi_handle, .ad .SH DESCRIPTION \fIcurl_multi_wait(3)\fP polls all file descriptors used by the curl easy -handles contained in the given multi handle set. It will block until activity -is detected on at least one of the handles or \fItimeout_ms\fP has passed. +handles contained in the given multi handle set. It blocks until activity is +detected on at least one of the handles or \fItimeout_ms\fP has passed. Alternatively, if the multi handle has a pending internal timeout that has a -shorter expiry time than \fItimeout_ms\fP, that shorter time will be used +shorter expiry time than \fItimeout_ms\fP, that shorter time is be used instead to make sure timeout accuracy is reasonably kept. The calling application may pass additional \fIcurl_waitfd\fP structures which are similar to \fIpoll(2)\fP's \fIpollfd\fP structure to be waited on in the same call. -On completion, if \fInumfds\fP is non-NULL, it will be populated with the -total number of file descriptors on which interesting events occurred. This -number can include both libcurl internal descriptors as well as descriptors -provided in \fIextra_fds\fP. +On completion, if \fInumfds\fP is non-NULL, it gets populated with the total +number of file descriptors on which interesting events occurred. This number +can include both libcurl internal descriptors as well as descriptors provided +in \fIextra_fds\fP. If no extra file descriptors are provided and libcurl has no file descriptor -to offer to wait for, this function will return immediately. (Try -\fIcurl_multi_poll(3)\fP instead if you rather avoid this behavior.) +to offer to wait for, this function returns immediately. (Consider using +\fIcurl_multi_poll(3)\fP to avoid this behavior.) This function is encouraged to be used instead of select(3) when using the multi interface to allow applications to easier circumvent the common problem diff --git a/docs/libcurl/curl_multi_wakeup.3 b/docs/libcurl/curl_multi_wakeup.3 index c22f22f95b..c8dc5b7c60 100644 --- a/docs/libcurl/curl_multi_wakeup.3 +++ b/docs/libcurl/curl_multi_wakeup.3 @@ -31,17 +31,16 @@ curl_multi_wakeup - wakes up a sleeping curl_multi_poll call CURLMcode curl_multi_wakeup(CURLM *multi_handle); .fi .SH DESCRIPTION -This function can be called from any thread and it wakes up a -sleeping \fIcurl_multi_poll(3)\fP call that is currently (or will be) -waiting for activity or a timeout. +This function can be called from any thread and it wakes up a sleeping +\fIcurl_multi_poll(3)\fP call that is currently (or is about to be) waiting +for activity or a timeout. -If the function is called when there is no \fIcurl_multi_poll(3)\fP call, -it will cause the next call to return immediately. +If the function is called when there is no \fIcurl_multi_poll(3)\fP call, it +causes the next call to return immediately. -Calling this function only guarantees to wake up the current (or the next -if there is no current) \fIcurl_multi_poll(3)\fP call, which means it is -possible that multiple calls to this function will wake up the same waiting -operation. +Calling this function only guarantees to wake up the current (or the next if +there is no current) \fIcurl_multi_poll(3)\fP call, which means it is possible +that multiple calls to this function wake up the same waiting operation. This function has no effect on \fIcurl_multi_wait(3)\fP calls. .SH EXAMPLE diff --git a/docs/libcurl/curl_pushheader_byname.3 b/docs/libcurl/curl_pushheader_byname.3 index 683a48d825..2c4c56e542 100644 --- a/docs/libcurl/curl_pushheader_byname.3 +++ b/docs/libcurl/curl_pushheader_byname.3 @@ -38,8 +38,8 @@ elsewhere and it has no function then. It returns the value for the given header field name (or NULL) for the incoming server push request. This is a shortcut so that the application does not have to loop through all headers to find the one it is interested in. The -data this function points to will be freed when this callback returns. If more -than one header field use the same name, this returns only the first one. +data this function points to is freed when this callback returns. If more than +one header field use the same name, this returns only the first one. .SH EXAMPLE .nf diff --git a/docs/libcurl/curl_pushheader_bynum.3 b/docs/libcurl/curl_pushheader_bynum.3 index a51b8d73e2..2eecb24292 100644 --- a/docs/libcurl/curl_pushheader_bynum.3 +++ b/docs/libcurl/curl_pushheader_bynum.3 @@ -36,9 +36,9 @@ This is a function that is only functional within a elsewhere and it has no function then. It returns the value for the header field at the given index \fBnum\fP, for -the incoming server push request or NULL. The data pointed will be freed when -this callback returns. The returned pointer points to a "name:value" string -that will be freed when this callback returns. +the incoming server push request or NULL. The data pointed to is freed by +libcurl when this callback returns. The returned pointer points to a +"name:value" string that gets freed when this callback returns. .SH EXAMPLE .nf diff --git a/docs/libcurl/curl_share_cleanup.3 b/docs/libcurl/curl_share_cleanup.3 index eaa5da1175..48fd4293b2 100644 --- a/docs/libcurl/curl_share_cleanup.3 +++ b/docs/libcurl/curl_share_cleanup.3 @@ -34,7 +34,7 @@ CURLSHcode curl_share_cleanup(CURLSH *share_handle); This function deletes a shared object. The share handle cannot be used anymore when this function has been called. -Passing in a NULL pointer in \fIshare_handle\fP will make this function return +Passing in a NULL pointer in \fIshare_handle\fP makes this function return immediately with no action. .SH EXAMPLE .nf @@ -50,6 +50,6 @@ Added in 7.10 CURLSHE_OK (zero) means that the option was set properly, non-zero means an error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP man page for the full list with descriptions. If an error occurs, then the -share object will not be deleted. +share object is not deleted. .SH "SEE ALSO" .BR curl_share_init "(3), " curl_share_setopt "(3)" diff --git a/docs/libcurl/curl_slist_free_all.3 b/docs/libcurl/curl_slist_free_all.3 index 68505034a6..8cca7a160e 100644 --- a/docs/libcurl/curl_slist_free_all.3 +++ b/docs/libcurl/curl_slist_free_all.3 @@ -34,8 +34,8 @@ void curl_slist_free_all(struct curl_slist *list); curl_slist_free_all() removes all traces of a previously built curl_slist linked list. -Passing in a NULL pointer in \fIlist\fP will make this function return -immediately with no action. +Passing in a NULL pointer in \fIlist\fP makes this function return immediately +with no action. .SH EXAMPLE .nf CURL *handle; diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index 5aef2e912a..c63e221f41 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -33,12 +33,12 @@ char *curl_unescape(const char *input, int length); .SH DESCRIPTION Obsolete function. Use \fIcurl_easy_unescape(3)\fP instead! -This function will convert the URL encoded string \fBinput\fP to a "plain -string" and return that as a new allocated string. All input characters that -are URL encoded (%XX where XX is a two-digit hexadecimal number) will be -converted to their plain text versions. +This function converts the URL encoded string \fBinput\fP to a "plain string" +and return that as a new allocated string. All input characters that are URL +encoded (%XX where XX is a two-digit hexadecimal number) are converted to +their plain text versions. -If the \fBlength\fP argument is set to 0, \fIcurl_unescape(3)\fP will use +If the \fBlength\fP argument is set to 0, \fIcurl_unescape(3)\fP calls strlen() on \fBinput\fP to find out the size. You must \fIcurl_free(3)\fP the returned string when you are done with it. @@ -57,7 +57,7 @@ if(curl) { } .fi .SH AVAILABILITY -Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function will +Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function might be removed in a future release. .SH RETURN VALUE A pointer to a null-terminated string or NULL if it failed. diff --git a/docs/libcurl/curl_url_set.3 b/docs/libcurl/curl_url_set.3 index bfc6bc6d63..cb635291c7 100644 --- a/docs/libcurl/curl_url_set.3 +++ b/docs/libcurl/curl_url_set.3 @@ -94,7 +94,7 @@ to 40 bytes long. The options field is an optional field that might follow the password in the userinfo part. It is only recognized/used when parsing URLs for the following schemes: pop3, smtp and imap. This function however allows users to -independently set this field at will. +independently set this field. .IP CURLUPART_HOST The host name. If it is International Domain Name (IDN) the string must then be encoded as your locale says or UTF-8 (when WinIDN is used). If it is a diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index 7755b16a4a..a0fb1932fd 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -35,10 +35,9 @@ curl_version_info_data *curl_version_info(CURLversion age); Returns a pointer to a filled in static struct with information about various features in the running version of libcurl. \fIage\fP should be set to the version of this functionality by the time you write your program. This way, -libcurl will always return a proper struct that your program understands, -while programs in the future might get a different -struct. \fBCURLVERSION_NOW\fP will be the most recent one for the library you -have installed: +libcurl always returns a proper struct that your program understands, while +programs in the future might get a different struct. \fBCURLVERSION_NOW\fP is +the most recent one for the library you have installed: .nf data = curl_version_info(CURLVERSION_NOW); .fi diff --git a/docs/libcurl/curl_ws_meta.3 b/docs/libcurl/curl_ws_meta.3 index 891ee7bdf4..c807812028 100644 --- a/docs/libcurl/curl_ws_meta.3 +++ b/docs/libcurl/curl_ws_meta.3 @@ -69,12 +69,12 @@ complete. .SH FLAGS .IP CURLWS_TEXT The buffer contains text data. Note that this makes a difference to WebSocket -but libcurl itself will not make any verification of the content or +but libcurl itself does not make any verification of the content or precautions that you actually receive valid UTF-8 content. .IP CURLWS_BINARY This is binary data. .IP CURLWS_CONT -This is not the final fragment of the message, it implies that there will be +This is not the final fragment of the message, it implies that there is another fragment coming as part of the same message. .IP CURLWS_CLOSE This transfer is now closed. diff --git a/docs/libcurl/curl_ws_send.3 b/docs/libcurl/curl_ws_send.3 index 3519d79140..25b59e4575 100644 --- a/docs/libcurl/curl_ws_send.3 +++ b/docs/libcurl/curl_ws_send.3 @@ -58,14 +58,13 @@ in all frames except the final one. .SH FLAGS .IP CURLWS_TEXT The buffer contains text data. Note that this makes a difference to WebSocket -but libcurl itself will not make any verification of the content or +but libcurl itself does not make any verification of the content or precautions that you actually send valid UTF-8 content. .IP CURLWS_BINARY This is binary data. .IP CURLWS_CONT -This is not the final fragment of the message, which implies that there will -be another fragment coming as part of the same message where this bit is not -set. +This is not the final fragment of the message, which implies that there is +another fragment coming as part of the same message where this bit is not set. .IP CURLWS_CLOSE Close this transfer. .IP CURLWS_PING @@ -73,7 +72,7 @@ This is a ping. .IP CURLWS_PONG This is a pong. .IP CURLWS_OFFSET -The provided data is only a partial fragment and there will be more in a +The provided data is only a partial fragment and there is more coming in a following call to \fIcurl_ws_send()\fP. When sending only a piece of the fragment like this, the \fIfragsize\fP must be provided with the total expected fragment size in the first call and it needs to be zero in subsequent diff --git a/docs/libcurl/libcurl-easy.3 b/docs/libcurl/libcurl-easy.3 index fe4fbc78f5..005aed7cd1 100644 --- a/docs/libcurl/libcurl-easy.3 +++ b/docs/libcurl/libcurl-easy.3 @@ -32,13 +32,13 @@ interface functions you use. Use \fIcurl_easy_init(3)\fP to get the handle. You continue by setting all the options you want in the upcoming transfer, the most important among them is the URL itself (you cannot transfer anything without a specified URL as you may have figured out yourself). You might want -to set some callbacks as well that will be called from the library when data -is available etc. \fIcurl_easy_setopt(3)\fP is used for all this. +to set some callbacks as well that are called from the library when data is +available etc. \fIcurl_easy_setopt(3)\fP is used for all this. \fICURLOPT_URL(3)\fP is the only option you really must set, as otherwise there can be no transfer. Another commonly used option is -\fICURLOPT_VERBOSE(3)\fP that will help you see what libcurl is doing under -the hood, which is useful when debugging for example. The +\fICURLOPT_VERBOSE(3)\fP that helps you see what libcurl is doing under the +hood, which is useful when debugging for example. The \fIcurl_easy_setopt(3)\fP man page has a full index of the almost 300 available options. @@ -48,8 +48,8 @@ make a clone of an easy handle (with all its set options) using \fIcurl_easy_duphandle(3)\fP. When all is setup, you tell libcurl to perform the transfer using -\fIcurl_easy_perform(3)\fP. It will then do the entire operation and will not -return until it is done (successfully or not). +\fIcurl_easy_perform(3)\fP. It performs the entire transfer operation and does +not return until it is done (successfully or not). After the transfer has been made, you can set new options and make another transfer, or if you are done, cleanup the session by calling diff --git a/docs/libcurl/libcurl-env.3 b/docs/libcurl/libcurl-env.3 index a7b5504bc8..de29f77b8b 100644 --- a/docs/libcurl/libcurl-env.3 +++ b/docs/libcurl/libcurl-env.3 @@ -25,30 +25,29 @@ .SH NAME libcurl-env \- environment variables libcurl understands .SH DESCRIPTION -libcurl reads and understands a set of environment variables that if set will -control and change behaviors. This is the full list of variables to set and +libcurl reads and understands a set of environment variables that if set +controls and changes behaviors. This is the full list of variables to set and description of what they do. Also note that curl, the command line tool, supports a set of additional environment variables independently of this. .IP "[scheme]_proxy" When libcurl is given a URL to use in a transfer, it first extracts the "scheme" part from the URL and checks if there is a given proxy set for that in its corresponding environment variable. A URL like "https://example.com" -will hence use the "http_proxy" variable, while a URL like "ftp://example.com" -will use the "ftp_proxy" variable. +makes libcurl use the "http_proxy" variable, while a URL like +"ftp://example.com" uses the "ftp_proxy" variable. These proxy variables are also checked for in their uppercase versions, except the "http_proxy" one which is only used lowercase. Note also that some systems actually have a case insensitive handling of environment variables and then of -course "HTTP_PROXY" will still work... +course "HTTP_PROXY" still works. .IP ALL_PROXY This is a setting to set proxy for all URLs, independently of what scheme is -being used. Note that the scheme specific variables will override this one if -set. +being used. Note that the scheme specific variables overrides this one if set. .IP CURL_SSL_BACKEND -When libcurl is built to support multiple SSL backends, it will select a -specific backend at first use. If no selection is done by the program using -libcurl, this variable's selection will be used. Setting a name that is not a -built-in alternative will make libcurl stay with the default. +When libcurl is built to support multiple SSL backends, it selects a specific +backend at first use. If no selection is done by the program using libcurl, +this variable's selection is used. Setting a name that is not a built-in +alternative makes libcurl stay with the default. SSL backend names (case-insensitive): BearSSL, GnuTLS, mbedTLS, nss, OpenSSL, rustls, Schannel, Secure-Transport, wolfSSL @@ -71,14 +70,17 @@ should not use a proxy. User name to use when invoking the \fIntlm-wb\fP tool. .IP SSLKEYLOGFILE When set and libcurl runs with a SSL backend that supports this feature, -libcurl will save SSL secrets into the given file name. Using those SSL -secrets, other tools (such as Wireshark) can decrypt the SSL communication and +libcurl saves SSL secrets into the given file name. Using those SSL secrets, +other tools (such as Wireshark) can decrypt the SSL communication and analyze/view the traffic. + +These secrets and this file might be sensitive. Users are advised to take +precautions so that they are not stolen or otherwise inadvertently revealed. .IP USER User name to use when invoking the \fIntlm-wb\fP tool, if \fINTLMUSER\fP and \fILOGNAME\fP were not set. .SH "Debug Variables" -There's a set of variables only recognized and used if libcurl was built +There is a set of variables only recognized and used if libcurl was built "debug enabled", which should never be true for a library used in production. .IP "CURL_GETHOSTNAME" Debug-only variable. diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 41743b961f..4ba3fc1e64 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -31,8 +31,8 @@ Why they occur and possibly what you can do to fix the problem are also included .SH "CURLcode" Almost all "easy" interface functions return a CURLcode error code. No matter what, using the \fIcurl_easy_setopt(3)\fP option \fICURLOPT_ERRORBUFFER(3)\fP -is a good idea as it will give you a human readable error string that may -offer more details about the cause of the error than just the error code. +is a good idea as it gives you a human readable error string that may offer +more details about the cause of the error than just the error code. \fIcurl_easy_strerror(3)\fP can be called to get an error string from a given CURLcode number. @@ -228,7 +228,7 @@ Illegal TFTP operation. .IP "CURLE_TFTP_UNKNOWNID (72)" Unknown TFTP transfer ID. .IP "CURLE_REMOTE_FILE_EXISTS (73)" -File already exists and will not be overwritten. +File already exists and is not overwritten. .IP "CURLE_TFTP_NOSUCHUSER (74)" This error should never be returned by a properly functioning TFTP server. .IP "Obsolete error (75-76)" @@ -252,8 +252,8 @@ Issuer check failed (Added in 7.19.0) .IP "CURLE_FTP_PRET_FAILED (84)" The FTP server does not understand the PRET command at all or does not support the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST(3)\fP, a -custom LIST command will be sent with the PRET command before PASV as -well. (Added in 7.20.0) +custom LIST command is sent with the PRET command before PASV as well. (Added +in 7.20.0) .IP "CURLE_RTSP_CSEQ_ERROR (85)" Mismatch of RTSP CSeq numbers. .IP "CURLE_RTSP_SESSION_ERROR (86)" @@ -263,8 +263,8 @@ Unable to parse FTP file list (during FTP wildcard downloading). .IP "CURLE_CHUNK_FAILED (88)" Chunk callback reported error. .IP "CURLE_NO_CONNECTION_AVAILABLE (89)" -(For internal use only, will never be returned by libcurl) No connection -available, the session will be queued. (added in 7.30.0) +(For internal use only, is never returned by libcurl) No connection available, +the session is queued. (added in 7.30.0) .IP "CURLE_SSL_PINNEDPUBKEYNOTMATCH (90)" Failed to match the pinned key specified with \fICURLOPT_PINNEDPUBLICKEY(3)\fP. .IP "CURLE_SSL_INVALIDCERTSTATUS (91)" @@ -289,8 +289,8 @@ SSL Client Certificate required. .IP "CURLE_UNRECOVERABLE_POLL (99)" An internal call to poll() or select() returned error that is not recoverable. .IP "CURLE_OBSOLETE*" -These error codes will never be returned. They were used in an old libcurl -version and are currently unused. +These error codes are never returned. They were used in an old libcurl version +and are currently unused. .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi interface. Also consider \fIcurl_multi_strerror(3)\fP. @@ -335,8 +335,8 @@ A multi handle callback returned error. .IP "CURLM_UNRECOVERABLE_POLL (12)" An internal call to poll() or select() returned error that is not recoverable. .SH "CURLSHcode" -The "share" interface will return a \fBCURLSHcode\fP to indicate when an error -has occurred. Also consider \fIcurl_share_strerror(3)\fP. +The "share" interface returns a \fBCURLSHcode\fP to indicate when an error has +occurred. Also consider \fIcurl_share_strerror(3)\fP. .IP "CURLSHE_OK (0)" All fine. Proceed as usual. .IP "CURLSHE_BAD_OPTION (1)" @@ -352,7 +352,7 @@ Not enough memory was available. The requested sharing could not be done because the library you use do not have that particular feature enabled. (Added in 7.23.0) .SH "CURLUcode" -The URL interface will return a \fICURLUcode\fP to indicate when an error has +The URL interface returns a \fICURLUcode\fP to indicate when an error has occurred. Also consider \fIcurl_url_strerror(3)\fP. .IP "CURLUE_OK (0)" All fine. Proceed as usual. diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index fb1fe4ac48..24751bc9e0 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -28,7 +28,7 @@ libcurl-multi \- how to use the multi interface .SH DESCRIPTION This is an overview on how to use the libcurl multi interface in your C programs. There are specific man pages for each function mentioned in -here. There's also the \fIlibcurl-tutorial(3)\fP man page for a complete +here. There is also the \fIlibcurl-tutorial(3)\fP man page for a complete tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page for an overview of the libcurl easy interface. @@ -59,8 +59,8 @@ handle. You create all the easy handles you need, and setup the appropriate options for each easy handle using \fIcurl_easy_setopt(3)\fP. There are two flavors of the multi interface, the select() oriented one and -the event based one we call multi_socket. You will benefit from reading -through the description of both versions to fully understand how they work and +the event based one we call multi_socket. You benefit from reading through the +description of both versions to fully understand how they work and differentiate. We start out with the select() oriented version. When an easy handle is setup and ready for transfer, then instead of using @@ -78,17 +78,17 @@ necessary. You can remove handles at any point during transfers. Adding the easy handle to the multi handle does not start the transfer. Remember that one of the main ideas with this interface is to let your application drive. You drive the transfers by invoking -\fIcurl_multi_perform(3)\fP. libcurl will then transfer data if there is -anything available to transfer. it will use the callbacks and everything else -you have setup in the individual easy handles. it will transfer data on all -current transfers in the multi stack that are ready to transfer anything. It -may be all, it may be none. When there's nothing more to do for now, it -returns back to the calling application. +\fIcurl_multi_perform(3)\fP. libcurl then transfers data if there is anything +available to transfer. It uses the callbacks and everything else you have +setup in the individual easy handles. It transfers data on all current +transfers in the multi stack that are ready to transfer anything. It may be +all, it may be none. When there is nothing more to do for now, it returns back +to the calling application. Your application extracts info from libcurl about when it would like to get invoked to transfer data or do other work. The most convenient way is to use -\fIcurl_multi_poll(3)\fP that will help you wait until the application should -call libcurl again. The older API to accomplish the same thing is +\fIcurl_multi_poll(3)\fP that helps you wait until the application should call +libcurl again. The older API to accomplish the same thing is \fIcurl_multi_fdset(3)\fP that extracts \fIfd_sets\fP from libcurl to use in select() or poll() calls in order to get to know when the transfers in the multi stack might need attention. Both these APIs allow for your program to @@ -119,13 +119,13 @@ When all transfers in the multi stack are done, close the multi handle with invoke separate \fIcurl_easy_cleanup(3)\fP calls for every single easy handle to clean them up properly. -If you want to re-use an easy handle that was added to the multi handle for +If you want to reuse an easy handle that was added to the multi handle for transfer, you must first remove it from the multi stack and then re-add it again (possibly after having altered some options at your own choice). .SH "MULTI_SOCKET" \fIcurl_multi_socket_action(3)\fP function offers a way for applications to not only avoid being forced to use select(), but it also offers a much more -high-performance API that will make a significant difference for applications +high-performance API that makes a significant difference for applications using large numbers of simultaneous connections. \fIcurl_multi_socket_action(3)\fP is then used instead of @@ -135,9 +135,9 @@ When using this API, you add easy handles to the multi handle just as with the normal multi interface. Then you also set two callbacks with the \fICURLMOPT_SOCKETFUNCTION(3)\fP and \fICURLMOPT_TIMERFUNCTION(3)\fP options to \fIcurl_multi_setopt(3)\fP. They are two callback functions that libcurl -will call with information about what sockets to wait for, and for what -activity, and what the current timeout time is - if that expires libcurl -should be notified. +calls with information about what sockets to wait for, and for what activity, +and what the current timeout time is - if that expires libcurl should be +notified. The multi_socket API is designed to inform your application about which sockets libcurl is currently using and for what activities (read and/or write) @@ -161,10 +161,10 @@ losing performance. When you have added your initial set of handles, you call \fIcurl_multi_socket_action(3)\fP with CURL_SOCKET_TIMEOUT set in the -\fIsockfd\fP argument, and you will get callbacks call that sets you up and -you then continue to call \fIcurl_multi_socket_action(3)\fP accordingly when -you get activity on the sockets you have been asked to wait on, or if the -timeout timer expires. +\fIsockfd\fP argument, and you get callbacks invoked that set you up and you +then continue to call \fIcurl_multi_socket_action(3)\fP accordingly when you +get activity on the sockets you have been asked to wait on, or if the timeout +timer expires. You can poll \fIcurl_multi_info_read(3)\fP to see if any transfer has completed, as it then has a message saying so. diff --git a/docs/libcurl/libcurl-security.3 b/docs/libcurl/libcurl-security.3 index 8d20a3d703..e95bb6ecc4 100644 --- a/docs/libcurl/libcurl-security.3 +++ b/docs/libcurl/libcurl-security.3 @@ -56,8 +56,8 @@ this. automatically to frequently visited sites. The file contains passwords in clear text and is a real security risk. In some cases, your .netrc is also stored in a home directory that is NFS mounted or used on another network -based file system, so the clear text password will fly through your network -every time anyone reads that file. +based file system, so the clear text password flies through your network every +time anyone reads that file. For applications that enable .netrc use, a user who manage to set the right URL might then be possible to pass on passwords. @@ -135,8 +135,8 @@ function in which addresses are sanitized before use. For all options in libcurl which specify headers, including but not limited to \fICURLOPT_HTTPHEADER(3)\fP, \fICURLOPT_PROXYHEADER(3)\fP, \fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_REFERER(3)\fP -and \fICURLOPT_RANGE(3)\fP, libcurl will send the headers as-is and will not -apply any special sanitation or normalization to them. +and \fICURLOPT_RANGE(3)\fP, libcurl sends the headers as-is and does not apply +any special sanitation or normalization to them. If you allow untrusted user input into these options without sanitizing CRLF sequences in them, someone malicious may be able to modify the request in a @@ -180,18 +180,18 @@ idea because of the many different ways a numerical IPv4 address can be specified and libcurl accepts: one to four dot-separated fields using one of or a mix of decimal, octal or hexadecimal encoding. .SH "IPv6 Addresses" -libcurl will normally handle IPv6 addresses transparently and just as easily -as IPv4 addresses. That means that a sanitizing function that filters out -addresses like 127.0.0.1 is not sufficient--the equivalent IPv6 addresses -\fB::1\fP, \fB::\fP, \fB0:00::0:1\fP, \fB::127.0.0.1\fP and -\fB::ffff:7f00:1\fP supplied somehow by an attacker would all bypass a naive -filter and could allow access to undesired local resources. IPv6 also has -special address blocks like link-local and site-local that generally should -not be accessed by a server-side libcurl-using application. A poorly -configured firewall installed in a data center, organization or server may -also be configured to limit IPv4 connections but leave IPv6 connections wide -open. In some cases, setting \fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4 -can be used to limit resolved addresses to IPv4 only and bypass these issues. +libcurl handles IPv6 addresses transparently and just as easily as IPv4 +addresses. That means that a sanitizing function that filters out addresses +like 127.0.0.1 is not sufficient - the equivalent IPv6 addresses \fB::1\fP, +\fB::\fP, \fB0:00::0:1\fP, \fB::127.0.0.1\fP and \fB::ffff:7f00:1\fP supplied +somehow by an attacker would all bypass a naive filter and could allow access +to undesired local resources. IPv6 also has special address blocks like +link-local and site-local that generally should not be accessed by a +server-side libcurl-using application. A poorly configured firewall installed +in a data center, organization or server may also be configured to limit IPv4 +connections but leave IPv6 connections wide open. In some cases, setting +\fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4 can be used to limit resolved +addresses to IPv4 only and bypass these issues. .SH Uploads When uploading, a redirect can cause a local (or remote) file to be overwritten. Applications must not allow any unsanitized URL to be passed in @@ -236,10 +236,10 @@ using the protocol. By default, libcurl prohibits redirects to file:// URLs. .SH "Warning: file:// on Windows" -The Windows operating system will automatically, and without any way for -applications to disable it, try to establish a connection to another host over -the network and access it (over SMB or other protocols), if only the correct -file path is accessed. +The Windows operating system tries automatically, and without any way for +applications to disable it, to establish a connection to another host over the +network and access it (over SMB or other protocols), if only the correct file +path is accessed. When first realizing this, the curl team tried to filter out such attempts in order to protect applications for inadvertent probes of for example internal @@ -253,13 +253,13 @@ system. The conclusion we have come to is that this is a weakness or feature in the Windows operating system itself, that we as an application cannot safely protect users against. It would just be a whack-a-mole race we do not want to -participate in. There are too many ways to do it and there's no knob we can +participate in. There are too many ways to do it and there is no knob we can use to turn off the practice. If you use curl or libcurl on Windows (any version), disable the use of the FILE protocol in curl or be prepared that accesses to a range of "magic paths" -will potentially make your system try to access other hosts on your -network. curl cannot protect you against this. +potentially make your system access other hosts on your network. curl cannot +protect you against this. .SH "What if the user can set the URL" Applications may find it tempting to let users set the URL that it can work on. That is probably fine, but opens up for mischief and trickery that you as @@ -311,7 +311,7 @@ given IP+PORT, or with PASV/EPSV that makes the server setup a port to listen to and tells the client to connect to a given IP+PORT. Again, unauthenticated means that the connection might be meddled with by a -man-in-the-middle or that there's a malicious server pretending to be the +man-in-the-middle or that there is a malicious server pretending to be the right one. A malicious FTP server can respond to PASV commands with the IP+PORT of a @@ -397,19 +397,19 @@ etc), it should be noted that libcurl still might understand proxy environment variables that allow the user to redirect libcurl operations to use a proxy controlled by the user. .SH "File descriptors, fork and NTLM" -An application that uses libcurl and invokes \fIfork()\fP will get all file +An application that uses libcurl and invokes \fIfork()\fP gets all file descriptors duplicated in the child process, including the ones libcurl created. libcurl itself uses \fIfork()\fP and \fIexecl()\fP if told to use the -\fBCURLAUTH_NTLM_WB\fP authentication method which then will invoke the helper +\fBCURLAUTH_NTLM_WB\fP authentication method which then invokes the helper command in a child process with file descriptors duplicated. Make sure that only the trusted and reliable helper program is invoked! .SH "Secrets in memory" When applications pass user names, passwords or other sensitive data to -libcurl to be used for upcoming transfers, those secrets will be kept around -as-is in memory. In many cases they will be stored in heap for as long as the -handle itself for which the options are set. +libcurl to be used for upcoming transfers, those secrets are kept around as-is +in memory. In many cases they are stored in the heap for as long as the handle +itself for which the options are set. If an attacker can access the heap, like maybe by reading swap space or via a core dump file, such data might be accessible. diff --git a/docs/libcurl/libcurl-share.3 b/docs/libcurl/libcurl-share.3 index 26b95d96d6..8f40c3bfe7 100644 --- a/docs/libcurl/libcurl-share.3 +++ b/docs/libcurl/libcurl-share.3 @@ -37,7 +37,7 @@ The share interface was added to enable sharing of data between curl .SH "ONE SET OF DATA - MANY TRANSFERS" You can have multiple easy handles share data between them. Have them update and use the \fBsame\fP cookie database, DNS cache, TLS session cache and/or -connection cache! This way, each single transfer will take advantage from data +connection cache! This way, each single transfer takes advantage from data updates made by the other transfer(s). .SH "SHARE OBJECT" You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle diff --git a/docs/libcurl/libcurl-thread.3 b/docs/libcurl/libcurl-thread.3 index 8612de610a..00e7d69d49 100644 --- a/docs/libcurl/libcurl-thread.3 +++ b/docs/libcurl/libcurl-thread.3 @@ -75,20 +75,22 @@ The engine is used by libcurl in a way that is fully thread-safe. The engine is used by libcurl in a way that is fully thread-safe. .SH "Signals" Signals are used for timing out name resolves (during DNS lookup) - when built -without using either the c-ares or threaded resolver backends. When using -multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP option to 1L for -all handles. Everything will or might work fine except that timeouts are not -honored during the DNS lookup - which you can work around by building libcurl -with c-ares or threaded-resolver support. c-ares is a library that provides -asynchronous name resolves. On some platforms, libcurl simply will not +without using either the c-ares or threaded resolver backends. On systems that +have a signal concept. + +When using multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP +option to 1L for all handles. Everything works fine except that timeouts +cannot be honored during DNS lookups - which you can work around by building +libcurl with c-ares or threaded-resolver support. c-ares is a library that +provides asynchronous name resolves. On some platforms, libcurl simply cannot function properly multi-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option is set. When \fICURLOPT_NOSIGNAL(3)\fP is set to 1L, your application needs to deal with the risk of a SIGPIPE (that at least the OpenSSL backend can -trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L will not work in a -threaded situation as there will be race where libcurl risks restoring the -former signal handler while another thread should still ignore it. +trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L does not work in a +threaded situation as there is a race condition where libcurl risks restoring +the former signal handler while another thread should still ignore it. .SH "Name resolving" The \fBgethostbyname\fP or \fBgetaddrinfo\fP and other name resolving system calls used by libcurl are provided by your operating system and must be thread diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 88c64b6d46..9c9a4b65f1 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -27,24 +27,23 @@ libcurl-tutorial \- libcurl programming tutorial .SH "Objective" This document attempts to describe the general principles and some basic -approaches to consider when programming with libcurl. The text will focus -mainly on the C interface but might apply fairly well on other interfaces as -well as they usually follow the C one pretty closely. +approaches to consider when programming with libcurl. The text focuses on the +C interface but should apply fairly well on other language bindings as well as +they usually follow the C API pretty closely. -This document will refer to 'the user' as the person writing the source code -that uses libcurl. That would probably be you or someone in your position. -What will be generally referred to as 'the program' will be the collected -source code that you write that is using libcurl for transfers. The program -is outside libcurl and libcurl is outside of the program. +This document refers to 'the user' as the person writing the source code that +uses libcurl. That would probably be you or someone in your position. What is +generally referred to as 'the program' is the collected source code that you +write that is using libcurl for transfers. The program is outside libcurl and +libcurl is outside of the program. To get more details on all options and functions described herein, please refer to their respective man pages. .SH "Building" -There are many different ways to build C programs. This chapter will assume a -Unix style build process. If you use a different build system, you can still -read this to get general information that may apply to your environment as -well. +There are many different ways to build C programs. This chapter assumes a Unix +style build process. If you use a different build system, you can still read +this to get general information that may apply to your environment as well. .IP "Compiling the Program" Your compiler needs to know where the libcurl headers are located. Therefore you must set your compiler's include path to point to the directory where you @@ -66,15 +65,15 @@ tool comes to the rescue: libcurl can be built and customized in many ways. One of the things that varies from different libraries and builds is the support for SSL-based transfers, like HTTPS and FTPS. If a supported SSL library was detected -properly at build-time, libcurl will be built with SSL support. To figure out -if an installed libcurl has been built with SSL support enabled, use -\&'curl-config' like this: +properly at build-time, libcurl is built with SSL support. To figure out if an +installed libcurl has been built with SSL support enabled, use \&'curl-config' +like this: .nf $ curl-config --feature .fi -And if SSL is supported, the keyword \fISSL\fP will be written to stdout, -possibly together with a few other features that could be either on or off on -for different libcurls. +And if SSL is supported, the keyword \fISSL\fP is written to stdout, possibly +together with a other features that could be either on or off on for different +libcurls. See also the "Features libcurl Provides" further down. .IP "autoconf macro" @@ -99,20 +98,20 @@ use the library. Once for your program's entire life time. This is done using curl_global_init() .fi and it takes one parameter which is a bit pattern that tells libcurl what to -initialize. Using \fICURL_GLOBAL_ALL\fP will make it initialize all known -internal sub modules, and might be a good default option. The current two bits -that are specified are: +initialize. Using \fICURL_GLOBAL_ALL\fP makes it initialize all known internal +sub modules, and might be a good default option. The current two bits that are +specified are: .RS .IP "CURL_GLOBAL_WIN32" -which only does anything on Windows machines. When used on -a Windows machine, it will make libcurl initialize the win32 socket -stuff. Without having that initialized properly, your program cannot use -sockets properly. You should only do this once for each application, so if -your program already does this or of another library in use does it, you -should not tell libcurl to do this as well. +which only does anything on Windows machines. When used on a Windows machine, +it makes libcurl initialize the win32 socket stuff. Without having that +initialized properly, your program cannot use sockets properly. You should +only do this once for each application, so if your program already does this +or of another library in use does it, you should not tell libcurl to do this +as well. .IP CURL_GLOBAL_SSL which only does anything on libcurls compiled and built SSL-enabled. On these -systems, this will make libcurl initialize the SSL library properly for this +systems, this makes libcurl initialize the SSL library properly for this application. This only needs to be done once for each application so if your program or another library already does this, this bit should not be needed. .RE @@ -124,8 +123,8 @@ function itself with a guessed bit pattern. Please note that depending solely on this is not considered nice nor good. When the program no longer uses libcurl, it should call -\fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It will -then do the reversed operations to cleanup the resources the +\fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It +performs the reversed operations to cleanup the resources the \fIcurl_global_init(3)\fP call initialized. Repeated calls to \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP @@ -164,9 +163,9 @@ transfer or series of transfers. You set properties and options for this handle using \fIcurl_easy_setopt(3)\fP. They control how the subsequent transfer or -transfers will be made. Options remain set in the handle until set again to -something different. They are sticky. Multiple requests using the same handle -will use the same options. +transfers using this handle are made. Options remain set in the handle until +set again to something different. They are sticky. Multiple requests using the +same handle use the same options. If you at any point would like to blank all previously set options for a single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also @@ -204,70 +203,70 @@ by setting another property: curl_easy_setopt(handle, CURLOPT_WRITEDATA, &internal_struct); .fi Using that property, you can easily pass local data between your application -and the function that gets invoked by libcurl. libcurl itself will not touch the -data you pass with \fICURLOPT_WRITEDATA(3)\fP. +and the function that gets invoked by libcurl. libcurl itself does not touch +the data you pass with \fICURLOPT_WRITEDATA(3)\fP. -libcurl offers its own default internal callback that will take care of the -data if you do not set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It -will then simply output the received data to stdout. You can have the default -callback write the data to a different file handle by passing a 'FILE *' to a -file opened for writing with the \fICURLOPT_WRITEDATA(3)\fP option. +libcurl offers its own default internal callback that takes care of the data +if you do not set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It simply +outputs the received data to stdout. You can have the default callback write +the data to a different file handle by passing a 'FILE *' to a file opened for +writing with the \fICURLOPT_WRITEDATA(3)\fP option. -Now, we need to take a step back and have a deep breath. Here's one of those +Now, we need to take a step back and take a deep breath. Here is one of those rare platform-dependent nitpicks. Did you spot it? On some platforms[2], -libcurl will not be able to operate on files opened by the program. Thus, if you -use the default callback and pass in an open file with -\fICURLOPT_WRITEDATA(3)\fP, it will crash. You should therefore avoid this to -make your program run fine virtually everywhere. +libcurl is not able to operate on file handles opened by the +program. Therefore, if you use the default callback and pass in an open file +handle with \fICURLOPT_WRITEDATA(3)\fP, libcurl crashes. You should avoid this +to make your program run fine virtually everywhere. (\fICURLOPT_WRITEDATA(3)\fP was formerly known as \fICURLOPT_FILE\fP. Both names still work and do the same thing). If you are using libcurl as a win32 DLL, you MUST use the -\fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP - or you -will experience crashes. +\fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP - or +experience crashes. -There are of course many more options you can set, and we will get back to a few -of them later. Let's instead continue to the actual transfer: +There are of course many more options you can set, and we get back to a few of +them later. Let's instead continue to the actual transfer: .nf success = curl_easy_perform(handle); .fi -\fIcurl_easy_perform(3)\fP will connect to the remote site, do the necessary -commands and receive the transfer. Whenever it receives data, it calls the +\fIcurl_easy_perform(3)\fP connects to the remote site, does the necessary +commands and performs the transfer. Whenever it receives data, it calls the callback function we previously set. The function may get one byte at a time, or it may get many kilobytes at once. libcurl delivers as much as possible as often as possible. Your callback function should return the number of bytes it \&"took care of". If that is not the same amount of bytes that was passed to -it, libcurl will abort the operation and return with an error code. +it, libcurl aborts the operation and returns with an error code. When the transfer is complete, the function returns a return code that informs you if it succeeded in its mission or not. If a return code is not enough for you, you can use the \fICURLOPT_ERRORBUFFER(3)\fP to point libcurl to a buffer -of yours where it will store a human readable error message as well. +of yours where it stores a human readable error message as well. If you then want to transfer another file, the handle is ready to be used -again. Mind you, it is even preferred that you re-use an existing handle if -you intend to make another transfer. libcurl will then attempt to re-use the +again. It is even preferred and encouraged that you reuse an existing handle +if you intend to make another transfer. libcurl then attempts to reuse a previous connection. For some protocols, downloading a file can involve a complicated process of logging in, setting the transfer mode, changing the current directory and finally transferring the file data. libcurl takes care of all that -complication for you. Given simply the URL to a file, libcurl will take care -of all the details needed to get the file moved from one machine to another. +complication for you. Given simply the URL to a file, libcurl takes care of +all the details needed to get the file moved from one machine to another. .SH "Multi-threading Issues" libcurl is thread safe but there are a few exceptions. Refer to \fIlibcurl-thread(3)\fP for more information. .SH "When It does not Work" -There will always be times when the transfer fails for some reason. You might -have set the wrong libcurl option or misunderstood what the libcurl option -actually does, or the remote server might return non-standard replies that -confuse the library which then confuses your program. +There are times when the transfer fails for some reason. You might have set +the wrong libcurl option or misunderstood what the libcurl option actually +does, or the remote server might return non-standard replies that confuse the +library which then confuses your program. -There's one golden rule when these things occur: set the -\fICURLOPT_VERBOSE(3)\fP option to 1. it will cause the library to spew out the +There is one golden rule when these things occur: set the +\fICURLOPT_VERBOSE(3)\fP option to 1. it causes the library to spew out the entire protocol details it sends, some internal info and some received protocol data as well (especially when using FTP). If you are using HTTP, adding the headers in the received output to study is also a clever way to get @@ -293,14 +292,14 @@ libcurl tries to keep a protocol independent approach to most transfers, thus uploading to a remote FTP site is similar to uploading data to an HTTP server with a PUT request. -Of course, first you either create an easy handle or you re-use one existing +Of course, first you either create an easy handle or you reuse one existing one. Then you set the URL to operate on just like before. This is the remote -URL, that we now will upload. +URL, that we now upload. Since we write an application, we most likely want libcurl to get the upload -data by asking us for it. To make it do that, we set the read callback and -the custom pointer libcurl will pass to our read callback. The read callback -should have a prototype similar to: +data by asking us for it. To make it do that, we set the read callback and the +custom pointer libcurl passes to our read callback. The read callback should +have a prototype similar to: .nf size_t function(char *bufptr, size_t size, size_t nitems, void *userp); .fi @@ -318,7 +317,7 @@ Tell libcurl that we want to upload: .nf curl_easy_setopt(handle, CURLOPT_UPLOAD, 1L); .fi -A few protocols will not behave properly when uploads are done without any prior +A few protocols do not behave properly when uploads are done without any prior knowledge of the expected file size. So, set the upload file size using the \fICURLOPT_INFILESIZE_LARGE(3)\fP for all known file sizes like this[1]: @@ -327,12 +326,12 @@ knowledge of the expected file size. So, set the upload file size using the curl_easy_setopt(handle, CURLOPT_INFILESIZE_LARGE, file_size); .fi -When you call \fIcurl_easy_perform(3)\fP this time, it will perform all the -necessary operations and when it has invoked the upload it will call your -supplied callback to get the data to upload. The program should return as much -data as possible in every invoke, as that is likely to make the upload perform -as fast as possible. The callback should return the number of bytes it wrote -in the buffer. Returning 0 will signal the end of the upload. +When you call \fIcurl_easy_perform(3)\fP this time, it performs all the +necessary operations and when it has invoked the upload it calls your supplied +callback to get the data to upload. The program should return as much data as +possible in every invoke, as that is likely to make the upload perform as fast +as possible. The callback should return the number of bytes it wrote in the +buffer. Returning 0 signals the end of the upload. .SH "Passwords" Many protocols use or even require that user name and password are provided @@ -340,8 +339,8 @@ to be able to download or upload the data of your choice. libcurl offers several ways to specify them. Most protocols support that you specify the name and password in the URL -itself. libcurl will detect this and use them accordingly. This is written -like this: +itself. libcurl detects this and use them accordingly. This is written like +this: .nf protocol://user:password@example.com/path/ .fi @@ -362,7 +361,7 @@ similar to the \fICURLOPT_USERPWD(3)\fP option like this: .nf curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); .fi -There's a long time Unix "standard" way of storing FTP user names and +There is a long time Unix "standard" way of storing FTP user names and passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks the \fI%USERPROFILE% environment\fP variable if \fI%HOME%\fP is unset, and tries "_netrc" as name). The file should be made private so that only the user @@ -393,12 +392,12 @@ To pass the known private key password to libcurl: curl_easy_setopt(handle, CURLOPT_KEYPASSWD, "keypassword"); .fi .SH "HTTP Authentication" -The previous chapter showed how to set user name and password for getting -URLs that require authentication. When using the HTTP protocol, there are -many different ways a client can provide those credentials to the server and -you can control which way libcurl will (attempt to) use them. The default HTTP -authentication method is called 'Basic', which is sending the name and -password in clear-text in the HTTP request, base64-encoded. This is insecure. +The previous chapter showed how to set user name and password for getting URLs +that require authentication. When using the HTTP protocol, there are many +different ways a client can provide those credentials to the server and you +can control which way libcurl uses them. The default HTTP authentication +method is called 'Basic', which is sending the name and password in clear-text +in the HTTP request, base64-encoded. This is insecure. At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM, Negotiate (SPNEGO). You can tell libcurl which one to use @@ -421,13 +420,13 @@ must first ask the server what it supports: For convenience, you can use the \fICURLAUTH_ANY\fP define (instead of a list with specific types) which allows libcurl to use whatever method it wants. -When asking for multiple types, libcurl will pick the available one it -considers "best" in its own internal order of preference. +When asking for multiple types, libcurl picks the available one it considers +"best" in its own internal order of preference. .SH "HTTP POSTing" We get many questions regarding how to issue HTTP POSTs with libcurl the -proper way. This chapter will thus include examples using both different -versions of HTTP POST that libcurl supports. +proper way. This chapter thus includes examples using both different versions +of HTTP POST that libcurl supports. The first version is the simple POST, the most common version, that most HTML pages using the
tag uses. We provide a pointer to the data and tell @@ -566,8 +565,8 @@ that describe the individual content-type, size etc. To enable your application to handicraft this formpost even more, libcurl allows you to supply your own set of custom headers to such an individual form part. You can of course supply headers to as many parts as you like, but this little example -will show how you set headers to one specific part when you add that to the -post handle: +shows how you set headers to one specific part when you add that to the post +handle: .nf struct curl_slist *headers=NULL; @@ -593,8 +592,8 @@ request. You force an easy handle to go back to GET by using the .nf curl_easy_setopt(handle, CURLOPT_HTTPGET, 1L); .fi -Just setting \fICURLOPT_POSTFIELDS(3)\fP to "" or NULL will *not* stop libcurl -from doing a POST. It will just make it POST without any data to send! +Just setting \fICURLOPT_POSTFIELDS(3)\fP to "" or NULL does *not* stop libcurl +from doing a POST. It just makes it POST without any data to send! .SH "Converting from deprecated form API to MIME API" Four rules have to be respected in building the multi-part: @@ -643,9 +642,9 @@ becomes: .fi \fIcurl_mime_name\fP always copies the field name. The special file name "-" -is not supported by \fIcurl_mime_file\fP: to read an open file, use -a callback source using fread(). The transfer will be chunked since the data -size is unknown. +is not supported by \fIcurl_mime_file\fP: to read an open file, use a callback +source using fread(). The transfer is be chunk-encoded since the data size is +unknown. .nf curl_formadd(&post, &last, @@ -735,10 +734,10 @@ terminal. Switch on the progress meter by, oddly enough, setting \fICURLOPT_NOPROGRESS(3)\fP to zero. This option is set to 1 by default. -For most applications however, the built-in progress meter is useless and -what instead is interesting is the ability to specify a progress -callback. The function pointer you pass to libcurl will then be called on -irregular intervals with information about the current transfer. +For most applications however, the built-in progress meter is useless and what +instead is interesting is the ability to specify a progress callback. The +function pointer you pass to libcurl is then called on irregular intervals +with information about the current transfer. Set the progress callback by using \fICURLOPT_PROGRESSFUNCTION(3)\fP. And pass a pointer to a function that matches this prototype: @@ -751,13 +750,13 @@ a pointer to a function that matches this prototype: double ulnow); .fi -If any of the input arguments is unknown, a 0 will be passed. The first -argument, the 'clientp' is the pointer you pass to libcurl with -\fICURLOPT_PROGRESSDATA(3)\fP. libcurl will not touch it. +If any of the input arguments is unknown, a 0 is provided. The first argument, +the 'clientp' is the pointer you pass to libcurl with +\fICURLOPT_PROGRESSDATA(3)\fP. libcurl does not touch it. .SH "libcurl with C++" -There's basically only one thing to keep in mind when using C++ instead of C +There is basically only one thing to keep in mind when using C++ instead of C when interfacing libcurl: The callbacks CANNOT be non-static class member functions @@ -786,7 +785,7 @@ the proxy for documents, the proxy does the actual request and then it returns them. libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl -will ask the proxy for it instead of trying to connect to the actual host +asks the proxy for it instead of trying to connect to the actual remote host identified in the URL. If you are using a SOCKS proxy, you may find that libcurl does not quite support @@ -794,11 +793,11 @@ all operations through it. For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain restrictions on what can actually happen. A requested URL that might not be a -HTTP URL will be still be passed to the HTTP proxy to deliver back to -libcurl. This happens transparently, and an application may not need to -know. I say "may", because at times it is important to understand that all -operations over an HTTP proxy use the HTTP protocol. For example, you cannot -invoke your own custom FTP commands or even proper FTP directory listings. +HTTP URL is passed to the HTTP proxy to deliver back to libcurl. This happens +transparently, and an application may not need to know. I say "may", because +at times it is important to understand that all operations over an HTTP proxy +use the HTTP protocol. For example, you cannot invoke your own custom FTP +commands or even proper FTP directory listings. .IP "Proxy Options" @@ -816,7 +815,7 @@ If you want to, you can specify the host name only in the \fICURLOPT_PROXYPORT(3)\fP. Tell libcurl what kind of proxy it is with \fICURLOPT_PROXYTYPE(3)\fP (if not, -it will default to assume an HTTP proxy): +it defaults to assuming an HTTP proxy): .nf curl_easy_setopt(handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4); .fi @@ -835,8 +834,7 @@ The proxy environment variable contents should be in the format \&"[protocol://][user:password@]machine[:port]". Where the protocol:// part specifies which type of proxy it is, and the optional port number specifies on which port the proxy operates. If not specified, the internal default port -number will be used and that is most likely not the one you would like it to -be. +number is used and that is most likely not the one you would like it to be. There are two special environment variables. 'all_proxy' is what sets proxy for any URL in case the protocol specific variable was not set, and @@ -886,10 +884,10 @@ Tell libcurl to use proxy tunneling like this: .nf curl_easy_setopt(handle, CURLOPT_HTTPPROXYTUNNEL, 1L); .fi -In fact, there might even be times when you want to do plain HTTP -operations using a tunnel like this, as it then enables you to operate on -the remote server instead of asking the proxy to do so. libcurl will not -stand in the way for such innovative actions either! +In fact, there might even be times when you want to do plain HTTP operations +using a tunnel like this, as it then enables you to operate on the remote +server instead of asking the proxy to do so. libcurl does not stand in the way +for such innovative actions either! .IP "Proxy Auto-Config" @@ -920,14 +918,14 @@ Mozilla JavaScript engine in the past. Re-cycling the same easy handle several times when doing multiple requests is the way to go. -After each single \fIcurl_easy_perform(3)\fP operation, libcurl will keep the +After each single \fIcurl_easy_perform(3)\fP operation, libcurl keeps the connection alive and open. A subsequent request using the same easy handle to the same host might just be able to use the already open connection! This reduces network impact a lot. Even if the connection is dropped, all connections involving SSL to the same -host again, will benefit from libcurl's session ID cache that drastically -reduces re-connection time. +host again, benefit from libcurl's session ID cache that drastically reduces +re-connection time. FTP connections that are kept alive save a lot of time, as the command- response round-trips are skipped, and also you do not risk getting blocked @@ -940,23 +938,22 @@ looked up name a lot faster. Other interesting details that improve performance for subsequent requests may also be added in the future. -Each easy handle will attempt to keep the last few connections alive for a -while in case they are to be used again. You can set the size of this "cache" -with the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is rarely -any point in changing this value, and if you think of changing this it is -often just a matter of thinking again. +Each easy handle attempts to keep the last few connections alive for a while +in case they are to be used again. You can set the size of this "cache" with +the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is rarely any +point in changing this value, and if you think of changing this it is often +just a matter of thinking again. -To force your upcoming request to not use an already existing connection (it -will even close one first if there happens to be one alive to the same host -you are about to operate on), you can do that by setting -\fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar spirit, you can also forbid -the upcoming request to be "lying" around and possibly get re-used after the -request by setting \fICURLOPT_FORBID_REUSE(3)\fP to 1. +To force your upcoming request to not use an already existing connection, you +can do that by setting \fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar +spirit, you can also forbid the upcoming request to be "lying" around and +possibly get reused after the request by setting +\fICURLOPT_FORBID_REUSE(3)\fP to 1. .SH "HTTP Headers Used by libcurl" -When you use libcurl to do HTTP requests, it will pass along a series of headers -automatically. It might be good for you to know and understand these. You -can replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option. +When you use libcurl to do HTTP requests, it passes along a series of headers +automatically. It might be good for you to know and understand these. You can +replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option. .IP "Host" This header is required by HTTP 1.1 and even many 1.0 servers and should be @@ -969,7 +966,7 @@ anything but default. .IP "Expect" When doing POST requests, libcurl sets this header to \&"100-continue" to ask the server for an "OK" message before it proceeds with sending the data part -of the post. If the posted data amount is deemed "small", libcurl will not use +of the post. If the posted data amount is deemed "small", libcurl does not use this header. .SH "Customizing Operations" @@ -1024,9 +1021,10 @@ replace them by simply setting them too: .fi .IP "Delete Headers" -If you replace an existing header with one with no contents, you will prevent -the header from being sent. For instance, if you want to completely prevent the -\&"Accept:" header from being sent, you can disable it with code similar to this: +If you replace an existing header with one with no contents, you prevent the +header from being sent. For instance, if you want to completely prevent the +\&"Accept:" header from being sent, you can disable it with code similar to +this: headers = curl_slist_append(headers, "Accept:"); @@ -1037,7 +1035,7 @@ when doing so. .IP "Enforcing chunked transfer-encoding" By making sure a request uses the custom header "Transfer-Encoding: chunked" -when doing a non-GET HTTP operation, libcurl will switch over to "chunked" +when doing a non-GET HTTP operation, libcurl switches over to "chunked" upload, even though the size of the data to upload might be known. By default, libcurl usually switches over to chunked upload automatically if the upload data size is unknown. @@ -1061,8 +1059,8 @@ commands exactly as the FTP server expects them (RFC 959 is a good guide here), and you can only use commands that work on the control-connection alone. All kinds of commands that require data interchange and thus need a data-connection must be left to libcurl's own judgment. Also be aware that -libcurl will do its best to change directory to the target directory before -doing any transfer, so if you change directory (with CWD or similar) you might +libcurl does its best to change directory to the target directory before doing +any transfer, so if you change directory (with CWD or similar) you might confuse libcurl and then it might not attempt to transfer the file in the correct remote directory. @@ -1084,24 +1082,24 @@ _after_ the data transfer took place the option to \fIcurl_easy_setopt(3)\fP would instead be called \fICURLOPT_POSTQUOTE(3)\fP and used the exact same way. -The custom FTP command will be issued to the server in the same order they are +The custom FTP commands are issued to the server in the same order they are added to the list, and if a command gets an error code returned back from the -server, no more commands will be issued and libcurl will bail out with an -error code (CURLE_QUOTE_ERROR). Note that if you use \fICURLOPT_QUOTE(3)\fP to -send commands before a transfer, no transfer will actually take place when a -quote command has failed. +server, no more commands are issued and libcurl bails out with an error code +(CURLE_QUOTE_ERROR). Note that if you use \fICURLOPT_QUOTE(3)\fP to send +commands before a transfer, no transfer actually takes place when a quote +command has failed. -If you set the \fICURLOPT_HEADER(3)\fP to 1, you will tell libcurl to get +If you set the \fICURLOPT_HEADER(3)\fP to 1, you tell libcurl to get information about the target file and output "headers" about it. The headers -will be in "HTTP-style", looking like they do in HTTP. +are in "HTTP-style", looking like they do in HTTP. The option to enable headers or to run custom FTP commands may be useful to combine with \fICURLOPT_NOBODY(3)\fP. If this option is set, no actual file -content transfer will be performed. +content transfer is performed. .IP "FTP Custom CUSTOMREQUEST" If you do want to list the contents of an FTP directory using your own defined -FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP will do just that. "NLST" is the +FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP does just that. "NLST" is the default one for listing directories but you are free to pass in your idea of a good alternative. @@ -1133,34 +1131,34 @@ figure out which cookies to use. Set the header file to read cookies from with \fICURLOPT_COOKIEFILE(3)\fP. The \fICURLOPT_COOKIEFILE(3)\fP option also automatically enables the cookie -parser in libcurl. Until the cookie parser is enabled, libcurl will not parse -or understand incoming cookies and they will just be ignored. However, when -the parser is enabled the cookies will be understood and the cookies will be -kept in memory and used properly in subsequent requests when the same handle -is used. Many times this is enough, and you may not have to save the cookies -to disk at all. Note that the file you specify to \fICURLOPT_COOKIEFILE(3)\fP -does not have to exist to enable the parser, so a common way to just enable the -parser and not read any cookies is to use the name of a file you know does not -exist. +parser in libcurl. Until the cookie parser is enabled, libcurl does not parse +or understand incoming cookies and they are just be ignored. However, when the +parser is enabled the cookies are understood and the cookies are kept in +memory and used properly in subsequent requests when the same handle is +used. Many times this is enough, and you may not have to save the cookies to +disk at all. Note that the file you specify to \fICURLOPT_COOKIEFILE(3)\fP +does not have to exist to enable the parser, so a common way to just enable +the parser and not read any cookies is to use the name of a file you know does +not exist. -If you would rather use existing cookies that you have previously received with -your Netscape or Mozilla browsers, you can make libcurl use that cookie file -as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as libcurl -will automatically find out what kind of file it is and act accordingly. +If you would rather use existing cookies that you have previously received +with your Netscape or Mozilla browsers, you can make libcurl use that cookie +file as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as +libcurl automatically finds out what kind of file it is and acts accordingly. Perhaps the most advanced cookie operation libcurl offers, is saving the entire internal cookie state back into a Netscape/Mozilla formatted cookie file. We call that the cookie-jar. When you set a file name with -\fICURLOPT_COOKIEJAR(3)\fP, that file name will be created and all received -cookies will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This -enables cookies to get passed on properly between multiple handles without any +\fICURLOPT_COOKIEJAR(3)\fP, that file name is created and all received cookies +get stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enables +cookies to get passed on properly between multiple handles without any information getting lost. .SH "FTP Peculiarities We Need" FTP transfers use a second TCP/IP connection for the data transfer. This is -usually a fact you can forget and ignore but at times this fact will come -back to haunt you. libcurl offers several different ways to customize how the +usually a fact you can forget and ignore but at times this detail comes back +to haunt you. libcurl offers several different ways to customize how the second connection is being made. libcurl can either connect to the server a second time or tell the server to @@ -1174,19 +1172,18 @@ and does not exist nor work on all FTP servers.) You can prevent libcurl from first trying the EPSV command by setting \fICURLOPT_FTP_USE_EPSV(3)\fP to zero. -In some cases, you will prefer to have the server connect back to you for the -second connection. This might be when the server is perhaps behind a firewall -or something and only allows connections on a single port. libcurl then -informs the remote server which IP address and port number to connect to. -This is made with the \fICURLOPT_FTPPORT(3)\fP option. If you set it to "-", -libcurl will use your system's "default IP address". If you want to use a -particular IP, you can set the full IP address, a host name to resolve to an -IP address or even a local network interface name that libcurl will get the IP -address from. +In some cases, you want to have the server connect back to you for the second +connection. This might be when the server is perhaps behind a firewall or +something and only allows connections on a single port. libcurl then informs +the remote server which IP address and port number to connect to. This is +made with the \fICURLOPT_FTPPORT(3)\fP option. If you set it to "-", libcurl +uses your system's "default IP address". If you want to use a particular IP, +you can set the full IP address, a host name to resolve to an IP address or +even a local network interface name that libcurl gets the IP address from. -When doing the "PORT" approach, libcurl will attempt to use the EPRT and the -LPRT before trying PORT, as they work with more protocols. You can disable -this behavior by setting \fICURLOPT_FTP_USE_EPRT(3)\fP to zero. +When doing the "PORT" approach, libcurl attempts to use the EPRT and the LPRT +before trying PORT, as they work with more protocols. You can disable this +behavior by setting \fICURLOPT_FTP_USE_EPRT(3)\fP to zero. .SH "MIME API revisited for SMTP and IMAP" In addition to support HTTP multi-part form fields, the MIME API can be used @@ -1321,8 +1318,8 @@ When you have added the handles you have for the moment (you can still add new ones at any time), you start the transfers by calling \fIcurl_multi_perform(3)\fP. -\fIcurl_multi_perform(3)\fP is asynchronous. It will only perform what can be -done now and then return control to your program. It is designed to never +\fIcurl_multi_perform(3)\fP is asynchronous. It only performs what can be done +now and then return control to your program. It is designed to never block. You need to keep calling the function until all transfers are completed. @@ -1333,7 +1330,7 @@ sockets/handles. You figure out what to select() for by using \fIcurl_multi_fdset(3)\fP, that fills in a set of \fIfd_set\fP variables for you with the particular file descriptors libcurl uses for the moment. -When you then call select(), it will return when one of the file handles signal +When you then call select(), it returns when one of the file handles signal action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do what it wants to do. Take note that libcurl does also feature some time-out code so we advise you to never use long timeouts on select() before you call @@ -1349,8 +1346,8 @@ can use \fIcurl_multi_remove_handle(3)\fP to remove individual easy handles. Remember that easy handles should be \fIcurl_easy_cleanup(3)\fPed. When a transfer within the multi stack has finished, the counter of running -transfers (as filled in by \fIcurl_multi_perform(3)\fP) will decrease. When -the number reaches zero, all transfers are done. +transfers (as filled in by \fIcurl_multi_perform(3)\fP) decreases. When the +number reaches zero, all transfers are done. \fIcurl_multi_info_read(3)\fP can be used to get information about completed transfers. It then returns the CURLcode for each easy transfer, to allow you @@ -1364,13 +1361,13 @@ to figure out success on each individual transfer. You can share some data between easy handles when the easy interface is used, and some data is share automatically when you use the multi interface. -When you add easy handles to a multi handle, these easy handles will -automatically share a lot of the data that otherwise would be kept on a -per-easy handle basis when the easy interface is used. +When you add easy handles to a multi handle, these easy handles automatically +share a lot of the data that otherwise would be kept on a per-easy handle +basis when the easy interface is used. The DNS cache is shared between handles within a multi handle, making subsequent name resolving faster, and the connection pool that is kept to -better allow persistent connections and connection re-use is also shared. If +better allow persistent connections and connection reuse is also shared. If you are using the easy interface, you can still share these between specific easy handles by using the share interface, see \fIlibcurl-share(3)\fP. diff --git a/docs/libcurl/libcurl-url.3 b/docs/libcurl/libcurl-url.3 index 2d63281004..3dc3c661e5 100644 --- a/docs/libcurl/libcurl-url.3 +++ b/docs/libcurl/libcurl-url.3 @@ -45,8 +45,8 @@ When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP: .fi .SH PARSING By setting a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed -and stored in the handle. If the URL is not syntactically correct it will -return an error instead. +and stored in the handle. If the URL is not syntactically correct it returns +an error instead. .nf rc = curl_url_set(h, CURLUPART_URL, "https://example.com:449/foo/bar?name=moo", 0); @@ -56,8 +56,8 @@ The zero in the fourth argument is a bitmask for changing specific features. If successful, this stores the URL in its individual parts within the handle. .SH REDIRECT -When a handle already contains info about a URL, setting a relative URL will -make it "redirect" to adapt to it. +When a handle already contains info about a URL, setting a relative URL makes +it "redirect" to that. .nf rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0); .fi @@ -120,13 +120,12 @@ application can then add the string "hat=1" to the query part like this: rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY); .fi -It will even notice the lack of an ampersand (&) separator so it will inject -one too, and the handle's full URL will then equal -"https://example.com/?shoes=2&hat=1". +It notices the lack of an ampersand (&) separator and injects one, and the +handle's full URL then equals "https://example.com/?shoes=2&hat=1". The appended string can of course also get URL encoded on add, and if asked to -URL encode, the encoding process will skip the '=' character. For example, -append "candy=N&N" to what we already have, and URL encode it to deal with the +URL encode, the encoding process skips the '=' character. For example, append +"candy=N&N" to what we already have, and URL encode it to deal with the ampersand in the data: .nf rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N", diff --git a/docs/libcurl/libcurl-ws.3 b/docs/libcurl/libcurl-ws.3 index 263430446b..959bbc7622 100644 --- a/docs/libcurl/libcurl-ws.3 +++ b/docs/libcurl/libcurl-ws.3 @@ -62,10 +62,10 @@ been received since only frames have set sizes. libcurl can be told to speak WebSocket in "raw mode" by setting the \fBCURLWS_RAW_MODE\fP bit to the \fICURLOPT_WS_OPTIONS(3)\fP option. -Raw WebSocket means that libcurl will pass on the data from the network -without parsing it leaving that entirely to the application. This mode assumes -that the user of this knows WebSocket and can parse and figure out the data -all by itself. +Raw WebSocket means that libcurl passes on the data from the network without +parsing it leaving that entirely to the application. This mode assumes that +the user of this knows WebSocket and can parse and figure out the data all by +itself. This mode is intended for applications that already have a WebSocket parser/engine that want to switch over to use libcurl for enabling WebSocket, @@ -86,17 +86,17 @@ different API models to use it: downloads for when the traffic is download oriented. 2. Using \fICURLOPT_CONNECT_ONLY(3)\fP and use the WebSocket recv/send -functions at will. +functions. .SH "Callback model" When a write callback is set and a WebSocket transfer is performed, the -callback will be called to deliver all WebSocket data that arrives. +callback is called to deliver all WebSocket data that arrives. The callback can then call \fIcurl_ws_meta(3)\fP to learn about the details of the incoming data fragment. .SH "CONNECT_ONLY model" -By setting \fICURLOPT_CONNECT_ONLY(3)\fP to \fB2L\fP, the transfer will only -establish and setup the WebSocket communication and then return control back -to the application. +By setting \fICURLOPT_CONNECT_ONLY(3)\fP to \fB2L\fP, the transfer only +establishes and setups the WebSocket communication and then returns control +back to the application. Once such a setup has been successfully performed, the application can proceed and use \fIcurl_ws_recv(3)\fP and \fIcurl_ws_send(3)\fP freely to exchange diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index ae8571a0ba..1c17406633 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -37,7 +37,7 @@ language. Look elsewhere for documentation on those. To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP for a single individual transfer (in either direction). You then set your desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options -you set with \fIcurl_easy_setopt(3)\fP stick. They will be used on every +you set with \fIcurl_easy_setopt(3)\fP stick. They are then used for every repeated use of this handle until you either change the option, or you reset them all with \fIcurl_easy_reset(3)\fP. @@ -82,7 +82,7 @@ See \fIlibcurl-ws(3)\fP .RE .SH "LINKING WITH LIBCURL" -On unix-like machines, there's a tool named curl-config that gets installed +On unix-like machines, there is a tool named curl-config that gets installed with the rest of the curl stuff when 'make install' is performed. curl-config is added to make it easier for applications to link with libcurl @@ -114,24 +114,24 @@ libcurl is thread safe but there are a few exceptions. Refer to \fIlibcurl-thread(3)\fP for more information. .SH "PERSISTENT CONNECTIONS" -Persistent connections means that libcurl can re-use the same connection for +Persistent connections means that libcurl can reuse the same connection for several transfers, if the conditions are right. -libcurl will \fBalways\fP attempt to use persistent connections. Whenever you -use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl -will attempt to use an existing connection to do the transfer, and if none -exists it will open a new one that will be subject for re-use on a possible -following call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. +libcurl always attempts to use persistent connections. Whenever you use +\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl +attempts to use an existing connection to do the transfer, and if none exists +it opens a new one that is subject for reuse on a possible following call to +\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. To allow libcurl to take full advantage of persistent connections, you should do as many of your file transfers as possible using the same handle. If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all -the possibly open connections held by libcurl will be closed and forgotten. +the possibly open connections held by libcurl are closed and forgotten. When you have created a multi handle and are using the multi interface, the connection pool is instead kept in the multi handle so closing and creating -new easy handles to do transfers will not affect them. Instead all added easy +new easy handles to do transfers do not affect them. Instead all added easy handles can take advantage of the single shared pool. .SH "GLOBAL CONSTANTS" There are a variety of constants that libcurl uses, mainly through its @@ -187,10 +187,9 @@ A module like this must have global constant functions of its own, just like \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus has control at the beginning and end of the program and has a place to call the libcurl functions. If multiple modules in the program use libcurl, they -all will separately call the libcurl functions, and that is OK because only -the first \fIcurl_global_init(3)\fP and the last \fIcurl_global_cleanup(3)\fP -in a program change anything. (libcurl uses a reference count in static -memory). +all separately call the libcurl functions, and that is OK because only the +first \fIcurl_global_init(3)\fP and the last \fIcurl_global_cleanup(3)\fP in a +program change anything. (libcurl uses a reference count in static memory). In a C++ module, it is common to deal with the global constant situation by defining a special class that represents the global constant environment of diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index 0e470ee9f9..2e215222cc 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -157,7 +157,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], if test $_libcurl_try_link = yes ; then - # we didn't find curl-config, so let's see if the user-supplied + # we did not find curl-config, so let's see if the user-supplied # link line (or failing that, "-lcurl") is enough. LIBCURL=${LIBCURL-"$_libcurl_ldflags -lcurl"} @@ -171,7 +171,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include ]],[[ /* Try and use a few common options to force a failure if we are - missing symbols or can't link. */ + missing symbols or cannot link. */ int x; curl_easy_setopt(NULL,CURLOPT_URL,NULL); x=CURL_ERROR_SIZE; @@ -221,14 +221,14 @@ if (x) {;} if test "x$_libcurl_protocols" = "x" ; then - # We don't have --protocols, so just assume that all + # We do not have --protocols, so just assume that all # protocols are available _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP" if test x$libcurl_feature_SSL = xyes ; then _libcurl_protocols="$_libcurl_protocols HTTPS" - # FTPS wasn't standards-compliant until version + # FTPS was not standards-compliant until version # 7.11.0 (0x070b00 == 461568) if test $_libcurl_version -ge 461568; then _libcurl_protocols="$_libcurl_protocols FTPS" diff --git a/docs/libcurl/opts/CURLINFO_CAINFO.3 b/docs/libcurl/opts/CURLINFO_CAINFO.3 index 094d4d0452..a992bd366f 100644 --- a/docs/libcurl/opts/CURLINFO_CAINFO.3 +++ b/docs/libcurl/opts/CURLINFO_CAINFO.3 @@ -42,7 +42,7 @@ currently set to be used does not support \fICURLOPT_CAINFO(3)\fP. This is a path identifying a single file containing CA certificates. -The \fBpath\fP pointer will be NULL if there is no default path. +The \fBpath\fP pointer is set to NULL if there is no default path. .SH PROTOCOLS All .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_CAPATH.3 b/docs/libcurl/opts/CURLINFO_CAPATH.3 index cbe26198f9..1cc92a928d 100644 --- a/docs/libcurl/opts/CURLINFO_CAPATH.3 +++ b/docs/libcurl/opts/CURLINFO_CAPATH.3 @@ -42,7 +42,7 @@ currently set to be used does not support \fICURLOPT_CAPATH(3)\fP. This is a path identifying a directory. -The \fBpath\fP pointer will be NULL if there is no default path. +The \fBpath\fP pointer is set to NULL if there is no default path. .SH PROTOCOLS All .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.3 b/docs/libcurl/opts/CURLINFO_CERTINFO.3 index b06b3ee4de..706888a743 100644 --- a/docs/libcurl/opts/CURLINFO_CERTINFO.3 +++ b/docs/libcurl/opts/CURLINFO_CERTINFO.3 @@ -33,8 +33,8 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CERTINFO, struct curl_certinfo **chainp); .fi .SH DESCRIPTION -Pass a pointer to a \fIstruct curl_certinfo *\fP and it will be set to point to -a struct that holds info about the server's certificate chain, assuming you had +Pass a pointer to a \fIstruct curl_certinfo *\fP and it is set to point to a +struct that holds info about the server's certificate chain, assuming you had \fICURLOPT_CERTINFO(3)\fP enabled when the request was made. .nf @@ -45,11 +45,11 @@ struct curl_certinfo { .fi The \fIcertinfo\fP struct member is an array of linked lists of certificate -information. The \fInum_of_certs\fP struct member is the number of certificates -which is the number of elements in the array. Each certificate's list has items -with textual information in the format "name:content" such as "Subject:Foo", -"Issuer:Bar", etc. The items in each list will vary depending on the SSL -backend and the certificate. +information. The \fInum_of_certs\fP struct member is the number of +certificates which is the number of elements in the array. Each certificate's +list has items with textual information in the format "name:content" such as +\&"Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on +the SSL backend and the certificate. .SH PROTOCOLS All TLS-based .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 index 5bb2e4d034..28955185b0 100644 --- a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 +++ b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 @@ -36,8 +36,8 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONDITION_UNMET, Pass a pointer to a long to receive the number 1 if the condition provided in the previous request did not match (see \fICURLOPT_TIMECONDITION(3)\fP). Alas, if this returns a 1 you know that the reason you did not get data in return is -because it did not fulfill the condition. The long this argument points to will -get a zero stored if the condition instead was met. This can also return 1 if +because it did not fulfill the condition. The long this argument points to +gets a zero stored if the condition instead was met. This can also return 1 if the server responded with a 304 HTTP status code, for example after sending a custom "If-Match-*" header. .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 index 4ee5b36d2f..ebf9e4ff27 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 +++ b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 @@ -37,9 +37,12 @@ object. This is the value read from the Content-Type: field. If you get NULL, it means that the server did not send a valid Content-Type header or that the protocol used does not support this. -The \fBct\fP pointer will be NULL or pointing to private memory you MUST NOT -free it - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the +The \fBct\fP pointer is set to NULL or pointing to private memory. You MUST +NOT free it - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding CURL handle. + +The modern way to get this header from a response is to instead use the +\fIcurl_easy_header(3)\fP function. .SH PROTOCOLS HTTP(S) .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_COOKIELIST.3 b/docs/libcurl/opts/CURLINFO_COOKIELIST.3 index 5dbd604a07..eed733e2d7 100644 --- a/docs/libcurl/opts/CURLINFO_COOKIELIST.3 +++ b/docs/libcurl/opts/CURLINFO_COOKIELIST.3 @@ -37,7 +37,7 @@ Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all cookies curl knows (expired ones, too). do not forget to call \fIcurl_slist_free_all(3)\fP on the list after it has been used. If there are no cookies (cookies for the handle have not been enabled or simply none have -been received) 'struct curl_slist *' will be set to point to NULL. +been received) the 'struct curl_slist *' is made a NULL pointer. Since 7.43.0 cookies that were imported in the Set-Cookie format without a domain name are not exported by this option. diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 index 8895c56d72..125e078e35 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 @@ -39,8 +39,8 @@ method. In cases when you have asked libcurl to follow redirects, the method may not be the same method the first request would use. -The \fBmethodp\fP pointer will be NULL or pointing to private memory you MUST -NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the +The \fBmethodp\fP pointer is NULL or points to private memory. You MUST NOT +free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding CURL handle. .SH PROTOCOLS HTTP(S) diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 index 7e95e905d3..42f258e70f 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 @@ -37,9 +37,9 @@ Pass in a pointer to a char pointer and get the last used effective URL. In cases when you have asked libcurl to follow redirects, it may not be the same value you set with \fICURLOPT_URL(3)\fP. -The \fBurlp\fP pointer will be NULL or pointing to private memory you MUST NOT -free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the -corresponding CURL handle. +The \fBurlp\fP pointer is NULL or points to private memory. You MUST NOT free +- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. .SH PROTOCOLS HTTP(S) .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_FILETIME.3 b/docs/libcurl/opts/CURLINFO_FILETIME.3 index 59e8e07ed8..4aed79199d 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME.3 +++ b/docs/libcurl/opts/CURLINFO_FILETIME.3 @@ -40,10 +40,10 @@ etc) and the time of the document is unknown. You must tell libcurl to collect this information before the transfer is made, by using the \fICURLOPT_FILETIME(3)\fP option to \fIcurl_easy_setopt(3)\fP or -you will unconditionally get a -1 back. +you this unconditionally gets a -1 back. Consider using \fICURLINFO_FILETIME_T(3)\fP to be able to extract dates beyond -the year 2038 on systems using 32 bit longs. +the year 2038 on systems using 32 bit longs (Windows). .SH PROTOCOLS HTTP(S), FTP(S), SFTP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_FILETIME_T.3 b/docs/libcurl/opts/CURLINFO_FILETIME_T.3 index 82057c20c4..cb3b8641a9 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME_T.3 +++ b/docs/libcurl/opts/CURLINFO_FILETIME_T.3 @@ -41,7 +41,7 @@ document time etc) and the time of the document is unknown. You must ask libcurl to collect this information before the transfer is made, by using the \fICURLOPT_FILETIME(3)\fP option to \fIcurl_easy_setopt(3)\fP or -you will unconditionally get a -1 back. +you unconditionally get a -1 back. This option is an alternative to \fICURLINFO_FILETIME(3)\fP to allow systems with 32 bit long variables to extract dates outside of the 32bit timestamp diff --git a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 index 016b97dff1..f71b59f302 100644 --- a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 +++ b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 @@ -37,9 +37,9 @@ path of the entry path. That is the initial path libcurl ended up in when logging on to the remote FTP server. This stores a NULL as pointer if something is wrong. -The \fBpath\fP pointer will be NULL or pointing to private memory you MUST NOT -free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the -corresponding CURL handle. +The \fBpath\fP pointer is NULL or points to private memory. You MUST NOT free +- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. .SH PROTOCOLS FTP(S) and SFTP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 index 976dec1d34..3622bffd9d 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 +++ b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 @@ -33,8 +33,8 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_CONNECTCODE, long *p); .fi .SH DESCRIPTION Pass a pointer to a long to receive the last received HTTP proxy response code -to a CONNECT request. The returned value will be zero if no such response code -was available. +to a CONNECT request. The returned value is zero if no such response code was +available. .SH PROTOCOLS HTTP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 index 79ffb7e2b2..c32ff689c6 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 +++ b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 @@ -33,9 +33,9 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_VERSION, long *p); .fi .SH DESCRIPTION Pass a pointer to a long to receive the version used in the last http -connection. The returned value will be CURL_HTTP_VERSION_1_0, -CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, CURL_HTTP_VERSION_3 or 0 if the -version cannot be determined. +connection done using this handle. The returned value is +CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, +CURL_HTTP_VERSION_3 or 0 if the version cannot be determined. .SH PROTOCOLS HTTP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 b/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 index c275f22b1a..8fc39dcc2e 100644 --- a/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 +++ b/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 @@ -35,13 +35,12 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LOCAL_IP, char **ip); Pass a pointer to a char pointer to receive the pointer to a null-terminated string holding the IP address of the local end of most recent connection done with this \fBcurl\fP handle. This string may be IPv6 when that is -enabled. Note that you get a pointer to a memory area that will be re-used at -next request so you need to copy the string if you want to keep the -information. +enabled. Note that you get a pointer to a memory area that is reused at next +request so you need to copy the string if you want to keep the information. -The \fBip\fP pointer will be NULL or pointing to private memory you MUST NOT -free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the -corresponding CURL handle. +The \fBip\fP pointer is NULL or points to private memory. You MUST NOT free - +it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. .SH PROTOCOLS All .SH EXAMPLE @@ -51,7 +50,7 @@ All curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - /* Perform the request, res will get the return code */ + /* Perform the transfer */ res = curl_easy_perform(curl); /* Check for errors */ if((res == CURLE_OK) && diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 index 35bab0d8be..79391ae858 100644 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 @@ -35,12 +35,12 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIMARY_IP, char **ip); Pass a pointer to a char pointer to receive the pointer to a null-terminated string holding the IP address of the most recent connection done with this \fBcurl\fP handle. This string may be IPv6 when that is enabled. Note that you -get a pointer to a memory area that will be re-used at next request so you -need to copy the string if you want to keep the information. +get a pointer to a memory area that is reused at next request so you need to +copy the string if you want to keep the information. -The \fBip\fP pointer will be NULL or pointing to private memory you MUST NOT -free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the -corresponding CURL handle. +The \fBip\fP pointer is NULL or points to private memory. You MUST NOT free - +it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. .SH PROTOCOLS All network based ones .SH EXAMPLE @@ -50,7 +50,7 @@ All network based ones curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - /* Perform the request, res will get the return code */ + /* Perform the transfer */ res = curl_easy_perform(curl); /* Check for errors */ if((res == CURLE_OK) && diff --git a/docs/libcurl/opts/CURLINFO_PROTOCOL.3 b/docs/libcurl/opts/CURLINFO_PROTOCOL.3 index c0b77ac405..9a3bdc74fa 100644 --- a/docs/libcurl/opts/CURLINFO_PROTOCOL.3 +++ b/docs/libcurl/opts/CURLINFO_PROTOCOL.3 @@ -37,7 +37,7 @@ This option is deprecated. We strongly recommend using possible protocols! Pass a pointer to a long to receive the version used in the last http -connection. The returned value will be exactly one of the CURLPROTO_* values: +connection. The returned value is set to one of the CURLPROTO_* values: .nf CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_FTP, CURLPROTO_FTPS, diff --git a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 index 30a2f85eae..fe322c9681 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 +++ b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 @@ -71,11 +71,10 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXY_ERROR, long *detail); .fi .SH DESCRIPTION Pass a pointer to a long to receive a detailed error code when the most recent -transfer returned a \fBCURLE_PROXY\fP error. That error code will match the +transfer returned a \fBCURLE_PROXY\fP error. That error code matches the \fBCURLproxycode\fP set. -The error code will be zero (\fBCURLPX_OK\fP) if no response code was -available. +The error code is zero (\fBCURLPX_OK\fP) if no response code was available. .SH PROTOCOLS All that can be done over SOCKS .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_REFERER.3 b/docs/libcurl/opts/CURLINFO_REFERER.3 index bdbfa4c93a..a0202caf0c 100644 --- a/docs/libcurl/opts/CURLINFO_REFERER.3 +++ b/docs/libcurl/opts/CURLINFO_REFERER.3 @@ -34,9 +34,9 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REFERER, char **hdrp); .SH DESCRIPTION Pass in a pointer to a char pointer and get the referrer header. -The \fBhdrp\fP pointer will be NULL or pointing to private memory you MUST NOT -free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the -corresponding CURL handle. +The \fBhdrp\fP pointer is NULL or points to private memory you MUST NOT free - +it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. .SH PROTOCOLS HTTP(S) .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 index e5ed11213f..f89df09cfa 100644 --- a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 +++ b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 @@ -32,12 +32,13 @@ CURLINFO_RESPONSE_CODE \- get the last response code CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RESPONSE_CODE, long *codep); .fi .SH DESCRIPTION -Pass a pointer to a long to receive the last received HTTP, FTP, SMTP or -LDAP (OpenLDAP only) response code. This option was previously known as -CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. -The stored value will be zero if no server response code has been received. -Note that a proxy's CONNECT response should -be read with \fICURLINFO_HTTP_CONNECTCODE(3)\fP and not this. +Pass a pointer to a long to receive the last received HTTP, FTP, SMTP or LDAP +(OpenLDAP only) response code. This option was previously known as +CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. The stored value is zero if +no server response code has been received. + +Note that a proxy's CONNECT response should be read with +\fICURLINFO_HTTP_CONNECTCODE(3)\fP and not this. .SH PROTOCOLS HTTP, FTP, SMTP and LDAP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 index e3c24be6e0..b2e66f04f0 100644 --- a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 +++ b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 @@ -38,7 +38,7 @@ HTTP server suggests the client should wait until the next request is issued. The information from the "Retry-After:" header. While the HTTP header might contain a fixed date string, the -\fICURLINFO_RETRY_AFTER(3)\fP will always return number of seconds to wait - +\fICURLINFO_RETRY_AFTER(3)\fP always returns the number of seconds to wait - or zero if there was no header or the header could not be parsed. .SH DEFAULT Returns zero delay if there was no header. diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 index 1c69d8879e..cbc6df64c9 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 +++ b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 @@ -33,8 +33,8 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_CLIENT_CSEQ, long *cseq); .fi .SH DESCRIPTION -Pass a pointer to a long to receive the next CSeq that will be used by the -application. +Pass a pointer to a long to receive the next CSeq that is expected to be used +by the application. .SH PROTOCOLS RTSP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 index bb7f45cb34..1c0bde12b4 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 +++ b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 @@ -33,8 +33,8 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_SERVER_CSEQ, long *cseq); .fi .SH DESCRIPTION -Pass a pointer to a long to receive the next CSeq that will be expected by the -application. +Pass a pointer to a long to receive the next CSeq that is expected to be used +by the application. Listening for server initiated requests is not implemented! diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 index 92cbb9ca9c..e14ab871db 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 +++ b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 @@ -38,9 +38,9 @@ most recent RTSP Session ID. Applications wishing to resume an RTSP session on another connection should retrieve this info before closing the active connection. -The \fBid\fP pointer will be NULL or pointing to private memory you MUST NOT -free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the -corresponding CURL handle. +The \fBid\fP pointer is NULL or points to private memory. You MUST NOT free - +it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding +CURL handle. .SH PROTOCOLS RTSP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_SCHEME.3 b/docs/libcurl/opts/CURLINFO_SCHEME.3 index 049b5ec6b0..f5b7f94a3f 100644 --- a/docs/libcurl/opts/CURLINFO_SCHEME.3 +++ b/docs/libcurl/opts/CURLINFO_SCHEME.3 @@ -36,8 +36,8 @@ Pass a pointer to a char pointer to receive the pointer to a null-terminated string holding the URL scheme used for the most recent connection done with this CURL \fBhandle\fP. -The \fBscheme\fP pointer will be NULL or pointing to private memory you MUST -NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the +The \fBscheme\fP pointer is NULL or points to private memory. You MUST NOT +free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding CURL handle. .SH PROTOCOLS All diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 index a18a89d125..12d2661a1a 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 @@ -33,10 +33,10 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_DOWNLOAD, double *dlp); .fi .SH DESCRIPTION Pass a pointer to a double to receive the total amount of bytes that were -downloaded. The amount is only for the latest transfer and will be reset -again for each new transfer. This counts actual payload data, what's also -commonly called body. All meta and header data are excluded and will not be -counted in this number. +downloaded. The amount is only for the latest transfer and gets reset again +for each new transfer. This counts actual payload data, what's also commonly +called body. All meta and header data is excluded and not included in this +number. \fICURLINFO_SIZE_DOWNLOAD_T(3)\fP is a newer replacement that returns a more sensible variable type. diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 index 63766a7be4..6df958edab 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 @@ -34,10 +34,9 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_DOWNLOAD_T, .fi .SH DESCRIPTION Pass a pointer to a \fIcurl_off_t\fP to receive the total amount of bytes that -were downloaded. The amount is only for the latest transfer and will be reset +were downloaded. The amount is only for the latest transfer and gets reset again for each new transfer. This counts actual payload data, what's also -commonly called body. All meta and header data are excluded and will not be -counted in this number. +commonly called body. All meta and header data is excluded from this amount. .SH PROTOCOLS All .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 index 29224c2602..aedc7a4a22 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 +++ b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 @@ -37,7 +37,7 @@ Pass the address of a 'struct curl_slist *' to receive a linked-list of OpenSSL crypto-engines supported. Note that engines are normally implemented in separate dynamic libraries. Hence not all the returned engines may be available at runtime. \fBNOTE:\fP you must call \fIcurl_slist_free_all(3)\fP -on the list pointer once you are done with it, as libcurl will not free the +on the list pointer once you are done with it, as libcurl does not free this data for you. .SH PROTOCOLS All TLS based ones. diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 index f058fa74c1..21e481302e 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 +++ b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 @@ -38,9 +38,9 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR, CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION, struct curl_tlssessioninfo **session); .SH DESCRIPTION -Pass a pointer to a \fIstruct curl_tlssessioninfo *\fP. The pointer will be -initialized to refer to a \fIstruct curl_tlssessioninfo *\fP that will contain -an enum indicating the SSL library used for the handshake and a pointer to the +Pass a pointer to a \fIstruct curl_tlssessioninfo *\fP. The pointer is +initialized to refer to a \fIstruct curl_tlssessioninfo *\fP that contains an +enum indicating the SSL library used for the handshake and a pointer to the respective internal TLS session structure of this underlying SSL library. This option may be useful for example to extract certificate information in a @@ -61,8 +61,8 @@ CURLSSLBACKEND_MBEDTLS, CURLSSLBACKEND_NSS, CURLSSLBACKEND_OPENSSL, CURLSSLBACKEND_SCHANNEL or CURLSSLBACKEND_MESALINK. (Note that the OpenSSL forks are all reported as just OpenSSL here.) -The \fIinternals\fP struct member will point to a TLS library specific pointer -for the active ("in use") SSL connection, with the following underlying types: +The \fIinternals\fP struct member points to a TLS library specific pointer for +the active ("in use") SSL connection, with the following underlying types: .RS .IP GnuTLS \fBgnutls_session_t\fP @@ -101,9 +101,9 @@ retrieve a second in-use SSL session associated with an easy handle. This option has not been thoroughly tested with clear text protocols that can be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with -\fICURLOPT_USE_SSL(3)\fP. Though you will be able to retrieve the SSL pointer, -it's possible that before you can do that data (including auth) may have -already been sent over a connection after it was upgraded. +\fICURLOPT_USE_SSL(3)\fP. Though you can to retrieve the SSL pointer, it's +possible that before you can do that, data (including auth) may have already +been sent over a connection after it was upgraded. Renegotiation. If unsafe renegotiation or renegotiation in a way that the certificate is allowed to change is allowed by your SSL library this may occur diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 index 7d3b957b6e..341b8cd48e 100644 --- a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 +++ b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 @@ -38,8 +38,8 @@ No function since pipelining was removed in 7.62.0. Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is currently processing a chunked (Transfer-encoding: chunked) request with a current chunk length larger than \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP, -that pipeline will not be considered for additional requests, even if it is -shorter than \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. +that pipeline is not considered for additional requests, even if it is shorter +than \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. .SH DEFAULT The default value is 0, which means that the penalization is inactive. .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 index a361f62e9a..194ae9aa37 100644 --- a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 +++ b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 @@ -37,8 +37,8 @@ No function since pipelining was removed in 7.62.0. Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is currently processing a request with a Content-Length larger than this -\fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP, that pipeline will then not be -considered for additional requests, even if it is shorter than +\fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP, that pipeline is not considered +for additional requests, even if it is shorter than \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. .SH DEFAULT The default value is 0, which means that the size penalization is inactive. diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 index ceba3538ee..dad2b4c779 100644 --- a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 +++ b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 @@ -32,10 +32,10 @@ CURLMOPT_MAXCONNECTS \- size of connection cache CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAXCONNECTS, long max); .fi .SH DESCRIPTION -Pass a long indicating the \fBmax\fP. The set number will be used as the -maximum amount of simultaneously open connections that libcurl may keep in its -connection cache after completed use. By default libcurl will enlarge the size -for each added easy handle to make it fit 4 times the number of added easy +Pass a long indicating the \fBmax\fP. The set number is used as the maximum +amount of simultaneously open connections that libcurl may keep in its +connection cache after completed use. By default libcurl enlarges the size for +each added easy handle to make it fit 4 times the number of added easy handles. By setting this option, you can prevent the cache size from growing beyond the diff --git a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 index ece39d5637..e149c21b17 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 +++ b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 @@ -33,9 +33,9 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_CONCURRENT_STREAMS, long max); .fi .SH DESCRIPTION -Pass a long indicating the \fBmax\fP. The set number will be used as the -maximum number of concurrent streams for a connections that libcurl should -support on connections done using HTTP/2. +Pass a long indicating the \fBmax\fP. The set number is used as the maximum +number of concurrent streams for a connections that libcurl should support on +connections done using HTTP/2. Valid values range from 1 to 2147483647 (2^31 - 1) and defaults to 100. The value passed here would be honored based on other system resources properties. diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 index 49095e19ba..16b30cd95e 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 +++ b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 @@ -33,28 +33,22 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS, long max); .fi .SH DESCRIPTION -Pass a long to indicate \fBmax\fP. The set number will be used as the maximum +Pass a long to indicate \fBmax\fP. The set number is used as the maximum amount of simultaneously open connections to a single host (a host being the same as a host name + port number pair). For each new session to a host, -libcurl will open a new connection up to the limit set by -\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. When the limit is reached, the -sessions will be pending until a connection becomes available. If -\fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to pipeline if the -host is capable of it. +libcurl might open a new connection up to the limit set by +\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. When the limit is reached, new +sessions are kept pending until a connection becomes available. -The default \fBmax\fP value is 0, unlimited. However, for backwards -compatibility, setting it to 0 when \fICURLMOPT_PIPELINING(3)\fP is 1 will not -be treated as unlimited. Instead it will open only 1 connection and try to -pipeline on it. - -This set limit is also used for proxy connections, and then the proxy is -considered to be the host for which this limit counts. +The default \fBmax\fP value is 0, unlimited. This set limit is also used for +proxy connections, and then the proxy is considered to be the host for which +this limit counts. When more transfers are added to the multi handle than what can be performed -due to the set limit, they will be queued up waiting for their chance. When -that happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout will be counted -inclusive of the waiting time, meaning that if you set a too narrow timeout in -such a case the transfer might never even start before it times out. +due to the set limit, they are queued up waiting for their chance. When that +happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is inclusive of the waiting +time, meaning that if you set a too narrow timeout in such a case the transfer +might never even start before it times out. Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP timeout is however treated as a per-connect timeout. diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 index b17dbe9b85..985ad060b5 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 +++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 @@ -35,11 +35,11 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_PIPELINE_LENGTH, .SH DESCRIPTION No function since pipelining was removed in 7.62.0. -Pass a long. The set \fBmax\fP number will be used as the maximum amount of +Pass a long. The set \fBmax\fP number is used as the maximum amount of outstanding requests in an HTTP/1.1 pipeline. This option is only used for HTTP/1.1 pipelining, not for HTTP/2 multiplexing. -When this limit is reached, libcurl will use another connection to the same +When this limit is reached, libcurl creates another connection to the same host (see \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP), or queue the request until one of the pipelines to the host is ready to accept a request. Thus, the total number of requests in-flight is \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP * diff --git a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 index 55ca1a2616..dc815060b2 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 +++ b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 @@ -33,19 +33,19 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_TOTAL_CONNECTIONS, long amount); .fi .SH DESCRIPTION -Pass a long for the \fBamount\fP. The set number will be used as the maximum -number of simultaneously open connections in total using this multi -handle. For each new session, libcurl will open a new connection up to the -limit set by \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. When the limit is -reached, the sessions will be pending until there are available -connections. If \fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to -use multiplexing if the host is capable of it. +Pass a long for the \fBamount\fP. The set number is used as the maximum number +of simultaneously open connections in total using this multi handle. For each +new session, libcurl might open a new connection up to the limit set by +\fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. When the limit is reached, new +sessions are held pending until there are available connections. If +\fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl can try multiplexing if the +host is capable of it. When more transfers are added to the multi handle than what can be performed -due to the set limit, they will be queued up waiting for their chance. When -that happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout will be counted -inclusive of the waiting time, meaning that if you set a too narrow timeout in -such a case the transfer might never even start before it times out. +due to the set limit, they get queued up waiting for their chance. When that +happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is counted inclusive of the +waiting time, meaning that if you set a too narrow timeout in such a case the +transfer might never even start before it times out. Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP timeout is however treated as a per-connect timeout. diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING.3 index fb0a76fdd2..9733f253ed 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING.3 +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING.3 @@ -32,40 +32,19 @@ CURLMOPT_PIPELINING \- enable HTTP pipelining and multiplexing CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, long bitmask); .fi .SH DESCRIPTION -Pass in the \fBbitmask\fP parameter to instruct libcurl to enable HTTP -pipelining and/or HTTP/2 multiplexing for this multi handle. +Pass in the correct value in the \fBbitmask\fP parameter to instruct libcurl +to enable multiplexing for this multi handle. -When enabled, libcurl will attempt to use those protocol features when doing -parallel requests to the same hosts. +With multiplexing enabled, libcurl attempts to do multiple transfers over the +same connection when doing parallel transfers to the same hosts. -For pipelining, this means that if you add a second request that can use an -already existing connection, the second request will be \&"piped" on the same -connection rather than being executed in parallel. - -For multiplexing, this means that follow-up requests can re-use an existing -connection and send the new request multiplexed over that at the same time as -other transfers are already using that single connection. - -There are several other related options that are interesting to tweak and -adjust to alter how libcurl spreads out requests on different connections or -not etc. - -Before 7.43.0, this option was set to 1 and 0 to enable and disable HTTP/1.1 -pipelining. - -Starting in 7.43.0, \fBbitmask\fP's second bit also has a meaning, and you can -ask for pipelining and multiplexing independently of each other by toggling -the correct bits. .IP CURLPIPE_NOTHING (0) -Default, which means doing no attempts at pipelining or multiplexing. +Default, which means doing no attempts at multiplexing. .IP CURLPIPE_HTTP1 (1) -If this bit is set, libcurl will try to pipeline HTTP/1.1 requests on -connections that are already established and in use to hosts. - This bit is deprecated and has no effect since version 7.62.0. .IP CURLPIPE_MULTIPLEX (2) -If this bit is set, libcurl will try to multiplex the new transfer over an -existing connection if possible. This requires HTTP/2. +If this bit is set, libcurl tries to multiplex the new transfer over an +existing connection if possible. This requires HTTP/2 or HTTP/3. .SH DEFAULT Since 7.62.0, \fBCURLPIPE_MULTIPLEX\fP is enabled by default. diff --git a/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 b/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 index f393f4a6b0..cc20c7c26c 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 +++ b/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 @@ -32,9 +32,9 @@ CURLMOPT_PUSHDATA \- pointer to pass to push callback CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHDATA, void *pointer); .fi .SH DESCRIPTION -Set \fIpointer\fP to pass as the last argument to the -\fICURLMOPT_PUSHFUNCTION(3)\fP callback. The pointer will not be touched or -used by libcurl itself, only passed on to the callback function. +Set a \fIpointer\fP to pass as the last argument to the +\fICURLMOPT_PUSHFUNCTION(3)\fP callback. The pointer is not touched or used by +libcurl itself, only passed on to the callback function. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 index 5bfe50027b..1a292ad813 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 +++ b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 @@ -41,7 +41,7 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION, .SH DESCRIPTION This callback gets called when a new HTTP/2 stream is being pushed by the server (using the PUSH_PROMISE frame). If no push callback is set, all offered -pushes will be denied automatically. +pushes are denied automatically. .SH CALLBACK DESCRIPTION The callback gets its arguments like this: @@ -57,19 +57,19 @@ be accessed \fIheaders\fP is a handle used to access push headers using the accessor functions described below. This only accesses and provides the PUSH_PROMISE -headers, the normal response headers will be provided in the header callback -as usual. +headers, the normal response headers are provided in the header callback as +usual. \fIclientp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP -If the callback returns CURL_PUSH_OK, the 'easy' handle will be added to the +If the callback returns CURL_PUSH_OK, the new easy handle is added to the multi handle, the callback must not do that by itself. The callback can access PUSH_PROMISE headers with two accessor functions. These functions can only be used from within this callback and they can only access the PUSH_PROMISE headers: \fIcurl_pushheader_byname(3)\fP and -\fIcurl_pushheader_bynum(3)\fP. The normal response headers will be passed to -the header callback for pushed streams just as for normal streams. +\fIcurl_pushheader_bynum(3)\fP. The normal response headers are passed to the +header callback for pushed streams just as for normal streams. The header fields can also be accessed with \fIcurl_easy_header(3)\fP, introduced in later libcurl versions. @@ -78,10 +78,10 @@ introduced in later libcurl versions. The application has accepted the stream and it can now start receiving data, the ownership of the CURL handle has been taken over by the application. .IP "CURL_PUSH_DENY (1)" -The callback denies the stream and no data for this will reach the -application, the easy handle will be destroyed by libcurl. +The callback denies the stream and no data reaches the application, the easy +handle is destroyed by libcurl. .IP "CURL_PUSH_ERROROUT (2)" -Returning this will reject the pushed stream and return an error back on the +Returning this code rejects the pushed stream and returns an error back on the parent stream making it get closed with an error. (Added in 7.72.0) .IP * All other return codes are reserved for future use. diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 index c2af856734..8239875746 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 +++ b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 @@ -34,8 +34,8 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETDATA, void *pointer); A data \fIpointer\fP to pass to the socket callback set with the \fICURLMOPT_SOCKETFUNCTION(3)\fP option. -This pointer will not be touched by libcurl but will only be passed in to the -socket callbacks's \fBclientp\fP argument. +This pointer is not touched by libcurl but is only passed in as the socket +callbacks's \fBclientp\fP argument. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 index 7e992c6f15..fd75e9f7a1 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 @@ -45,7 +45,7 @@ callback to inform the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the \fBsocket_callback\fP. The callback function gets status updates with changes since the previous time the callback was called. If the given callback pointer -is set to NULL, no callback will be called. +is set to NULL, no callback is called. libcurl then expects the application to monitor the sockets for the specific activities and tell libcurl again when something happens on one of them. Tell @@ -61,11 +61,11 @@ for a socket that is already monitored. The socket callback should return 0 on success, and -1 on error. If this callback returns error, \fBall\fP transfers currently in progress in this -multi handle will be aborted and fail. +multi handle are aborted and made to fail. \fBclientp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP. -\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or will be NULL. +\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or NULL. The \fBwhat\fP parameter informs the callback on the status of the given socket. It can hold one of these values: diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 index a1f9ec462e..7c5eef7c27 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 +++ b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 @@ -34,8 +34,8 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERDATA, void *pointer); A data \fBpointer\fP to pass to the timer callback set with the \fICURLMOPT_TIMERFUNCTION(3)\fP option. -This pointer will not be touched by libcurl but will only be passed in to the -timer callbacks's \fBclientp\fP argument. +This pointer is not touched by libcurl but is only be passed in to the timer +callbacks's \fBclientp\fP argument. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 index 1bccb91ac3..425743a369 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 +++ b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 @@ -49,14 +49,13 @@ fires, call either \fIcurl_multi_socket_action(3)\fP or A \fBtimeout_ms\fP value of -1 passed to this callback means you should delete the timer. All other values are valid expire times in number of milliseconds. -The \fBtimer_callback\fP will only be called when the timeout expire time is -changed. +The \fBtimer_callback\fP is called when the timeout expire time is changed. The \fBclientp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP. The timer callback should return 0 on success, and -1 on error. If this callback returns error, \fBall\fP transfers currently in progress in this -multi handle will be aborted and fail. +multi handle are aborted and made to fail. This callback can be used instead of, or in addition to, \fIcurl_multi_timeout(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 index a848348223..b453931a60 100644 --- a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 +++ b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 @@ -35,13 +35,13 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ABSTRACT_UNIX_SOCKET, .SH DESCRIPTION Enables the use of an abstract Unix domain socket instead of establishing a TCP connection to a host. The parameter should be a char * to a -null-terminated string holding the path of the socket. The path will be set to -\fIpath\fP prefixed by a NULL byte (this is the convention for abstract +null-terminated string holding the path of the socket. The path is set to +\fIpath\fP prefixed by a NULL byte. This is the convention for abstract sockets, however it should be stressed that the path passed to this function -should not contain a leading NULL). +should not contain a leading NULL byte. -On non-supporting platforms, the abstract address will be interpreted as an -empty string and fail gracefully, generating a runtime error. +On non-supporting platforms, the abstract address is interpreted as an empty +string and fails gracefully, generating a runtime error. This option shares the same semantics as \fICURLOPT_UNIX_SOCKET_PATH(3)\fP in which documentation more details can be found. Internally, these two options diff --git a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 index 8a2fd8da22..9ade4bddd5 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 +++ b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 @@ -58,8 +58,8 @@ makes libcurl not send an Accept-Encoding: header and not decompress received contents automatically. You can also opt to just include the Accept-Encoding: header in your request -with \fICURLOPT_HTTPHEADER(3)\fP but then there will be no automatic -decompressing when receiving data. +with \fICURLOPT_HTTPHEADER(3)\fP but then there is no automatic decompressing +when receiving data. This is a request, not an order; the server may or may not do it. This option must be set (to any non-NULL value) or else any unsolicited encoding done by diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 index 4bff498710..c77b4101a5 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 +++ b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 @@ -41,29 +41,27 @@ Populate the long \fIbitmask\fP with the correct set of features to instruct libcurl how to handle Alt-Svc for the transfers using this handle. libcurl only accepts Alt-Svc headers over a secure transport, meaning -HTTPS. It will also only complete a request to an alternative origin if that +HTTPS. It also only completes a request to an alternative origin if that origin is properly hosted over HTTPS. These requirements are there to make sure both the source and the destination are legitimate. Alternative services are only used when setting up new connections. If there -exists an existing connection to the host in the connection pool, then that -will be preferred. +exists an existing connection to the host in the connection pool, then that is +preferred. -Setting any bit will enable the alt-svc engine. +Setting any bit enables the alt-svc engine. .IP "CURLALTSVC_READONLYFILE" Do not write the alt-svc cache back to the file specified with \fICURLOPT_ALTSVC(3)\fP even if it gets updated. By default a file specified -with that option will be read and written to as deemed necessary. +with that option is read and written to as deemed necessary. .IP "CURLALTSVC_H1" Accept alternative services offered over HTTP/1.1. .IP "CURLALTSVC_H2" -Accept alternative services offered over HTTP/2. This will only be used if -libcurl was also built to actually support HTTP/2, otherwise this bit will be -ignored. +Accept alternative services offered over HTTP/2. This is only used if libcurl +was also built to actually support HTTP/2, otherwise this bit is ignored. .IP "CURLALTSVC_H3" -Accept alternative services offered over HTTP/3. This will only be used if -libcurl was also built to actually support HTTP/3, otherwise this bit will be -ignored. +Accept alternative services offered over HTTP/3. This is only used if libcurl +was also built to actually support HTTP/3, otherwise this bit is ignored. .SH DEFAULT Alt-Svc handling is disabled by default. If \fICURLOPT_ALTSVC(3)\fP is set, \fICURLOPT_ALTSVC_CTRL(3)\fP has a default value corresponding to diff --git a/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 b/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 index 2931a2dfea..14f1e07b37 100644 --- a/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 +++ b/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 @@ -32,9 +32,9 @@ CURLOPT_AUTOREFERER \- automatically update the referer header CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AUTOREFERER, long autorefer); .fi .SH DESCRIPTION -Pass a long parameter set to 1 to enable this. When enabled, libcurl will -automatically set the Referer: header field in HTTP requests to the full URL -where it follows a Location: redirect. +Pass a long parameter set to 1 to enable this. When enabled, libcurl +automatically sets the Referer: header field in HTTP requests to the full URL +when it follows a Location: redirect to a new destination. The automatic referer is set to the full previous URL even when redirects are done cross-origin or following redirects to insecure protocols. This is diff --git a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 index cb14231bc7..fbe4fe8eb7 100644 --- a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 +++ b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 @@ -52,13 +52,13 @@ NOTE: This call set \fICURLOPT_HTTPAUTH(3)\fP to CURLAUTH_AWS_SIGV4. Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same as calling this with \fB"aws:amz"\fP in parameter. .PP -Example with "Test:Try", when curl will do the algorithm, it will generate +Example with "Test:Try", when curl uses the algorithm, it generates \fB"TEST-HMAC-SHA256"\fP for "Algorithm", \fB"x-try-date"\fP and \fB"X-Try-Date"\fP for "date", \fB"test4_request"\fP for "request type", \fB"SignedHeaders=content-type;host;x-try-date"\fP for "signed headers" .PP -If you use just "test", instead of "test:try", -test will be use for every strings generated +If you use just "test", instead of "test:try", test is used for every +generated string. .SH DEFAULT By default, the value of this parameter is NULL. Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same diff --git a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 index b7697d2eb9..d2c9165a02 100644 --- a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 @@ -35,7 +35,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_BUFFERSIZE, long size); Pass a long specifying your preferred \fIsize\fP (in bytes) for the receive buffer in libcurl. The main point of this would be that the write callback gets called more often and with smaller chunks. Secondly, for some protocols, -there's a benefit of having a larger buffer for performance. +there is a benefit of having a larger buffer for performance. This is just treated as a request, not an order. You cannot be guaranteed to actually get the given size. diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.3 b/docs/libcurl/opts/CURLOPT_CAINFO.3 index daafaa5baf..c57994aa85 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO.3 +++ b/docs/libcurl/opts/CURLOPT_CAINFO.3 @@ -43,12 +43,12 @@ This option is by default set to the system path where libcurl's CA certificate bundle is assumed to be stored, as established at build time. (iOS and macOS) When curl uses Secure Transport this option is supported. If -the option is not set, then curl will use the certificates in the system and -user Keychain to verify the peer. +the option is not set, then curl uses the certificates in the system and user +Keychain to verify the peer. (Schannel) This option is supported for Schannel in Windows 7 or later but we recommend not using it until Windows 8 since it works better starting then. -If the option is not set, then curl will use the certificates in the Windows' +If the option is not set, then curl uses the certificates in the Windows' store of root certificates (the default for Schannel). The application does not have to keep the string around after setting this diff --git a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.3 index d786ec0749..d0246b5c74 100644 --- a/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.3 +++ b/docs/libcurl/opts/CURLOPT_CA_CACHE_TIMEOUT.3 @@ -35,7 +35,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CA_CACHE_TIMEOUT, long age); Pass a long, this sets the timeout in seconds. This tells libcurl the maximum time any cached certificate store it has in memory may be kept and reused for new connections. Once the timeout has expired, a subsequent fetch requiring a -certificate store will have to build a new one. +certificate has to reload it. Building a certificate store from a \fICURLOPT_CAINFO\fP file is a slow operation so curl may cache the generated certificate store internally to speed @@ -58,8 +58,8 @@ if(curl) { ret = curl_easy_perform(curl); - /* in this second request, the cache will not be used if more than - sixty seconds have passed since the previous connection */ + /* in this second request, the cache is not used if more than + sixty seconds passed since the previous connection */ ret = curl_easy_perform(curl); curl_easy_cleanup(curl); diff --git a/docs/libcurl/opts/CURLOPT_CERTINFO.3 b/docs/libcurl/opts/CURLOPT_CERTINFO.3 index 6efe4075fc..a55b754178 100644 --- a/docs/libcurl/opts/CURLOPT_CERTINFO.3 +++ b/docs/libcurl/opts/CURLOPT_CERTINFO.3 @@ -33,7 +33,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CERTINFO, long certinfo); .fi .SH DESCRIPTION Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With -this enabled, libcurl will extract lots of information and data about the +this enabled, libcurl extracts lots of information and data about the certificates in the certificate chain used in the SSL connection. This data may then be retrieved after a transfer using \fIcurl_easy_getinfo(3)\fP and its option \fICURLINFO_CERTINFO(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 index 6b914d566d..bd7cfb45b0 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 @@ -68,8 +68,8 @@ shown above. This callback function gets called by libcurl before a part of the stream is going to be transferred (if the transfer supports chunks). -The \fItransfer_info\fP pointer will point to a \fBcurl_fileinfo\fP struct -with details about the file that is about to get transferred. +The \fItransfer_info\fP pointer points to a \fBcurl_fileinfo\fP struct with +details about the file that is about to get transferred. This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH(3)\fP option for now. diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 index ccff3e2ff1..aa4eb1d271 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 +++ b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 @@ -32,7 +32,7 @@ CURLOPT_CHUNK_DATA \- pointer passed to the FTP chunk callbacks CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_DATA, void *pointer); .fi .SH DESCRIPTION -Pass a \fIpointer\fP that will be untouched by libcurl and passed as the ptr +Pass a \fIpointer\fP that is untouched by libcurl and passed as the ptr argument to the \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP and \fICURLOPT_CHUNK_END_FUNCTION(3)\fP. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 index 7fe14fcfc9..1a8b321db9 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 @@ -33,7 +33,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETDATA, void *pointer); .fi .SH DESCRIPTION -Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first +Pass a \fIpointer\fP that remains untouched by libcurl and passed as the first argument in the closesocket callback set with \fICURLOPT_CLOSESOCKETFUNCTION(3)\fP. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 index 5cc580aa6b..4a72310b22 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 @@ -41,7 +41,7 @@ switch to the default built-in connection timeout - 300 seconds. See also the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP is the same function but set in milliseconds. If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP -are set, the value set last will be used. +are set, the value set last is used. The "connection phase" is considered complete when the requested TCP, TLS or QUIC handshakes are done. diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 index 0366342de5..b138944354 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 +++ b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 @@ -42,12 +42,12 @@ useful when used with the \fICURLINFO_ACTIVESOCKET(3)\fP option to the application can obtain the most recently used socket for special data transfers. -Since 7.86.0, this option can be set to '2' and if HTTP or WebSocket are -used, libcurl will do the request and read all response headers before handing +Since 7.86.0, this option can be set to '2' and if HTTP or WebSocket are used, +libcurl performs the request and reads all response headers before handing over control to the application. -Transfers marked connect only will not reuse any existing connections and -connections marked connect only will not be allowed to get reused. +Transfers marked connect only do not reuse any existing connections and +connections marked connect only are not allowed to get reused. If the connect only transfer is done using the multi interface, the particular easy handle must remain added to the multi handle for as long as the diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 b/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 index 89be2ba9d2..6bab8e3892 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 +++ b/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 @@ -50,10 +50,10 @@ Dotted numerical IP addresses are supported for HOST and CONNECT-TO-HOST. A numerical IPv6 address must be written within [brackets]. Any of the four values may be empty. When the HOST or PORT is empty, the host -or port will always match (the request's host or port is ignored). -When CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to" feature -will be disabled for the host or port, and the request's host or port will be -used to establish the network connection. +or port always match (the request's host or port is ignored). When +CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to" feature is +disabled for the host or port, and the request's host or port are used to +establish the network connection. This option is suitable to direct the request at a specific server, e.g. at a specific cluster node in a cluster of servers. @@ -77,8 +77,8 @@ port, the HTTP proxy is automatically switched to tunnel mode for this specific request. This is necessary because it is not possible to connect to a specific host or port in normal (non-tunnel) mode. -When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl will not copy -the entire list so you \fBmust\fP keep it around until you no longer use this +When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy +the list so you \fBmust\fP keep it around until you no longer use this \fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on the list. diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 index 2d9fff1769..120c6d7aa0 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 @@ -37,7 +37,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_NETWORK_FUNCTION, Pass a pointer to your callback function, which should match the prototype shown above. -Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the +Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP returns the \fBCURL_VERSION_CONV\fP feature bit set if this option is provided. The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. @@ -52,24 +52,23 @@ network encoding. It is used when commands or ASCII data are received over the network. If you set a callback pointer to NULL, or do not set it at all, the built-in -libcurl iconv functions will be used. If HAVE_ICONV was not defined when -libcurl was built, and no callback has been established, conversion will -return the \fBCURLE_CONV_REQD\fP error code. +libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl +was built, and no callback has been established, the conversion returns the +\fBCURLE_CONV_REQD\fP error code. If \fBHAVE_ICONV\fP is defined, \fBCURL_ICONV_CODESET_OF_HOST\fP must also be defined. For example: \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" -The iconv code in libcurl will default the network and UTF8 codeset names as +The iconv code in libcurl defaults the network and UTF8 codeset names as follows: \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" -You will need to override these definitions if they are different on your -system. +You need to override these definitions if they are different on your system. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 index af1a8fe2bd..891ddd8bf8 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 @@ -37,7 +37,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_UTF8_FUNCTION, Pass a pointer to your callback function, which should match the prototype shown above. -Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the +Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP returns the CURL_VERSION_CONV feature bit set if this option is provided. The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. @@ -51,24 +51,23 @@ should be returned if an error was encountered. encoding. It is required only for SSL processing. If you set a callback pointer to NULL, or do not set it at all, the built-in -libcurl iconv functions will be used. If HAVE_ICONV was not defined when -libcurl was built, and no callback has been established, conversion will -return the CURLE_CONV_REQD error code. +libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl +was built, and no callback has been established, the conversion returns the +CURLE_CONV_REQD error code. If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. For example: \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" -The iconv code in libcurl will default the network and UTF8 codeset names as +The iconv code in libcurl defaults the network and UTF8 codeset names as follows: \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" -You will need to override these definitions if they are different on your -system. +You need to override these definitions if they are different on your system. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 index 4fd1243678..30d280d411 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 @@ -37,7 +37,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_TO_NETWORK_FUNCTION, Pass a pointer to your callback function, which should match the prototype shown above. -Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the +Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP returns the CURL_VERSION_CONV feature bit set if this option is provided. The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. @@ -52,24 +52,23 @@ network encoding. It is used when commands or ASCII data are sent over the network. If you set a callback pointer to NULL, or do not set it at all, the built-in -libcurl iconv functions will be used. If HAVE_ICONV was not defined when -libcurl was built, and no callback has been established, conversion will -return the CURLE_CONV_REQD error code. +libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl +was built, and no callback has been established, the conversion returns the +CURLE_CONV_REQD error code. If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. For example: \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" -The iconv code in libcurl will default the network and UTF8 codeset names as +The iconv code in libcurl defaults the network and UTF8 codeset names as follows: \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" -You will need to override these definitions if they are different on your -system. +You need to override these definitions if they are different on your system. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_COOKIE.3 b/docs/libcurl/opts/CURLOPT_COOKIE.3 index 2513de68f1..6a14c1e6fc 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIE.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIE.3 @@ -32,31 +32,31 @@ CURLOPT_COOKIE \- HTTP Cookie header CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIE, char *cookie); .fi .SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. It will be used to -set a cookie in the HTTP request. The format of the string should be +Pass a pointer to a null-terminated string as parameter. It is used to set one +or more cookies in the HTTP request. The format of the string should be NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie should contain. -If you need to set multiple cookies, set them all using a single option -concatenated like this: "name1=content1; name2=content2;" etc. +To set multiple cookies, set them all using a single option concatenated like +this: "name1=content1; name2=content2;" etc. This option sets the cookie header explicitly in the outgoing request(s). If multiple requests are done due to authentication, followed redirections or -similar, they will all get this cookie passed on. +similar, they all get this cookie passed on. The cookies set by this option are separate from the internal cookie storage -held by the cookie engine and will not be modified by it. If you enable the -cookie engine and either you have imported a cookie of the same name (e.g. 'foo') -or the server has set one, it will have no effect on the cookies you set here. -A request to the server will send both the 'foo' held by the cookie engine and -the 'foo' held by this option. To set a cookie that is instead held by the -cookie engine and can be modified by the server use +held by the cookie engine and they are not be modified by it. If you enable +the cookie engine and either you have imported a cookie of the same name +(e.g. 'foo') or the server has set one, it has no effect on the cookies you +set here. A request to the server sends both the 'foo' held by the cookie +engine and the 'foo' held by this option. To set a cookie that is instead held +by the cookie engine and can be modified by the server use \fICURLOPT_COOKIELIST(3)\fP. -Using this option multiple times will only make the latest string override the +Using this option multiple times makes the last set string override the previous ones. -This option will not enable the cookie engine. Use \fICURLOPT_COOKIEFILE(3)\fP +This option does not enable the cookie engine. Use \fICURLOPT_COOKIEFILE(3)\fP or \fICURLOPT_COOKIEJAR(3)\fP to enable parsing and sending cookies automatically. diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 index 898d8e100b..46ac57e9da 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 @@ -42,28 +42,29 @@ subsequent requests with this handle. By passing the empty string ("") to this option, you enable the cookie engine without reading any initial cookies. If you tell libcurl the file name is "-" -(just a single minus sign), libcurl will instead read from stdin. +(just a single minus sign), libcurl instead reads from stdin. This option only \fBreads\fP cookies. To make libcurl write cookies to file, see \fICURLOPT_COOKIEJAR(3)\fP. -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 sub-domains) or preferably: -use the Netscape format. +If you read cookies from a plain HTTP headers file and it does not specify a +domain in the Set-Cookie line, then the cookie is not sent since the cookie +domain cannot match the target URL's. To address this, set a domain in +Set-Cookie line (doing that includes sub-domains) or preferably: use the +Netscape format. -If you use this option multiple times, you just add more files to read. -Subsequent files will add more cookies. +If you use this option multiple times, you add more files to read cookies +from. The application does not have to keep the string around after setting this option. -Setting this option to NULL will (since 7.77.0) explicitly disable the cookie -engine and clear the list of files to read cookies from. +Setting this option to NULL (since 7.77.0) explicitly disables the cookie +engine and clears the list of files to read cookies from. .SH SECURITY This document previously mentioned how specifying a non-existing file can also enable the cookie engine. While true, we strongly advise against using that -method as it is too hard to be sure what files will stay that way in the long +method as it is too hard to be sure that files that stay that way in the long run. .SH DEFAULT NULL diff --git a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 index 2873573eb8..c0d21a1df7 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 @@ -32,24 +32,25 @@ CURLOPT_COOKIEJAR \- file name to store cookies to CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEJAR, char *filename); .fi .SH DESCRIPTION -Pass a \fIfilename\fP as char *, null-terminated. This will make libcurl write +Pass a \fIfilename\fP as a char *, null-terminated. This makes libcurl write all internally known cookies to the specified file when -\fIcurl_easy_cleanup(3)\fP is called. If no cookies are known, no file will be -created. Specify "-" as filename to instead have the cookies written to -stdout. Using this option also enables cookies for this session, so if you for -example follow a location it will make matching cookies get sent accordingly. +\fIcurl_easy_cleanup(3)\fP is called. If no cookies are kept in memory at that +time, no file is created. Specify "-" as filename to instead have the cookies +written to stdout. Using this option also enables cookies for this session, so +if you for example follow a redirect it makes matching cookies get sent +accordingly. -Note that libcurl does not read any cookies from the cookie jar. If you want to -read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP. +Note that libcurl does not read any cookies from the cookie jar specified with +this option. To read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP. If the cookie jar file cannot be created or written to (when the -\fIcurl_easy_cleanup(3)\fP is called), libcurl will not and cannot report an +\fIcurl_easy_cleanup(3)\fP is called), libcurl does not and cannot report an error for this. Using \fICURLOPT_VERBOSE(3)\fP or -\fICURLOPT_DEBUGFUNCTION(3)\fP will get a warning to display, but that is the -only visible feedback you get about this possibly lethal situation. +\fICURLOPT_DEBUGFUNCTION(3)\fP displays a warning, but that is the only +visible feedback you get about this possibly lethal situation. -Since 7.43.0 cookies that were imported in the Set-Cookie format without a -domain name are not exported by this option. +Cookies are imported in the Set-Cookie format without a domain name are not +exported by this option. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 b/docs/libcurl/opts/CURLOPT_COOKIELIST.3 index 849f62ef8a..00ebbb66f5 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.3 @@ -35,17 +35,20 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST, Pass a char * to a \fIcookie\fP string. Such a cookie can be either a single line in Netscape / Mozilla format or just -regular HTTP-style header (Set-Cookie: ...) format. This will also enable the -cookie engine. This adds that single cookie to the internal cookie store. +regular HTTP-style header (Set-Cookie: ...) format. This option also enables +the cookie engine. This adds that single cookie to the internal cookie store. -Exercise caution if you are using this option and multiple transfers may occur. -If you use the Set-Cookie format and do not specify a domain then the cookie is -sent for any domain (even after redirects are followed) and cannot be modified -by a server-set cookie. If a server sets a cookie of the same name (or maybe -you have imported one) then both will be sent on a future transfer to that -server, likely not what you intended. To address these issues set a domain in -Set-Cookie (doing that will include sub-domains) or use the Netscape format as -shown in EXAMPLE. +We strongly advice against loading cookies from a HTTP header file, as that is +an inferior data exchange format. + +Exercise caution if you are using this option and multiple transfers may +occur. If you use the Set-Cookie format and the string does not specify a +domain, then the cookie is sent for any domain (even after redirects are +followed) and cannot be modified by a server-set cookie. If a server sets a +cookie of the same name (or maybe you have imported one) then both are sent on +future transfers to that server, likely not what you intended. To address +these issues set a domain in Set-Cookie (doing that includes sub-domains) or +much better: use the Netscape file format. Additionally, there are commands available that perform actions if you pass in these exact strings: @@ -67,11 +70,7 @@ NULL HTTP .SH EXAMPLE .nf -/* This example shows an inline import of a cookie in Netscape format. -You can set the cookie as HttpOnly to prevent XSS attacks by prepending -#HttpOnly_ to the hostname. That may be useful if the cookie will later -be imported by a browser. -*/ +/* an inline import of a cookie in Netscape format. */ #define SEP "\\t" /* Tab separates the fields */ @@ -84,21 +83,20 @@ char *my_cookie = SEP "foo" /* Name */ SEP "bar"; /* Value */ -/* my_cookie is imported immediately via CURLOPT_COOKIELIST. -*/ +/* my_cookie is imported immediately via CURLOPT_COOKIELIST. */ curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie); -/* The list of cookies in cookies.txt will not be imported until right -before a transfer is performed. Cookies in the list that have the same -hostname, path and name as in my_cookie are skipped. That is because -libcurl has already imported my_cookie and it's considered a "live" -cookie. A live cookie will not be replaced by one read from a file. +/* The list of cookies in cookies.txt are not be imported until right + before a transfer is performed. Cookies in the list that have the same + hostname, path and name as in my_cookie are skipped. That is because + libcurl has already imported my_cookie and it's considered a "live" + cookie. A live cookie is not replaced by one read from a file. */ curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt"); /* import */ /* Cookies are exported after curl_easy_cleanup is called. The server -may have added, deleted or modified cookies by then. The cookies that -were skipped on import are not exported. + may have added, deleted or modified cookies by then. The cookies that + were skipped on import are not exported. */ curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt"); /* export */ diff --git a/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 b/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 index 63f92bb0a4..90019acba1 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 @@ -32,15 +32,16 @@ CURLOPT_COOKIESESSION \- start a new cookie session CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIESESSION, long init); .fi .SH DESCRIPTION -Pass a long set to 1 to mark this as a new cookie "session". It will force -libcurl to ignore all cookies it is about to load that are "session cookies" -from the previous session. By default, libcurl always stores and loads all -cookies, independent if they are session cookies or not. Session cookies are -cookies without expiry date and they are meant to be alive and existing for -this "session" only. +Pass a long set to 1 to mark this as a new cookie "session". It forces libcurl +to ignore all cookies it is about to load that are "session cookies" from the +previous session. By default, libcurl always loads all cookies, independent if +they are session cookies or not. Session cookies are cookies without expiry +date and they are meant to be alive and existing for this "session" only. A "session" is usually defined in browser land for as long as you have your -browser up, more or less. +browser up, more or less. libcurl needs the application to use this option to +tell it when a new session starts, otherwise it assumes everything is still in +the same session. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_CRLFILE.3 b/docs/libcurl/opts/CURLOPT_CRLFILE.3 index 4487c48b9e..ac215cb3fa 100644 --- a/docs/libcurl/opts/CURLOPT_CRLFILE.3 +++ b/docs/libcurl/opts/CURLOPT_CRLFILE.3 @@ -42,7 +42,7 @@ passed to help in the verification process. When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the elements of the certificate chain if a CRL file is passed. Also note that -\fICURLOPT_CRLFILE(3)\fP will imply \fBCURLSSLOPT_NO_PARTIALCHAIN\fP (see +\fICURLOPT_CRLFILE(3)\fP implies \fBCURLSSLOPT_NO_PARTIALCHAIN\fP (see \fICURLOPT_SSL_OPTIONS(3)\fP) since curl 7.71.0 due to an OpenSSL bug. This option makes sense only when used in combination with the diff --git a/docs/libcurl/opts/CURLOPT_CURLU.3 b/docs/libcurl/opts/CURLOPT_CURLU.3 index 670b136620..0e4d9acb69 100644 --- a/docs/libcurl/opts/CURLOPT_CURLU.3 +++ b/docs/libcurl/opts/CURLOPT_CURLU.3 @@ -29,20 +29,20 @@ CURLOPT_CURLU \- URL in URL handle format .nf #include -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CURLU, void *pointer); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CURLU, CURLU *pointer); .fi .SH DESCRIPTION -Pass in a pointer to the \fIURL\fP to work with. The parameter should be a -\fICURLU *\fP. Setting \fICURLOPT_CURLU(3)\fP will explicitly override +Pass in a pointer to the \fIURL\fP handle to work with. The parameter should +be a \fICURLU *\fP. Setting \fICURLOPT_CURLU(3)\fP explicitly overrides \fICURLOPT_URL(3)\fP. \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a transfer is started. -libcurl will use this handle and its contents read-only and will not change -its contents. An application can update the contents of the URL handle after a -transfer is done and if the same handle is then used in a subsequent request -the updated contents will then be used. +libcurl uses this handle and its contents read-only and does not change its +contents. An application can update the contents of the URL handle after a +transfer is done and if the same handle is used in a subsequent request the +updated contents is used. .SH DEFAULT The default value of this parameter is NULL. .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 index 21cf7760b7..06cd5fed01 100644 --- a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 +++ b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 @@ -29,15 +29,15 @@ CURLOPT_CUSTOMREQUEST \- custom request method .nf #include -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *request); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *method); .fi .SH DESCRIPTION Pass a pointer to a null-terminated string as parameter. -When you change the request method by setting \fICURLOPT_CUSTOMREQUEST(3)\fP -to something, you do not actually change how libcurl behaves or acts in regards -to the particular request method, it will only change the actual string sent -in the request. +When you change the request \fImethod\fP by setting +\fICURLOPT_CUSTOMREQUEST(3)\fP to something, you do not actually change how +libcurl behaves or acts in regards to the particular request method, it only +changes the actual string sent in the request. Restore to the internal default by setting this to NULL. @@ -49,14 +49,14 @@ particularly useful, for example, for performing an HTTP DELETE request. For example: When you tell libcurl to do a HEAD request, but then specify a GET though a -custom request libcurl will still act as if it sent a HEAD. To switch to a -proper HEAD use \fICURLOPT_NOBODY(3)\fP, to switch to a proper POST use +custom request libcurl still acts as if it sent a HEAD. To switch to a proper +HEAD use \fICURLOPT_NOBODY(3)\fP, to switch to a proper POST use \fICURLOPT_POST(3)\fP or \fICURLOPT_POSTFIELDS(3)\fP and to switch to a proper GET use \fICURLOPT_HTTPGET(3)\fP. Many people have wrongly used this option to replace the entire request with their own, including multiple headers and POST contents. While that might work -in many cases, it will cause libcurl to send invalid requests and it could +in many cases, it might cause libcurl to send invalid requests and it could possibly confuse the remote server badly. Use \fICURLOPT_POST(3)\fP and \fICURLOPT_POSTFIELDS(3)\fP to set POST data. Use \fICURLOPT_HTTPHEADER(3)\fP to replace or extend the set of headers sent by libcurl. Use @@ -71,9 +71,9 @@ Instead of LIST and RETR when issuing POP3 based requests. For example: -When you tell libcurl to use a custom request it will behave like a LIST or -RETR command was sent where it expects data to be returned by the server. As -such \fICURLOPT_NOBODY(3)\fP should be used when specifying commands such as +When you tell libcurl to use a custom request it behaves like a LIST or RETR +command was sent where it expects data to be returned by the server. As such +\fICURLOPT_NOBODY(3)\fP should be used when specifying commands such as \fBDELE\fP and \fBNOOP\fP for example. .IP SMTP Instead of a \fBHELP\fP or \fBVRFY\fP when issuing SMTP based requests. diff --git a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 index 98eb378f33..ed26f1497f 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 @@ -55,8 +55,8 @@ shown above. \fICURLOPT_DEBUGFUNCTION(3)\fP replaces the standard debug function used when \fICURLOPT_VERBOSE(3)\fP is in effect. This callback receives debug information, as specified in the \fItype\fP argument. This function must -return 0. The \fIdata\fP pointed to by the char * passed to this function WILL -NOT be null-terminated, but will be exactly of the \fIsize\fP as told by the +return 0. The \fIdata\fP pointed to by the char * passed to this function is +not null-terminated, but is exactly of the \fIsize\fP as told by the \fIsize\fP argument. The \fIclientp\fP argument is the pointer set with \fICURLOPT_DEBUGDATA(3)\fP. @@ -70,9 +70,9 @@ The data is header (or header-like) data received from the peer. The data is header (or header-like) data sent to the peer. .IP CURLINFO_DATA_IN The data is the unprocessed protocol data received from the peer. Even if the -data is encoded or compressed, it will not be provided decoded nor -decompressed to this callback. If you need the data in decoded and -decompressed form, use \fICURLOPT_WRITEFUNCTION(3)\fP. +data is encoded or compressed, it is not not provided decoded nor decompressed +to this callback. If you need the data in decoded and decompressed form, use +\fICURLOPT_WRITEFUNCTION(3)\fP. .IP CURLINFO_DATA_OUT The data is protocol data sent to the peer. .IP CURLINFO_SSL_DATA_OUT diff --git a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 index 303f37156e..f4f9793d97 100644 --- a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 +++ b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 @@ -45,7 +45,7 @@ pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp An unknown or unsupported protocol causes error \fICURLE_UNSUPPORTED_PROTOCOL\fP when libcurl parses a URL without a scheme. Parsing happens when \fIcurl_easy_perform(3)\fP or -\fIcurl_multi_perform(3)\fP is called. The protocols supported by libcurl will +\fIcurl_multi_perform(3)\fP is called. The protocol set supported by libcurl vary depending on how it was built. Use \fIcurl_version_info(3)\fP if you need a list of protocol names supported by the build of libcurl that you are using. diff --git a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 index 57c4cb5685..15fe79f1a9 100644 --- a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 +++ b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 @@ -48,8 +48,8 @@ include subdirectories and symbolic links. Setting this option to 1 also implies a directory listing even if the URL does not end with a slash, which otherwise is necessary. -Do NOT use this option if you also use \fICURLOPT_WILDCARDMATCH(3)\fP as it -will effectively break that feature then. +Do not use this option if you also use \fICURLOPT_WILDCARDMATCH(3)\fP as it +effectively breaks that feature. .SH DEFAULT 0, disabled .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 index c7c9e69a5a..fcccd2e365 100644 --- a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 +++ b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 @@ -35,6 +35,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DISALLOW_USERNAME_IN_URL, .SH DESCRIPTION A long parameter set to 1 tells the library to not allow URLs that include a username. + +This is the equivalent to the \fICURLU_DISALLOW_USER\fP flag for the +\fIcurl_url_set(3)\fP function. .SH DEFAULT 0 (disabled) - user names are allowed by default. .SH PROTOCOLS @@ -55,7 +58,8 @@ Added in 7.61.0 .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. -curl_easy_perform() will return CURLE_LOGIN_DENIED if this option is enabled -and a URL containing a username is specified. +curl_easy_perform() returns CURLE_LOGIN_DENIED if this option is enabled and a +URL containing a username is specified. .SH "SEE ALSO" -.BR libcurl-security "(3), ", CURLOPT_PROTOCOLS "(3)" +.BR libcurl-security "(3), ", CURLOPT_PROTOCOLS "(3), " +.BR curl_url_set "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 index 1c60f5b26c..7027ab5403 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 @@ -32,10 +32,10 @@ CURLOPT_DNS_CACHE_TIMEOUT \- life-time for DNS cache entries CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age); .fi .SH DESCRIPTION -Pass a long, this sets the timeout in seconds. Name resolves will be kept in -memory and used for this number of seconds. Set to zero to completely disable -caching, or set to -1 to make the cached entries remain forever. By default, -libcurl caches this info for 60 seconds. +Pass a long, this sets the timeout in seconds. Name resolve results are kept +in memory and used for this number of seconds. Set to zero to completely +disable caching, or set to -1 to make the cached entries remain forever. By +default, libcurl caches this info for 60 seconds. We recommend users not to tamper with this option unless strictly necessary. If you do, be careful of using large values that can make the cache size grow @@ -49,8 +49,8 @@ if DHCP has updated the server info, and this may look like a DNS cache issue to the casual libcurl-app user. DNS entries have a "TTL" property but libcurl does not use that. This DNS -cache timeout is entirely speculative that a name will resolve to the same -address for a certain small amount of time into the future. +cache timeout is entirely speculative that a name resolves to the same address +for a small amount of time into the future. Since version 8.1.0, libcurl prunes entries from the DNS cache if it exceeds 30,000 entries no matter which timeout value is used. @@ -69,7 +69,7 @@ if(curl) { ret = curl_easy_perform(curl); - /* in this second request, the cache will not be used if more than + /* in this second request, the cache is not be used if more than two seconds have passed since the previous name resolve */ ret = curl_easy_perform(curl); diff --git a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 index 0c52ea0432..910fe75afd 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 @@ -32,18 +32,20 @@ CURLOPT_DNS_SHUFFLE_ADDRESSES \- shuffle IP addresses for hostname CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SHUFFLE_ADDRESSES, long onoff); .fi .SH DESCRIPTION -When a name is resolved and more than one IP address is returned, shuffle the -order of all returned addresses so that they will be used in a random order. -This is similar to the ordering behavior of gethostbyname which is no longer -used on most platforms. +Pass a long set to 1 to enable this option. -Addresses will not be reshuffled if a name resolution is completed using the -DNS cache. \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP can be used together with this +When a name is resolved and more than one IP address is returned, this +function shuffles the order of all returned addresses so that they are used in +a random order. This is similar to the ordering behavior of the legacy +gethostbyname function which is no longer used on most platforms. + +Addresses are not reshuffled if name resolution is completed using the DNS +cache. \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP can be used together with this option to reduce DNS cache timeout or disable caching entirely if frequent reshuffling is needed. -Since the addresses returned will be reordered randomly, their order will not -be in accordance with RFC 3484 or any other deterministic order that may be +Since the addresses returned are randomly reordered, the order is not in +accordance with RFC 3484 or any other deterministic order that may be generated by the system's name resolution implementation. This may have performance impacts and may cause IPv4 to be used before IPv6 or vice versa. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 index 790ceec02f..8754e63123 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 @@ -36,12 +36,11 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_USE_GLOBAL_CACHE, Has no function since 7.62.0. Do not use! Pass a long. If the \fIenable\fP value is 1, it tells curl to use a global DNS -cache that will survive between easy handle creations and deletions. This is -not thread-safe and this will use a global variable. +cache that survives between easy handle creations and deletions. This is not +thread-safe and this uses a global variable. -\fBWARNING:\fP this option is considered obsolete. Stop using it. Switch over -to using the share interface instead! See \fICURLOPT_SHARE(3)\fP and -\fIcurl_share_init(3)\fP. +See \fICURLOPT_SHARE(3)\fP and \fIcurl_share_init(3)\fP for the correct way to +share DNS cache between transfers. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 index 97d11a9ded..8d92b1eba6 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 @@ -42,8 +42,8 @@ extension (aka. OCSP stapling). This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYSTATUS(3)\fP and only affects requests to the DoH server. -Note that if this option is enabled but the server does not support the TLS -extension, the verification will fail. +If this option is enabled and the server does not support the TLS extension, +the verification fails. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_DOH_URL.3 b/docs/libcurl/opts/CURLOPT_DOH_URL.3 index 2f08155e5b..7042e17439 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_URL.3 +++ b/docs/libcurl/opts/CURLOPT_DOH_URL.3 @@ -37,15 +37,15 @@ resolving. The parameter should be a char * to a null-terminated string which must be URL-encoded in the following format: "https://host:port/path". It MUST specify an HTTPS URL. -libcurl does not validate the syntax or use this variable until the transfer is -issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will -still return \fICURLE_OK\fP. +libcurl does not validate the syntax or use this variable until the transfer +is issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP still +returns \fICURLE_OK\fP. curl sends POST requests to the given DNS-over-HTTPS URL. To find the DoH server itself, which might be specified using a name, libcurl -will use the default name lookup function. You can bootstrap that by providing -the address for the DoH server with \fICURLOPT_RESOLVE(3)\fP. +uses the default name lookup function. You can bootstrap that by providing the +address for the DoH server with \fICURLOPT_RESOLVE(3)\fP. Disable DoH use again by setting this option to NULL. .SH "INHERIT OPTIONS" @@ -64,7 +64,7 @@ mechanism. This includes name resolves done for \fICURLOPT_INTERFACE(3)\fP, \fICURLOPT_FTPPORT(3)\fP, a proxy type set to \fBCURLPROXY_SOCKS4\fP or \fBCURLPROXY_SOCKS5\fP and probably some more. .SH DEFAULT -NULL - there is no default DoH URL. If this option is not set, libcurl will use +NULL - there is no default DoH URL. If this option is not set, libcurl uses the default name resolver. .SH PROTOCOLS All @@ -83,8 +83,8 @@ Added in 7.62.0 Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -Note that \fIcurl_easy_setopt(3)\fP will not immediately parse the given -string so when given a bad DoH URL, libcurl might not detect the problem until -it later tries to resolve a name with it. +Note that \fIcurl_easy_setopt(3)\fP does immediately parse the given string so +when given a bad DoH URL, libcurl might not detect the problem until it later +tries to resolve a name with it. .SH "SEE ALSO" .BR CURLOPT_VERBOSE "(3), " CURLOPT_RESOLVE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 b/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 index 7a2e75f727..ba953d4cc9 100644 --- a/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 +++ b/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 @@ -35,7 +35,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EGDSOCKET, char *path); Deprecated option. It serves no purpose anymore. Pass a char * to the null-terminated path name to the Entropy Gathering Daemon -socket. It will be used to seed the random engine for TLS. +socket. It is used to seed the random engine for TLS. The application does not have to keep the string around after setting this option. @@ -54,8 +54,8 @@ if(curl) { } .fi .SH AVAILABILITY -If built with TLS enabled. Only the OpenSSL backend will use this, and only -with OpenSSL versions before 1.1.0. +If built with TLS enabled. Only the OpenSSL backend uses this, and only with +OpenSSL versions before 1.1.0. This option was deprecated in 7.84.0. .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 index 83beeb539c..5953d5e651 100644 --- a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 +++ b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 @@ -32,20 +32,20 @@ CURLOPT_ERRORBUFFER \- error buffer for error messages CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ERRORBUFFER, char *buf); .fi .SH DESCRIPTION -Pass a char * to a buffer that libcurl \fBmay\fP store human readable error +Pass a char * to a buffer that libcurl may use to store human readable error messages on failures or problems. This may be more helpful than just the return code from \fIcurl_easy_perform(3)\fP and related functions. The buffer -\fBmust be at least CURL_ERROR_SIZE bytes big\fP. +must be at least \fBCURL_ERROR_SIZE\fP bytes big. You must keep the associated buffer available until libcurl no longer needs -it. Failing to do so will cause odd behavior or even crashes. libcurl will +it. Failing to do so might cause odd behavior or even crashes. libcurl might need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same option again to use a different pointer. Do not rely on the contents of the buffer unless an error code was returned. -Since 7.60.0 libcurl will initialize the contents of the error buffer to an -empty string before performing the transfer. For earlier versions if an error -code was returned but there was no error detail then the buffer is untouched. +Since 7.60.0 libcurl initializes the contents of the error buffer to an empty +string before performing the transfer. For earlier versions if an error code +was returned but there was no error detail then the buffer was untouched. Consider \fICURLOPT_VERBOSE(3)\fP and \fICURLOPT_DEBUGFUNCTION(3)\fP to better debug and trace why errors happen. diff --git a/docs/libcurl/opts/CURLOPT_FAILONERROR.3 b/docs/libcurl/opts/CURLOPT_FAILONERROR.3 index 966f3019a8..e4d16d79ac 100644 --- a/docs/libcurl/opts/CURLOPT_FAILONERROR.3 +++ b/docs/libcurl/opts/CURLOPT_FAILONERROR.3 @@ -37,15 +37,15 @@ code returned is equal to or larger than 400. The default action would be to return the page normally, ignoring that code. 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). You might get some amounts of headers transferred before this situation is detected, like when a "100-continue" is received as a response to a POST/PUT and a 401 or 407 is received immediately afterwards. -When this option is used and an error is detected, it will cause the -connection to get closed and \fICURLE_HTTP_RETURNED_ERROR\fP is returned. +When this option is used and an error is detected, it causes the connection to +get closed and \fICURLE_HTTP_RETURNED_ERROR\fP is returned. .SH DEFAULT 0, do not fail on error .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_FILETIME.3 b/docs/libcurl/opts/CURLOPT_FILETIME.3 index 12cad8cb07..9f9a0f44b1 100644 --- a/docs/libcurl/opts/CURLOPT_FILETIME.3 +++ b/docs/libcurl/opts/CURLOPT_FILETIME.3 @@ -32,11 +32,11 @@ CURLOPT_FILETIME \- get the modification time of the remote resource CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FILETIME, long gettime); .fi .SH DESCRIPTION -Pass a long. If it is 1, libcurl will attempt to get the modification time of -the remote document in this operation. This requires that the remote server -sends the time or replies to a time querying command. The -\fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME(3)\fP -argument can be used after a transfer to extract the received time (if any). +Pass a long. If it is 1, libcurl attempts to get the modification time of the +remote document in this operation. This requires that the remote server sends +the time or replies to a time querying command. The \fIcurl_easy_getinfo(3)\fP +function with the \fICURLINFO_FILETIME(3)\fP argument can be used after a +transfer to extract the received time (if any). .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 index ed61faffa7..a25332b39e 100644 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 @@ -32,8 +32,8 @@ CURLOPT_FNMATCH_DATA \- pointer passed to the fnmatch callback CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_DATA, void *pointer); .SH DESCRIPTION -Pass a pointer that will be untouched by libcurl and passed as the ptr -argument to the \fICURLOPT_FNMATCH_FUNCTION(3)\fP. +Pass a pointer that is untouched by libcurl and passed as the ptr argument to +the \fICURLOPT_FNMATCH_FUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 index 5be8c54bda..f7374b9df6 100644 --- a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 +++ b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 @@ -33,32 +33,35 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable); .fi .SH DESCRIPTION A long parameter set to 1 tells the library to follow any Location: header -that the server sends as part of an HTTP header in a 3xx response. The -Location: header can specify a relative or an absolute URL to follow. +redirects that a HTTP server sends in a 30x response. The Location: header can +specify a relative or an absolute URL to follow. -libcurl will issue another request for the new URL and follow new Location: -headers all the way until no more such headers are returned. -\fICURLOPT_MAXREDIRS(3)\fP can be used to limit the number of redirects -libcurl will follow. +libcurl issues another request for the new URL and follows subsequent new +Location: redirects all the way until no more such headers are returned or the +maximum limit is reached. \fICURLOPT_MAXREDIRS(3)\fP is used to limit the +number of redirects libcurl follows. -libcurl limits what protocols it automatically follows to. The accepted -protocols are set with \fICURLOPT_REDIR_PROTOCOLS(3)\fP. By default libcurl -will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). Older versions of -libcurl allowed all protocols on redirect except those disabled for security -reasons: Since 7.19.4 FILE and SCP are disabled, and since 7.40.0 SMB and SMBS -are also disabled. +libcurl restricts what protocols it automatically follow redirects to. The +accepted target protocols are set with \fICURLOPT_REDIR_PROTOCOLS(3)\fP. By +default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects. -When following a Location:, the 3xx response code that redirected it also -dictates which request method it will use in the subsequent request: For 301, -302 and 303 responses libcurl will switch method from POST to GET unless -\fICURLOPT_POSTREDIR(3)\fP instructs libcurl otherwise. All other 3xx codes -will make libcurl send the same method again. +When following a redirect, the specific 30x response code also dictates which +request method libcurl uses in the subsequent request: For 301, 302 and 303 +responses libcurl switches method from POST to GET unless +\fICURLOPT_POSTREDIR(3)\fP instructs libcurl otherwise. All other redirect +response codes make libcurl use the same method again. For users who think the existing location following is too naive, too simple or just lacks features, it is easy to instead implement your own redirect follow logic with the use of \fIcurl_easy_getinfo(3)\fP's \fICURLINFO_REDIRECT_URL(3)\fP option instead of using \fICURLOPT_FOLLOWLOCATION(3)\fP. +.SH NOTE +Since libcurl changes method or not based on the specific HTTP response code, +setting \fICURLOPT_CUSTOMREQUEST(3)\fP while following redirects may change +what libcurl would otherwise do and if not that carefully may even make it +misbehave since \fICURLOPT_CUSTOMREQUEST(3)\fP overrides the method libcurl +would otherwise select internally. .SH DEFAULT 0, disabled .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 index 684fd71563..4231051467 100644 --- a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 +++ b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 @@ -35,10 +35,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FORBID_REUSE, long close); Pass a long. Set \fIclose\fP to 1 to make libcurl explicitly close the connection when done with the transfer. Normally, libcurl keeps all connections alive when done with one transfer in case a succeeding one follows -that can re-use them. This option should be used with caution and only if you +that can reuse them. This option should be used with caution and only if you understand what it does as it can seriously impact performance. -Set to 0 to have libcurl keep the connection open for possible later re-use +Set to 0 to have libcurl keep the connection open for possible later reuse (default behavior). .SH DEFAULT 0 diff --git a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 index 804ccf272a..bc385c993c 100644 --- a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 +++ b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 @@ -33,14 +33,14 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FRESH_CONNECT, long fresh); .fi .SH DESCRIPTION Pass a long. Set to 1 to make the next transfer use a new (fresh) connection -by force instead of trying to re-use an existing one. This option should be -used with caution and only if you understand what it does as it may seriously -impact performance. +by force instead of trying to reuse an existing one. This option should be +used with caution and only if you understand what it does as it may impact +performance negatively. Related functionality is \fICURLOPT_FORBID_REUSE(3)\fP which makes sure the -connection is closed after use so that it will not be re-used. +connection is closed after use so that it cannot be reused. -Set \fIfresh\fP to 0 to have libcurl attempt re-using an existing connection +Set \fIfresh\fP to 0 to have libcurl attempt reusing an existing connection (default behavior). .SH DEFAULT 0 diff --git a/docs/libcurl/opts/CURLOPT_FTPPORT.3 b/docs/libcurl/opts/CURLOPT_FTPPORT.3 index fc1272b553..7775eb486d 100644 --- a/docs/libcurl/opts/CURLOPT_FTPPORT.3 +++ b/docs/libcurl/opts/CURLOPT_FTPPORT.3 @@ -33,19 +33,19 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPPORT, char *spec); .fi .SH DESCRIPTION Pass a pointer to a null-terminated string as parameter. It specifies that the -FTP transfer will be made actively and the given string will be used to get -the IP address to use for the FTP PORT instruction. +FTP transfer should be made actively and the given string is used to get the +IP address to use for the FTP PORT instruction. -The PORT instruction tells the remote server to connect to our specified IP -address. The string may be a plain IP address, a host name, a network -interface name (under Unix) or just a '-' symbol to let the library use your -system's default IP address. Default FTP operations are passive, and thus -will not use PORT. +The PORT instruction tells the remote server to do a TCP connect to our +specified IP address. The string may be a plain IP address, a host name, a +network interface name (under Unix) or just a '-' symbol to let the library +use your system's default IP address. Default FTP operations are passive, and +does not use the PORT command. The address can be followed by a ':' to specify a port, optionally followed by a '-' to specify a port range. If the port specified is 0, the operating -system will pick a free port. If a range is provided and all ports in the -range are not available, libcurl will report CURLE_FTP_PORT_FAILED for the +system picks a free port. If a range is provided and all ports in the range +are not available, libcurl reports CURLE_FTP_PORT_FAILED for the handle. Invalid port/range settings are ignored. IPv6 addresses followed by a port or port range have to be in brackets. IPv6 addresses without port/range specifier can be in brackets. @@ -61,9 +61,12 @@ Examples with specified ports: We strongly advise against specifying the address with a name, as it causes libcurl to do a blocking name resolve call to retrieve the IP address. That -name resolve operation will \fBnot\fP use DNS-over-HTTPS even if +name resolve operation does \fBnot\fP use DNS-over-HTTPS even if \fICURLOPT_DOH_URL(3)\fP is set. +Using anything else than "-" for this option should typically only be done if +you have special knowledge and confirmation that it works. + You disable PORT again and go back to using the passive version by setting this option to NULL. diff --git a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 index 79d78867dd..317b556a57 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 @@ -32,11 +32,10 @@ CURLOPT_FTP_ALTERNATIVE_TO_USER \- command to use instead of USER with FTP CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ALTERNATIVE_TO_USER, char *cmd); .SH DESCRIPTION -Pass a char * as parameter, pointing to a string which will be used to -authenticate if the usual FTP "USER user" and "PASS password" negotiation -fails. This is currently only known to be required when connecting to -Tumbleweed's Secure Transport FTPS server using client certificates for -authentication. +Pass a char * as parameter, pointing to a string which is used to authenticate +if the usual FTP "USER user" and "PASS password" negotiation fails. This is +currently only known to be required when connecting to Tumbleweed's Secure +Transport FTPS server using client certificates for authentication. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 index 6dd062f6a1..7299fc4d02 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 @@ -39,16 +39,16 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_CREATE_MISSING_DIRS, long create); .SH DESCRIPTION Pass a long telling libcurl to \fIcreate\fP the dir. If the value is -\fICURLFTP_CREATE_DIR\fP (1), libcurl will attempt to create any remote -directory that it fails to "move" into. +\fICURLFTP_CREATE_DIR\fP (1), libcurl may create any remote directory that it +fails to "move" into. For FTP requests, that means a CWD command fails. CWD being the command that changes working directory. -For SFTP requests, libcurl will attempt to create the remote directory if it -cannot obtain a handle to the target-location. The creation will fail if a file -of the same name as the directory to create already exists or lack of -permissions prevents creation. +For SFTP requests, libcurl may create the remote directory if it cannot obtain +a handle to the target-location. The creation fails if a file of the same name +as the directory to create already exists or lack of permissions prevents +creation. Setting \fIcreate\fP to \fICURLFTP_CREATE_DIR_RETRY\fP (2), tells libcurl to retry the CWD command again if the subsequent \fBMKD\fP command fails. This is diff --git a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 index 99caebf51e..d0bafc7c5e 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 @@ -44,8 +44,9 @@ libcurl 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 CURLFTPMETHOD_NOCWD -libcurl does no CWD at all. libcurl will do SIZE, RETR, STOR etc and give a -full path to the server for all these commands. This is the fastest behavior. +libcurl makes no CWD at all. libcurl does SIZE, RETR, STOR etc and gives a +full path to the server for all these commands. This is the fastest behavior +since it skips having to change directories. .IP CURLFTPMETHOD_SINGLECWD libcurl does one CWD with the full target directory and then operates on the file \&"normally" (like in the multicwd case). This is somewhat more standards diff --git a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 index 86b2ed7d01..d6c89ba3f4 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 @@ -34,13 +34,13 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SKIP_PASV_IP, long skip); .SH DESCRIPTION Pass a long. If \fIskip\fP is set to 1, it instructs libcurl to not use the IP address the server suggests in its 227-response to libcurl's PASV command when -libcurl connects the data connection. Instead libcurl will re-use the same IP -address it already uses for the control connection. But it will use the port +libcurl connects the data connection. Instead libcurl reuses the same IP +address it already uses for the control connection. It still uses the port number from the 227-response. -This option thus allows libcurl to work around broken server installations -that due to NATs, firewalls or incompetence report the wrong IP address -back. Setting the option also reduces the risk for various sorts of client +This option allows libcurl to work around broken server installations or funny +network setups that due to NATs, firewalls or incompetence report the wrong IP +address. Setting this option also reduces the risk for various sorts of client abuse by malicious servers. This option has no effect if PORT, EPRT or EPSV is used instead of PASV. diff --git a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 index 690d3a4e00..8d58faa7aa 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 @@ -35,7 +35,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SSL_CCC, .SH DESCRIPTION If enabled, this option makes libcurl use CCC (Clear Command Channel). It shuts down the SSL/TLS layer after authenticating. The rest of the control -channel communication will be unencrypted. This allows NAT routers to follow +channel communication remains unencrypted. This allows NAT routers to follow the FTP transaction. Pass a long using one of the values below .IP CURLFTPSSL_CCC_NONE do not attempt to use CCC. diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 index a15c917d3c..79a56ea8da 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 @@ -34,12 +34,18 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPRT, long enabled); .SH DESCRIPTION Pass a long. If the value is 1, it tells curl to use the EPRT command when doing active FTP downloads (which is enabled by -\fICURLOPT_FTPPORT(3)\fP). Using EPRT means that it will first attempt to use -EPRT before using PORT, but if you pass zero to this option, it will not try -using EPRT, only plain PORT. +\fICURLOPT_FTPPORT(3)\fP). Using EPRT means that libcurl first attempts to use +EPRT before using PORT, but if you pass zero to this option, it avoids using +EPRT, only plain PORT. -If the server is an IPv6 host, this option will have no effect as EPRT is -necessary then. +The EPRT command is a slightly newer addition to the FTP protocol than PORT +and is the preferred command to use since it enables IPv6 to be used. Very old +FTP servers might not support it, which is why libcurl has a fallback +mechanism. Sometimes that fallback is not enough and then this option might +come handy. + +If the server is an IPv6 host, this option has no effect as EPRT is necessary +then. .SH DEFAULT .SH PROTOCOLS .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 index 7b7d843290..6c0c34d56e 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 @@ -34,10 +34,16 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPSV, long epsv); .SH DESCRIPTION Pass \fIepsv\fP as a long. If the value is 1, it tells curl to use the EPSV command when doing passive FTP downloads (which it does by default). Using -EPSV means that it will first attempt to use EPSV before using PASV, but if -you pass zero to this option, it will not try using EPSV, only plain PASV. +EPSV means that libcurl first attempts to use the EPSV command before using +PASV. If you pass zero to this option, it does not use EPSV, only plain PASV. -If the server is an IPv6 host, this option will have no effect as of 7.12.3. +The EPSV command is a slightly newer addition to the FTP protocol than PASV +and is the preferred command to use since it enables IPv6 to be used. Very old +FTP servers might not support it, which is why libcurl has a fallback +mechanism. Sometimes that fallback is not enough and then this option might +come handy. + +If the server is an IPv6 host, this option has no effect. .SH DEFAULT 1 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.3 b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.3 index 6c54ee89bd..04d8621f5a 100644 --- a/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.3 +++ b/docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.3 @@ -33,15 +33,14 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPROXY_CLIENT_IP, char *client_ip); .fi .SH DESCRIPTION -When this parameter is set to a valid IPv4 or IPv6, the library will -not send this address in the HAProxy PROXY protocol -v1 header at beginning of the connection. - -This option is primarily useful when sending test requests to verify that -a service is working as intended. +When this parameter is set to a valid IPv4 or IPv6 numerical address, the +library sends this address as client address in the HAProxy PROXY protocol v1 +header at beginning of the connection. +This option is an alternative to \fICURLOPT_HAPROXYPROTOCOL(3)\fP as that one +cannot use a specified address. .SH DEFAULT -no HAProxy header will be sent +NULL, no HAProxy header is sent .SH PROTOCOLS HTTP, HAProxy PROTOCOL .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_HEADERDATA.3 b/docs/libcurl/opts/CURLOPT_HEADERDATA.3 index c5751be3f0..269965b205 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERDATA.3 +++ b/docs/libcurl/opts/CURLOPT_HEADERDATA.3 @@ -36,14 +36,14 @@ Pass a \fIpointer\fP to be used to write the header part of the received data to. If \fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP is used, -\fIpointer\fP will be passed in to the respective callback. +\fIpointer\fP is passed in to the respective callback. If neither of those options are set, \fIpointer\fP must be a valid FILE * and -it will be used by a plain fwrite() to write headers to. +it is used by a plain fwrite() to write headers to. If you are using libcurl as a win32 DLL, you \fBMUST\fP use a \fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP if you set -this option or you will experience crashes. +this option or you might experience crashes. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 index 92691f9650..a2137c24d6 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 @@ -41,20 +41,20 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION, Pass a pointer to your callback function, which should match the prototype shown above. -This function gets called by libcurl as soon as it has received header -data. The header callback will be called once for each header and only +This callback function gets invoked by libcurl as soon as it has received +header data. The header callback is called once for each header and only complete header lines are passed on to the callback. Parsing headers is easy to do using this callback. \fIbuffer\fP points to the delivered data, and the -size of that data is \fInitems\fP; \fIsize\fP is always 1. Do not assume that -the header line is null-terminated! +size of that data is \fInitems\fP; \fIsize\fP is always 1. The provide header +line is not null-terminated! The pointer named \fIuserdata\fP is the one you set with the \fICURLOPT_HEADERDATA(3)\fP option. Your callback should return the number of bytes actually taken care of. If -that amount differs from the amount passed to your callback function, it will -signal an error condition to the library. This will cause the transfer to get -aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP. +that amount differs from the amount passed to your callback function, it +signals an error condition to the library. This causes the transfer to get +aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0) @@ -63,16 +63,16 @@ A complete HTTP header that is passed to this function can be up to If this option is not set, or if it is set to NULL, but \fICURLOPT_HEADERDATA(3)\fP is set to anything but NULL, the function used to -accept response data will be used instead. That is, it will be the function -specified with \fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or -NULL - the default, stream-writing function. +accept response data is used instead. That is the function specified with +\fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or NULL - the +default, stream-writing function. -It's important to note that the callback will be invoked for the headers of -all responses received after initiating a request and not just the final +It's important to note that the callback is invoked for the headers of all +responses received after initiating a request and not just the final response. This includes all responses which occur during authentication negotiation. If you need to operate on only the headers from the final -response, you will need to collect headers in the callback yourself and use -HTTP status lines, for example, to delimit response boundaries. +response, you need to collect headers in the callback yourself and use HTTP +status lines, for example, to delimit response boundaries. For an HTTP transfer, the status line and the blank line preceding the response body are both included as headers and passed to this function. @@ -85,13 +85,16 @@ response-body. 2) it comes after the final header line (CR LF) 3) a Trailer: header among the regular response-headers mention what header(s) to expect in the trailer. -For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get -called with the server responses to the commands that libcurl sends. +For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function gets called +with the server responses to the commands that libcurl sends. + +A more convenient way to get HTTP headers might be to use +\fIcurl_easy_header(3)\fP. .SH LIMITATIONS libcurl does not unfold HTTP "folded headers" (deprecated since RFC 7230). A folded header is a header that continues on a subsequent line and starts with -a whitespace. Such folds will be passed to the header callback as a separate -one, although strictly it is just a continuation of the previous line. +a whitespace. Such folds are passed to the header callback as separate ones, +although strictly they are just continuations of the previous lines. .SH DEFAULT Nothing. .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_HEADEROPT.3 b/docs/libcurl/opts/CURLOPT_HEADEROPT.3 index 499dcb64a9..5774fd45de 100644 --- a/docs/libcurl/opts/CURLOPT_HEADEROPT.3 +++ b/docs/libcurl/opts/CURLOPT_HEADEROPT.3 @@ -36,17 +36,16 @@ Pass a long that is a bitmask of options of how to deal with headers. The two mutually exclusive options are: \fBCURLHEADER_UNIFIED\fP - the headers specified in -\fICURLOPT_HTTPHEADER(3)\fP will be used in requests both to servers and -proxies. With this option enabled, \fICURLOPT_PROXYHEADER(3)\fP will not have +\fICURLOPT_HTTPHEADER(3)\fP are used in requests both to servers and +proxies. With this option enabled, \fICURLOPT_PROXYHEADER(3)\fP does not have any effect. \fBCURLHEADER_SEPARATE\fP - makes \fICURLOPT_HTTPHEADER(3)\fP headers only get sent to a server and not to a proxy. Proxy headers must be set with \fICURLOPT_PROXYHEADER(3)\fP to get used. Note that if a non-CONNECT request -is sent to a proxy, libcurl will send both server headers and proxy -headers. When doing CONNECT, libcurl will send \fICURLOPT_PROXYHEADER(3)\fP -headers only to the proxy and then \fICURLOPT_HTTPHEADER(3)\fP headers only to -the server. +is sent to a proxy, libcurl sends both server headers and proxy headers. When +doing CONNECT, libcurl sends \fICURLOPT_PROXYHEADER(3)\fP headers only to the +proxy and then \fICURLOPT_HTTPHEADER(3)\fP headers only to the server. .SH DEFAULT CURLHEADER_SEPARATE (changed in 7.42.1, used CURLHEADER_UNIFIED before then) .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_HSTS.3 b/docs/libcurl/opts/CURLOPT_HSTS.3 index 2d4eb94c5c..cce62ac4ff 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS.3 +++ b/docs/libcurl/opts/CURLOPT_HSTS.3 @@ -34,15 +34,15 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS, char *filename); .SH DESCRIPTION Make the \fIfilename\fP point to a file name to load an existing HSTS cache from, and to store the cache in when the easy handle is closed. Setting a file -name with this option will also enable HSTS for this handle (the equivalent of +name with this option also enables HSTS for this handle (the equivalent of setting \fICURLHSTS_ENABLE\fP with \fICURLOPT_HSTS_CTRL(3)\fP). If the given file does not exist or contains no HSTS entries at startup, the -HSTS cache will simply start empty. Setting the file name to NULL or "" will -only enable HSTS without reading from or writing to any file. +HSTS cache simply starts empty. Setting the file name to NULL or "" only +enables HSTS without reading from or writing to any file. -If this option is set multiple times, libcurl will load cache entries from -each given file but will only store the last used name for later writing. +If this option is set multiple times, libcurl loads cache entries from each +given file but only stores the last used name for later writing. .SH "FILE FORMAT" The HSTS cache is saved to and loaded from a text file with one entry per physical line. Each line in the file has the following format: diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 index cd82134d44..fb348ac449 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 +++ b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 @@ -33,8 +33,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADDATA, void *pointer); .fi .SH DESCRIPTION Data \fIpointer\fP to pass to the HSTS read function. If you use the -\fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you will get as -input in the 3rd argument to the callback. +\fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you get as input +in the 3rd argument to the callback. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to do that. @@ -59,7 +59,7 @@ if(curl) { .SH AVAILABILITY Added in 7.74.0 .SH RETURN VALUE -This will return CURLE_OK. +This returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_HSTSREADFUNCTION "(3), " CURLOPT_HSTSWRITEDATA "(3), " .BR CURLOPT_HSTSWRITEFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 index 83c6f0a8a5..1f1b7d47d1 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 @@ -47,7 +47,7 @@ This callback function gets called by libcurl repeatedly when it populates the in-memory HSTS cache. Set the \fIclientp\fP argument with the \fICURLOPT_HSTSREADDATA(3)\fP option -or it will be NULL. +or it is NULL. When this callback is invoked, the \fIsts\fP pointer points to a populated struct: Copy the host name to \fIname\fP (no longer than \fInamelen\fP @@ -58,8 +58,8 @@ FALSE. Set \fIexpire\fP to a date stamp or a zero length string for *forever* The callback should return \fICURLSTS_OK\fP if it returns a name and is prepared to be called again (for another host) or \fICURLSTS_DONE\fP if it has no entry to return. It can also return \fICURLSTS_FAIL\fP to signal -error. Returning \fICURLSTS_FAIL\fP will stop the transfer from being -performed and make \fICURLE_ABORTED_BY_CALLBACK\fP get returned. +error. Returning \fICURLSTS_FAIL\fP stops the transfer from being performed +and make \fICURLE_ABORTED_BY_CALLBACK\fP get returned. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to do that. @@ -82,7 +82,7 @@ This feature is only used for HTTP(S) transfer. .SH AVAILABILITY Added in 7.74.0 .SH RETURN VALUE -This will return CURLE_OK. +This returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_HSTSREADDATA "(3), " CURLOPT_HSTSWRITEFUNCTION "(3), " .BR CURLOPT_HSTS "(3), " CURLOPT_HSTS_CTRL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 index 49659b22cc..c088d97bba 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 @@ -33,7 +33,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEDATA, void *pointer); .fi .SH DESCRIPTION Data \fIpointer\fP to pass to the HSTS write function. If you use the -\fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you will get as +\fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you get as input in the fourth argument to the callback. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to @@ -59,7 +59,7 @@ if(curl) { .SH AVAILABILITY Added in 7.74.0 .SH RETURN VALUE -This will return CURLE_OK. +This returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_HSTSWRITEFUNCTION "(3), " CURLOPT_HSTSREADDATA "(3), " .BR CURLOPT_HSTSREADFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 index 2da223fc0a..3a185b27e9 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 @@ -54,8 +54,7 @@ application to store the in-memory HSTS cache when libcurl is about to discard it. Set the \fIclientp\fP argument with the \fICURLOPT_HSTSWRITEDATA(3)\fP option -or it will be NULL. - +or it is NULL. When the callback is invoked, the \fIsts\fP pointer points to a populated struct: Read the host name to 'name' (it is \fInamelen\fP bytes long and null terminated. The \fIincludeSubDomains\fP field is non-zero if the entry matches @@ -63,7 +62,7 @@ subdomains. The \fIexpire\fP string is a date stamp null-terminated string using the syntax YYYYMMDD HH:MM:SS. The callback should return \fICURLSTS_OK\fP if it succeeded and is prepared to -be called again (for another host) or \fICURLSTS_DONE\fP if there's nothing +be called again (for another host) or \fICURLSTS_DONE\fP if there is nothing more to do. It can also return \fICURLSTS_FAIL\fP to signal error. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to @@ -87,7 +86,7 @@ This feature is only used for HTTP(S) transfer. .SH AVAILABILITY Added in 7.74.0 .SH RETURN VALUE -This will return CURLE_OK. +This returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_HSTSWRITEDATA "(3), " CURLOPT_HSTSWRITEFUNCTION "(3), " .BR CURLOPT_HSTS "(3), " CURLOPT_HSTS_CTRL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 index 8f7801da88..2136e48308 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 +++ b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 @@ -37,9 +37,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS_CTRL, long bitmask); .SH DESCRIPTION HSTS (HTTP Strict Transport Security) means that an HTTPS server can instruct the client to not contact it again over clear-text HTTP for a certain period -into the future. libcurl will then automatically redirect HTTP attempts to -such hosts to instead use HTTPS. This is done by libcurl retaining this -knowledge in an in-memory cache. +into the future. libcurl then automatically redirects HTTP attempts to such +hosts to instead use HTTPS. This is done by libcurl retaining this knowledge +in an in-memory cache. Populate the long \fIbitmask\fP with the correct set of features to instruct libcurl how to handle HSTS for the transfers using this handle. diff --git a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 index b0fde4dcfa..06ac5233bd 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 @@ -35,10 +35,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP200ALIASES, Pass a pointer to a linked list of \fIaliases\fP to be treated as valid HTTP 200 responses. Some servers respond with a custom header response line. For example, SHOUTcast servers respond with "ICY 200 OK". Also some old Icecast -1.3.x servers will respond like that for certain user agent headers or in -absence of such. By including this string in your list of aliases, the -response will be treated as a valid HTTP header line such as "HTTP/1.0 200 -OK". +1.3.x servers respond like that for certain user agent headers or in absence +of such. By including this string in your list of aliases, the response gets +treated as a valid HTTP header line such as "HTTP/1.0 200 OK". The linked list should be a fully valid list of struct curl_slist structs, and be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and diff --git a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 b/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 index 5e981268bd..53a19c9424 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 @@ -34,9 +34,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPAUTH, long bitmask); Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use speaking to the remote server. -The available bits are listed below. If more than one bit is set, libcurl will -first query the site to see which authentication methods it supports and then -pick the best one you allow it to use. For some methods, this will induce an +The available bits are listed below. If more than one bit is set, libcurl +first queries the host to see which authentication methods it supports and +then picks the best one you allow it to use. For some methods, this induces an extra network round-trip. Set the actual name and password with the \fICURLOPT_USERPWD(3)\fP option or with the \fICURLOPT_USERNAME(3)\fP and the \fICURLOPT_PASSWORD(3)\fP options. @@ -56,7 +56,7 @@ regular old-fashioned Basic method. HTTP Digest authentication with an IE flavor. Digest authentication is defined in RFC 2617 and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. The IE flavor is simply -that libcurl will use a special "quirk" that IE is known to have used before +that libcurl uses a special "quirk" that IE is known to have used before version 7 and that some servers require the client to use. .IP CURLAUTH_BEARER HTTP Bearer token authentication, used primarily in OAuth 2.0 protocol. @@ -80,9 +80,9 @@ NTLM delegating to winbind helper. Authentication is performed by a separate binary application that is executed when needed. The name of the application is specified at compile time but is typically \fB/usr/bin/ntlm_auth\fP. -Note that libcurl will fork when necessary to run the winbind application and -kill it when complete, calling \fBwaitpid()\fP to await its exit when done. On -POSIX operating systems, killing the process will cause a SIGCHLD signal to be +Note that libcurl forks when necessary to run the winbind application and kill +it when complete, calling \fBwaitpid()\fP to await its exit when done. On +POSIX operating systems, killing the process causes a SIGCHLD signal to be raised (regardless of whether \fICURLOPT_NOSIGNAL(3)\fP is set), which must be handled intelligently by the application. In particular, the application must not unconditionally call wait() in its SIGCHLD signal handler to avoid being @@ -90,12 +90,11 @@ subject to a race condition. This behavior is subject to change in future versions of libcurl. .IP CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any -it finds suitable. libcurl will automatically select the one it finds most -secure. +it finds suitable. libcurl automatically selects the one it finds most secure. .IP CURLAUTH_ANYSAFE This is a convenience macro that sets all bits except Basic and thus makes -libcurl pick any it finds suitable. libcurl will automatically select the one -it finds most secure. +libcurl pick any it finds suitable. libcurl automatically selects the one it +finds most secure. .IP CURLAUTH_ONLY This is a meta symbol. OR this value together with a single specific auth value to force libcurl to probe for unrestricted auth and if not, only that diff --git a/docs/libcurl/opts/CURLOPT_HTTPGET.3 b/docs/libcurl/opts/CURLOPT_HTTPGET.3 index 19104fba5f..4d4a9106f6 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPGET.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPGET.3 @@ -36,7 +36,7 @@ Pass a long. If \fIuseget\fP is 1, this forces the HTTP request to get back to using GET. Usable if a POST, HEAD, PUT, etc has been used previously using the same curl \fIhandle\fP. -When setting \fICURLOPT_HTTPGET(3)\fP to 1, it will automatically set +When setting \fICURLOPT_HTTPGET(3)\fP to 1, libcurl automatically sets \fICURLOPT_NOBODY(3)\fP to 0 and \fICURLOPT_UPLOAD(3)\fP to 0. Setting this option to zero has no effect. Applications need to explicitly diff --git a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 index c989b433c0..baf6cb047c 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 @@ -46,24 +46,24 @@ The linked list should be a fully valid list of \fBstruct curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. If you add a header that is otherwise generated and used by libcurl internally, your added -one will be used instead. If you add a header with no content as in 'Accept:' -(no data on the right side of the colon), the internally used header will get -disabled. With this option you can add new headers, replace internal headers -and remove internal headers. To add a header with no content (nothing to the -right side of the colon), use the form 'name;' (note the ending semicolon). +header is used instead. If you add a header with no content as in 'Accept:' +(no data on the right side of the colon), the internally used header is +disabled/removed. With this option you can add new headers, replace internal +headers and remove internal headers. To add a header with no content (nothing +to the right side of the colon), use the form 'name;' (note the ending +semicolon). The headers included in the linked list \fBmust not\fP be CRLF-terminated, -because libcurl adds CRLF after each header item. Failure to comply with this -will result in strange bugs because the server will most likely ignore part of -the headers you specified. +because libcurl adds CRLF after each header item itself. Failure to comply +with this might result in strange behavior. The first line in an HTTP request (containing the method, usually a GET or POST) is not a header and cannot be replaced using this option. Only the lines following the request-line are headers. Adding this method line in this list -of headers will only cause your request to send an invalid header. Use +of headers only causes your request to send an invalid header. Use \fICURLOPT_CUSTOMREQUEST(3)\fP to change the method. -When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl will not copy +When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy the entire list so you \fBmust\fP keep it around until you no longer use this \fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on the list. @@ -74,16 +74,16 @@ The most commonly replaced HTTP headers have "shortcuts" in the options \fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP and \fICURLOPT_REFERER(3)\fP. We recommend using those. -There's an alternative option that sets or replaces headers only for requests +There is an alternative option that sets or replaces headers only for requests that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER(3)\fP. Use \fICURLOPT_HEADEROPT(3)\fP to control the behavior. .SH SPECIFIC HTTP HEADERS -Setting some specific headers will cause libcurl to act differently. +Setting some specific headers causes libcurl to act differently. .IP "Host:" -The specified host name will be used for cookie matching if the cookie engine -is also enabled for this transfer. If the request is done over HTTP/2 or -HTTP/3, the custom host name will instead be used in the ":authority" header -field and Host: will not be sent at all over the wire. +The specified host name is used for cookie matching if the cookie engine is +also enabled for this transfer. If the request is done over HTTP/2 or HTTP/3, +the custom host name is instead used in the ":authority" header field and +Host: is not sent at all over the wire. .IP "Transfer-Encoding: chunked" Tells libcurl the upload is to be done using this chunked encoding instead of providing the Content-Length: field in the request. @@ -115,19 +115,19 @@ the headers. They may be private or otherwise sensitive to leak. Use \fICURLOPT_HEADEROPT(3)\fP to make the headers only get sent to where you intend them to get sent. -Custom headers are sent in all requests done by the easy handles, which -implies that if you tell libcurl to follow redirects -(\fICURLOPT_FOLLOWLOCATION(3)\fP), the same set of custom headers will be sent -in the subsequent request. Redirects can of course go to other hosts and thus -those servers will get all the contents of your custom headers too. +Custom headers are sent in all requests done by the easy handle, which implies +that if you tell libcurl to follow redirects +(\fICURLOPT_FOLLOWLOCATION(3)\fP), the same set of custom headers is sent in +the subsequent request. Redirects can of course go to other hosts and thus +those servers get all the contents of your custom headers too. -Starting in 7.58.0, libcurl will specifically prevent "Authorization:" headers +Starting in 7.58.0, libcurl specifically prevents "Authorization:" headers from being sent to other hosts than the first used one, unless specifically permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option. -Starting in 7.64.0, libcurl will specifically prevent "Cookie:" headers -from being sent to other hosts than the first used one, unless specifically -permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option. +Starting in 7.64.0, libcurl specifically prevents "Cookie:" headers from being +sent to other hosts than the first used one, unless specifically permitted +with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 index 2c647950c1..c064b2c426 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 @@ -44,7 +44,7 @@ transfer is alive and is using it. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP. -When setting \fICURLOPT_HTTPPOST(3)\fP, it will automatically set +When setting \fICURLOPT_HTTPPOST(3)\fP, libcurl automatically sets \fICURLOPT_NOBODY(3)\fP to 0. .SH DEFAULT NULL diff --git a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 index 3d9f557c97..be9b514b77 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 @@ -47,7 +47,7 @@ To suppress proxy CONNECT response headers from user callbacks use HTTP proxies can generally only speak HTTP (for obvious reasons), which makes libcurl convert non-HTTP requests to HTTP when using an HTTP proxy without this tunnel option set. For example, asking for an FTP URL and specifying an -HTTP proxy will make libcurl send an FTP URL in an HTTP GET request to the +HTTP proxy makes libcurl send an FTP URL in an HTTP GET request to the proxy. By instead tunneling through the proxy, you avoid that conversion (that rarely works through the proxy anyway). .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 index ddbd4be73b..61e3efef4f 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 @@ -33,7 +33,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_CONTENT_DECODING, long enabled); .SH DESCRIPTION Pass a long to tell libcurl how to act on content decoding. If set to zero, -content decoding will be disabled. If set to 1 it is enabled. Libcurl has no +content decoding is disabled. If set to 1 it is enabled. Libcurl has no default content decoding but requires you to use \fICURLOPT_ACCEPT_ENCODING(3)\fP for that. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 index 899d0742ed..e1a7a335e2 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 @@ -33,9 +33,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_TRANSFER_DECODING, long enabled); .SH DESCRIPTION Pass a long to tell libcurl how to act on transfer decoding. If set to zero, -transfer decoding will be disabled, if set to 1 it is enabled -(default). libcurl does chunked transfer decoding by default unless this -option is set to zero. +transfer decoding is disabled, if set to 1 it is enabled (default). libcurl +does chunked transfer decoding by default unless this option is set to zero. .SH DEFAULT 1 .SH PROTOCOLS @@ -51,8 +50,8 @@ if(curl) { } .fi .SH AVAILABILITY -Added in 7.16.2 Does not work with the hyper backend (it will always have -transfer decoding enabled). +Added in 7.16.2 Does not work with the hyper backend (it always has transfer +decoding enabled). .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 index 0b5be1ce70..c8b0ce44f8 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 @@ -35,19 +35,19 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_VERSION, long version); Pass \fIversion\fP a long, set to one of the values described below. They ask libcurl to use the specific HTTP versions. -Note that the HTTP version is just a request. libcurl will still prioritize to -re-use an existing connection so it might then re-use a connection using a -HTTP version you have not asked for. +Note that the HTTP version is just a request. libcurl still prioritizes to +reuse existing connections so it might then reuse a connection using a HTTP +version you have not asked for. .IP CURL_HTTP_VERSION_NONE -We do not care about what version the library uses. libcurl will use whatever -it thinks fit. +We do not care about what version the library uses. libcurl uses whatever it +thinks fit. .IP CURL_HTTP_VERSION_1_0 Enforce HTTP 1.0 requests. .IP CURL_HTTP_VERSION_1_1 Enforce HTTP 1.1 requests. .IP CURL_HTTP_VERSION_2_0 -Attempt HTTP 2 requests. libcurl will fall back to HTTP 1.1 if HTTP 2 cannot be +Attempt HTTP 2 requests. libcurl falls back to HTTP 1.1 if HTTP 2 cannot be negotiated with the server. (Added in 7.33.0) When libcurl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or @@ -57,21 +57,21 @@ version requirement with \fICURLOPT_SSLVERSION(3)\fP. The alias \fICURL_HTTP_VERSION_2\fP was added in 7.43.0 to better reflect the actual protocol name. .IP CURL_HTTP_VERSION_2TLS -Attempt HTTP 2 over TLS (HTTPS) only. libcurl will fall back to HTTP 1.1 if -HTTP 2 cannot be negotiated with the HTTPS server. For clear text HTTP servers, -libcurl will use 1.1. (Added in 7.47.0) +Attempt HTTP 2 over TLS (HTTPS) only. libcurl falls back to HTTP 1.1 if HTTP 2 +cannot be negotiated with the HTTPS server. For clear text HTTP servers, +libcurl uses 1.1. (Added in 7.47.0) .IP CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE Issue 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. (Added in 7.49.0) +still do HTTP/2 the standard way with negotiated protocol version in the TLS +handshake. (Added in 7.49.0) .IP CURL_HTTP_VERSION_3 (Added in 7.66.0) This option makes libcurl attempt to use HTTP/3 to the host given in the URL, with fallback to earlier HTTP versions if needed. .IP CURL_HTTP_VERSION_3ONLY -(Added in 7.88.0) Setting this value will make libcurl attempt to use HTTP/3 -directly to server given in the URL but will not downgrade to earlier HTTP -version if the server does not support HTTP/3. +(Added in 7.88.0) Setting this makes libcurl attempt to use HTTP/3 directly to +server given in the URL and does not downgrade to earlier HTTP version if the +server does not support HTTP/3. .SH DEFAULT Since curl 7.62.0: CURL_HTTP_VERSION_2TLS diff --git a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 index 3f9502ce0a..61c844c5a2 100644 --- a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 +++ b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 @@ -35,13 +35,13 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IGNORE_CONTENT_LENGTH, If \fIignore\fP is set to 1L, ignore the Content-Length header in the HTTP response and ignore asking for or relying on it for FTP transfers. -This is useful for HTTP with Apache 1.x (and similar servers) which will -report incorrect content length for files over 2 gigabytes. If this option is -used, curl will not be able to accurately report progress, and will simply -stop the download when the server ends the connection. +This is useful for doing HTTP transfers with ancient web servers which report +incorrect content length for files over 2 gigabytes. If this option is used, +curl cannot accurately report progress, and it instead stops the download when +the server ends the connection. It is also useful with FTP when for example the file is growing while the -transfer is in progress which otherwise will unconditionally cause libcurl to +transfer is in progress which otherwise unconditionally causes libcurl to report error. Only use this option if strictly necessary. diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE.3 b/docs/libcurl/opts/CURLOPT_INFILESIZE.3 index 86961de5e8..c3cb8497f5 100644 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE.3 +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE.3 @@ -48,9 +48,9 @@ makes libcurl do a chunked transfer-encoded upload. When sending emails using SMTP, this command can be used to specify the optional SIZE parameter for the MAIL FROM command. -This option does not limit how much data libcurl will actually send, as that -is controlled entirely by what the read callback returns, but telling one -value and sending a different amount may lead to errors. +This option does not limit how much data libcurl actually sends, as that is +controlled entirely by what the read callback returns, but telling one value +and sending a different amount may lead to errors. .SH DEFAULT Unset .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 index 5d62e16ee2..badb337022 100644 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 @@ -44,9 +44,9 @@ To unset this value again, set it to -1. When sending emails using SMTP, this command can be used to specify the optional SIZE parameter for the MAIL FROM command. -This option does not limit how much data libcurl will actually send, as that -is controlled entirely by what the read callback returns, but telling one -value and sending a different amount may lead to errors. +This option does not limit how much data libcurl actually sends, as that is +controlled entirely by what the read callback returns, but telling one value +and sending a different amount may lead to errors. .SH DEFAULT Unset .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_INTERFACE.3 b/docs/libcurl/opts/CURLOPT_INTERFACE.3 index e8c9c7a528..6997ede70d 100644 --- a/docs/libcurl/opts/CURLOPT_INTERFACE.3 +++ b/docs/libcurl/opts/CURLOPT_INTERFACE.3 @@ -36,10 +36,9 @@ Pass a char * as parameter. This sets the \fIinterface\fP name to use as outgoing network interface. The name can be an interface name, an IP address, or a host name. -If the parameter starts with "if!" then it is treated as only as interface -name and no attempt will ever be named to do treat it as an IP address or to -do name resolution on it. If the parameter starts with \&"host!" it is treated -as either an IP address or a hostname. +If the parameter starts with "if!" then it is treated only as an interface +name. If the parameter starts with \&"host!" it is treated as either an IP +address or a hostname. If "if!" is specified but the parameter does not match an existing interface, \fICURLE_INTERFACE_FAILED\fP is returned from the libcurl function used to @@ -50,7 +49,7 @@ Windows. We strongly advise against specifying the interface with a hostname, as it causes libcurl to do a blocking name resolve call to retrieve the IP -address. That name resolve operation will \fBnot\fP use DNS-over-HTTPS even if +address. That name resolve operation does \fBnot\fP use DNS-over-HTTPS even if \fICURLOPT_DOH_URL(3)\fP is set. The application does not have to keep the string around after setting this diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 index be4cb19491..962847fa0a 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 @@ -32,7 +32,7 @@ CURLOPT_INTERLEAVEDATA \- pointer passed to RTSP interleave callback CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEDATA, void *pointer); .fi .SH DESCRIPTION -This is the userdata \fIpointer\fP that will be passed to +This is the userdata \fIpointer\fP that is passed to \fICURLOPT_INTERLEAVEFUNCTION(3)\fP when interleaved RTP data is received. If the interleave function callback is not set, this pointer is not used anywhere. diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 index fbdf3dbe18..bb8fe73d6c 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 @@ -45,7 +45,7 @@ writes the interleaved header as well as the included data for each call. The first byte is always an ASCII dollar sign. The dollar sign is followed by a one byte channel identifier and then a 2 byte integer length in network byte order. See RFC 2326 Section 10.12 for more information on how RTP interleaving -behaves. If unset or set to NULL, curl will use the default write function. +behaves. If unset or set to NULL, curl uses the default write function. Interleaved RTP poses some challenges for the client application. Since the stream data is sharing the RTSP control connection, it is critical to service @@ -53,16 +53,16 @@ the RTP in a timely fashion. If the RTP data is not handled quickly, subsequent response processing may become unreasonably delayed and the connection may close. The application may use \fICURL_RTSPREQ_RECEIVE\fP to service RTP data when no requests are desired. If the application makes a -request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler will -process any pending RTP data before marking the request as finished. +request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler processes +any pending RTP data before marking the request as finished. The \fICURLOPT_INTERLEAVEDATA(3)\fP is passed in the \fIuserdata\fP argument in the callback. Your callback should return the number of bytes actually taken care of. If -that amount differs from the amount passed to your callback function, it will -signal an error condition to the library. This will cause the transfer to get -aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP. +that amount differs from the amount passed to your callback function, it +signals an error condition to the library. This causes the transfer to abort +and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0) .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 b/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 index 5d18393bbc..190f4d5826 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 +++ b/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 @@ -32,7 +32,7 @@ CURLOPT_IOCTLDATA \- pointer passed to I/O callback CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLDATA, void *pointer); .fi .SH DESCRIPTION -Pass the \fIpointer\fP that will be untouched by libcurl and passed as the 3rd +Pass the \fIpointer\fP that is untouched by libcurl and passed as the 3rd argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION(3)\fP. .SH DEFAULT By default, the value of this parameter is NULL. diff --git a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 index f2ec3b4fb8..b933ab8781 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 @@ -63,7 +63,7 @@ The \fIclientp\fP argument to the callback is set with the This option is deprecated! Do not use it. Use \fICURLOPT_SEEKFUNCTION(3)\fP instead to provide seeking! If \fICURLOPT_SEEKFUNCTION(3)\fP is set, this -parameter will be ignored when seeking. +parameter is ignored when seeking. .SH DEFAULT By default, this parameter is set to NULL. Not used. .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 b/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 index ec9d6b7c6f..38209f6b01 100644 --- a/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 +++ b/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 @@ -34,10 +34,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IPRESOLVE, long resolve); .SH DESCRIPTION Allows an application to select what kind of IP addresses to use when establishing a connection or choosing one from the connection pool. This is -interesting when using host names that resolve to more than one version of IP. +interesting when using host names that resolve to more than one IP family. If the URL provided for a transfer contains a numerical IP version as a host -name, this option will not override or prohibit libcurl from using that IP +name, this option does not override or prohibit libcurl from using that IP version. Available values for this option are: diff --git a/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 b/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 index 632525b945..4f32976119 100644 --- a/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 +++ b/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 @@ -32,8 +32,8 @@ CURLOPT_KEYPASSWD \- passphrase to private key CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEYPASSWD, char *pwd); .fi .SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. It will be used as -the password required to use the \fICURLOPT_SSLKEY(3)\fP or +Pass a pointer to a null-terminated string as parameter. It is used as the +password required to use the \fICURLOPT_SSLKEY(3)\fP or \fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP private key. You never need a pass phrase to load a certificate but you need one to load your private key. diff --git a/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 b/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 index 9116380962..c405462061 100644 --- a/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 +++ b/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 @@ -34,9 +34,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KRBLEVEL, char *level); .SH DESCRIPTION Pass a char * as parameter. Set the kerberos security level for FTP; this also enables kerberos awareness. This is a string that should match one of the -following: \&'clear', \&'safe', \&'confidential' or \&'private'. If the -string is set but does not match one of these, 'private' will be used. Set the -string to NULL to disable kerberos support for FTP. +following: \&'clear', \&'safe', \&'confidential' or \&'private'. If the string +is set but does not match one of these, 'private' is used. Set the string to +NULL to disable kerberos support for FTP. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 index 9741e01d19..58d4ea4582 100644 --- a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 +++ b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 @@ -33,12 +33,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORTRANGE, long range); .fi .SH DESCRIPTION -Pass a long. The \fIrange\fP argument is the number of attempts libcurl will -make to find a working local port number. It starts with the given +Pass a long. The \fIrange\fP argument is the number of attempts libcurl makes +to find a working local port number. It starts with the given \fICURLOPT_LOCALPORT(3)\fP and adds one to the number for each retry. Setting -this option to 1 or below will make libcurl do only one try for the exact port -number. Port numbers by nature are scarce resources that will be busy at times -so setting this value to something too low might cause unnecessary connection +this option to 1 or below makes libcurl only do one try for the exact port +number. Port numbers by nature are scarce resources that are busy at times so +setting this value to something too low might cause unnecessary connection setup failures. .SH DEFAULT 1 diff --git a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 index 0fb32a47e2..c1506ba279 100644 --- a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 @@ -44,10 +44,10 @@ options, such as the preferred authentication mechanism via "AUTH=NTLM" or option. 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 in plain text. This does not work if the IMAP server +disables the plain LOGIN (e.g. to prevent password snooping). The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 index d914fc4ce4..c709e3d001 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 +++ b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 @@ -32,7 +32,7 @@ CURLOPT_MAIL_AUTH \- SMTP authentication address CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_AUTH, char *auth); .fi .SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. This will be used to +Pass a pointer to a null-terminated string as parameter. This is used to specify the authentication address (identity) of a submitted message that is being relayed to another server. @@ -45,8 +45,8 @@ be used for this parameter. Unlike \fICURLOPT_MAIL_FROM(3)\fP and \fICURLOPT_MAIL_RCPT(3)\fP, the address should not be specified within a pair of angled brackets (<>). However, if an -empty string is used then a pair of brackets will be sent by libcurl as -required by RFC 2554. +empty string is used then a pair of brackets are sent by libcurl as required +by RFC 2554. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 b/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 index cc0f859ab0..4fa5646a07 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 +++ b/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 @@ -36,10 +36,10 @@ Pass a pointer to a null-terminated string as parameter. This should be used to specify the sender's email address when sending SMTP mail with libcurl. An originator email address should be specified with angled brackets (<>) -around it, which if not specified will be added automatically. +around it, which if not specified are added automatically. -If this parameter is not specified then an empty address will be sent to the -mail server which may cause the email to be rejected. +If this parameter is not specified then an empty address is sent to the SMTP +server which might cause the email to be rejected. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 index 0f63c04aa6..a239b0736e 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 @@ -40,8 +40,8 @@ to clean up an entire list. When performing a mail transfer, each recipient should be specified within a pair of angled brackets (<>), however, should you not use an angled bracket as -the first character libcurl will assume you provided a single email address -and enclose that address within brackets for you. +the first character libcurl assumes you provided a single email address and +encloses that address within brackets for you. When performing an address verification (\fBVRFY\fP command), each recipient should be specified as the user name or user name and domain (as per Section diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 index 981e8b2fd4..6e486f5cc3 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLOWFAILS.3 @@ -34,16 +34,17 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT_ALLOWFAILS, .SH DESCRIPTION If \fIallow\fP is set to 1L, allow RCPT TO command to fail for some recipients. -When sending data to multiple recipients, by default curl will abort SMTP -conversation if at least one of the recipients causes RCPT TO command to +When sending data to multiple recipients, by default curl aborts the SMTP +conversation if either one of the recipients causes the RCPT TO command to return an error. -The default behavior can be changed by setting \fIignore\fP to 1L which will -make curl ignore errors and proceed with the remaining valid recipients. +The default behavior can be changed by setting \fIallow\fP to 1L which makes +libcurl ignore errors for individual recipients and proceed with the remaining +accepted 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. +aborts the SMTP conversation and returns the error received from to the last +RCPT TO command. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 index 3010c68902..eb32421b54 100644 --- a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 +++ b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 @@ -33,16 +33,16 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXAGE_CONN, long age); .fi .SH DESCRIPTION Pass a long as parameter containing \fIage\fP - the maximum time in seconds -that you allow an existing connection to have been idle to be considered for +allowed for an existing connection to have been idle to be considered for reuse for this request. -The "connection cache" that holds previously used connections. When a new -request is to be done, it will consider any connection that matches for -reuse. The \fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too -old connections for reuse, since old connections have a high risk of not -working and thus trying them is a performance loss and sometimes service loss -due to the difficulties to figure out the situation. If a connection is found -in the cache that is older than this set \fIage\fP, it will instead be closed. +The "connection cache" holds previously used connections. When a new request +is to be done, libcurl considers any connection that matches for reuse. The +\fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too old +connections for reuse, since old connections have a higher risk of not working +and thus trying them is a performance loss and sometimes service loss due to +the difficulties to figure out the situation. If a connection is found in the +cache that is older than this set \fIage\fP, it is closed instead. .SH DEFAULT Default maximum age is set to 118 seconds. .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 index ed0dbcae8f..b07f98c2c2 100644 --- a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 +++ b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 @@ -32,12 +32,11 @@ CURLOPT_MAXCONNECTS \- maximum connection cache size CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXCONNECTS, long amount); .fi .SH DESCRIPTION -Pass a long. The set \fIamount\fP will be the maximum number of simultaneously -open persistent connections that libcurl may cache in the pool associated with -this handle. The default is 5, and there is not much point in changing this -value unless you are perfectly aware of how this works and changes libcurl's -behavior. This concerns connections using any of the protocols that support -persistent connections. +Pass a long. The set \fIamount\fP is the maximum number of simultaneously open +persistent connections that libcurl may cache in the pool associated with this +handle. The default is 5, and there is not much point in changing this value +unless you are perfectly aware of how this works. This concerns connections +using any of the protocols that support persistent connections. When reaching the maximum limit, curl closes the oldest one in the cache to prevent increasing the number of open connections. diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 index 8460016bec..f4b024047f 100644 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 @@ -32,14 +32,13 @@ CURLOPT_MAXFILESIZE \- maximum file size allowed to download CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE, long size); .fi .SH DESCRIPTION -Pass a long as parameter. This allows you to specify the maximum \fIsize\fP -(in bytes) of a file to download. If the file requested is found larger than -this value, the transfer will not start and \fICURLE_FILESIZE_EXCEEDED\fP will -be returned. +Pass a long as parameter. This specifies the maximum accepted \fIsize\fP (in +bytes) of a file to download. If the file requested is found larger than this +value, the transfer is aborted and \fICURLE_FILESIZE_EXCEEDED\fP is returned. -The file size is not always known prior to download, and for such files this -option has no effect even if the file transfer ends up being larger than this -given limit. +The file size is not always known prior to the download start, and for such +transfers this option has no effect - even if the file transfer eventually +ends up being larger than this given limit. If you want a limit above 2GB, use \fICURLOPT_MAXFILESIZE_LARGE(3)\fP. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 index 1ee004c1f9..7e37fca92a 100644 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 @@ -32,14 +32,14 @@ CURLOPT_MAXFILESIZE_LARGE \- maximum file size allowed to download CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE_LARGE, curl_off_t size); .SH DESCRIPTION -Pass a curl_off_t as parameter. This allows you to specify the maximum -\fIsize\fP (in bytes) of a file to download. If the file requested is found -larger than this value, the transfer will not start and -\fICURLE_FILESIZE_EXCEEDED\fP will be returned. +Pass a curl_off_t as parameter. This specifies the maximum accepted \fIsize\fP +(in bytes) of a file to download. If the file requested is found larger than +this value, the transfer is aborted and \fICURLE_FILESIZE_EXCEEDED\fP is +returned. -The file size is not always known prior to download, and for such files this -option has no effect even if the file transfer ends up being larger than this -given limit. +The file size is not always known prior to the download start, and for such +transfers this option has no effect - even if the file transfer eventually +ends up being larger than this given limit. .SH DEFAULT None .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 index a459c82fbd..2d7536f8c7 100644 --- a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 +++ b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 @@ -38,12 +38,11 @@ seconds, since the creation of the connection, that you allow an existing connection to have to be considered for reuse for this request. libcurl features a connection cache that holds previously used connections. -When a new request is to be done, it will consider any connection that matches -for reuse. The \fICURLOPT_MAXLIFETIME_CONN(3)\fP limit prevents libcurl from -trying too old connections for reuse. This can be used for client-side load -balancing. If a connection is found in the cache that is older than this set -\fImaxlifetime\fP, it will instead be closed once any in-progress transfers -complete. +When a new request is to be done, libcurl considers any connection that +matches for reuse. The \fICURLOPT_MAXLIFETIME_CONN(3)\fP limit prevents +libcurl from trying too old connections for reuse. This can be used for +client-side load balancing. If a connection is found in the cache that is +older than this set \fImaxlifetime\fP, it is instead marked for closure. If set to 0, this behavior is disabled: all connections are eligible for reuse. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 b/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 index bd1108931c..7191f7da7d 100644 --- a/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 +++ b/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 @@ -32,14 +32,15 @@ CURLOPT_MAXREDIRS \- maximum number of redirects allowed CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXREDIRS, long amount); .fi .SH DESCRIPTION -Pass a long. The set number will be the redirection limit \fIamount\fP. If -that many redirections have been followed, the next redirect will cause an -error (\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the +Pass a long. The set number is the redirection limit \fIamount\fP. If that +many redirections have been followed, the next redirect triggers the error +(\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the \fICURLOPT_FOLLOWLOCATION(3)\fP is used at the same time. -Setting the limit to 0 will make libcurl refuse any redirect. +Setting the limit to 0 makes libcurl refuse any redirect. -Set it to -1 for an infinite number of redirects. +Set it to -1 for an infinite number of redirects. This allows your application +to get stuck in never-ending redirect loops. .SH DEFAULT 30 (since 8.3.0), it was previously unlimited. .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 index 64fd4046cd..6e8d4f87de 100644 --- a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 @@ -32,9 +32,9 @@ CURLOPT_MAX_RECV_SPEED_LARGE \- rate limit data download speed CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_RECV_SPEED_LARGE, curl_off_t maxspeed); .SH DESCRIPTION -Pass a curl_off_t as parameter. If a download exceeds this \fImaxspeed\fP -(counted in bytes per second) the transfer will pause to keep the speed less -than or equal to the parameter value. Defaults to unlimited speed. +Pass a curl_off_t as parameter. If a download exceeds this \fImaxspeed\fP +(counted in bytes per second) the transfer pauses to keep the average speed +less than or equal to the parameter value. Defaults to unlimited speed. This is not an exact science. libcurl attempts to keep the average speed below the given threshold over a period time. diff --git a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 index ab7c6c228f..d9e4bd3a57 100644 --- a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 @@ -32,9 +32,9 @@ CURLOPT_MAX_SEND_SPEED_LARGE \- rate limit data upload speed CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_SEND_SPEED_LARGE, curl_off_t maxspeed); .SH DESCRIPTION -Pass a curl_off_t as parameter with the \fImaxspeed\fP. If an upload exceeds -this speed (counted in bytes per second) the transfer will pause to keep the -speed less than or equal to the parameter value. Defaults to unlimited +Pass a curl_off_t as parameter with the \fImaxspeed\fP. If an upload exceeds +this speed (counted in bytes per second) the transfer pauses to keep the +average speed less than or equal to the parameter value. Defaults to unlimited speed. This is not an exact science. libcurl attempts to keep the average speed below diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 b/docs/libcurl/opts/CURLOPT_MIMEPOST.3 index e8e5433da7..f588f7a380 100644 --- a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 +++ b/docs/libcurl/opts/CURLOPT_MIMEPOST.3 @@ -69,6 +69,6 @@ HTTP, SMTP, IMAP. .SH AVAILABILITY Added in 7.56.0 .SH RETURN VALUE -This will return CURLE_OK. +This returns CURLE_OK. .SH "SEE ALSO" .BR curl_mime_init "(3)" diff --git a/docs/libcurl/opts/CURLOPT_NETRC.3 b/docs/libcurl/opts/CURLOPT_NETRC.3 index 672134b2e4..08d3196341 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC.3 +++ b/docs/libcurl/opts/CURLOPT_NETRC.3 @@ -36,8 +36,8 @@ This parameter controls the preference \fIlevel\fP of libcurl between using user names and passwords from your \fI~/.netrc\fP file, relative to user names and passwords in the URL supplied with \fICURLOPT_URL(3)\fP. -On Windows, libcurl will use the file as \fI%HOME%/_netrc\fP. If \fI%HOME%\fP -is not set on Windows, libcurl falls back to \fI%USERPROFILE%\fP. +On Windows, libcurl uses the file as \fI%HOME%/_netrc\fP. If \fI%HOME%\fP is +not set on Windows, libcurl falls back to \fI%USERPROFILE%\fP. You can also tell libcurl a different file name to use with \fICURLOPT_NETRC_FILE(3)\fP. @@ -54,17 +54,17 @@ standard Unix ftp client does). It should only be readable by user. \fIlevel\fP is a long that should be set to one of the values described below. .IP "CURL_NETRC_IGNORED (0)" -The library will ignore the \fI.netrc\fP file. This is the default. +libcurl ignores the \fI.netrc\fP file. This is the default. .IP "CURL_NETRC_OPTIONAL (1)" The use of the \fI.netrc\fP file is optional, and information in the URL is to -be preferred. The file will be scanned for the host and user name (to find -the password only) or for the host only, to find the first user name and -password after that \fImachine\fP, which ever information is not specified. +be preferred. The file is scanned for the host and user name (to find the +password only) or for the host only, to find the first user name and password +after that \fImachine\fP, which ever information is not specified. .IP "CURL_NETRC_REQUIRED (2)" The use of the \fI.netrc\fP file is required, and any credential information -present in the URL is ignored. The file will be scanned for the host and user -name (to find the password only) or for the host only, to find the first user -name and password after that \fImachine\fP, which ever information is not +present in the URL is ignored. The file is scanned for the host and user name +(to find the password only) or for the host only, to find the first user name +and password after that \fImachine\fP, which ever information is not specified. .SH FILE FORMAT The \fB.netrc\fP file format is simple: you specify lines with a machine name @@ -91,14 +91,14 @@ add a line similar to this in the end: .IP "login " The user name string for the remote machine. .IP "password " -Supply a password. If this token is present, curl will supply the specified +Supply a password. If this token is present, curl supplies the specified string if the remote server requires a password as part of the login process. Note that if this token is present in the .netrc file you really should make sure the file is not readable by anyone besides the user. .IP "macdef " Define a macro. This feature is not supported by libcurl. In order for the -rest of the .netrc to still work fine, libcurl will properly skip every -definition done with "macdef" that it finds. +rest of the .netrc to still work fine, libcurl properly skips every definition +done with "macdef" that it finds. .SH DEFAULT CURL_NETRC_IGNORED .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 b/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 index 105540c982..1a05540a6a 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 +++ b/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 @@ -35,8 +35,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC_FILE, char *file); Pass a char * as parameter, pointing to a null-terminated string containing the full path name to the \fIfile\fP you want libcurl to use as .netrc file. If this option is omitted, and \fICURLOPT_NETRC(3)\fP is set, libcurl -will attempt to find a .netrc file in the current user's home -directory. +checks for a .netrc file in the current user's home directory. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 index e6e80311ee..4f0dfd43e0 100644 --- a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 +++ b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 @@ -32,8 +32,8 @@ CURLOPT_NEW_DIRECTORY_PERMS \- permissions for remotely created directories CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_DIRECTORY_PERMS, long mode); .SH DESCRIPTION -Pass a long as a parameter, containing the value of the permissions that will -be assigned to newly created directories on the remote server. The default value is +Pass a long as a parameter, containing the value of the permissions that is +set on newly created directories on the remote server. The default value is \fI0755\fP, but any valid value can be used. The only protocols that can use this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 index ec798e957a..765064dd4b 100644 --- a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 +++ b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 @@ -32,8 +32,8 @@ CURLOPT_NEW_FILE_PERMS \- permissions for remotely created files CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_FILE_PERMS, long mode); .SH DESCRIPTION -Pass a long as a parameter, containing the value of the permissions that will -be assigned to newly created files on the remote server. The default value is +Pass a long as a parameter, containing the value of the permissions that are +set on newly created files on the remote server. The default value is \fI0644\fP, but any valid value can be used. The only protocols that can use this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_NOBODY.3 b/docs/libcurl/opts/CURLOPT_NOBODY.3 index f190ff6f94..551744f033 100644 --- a/docs/libcurl/opts/CURLOPT_NOBODY.3 +++ b/docs/libcurl/opts/CURLOPT_NOBODY.3 @@ -38,16 +38,16 @@ libcurl do a HEAD request. For most other protocols it means just not asking to transfer the body data. For HTTP operations when \fICURLOPT_NOBODY(3)\fP has been set, disabling this -option (with 0) will make it a GET again - only if the method is still set to -be HEAD. The proper way to get back to a GET request is to set +option (with 0) makes it a GET again - only if the method is still set to be +HEAD. The proper way to get back to a GET request is to set \fICURLOPT_HTTPGET(3)\fP and for other methods, use the POST or UPLOAD options. Enabling \fICURLOPT_NOBODY(3)\fP means asking for a download without a body. -If you do a transfer with HTTP that involves a method other than HEAD, you -will get a body (unless the resource and server sends a zero byte body for the -specific URL you request). +If you do a transfer with HTTP that involves a method other than HEAD, you get +a body (unless the resource and server sends a zero byte body for the specific +URL you request). .SH DEFAULT 0, the body is transferred .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 b/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 index 7c3794a067..216b573177 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 +++ b/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 @@ -33,7 +33,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROGRESS, long onoff); .fi .SH DESCRIPTION If \fIonoff\fP is to 1, it tells the library to shut off the progress meter -completely for requests done with this \fIhandle\fP. It will also prevent the +completely for requests done with this \fIhandle\fP. It also prevents the \fICURLOPT_XFERINFOFUNCTION(3)\fP or \fICURLOPT_PROGRESSFUNCTION(3)\fP from getting called. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_NOPROXY.3 b/docs/libcurl/opts/CURLOPT_NOPROXY.3 index 50157f97f9..bd07d0e648 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROXY.3 +++ b/docs/libcurl/opts/CURLOPT_NOPROXY.3 @@ -40,9 +40,9 @@ list is matched as either a domain which contains the hostname, or the hostname itself. For example, "ample.com" would match ample.com, ample.com:80, and www.ample.com, but not www.example.com or ample.com.org. -Setting the \fInoproxy\fP string to "" (an empty string) will explicitly -enable the proxy for all host names, even if there is an environment variable -set for it. +Setting the \fInoproxy\fP string to "" (an empty string) explicitly enables +the proxy for all host names, even if there is an environment variable set for +it. Enter IPv6 numerical addresses in the list of host names without enclosing brackets: @@ -57,9 +57,9 @@ would match all addresses starting with "192.168". The application does not have to keep the string around after setting this option. .SH "Environment variables" -If there's an environment variable called \fBno_proxy\fP (or \fBNO_PROXY\fP), -it will be used if the \fICURLOPT_NOPROXY(3)\fP option is not set. It works -exactly the same way. +If there is an environment variable called \fBno_proxy\fP (or \fBNO_PROXY\fP), +it is used if the \fICURLOPT_NOPROXY(3)\fP option is not set. It works exactly +the same way. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 index f6c69aa77e..2ab15c2b6e 100644 --- a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 +++ b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 @@ -32,16 +32,16 @@ CURLOPT_NOSIGNAL \- skip all signal handling CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOSIGNAL, long onoff); .fi .SH DESCRIPTION -If \fIonoff\fP is 1, libcurl will not use any functions that install signal -handlers or any functions that cause signals to be sent to the process. This -option is here to allow multi-threaded unix applications to still set/use all -timeout options etc, without risking getting signals. +If \fIonoff\fP is 1, libcurl uses no functions that install signal handlers or +any functions that cause signals to be sent to the process. This option is +here to allow multi-threaded unix applications to still set/use all timeout +options etc, without risking getting signals. If this option is set and libcurl has been built with the standard name -resolver, timeouts will not occur while the name resolve takes place. -Consider building libcurl with the c-ares or threaded resolver backends to -enable asynchronous DNS lookups, to enable timeouts for name resolves without -the use of signals. +resolver, timeouts cannot occur while the name resolve takes place. Consider +building libcurl with the c-ares or threaded resolver backends to enable +asynchronous DNS lookups, to enable timeouts for name resolves without the use +of signals. Setting \fICURLOPT_NOSIGNAL(3)\fP to 1 makes libcurl NOT ask the system to ignore SIGPIPE signals, which otherwise are sent by the system when trying to diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 index a4811f56d0..dc1b27a92a 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 @@ -32,7 +32,7 @@ CURLOPT_OPENSOCKETDATA \- pointer passed to open socket callback CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETDATA, void *pointer); .fi .SH DESCRIPTION -Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first +Pass a \fIpointer\fP that is untouched by libcurl and passed as the first argument in the open socket callback set with \fICURLOPT_OPENSOCKETFUNCTION(3)\fP. .SH DEFAULT @@ -63,7 +63,7 @@ static int sockopt_callback(void *clientp, curl_socket_t curlfd, curl = curl_easy_init(); if(curl) { - /* libcurl will internally think that you connect to the host + /* libcurl thinks that you connect to the host * and port that you specify in the URL option. */ curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); /* call this function to get a socket */ diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 index 93ee859b7f..f936271d0e 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 @@ -64,8 +64,8 @@ is allowed to modify the address or refuse to connect completely. The callback function should return the newly created socket or \fICURL_SOCKET_BAD\fP in case no connection could be established or another error was detected. Any additional \fIsetsockopt(2)\fP calls can of course be done on the socket at -the user's discretion. A \fICURL_SOCKET_BAD\fP return value from the callback -function will signal an unrecoverable error to libcurl and it will return +the user's discretion. A \fICURL_SOCKET_BAD\fP return value from the callback +function signals an unrecoverable error to libcurl and it returns \fICURLE_COULDNT_CONNECT\fP from the function that triggered this callback. This return code can be used for IP address block listing. @@ -103,7 +103,7 @@ static int sockopt_callback(void *clientp, curl_socket_t curlfd, curl = curl_easy_init(); if(curl) { - /* libcurl will internally think that you connect to the host + /* libcurl thinks that you connect to the host * and port that you specify in the URL option. */ curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); /* call this function to get a socket */ diff --git a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 index e02683b0a1..8545fb4d74 100644 --- a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 +++ b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 @@ -43,7 +43,10 @@ Some server implementations are known to (erroneously) require the dot dot sequences to remain in the path and some clients want to pass these on in order to try out server implementations. -By default libcurl will merge such sequences before using the path. +By default libcurl normalizes such sequences before using the path. + +The corresponding flag for the \fIcurl_url_set(3)\fP function is called +\fBCURLU_PATH_AS_IS\fP. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 index 3c317e1232..dd5e5dc871 100644 --- a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 @@ -40,8 +40,8 @@ The string can also be 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. On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned. diff --git a/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 b/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 index 6402e3b768..5a73fed1b2 100644 --- a/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 +++ b/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_PIPEWAIT 3 "12 May 2015" libcurl libcurl .SH NAME -CURLOPT_PIPEWAIT \- wait for pipelining/multiplexing +CURLOPT_PIPEWAIT \- wait for multiplexing .SH SYNOPSIS .nf #include @@ -33,22 +33,21 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PIPEWAIT, long wait); .fi .SH DESCRIPTION Set \fIwait\fP to 1L to tell libcurl to prefer to wait for a connection to -confirm or deny that it can do pipelining or multiplexing before continuing. +confirm or deny that it can do multiplexing before continuing. -When about to perform a new transfer that allows pipelining or multiplexing, -libcurl will check for existing connections to re-use and pipeline on. If no -such connection exists it will immediately continue and create a fresh new -connection to use. +When about to perform a new transfer that allows multiplexing, libcurl checks +for existing connections to use. If no such connection exists it immediately +continues and creates a fresh new connection to use. By setting this option to 1 - and having \fICURLMOPT_PIPELINING(3)\fP enabled -for the multi handle this transfer is associated with - libcurl will instead -wait for the connection to reveal if it is possible to pipeline/multiplex on -before it continues. This enables libcurl to much better keep the number of -connections to a minimum when using pipelining or multiplexing protocols. +for the multi handle this transfer is associated with - libcurl instead waits +for the connection to reveal if it is possible to multiplex on before it +continues. This enables libcurl to much better keep the number of connections +to a minimum when using multiplexing protocols. -The effect thus becomes that with this option set, libcurl prefers to wait and -re-use an existing connection for pipelining rather than the opposite: prefer -to open a new connection rather than waiting. +With this option set, libcurl prefers to wait and reuse an existing connection +for multiplexing rather than the opposite: prefer to open a new connection +rather than waiting. The waiting time is as long as it takes for the connection to get up and for libcurl to get the necessary response back that informs it about its protocol diff --git a/docs/libcurl/opts/CURLOPT_PORT.3 b/docs/libcurl/opts/CURLOPT_PORT.3 index 320f9ed8b6..ceee890cc4 100644 --- a/docs/libcurl/opts/CURLOPT_PORT.3 +++ b/docs/libcurl/opts/CURLOPT_PORT.3 @@ -43,7 +43,7 @@ Usually, you just let the URL decide which port to use but this allows the application to override that. While this option accepts a 'long', a port number is an unsigned 16 bit number -and therefore using a port number lower than zero or over 65535 will cause a +and therefore using a port number lower than zero or over 65535 causes a \fBCURLE_BAD_FUNCTION_ARGUMENT\fP error. .SH DEFAULT By default this is 0 which makes it not used. This also makes port number zero diff --git a/docs/libcurl/opts/CURLOPT_POST.3 b/docs/libcurl/opts/CURLOPT_POST.3 index a6f0acbe41..e824ef7ab7 100644 --- a/docs/libcurl/opts/CURLOPT_POST.3 +++ b/docs/libcurl/opts/CURLOPT_POST.3 @@ -32,9 +32,9 @@ CURLOPT_POST \- make an HTTP POST CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POST, long post); .fi .SH DESCRIPTION -A parameter set to 1 tells libcurl to do a regular HTTP post. This will also -make the library use a "Content-Type: application/x-www-form-urlencoded" -header. (This is by far the most commonly used POST method). +A parameter set to 1 tells libcurl to do a regular HTTP post. This also makes +libcurl use a "Content-Type: application/x-www-form-urlencoded" header. This +is the most commonly used POST method. Use one of \fICURLOPT_POSTFIELDS(3)\fP or \fICURLOPT_COPYPOSTFIELDS(3)\fP options to specify what data to post and \fICURLOPT_POSTFIELDSIZE(3)\fP or @@ -59,14 +59,14 @@ If you use POST to an HTTP 1.1 server, you can send data without knowing the size before starting the POST if you use chunked encoding. You enable this by adding a header like "Transfer-Encoding: chunked" with \fICURLOPT_HTTPHEADER(3)\fP. With HTTP 1.0 or without chunked transfer, you -must specify the size in the request. (Since 7.66.0, libcurl will -automatically use chunked encoding for POSTs if the size is unknown.) +must specify the size in the request. (Since 7.66.0, libcurl automatically +uses chunked encoding for POSTs if the size is unknown.) -When setting \fICURLOPT_POST(3)\fP to 1, libcurl will automatically set +When setting \fICURLOPT_POST(3)\fP to 1, libcurl automatically sets \fICURLOPT_NOBODY(3)\fP and \fICURLOPT_HTTPGET(3)\fP to 0. If you issue a POST request and then want to make a HEAD or GET using the same -re-used handle, you must explicitly set the new request type using +reused handle, you must explicitly set the new request type using \fICURLOPT_NOBODY(3)\fP or \fICURLOPT_HTTPGET(3)\fP or similar. When setting \fICURLOPT_POST(3)\fP to 0, libcurl resets the request type to diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 index 73be852888..6efcf31139 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 @@ -32,19 +32,19 @@ CURLOPT_POSTFIELDS \- data to POST to server CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata); .fi .SH DESCRIPTION -Pass a char * as parameter, pointing to the full data to send in an HTTP POST -operation. You must make sure that the data is formatted the way you want the -server to receive it. libcurl will not convert or encode it for you in any -way. For example, the web server may assume that this data is URL encoded. +Pass a char * as parameter, pointing to the data buffer to use in an HTTP POST +operation. The data must be formatted and encoded the way you want the server +to receive it. libcurl does not convert or encode it in any way. For example, +the web server may assume that this data is URL encoded. The data pointed to is NOT copied by the library: as a consequence, it must be preserved by the calling application until the associated transfer finishes. -This behavior can be changed (so libcurl does copy the data) by setting the -\fICURLOPT_COPYPOSTFIELDS(3)\fP option. +This behavior can be changed (so libcurl does copy the data) by instead using +the \fICURLOPT_COPYPOSTFIELDS(3)\fP option. This POST is a normal \fBapplication/x-www-form-urlencoded\fP kind (and -libcurl will set that Content-Type by default when this option is used), which -is commonly used by HTML forms. Change Content-Type with +libcurl sets that Content-Type by default when this option is used), which is +commonly used by HTML forms. Change Content-Type with \fICURLOPT_HTTPHEADER(3)\fP. You can use \fIcurl_easy_escape(3)\fP to URL encode your data, if @@ -53,19 +53,19 @@ necessary. It returns a pointer to an encoded string that can be passed as Using \fICURLOPT_POSTFIELDS(3)\fP implies setting \fICURLOPT_POST(3)\fP to 1. -If \fICURLOPT_POSTFIELDS(3)\fP is explicitly set to NULL then libcurl will get -the POST data from the read callback. If you want to send a zero-byte POST set -\fICURLOPT_POSTFIELDS(3)\fP to an empty string, or set \fICURLOPT_POST(3)\fP to -1 and \fICURLOPT_POSTFIELDSIZE(3)\fP to 0. +If \fICURLOPT_POSTFIELDS(3)\fP is explicitly set to NULL then libcurl gets the +POST data from the read callback. If you want to send a zero-byte POST set +\fICURLOPT_POSTFIELDS(3)\fP to an empty string, or set \fICURLOPT_POST(3)\fP +to 1 and \fICURLOPT_POSTFIELDSIZE(3)\fP to 0. -libcurl will use assume this option points to a null-terminated string unless -you also set \fICURLOPT_POSTFIELDSIZE(3)\fP to specify the length of the -provided data, which then is strictly required if you want to send off null -bytes included in the data. +libcurl assumes this option points to a null-terminated string unless you also +set \fICURLOPT_POSTFIELDSIZE(3)\fP to specify the length of the provided data, +which then is strictly required if you want to send off null bytes included in +the data. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header, -and libcurl will add that header automatically if the POST is either known to -be larger than 1MB or if the expected size is unknown. You can disable this +and libcurl adds that header automatically if the POST is either known to be +larger than 1MB or if the expected size is unknown. You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. To make \fBmultipart/formdata\fP posts, check out the @@ -76,20 +76,41 @@ NULL HTTP .SH EXAMPLE .nf +/* send an application/x-www-form-urlencoded POST */ CURL *curl = curl_easy_init(); if(curl) { const char *data = "data to send"; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - /* size of the POST data */ + /* size of the POST data if strlen() is not good enough */ curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); - /* pass in a pointer to the data - libcurl will not copy */ + /* pass in a pointer to the data - libcurl does not copy */ curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); curl_easy_perform(curl); } + +/* send an application/json POST */ +CURL *curl = curl_easy_init(); +if(curl) { + const char *json = "{\"name\": \"daniel\"}"; + struct curl_slist *slist1 = NULL; + slist1 = curl_slist_append(slist1, "Content-Type: application/json"); + slist1 = curl_slist_append(slist1, "Accept: application/json"); + + /* set custom headers */ + curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, slist1); + + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* pass in a pointer to the data - libcurl does not copy */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json); + + curl_easy_perform(curl); +} + .fi .SH AVAILABILITY Always diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 index 20adcb591c..37847b5eac 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 @@ -35,8 +35,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE, long size); If you want to post static data to the server without having libcurl do a strlen() to measure the data size, this option must be used. When this option is used you can post fully binary data, which otherwise is likely to fail. If -this size is set to -1, the library will use strlen() to get the size or rely -on the \fICURLOPT_READFUNCTION\fP (if used) to signal the end of data. +this size is set to -1, libcurl uses strlen() to get the size or relies on the +\fICURLOPT_READFUNCTION\fP (if used) to signal the end of data. If you post more than 2GB, use \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 index 6680d745c2..aa047f9a4a 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 @@ -35,8 +35,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE_LARGE, If you want to post static data to the server without having libcurl do a strlen() to measure the data size, this option must be used. When this option is used you can post fully binary data, which otherwise is likely to fail. If -this size is set to -1, the library will use strlen() to get the size or rely -on the \fICURLOPT_READFUNCTION\fP (if used) to signal the end of data. +this size is set to -1, libcurl uses strlen() to get the size or relies on the +\fICURLOPT_READFUNCTION\fP (if used) to signal the end of data. .SH DEFAULT -1 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 b/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 index 7dce326a6e..629477a6b5 100644 --- a/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 +++ b/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 @@ -34,8 +34,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTQUOTE, .fi .SH DESCRIPTION Pass a pointer to a linked list of FTP or SFTP commands to pass to the server -after your FTP transfer request. The commands will only be run if no error -occurred. The linked list should be a fully valid list of struct curl_slist +after your FTP transfer request. The commands are only issues if no error +occur. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for \fICURLOPT_QUOTE(3)\fP. Disable this operation again by setting a NULL to this option. diff --git a/docs/libcurl/opts/CURLOPT_PREREQDATA.3 b/docs/libcurl/opts/CURLOPT_PREREQDATA.3 index fe8d3e62d3..b7d620db4e 100644 --- a/docs/libcurl/opts/CURLOPT_PREREQDATA.3 +++ b/docs/libcurl/opts/CURLOPT_PREREQDATA.3 @@ -32,9 +32,8 @@ CURLOPT_PREREQDATA \- pointer passed to the pre-request callback CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, void *pointer); .fi .SH DESCRIPTION -Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first -argument in the pre-request callback set with -\fICURLOPT_PREREQFUNCTION(3)\fP. +Pass a \fIpointer\fP that is untouched by libcurl and passed as the first +argument in the pre-request callback set with \fICURLOPT_PREREQFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 b/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 index 3a490de9ff..982e1991c1 100644 --- a/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 +++ b/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 @@ -39,8 +39,8 @@ numerical IP address. A numerical IPv6 address must be written within To specify port number in this string, append :[port] to the end of the host name. The proxy's port number may optionally be specified with the separate -option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl will default to -using port 1080 for proxies. +option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl defaults to using +port 1080 for proxies. A pre proxy is a SOCKS proxy that curl connects to before it connects to the HTTP(S) proxy specified in the \fICURLOPT_PROXY\fP option. The pre proxy can @@ -52,15 +52,15 @@ one to enable socks5 and asking the proxy to do the resolving, also known as \fICURLPROXY_SOCKS5_HOSTNAME\fP type) to request the specific SOCKS version to be used. Otherwise SOCKS4 is used as default. -Setting the pre proxy string to "" (an empty string) will explicitly disable -the use of a pre proxy. +Setting the pre proxy string to "" (an empty string) explicitly disables the +use of a pre proxy. The application does not have to keep the string around after setting this option. .SH DEFAULT Default is NULL, meaning no pre proxy is used. -When you set a host name to use, do not assume that there's any particular +When you set a host name to use, do not assume that there is any particular single port number used widely for proxies. Specify it! .SH PROTOCOLS All except file://. Note that some protocols do not work well over proxy. diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 index 1cfebe6dd9..f85c68d047 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 +++ b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 @@ -32,7 +32,7 @@ CURLOPT_PROGRESSDATA \- pointer passed to the progress callback CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSDATA, void *pointer); .fi .SH DESCRIPTION -Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first +Pass a \fIpointer\fP that is untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION(3)\fP. .SH DEFAULT The default value of this parameter is NULL. diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 index adae5bdb06..9f7a865c75 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 @@ -46,34 +46,34 @@ This option is deprecated and we encourage users to use the newer \fICURLOPT_XFERINFOFUNCTION(3)\fP instead, if you can. This function gets called by libcurl instead of its internal equivalent with a -frequent interval. While data is being transferred it will be called -frequently, and during slow periods like when nothing is being transferred it -can slow down to about one call per second. +frequent interval. While data is being transferred it is invoked frequently, +and during slow periods like when nothing is being transferred it can slow +down to about one call per second. \fIclientp\fP is the pointer set with \fICURLOPT_PROGRESSDATA(3)\fP, it is not used by libcurl but is only passed along from the application to the callback. -The callback gets told how much data libcurl will transfer and has +The callback gets told how much data libcurl is about to transfer and has transferred, in number of bytes. \fIdltotal\fP is the total number of bytes libcurl expects to download in this transfer. \fIdlnow\fP is the number of bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl expects to upload in this transfer. \fIulnow\fP is the number of bytes uploaded so far. -Unknown/unused argument values passed to the callback will be set to zero -(like if you only download data, the upload size will remain 0). Many times -the callback will be called one or more times first, before it knows the data -sizes so a program must be made to handle that. +Unknown/unused argument values passed to the callback are be set to zero (like +if you only download data, the upload size remains 0). Many times the callback +is called one or more times first, before it knows the data sizes so a program +must be made to handle that. -If your callback function returns CURL_PROGRESSFUNC_CONTINUE it will cause -libcurl to continue executing the default progress function. +If your callback function returns CURL_PROGRESSFUNC_CONTINUE it causes libcurl +to continue executing the default progress function. -Returning any other non-zero value from this callback will cause libcurl to -abort the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. +Returning any other non-zero value from this callback makes libcurl abort the +transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. -If you transfer data with the multi interface, this function will not be -called during periods of idleness unless you call the appropriate libcurl -function that performs transfers. +If you transfer data with the multi interface, this function is not called +during periods of idleness unless you call the appropriate libcurl function +that performs transfers. \fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually get called. diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 b/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 index 07d3d4434a..2f35e538ce 100644 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 @@ -39,8 +39,8 @@ available protocols! Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask limits what protocols libcurl may use in the transfer. This allows you to have a libcurl built to support a wide range of protocols but still limit specific -transfers to only be allowed to use a subset of them. By default libcurl will -accept all protocols it supports (\fICURLPROTO_ALL\fP). See also +transfers to only be allowed to use a subset of them. By default libcurl +accepts all protocols it supports (\fICURLPROTO_ALL\fP). See also \fICURLOPT_REDIR_PROTOCOLS(3)\fP. These are the available protocol defines: diff --git a/docs/libcurl/opts/CURLOPT_PROXY.3 b/docs/libcurl/opts/CURLOPT_PROXY.3 index db8d46639f..bdd59add95 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY.3 @@ -32,14 +32,15 @@ CURLOPT_PROXY \- proxy to use CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy); .fi .SH DESCRIPTION -Set the \fIproxy\fP to use for the upcoming request. The parameter should be a -char * to a null-terminated string holding the host name or dotted numerical -IP address. A numerical IPv6 address must be written within [brackets]. +Set the \fIproxy\fP to use for transfers with this easy handle. The parameter +should be a char * to a null-terminated string holding the host name or dotted +numerical IP address. A numerical IPv6 address must be written within +[brackets]. To specify port number in this string, append :[port] to the end of the host -name. The proxy's port number may optionally be specified with the separate -option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl will default to -using port 1080 for proxies. +name. The proxy's port number may optionally (but discouraged) be specified +with the separate option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl +defaults to using port 1080 for proxies. The proxy string may be prefixed with [scheme]:// to specify which kind of proxy is used. @@ -52,7 +53,7 @@ HTTPS Proxy. (Added in 7.52.0 for OpenSSL and GnuTLS Since 7.87.0, it also works for BearSSL, mbedTLS, rustls, Schannel, Secure Transport and wolfSSL.) -This will use HTTP/1 by default. Setting \fICURLOPT_PROXYTYPE(3)\fP to +This uses HTTP/1 by default. Setting \fICURLOPT_PROXYTYPE(3)\fP to \fBCURLPROXY_HTTPS2\fP allows libcurl to negotiate using HTTP/2 with proxy. .IP socks4:// SOCKS4 Proxy. @@ -67,15 +68,15 @@ SOCKS5 Proxy. Proxy resolves URL hostname. Without a scheme prefix, \fICURLOPT_PROXYTYPE(3)\fP can be used to specify which kind of proxy the string identifies. -When you tell the library to use an HTTP proxy, libcurl will transparently -convert operations to HTTP even if you specify an FTP URL etc. This may have -an impact on what other features of the library you can use, such as +When you tell the library to use an HTTP proxy, libcurl transparently converts +operations to HTTP even if you specify an FTP URL etc. This may have an impact +on what other features of the library you can use, such as \fICURLOPT_QUOTE(3)\fP and similar FTP specifics that do not work unless you tunnel through the HTTP proxy. Such tunneling is activated with \fICURLOPT_HTTPPROXYTUNNEL(3)\fP. -Setting the proxy string to "" (an empty string) will explicitly disable the -use of a proxy, even if there is an environment variable set for it. +Setting the proxy string to "" (an empty string) explicitly disables the use +of a proxy, even if there is an environment variable set for it. A proxy host string can also include protocol scheme (http://) and embedded user + password. @@ -90,7 +91,7 @@ When a proxy is used, the active FTP mode as set with \fICUROPT_FTPPORT(3)\fP, cannot be used. .SH "Environment variables" libcurl respects the proxy environment variables named \fBhttp_proxy\fP, -\fBftp_proxy\fP, \fBsftp_proxy\fP etc. If set, libcurl will use the specified +\fBftp_proxy\fP, \fBsftp_proxy\fP etc. If set, libcurl uses the specified proxy for that URL scheme. So for a "FTP://" URL, the \fBftp_proxy\fP is considered. \fBall_proxy\fP is used if no protocol specific proxy was set. @@ -102,7 +103,7 @@ environment variables. .SH DEFAULT Default is NULL, meaning no proxy is used. -When you set a host name to use, do not assume that there's any particular +When you set a host name to use, do not assume that there is any particular single port number used widely for proxies. Specify it! .SH PROTOCOLS All except file://. Note that some protocols do not work well over proxy. diff --git a/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 b/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 index 96be78aeb5..f37197c269 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 @@ -34,11 +34,11 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYAUTH, long bitmask); .SH DESCRIPTION Pass a long as parameter, which is set to a bitmask, to tell libcurl which HTTP authentication method(s) you want it to use for your proxy -authentication. If more than one bit is set, libcurl will first query the -site to see what authentication methods it supports and then pick the best one -you allow it to use. For some methods, this will induce an extra network -round-trip. Set the actual name and password with the -\fICURLOPT_PROXYUSERPWD(3)\fP option. +authentication. If more than one bit is set, libcurl first queries the site to +see what authentication methods it supports and then it picks the best one you +allow it to use. For some methods, this induces an extra network round-trip. +Set the actual name and password with the \fICURLOPT_PROXYUSERPWD(3)\fP +option. The bitmask can be constructed by the bits listed and described in the \fICURLOPT_HTTPAUTH(3)\fP man page. diff --git a/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 b/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 index 1320cbc31a..47b5f33af7 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 @@ -37,12 +37,12 @@ sent to a proxy. The rules for this list is identical to the \fICURLOPT_HTTPHEADER(3)\fP option's. The headers set with this option is only ever used in requests sent to a proxy -- when there's also a request sent to a host. +- when there is also a request sent to a host. The first line in a request (containing the method, usually a GET or POST) is NOT a header and cannot be replaced using this option. Only the lines following the request-line are headers. Adding this method line in this list -of headers will only cause your request to send an invalid header. +of headers causes your request to send an invalid header. Pass a NULL to this to reset back to no custom headers. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 index d31721eddb..fee96ebd58 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 @@ -33,8 +33,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERPWD, char *userpwd); .fi .SH DESCRIPTION Pass a char * as parameter, which should be [user name]:[password] to use for -the connection to the HTTP proxy. Both the name and the password will be URL -decoded before use, so to include for example a colon in the user name you +the connection to the HTTP proxy. Both the name and the password are URL +decoded before used, so to include for example a colon in the user name you should encode it as %3A. (This is different to how \fICURLOPT_USERPWD(3)\fP is used - beware.) diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 index a66954bf90..5f871e90e9 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 @@ -46,9 +46,9 @@ certificate bundle is assumed to be stored, as established at build time. (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. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 index 3f6d85c75f..23343ffe80 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 @@ -34,10 +34,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_KEYPASSWD, char *pwd); .SH DESCRIPTION This option is for connecting to an HTTPS proxy, not an HTTPS server. -Pass a pointer to a null-terminated string as parameter. It will be used as -the password required to use the \fICURLOPT_PROXY_SSLKEY(3)\fP private key. -You never need a pass phrase to load a certificate but you need one to load -your private key. +Pass a pointer to a null-terminated string as parameter. It is used as the +password required to use the \fICURLOPT_PROXY_SSLKEY(3)\fP private key. You +never need a pass phrase to load a certificate but you need one to load your +private key. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 index dd8d9fdda5..1d17551000 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 @@ -39,8 +39,8 @@ The string can also be any number of base64 encoded sha256 hashes preceded by When negotiating a TLS or SSL connection, the https proxy 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, libcurl +aborts the connection before sending or receiving any data. On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 index 2bbc30a1ca..08c8c86ab3 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 @@ -39,7 +39,7 @@ when connecting to an HTTPS proxy. Use one of the available defines for this purpose. The available options are: .RS .IP CURL_SSLVERSION_DEFAULT -The default action. This will attempt to figure out the remote SSL protocol +The default action. This attempts to figure out the remote SSL protocol version. .IP CURL_SSLVERSION_TLSv1 TLSv1.x diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 index e89b46c89b..88acfe370c 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 @@ -53,7 +53,7 @@ etc. With BearSSL you do not add/remove ciphers. If one uses this option then all known ciphers are disabled and only those passed in are enabled. -you will find more details about cipher lists on this URL: +Find more details about cipher lists on this URL: https://curl.se/docs/ssl-ciphers.html diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 index 5cb9a5c648..7097842cdc 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 @@ -51,7 +51,7 @@ Untrusted Publishers block list which it seems cannot be bypassed. (Added in 7.44.0) .IP CURLSSLOPT_NO_PARTIALCHAIN Tells libcurl to not accept "partial" certificate chains, which it otherwise -does by default. This option is only supported for OpenSSL and will fail the +does by default. This option is only supported for OpenSSL and fails the certificate verification if the chain ends with an intermediate certificate and not with a root cert. (Added in 7.68.0) .IP CURLSSLOPT_REVOKE_BEST_EFFORT diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 index 1af44c0186..01a603b202 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 @@ -38,7 +38,7 @@ suites to use for the TLS 1.3 connection to a proxy. The list must be syntactically correct, it consists of one or more cipher suite strings separated by colons. -you will find more details about cipher lists on this URL: +Find more details about cipher lists on this URL: https://curl.se/docs/ssl-ciphers.html diff --git a/docs/libcurl/opts/CURLOPT_QUOTE.3 b/docs/libcurl/opts/CURLOPT_QUOTE.3 index f15396be63..7f842b62c9 100644 --- a/docs/libcurl/opts/CURLOPT_QUOTE.3 +++ b/docs/libcurl/opts/CURLOPT_QUOTE.3 @@ -34,24 +34,24 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_QUOTE, .fi .SH DESCRIPTION Pass a pointer to a linked list of FTP or SFTP commands to pass to the server -prior to your request. This will be done before any other commands are issued -(even before the CWD command for FTP). The linked list should be a fully valid -list of 'struct curl_slist' structs properly filled in with text strings. Use +prior to your request. This is done before any other commands are issued (even +before the CWD command for FTP). The linked list should be a fully valid list +of 'struct curl_slist' structs properly filled in with text strings. Use \fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear the entire list afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a NULL to this option. When speaking to an FTP server, prefix the command with an asterisk (*) to -make libcurl continue even if the command fails as by default libcurl will -stop at first failure. +make libcurl continue even if the command fails as by default libcurl stops at +first failure. The set of valid FTP commands depends on the server (see RFC 959 for a list of mandatory commands). libcurl does not inspect, parse or "understand" the commands passed to the server using this option. If you change connection state, working directory or -similar using quote commands, libcurl will not know about it. +similar using quote commands, libcurl does not know about it. The valid SFTP commands are: .RS diff --git a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 index 0cfc2574b4..1ee5ef1855 100644 --- a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 +++ b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 @@ -54,8 +54,8 @@ if(curl) { } .fi .SH AVAILABILITY -If built with TLS enabled. Only the OpenSSL backend will use this, and only -with OpenSSL versions before 1.1.0. +If built with TLS enabled. Only the OpenSSL backend uses this, and only with +OpenSSL versions before 1.1.0. This option was deprecated in 7.84.0. .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_RANGE.3 b/docs/libcurl/opts/CURLOPT_RANGE.3 index fb1f5a9d3d..cad29a0c63 100644 --- a/docs/libcurl/opts/CURLOPT_RANGE.3 +++ b/docs/libcurl/opts/CURLOPT_RANGE.3 @@ -37,8 +37,8 @@ to retrieve. It should be in the format "X-Y", where either X or Y may be left out and X and Y are byte indexes. HTTP transfers also support several intervals, separated with commas as in -\fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP -server to send the response document in pieces (using standard MIME separation +\fI"X-Y,N-M"\fP. Using this kind of multiple intervals causes the HTTP server +to send the response document in pieces (using standard MIME separation techniques). Unfortunately, the HTTP standard (RFC 7233 section 3.1) allows servers to ignore range requests so even when you set \fICURLOPT_RANGE(3)\fP for a request, you may end up getting the full response sent back. diff --git a/docs/libcurl/opts/CURLOPT_READDATA.3 b/docs/libcurl/opts/CURLOPT_READDATA.3 index a4c7cb8bb5..9040a64f1a 100644 --- a/docs/libcurl/opts/CURLOPT_READDATA.3 +++ b/docs/libcurl/opts/CURLOPT_READDATA.3 @@ -33,15 +33,15 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READDATA, void *pointer); .fi .SH DESCRIPTION Data \fIpointer\fP to pass to the file read function. If you use the -\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you will get as -input in the fourth argument to the callback. +\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you get as input in +the fourth argument to the callback. If you do not specify a read callback but instead rely on the default internal read function, this data must be a valid readable FILE * (cast to 'void *'). -If you are using libcurl as a win32 DLL, you \fBMUST\fP use a -\fICURLOPT_READFUNCTION(3)\fP if you set this option or you will experience -crashes. +If you are using libcurl as a DLL on Windows, you must use the +\fICURLOPT_READFUNCTION(3)\fP callback if you set this option, otherwise you +might experience crashes. .SH DEFAULT By default, this is a FILE * to stdin. .SH PROTOCOLS @@ -64,6 +64,6 @@ if(curl) { This option was once known by the older name CURLOPT_INFILE, the name \fICURLOPT_READDATA(3)\fP was introduced in 7.9.7. .SH RETURN VALUE -This will return CURLE_OK. +This returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_READFUNCTION "(3), " CURLOPT_WRITEDATA "(3), " diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 b/docs/libcurl/opts/CURLOPT_READFUNCTION.3 index cb2860abd9..d3f4f3bb02 100644 --- a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_READFUNCTION.3 @@ -44,14 +44,14 @@ by your function. \fIsize\fP is always 1. Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option. -Your function must return the actual number of bytes that it stored in the data -area pointed at by the pointer \fIbuffer\fP. Returning 0 will signal -end-of-file to the library and cause it to stop the current transfer. +Your function must return the actual number of bytes that it stored in the +data area pointed at by the pointer \fIbuffer\fP. Returning 0 signals +end-of-file to the library and causes it to stop the current transfer. If you stop the current transfer by returning 0 "pre-maturely" (i.e before the -server expected it, like when you have said you will upload N bytes and you +server expected it, like when you have said you would upload N bytes and you upload less than N bytes), you may experience that the server "hangs" waiting -for the rest of the data that will not come. +for the rest of the data that is not sent. The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error @@ -61,12 +61,12 @@ The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this connection to pause. See \fIcurl_easy_pause(3)\fP for further details. \fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data -that the callback wants, or it will be considered the final packet by the -server end and the transfer will end there. +that the callback wants, or it is considered the final packet by the server +end and the transfer ends there. If you set this callback pointer to NULL, or do not set it at all, the default -internal read function will be used. It is doing an fread() on the FILE * -userdata set with \fICURLOPT_READDATA(3)\fP. +internal read function is used. It is doing an fread() on the FILE * userdata +set with \fICURLOPT_READDATA(3)\fP. You can set the total size of the data you are sending by using \fICURLOPT_INFILESIZE_LARGE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP, @@ -112,7 +112,7 @@ void setup(char *uploadthis) CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT was added in 7.12.1. .SH RETURN VALUE -This will return CURLE_OK. +This returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_READDATA "(3), " CURLOPT_WRITEFUNCTION "(3), " .BR CURLOPT_SEEKFUNCTION "(3), " CURLOPT_UPLOAD "(3), " CURLOPT_POST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 index 3238c4cb87..2649407918 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 @@ -45,11 +45,9 @@ redirections. Protocols denied by \fICURLOPT_PROTOCOLS(3)\fP are not overridden by this option. -By default libcurl will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). -Older versions of libcurl allowed all protocols on redirect except several -disabled for security reasons: Since 7.19.4 FILE and SCP are disabled, and -since 7.40.0 SMB and SMBS are also disabled. \fICURLPROTO_ALL\fP enables all -protocols on redirect, including those disabled for security. +By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). +\fICURLPROTO_ALL\fP enables all protocols on redirect, including those +otherwise disabled for security. These are the available protocol defines: .nf diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.3 b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.3 index db41e11964..62629170c1 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.3 +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.3 @@ -43,10 +43,8 @@ redirections. Protocols denied by \fICURLOPT_PROTOCOLS_STR(3)\fP are not overridden by this option. -By default libcurl will allow HTTP, HTTPS, FTP and FTPS on redirects (since -7.65.2). Older versions of libcurl allowed all protocols on redirect except -several disabled for security reasons: Since 7.19.4 FILE and SCP are disabled, -and since 7.40.0 SMB and SMBS are also disabled. +By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects (since +7.65.2). These are the available protocols: diff --git a/docs/libcurl/opts/CURLOPT_REFERER.3 b/docs/libcurl/opts/CURLOPT_REFERER.3 index 53491493d7..f5bc74dd54 100644 --- a/docs/libcurl/opts/CURLOPT_REFERER.3 +++ b/docs/libcurl/opts/CURLOPT_REFERER.3 @@ -32,10 +32,9 @@ CURLOPT_REFERER \- the HTTP referer header CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REFERER, char *where); .fi .SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. It will be used to -set the Referer: header in the http request sent to the remote server. This -can be used to fool servers or scripts. You can also set any custom header -with \fICURLOPT_HTTPHEADER(3)\fP. +Pass a pointer to a null-terminated string as parameter. It is used to set the +Referer: header field in the HTTP request sent to the remote server. You can +set any custom header with \fICURLOPT_HTTPHEADER(3)\fP. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_RESOLVE.3 b/docs/libcurl/opts/CURLOPT_RESOLVE.3 index 2c1b2022a5..7647df50ba 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVE.3 +++ b/docs/libcurl/opts/CURLOPT_RESOLVE.3 @@ -44,24 +44,24 @@ Each resolve rule to add should be written using the format [+]HOST:PORT:ADDRESS[,ADDRESS] .fi -\&... where HOST is the name libcurl will try to resolve, PORT is the port -number of the service where libcurl wants to connect to the HOST and ADDRESS -is one or more numerical IP addresses. If you specify multiple IP addresses -they need to be separated by comma. If libcurl is built to support IPv6, each -of the ADDRESS entries can of course be either IPv4 or IPv6 style addressing. +HOST is the name libcurl wants to resolve, PORT is the port number of the +service where libcurl wants to connect to the HOST and ADDRESS is one or more +numerical IP addresses. If you specify multiple IP addresses they need to be +separated by comma. If libcurl is built to support IPv6, each of the ADDRESS +entries can of course be either IPv4 or IPv6 style addressing. -This option effectively pre-populates the DNS cache with entries for the -host+port pair so redirects and everything that operations against the -HOST+PORT will instead use your provided ADDRESS. +This option effectively populates the DNS cache with entries for the host+port +pair so redirects and everything that operations against the HOST+PORT instead +use your provided ADDRESS. The optional leading "+" specifies that the new entry should time-out. Entries -added without the leading plus character will never time-out whereas entries -added with "+HOST:..." will time-out just like ordinary DNS cache entries. +added without the leading plus character never times out whereas entries added +with "+HOST:..." times out just like ordinary DNS cache entries. If the DNS cache already has an entry for the given host+port pair, the new -entry will override the former one. +entry overrides the former one. -An ADDRESS provided by this option will only be used if not restricted by the +An ADDRESS provided by this option is only used if not restricted by the setting of \fICURLOPT_IPRESOLVE(3)\fP to a different IP version. To remove names from the DNS cache again, to stop providing these fake diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 index 904d8db7d3..52c6844cd7 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 @@ -33,7 +33,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVER_START_DATA, void *pointer); .fi .SH DESCRIPTION -Pass a \fIpointer\fP that will be untouched by libcurl and passed as the third +Pass a \fIpointer\fP is be untouched by libcurl and passed as the third argument in the resolver start callback set with \fICURLOPT_RESOLVER_START_FUNCTION(3)\fP. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 index 0b0addea86..8e2aab1efc 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 @@ -51,8 +51,8 @@ socket callback options. \fIuserdata\fP is the user pointer set with the \fICURLOPT_RESOLVER_START_DATA(3)\fP option. -The callback must return 0 on success. Returning a non-zero value will cause -the resolve to fail. +The callback must return 0 on success. Returning a non-zero value causes the +resolve to fail. .SH DEFAULT NULL (No callback) .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 b/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 index 9b81448a40..ebae1edd02 100644 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 @@ -39,7 +39,7 @@ option to -1 to make the transfer start from the end of the target file (useful to continue an interrupted upload). When doing uploads with FTP, the resume position is where in the local/source -file libcurl should try to resume the upload from and it will then append the +file libcurl should try to resume the upload from and it then appends the source file to the remote target file. If you need to resume a transfer beyond the 2GB limit, use diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 index 33f88a9f10..e8f520b359 100644 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 @@ -39,8 +39,8 @@ option to -1 to make the transfer start from the end of the target file (useful to continue an interrupted upload). When doing uploads with FTP, the resume position is where in the local/source -file libcurl should try to resume the upload from and it will then append the -source file to the remote target file. +file libcurl should try to resume the upload from and it appends the source +file to the remote target file. .SH DEFAULT 0, not used .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 index fd5272f9bb..9c3a81a2cd 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 @@ -32,9 +32,9 @@ CURLOPT_RTSP_CLIENT_CSEQ \- RTSP client CSEQ number CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_CLIENT_CSEQ, long cseq); .fi .SH DESCRIPTION -Pass a long to set the CSEQ number to issue for the next RTSP -request. Useful if the application is resuming a previously broken -connection. The CSEQ will increment from this new number henceforth. +Pass a long to set the CSEQ number to issue for the next RTSP request. Useful +if the application is resuming a previously broken connection. The CSEQ +increments from this new number henceforth. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 index 3ed1220eae..9b3fc84912 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 @@ -42,9 +42,9 @@ for this method. .IP CURL_RTSPREQ_DESCRIBE Used to get the low level description of a stream. The application should note what formats it understands in the \fI'Accept:'\fP header. Unless set -manually, libcurl will automatically fill in \fI'Accept: application/sdp'\fP. -Time-condition headers will be added to Describe requests if the -\fICURLOPT_TIMECONDITION(3)\fP option is active. \fB(The session ID is not +manually, libcurl automatically adds in \fI'Accept: application/sdp'\fP. +Time-condition headers are added to Describe requests if the +\fICURLOPT_TIMECONDITION(3)\fP option is used. \fB(The session ID is not needed for this method)\fP .IP CURL_RTSPREQ_ANNOUNCE When sent by a client, this method changes the description of the session. For @@ -56,9 +56,9 @@ session. ANNOUNCE acts like an HTTP PUT or POST just like Setup is used to initialize the transport layer for the session. The application must set the desired Transport options for a session by using the \fICURLOPT_RTSP_TRANSPORT(3)\fP option prior to calling setup. If no session -ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl will -extract and use the session ID in the response to this request. The session ID -is not needed for this method. +ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl extracts +and uses the session ID in the response to this request. The session ID is not +needed for this method. .IP CURL_RTSPREQ_PLAY Send a Play command to the server. Use the \fICURLOPT_RANGE(3)\fP option to modify the playback time (e.g. \fInpt=10-15\fP). @@ -71,29 +71,30 @@ This command terminates an RTSP session. Simply closing a connection does not terminate the RTSP session since it is valid to control an RTSP session over different connections. .IP CURL_RTSPREQ_GET_PARAMETER -Retrieve a parameter from the server. By default, libcurl will automatically -include a \fIContent-Type: text/parameters\fP header on all non-empty requests -unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST -(see \fICURL_RTSPREQ_SET_PARAMETER\fP). -Applications wishing to send a heartbeat message (e.g. in the presence of a -server-specified timeout) should send use an empty GET_PARAMETER request. +Retrieve a parameter from the server. By default, libcurl adds a +\fIContent-Type: text/parameters\fP header on all non-empty requests unless a +custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see +\fICURL_RTSPREQ_SET_PARAMETER\fP). Applications wishing to send a heartbeat +message (e.g. in the presence of a server-specified timeout) should send use +an empty GET_PARAMETER request. .IP CURL_RTSPREQ_SET_PARAMETER -Set a parameter on the server. By default, libcurl will automatically include -a \fIContent-Type: text/parameters\fP header unless a custom one is set. The -interaction with SET_PARAMETER is much like an HTTP PUT or POST. An application -may either use \fICURLOPT_UPLOAD(3)\fP with \fICURLOPT_READDATA(3)\fP like a -HTTP PUT, or it may use \fICURLOPT_POSTFIELDS(3)\fP like an HTTP POST. No -chunked transfers are allowed, so the application must set the -\fICURLOPT_INFILESIZE(3)\fP in the former and \fICURLOPT_POSTFIELDSIZE(3)\fP -in the latter. Also, there is no use of multi-part POSTs within RTSP. +Set a parameter on the server. By default, libcurl uses a +\fIContent-Type: text/parameters\fP header unless a custom one is set. +The interaction with SET_PARAMETER is much like an HTTP PUT or POST. An +application may either use \fICURLOPT_UPLOAD(3)\fP with +\fICURLOPT_READDATA(3)\fP like a HTTP PUT, or it may use +\fICURLOPT_POSTFIELDS(3)\fP like an HTTP POST. No chunked transfers are +allowed, so the application must set the \fICURLOPT_INFILESIZE(3)\fP in the +former and \fICURLOPT_POSTFIELDSIZE(3)\fP in the latter. Also, there is no use +of multi-part POSTs within RTSP. .IP CURL_RTSPREQ_RECORD Used to tell the server to record a session. Use the \fICURLOPT_RANGE(3)\fP option to modify the record time. .IP CURL_RTSPREQ_RECEIVE This is a special request because it does not send any data to the server. The application may call this function in order to receive interleaved RTP -data. It will return after processing one read buffer of data in order to give -the application a chance to run. +data. It returns after processing one read buffer of data in order to give the +application a chance to run. .SH DEFAULT .SH PROTOCOLS RTSP diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 index aa75b2971f..b895f7c7c3 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 @@ -34,10 +34,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SESSION_ID, char *id); .SH DESCRIPTION Pass a char * as a parameter to set the value of the current RTSP Session ID for the handle. Useful for resuming an in-progress session. Once this value is -set to any non-NULL value, libcurl will return \fICURLE_RTSP_SESSION_ERROR\fP -if ID received from the server does not match. If unset (or set to NULL), -libcurl will automatically set the ID the first time the server sets it in a -response. +set to any non-NULL value, libcurl returns \fICURLE_RTSP_SESSION_ERROR\fP if +ID received from the server does not match. If unset (or set to NULL), libcurl +automatically sets the ID the first time the server sets it in a response. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 index 95f25ab2bc..e0cee0cbed 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 @@ -35,13 +35,13 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_STREAM_URI, char *URI); Set the stream \fIURI\fP to operate on by passing a char * . For example, a single session may be controlling \fIrtsp://foo/twister/audio\fP and \fIrtsp://foo/twister/video\fP and the application can switch to the -appropriate stream using this option. If unset, libcurl will default to -operating on generic server options by passing '*' in the place of the RTSP -Stream URI. This option is distinct from \fICURLOPT_URL(3)\fP. When working -with RTSP, the \fICURLOPT_RTSP_STREAM_URI(3)\fP indicates what URL to send to -the server in the request header while the \fICURLOPT_URL(3)\fP indicates -where to make the connection to. (e.g. the \fICURLOPT_URL(3)\fP for the above -examples might be set to \fIrtsp://foo/twister\fP +appropriate stream using this option. If unset, libcurl defaults to operating +on generic server options by passing '*' in the place of the RTSP Stream +URI. This option is distinct from \fICURLOPT_URL(3)\fP. When working with +RTSP, the \fICURLOPT_RTSP_STREAM_URI(3)\fP indicates what URL to send to the +server in the request header while the \fICURLOPT_URL(3)\fP indicates where to +make the connection to. (e.g. the \fICURLOPT_URL(3)\fP for the above examples +might be set to \fIrtsp://foo/twister\fP The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 index aab3ebf79e..514704c65c 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 +++ b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 @@ -37,9 +37,9 @@ authorization identity (\fIauthzid\fP) for the transfer. Only applicable to the PLAIN SASL authentication mechanism where it is optional. When not specified only the authentication identity (\fIauthcid\fP) as -specified by the username will be sent to the server, along with the -password. The server will derive a \fIauthzid\fP from the \fIauthcid\fP when -not provided, which it will then uses internally. +specified by the username is sent to the server, along with the password. The +server derives a \fIauthzid\fP from the \fIauthcid\fP when not provided, which +it then uses internally. When the \fIauthzid\fP is specified, the use of which is server dependent, it can be used to access another user's inbox, that the user has been granted diff --git a/docs/libcurl/opts/CURLOPT_SASL_IR.3 b/docs/libcurl/opts/CURLOPT_SASL_IR.3 index e48710af5c..e0ff2317cb 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_IR.3 +++ b/docs/libcurl/opts/CURLOPT_SASL_IR.3 @@ -32,10 +32,10 @@ CURLOPT_SASL_IR \- send initial response in first packet CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_IR, long enable); .fi .SH DESCRIPTION -Pass a long. If the value is 1, curl will send the initial response to the -server in the first authentication packet in order to reduce the number of -ping pong requests. Only applicable to the following supporting SASL -authentication mechanisms: +Pass a long. If the value is 1, curl sends the initial response to the server +in the first authentication packet in order to reduce the number of ping pong +requests. Only applicable to the following supporting SASL authentication +mechanisms: * Login * Plain diff --git a/docs/libcurl/opts/CURLOPT_SEEKDATA.3 b/docs/libcurl/opts/CURLOPT_SEEKDATA.3 index 98cdbf37f5..4fe8206334 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKDATA.3 +++ b/docs/libcurl/opts/CURLOPT_SEEKDATA.3 @@ -33,8 +33,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKDATA, void *pointer); .fi .SH DESCRIPTION Data \fIpointer\fP to pass to the seek callback function. If you use the -\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you will get as -input. +\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you get as input. .SH DEFAULT If you do not set this, NULL is passed to the callback. .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_SHARE.3 b/docs/libcurl/opts/CURLOPT_SHARE.3 index f26c9f0253..40e8bf1b0d 100644 --- a/docs/libcurl/opts/CURLOPT_SHARE.3 +++ b/docs/libcurl/opts/CURLOPT_SHARE.3 @@ -34,19 +34,19 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SHARE, CURLSH *share); .SH DESCRIPTION Pass a \fIshare\fP handle as a parameter. The share handle must have been created by a previous call to \fIcurl_share_init(3)\fP. Setting this option, -will make this curl handle use the data from the shared handle instead of -keeping the data to itself. This enables several curl handles to share -data. If the curl handles are used simultaneously in multiple threads, you -\fBMUST\fP use the locking methods in the share handle. See -\fIcurl_share_setopt(3)\fP for details. +makes this curl handle use the data from the shared handle instead of keeping +the data to itself. This enables several curl handles to share data. If the +curl handles are used simultaneously in multiple threads, you \fBMUST\fP use +the locking methods in the share handle. See \fIcurl_share_setopt(3)\fP for +details. -If you add a share that is set to share cookies, your easy handle will use -that cookie cache and get the cookie engine enabled. If you stop sharing an -object that was using cookies (or change to another object that does not share -cookies), the easy handle will get its cookie engine disabled. +If you add a share that is set to share cookies, your easy handle uses that +cookie cache and get the cookie engine enabled. If you stop sharing an object +that was using cookies (or change to another object that does not share +cookies), the easy handle gets its cookie engine disabled. -Data that the share object is not set to share will be dealt with the usual -way, as if no share was used. +Data that the share object is not set to share is dealt with the usual way, as +if no share was used. Set this option to NULL again to stop using that share object. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 index 4c33841e7b..b2e6aa76d1 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 @@ -32,7 +32,7 @@ CURLOPT_SOCKOPTDATA \- pointer to pass to sockopt callback CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTDATA, void *pointer); .fi .SH DESCRIPTION -Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first +Pass a \fIpointer\fP that is untouched by libcurl and passed as the first argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION(3)\fP. .SH DEFAULT The default value of this parameter is NULL. diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 index 3d65434310..b385040178 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 @@ -67,12 +67,11 @@ The \fIclientp\fP pointer contains whatever user-defined value set using the Return \fICURL_SOCKOPT_OK\fP from the callback on success. Return \fICURL_SOCKOPT_ERROR\fP from the callback function to signal an unrecoverable -error to the library and it will close the socket and return -\fICURLE_COULDNT_CONNECT\fP. -Alternatively, the callback function can return +error to the library and it closes the socket and returns +\fICURLE_COULDNT_CONNECT\fP. Alternatively, the callback function can return \fICURL_SOCKOPT_ALREADY_CONNECTED\fP, to tell libcurl that the socket is -already connected and then libcurl will not attempt to connect it. This allows -an application to pass in an already connected socket with +already connected and then libcurl does no attempt to connect. This allows an +application to pass in an already connected socket with \fICURLOPT_OPENSOCKETFUNCTION(3)\fP and then have this function make libcurl not attempt to connect (again). .SH DEFAULT @@ -103,7 +102,7 @@ static int sockopt_callback(void *clientp, curl_socket_t curlfd, curl = curl_easy_init(); if(curl) { - /* libcurl will internally think that you connect to the host + /* libcurl thinks that you connect to the host * and port that you specify in the URL option. */ curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); /* call this function to get a socket */ diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 index 095a10ec8e..def7991625 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 @@ -32,8 +32,8 @@ CURLOPT_SSH_HOSTKEYDATA \- pointer to pass to the SSH host key callback CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOSTKEYDATA, void *pointer); .fi .SH DESCRIPTION -Pass a void * as parameter. This \fIpointer\fP will be passed along verbatim -to the callback set with \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP. +Pass a void * as parameter. This \fIpointer\fP is passed along untouched to +the callback set with \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 index 60a885c363..2772ae8619 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 @@ -34,7 +34,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5, .SH DESCRIPTION Pass a char * pointing to a string containing 32 hexadecimal digits. The string should be the 128 bit MD5 checksum of the remote host's public key, and -libcurl will reject the connection to the host unless the MD5 checksum match. +libcurl aborts the connection to the host unless the MD5 checksum match. + +MD5 is a weak algorithm. We strongly recommend using +\fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP instead. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 index 167526cc06..8d6311d51f 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 @@ -32,10 +32,9 @@ CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 \- SHA256 hash of SSH server public key CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256, char *sha256); .SH DESCRIPTION -Pass a char * pointing to a string containing a Base64-encoded SHA256 -hash of the remote host's public key. -The transfer will fail if the given hash does not match the hash the -remote host provides. +Pass a char * pointing to a string containing a Base64-encoded SHA256 hash of +the remote host's public key. The transfer fails if the given hash does not +match the hash the remote host provides. .SH DEFAULT NULL diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 index 7d21790556..3696ab325e 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 @@ -32,8 +32,8 @@ CURLOPT_SSH_KEYDATA \- pointer passed to the SSH key callback CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYDATA, void *pointer); .fi .SH DESCRIPTION -Pass a void * as parameter. This \fIpointer\fP will be passed along verbatim -to the callback set with \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +Pass a void * as parameter. This \fIpointer\fP is passed along verbatim to the +callback set with \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 index 53bb88e0c9..a8f77827ab 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 @@ -35,7 +35,7 @@ enum curl_khstat { CURLKHSTAT_REJECT, /* reject the connection, return an error */ CURLKHSTAT_DEFER, /* do not accept it, but we cannot answer right now. Causes a CURLE_PEER_FAILED_VERIFICATION error but - the connection will be left intact */ + the connection is left intact */ CURLKHSTAT_FINE_REPLACE }; @@ -66,8 +66,8 @@ Pass a pointer to your callback function, which should match the prototype shown above. It gets called when the known_host matching has been done, to allow the -application to act and decide for libcurl how to proceed. The callback will -only be called if \fICURLOPT_SSH_KNOWNHOSTS(3)\fP is also set. +application to act and decide for libcurl how to proceed. The callback is only +called if \fICURLOPT_SSH_KNOWNHOSTS(3)\fP is also set. This callback function gets passed the CURL handle, the key from the known_hosts file \fIknownkey\fP, the key from the remote site \fIfoundkey\fP, @@ -75,25 +75,25 @@ info from libcurl on the matching status and a custom pointer (set with \fICURLOPT_SSH_KEYDATA(3)\fP). It MUST return one of the following return codes to tell libcurl how to act: .IP CURLKHSTAT_FINE_REPLACE -The new host+key is accepted and libcurl will replace the old host+key into -the known_hosts file before continuing with the connection. This will also -add the new host+key combo to the known_host pool kept in memory if it was not -already present there. The adding of data to the file is done by completely -replacing the file with a new copy, so the permissions of the file must allow +The new host+key is accepted and libcurl replaces the old host+key into the +known_hosts file before continuing with the connection. This also adds the new +host+key combo to the known_host pool kept in memory if it was not already +present there. The adding of data to the file is done by completely replacing +the file with a new copy, so the permissions of the file must allow this. (Added in 7.73.0) .IP CURLKHSTAT_FINE_ADD_TO_FILE -The host+key is accepted and libcurl will append it to the known_hosts file -before continuing with the connection. This will also add the host+key combo -to the known_host pool kept in memory if it was not already present there. The -adding of data to the file is done by completely replacing the file with a new -copy, so the permissions of the file must allow this. +The host+key is accepted and libcurl appends it to the known_hosts file before +continuing with the connection. This also adds the host+key combo to the +known_host pool kept in memory if it was not already present there. The adding +of data to the file is done by completely replacing the file with a new copy, +so the permissions of the file must allow this. .IP CURLKHSTAT_FINE -The host+key is accepted libcurl will continue with the connection. This will -also add the host+key combo to the known_host pool kept in memory if it was not -already present there. +The host+key is accepted libcurl continues with the connection. This also adds +the host+key combo to the known_host pool kept in memory if it was not already +present there. .IP CURLKHSTAT_REJECT -The host+key is rejected. libcurl will deny the connection to continue and it -will be closed. +The host+key is rejected. libcurl denies the connection to continue and it is +closed. .IP CURLKHSTAT_DEFER The host+key is rejected, but the SSH connection is asked to be kept alive. This feature could be used when the app wants to somehow return back and act diff --git a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 index 8c4e1a0c87..6ced1657b4 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 @@ -34,8 +34,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KNOWNHOSTS, char *fname); .SH DESCRIPTION Pass a pointer to a null-terminated string holding the file name of the known_host file to use. The known_hosts file should use the OpenSSH file -format as supported by libssh2. If this file is specified, libcurl will only -accept connections with hosts that are known and present in that file, with a +format as supported by libssh2. If this file is specified, libcurl only +accepts connections with hosts that are known and present in that file, with a matching public key. Use \fICURLOPT_SSH_KEYFUNCTION(3)\fP to alter the default behavior on host and key matches and mismatches. diff --git a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 index c9009740c1..516185493c 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 @@ -37,9 +37,9 @@ libcurl defaults to \fB$HOME/.ssh/id_dsa.pub\fP if the HOME environment variable is set, and just "id_dsa.pub" in the current directory if HOME is not set. -If NULL (or an empty string) is passed, libcurl will pass no public key to -libssh2, which then tries to compute it from the private key. This is known -to work with libssh2 1.4.0+ linked against OpenSSL. +If NULL (or an empty string) is passed, libcurl passes no public key to +libssh2, which then computes it from the private key. This is known to work +with libssh2 1.4.0+ linked against OpenSSL. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE.3 b/docs/libcurl/opts/CURLOPT_SSLENGINE.3 index 56565bb8bb..868cc789af 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE.3 +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE.3 @@ -32,8 +32,8 @@ CURLOPT_SSLENGINE \- SSL engine identifier CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE, char *id); .fi .SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. It will be used as -the identifier for the crypto engine you want to use for your private key. +Pass a pointer to a null-terminated string as parameter. It is used as the +identifier for the crypto engine you want to use for your private key. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_SSLVERSION.3 b/docs/libcurl/opts/CURLOPT_SSLVERSION.3 index 0288dd7d19..3424e629d1 100644 --- a/docs/libcurl/opts/CURLOPT_SSLVERSION.3 +++ b/docs/libcurl/opts/CURLOPT_SSLVERSION.3 @@ -67,9 +67,9 @@ The MAX macros are not supported for WolfSSL. .RS .IP CURL_SSLVERSION_MAX_DEFAULT The flag defines the maximum supported TLS version by libcurl, or the default -value from the SSL library is used. libcurl will use a sensible default -maximum, which was TLS v1.2 up to before 7.61.0 and is TLS v1.3 since then - -assuming the TLS library support it. (Added in 7.54.0) +value from the SSL library is used. libcurl uses a sensible default maximum, +which was TLS v1.2 up to before 7.61.0 and is TLS v1.3 since then - assuming +the TLS library support it. (Added in 7.54.0) .IP CURL_SSLVERSION_MAX_TLSv1_0 The flag defines maximum supported TLS version as TLS v1.0. (Added in 7.54.0) diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 index 15d153cf9c..2e4f77bc1f 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 @@ -55,7 +55,7 @@ known ciphers are disabled and only those passed in are enabled. For Schannel, you can use this option to set algorithms but not specific cipher suites. Refer to the ciphers lists document for algorithms. -You will find more details about cipher lists on this URL: +Find more details about cipher lists on this URL: https://curl.se/docs/ssl-ciphers.html diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 index aa497519b4..5c3a9e0a6f 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 @@ -33,7 +33,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_DATA, void *pointer); .fi .SH DESCRIPTION Data \fIpointer\fP to pass to the ssl context callback set by the option -\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you will get as third +\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you get as third parameter. .SH DEFAULT NULL @@ -99,10 +99,6 @@ int main(void) curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L); curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/"); - /* Retrieve page using cacerts' certificate -> will succeed - * load the certificate by installing a function doing the necessary - * "modifications" to the SSL CONTEXT just before link init - */ curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function); curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem); rv = curl_easy_perform(ch); diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 index 11806de817..663a0868cc 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 @@ -49,12 +49,12 @@ library's \fISSL_CTX\fP for OpenSSL or wolfSSL, a pointer to \fImbedtls_ssl_config\fP for mbedTLS or a pointer to \fIbr_ssl_client_context\fP for BearSSL. If an error is returned from the callback no attempt to establish a connection is made and the perform -operation will return the callback's error code. Set the \fIclientp\fP -argument with the \fICURLOPT_SSL_CTX_DATA(3)\fP option. +operation returns the callback's error code. Set the \fIclientp\fP argument +with the \fICURLOPT_SSL_CTX_DATA(3)\fP option. -This function will get called on all new connections made to a server, during -the SSL negotiation. The \fIssl_ctx\fP will point to a newly initialized object -each time, but note the pointer may be the same as from a prior call. +This function gets called on all new connections made to a server, during the +SSL negotiation. The \fIssl_ctx\fP points to a newly initialized object each +time, but note the pointer may be the same as from a prior call. To use this properly, a non-trivial amount of knowledge of your SSL library is necessary. For example, you can use this function to call library-specific @@ -71,8 +71,8 @@ unknowingly reusing SSL connections with different properties. To remedy this you may set \fICURLOPT_FORBID_REUSE(3)\fP from the callback function. WARNING: If you are using DNS-over-HTTPS (DoH) via \fICURLOPT_DOH_URL(3)\fP -then this callback will also be called for those transfers and the curl handle -is set to an internal handle. \fBThis behavior is subject to change.\fP We +then this callback is also called for those transfers and the curl handle is +set to an internal handle. \fBThis behavior is subject to change.\fP We recommend before performing your transfer set \fICURLOPT_PRIVATE(3)\fP on your curl handle so you can identify it in the context callback. If you have a reason to modify DoH SSL context please let us know on the curl-library @@ -141,10 +141,6 @@ int main(void) curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L); curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/"); - /* Retrieve page using cacerts' certificate -> will succeed - * load the certificate by installing a function doing the necessary - * "modifications" to the SSL CONTEXT just before link init - */ curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function); curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem); rv = curl_easy_perform(ch); diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 index c58decaba7..4d3339e530 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 @@ -35,9 +35,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_FALSESTART, long enable); Pass a long as parameter set to 1L to enable or 0 to disable. This option determines whether libcurl should use false start during the TLS -handshake. False start is a mode where a TLS client will start sending -application data before verifying the server's Finished message, thus saving a -round trip when performing a full handshake. +handshake. False start is a mode 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. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 index cc61a85b92..6d6821420a 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 @@ -50,7 +50,7 @@ Untrusted Publishers block list which it seems cannot be bypassed. (Added in 7.44.0) .IP CURLSSLOPT_NO_PARTIALCHAIN Tells libcurl to not accept "partial" certificate chains, which it otherwise -does by default. This option is only supported for OpenSSL and will fail the +does by default. This option is only supported for OpenSSL and fails the certificate verification if the chain ends with an intermediate certificate and not with a root cert. (Added in 7.68.0) .IP CURLSSLOPT_REVOKE_BEST_EFFORT diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 index eb3e4a7065..c8f1b52c7a 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 @@ -38,7 +38,7 @@ This option determines whether libcurl verifies the status of the server cert using the "Certificate Status Request" TLS extension (aka. OCSP stapling). Note that if this option is enabled but the server does not support the TLS -extension, the verification will fail. +extension, the verification fails. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_STDERR.3 b/docs/libcurl/opts/CURLOPT_STDERR.3 index 2c2071cdcc..e28d8367c4 100644 --- a/docs/libcurl/opts/CURLOPT_STDERR.3 +++ b/docs/libcurl/opts/CURLOPT_STDERR.3 @@ -36,8 +36,8 @@ Pass a FILE * as parameter. Tell libcurl to use this \fIstream\fP instead of stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE(3)\fP data. -If you are using libcurl as a win32 DLL, this option will cause an exception -and crash in the library since it cannot access a FILE * passed on from the +If you are using libcurl as a Windows DLL, this option causes an exception and +a crash in the library since it cannot access a FILE * passed on from the application. A work-around is to instead use \fICURLOPT_DEBUGFUNCTION(3)\fP. .SH DEFAULT stderr diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 index d2929046ee..ce92062917 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 @@ -43,9 +43,9 @@ resources to the identified stream rather than to the dependent stream." This option can be set during transfer. -\fIdephandle\fP must not be the same as \fIhandle\fP, that will cause this -function to return an error. It must be another easy handle, and it also needs -to be a handle of a transfer that will be sent over the same HTTP/2 connection +\fIdephandle\fP must not be the same as \fIhandle\fP, that makes this function +return an error. It must be another easy handle, and it also needs to be a +handle of a transfer that is about to be sent over the same HTTP/2 connection for this option to have an actual effect. .SH DEFAULT NULL diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 index f9b2776986..c6f5a13e04 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 @@ -46,9 +46,9 @@ reprioritized stream. This option can be set during transfer. -\fIdephandle\fP must not be the same as \fIhandle\fP, that will cause this -function to return an error. It must be another easy handle, and it also needs -to be a handle of a transfer that will be sent over the same HTTP/2 connection +\fIdephandle\fP must not be the same as \fIhandle\fP, that makes this function +return an error. It must be another easy handle, and it also needs to be a +handle of a transfer that is about to be sent over the same HTTP/2 connection for this option to have an actual effect. .SH DEFAULT NULL diff --git a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 index a91588fa38..7c12b9c1e0 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 +++ b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 @@ -39,20 +39,19 @@ stream used by the easy \fIhandle\fP. Setting and using weights only makes sense and is only usable when doing multiple streams over the same connections, which thus implies that you use \fICURLMOPT_PIPELINING(3)\fP. -This option can be set during transfer and will then cause the updated weight -info get sent to the server the next time an HTTP/2 frame is sent to the -server. +This option can be set during transfer and causes the updated weight info get +sent to the server the next time an HTTP/2 frame is sent to the server. See section 5.3 of RFC 7540 for protocol details. Streams with the same parent should be allocated resources proportionally based on their weight. So if you have two streams going, stream A with weight -16 and stream B with weight 32, stream B will get two thirds (32/48) of the +16 and stream B with weight 32, stream B gets two thirds (32/48) of the available bandwidth (assuming the server can send off the data equally for both streams). .SH DEFAULT -If nothing is set, the HTTP/2 protocol itself will use its own default which -is 16. +If nothing is set, the HTTP/2 protocol itself uses its own default which is +16. .SH PROTOCOLS HTTP/2 .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 index ef6542135a..9ccb38573a 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 @@ -32,7 +32,7 @@ CURLOPT_TCP_KEEPALIVE \- TCP keep-alive probing CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPALIVE, long probe); .fi .SH DESCRIPTION -Pass a long. If set to 1, TCP keepalive probes will be sent. The delay and +Pass a long. If set to 1, TCP keepalive probes are used. The delay and frequency of these probes can be controlled by the \fICURLOPT_TCP_KEEPIDLE(3)\fP and \fICURLOPT_TCP_KEEPINTVL(3)\fP options, provided the operating system supports them. Set to 0 (default behavior) to diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 index 20100b03dd..a4e16be270 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 @@ -32,12 +32,12 @@ CURLOPT_TCP_KEEPIDLE \- TCP keep-alive idle time wait CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPIDLE, long delay); .fi .SH DESCRIPTION -Pass a long. Sets the \fIdelay\fP, in seconds, that the operating system will -wait while the connection is idle before sending keepalive probes. Not all -operating systems support this option. +Pass a long. Sets the \fIdelay\fP, in seconds, to wait while the connection is +idle before sending keepalive probes. Not all operating systems support this +option. -The maximum value this accepts is 2147483648. Any larger value will be capped -to this amount. +The maximum value this accepts is 2147483648. Any larger value is capped to +this amount. .SH DEFAULT 60 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 index 5a845c649c..b5597da838 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 @@ -32,12 +32,11 @@ CURLOPT_TCP_KEEPINTVL \- TCP keep-alive interval CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPINTVL, long interval); .fi .SH DESCRIPTION -Pass a long. Sets the interval, in seconds, that the operating system will -wait between sending keepalive probes. Not all operating systems support this -option. (Added in 7.25.0) +Pass a long. Sets the interval, in seconds, to wait between sending keepalive +probes. Not all operating systems support this option. (Added in 7.25.0) -The maximum value this accepts is 2147483648. Any larger value will be capped -to this amount. +The maximum value this accepts is 2147483648. Any larger value is capped to +this amount. .SH DEFAULT 60 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 index 2d30ad47f9..d1dd97217a 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 @@ -33,13 +33,13 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_NODELAY, long nodelay); .fi .SH DESCRIPTION Pass a long specifying whether the \fITCP_NODELAY\fP option is to be set or -cleared (1L = set, 0 = clear). The option is set by default. This will have no +cleared (1L = set, 0 = clear). The option is set by default. This has no effect after the connection has been established. -Setting this option to 1L will disable TCP's Nagle algorithm on this -connection. The purpose of this algorithm is to try to minimize the number of -small packets on the network (where "small packets" means TCP segments less -than the Maximum Segment Size for the network). +Setting this option to 1L disables TCP's Nagle algorithm on connections +created using this handle. The purpose of this algorithm is to try to minimize +the number of small packets on the network (where "small packets" means TCP +segments less than the Maximum Segment Size for the network). Maximizing the amount of data sent per TCP segment is good because it amortizes the overhead of the send. However, in some cases small segments may diff --git a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 index fd79db9dec..20881d6921 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 @@ -33,11 +33,11 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_BLKSIZE, long blocksize); .fi .SH DESCRIPTION Specify \fIblocksize\fP to use for TFTP data transmission. Valid range as per -RFC 2348 is 8-65464 bytes. The default of 512 bytes will be used if this option -is not specified. The specified block size will only be used pending support -by the remote server. If the server does not return an option acknowledgment -or returns an option acknowledgment with no block size, the default of 512 -bytes will be used. +RFC 2348 is 8-65464 bytes. The default of 512 bytes is used if this option is +not specified. The specified block size is only used if supported by the +remote server. If the server does not return an option acknowledgment or +returns an option acknowledgment with no block size, the default of 512 bytes +is used. .SH DEFAULT 512 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 b/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 index 84d0516c54..f1b971ce01 100644 --- a/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 +++ b/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 @@ -37,10 +37,10 @@ value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP or \fICURL_TIMECOND_IFUNMODSINCE\fP. The last modification time of a file is not always known and in such instances -this feature will have no effect even if the given time condition would not -have been met. \fIcurl_easy_getinfo(3)\fP with the -\fICURLINFO_CONDITION_UNMET\fP option can be used after a transfer to learn if -a zero-byte successful "transfer" was due to this condition not matching. +this feature has no effect even if the given time condition would not have +been met. \fIcurl_easy_getinfo(3)\fP with the \fICURLINFO_CONDITION_UNMET\fP +option can be used after a transfer to learn if a zero-byte successful +"transfer" was due to this condition not matching. .SH DEFAULT CURL_TIMECOND_NONE (0) .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_TIMEOUT.3 index 37e84b0590..e45fbefa5d 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT.3 +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT.3 @@ -40,7 +40,7 @@ limiting operations risk aborting perfectly normal operations. \fICURLOPT_TIMEOUT_MS(3)\fP is the same function but set in milliseconds. If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the -value set last will be used. +value set last is used. Since this option puts a hard limit on how long time a request is allowed to take, it has limited use in dynamic use cases with varying transfer diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 b/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 index 5d4f530ba1..3b58077f25 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 @@ -33,11 +33,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE, long val); .fi .SH DESCRIPTION Pass a long \fIval\fP as parameter. This should be the time counted as seconds -since 1 Jan 1970, and the time will be used in a condition as specified with +since 1 Jan 1970, and the time is used in a condition as specified with \fICURLOPT_TIMECONDITION(3)\fP. -On systems with 32 bit 'long' variables, this option cannot set dates beyond -the year 2038. Consider \fICURLOPT_TIMEVALUE_LARGE(3)\fP instead. +On systems with 32 bit 'long' variables (such as Windows), this option cannot +set dates beyond the year 2038. Consider \fICURLOPT_TIMEVALUE_LARGE(3)\fP +instead. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 index 0d0f57545a..1afd20f8bc 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 @@ -34,8 +34,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE_LARGE, .fi .SH DESCRIPTION Pass a curl_off_t \fIval\fP as parameter. This should be the time counted as -seconds since 1 Jan 1970, and the time will be used in a condition as -specified with \fICURLOPT_TIMECONDITION(3)\fP. +seconds since 1 Jan 1970, and the time is used in a condition as specified +with \fICURLOPT_TIMECONDITION(3)\fP. The difference between this option and \fICURLOPT_TIMEVALUE(3)\fP is the type of the argument. On systems where 'long' is only 32 bit wide, this option has diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 index 3af4531327..d5aac1d9c9 100644 --- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 +++ b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 @@ -36,7 +36,7 @@ Pass a char *, pointing to a null-terminated string holding the list of cipher suites to use for the TLS 1.3 connection. The list must be syntactically correct, it consists of one or more cipher suite strings separated by colons. -You will find more details about cipher lists on this URL: +Find more details about cipher lists on this URL: https://curl.se/docs/ssl-ciphers.html diff --git a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 index 00783e4647..4895592c08 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 @@ -37,23 +37,23 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERFUNCTION, .SH DESCRIPTION Pass a pointer to a callback function. -This callback function will be called once right before sending the final -CR LF in an HTTP chunked transfer to fill a list of trailing headers to be -sent before finishing the HTTP transfer. +This callback function is called once right before sending the final CR LF in +an HTTP chunked transfer to fill a list of trailing headers to be sent before +finishing the HTTP transfer. You can set the userdata argument with the \fICURLOPT_TRAILERDATA(3)\fP option. The trailing headers included in the linked list must not be CRLF-terminated, -because libcurl will add the appropriate line termination characters after -each header item. +because libcurl adds the appropriate line termination characters after each +header item. If you use curl_slist_append to add trailing headers to the curl_slist then -libcurl will duplicate the strings, and will free the curl_slist and the -duplicates once the trailers have been sent. +libcurl duplicates the strings, and frees the curl_slist and the duplicates +once the trailers have been sent. -If one of the trailing header fields is not formatted correctly it will be -ignored and an info message will be emitted. +If one of the trailing header fields is not formatted correctly it is ignored +and an info message is emitted. The return value can either be \fBCURL_TRAILERFUNC_OK\fP or \fBCURL_TRAILERFUNC_ABORT\fP which would respectively instruct libcurl to @@ -70,7 +70,7 @@ HTTP static int trailer_cb(struct curl_slist **tr, void *data) { - /* libcurl will free the list */ + /* libcurl frees the list */ *tr = curl_slist_append(*tr, "My-super-awesome-trailer: trailer-stuff"); return CURL_TRAILERFUNC_OK; } @@ -82,7 +82,7 @@ if(curl) { /* Now set it as a put */ curl_easy_setopt(curl, CURLOPT_PUT, 1L); - /* Assuming we have a function that will return the data to be pushed + /* Assuming we have a function that returns the data to be pushed Let that function be read_cb */ curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); @@ -93,7 +93,7 @@ if(curl) { /* Set the trailers filling callback */ curl_easy_setopt(curl, CURLOPT_TRAILERFUNCTION, trailer_cb); - /* Perform the request, res will get the return code */ + /* Perform the transfer */ res = curl_easy_perform(curl); curl_easy_cleanup(curl); diff --git a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 index 2a64d86fc0..dc62f39b8f 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 +++ b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 @@ -37,8 +37,8 @@ Pass a long set to 1L to \fIenable\fP or 0 to disable. Adds a request for compressed Transfer Encoding in the outgoing HTTP request. If the server supports this and so desires, it can respond with the -HTTP response sent using a compressed Transfer-Encoding that will be -automatically uncompressed by libcurl on reception. +HTTP response sent using a compressed Transfer-Encoding that is automatically +uncompressed by libcurl on reception. Transfer-Encoding differs slightly from the Content-Encoding you ask for with \fICURLOPT_ACCEPT_ENCODING(3)\fP in that a Transfer-Encoding is strictly meant diff --git a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 index 0836610ca0..1c51dd7383 100644 --- a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 +++ b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 @@ -32,14 +32,13 @@ CURLOPT_UNIX_SOCKET_PATH \- Unix domain socket CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNIX_SOCKET_PATH, char *path); .fi .SH DESCRIPTION -Enables the use of Unix domain sockets as connection endpoint and sets the path -to \fIpath\fP. If \fIpath\fP is NULL, then Unix domain sockets are disabled. An -empty string will result in an error at some point, it will not disable use of -Unix domain sockets. +Enables the use of Unix domain sockets as connection endpoint and sets the +path to \fIpath\fP. If \fIpath\fP is NULL, then Unix domain sockets are +disabled. -When enabled, curl will connect to the Unix domain socket instead of -establishing a TCP connection to a host. Since no TCP connection is created, -curl does not need to resolve the DNS hostname in the URL. +When enabled, curl connects to the Unix domain socket instead of establishing +a TCP connection to the host. Since no network connection is created, curl +does not resolve the DNS hostname in the URL. The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms it might be even less. diff --git a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 index 9813437859..44e9412c0a 100644 --- a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 +++ b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 @@ -37,19 +37,20 @@ authentication (user+password) credentials when following locations, even when hostname changed. This option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION(3)\fP. -Further, when this option is not used or set to \fB0L\fP, libcurl will not -send custom set nor internally generated Authentication: headers on requests -done to other hosts than the one used for the initial URL. +Further, when this option is not used or set to \fB0L\fP, libcurl does not +send custom nor internally generated Authentication: headers on requests done +to other hosts than the one used for the initial URL. -By default, libcurl will only send credentials and Authentication headers to -the initial host name as given in the original URL, to avoid leaking username -+ password to other sites. +By default, libcurl only sends credentials and Authentication headers to the +initial host name as given in the original URL, to avoid leaking username + +password to other sites. This option should be used with caution: when curl follows redirects it blindly fetches the next URL as instructed by the server. Setting -\fICURLOPT_UNRESTRICTED_AUTH(3)\fP to 1L will therefore also make curl trust -the server and send possibly sensitive credentials to a host the server points -out. +\fICURLOPT_UNRESTRICTED_AUTH(3)\fP to 1L therefore also makes curl trust the +server and sends possibly sensitive credentials to any host the server points +out. And then maybe again and again as the following hosts can keep +redirecting to new hosts. .SH DEFAULT 0 .SH PROTOCOLS @@ -70,3 +71,5 @@ Along with HTTP Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" .BR CURLOPT_FOLLOWLOCATION "(3), " CURLOPT_USERPWD "(3), " +.BR CURLOPT_MAXREDIRS "(3), " +.BR CURLOPT_REDIR_PROTOCOLS_STR "(3), " diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 index 380e2ac1e6..69d7b7ad0d 100644 --- a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 @@ -35,7 +35,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD_BUFFERSIZE, long size); Pass a long specifying your preferred \fIsize\fP (in bytes) for the upload buffer in libcurl. It makes libcurl uses a larger buffer that gets passed to the next layer in the stack to get sent off. In some setups and for some -protocols, there's a huge performance benefit of having a larger upload +protocols, there is a huge performance benefit of having a larger upload buffer. This is just treated as a request, not an order. You cannot be guaranteed to @@ -45,8 +45,8 @@ The upload buffer size is by default 64 kilobytes. The maximum buffer size allowed to be set is 2 megabytes. The minimum buffer size allowed to be set is 16 kilobytes. -Since curl 7.61.1 the upload buffer is allocated on-demand - so if the handle -is not used for upload, this buffer will not be allocated at all. +The upload buffer is allocated on-demand - so if the handle is not used for +upload, this buffer is not allocated at all. DO NOT set this option on a handle that is currently used for an active transfer as that may lead to unintended consequences. diff --git a/docs/libcurl/opts/CURLOPT_URL.3 b/docs/libcurl/opts/CURLOPT_URL.3 index 30837862c3..3cbf6e8029 100644 --- a/docs/libcurl/opts/CURLOPT_URL.3 +++ b/docs/libcurl/opts/CURLOPT_URL.3 @@ -41,32 +41,31 @@ scheme://host:port/path For a greater explanation of the format please see RFC 3986. -libcurl does not validate the syntax or use this variable until the transfer is -issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will +libcurl does not validate the syntax or use the URL until the transfer is +started. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP might still return \fICURLE_OK\fP. If the given URL is missing a scheme name (such as "http://" or "ftp://" etc) -then libcurl will make a guess based on the host. If the outermost sub-domain -name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be -used, otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by -setting a default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details. +then libcurl guesses based on the host. If the outermost sub-domain name +matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol gets used, +otherwise HTTP is used. Since 7.45.0 guessing can be disabled by setting a +default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details. -Should the protocol, either that specified by the scheme or deduced by libcurl -from the host name, not be supported by libcurl then -\fICURLE_UNSUPPORTED_PROTOCOL\fP will be returned from either the +Should the protocol, either as specified by the URL scheme or deduced by +libcurl from the host name, not be supported by libcurl then +\fICURLE_UNSUPPORTED_PROTOCOL\fP is returned from either the \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you call them. Use \fIcurl_version_info(3)\fP for detailed information of which protocols are supported by the build of libcurl you are using. -\fICURLOPT_PROTOCOLS(3)\fP can be used to limit what protocols libcurl will +\fICURLOPT_PROTOCOLS_STR(3)\fP can be used to limit what protocols libcurl may use for this transfer, independent of what libcurl has been compiled to support. That may be useful if you accept the URL from an external source and want to limit the accessibility. -The \fICURLOPT_URL(3)\fP string will be ignored if \fICURLOPT_CURLU(3)\fP is -set. +The \fICURLOPT_URL(3)\fP string is ignored if \fICURLOPT_CURLU(3)\fP is set. -\fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a +Either \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP must be set before a transfer is started. The application does not have to keep the string around after setting this @@ -88,8 +87,8 @@ performed. Applications may at times find it convenient to allow users to specify URLs for various purposes and that string would then end up fed to this option. -Getting a URL from an external untrusted party will bring reasons for several -security concerns: +Getting a URL from an external untrusted party brings several security +concerns: If you have an application that runs as or in a server application, getting an unfiltered URL can easily trick your application to access a local resource @@ -124,9 +123,9 @@ POP3 and SMTP were added in 7.31.0 Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -Note that \fIcurl_easy_setopt(3)\fP will not actually parse the given string so -given a bad URL, it will not be detected until \fIcurl_easy_perform(3)\fP or -similar is called. +Note that \fIcurl_easy_setopt(3)\fP does not parse the given string so given a +bad URL, it is not detected until \fIcurl_easy_perform(3)\fP or similar is +called. .SH "SEE ALSO" .BR CURLOPT_VERBOSE "(3), " CURLOPT_PROTOCOLS "(3), " .BR CURLOPT_FORBID_REUSE "(3), " CURLOPT_FRESH_CONNECT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_USERAGENT.3 b/docs/libcurl/opts/CURLOPT_USERAGENT.3 index 5b4365c6e1..793dc5c34a 100644 --- a/docs/libcurl/opts/CURLOPT_USERAGENT.3 +++ b/docs/libcurl/opts/CURLOPT_USERAGENT.3 @@ -32,10 +32,9 @@ CURLOPT_USERAGENT \- HTTP user-agent header CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERAGENT, char *ua); .fi .SH DESCRIPTION -Pass a pointer to a null-terminated string as parameter. It will be used to -set the User-Agent: header in the HTTP request sent to the remote server. This -can be used to fool servers or scripts. You can also set any custom header -with \fICURLOPT_HTTPHEADER(3)\fP. +Pass a pointer to a null-terminated string as parameter. It is used to set the +User-Agent: header field in the HTTP request sent to the remote server. You +can also set any custom header with \fICURLOPT_HTTPHEADER(3)\fP. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_USERPWD.3 b/docs/libcurl/opts/CURLOPT_USERPWD.3 index c5c551a6fb..ffff859822 100644 --- a/docs/libcurl/opts/CURLOPT_USERPWD.3 +++ b/docs/libcurl/opts/CURLOPT_USERPWD.3 @@ -52,17 +52,17 @@ Some HTTP servers (on Windows) support inclusion of the domain for Basic authentication as well. When using HTTP and \fICURLOPT_FOLLOWLOCATION(3)\fP, libcurl might perform -several requests to possibly different hosts. libcurl will only send this user -and password information to hosts using the initial host name (unless -\fICURLOPT_UNRESTRICTED_AUTH(3)\fP is set), so if libcurl follows locations to -other hosts it will not send the user and password to those. This is enforced +several requests to possibly different hosts. libcurl only sends this user and +password information to hosts using the initial host name (unless +\fICURLOPT_UNRESTRICTED_AUTH(3)\fP is set), so if libcurl follows redirects to +other hosts, it does not send the user and password to those. This is enforced to prevent accidental information leakage. Use \fICURLOPT_HTTPAUTH(3)\fP to specify the authentication method for HTTP based connections or \fICURLOPT_LOGIN_OPTIONS(3)\fP to control IMAP, POP3 and SMTP options. -The user and password strings are not URL decoded, so there's no way to send +The user and password strings are not URL decoded, so there is no way to send in a user name containing a colon using this option. Use \fICURLOPT_USERNAME(3)\fP for that, or include it in the URL. diff --git a/docs/libcurl/opts/CURLOPT_VERBOSE.3 b/docs/libcurl/opts/CURLOPT_VERBOSE.3 index 6a99dffefa..59993b8895 100644 --- a/docs/libcurl/opts/CURLOPT_VERBOSE.3 +++ b/docs/libcurl/opts/CURLOPT_VERBOSE.3 @@ -35,10 +35,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_VERBOSE, long onoff); Set the \fIonoff\fP parameter to 1 to make the library display a lot of verbose information about its operations on this \fIhandle\fP. Useful for libcurl and/or protocol debugging and understanding. The verbose information -will be sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP. +is sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP. -You hardly ever want this set in production use, you will almost always want -this when you debug/report problems. +You hardly ever want this enabled in production use, you almost always want +this used when you debug/report problems. To also get all the protocol data sent and received, consider using the \fICURLOPT_DEBUGFUNCTION(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 index 0cef31545f..1de226e842 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 +++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 @@ -33,16 +33,16 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEDATA, void *pointer); .fi .SH DESCRIPTION A data \fIpointer\fP to pass to the write callback. If you use the -\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you will get in -that callback's fourth and last argument. If you do not use a write callback, -you must make \fIpointer\fP a 'FILE *' (cast to 'void *') as libcurl will pass -this to \fIfwrite(3)\fP when writing data. +\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you get in that +callback's fourth and last argument. If you do not use a write callback, you +must make \fIpointer\fP a 'FILE *' (cast to 'void *') as libcurl passes this +to \fIfwrite(3)\fP when writing data. -The internal \fICURLOPT_WRITEFUNCTION(3)\fP will write the data to the FILE * +The internal \fICURLOPT_WRITEFUNCTION(3)\fP writes the data to the FILE * given with this option, or to stdout if this option has not been set. -If you are using libcurl as a win32 DLL, you \fBMUST\fP use a -\fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you will experience +If you are using libcurl as a Windows DLL, you \fBMUST\fP use a +\fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you might experience crashes. .SH DEFAULT By default, this is a FILE * to stdout. @@ -59,6 +59,6 @@ Available in all libcurl versions. This option was formerly known as \fICURLOPT_FILE\fP, the name \fICURLOPT_WRITEDATA(3)\fP was introduced in 7.9.7. .SH RETURN VALUE -This will return CURLE_OK. +This returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_WRITEFUNCTION "(3), " CURLOPT_READDATA "(3), " diff --git a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 index e443234f50..775a6f0bc2 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 @@ -42,9 +42,9 @@ many times and each invoke delivers another chunk of data. \fIptr\fP points to the delivered data, and the size of that data is \fInmemb\fP; \fIsize\fP is always 1. -The callback function will be passed as much data as possible in all invokes, -but you must not make any assumptions. It may be one byte, it may be -thousands. The maximum amount of body data that will be passed to the write +The callback function is passed as much data as possible in all invokes, but +you must not make any assumptions. It may be one byte, it may be +thousands. The maximum amount of body data that is be passed to the write callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the usual default is 16K). If \fICURLOPT_HEADER(3)\fP is enabled, which makes header data get passed to the write callback, you can get up to @@ -54,28 +54,28 @@ means 100K. This function may be called with zero bytes data if the transferred file is empty. -The data passed to this function will not be null-terminated! +The data passed to this function is not null-terminated! Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option. Your callback should return the number of bytes actually taken care of. If -that amount differs from the amount passed to your callback function, it will -signal an error condition to the library. This will cause the transfer to get -aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP. +that amount differs from the amount passed to your callback function, it +signals an error condition to the library. This causes the transfer to get +aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0) -If your callback function returns CURL_WRITEFUNC_PAUSE it will cause this -transfer to become paused. See \fIcurl_easy_pause(3)\fP for further details. +If the callback function returns CURL_WRITEFUNC_PAUSE it pauses this +transfer. See \fIcurl_easy_pause(3)\fP for further details. Set this option to NULL to get the internal default function used instead of -your callback. The internal default function will write the data to the FILE * +your callback. The internal default function writes the data to the FILE * given with \fICURLOPT_WRITEDATA(3)\fP. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to do that. .SH DEFAULT -libcurl will use 'fwrite' as a callback by default. +libcurl uses 'fwrite' as a callback by default. .SH PROTOCOLS For all protocols .SH EXAMPLE @@ -126,7 +126,7 @@ if (curl_handle) .SH AVAILABILITY Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0. .SH RETURN VALUE -This will return CURLE_OK. +This returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_WRITEDATA "(3), " CURLOPT_READFUNCTION "(3), " .BR CURLOPT_HEADERFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 b/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 index e3d31bf690..2b7c75023d 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 +++ b/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 @@ -32,7 +32,7 @@ CURLOPT_XFERINFODATA \- pointer passed to the progress callback CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFODATA, void *pointer); .fi .SH DESCRIPTION -Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first +Pass a \fIpointer\fP that is untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION(3)\fP. This is an alias for \fICURLOPT_PROGRESSDATA(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 index 5f7105f760..27644e2750 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 @@ -43,34 +43,34 @@ Pass a pointer to your callback function, which should match the prototype shown above. This function gets called by libcurl instead of its internal equivalent with a -frequent interval. While data is being transferred it will be called -frequently, and during slow periods like when nothing is being transferred it -can slow down to about one call per second. +frequent interval. While data is being transferred it gets called frequently, +and during slow periods like when nothing is being transferred it can slow +down to about one call per second. \fIclientp\fP is the pointer set with \fICURLOPT_XFERINFODATA(3)\fP, it is not used by libcurl but is only passed along from the application to the callback. -The callback gets told how much data libcurl will transfer and has -transferred, in number of bytes. \fIdltotal\fP is the total number of bytes -libcurl expects to download in this transfer. \fIdlnow\fP is the number of -bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl +The callback gets told how much data libcurl is about to transfer and has +already transferred, in number of bytes. \fIdltotal\fP is the total number of +bytes libcurl expects to download in this transfer. \fIdlnow\fP is the number +of bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl expects to upload in this transfer. \fIulnow\fP is the number of bytes uploaded so far. -Unknown/unused argument values passed to the callback will be set to zero -(like if you only download data, the upload size will remain 0). Many times -the callback will be called one or more times first, before it knows the data -sizes so a program must be made to handle that. +Unknown/unused argument values passed to the callback are set to zero (like if +you only download data, the upload size remains 0). Many times the callback is +called one or more times first, before it knows the data sizes so a program +must be made to handle that. -If your callback function returns CURL_PROGRESSFUNC_CONTINUE it will cause -libcurl to continue executing the default progress function. +If your callback function returns CURL_PROGRESSFUNC_CONTINUE it makes libcurl +to continue executing the default progress function. -Returning any other non-zero value from this callback will cause libcurl to -abort the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. +Returning any other non-zero value from this callback makes libcurl abort the +transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. -If you transfer data with the multi interface, this function will not be -called during periods of idleness unless you call the appropriate libcurl -function that performs transfers. +If you transfer data with the multi interface, this function is not called +during periods of idleness unless you call the appropriate libcurl function +that performs transfers. \fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually get called. diff --git a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 index 4fcff5384f..45b456a1a2 100644 --- a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 +++ b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 @@ -35,7 +35,7 @@ CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_LOCKFUNC, lockcb); .fi .SH DESCRIPTION Set a mutex lock callback for the share object, to allow it to get used by -multiple threads concurrently. There's a corresponding +multiple threads concurrently. There is a corresponding \fICURLSHOPT_UNLOCKFUNC(3)\fP callback called when the mutex is again released. The \fIlockcb\fP argument must be a pointer to a function matching the diff --git a/docs/libcurl/opts/CURLSHOPT_SHARE.3 b/docs/libcurl/opts/CURLSHOPT_SHARE.3 index 78c051d326..2d4592ec7c 100644 --- a/docs/libcurl/opts/CURLSHOPT_SHARE.3 +++ b/docs/libcurl/opts/CURLSHOPT_SHARE.3 @@ -38,20 +38,19 @@ The given \fItype\fP must be be one of the values described below. You can set the share object share multiple types of data. Unset a type again by setting \fICURLSHOPT_UNSHARE(3)\fP. .IP CURL_LOCK_DATA_COOKIE -Cookie data will be shared across the easy handles using this shared object. -Note that this does not activate an easy handle's cookie handling. You can do -that separately by using \fICURLOPT_COOKIEFILE(3)\fP for example. +Cookie data is shared across the easy handles using this shared object. Note +that this does not activate an easy handle's cookie handling. You can do that +separately by using \fICURLOPT_COOKIEFILE(3)\fP for example. .IP CURL_LOCK_DATA_DNS -Cached DNS hosts will be shared across the easy handles using this shared +Cached DNS hosts are shared across the easy handles using this shared object. Note that when you use the multi interface, all easy handles added to -the same multi handle will share DNS cache by default without using this -option. +the same multi handle share DNS cache by default without using this option. .IP CURL_LOCK_DATA_SSL_SESSION -SSL session IDs will be shared across the easy handles using this shared -object. This will reduce the time spent in the SSL handshake when reconnecting -to the same server. Note SSL session IDs are reused within the same easy -handle by default. Note this symbol was added in 7.10.3 but was not -implemented until 7.23.0. +SSL session IDs are shared across the easy handles using this shared +object. This reduces the time spent in the SSL handshake when reconnecting to +the same server. Note SSL session IDs are reused within the same easy handle +by default. Note this symbol was added in 7.10.3 but was not implemented until +7.23.0. .IP CURL_LOCK_DATA_CONNECT Put the connection cache in the share object and make all easy handles using this share object share the connection cache. @@ -67,7 +66,7 @@ Support for \fBCURL_LOCK_DATA_CONNECT\fP was added in 7.57.0, but the symbol existed before this. Note that when you use the multi interface, all easy handles added to the same -multi handle will share connection cache by default without using this option. +multi handle shares connection cache by default without using this option. .IP CURL_LOCK_DATA_PSL The Public Suffix List stored in the share object is made available to all easy handle bound to the later. Since the Public Suffix List is periodically @@ -76,7 +75,7 @@ refreshed, this avoids updates in too many different contexts. Added in 7.61.0. Note that when you use the multi interface, all easy handles added to the same -multi handle will share PSL cache by default without using this option. +multi handle shares PSL cache by default without using this option. .IP CURL_LOCK_DATA_HSTS The in-memory HSTS cache. diff --git a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 index 13f0258d59..18c955df81 100644 --- a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 +++ b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 @@ -33,7 +33,7 @@ void unlockcb(CURL *handle, curl_lock_data data, void *clientp); CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNLOCKFUNC, unlockcb); .fi .SH DESCRIPTION -Set a mutex unlock callback for the share object. There's a corresponding +Set a mutex unlock callback for the share object. There is a corresponding \fICURLSHOPT_LOCKFUNC(3)\fP callback called when the mutex is first locked. The \fIunlockcb\fP argument must be a pointer to a function matching the diff --git a/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 b/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 index f1b6d023cc..a7de4399c1 100644 --- a/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 +++ b/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 @@ -39,14 +39,14 @@ below. You can set \fICURLSHOPT_UNSHARE(3)\fP multiple times with different data arguments to remove multiple types from the shared object. Add data to share again with \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_DATA_COOKIE -Cookie data will no longer be shared across the easy handles using this shared +Cookie data is no longer shared across the easy handles using this shared object. .IP CURL_LOCK_DATA_DNS -Cached DNS hosts will be no longer be shared across the easy handles using -this shared object. -.IP CURL_LOCK_DATA_SSL_SESSION -SSL session IDs will no longer be shared across the easy handles using this +Cached DNS hosts are no longer shared across the easy handles using this shared object. +.IP CURL_LOCK_DATA_SSL_SESSION +SSL session IDs are no longer shared across the easy handles using this shared +object. .IP CURL_LOCK_DATA_CONNECT The connection cache is no longer shared. .IP CURL_LOCK_DATA_PSL