romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-07-23 19:17:18 +03:00
Code Issues Projects Releases Packages Wiki Activity

docs: rewrite to present tense

Browse source 
... instead of using future tense.

+ numerous cleanups and improvements
+ stick to "reuse" not "re-use"
+ fewer contractions

Closes #11713
This commit is contained in:
Daniel Stenberg 2023-08-22 17:40:39 +02:00
parent 887b998e6e
commit 5b060a4108
No known key found for this signature in database
GPG key ID: 5CC908FDB71E12C2
339 changed files with 1873 additions and 1884 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/CHECKSRC.md
View file

@ -41,7 +41,7 @@ warnings are:
more appropriate `char *name` style. The asterisk should sit right next to
the name without a space in between.
- `BADCOMMAND`: There's a bad `checksrc` instruction in the code. See the
- `BADCOMMAND`: There is a bad `checksrc` instruction in the code. See the
**Ignore certain warnings** section below for details.
- `BANNEDFUNC`: A banned function was used. The functions sprintf, vsprintf,

2
docs/CODE_STYLE.md
View file

@ -60,7 +60,7 @@ Source code in curl may never be wider than 79 columns and there are two
reasons for maintaining this even in the modern era of large and high
resolution screens:
1. Narrower columns are easier to read than wide ones. There's a reason
1. Narrower columns are easier to read than wide ones. There is a reason
newspapers have used columns for decades or centuries.
2. Narrower columns allow developers to easier show multiple pieces of code

14
docs/CONTRIBUTE.md
View file

@ -206,11 +206,11 @@ A short guide to how to write git commit messages in the curl project.
[Bug: URL to the source of the report or more related discussion; use Fixes
for GitHub issues instead when that is appropriate]
[Approved-by: John Doe - credit someone who approved the PR; if you are
committing this for someone else using --author=... you don't need this
committing this for someone else using --author=... you do not need this
as you are implicitly approving it by committing]
[Authored-by: John Doe - credit the original author of the code; only use
this if you can't use "git commit --author=..."]
[Signed-off-by: John Doe - we don't use this, but don't bother removing it]
this if you cannot use "git commit --author=..."]
[Signed-off-by: John Doe - we do not use this, but do not bother removing it]
[whatever-else-by: credit all helpers, finders, doers; try to use one of
the following keywords if at all possible, for consistency:
Acked-by:, Assisted-by:, Co-authored-by:, Found-by:, Reported-by:,
@ -232,7 +232,7 @@ The first line is a succinct description of the change:
- no period (.) at the end
The `[area]` in the first line can be `http2`, `cookies`, `openssl` or
similar. There's no fixed list to select from but using the same "area" as
similar. There is no fixed list to select from but using the same "area" as
other related changes could make sense.
Do not forget to use commit --author=... if you commit someone else's work, and
@ -240,9 +240,9 @@ make sure that you have your own user and email setup correctly in git before
you commit.
Add whichever header lines as appropriate, with one line per person if more
than one person was involved. There's no need to credit yourself unless you are
using --author=... which hides your identity. Don't include people's e-mail
addresses in headers to avoid spam, unless they're already public from a
than one person was involved. There is no need to credit yourself unless you are
using --author=... which hides your identity. Do not include people's e-mail
addresses in headers to avoid spam, unless they are already public from a
previous commit; saying `{userid} on github` is OK.
### Write Access to git Repository

2
docs/DYNBUF.md
View file

@ -27,7 +27,7 @@ void Curl_dyn_free(struct dynbuf *s);
```
Free the associated memory and clean up. After a free, the `dynbuf` struct can
be re-used to start appending new data to.
be reused to start appending new data to.
## `Curl_dyn_addn`

2
docs/EARLY-RELEASE.md
View file

@ -49,7 +49,7 @@ the three ones above are all 'no'.
- Is there a (decent) workaround?
- Is it a regression? Is the bug introduced in this release?
- Can the bug be fixed "easily" by applying a patch?
- Does the bug break the build? Most users don't build curl themselves.
- Does the bug break the build? Most users do not build curl themselves.
- How long is it until the already scheduled next release?
- Can affected users safely rather revert to a former release until the next
scheduled release?

2
docs/FAQ
View file

@ -1498,7 +1498,7 @@ FAQ
unknown to me).
After a transfer, you just set new options in the handle and make another
transfer. This will make libcurl re-use the same connection if it can.
transfer. This will make libcurl reuse the same connection if it can.
7.4 Does PHP/CURL have dependencies?

2
docs/HELP-US.md
View file

@ -38,7 +38,7 @@ even maybe not a terribly experienced developer, here's our advice:
In the issue tracker we occasionally mark bugs with [help
wanted](https://github.com/curl/curl/labels/help%20wanted), as a sign that the
bug is acknowledged to exist and that there's nobody known to work on this
bug is acknowledged to exist and that there is nobody known to work on this
issue for the moment. Those are bugs that are fine to "grab" and provide a
pull request for. The complexity level of these will of course vary, so pick
one that piques your interest.

2
docs/HISTORY.md
View file

@ -161,7 +161,7 @@ Starting with 7.10, curl verifies SSL server certificates by default.
January: Started working on the distributed curl tests. The autobuilds.
February: the curl site averages at 20000 visits weekly. At any given moment,
there's an average of 3 people browsing the website.
there is an average of 3 people browsing the website.
Multiple new authentication schemes are supported: Digest (May), NTLM (June)
and Negotiate (June).

4
docs/HTTP2.md
View file

@ -55,14 +55,14 @@ connection.
To take advantage of multiplexing, you need to use the multi interface and set
`CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl will
attempt to re-use existing HTTP/2 connections and just add a new stream over
attempt to reuse existing HTTP/2 connections and just add a new stream over
that when doing subsequent parallel requests.
While libcurl sets up a connection to an HTTP server there is a period during
which it does not know if it can pipeline or do multiplexing and if you add
new transfers in that period, libcurl will default to start new connections
for those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0),
you can ask that a transfer should rather wait and see in case there's a
you can ask that a transfer should rather wait and see in case there is a
connection for the same host in progress that might end up being possible to
multiplex on. It favors keeping the number of connections low to the cost of
slightly longer time to first byte transferred.

2
docs/HTTP3.md
View file

@ -340,7 +340,7 @@ should be either in your PATH or your current directory.
Create a `Caddyfile` with the following content:
~~~
localhost:7443 {
respond "Hello, world! You're using {http.request.proto}"
respond "Hello, world! you are using {http.request.proto}"
}
~~~

12
docs/KNOWN_BUGS
View file

@ -101,8 +101,8 @@ problems may have been fixed or changed somewhat since this was written.
15.13 CMake build with MIT Kerberos does not work
16. aws-sigv4
16.1 aws-sigv4 doesn't sign requests with * correctly
16.2 aws-sigv4 doesn't sign requests with valueless queries correctly
16.1 aws-sigv4 does not sign requests with * correctly
16.2 aws-sigv4 does not sign requests with valueless queries correctly
16.3 aws-sigv4 is missing the amz-content-sha256 header
16.4 aws-sigv4 does not sort query string parameters before signing
16.5 aws-sigv4 does not sign requests with empty URL query correctly
@ -516,8 +516,8 @@ problems may have been fixed or changed somewhat since this was written.
13.2 Trying local ports fails on Windows
This makes '--local-port [range]' to not work since curl can't properly
detect if a port is already in use, so it'll try the first port, use that and
This makes '--local-port [range]' to not work since curl cannot properly
detect if a port is already in use, so it will try the first port, use that and
then subsequently fail anyway if that was actually in use.
https://github.com/curl/curl/issues/8112
@ -581,11 +581,11 @@ problems may have been fixed or changed somewhat since this was written.
16. aws-sigv4
16.1 aws-sigv4 doesn't sign requests with * correctly
16.1 aws-sigv4 does not sign requests with * correctly
https://github.com/curl/curl/issues/7559
16.2 aws-sigv4 doesn't sign requests with valueless queries correctly
16.2 aws-sigv4 does not sign requests with valueless queries correctly
https://github.com/curl/curl/issues/8107

2
docs/MAIL-ETIQUETTE
View file

@ -120,7 +120,7 @@ MAIL ETIQUETTE
your email address and password and press the unsubscribe button.
Also, the instructions to unsubscribe are included in the headers of every
mail that is sent out to all curl related mailing lists and there's a footer
mail that is sent out to all curl related mailing lists and there is a footer
in each mail that links to the "admin" page on which you can unsubscribe and
change other options.

2
docs/THANKS-filter
View file

@ -26,7 +26,7 @@
# appropriately in THANKS. This list contains variations of their names and
# their "canonical" name. This file is used for scripting purposes to avoid
# duplicate entries and will not be included in release tarballs.
# When removing dupes that aren't identical names from THANKS, add a line
# When removing dupes that are not identical names from THANKS, add a line
# here!
#
# Used-by: contributors.sh

20
docs/TODO
View file

@ -685,7 +685,7 @@
6.4 exit immediately upon connection if stdin is /dev/null
If it did, curl could be used to probe if there's an server there listening
If it did, curl could be used to probe if there is an server there listening
on a specific port. That is, the following command would exit immediately
after the connection is established with exit code 0:
@ -819,9 +819,9 @@
request as well, when they should only be necessary once per SSL context (or
once per handle)". The major improvement we can rather easily do is to make
sure we do not create and kill a new SSL "context" for every request, but
instead make one for every connection and re-use that SSL context in the same
style connections are re-used. It will make us use slightly more memory but
it will libcurl do less creations and deletions of SSL contexts.
instead make one for every connection and reuse that SSL context in the same
style connections are reused. It will make us use slightly more memory but it
will libcurl do less creations and deletions of SSL contexts.
Technically, the "caching" is probably best implemented by getting added to
the share interface so that easy handles who want to and can reuse the
@ -841,7 +841,7 @@
OpenSSL supports a callback for customised verification of the peer
certificate, but this does not seem to be exposed in the libcurl APIs. Could
it be? There's so much that could be done if it were.
it be? There is so much that could be done if it were.
13.7 Less memory massaging with Schannel
@ -1101,7 +1101,7 @@
18.13 Ratelimit or wait between serial requests
Consider a command line option that can make curl do multiple serial requests
slow, potentially with a (random) wait between transfers. There's also a
slow, potentially with a (random) wait between transfers. There is also a
proposed set of standard HTTP headers to let servers let the client adapt to
its rate limits:
https://www.ietf.org/id/draft-polli-ratelimit-headers-02.html
@ -1139,7 +1139,7 @@
URL, the file name is not extracted and used from the newly redirected-to URL
even if the new URL may have a much more sensible file name.
This is clearly documented and helps for security since there's no surprise
This is clearly documented and helps for security since there is no surprise
to users which file name that might get overwritten. But maybe a new option
could allow for this or maybe -J should imply such a treatment as well as -J
already allows for the server to decide what file name to use so it already
@ -1341,9 +1341,9 @@
20.5 Add support for concurrent connections
Tests 836, 882 and 938 were designed to verify that separate connections
are not used when using different login credentials in protocols that
should not re-use a connection under such circumstances.
Tests 836, 882 and 938 were designed to verify that separate connections are
not used when using different login credentials in protocols that should not
reuse a connection under such circumstances.
Unfortunately, ftpserver.pl does not appear to support multiple concurrent
connections. The read while() loop seems to loop until it receives a

4
docs/URL-SYNTAX.md
View file

@ -197,7 +197,7 @@ of Windows.
## Port number
If there's a colon after the hostname, that should be followed by the port
If there is a colon after the hostname, that should be followed by the port
number to use. 1 - 65535. curl also supports a blank port number field - but
only if the URL starts with a scheme.
@ -379,7 +379,7 @@ The default smtp port is 25. Some servers use port 587 as an alternative.
## RTMP
There's no official URL spec for RTMP so libcurl uses the URL syntax supported
There is no official URL spec for RTMP so libcurl uses the URL syntax supported
by the underlying librtmp library. It has a syntax where it wants a
traditional URL, followed by a space and a series of space-separated
`name=value` pairs.

2
docs/cmdline-opts/form-string.d
View file

@ -13,5 +13,5 @@ Multi: append
Similar to --form except that the value string for the named parameter is used
literally. Leading '@' and '<' characters, and the ';type=' string in
the value have no special meaning. Use this in preference to --form if
there's any possibility that the string value may accidentally trigger the
there is any possibility that the string value may accidentally trigger the
'@' or '<' features of --form.

7
docs/cmdline-opts/ftp-skip-pasv-ip.d
View file

@ -9,10 +9,9 @@ Category: ftp
Example: --ftp-skip-pasv-ip ftp://example.com/
Multi: boolean
---
Tell curl to not use the IP address the server suggests in its response
to curl's PASV command when curl connects the data connection. Instead curl
will re-use the same IP address it already uses for the control
connection.
Tell curl to not use the IP address the server suggests in its response to
curl's PASV command when curl connects the data connection. Instead curl will
reuse the same IP address it already uses for the control connection.
Since curl 7.74.0 this option is enabled by default.

4
docs/cmdline-opts/gen.pl
View file

@ -33,7 +33,7 @@ Dev notes:
We open *input* files in :crlf translation (a no-op on many platforms) in
case we have CRLF line endings in Windows but a perl that defaults to LF.
Unfortunately it seems some perls like msysgit can't handle a global input-only
Unfortunately it seems some perls like msysgit cannot handle a global input-only
:crlf so it has to be specified on each file open for text input.
=end comment
@ -183,7 +183,7 @@ sub too_old {
sub added {
my ($standalone, $data)=@_;
if(too_old($data)) {
# don't mention ancient additions
# do not mention ancient additions
return "";
}
if($standalone) {

2
docs/cmdline-opts/noproxy.d
View file

@ -17,7 +17,7 @@ example, local.com would match local.com, local.com:80, and www.local.com, but
not www.notlocal.com.
Since 7.53.0, This option overrides the environment variables that disable the
proxy ('no_proxy' and 'NO_PROXY'). If there's an environment variable
proxy ('no_proxy' and 'NO_PROXY'). If there is an environment variable
disabling a proxy, you can set the no proxy list to "" to override it.
Since 7.86.0, IP addresses specified to this option can be provided using CIDR

4
docs/cmdline-opts/page-header
View file

@ -51,9 +51,9 @@ in a sequential manner in the specified order unless you use --parallel. You
can specify command line options and URLs mixed and in any order on the
command line.
curl attempts to re-use connections when doing multiple transfers, so that
curl attempts to reuse connections when doing multiple transfers, so that
getting many files from the same server do not use multiple connects and setup
handshakes. This improves speed. Connection re-use can only be done for URLs
handshakes. This improves speed. Connection reuse can only be done for URLs
specified for a single command line invocation and cannot be performed between
separate curl runs.

2
docs/cmdline-opts/proxy.d
View file

@ -31,7 +31,7 @@ If the port number is not specified in the proxy string, it is assumed to be
1080.
This option overrides existing environment variables that set the proxy to
use. If there's an environment variable setting a proxy, you can set proxy to
use. If there is an environment variable setting a proxy, you can set proxy to
"" to override it.
All operations that are performed over an HTTP proxy will transparently be

2
docs/cmdline-opts/remote-header-name.d
View file

@ -23,7 +23,7 @@ in the destination directory, it will not be overwritten and an error will
occur - unless you allow it by using the --clobber option. If the server does
not specify a file name then this option has no effect.
There's no attempt to decode %-sequences (yet) in the provided file name, so
There is no attempt to decode %-sequences (yet) in the provided file name, so
this option may provide you with rather unexpected file names.
This feature uses the name from the "filename" field, it does not yet support

2
docs/examples/Makefile.example
View file

@ -34,7 +34,7 @@ CC = gcc
# Compiler flags, -g for debug, -c to make an object file
CFLAGS = -c -g
# This should point to a directory that holds libcurl, if it isn't
# This should point to a directory that holds libcurl, if it is not
# in the system's standard lib dir
# We also set a -L to include the directory where we have the openssl
# libraries

2
docs/examples/Makefile.inc
View file

@ -129,7 +129,7 @@ check_PROGRAMS = \
websocket-cb
# These examples require external dependencies that may not be commonly
# available on POSIX systems, so don't bother attempting to compile them here.
# available on POSIX systems, so do not bother attempting to compile them here.
COMPLICATED_EXAMPLES = \
cacertinmem.c \
crawler.c \

2
docs/examples/anyauthput.c
View file

@ -60,7 +60,7 @@ static int my_seek(void *userp, curl_off_t offset, int origin)
FILE *fp = (FILE *) userp;
if(-1 == fseek(fp, (long) offset, origin))
/* couldn't seek */
/* could not seek */
return CURL_SEEKFUNC_CANTSEEK;
return CURL_SEEKFUNC_OK; /* success! */

2
docs/examples/ftpget.c
View file

@ -66,7 +66,7 @@ int main(void)
*/
curl_easy_setopt(curl, CURLOPT_URL,
"ftp://ftp.example.com/curl/curl-7.9.2.tar.gz");
/* Define our callback to get called when there's data to be written */
/* Define our callback to get called when there is data to be written */
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, my_fwrite);
/* Set a pointer to our struct to pass to the callback */
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &ftpfile);

2
docs/examples/ftpsget.c
View file

@ -70,7 +70,7 @@ int main(void)
*/
curl_easy_setopt(curl, CURLOPT_URL,
"ftp://user@server/home/user/file.txt");
/* Define our callback to get called when there's data to be written */
/* Define our callback to get called when there is data to be written */
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, my_fwrite);
/* Set a pointer to our struct to pass to the callback */
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &ftpfile);

2
docs/examples/http2-pushinmemory.c
View file

@ -92,7 +92,7 @@ static void setup(CURL *hnd)
curl_easy_setopt(hnd, CURLOPT_PIPEWAIT, 1L);
}
/* called when there's an incoming push */
/* called when there is an incoming push */
static int server_push_callback(CURL *parent,
CURL *easy,
size_t num_headers,

2
docs/examples/http2-serverpush.c
View file

@ -161,7 +161,7 @@ static int setup(CURL *hnd, const char *url)
return 0; /* all is good */
}
/* called when there's an incoming push */
/* called when there is an incoming push */
static int server_push_callback(CURL *parent,
CURL *easy,
size_t num_headers,

2
docs/examples/persistent.c
View file

@ -22,7 +22,7 @@
*
***************************************************************************/
/* <DESC>
* re-using handles to do HTTP persistent connections
* reusing handles to do HTTP persistent connections
* </DESC>
*/
#include <stdio.h>

2
docs/examples/sftpget.c
View file

@ -77,7 +77,7 @@ int main(void)
*/
curl_easy_setopt(curl, CURLOPT_URL,
"sftp://user@server/home/user/file.txt");
/* Define our callback to get called when there's data to be written */
/* Define our callback to get called when there is data to be written */
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, my_fwrite);
/* Set a pointer to our struct to pass to the callback */
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &ftpfile);

