mirror/curl
2
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2025-03-31 16:00:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: spellfixes

Browse Source 
Pointed by the new CI job
This commit is contained in:
Daniel Stenberg 2022-09-20 23:30:19 +02:00
parent 72c41f7c8b
commit fd1ce3d4b0
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
188 changed files with 1203 additions and 1208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -6,7 +6,7 @@ SPDX-License-Identifier: curl
# ![curl logo](https://curl.se/logo/curl-logo.svg)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/63/badge)](https://bestpractices.coreinfrastructure.org/projects/63)
[![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/63/badge)](https://bestpractices.coreinfrastructure.org/projects/63)
[![Coverity passed](https://scan.coverity.com/projects/curl/badge.svg)](https://scan.coverity.com/projects/curl)
[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/l1vv31029huhf4g4?svg=true)](https://ci.appveyor.com/project/curlorg/curl)
[![Azure DevOps Build Status](https://dev.azure.com/daniel0244/curl/_apis/build/status/curl.curl?branchName=master)](https://dev.azure.com/daniel0244/curl/_build/latest?definitionId=1&branchName=master)

6
SECURITY.md
View File

@ -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.

18
docs/BUFREF.md
View File

@ -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);

20
docs/CHECKSRC.md
View File

@ -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.

16
docs/CIPHERS.md
View File

@ -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.

4
docs/CODE_REVIEW.md
View File

@ -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.

20
docs/CONTRIBUTE.md
View File

@ -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)

72
docs/CURL-DISABLE.md
View File

@ -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.

2
docs/DEPRECATE.md
View File

@ -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

31
docs/DYNBUF.md
View File

@ -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);

2
docs/EXPERIMENTAL.md
View File

@ -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

6
docs/FEATURES.md
View File

@ -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,

4
docs/GOVERNANCE.md
View File

@ -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

8
docs/HISTORY.md
View File

@ -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.

8
docs/HSTS.md
View File

@ -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

15
docs/HTTP-COOKIES.md
View File

@ -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.

10
docs/HTTP2.md
View File

@ -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

6
docs/HTTP3.md
View File

@ -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

54
docs/INSTALL.md
View File

@ -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

2
docs/INTERNALS.md
View File

@ -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

4
docs/KNOWN_BUGS
View File

@ -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.

140
docs/MANUAL.md
View File

@ -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.

2
docs/NEW-PROTOCOL.md
View File

@ -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

4
docs/PARALLEL-TRANSFERS.md
View File

@ -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:

4
docs/RELEASE-PROCEDURE.md
View File

@ -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

10
docs/SECURITY-PROCESS.md
View File

@ -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

9
docs/SSL-PROBLEMS.md
View File

@ -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

80
docs/SSLCERTS.md
View File

@ -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).
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.
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
-----------------------------------------------------------

22
docs/TheArtOfHttpScripting.md
View File

@ -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

31
docs/URL-SYNTAX.md
View File

@ -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

6
docs/VERSIONS.md
View File

@ -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.

2
docs/WEBSOCKET.md
View File

@ -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

2
docs/cmdline-opts/ssl-reqd.d
View File

@ -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.

2
docs/cmdline-opts/ssl.d
View File

@ -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.

19
docs/curl-config.1
View File

@ -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)

5
docs/examples/README.md
View File

@ -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:

8
docs/libcurl/ABI.md
View File

@ -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

2
docs/libcurl/curl_easy_escape.3
View File

@ -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

2
docs/libcurl/curl_easy_header.3
View File

@ -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

6
docs/libcurl/curl_easy_option_by_id.3
View File

@ -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),"

11
docs/libcurl/curl_easy_option_by_name.3
View File

@ -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),"

6
docs/libcurl/curl_easy_option_next.3
View File

@ -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),"

2
docs/libcurl/curl_easy_perform.3
View File

@ -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

10
docs/libcurl/curl_easy_setopt.3
View File

@ -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

9
docs/libcurl/curl_easy_unescape.3
View File

