diff options
188 files changed, 1204 insertions, 1209 deletions
@@ -6,7 +6,7 @@ SPDX-License-Identifier: curl #  -[](https://bestpractices.coreinfrastructure.org/projects/63) +[](https://bestpractices.coreinfrastructure.org/projects/63) [](https://scan.coverity.com/projects/curl) [](https://ci.appveyor.com/project/curlorg/curl) [](https://dev.azure.com/daniel0244/curl/_build/latest?definitionId=1&branchName=master) diff --git a/SECURITY.md b/SECURITY.md index e0d4cfb13..be37cd153 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,11 +6,11 @@ SPDX-License-Identifier: curl # Security Policy -See [docs/SECURITY-PROCESS.md](docs/SECURITY-PROCESS.md) for full details. +See [SECURITY-PROCESS](docs/SECURITY-PROCESS.md) for full details. ## Reporting a Vulnerability -If you have found or just suspect a security problem somewhere in curl or libcurl, -report it on [https://hackerone.com/curl](https://hackerone.com/curl). +If you have found or just suspect a security problem somewhere in curl or +libcurl, report it on [HackerOne](https://hackerone.com/curl). We treat security issues with confidentiality until controlled and disclosed responsibly. diff --git a/docs/BUFREF.md b/docs/BUFREF.md index c11c60151..14f41b38b 100644 --- a/docs/BUFREF.md +++ b/docs/BUFREF.md @@ -12,13 +12,13 @@ The `struct bufref` is used to hold data referencing a buffer. The members of that structure **MUST NOT** be accessed or modified without using the dedicated bufref API. -## init +## `init` ```c void Curl_bufref_init(struct bufref *br); ``` -Initialises a `bufref` structure. This function **MUST** be called before any +Initializes a `bufref` structure. This function **MUST** be called before any other operation is performed on the structure. Upon completion, the referenced buffer is `NULL` and length is zero. @@ -26,16 +26,16 @@ Upon completion, the referenced buffer is `NULL` and length is zero. This function may also be called to bypass referenced buffer destruction while invalidating the current reference. -## free +## `free` ```c void Curl_bufref_free(struct bufref *br); ``` Destroys the previously referenced buffer using its destructor and -reinitialises the structure for a possible subsequent reuse. +reinitializes the structure for a possible subsequent reuse. -## set +## `set` ```c void Curl_bufref_set(struct bufref *br, const void *buffer, size_t length, @@ -47,9 +47,9 @@ the structure, associated with its `destructor` function. The latter can be specified as `NULL`: this will be the case when the referenced buffer is static. -if `buffer` is NULL, `length`must be zero. +if `buffer` is NULL, `length` must be zero. -## memdup +## `memdup` ```c CURLcode Curl_bufref_memdup(struct bufref *br, const void *data, size_t length); @@ -64,7 +64,7 @@ null-terminator; it is not counted in the stored length. Returns `CURLE_OK` if successful, else `CURLE_OUT_OF_MEMORY`. -## ptr +## `ptr` ```c const unsigned char *Curl_bufref_ptr(const struct bufref *br); @@ -72,7 +72,7 @@ const unsigned char *Curl_bufref_ptr(const struct bufref *br); Returns a `const unsigned char *` to the referenced buffer. -## len +## `len` ```c size_t Curl_bufref_len(const struct bufref *br); diff --git a/docs/CHECKSRC.md b/docs/CHECKSRC.md index 5fe1c52ef..0406a7f6b 100644 --- a/docs/CHECKSRC.md +++ b/docs/CHECKSRC.md @@ -16,9 +16,9 @@ when, for example, one of the files is generated. `-h` shows the help output, that also lists all recognized warnings -## What does checksrc warn for? +## What does `checksrc` warn for? -checksrc does not check and verify the code against the entire style guide. +`checksrc` does not check and verify the code against the entire style guide. The script is an effort to detect the most common mistakes and syntax mistakes that contributors make before they get accustomed to our code style. Heck, many of us regulars do the mistakes too and this script helps us keep the code @@ -27,7 +27,7 @@ in shape. checksrc.pl -h Lists how to use the script and it lists all existing warnings it has and -problems it detects. At the time of this writing, the existing checksrc +problems it detects. At the time of this writing, the existing `checksrc` warnings are: - `ASSIGNWITHINCONDITION`: Assignment within a conditional expression. The @@ -119,8 +119,8 @@ warnings are: - `TYPEDEFSTRUCT`: we frown upon (most) typedefed structs -- `UNUSEDIGNORE`: a checksrc inlined warning ignore was asked for but not used, - that is an ignore that should be removed or changed to get used. +- `UNUSEDIGNORE`: a `checksrc` inlined warning ignore was asked for but not + used, that is an ignore that should be removed or changed to get used. ### Extended warnings @@ -139,16 +139,16 @@ Currently these are the extended warnings which can be enabled: ## Ignore certain warnings -Due to the nature of the source code and the flaws of the checksrc tool, there -is sometimes a need to ignore specific warnings. checksrc allows a few +Due to the nature of the source code and the flaws of the `checksrc` tool, +there is sometimes a need to ignore specific warnings. `checksrc` allows a few different ways to do this. ### Inline ignore You can control what to ignore within a specific source file by providing -instructions to checksrc in the source code itself. See examples below. The -instruction can ask to ignore a specific warning N number of times or you -ignore all of them until you mark the end of the ignored section. +instructions to `checksrc` in the source code itself. See examples below. The +instruction can ask to ignore a specific warning a specific number of times or +you ignore all of them until you mark the end of the ignored section. Inline ignores are only done for that single specific source code file. diff --git a/docs/CIPHERS.md b/docs/CIPHERS.md index ff35ff283..e5e5def19 100644 --- a/docs/CIPHERS.md +++ b/docs/CIPHERS.md @@ -7,7 +7,7 @@ and users can control which ciphers to consider when negotiating TLS connections. TLS 1.3 ciphers are supported since curl 7.61 for OpenSSL 1.1.1+, and since -curl 7.85 for SChannel with options +curl 7.85 for Schannel with options [`CURLOPT_TLS13_CIPHERS`](https://curl.se/libcurl/c/CURLOPT_TLS13_CIPHERS.html) and [`--tls13-ciphers`](https://curl.se/docs/manpage.html#--tls13-ciphers) @@ -51,7 +51,7 @@ When specifying multiple cipher names, separate them with colon (`:`). `ADH-RC4-MD5` `ADH-DES-CBC3-SHA` -### AES ciphersuites from RFC3268, extending TLS v1.0 +### AES cipher suites from RFC3268, extending TLS v1.0 `AES128-SHA` `AES256-SHA` @@ -66,7 +66,7 @@ When specifying multiple cipher names, separate them with colon (`:`). `ADH-AES128-SHA` `ADH-AES256-SHA` -### SEED ciphersuites from RFC4162, extending TLS v1.0 +### SEED cipher suites from RFC4162, extending TLS v1.0 `SEED-SHA` `DH-DSS-SEED-SHA` @@ -75,7 +75,7 @@ When specifying multiple cipher names, separate them with colon (`:`). `DHE-RSA-SEED-SHA` `ADH-SEED-SHA` -### GOST ciphersuites, extending TLS v1.0 +### GOST cipher suites, extending TLS v1.0 `GOST94-GOST89-GOST89` `GOST2001-GOST89-GOST89` @@ -148,7 +148,7 @@ When specifying multiple cipher names, separate them with colon (`:`). `ECDHE-ECDSA-AES128-CCM8` `ECDHE-ECDSA-AES256-CCM8` -### Camellia HMAC-Based ciphersuites from RFC6367, extending TLS v1.2 +### Camellia HMAC-Based cipher suites from RFC6367, extending TLS v1.2 `ECDHE-ECDSA-CAMELLIA128-SHA256` `ECDHE-ECDSA-CAMELLIA256-SHA384` @@ -177,7 +177,7 @@ When specifying multiple cipher names, separate them with colon (`:`). `des` `desede3` -### SSL3/TLS cipher suites +### SSL3/TLS cipher suites `rsa_rc4_128_md5` `rsa_rc4_128_sha` @@ -458,7 +458,7 @@ maps them to the following case-insensitive names. ## Schannel Schannel allows the enabling and disabling of encryption algorithms, but not -specific ciphersuites. They are +specific cipher suites. They are [defined](https://docs.microsoft.com/windows/desktop/SecCrypto/alg-id) by Microsoft. @@ -517,7 +517,7 @@ and the request will fail. `CALG_ECDH_EPHEM`, As of curl 7.77.0, you can also pass `SCH_USE_STRONG_CRYPTO` as a cipher name -to [constrain the set of available ciphers as specified in the schannel +to [constrain the set of available ciphers as specified in the Schannel documentation](https://docs.microsoft.com/en-us/windows/win32/secauthn/tls-cipher-suites-in-windows-server-2022). Note that the supported ciphers in this case follow the OS version, so if you are running an outdated OS you might still be supporting weak ciphers. diff --git a/docs/CODE_REVIEW.md b/docs/CODE_REVIEW.md index 338028117..0776d30a0 100644 --- a/docs/CODE_REVIEW.md +++ b/docs/CODE_REVIEW.md @@ -70,7 +70,7 @@ on final or release builds. Can the mallocs be avoided? Do not introduce mallocs in any hot paths. If there are (new) mallocs, can they be combined into fewer calls? -Are all allocations handled in errorpaths to avoid leaks and crashes? +Are all allocations handled in error paths to avoid leaks and crashes? ## Thread-safety @@ -164,5 +164,5 @@ used as input to string functions. Tightly coupled with a code review is making sure that the commit message is good. It is the responsibility of the person who merges the code to make sure that the commit message follows our standard (detailed in the -[CONTRIBUTE.md](CONTRIBUTE.md) document). This includes making sure the PR +[CONTRIBUTE](CONTRIBUTE.md) document). This includes making sure the PR identifies related issues and giving credit to reporters and helpers. diff --git a/docs/CONTRIBUTE.md b/docs/CONTRIBUTE.md index 712f3e9b2..43a747df5 100644 --- a/docs/CONTRIBUTE.md +++ b/docs/CONTRIBUTE.md @@ -157,12 +157,12 @@ git commit that is easy to merge and they are easy to track and not that easy to lose in the flood of many emails, like they sometimes do on the mailing lists. -Every pull request submitted will automatically be -tested in several different ways. [See CI.md for more +Every pull request submitted will automatically be tested in several different +ways. [See the CI document for more information](https://github.com/curl/curl/blob/master/tests/CI.md). Sometimes the tests fail due to a dependency service temporarily being offline -or otherwise unavailable, eg. package downloads. In this case you can just +or otherwise unavailable, e.g. package downloads. In this case you can just try to update your pull requests to rerun the tests later as described below. You can update your pull requests by pushing new commits or force-pushing @@ -245,7 +245,7 @@ can make patches out of your changes that are suitable for mailing: git format-patch remotes/origin/master -This creates files in your local directory named NNNN-[name].patch for each +This creates files in your local directory named `NNNN-[name].patch` for each commit. Now send those patches off to the curl-library list. You can of course opt to @@ -267,17 +267,7 @@ can use diff recursively: diff -ur curl-original-dir curl-modified-sources-dir > my-fixes.diff The GNU diff and GNU patch tools exist for virtually all platforms, including -all kinds of Unixes and Windows: - -For unix-like operating systems: - - - [https://savannah.gnu.org/projects/patch/](https://savannah.gnu.org/projects/patch/) - - [https://www.gnu.org/software/diffutils/](https://www.gnu.org/software/diffutils/) - -For Windows: - - - [https://gnuwin32.sourceforge.io/packages/patch.htm](https://gnuwin32.sourceforge.io/packages/patch.htm) - - [https://gnuwin32.sourceforge.io/packages/diffutils.htm](https://gnuwin32.sourceforge.io/packages/diffutils.htm) +all kinds of Unixes and Windows. ### Useful resources - [Webinar on getting code into cURL](https://www.youtube.com/watch?v=QmZ3W1d6LQI) diff --git a/docs/CURL-DISABLE.md b/docs/CURL-DISABLE.md index 7ece3dc51..1548df6bc 100644 --- a/docs/CURL-DISABLE.md +++ b/docs/CURL-DISABLE.md @@ -1,140 +1,140 @@ # Code defines to disable features and protocols -## CURL_DISABLE_ALTSVC +## `CURL_DISABLE_ALTSVC` Disable support for Alt-Svc: HTTP headers. -## CURL_DISABLE_COOKIES +## `CURL_DISABLE_COOKIES` Disable support for HTTP cookies. -## CURL_DISABLE_CRYPTO_AUTH +## `CURL_DISABLE_CRYPTO_AUTH` Disable support for authentication methods using crypto. -## CURL_DISABLE_DICT +## `CURL_DISABLE_DICT` Disable the DICT protocol -## CURL_DISABLE_DOH +## `CURL_DISABLE_DOH` Disable DNS-over-HTTPS -## CURL_DISABLE_FILE +## `CURL_DISABLE_FILE` Disable the FILE protocol -## CURL_DISABLE_FTP +## `CURL_DISABLE_FTP` Disable the FTP (and FTPS) protocol -## CURL_DISABLE_GETOPTIONS +## `CURL_DISABLE_GETOPTIONS` Disable the `curl_easy_options` API calls that lets users get information about existing options to `curl_easy_setopt`. -## CURL_DISABLE_GOPHER +## `CURL_DISABLE_GOPHER` Disable the GOPHER protocol. -## CURL_DISABLE_HEADERS_API +## `CURL_DISABLE_HEADERS_API` Disable the HTTP header API. -## CURL_DISABLE_HSTS +## `CURL_DISABLE_HSTS` Disable the HTTP Strict Transport Security support. -## CURL_DISABLE_HTTP +## `CURL_DISABLE_HTTP` Disable the HTTP(S) protocols. Note that this then also disable HTTP proxy support. -## CURL_DISABLE_HTTP_AUTH +## `CURL_DISABLE_HTTP_AUTH` Disable support for all HTTP authentication methods. -## CURL_DISABLE_IMAP +## `CURL_DISABLE_IMAP` Disable the IMAP(S) protocols. -## CURL_DISABLE_LDAP +## `CURL_DISABLE_LDAP` Disable the LDAP(S) protocols. -## CURL_DISABLE_LDAPS +## `CURL_DISABLE_LDAPS` Disable the LDAPS protocol. -## CURL_DISABLE_LIBCURL_OPTION +## `CURL_DISABLE_LIBCURL_OPTION` Disable the --libcurl option from the curl tool. -## CURL_DISABLE_MIME +## `CURL_DISABLE_MIME` Disable MIME support. -## CURL_DISABLE_MQTT +## `CURL_DISABLE_MQTT` Disable MQTT support. -## CURL_DISABLE_NETRC +## `CURL_DISABLE_NETRC` Disable the netrc parser. -## CURL_DISABLE_NTLM +## `CURL_DISABLE_NTLM` Disable support for NTLM. -## CURL_DISABLE_OPENSSL_AUTO_LOAD_CONFIG +## `CURL_DISABLE_OPENSSL_AUTO_LOAD_CONFIG` Disable the auto load config support in the OpenSSL backend. -## CURL_DISABLE_PARSEDATE +## `CURL_DISABLE_PARSEDATE` Disable date parsing -## CURL_DISABLE_POP3 +## `CURL_DISABLE_POP3` Disable the POP3 protocol -## CURL_DISABLE_PROGRESS_METER +## `CURL_DISABLE_PROGRESS_METER` Disable the built-in progress meter -## CURL_DISABLE_PROXY +## `CURL_DISABLE_PROXY` Disable support for proxies -## CURL_DISABLE_RTSP +## `CURL_DISABLE_RTSP` Disable the RTSP protocol. -## CURL_DISABLE_SHUFFLE_DNS +## `CURL_DISABLE_SHUFFLE_DNS` Disable the shuffle DNS feature -## CURL_DISABLE_SMB +## `CURL_DISABLE_SMB` Disable the SMB(S) protocols -## CURL_DISABLE_SMTP +## `CURL_DISABLE_SMTP` Disable the SMTP(S) protocols -## CURL_DISABLE_SOCKETPAIR +## `CURL_DISABLE_SOCKETPAIR` -Disable the use of socketpair internally to allow waking up and canceling -curl_multi_poll(). +Disable the use of `socketpair()` internally to allow waking up and canceling +`curl_multi_poll()`. -## CURL_DISABLE_TELNET +## `CURL_DISABLE_TELNET` Disable the TELNET protocol -## CURL_DISABLE_TFTP +## `CURL_DISABLE_TFTP` Disable the TFTP protocol -## CURL_DISABLE_VERBOSE_STRINGS +## `CURL_DISABLE_VERBOSE_STRINGS` Disable verbose strings and error messages. diff --git a/docs/DEPRECATE.md b/docs/DEPRECATE.md index 3ee4b1e39..1b8eba9a5 100644 --- a/docs/DEPRECATE.md +++ b/docs/DEPRECATE.md @@ -17,7 +17,7 @@ We remove support for building curl with the NSS TLS library in August 2023. features on top of the regular NSS that is not shipped by the vanilla library Starting in 7.82.0, building curl to use NSS configure requires the additional -flag --with-nss-deprecated in an attempt to highlight these plans. +flag `--with-nss-deprecated` in an attempt to highlight these plans. ## past removals diff --git a/docs/DYNBUF.md b/docs/DYNBUF.md index 7ed8d80ec..41b022c42 100644 --- a/docs/DYNBUF.md +++ b/docs/DYNBUF.md @@ -9,17 +9,18 @@ The `struct dynbuf` is used to hold data for each instance of a dynamic buffer. The members of that struct **MUST NOT** be accessed or modified without using the dedicated dynbuf API. -## init +## `Curl_dyn_init` ```c void Curl_dyn_init(struct dynbuf *s, size_t toobig); ``` -This inits a struct to use for dynbuf and it cannot fail. The `toobig` value -**must** be set to the maximum size we allow this buffer instance to grow to. -The functions below will return `CURLE_OUT_OF_MEMORY` when hitting this limit. +This initializes a struct to use for dynbuf and it cannot fail. The `toobig` +value **must** be set to the maximum size we allow this buffer instance to +grow to. The functions below will return `CURLE_OUT_OF_MEMORY` when hitting +this limit. -## free +## `Curl_dyn_free` ```c void Curl_dyn_free(struct dynbuf *s); @@ -28,7 +29,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. -## addn +## `Curl_dyn_addn` ```c CURLcode Curl_dyn_addn(struct dynbuf *s, const void *mem, size_t len); @@ -36,7 +37,7 @@ CURLcode Curl_dyn_addn(struct dynbuf *s, const void *mem, size_t len); Append arbitrary data of a given length to the end of the buffer. -## add +## `Curl_dyn_add` ```c CURLcode Curl_dyn_add(struct dynbuf *s, const char *str); @@ -44,7 +45,7 @@ CURLcode Curl_dyn_add(struct dynbuf *s, const char *str); Append a C string to the end of the buffer. -## addf +## `Curl_dyn_addf` ```c CURLcode Curl_dyn_addf(struct dynbuf *s, const char *fmt, ...); @@ -52,7 +53,7 @@ CURLcode Curl_dyn_addf(struct dynbuf *s, const char *fmt, ...); Append a `printf()`-style string to the end of the buffer. -## vaddf +## `Curl_dyn_vaddf` ```c CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap); @@ -60,7 +61,7 @@ CURLcode Curl_dyn_vaddf(struct dynbuf *s, const char *fmt, va_list ap); Append a `vprintf()`-style string to the end of the buffer. -## reset +## `Curl_dyn_reset` ```c void Curl_dyn_reset(struct dynbuf *s); @@ -68,7 +69,7 @@ void Curl_dyn_reset(struct dynbuf *s); Reset the buffer length, but leave the allocation. -## tail +## `Curl_dyn_tail` ```c CURLcode Curl_dyn_tail(struct dynbuf *s, size_t length); @@ -79,7 +80,7 @@ buffer). The rest of the buffer is dropped. The specified `length` must not be larger than the buffer length. To instead keep the leading part, see `Curl_dyn_setlen()`. -## ptr +## `Curl_dyn_ptr` ```c char *Curl_dyn_ptr(const struct dynbuf *s); @@ -89,7 +90,7 @@ Returns a `char *` to the buffer if it has a length, otherwise may return NULL. Since the buffer may be reallocated, this pointer should not be trusted or used anymore after the next buffer manipulation call. -## uptr +## `Curl_dyn_uptr` ```c unsigned char *Curl_dyn_uptr(const struct dynbuf *s); @@ -99,7 +100,7 @@ Returns an `unsigned char *` to the buffer if it has a length, otherwise may return NULL. Since the buffer may be reallocated, this pointer should not be trusted or used anymore after the next buffer manipulation call. -## len +## `Curl_dyn_len` ```c size_t Curl_dyn_len(const struct dynbuf *s); @@ -108,7 +109,7 @@ size_t Curl_dyn_len(const struct dynbuf *s); Returns the length of the buffer in bytes. Does not include the terminating zero byte. -## setlen +## `Curl_dyn_setlen` ```c CURLcode Curl_dyn_setlen(struct dynbuf *s, size_t len); diff --git a/docs/EXPERIMENTAL.md b/docs/EXPERIMENTAL.md index bf359da22..9aaa7ada1 100644 --- a/docs/EXPERIMENTAL.md +++ b/docs/EXPERIMENTAL.md @@ -22,4 +22,4 @@ Experimental support in curl means: - HTTP/3 support and options - `CURLSSLOPT_NATIVE_CA` (No configure option, feature built in when supported) - The rustls backend -- WebSockets + - WebSocket diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 7451ee635..52608c08e 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -7,7 +7,7 @@ - range "globbing" support: [0-13], {one,two,three} - multiple file upload on a single command line - custom maximum transfer rate - - redirectable stderr + - redirect stderr - parallel transfers ## libcurl @@ -174,7 +174,7 @@ ## POP3S (1) - implicit `pop3s://` support - - explicit "STLS" usage to "upgrade" plain `pop3://` connections to use SSL + - explicit `STLS` usage to "upgrade" plain `pop3://` connections to use SSL - via http-proxy ## IMAP @@ -183,7 +183,7 @@ - SASL based authentication: Plain, Login, CRAM-MD5, Digest-MD5, NTLM (9), Kerberos 5 (4) and External. - list the folders of a mailbox - - select a mailbox with support for verifying the UIDVALIDITY + - select a mailbox with support for verifying the `UIDVALIDITY` - fetch emails with support for specifying the UID and SECTION - upload emails via the append command - enhanced command support for: EXAMINE, CREATE, DELETE, RENAME, STATUS, diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md index 0d6c5b2d7..f45aaa24c 100644 --- a/docs/GOVERNANCE.md +++ b/docs/GOVERNANCE.md @@ -116,7 +116,7 @@ admin of all things curl related server stuff, but Björn Stenberg and Linus Feltzing serve as backup admins for when Daniel is gone or unable. The primary server is paid for by Haxx. The machine is physically located in a -server bunker in Stockholm Sweden, operated by the company Portlane. +server bunker in Stockholm Sweden, operated by the company Glesys. The website contents are served to the web via Fastly and Daniel is the primary curl contact with Fastly. @@ -152,7 +152,7 @@ within the area of personal expertise and experience. ### Merge advice -When you are merging patches/PRs... +When you are merging patches/pull requests... - make sure the commit messages follow our template - squash patch sets into a few logical commits even if the PR did not, if diff --git a/docs/HISTORY.md b/docs/HISTORY.md index 87760a4d6..5a142b4b2 100644 --- a/docs/HISTORY.md +++ b/docs/HISTORY.md @@ -24,7 +24,7 @@ new maintainer of the project. HttpGet 0.3 was released in January 1997 and now it accepted HTTP URLs on the command line. -HttpGet 1.0 was released on April 8th 1997 with brand new HTTP proxy support. +HttpGet 1.0 was released on April 8 1997 with brand new HTTP proxy support. We soon found and fixed support for getting currencies over GOPHER. Once FTP download support was added, the name of the project was changed and urlget 2.0 @@ -130,7 +130,7 @@ August: The curl website gets 8000 visits weekly. Curl Corporation contacted Daniel to discuss "the name issue". After Daniel's reply, they have never since got back in touch again. -September: libcurl 7.9 introduces cookie jar and curl_formadd(). During the +September: libcurl 7.9 introduces cookie jar and `curl_formadd()`. During the forthcoming 7.9.x releases, we introduced the multi interface slowly and without many whistles. @@ -179,7 +179,7 @@ January: curl 7.11.0 introduced large file support. June: curl 7.12.0 introduced IDN support. 10 official web mirrors. This release bumped the major SONAME to 3 due to the removal of the -curl_formparse() function +`curl_formparse()` function August: Curl and libcurl 7.12.1 @@ -288,7 +288,7 @@ April: added the cyassl backend (later renamed to WolfSSL) July: Added support for Schannel (native Windows TLS backend) and Darwin SSL (Native Mac OS X and iOS TLS backend). - Supports metalink + Supports Metalink October: SSH-agent support. diff --git a/docs/HSTS.md b/docs/HSTS.md index cecdc75c0..e54102493 100644 --- a/docs/HSTS.md +++ b/docs/HSTS.md @@ -19,7 +19,7 @@ HTTP-only requests to a host name present in the cache will get internally - `CURLOPT_HSTS` - specify file name where to store the HSTS cache on close (and possibly read from at startup) -## curl cmdline options +## curl command line options - `--hsts [filename]` - enable HSTS, use the file as HSTS cache. If filename is `""` (no length) then no file will be used, only in-memory cache. @@ -32,13 +32,11 @@ For each hsts entry: [host name] "YYYYMMDD HH:MM:SS" -The `[host name]` is dot-prefixed if it is a includeSubDomain. +The `[host name]` is dot-prefixed if it includes subdomains. The time stamp is when the entry expires. -I considered using wget's file format for the HSTS cache. However, they store the time stamp as the epoch (number of seconds since 1970) and I strongly disagree with using that format. Instead I opted to use a format similar to the curl alt-svc cache file format. - ## Possible future additions - - `CURLOPT_HSTS_PRELOAD` - provide a set of preloaded HSTS host names + - `CURLOPT_HSTS_PRELOAD` - provide a set of HSTS host names to load first - ability to save to something else than a file diff --git a/docs/HTTP-COOKIES.md b/docs/HTTP-COOKIES.md index 73fa242bb..939e9fab2 100644 --- a/docs/HTTP-COOKIES.md +++ b/docs/HTTP-COOKIES.md @@ -38,10 +38,11 @@ The Netscape cookie file format stores one cookie per physical line in the file with a bunch of associated meta data, each field separated with - TAB. That file is called the cookiejar in curl terminology. + TAB. That file is called the cookie jar in curl terminology. - When libcurl saves a cookiejar, it creates a file header of its own in which - there is a URL mention that will link to the web version of this document. + When libcurl saves a cookie jar, it creates a file header of its own in + which there is a URL mention that will link to the web version of this + document. ## Cookie file format @@ -74,8 +75,8 @@ `-b, --cookie` tell curl a file to read cookies from and start the cookie engine, or if it - is not a file it will pass on the given string. -b name=var works and so does - -b cookiefile. + is not a file it will pass on the given string. `-b name=var` works and so + does `-b cookiefile`. `-j, --junk-session-cookies` @@ -106,7 +107,7 @@ `CURLOPT_COOKIEJAR` Tell libcurl to activate the cookie engine, and when the easy handle is - closed save all known cookies to the given cookiejar file. Write-only. + closed save all known cookies to the given cookie jar file. Write-only. `CURLOPT_COOKIELIST` @@ -127,7 +128,7 @@ ## Cookies with JavaScript - These days a lot of the web is built up by JavaScript. The webbrowser loads + These days a lot of the web is built up by JavaScript. The web browser loads complete programs that render the page you see. These JavaScript programs can also set and access cookies. diff --git a/docs/HTTP2.md b/docs/HTTP2.md index bd7b74116..a15bb3108 100644 --- a/docs/HTTP2.md +++ b/docs/HTTP2.md @@ -59,12 +59,12 @@ attempt to re-use 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 +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 connection for the same host in progress that might end up being possible to -multiplex on. It favours keeping the number of connections low to the cost of +multiplex on. It favors keeping the number of connections low to the cost of slightly longer time to first byte transferred. Applications diff --git a/docs/HTTP3.md b/docs/HTTP3.md index 1ca9eb8c6..16202b78c 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -291,10 +291,10 @@ that exists in curl's test dir. ### Caddy -[Install caddy](https://caddyserver.com/docs/install), you can even put the +[Install Caddy](https://caddyserver.com/docs/install), you can even put the single binary in a separate directory if you prefer. -In the same directory you put caddy, create a `Caddyfile` with the following +In the same directory you put Caddy, create a `Caddyfile` with the following content to run an HTTP/3 reverse-proxy on port 7443: ~~~ { @@ -311,6 +311,6 @@ localhost:7443 { } ~~~ -Then run caddy: +Then run Caddy: ./caddy start diff --git a/docs/INSTALL.md b/docs/INSTALL.md index c2782c69d..306df16dd 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -17,7 +17,9 @@ You can download and install curl and libcurl using the [vcpkg](https://github.c ./vcpkg integrate install vcpkg install curl[tool] -The curl port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. +The curl port in vcpkg is kept up to date by Microsoft team members and +community contributors. If the version is out of date, please [create an issue +or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. ## Building from git @@ -120,8 +122,8 @@ These options are provided to select the TLS backend to use. - NSS: `--with-nss` - OpenSSL: `--with-openssl` (also for BoringSSL and libressl) - rustls: `--with-rustls` - - schannel: `--with-schannel` - - secure transport: `--with-secure-transport` + - Schannel: `--with-schannel` + - Secure Transport: `--with-secure-transport` - wolfSSL: `--with-wolfssl` # Windows @@ -140,16 +142,16 @@ These options are provided to select the TLS backend to use. - [Run-Time Library Compiler Options](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library) - [Potential Errors Passing CRT Objects Across DLL Boundaries](https://docs.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries) -If your app is misbehaving in some strange way, or it is suffering from -memory corruption, before asking for further help, please try first to -rebuild every single library your app uses as well as your app using the -debug multithreaded dynamic C runtime. +If your app is misbehaving in some strange way, or it is suffering from memory +corruption, before asking for further help, please try first to rebuild every +single library your app uses as well as your app using the debug +multi-threaded dynamic C runtime. If you get linkage errors read section 5.7 of the FAQ document. ## MingW32 -Make sure that MinGW32's bin directory is in the search path, for example: +Make sure that MingW32's bin directory is in the search path, for example: ```cmd set PATH=c:\mingw32\bin;%PATH% @@ -175,9 +177,9 @@ set OPENSSL_PATH=c:\openssl-1.0.2c set LIBSSH2_PATH=c:\libssh2-1.6.0 ``` -It is also possible to build with other LDAP SDKs than MS LDAP; currently -it is possible to build with native Win32 OpenLDAP, or with the Novell CLDAP -SDK. If you want to use these you need to set these vars: +It is also possible to build with other LDAP installations than MS LDAP; +currently it is possible to build with native Win32 OpenLDAP, or with the +*Novell CLDAP* SDK. If you want to use these you need to set these vars: ```cmd set LDAP_SDK=c:\openldap @@ -207,7 +209,7 @@ environment, therefore, you cannot use the various disable-protocol options of the configure utility on this platform. You can use specific defines to disable specific protocols and features. See -[CURL-DISABLE.md](CURL-DISABLE.md) for the full list. +[CURL-DISABLE](CURL-DISABLE.md) for the full list. If you want to set any of these defines you have the following options: @@ -241,13 +243,11 @@ lwIP header file `<lwip/opt.h>` (or another lwIP header that includes this) before including any libcurl header. Your program does not need the `USE_LWIPSOCK` preprocessor definition which is for libcurl internals only. -Compilation has been verified with [lwIP -1.4.0](https://download.savannah.gnu.org/releases/lwip/lwip-1.4.0.zip) and -[contrib-1.4.0](https://download.savannah.gnu.org/releases/lwip/contrib-1.4.0.zip). +Compilation has been verified with lwIP 1.4.0. This BSD-style lwIP TCP/IP stack support must be considered experimental given that it has been verified that lwIP 1.4.0 still needs some polish, and libcurl -might yet need some additional adjustment, caveat emptor. +might yet need some additional adjustment. ## Important static libcurl usage note @@ -382,12 +382,12 @@ For IBM i (formerly OS/400), you can use curl in two different ways: There are some additional limitations and quirks with curl on this platform; they affect both environments. -## Multithreading notes +## Multi-threading notes By default, jobs in IBM i will not start with threading enabled. (Exceptions include interactive PASE sessions started by `QP2TERM` or SSH.) If you use -curl in an environment without threading when options like async DNS were -enabled, you will get messages like: +curl in an environment without threading when options like asynchronous DNS +were enabled, you will get messages like: ``` getaddrinfo() thread failed to start @@ -407,9 +407,9 @@ Download and unpack the curl package. Set environment variables to point to the cross-compile toolchain and call configure with any options you need. Be sure and specify the `--host` and -`--build` parameters at configuration time. The following script is an -example of cross-compiling for the IBM 405GP PowerPC processor using the -toolchain from MonteVista for Hardhat Linux. +`--build` parameters at configuration time. The following script is an example +of cross-compiling for the IBM 405GP PowerPC processor using the toolchain on +Linux. ```bash #! /bin/sh @@ -461,7 +461,7 @@ know your application is not going to need. Besides specifying the use, here are some other flags that can reduce the size of the library by disabling support for some feature: - - `--disable-alt-svc` (HTTP Alt-Srv) + - `--disable-alt-svc` (HTTP Alt-Svc) - `--disable-ares` (the C-ARES DNS library) - `--disable-cookies` (HTTP cookies) - `--disable-crypto-auth` (cryptographic authentication) @@ -478,8 +478,8 @@ disabling support for some feature: - `--disable-ntlm-wb` (NTLM WinBind) - `--disable-progress-meter` (graphical progress meter in library) - `--disable-proxy` (HTTP and SOCKS proxies) - - `--disable-pthreads` (multithreading) - - `--disable-socketpair` (socketpair for async name resolving) + - `--disable-pthreads` (multi-threading) + - `--disable-socketpair` (socketpair for asynchronous name resolving) - `--disable-threaded-resolver` (threaded name resolver) - `--disable-tls-srp` (Secure Remote Password authentication for TLS) - `--disable-unix-sockets` (UNIX sockets) @@ -525,8 +525,8 @@ line. Following is a list of appropriate key words for those configure options that are not automatically detected: - `--disable-cookies` !cookies - - `--disable-dateparse` !RETRY-AFTER !CURLOPT_TIMECONDITION !CURLINFO_FILETIME !If-Modified-Since !getdate !-z - - `--disable-libcurl-option` !--libcurl + - `--disable-dateparse` !RETRY-AFTER !`CURLOPT_TIMECONDITION` !`CURLINFO_FILETIME` !`If-Modified-Since` !`curl_getdate` !`-z` + - `--disable-libcurl-option` !`--libcurl` - `--disable-verbose` !verbose\ logs # PORTS diff --git a/docs/INTERNALS.md b/docs/INTERNALS.md index afb13b512..30cce8c98 100644 --- a/docs/INTERNALS.md +++ b/docs/INTERNALS.md @@ -25,7 +25,7 @@ versions of libs, tools and operating systems. - c-ares 1.16.0 - libidn2 2.0.0 - wolfSSL 2.0.0 - - openldap 2.0 + - OpenLDAP 2.0 - MIT Kerberos 1.2.4 - GSKit V5R3M0 - NSS 3.14.x diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS index 976cf325e..5a1dea1b5 100644 --- a/docs/KNOWN_BUGS +++ b/docs/KNOWN_BUGS @@ -969,10 +969,10 @@ problems may have been fixed or changed somewhat since this was written. 12.1 OpenLDAP hangs after returning results - By configuration defaults, openldap automatically chase referrals on + By configuration defaults, OpenLDAP automatically chase referrals on secondary socket descriptors. The OpenLDAP backend is asynchronous and thus should monitor all socket descriptors involved. Currently, these secondary - descriptors are not monitored, causing openldap library to never receive + descriptors are not monitored, causing OpenLDAP library to never receive data from them. As a temporary workaround, disable referrals chasing by configuration. diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 6b8acd672..4bfe42911 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -6,7 +6,7 @@ Get the main page from a web-server: curl https://www.example.com/ -Get the README file the user's home directory at funet's ftp-server: +Get a README file from an FTP server: curl ftp://ftp.funet.fi/README @@ -77,11 +77,11 @@ Fetch two files and store them with their remote names: ### FTP -To ftp files using name+passwd, include them in the URL like: +To ftp files using name and password, include them in the URL like: curl ftp://name:passwd@machine.domain:port/full/path/to/file -or specify them with the -u flag like +or specify them with the `-u` flag like curl -u name:passwd ftp://machine.domain:port/full/path/to/file @@ -90,9 +90,9 @@ or specify them with the -u flag like It is just like for FTP, but you may also want to specify and use SSL-specific options for certificates etc. -Note that using `FTPS://` as prefix is the "implicit" way as described in the -standards while the recommended "explicit" way is done by using FTP:// and the -`--ftp-ssl` option. +Note that using `FTPS://` as prefix is the *implicit* way as described in the +standards while the recommended *explicit* way is done by using `FTP://` and +the `--ssl-reqd` option. ### SFTP / SCP @@ -180,8 +180,8 @@ transfers, and curl's `-v` option to see exactly what curl is sending. ## Ranges HTTP 1.1 introduced byte-ranges. Using this, a client can request to get only -one or more subparts of a specified document. Curl supports this with the `-r` -flag. +one or more sub-parts of a specified document. Curl supports this with the +`-r` flag. Get the first 100 bytes of a document: @@ -281,10 +281,10 @@ cookies section. ## POST (HTTP) -It's easy to post data using curl. This is done using the `-d <data>` option. +It is easy to post data using curl. This is done using the `-d <data>` option. The post data must be urlencoded. -Post a simple "name" and "phone" guestbook. +Post a simple `name` and `phone` guestbook. curl -d "name=Rafael%20Sagula&phone=3320780" http://www.where.com/guest.cgi @@ -292,15 +292,15 @@ How to post a form with curl, lesson #1: Dig out all the `<input>` tags in the form that you want to fill in. -If there is a "normal" post, you use `-d` to post. `-d` takes a full "post -string", which is in the format +If there is a normal post, you use `-d` to post. `-d` takes a full post +string, which is in the format <variable1>=<data1>&<variable2>=<data2>&... -The 'variable' names are the names set with `"name="` in the `<input>` tags, -and the data is the contents you want to fill in for the inputs. The data -*must* be properly URL encoded. That means you replace space with + and that -you replace weird letters with %XX where XX is the hexadecimal representation +The variable names are the names set with `"name="` in the `<input>` tags, and +the data is the contents you want to fill in for the inputs. The data *must* +be properly URL encoded. That means you replace space with + and that you +replace weird letters with `%XX` where `XX` is the hexadecimal representation of the letter's ASCII code. Example: @@ -316,7 +316,7 @@ Example: </form> ``` -We want to enter user 'foobar' with password '12345'. +We want to enter user `foobar` with password `12345`. To post to this, you enter a curl command line like: @@ -331,7 +331,7 @@ multipart/form-data type. This latter type supports things like file upload. be read from a file, use `@filename` as contents. When specifying a file, you can also specify the file content type by appending `;type=<mime type>` to the file name. You can also post the contents of several files in one field. For -example, the field name 'coolfiles' is used to send three files, with +example, the field name `coolfiles` is used to send three files, with different content types using the following syntax: curl -F "coolfiles=@fil1.gif;type=image/gif,fil2.txt,fil3.html" @@ -340,15 +340,15 @@ different content types using the following syntax: If the content-type is not specified, curl will try to guess from the file extension (it only knows a few), or use the previously specified type (from an earlier file if several files are specified in a list) or else it will use the -default type 'application/octet-stream'. +default type `application/octet-stream`. Emulate a fill-in form with `-F`. Let's say you fill in three fields in a form. One field is a file name which to post, one field is your name and one field is a file description. We want to post the file we have written named -"cooltext.txt". To let curl do the posting of this data instead of your -favourite browser, you have to read the HTML source of the form page and find +`cooltext.txt`. To let curl do the posting of this data instead of your +favorite browser, you have to read the HTML source of the form page and find the names of the input fields. In our example, the input field names are -'file', 'yourname' and 'filedescription'. +`file`, `yourname` and `filedescription`. curl -F "file=@cooltext.txt" -F "yourname=Daniel" -F "filedescription=Cool text file with cool text inside" @@ -356,7 +356,7 @@ the names of the input fields. In our example, the input field names are To send two files in one post you can do it in two ways: -Send multiple files in a single "field" with a single field name: +Send multiple files in a single field with a single field name: curl -F "pictures=@dog.gif,cat.gif" $URL @@ -415,7 +415,7 @@ client's side. The server sets cookies by sending a response line in the headers that looks like `Set-Cookie: <data>` where the data part then typically contains a set of `NAME=VALUE` pairs (separated by semicolons `;` like `NAME1=VALUE1; NAME2=VALUE2;`). The server can also specify for what path -the "cookie" should be used for (by specifying `path=value`), when the cookie +the cookie should be used for (by specifying `path=value`), when the cookie should expire (`expire=DATE`), for what domain to use it (`domain=NAME`) and if it should be used on secure connections only (`secure`). @@ -426,7 +426,7 @@ Set-Cookie: sessionid=boo123; path="/foo"; ``` it means the server wants that first pair passed on when we get anything in a -path beginning with "/foo". +path beginning with `/foo`. Example, get a page that wants my name passed in a cookie: @@ -439,9 +439,9 @@ manner similar to: curl --dump-header headers www.example.com ... you can then in a second connect to that (or another) site, use the -cookies from the 'headers' file like: +cookies from the `headers.txt` file like: - curl -b headers www.example.com + curl -b headers.txt www.example.com While saving headers to a file is a working way to store cookies, it is however error-prone and not the preferred way to do this. Instead, make curl @@ -450,9 +450,9 @@ this: curl -c cookies.txt www.example.com -Note that by specifying `-b` you enable the "cookie awareness" and with `-L` -you can make curl follow a location: (which often is used in combination with -cookies). So that if a site sends cookies and a location, you can use a +Note that by specifying `-b` you enable the cookie engine and with `-L` you +can make curl follow a `location:` (which often is used in combination with +cookies). If a site sends cookies and a location field, you can use a non-existing file to trigger the cookie awareness like: curl -L -b empty.txt www.example.com @@ -460,9 +460,9 @@ non-existing file to trigger the cookie awareness like: The file to read cookies from must be formatted using plain HTTP headers OR as Netscape's cookie file. Curl will determine what kind it is based on the file contents. In the above command, curl will parse the header and store the -cookies received from www.example.com. curl will send to the server the -stored cookies which match the request as it follows the location. The file -"empty.txt" may be a nonexistent file. +cookies received from www.example.com. curl will send to the server the stored +cookies which match the request as it follows the location. The file +`empty.txt` may be a nonexistent file. To read and write cookies from a Netscape cookie file, you can set both `-b` and `-c` to use the same file: @@ -480,18 +480,18 @@ happening. The different fields in the output have the following meaning: From left-to-right: - - % - percentage completed of the whole transfer - - Total - total size of the whole expected transfer - - % - percentage completed of the download - - Received - currently downloaded amount of bytes - - % - percentage completed of the upload - - Xferd - currently uploaded amount of bytes - - Average Speed Dload - the average transfer speed of the download - - Average Speed Upload - the average transfer speed of the upload - - Time Total - expected time to complete the operation - - Time Current - time passed since the invoke - - Time Left - expected time left to completion - - Curr.Speed - the average transfer speed the last 5 seconds (the first + - `%` - percentage completed of the whole transfer + - `Total` - total size of the whole expected transfer + - `%` - percentage completed of the download + - `Received` - currently downloaded amount of bytes + - `%` - percentage completed of the upload + - `Xferd` - currently uploaded amount of bytes + - `Average Speed Dload` - the average transfer speed of the download + - `Average Speed Upload` - the average transfer speed of the upload + - `Time Total` - expected time to complete the operation + - `Time Current` - time passed since the invoke + - `Time Left` - expected time left to completion + - `Curr.Speed` - the average transfer speed the last 5 seconds (the first 5 seconds of a transfer is based on less time of course.) The `-#` option will display a totally different progress bar that does not @@ -517,7 +517,7 @@ operation must be completed in whole within 30 minutes: Forcing curl not to transfer data faster than a given rate is also possible, which might be useful if you are using a limited bandwidth connection and you do not want your transfer to use all of it (sometimes referred to as -"bandwidth throttle"). +*bandwidth throttle*). Make curl transfer data no faster than 10 kilobytes per second: @@ -681,8 +681,8 @@ curl is also capable of using client certificates to get/post files from sites that require valid certificates. The only drawback is that the certificate needs to be in PEM-format. PEM is a standard and open format to store certificates with, but it is not used by the most commonly used browsers. If -you want curl to use the certificates you use with your (favourite) browser, -you may need to download/compile a converter that can convert your browser's +you want curl to use the certificates you use with your favorite browser, you +may need to download/compile a converter that can convert your browser's formatted certificates to PEM formatted ones. Example on how to automatically retrieve a document using a certificate with a @@ -695,10 +695,9 @@ prompted for the correct password before any data can be received. Many older HTTPS servers have problems with specific SSL or TLS versions, which newer versions of OpenSSL etc use, therefore it is sometimes useful to -specify what SSL-version curl should use. Use -3, -2 or -1 to specify that -exact SSL version to use (for SSLv3, SSLv2 or TLSv1 respectively): +specify what TLS version curl should use.: - curl -2 https://secure.site.com/ + curl --tlv1.0 https://secure.site.com/ Otherwise, curl will attempt to use a sensible TLS default version. @@ -735,13 +734,13 @@ one. Do this by prepending the date string with a `-`, as in: curl -z -local.html http://remote.server.com/remote.html -You can specify a "free text" date as condition. Tell curl to only download -the file if it was updated since January 12, 2012: +You can specify a plain text date as condition. Tell curl to only download the +file if it was updated since January 12, 2012: curl -z "Jan 12 2012" http://remote.server.com/remote.html -Curl will then accept a wide range of date formats. You always make the date -check the other way around by prepending it with a dash (`-`). +curl accepts a wide range of date formats. You always make the date check the +other way around by prepending it with a dash (`-`). ## DICT @@ -751,8 +750,8 @@ For fun try curl dict://dict.org/d:heisenbug:jargon curl dict://dict.org/d:daniel:gcide -Aliases for 'm' are 'match' and 'find', and aliases for 'd' are 'define' and -'lookup'. For example, +Aliases for `m` are `match` and `find`, and aliases for `d` are `define` and +`lookup`. For example, curl dict://dict.org/find:curl @@ -770,13 +769,12 @@ If you have installed the OpenLDAP library, curl can take advantage of it and offer `ldap://` support. On Windows, curl will use WinLDAP from Platform SDK by default. -Default protocol version used by curl is LDAPv3. LDAPv2 will be used as a -fallback mechanism in case LDAPv3 fails to connect. +Default protocol version used by curl is LDAP version 3. Version 2 will be +used as a fallback mechanism in case version 3 fails to connect. LDAP is a complex thing and writing an LDAP query is not an easy task. I do advise you to dig up the syntax description for that elsewhere. One such place -might be: [RFC 2255, The LDAP URL -Format](https://curl.se/rfc/rfc2255.txt) +might be: [RFC 2255, The LDAP URL Format](https://curl.se/rfc/rfc2255.txt) To show you an example, this is how I can get all people from my local LDAP server that has a certain sub-domain in their email address: @@ -817,8 +815,8 @@ set in (only an asterisk, `*` matches all hosts) NO_PROXY If the host name matches one of these strings, or the host is within the -domain of one of these strings, transactions with that node will not be -proxied. When a domain is used, it needs to start with a period. A user can +domain of one of these strings, transactions with that node will not be done +over proxy. When a domain is used, it needs to start with a period. A user can specify that both www.example.com and foo.example.com should not use a proxy by setting `NO_PROXY` to `.example.com`. By including the full name you can exclude specific host names, so to make `www.example.com` not use a proxy but @@ -859,13 +857,13 @@ ending newline: Curl supports kerberos4 and kerberos5/GSSAPI for FTP transfers. You need the kerberos package installed and used at curl build time for it to be available. -First, get the krb-ticket the normal way, like with the kinit/kauth tool. +First, get the krb-ticket the normal way, like with the `kinit`/`kauth` tool. Then use curl in way similar to: curl --krb private ftp://krb4site.com -u username:fakepwd There is no use for a password on the `-u` switch, but a blank one will make -curl ask for one and you already entered the real password to kinit/kauth. +curl ask for one and you already entered the real password to `kinit`/`kauth`. ## TELNET @@ -908,7 +906,7 @@ decreases connection time for all but the first transfer and it makes a far better use of the network. Note that curl cannot use persistent connections for transfers that are used -in subsequence curl invokes. Try to stuff as many URLs as possible on the same +in subsequent curl invokes. Try to stuff as many URLs as possible on the same command line if they are using the same host, as that will make the transfers faster. If you use an HTTP proxy for file transfers, practically all transfers will be persistent. @@ -963,28 +961,28 @@ these mailing lists instead of mailing any individual. Available lists include: -### curl-users +### `curl-users` Users of the command line tool. How to use it, what does not work, new features, related tools, questions, news, installations, compilations, running, porting etc. -### curl-library +### `curl-library` Developers using or developing libcurl. Bugs, extensions, improvements. -### curl-announce +### `curl-announce` Low-traffic. Only receives announcements of new public versions. At worst, that makes something like one or two mails per month, but usually only one mail every second month. -### curl-and-php +### `curl-and-php` Using the curl functions in PHP. Everything curl with a PHP angle. Or PHP with a curl angle. -### curl-and-python +### `curl-and-python` Python hackers using curl with or without the python binding pycurl. diff --git a/docs/NEW-PROTOCOL.md b/docs/NEW-PROTOCOL.md index 9a1451817..43016e22c 100644 --- a/docs/NEW-PROTOCOL.md +++ b/docs/NEW-PROTOCOL.md @@ -98,7 +98,7 @@ will try to debug something five years from now can figure out functionality a little easier! The protocol specification itself should be freely available without requiring -any NDA or similar. +a non-disclosure agreement or similar. ## Do not compare diff --git a/docs/PARALLEL-TRANSFERS.md b/docs/PARALLEL-TRANSFERS.md index 325e64f9b..8ab477862 100644 --- a/docs/PARALLEL-TRANSFERS.md +++ b/docs/PARALLEL-TRANSFERS.md @@ -27,8 +27,8 @@ completely different than the regular one used for each single transfer. o total time all transfers are expected to take (if sizes are known) o current time the transfers have spent so far o estimated time left (if sizes are known) - o current transfer speed (the faster of UL/DL speeds measured over the last - few seconds) + o current transfer speed (the faster of upload/download speeds measured over + the last few seconds) Example: diff --git a/docs/RELEASE-PROCEDURE.md b/docs/RELEASE-PROCEDURE.md index 623b3ffd1..776bebe83 100644 --- a/docs/RELEASE-PROCEDURE.md +++ b/docs/RELEASE-PROCEDURE.md @@ -16,14 +16,14 @@ in the source code repo tag and we use underscores instead of dots in the version number. Make sure the tag is GPG signed (using -s). -- run "./maketgz 7.34.0" to build the release tarballs. It is important that +- run `./maketgz 7.34.0` to build the release tarballs. It is important that you run this on a machine with the correct set of autotools etc installed as this is what then will be shipped and used by most users on \*nix like systems. - push the git commits and the new tag -- gpg sign the 4 tarballs as maketgz suggests +- GPG sign the 4 tarballs as `maketgz` suggests - upload the 8 resulting files to the primary download directory diff --git a/docs/SECURITY-PROCESS.md b/docs/SECURITY-PROCESS.md index 3203146e1..806122c8b 100644 --- a/docs/SECURITY-PROCESS.md +++ b/docs/SECURITY-PROCESS.md @@ -24,8 +24,8 @@ reference to the security nature of the commit if done prior to the public announcement. - The person discovering the issue, the reporter, reports the vulnerability on - [https://hackerone.com/curl](https://hackerone.com/curl). Issues filed there - reach a handful of selected and trusted people. + [HackerOne](https://hackerone.com/curl). Issues filed there reach a handful + of selected and trusted people. - Messages that do not relate to the reporting or managing of an undisclosed security vulnerability in curl or libcurl are ignored and no further action @@ -112,9 +112,9 @@ somewhat over time and a list somewhere will only risk getting outdated. 2. Name the advisory file after the allocated CVE id. -3. Add a line on the top of the array in `curl-www/docs/vuln.pm'. +3. Add a line on the top of the array in `curl-www/docs/vuln.pm`. -4. Put the new advisory markdown file in the curl-www/docs/ directory. Add it +4. Put the new advisory markdown file in the `curl-www/docs/` directory. Add it to the git repository. 5. Run `make` in your local web checkout and verify that things look fine. @@ -122,7 +122,7 @@ somewhat over time and a list somewhere will only risk getting outdated. 6. On security advisory release day, push the changes on the curl-www repository's remote master branch. -## Hackerone +## HackerOne Request the issue to be disclosed. If there are sensitive details present in the report and discussion, those should be redacted from the disclosure. The diff --git a/docs/SSL-PROBLEMS.md b/docs/SSL-PROBLEMS.md index 4afe30018..29f400a59 100644 --- a/docs/SSL-PROBLEMS.md +++ b/docs/SSL-PROBLEMS.md @@ -17,7 +17,7 @@ ## CA certs CA certs are used to digitally verify the server's certificate. You need a - "ca bundle" for this. See lots of more details on this in the SSLCERTS + "ca bundle" for this. See lots of more details on this in the `SSLCERTS` document. ## CA bundle missing intermediate certificates @@ -59,7 +59,7 @@ ciphers from its default set (slightly depending on SSL backend in use). You may have to explicitly provide an alternative list of ciphers for curl - to use to allow the server to use a WEAK cipher for you. + to use to allow the server to use a weak cipher for you. Note that these weak ciphers are identified as flawed. For example, this includes symmetric ciphers with less than 128 bit keys and RC4. @@ -68,9 +68,8 @@ support the legacy handshakes and algorithms used by those versions, so we advice against building curl to use Schannel on really old Windows versions. - References: - - https://datatracker.ietf.org/doc/html/draft-popov-tls-prohibiting-rc4-01 + Reference: [Prohibiting RC4 Cipher + Suites](https://datatracker.ietf.org/doc/html/draft-popov-tls-prohibiting-rc4-01) ## Allow BEAST diff --git a/docs/SSLCERTS.md b/docs/SSLCERTS.md index 9e6087373..7f2f73557 100644 --- a/docs/SSLCERTS.md +++ b/docs/SSLCERTS.md @@ -6,7 +6,6 @@ SSL is TLS SSL is the old name. It is called TLS these days. - Native SSL ---------- @@ -21,15 +20,16 @@ It is about trust ----------------- This system is about trust. In your local CA certificate store you have certs -from *trusted* Certificate Authorities that you then can use to verify that the -server certificates you see are valid. They are signed by one of the CAs you -trust. +from *trusted* Certificate Authorities that you then can use to verify that +the server certificates you see are valid. They are signed by one of the +certificate authorities you trust. -Which CAs do you trust? You can decide to trust the same set of companies your -operating system trusts, or the set one of the known browsers trust. That is -basically trust via someone else you trust. You should just be aware that -modern operating systems and browsers are setup to trust *hundreds* of -companies and in recent years several such CAs have been found untrustworthy. +Which certificate authorities do you trust? You can decide to trust the same +set of companies your operating system trusts, or the set one of the known +browsers trust. That is basically trust via someone else you trust. You should +just be aware that modern operating systems and browsers are setup to trust +*hundreds* of companies and in recent years several certificate authorities +have been found untrustworthy. Certificate Verification ------------------------ @@ -39,8 +39,8 @@ by using a CA certificate store that the SSL library can use to make sure the peer's server certificate is valid. If you communicate with HTTPS, FTPS or other TLS-using servers using -certificates that are signed by CAs present in the store, you can be sure -that the remote server really is the one it claims to be. +certificates in the CA store, you can be sure that the remote server really is +the one it claims to be. If the remote server uses a self-signed certificate, if you do not install a CA cert store, if the server uses a certificate signed by a CA that is not @@ -51,30 +51,31 @@ server, do one of the following: 1. Tell libcurl to *not* verify the peer. With libcurl you disable this with `curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, FALSE);` - With the curl command line tool, you disable this with -k/--insecure. + With the curl command line tool, you disable this with `-k`/`--insecure`. 2. Get a CA certificate that can verify the remote server and use the proper option to point out this CA cert for verification when connecting. For libcurl hackers: `curl_easy_setopt(curl, CURLOPT_CAINFO, cacert);` - With the curl command line tool: --cacert [file] + With the curl command line tool: `--cacert [file]` 3. Add the CA cert for your server to the existing default CA certificate store. The default CA certificate store can be changed at compile time with the following configure options: - --with-ca-bundle=FILE: use the specified file as the CA certificate store. - CA certificates need to be concatenated in PEM format into this file. + `--with-ca-bundle=FILE`: use the specified file as the CA certificate + store. CA certificates need to be concatenated in PEM format into this + file. - --with-ca-path=PATH: use the specified path as CA certificate store. CA + `--with-ca-path=PATH`: use the specified path as CA certificate store. CA certificates need to be stored as individual PEM files in this directory. You may need to run c_rehash after adding files there. - If neither of the two options is specified, configure will try to auto-detect - a setting. It's also possible to explicitly not hardcode any default store - but rely on the built in default the crypto library may provide instead. - You can achieve that by passing both --without-ca-bundle and - --without-ca-path to the configure script. + If neither of the two options is specified, configure will try to + auto-detect a setting. It's also possible to explicitly not set any + default store but rely on the built in default the crypto library may + provide instead. You can achieve that by passing both + `--without-ca-bundle` and `--without-ca-path` to the configure script. If you use Internet Explorer, this is one way to get extract the CA cert for a particular server: @@ -83,22 +84,21 @@ server, do one of the following: - Find out where the CA certificate is kept (Certificate> Authority Information Access>URL) - Get a copy of the crt file using curl - - Convert it from crt to PEM using the openssl tool: - openssl x509 -inform DES -in yourdownloaded.crt \ - -out outcert.pem -text - - Add the 'outcert.pem' to the CA certificate store or use it stand-alone + - Convert it from crt to PEM using the OpenSSL tool: + `openssl x509 -inform DES -in yourdownloaded.crt -out outcert.pem -text` + - Add the `outcert.pem` to the CA certificate store or use it stand-alone as described below. - If you use the 'openssl' tool, this is one way to get extract the CA cert + If you use the `openssl` tool, this is one way to get extract the CA cert for a particular server: - `openssl s_client -showcerts -servername server -connect server:443 > cacert.pem` - type "quit", followed by the "ENTER" key - The certificate will have "BEGIN CERTIFICATE" and "END CERTIFICATE" markers. - - If you want to see the data in the certificate, you can do: "openssl - x509 -inform PEM -in certfile -text -out certdata" where certfile is - the cert you extracted from logfile. Look in certdata. + - If you want to see the data in the certificate, you can do: `openssl + x509 -inform PEM -in certfile -text -out certdata` where `certfile` is + the cert you extracted from logfile. Look in `certdata`. - If you want to trust the certificate, you can add it to your CA certificate store or use it stand-alone as described. Just remember that the security is no better than the way you obtained the certificate. @@ -132,18 +132,20 @@ Certificate Verification with NSS If libcurl was built with NSS support, then depending on the OS distribution, it is probably required to take some additional steps to use the system-wide -CA cert db. RedHat ships with an additional module, libnsspem.so, which +CA cert db. Red Hat ships with an additional module, libnsspem.so, which enables NSS to read the OpenSSL PEM CA bundle. On openSUSE you can install -p11-kit-nss-trust which makes NSS use the system wide CA certificate store. NSS -also has a new [database format](https://wiki.mozilla.org/NSS_Shared_DB). - -Starting with version 7.19.7, libcurl automatically adds the 'sql:' prefix to -the certdb directory (either the hardcoded default /etc/pki/nssdb or the -directory configured with SSL_DIR environment variable). To check which certdb -format your distribution provides, examine the default certdb location: -/etc/pki/nssdb; the new certdb format can be identified by the filenames -cert9.db, key4.db, pkcs11.txt; filenames of older versions are cert8.db, -key3.db, secmod.db. +p11-kit-nss-trust which makes NSS use the system wide CA certificate +store. NSS also has a new [database +format](https://wiki.mozilla.org/NSS_Shared_DB). + +Starting with version 7.19.7, libcurl automatically adds the `sql:` prefix to +the certificate database directory (either the set default `/etc/pki/nssdb` or +the directory configured with the `SSL_DIR` environment variable). To check +which certificate database format your distribution provides, examine the +default certificate database location: `/etc/pki/nssdb`; the new certificate +database format can be identified by the filenames `cert9.db`, `key4.db`, +`pkcs11.txt`; filenames of older versions are `cert8.db`, `key3.db`, +`secmod.db`. Certificate Verification with Schannel and Secure Transport ----------------------------------------------------------- diff --git a/docs/TheArtOfHttpScripting.md b/docs/TheArtOfHttpScripting.md index 78dbd7a8f..7d0d77e66 100644 --- a/docs/TheArtOfHttpScripting.md +++ b/docs/TheArtOfHttpScripting.md @@ -66,7 +66,7 @@ ## See the Response By default curl sends the response to stdout. You need to redirect it - somewhere to avoid that, most often that is done with ` -o` or `-O`. + somewhere to avoid that, most often that is done with `-o` or `-O`. # URL @@ -74,7 +74,7 @@ The Uniform Resource Locator format is how you specify the address of a particular resource on the Internet. You know these, you have seen URLs like - https://curl.se or https://yourbank.com a million times. RFC 3986 is the + https://curl.se or https://example.com a million times. RFC 3986 is the canonical spec. And yeah, the formal name is not URL, it is URI. ## Host @@ -169,7 +169,7 @@ any. No limits. You will then get requests repeated over and over for all the given URLs. - Example, send two GETs: + Example, send two GET requests: curl http://url1.example.com http://url2.example.com @@ -435,7 +435,7 @@ applications use this information to decide how to display pages. Silly web programmers try to make different pages for users of different browsers to make them look the best possible for their particular browsers. They usually - also do different kinds of JavaScript, VBScript etc. + also do different kinds of JavaScript etc. At times, you will see that getting a page with curl will not return the same page that you see when getting the page with your browser. Then you know it @@ -554,9 +554,8 @@ SSL. SSL encrypts all the data that is sent and received over the network and thus makes it harder for attackers to spy on sensitive information. - SSL (or TLS as the latest version of the standard is called) offers a - truckload of advanced features to allow all those encryptions and key - infrastructure mechanisms encrypted HTTP requires. + SSL (or TLS as the current version of the standard is called) offers a set of + advanced features to do secure transfers over HTTP. Curl supports encrypted fetches when built to use a TLS library and it can be built to use one out of a fairly large set of libraries - `curl -V` will show @@ -584,7 +583,7 @@ verified. More about server certificate verification and ca cert bundles can be read in - the [SSLCERTS document](https://curl.se/docs/sslcerts.html). + the [`SSLCERTS` document](https://curl.se/docs/sslcerts.html). At times you may end up with your own CA cert store and then you can tell curl to use that to verify the server's certificate: @@ -598,14 +597,15 @@ Doing fancy stuff, you may need to add or change elements of a single curl request. - For example, you can change the POST request to a PROPFIND and send the data - as `Content-Type: text/xml` (instead of the default Content-Type) like this: + For example, you can change the POST method to `PROPFIND` and send the data + as `Content-Type: text/xml` (instead of the default `Content-Type`) like + this: curl --data "<xml>" --header "Content-Type: text/xml" \ --request PROPFIND example.com You can delete a default header by providing one without content. Like you - can ruin the request by chopping off the Host: header: + can ruin the request by chopping off the `Host:` header: curl --header "Host:" http://www.example.com diff --git a/docs/URL-SYNTAX.md b/docs/URL-SYNTAX.md index 0b452f87f..d6470ab99 100644 --- a/docs/URL-SYNTAX.md +++ b/docs/URL-SYNTAX.md @@ -259,7 +259,7 @@ A folder list on the user's inbox: imap://user:password@mail.example.com/INBOX -Select the user's inbox and fetch message with uid = 1: +Select the user's inbox and fetch message with `uid = 1`: imap://user:password@mail.example.com/INBOX/;UID=1 @@ -289,26 +289,27 @@ subject line: imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows -Searching via the query part of the URL `?` is a search request for the results -to be returned as message sequence numbers (MAILINDEX). It is possible to make -a search request for results to be returned as unique ID numbers (UID) by using -a custom curl request via `-X`. UID numbers are unique per session (and -multiple sessions when UIDVALIDITY is the same). For example, if you are -searching for `"foo bar"` in header+body (TEXT) and you want the matching -MAILINDEX numbers returned then you could search via URL: +Searching via the query part of the URL `?` is a search request for the +results to be returned as message sequence numbers (`MAILINDEX`). It is +possible to make a search request for results to be returned as unique ID +numbers (`UID`) by using a custom curl request via `-X`. `UID` numbers are +unique per session (and multiple sessions when `UIDVALIDITY` is the same). For +example, if you are searching for `"foo bar"` in header+body (`TEXT`) and you +want the matching `MAILINDEX` numbers returned then you could search via URL: imap://user:password@mail.example.com/INBOX?TEXT%20%22foo%20bar%22 -.. but if you wanted matching UID numbers you would have to use a custom request: +.. but if you wanted matching `UID` numbers you would have to use a custom +request: imap://user:password@mail.example.com/INBOX -X "UID SEARCH TEXT \"foo bar\"" For more information about IMAP commands please see RFC 9051. For more information about the individual components of an IMAP URL please see RFC 5092. -* Note old curl versions would FETCH by message sequence number when UID was -specified in the URL. That was a bug fixed in 7.62.0, which added MAILINDEX to -FETCH by mail sequence number. +* Note old curl versions would `FETCH` by message sequence number when `UID` +was specified in the URL. That was a bug fixed in 7.62.0, which added +`MAILINDEX` to `FETCH` by mail sequence number. ## LDAP @@ -317,15 +318,15 @@ Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field is separated by a question mark and when that field is not required an empty string with the question mark separator should be included. -Search for the DN as `My Organization`: +Search for the `DN` as `My Organization`: ldap://ldap.example.com/o=My%20Organization -the same search but will only return postalAddress attributes: +the same search but will only return `postalAddress` attributes: ldap://ldap.example.com/o=My%20Organization?postalAddress -Search for an empty DN and request information about the +Search for an empty `DN` and request information about the `rootDomainNamingContext` attribute for an Active Directory server: ldap://ldap.example.com/?rootDomainNamingContext diff --git a/docs/VERSIONS.md b/docs/VERSIONS.md index b1727597e..0ec9cd518 100644 --- a/docs/VERSIONS.md +++ b/docs/VERSIONS.md @@ -37,7 +37,7 @@ Version Numbers and Releases As a service to any application that might want to support new libcurl features while still being able to build with older versions, all releases - have the libcurl version stored in the curl/curlver.h file using a static + have the libcurl version stored in the `curl/curlver.h` file using a static numbering scheme that can be used for comparison. The version number is defined as: @@ -45,10 +45,10 @@ Version Numbers and Releases #define LIBCURL_VERSION_NUM 0xXXYYZZ ``` - Where XX, YY and ZZ are the main version, release and patch numbers in + Where `XX`, `YY` and `ZZ` are the main version, release and patch numbers in hexadecimal. All three number fields are always represented using two digits (eight bits each). 1.2 would appear as "0x010200" while version 9.11.7 - appears as "0x090b07". + appears as `0x090b07`. This 6-digit hexadecimal number is always a greater number in a more recent release. It makes comparisons with greater than and less than work. diff --git a/docs/WEBSOCKET.md b/docs/WEBSOCKET.md index cab8a6f1d..25b1e5244 100644 --- a/docs/WEBSOCKET.md +++ b/docs/WEBSOCKET.md @@ -96,7 +96,7 @@ Ideas: [libWebSocket](https://libWebSocket.org/) is said to be a solid, fast and efficient WebSocket library with a vast amount of users. My plan was -originally to build upon it to skip having to implement the lowlevel parts of +originally to build upon it to skip having to implement the low level parts of WebSocket myself. Here are the reasons why I have decided to move forward with WebSocket in diff --git a/docs/cmdline-opts/ssl-reqd.d b/docs/cmdline-opts/ssl-reqd.d index 0c0718435..8193fdd50 100644 --- a/docs/cmdline-opts/ssl-reqd.d +++ b/docs/cmdline-opts/ssl-reqd.d @@ -12,7 +12,7 @@ Require SSL/TLS for the connection. Terminates the connection if the server does not support SSL/TLS. This option is handled in LDAP since version 7.81.0. It is fully supported -by the openldap backend and rejected by the generic ldap backend if explicit +by the OpenLDAP backend and rejected by the generic ldap backend if explicit TLS is required. This option was formerly known as --ftp-ssl-reqd. diff --git a/docs/cmdline-opts/ssl.d b/docs/cmdline-opts/ssl.d index b46c1eaba..8c25ca036 100644 --- a/docs/cmdline-opts/ssl.d +++ b/docs/cmdline-opts/ssl.d @@ -16,7 +16,7 @@ the server does not support SSL/TLS. See also --ftp-ssl-control and --ssl-reqd for different levels of encryption required. This option is handled in LDAP since version 7.81.0. It is fully supported -by the openldap backend and ignored by the generic ldap backend. +by the OpenLDAP backend and ignored by the generic ldap backend. Please note that a server may close the connection if the negotiation does not succeed. diff --git a/docs/curl-config.1 b/docs/curl-config.1 index ce8d62274..0d1d61fbb 100644 --- a/docs/curl-config.1 +++ b/docs/curl-config.1 @@ -82,23 +82,24 @@ major, minor, and patch. So that libcurl 7.7.4 would appear as 070704 and libcur omitted. (This option was broken in the 7.15.0 release.) .SH "EXAMPLES" What linker options do I need when I link with libcurl? - +.nf $ curl-config --libs - +.fi What compiler options do I need when I compile using libcurl functions? - +.nf $ curl-config --cflags - +.fi How do I know if libcurl was built with SSL support? - +.nf $ curl-config --feature | grep SSL - +.fi What's the installed libcurl version? - +.nf $ curl-config --version - +.fi How do I build a single file with a one-line command? - +.nf $ `curl-config --cc --cflags` -o example example.c `curl-config --libs` +.fi .SH "SEE ALSO" .BR curl (1) diff --git a/docs/examples/README.md b/docs/examples/README.md index f70a8b44a..c74dc9416 100644 --- a/docs/examples/README.md +++ b/docs/examples/README.md @@ -15,8 +15,9 @@ them for submission in future packages and on the website. ## Building -The Makefile.example is an example makefile that could be used to build these -examples. Just edit the file according to your system and requirements first. +The `Makefile.example` is an example Makefile that could be used to build +these examples. Just edit the file according to your system and requirements +first. Most examples should build fine using a command line like this: diff --git a/docs/libcurl/ABI.md b/docs/libcurl/ABI.md index 270c6d526..f03363327 100644 --- a/docs/libcurl/ABI.md +++ b/docs/libcurl/ABI.md @@ -26,11 +26,11 @@ ABI - Application Binary Interface we do not break the ABI so you can *always* upgrade to a later version without any loss or change in functionality. -## Soname Bumps +## SONAME Bumps Whenever there are changes done to the library that will cause an ABI breakage, that may require your application to get attention or possibly be - changed to adhere to new things, we will bump the soname. Then the library + changed to adhere to new things, we will bump the SONAME. Then the library will get a different output name and thus can in fact be installed in parallel with an older installed lib (on most systems). Thus, old applications built against the previous ABI version will remain working and @@ -50,11 +50,11 @@ ABI - Application Binary Interface that going backwards may get you in a situation where you pick a libcurl that does not support the options your application needs. Or possibly you even downgrade so far so you cross an ABI break border and thus a different - soname, and then your application may need to adapt to the modified ABI. + SONAME, and then your application may need to adapt to the modified ABI. ## History - The previous major library soname number bumps (breaking backwards + The previous major library SONAME number bumps (breaking backwards compatibility) happened the following times: 0 - libcurl 7.1, August 2000 diff --git a/docs/libcurl/curl_easy_escape.3 b/docs/libcurl/curl_easy_escape.3 index 307982ecf..b4594817e 100644 --- a/docs/libcurl/curl_easy_escape.3 +++ b/docs/libcurl/curl_easy_escape.3 @@ -35,7 +35,7 @@ char *curl_easy_escape(CURL *curl, const char *string, int length); This function converts the given input \fIstring\fP to a URL encoded string and returns that as a new allocated string. All input characters that are not a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" -version (%NN where NN is a two-digit hexadecimal number). +version (\fB%NN\fP where \fBNN\fP is a two-digit hexadecimal number). If \fIlength\fP is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on the input \fIstring\fP to find out the size. This function does not accept diff --git a/docs/libcurl/curl_easy_header.3 b/docs/libcurl/curl_easy_header.3 index e0676883c..186f0be36 100644 --- a/docs/libcurl/curl_easy_header.3 +++ b/docs/libcurl/curl_easy_header.3 @@ -122,7 +122,7 @@ setup a transfer "through" an HTTP(S) proxy. .IP CURLH_1XX The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate" response that might happen before the "real" response. -.IP CURLH_PSUEDO +.IP CURLH_PSEUDO The header is an HTTP/2 or HTTP/3 pseudo header .SH EXAMPLE .nf diff --git a/docs/libcurl/curl_easy_option_by_id.3 b/docs/libcurl/curl_easy_option_by_id.3 index f0a460d8e..734cd6924 100644 --- a/docs/libcurl/curl_easy_option_by_id.3 +++ b/docs/libcurl/curl_easy_option_by_id.3 @@ -31,8 +31,8 @@ curl_easy_option_by_id - find an easy setopt option by id const struct curl_easyoption *curl_easy_option_by_id(CURLoption id); .fi .SH DESCRIPTION -Given a CURLoption \fBid\fP, this function returns a pointer to the -curl_easyoption struct, holding information about the +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 @@ -49,7 +49,7 @@ if(opt) { .SH AVAILABILITY This function was added in libcurl 7.73.0 .SH RETURN VALUE -A pointer to the curl_easyoption struct for the option or NULL. +A pointer to the \fIcurl_easyoption\fP struct for the option or NULL. .SH "SEE ALSO" .BR curl_easy_option_by_name "(3)," curl_easy_option_next "(3)," .BR curl_easy_setopt "(3)," diff --git a/docs/libcurl/curl_easy_option_by_name.3 b/docs/libcurl/curl_easy_option_by_name.3 index f2abfbc29..f7e315a23 100644 --- a/docs/libcurl/curl_easy_option_by_name.3 +++ b/docs/libcurl/curl_easy_option_by_name.3 @@ -31,10 +31,11 @@ curl_easy_option_by_name - find an easy setopt option by name const struct curl_easyoption *curl_easy_option_by_name(const char *name); .fi .SH DESCRIPTION -Given a \fBname\fP, this function returns a pointer to the curl_easyoption -struct, holding information about the \fIcurl_easy_setopt(3)\fP option using -that name. The name should be specified without the "CURLOPT_" prefix and the -name comparison is made case insensitive. +Given a \fBname\fP, this function returns a pointer to the +\fIcurl_easyoption\fP struct, holding information about the +\fIcurl_easy_setopt(3)\fP option using that name. The name should be specified +without the "CURLOPT_" prefix and the name comparison is made case +insensitive. If libcurl has no option with the given name, this function returns NULL. .SH EXAMPLE @@ -47,7 +48,7 @@ if(opt) { .SH AVAILABILITY This function was added in libcurl 7.73.0 .SH RETURN VALUE -A pointer to the curl_easyoption struct for the option or NULL. +A pointer to the \fIcurl_easyoption\fP struct for the option or NULL. .SH "SEE ALSO" .BR curl_easy_option_next "(3)," curl_easy_option_by_id "(3)," .BR curl_easy_setopt "(3)," diff --git a/docs/libcurl/curl_easy_option_next.3 b/docs/libcurl/curl_easy_option_next.3 index 934edd838..58adf78d1 100644 --- a/docs/libcurl/curl_easy_option_next.3 +++ b/docs/libcurl/curl_easy_option_next.3 @@ -53,7 +53,7 @@ const struct curl_easyoption * curl_easy_option_next(const struct curl_easyoption *prev); .fi .SH DESCRIPTION -This function returns a pointer to the first or the next curl_easyoption +This function returns a pointer to the first or the next \fIcurl_easyoption\fP struct, providing an ability to iterate over all known options for \fIcurl_easy_setopt(3)\fP in this instance of libcurl. @@ -79,8 +79,8 @@ while(opt) { .SH AVAILABILITY This function was added in libcurl 7.73.0 .SH RETURN VALUE -A pointer to the curl_easyoption struct for the next option or NULL if no more -options. +A pointer to the \fIcurl_easyoption\fP struct for the next option or NULL if +no more options. .SH "SEE ALSO" .BR curl_easy_option_by_name "(3)," curl_easy_option_by_id "(3)," .BR curl_easy_setopt "(3)," diff --git a/docs/libcurl/curl_easy_perform.3 b/docs/libcurl/curl_easy_perform.3 index ac6320399..77d7f59a2 100644 --- a/docs/libcurl/curl_easy_perform.3 +++ b/docs/libcurl/curl_easy_perform.3 @@ -74,7 +74,7 @@ if(curl) { .SH AVAILABILITY Always .SH RETURN VALUE -CURLE_OK (0) means everything was ok, non-zero means an error occurred as +CURLE_OK (0) means everything was OK, non-zero means an error occurred as .I <curl/curl.h> 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 diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 33be54d36..959c86b9b 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -220,7 +220,7 @@ Ask for alternate buffer size. See \fICURLOPT_BUFFERSIZE(3)\fP .IP CURLOPT_PORT Port number to connect to. See \fICURLOPT_PORT(3)\fP .IP CURLOPT_TCP_FASTOPEN -Enable TFO, TCP Fast Open. See \fICURLOPT_TCP_FASTOPEN(3)\fP +Enable TCP Fast Open. See \fICURLOPT_TCP_FASTOPEN(3)\fP .IP CURLOPT_TCP_NODELAY Disable the Nagle algorithm. See \fICURLOPT_TCP_NODELAY(3)\fP .IP CURLOPT_ADDRESS_SCOPE @@ -402,7 +402,7 @@ Commands to run just before transfer. See \fICURLOPT_PREQUOTE(3)\fP .IP CURLOPT_APPEND Append to remote file. See \fICURLOPT_APPEND(3)\fP .IP CURLOPT_FTP_USE_EPRT -Use EPTR. See \fICURLOPT_FTP_USE_EPRT(3)\fP +Use EPRT. See \fICURLOPT_FTP_USE_EPRT(3)\fP .IP CURLOPT_FTP_USE_EPSV Use EPSV. See \fICURLOPT_FTP_USE_EPSV(3)\fP .IP CURLOPT_FTP_USE_PRET @@ -452,7 +452,7 @@ Resume a transfer. See \fICURLOPT_RESUME_FROM(3)\fP .IP CURLOPT_RESUME_FROM_LARGE Resume a transfer. See \fICURLOPT_RESUME_FROM_LARGE(3)\fP .IP CURLOPT_CURLU -Set URL to work on with CURLU *. See \fICURLOPT_CURLU(3)\fP +Set URL to work on with a URL handle. See \fICURLOPT_CURLU(3)\fP .IP CURLOPT_CUSTOMREQUEST Custom request/method. See \fICURLOPT_CUSTOMREQUEST(3)\fP .IP CURLOPT_FILETIME @@ -675,9 +675,9 @@ Custom pointer to pass to ssh key callback. See \fICURLOPT_SSH_KEYDATA(3)\fP Callback for checking host key handling. See \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP .IP CURLOPT_SSH_HOSTKEYDATA Custom pointer to pass to ssh host key callback. See \fICURLOPT_SSH_HOSTKEYDATA(3)\fP -.SH WEBSOCKETS +.SH WEBSOCKET .IP CURLOPT_WS_OPTIONS -Set Websockets options. See \fICURLOPT_WS_OPTIONS(3)\fP +Set WebSocket options. See \fICURLOPT_WS_OPTIONS(3)\fP .SH OTHER OPTIONS .IP CURLOPT_PRIVATE Private pointer to store. See \fICURLOPT_PRIVATE(3)\fP diff --git a/docs/libcurl/curl_easy_unescape.3 b/docs/libcurl/curl_easy_unescape.3 index 6729cbc5f..e68c6dcef 100644 --- a/docs/libcurl/curl_easy_unescape.3 +++ b/docs/libcurl/curl_easy_unescape.3 @@ -42,11 +42,10 @@ If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP will use strlen() on the input \fIurl\fP string 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 an escaped string -containing %00 to still get used properly after unescaping. Since this is a -pointer to an \fIint\fP type, it can only return a value up to INT_MAX so no -longer string can be unescaped if the string length is returned in this -parameter. +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 b48322638..c54437688 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -35,11 +35,11 @@ Obsolete function. Use \fIcurl_easy_escape(3)\fP instead! This function will convert the given input string to an 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 (%NN where NN is a -two-digit hexadecimal number). +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). -If the \fBlength\fP argument is set to 0, curl_escape() will use strlen() on -the input \fBurl\fP string to find out the size. +If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP will use +strlen() on the input \fBurl\fP string to find out the size. You must \fIcurl_free(3)\fP the returned string when you are done with it. .SH EXAMPLE diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index f9997e2a3..92135bf81 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -23,7 +23,7 @@ .\" ************************************************************************** .TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME -curl_formadd - add a section to a multipart/formdata HTTP POST +curl_formadd - add a section to a multipart form POST .SH SYNOPSIS .nf #include <curl/curl.h> @@ -34,13 +34,12 @@ CURLFORMcode curl_formadd(struct curl_httppost **firstitem, .SH DESCRIPTION This function is deprecated. Do not use. See \fIcurl_mime_init(3)\fP instead. -curl_formadd() is used to append sections when building a multipart/formdata -HTTP POST (sometimes referred to as RFC2388-style posts). Append one section -at a time until you have added all the sections you want included and then you -pass the \fIfirstitem\fP pointer as parameter to \fICURLOPT_HTTPPOST(3)\fP. -\fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated -invokes it should be left as set to allow repeated invokes to find the end of -the list faster. +curl_formadd() is used to append sections when building a multipart form +post. Append one section at a time until you have added all the sections you +want included and then you pass the \fIfirstitem\fP pointer as parameter to +\fICURLOPT_HTTPPOST(3)\fP. \fIlastitem\fP is set after each +\fIcurl_formadd(3)\fP call and on repeated invokes it should be left as set to +allow repeated invokes to find the end of the list faster. After the \fIlastitem\fP pointer follow the real arguments. @@ -52,7 +51,7 @@ the function itself. You must call \fIcurl_formfree(3)\fP on the 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. -First, there are some basics you need to understand about multipart/formdata +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 @@ -65,14 +64,15 @@ parts. .IP CURLFORM_COPYNAME 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 NUL-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. +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. .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 NUL-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP. +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 @@ -82,11 +82,11 @@ 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. .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 NUL-terminated, or if you would like it to contain zero bytes, -you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. +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. .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. @@ -157,10 +157,10 @@ chunked encoded. (Option added in libcurl 7.18.2) .IP CURLFORM_ARRAY Another possibility to send options to curl_formadd() is the \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as -its value. Each curl_forms structure element has a CURLformoption and a char -pointer. The final element in the array must be a CURLFORM_END. All available -options can be used in an array, except the CURLFORM_ARRAY option itself. The -last argument in such an array must always be \fBCURLFORM_END\fP. +its value. Each curl_forms structure element has a \fICURLformoption\fP and a +char pointer. The final element in the array must be a CURLFORM_END. All +available options can be used in an array, except the CURLFORM_ARRAY option +itself. The last argument in such an array must always be \fBCURLFORM_END\fP. .IP CURLFORM_CONTENTHEADER specifies extra headers for the form POST section. This takes a curl_slist prepared in the usual way using \fBcurl_slist_append\fP and appends the list @@ -168,9 +168,10 @@ of headers to those libcurl automatically generates. The list must exist while the POST occurs, if you free it before the post completes you may experience problems. -When you have passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using -the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after -you have called \fIcurl_easy_cleanup(3)\fP for the curl handle. +When you have passed the \fIstruct curl_httppost\fP pointer to +\fIcurl_easy_setopt(3)\fP (using the \fICURLOPT_HTTPPOST(3)\fP option), you +must not free the list until after you have called \fIcurl_easy_cleanup(3)\fP +for the curl handle. See example below. .SH EXAMPLE @@ -259,7 +260,7 @@ actually sent: the effective data size can then not be automatically determined, resulting in a chunked encoding transfer. Backslashes and double quotes in field and file names are now escaped before transmission. .SH RETURN VALUE -0 means everything was ok, non-zero means an error occurred corresponding +0 means everything was OK, non-zero means an error occurred corresponding to a CURL_FORMADD_* constant defined in .I <curl/curl.h> .SH "SEE ALSO" diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index 89dfdbc6d..fc0a25c43 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -23,7 +23,7 @@ .\" ************************************************************************** .TH curl_formfree 3 "6 April 2001" "libcurl 7.7.1" "libcurl Manual" .SH NAME -curl_formfree - free a previously build multipart/formdata HTTP POST chain +curl_formfree - free a previously build multipart form post chain .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index 5b57c38e4..7b55014be 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -23,7 +23,7 @@ .\" ************************************************************************** .TH curl_formget 3 "20 June 2006" "libcurl 7.15.5" "libcurl Manual" .SH NAME -curl_formget - serialize a previously built multipart/formdata HTTP POST chain +curl_formget - serialize a previously built multipart form POST chain .SH SYNOPSIS .nf .B #include <curl/curl.h> @@ -67,6 +67,6 @@ request as only then will libcurl get the actual read callback to use! This function was added in libcurl 7.15.5. The form API is deprecated in libcurl 7.56.0. .SH RETURN VALUE -0 means everything was ok, non-zero means an error occurred +0 means everything was OK, non-zero means an error occurred .SH "SEE ALSO" .BR curl_formadd "(3), " curl_mime_init "(3)" diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index fe7c12f8c..ffe8201fe 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -45,9 +45,9 @@ order of the items is immaterial. A date string may contain many flavors of items: .TP 0.8i .B calendar date items -Can be specified several ways. Month names can only be three-letter english -abbreviations, numbers can be zero-prefixed and the year may use 2 or 4 digits. -Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6. +Can be specified several ways. Month names can only be three-letter English +abbreviations, numbers can be zero-prefixed and the year may use 2 or 4 +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 @@ -61,7 +61,7 @@ UTC. Supported formats include: -1200, MST, +0100. .TP .B day of the week items Specifies a day of the week. Days of the week may be spelled out in full -(using english): `Sunday', `Monday', etc or they may be abbreviated to their +(using English): `Sunday', `Monday', etc or they may be abbreviated to their first three letters. This is usually not info that adds anything. .TP .B pure numbers @@ -97,8 +97,8 @@ calendar date. .SH STANDARDS This parser handles date formats specified in RFC 822 (including the update in RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted by -RFC 1036) and ANSI C's asctime() format. These formats are the only ones RFC -7231 says HTTP applications may use. +RFC 1036) and ANSI C's \fIasctime()\fP format. These formats are the only ones +RFC 7231 says HTTP applications may use. .SH AVAILABILITY Always .SH RETURN VALUE diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 index bcce866fe..51218ca1b 100644 --- a/docs/libcurl/curl_getenv.3 +++ b/docs/libcurl/curl_getenv.3 @@ -45,9 +45,7 @@ You must \fIcurl_free(3)\fP the returned string when you are done with it. } .fi .SH AVAILABILITY -This function will be removed from the public libcurl API in a near future. It -will instead be made "available" by source code access only, and then as -curlx_getenv(). +Always .SH RETURN VALUE A pointer to a null-terminated string or NULL if it failed to find the specified name. diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index fd33ccd99..09a34e4bc 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -57,9 +57,9 @@ This does not just mean no other thread that is using libcurl. Because similarly thread unsafe, it could conflict with any other thread that uses these other libraries. -If you are initializing libcurl from a Windows DLL you should not initialize it -from DllMain or a static initializer because Windows holds the loader lock -during that time and it could cause a deadlock. +If you are initializing libcurl from a Windows DLL you should not initialize +it from \fIDllMain\fP or a static initializer because Windows holds the loader +lock during that time and it could cause a deadlock. See the description in \fIlibcurl(3)\fP of global environment requirements for details of how to use this function. @@ -89,7 +89,7 @@ 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. .IP CURL_GLOBAL_NOTHING -Initialise nothing extra. This sets no bit. +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 the functionality of the \fBCURL_GLOBAL_ALL\fP mask. diff --git a/docs/libcurl/curl_global_init_mem.3 b/docs/libcurl/curl_global_init_mem.3 index c4f49b503..8699756c4 100644 --- a/docs/libcurl/curl_global_init_mem.3 +++ b/docs/libcurl/curl_global_init_mem.3 @@ -72,7 +72,7 @@ screw things up for libcurl. Take care! .SH AVAILABILITY Added in 7.12.0 .SH RETURN VALUE -CURLE_OK (0) means everything was ok, non-zero means an error occurred as +CURLE_OK (0) means everything was OK, non-zero means an error occurred as \fI<curl/curl.h>\fP defines - see \fIlibcurl-errors(3)\fP. .SH "SEE ALSO" .BR curl_global_init "(3), " diff --git a/docs/libcurl/curl_global_sslset.3 b/docs/libcurl/curl_global_sslset.3 index 1b99f96da..c1e791afe 100644 --- a/docs/libcurl/curl_global_sslset.3 +++ b/docs/libcurl/curl_global_sslset.3 @@ -64,17 +64,17 @@ The backend can be identified by the \fIid\fP both \fIid\fP and \fIname\fP are specified, the \fIname\fP will be ignored. If neither \fIid\fP nor \fPname\fP are specified, the function will fail with -CURLSSLSET_UNKNOWN_BACKEND and set the \fIavail\fP pointer to the +\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. -Upon success, the function returns CURLSSLSET_OK. +Upon success, the function returns \fBCURLSSLSET_OK\fP. If the specified SSL backend is not available, the function returns -CURLSSLSET_UNKNOWN_BACKEND and sets the \fIavail\fP pointer to a +\fBCURLSSLSET_UNKNOWN_BACKEND\fP and sets the \fIavail\fP pointer to a NULL-terminated list of available SSL backends. In this case, you may call the function again to try to select a different backend. @@ -105,7 +105,8 @@ This does not just mean no other thread that is using libcurl. This function was added in libcurl 7.56.0. Before this version, there was no support for choosing SSL backends at runtime. .SH RETURN VALUE -If this function returns CURLSSLSET_OK, the backend was successfully selected. +If this function returns \fICURLSSLSET_OK\fP, the backend was successfully +selected. If the chosen backend is unknown (or support for the chosen backend has not been compiled into libcurl), the function returns diff --git a/docs/libcurl/curl_mime_encoder.3 b/docs/libcurl/curl_mime_encoder.3 index 203482462..dad13e80a 100644 --- a/docs/libcurl/curl_mime_encoder.3 +++ b/docs/libcurl/curl_mime_encoder.3 @@ -67,7 +67,7 @@ not be used with other types of data. If the original data is already encoded in such a scheme, a custom \fIContent-Transfer-Encoding\fP header should be added with -\FIcurl_mime_headers\fP() instead of setting a part encoder. +\fIcurl_mime_headers\fP() instead of setting a part encoder. Encoding should not be applied to multiparts, thus the use of this function on a part with content set with \fIcurl_mime_subparts\fP() is diff --git a/docs/libcurl/curl_mime_free.3 b/docs/libcurl/curl_mime_free.3 index 63d8dc98f..f4b3ac462 100644 --- a/docs/libcurl/curl_mime_free.3 +++ b/docs/libcurl/curl_mime_free.3 @@ -36,9 +36,9 @@ with \fIcurl_mime_addpart(3)\fP and other mime-handling functions. This must be called when the data has been used, which typically means after \fIcurl_easy_perform(3)\fP has been called. -The handle to free is the one you passed to -the \fICURLOPT_MIMEPOST(3)\fP option: attached subparts mime structures must -not be explicitly freed as they are by the top structure freeing. +The handle to free is the one you passed to the \fICURLOPT_MIMEPOST(3)\fP +option: attached sub part mime structures must not be explicitly freed as they +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. diff --git a/docs/libcurl/curl_mime_name.3 b/docs/libcurl/curl_mime_name.3 index 385d9f82f..10fe35fb5 100644 --- a/docs/libcurl/curl_mime_name.3 +++ b/docs/libcurl/curl_mime_name.3 @@ -41,7 +41,7 @@ fields are named. The name string is copied into the part, thus the associated storage may safely be released or reused after call. Setting a part's name multiple times is valid: only the value set by the last call is retained. It is possible to -"unname" a part by setting \fIname\fP to NULL. +reset the name of a part by setting \fIname\fP to NULL. .SH EXAMPLE .nf curl_mime *mime; diff --git a/docs/libcurl/curl_mime_subparts.3 b/docs/libcurl/curl_mime_subparts.3 index 6d1daaf94..294832571 100644 --- a/docs/libcurl/curl_mime_subparts.3 +++ b/docs/libcurl/curl_mime_subparts.3 @@ -23,7 +23,7 @@ .\" ************************************************************************** .TH curl_mime_subparts 3 "22 August 2017" "libcurl 7.56.0" "libcurl Manual" .SH NAME -curl_mime_subparts - set subparts of a multipart mime part +curl_mime_subparts - set sub-parts of a multipart mime part .SH SYNOPSIS .nf #include <curl/curl.h> @@ -36,7 +36,7 @@ structure. \fIpart\fP is a handle to the multipart part. -\fIsubparts\fP is a mime structure handle holding the subparts. After +\fIsubparts\fP is a mime structure handle holding the sub-parts. After \fIcurl_mime_subparts\fP succeeds, the mime structure handle belongs to the multipart part and must not be freed explicitly. It may however be updated by subsequent calls to mime API functions. diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index f124f3ac8..35a3baa18 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -64,9 +64,9 @@ The functions \fBcurl_mvprintf()\fP, \fBcurl_mvfprintf()\fP, \fBcurl_mvsprintf()\fP, \fBcurl_mvsnprintf()\fP are equivalent to the functions \fBcurl_mprintf()\fP, \fBcurl_mfprintf()\fP, \fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, respectively, except that they are called with a -va_list instead of a variable number of arguments. These functions do not -call the va_end macro. Because they invoke the va_arg macro, the value of ap -is undefined after the call. +\fIva_list\fP instead of a variable number of arguments. These functions do +not call the \fIva_end\fP macro. Because they invoke the \fIva_arg\fP macro, +the value of \fIap\fP is undefined after the call. The functions \fBcurl_maprintf()\fP and \fBcurl_mvaprintf()\fP return the output string as pointer to a newly allocated memory area. The returned string @@ -93,21 +93,21 @@ can also specify explicitly which argument is taken, at each place where an argument is required, by writing "%m$" instead of '%' and "*m$" instead of '*', where the decimal integer m denotes the position in the argument list of the desired argument, indexed starting from 1. Thus, - +.nf curl_mprintf("%*d", width, num); - +.fi and - +.nf curl_mprintf("%2$*1$d", width, num); - +.fi are equivalent. The second style allows repeated references to the same argument. If the style using '$' is used, it must be used throughout for all conversions taking an argument and all width and precision arguments, but it may be mixed with "%%" formats, which do not consume an argument. There may be no gaps in -the numbers of argu‐ ments specified using '$'; for example, if arguments 1 -and 3 are specified, argument 2 must also be specified somewhere in the format +the numbers of arguments specified using '$'; for example, if arguments 1 and +3 are specified, argument 2 must also be specified somewhere in the format string. .SH "Flag characters" @@ -139,17 +139,17 @@ 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 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 m-th argument, respec‐ tively, -which must be of type int. A negative field width is taken as a '-' flag -followed by a positive field width. In no case does a nonexistent or small -field width cause truncation of a field; if the result of a conversion is -wider than the field width, the field is expanded to contain the conversion -result. +width is given in the next argument, or in the \fIm-th\fP argument, +respectively, which must be of type int. A negative field width is taken as +a '-' flag followed by a positive field width. In no case does a nonexistent +or small field width cause truncation of a field; if the result of a +conversion is wider than the field width, the field is expanded to contain the +conversion result. .SH "Precision" An optional precision in the form of a period ('.') followed by an optional decimal digit string. Instead of a decimal digit string one may write "*" or "*m$" (for some decimal integer m) to specify that the precision is given in -the next argument, or in the m-th argument, respectively, which must be of +the next argument, or in the \fIm-th\fP argument, respectively, which must be of type int. If the precision is given as just '.', the precision is taken to be zero. A negative precision is taken as if the precision were omitted. This gives the minimum number of digits to appear for \fBd\fP, \fBi\fP, \fBo\fP, @@ -198,18 +198,18 @@ empty. .B o, u, x, X The unsigned int argument is converted to unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters -abcdef are used for \fBx\fP conversions; the letters ABCDEF are used for -\fBX\fP conversions. The precision, if any, gives the minimum number of digits -that must appear; if the converted value requires fewer digits, it is padded -on the left with zeros. The default precision is 1. When 0 is printed with -an explicit precision 0, the output is empty. +\fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP are +used for \fBX\fP conversions. The precision, if any, gives the minimum number +of digits that must appear; if the converted value requires fewer digits, it +is padded on the left with zeros. The default precision is 1. When 0 is +printed with an explicit precision 0, the output is empty. .TP .B e, E -The double argument is rounded and output in the style "[-]d.ddde±dd" +The double argument is rounded and output in the style \fB"[-]d.ddde±dd"\fP .TP .B f, F -The double argument is rounded and output to decimal notiation in the style -[-]ddd.ddd. +The double argument is rounded and output to decimal notation in the style +\fB"[-]ddd.ddd"\fP. .TP .B g, G The double argument is converted in style f or e. @@ -219,12 +219,12 @@ The int argument is converted to an unsigned char, and the resulting character is written. .TP .B s -The const char * argument is expected to be a pointer to an array of character -type (pointer to a string). Characters from the array are written up to (but -not including) a terminating null byte. If a precision is specified, no more -than the number specified are written. If a precision is given, no null byte -need be present; if the precision is not specified, or is greater than the -size of the array, the array must contain a terminating null byte. +The \fIconst char *\fP argument is expected to be a pointer to an array of +character type (pointer to a string). Characters from the array are written up +to (but not including) a terminating null byte. If a precision is specified, +no more than the number specified are written. If a precision is given, no +null byte need be present; if the precision is not specified, or is greater +than the size of the array, the array must contain a terminating null byte. .TP .B p The \fIvoid *\fP pointer argument is printed in hexadecimal. diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 index 93b6e4a89..7237eba08 100644 --- a/docs/libcurl/curl_multi_add_handle.3 +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -77,7 +77,7 @@ first the easy handle and then the multi handle: curl_multi_add_handle(multi_handle, http_handle2); .fi .SH AVAILABILITY -ADded in 7.9.6 +Added in 7.9.6 .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 9c83344c9..5265b06fb 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -36,23 +36,23 @@ CURLMcode curl_multi_fdset(CURLM *multi_handle, .ad .SH DESCRIPTION This function extracts file descriptor information from a given multi_handle. -libcurl returns its fd_set sets. The application can use these to select() on, -but be sure to FD_ZERO them before calling this function as +libcurl returns its \fIfd_set\fP sets. The application can use these to +select() on, but be sure to \fIFD_ZERO\fP them before calling this function as \fIcurl_multi_fdset(3)\fP only adds its own descriptors, it does not zero or otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should be called as soon as one of them is ready to be read from or written to. If the \fIread_fd_set\fP argument is not a null pointer, it points to an -object of type fd_set that on returns specifies the file descriptors to be -checked for being ready to read. +object of type \fBfd_set\fP that on returns specifies the file descriptors to +be checked for being ready to read. If the \fIwrite_fd_set\fP argument is not a null pointer, it points to an -object of type fd_set that on return specifies the file descriptors to be -checked for being ready to write. +object of type \fBfd_set\fP that on return specifies the file descriptors to +be checked for being ready to write. If the \fIexc_fd_set\fP argument is not a null pointer, it points to an object -of type fd_set that on return specifies the file descriptors to be checked for -error conditions pending. +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 @@ -67,16 +67,17 @@ conditions to find a suitable value. When doing select(), you should use \fIcurl_multi_timeout(3)\fP to figure out how long to wait for action. Call \fIcurl_multi_perform(3)\fP even if no -activity has been seen on the fd_sets after the timeout expires as otherwise -internal retries and timeouts may not work as you would think and want. +activity has been seen on the \fBfd_sets\fP after the timeout expires as +otherwise internal retries and timeouts may not work as you would think and +want. If one of the sockets used by libcurl happens to be larger than what can be -set in an fd_set, which on POSIX systems means that the file descriptor is -larger than FD_SETSIZE, then libcurl will try to not set it. Setting a too -large file descriptor in an fd_set 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... +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... .SH EXAMPLE .nf /* get file descriptors from the transfers */ @@ -93,7 +94,7 @@ for... .SH AVAILABILITY Added in 7.9.6 .SH RETURN VALUE -CURLMcode type, general libcurl multi interface error code. See +\fBCURLMcode\fP type, general libcurl multi interface error code. See \fIlibcurl-errors(3)\fP .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index bb66ef185..1b099a946 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -23,7 +23,7 @@ .\" ************************************************************************** .TH curl_multi_info_read 3 "18 Dec 2004" "libcurl 7.10.3" "libcurl Manual" .SH NAME -curl_multi_info_read - read multi stack informationals +curl_multi_info_read - read multi stack information .SH SYNOPSIS .nf #include <curl/curl.h> @@ -31,10 +31,10 @@ curl_multi_info_read - read multi stack informationals CURLMsg *curl_multi_info_read(CURLM *multi_handle, int *msgs_in_queue); .fi .SH DESCRIPTION -Ask the multi handle if there are any messages/informationals from the -individual transfers. Messages may include informationals 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. +Ask the multi handle if there are any messages from the individual +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 @@ -50,10 +50,10 @@ is emptied. calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or \fIcurl_easy_cleanup(3)\fP. -The 'CURLMsg' struct is simple and only contains basic information. If more -involved information is wanted, the particular "easy handle" is present in -that struct and can be used in subsequent regular \fIcurl_easy_getinfo(3)\fP -calls (or similar): +The \fICURLMsg\fP struct is simple and only contains basic information. If +more involved information is wanted, the particular "easy handle" is present +in that struct and can be used in subsequent regular +\fIcurl_easy_getinfo(3)\fP calls (or similar): .nf struct CURLMsg { diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 index 6e2122627..d1c4446a6 100644 --- a/docs/libcurl/curl_multi_init.3 +++ b/docs/libcurl/curl_multi_init.3 @@ -31,9 +31,9 @@ curl_multi_init - create a multi handle CURLM *curl_multi_init(); .fi .SH DESCRIPTION -This function returns a CURLM handle to be used as input to all the other -multi-functions, sometimes referred to as a multi handle in some places in the -documentation. This init call MUST have a corresponding call to +This function returns a pointer to a \fICURLM\fP handle to be used as input to +all the other multi-functions, sometimes referred to as a multi handle in some +places in the documentation. This init call MUST have a corresponding call to \fIcurl_multi_cleanup(3)\fP when the operation is complete. .SH EXAMPLE .nf diff --git a/docs/libcurl/curl_multi_poll.3 b/docs/libcurl/curl_multi_poll.3 index ab0182180..dca6be43c 100644 --- a/docs/libcurl/curl_multi_poll.3 +++ b/docs/libcurl/curl_multi_poll.3 @@ -43,7 +43,8 @@ shorter expiry time than \fItimeout_ms\fP, that shorter time will be 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 pollfd structure to be waited on in the same call. +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 diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3 index e4349c940..cafce1b5a 100644 --- a/docs/libcurl/curl_multi_strerror.3 +++ b/docs/libcurl/curl_multi_strerror.3 @@ -29,8 +29,8 @@ curl_multi_strerror - return string describing error code .B #include <curl/curl.h> .BI "const char *curl_multi_strerror(CURLMcode " errornum ");" .SH DESCRIPTION -The curl_multi_strerror() function returns a string describing the CURLMcode -error code passed in the argument \fIerrornum\fP. +The curl_multi_strerror() function returns a string describing the +\fICURLMcode\fP error code passed in the argument \fIerrornum\fP. .SH EXAMPLE .nf int still_running; diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 index ec55dd9d5..cf3260814 100644 --- a/docs/libcurl/curl_multi_wait.3 +++ b/docs/libcurl/curl_multi_wait.3 @@ -42,8 +42,9 @@ 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. -The calling application may pass additional curl_waitfd structures which are -similar to \fIpoll(2)\fP's pollfd structure to be waited on in the same call. +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 @@ -66,14 +67,14 @@ struct curl_waitfd { }; .fi .IP CURL_WAIT_POLLIN -Bit flag to curl_waitfd.events indicating the socket should poll on read +Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on read events such as new data received. .IP CURL_WAIT_POLLPRI -Bit flag to curl_waitfd.events indicating the socket should poll on high +Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on high priority read events such as out of band data. .IP CURL_WAIT_POLLOUT -Bit flag to curl_waitfd.events indicating the socket should poll on write -events such as the socket being clear to write without blocking. +Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on +write events such as the socket being clear to write without blocking. .SH EXAMPLE .nf CURL *easy_handle; diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 index a1a3af3a2..bf36c1a46 100644 --- a/docs/libcurl/curl_share_init.3 +++ b/docs/libcurl/curl_share_init.3 @@ -31,10 +31,11 @@ curl_share_init - Create a shared object CURLSH *curl_share_init(); .fi .SH DESCRIPTION -This function returns a CURLSH handle to be used as input to all the other -share-functions, sometimes referred to as a share handle in some places in the -documentation. This init call MUST have a corresponding call to -\fIcurl_share_cleanup\fP when all operations using the share are complete. +This function returns a pointer to a \fICURLSH\fP handle to be used as input +to all the other share-functions, sometimes referred to as a share handle in +some places in the documentation. This init call MUST have a corresponding +call to \fIcurl_share_cleanup(3)\fP when all operations using the share are +complete. This \fIshare handle\fP is what you pass to curl using the \fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, to make that diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3 index 0c4824c00..dc66f0936 100644 --- a/docs/libcurl/curl_share_strerror.3 +++ b/docs/libcurl/curl_share_strerror.3 @@ -29,8 +29,8 @@ curl_share_strerror - return string describing error code .B #include <curl/curl.h> .BI "const char *curl_share_strerror(CURLSHcode " errornum ");" .SH DESCRIPTION -The curl_share_strerror() function returns a string describing the CURLSHcode -error code passed in the argument \fIerrornum\fP. +The \fIcurl_share_strerror(3)\fP function returns a string describing the +\fICURLSHcode\fP error code passed in the argument \fIerrornum\fP. .SH EXAMPLE .nf CURLSHcode sh; diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 index dc65320fc..b97061dcf 100644 --- a/docs/libcurl/curl_strequal.3 +++ b/docs/libcurl/curl_strequal.3 @@ -52,9 +52,7 @@ if(curl_strnequal(name, input, 5)) printf("Name and input matches in the 5 first bytes\\n"); .fi .SH AVAILABILITY -These functions will be removed from the public libcurl API in a near -future. They will instead be made "available" by source code access only, and -then as curlx_strequal() and curlx_strenqual(). +Always .SH RETURN VALUE Non-zero if the strings are identical. Zero if they are not. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index cf5422528..43f7dc4d9 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -38,8 +38,8 @@ 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. -If the 'length' argument is set to 0, curl_unescape() will use strlen() on the -input 'url' string to find out the size. +If the 'length' argument is set to 0, \fIcurl_unescape(3)\fP will use strlen() +on the input \fBurl\fP string to find out the size. You must \fIcurl_free(3)\fP the returned string when you are done with it. .SH EXAMPLE diff --git a/docs/libcurl/curl_url.3 b/docs/libcurl/curl_url.3 index b761e61c3..de941a120 100644 --- a/docs/libcurl/curl_url.3 +++ b/docs/libcurl/curl_url.3 @@ -23,7 +23,7 @@ .\" ************************************************************************** .TH curl_url 3 "6 Aug 2018" "libcurl" "libcurl Manual" .SH NAME -curl_url - returns a new CURLU handle +curl_url - returns a new URL handle .SH SYNOPSIS .nf #include <curl/curl.h> @@ -31,8 +31,8 @@ curl_url - returns a new CURLU handle CURLU *curl_url(); .fi .SH DESCRIPTION -This function will allocates and returns a pointer to a fresh CURLU handle, to -be used for further use of the URL API. +This function will allocates and returns a pointer to a fresh \fICURLU\fP +handle, to be used for further use of the URL API. .SH EXAMPLE .nf CURLUcode rc; diff --git a/docs/libcurl/curl_url_cleanup.3 b/docs/libcurl/curl_url_cleanup.3 index eb1623516..0d95b43cf 100644 --- a/docs/libcurl/curl_url_cleanup.3 +++ b/docs/libcurl/curl_url_cleanup.3 @@ -23,7 +23,7 @@ .\" ************************************************************************** .TH curl_url_cleanup 3 "6 Aug 2018" "libcurl" "libcurl Manual" .SH NAME -curl_url_cleanup - free a CURLU handle +curl_url_cleanup - free the URL handle .SH SYNOPSIS .nf #include <curl/curl.h> @@ -31,7 +31,7 @@ curl_url_cleanup - free a CURLU handle void curl_url_cleanup(CURLU *handle); .fi .SH DESCRIPTION -Frees all the resources associated with the given CURLU handle! +Frees all the resources associated with the given \fICURLU\fP handle! .SH EXAMPLE .nf CURLU *url = curl_url(); diff --git a/docs/libcurl/curl_url_dup.3 b/docs/libcurl/curl_url_dup.3 index 7eff4ab3d..66f48ecb7 100644 --- a/docs/libcurl/curl_url_dup.3 +++ b/docs/libcurl/curl_url_dup.3 @@ -23,7 +23,7 @@ .\" ************************************************************************** .TH curl_url_dup 3 "6 Aug 2018" "libcurl" "libcurl Manual" .SH NAME -curl_url_dup - duplicate a CURLU handle +curl_url_dup - duplicate a URL handle .SH SYNOPSIS .nf #include <curl/curl.h> @@ -31,9 +31,9 @@ curl_url_dup - duplicate a CURLU handle CURLU *curl_url_dup(CURLU *inhandle); .fi .SH DESCRIPTION -Duplicates a given CURLU \fIinhandle\fP and all its contents and returns a -pointer to a new CURLU handle. The new handle also needs to be freed with -\fIcurl_url_cleanup(3)\fP. +Duplicates a given \fICURLU\fP \fIinhandle\fP and all its contents and returns +a pointer to a new \fICURLU\fP handle. The new handle also needs to be freed +with \fIcurl_url_cleanup(3)\fP. .SH EXAMPLE .nf CURLUcode rc; diff --git a/docs/libcurl/curl_url_get.3 b/docs/libcurl/curl_url_get.3 index 88a96b3cc..815134ba7 100644 --- a/docs/libcurl/curl_url_get.3 +++ b/docs/libcurl/curl_url_get.3 @@ -86,7 +86,7 @@ Scheme cannot be URL decoded on get. .IP CURLUPART_PASSWORD .IP CURLUPART_OPTIONS .IP CURLUPART_HOST -The host name. If it is an IPv6 numeric address, the zoneid will not be part +The host name. If it is an IPv6 numeric address, the zone id will not be part of it but is provided separately in \fICURLUPART_ZONEID\fP. IPv6 numerical addresses are returned within brackets ([]). .IP CURLUPART_ZONEID diff --git a/docs/libcurl/curl_url_set.3 b/docs/libcurl/curl_url_set.3 index bbea5de4b..f2f2e5df2 100644 --- a/docs/libcurl/curl_url_set.3 +++ b/docs/libcurl/curl_url_set.3 @@ -46,7 +46,7 @@ The application does not have to keep \fIcontent\fP around after a successful call. Setting a part to a NULL pointer will effectively remove that part's contents -from the CURLU handle. +from the \fICURLU\fP handle. By default, this API only accepts URLs using schemes for protocols that are supported built-in. To make libcurl parse URLs generically even for schemes it @@ -87,7 +87,7 @@ If a path is set in the URL without a leading slash, a slash will be inserted automatically when this URL is read from the handle. .IP CURLUPART_QUERY The query part will also get spaces converted to pluses when asked to URL -encode on set with the CURLU_URLENCODE bit. +encode on set with the \fICURLU_URLENCODE\fP bit. If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part will be appended on the end of the existing query - and if the previous part did not @@ -159,8 +159,8 @@ individual parts. (Added in 7.78.0) .SH AVAILABILITY Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0. .SH RETURN VALUE -Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went -fine. See the \fIlibcurl-errors(3)\fP man page for the full list with +Returns a \fICURLUcode\fP error value, which is CURLUE_OK (0) if everything +went fine. See the \fIlibcurl-errors(3)\fP man page for the full list with descriptions. A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index 2a27c999e..49d8b5220 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -208,8 +208,7 @@ Digest authentication. It also allows libcurl to use the current user credentials without the app having to pass them on. (Added in 7.13.2) .IP CURL_VERSION_THREADSAFE libcurl was built with thread-safety support (Atomic or SRWLOCK) to protect -curl initialisation. (Added in 7.84.0) -See \fIlibcurl-thread(3)\fP +curl initialization. (Added in 7.84.0) See \fIlibcurl-thread(3)\fP .IP CURL_VERSION_TLSAUTH_SRP libcurl was built with support for TLS-SRP (in one or more of the built-in TLS backends). (Added in 7.21.4) @@ -219,7 +218,7 @@ libcurl was built with support for Unix domain sockets. .RE \fIssl_version\fP is an ASCII string for the TLS library name + version used. If libcurl has no SSL support, this is NULL. For example "Schannel", -\&"SecureTransport" or "OpenSSL/1.1.0g". +\&"Secure Transport" or "OpenSSL/1.1.0g". \fIssl_version_num\fP is always 0. diff --git a/docs/libcurl/curl_ws_recv.3 b/docs/libcurl/curl_ws_recv.3 index bdfcd2667..86254e0ff 100644 --- a/docs/libcurl/curl_ws_recv.3 +++ b/docs/libcurl/curl_ws_recv.3 @@ -30,24 +30,24 @@ curl_ws_recv - receive WebSocket data #include <curl/easy.h> CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen, - size_t *recv, unsigned int *recvflags); + size_t *recv, unsigned int *flags); .fi .SH DESCRIPTION This function call is EXPERIMENTAL. -Retrives as much as possible of a received WebSocket data fragment into the +Retrieves as much as possible of a received WebSocket data fragment into the \fBbuffer\fP, but not more than \fBbuflen\fP bytes. The provide -\fIrecvflags\fP argument gets bits set to help characterize the fragment. -.SH RECVFLAGS +\fIflags\fP argument gets bits set to help characterize the fragment. +.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 precautions that you actually receive valid UTF-8 content. .IP CURLWS_BINARY This is binary data. -.IP CURLWS_FINAL -This is the final fragment of the message, if this is not set, it implies that -there will be another fragment coming as part of the same message. +.IP CURLWS_CONT +This is not the final fragment of the message, it implies that there will be +another fragment coming as part of the same message. .IP CURLWS_CLOSE This transfer is now closed. .IP CURLWS_PING diff --git a/docs/libcurl/curl_ws_send.3 b/docs/libcurl/curl_ws_send.3 index 53147cfb1..73ebc2540 100644 --- a/docs/libcurl/curl_ws_send.3 +++ b/docs/libcurl/curl_ws_send.3 @@ -24,13 +24,13 @@ .\" .TH curl_ws_send 3 "12 Jun 2022" "libcurl 7.85.0" "libcurl Manual" .SH NAME -curl_ws_send - receive websocket data +curl_ws_send - receive WebSocket data .SH SYNOPSIS .nf #include <curl/easy.h> CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen, - size_t *sent, unsigned int sendflags); + size_t *sent, unsigned int flags); .fi .SH DESCRIPTION This function call is EXPERIMENTAL. @@ -38,9 +38,9 @@ This function call is EXPERIMENTAL. Send the specific message fragment over the established WebSocket connection. If \fBCURLWS_RAW_MODE\fP is enabled in \fICURLOPT_WS_OPTIONS(3)\fP, the -\fBsendflags\fP argument should be set to 0. +\fBflags\fP argument should be set to 0. -.SH SENDFLAGS +.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 diff --git a/docs/libcurl/libcurl-env.3 b/docs/libcurl/libcurl-env.3 index 6cae1c7ad..8db55acd2 100644 --- a/docs/libcurl/libcurl-env.3 +++ b/docs/libcurl/libcurl-env.3 @@ -50,8 +50,8 @@ 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. -SSL backend names (case-insensitive): bearssl, gnutls, gskit, mbedtls, -nss, openssl, rustls, schannel, secure-transport, wolfssl +SSL backend names (case-insensitive): BearSSL, GnuTLS, gskit, mbedTLS, +nss, OpenSSL, rustls, Schannel, Secure-Transport, wolfSSL .IP HOME When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is checked as the primary way to find the "current" home directory in which @@ -61,13 +61,14 @@ When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is checked as the secondary way to find the "current" home directory (on Windows only) in which the .netrc file is likely to exist. .IP LOGNAME -User name to use when invoking the ntlm-wb tool, if NTLMUSER was not set. +User name to use when invoking the \fIntlm-wb\fP tool, if \fINTLMUSER\fP was +not set. .IP NO_PROXY This has the same functionality as the \fICURLOPT_NOPROXY(3)\fP option: it gives libcurl a comma-separated list of host name patterns for which libcurl should not use a proxy. .IP NTLMUSER -User name to use when invoking the ntlm-wb tool. +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 @@ -77,8 +78,8 @@ analyze/view the traffic. When libcurl runs with the NSS backends for TLS features, this variable is used to find the directory for NSS PKI database instead of the built-in. .IP USER -User name to use when invoking the ntlm-wb tool, if NTLMUSER and LOGNAME -were not set. +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 "debug enabled", which should never be true for a library used in production. @@ -93,6 +94,7 @@ random outputs can be tested for what they generate. .IP "CURL_TRACE" Debug-only variable. Used for debugging the lib/ldap implementation. .IP "CURL_NTLM_WB_FILE" -Debug-only variable. Used to set to a debug-version of the ntlm-wb executable. +Debug-only variable. Used to set to a debug-version of the \fIntlm-wb\fP +executable. .IP "CURL_OPENLDAP_TRACE" -Debug-only variable. Used for debugging the lib/openldap.c implementation. +Debug-only variable. Used for debugging the OpenLDAP implementation. diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 78d5101d4..d28cdd0d5 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -56,9 +56,9 @@ due to a build-time decision. This means that a feature or option was not enabled or explicitly disabled when libcurl was built and in order to get it to function you have to get a rebuilt libcurl. .IP "CURLE_COULDNT_RESOLVE_PROXY (5)" -Couldn't resolve proxy. The given proxy host could not be resolved. +Could not resolve proxy. The given proxy host could not be resolved. .IP "CURLE_COULDNT_RESOLVE_HOST (6)" -Couldn't resolve host. The given remote host was not resolved. +Could not resolve host. The given remote host was not resolved. .IP "CURLE_COULDNT_CONNECT (7)" Failed to connect() to host or proxy. .IP "CURLE_WEIRD_SERVER_REPLY (8)" @@ -197,9 +197,9 @@ Not used in modern versions. .IP "CURLE_SSL_CERTPROBLEM (58)" problem with the local client certificate. .IP "CURLE_SSL_CIPHER (59)" -Couldn't use specified cipher. +Could not use specified cipher. .IP "CURLE_PEER_FAILED_VERIFICATION (60)" -The remote server's SSL certificate or SSH md5 fingerprint was deemed not OK. +The remote server's SSL certificate or SSH fingerprint was deemed not OK. This error code has been unified with CURLE_SSL_CACERT since 7.62.0. Its previous value was 51. .IP "CURLE_BAD_CONTENT_ENCODING (61)" @@ -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 PRET CMD before PASV as well. (Added in -7.20.0) +custom LIST command will be 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)" @@ -301,12 +301,12 @@ between. Before version 7.20.0 (released on February 9 2010) this could be retur \fIcurl_multi_perform(3)\fP, but in later versions this return code is never used. .IP "CURLM_CALL_MULTI_SOCKET (-1)" -An alias for CURLM_CALL_MULTI_PERFORM. Never returned by modern libcurl +An alias for \fICURLM_CALL_MULTI_PERFORM\fP. Never returned by modern libcurl versions. .IP "CURLM_OK (0)" Things are fine. .IP "CURLM_BAD_HANDLE (1)" -The passed-in handle is not a valid CURLM handle. +The passed-in handle is not a valid \fICURLM\fP handle. .IP "CURLM_BAD_EASY_HANDLE (2)" An easy handle was not good/valid. It could mean that it is not an easy handle at all, or possibly that the handle already is in use by this or another multi @@ -327,7 +327,7 @@ second time. (Added in 7.32.1) .IP "CURLM_RECURSIVE_API_CALL (8)" An API function was called from inside a callback. .IP "CURLM_WAKEUP_FAILURE (9)" -Wakeup is unavailable or failed. +Wake up is unavailable or failed. .IP "CURLM_BAD_FUNCTION_ARGUMENT (10)" A function was called with a bad parameter. .IP "CURLM_ABORTED_BY_CALLBACK (11)" @@ -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 CURLSHcode to indicate when an error has -occurred. Also consider \fIcurl_share_strerror(3)\fP. +The "share" interface will return 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,10 +352,10 @@ 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 CURLUcode to indicate when an error has +The URL interface will return a \fICURLUcode\fP to indicate when an error has occurred. Also consider \fIcurl_url_strerror(3)\fP. .IP "CURLUE_BAD_HANDLE (1)" -An invalid CURLU pointer was passed as argument. +An invalid URL handle was passed as argument. .IP "CURLUE_BAD_PARTPOINTER (2)" An invalid 'part' argument was passed as argument. .IP "CURLUE_MALFORMED_INPUT (3)" @@ -389,7 +389,7 @@ There is no query part in the URL. .IP "CURLUE_NO_FRAGMENT (17)" There is no fragment part in the URL. .IP "CURLUE_NO_ZONEID (18)" -There is no zoneid set in the URL. +There is no zone id set in the URL. .IP "CURLUE_BAD_FILE_URL (19)" The file:// URL is invalid. .IP "CURLUE_BAD_FRAGMENT (20)" diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 61fa9c603..55bed7cc2 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -58,7 +58,7 @@ transfers in parallel. Each single transfer is built up around an easy 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 flavours of the multi interface, the select() oriented one and +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 differentiate. We start out with the select() oriented version. @@ -89,7 +89,7 @@ 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_fdset(3)\fP that extracts fd_sets from libcurl to use in +\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 wait for input on your own private file descriptors at the same time. @@ -160,10 +160,11 @@ better scale upward and beyond thousands of simultaneous transfers without 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 sockfd -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. +\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. 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 5163b6c6e..4f307aee4 100644 --- a/docs/libcurl/libcurl-security.3 +++ b/docs/libcurl/libcurl-security.3 @@ -45,7 +45,7 @@ should be aware. .SH "Command Lines" If you use a command line tool (such as curl) that uses libcurl, and you give options to the tool on the command line those options can get read by other -users of your system when they use 'ps' or other tools to list currently +users of your system when they use \fIps\fP or other tools to list currently running processes. To avoid these problems, never feed sensitive things to programs using command @@ -76,23 +76,22 @@ To avoid this problem, use an authentication mechanism or other protocol that does not let snoopers see your password: Digest, CRAM-MD5, Kerberos, SPNEGO or NTLM authentication. Or even better: use authenticated protocols that protect the entire connection and everything sent over it. -.SH "Un-authenticated Connections" +.SH "Unauthenticated Connections" Protocols that do not have any form of cryptographic authentication cannot with any certainty know that they communicate with the right remote server. If your application is using a fixed scheme or fixed host name, it is not safe -as long as the connection is un-authenticated. There can be a -man-in-the-middle or in fact the whole server might have been replaced by an -evil actor. +as long as the connection is unauthenticated. There can be a man-in-the-middle +or in fact the whole server might have been replaced by an evil actor. -Un-authenticated protocols are unsafe. The data that comes back to curl may +Unauthenticated protocols are unsafe. The data that comes back to curl may have been injected by an attacker. The data that curl sends might be modified before it reaches the intended server. If it even reaches the intended server at all. Remedies: .IP "Restrict operations to authenticated transfers" -Ie use authenticated protocols protected with HTTPS or SSH. +Use authenticated protocols protected with HTTPS or SSH. .IP "Make sure the server's certificate etc is verified" Never ever switch off certificate verification. .SH "Redirects" @@ -106,7 +105,7 @@ A redirect to a file: URL would cause the libcurl to read (or write) arbitrary files from the local filesystem. If the application returns the data back to the user (as would happen in some kinds of CGI scripts), an attacker could leverage this to read otherwise forbidden data (e.g. -file://localhost/etc/passwd). +\fBfile://localhost/etc/passwd\fP). If authentication credentials are stored in the ~/.netrc file, or Kerberos is in use, any other URL type (not just file:) that requires authentication is @@ -116,7 +115,7 @@ then return data even when the server is password protected. In the same way, if an unencrypted SSH private key has been configured for the user running the libcurl application, SCP: or SFTP: URLs could access password or private-key protected resources, -e.g. sftp://user@some-internal-server/etc/passwd +e.g. \fBsftp://user@some-internal-server/etc/passwd\fP The \fICURLOPT_REDIR_PROTOCOLS(3)\fP and \fICURLOPT_NETRC(3)\fP options can be used to mitigate against this kind of attack. @@ -137,26 +136,26 @@ 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 sanitization or normalization to them. +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 way -you didn't intend such as injecting new headers. +sequences in them, someone malicious may be able to modify the request in a +way you did not intend such as injecting new headers. .SH "Local Resources" A user who can control the DNS server of a domain being passed in within a URL can change the address of the host to a local, private address which a server-side libcurl-using application could then use. e.g. the innocuous URL -http://fuzzybunnies.example.com/ could actually resolve to the IP address of a -server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Applications can -mitigate against this by setting a \fICURLOPT_OPENSOCKETFUNCTION(3)\fP -or \fICURLOPT_PREREQFUNCTION(3)\fP and checking the address before a -connection. +\fBhttp://fuzzybunnies.example.com/\fP could actually resolve to the IP +address of a server behind a firewall, such as 127.0.0.1 or +10.1.2.3. Applications can mitigate against this by setting a +\fICURLOPT_OPENSOCKETFUNCTION(3)\fP or \fICURLOPT_PREREQFUNCTION(3)\fP and +checking the address before a connection. All the malicious scenarios regarding redirected URLs apply just as well to non-redirected URLs, if the user is allowed to specify an arbitrary URL that could point to a private resource. For example, a web app providing a -translation service might happily translate file://localhost/etc/passwd and -display the result. Applications can mitigate against this with the +translation service might happily translate \fBfile://localhost/etc/passwd\fP +and display the result. Applications can mitigate against this with the \fICURLOPT_PROTOCOLS(3)\fP option as well as by similar mitigation techniques for redirections. @@ -183,16 +182,16 @@ 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 ::1, -::, 0:00::0:1, ::127.0.0.1 and ::ffff:7f00:1 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. +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 @@ -223,9 +222,9 @@ between requests. .SH "Dangerous SCP URLs" SCP URLs can contain raw commands within the scp: URL, which is a side effect of how the SCP protocol is designed. e.g. - +.nf scp://user:pass@host/a;date >/tmp/test; - +.fi Applications must not allow unsanitized SCP: URLs to be passed in for downloads. .SH "file://" @@ -305,13 +304,13 @@ as within libcurl itself. When performing an FTP transfer, two TCP connections are used: one for setting up the transfer and one for the actual data. -FTP is not only un-authenticated, but the setting up of the second transfer is +FTP is not only unauthenticated, but the setting up of the second transfer is also a weak spot. The second connection to use for data, is either setup with the PORT/EPRT command that makes the server connect back to the client on the 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, un-authenticated means that the connection might be meddled with by a +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 right one. @@ -360,7 +359,8 @@ file name. The curl command-line tool does this with a file name. An application could also use \fICURLINFO_EFFECTIVE_URL(3)\fP to generate a file name from a server-supplied redirect URL. Special care must be taken to sanitize such names to avoid the possibility of a malicious server -supplying one like "/etc/passwd", "\\autoexec.bat", "prn:" or even ".bashrc". +supplying one like \fB"/etc/passwd"\fP, \fB"\\autoexec.bat"\fP, \fB"prn:"\fP +or even \fB".bashrc"\fP. .SH "Server Certificates" A secure application should never use the \fICURLOPT_SSL_VERIFYPEER(3)\fP option to disable certificate validation. There are numerous attacks that are @@ -384,7 +384,7 @@ sensitive data. To avoid this problem, you must of course use your common sense. Often, you can just edit out the sensitive data or just search/replace your true information with faked data. -.SH "Setuid applications using libcurl" +.SH "setuid applications using libcurl" libcurl-using applications that set the 'setuid' bit to run with elevated or modified rights also implicitly give that extra power to libcurl and this should only be done after careful considerations. @@ -396,13 +396,13 @@ that the user is otherwise not able to view (like credentials for a login 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_wb" -An application that uses libcurl and invokes `fork()` will get all file +.SH "File descriptors, fork and NTLM" +An application that uses libcurl and invokes \fIfork()\fP will get all file descriptors duplicated in the child process, including the ones libcurl created. -libcurl itself uses `fork()` and `execl()` if told to use the -`CURLAUTH_NTLM_WB` authentication method which then will invoke the helper +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 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" @@ -416,7 +416,7 @@ core dump file, such data might be accessible. Further, when eventually closing a handle and the secrets are no longer needed, libcurl does not explicitly clear memory before freeing it, so -crendentials may be left in freed data. +credentials may be left in freed data. .SH "Report Security Problems" Should you detect or just suspect a security problem in libcurl or curl, contact the project curl security team immediately. See diff --git a/docs/libcurl/libcurl-thread.3 b/docs/libcurl/libcurl-thread.3 index 1b00b90d1..1aebbb3e8 100644 --- a/docs/libcurl/libcurl-thread.3 +++ b/docs/libcurl/libcurl-thread.3 @@ -95,8 +95,8 @@ days). Some operating systems that are known to have solid and working thread support are Linux, Solaris and Windows. .IP "curl_global_* functions" These functions are thread-safe since libcurl 7.84.0 if -\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set -(most platforms). +\fIcurl_version_info(3)\fP has the \fBCURL_VERSION_THREADSAFE\fP feature bit +set (most platforms). If these functions are not thread-safe and you are using libcurl with multiple threads it is especially important that before use you call diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 73b8cab46..d9ab5a4c6 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -49,9 +49,9 @@ well. 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 installed them. The 'curl-config'[3] tool can be used to get this information: - -$ curl-config --cflags - +.nf + $ curl-config --cflags +.fi .IP "Linking the Program with libcurl" When having compiled the program, you need to link your object files to create a single executable. For that to succeed, you need to link with libcurl and @@ -59,9 +59,9 @@ possibly also with other libraries that libcurl itself depends on. Like the OpenSSL libraries, but even some standard OS libraries may be needed on the command line. To figure out which flags to use, once again the 'curl-config' tool comes to the rescue: - -$ curl-config --libs - +.nf + $ curl-config --libs +.fi .IP "SSL or Not" 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 @@ -69,10 +69,10 @@ 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: - -$ curl-config --feature - -And if SSL is supported, the keyword 'SSL' will be written to stdout, +.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. @@ -95,9 +95,9 @@ stop you from that. The program must initialize some of the libcurl functionality globally. That means it should be done exactly once, no matter how many times you intend to use the library. Once for your program's entire life time. This is done using - +.nf 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 @@ -155,9 +155,9 @@ should use one handle for every thread you plan to use for transferring. You must never share the same handle in multiple threads. Get an easy handle with - - easyhandle = curl_easy_init(); - +.nf + handle = curl_easy_init(); +.fi It returns an easy handle. Using that you proceed to the next step: setting up your preferred actions. A handle is just a logic entity for the upcoming transfer or series of transfers. @@ -190,19 +190,19 @@ remote resource you want to get here. Since you write a sort of application that needs this transfer, I assume that you would like to get the data passed to you directly instead of simply getting it passed to stdout. So, you write your own function that matches this prototype: - +.nf size_t write_data(void *buffer, size_t size, size_t nmemb, void *userp); - +.fi You tell libcurl to pass all data to this function by issuing a function similar to this: - - curl_easy_setopt(easyhandle, CURLOPT_WRITEFUNCTION, write_data); - +.nf + curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, write_data); +.fi You can control what data your callback function gets in the fourth argument by setting another property: - - curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct); - +.nf + 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. @@ -229,9 +229,9 @@ will 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: - - success = curl_easy_perform(easyhandle); - +.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 callback function we previously set. The function may get one byte at a time, @@ -301,30 +301,30 @@ 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: - +.nf size_t function(char *bufptr, size_t size, size_t nitems, void *userp); - -Where bufptr is the pointer to a buffer we fill in with data to upload and -size*nitems is the size of the buffer and therefore also the maximum amount -of data we can return to libcurl in this call. The 'userp' pointer is the -custom pointer we set to point to a struct of ours to pass private data +.fi +Where \fIbufptr\fP is the pointer to a buffer we fill in with data to upload +and \fIsize*nitems\fP is the size of the buffer and therefore also the maximum +amount of data we can return to libcurl in this call. The \fIuserp\fP pointer +is the custom pointer we set to point to a struct of ours to pass private data between the application and the callback. +.nf + curl_easy_setopt(handle, CURLOPT_READFUNCTION, read_function); - curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, read_function); - - curl_easy_setopt(easyhandle, CURLOPT_READDATA, &filedata); - + curl_easy_setopt(handle, CURLOPT_READDATA, &filedata); +.fi Tell libcurl that we want to upload: - - curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, 1L); - +.nf + curl_easy_setopt(handle, CURLOPT_UPLOAD, 1L); +.fi A few protocols will 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]: .nf /* in this example, file_size must be an curl_off_t variable */ - curl_easy_setopt(easyhandle, CURLOPT_INFILESIZE_LARGE, file_size); + 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 @@ -342,9 +342,9 @@ 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: - +.nf protocol://user:password@example.com/path/ - +.fi If you need any odd letters in your user name or password, you should enter them URL encoded, as %XX where XX is a two-digit hexadecimal number. @@ -352,29 +352,29 @@ libcurl also provides options to set various passwords. The user name and password as shown embedded in the URL can instead get set with the \fICURLOPT_USERPWD(3)\fP option. The argument passed to libcurl should be a char * to a string in the format "user:password". In a manner like this: - - curl_easy_setopt(easyhandle, CURLOPT_USERPWD, "myname:thesecret"); - +.nf + curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret"); +.fi Another case where name and password might be needed at times, is for those users who need to authenticate themselves to a proxy they use. libcurl offers another option for this, the \fICURLOPT_PROXYUSERPWD(3)\fP. It is used quite similar to the \fICURLOPT_USERPWD(3)\fP option like this: - - curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); - +.nf + curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); +.fi There's 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 %USERPROFILE% environment variable if %HOME% is unset, and tries -_netrc as name). The file should be made private so that only the user may -read it (see also the "Security Considerations" chapter), -as it might contain the password in plain text. libcurl has the -ability to use this file to figure out what set of user name and password to -use for a particular host. As an extension to the normal functionality, -libcurl also supports this file for non-FTP protocols such as HTTP. To make -curl use this file, use the \fICURLOPT_NETRC(3)\fP option: - - curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L); - +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 +may read it (see also the "Security Considerations" chapter), as it might +contain the password in plain text. libcurl has the ability to use this file +to figure out what set of user name and password to use for a particular +host. As an extension to the normal functionality, libcurl also supports this +file for non-FTP protocols such as HTTP. To make curl use this file, use the +\fICURLOPT_NETRC(3)\fP option: +.nf + curl_easy_setopt(handle, CURLOPT_NETRC, 1L); +.fi And a basic example of how such a .netrc file may look like: .nf @@ -389,9 +389,9 @@ without it. There are times when the password is not optional, like when you are using an SSL private key for secure transfers. To pass the known private key password to libcurl: - - curl_easy_setopt(easyhandle, CURLOPT_KEYPASSWD, "keypassword"); - +.nf + 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 @@ -403,23 +403,22 @@ 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 with \fICURLOPT_HTTPAUTH(3)\fP as in: - - curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST); - +.nf + curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST); +.fi And when you send authentication to a proxy, you can also set authentication type the same way but instead with \fICURLOPT_PROXYAUTH(3)\fP: - - curl_easy_setopt(easyhandle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM); - +.nf + curl_easy_setopt(handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM); +.fi Both these options allow you to set multiple types (by ORing them together), to make libcurl pick the most secure one out of the types the server/proxy claims to support. This method does however add a round-trip since libcurl must first ask the server what it supports: - - curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, - CURLAUTH_DIGEST|CURLAUTH_BASIC); - -For convenience, you can use the 'CURLAUTH_ANY' define (instead of a list +.nf + curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST|CURLAUTH_BASIC); +.fi +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 @@ -436,10 +435,10 @@ libcurl to post it all to the remote site: .nf char *data="name=daniel&project=curl"; - curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, data); - curl_easy_setopt(easyhandle, CURLOPT_URL, "http://posthere.com/"); + curl_easy_setopt(handle, CURLOPT_POSTFIELDS, data); + curl_easy_setopt(handle, CURLOPT_URL, "http://posthere.com/"); - curl_easy_perform(easyhandle); /* post away! */ + curl_easy_perform(handle); /* post away! */ .fi Simple enough, huh? Since you set the POST options with the @@ -458,15 +457,15 @@ that list to libcurl. headers = curl_slist_append(headers, "Content-Type: text/xml"); /* post binary data */ - curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, binaryptr); + curl_easy_setopt(handle, CURLOPT_POSTFIELDS, binaryptr); /* set the size of the postfields data */ - curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23L); + curl_easy_setopt(handle, CURLOPT_POSTFIELDSIZE, 23L); /* pass our list of custom made headers */ - curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers); + curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); - curl_easy_perform(easyhandle); /* post away! */ + curl_easy_perform(handle); /* post away! */ curl_slist_free_all(headers); /* free the header list */ .fi @@ -497,7 +496,7 @@ The following example sets two simple text parts with plain textual contents, and then a file with binary contents and uploads the whole thing. .nf - curl_mime *multipart = curl_mime_init(easyhandle); + curl_mime *multipart = curl_mime_init(handle); curl_mimepart *part = curl_mime_addpart(multipart); curl_mime_name(part, "name"); curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); @@ -509,9 +508,9 @@ and then a file with binary contents and uploads the whole thing. curl_mime_filedata(part, "curl.png"); /* Set the form info */ - curl_easy_setopt(easyhandle, CURLOPT_MIMEPOST, multipart); + curl_easy_setopt(handle, CURLOPT_MIMEPOST, multipart); - curl_easy_perform(easyhandle); /* post away! */ + curl_easy_perform(handle); /* post away! */ /* free the post data again */ curl_mime_free(multipart); @@ -553,9 +552,9 @@ The MIME API example above is expressed as follows using this function: CURLFORM_FILECONTENT, "curl.png", CURLFORM_END); /* Set the form info */ - curl_easy_setopt(easyhandle, CURLOPT_HTTPPOST, post); + curl_easy_setopt(handle, CURLOPT_HTTPPOST, post); - curl_easy_perform(easyhandle); /* post away! */ + curl_easy_perform(handle); /* post away! */ /* free the post data again */ curl_formfree(post); @@ -580,20 +579,20 @@ post handle: CURLFORM_CONTENTHEADER, headers, CURLFORM_END); - curl_easy_perform(easyhandle); /* post away! */ + curl_easy_perform(handle); /* post away! */ curl_formfree(post); /* free post */ curl_slist_free_all(headers); /* free custom header list */ .fi -Since all options on an easyhandle are "sticky", they remain the same until +Since all options on an easy handle are "sticky", they remain the same until changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell curl to go back to a plain GET request if you intend to do one as your next -request. You force an easyhandle to go back to GET by using the +request. You force an easy handle to go back to GET by using the \fICURLOPT_HTTPGET(3)\fP option: - - curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L); - +.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! @@ -602,7 +601,7 @@ Four rules have to be respected in building the multi-part: .br - The easy handle must be created before building the multi-part. .br -- The multi-part is always created by a call to curl_mime_init(easyhandle). +- The multi-part is always created by a call to curl_mime_init(handle). .br - Each part is created by a call to curl_mime_addpart(multipart). .br @@ -669,7 +668,7 @@ The deprecated multipart/mixed implementation of multiple files field is translated to two distinct parts with the same name. .nf - curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, myreadfunc); + curl_easy_setopt(handle, CURLOPT_READFUNCTION, myreadfunc); curl_formadd(&post, &last, CURLFORM_COPYNAME, "stream", CURLFORM_STREAM, arg, @@ -804,40 +803,40 @@ invoke your own custom FTP commands or even proper FTP directory listings. .IP "Proxy Options" To tell libcurl to use a proxy at a given port number: - - curl_easy_setopt(easyhandle, CURLOPT_PROXY, "proxy-host.com:8080"); - +.nf + curl_easy_setopt(handle, CURLOPT_PROXY, "proxy-host.com:8080"); +.fi Some proxies require user authentication before allowing a request, and you pass that information similar to this: - - curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "user:password"); - +.nf + curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "user:password"); +.fi If you want to, you can specify the host name only in the \fICURLOPT_PROXY(3)\fP option, and set the port number separately with \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): - - curl_easy_setopt(easyhandle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4); - +.nf + curl_easy_setopt(handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4); +.fi .IP "Environment Variables" libcurl automatically checks and uses a set of environment variables to know what proxies to use for certain protocols. The names of the variables are -following an ancient de facto standard and are built up as "[protocol]_proxy" -(note the lower casing). Which makes the variable \&'http_proxy' checked for a -name of a proxy to use when the input URL is HTTP. Following the same rule, -the variable named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are -always HTTP proxies, the different names of the variables simply allows -different HTTP proxies to be used. +following an old tradition and are built up as "[protocol]_proxy" (note the +lower casing). Which makes the variable \&'http_proxy' checked for a name of a +proxy to use when the input URL is HTTP. Following the same rule, the variable +named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are always HTTP +proxies, the different names of the variables simply allows different HTTP +proxies to be used. The proxy environment variable contents should be in the format -\&"[protocol://][user:password@]machine[:port]". Where the protocol:// part is -simply ignored if present (so http://proxy and bluerk://proxy will do the -same) and the optional port number specifies on which port the proxy operates -on the host. 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. +\&"[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. 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 @@ -859,7 +858,7 @@ with the traffic. Opening an SSL connection over an HTTP proxy is therefore a matter of asking the proxy for a straight connection to the target host on a specified port. This -is made with the HTTP request CONNECT. ("please mr proxy, connect me to that +is made with the HTTP request CONNECT. ("please dear proxy, connect me to that remote host"). Because of the nature of this operation, where the proxy has no idea what kind @@ -884,9 +883,9 @@ Again, this is often prevented by the administrators of proxies and is rarely allowed. Tell libcurl to use proxy tunneling like this: - - curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, 1L); - +.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 @@ -970,7 +969,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 will not use this header. .SH "Customizing Operations" @@ -988,9 +987,9 @@ libcurl is your friend here too. If just changing the actual HTTP request keyword is what you want, like when GET, HEAD or POST is not good enough for you, \fICURLOPT_CUSTOMREQUEST(3)\fP is there for you. It is simple to use: - - curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST"); - +.nf + curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST"); +.fi When using the custom request, you change the request keyword of the actual request you are performing. Thus, by default you make a GET request but you can also make a POST operation (as described before) and then replace the POST @@ -1008,9 +1007,9 @@ think fit. Adding headers is this easy: headers = curl_slist_append(headers, "X-silly-content: yes"); /* pass our list of custom made headers */ - curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers); + curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); - curl_easy_perform(easyhandle); /* transfer http */ + curl_easy_perform(handle); /* transfer http */ curl_slist_free_all(headers); /* free the header list */ .fi @@ -1050,7 +1049,7 @@ we support. libcurl speaks HTTP 1.1 by default. Some old servers do not like getting 1.1-requests and when dealing with stubborn old things like that, you can tell libcurl to use 1.0 instead by doing something like this: - curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0); + curl_easy_setopt(handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0); .IP "FTP Custom Commands" @@ -1061,7 +1060,7 @@ Sending custom commands to an FTP server means that you need to send the commands exactly as the FTP server expects them (RFC959 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 judgement. Also be aware that +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 confuse libcurl and then it might not attempt to transfer the file in the @@ -1073,9 +1072,9 @@ A little example that deletes a given file before an operation: headers = curl_slist_append(headers, "DELE file-to-remove"); /* pass the list of custom commands to the handle */ - curl_easy_setopt(easyhandle, CURLOPT_QUOTE, headers); + curl_easy_setopt(handle, CURLOPT_QUOTE, headers); - curl_easy_perform(easyhandle); /* transfer ftp data! */ + curl_easy_perform(handle); /* transfer ftp data! */ curl_slist_free_all(headers); /* free the header list */ .fi @@ -1121,9 +1120,9 @@ they are sent from clients to servers with the Cookie: header. To just send whatever cookie you want to a server, you can use \fICURLOPT_COOKIE(3)\fP to set a cookie string like this: - - curl_easy_setopt(easyhandle, CURLOPT_COOKIE, "name1=var1; name2=var2;"); - +.nf + curl_easy_setopt(handle, CURLOPT_COOKIE, "name1=var1; name2=var2;"); +.fi In many cases, that is not enough. You might want to dynamically save whatever cookies the remote server passes to you, and make sure those cookies are then used accordingly on later requests. @@ -1215,17 +1214,17 @@ use this function (this would over-encode it), but explicitly set the corresponding part header. Upon sending such a message, libcurl prepends it with the header list -set with \fICURLOPT_HTTPHEADER(3)\fP, as 0th-level mime part headers. +set with \fICURLOPT_HTTPHEADER(3)\fP, as zero level mime part headers. Here is an example building an email message with an inline plain/html text alternative and a file attachment encoded in base64: .nf - curl_mime *message = curl_mime_init(easyhandle); + curl_mime *message = curl_mime_init(handle); /* The inline part is an alternative proposing the html and the text versions of the email. */ - curl_mime *alt = curl_mime_init(easyhandle); + curl_mime *alt = curl_mime_init(handle); /* HTML message. */ curl_mimepart *part = curl_mime_addpart(alt); @@ -1256,8 +1255,8 @@ alternative and a file attachment encoded in base64: headers = curl_slist_append(headers, "To: you@example.com"); /* Set these into the easy handle. */ - curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers); - curl_easy_setopt(easyhandle, CURLOPT_MIMEPOST, mime); + curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); + curl_easy_setopt(handle, CURLOPT_MIMEPOST, mime); .fi It should be noted that appending a message to an IMAP directory requires @@ -1331,8 +1330,8 @@ The best usage of this interface is when you do a select() on all possible file descriptors or sockets to know when to call libcurl again. This also makes it easy for you to wait and respond to actions on your own application's sockets/handles. You figure out what to select() for by using -\fIcurl_multi_fdset(3)\fP, that fills in a set of fd_set variables for you -with the particular file descriptors libcurl uses for the moment. +\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 action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do diff --git a/docs/libcurl/libcurl-url.3 b/docs/libcurl/libcurl-url.3 index 0732f3ea7..830fec9ce 100644 --- a/docs/libcurl/libcurl-url.3 +++ b/docs/libcurl/libcurl-url.3 @@ -30,21 +30,23 @@ The URL interface provides functions for parsing and generating URLs. You still only include <curl/curl.h> in your code. .SH CREATE Create a handle that holds URL info and resources with \fIcurl_url(3)\fP: - +.nf CURLU *h = curl_url(); +.fi .SH CLEANUP -When done with it, clean it up with \fIcurl_url_cleanup(3)\fP: - +When done with it, clean it up with \fIcurl_url_cleanup(3)\fP +.nf curl_url_cleanup(h); +.fi .SH DUPLICATE When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP: - +.nf CURLU *nh = curl_url_dup(h); +.fi .SH PARSING -By "setting" a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed +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. - .nf rc = curl_url_set(h, CURLUPART_URL, "https://example.com:449/foo/bar?name=moo", 0); @@ -56,16 +58,17 @@ 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. - +.nf rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0); +.fi .SH "GET URL" -The `CURLU` handle represents a URL and you can easily extract that with +The \fBCURLU\fP handle represents a URL and you can easily extract that with \fIcurl_url_get(3)\fP: - +.nf char *url; rc = curl_url_get(h, CURLUPART_URL, &url, 0); curl_free(url); - +.fi The zero in the fourth argument is a bitmask for changing specific features. .SH "GET PARTS" When a URL has been parsed or parts have been set, you can extract those @@ -83,7 +86,7 @@ pieces from the handle at any time. .fi Extracted parts are not URL decoded unless the user also asks for it with the -CURLU_URLDECODE flag set in the fourth bitmask argument. +\fICURLU_URLDECODE\fP flag set in the fourth bitmask argument. Remember to free the returned string with \fIcurl_free(3)\fP when you are done with it! @@ -103,27 +106,26 @@ instead of parsing such. .fi Set parts are not URL encoded unless the user asks for it with the -`CURLU_URLENCODE` flag. -.SH "APPENDQUERY" +\fICURLU_URLENCODE\fP flag. +.SH "CURLU_APPENDQUERY" An application can append a string to the right end of the query part with the -`CURLU_APPENDQUERY` flag to \fIcurl_url_set(3)\fP. +\fICURLU_APPENDQUERY\fP flag to \fIcurl_url_set(3)\fP. -Imagine a handle that holds the URL `https://example.com/?shoes=2`. An -application can then add the string `hat=1` to the query part like this: +Imagine a handle that holds the URL "https://example.com/?shoes=2". An +application can then add the string "hat=1" to the query part like this: .nf 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 +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`. +"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 +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", CURLU_APPENDQUERY | CURLU_URLENCODE); @@ -131,9 +133,9 @@ ampersand in the data: Now the URL looks like .nf - https://example.com/?shoes=2&hat=1&candy=N%26N` + https://example.com/?shoes=2&hat=1&candy=N%26N .fi -.SH AVALABILITY +.SH AVAILABILITY The URL API was introduced in libcurl 7.62.0. .SH "SEE ALSO" .BR curl_url "(3), " curl_url_cleanup "(3), " curl_url_get "(3), " diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 5f3e264da..c1ed7c0bb 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -31,7 +31,7 @@ specific man pages for each function mentioned in here. See \fIlibcurl-url(3)\fP and \fIlibcurl-tutorial(3)\fP for in-depth understanding on how to program with libcurl. -There are many bindings available that bring libcurl access to your favourite +There are many bindings available that bring libcurl access to your favorite language. Look elsewhere for documentation on those. libcurl has a global constant environment that you must set up and maintain @@ -205,8 +205,8 @@ author of this libcurl-using module, you can make the constructor call \fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP and satisfy libcurl's requirements without your user having to think about it. (Caveat: If you are initializing libcurl from a Windows DLL you should not -initialize it from DllMain or a static initializer because Windows holds the -loader lock during that time and it could cause a deadlock.) +initialize it from \fIDllMain\fP or a static initializer because Windows holds +the loader lock during that time and it could cause a deadlock.) \fIcurl_global_init(3)\fP has an argument that tells what particular parts of the global constant environment to set up. In order to successfully use any diff --git a/docs/libcurl/opts/CURLINFO_CAINFO.3 b/docs/libcurl/opts/CURLINFO_CAINFO.3 index 3c620bb56..70ecc4c65 100644 --- a/docs/libcurl/opts/CURLINFO_CAINFO.3 +++ b/docs/libcurl/opts/CURLINFO_CAINFO.3 @@ -24,7 +24,7 @@ .\" .TH CURLINFO_CAINFO 3 "20 May 2022" "libcurl 7.84.0" "curl_easy_getinfo options" .SH NAME -CURLINFO_CAINFO \- get the default built-in CAINFO string +CURLINFO_CAINFO \- get the default built-in CA certificate path .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLINFO_CAPATH.3 b/docs/libcurl/opts/CURLINFO_CAPATH.3 index a5d396dad..28e84c171 100644 --- a/docs/libcurl/opts/CURLINFO_CAPATH.3 +++ b/docs/libcurl/opts/CURLINFO_CAPATH.3 @@ -24,7 +24,7 @@ .\" .TH CURLINFO_CAPATH 3 "20 May 2022" "libcurl 7.84.0" "curl_easy_getinfo options" .SH NAME -CURLINFO_CAPATH \- get the default built-in CAPATH string +CURLINFO_CAPATH \- get the default built-in CA path string .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.3 b/docs/libcurl/opts/CURLINFO_CERTINFO.3 index 550390ac2..1e604cccf 100644 --- a/docs/libcurl/opts/CURLINFO_CERTINFO.3 +++ b/docs/libcurl/opts/CURLINFO_CERTINFO.3 @@ -33,13 +33,13 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CERTINFO, struct curl_certinfo **chainp); .fi .SH DESCRIPTION -Pass a pointer to a 'struct curl_certinfo *' and you will get it set to point to -a struct that holds a number of linked lists with info about the certificate -chain, assuming you had \fICURLOPT_CERTINFO(3)\fP enabled when the request was -made. The struct reports how many certs it found and then you can extract info -for each of those certs by following the linked lists. The info chain is -provided in a series of data in the format "name:content" where the content is -for the specific named data. See also the certinfo.c example. +Pass a pointer to a \fIstruct curl_certinfo *\fP and you will get it set to +point to a struct that holds a number of linked lists with info about the +certificate chain, assuming you had \fICURLOPT_CERTINFO(3)\fP enabled when the +request was made. The struct reports how many certs it found and then you can +extract info for each of those certs by following the linked lists. The info +chain is provided in a series of data in the format "name:content" where the +content is for the specific named data. See also the \fIcertinfo.c\fP example. .SH PROTOCOLS All TLS-based .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_FILETIME.3 b/docs/libcurl/opts/CURLINFO_FILETIME.3 index 68734d93a..5c34ffc8d 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME.3 +++ b/docs/libcurl/opts/CURLINFO_FILETIME.3 @@ -33,7 +33,7 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME, long *timep); .fi .SH DESCRIPTION Pass a pointer to a long to receive the remote time of the retrieved document -(in number of seconds since 1 jan 1970 in the GMT/UTC time zone). If you get +in number of seconds since January 1 1970 in the GMT/UTC time zone. If you get -1, it can be because of many reasons (it might be unknown, the server might hide it or the server does not support the command that tells document time etc) and the time of the document is unknown. diff --git a/docs/libcurl/opts/CURLINFO_FILETIME_T.3 b/docs/libcurl/opts/CURLINFO_FILETIME_T.3 index b3fc11594..cb6c4a941 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME_T.3 +++ b/docs/libcurl/opts/CURLINFO_FILETIME_T.3 @@ -34,10 +34,10 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME_T, .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the remote time of the retrieved -document (in number of seconds since 1 jan 1970 in the GMT/UTC time zone). If -you get -1, it can be because of many reasons (it might be unknown, the server -might hide it or the server does not support the command that tells document -time etc) and the time of the document is unknown. +document in number of seconds since January 1 1970 in the GMT/UTC time +zone. If you get -1, it can be because of many reasons (it might be unknown, +the server might hide it or the server does not support the command that tells +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 diff --git a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 index ffc551a29..45100cd27 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 +++ b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 @@ -71,12 +71,11 @@ 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 CURLE_PROXY error. +transfer returned a \fBCURLE_PROXY\fP error. That error code will match the +\fBCURLproxycode\fP set. -The return value will match the CURLproxycode set. - -The returned value will be zero (equal to CURLPX_OK) if no such response code -was available. +The error code will be 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_RESPONSE_CODE.3 b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 index 774c51ada..f833a3f91 100644 --- a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 +++ b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 @@ -33,7 +33,7 @@ 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 +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 diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 index e18acb297..30b06e89b 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 +++ b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 @@ -36,7 +36,7 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_SERVER_CSEQ, Pass a pointer to a long to receive the next CSeq that will be expected by the application. -Llistening for server initiated requests is currently unimplemented! +Listening for server initiated requests is not implemented! Applications wishing to resume an RTSP session on another connection should retrieve this info before closing the active connection. diff --git a/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 b/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 index cd06610ee..c7e635070 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 +++ b/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 @@ -40,14 +40,14 @@ This option is exactly the same as \fICURLINFO_TLS_SSL_PTR(3)\fP except in the case of OpenSSL. If the session \fIbackend\fP is CURLSSLBACKEND_OPENSSL the session \fIinternals\fP pointer varies depending on the option: -CURLINFO_TLS_SESSION OpenSSL session \fIinternals\fP is SSL_CTX *. +CURLINFO_TLS_SESSION OpenSSL session \fIinternals\fP is \fBSSL_CTX *\fP. -CURLINFO_TLS_SSL_PTR OpenSSL session \fIinternals\fP is SSL *. +CURLINFO_TLS_SSL_PTR OpenSSL session \fIinternals\fP is \fBSSL *\fP. -You can obtain an SSL_CTX pointer from an SSL pointer using OpenSSL function -SSL_get_SSL_CTX. Therefore unless you need compatibility with older versions of -libcurl use \fICURLINFO_TLS_SSL_PTR(3)\fP. Refer to that document for more -information. +You can obtain an \fBSSL_CTX\fP pointer from an SSL pointer using OpenSSL +function \fISSL_get_SSL_CTX(3)\fP. Therefore unless you need compatibility +with older versions of libcurl use \fICURLINFO_TLS_SSL_PTR(3)\fP. Refer to +that document for more information. .SH PROTOCOLS All TLS-based .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 index 854d2efbc..f260cd690 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 'struct curl_tlssessioninfo *'. The pointer will be -initialized to refer to a 'struct curl_tlssessioninfo *' 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 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 respective internal TLS session structure of this underlying SSL library. This option may be useful for example to extract certificate information in a @@ -66,34 +66,32 @@ 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: .RS .IP GnuTLS -gnutls_session_t +\fBgnutls_session_t\fP .IP gskit -gsk_handle +\fBgsk_handle\fP .IP NSS -PRFileDesc * +\fBPRFileDesc *\fP .IP OpenSSL -CURLINFO_TLS_SESSION: SSL_CTX * +CURLINFO_TLS_SESSION: \fBSSL_CTX *\fP -CURLINFO_TLS_SSL_PTR: SSL * +CURLINFO_TLS_SSL_PTR: \fBSSL *\fP .RE Since 7.48.0 the \fIinternals\fP member can point to these other SSL backends as well: .RS .IP mbedTLS -mbedtls_ssl_context * +\fBmbedTLS_ssl_context *\fP .IP "Secure Channel" -CtxtHandle * +\fBCtxtHandle *\fP .IP "Secure Transport" -SSLContext * +\fBSSLContext *\fP .IP "wolfSSL" -SSL * -.IP "MesaLink" -SSL * +\fBSSL *\fP .RE If the \fIinternals\fP pointer is NULL then either the SSL backend is not supported, an SSL session has not yet been established or the connection is no -longer associated with the easy handle (eg curl_easy_perform has returned). +longer associated with the easy handle (e.g. curl_easy_perform has returned). .SH LIMITATIONS This option has some limitations that could make it unsafe when it comes to the manual verification of certificates. @@ -104,7 +102,7 @@ using FTP over SSL. That is because the FTP protocol has a control channel and a data channel and one or both may be over SSL. Currently there is no way to retrieve a second in-use SSL session associated with an easy handle. -This option has not been thoroughly tested with plaintext protocols that can +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 @@ -117,10 +115,10 @@ after renegotiation but before you are able to get the (possibly) changed SSL pointer, with the (possibly) changed certificate information. If you are using OpenSSL or wolfSSL then \fICURLOPT_SSL_CTX_FUNCTION(3)\fP can -be used to set a certificate verification callback in the CTX. That is safer -than using this option to poll for certificate changes and does not suffer from -any of the problems above. There is currently no way in libcurl to set a -verification callback for the other SSL backends. +be used to set a certificate verification callback. That is safer than using +this option to poll for certificate changes and does not suffer from any of +the problems above. There is currently no way in libcurl to set a verification +callback for the other SSL backends. How are you using this option? Are you affected by any of these limitations? Please let us know by making a comment at diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 index 274c0a96e..b15288735 100644 --- a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 +++ b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 @@ -35,11 +35,11 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, .SH DESCRIPTION No function since pipelining was removed in 7.62.0. -Pass a long with a \fBsize\fP in bytes. If a pipelined connection 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. +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. .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 d96a4f1e1..f6a01e142 100644 --- a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 +++ b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 @@ -35,8 +35,8 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, .SH DESCRIPTION No function since pipelining was removed in 7.62.0. -Pass a long with a \fBsize\fP in bytes. If a pipelined connection is currently -processing a request with a Content-Length larger than this +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_MAX_PIPELINE_LENGTH(3)\fP. diff --git a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 index 725f98b2b..7d06b96ac 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 +++ b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 @@ -38,8 +38,7 @@ 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 honoured based on other system resources -properties. +value passed here would be honored based on other system resources properties. .SH DEFAULT 100 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 index 2bb83443f..e399f61f7 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 +++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 @@ -36,8 +36,8 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_PIPELINE_LENGTH, 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 -outstanding requests in an HTTP/1.1 pipelined connection. This option is only -used for HTTP/1.1 pipelining, not for HTTP/2 multiplexing. +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 host (see \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP), or queue the request until diff --git a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 index 68898745d..fa2d966f7 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 +++ b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 @@ -49,9 +49,9 @@ pushes will be denied automatically. The callback gets its arguments like this: \fIparent\fP is the handle of the stream on which this push arrives. The new -handle has been duphandle()d from the parent, meaning that it has gotten all -its options inherited. It is then up to the application to alter any options -if desired. +handle has been duplicated from the parent, meaning that it has gotten all its +options inherited. It is then up to the application to alter any options if +desired. \fIeasy\fP is a newly created handle that represents this upcoming transfer. @@ -73,8 +73,8 @@ functions. These functions can only be used from within this callback and they can only access the PUSH_PROMISE headers. The normal response headers will be passed to the header callback for pushed streams just as for normal streams. .IP curl_pushheader_bynum -Returns the header at index 'num' (or NULL). The returned pointer points to a -"name:value" string that will be freed when this callback returns. +Returns the header at index \fInum\fP (or NULL). The returned pointer points +to a "name:value" string that will be freed when this callback returns. .IP curl_pushheader_byname Returns the value for the given header name (or NULL). This is a shortcut so that the application does not have to loop through all headers to find the one diff --git a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 index 2f7ee960f..7f3e2ea7e 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 +++ b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 @@ -51,9 +51,7 @@ non-compressed, \fIdeflate\fP which requests the server to compress its response using the zlib algorithm, \fIgzip\fP which requests the gzip algorithm, (since curl 7.57.0) \fIbr\fP which is brotli and (since curl 7.72.0) \fIzstd\fP which is zstd. Provide them in the string as a -comma-separated list of accepted encodings, like: - - "br, gzip, deflate". +comma-separated list of accepted encodings, like: \fB"br, gzip, deflate"\fP. Set \fICURLOPT_ACCEPT_ENCODING(3)\fP to NULL to explicitly disable it, which makes libcurl not send an Accept-Encoding: header and not decompress received diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC.3 b/docs/libcurl/opts/CURLOPT_ALTSVC.3 index 38c2bab25..e2ada903b 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC.3 +++ b/docs/libcurl/opts/CURLOPT_ALTSVC.3 @@ -57,7 +57,7 @@ nine space-separated fields. An example line could look like - h2 www.example 8443 h3 quic.example 443 "20190808 06:18:37" 1 0 + h2 www.example 8443 h3 second.example 443 "20190808 06:18:37" 1 0 The fields of that line are: @@ -69,7 +69,7 @@ Host name for the source origin Port number for the source origin .IP h3 ALPN id for the destination host -.IP quic.example +.IP second.example Host name for the destination host .IP 443 Port number for the destination host diff --git a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 index 8dea3274d..415f86e96 100644 --- a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 +++ b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 @@ -35,8 +35,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); Provides AWS V4 signature authentication on HTTP(S) header. .PP Pass a char * that is the collection of specific arguments are used for -creating outgoing authentication headers. -The format of the param option is: +creating outgoing authentication headers. The format of the \fIparam\fP +option is: .IP provider1[:provider2[:region[:service]]] .IP provider1,\ provider2 The providers arguments are used for generating some authentication parameters @@ -50,19 +50,19 @@ It is extracted from the host name specified in the URL if omitted. .PP 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 "aws:amz" in parameter. +as calling this with \fB"aws:amz"\fP in parameter. .PP Example with "Test:Try", when curl will do the algorithm, it will generate -"TEST-HMAC-SHA256" for "Algorithm", "x-try-date" and "X-Try-Date" for "date", -"test4_request" for "request type", -"SignedHeaders=content-type;host;x-try-date" for "signed headers" +\fB"TEST-HMAC-SHA256"\đP 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 .SH DEFAULT By default, the value of this parameter is NULL. Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same -as calling this with "aws:amz" in parameter. +as calling this with \fB"aws:amz"\fP in parameter. .SH PROTOCOLS HTTP .SH EXAMPLE @@ -92,8 +92,8 @@ Added in 7.75.0 .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH NOTES -This option overrides the other auth types you might have set in CURL_HTTPAUTH -which should be highlighted as this makes this auth method special. -This method cannot be combined with other auth types. +This option overrides the other auth types you might have set in +\fICURLOPT_HTTPAUTH(3)\fP which should be highlighted as this makes this auth +method special. This method cannot be combined with other auth types. .SH "SEE ALSO" .BR CURLOPT_HEADEROPT "(3), " CURLOPT_HTTPHEADER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.3 b/docs/libcurl/opts/CURLOPT_CAINFO.3 index 39c443b51..ff4f3647d 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO.3 +++ b/docs/libcurl/opts/CURLOPT_CAINFO.3 @@ -39,8 +39,8 @@ If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the server's certificate, \fICURLOPT_CAINFO(3)\fP need not even indicate an accessible file. -This option is by default set to the system path where libcurl's cacert bundle -is assumed to be stored, as established at build time. +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. If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module (libnsspem.so) needs to be available for this option to work properly. diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.3 b/docs/libcurl/opts/CURLOPT_CAPATH.3 index 4842629e1..565c02f38 100644 --- a/docs/libcurl/opts/CURLOPT_CAPATH.3 +++ b/docs/libcurl/opts/CURLOPT_CAPATH.3 @@ -34,12 +34,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAPATH, char *capath); .SH DESCRIPTION Pass a char * to a null-terminated string naming a directory holding multiple CA certificates to verify the peer with. If libcurl is built against OpenSSL, -the certificate directory must be prepared using the openssl c_rehash utility. +the certificate directory must be prepared using the OpenSSL c_rehash utility. This makes sense only when used in combination with the \fICURLOPT_SSL_VERIFYPEER(3)\fP option. The \fICURLOPT_CAPATH(3)\fP function apparently does not work in Windows due -to some limitation in openssl. +to some limitation in OpenSSL. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 index 85fbfa2cb..fd0ed1d79 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_CHUNK_BGN_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CHUNK_BGN_FUNCTION \- callback before a transfer with FTP wildcardmatch +CURLOPT_CHUNK_BGN_FUNCTION \- callback before a transfer with FTP wildcard match .SH SYNOPSIS .nf #include <curl/curl.h> @@ -68,14 +68,14 @@ 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 struct curl_fileinfo with -details about the file that is about to get transferred. +The \fItransfer_info\fP pointer will point 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. The target of transfer_info parameter is a "feature depended" structure. For -the FTP wildcard download, the target is curl_fileinfo structure (see +the FTP wildcard download, the target is \fBcurl_fileinfo\fP structure (see \fIcurl/curl.h\fP). The parameter \fIptr\fP is a pointer given by \fICURLOPT_CHUNK_DATA(3)\fP. The parameter remains contains number of chunks remaining per the transfer. If the feature is not available, the parameter has diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 index 90afbc84c..813554ea9 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_CHUNK_END_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CHUNK_END_FUNCTION \- callback after a transfer with FTP wildcardmatch +CURLOPT_CHUNK_END_FUNCTION \- callback after a transfer with FTP wildcard match .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 index 55cf10249..1c6a921fd 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 @@ -38,7 +38,7 @@ 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 -CURL_VERSION_CONV feature bit set if this option is provided. +\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. The amount of data to convert is indicated by the \fIlength\fP parameter. The @@ -54,10 +54,10 @@ 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. +return the \fBCURLE_CONV_REQD\fP error code. -If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. -For example: +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" diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 index 6f018d61e..d6615352b 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 @@ -80,9 +80,8 @@ if(curl) { } .fi .SH "Cookie file format" -The cookie file format and general cookie concepts in curl are described in -the HTTP-COOKIES.md file, also hosted online here: -https://curl.se/docs/http-cookies.html +The cookie file format and general cookie concepts in curl are described +online here: https://curl.se/docs/http-cookies.html .SH AVAILABILITY As long as HTTP is supported .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 b/docs/libcurl/opts/CURLOPT_COOKIELIST.3 index 27502a308..572da56ce 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.3 @@ -107,17 +107,16 @@ curl_easy_perform(curl); /* cookies imported from cookies.txt */ curl_easy_cleanup(curl); /* cookies exported to cookies.txt */ .fi .SH "Cookie file format" -The cookie file format and general cookie concepts in curl are described in -the HTTP-COOKIES.md file, also hosted online here: -https://curl.se/docs/http-cookies.html +The cookie file format and general cookie concepts in curl are described +online here: https://curl.se/docs/http-cookies.html .SH AVAILABILITY -ALL was added in 7.14.1 +\fBALL\fP was added in 7.14.1 -SESS was added in 7.15.4 +\fBSESS\fP was added in 7.15.4 -FLUSH was added in 7.17.1 +\fBFLUSH\fP was added in 7.17.1 -RELOAD was added in 7.39.0 +\fFRELOAD\fP was added in 7.39.0 .SH RETURN VALUE Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_CURLU.3 b/docs/libcurl/opts/CURLOPT_CURLU.3 index 6e96fcd8c..f4dfa9d60 100644 --- a/docs/libcurl/opts/CURLOPT_CURLU.3 +++ b/docs/libcurl/opts/CURLOPT_CURLU.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_CURLU 3 "28 Oct 2018" "libcurl 7.63.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CURLU \- URL in CURLU * format +CURLOPT_CURLU \- URL in URL handle format .SH SYNOPSIS .nf #include <curl/curl.h> @@ -33,7 +33,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CURLU, void *pointer); .fi .SH DESCRIPTION Pass in a pointer to the \fIURL\fP to work with. The parameter should be a -CURLU *. Setting \fICURLOPT_CURLU(3)\fP will explicitly override +\fICURLU *\fP. Setting \fICURLOPT_CURLU(3)\fP will explicitly override \fICURLOPT_URL(3)\fP. \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a diff --git a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 index 065c408b6..0a1b19464 100644 --- a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 +++ b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 @@ -74,16 +74,16 @@ 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 -DELE and NOOP for example. +\fBDELE\fP and \fBNOOP\fP for example. .IP SMTP -Instead of a HELP or VRFY when issuing SMTP based requests. +Instead of a \fBHELP\fP or \fBVRFY\fP when issuing SMTP based requests. For example: -Normally a multiline response is returned which can be used, in conjunction +Normally a multi line response is returned which can be used, in conjunction with \fICURLOPT_MAIL_RCPT(3)\fP, to specify an EXPN request. If the \fICURLOPT_NOBODY(3)\fP option is specified then the request can be used to -issue NOOP and RSET commands. +issue \fBNOOP\fP and \fBRSET\fP commands. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 index 6afe1da03..d7442d4cd 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 @@ -61,7 +61,7 @@ NOT be null-terminated, but will be exactly of the \fIsize\fP as told by the The \fIuserptr\fP argument is the pointer set with \fICURLOPT_DEBUGDATA(3)\fP. -Available curl_infotype values: +Available \fBcurl_infotype\fP values: .IP CURLINFO_TEXT The data is informational text. .IP CURLINFO_HEADER_IN diff --git a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 index d0d26bdfd..5c69aefd3 100644 --- a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 +++ b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 @@ -43,11 +43,11 @@ dict, file, ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps, pop3, 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 schemeless URL. Parsing -happens when \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP is -called. The protocols supported by libcurl will 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. +\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 +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. This option does not change the default proxy protocol (http). diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 index 4aa4653c0..c59ab6399 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 @@ -48,7 +48,8 @@ Subject Alternate Name field in the certificate matches the host name in the DoH URL to which you told Curl to connect. When the \fIverify\fP value is set to 1L it is treated the same as 2L. However -for consistency with the other VERIFYHOST options we suggest use 2 and not 1. +for consistency with the other \fIVERIFYHOST\fP options we suggest use 2 and +not 1. When the \fIverify\fP value is set to 0L, the connection succeeds regardless of the names used in the certificate. Use that ability with caution! diff --git a/docs/libcurl/opts/CURLOPT_FTPPORT.3 b/docs/libcurl/opts/CURLOPT_FTPPORT.3 index b81527d24..c4d73d790 100644 --- a/docs/libcurl/opts/CURLOPT_FTPPORT.3 +++ b/docs/libcurl/opts/CURLOPT_FTPPORT.3 @@ -47,8 +47,8 @@ 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 handle. Invalid port/range settings are ignored. IPv6 addresses followed by -a port or portrange have to be in brackets. IPv6 addresses without port/range -specifier can be in brackets. +a port or port range have to be in brackets. IPv6 addresses without +port/range specifier can be in brackets. Examples with specified ports: diff --git a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 index 3e6c96098..2fbe06001 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_FTP_CREATE_MISSING_DIRS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" .SH NAME -CURLOPT_FTP_CREATE_MISSING_DIRS \- create missing dirs for FTP and SFTP +CURLOPT_FTP_CREATE_MISSING_DIRS \- create missing directories for FTP and SFTP .SH SYNOPSIS .nf #include <curl/curl.h> @@ -51,11 +51,11 @@ 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 MKD command fails. This is +retry the CWD command again if the subsequent \fBMKD\fP command fails. This is especially useful if you are doing many simultaneous connections against the same server and they all have this option enabled, as then CWD may first fail -but then another connection does MKD before this connection and thus MKD fails -but trying CWD works! +but then another connection does \fBMKD\fP before this connection and thus +\fBMKD\fP fails but trying CWD works! .SH DEFAULT CURLFTP_CREATE_DIR_NONE (0) .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 index a4ffa4e6e..4cf7a513c 100644 --- a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 +++ b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 @@ -37,7 +37,7 @@ allow unconditional GSSAPI credential delegation. The delegation is disabled by default since 7.21.7. Set the parameter to \fBCURLGSSAPI_DELEGATION_POLICY_FLAG\fP to delegate only if the OK-AS-DELEGATE flag is set in the service ticket in case this feature is supported by the -GSS-API implementation and the definition of GSS_C_DELEG_POLICY_FLAG was +GSS-API implementation and the definition of \fIGSS_C_DELEG_POLICY_FLAG\fP was available at compile-time. .SH DEFAULT CURLGSSAPI_DELEGATION_NONE diff --git a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 index b2abceb52..932b0311b 100644 --- a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 +++ b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS 3 "1 Feb 2018" "libcurl 7.59.0" "curl_easy_setopt options" .SH NAME -CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS \- head start for ipv6 for happy eyeballs +CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS \- head start for IPv6 for happy eyeballs .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_HSTS.3 b/docs/libcurl/opts/CURLOPT_HSTS.3 index f44f40515..559435399 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS.3 +++ b/docs/libcurl/opts/CURLOPT_HSTS.3 @@ -50,8 +50,8 @@ physical line. Each line in the file has the following format: [host] [stamp] [host] is the domain name for the entry and the name is dot-prefixed if it is -a includeSubDomain entry (if the entry is valid for all subdmains to the name -as well or only for the exact name). +an entry valid for all subdomains to the name as well or only for the exact +name. [stamp] is the time (in UTC) when the entry expires and it uses the format \&"YYYYMMDD HH:MM:SS". diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 index 2026124af..e27d31cda 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 @@ -50,10 +50,10 @@ Set the \fIuserp\fP argument with the \fICURLOPT_HSTSREADDATA(3)\fP option or it will be NULL. When this callback is invoked, the \fIsts\fP pointer points to a populated -struct: Copy the host name to 'name' (no longer than 'namelen' bytes). Make it -null-terminated. Set 'includeSubDomains' to TRUE or FALSE. Set 'expire' to a -date stamp or a zero length string for *forever* (wrong date stamp format -might cause the name to not get accepted) +struct: Copy the host name to \fIname\fP (no longer than \fInamelen\fP +bytes). Make it null-terminated. Set \fIincludeSubDomains\fP to TRUE or +FALSE. Set \fIexpire\fP to a date stamp or a zero length string for *forever* +(wrong date stamp format might cause the name to not get accepted) 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 diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 index 6f05e4810..e4e4c30cc 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 @@ -34,7 +34,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEDATA, void *pointer); .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 -input in the 4th argument to the callback. +input in the fourth argument to the callback. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to do that. diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 index 5d7a8c4e8..373f3e5ab 100644 --- a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 @@ -57,10 +57,10 @@ Set the \fIuserp\fP argument with the \fICURLOPT_HSTSWRITEDATA(3)\fP option or it will be NULL. When the callback is invoked, the \fIsts\fP pointer points to a populated -struct: Read the host name to 'name' (it is 'namelen' bytes long and null -terminated. The 'includeSubDomains' field is non-zero if the entry matches -subdomains. The 'expire' string is a date stamp null-terminated string using -the syntax YYYYMMDD HH:MM:SS. +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 +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 diff --git a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 b/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 index 1984870d2..3477b025e 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 @@ -78,11 +78,11 @@ option to work, or build libcurl on Windows with SSPI support. .IP CURLAUTH_NTLM_WB 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 /usr/bin/ntlm_auth +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 waitpid() to await its exit when done. On POSIX -operating systems, killing the process will cause a SIGCHLD signal to be +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 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 @@ -98,7 +98,7 @@ libcurl pick any it finds suitable. libcurl will automatically select 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 un-restricted auth and if not, only that +value to force libcurl to probe for unrestricted auth and if not, only that single auth algorithm is acceptable. .IP CURLAUTH_AWS_SIGV4 provides AWS V4 signature authentication on HTTPS header diff --git a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 index 933609f38..c6cf055e1 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 @@ -45,8 +45,7 @@ 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 'MyHeader;' (note the ending -semicolon). +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 diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 index 4be131683..d9a705336 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 @@ -32,10 +32,10 @@ CURLOPT_HTTPPOST \- multipart formpost content CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPOST, struct curl_httppost *formpost); .SH DESCRIPTION -Tells libcurl you want a multipart/formdata HTTP POST to be made and you +Tells libcurl you want a \fBmultipart/formdata\fP HTTP POST to be made and you instruct what data to pass on to the server in the \fIformpost\fP argument. -Pass a pointer to a linked list of curl_httppost structs as parameter. The -easiest way to create such a list, is to use \fIcurl_formadd(3)\fP as +Pass a pointer to a linked list of \fIcurl_httppost\fP structs as parameter. +The easiest way to create such a list, is to use \fIcurl_formadd(3)\fP as documented. The data in this list must remain intact as long as the curl transfer is alive and is using it. diff --git a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 index 403acfb74..8e4dc8358 100644 --- a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 @@ -36,7 +36,7 @@ Pass a char * as parameter, which should be pointing to the null-terminated \fIoptions\fP string to use for the transfer. For more information about the login options please see RFC2384, RFC5092 and -IETF draft draft-earhart-url-smtp-00.txt +the IETF draft \fBdraft-earhart-url-smtp-00.txt\fP. \fICURLOPT_LOGIN_OPTIONS(3)\fP can be used to set protocol specific login options, such as the preferred authentication mechanism via "AUTH=NTLM" or diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 index 98df48af6..950dd4b5b 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 @@ -43,12 +43,13 @@ 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. -When performing an address verification (VRFY command), each recipient should -be specified as the user name or user name and domain (as per Section 3.5 of -RFC5321). +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 +3.5 of RFC5321). -When performing a mailing list expand (EXPN command), each recipient should be -specified using the mailing list name, such as "Friends" or "London-Office". +When performing a mailing list expand (\fBEXPN\fP command), each recipient +should be specified using the mailing list name, such as "Friends" or +"London-Office". .SH DEFAULT NULL .SH PROTOCOLS @@ -68,7 +69,7 @@ if(curl) { } .fi .SH AVAILABILITY -Added in 7.20.0. The VRFY and EXPN logic was added in 7.34.0 +Added in 7.20.0. The \fBVRFY\fP and \fBEXPN\fP logic was added in 7.34.0 .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_MAXAGE_CONN.3 b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 index d44384525..01c7f8a74 100644 --- a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 +++ b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 @@ -29,10 +29,10 @@ CURLOPT_MAXAGE_CONN \- max idle time allowed for reusing a connection .nf #include <curl/curl.h> -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXAGE_CONN, long maxage); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXAGE_CONN, long age); .fi .SH DESCRIPTION -Pass a long as parameter containing \fImaxage\fP - the maximum time in seconds +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 reuse for this request. @@ -42,10 +42,9 @@ 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 \fImaxage\fP, it will instead be -closed. +in the cache that is older than this set \fIage\fP, it will instead be closed. .SH DEFAULT -Default maxage is 118 seconds. +Default maximum age is set to 118 seconds. .SH PROTOCOLS All .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_NETRC.3 b/docs/libcurl/opts/CURLOPT_NETRC.3 index 883bccd7f..d1b7880b0 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC.3 +++ b/docs/libcurl/opts/CURLOPT_NETRC.3 @@ -74,7 +74,7 @@ Each field is provided as a sequence of letters that ends with a space or newline. Starting in 7.84.0, libcurl also supports quoted strings. They start and end with double quotes and support the escaped special letters \\\", \\n, \\r, and \\t. Quoted strings are the only way a space character can be used in -a user namd or password. +a user name or password. .IP "machine <name>" Provides credentials for a host called \fBname\fP. libcurl searches the .netrc diff --git a/docs/libcurl/opts/CURLOPT_NOBODY.3 b/docs/libcurl/opts/CURLOPT_NOBODY.3 index 6805a3781..a87cf44df 100644 --- a/docs/libcurl/opts/CURLOPT_NOBODY.3 +++ b/docs/libcurl/opts/CURLOPT_NOBODY.3 @@ -37,7 +37,7 @@ output when doing what would otherwise be a download. For HTTP(S), this makes 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, unsetting the +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 \fICURLOPT_HTTPGET(3)\fP and for other methods, use the POST or UPLOAD diff --git a/docs/libcurl/opts/CURLOPT_NOPROXY.3 b/docs/libcurl/opts/CURLOPT_NOPROXY.3 index a006ae42a..da336014f 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROXY.3 +++ b/docs/libcurl/opts/CURLOPT_NOPROXY.3 @@ -37,16 +37,16 @@ separated list of host names that do not require a proxy to get reached, even if one is specified. The only wildcard available is a single * character, which matches all hosts, and effectively disables the proxy. Each name in this list is matched as either a domain which contains the hostname, or the -hostname itself. For example, example.com would match example.com, -example.com:80, and www.example.com, but not www.notanexample.com or -example.com.othertld. +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. -If the name in the noproxy list has a leading period, it is a domain match -against the provided host name. This way ".example.com" will switch off proxy -use for both "www.example.com" as well as for "foo.example.com". +If the name in the \fInoproxy\fP list has a leading period, it is a domain +match against the provided host name. This way ".example.com" will switch off +proxy use for both "www.example.com" as well as for "foo.example.com". -Setting the noproxy 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) will explicitly +enable 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: diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 index fb95c1e15..416b2d758 100644 --- a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 +++ b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 @@ -46,10 +46,10 @@ 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 send data to a socket which is closed in the other end. libcurl makes an -effort to never cause such SIGPIPEs to trigger, but some operating systems -have no way to avoid them and even on those that have there are some corner -cases when they may still happen, contrary to our desire. In addition, using -\fICURLAUTH_NTLM_WB\fP authentication could cause a SIGCHLD signal to be +effort to never cause such SIGPIPE signals to trigger, but some operating +systems have no way to avoid them and even on those that have there are some +corner cases when they may still happen, contrary to our desire. In addition, +using \fICURLAUTH_NTLM_WB\fP authentication could cause a SIGCHLD signal to be raised. .SH DEFAULT 0 diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 index 74266600a..f72c3188f 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 @@ -33,7 +33,8 @@ 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 -argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION(3)\fP. +argument in the open socket callback set with +\fICURLOPT_OPENSOCKETFUNCTION(3)\fP. .SH DEFAULT The default value of this parameter is NULL. .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 index e5bf58116..40279021a 100644 --- a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 @@ -106,21 +106,21 @@ PEM/DER support: 7.43.0: NSS and wolfSSL - 7.47.0: mbedtls + 7.47.0: mbedTLS - 7.54.1: SecureTransport on macOS 10.7+/iOS 10+ + 7.54.1: Secure Transport on macOS 10.7+/iOS 10+ - 7.58.1: SChannel + 7.58.1: Schannel sha256 support: 7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL - 7.47.0: mbedtls + 7.47.0: mbedTLS - 7.54.1: SecureTransport on macOS 10.7+/iOS 10+ + 7.54.1: Secure Transport on macOS 10.7+/iOS 10+ - 7.58.1: SChannel Windows XP SP3+ + 7.58.1: Schannel Windows XP SP3+ Other SSL backends not supported. .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 index 459b40d7c..518aa3084 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 @@ -35,19 +35,21 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata); 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. +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 POST is a normal application/x-www-form-urlencoded 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 \fICURLOPT_HTTPHEADER(3)\fP. +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 +\fICURLOPT_HTTPHEADER(3)\fP. -You can use \fIcurl_easy_escape(3)\fP to url-encode your data, if necessary. It -returns a pointer to an encoded string that can be passed as \fIpostdata\fP. +You can use \fIcurl_easy_escape(3)\fP to URL encode your data, if +necessary. It returns a pointer to an encoded string that can be passed as +\fIpostdata\fP. Using \fICURLOPT_POSTFIELDS(3)\fP implies setting \fICURLOPT_POST(3)\fP to 1. @@ -58,7 +60,7 @@ the POST data from the read callback. If you want to send a zero-byte POST set 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 nul +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, @@ -66,8 +68,8 @@ 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 header with \fICURLOPT_HTTPHEADER(3)\fP as usual. -To make multipart/formdata posts (aka RFC2388-posts), check out the -\fICURLOPT_HTTPPOST(3)\fP option combined with \fIcurl_formadd(3)\fP. +To make \fBmultipart/formdata\fP posts, check out the +\fICURLOPT_HTTPPOST(3)\fP option combined with \fIcurl_mime_init(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 index ba345c7d3..050d64742 100644 --- a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 @@ -69,10 +69,10 @@ connection. IPv6 addresses are represented without surrounding brackets. .IP conn_primary_port The primary port number on the remote server established with this connection. For FTP, this is the port for the control connection. This can be a TCP or a -UDP port number dependending on the protocol. +UDP port number depending on the protocol. .IP conn_local_port The originating port number for this connection. This can be a TCP or a UDP -port number dependending on the protocol. +port number depending on the protocol. .IP clientp The pointer you set with \fICURLOPT_PREREQDATA(3)\fP. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 b/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 index 2f0bac3f3..894b3c181 100644 --- a/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 +++ b/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 @@ -69,7 +69,7 @@ All except file://. Note that some protocols do not work well over proxy. CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt"); - curl_easy_setopt(curl, CURLOPT_PREPROXY, "socks4://socks-proxy:1080"); + curl_easy_setopt(curl, CURLOPT_PRE_PROXY, "socks4://socks-proxy:1080"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); curl_easy_perform(curl); } diff --git a/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 b/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 index b87c92184..84b5ea1f7 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 @@ -40,8 +40,8 @@ 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. -The bitmask can be constructed by or'ing together the bits fully listed and -described in the \fICURLOPT_HTTPAUTH(3)\fP man page. +The bitmask can be constructed by the bits listed and described in the +\fICURLOPT_HTTPAUTH(3)\fP man page. .SH DEFAULT CURLAUTH_BASIC .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 b/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 index 1d13a73dc..537f01aad 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 @@ -41,7 +41,7 @@ HTTP Proxy. Default. HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS) .IP CURLPROXY_HTTP_1_0 HTTP 1.0 Proxy. This is similar to CURLPROXY_HTTP except it uses HTTP/1.0 for -any CONNECT tunnelling. It does not change the HTTP version of the actual HTTP +any CONNECT tunneling. It does not change the HTTP version of the actual HTTP requests, controlled by \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURLPROXY_SOCKS4 SOCKS4 Proxy. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 index 28b54e11c..07b9a665a 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 @@ -41,8 +41,8 @@ If \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the server's certificate, \fICURLOPT_PROXY_CAINFO(3)\fP need not even indicate an accessible file. -This option is by default set to the system path where libcurl's cacert bundle -is assumed to be stored, as established at build time. +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. If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module (libnsspem.so) needs to be available for this option to work properly. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 index 25d889c00..90ebe2307 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 @@ -34,9 +34,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAPATH, char *capath); .SH DESCRIPTION Pass a char * to a null-terminated string naming a directory holding multiple CA certificates to verify the HTTPS proxy with. If libcurl is built against -OpenSSL, the certificate directory must be prepared using the openssl c_rehash -utility. This makes sense only when \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is -enabled (which it is by default). +OpenSSL, the certificate directory must be prepared using the OpenSSL +\fBc_rehash\fP utility. This makes sense only when +\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is enabled (which it is by default). 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 a81f82bb3..8a319e65a 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 @@ -98,11 +98,11 @@ footer: .SH AVAILABILITY PEM/DER support: - 7.52.0: GSKit, GnuTLS, NSS, OpenSSL, mbedtls, wolfSSL + 7.52.0: GSKit, GnuTLS, NSS, OpenSSL, mbedTLS, wolfSSL sha256 support: - 7.52.0: GnuTLS, NSS, OpenSSL, mbedtls, wolfSSL + 7.52.0: GnuTLS, NSS, OpenSSL, mbedTLS, wolfSSL Other SSL backends not supported. .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 index 86de34c1a..db9f838bc 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 @@ -34,8 +34,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SERVICE_NAME, .fi .SH DESCRIPTION Pass a char * as parameter to a string holding the \fIname\fP of the -service. The default service name is "HTTP" for HTTP based proxies and "rcmd" -for SOCKS5. This option allows you to change it. +service. The default service name is \fB"HTTP"\fP for HTTP based proxies and +\fB"rcmd"\fP for SOCKS5. This option allows you to change it. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 index 5e462385f..670f1147d 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_PROXY_SSLKEY 3 "16 Nov 2016" "libcurl 7.52.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_SSLKEY \- private keyfile for HTTPS proxy client cert +CURLOPT_PROXY_SSLKEY \- private key file for HTTPS proxy client cert .SH SYNOPSIS .nf #include <curl/curl.h> @@ -38,8 +38,8 @@ default format is "PEM" and can be changed with \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP. (Windows, iOS and Mac OS X) This option is ignored by Secure Transport and -Schannel SSL backends because they expect the private key to be already present -in the keychain or PKCS#12 file containing the certificate. +Schannel SSL backends because they expect the private key to be already +present in the key chain or PKCS#12 file containing the certificate. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_QUOTE.3 b/docs/libcurl/opts/CURLOPT_QUOTE.3 index 99d27cc7f..01bd56c9d 100644 --- a/docs/libcurl/opts/CURLOPT_QUOTE.3 +++ b/docs/libcurl/opts/CURLOPT_QUOTE.3 @@ -71,8 +71,8 @@ The chown command sets the owner of the file named by the file operand to the user ID specified by the user operand. The user operand is a decimal integer user ID. .IP "ln source_file target_file" -The ln and symlink commands create a symbolic link at the target_file location -pointing to the source_file location. +The \fBln\fP and \fBsymlink\fP commands create a symbolic link at the +target_file location pointing to the source_file location. .IP "mkdir directory_name" The mkdir command creates the directory named by the directory_name operand. .IP "mtime date file" @@ -80,7 +80,8 @@ The mtime command sets the last modification time of the file named by the file operand. The <date expression> can be all sorts of date strings, see the \fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) .IP "pwd" -The pwd command returns the absolute pathname of the current working directory. +The \fBpwd\fP command returns the absolute path of the current working +directory. .IP "rename source target" The rename command renames the file or directory named by the source operand to the destination path named by the target operand. diff --git a/docs/libcurl/opts/CURLOPT_RANGE.3 b/docs/libcurl/opts/CURLOPT_RANGE.3 index 504efc7a1..067f0e61b 100644 --- a/docs/libcurl/opts/CURLOPT_RANGE.3 +++ b/docs/libcurl/opts/CURLOPT_RANGE.3 @@ -45,7 +45,7 @@ for a request, you may end up getting the full response sent back. For RTSP, the formatting of a range should follow RFC2326 Section 12.29. For RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should be given in -npt, utc, or smpte formats. +\fBnpt\fP, \fButc\fP, or \fBsmpte\fP formats. For HTTP PUT uploads this option should not be used, since it may conflict with other options. diff --git a/docs/libcurl/opts/CURLOPT_READDATA.3 b/docs/libcurl/opts/CURLOPT_READDATA.3 index 79a804b56..70f1b095e 100644 --- a/docs/libcurl/opts/CURLOPT_READDATA.3 +++ b/docs/libcurl/opts/CURLOPT_READDATA.3 @@ -34,7 +34,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READDATA, void *pointer); .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 4th argument to the callback. +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 *'). diff --git a/docs/libcurl/opts/CURLOPT_RESOLVE.3 b/docs/libcurl/opts/CURLOPT_RESOLVE.3 index cf1595dc9..08baa4a30 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVE.3 +++ b/docs/libcurl/opts/CURLOPT_RESOLVE.3 @@ -46,7 +46,7 @@ Each resolve rule to add should be written using the format \&... 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 +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. diff --git a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 index 7dcc1e671..d0d11a936 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 @@ -61,10 +61,11 @@ extract and use 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. 'npt=10-15'). +modify the playback time (e.g. \fInpt=10-15\fP). .IP CURL_RTSPREQ_PAUSE Send a Pause command to the server. Use the \fICURLOPT_RANGE(3)\fP option with -a single value to indicate when the stream should be halted. (e.g. npt='25') +a single value to indicate when the stream should be +halted. (e.g. \fInpt=25\fP) .IP CURL_RTSPREQ_TEARDOWN 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 diff --git a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 index 6d13dddce..106e77e8e 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 +++ b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 @@ -33,17 +33,17 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_AUTHZID, char *authzid); .fi .SH DESCRIPTION Pass a char * as parameter, which should be pointing to the null-terminated -authorization identity (authzid) for the transfer. Only applicable to the PLAIN -SASL authentication mechanism where it is optional. +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 (authcid) as specified by -the username will be sent to the server, along with the password. The server -will derive a authzid from the authcid when not provided, which it will then -uses internally. +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. -When the authzid 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 access to, -or a shared mailbox for example. +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 +access to, or a shared mailbox for example. .SH DEFAULT blank .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_SHARE.3 b/docs/libcurl/opts/CURLOPT_SHARE.3 index 95976b9c7..05a2e4aeb 100644 --- a/docs/libcurl/opts/CURLOPT_SHARE.3 +++ b/docs/libcurl/opts/CURLOPT_SHARE.3 @@ -41,8 +41,8 @@ data. If the curl handles are used simultaneously in multiple threads, you \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 unshare an object -that was using cookies (or change to another object that does not share +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. Data that the share object is not set to share will be dealt with the usual diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 index 44eead944..b313ea055 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_SOCKS5_GSSAPI_NEC 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SOCKS5_GSSAPI_NEC \- socks proxy gssapi negotiation protection +CURLOPT_SOCKS5_GSSAPI_NEC \- SOCKS proxy GSSAPI negotiation protection .SH SYNOPSIS .nf #include <curl/curl.h> @@ -32,7 +32,7 @@ CURLOPT_SOCKS5_GSSAPI_NEC \- socks proxy gssapi negotiation protection CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_NEC, long nec); .fi .SH DESCRIPTION -Pass a long set to 1 to enable or 0 to disable. As part of the gssapi +Pass a long set to 1 to enable or 0 to disable. As part of the GSSAPI negotiation a protection mode is negotiated. The RFC1961 says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. If enabled, this option allows the unprotected exchange of the protection mode diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 index b88581efe..e4a902dac 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 @@ -35,9 +35,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_SERVICE, .SH DESCRIPTION Deprecated since 7.49.0. Use \fICURLOPT_PROXY_SERVICE_NAME(3)\fP instead. -Pass a char * as parameter to a string holding the \fIname\fP of the service. -The default service name for a SOCKS5 server is "rcmd". This option allows you -to change it. +Pass a \fBchar *\fP as parameter to a string holding the \fIname\fP of the +service. The default service name for a SOCKS5 server is \fI"rcmd"\fP. This +option allows you to change it. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 index 563ae577d..592bcc434 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 @@ -41,7 +41,7 @@ CURLSSH_AUTH_HOST has no effect. If CURLSSH_AUTH_AGENT is used, libcurl attempts to connect to ssh-agent or pageant and let the agent attempt the authentication. .SH DEFAULT -CURLSSH_AUTH_ANY (all availables ones) +CURLSSH_AUTH_ANY (all available) .SH PROTOCOLS SFTP and SCP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 index e74573860..f09b00ee2 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYDATA.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_SSH_KEYDATA 3 "4 Nov 2021" "libcurl 7.84.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSH_HOSTKEYDATA \- pointer to pass to the SSH hostkey callback +CURLOPT_SSH_HOSTKEYDATA \- pointer to pass to the SSH host key callback .SH SYNOPSIS .nf #include <curl/curl.h> @@ -42,8 +42,8 @@ SCP and SFTP .nf int hostkeycb(void *clientp, /* passed with CURLOPT_SSH_HOSTKEYDATA */ int keytype, /* CURLKHTYPE */ - const char * key, /*hostkey to check*/ - size_t keylen); /*length of the key*/ + const char * key, /* host key to check */ + size_t keylen); /* length of the key */ { /* 'clientp' points to the callback_data struct */ /* investigate the situation and return the correct value */ diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.3 index 422392e50..7a39b37f9 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_SSH_HOSTKEYFUNCTION 3 "4 Nov 2021" "libcurl 7.84.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSH_HOSTKEYFUNCTION \- callback to check hostkey +CURLOPT_SSH_HOSTKEYFUNCTION \- callback to check host key .SH SYNOPSIS .nf #include <curl/curl.h> @@ -41,20 +41,20 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOSTKEYFUNCTION, Pass a pointer to your callback function, which should match the prototype shown above. It overrides \fICURLOPT_SSH_KNOWNHOSTS(3)\fP. -This callback gets called when the verification of the SSH hostkey is needed. +This callback gets called when the verification of the SSH host key is needed. \fBkey\fP is \fBkeylen\fP bytes long and is the key to check. \fBkeytype\fP -says what type it is, from the \fBCURLKHTYPE_*\fP series in the curl_khtype -enum. +says what type it is, from the \fBCURLKHTYPE_*\fP series in the +\fBcurl_khtype\fP enum. \fBclientp\fP is a custom pointer set with \fICURLOPT_SSH_HOSTKEYDATA(3)\fP. The callback MUST return one of the following return codes to tell libcurl how to act: .IP CURLKHMATCH_OK -The hostkey is accepted, the connection should continue. +The host key is accepted, the connection should continue. .IP CURLKHMATCH_MISMATCH -the hostkey is rejected, the connection is canceled. +the host key is rejected, the connection is canceled. .SH DEFAULT NULL .SH PROTOCOLS @@ -63,8 +63,8 @@ SCP and SFTP .nf int hostkeycb(void *clientp, /* passed with CURLOPT_SSH_HOSTKEYDATA */ int keytype, /* CURLKHTYPE */ - const char * key, /*hostkey to check*/ - size_t keylen); /*length of the key*/ + const char * key, /* host key to check */ + size_t keylen); /* length of the key */ { /* 'clientp' points to the callback_data struct */ /* investigate the situation and return the correct value */ 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 22e158b25..f9bd36d7b 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,7 @@ 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 md5sums match. +libcurl will reject the connection to the host unless the MD5 checksum match. The application does not have to keep the string around after setting this option. @@ -60,3 +60,4 @@ Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. .SH "SEE ALSO" .BR CURLOPT_SSH_PUBLIC_KEYFILE "(3), " CURLOPT_SSH_AUTH_TYPES "(3), " +.BR CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 index 7dc723ce2..f47801dcb 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 @@ -37,7 +37,7 @@ 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 matching public key. Use \fICURLOPT_SSH_KEYFUNCTION(3)\fP to alter the default -behavior on host and key (mis)matching. +behavior on host and key matches and mismatches. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.3 b/docs/libcurl/opts/CURLOPT_SSLCERT.3 index 956129a8b..fd0ee71c4 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT.3 +++ b/docs/libcurl/opts/CURLOPT_SSLCERT.3 @@ -42,17 +42,17 @@ you wish to authenticate with as it is named in the security database. If you want to use a file from the current directory, please precede it with "./" prefix, in order to avoid confusion with a nickname. -(Schannel only) Client certificates can be specified by a path expression to -a certificate store. (You can import PFX to a store first). You can use -"<store location>\\<store name>\\<thumbprint>" to refer to a certificate -in the system certificates store, for example, -"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a". Thumbprint is -usually a SHA-1 hex string which you can see in certificate details. Following -store locations are supported: CurrentUser, LocalMachine, CurrentService, -Services, CurrentUserGroupPolicy, LocalMachineGroupPolicy, -LocalMachineEnterprise. -Schannel also support P12 certificate file, with the string "P12" specified -with \fICURLOPT_SSLCERTTYPE(3)\fP. +(Schannel only) Client certificates can be specified by a path expression to a +certificate store. (You can import \fIPFX\fP to a store first). You can use +"<store location>\\<store name>\\<thumbprint>" to refer to a certificate in +the system certificates store, for example, +\fB"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa"\fP. The thumbprint is usually a +SHA-1 hex string which you can see in certificate details. Following store +locations are supported: \fBCurrentUser\fP, \fBLocalMachine\fP, +\fBCurrentService\fP, \fBServices\fP, \fBCurrentUserGroupPolicy\fP, +\fBLocalMachineGroupPolicy\fP, \fBLocalMachineEnterprise\fP. Schannel also +support P12 certificate file, with the string "P12" specified with +\fICURLOPT_SSLCERTTYPE(3)\fP. When using a client certificate, you most likely also need to provide a private key with \fICURLOPT_SSLKEY(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY.3 b/docs/libcurl/opts/CURLOPT_SSLKEY.3 index 91c4c26cd..df6d1c94b 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY.3 +++ b/docs/libcurl/opts/CURLOPT_SSLKEY.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_SSLKEY 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSLKEY \- private keyfile for TLS and SSL client cert +CURLOPT_SSLKEY \- private key file for TLS and SSL client cert .SH SYNOPSIS .nf #include <curl/curl.h> @@ -38,7 +38,7 @@ changed with \fICURLOPT_SSLKEYTYPE(3)\fP. (Windows, iOS and Mac OS X) This option is ignored by Secure Transport and Schannel SSL backends because they expect the private key to be already present -in the keychain or PKCS#12 file containing the certificate. +in the key-chain or PKCS#12 file containing the certificate. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 index f6d6eac2c..dd5d02cbf 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_SSL_CTX_DATA 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSL_CTX_DATA \- pointer passed to ssl_ctx callback +CURLOPT_SSL_CTX_DATA \- pointer passed to SSL context callback .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 index 407dd4b5f..c36882b1f 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 @@ -68,12 +68,12 @@ 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 the CTX 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 recommend before performing your transfer set \fICURLOPT_PRIVATE(3)\fP on -your curl handle so you can identify it in the CTX callback. If you have a -reason to modify DoH SSL context please let us know on the curl-library mailing -list because we are considering removing this capability. +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 +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 +mailing list because we are considering removing this capability. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 index 7bf5d2a15..73421c757 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 +++ b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 @@ -43,8 +43,7 @@ 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. -See section 5.3 of RFC 7540 for protocol details: -https://httpwg.github.io/specs/rfc7540.html#StreamPriority +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 diff --git a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 index da05ed9c6..b8b57fafd 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 @@ -51,8 +51,8 @@ if(curl) { } .fi .SH AVAILABILITY -Added in 7.49.0. This option is currently only supported on Linux and OS X -El Capitan. +Added in 7.49.0. This option is currently only supported on Linux and macOS +10.11 or later. .SH RETURN VALUE Returns CURLE_OK if fast open is supported by the operating system, otherwise returns CURLE_NOT_BUILT_IN. diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 index b6c1d2158..0ba8bad93 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 @@ -32,14 +32,14 @@ CURLOPT_TCP_NODELAY \- the TCP_NODELAY option CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_NODELAY, long nodelay); .fi .SH DESCRIPTION -Pass a long specifying whether the TCP_NODELAY option is to be set or cleared -(1L = set, 0 = clear). The option is set by default. This will have no effect -after the connection has been established. +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 +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 (MSS) for the network). +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_TELNETOPTIONS.3 b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 index f8e17a0c4..6bd449a03 100644 --- a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 @@ -35,8 +35,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TELNETOPTIONS, .SH DESCRIPTION Provide a pointer to a curl_slist with variables to pass to the telnet negotiations. The variables should be in the format <option=value>. libcurl -supports the options 'TTYPE', 'XDISPLOC' and 'NEW_ENV'. See the TELNET -standard for details. +supports the options \fBTTYPE\fP, \fBXDISPLOC\fP and \fBNEW_ENV\fP. See the +TELNET standard for details. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 index 4fe3a616e..6d63e88e4 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 @@ -35,9 +35,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_BLKSIZE, long blocksize); Specify \fIblocksize\fP to use for TFTP data transmission. Valid range as per RFC2348 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 acknowledgement -or returns an option acknowledgement with no blksize, the default of 512 bytes -will be used. +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. .SH DEFAULT 512 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 index c4678726a..43de154c8 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 @@ -33,10 +33,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_NO_OPTIONS, long onoff); .fi .SH DESCRIPTION Set \fIonoff\fP to 1L to exclude all TFTP options defined in RFC2347, RFC2348 -and RFC2349 from read and write requests (RRQs/WRQs). +and RFC2349 from read and write requests. -This option improves interop with some legacy servers that do not acknowledge -or properly implement TFTP options. When this option is used +This option improves interoperability with legacy servers that do not +acknowledge or properly implement TFTP options. When this option is used \fICURLOPT_TFTP_BLKSIZE(3)\fP is ignored. .SH DEFAULT 0 diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 index 5521a1ebb..7d9c93326 100644 --- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 +++ b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 @@ -41,7 +41,7 @@ you will find more details about cipher lists on this URL: https://curl.se/docs/ssl-ciphers.html This option is currently used only when curl is built to use OpenSSL 1.1.1 or -later or SChannel. If you are using a different SSL backend you can try +later or Schannel. If you are using a different SSL backend you can try setting TLS 1.3 cipher suites by using the CURLOPT_SSL_CIPHER_LIST option. The application does not have to keep the string around after setting this @@ -64,7 +64,7 @@ if(curl) { .SH AVAILABILITY Added in 7.61.0 for OpenSSL. Available when built with OpenSSL >= 1.1.1. -Added in 7.85.0 for SChannel. +Added in 7.85.0 for Schannel. .SH RETURN VALUE Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 index efa3e90f6..bba40845f 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 @@ -41,7 +41,8 @@ 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. -You can set the userdata argument with the CURLOPT_TRAILERDATA option. +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 @@ -51,13 +52,12 @@ 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. -If one of the trailing headers is not formatted correctly -(i.e. HeaderName: headerdata) it will be ignored and an info message -will be emitted. +If one of the trailing header fields is not formatted correctly it will be +ignored and an info message will be emitted. -The return value can either be CURL_TRAILERFUNC_OK or CURL_TRAILERFUNC_ABORT -which would respectively instruct libcurl to either continue with sending the -trailers or to abort the request. +The return value can either be \fBCURL_TRAILERFUNC_OK\fP or +\fBCURL_TRAILERFUNC_ABORT\fP which would respectively instruct libcurl to +either continue with sending the trailers or to abort the request. If you set this option to NULL, then the transfer proceeds as usual without any interruptions. diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 index ed7e006d5..a2903c322 100644 --- a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 @@ -51,7 +51,7 @@ is not used for upload, this buffer will not be 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. .SH DEFAULT -64 kB +65536 bytes .SH PROTOCOLS All .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_USE_SSL.3 b/docs/libcurl/opts/CURLOPT_USE_SSL.3 index 1f3e0a823..43aed8cee 100644 --- a/docs/libcurl/opts/CURLOPT_USE_SSL.3 +++ b/docs/libcurl/opts/CURLOPT_USE_SSL.3 @@ -68,7 +68,7 @@ if(curl) { .SH AVAILABILITY Added in 7.11.0. This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants were known as CURLFTPSSL_* -Handled by LDAP since 7.81.0. Fully supported by the openldap backend only. +Handled by LDAP since 7.81.0. Fully supported by the OpenLDAP backend only. .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_WILDCARDMATCH.3 b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 index 5943e624e..9634d671e 100644 --- a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 +++ b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 @@ -34,8 +34,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WILDCARDMATCH, long onoff); .SH DESCRIPTION Set \fIonoff\fP to 1 if you want to transfer multiple files according to a file name pattern. The pattern can be specified as part of the -\fICURLOPT_URL(3)\fP option, using an fnmatch-like pattern (Shell Pattern -Matching) in the last part of URL (file name). +\fICURLOPT_URL(3)\fP option, using an \fBfnmatch\fP-like pattern (Shell +Pattern Matching) in the last part of URL (file name). By default, libcurl uses its internal wildcard matching implementation. You can provide your own matching function by the @@ -44,14 +44,18 @@ can provide your own matching function by the A brief introduction of its syntax follows: .RS .IP "* - ASTERISK" -\&ftp://example.com/some/path/\fB*.txt\fP (for all txt's from the root -directory). Only two asterisks are allowed within the same pattern string. +.nf + ftp://example.com/some/path/*.txt +.fi +for all txt's from the root directory. Only two asterisks are allowed within +the same pattern string. .RE .RS .IP "? - QUESTION MARK" Question mark matches any (exactly one) character. - -\&ftp://example.com/some/path/\fBphoto?.jpeg\fP +.nf + ftp://example.com/some/path/photo?.jpg +.fi .RE .RS .IP "[ - BRACKET EXPRESSION" @@ -65,7 +69,7 @@ right bracket and matches exactly one character. Some examples follow: \fB[^abc]\fP or \fB[!abc]\fP - negation -\fB[[:\fP\fIname\fP\fB:]]\fP class expression. Supported classes are +\fB[[:name:]]\fP class expression. Supported classes are \fBalnum\fP,\fBlower\fP, \fBspace\fP, \fBalpha\fP, \fBdigit\fP, \fBprint\fP, \fBupper\fP, \fBblank\fP, \fBgraph\fP, \fBxdigit\fP. @@ -75,8 +79,9 @@ characters have no special purpose. \fB[\\[\\]\\\\]\fP - escape syntax. Matches '[', ']' or '\e'. Using the rules above, a file name pattern can be constructed: - -\&ftp://example.com/some/path/\fB[a-z[:upper:]\\\\].jpeg\fP +.nf + ftp://example.com/some/path/[a-z[:upper:]\\\\].jpg +.fi .SH PROTOCOLS This feature is only supported for FTP download. .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 index c954e4194..5e718ec30 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 +++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 @@ -33,10 +33,10 @@ 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 4th 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 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. The internal \fICURLOPT_WRITEFUNCTION(3)\fP will write the data to the FILE * given with this option, or to stdout if this option has not been set. diff --git a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.3 index b5c21b64b..bfd59ccd9 100644 --- a/docs/libcurl/opts/CURLOPT_WS_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_WS_OPTIONS.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_WS_OPTIONS 3 "10 Jun 2022" "libcurl 7.85.0" "curl_easy_setopt options" .SH NAME -CURLOPT_WS_OPTIONS \- WebSockets behavior options +CURLOPT_WS_OPTIONS \- WebSocket behavior options .SH SYNOPSIS .nf #include <curl/curl.h> @@ -32,35 +32,31 @@ CURLOPT_WS_OPTIONS \- WebSockets behavior options CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WS_OPTIONS, long bitmask); .fi .SH DESCRIPTION -Pass a long with a bitmask to tell libcurl about specific WebSockets +Pass a long with a bitmask to tell libcurl about specific WebSocket behaviors. -To "detatch" a websockets connection and use the \fIcurl_ws_send(3)\fP and +To detach a WebSocket connection and use the \fIcurl_ws_send(3)\fP and \fIcurl_ws_recv(3)\fP functions after the HTTP upgrade procedure, set the \fICURLOPT_CONNECT_ONLY(3)\fP option to 2L. Available bits in the bitmask .IP "CURLWS_RAW_MODE (1)" -Deliver "raw" websockets traffic to the \fICURLOPT_WRITEFUNCTION(3)\fP +Deliver "raw" WebSocket traffic to the \fICURLOPT_WRITEFUNCTION(3)\fP callback. In raw mode, libcurl does not handle pings or any other frame for the application. -.IP "CURLWS_COMPRESS_MODE (2)" -Negotiate compression for this transfer. (NOT IMPLEMENTED YET) -.IP "CURLWS_PINGOFF_MODE (4)" -Disable automated ping/pong handling. (NOT IMPLEMENTED YET) .SH DEFAULT 0 .SH PROTOCOLS -WebSockets +WebSocket .SH EXAMPLE .nf CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "ws://example.com/"); - /* use the stand alone API */ - curl_easy_setopt(curl, CURLOPT_WS_OPTIONS, CURLWS_ALONE); + /* tell curl we deal with all the WebSocket magic ourselves */ + curl_easy_setopt(curl, CURLOPT_WS_OPTIONS, CURLWS_RAW_MODE); ret = curl_easy_perform(curl); curl_easy_cleanup(curl); } diff --git a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 index 549d9cb28..d5c8badbf 100644 --- a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 +++ b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 @@ -56,7 +56,7 @@ if(curl) { } .fi .SH AVAILABILITY -Added in 7.33.0. Support for OpenLAP added in 7.82.0. +Added in 7.33.0. Support for OpenLDAP added in 7.82.0. .SH RETURN VALUE Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLSHOPT_USERDATA.3 b/docs/libcurl/opts/CURLSHOPT_USERDATA.3 index f5958a901..4c864413f 100644 --- a/docs/libcurl/opts/CURLSHOPT_USERDATA.3 +++ b/docs/libcurl/opts/CURLSHOPT_USERDATA.3 @@ -23,7 +23,7 @@ .\" ************************************************************************** .TH CURLSHOPT_USERDATA 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME -CURLSHOPT_USERDATA - pointer passed to the (un)lock mutex callbacks +CURLSHOPT_USERDATA - pointer passed to the lock and unlock mutex callbacks .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/template.3 b/docs/libcurl/opts/template.3 index 9b4e3ef0c..835454971 100644 --- a/docs/libcurl/opts/template.3 +++ b/docs/libcurl/opts/template.3 @@ -24,7 +24,7 @@ .\" .TH CURLOPT_TEMPLATE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TEMPLATE \- [short desc] +CURLOPT_TEMPLATE \- [short description] .SH SYNOPSIS #include <curl/curl.h> diff --git a/docs/mk-ca-bundle.1 b/docs/mk-ca-bundle.1 index f4ee20d83..98b5ae1c4 100644 --- a/docs/mk-ca-bundle.1 +++ b/docs/mk-ca-bundle.1 @@ -24,33 +24,35 @@ .\" .TH mk-ca-bundle 1 "24 Oct 2016" "version 1.27" "mk-ca-bundle manual" .SH NAME -mk-ca-bundle \- convert mozilla's certdata.txt to PEM format +mk-ca-bundle \- convert Mozilla's certificate bundle to PEM format .SH SYNOPSIS mk-ca-bundle [options] .I [outputfile] .SH DESCRIPTION -The mk-ca-bundle tool downloads the certdata.txt file from Mozilla's source -tree over HTTPS, then parses certdata.txt and extracts certificates into PEM -format. By default, only CA root certificates trusted to issue SSL server -authentication certificates are extracted. These are then processed with the -OpenSSL commandline tool to produce the final ca-bundle file. +The mk-ca-bundle tool downloads the \fIcertdata.txt\fP file from Mozilla's +source tree over HTTPS, then parses \fIcertdata.txt\fP and extracts +certificates into PEM format. By default, only CA root certificates trusted to +issue SSL server authentication certificates are extracted. These are then +processed with the OpenSSL command line tool to produce the final ca-bundle +file. The default \fIoutputfile\fP name is \fBca-bundle.crt\fP. By setting it to '-' (a single dash) you will get the output sent to STDOUT instead of a file. The PEM format this scripts uses for output makes the result readily available -for use by just about all OpenSSL or GnuTLS powered applications, such as -curl, wget and more. +for use by just about all OpenSSL or GnuTLS powered applications, such as curl +and others. .SH OPTIONS The following options are supported: .IP -b backup an existing version of \fIoutputfilename\fP .IP "-d [name]" -specify which Mozilla tree to pull certdata.txt from (or a custom URL). Valid -names are: aurora, beta, central, mozilla, nss, release (default). They are -shortcuts for which source tree to get the cert data from. +specify which Mozilla tree to pull \fIcertdata.txt\fP from (or a custom +URL). Valid names are: aurora, beta, central, Mozilla, nss, release +(default). They are shortcuts for which source tree to get the certificates +data from. .IP -f -force rebuild even if certdata.txt is current (Added in version 1.17) +force rebuild even if \fIcertdata.txt\fP is current (Added in version 1.17) .IP -i print version info about used modules .IP -k @@ -58,33 +60,36 @@ Allow insecure data transfer. By default (since 1.27) this command will fail if the HTTPS transfer fails. This overrides that decision (and opens for man-in-the-middle attacks). .IP -l -print license info about certdata.txt +print license info about \fIcertdata.txt\fP .IP -m (Added in 1.26) Include meta data comments in the output. The meta data is specific information about each certificate that is stored in the original file as comments and using this option will make those comments get passed on to the output file. The meta data is not parsed in any way by mk-ca-bundle. .IP -n -no download of certdata.txt (to use existing) +no download of \fIcertdata.txt\fP (to use existing) .IP "-p [purposes]:[levels]" -list of Mozilla trust purposes and levels for certificates to include in output. -Takes the form of a comma separated list of purposes, a colon, and a comma -separated list of levels. The default is to include all certificates trusted -to issue SSL Server certificates (SERVER_AUTH:TRUSTED_DELEGATOR). +list of Mozilla trust purposes and levels for certificates to include in +output. Takes the form of a comma separated list of purposes, a colon, and a +comma separated list of levels. The default is to include all certificates +trusted to issue SSL Server certificates +(\fISERVER_AUTH:TRUSTED_DELEGATOR\fP). (Added in version 1.21, Perl only) Valid purposes are: .RS -ALL, DIGITAL_SIGNATURE, NON_REPUDIATION, KEY_ENCIPHERMENT, -DATA_ENCIPHERMENT, KEY_AGREEMENT, KEY_CERT_SIGN, CRL_SIGN, -SERVER_AUTH (default), CLIENT_AUTH, CODE_SIGNING, EMAIL_PROTECTION, -IPSEC_END_SYSTEM, IPSEC_TUNNEL, IPSEC_USER, TIME_STAMPING, STEP_UP_APPROVED +\fIALL\fP, \fIDIGITAL_SIGNATURE\fP, \fINON_REPUDIATION\fP, +\fIKEY_ENCIPHERMENT\fP, \fIDATA_ENCIPHERMENT\fP, \fIKEY_AGREEMENT\fP, +\fIKEY_CERT_SIGN\fP, \fICRL_SIGN\fP, \fISERVER_AUTH\fP (default), +\fICLIENT_AUTH\fP, \fICODE_SIGNING\fP, \fIEMAIL_PROTECTION\fP, +\fIIPSEC_END_SYSTEM\fP, \fIIPSEC_TUNNEL\fP, \fIIPSEC_USER\fP, +\fITIME_STAMPING\fP, \fISTEP_UP_APPROVED\fP .RE .IP Valid trust levels are: .RS -ALL, TRUSTED_DELEGATOR (default), NOT_TRUSTED, MUST_VERIFY_TRUST, TRUSTED +\fIALL\fP, \fITRUSTED_DELEGATOR\fP (default), \fINOT_TRUSTED\fP, \fIMUST_VERIFY_TRUST\fP, \fITRUSTED\fP .RE .IP -q be really quiet (no progress output at all) @@ -101,21 +106,15 @@ Valid algorithms are: ALL, NONE, MD5 (default), SHA1, SHA256, SHA384, SHA512 .RE .IP -u -unlink (remove) certdata.txt after processing +unlink (remove) \fIcertdata.txt\fP after processing .IP -v -be verbose and print out processed CAs +be verbose and print out processed certificate authorities .SH EXIT STATUS Returns 0 on success. Returns 1 if it fails to download data. -.SH CERTDATA FORMAT -The file format used by Mozilla for this trust information seems to be documented here: +.SH FILE FORMAT +The file format used by Mozilla for this trust information is documented here: .nf https://p11-glue.freedesktop.org/doc/storing-trust-policy/storing-trust-existing.html .fi .SH SEE ALSO .BR curl (1) -.SH HISTORY -\fBmk-ca-bundle\fP is a command line tool that is shipped as part of every -curl and libcurl release (see https://curl.se/). It was originally based -on the parse-certs script written by Roland Krikava and was later much -improved by Guenter Knauf. This manual page was initially written by Jan -Schaumann \&<jschauma@netmeister.org>. diff --git a/projects/README.md b/projects/README.md index a578f9aaa..fca9cf43e 100644 --- a/projects/README.md +++ b/projects/README.md @@ -92,10 +92,10 @@ use `VC14.30\curl-all.sln` to build curl and libcurl. ## Running DLL based configurations -If you are a developer and plan to run the curl tool from Visual Studio (eg -you are debugging) with any third-party libraries (such as OpenSSL, wolfSSL or -LibSSH2) then you will need to add the search path of these DLLs to the -configuration's PATH environment. To do that: +If you are a developer and plan to run the curl tool from Visual Studio with +any third-party libraries (such as OpenSSL, wolfSSL or LibSSH2) then you will +need to add the search path of these DLLs to the configuration's PATH +environment. To do that: 1. Open the 'curl-all.sln' or 'curl.sln' solutions 2. Right-click on the 'curl' project and select Properties diff --git a/tests/CI.md b/tests/CI.md index febd1f823..92d57a058 100644 --- a/tests/CI.md +++ b/tests/CI.md @@ -39,15 +39,15 @@ Consider the following table while looking at pull request failures: | LGTM analysis: Python | stable | new findings | | LGTM analysis: C/C++ | stable | new findings | | buildbot/curl_winssl_ ... | stable | all errors and failures | - | continuous-integration/appveyor/pr | stable | all errors and failures | + | AppVeyor | flaky | all errors and failures | | curl.curl (linux ...) | stable | all errors and failures | | curl.curl (windows ...) | flaky | repetitive errors/failures | - | deepcode-ci-bot | stable | new findings | - | musedev | stable | new findings | + | CodeQL | stable | new findings | Sometimes the tests fail due to a dependency service temporarily being offline -or otherwise unavailable, eg. package downloads. In this case you can just -try to update your pull requests to rerun the tests later as described below. +or otherwise unavailable, for example package downloads. In this case you can +just try to update your pull requests to rerun the tests later as described +below. ## CI servers @@ -75,20 +75,20 @@ The following tests are run in Microsoft Azure CI environment: These are all configured in `.azure-pipelines.yml`. -As of November 2021 @bagder and @mback2k are the only people with administrator -access to the Azure CI environment. Additional admins/group members can be added -on request. +As of November 2021 `@bagder` and `@mback2k` are the only people with +administrator access to the Azure CI environment. Additional admins/group +members can be added on request. -### Appveyor +### AppVeyor -Appveyor runs a variety of different Windows builds, with different compilation +AppVeyor runs a variety of different Windows builds, with different compilation options. -As of November 2021 @bagder, @mback2k, @jay, @vszakats, @dfandrich and -@danielgustafsson have administrator access to the Appveyor CI environment. -Additional admins/group members can be added on request. +As of November 2021 `@bagder`, `@mback2k`, `@jay`, `@vszakats`, `@dfandrich` +and `@danielgustafsson` have administrator access to the AppVeyor CI +environment. Additional admins/group members can be added on request. -The tests are configured in appveyor.yml. +The tests are configured in `appveyor.yml`. ### Zuul @@ -105,21 +105,21 @@ do not report results to the Github checks runner - you need to manually check for failures. See [#7522](https://github.com/curl/curl/issues/7522) for more information. -As of November 2021 Daniel Stenberg is the only person with administrator access -to the Zuul CI environment. +As of November 2021 Daniel Stenberg is the only person with administrator +access to the Zuul CI environment. These are configured in `zuul.d` and have test runners in `scripts/zuul`. -### CircleCI +### Circle CI -CircleCI runs a basic Linux test suite on Ubuntu for both x86 and ARM +Circle CI runs a basic Linux test suite on Ubuntu for both x86 and ARM processors. This is configured in `.circleci/config.yml`. -You can [view the full list of CI jobs on CircleCI's +You can [view the full list of CI jobs on Circle CI's website](https://app.circleci.com/pipelines/github/curl/curl). -@bagder has access to edit the "Project Settings" on that page. -Additional admins/group members can be added on request. +`@bagder` has access to edit the "Project Settings" on that page. Additional +admins/group members can be added on request. ### Cirrus CI @@ -129,5 +129,5 @@ Cirrus CI runs a basic test suite on FreeBSD and Windows. This is configured in You can [view the full list of CI jobs on Cirrus CI's website](https://cirrus-ci.com/github/curl/curl). -@bagder has access to edit the "Project Settings" on that page. -Additional admins/group members can be added on request. +`@bagder` has access to edit the "Project Settings" on that page. Additional +admins/group members can be added on request. diff --git a/tests/FILEFORMAT.md b/tests/FILEFORMAT.md index a1d1c12ea..03e6fa171 100644 --- a/tests/FILEFORMAT.md +++ b/tests/FILEFORMAT.md @@ -17,8 +17,8 @@ character entities and the preservation of CR/LF characters at the end of lines are the biggest differences). Each test case source exists as a file matching the format -`tests/data/testNUM`, where NUM is the unique test number, and must begin with -a 'testcase' tag, which encompasses the remainder of the file. +`tests/data/testNUM`, where `NUM` is the unique test number, and must begin +with a `testcase` tag, which encompasses the remainder of the file. # Preprocessing @@ -79,7 +79,7 @@ For example, to insert the word hello a 100 times: Lines in the test file can be made to appear conditionally on a specific feature (see the "features" section below) being set or not set. If the specific feature is present, the following lines will be output, otherwise it -outputs nothing, until a following else or endif clause. Like this: +outputs nothing, until a following else or `endif` clause. Like this: %if brotli Accept-Encoding @@ -120,7 +120,7 @@ Available substitute variables include: - `%FTPSPORT` - Port number of the FTPS server - `%FTPTIME2` - Timeout in seconds that should be just sufficient to receive a response from the test FTP server -- `%FTPTIME3` - Even longer than %FTPTIME2 +- `%FTPTIME3` - Even longer than `%FTPTIME2` - `%GOPHER6PORT` - IPv6 port number of the Gopher server - `%GOPHERPORT` - Port number of the Gopher server - `%GOPHERSPORT` - Port number of the Gophers server @@ -165,8 +165,9 @@ Available substitute variables include: # `<testcase>` -Each test is always specified entirely within the testcase tag. Each test case -is split up in four main sections: `info`, `reply`, `client` and `verify`. +Each test is always specified entirely within the `testcase` tag. Each test +case is split up in four main sections: `info`, `reply`, `client` and +`verify`. - **info** provides information about the test case @@ -225,28 +226,28 @@ and used as "raw" data. should be cut off from the data before sending or comparing it. For FTP file listings, the `<data>` section will be used *only* if you make -sure that there has been a CWD done first to a directory named `test-[num]` -where [num] is the test case number. Otherwise the ftp server can't know from +sure that there has been a CWD done first to a directory named `test-[NUM]` +where `NUM` is the test case number. Otherwise the ftp server can't know from which test file to load the list content. ### `<dataNUM>` -Send back this contents instead of the <data> one. The num is set by: +Send back this contents instead of the <data> one. The `NUM` is set by: - The test number in the request line is >10000 and this is the remainder of [test case number]%10000. - - The request was HTTP and included digest details, which adds 1000 to NUM - - If a HTTP request is NTLM type-1, it adds 1001 to num - - If a HTTP request is NTLM type-3, it adds 1002 to num - - If a HTTP request is Basic and num is already >=1000, it adds 1 to num - - If a HTTP request is Negotiate, num gets incremented by one for each + - The request was HTTP and included digest details, which adds 1000 to `NUM` + - If a HTTP request is NTLM type-1, it adds 1001 to `NUM` + - If a HTTP request is NTLM type-3, it adds 1002 to `NUM` + - If a HTTP request is Basic and `NUM` is already >=1000, it adds 1 to `NUM` + - If a HTTP request is Negotiate, `NUM` gets incremented by one for each request with Negotiate authorization header on the same test case. -Dynamically changing num in this way allows the test harness to be used to +Dynamically changing `NUM` in this way allows the test harness to be used to test authentication negotiation where several different requests must be sent to complete a transfer. The response to each request is found in its own data section. Validating the entire negotiation sequence can be done by specifying -a datacheck section. +a `datacheck` section. ### `<connect>` The connect section is used instead of the 'data' for all CONNECT @@ -265,14 +266,14 @@ Use the `mode="text"` attribute if the output is in text mode on platforms that have a text/binary difference. ### `<datacheckNUM [nonewline="yes"] [mode="text"]>` -The contents of numbered datacheck sections are appended to the non-numbered +The contents of numbered `datacheck` sections are appended to the non-numbered one. ### `<size>` number to return on a ftp SIZE command (set to -1 to make this command fail) ### `<mdtm>` -what to send back if the client sends a (FTP) MDTM command, set to -1 to +what to send back if the client sends a (FTP) `MDTM` command, set to -1 to have it return that the file doesn't exist ### `<postcmd>` @@ -460,8 +461,8 @@ to have failed. ### `<tool>` Name of tool to invoke instead of "curl". This tool must be built and exist -either in the libtest/ directory (if the tool name starts with 'lib') or in -the unit/ directory (if the tool name starts with 'unit'). +either in the `libtest/` directory (if the tool name starts with `lib`) or in +the `unit/` directory (if the tool name starts with `unit`). ### `<name>` Brief test case description, shown when the test runs. @@ -525,13 +526,13 @@ needed. This creates the named file with this content before the test case is run, which is useful if the test case needs a file to act on. -If 'nonewline="yes"` is used, the created file will have the final newline +If `nonewline="yes"` is used, the created file will have the final newline stripped off. ### `<stdin [nonewline="yes"]>` Pass this given data on stdin to the tool. -If 'nonewline' is set, we will cut off the trailing newline of this given data +If `nonewline` is set, we will cut off the trailing newline of this given data before comparing with the one actually received by the client ## `<verify>` @@ -551,7 +552,7 @@ advanced. Example: `s/^EPRT .*/EPRT stripped/`. ### `<protocol [nonewline="yes"]>` -the protocol dump curl should transmit, if 'nonewline' is set, we will cut off +the protocol dump curl should transmit, if `nonewline` is set, we will cut off the trailing newline of this given data before comparing with the one actually sent by the client The `<strip>` and `<strippart>` rules are applied before comparisons are made. @@ -559,7 +560,7 @@ comparisons are made. ### `<proxy [nonewline="yes"]>` The protocol dump curl should transmit to a HTTP proxy (when the http-proxy -server is used), if 'nonewline' is set, we will cut off the trailing newline +server is used), if `nonewline` is set, we will cut off the trailing newline of this given data before comparing with the one actually sent by the client The `<strip>` and `<strippart>` rules are applied before comparisons are made. @@ -569,7 +570,7 @@ This verifies that this data was passed to stderr. Use the mode="text" attribute if the output is in text mode on platforms that have a text/binary difference. -If 'nonewline' is set, we will cut off the trailing newline of this given data +If `nonewline` is set, we will cut off the trailing newline of this given data before comparing with the one actually received by the client ### `<stdout [mode="text"] [nonewline="yes"]>` @@ -578,7 +579,7 @@ This verifies that this data was passed to stdout. Use the mode="text" attribute if the output is in text mode on platforms that have a text/binary difference. -If 'nonewline' is set, we will cut off the trailing newline of this given data +If `nonewline` is set, we will cut off the trailing newline of this given data before comparing with the one actually received by the client ### `<file name="log/filename" [mode="text"]>` @@ -601,7 +602,7 @@ compared with what is stored in the test file. This is pretty advanced. Example: "s/^EPRT .*/EPRT stripped/" ### `<stripfile1>` -1 to 4 can be appended to 'stripfile' to strip the corresponding <fileN> +1 to 4 can be appended to `stripfile` to strip the corresponding <fileN> content ### `<stripfile2>` diff --git a/tests/README.md b/tests/README.md index daa168014..7fff0a534 100644 --- a/tests/README.md +++ b/tests/README.md @@ -53,7 +53,7 @@ SPDX-License-Identifier: curl continue to work independent on what port numbers the test servers actually use. - See [FILEFORMAT](FILEFORMAT.md) for the port number variables. + See [`FILEFORMAT`](FILEFORMAT.md) for the port number variables. ### Test servers @@ -129,13 +129,13 @@ SPDX-License-Identifier: curl The test script will check that all allocated memory is freed properly IF curl has been built with the `CURLDEBUG` define set. The script will automatically detect if that is the case, and it will use the - 'memanalyze.pl' script to analyze the memory debugging output. + `memanalyze.pl` script to analyze the memory debugging output. Also, if you run tests on a machine where valgrind is found, the script will use valgrind to run the test with (unless you use `-n`) to further verify correctness. - runtests.pl's `-t` option will enable torture testing mode, which runs each + The `runtests.pl` `-t` option enables torture testing mode. It runs each test many times and makes each different memory allocation fail on each successive run. This tests the out of memory error handling code to ensure that memory leaks do not occur even in those situations. It can help to @@ -159,7 +159,7 @@ SPDX-License-Identifier: curl All test cases are put in the `data/` subdirectory. Each test is stored in the file named according to the test number. - See [FILEFORMAT.md](FILEFORMAT.md) for a description of the test case file + See [`FILEFORMAT`](FILEFORMAT.md) for a description of the test case file format. ### Code coverage @@ -172,13 +172,13 @@ SPDX-License-Identifier: curl make test make test-torture - The graphical tool ggcov can be used to browse the source and create + The graphical tool `ggcov` can be used to browse the source and create coverage reports on \*nix hosts: ggcov -r lib src - The text mode tool gcov may also be used, but it doesn't handle object files - in more than one directory correctly. + The text mode tool `gcov` may also be used, but it doesn't handle object + files in more than one directory correctly. ### Remote testing @@ -211,7 +211,7 @@ SPDX-License-Identifier: curl These files are `tests/data/test[num]` where `[num]` is just a unique identifier described above, and the XML-like file format of them is - described in the separate [FILEFORMAT.md](FILEFORMAT.md) document. + described in the separate [`FILEFORMAT`](FILEFORMAT.md) document. ### curl tests diff --git a/tests/disable-scan.pl b/tests/disable-scan.pl index b6ca37fa0..5d09bff27 100755 --- a/tests/disable-scan.pl +++ b/tests/disable-scan.pl @@ -95,7 +95,7 @@ sub scan_docs { my $line = 0; while(<F>) { $line++; - if(/^## (CURL_DISABLE_[A-Z_]+)/g) { + if(/^## `(CURL_DISABLE_[A-Z_]+)/g) { my ($sym)=($1); $docs{$sym} = $line; } diff --git a/tests/unit/README.md b/tests/unit/README.md index 0d32e010f..d17b249a0 100644 --- a/tests/unit/README.md +++ b/tests/unit/README.md @@ -33,7 +33,7 @@ start up gdb and run the same case using that. ## Write Unit Tests We put tests that focus on an area or a specific function into a single C -source file. The source file should be named 'unitNNNN.c' where NNNN is a +source file. The source file should be named `unitNNNN.c` where `NNNN` is a previously unused number. Add your test to `tests/unit/Makefile.inc` (if it is a unit test). Add your @@ -45,28 +45,29 @@ and the `tests/FILEFORMAT.md` documentation. For the actual C file, here's a simple example: ~~~c -#include "curlcheck.h" -#include "a libcurl header.h" /* from the lib dir */ + #include "curlcheck.h" -static CURLcode unit_setup( void ) -{ - /* whatever you want done first */ - return CURLE_OK; -} + #include "a libcurl header.h" /* from the lib dir */ -static void unit_stop( void ) -{ - /* done before shutting down and exiting */ -} + static CURLcode unit_setup( void ) + { + /* whatever you want done first */ + return CURLE_OK; + } -UNITTEST_START + static void unit_stop( void ) + { + /* done before shutting down and exiting */ + } - /* here you start doing things and checking that the results are good */ + UNITTEST_START - fail_unless( size == 0 , "initial size should be zero" ); - fail_if( head == NULL , "head should not be initiated to NULL" ); + /* here you start doing things and checking that the results are good */ - /* you end the test code like this: */ + fail_unless( size == 0 , "initial size should be zero" ); + fail_if( head == NULL , "head should not be initiated to NULL" ); -UNITTEST_STOP + /* you end the test code like this: */ + + UNITTEST_STOP diff --git a/winbuild/README.md b/winbuild/README.md index bcc4a61f2..fe35a2145 100644 --- a/winbuild/README.md +++ b/winbuild/README.md @@ -21,8 +21,8 @@ SPDX-License-Identifier: curl ## Prerequisites
- If you wish to support zlib, openssl, c-ares, ssh2, you will have to download
- them separately and copy them to the deps directory as shown below:
+ If you wish to support zlib, OpenSSL, c-ares, ssh2, you will have to download
+ them separately and copy them to the `deps` directory as shown below:
somedirectory\
|_curl-src
@@ -33,8 +33,8 @@ SPDX-License-Identifier: curl |_ include
|_ bin
- It is also possible to create the deps directory in some other random places
- and tell the Makefile its location using the WITH_DEVEL option.
+ It is also possible to create the `deps` directory in some other random places
+ and tell the `Makefile` its location using the `WITH_DEVEL` option.
## Building straight from git
@@ -81,9 +81,7 @@ where `<options>` is one or many of: - `VC=<num>` - VC version. 6 or later.
- `WITH_DEVEL=<path>` - Paths for the development files (SSL, zlib, etc.)
- Defaults to sibbling directory deps: ../deps
- Libraries can be fetched at https://windows.php.net/downloads/php-sdk/deps/
- Uncompress them into the deps folder.
+ Defaults to sibling directory: `../deps`
- `WITH_SSL=<dll/static>` - Enable OpenSSL support, DLL or static
- `WITH_NGHTTP2=<dll/static>` - Enable HTTP/2 support, DLL or static
- `WITH_MSH3=<dll/static>` - Enable (experimental) HTTP/3 support, DLL or static
@@ -115,20 +113,20 @@ where `<options>` is one or many of: - `SSL_PATH=<path>` - Custom path for OpenSSL
- `ZLIB_PATH=<path>` - Custom path for zlib
-## Static linking of Microsoft's C RunTime (CRT):
+## Static linking of Microsoft's C runtime (CRT):
If you are using mode=static nmake will create and link to the static build
of libcurl but *not* the static CRT. If you must you can force nmake to link
- in the static CRT by passing RTLIBCFG=static. Typically you shouldn't use
- that option, and nmake will default to the DLL CRT. RTLIBCFG is rarely used
- and therefore rarely tested. When passing RTLIBCFG for a configuration that
+ in the static CRT by passing `RTLIBCFG=static`. Typically you shouldn't use
+ that option, and nmake will default to the DLL CRT. `RTLIBCFG` is rarely used
+ and therefore rarely tested. When passing `RTLIBCFG` for a configuration that
was already built but not with that option, or if the option was specified
differently, you must destroy the build directory containing the
configuration so that nmake can build it from scratch.
This option is not recommended unless you have enough development experience
- to know how to match the runtime library for linking (that is, the CRT).
- If RTLIBCFG=static then release builds use /MT and debug builds use /MTd.
+ to know how to match the runtime library for linking (that is, the CRT). If
+ `RTLIBCFG=static` then release builds use `/MT` and debug builds use `/MTd`.
## Building your own application with libcurl (Visual Studio example)
@@ -140,17 +138,17 @@ where `<options>` is one or many of: For example let's say you've built curl.exe and libcurl.dll from the Visual
Studio 2010 x64 Win64 Command Prompt:
- nmake /f Makefile.vc mode=dll VC=10
+ nmake /f Makefile.vc mode=dll VC=10
The output directory will have a name similar to
- ..\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel.
+ `..\builds\libcurl-vc10-x64-release-dll-ipv6-sspi-schannel`.
The output directory contains subdirectories bin, lib and include. Those are
the directories to set in your Visual Studio project. You can either copy the
output directory to your project or leave it in place. Following the example,
let's assume you leave it in place and your curl top source directory is
- C:\curl-7.82.0. You would set these options for configurations using the x64
- platform:
+ `C:\curl-7.82.0`. You would set these options for configurations using the
+ x64 platform:
~~~
- Configuration Properties > Debugging > Environment
@@ -169,26 +167,27 @@ where `<options>` is one or many of: For configurations using the x86 platform (aka Win32 platform) you would
need to make a separate x86 build of libcurl.
- If you build libcurl static (mode=static) or debug (DEBUG=yes) then the
+ If you build libcurl static (`mode=static`) or debug (`DEBUG=yes`) then the
library name will vary and separate builds may be necessary for separate
- configurations of your project within the same platform. This is discussed
- in the next section.
+ configurations of your project within the same platform. This is discussed in
+ the next section.
## Building your own application with a static libcurl
When building an application that uses the static libcurl library on Windows,
- you must define CURL_STATICLIB. Otherwise the linker will look for dynamic
+ you must define `CURL_STATICLIB`. Otherwise the linker will look for dynamic
import symbols.
- The static library name has an '_a' suffix in the basename and the debug
- library name has a '_debug' suffix in the basename. For example,
- libcurl_a_debug.lib is a static debug build of libcurl.
+ The static library name has an `_a` suffix in the basename and the debug
+ library name has a `_debug` suffix in the basename. For example,
+ `libcurl_a_debug.lib` is a static debug build of libcurl.
You may need a separate build of libcurl for each VC configuration combination
- (eg: Debug|Win32, Debug|x64, Release|Win32, Release|x64).
+ (for example: Debug|Win32, Debug|x64, Release|Win32, Release|x64).
You must specify any additional dependencies needed by your build of static
- libcurl (eg: advapi32.lib;crypt32.lib;normaliz.lib;ws2_32.lib;wldap32.lib).
+ libcurl (for example:
+ `advapi32.lib;crypt32.lib;normaliz.lib;ws2_32.lib;wldap32.lib`).
## Legacy Windows and SSL
|