2
docs/examples/smtp-authzid.c
View file

@ -148,7 +148,7 @@ int main(void)
curl_slist_free_all(recipients);
/* curl will not send the QUIT command until you call cleanup, so you
* should be able to re-use this connection for additional messages
* should be able to reuse this connection for additional messages
* (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and
* calling curl_easy_perform() again. It may not be a good idea to keep
* the connection open for a very long time though (more than a few

2
docs/examples/smtp-expn.c
View file

@ -69,7 +69,7 @@ int main(void)
curl_slist_free_all(recipients);
/* curl will not send the QUIT command until you call cleanup, so you
* should be able to re-use this connection for additional requests. It
* should be able to reuse this connection for additional requests. It
* may not be a good idea to keep the connection open for a very long time
* though (more than a few minutes may result in the server timing out the
* connection) and you do want to clean up in the end.

2
docs/examples/smtp-mail.c
View file

@ -136,7 +136,7 @@ int main(void)
curl_slist_free_all(recipients);
/* curl will not send the QUIT command until you call cleanup, so you
* should be able to re-use this connection for additional messages
* should be able to reuse this connection for additional messages
* (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and
* calling curl_easy_perform() again. It may not be a good idea to keep
* the connection open for a very long time though (more than a few

2
docs/examples/smtp-mime.c
View file

@ -151,7 +151,7 @@ int main(void)
curl_slist_free_all(headers);
/* curl will not send the QUIT command until you call cleanup, so you
* should be able to re-use this connection for additional messages
* should be able to reuse this connection for additional messages
* (setting CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and
* calling curl_easy_perform() again. It may not be a good idea to keep
* the connection open for a very long time though (more than a few

2
docs/examples/smtp-vrfy.c
View file

@ -69,7 +69,7 @@ int main(void)
curl_slist_free_all(recipients);
/* curl will not send the QUIT command until you call cleanup, so you
* should be able to re-use this connection for additional requests. It
* should be able to reuse this connection for additional requests. It
* may not be a good idea to keep the connection open for a very long time
* though (more than a few minutes may result in the server timing out the
* connection) and you do want to clean up in the end.

22
docs/libcurl/curl_easy_cleanup.3
View file

@ -32,14 +32,13 @@ curl_easy_cleanup - End a libcurl easy handle
void curl_easy_cleanup(CURL *handle);
.fi
.SH DESCRIPTION
This function must be the last function to call for an easy session. It is the
opposite of the \fIcurl_easy_init(3)\fP function and must be called with the
same \fIhandle\fP as input that a \fIcurl_easy_init(3)\fP call returned.
This function is the opposite of \fIcurl_easy_init(3)\fP. It closes down and
frees all resources previously associated with this easy handle.
This might close all connections this handle has used and possibly has kept
open until now - unless it was attached to a multi handle while doing the
transfers. Do not call this function if you intend to transfer more files,
re-using handles is a key to good performance with libcurl.
This call closes all connections this handle has used and possibly has kept
open until now unless the easy handle was attached to a multi handle while
doing the transfers. Do not call this function if you intend to transfer more
files, reusing handles is a key to good performance with libcurl.
Occasionally you may get your progress callback or header callback called from
within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using
@ -47,15 +46,14 @@ within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using
connection and the protocol is of a kind that requires a command/response
sequence before disconnect. Examples of such protocols are FTP, POP3 and IMAP.
Any use of the \fBhandle\fP after this function has been called and have
returned, is illegal. \fIcurl_easy_cleanup(3)\fP kills the handle and all
memory associated with it!
Any use of the easy \fBhandle\fP after this function has been called and have
returned, is illegal.
To close an easy handle that has been used with the multi interface, make sure
to call \fIcurl_multi_remove_handle(3)\fP first to remove it from the multi
to first call \fIcurl_multi_remove_handle(3)\fP to remove it from the multi
handle before it is closed.
Passing in a NULL pointer in \fIhandle\fP will make this function return
Passing in a NULL pointer in \fIhandle\fP makes this function return
immediately with no action.
.SH EXAMPLE
.nf

21
docs/libcurl/curl_easy_duphandle.3
View file

@ -31,20 +31,19 @@ curl_easy_duphandle - Clone a libcurl session handle
CURL *curl_easy_duphandle(CURL *handle);
.fi
.SH DESCRIPTION
This function will return a new curl handle, a duplicate, using all the
options previously set in the input curl \fIhandle\fP. Both handles can
subsequently be used independently and they must both be freed with
This function returns a new curl handle, a duplicate, using all the options
previously set in the input curl \fIhandle\fP. Both handles can subsequently
be used independently and they must both be freed with
\fIcurl_easy_cleanup(3)\fP.
All strings that the input handle has been told to point to (as opposed to
copy) with previous calls to \fIcurl_easy_setopt(3)\fP using char * inputs,
will be pointed to by the new handle as well. You must therefore make sure to
keep the data around until both handles have been cleaned up.
Any options that the input handle has been told to point to (as opposed to
copy) with previous calls to \fIcurl_easy_setopt(3)\fP, are pointed to by the
new handle as well. You must therefore make sure to keep the data around until
both handles have been cleaned up.
The new handle will \fBnot\fP inherit any state information, no connections,
no SSL sessions and no cookies. It also will not inherit any share object
states or options (it will be made as if \fICURLOPT_SHARE(3)\fP was set to
NULL).
The new handle does \fBnot\fP inherit any state information, no connections,
no SSL sessions and no cookies. It also does not inherit any share object
states or options (created as if \fICURLOPT_SHARE(3)\fP was set to NULL).
In multi-threaded programs, this function must be called in a synchronous way,
the input handle may not be in use when cloned.

18
docs/libcurl/curl_easy_getinfo.3
View file

@ -32,12 +32,12 @@ curl_easy_getinfo - extract information from a curl handle
CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );
.fi
.SH DESCRIPTION
Request internal information from the curl session with this function. The
third argument \fBMUST\fP be pointing to the specific type of the used option
which is documented in each man page of the option. The data pointed-to will
be filled in accordingly and can be relied upon only if the function returns
CURLE_OK. Use this function AFTER a performed transfer if you want to get
transfer related data.
Get the \fIinfo\fP kept in the \fIcurl\fP handle. The third argument
\fBMUST\fP be pointing to the specific type of the used option which is
documented in each man page of the \fIinfo\fP option. The data is stored
accordingly and can be relied upon only if this function returns CURLE_OK. Use
this function after a performed transfer if you want to get transfer related
data.
You should not free the memory returned by this function unless it is
explicitly mentioned below.
@ -233,10 +233,10 @@ See \fICURLINFO_CONDITION_UNMET(3)\fP
RTSP session ID.
See \fICURLINFO_RTSP_SESSION_ID(3)\fP
.IP CURLINFO_RTSP_CLIENT_CSEQ
RTSP CSeq that will next be used.
The RTSP client CSeq that is expected next.
See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP
.IP CURLINFO_RTSP_SERVER_CSEQ
RTSP CSeq that will next be expected.
The RTSP server CSeq that is expected next.
See \fICURLINFO_RTSP_SERVER_CSEQ(3)\fP
.IP CURLINFO_RTSP_CSEQ_RECV
RTSP CSeq last received.
@ -320,6 +320,6 @@ transaction was started. So, this is zero if no redirection took place.
Added in 7.4.1
.SH RETURN VALUE
If the operation was successful, CURLE_OK is returned. Otherwise an
appropriate error code will be returned.
appropriate error code is returned.
.SH "SEE ALSO"
.BR curl_easy_setopt "(3)"

22
docs/libcurl/curl_easy_header.3
View file

@ -60,23 +60,23 @@ amount of requests used.
libcurl stores and provides the actually used "correct" headers. If for
example two headers with the same name arrive and the latter overrides the
former, then only the latter will be provided. If the first header survives
the second, then only the first one will be provided. An application using
this API does not have to bother about multiple headers used wrongly.
former, then only the latter is provided. If the first header survives the
second, then only the first one is provided. An application using this API
does not have to bother about multiple headers used wrongly.
The memory for the returned struct is associated with the easy handle and
subsequent calls to \fIcurl_easy_header(3)\fP will clobber the struct used in
the previous calls for the same easy handle. Applications need to copy the
data if it wants to keep it around. The memory used for the struct gets freed
with calling \fIcurl_easy_cleanup(3)\fP of the easy handle.
subsequent calls to \fIcurl_easy_header(3)\fP clobbers the struct used in the
previous calls for the same easy handle. Applications need to copy the data if
it wants to keep it around. The memory used for the struct gets freed with
calling \fIcurl_easy_cleanup(3)\fP of the easy handle.
The first line in an HTTP response is called the status line. It is not
considered a header by this function. Headers are the "name: value" lines
following the status.
This function can be used before (all) headers have been received and is fine
to call from within libcurl callbacks. It will always return the state of the
headers at the time it is called.
to call from within libcurl callbacks. It returns the state of the headers at
the time it is called.
.SH "The header struct"
.nf
struct curl_header {
@ -89,8 +89,8 @@ struct curl_header {
};
.fi
The data \fBname\fP field points to, will be the same as the requested name
but it might have a different case.
The data \fBname\fP field points to, is the same as the requested name, but
might have a different case.
The data \fBvalue\fP field points to, comes exactly as delivered over the
network but with leading and trailing whitespace and newlines stripped

29
docs/libcurl/curl_easy_init.3
View file

@ -31,20 +31,30 @@ curl_easy_init - Start a libcurl easy session
CURL *curl_easy_init();
.fi
.SH DESCRIPTION
This function must be the first function to call, and it returns a CURL easy
handle that you must use as input to other functions in the easy
interface. This call \fBMUST\fP have a corresponding call to
\fIcurl_easy_cleanup(3)\fP when the operation is complete.
This function allocates and returns a CURL easy handle. Such a handle is used
as input to other functions in the easy interface. This call must have a
corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is
complete.
If you did not already call \fIcurl_global_init(3)\fP, \fIcurl_easy_init(3)\fP
does it automatically. This may be lethal in multi-threaded cases, since
\fIcurl_global_init(3)\fP is not thread-safe, and it may result in resource
problems because there is no corresponding cleanup.
The easy handle is used to hold and control a single network transfer. It is
encouraged to reuse easy handles for repeated transfers.
An alternative way to get a new easy handle is to duplicate an already
existing one with \fIcurl_easy_duphandle(3)\fP, which has the upside that it
gets all the options that were set in the source handle set in the new copy as
well.
If you did not already call \fIcurl_global_init(3)\fP before calling this
function, \fIcurl_easy_init(3)\fP does it automatically. This may be lethal in
multi-threaded cases, if \fIcurl_global_init(3)\fP is not thread-safe in your
system, and it may then result in resource problems because there is no
corresponding cleanup.
You are strongly advised to not allow this automatic behavior, by calling
\fIcurl_global_init(3)\fP yourself properly. See the description in
\fBlibcurl\fP(3) of global environment requirements for details of how to use
this function.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
@ -62,4 +72,5 @@ If this function returns NULL, something went wrong and you cannot use the
other curl functions.
.SH "SEE ALSO"
.BR curl_easy_cleanup "(3), " curl_global_init "(3), " curl_easy_reset "(3), "
.BR curl_easy_perform "(3) "
.BR curl_easy_perform "(3), " curl_easy_duphandle "(3), "
.BR curl_multi_init "(3), "

4
docs/libcurl/curl_easy_option_by_id.3
View file

@ -35,8 +35,8 @@ Given a \fICURLoption\fP \fBid\fP, this function returns a pointer to the
\fIcurl_easyoption\fP struct, holding information about the
\fIcurl_easy_setopt(3)\fP option using that id. The option id is the CURLOPT_
prefix ones provided in the standard curl/curl.h header file. This function
will return the non-aliases version for the cases where there is an alias
function as well.
returns the non-alias version of the cases where there is an alias function as
well.
If libcurl has no option with the given id, this function returns NULL.
.SH EXAMPLE

46
docs/libcurl/curl_easy_pause.3
View file

@ -38,8 +38,8 @@ A connection can be paused by using this function or by letting the read or
the write callbacks return the proper magic return code
(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback
that returns pause signals to the library that it could not take care of any
data at all, and that data will then be delivered again to the callback when
the transfer is unpaused.
data at all, and that data is then delivered again to the callback when the
transfer is unpaused.
While it may feel tempting, take care and notice that you cannot call this
function from another thread. To unpause, you may for example call it from the
@ -47,27 +47,27 @@ progress callback (\fICURLOPT_PROGRESSFUNCTION(3)\fP).
When this function is called to unpause receiving, the write callback might
get called before this function returns to deliver cached content. When
libcurl delivers such cached data to the write callback, it will be delivered
as fast as possible, which may overstep the boundary set in
libcurl delivers such cached data to the write callback, it is delivered as
fast as possible, which may overstep the boundary set in
\fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP etc.
The \fBhandle\fP argument identifies the transfer you want to pause or
unpause.
A paused transfer is excluded from low speed cancels via the
\fICURLOPT_LOW_SPEED_LIMIT(3)\fP option and unpausing a transfer will reset
the time period required for the low speed limit to be met.
\fICURLOPT_LOW_SPEED_LIMIT(3)\fP option and unpausing a transfer resets the
time period required for the low speed limit to be met.
The \fBbitmask\fP argument is a set of bits that sets the new state of the
connection. The following bits can be used:
.IP CURLPAUSE_RECV
Pause receiving data. There will be no data received on this connection until
this function is called again without this bit set. Thus, the write callback
(\fICURLOPT_WRITEFUNCTION(3)\fP) will not be called.
Pause receiving data. There is no data received on this connection until this
function is called again without this bit set. Thus, the write callback
(\fICURLOPT_WRITEFUNCTION(3)\fP) is not called.
.IP CURLPAUSE_SEND
Pause sending data. There will be no data sent on this connection until this
Pause sending data. There is no data sent on this connection until this
function is called again without this bit set. Thus, the read callback
(\fICURLOPT_READFUNCTION(3)\fP) will not be called.
(\fICURLOPT_READFUNCTION(3)\fP) is not called.
.IP CURLPAUSE_ALL
Convenience define that pauses both directions.
.IP CURLPAUSE_CONT
@ -75,37 +75,37 @@ Convenience define that unpauses both directions.
.SH LIMITATIONS
The pausing of transfers does not work with protocols that work without
network connectivity, like FILE://. Trying to pause such a transfer, in any
direction, will cause problems in the worst case or an error in the best case.
direction, might cause problems or error.
.SH MULTIPLEXED
When a connection is used multiplexed, like for HTTP/2, and one of the
transfers over the connection is paused and the others continue flowing,
libcurl might end up buffering contents for the paused transfer. It has to do
this because it needs to drain the socket for the other transfers and the
already announced window size for the paused transfer will allow the server to
already announced window size for the paused transfer allows the server to
continue sending data up to that window size amount. By default, libcurl
announces a 32 megabyte window size, which thus can make libcurl end up
buffering 32 megabyte of data for a paused stream.
When such a paused stream is unpaused again, any buffered data will be
delivered first.
When such a paused stream is unpaused again, any buffered data is delivered
first.
.SH EXAMPLE
.nf
/* pause a transfer in both directions */
curl_easy_pause(curl, CURL_READFUNC_PAUSE | CURL_WRITEFUNC_PAUSE);
.fi
.SH "MEMORY USE"
When pausing a read by returning the magic return code from a write callback,
the read data is already in libcurl's internal buffers so it will have to keep
it in an allocated buffer until the receiving is again unpaused using this
function.
When pausing a download transfer by returning the magic return code from a
write callback, the read data is already in libcurl's internal buffers so it
has to keep it in an allocated buffer until the receiving is again unpaused
using this function.
If the downloaded data is compressed and is asked to get uncompressed
automatically on download, libcurl will continue to uncompress the entire
downloaded chunk and it will cache the data uncompressed. This has the side-
automatically on download, libcurl continues to uncompress the entire
downloaded chunk and it caches the data uncompressed. This has the side-
effect that if you download something that is compressed a lot, it can result
in a large data amount needing to be allocated to save the data during the
pause. This said, you should probably consider not using paused receiving if
you allow libcurl to uncompress data automatically.
pause. consider not using paused receiving if you allow libcurl to uncompress
data automatically.
.SH AVAILABILITY
Added in 7.18.0.
.SH RETURN VALUE

20
docs/libcurl/curl_easy_perform.3
View file

@ -31,22 +31,22 @@ curl_easy_perform - perform a blocking file transfer
CURLcode curl_easy_perform(CURL *easy_handle);
.fi
.SH DESCRIPTION
\fIcurl_easy_perform(3)\fP performs a network transfer in a blocking manner
and returns when done, or earlier if it fails. For non-blocking behavior, see
\fIcurl_multi_perform(3)\fP.
Invoke this function after \fIcurl_easy_init(3)\fP and all the
\fIcurl_easy_setopt(3)\fP calls are made, and it performs the transfer as
described in the options. It must be called with the same \fBeasy_handle\fP as
input as the \fIcurl_easy_init(3)\fP call returned.
\fIcurl_easy_perform(3)\fP performs the entire request in a blocking manner
and returns when done, or earlier if it fails. For non-blocking behavior, see
\fIcurl_multi_perform(3)\fP.
You can do any amount of calls to \fIcurl_easy_perform(3)\fP while using the
same \fBeasy_handle\fP. If you intend to transfer more than one file, you are
even encouraged to do so. libcurl will then attempt to re-use the same
connection for the following transfers, thus making the operations faster,
less CPU intense and using less network resources. Just note that you will
have to use \fIcurl_easy_setopt(3)\fP between the invokes to set options for
the following curl_easy_perform.
even encouraged to do so. libcurl attempts to reuse existing connections for
the following transfers, thus making the operations faster, less CPU intense
and using less network resources. You probably want to use
\fIcurl_easy_setopt(3)\fP between the invokes to set options for the following
curl_easy_perform call.
You must never call this function simultaneously from two places using the
same \fBeasy_handle\fP. Let the function return first before invoking it
@ -77,7 +77,7 @@ Always
CURLE_OK (0) means everything was OK, non-zero means an error occurred as
.I <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
set with \fIcurl_easy_setopt(3)\fP there is a readable error message stored in
the error buffer when non-zero is returned.
.SH "SEE ALSO"
.BR curl_easy_init "(3), " curl_easy_setopt "(3), "