@ -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

8
docs/libcurl/curl_escape.3
View File

@ -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

53
docs/libcurl/curl_formadd.3
View File

@ -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"

2
docs/libcurl/curl_formfree.3
View File

@ -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>

4
docs/libcurl/curl_formget.3
View File

@ -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)"

12
docs/libcurl/curl_getdate.3
View File

@ -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

4
docs/libcurl/curl_getenv.3
View File

@ -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.

8
docs/libcurl/curl_global_init.3
View File

@ -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.

2
docs/libcurl/curl_global_init_mem.3
View File

@ -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), "

9
docs/libcurl/curl_global_sslset.3
View File

@ -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

2
docs/libcurl/curl_mime_encoder.3
View File

@ -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

6
docs/libcurl/curl_mime_free.3
View File

@ -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.

2
docs/libcurl/curl_mime_name.3
View File

@ -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;

4
docs/libcurl/curl_mime_subparts.3
View File

@ -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.

60
docs/libcurl/curl_mprintf.3
View File

@ -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.

2
docs/libcurl/curl_multi_add_handle.3
View File

@ -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"

35
docs/libcurl/curl_multi_fdset.3
View File

@ -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), "

18
docs/libcurl/curl_multi_info_read.3
View File

@ -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 {

6
docs/libcurl/curl_multi_init.3
View File

@ -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

3
docs/libcurl/curl_multi_poll.3
View File

@ -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

4
docs/libcurl/curl_multi_strerror.3
View File

@ -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;

13
docs/libcurl/curl_multi_wait.3
View File

@ -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;

9
docs/libcurl/curl_share_init.3
View File

@ -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

4
docs/libcurl/curl_share_strerror.3
View File

@ -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;

4
docs/libcurl/curl_strequal.3
View File

@ -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"

4
docs/libcurl/curl_unescape.3
View File

@ -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

6
docs/libcurl/curl_url.3
View File

@ -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;

4
docs/libcurl/curl_url_cleanup.3
View File

@ -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();

8
docs/libcurl/curl_url_dup.3
View File

@ -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;

2
docs/libcurl/curl_url_get.3
View File

@ -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

8
docs/libcurl/curl_url_set.3
View File

@ -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

5
docs/libcurl/curl_version_info.3
View File

@ -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.

14
docs/libcurl/curl_ws_recv.3
View File

@ -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

8
docs/libcurl/curl_ws_send.3
View File

@ -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

18
docs/libcurl/libcurl-env.3
View File

@ -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.

28
docs/libcurl/libcurl-errors.3
View File

@ -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)"

13
docs/libcurl/libcurl-multi.3
View File

@ -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.

80
docs/libcurl/libcurl-security.3
View File

@ -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

4
docs/libcurl/libcurl-thread.3
View File

@ -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

273
docs/libcurl/libcurl-tutorial.3
View File

@ -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

46
docs/libcurl/libcurl-url.3
View File

@ -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), "

6
docs/libcurl/libcurl.3
View File

@ -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

2
docs/libcurl/opts/CURLINFO_CAINFO.3
View File

@ -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>

2
docs/libcurl/opts/CURLINFO_CAPATH.3
View File

@ -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>

14
docs/libcurl/opts/CURLINFO_CERTINFO.3
View File

@ -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

2
docs/libcurl/opts/CURLINFO_FILETIME.3
View File

@ -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.

8
docs/libcurl/opts/CURLINFO_FILETIME_T.3
View File

@ -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

9
docs/libcurl/opts/CURLINFO_PROXY_ERROR.3
View File

@ -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

2
docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3
View File

@ -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

2
docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3
View File

@ -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.

12
docs/libcurl/opts/CURLINFO_TLS_SESSION.3
View File

@ -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

38
docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3
View File

@ -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

10
docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3
View File

@ -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

4
docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3
View File

@ -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.

3
docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3
View File

@ -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

4
docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3
View File

@ -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

Some files were not shown because too many files have changed in this diff Show More