24
docs/libcurl/curl_easy_recv.3
View file

@ -35,23 +35,22 @@ CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n);
This function receives raw data from the established connection. You may use
it together with \fIcurl_easy_send(3)\fP to implement custom protocols using
libcurl. This functionality can be particularly useful if you use proxies
and/or SSL encryption: libcurl will take care of proxy negotiation and
connection setup.
and/or SSL encryption: libcurl takes care of proxy negotiation and connection
setup.
\fBbuffer\fP is a pointer to your buffer that will get the received
data. \fBbuflen\fP is the maximum amount of data you can get in that
buffer. The variable \fBn\fP points to will receive the number of received
bytes.
\fBbuffer\fP is a pointer to your buffer memory that gets populated by the
received data. \fBbuflen\fP is the maximum amount of data you can get in that
buffer. The variable \fBn\fP points to receives the number of received bytes.
To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before
calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that
\fIcurl_easy_recv(3)\fP does not work on connections that were created without
this option.
The call will return \fBCURLE_AGAIN\fP if there is no data to read - the
socket is used in non-blocking mode internally. When \fBCURLE_AGAIN\fP is
returned, use your operating system facilities like \fIselect(2)\fP to wait
for data. The socket may be obtained using \fIcurl_easy_getinfo(3)\fP with
The call returns \fBCURLE_AGAIN\fP if there is no data to read - the socket is
used in non-blocking mode internally. When \fBCURLE_AGAIN\fP is returned, use
your operating system facilities like \fIselect(2)\fP to wait for data. The
socket may be obtained using \fIcurl_easy_getinfo(3)\fP with
\fICURLINFO_ACTIVESOCKET(3)\fP.
Wait on the socket only if \fIcurl_easy_recv(3)\fP returns \fBCURLE_AGAIN\fP.
@ -70,8 +69,7 @@ read was for internal SSL processing, and no other data is available.
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
/* Extract the socket from the curl handle -
we will need it for waiting. */
/* Extract the socket from the curl handle - we need it for waiting. */
res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
/* read data */
@ -91,7 +89,7 @@ system facilities to wait until data can be read, and retry.
Reading exactly 0 bytes indicates a closed connection.
If there's no socket available to use from the previous transfer, this function
If there is no socket available to use from the previous transfer, this function
returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), " curl_easy_perform "(3), "

23
docs/libcurl/curl_easy_send.3
View file

@ -36,22 +36,22 @@ CURLcode curl_easy_send(CURL *curl, const void *buffer,
This function sends arbitrary data over the established connection. You may
use it together with \fIcurl_easy_recv(3)\fP to implement custom protocols
using libcurl. This functionality can be particularly useful if you use
proxies and/or SSL encryption: libcurl will take care of proxy negotiation and
proxies and/or SSL encryption: libcurl takes care of proxy negotiation and
connection setup.
\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want sent.
The variable \fBn\fP points to will receive the number of sent bytes.
\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want
sent. The variable \fBn\fP points to receives the number of sent bytes.
To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before
calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that
\fIcurl_easy_send(3)\fP will not work on connections that were created without
\fIcurl_easy_send(3)\fP does not work on connections that were created without
this option.
The call will return \fBCURLE_AGAIN\fP if it's not possible to send data right
now - the socket is used in non-blocking mode internally. When
\fBCURLE_AGAIN\fP is returned, use your operating system facilities like
\fIselect(2)\fP to wait until the socket is writable. The socket may be
obtained using \fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP.
The call returns \fBCURLE_AGAIN\fP if it's not possible to send data right now
- the socket is used in non-blocking mode internally. When \fBCURLE_AGAIN\fP
is returned, use your operating system facilities like \fIselect(2)\fP to wait
until the socket is writable. The socket may be obtained using
\fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP.
Furthermore if you wait on the socket and it tells you it's writable,
\fIcurl_easy_send(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was
@ -64,8 +64,7 @@ sent was for internal SSL processing, and no other data could be sent.
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
/* Extract the socket from the curl handle -
we will need it for waiting. */
/* Extract the socket from the curl handle - we need it for waiting. */
res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
/* send data */
@ -84,7 +83,7 @@ On failure, returns the appropriate error code.
This function may return \fBCURLE_AGAIN\fP. In this case, use your operating
system facilities to wait until the socket is writable, and retry.
If there's no socket available to use from the previous transfer, this function
If there is no socket available to use from the previous transfer, this function
returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), " curl_easy_perform "(3), " curl_easy_getinfo "(3), "

7
docs/libcurl/curl_easy_setopt.3
View file

@ -513,7 +513,7 @@ Maximum number of connections in the connection pool. See \fICURLOPT_MAXCONNECTS
.IP CURLOPT_FRESH_CONNECT
Use a new connection. \fICURLOPT_FRESH_CONNECT(3)\fP
.IP CURLOPT_FORBID_REUSE
Prevent subsequent connections from re-using this. See \fICURLOPT_FORBID_REUSE(3)\fP
Prevent subsequent connections from reusing this. See \fICURLOPT_FORBID_REUSE(3)\fP
.IP CURLOPT_MAXAGE_CONN
Limit the age (idle time) of connections for reuse. See \fICURLOPT_MAXAGE_CONN(3)\fP
.IP CURLOPT_MAXLIFETIME_CONN
@ -733,9 +733,8 @@ is invalid, like perhaps out of range.
If you try to set an option that libcurl does not know about, perhaps because
the library is too old to support it or the option was removed in a recent
version, this function will return \fICURLE_UNKNOWN_OPTION\fP. If support for
the option was disabled at compile-time, it will return
\fICURLE_NOT_BUILT_IN\fP.
version, this function returns \fICURLE_UNKNOWN_OPTION\fP. If support for the
option was disabled at compile-time, it returns \fICURLE_NOT_BUILT_IN\fP.
.SH "SEE ALSO"
.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3), "
.BR curl_easy_getinfo "(3), " curl_multi_setopt "(3), "

2
docs/libcurl/curl_easy_strerror.3
View file

@ -38,7 +38,7 @@ Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more
specific error descriptions generated at runtime.
.SH EXAMPLE
.nf
/* Perform the request, res will get the return code */
/* Perform the entire transfer */
res = curl_easy_perform(curl);
/* Check for errors */
if(res != CURLE_OK)

12
docs/libcurl/curl_easy_unescape.3
View file

@ -39,13 +39,13 @@ encoded (%XX where XX is a two-digit hexadecimal number) are converted to their
binary versions.
If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP
will use strlen() on \fBinput\fP to find out the size.
uses strlen() on \fBinput\fP to find out the size.
If \fBoutlength\fP is non-NULL, the function will write the length of the
returned string in the integer it points to. This allows proper handling even
for strings containing %00. Since this is a pointer to an \fIint\fP type, it
can only return a value up to \fIINT_MAX\fP so no longer string can be
returned in this parameter.
If \fBoutlength\fP is non-NULL, the function writes the length of the returned
string in the integer it points to. This allows proper handling even for
strings containing %00. Since this is a pointer to an \fIint\fP type, it can
only return a value up to \fIINT_MAX\fP so no longer string can be returned in
this parameter.
Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was
per-handle character conversion support for some very old operating systems

14
docs/libcurl/curl_escape.3
View file

@ -33,13 +33,13 @@ char *curl_escape(const char *string, int length);
.SH DESCRIPTION
Obsolete function. Use \fIcurl_easy_escape(3)\fP instead!
This function will convert the given input \fBstring\fP to a URL encoded string
This function converts the given input \fBstring\fP to a URL encoded string
and return that as a new allocated string. All input characters that are not
a-z, A-Z or 0-9 will be converted to their "URL escaped" version (\fB%NN\fP
where \fBNN\fP is a two-digit hexadecimal number).
a-z, A-Z or 0-9 are converted to their "URL escaped" version (\fB%NN\fP where
\fBNN\fP is a two-digit hexadecimal number).
If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP will use
strlen() on \fBstring\fP to find out the size.
If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP uses strlen()
on \fBstring\fP to find out the size.
You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH EXAMPLE
@ -51,8 +51,8 @@ if(output) {
}
.fi
.SH AVAILABILITY
Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function will
be removed in a future release.
Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function might be
removed in a future release.
.SH RETURN VALUE
A pointer to a null-terminated string or NULL if it failed.
.SH "SEE ALSO"

55
docs/libcurl/curl_formadd.3
View file

@ -44,9 +44,9 @@ allow repeated invokes to find the end of the list faster.
After the \fIlastitem\fP pointer follow the real arguments.
The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to
NULL in the first call to this function. All list-data will be allocated by
the function itself. You must call \fIcurl_formfree(3)\fP on the
\fIfirstitem\fP after the form post has been done to free the resources.
NULL in the first call to this function. All list-data is allocated by the
function itself. You must call \fIcurl_formfree(3)\fP on the \fIfirstitem\fP
after the form post has been done to free the resources.
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
@ -54,8 +54,8 @@ You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
First, there are some basics you need to understand about multipart form
posts. Each part consists of at least a NAME and a CONTENTS part. If the part
is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
Below, we will discuss what options you use to set these properties in the
parts you want to add to your post.
Below, we discuss what options you use to set these properties in the parts
you want to add to your post.
The options listed first are for making normal parts. The options from
\fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload
@ -66,34 +66,33 @@ followed by a string which provides the \fIname\fP of this part. libcurl
copies the string so your application does not need to keep it around after
this function call. If the name is not null-terminated, you must set its
length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to
contain zero-valued bytes. The copied data will be freed by
\fIcurl_formfree(3)\fP.
contain zero-valued bytes. The copied data is freed by \fIcurl_formfree(3)\fP.
.IP CURLFORM_PTRNAME
followed by a string which provides the \fIname\fP of this part. libcurl
will use the pointer and refer to the data in your application, so you
must make sure it remains until curl no longer needs it. If the name
is not null-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
The \fIname\fP is not allowed to contain zero-valued bytes.
followed by a string which provides the \fIname\fP of this part. libcurl uses
the pointer and refer to the data in your application, so you must make sure
it remains until curl no longer needs it. If the name is not null-terminated,
you must set its length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not
allowed to contain zero-valued bytes.
.IP CURLFORM_COPYCONTENTS
followed by a pointer to the contents of this part, the actual data
to send away. libcurl copies the provided data, so your application does not
need to keep it around after this function call. If the data is not null
terminated, or if you would like it to contain zero bytes, you must
set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied
data will be freed by \fIcurl_formfree(3)\fP.
followed by a pointer to the contents of this part, the actual data to send
away. libcurl copies the provided data, so your application does not need to
keep it around after this function call. If the data is not null terminated,
or if you would like it to contain zero bytes, you must set the length of the
name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied data is freed by
\fIcurl_formfree(3)\fP.
.IP CURLFORM_PTRCONTENTS
followed by a pointer to the contents of this part, the actual data to send
away. libcurl will use the pointer and refer to the data in your application,
so you must make sure it remains until curl no longer needs it. If the data
is not null-terminated, or if you would like it to contain zero bytes, you
must set its length with \fBCURLFORM_CONTENTSLENGTH\fP.
away. libcurl uses the pointer and refer to the data in your application, so
you must make sure it remains until curl no longer needs it. If the data is
not null-terminated, or if you would like it to contain zero bytes, you must
set its length with \fBCURLFORM_CONTENTSLENGTH\fP.
.IP CURLFORM_CONTENTLEN
followed by a curl_off_t value giving the length of the contents. Note that
for \fICURLFORM_STREAM\fP contents, this option is mandatory.
If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
the contents to figure out the size. If you really want to send a zero byte
content then you must make sure strlen() on the data pointer returns zero.
If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents
to figure out the size. If you really want to send a zero byte content then
you must make sure strlen() on the data pointer returns zero.
(Option added in 7.46.0)
.IP CURLFORM_CONTENTSLENGTH
@ -102,9 +101,9 @@ content then you must make sure strlen() on the data pointer returns zero.
followed by a long giving the length of the contents. Note that for
\fICURLFORM_STREAM\fP contents, this option is mandatory.
If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
the contents to figure out the size. If you really want to send a zero byte
content then you must make sure strlen() on the data pointer returns zero.
If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents
to figure out the size. If you really want to send a zero byte content then
you must make sure strlen() on the data pointer returns zero.
.IP CURLFORM_FILECONTENT
followed by a filename, causes that file to be read and its contents used
as data in this part. This part does \fInot\fP automatically become a file

4
docs/libcurl/curl_formfree.3
View file

@ -44,8 +44,8 @@ the \fIcurl_formadd(3)\fP invoke(s).
\fBform\fP is the pointer as returned from a previous call to
\fIcurl_formadd(3)\fP and may be NULL.
Passing in a NULL pointer in \fIform\fP will make this function return
immediately with no action.
Passing in a NULL pointer in \fIform\fP makes this function return immediately
with no action.
.SH EXAMPLE
.nf
/* Fill in a file upload field */

15
docs/libcurl/curl_formget.3
View file

@ -33,19 +33,20 @@ int curl_formget(struct curl_httppost * form, void *userp,
.SH DESCRIPTION
curl_formget() is used to serialize data previously built/appended with
\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument named
\fIuserp\fP which will be passed as the first argument to the
curl_formget_callback function.
\fIuserp\fP which is passed as the first argument to the curl_formget_callback
function.
.BI "typedef size_t (*curl_formget_callback)(void *" userp, " const char *" buf,
.BI " size_t " len ");"
The curl_formget_callback will be executed for each part of the HTTP POST
chain. The character buffer passed to the callback must not be freed. The
callback should return the buffer length passed to it on success.
The curl_formget_callback is invoked for each part of the HTTP POST chain. The
character buffer passed to the callback must not be freed. The callback should
return the buffer length passed to it on success.
If the \fBCURLFORM_STREAM\fP option is used in the formpost, it will prevent
If the \fBCURLFORM_STREAM\fP option is used in the formpost, it prevents
\fIcurl_formget(3)\fP from working until you have performed the actual HTTP
request as only then will libcurl get the actual read callback to use!
request. This, because first then does libcurl known which actual read
callback to use!
.SH EXAMPLE
.nf
size_t print_httppost_callback(void *arg, const char *buf, size_t len)

4
docs/libcurl/curl_free.3
View file

@ -35,8 +35,8 @@ curl_free reclaims memory that has been obtained through a libcurl call. Use
\fIcurl_free(3)\fP instead of free() to avoid anomalies that can result from
differences in memory management between your application and libcurl.
Passing in a NULL pointer in \fIptr\fP will make this function return
immediately with no action.
Passing in a NULL pointer in \fIptr\fP makes this function return immediately
with no action.
.SH EXAMPLE
.nf
char *width = curl_getenv("COLUMNS");

10
docs/libcurl/curl_getdate.3
View file

@ -51,8 +51,8 @@ digits. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6.
.TP
.B time of the day items
This string specifies the time on a given day. You must specify it with 6
digits with two colons: HH:MM:SS. To not include the time in a date string,
will make the function assume 00:00:00. Example: 18:19:21.
digits with two colons: HH:MM:SS. If there is no time given in a provided date
string, 00:00:00 is assumed. Example: 18:19:21.
.TP
.B time zone items
Specifies international time zone. There are a few acronyms supported, but in
@ -107,13 +107,13 @@ This function returns -1 when it fails to parse the date string. Otherwise it
returns the number of seconds as described.
On systems with a signed 32 bit time_t: if the year is larger than 2037 or
less than 1903, this function will return -1.
less than 1903, this function returns -1.
On systems with an unsigned 32 bit time_t: if the year is larger than 2106 or
less than 1970, this function will return -1.
less than 1970, this function returns -1.
On systems with 64 bit time_t: if the year is less than 1583, this function
will return -1. (The Gregorian calendar was first introduced 1582 so no "real"
returns -1. (The Gregorian calendar was first introduced 1582 so no "real"
dates in this way of doing dates existed before then.)
.SH "SEE ALSO"
.BR curl_easy_escape "(3), " curl_easy_unescape "(3), "

5
docs/libcurl/curl_getenv.3
View file

@ -51,8 +51,7 @@ A pointer to a null-terminated string or NULL if it failed to find the
specified name.
.SH NOTE
Under unix operating systems, there is no point in returning an allocated
memory, although other systems will not work properly if this is not done. The
unix implementation thus has to suffer slightly from the drawbacks of other
systems.
memory, although other systems does not work properly if this is not done. The
unix implementation thus suffers slightly from the drawbacks of other systems.
.SH "SEE ALSO"
.BR getenv "(3C), "

10
docs/libcurl/curl_global_init.3
View file

@ -87,18 +87,18 @@ Initialize the Win32 socket libraries.
The implication here is that if this bit is not set, the initialization of
winsock has to be done by the application or you risk getting undefined
behaviors. This option exists for when the initialization is handled outside
of libcurl so there's no need for libcurl to do it again.
of libcurl so there is no need for libcurl to do it again.
.IP CURL_GLOBAL_NOTHING
Initialize nothing extra. This sets no bit.
.IP CURL_GLOBAL_DEFAULT
A sensible default. It will init both SSL and Win32. Right now, this equals
A sensible default. It initializes both SSL and Win32. Right now, this equals
the functionality of the \fBCURL_GLOBAL_ALL\fP mask.
.IP CURL_GLOBAL_ACK_EINTR
This bit has no point since 7.69.0 but its behavior is instead the default.
Before 7.69.0: when this flag is set, curl will acknowledge EINTR condition
when connecting or when waiting for data. Otherwise, curl waits until full
timeout elapses. (Added in 7.30.0)
Before 7.69.0: when this flag is set, curl acknowledges EINTR condition when
connecting or when waiting for data. Otherwise, curl waits until full timeout
elapses. (Added in 7.30.0)
.SH EXAMPLE
.nf
curl_global_init(CURL_GLOBAL_DEFAULT);

10
docs/libcurl/curl_global_sslset.3
View file

@ -62,15 +62,15 @@ must be called \fBbefore\fP \fIcurl_global_init(3)\fP.
The backend can be identified by the \fIid\fP
(e.g. \fBCURLSSLBACKEND_OPENSSL\fP). The backend can also be specified via the
\fIname\fP parameter for a case insensitive match (passing -1 as \fIid\fP). If
both \fIid\fP and \fIname\fP are specified, the \fIname\fP will be ignored.
both \fIid\fP and \fIname\fP are specified, the \fIname\fP is ignored.
If neither \fIid\fP nor \fPname\fP are specified, the function will fail with
If neither \fIid\fP nor \fPname\fP are specified, the function fails with
\fBCURLSSLSET_UNKNOWN_BACKEND\fP and set the \fIavail\fP pointer to the
NULL-terminated list of available backends. The available backends are those
that this particular build of libcurl supports.
Since libcurl 7.60.0, the \fIavail\fP pointer will always be set to the list
of alternatives if non-NULL.
Since libcurl 7.60.0, the \fIavail\fP pointer is always set to the list of
alternatives if non-NULL.
Upon success, the function returns \fBCURLSSLSET_OK\fP.
@ -80,7 +80,7 @@ NULL-terminated list of available SSL backends. In this case, you may call the
function again to try to select a different backend.
The SSL backend can be set only once. If it has already been set, a subsequent
attempt to change it will result in a \fBCURLSSLSET_TOO_LATE\fP.
attempt to change it results in a \fBCURLSSLSET_TOO_LATE\fP getting returned.
This function is thread-safe since libcurl 7.84.0 if
\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set

16
docs/libcurl/curl_global_trace.3
View file

@ -61,11 +61,11 @@ are case-insensitive and unknown names are ignored. The special name "all"
applies to all components. Names may be prefixed with '+' or '-' to enable
or disable detailed logging for a component.
The list of component names is not part of curl's public API. Names may
be added or disappear in future versions of libcurl. Since unknown names
are silently ignored, outdated log configurations will not error when
upgrading libcurl. Given that, some names can be expected to be fairly
stable and are listed below for easy reference.
The list of component names is not part of curl's public API. Names may be
added or disappear in future versions of libcurl. Since unknown names are
silently ignored, outdated log configurations does not cause errors when
upgrading libcurl. Given that, some names can be expected to be fairly stable
and are listed below for easy reference.
Note that log configuration applies only to transfers where debug logging
is enabled. See \fICURLOPT_VERBOSE(3)\fP or \fICURLOPT_DEBUGFUNCTION(3)\fP
@ -85,9 +85,9 @@ Involved when transfers are tunneled through a HTTP proxy. "h1-proxy" or
"h2-proxy" are also involved, depending on the HTTP version negotiated with
the proxy.
In order to find out all components involved in
a transfer, run it with "all" configured. You will then see all names
involved in your libcurl version in the trace.
In order to find out all components involved in a transfer, run it with "all"
configured. You can then see all names involved in your libcurl version in the
trace.
.SH EXAMPLE
.nf

34
docs/libcurl/curl_mime_data_cb.3
View file

@ -49,13 +49,13 @@ from a data read callback function.
as shown by the above prototype. It may not be set to NULL.
\fIseekfunc\fP is a pointer to a seek callback function, with a signature as
shown by the above prototype. This function will be used upon resending data
(i.e.: after a redirect); this pointer may be set to NULL, in which case a
resend is not possible.
shown by the above prototype. This function is used when resending data (i.e.:
after a redirect); this pointer may be set to NULL, in which case a resend
might not be not possible.
\fIfreefunc\fP is a pointer to a user resource freeing callback function, with
a signature as shown by the above prototype. If no resource is to be freed, it
may safely be set to NULL. This function will be called upon mime structure
may safely be set to NULL. This function is called upon mime structure
freeing.
\fIarg\fP is a user defined argument to callback functions.
@ -67,13 +67,13 @@ should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number
of bytes by your function.
Your read function must then return the actual number of bytes that it stored
in that memory area. Returning 0 will signal end-of-file to the library and
cause it to stop the current transfer.
in that memory area. Returning 0 signals end-of-file to the library and cause
it to stop the current transfer.
If you stop the current transfer by returning 0 "pre-maturely" (i.e. before the
server expected it, like when you have said you will upload N bytes and you
upload less than N bytes), you may experience that the server "hangs" waiting
for the rest of the data that will not come.
If you stop the current transfer by returning 0 "pre-maturely" (i.e. before
the server expected it, like when you have said you intend to upload N bytes
and yet you upload less than N bytes), you may experience that the server
"hangs" waiting for the rest of the data that does not come.
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
@ -95,14 +95,14 @@ done by instead reading from the input or similar.
Care must be taken if the part is bound to a curl easy handle that is later
duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in
the pointed item to be shared between the original and the copied handle.
In particular, special attention should be given to the \fIfreefunc\fP
procedure code since it will be called twice with the same argument.
the pointed item to be shared between the original and the copied handle. In
particular, special attention should be given to the \fIfreefunc\fP procedure
code since it then gets called twice with the same argument.
.SH EXAMPLE
Sending a huge data string will cause the same amount of memory to be
allocated: to avoid overhead resources consumption, one might want to use a
callback source to avoid data duplication. In this case, original data
must be retained until after the transfer terminates.
Sending a huge data string causes the same amount of memory to be allocated:
to avoid overhead resources consumption, one might want to use a callback
source to avoid data duplication. In this case, original data must be retained
until after the transfer terminates.
.nf
char hugedata[512000];

4
docs/libcurl/curl_mime_filedata.3
View file

@ -51,8 +51,8 @@ manner to allow huge files to get transferred without using much memory. It
therefore requires that the file is kept intact during the entire request.
If the file size cannot be determined before actually reading it (such as for
a device or named pipe), the whole mime structure containing the part
will be transferred as chunks by HTTP and rejected by IMAP.
a character device or named pipe), the whole mime structure containing the
part is transferred using chunks by HTTP but is rejected by IMAP.
Setting a part's contents multiple times is valid: only the value set by the
last call is retained.

4
docs/libcurl/curl_mime_free.3
View file

@ -43,8 +43,8 @@ are by the top structure freeing.
\fBmime\fP is the handle as returned from a previous call to
\fIcurl_mime_init(3)\fP and may be NULL.
Passing in a NULL pointer in \fImime\fP will make this function return
immediately with no action.
Passing in a NULL pointer in \fImime\fP makes this function return immediately
with no action.
.SH EXAMPLE
.nf
/* Build the mime message. */

4
docs/libcurl/curl_mprintf.3
View file

@ -136,7 +136,7 @@ overrides a space if both are used.
.SH "Field width"
An optional decimal digit string (with nonzero first digit) specifying a
minimum field width. If the converted value has fewer characters than the
field width, it will be padded with spaces on the left (or right, if the
field width, it gets padded with spaces on the left (or right, if the
left-adjustment flag has been given). Instead of a decimal digit string one
may write "*" or "*m$" (for some decimal integer m) to specify that the field
width is given in the next argument, or in the \fIm-th\fP argument,
@ -241,7 +241,7 @@ A '%' is written. No argument is converted.
curl_mprintf("Pi is almost %f\\n", 25/8);
.fi
.SH AVAILABILITY
These functions will be removed from the public libcurl API in the future. Do
These functions might be removed from the public libcurl API in the future. Do
not use them in new programs or projects.
.SH RETURN VALUE
The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to

30
docs/libcurl/curl_multi_add_handle.3
View file

@ -31,32 +31,30 @@ curl_multi_add_handle - add an easy handle to a multi session
CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle);
.fi
.SH DESCRIPTION
Adds a standard easy handle to the multi stack. This function call will make
this \fImulti_handle\fP control the specified \fIeasy_handle\fP.
Adds the \fIeasy handle\fP to the \fImulti_handle\fP.
While an easy handle is added to a multi stack, you cannot and you must not
use \fIcurl_easy_perform(3)\fP on that handle. After having removed the easy
handle from the multi stack again, it is perfectly fine to use it with the
easy interface again.
If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) or
global DNS cache (\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP), it will be made to
use the DNS cache that is shared between all easy handles within the multi
handle when \fIcurl_multi_add_handle(3)\fP is called.
If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) cache,
it is made to use a DNS cache that is shared between all easy handles within
the multi handle when \fIcurl_multi_add_handle(3)\fP is called.
When an easy interface is added to a multi handle, it will use a shared
When an easy interface is added to a multi handle, it is set to use a shared
connection cache owned by the multi handle. Removing and adding new easy
handles will not affect the pool of connections or the ability to do
connection re-use.
handles does not affect the pool of connections or the ability to do
connection reuse.
If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (and you
really should if you are working event-based with
\fIcurl_multi_socket_action(3)\fP and friends), that callback will be called
from within this function to ask for an updated timer so that your main event
loop will get the activity on this handle to get started.
If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (as you
should if you are working event-based with \fIcurl_multi_socket_action(3)\fP
and friends), that callback is called from within this function to ask for an
updated timer so that your main event loop gets the activity on this handle to
get started.
The easy handle will remain added to the multi handle until you remove it
again with \fIcurl_multi_remove_handle(3)\fP - even when a transfer with that
The easy handle remains added to the multi handle until you remove it again
with \fIcurl_multi_remove_handle(3)\fP - even when a transfer with that
specific easy handle is completed.
You should remove the easy handle from the multi stack before you terminate

18
docs/libcurl/curl_multi_assign.3
View file

@ -36,20 +36,20 @@ This function creates an association in the multi handle between the given
socket and a private pointer of the application. This is designed for
\fIcurl_multi_socket_action(3)\fP uses.
When set, the \fIsockptr\fP pointer will be passed to all future socket
callbacks for the specific \fIsockfd\fP socket.
When set, the \fIsockptr\fP pointer is passed to all future socket callbacks
for the specific \fIsockfd\fP socket.
If the given \fIsockfd\fP is not already in use by libcurl, this function will
return an error.
If the given \fIsockfd\fP is not already in use by libcurl, this function
returns an error.
libcurl only keeps one single pointer associated with a socket, so calling
this function several times for the same socket will make the last set pointer
get used.
this function several times for the same socket makes the last set pointer get
used.
The idea here being that this association (socket to private pointer) is
something that just about every application that uses this API will need and
then libcurl can just as well do it since it already has an internal hash
table lookup for this.
something that just about every application that uses this API needs and then
libcurl can just as well do it since it already has the necessary
functionality.
It is acceptable to call this function from your multi callback functions.
.SH EXAMPLE

2
docs/libcurl/curl_multi_cleanup.3
View file

@ -44,7 +44,7 @@ handle is no longer connected to the multi handle
3 - \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are
removed
Passing in a NULL pointer in \fImulti_handle\fP will make this function return
Passing in a NULL pointer in \fImulti_handle\fP makes this function return
CURLM_BAD_HANDLE immediately with no other action.
.SH EXAMPLE
.nf

24
docs/libcurl/curl_multi_fdset.3
View file

@ -54,13 +54,13 @@ If the \fIexc_fd_set\fP argument is not a null pointer, it points to an object
of type \fBfd_set\fP that on return specifies the file descriptors to be
checked for error conditions pending.
If no file descriptors are set by libcurl, \fImax_fd\fP will contain -1 when
this function returns. Otherwise it will contain the highest descriptor number
libcurl set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl
currently does something that is not possible for your application to monitor
with a socket and unfortunately you can then not know exactly when the current
action is completed using select(). You then need to wait a while before you
proceed and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless
If no file descriptors are set by libcurl, \fImax_fd\fP contain -1 when this
function returns. Otherwise it contains the highest descriptor number libcurl
set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl currently
does something that is not possible for your application to monitor with a
socket and unfortunately you can then not know exactly when the current action
is completed using select(). You then need to wait a while before you proceed
and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless
\fIcurl_multi_timeout(3)\fP gives you a lower number, we suggest 100
milliseconds or so, but you may want to test it out in your own particular
conditions to find a suitable value.
@ -73,11 +73,11 @@ want.
If one of the sockets used by libcurl happens to be larger than what can be
set in an \fBfd_set\fP, which on POSIX systems means that the file descriptor
is larger than \fBFD_SETSIZE\fP, then libcurl will try to not set it. Setting
a too large file descriptor in an \fBfd_set\fP implies an out of bounds write
which can cause crashes, or worse. The effect of NOT storing it will possibly
save you from the crash, but will make your program NOT wait for sockets it
should wait for...
is larger than \fBFD_SETSIZE\fP, then libcurl tries to not set it. Setting a
too large file descriptor in an \fBfd_set\fP implies an out of bounds write
which can cause crashes, or worse. The effect of NOT storing it might possibly
save you from the crash, but makes your program NOT wait for sockets it should
wait for...
.SH EXAMPLE
.nf
/* get file descriptors from the transfers */

16
docs/libcurl/curl_multi_info_read.3
View file

@ -36,17 +36,17 @@ transfers. Messages may include information such as an error code from the
transfer or just the fact that a transfer is completed. More details on these
should be written down as well.
Repeated calls to this function will return a new struct each time, until a
NULL is returned as a signal that there is no more to get at this point. The
integer pointed to with \fImsgs_in_queue\fP will contain the number of
remaining messages after this function was called.
Repeated calls to this function returns a new struct each time, until a NULL
is returned as a signal that there is no more to get at this point. The
integer pointed to with \fImsgs_in_queue\fP contains the number of remaining
messages after this function was called.
When you fetch a message using this function, it is removed from the internal
queue so calling this function again will not return the same message
again. It will instead return new messages at each new invoke until the queue
is emptied.
queue so calling this function again does not return the same message
again. It instead returns new messages at each new invoke until the queue is
emptied.
\fBWARNING:\fP The data the returned pointer points to will not survive
\fBWARNING:\fP The data the returned pointer points to does not survive
calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or
\fIcurl_easy_cleanup(3)\fP.

8
docs/libcurl/curl_multi_perform.3
View file

@ -35,13 +35,13 @@ This function performs transfers on all the added handles that need attention
in a non-blocking fashion. The easy handles have previously been added to the
multi handle with \fIcurl_multi_add_handle(3)\fP.
When an application has found out there's data available for the multi_handle
When an application has found out there is data available for the multi_handle
or a timeout has elapsed, the application should call this function to
read/write whatever there is to read or write right now etc.
\fIcurl_multi_perform(3)\fP returns as soon as the reads/writes are done. This
function does not require that there actually is any data available for
reading or that data can be written, it can be called just in case. It will
store the number of handles that still transfer data in the second argument's
reading or that data can be written, it can be called just in case. It stores
the number of handles that still transfer data in the second argument's
integer-pointer.
If the amount of \fIrunning_handles\fP is changed from the previous call (or
@ -88,7 +88,7 @@ individual transfers may have occurred even when this function returns
\fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure out how individual
transfers did.
.SH "TYPICAL USAGE"
Most applications will use \fIcurl_multi_poll(3)\fP to make libcurl wait for
Most applications use \fIcurl_multi_poll(3)\fP to make libcurl wait for
activity on any of the ongoing transfers. As soon as one or more file
descriptor has activity or the function times out, the application calls
\fIcurl_multi_perform(3)\fP.

23
docs/libcurl/curl_multi_poll.3
View file

@ -36,20 +36,20 @@ CURLMcode curl_multi_poll(CURLM *multi_handle,
.ad
.SH DESCRIPTION
\fIcurl_multi_poll(3)\fP polls all file descriptors used by the curl easy
handles contained in the given multi handle set. It will block until activity
is detected on at least one of the handles or \fItimeout_ms\fP has passed.
handles contained in the given multi handle set. It blocks until activity is
detected on at least one of the handles or \fItimeout_ms\fP has passed.
Alternatively, if the multi handle has a pending internal timeout that has a
shorter expiry time than \fItimeout_ms\fP, that shorter time will be used
instead to make sure timeout accuracy is reasonably kept.
shorter expiry time than \fItimeout_ms\fP, that shorter time is used instead
to make sure timeout accuracy is reasonably kept.
The calling application may pass additional curl_waitfd structures which are
similar to \fIpoll(2)\fP's \fIpollfd\fP structure to be waited on in the same
call.
On completion, if \fInumfds\fP is non-NULL, it will be populated with the
total number of file descriptors on which interesting events occurred. This
number can include both libcurl internal descriptors as well as descriptors
provided in \fIextra_fds\fP.
On completion, if \fInumfds\fP is non-NULL, it gets populated with the total
number of file descriptors on which interesting events occurred. This number
can include both libcurl internal descriptors as well as descriptors provided
in \fIextra_fds\fP.
The \fIcurl_multi_wakeup(3)\fP function can be used from another thread to
wake up this function and return faster. This is one of the details
@ -57,10 +57,9 @@ that makes this function different than \fIcurl_multi_wait(3)\fP which cannot
be woken up this way.
If no extra file descriptors are provided and libcurl has no file descriptor
to offer to wait for, this function will instead wait during \fItimeout_ms\fP
milliseconds (or shorter if an internal timer indicates so). This is the
other detail that makes this function different than
\fIcurl_multi_wait(3)\fP.
to offer to wait for, this function instead waits during \fItimeout_ms\fP
milliseconds (or shorter if an internal timer indicates so). This is the other
detail that makes this function different than \fIcurl_multi_wait(3)\fP.
This function is encouraged to be used instead of select(3) when using the
multi interface to allow applications to easier circumvent the common problem

10
docs/libcurl/curl_multi_remove_handle.3
View file

@ -31,15 +31,15 @@ curl_multi_remove_handle - remove an easy handle from a multi session
CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle);
.fi
.SH DESCRIPTION
Removes a given \fIeasy_handle\fP from the \fImulti_handle\fP. This will make
the specified easy handle be removed from this multi handle's control.
Removes a given \fIeasy_handle\fP from the \fImulti_handle\fP. This makes the
specified easy handle be removed from this multi handle's control.
When the easy handle has been removed from a multi stack, it is again
perfectly legal to invoke \fIcurl_easy_perform(3)\fP on this easy handle.
Removing an easy handle while being used is perfectly legal and will
effectively halt the transfer in progress involving that easy handle. All
other easy handles and transfers will remain unaffected.
Removing an easy handle while being in use is perfectly legal and effectively
halts the transfer in progress involving that easy handle. All other easy
handles and transfers remain unaffected.
It is fine to remove a handle at any time during a transfer, just not from
within any libcurl callback function.

8
docs/libcurl/curl_multi_socket.3
View file

@ -37,9 +37,9 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle,
These functions are deprecated. Do not use. See
\fIcurl_multi_socket_action(3)\fP instead.
At return, the integer \fBrunning_handles\fP points to will contain the number
of still running easy handles within the multi handle. When this number
reaches zero, all transfers are complete/done. Note that when you call
At return, the integer \fBrunning_handles\fP points to contains the number of
still running easy handles within the multi handle. When this number reaches
zero, all transfers are complete/done. Note that when you call
\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter
decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out
@ -53,7 +53,7 @@ update the status with changes since the previous time the callback was
called.
Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option
with \fIcurl_multi_setopt(3)\fP. Your application will then get called with
with \fIcurl_multi_setopt(3)\fP. Your application then gets called with
information on how long to wait for socket actions at most before doing the
timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the

4
docs/libcurl/curl_multi_socket_action.3
View file

@ -41,7 +41,7 @@ can be passed as an events bitmask \fBev_bitmask\fP by first setting
\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of
events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or
CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and
libcurl will test the descriptor internally. It is also permissible to pass
libcurl tests the descriptor internally. It is also permissible to pass
CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the
whole process or when a timeout occurs.
@ -60,7 +60,7 @@ update the status with changes since the previous time the callback was
called.
Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option
with \fIcurl_multi_setopt(3)\fP. Your application will then get called with
with \fIcurl_multi_setopt(3)\fP. Your application then gets called with
information on how long to wait for socket actions at most before doing the
timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the

2
docs/libcurl/curl_multi_timeout.3
View file

@ -43,7 +43,7 @@ the simpler and older multi interface approach.
The timeout value returned in the long \fBtimeout\fP points to, is in number
of milliseconds at this moment. If 0, it means you should proceed immediately
without waiting for anything. If it returns -1, there's no timeout at all set.
without waiting for anything. If it returns -1, there is no timeout at all set.
An application that uses the multi_socket API SHOULD NOT use this function,
but SHOULD instead use the \fICURLMOPT_TIMERFUNCTION(3)\fP option for proper

18
docs/libcurl/curl_multi_wait.3
View file

@ -36,24 +36,24 @@ CURLMcode curl_multi_wait(CURLM *multi_handle,
.ad
.SH DESCRIPTION
\fIcurl_multi_wait(3)\fP polls all file descriptors used by the curl easy
handles contained in the given multi handle set. It will block until activity
is detected on at least one of the handles or \fItimeout_ms\fP has passed.
handles contained in the given multi handle set. It blocks until activity is
detected on at least one of the handles or \fItimeout_ms\fP has passed.
Alternatively, if the multi handle has a pending internal timeout that has a
shorter expiry time than \fItimeout_ms\fP, that shorter time will be used
shorter expiry time than \fItimeout_ms\fP, that shorter time is be used
instead to make sure timeout accuracy is reasonably kept.
The calling application may pass additional \fIcurl_waitfd\fP structures which
are similar to \fIpoll(2)\fP's \fIpollfd\fP structure to be waited on in the
same call.
On completion, if \fInumfds\fP is non-NULL, it will be populated with the
total number of file descriptors on which interesting events occurred. This
number can include both libcurl internal descriptors as well as descriptors
provided in \fIextra_fds\fP.
On completion, if \fInumfds\fP is non-NULL, it gets populated with the total
number of file descriptors on which interesting events occurred. This number
can include both libcurl internal descriptors as well as descriptors provided
in \fIextra_fds\fP.
If no extra file descriptors are provided and libcurl has no file descriptor
to offer to wait for, this function will return immediately. (Try
\fIcurl_multi_poll(3)\fP instead if you rather avoid this behavior.)
to offer to wait for, this function returns immediately. (Consider using
\fIcurl_multi_poll(3)\fP to avoid this behavior.)
This function is encouraged to be used instead of select(3) when using the
multi interface to allow applications to easier circumvent the common problem

17
docs/libcurl/curl_multi_wakeup.3
View file

@ -31,17 +31,16 @@ curl_multi_wakeup - wakes up a sleeping curl_multi_poll call
CURLMcode curl_multi_wakeup(CURLM *multi_handle);
.fi
.SH DESCRIPTION
This function can be called from any thread and it wakes up a
sleeping \fIcurl_multi_poll(3)\fP call that is currently (or will be)
waiting for activity or a timeout.
This function can be called from any thread and it wakes up a sleeping
\fIcurl_multi_poll(3)\fP call that is currently (or is about to be) waiting
for activity or a timeout.
If the function is called when there is no \fIcurl_multi_poll(3)\fP call,
it will cause the next call to return immediately.
If the function is called when there is no \fIcurl_multi_poll(3)\fP call, it
causes the next call to return immediately.
Calling this function only guarantees to wake up the current (or the next
if there is no current) \fIcurl_multi_poll(3)\fP call, which means it is
possible that multiple calls to this function will wake up the same waiting
operation.
Calling this function only guarantees to wake up the current (or the next if
there is no current) \fIcurl_multi_poll(3)\fP call, which means it is possible
that multiple calls to this function wake up the same waiting operation.
This function has no effect on \fIcurl_multi_wait(3)\fP calls.
.SH EXAMPLE

4
docs/libcurl/curl_pushheader_byname.3
View file

@ -38,8 +38,8 @@ elsewhere and it has no function then.
It returns the value for the given header field name (or NULL) for the
incoming server push request. This is a shortcut so that the application does
not have to loop through all headers to find the one it is interested in. The
data this function points to will be freed when this callback returns. If more
than one header field use the same name, this returns only the first one.
data this function points to is freed when this callback returns. If more than
one header field use the same name, this returns only the first one.
.SH EXAMPLE
.nf

6
docs/libcurl/curl_pushheader_bynum.3
View file

@ -36,9 +36,9 @@ This is a function that is only functional within a
elsewhere and it has no function then.
It returns the value for the header field at the given index \fBnum\fP, for
the incoming server push request or NULL. The data pointed will be freed when
this callback returns. The returned pointer points to a "name:value" string
that will be freed when this callback returns.
the incoming server push request or NULL. The data pointed to is freed by
libcurl when this callback returns. The returned pointer points to a
"name:value" string that gets freed when this callback returns.
.SH EXAMPLE
.nf

4
docs/libcurl/curl_share_cleanup.3
View file

@ -34,7 +34,7 @@ CURLSHcode curl_share_cleanup(CURLSH *share_handle);
This function deletes a shared object. The share handle cannot be used anymore
when this function has been called.
Passing in a NULL pointer in \fIshare_handle\fP will make this function return
Passing in a NULL pointer in \fIshare_handle\fP makes this function return
immediately with no action.
.SH EXAMPLE
.nf
@ -50,6 +50,6 @@ Added in 7.10
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors.3\fP
man page for the full list with descriptions. If an error occurs, then the
share object will not be deleted.
share object is not deleted.
.SH "SEE ALSO"
.BR curl_share_init "(3), " curl_share_setopt "(3)"

4
docs/libcurl/curl_slist_free_all.3
View file

@ -34,8 +34,8 @@ void curl_slist_free_all(struct curl_slist *list);
curl_slist_free_all() removes all traces of a previously built curl_slist
linked list.
Passing in a NULL pointer in \fIlist\fP will make this function return
immediately with no action.
Passing in a NULL pointer in \fIlist\fP makes this function return immediately
with no action.
.SH EXAMPLE
.nf
CURL *handle;

12
docs/libcurl/curl_unescape.3
View file

@ -33,12 +33,12 @@ char *curl_unescape(const char *input, int length);
.SH DESCRIPTION
Obsolete function. Use \fIcurl_easy_unescape(3)\fP instead!
This function will convert the URL encoded string \fBinput\fP to a "plain
string" and return that as a new allocated string. All input characters that
are URL encoded (%XX where XX is a two-digit hexadecimal number) will be
converted to their plain text versions.
This function converts the URL encoded string \fBinput\fP to a "plain string"
and return that as a new allocated string. All input characters that are URL
encoded (%XX where XX is a two-digit hexadecimal number) are converted to
their plain text versions.
If the \fBlength\fP argument is set to 0, \fIcurl_unescape(3)\fP will use
If the \fBlength\fP argument is set to 0, \fIcurl_unescape(3)\fP calls
strlen() on \fBinput\fP to find out the size.
You must \fIcurl_free(3)\fP the returned string when you are done with it.
@ -57,7 +57,7 @@ if(curl) {
}
.fi
.SH AVAILABILITY
Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function will
Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function might
be removed in a future release.
.SH RETURN VALUE
A pointer to a null-terminated string or NULL if it failed.

2
docs/libcurl/curl_url_set.3
View file

@ -94,7 +94,7 @@ to 40 bytes long.
The options field is an optional field that might follow the password in the
userinfo part. It is only recognized/used when parsing URLs for the following
schemes: pop3, smtp and imap. This function however allows users to
independently set this field at will.
independently set this field.
.IP CURLUPART_HOST
The host name. If it is International Domain Name (IDN) the string must then
be encoded as your locale says or UTF-8 (when WinIDN is used). If it is a

7
docs/libcurl/curl_version_info.3
View file

@ -35,10 +35,9 @@ curl_version_info_data *curl_version_info(CURLversion age);
Returns a pointer to a filled in static struct with information about various
features in the running version of libcurl. \fIage\fP should be set to the
version of this functionality by the time you write your program. This way,
libcurl will always return a proper struct that your program understands,
while programs in the future might get a different
struct. \fBCURLVERSION_NOW\fP will be the most recent one for the library you
have installed:
libcurl always returns a proper struct that your program understands, while
programs in the future might get a different struct. \fBCURLVERSION_NOW\fP is
the most recent one for the library you have installed:
.nf
data = curl_version_info(CURLVERSION_NOW);
.fi

4
docs/libcurl/curl_ws_meta.3
View file

@ -69,12 +69,12 @@ complete.
.SH FLAGS
.IP CURLWS_TEXT
The buffer contains text data. Note that this makes a difference to WebSocket
but libcurl itself will not make any verification of the content or
but libcurl itself does not make any verification of the content or
precautions that you actually receive valid UTF-8 content.
.IP CURLWS_BINARY
This is binary data.
.IP CURLWS_CONT
This is not the final fragment of the message, it implies that there will be
This is not the final fragment of the message, it implies that there is
another fragment coming as part of the same message.
.IP CURLWS_CLOSE
This transfer is now closed.

9
docs/libcurl/curl_ws_send.3
View file

@ -58,14 +58,13 @@ in all frames except the final one.
.SH FLAGS
.IP CURLWS_TEXT
The buffer contains text data. Note that this makes a difference to WebSocket
but libcurl itself will not make any verification of the content or
but libcurl itself does not make any verification of the content or
precautions that you actually send valid UTF-8 content.
.IP CURLWS_BINARY
This is binary data.
.IP CURLWS_CONT
This is not the final fragment of the message, which implies that there will
be another fragment coming as part of the same message where this bit is not
set.
This is not the final fragment of the message, which implies that there is
another fragment coming as part of the same message where this bit is not set.
.IP CURLWS_CLOSE
Close this transfer.
.IP CURLWS_PING
@ -73,7 +72,7 @@ This is a ping.
.IP CURLWS_PONG
This is a pong.
.IP CURLWS_OFFSET
The provided data is only a partial fragment and there will be more in a
The provided data is only a partial fragment and there is more coming in a
following call to \fIcurl_ws_send()\fP. When sending only a piece of the
fragment like this, the \fIfragsize\fP must be provided with the total
expected fragment size in the first call and it needs to be zero in subsequent

12
docs/libcurl/libcurl-easy.3
View file

@ -32,13 +32,13 @@ interface functions you use. Use \fIcurl_easy_init(3)\fP to get the handle.
You continue by setting all the options you want in the upcoming transfer, the
most important among them is the URL itself (you cannot transfer anything
without a specified URL as you may have figured out yourself). You might want
to set some callbacks as well that will be called from the library when data
is available etc. \fIcurl_easy_setopt(3)\fP is used for all this.
to set some callbacks as well that are called from the library when data is
available etc. \fIcurl_easy_setopt(3)\fP is used for all this.
\fICURLOPT_URL(3)\fP is the only option you really must set, as otherwise
there can be no transfer. Another commonly used option is
\fICURLOPT_VERBOSE(3)\fP that will help you see what libcurl is doing under
the hood, which is useful when debugging for example. The
\fICURLOPT_VERBOSE(3)\fP that helps you see what libcurl is doing under the
hood, which is useful when debugging for example. The
\fIcurl_easy_setopt(3)\fP man page has a full index of the almost 300
available options.
@ -48,8 +48,8 @@ make a clone of an easy handle (with all its set options) using
\fIcurl_easy_duphandle(3)\fP.
When all is setup, you tell libcurl to perform the transfer using
\fIcurl_easy_perform(3)\fP. It will then do the entire operation and will not
return until it is done (successfully or not).
\fIcurl_easy_perform(3)\fP. It performs the entire transfer operation and does
not return until it is done (successfully or not).
After the transfer has been made, you can set new options and make another
transfer, or if you are done, cleanup the session by calling

30
docs/libcurl/libcurl-env.3
View file

@ -25,30 +25,29 @@
.SH NAME
libcurl-env \- environment variables libcurl understands
.SH DESCRIPTION
libcurl reads and understands a set of environment variables that if set will
control and change behaviors. This is the full list of variables to set and
libcurl reads and understands a set of environment variables that if set
controls and changes behaviors. This is the full list of variables to set and
description of what they do. Also note that curl, the command line tool,
supports a set of additional environment variables independently of this.
.IP "[scheme]_proxy"
When libcurl is given a URL to use in a transfer, it first extracts the
"scheme" part from the URL and checks if there is a given proxy set for that
in its corresponding environment variable. A URL like "https://example.com"
will hence use the "http_proxy" variable, while a URL like "ftp://example.com"
will use the "ftp_proxy" variable.
makes libcurl use the "http_proxy" variable, while a URL like
"ftp://example.com" uses the "ftp_proxy" variable.
These proxy variables are also checked for in their uppercase versions, except
the "http_proxy" one which is only used lowercase. Note also that some systems
actually have a case insensitive handling of environment variables and then of
course "HTTP_PROXY" will still work...
course "HTTP_PROXY" still works.
.IP ALL_PROXY
This is a setting to set proxy for all URLs, independently of what scheme is
being used. Note that the scheme specific variables will override this one if
set.
being used. Note that the scheme specific variables overrides this one if set.
.IP CURL_SSL_BACKEND
When libcurl is built to support multiple SSL backends, it will select a
specific backend at first use. If no selection is done by the program using
libcurl, this variable's selection will be used. Setting a name that is not a
built-in alternative will make libcurl stay with the default.
When libcurl is built to support multiple SSL backends, it selects a specific
backend at first use. If no selection is done by the program using libcurl,
this variable's selection is used. Setting a name that is not a built-in
alternative makes libcurl stay with the default.
SSL backend names (case-insensitive): BearSSL, GnuTLS, mbedTLS,
nss, OpenSSL, rustls, Schannel, Secure-Transport, wolfSSL
@ -71,14 +70,17 @@ should not use a proxy.
User name to use when invoking the \fIntlm-wb\fP tool.
.IP SSLKEYLOGFILE
When set and libcurl runs with a SSL backend that supports this feature,
libcurl will save SSL secrets into the given file name. Using those SSL
secrets, other tools (such as Wireshark) can decrypt the SSL communication and
libcurl saves SSL secrets into the given file name. Using those SSL secrets,
other tools (such as Wireshark) can decrypt the SSL communication and
analyze/view the traffic.
These secrets and this file might be sensitive. Users are advised to take
precautions so that they are not stolen or otherwise inadvertently revealed.
.IP USER
User name to use when invoking the \fIntlm-wb\fP tool, if \fINTLMUSER\fP and
\fILOGNAME\fP were not set.
.SH "Debug Variables"
There's a set of variables only recognized and used if libcurl was built
There is a set of variables only recognized and used if libcurl was built
"debug enabled", which should never be true for a library used in production.
.IP "CURL_GETHOSTNAME"
Debug-only variable.

24
docs/libcurl/libcurl-errors.3
View file

@ -31,8 +31,8 @@ Why they occur and possibly what you can do to fix the problem are also included
.SH "CURLcode"
Almost all "easy" interface functions return a CURLcode error code. No matter
what, using the \fIcurl_easy_setopt(3)\fP option \fICURLOPT_ERRORBUFFER(3)\fP
is a good idea as it will give you a human readable error string that may
offer more details about the cause of the error than just the error code.
is a good idea as it gives you a human readable error string that may offer
more details about the cause of the error than just the error code.
\fIcurl_easy_strerror(3)\fP can be called to get an error string from a given
CURLcode number.
@ -228,7 +228,7 @@ Illegal TFTP operation.
.IP "CURLE_TFTP_UNKNOWNID (72)"
Unknown TFTP transfer ID.
.IP "CURLE_REMOTE_FILE_EXISTS (73)"
File already exists and will not be overwritten.
File already exists and is not overwritten.
.IP "CURLE_TFTP_NOSUCHUSER (74)"
This error should never be returned by a properly functioning TFTP server.
.IP "Obsolete error (75-76)"
@ -252,8 +252,8 @@ Issuer check failed (Added in 7.19.0)
.IP "CURLE_FTP_PRET_FAILED (84)"
The FTP server does not understand the PRET command at all or does not support
the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST(3)\fP, a
custom LIST command will be sent with the PRET command before PASV as
well. (Added in 7.20.0)
custom LIST command is sent with the PRET command before PASV as well. (Added
in 7.20.0)
.IP "CURLE_RTSP_CSEQ_ERROR (85)"
Mismatch of RTSP CSeq numbers.
.IP "CURLE_RTSP_SESSION_ERROR (86)"
@ -263,8 +263,8 @@ Unable to parse FTP file list (during FTP wildcard downloading).
.IP "CURLE_CHUNK_FAILED (88)"
Chunk callback reported error.
.IP "CURLE_NO_CONNECTION_AVAILABLE (89)"
(For internal use only, will never be returned by libcurl) No connection
available, the session will be queued. (added in 7.30.0)
(For internal use only, is never returned by libcurl) No connection available,
the session is queued. (added in 7.30.0)
.IP "CURLE_SSL_PINNEDPUBKEYNOTMATCH (90)"
Failed to match the pinned key specified with \fICURLOPT_PINNEDPUBLICKEY(3)\fP.
.IP "CURLE_SSL_INVALIDCERTSTATUS (91)"
@ -289,8 +289,8 @@ SSL Client Certificate required.
.IP "CURLE_UNRECOVERABLE_POLL (99)"
An internal call to poll() or select() returned error that is not recoverable.
.IP "CURLE_OBSOLETE*"
These error codes will never be returned. They were used in an old libcurl
version and are currently unused.
These error codes are never returned. They were used in an old libcurl version
and are currently unused.
.SH "CURLMcode"
This is the generic return code used by functions in the libcurl multi
interface. Also consider \fIcurl_multi_strerror(3)\fP.
@ -335,8 +335,8 @@ A multi handle callback returned error.
.IP "CURLM_UNRECOVERABLE_POLL (12)"
An internal call to poll() or select() returned error that is not recoverable.
.SH "CURLSHcode"
The "share" interface will return a \fBCURLSHcode\fP to indicate when an error
has occurred. Also consider \fIcurl_share_strerror(3)\fP.
The "share" interface returns a \fBCURLSHcode\fP to indicate when an error has
occurred. Also consider \fIcurl_share_strerror(3)\fP.
.IP "CURLSHE_OK (0)"
All fine. Proceed as usual.
.IP "CURLSHE_BAD_OPTION (1)"
@ -352,7 +352,7 @@ Not enough memory was available.
The requested sharing could not be done because the library you use do not have
that particular feature enabled. (Added in 7.23.0)
.SH "CURLUcode"
The URL interface will return a \fICURLUcode\fP to indicate when an error has
The URL interface returns a \fICURLUcode\fP to indicate when an error has
occurred. Also consider \fIcurl_url_strerror(3)\fP.
.IP "CURLUE_OK (0)"
All fine. Proceed as usual.

40
docs/libcurl/libcurl-multi.3
View file

@ -28,7 +28,7 @@ libcurl-multi \- how to use the multi interface
.SH DESCRIPTION
This is an overview on how to use the libcurl multi interface in your C
programs. There are specific man pages for each function mentioned in
here. There's also the \fIlibcurl-tutorial(3)\fP man page for a complete
here. There is also the \fIlibcurl-tutorial(3)\fP man page for a complete
tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page
for an overview of the libcurl easy interface.
@ -59,8 +59,8 @@ handle. You create all the easy handles you need, and setup the appropriate
options for each easy handle using \fIcurl_easy_setopt(3)\fP.
There are two flavors of the multi interface, the select() oriented one and
the event based one we call multi_socket. You will benefit from reading
through the description of both versions to fully understand how they work and
the event based one we call multi_socket. You benefit from reading through the
description of both versions to fully understand how they work and
differentiate. We start out with the select() oriented version.
When an easy handle is setup and ready for transfer, then instead of using
@ -78,17 +78,17 @@ necessary. You can remove handles at any point during transfers.
Adding the easy handle to the multi handle does not start the transfer.
Remember that one of the main ideas with this interface is to let your
application drive. You drive the transfers by invoking
\fIcurl_multi_perform(3)\fP. libcurl will then transfer data if there is
anything available to transfer. it will use the callbacks and everything else
you have setup in the individual easy handles. it will transfer data on all
current transfers in the multi stack that are ready to transfer anything. It
may be all, it may be none. When there's nothing more to do for now, it
returns back to the calling application.
\fIcurl_multi_perform(3)\fP. libcurl then transfers data if there is anything
available to transfer. It uses the callbacks and everything else you have
setup in the individual easy handles. It transfers data on all current
transfers in the multi stack that are ready to transfer anything. It may be
all, it may be none. When there is nothing more to do for now, it returns back
to the calling application.
Your application extracts info from libcurl about when it would like to get
invoked to transfer data or do other work. The most convenient way is to use
\fIcurl_multi_poll(3)\fP that will help you wait until the application should
call libcurl again. The older API to accomplish the same thing is
\fIcurl_multi_poll(3)\fP that helps you wait until the application should call
libcurl again. The older API to accomplish the same thing is
\fIcurl_multi_fdset(3)\fP that extracts \fIfd_sets\fP from libcurl to use in
select() or poll() calls in order to get to know when the transfers in the
multi stack might need attention. Both these APIs allow for your program to
@ -119,13 +119,13 @@ When all transfers in the multi stack are done, close the multi handle with
invoke separate \fIcurl_easy_cleanup(3)\fP calls for every single easy handle
to clean them up properly.
If you want to re-use an easy handle that was added to the multi handle for
If you want to reuse an easy handle that was added to the multi handle for
transfer, you must first remove it from the multi stack and then re-add it
again (possibly after having altered some options at your own choice).
.SH "MULTI_SOCKET"
\fIcurl_multi_socket_action(3)\fP function offers a way for applications to
not only avoid being forced to use select(), but it also offers a much more
high-performance API that will make a significant difference for applications
high-performance API that makes a significant difference for applications
using large numbers of simultaneous connections.
\fIcurl_multi_socket_action(3)\fP is then used instead of
@ -135,9 +135,9 @@ When using this API, you add easy handles to the multi handle just as with the
normal multi interface. Then you also set two callbacks with the
\fICURLMOPT_SOCKETFUNCTION(3)\fP and \fICURLMOPT_TIMERFUNCTION(3)\fP options
to \fIcurl_multi_setopt(3)\fP. They are two callback functions that libcurl
will call with information about what sockets to wait for, and for what
activity, and what the current timeout time is - if that expires libcurl
should be notified.
calls with information about what sockets to wait for, and for what activity,
and what the current timeout time is - if that expires libcurl should be
notified.
The multi_socket API is designed to inform your application about which
sockets libcurl is currently using and for what activities (read and/or write)
@ -161,10 +161,10 @@ losing performance.
When you have added your initial set of handles, you call
\fIcurl_multi_socket_action(3)\fP with CURL_SOCKET_TIMEOUT set in the
\fIsockfd\fP argument, and you will get callbacks call that sets you up and
you then continue to call \fIcurl_multi_socket_action(3)\fP accordingly when
you get activity on the sockets you have been asked to wait on, or if the
timeout timer expires.
\fIsockfd\fP argument, and you get callbacks invoked that set you up and you
then continue to call \fIcurl_multi_socket_action(3)\fP accordingly when you
get activity on the sockets you have been asked to wait on, or if the timeout
timer expires.
You can poll \fIcurl_multi_info_read(3)\fP to see if any transfer has
completed, as it then has a message saying so.

58
docs/libcurl/libcurl-security.3
View file

@ -56,8 +56,8 @@ this.
automatically to frequently visited sites. The file contains passwords in
clear text and is a real security risk. In some cases, your .netrc is also
stored in a home directory that is NFS mounted or used on another network
based file system, so the clear text password will fly through your network
every time anyone reads that file.
based file system, so the clear text password flies through your network every
time anyone reads that file.
For applications that enable .netrc use, a user who manage to set the right
URL might then be possible to pass on passwords.
@ -135,8 +135,8 @@ function in which addresses are sanitized before use.
For all options in libcurl which specify headers, including but not limited to
\fICURLOPT_HTTPHEADER(3)\fP, \fICURLOPT_PROXYHEADER(3)\fP,
\fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_REFERER(3)\fP
and \fICURLOPT_RANGE(3)\fP, libcurl will send the headers as-is and will not
apply any special sanitation or normalization to them.
and \fICURLOPT_RANGE(3)\fP, libcurl sends the headers as-is and does not apply
any special sanitation or normalization to them.
If you allow untrusted user input into these options without sanitizing CRLF
sequences in them, someone malicious may be able to modify the request in a
@ -180,18 +180,18 @@ idea because of the many different ways a numerical IPv4 address can be
specified and libcurl accepts: one to four dot-separated fields using one of
or a mix of decimal, octal or hexadecimal encoding.
.SH "IPv6 Addresses"
libcurl will normally handle IPv6 addresses transparently and just as easily
as IPv4 addresses. That means that a sanitizing function that filters out
addresses like 127.0.0.1 is not sufficient--the equivalent IPv6 addresses
\fB::1\fP, \fB::\fP, \fB0:00::0:1\fP, \fB::127.0.0.1\fP and
\fB::ffff:7f00:1\fP supplied somehow by an attacker would all bypass a naive
filter and could allow access to undesired local resources. IPv6 also has
special address blocks like link-local and site-local that generally should
not be accessed by a server-side libcurl-using application. A poorly
configured firewall installed in a data center, organization or server may
also be configured to limit IPv4 connections but leave IPv6 connections wide
open. In some cases, setting \fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4
can be used to limit resolved addresses to IPv4 only and bypass these issues.
libcurl handles IPv6 addresses transparently and just as easily as IPv4
addresses. That means that a sanitizing function that filters out addresses
like 127.0.0.1 is not sufficient - the equivalent IPv6 addresses \fB::1\fP,
\fB::\fP, \fB0:00::0:1\fP, \fB::127.0.0.1\fP and \fB::ffff:7f00:1\fP supplied
somehow by an attacker would all bypass a naive filter and could allow access
to undesired local resources. IPv6 also has special address blocks like
link-local and site-local that generally should not be accessed by a
server-side libcurl-using application. A poorly configured firewall installed
in a data center, organization or server may also be configured to limit IPv4
connections but leave IPv6 connections wide open. In some cases, setting
\fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4 can be used to limit resolved
addresses to IPv4 only and bypass these issues.
.SH Uploads
When uploading, a redirect can cause a local (or remote) file to be
overwritten. Applications must not allow any unsanitized URL to be passed in
@ -236,10 +236,10 @@ using the protocol.
By default, libcurl prohibits redirects to file:// URLs.
.SH "Warning: file:// on Windows"
The Windows operating system will automatically, and without any way for
applications to disable it, try to establish a connection to another host over
the network and access it (over SMB or other protocols), if only the correct
file path is accessed.
The Windows operating system tries automatically, and without any way for
applications to disable it, to establish a connection to another host over the
network and access it (over SMB or other protocols), if only the correct file
path is accessed.
When first realizing this, the curl team tried to filter out such attempts in
order to protect applications for inadvertent probes of for example internal
@ -253,13 +253,13 @@ system.
The conclusion we have come to is that this is a weakness or feature in the
Windows operating system itself, that we as an application cannot safely
protect users against. It would just be a whack-a-mole race we do not want to
participate in. There are too many ways to do it and there's no knob we can
participate in. There are too many ways to do it and there is no knob we can
use to turn off the practice.
If you use curl or libcurl on Windows (any version), disable the use of the
FILE protocol in curl or be prepared that accesses to a range of "magic paths"
will potentially make your system try to access other hosts on your
network. curl cannot protect you against this.
potentially make your system access other hosts on your network. curl cannot
protect you against this.
.SH "What if the user can set the URL"
Applications may find it tempting to let users set the URL that it can work
on. That is probably fine, but opens up for mischief and trickery that you as
@ -311,7 +311,7 @@ given IP+PORT, or with PASV/EPSV that makes the server setup a port to listen
to and tells the client to connect to a given IP+PORT.
Again, unauthenticated means that the connection might be meddled with by a
man-in-the-middle or that there's a malicious server pretending to be the
man-in-the-middle or that there is a malicious server pretending to be the
right one.
A malicious FTP server can respond to PASV commands with the IP+PORT of a
@ -397,19 +397,19 @@ etc), it should be noted that libcurl still might understand proxy environment
variables that allow the user to redirect libcurl operations to use a proxy
controlled by the user.
.SH "File descriptors, fork and NTLM"
An application that uses libcurl and invokes \fIfork()\fP will get all file
An application that uses libcurl and invokes \fIfork()\fP gets all file
descriptors duplicated in the child process, including the ones libcurl
created.
libcurl itself uses \fIfork()\fP and \fIexecl()\fP if told to use the
\fBCURLAUTH_NTLM_WB\fP authentication method which then will invoke the helper
\fBCURLAUTH_NTLM_WB\fP authentication method which then invokes the helper
command in a child process with file descriptors duplicated. Make sure that
only the trusted and reliable helper program is invoked!
.SH "Secrets in memory"
When applications pass user names, passwords or other sensitive data to
libcurl to be used for upcoming transfers, those secrets will be kept around
as-is in memory. In many cases they will be stored in heap for as long as the
handle itself for which the options are set.
libcurl to be used for upcoming transfers, those secrets are kept around as-is
in memory. In many cases they are stored in the heap for as long as the handle
itself for which the options are set.
If an attacker can access the heap, like maybe by reading swap space or via a
core dump file, such data might be accessible.

2
docs/libcurl/libcurl-share.3
View file

@ -37,7 +37,7 @@ The share interface was added to enable sharing of data between curl
.SH "ONE SET OF DATA - MANY TRANSFERS"
You can have multiple easy handles share data between them. Have them update
and use the \fBsame\fP cookie database, DNS cache, TLS session cache and/or
connection cache! This way, each single transfer will take advantage from data
connection cache! This way, each single transfer takes advantage from data
updates made by the other transfer(s).
.SH "SHARE OBJECT"
You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle

20
docs/libcurl/libcurl-thread.3
View file

@ -75,20 +75,22 @@ The engine is used by libcurl in a way that is fully thread-safe.
The engine is used by libcurl in a way that is fully thread-safe.
.SH "Signals"
Signals are used for timing out name resolves (during DNS lookup) - when built
without using either the c-ares or threaded resolver backends. When using
multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP option to 1L for
all handles. Everything will or might work fine except that timeouts are not
honored during the DNS lookup - which you can work around by building libcurl
with c-ares or threaded-resolver support. c-ares is a library that provides
asynchronous name resolves. On some platforms, libcurl simply will not
without using either the c-ares or threaded resolver backends. On systems that
have a signal concept.
When using multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP
option to 1L for all handles. Everything works fine except that timeouts
cannot be honored during DNS lookups - which you can work around by building
libcurl with c-ares or threaded-resolver support. c-ares is a library that
provides asynchronous name resolves. On some platforms, libcurl simply cannot
function properly multi-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option
is set.
When \fICURLOPT_NOSIGNAL(3)\fP is set to 1L, your application needs to deal
with the risk of a SIGPIPE (that at least the OpenSSL backend can
trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L will not work in a
threaded situation as there will be race where libcurl risks restoring the
former signal handler while another thread should still ignore it.
trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L does not work in a
threaded situation as there is a race condition where libcurl risks restoring
the former signal handler while another thread should still ignore it.
.SH "Name resolving"
The \fBgethostbyname\fP or \fBgetaddrinfo\fP and other name resolving system
calls used by libcurl are provided by your operating system and must be thread

373
docs/libcurl/libcurl-tutorial.3
View file

@ -27,24 +27,23 @@
libcurl-tutorial \- libcurl programming tutorial
.SH "Objective"
This document attempts to describe the general principles and some basic
approaches to consider when programming with libcurl. The text will focus
mainly on the C interface but might apply fairly well on other interfaces as
well as they usually follow the C one pretty closely.
approaches to consider when programming with libcurl. The text focuses on the
C interface but should apply fairly well on other language bindings as well as
they usually follow the C API pretty closely.
This document will refer to 'the user' as the person writing the source code
that uses libcurl. That would probably be you or someone in your position.
What will be generally referred to as 'the program' will be the collected
source code that you write that is using libcurl for transfers. The program
is outside libcurl and libcurl is outside of the program.
This document refers to 'the user' as the person writing the source code that
uses libcurl. That would probably be you or someone in your position. What is
generally referred to as 'the program' is the collected source code that you
write that is using libcurl for transfers. The program is outside libcurl and
libcurl is outside of the program.
To get more details on all options and functions described herein, please
refer to their respective man pages.
.SH "Building"
There are many different ways to build C programs. This chapter will assume a
Unix style build process. If you use a different build system, you can still
read this to get general information that may apply to your environment as
well.
There are many different ways to build C programs. This chapter assumes a Unix
style build process. If you use a different build system, you can still read
this to get general information that may apply to your environment as well.
.IP "Compiling the Program"
Your compiler needs to know where the libcurl headers are located. Therefore
you must set your compiler's include path to point to the directory where you
@ -66,15 +65,15 @@ tool comes to the rescue:
libcurl can be built and customized in many ways. One of the things that
varies from different libraries and builds is the support for SSL-based
transfers, like HTTPS and FTPS. If a supported SSL library was detected
properly at build-time, libcurl will be built with SSL support. To figure out
if an installed libcurl has been built with SSL support enabled, use
\&'curl-config' like this:
properly at build-time, libcurl is built with SSL support. To figure out if an
installed libcurl has been built with SSL support enabled, use \&'curl-config'
like this:
.nf
$ curl-config --feature
.fi
And if SSL is supported, the keyword \fISSL\fP will be written to stdout,
possibly together with a few other features that could be either on or off on
for different libcurls.
And if SSL is supported, the keyword \fISSL\fP is written to stdout, possibly
together with a other features that could be either on or off on for different
libcurls.
See also the "Features libcurl Provides" further down.
.IP "autoconf macro"
@ -99,20 +98,20 @@ use the library. Once for your program's entire life time. This is done using
curl_global_init()
.fi
and it takes one parameter which is a bit pattern that tells libcurl what to
initialize. Using \fICURL_GLOBAL_ALL\fP will make it initialize all known
internal sub modules, and might be a good default option. The current two bits
that are specified are:
initialize. Using \fICURL_GLOBAL_ALL\fP makes it initialize all known internal
sub modules, and might be a good default option. The current two bits that are
specified are:
.RS
.IP "CURL_GLOBAL_WIN32"
which only does anything on Windows machines. When used on
a Windows machine, it will make libcurl initialize the win32 socket
stuff. Without having that initialized properly, your program cannot use
sockets properly. You should only do this once for each application, so if
your program already does this or of another library in use does it, you
should not tell libcurl to do this as well.
which only does anything on Windows machines. When used on a Windows machine,
it makes libcurl initialize the win32 socket stuff. Without having that
initialized properly, your program cannot use sockets properly. You should
only do this once for each application, so if your program already does this
or of another library in use does it, you should not tell libcurl to do this
as well.
.IP CURL_GLOBAL_SSL
which only does anything on libcurls compiled and built SSL-enabled. On these
systems, this will make libcurl initialize the SSL library properly for this
systems, this makes libcurl initialize the SSL library properly for this
application. This only needs to be done once for each application so if your
program or another library already does this, this bit should not be needed.
.RE
@ -124,8 +123,8 @@ function itself with a guessed bit pattern. Please note that depending solely
on this is not considered nice nor good.
When the program no longer uses libcurl, it should call
\fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It will
then do the reversed operations to cleanup the resources the
\fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It
performs the reversed operations to cleanup the resources the
\fIcurl_global_init(3)\fP call initialized.
Repeated calls to \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP
@ -164,9 +163,9 @@ transfer or series of transfers.
You set properties and options for this handle using
\fIcurl_easy_setopt(3)\fP. They control how the subsequent transfer or
transfers will be made. Options remain set in the handle until set again to
something different. They are sticky. Multiple requests using the same handle
will use the same options.
transfers using this handle are made. Options remain set in the handle until
set again to something different. They are sticky. Multiple requests using the
same handle use the same options.
If you at any point would like to blank all previously set options for a
single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also
@ -204,70 +203,70 @@ by setting another property:
curl_easy_setopt(handle, CURLOPT_WRITEDATA, &internal_struct);
.fi
Using that property, you can easily pass local data between your application
and the function that gets invoked by libcurl. libcurl itself will not touch the
data you pass with \fICURLOPT_WRITEDATA(3)\fP.
and the function that gets invoked by libcurl. libcurl itself does not touch
the data you pass with \fICURLOPT_WRITEDATA(3)\fP.
libcurl offers its own default internal callback that will take care of the
data if you do not set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It
will then simply output the received data to stdout. You can have the default
callback write the data to a different file handle by passing a 'FILE *' to a
file opened for writing with the \fICURLOPT_WRITEDATA(3)\fP option.
libcurl offers its own default internal callback that takes care of the data
if you do not set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It simply
outputs the received data to stdout. You can have the default callback write
the data to a different file handle by passing a 'FILE *' to a file opened for
writing with the \fICURLOPT_WRITEDATA(3)\fP option.
Now, we need to take a step back and have a deep breath. Here's one of those
Now, we need to take a step back and take a deep breath. Here is one of those
rare platform-dependent nitpicks. Did you spot it? On some platforms[2],
libcurl will not be able to operate on files opened by the program. Thus, if you
use the default callback and pass in an open file with
\fICURLOPT_WRITEDATA(3)\fP, it will crash. You should therefore avoid this to
make your program run fine virtually everywhere.
libcurl is not able to operate on file handles opened by the
program. Therefore, if you use the default callback and pass in an open file
handle with \fICURLOPT_WRITEDATA(3)\fP, libcurl crashes. You should avoid this
to make your program run fine virtually everywhere.
(\fICURLOPT_WRITEDATA(3)\fP was formerly known as \fICURLOPT_FILE\fP. Both
names still work and do the same thing).
If you are using libcurl as a win32 DLL, you MUST use the
\fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP - or you
will experience crashes.
\fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP - or
experience crashes.
There are of course many more options you can set, and we will get back to a few
of them later. Let's instead continue to the actual transfer:
There are of course many more options you can set, and we get back to a few of
them later. Let's instead continue to the actual transfer:
.nf
success = curl_easy_perform(handle);
.fi
\fIcurl_easy_perform(3)\fP will connect to the remote site, do the necessary
commands and receive the transfer. Whenever it receives data, it calls the
\fIcurl_easy_perform(3)\fP connects to the remote site, does the necessary
commands and performs the transfer. Whenever it receives data, it calls the
callback function we previously set. The function may get one byte at a time,
or it may get many kilobytes at once. libcurl delivers as much as possible as
often as possible. Your callback function should return the number of bytes it
\&"took care of". If that is not the same amount of bytes that was passed to
it, libcurl will abort the operation and return with an error code.
it, libcurl aborts the operation and returns with an error code.
When the transfer is complete, the function returns a return code that informs
you if it succeeded in its mission or not. If a return code is not enough for
you, you can use the \fICURLOPT_ERRORBUFFER(3)\fP to point libcurl to a buffer
of yours where it will store a human readable error message as well.
of yours where it stores a human readable error message as well.
If you then want to transfer another file, the handle is ready to be used
again. Mind you, it is even preferred that you re-use an existing handle if
you intend to make another transfer. libcurl will then attempt to re-use the
again. It is even preferred and encouraged that you reuse an existing handle
if you intend to make another transfer. libcurl then attempts to reuse a
previous connection.
For some protocols, downloading a file can involve a complicated process of
logging in, setting the transfer mode, changing the current directory and
finally transferring the file data. libcurl takes care of all that
complication for you. Given simply the URL to a file, libcurl will take care
of all the details needed to get the file moved from one machine to another.
complication for you. Given simply the URL to a file, libcurl takes care of
all the details needed to get the file moved from one machine to another.
.SH "Multi-threading Issues"
libcurl is thread safe but there are a few exceptions. Refer to
\fIlibcurl-thread(3)\fP for more information.
.SH "When It does not Work"
There will always be times when the transfer fails for some reason. You might
have set the wrong libcurl option or misunderstood what the libcurl option
actually does, or the remote server might return non-standard replies that
confuse the library which then confuses your program.
There are times when the transfer fails for some reason. You might have set
the wrong libcurl option or misunderstood what the libcurl option actually
does, or the remote server might return non-standard replies that confuse the
library which then confuses your program.
There's one golden rule when these things occur: set the
\fICURLOPT_VERBOSE(3)\fP option to 1. it will cause the library to spew out the
There is one golden rule when these things occur: set the
\fICURLOPT_VERBOSE(3)\fP option to 1. it causes the library to spew out the
entire protocol details it sends, some internal info and some received
protocol data as well (especially when using FTP). If you are using HTTP,
adding the headers in the received output to study is also a clever way to get
@ -293,14 +292,14 @@ libcurl tries to keep a protocol independent approach to most transfers, thus
uploading to a remote FTP site is similar to uploading data to an HTTP server
with a PUT request.
Of course, first you either create an easy handle or you re-use one existing
Of course, first you either create an easy handle or you reuse one existing
one. Then you set the URL to operate on just like before. This is the remote
URL, that we now will upload.
URL, that we now upload.
Since we write an application, we most likely want libcurl to get the upload
data by asking us for it. To make it do that, we set the read callback and
the custom pointer libcurl will pass to our read callback. The read callback
should have a prototype similar to:
data by asking us for it. To make it do that, we set the read callback and the
custom pointer libcurl passes to our read callback. The read callback should
have a prototype similar to:
.nf
size_t function(char *bufptr, size_t size, size_t nitems, void *userp);
.fi
@ -318,7 +317,7 @@ Tell libcurl that we want to upload:
.nf
curl_easy_setopt(handle, CURLOPT_UPLOAD, 1L);
.fi
A few protocols will not behave properly when uploads are done without any prior
A few protocols do not behave properly when uploads are done without any prior
knowledge of the expected file size. So, set the upload file size using the
\fICURLOPT_INFILESIZE_LARGE(3)\fP for all known file sizes like this[1]:
@ -327,12 +326,12 @@ knowledge of the expected file size. So, set the upload file size using the
curl_easy_setopt(handle, CURLOPT_INFILESIZE_LARGE, file_size);
.fi
When you call \fIcurl_easy_perform(3)\fP this time, it will perform all the
necessary operations and when it has invoked the upload it will call your
supplied callback to get the data to upload. The program should return as much
data as possible in every invoke, as that is likely to make the upload perform
as fast as possible. The callback should return the number of bytes it wrote
in the buffer. Returning 0 will signal the end of the upload.
When you call \fIcurl_easy_perform(3)\fP this time, it performs all the
necessary operations and when it has invoked the upload it calls your supplied
callback to get the data to upload. The program should return as much data as
possible in every invoke, as that is likely to make the upload perform as fast
as possible. The callback should return the number of bytes it wrote in the
buffer. Returning 0 signals the end of the upload.
.SH "Passwords"
Many protocols use or even require that user name and password are provided
@ -340,8 +339,8 @@ to be able to download or upload the data of your choice. libcurl offers
several ways to specify them.
Most protocols support that you specify the name and password in the URL
itself. libcurl will detect this and use them accordingly. This is written
like this:
itself. libcurl detects this and use them accordingly. This is written like
this:
.nf
protocol://user:password@example.com/path/
.fi
@ -362,7 +361,7 @@ similar to the \fICURLOPT_USERPWD(3)\fP option like this:
.nf
curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
.fi
There's a long time Unix "standard" way of storing FTP user names and
There is a long time Unix "standard" way of storing FTP user names and
passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks
the \fI%USERPROFILE% environment\fP variable if \fI%HOME%\fP is unset, and
tries "_netrc" as name). The file should be made private so that only the user
@ -393,12 +392,12 @@ To pass the known private key password to libcurl:
curl_easy_setopt(handle, CURLOPT_KEYPASSWD, "keypassword");
.fi
.SH "HTTP Authentication"
The previous chapter showed how to set user name and password for getting
URLs that require authentication. When using the HTTP protocol, there are
many different ways a client can provide those credentials to the server and
you can control which way libcurl will (attempt to) use them. The default HTTP
authentication method is called 'Basic', which is sending the name and
password in clear-text in the HTTP request, base64-encoded. This is insecure.
The previous chapter showed how to set user name and password for getting URLs
that require authentication. When using the HTTP protocol, there are many
different ways a client can provide those credentials to the server and you
can control which way libcurl uses them. The default HTTP authentication
method is called 'Basic', which is sending the name and password in clear-text
in the HTTP request, base64-encoded. This is insecure.
At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM,
Negotiate (SPNEGO). You can tell libcurl which one to use
@ -421,13 +420,13 @@ must first ask the server what it supports:
For convenience, you can use the \fICURLAUTH_ANY\fP define (instead of a list
with specific types) which allows libcurl to use whatever method it wants.
When asking for multiple types, libcurl will pick the available one it
considers "best" in its own internal order of preference.
When asking for multiple types, libcurl picks the available one it considers
"best" in its own internal order of preference.
.SH "HTTP POSTing"
We get many questions regarding how to issue HTTP POSTs with libcurl the
proper way. This chapter will thus include examples using both different
versions of HTTP POST that libcurl supports.
proper way. This chapter thus includes examples using both different versions
of HTTP POST that libcurl supports.
The first version is the simple POST, the most common version, that most HTML
pages using the <form> tag uses. We provide a pointer to the data and tell
@ -566,8 +565,8 @@ that describe the individual content-type, size etc. To enable your
application to handicraft this formpost even more, libcurl allows you to
supply your own set of custom headers to such an individual form part. You can
of course supply headers to as many parts as you like, but this little example
will show how you set headers to one specific part when you add that to the
post handle:
shows how you set headers to one specific part when you add that to the post
handle:
.nf
struct curl_slist *headers=NULL;
@ -593,8 +592,8 @@ request. You force an easy handle to go back to GET by using the
.nf
curl_easy_setopt(handle, CURLOPT_HTTPGET, 1L);
.fi
Just setting \fICURLOPT_POSTFIELDS(3)\fP to "" or NULL will *not* stop libcurl
from doing a POST. It will just make it POST without any data to send!
Just setting \fICURLOPT_POSTFIELDS(3)\fP to "" or NULL does *not* stop libcurl
from doing a POST. It just makes it POST without any data to send!
.SH "Converting from deprecated form API to MIME API"
Four rules have to be respected in building the multi-part:
@ -643,9 +642,9 @@ becomes:
.fi
\fIcurl_mime_name\fP always copies the field name. The special file name "-"
is not supported by \fIcurl_mime_file\fP: to read an open file, use
a callback source using fread(). The transfer will be chunked since the data
size is unknown.
is not supported by \fIcurl_mime_file\fP: to read an open file, use a callback
source using fread(). The transfer is be chunk-encoded since the data size is
unknown.
.nf
curl_formadd(&post, &last,
@ -735,10 +734,10 @@ terminal.
Switch on the progress meter by, oddly enough, setting
\fICURLOPT_NOPROGRESS(3)\fP to zero. This option is set to 1 by default.
For most applications however, the built-in progress meter is useless and
what instead is interesting is the ability to specify a progress
callback. The function pointer you pass to libcurl will then be called on
irregular intervals with information about the current transfer.
For most applications however, the built-in progress meter is useless and what
instead is interesting is the ability to specify a progress callback. The
function pointer you pass to libcurl is then called on irregular intervals
with information about the current transfer.
Set the progress callback by using \fICURLOPT_PROGRESSFUNCTION(3)\fP. And pass
a pointer to a function that matches this prototype:
@ -751,13 +750,13 @@ a pointer to a function that matches this prototype:
double ulnow);
.fi
If any of the input arguments is unknown, a 0 will be passed. The first
argument, the 'clientp' is the pointer you pass to libcurl with
\fICURLOPT_PROGRESSDATA(3)\fP. libcurl will not touch it.
If any of the input arguments is unknown, a 0 is provided. The first argument,
the 'clientp' is the pointer you pass to libcurl with
\fICURLOPT_PROGRESSDATA(3)\fP. libcurl does not touch it.
.SH "libcurl with C++"
There's basically only one thing to keep in mind when using C++ instead of C
There is basically only one thing to keep in mind when using C++ instead of C
when interfacing libcurl:
The callbacks CANNOT be non-static class member functions
@ -786,7 +785,7 @@ the proxy for documents, the proxy does the actual request and then it returns
them.
libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl
will ask the proxy for it instead of trying to connect to the actual host
asks the proxy for it instead of trying to connect to the actual remote host
identified in the URL.
If you are using a SOCKS proxy, you may find that libcurl does not quite support
@ -794,11 +793,11 @@ all operations through it.
For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain
restrictions on what can actually happen. A requested URL that might not be a
HTTP URL will be still be passed to the HTTP proxy to deliver back to
libcurl. This happens transparently, and an application may not need to
know. I say "may", because at times it is important to understand that all
operations over an HTTP proxy use the HTTP protocol. For example, you cannot
invoke your own custom FTP commands or even proper FTP directory listings.
HTTP URL is passed to the HTTP proxy to deliver back to libcurl. This happens
transparently, and an application may not need to know. I say "may", because
at times it is important to understand that all operations over an HTTP proxy
use the HTTP protocol. For example, you cannot invoke your own custom FTP
commands or even proper FTP directory listings.
.IP "Proxy Options"
@ -816,7 +815,7 @@ If you want to, you can specify the host name only in the
\fICURLOPT_PROXYPORT(3)\fP.
Tell libcurl what kind of proxy it is with \fICURLOPT_PROXYTYPE(3)\fP (if not,
it will default to assume an HTTP proxy):
it defaults to assuming an HTTP proxy):
.nf
curl_easy_setopt(handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4);
.fi
@ -835,8 +834,7 @@ The proxy environment variable contents should be in the format
\&"[protocol://][user:password@]machine[:port]". Where the protocol:// part
specifies which type of proxy it is, and the optional port number specifies on
which port the proxy operates. If not specified, the internal default port
number will be used and that is most likely not the one you would like it to
be.
number is used and that is most likely not the one you would like it to be.
There are two special environment variables. 'all_proxy' is what sets proxy
for any URL in case the protocol specific variable was not set, and
@ -886,10 +884,10 @@ Tell libcurl to use proxy tunneling like this:
.nf
curl_easy_setopt(handle, CURLOPT_HTTPPROXYTUNNEL, 1L);
.fi
In fact, there might even be times when you want to do plain HTTP
operations using a tunnel like this, as it then enables you to operate on
the remote server instead of asking the proxy to do so. libcurl will not
stand in the way for such innovative actions either!
In fact, there might even be times when you want to do plain HTTP operations
using a tunnel like this, as it then enables you to operate on the remote
server instead of asking the proxy to do so. libcurl does not stand in the way
for such innovative actions either!
.IP "Proxy Auto-Config"
@ -920,14 +918,14 @@ Mozilla JavaScript engine in the past.
Re-cycling the same easy handle several times when doing multiple requests is
the way to go.
After each single \fIcurl_easy_perform(3)\fP operation, libcurl will keep the
After each single \fIcurl_easy_perform(3)\fP operation, libcurl keeps the
connection alive and open. A subsequent request using the same easy handle to
the same host might just be able to use the already open connection! This
reduces network impact a lot.
Even if the connection is dropped, all connections involving SSL to the same
host again, will benefit from libcurl's session ID cache that drastically
reduces re-connection time.
host again, benefit from libcurl's session ID cache that drastically reduces
re-connection time.
FTP connections that are kept alive save a lot of time, as the command-
response round-trips are skipped, and also you do not risk getting blocked
@ -940,23 +938,22 @@ looked up name a lot faster.
Other interesting details that improve performance for subsequent requests
may also be added in the future.
Each easy handle will attempt to keep the last few connections alive for a
while in case they are to be used again. You can set the size of this "cache"
with the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is rarely
any point in changing this value, and if you think of changing this it is
often just a matter of thinking again.
Each easy handle attempts to keep the last few connections alive for a while
in case they are to be used again. You can set the size of this "cache" with
the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is rarely any
point in changing this value, and if you think of changing this it is often
just a matter of thinking again.
To force your upcoming request to not use an already existing connection (it
will even close one first if there happens to be one alive to the same host
you are about to operate on), you can do that by setting
\fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar spirit, you can also forbid
the upcoming request to be "lying" around and possibly get re-used after the
request by setting \fICURLOPT_FORBID_REUSE(3)\fP to 1.
To force your upcoming request to not use an already existing connection, you
can do that by setting \fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar
spirit, you can also forbid the upcoming request to be "lying" around and
possibly get reused after the request by setting
\fICURLOPT_FORBID_REUSE(3)\fP to 1.
.SH "HTTP Headers Used by libcurl"
When you use libcurl to do HTTP requests, it will pass along a series of headers
automatically. It might be good for you to know and understand these. You
can replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option.
When you use libcurl to do HTTP requests, it passes along a series of headers
automatically. It might be good for you to know and understand these. You can
replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option.
.IP "Host"
This header is required by HTTP 1.1 and even many 1.0 servers and should be
@ -969,7 +966,7 @@ anything but default.
.IP "Expect"
When doing POST requests, libcurl sets this header to \&"100-continue" to ask
the server for an "OK" message before it proceeds with sending the data part
of the post. If the posted data amount is deemed "small", libcurl will not use
of the post. If the posted data amount is deemed "small", libcurl does not use
this header.
.SH "Customizing Operations"
@ -1024,9 +1021,10 @@ replace them by simply setting them too:
.fi
.IP "Delete Headers"
If you replace an existing header with one with no contents, you will prevent
the header from being sent. For instance, if you want to completely prevent the
\&"Accept:" header from being sent, you can disable it with code similar to this:
If you replace an existing header with one with no contents, you prevent the
header from being sent. For instance, if you want to completely prevent the
\&"Accept:" header from being sent, you can disable it with code similar to
this:
headers = curl_slist_append(headers, "Accept:");
@ -1037,7 +1035,7 @@ when doing so.
.IP "Enforcing chunked transfer-encoding"
By making sure a request uses the custom header "Transfer-Encoding: chunked"
when doing a non-GET HTTP operation, libcurl will switch over to "chunked"
when doing a non-GET HTTP operation, libcurl switches over to "chunked"
upload, even though the size of the data to upload might be known. By default,
libcurl usually switches over to chunked upload automatically if the upload
data size is unknown.
@ -1061,8 +1059,8 @@ commands exactly as the FTP server expects them (RFC 959 is a good guide
here), and you can only use commands that work on the control-connection
alone. All kinds of commands that require data interchange and thus need a
data-connection must be left to libcurl's own judgment. Also be aware that
libcurl will do its best to change directory to the target directory before
doing any transfer, so if you change directory (with CWD or similar) you might
libcurl does its best to change directory to the target directory before doing
any transfer, so if you change directory (with CWD or similar) you might
confuse libcurl and then it might not attempt to transfer the file in the
correct remote directory.
@ -1084,24 +1082,24 @@ _after_ the data transfer took place the option to \fIcurl_easy_setopt(3)\fP
would instead be called \fICURLOPT_POSTQUOTE(3)\fP and used the exact same
way.
The custom FTP command will be issued to the server in the same order they are
The custom FTP commands are issued to the server in the same order they are
added to the list, and if a command gets an error code returned back from the
server, no more commands will be issued and libcurl will bail out with an
error code (CURLE_QUOTE_ERROR). Note that if you use \fICURLOPT_QUOTE(3)\fP to
send commands before a transfer, no transfer will actually take place when a
quote command has failed.
server, no more commands are issued and libcurl bails out with an error code
(CURLE_QUOTE_ERROR). Note that if you use \fICURLOPT_QUOTE(3)\fP to send
commands before a transfer, no transfer actually takes place when a quote
command has failed.
If you set the \fICURLOPT_HEADER(3)\fP to 1, you will tell libcurl to get
If you set the \fICURLOPT_HEADER(3)\fP to 1, you tell libcurl to get
information about the target file and output "headers" about it. The headers
will be in "HTTP-style", looking like they do in HTTP.
are in "HTTP-style", looking like they do in HTTP.
The option to enable headers or to run custom FTP commands may be useful to
combine with \fICURLOPT_NOBODY(3)\fP. If this option is set, no actual file
content transfer will be performed.
content transfer is performed.
.IP "FTP Custom CUSTOMREQUEST"
If you do want to list the contents of an FTP directory using your own defined
FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP will do just that. "NLST" is the
FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP does just that. "NLST" is the
default one for listing directories but you are free to pass in your idea of a
good alternative.
@ -1133,34 +1131,34 @@ figure out which cookies to use. Set the header file to read cookies from with
\fICURLOPT_COOKIEFILE(3)\fP.
The \fICURLOPT_COOKIEFILE(3)\fP option also automatically enables the cookie
parser in libcurl. Until the cookie parser is enabled, libcurl will not parse
or understand incoming cookies and they will just be ignored. However, when
the parser is enabled the cookies will be understood and the cookies will be
kept in memory and used properly in subsequent requests when the same handle
is used. Many times this is enough, and you may not have to save the cookies
to disk at all. Note that the file you specify to \fICURLOPT_COOKIEFILE(3)\fP
does not have to exist to enable the parser, so a common way to just enable the
parser and not read any cookies is to use the name of a file you know does not
exist.
parser in libcurl. Until the cookie parser is enabled, libcurl does not parse
or understand incoming cookies and they are just be ignored. However, when the
parser is enabled the cookies are understood and the cookies are kept in
memory and used properly in subsequent requests when the same handle is
used. Many times this is enough, and you may not have to save the cookies to
disk at all. Note that the file you specify to \fICURLOPT_COOKIEFILE(3)\fP
does not have to exist to enable the parser, so a common way to just enable
the parser and not read any cookies is to use the name of a file you know does
not exist.
If you would rather use existing cookies that you have previously received with
your Netscape or Mozilla browsers, you can make libcurl use that cookie file
as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as libcurl
will automatically find out what kind of file it is and act accordingly.
If you would rather use existing cookies that you have previously received
with your Netscape or Mozilla browsers, you can make libcurl use that cookie
file as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as
libcurl automatically finds out what kind of file it is and acts accordingly.
Perhaps the most advanced cookie operation libcurl offers, is saving the
entire internal cookie state back into a Netscape/Mozilla formatted cookie
file. We call that the cookie-jar. When you set a file name with
\fICURLOPT_COOKIEJAR(3)\fP, that file name will be created and all received
cookies will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This
enables cookies to get passed on properly between multiple handles without any
\fICURLOPT_COOKIEJAR(3)\fP, that file name is created and all received cookies
get stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enables
cookies to get passed on properly between multiple handles without any
information getting lost.
.SH "FTP Peculiarities We Need"
FTP transfers use a second TCP/IP connection for the data transfer. This is
usually a fact you can forget and ignore but at times this fact will come
back to haunt you. libcurl offers several different ways to customize how the
usually a fact you can forget and ignore but at times this detail comes back
to haunt you. libcurl offers several different ways to customize how the
second connection is being made.
libcurl can either connect to the server a second time or tell the server to
@ -1174,19 +1172,18 @@ and does not exist nor work on all FTP servers.)
You can prevent libcurl from first trying the EPSV command by setting
\fICURLOPT_FTP_USE_EPSV(3)\fP to zero.
In some cases, you will prefer to have the server connect back to you for the
second connection. This might be when the server is perhaps behind a firewall
or something and only allows connections on a single port. libcurl then
informs the remote server which IP address and port number to connect to.
This is made with the \fICURLOPT_FTPPORT(3)\fP option. If you set it to "-",
libcurl will use your system's "default IP address". If you want to use a
particular IP, you can set the full IP address, a host name to resolve to an
IP address or even a local network interface name that libcurl will get the IP
address from.
In some cases, you want to have the server connect back to you for the second
connection. This might be when the server is perhaps behind a firewall or
something and only allows connections on a single port. libcurl then informs
the remote server which IP address and port number to connect to. This is
made with the \fICURLOPT_FTPPORT(3)\fP option. If you set it to "-", libcurl
uses your system's "default IP address". If you want to use a particular IP,
you can set the full IP address, a host name to resolve to an IP address or
even a local network interface name that libcurl gets the IP address from.
When doing the "PORT" approach, libcurl will attempt to use the EPRT and the
LPRT before trying PORT, as they work with more protocols. You can disable
this behavior by setting \fICURLOPT_FTP_USE_EPRT(3)\fP to zero.
When doing the "PORT" approach, libcurl attempts to use the EPRT and the LPRT
before trying PORT, as they work with more protocols. You can disable this
behavior by setting \fICURLOPT_FTP_USE_EPRT(3)\fP to zero.
.SH "MIME API revisited for SMTP and IMAP"
In addition to support HTTP multi-part form fields, the MIME API can be used
@ -1321,8 +1318,8 @@ When you have added the handles you have for the moment (you can still add new
ones at any time), you start the transfers by calling
\fIcurl_multi_perform(3)\fP.
\fIcurl_multi_perform(3)\fP is asynchronous. It will only perform what can be
done now and then return control to your program. It is designed to never
\fIcurl_multi_perform(3)\fP is asynchronous. It only performs what can be done
now and then return control to your program. It is designed to never
block. You need to keep calling the function until all transfers are
completed.
@ -1333,7 +1330,7 @@ sockets/handles. You figure out what to select() for by using
\fIcurl_multi_fdset(3)\fP, that fills in a set of \fIfd_set\fP variables for
you with the particular file descriptors libcurl uses for the moment.
When you then call select(), it will return when one of the file handles signal
When you then call select(), it returns when one of the file handles signal
action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do
what it wants to do. Take note that libcurl does also feature some time-out
code so we advise you to never use long timeouts on select() before you call
@ -1349,8 +1346,8 @@ can use \fIcurl_multi_remove_handle(3)\fP to remove individual easy
handles. Remember that easy handles should be \fIcurl_easy_cleanup(3)\fPed.
When a transfer within the multi stack has finished, the counter of running
transfers (as filled in by \fIcurl_multi_perform(3)\fP) will decrease. When
the number reaches zero, all transfers are done.
transfers (as filled in by \fIcurl_multi_perform(3)\fP) decreases. When the
number reaches zero, all transfers are done.
\fIcurl_multi_info_read(3)\fP can be used to get information about completed
transfers. It then returns the CURLcode for each easy transfer, to allow you
@ -1364,13 +1361,13 @@ to figure out success on each individual transfer.
You can share some data between easy handles when the easy interface is used,
and some data is share automatically when you use the multi interface.
When you add easy handles to a multi handle, these easy handles will
automatically share a lot of the data that otherwise would be kept on a
per-easy handle basis when the easy interface is used.
When you add easy handles to a multi handle, these easy handles automatically
share a lot of the data that otherwise would be kept on a per-easy handle
basis when the easy interface is used.
The DNS cache is shared between handles within a multi handle, making
subsequent name resolving faster, and the connection pool that is kept to
better allow persistent connections and connection re-use is also shared. If
better allow persistent connections and connection reuse is also shared. If
you are using the easy interface, you can still share these between specific
easy handles by using the share interface, see \fIlibcurl-share(3)\fP.

17
docs/libcurl/libcurl-url.3
View file

@ -45,8 +45,8 @@ When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP:
.fi
.SH PARSING
By setting a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed
and stored in the handle. If the URL is not syntactically correct it will
return an error instead.
and stored in the handle. If the URL is not syntactically correct it returns
an error instead.
.nf
rc = curl_url_set(h, CURLUPART_URL,
"https://example.com:449/foo/bar?name=moo", 0);
@ -56,8 +56,8 @@ The zero in the fourth argument is a bitmask for changing specific features.
If successful, this stores the URL in its individual parts within the handle.
.SH REDIRECT
When a handle already contains info about a URL, setting a relative URL will
make it "redirect" to adapt to it.
When a handle already contains info about a URL, setting a relative URL makes
it "redirect" to that.
.nf
rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
.fi
@ -120,13 +120,12 @@ application can then add the string "hat=1" to the query part like this:
rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
.fi
It will even notice the lack of an ampersand (&) separator so it will inject
one too, and the handle's full URL will then equal
"https://example.com/?shoes=2&hat=1".
It notices the lack of an ampersand (&) separator and injects one, and the
handle's full URL then equals "https://example.com/?shoes=2&hat=1".
The appended string can of course also get URL encoded on add, and if asked to
URL encode, the encoding process will skip the '=' character. For example,
append "candy=N&N" to what we already have, and URL encode it to deal with the
URL encode, the encoding process skips the '=' character. For example, append
"candy=N&N" to what we already have, and URL encode it to deal with the
ampersand in the data:
.nf
rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",

18
docs/libcurl/libcurl-ws.3
View file

@ -62,10 +62,10 @@ been received since only frames have set sizes.
libcurl can be told to speak WebSocket in "raw mode" by setting the
\fBCURLWS_RAW_MODE\fP bit to the \fICURLOPT_WS_OPTIONS(3)\fP option.
Raw WebSocket means that libcurl will pass on the data from the network
without parsing it leaving that entirely to the application. This mode assumes
that the user of this knows WebSocket and can parse and figure out the data
all by itself.
Raw WebSocket means that libcurl passes on the data from the network without
parsing it leaving that entirely to the application. This mode assumes that
the user of this knows WebSocket and can parse and figure out the data all by
itself.
This mode is intended for applications that already have a WebSocket
parser/engine that want to switch over to use libcurl for enabling WebSocket,
@ -86,17 +86,17 @@ different API models to use it:
downloads for when the traffic is download oriented.
2. Using \fICURLOPT_CONNECT_ONLY(3)\fP and use the WebSocket recv/send
functions at will.
functions.
.SH "Callback model"
When a write callback is set and a WebSocket transfer is performed, the
callback will be called to deliver all WebSocket data that arrives.
callback is called to deliver all WebSocket data that arrives.
The callback can then call \fIcurl_ws_meta(3)\fP to learn about the details of
the incoming data fragment.
.SH "CONNECT_ONLY model"
By setting \fICURLOPT_CONNECT_ONLY(3)\fP to \fB2L\fP, the transfer will only
establish and setup the WebSocket communication and then return control back
to the application.
By setting \fICURLOPT_CONNECT_ONLY(3)\fP to \fB2L\fP, the transfer only
establishes and setups the WebSocket communication and then returns control
back to the application.
Once such a setup has been successfully performed, the application can proceed
and use \fIcurl_ws_recv(3)\fP and \fIcurl_ws_send(3)\fP freely to exchange

27
docs/libcurl/libcurl.3
View file

@ -37,7 +37,7 @@ language. Look elsewhere for documentation on those.
To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP
for a single individual transfer (in either direction). You then set your
desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options
you set with \fIcurl_easy_setopt(3)\fP stick. They will be used on every
you set with \fIcurl_easy_setopt(3)\fP stick. They are then used for every
repeated use of this handle until you either change the option, or you reset
them all with \fIcurl_easy_reset(3)\fP.
@ -82,7 +82,7 @@ See \fIlibcurl-ws(3)\fP
.RE
.SH "LINKING WITH LIBCURL"
On unix-like machines, there's a tool named curl-config that gets installed
On unix-like machines, there is a tool named curl-config that gets installed
with the rest of the curl stuff when 'make install' is performed.
curl-config is added to make it easier for applications to link with libcurl
@ -114,24 +114,24 @@ libcurl is thread safe but there are a few exceptions. Refer to
\fIlibcurl-thread(3)\fP for more information.
.SH "PERSISTENT CONNECTIONS"
Persistent connections means that libcurl can re-use the same connection for
Persistent connections means that libcurl can reuse the same connection for
several transfers, if the conditions are right.
libcurl will \fBalways\fP attempt to use persistent connections. Whenever you
use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl
will attempt to use an existing connection to do the transfer, and if none
exists it will open a new one that will be subject for re-use on a possible
following call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP.
libcurl always attempts to use persistent connections. Whenever you use
\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl
attempts to use an existing connection to do the transfer, and if none exists
it opens a new one that is subject for reuse on a possible following call to
\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP.
To allow libcurl to take full advantage of persistent connections, you should
do as many of your file transfers as possible using the same handle.
If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all
the possibly open connections held by libcurl will be closed and forgotten.
the possibly open connections held by libcurl are closed and forgotten.
When you have created a multi handle and are using the multi interface, the
connection pool is instead kept in the multi handle so closing and creating
new easy handles to do transfers will not affect them. Instead all added easy
new easy handles to do transfers do not affect them. Instead all added easy
handles can take advantage of the single shared pool.
.SH "GLOBAL CONSTANTS"
There are a variety of constants that libcurl uses, mainly through its
@ -187,10 +187,9 @@ A module like this must have global constant functions of its own, just like
\fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus
has control at the beginning and end of the program and has a place to call
the libcurl functions. If multiple modules in the program use libcurl, they
all will separately call the libcurl functions, and that is OK because only
the first \fIcurl_global_init(3)\fP and the last \fIcurl_global_cleanup(3)\fP
in a program change anything. (libcurl uses a reference count in static
memory).
all separately call the libcurl functions, and that is OK because only the
first \fIcurl_global_init(3)\fP and the last \fIcurl_global_cleanup(3)\fP in a
program change anything. (libcurl uses a reference count in static memory).
In a C++ module, it is common to deal with the global constant situation by
defining a special class that represents the global constant environment of

8
docs/libcurl/libcurl.m4
View file

@ -157,7 +157,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG],
if test $_libcurl_try_link = yes ; then
# we didn't find curl-config, so let's see if the user-supplied
# we did not find curl-config, so let's see if the user-supplied
# link line (or failing that, "-lcurl") is enough.
LIBCURL=${LIBCURL-"$_libcurl_ldflags -lcurl"}
@ -171,7 +171,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG],
AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <curl/curl.h>]],[[
/* Try and use a few common options to force a failure if we are
missing symbols or can't link. */
missing symbols or cannot link. */
int x;
curl_easy_setopt(NULL,CURLOPT_URL,NULL);
x=CURL_ERROR_SIZE;
@ -221,14 +221,14 @@ if (x) {;}
if test "x$_libcurl_protocols" = "x" ; then
# We don't have --protocols, so just assume that all
# We do not have --protocols, so just assume that all
# protocols are available
_libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP"
if test x$libcurl_feature_SSL = xyes ; then
_libcurl_protocols="$_libcurl_protocols HTTPS"
# FTPS wasn't standards-compliant until version
# FTPS was not standards-compliant until version
# 7.11.0 (0x070b00 == 461568)
if test $_libcurl_version -ge 461568; then
_libcurl_protocols="$_libcurl_protocols FTPS"

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

@ -42,7 +42,7 @@ currently set to be used does not support \fICURLOPT_CAINFO(3)\fP.
This is a path identifying a single file containing CA certificates.
The \fBpath\fP pointer will be NULL if there is no default path.
The \fBpath\fP pointer is set to NULL if there is no default path.
.SH PROTOCOLS
All
.SH EXAMPLE

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

@ -42,7 +42,7 @@ currently set to be used does not support \fICURLOPT_CAPATH(3)\fP.
This is a path identifying a directory.
The \fBpath\fP pointer will be NULL if there is no default path.
The \fBpath\fP pointer is set to NULL if there is no default path.
.SH PROTOCOLS
All
.SH EXAMPLE

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

@ -33,8 +33,8 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CERTINFO,
struct curl_certinfo **chainp);
.fi
.SH DESCRIPTION
Pass a pointer to a \fIstruct curl_certinfo *\fP and it will be set to point to
a struct that holds info about the server's certificate chain, assuming you had
Pass a pointer to a \fIstruct curl_certinfo *\fP and it is set to point to a
struct that holds info about the server's certificate chain, assuming you had
\fICURLOPT_CERTINFO(3)\fP enabled when the request was made.
.nf
@ -45,11 +45,11 @@ struct curl_certinfo {
.fi
The \fIcertinfo\fP struct member is an array of linked lists of certificate
information. The \fInum_of_certs\fP struct member is the number of certificates
which is the number of elements in the array. Each certificate's list has items
with textual information in the format "name:content" such as "Subject:Foo",
"Issuer:Bar", etc. The items in each list will vary depending on the SSL
backend and the certificate.
information. The \fInum_of_certs\fP struct member is the number of
certificates which is the number of elements in the array. Each certificate's
list has items with textual information in the format "name:content" such as
\&"Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on
the SSL backend and the certificate.
.SH PROTOCOLS
All TLS-based
.SH EXAMPLE

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