... instead of using future tense.
+ numerous cleanups and improvements
+ stick to "reuse" not "re-use"
+ fewer contractions
Closes #11713
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,
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
[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:,
- 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
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
```
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`
- 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?
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?
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.
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).
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.
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}"
}
~~~
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
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
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
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.
# 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
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:
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
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
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
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
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
## 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.
## 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.
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.
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.
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
sub added {
my ($standalone, $data)=@_;
if(too_old($data)) {
- # don't mention ancient additions
+ # do not mention ancient additions
return "";
}
if($standalone) {
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
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.
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
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
# 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
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 \
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! */
*/
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);
*/
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);
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,
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,
*
***************************************************************************/
/* <DESC>
- * re-using handles to do HTTP persistent connections
+ * reusing handles to do HTTP persistent connections
* </DESC>
*/
#include <stdio.h>
*/
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);
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
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.
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
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
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.
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
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
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.
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.
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.
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)"
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 {
};
.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
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();
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), "
\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
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
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
.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
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
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), "
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.
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 */
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), "
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
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 */
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), "
.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
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), "
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)
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
.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
}
.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"
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.
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
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
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
\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 */
.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)
\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");
.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
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), "
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), "
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);
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.
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
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
"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
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.
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
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];
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.
\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. */
.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,
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
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
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
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
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.
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 */
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.
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
\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.
.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
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
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.
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
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
\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.
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
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
.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
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
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
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
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
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)"
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;
.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.
}
.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.
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
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
.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.
.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
.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
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.
\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
.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
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.
.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.
.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)"
.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)"
.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)"
.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.
.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)"
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.
.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.
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
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
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
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)
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.
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.
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
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
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
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
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
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.
.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
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
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
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"
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
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
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
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
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
.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]:
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
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
.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
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
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
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;
.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:
.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,
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:
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
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
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"
\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
\&"[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
.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"
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
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
.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"
.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:");
.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.
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.
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.
\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.
-
-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.
+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 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
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
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.
\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
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
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.
.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);
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
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",
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,
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
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.
.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
\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
\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
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"}
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;
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"
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
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
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
.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
Pass a pointer to a long to receive the number 1 if the condition provided in
the previous request did not match (see \fICURLOPT_TIMECONDITION(3)\fP). Alas,
if this returns a 1 you know that the reason you did not get data in return is
-because it did not fulfill the condition. The long this argument points to will
-get a zero stored if the condition instead was met. This can also return 1 if
+because it did not fulfill the condition. The long this argument points to
+gets a zero stored if the condition instead was met. This can also return 1 if
the server responded with a 304 HTTP status code, for example after sending a
custom "If-Match-*" header.
.SH PROTOCOLS
it means that the server did not send a valid Content-Type header or that the
protocol used does not support this.
-The \fBct\fP pointer will be NULL or pointing to private memory you MUST NOT
-free it - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
+The \fBct\fP pointer is set to NULL or pointing to private memory. You MUST
+NOT free it - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
+
+The modern way to get this header from a response is to instead use the
+\fIcurl_easy_header(3)\fP function.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
cookies curl knows (expired ones, too). do not forget to call
\fIcurl_slist_free_all(3)\fP on the list after it has been used. If there are
no cookies (cookies for the handle have not been enabled or simply none have
-been received) 'struct curl_slist *' will be set to point to NULL.
+been received) the 'struct curl_slist *' is made a NULL pointer.
Since 7.43.0 cookies that were imported in the Set-Cookie format without a
domain name are not exported by this option.
In cases when you have asked libcurl to follow redirects, the method may not be
the same method the first request would use.
-The \fBmethodp\fP pointer will be NULL or pointing to private memory you MUST
-NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
+The \fBmethodp\fP pointer is NULL or points to private memory. You MUST NOT
+free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
HTTP(S)
In cases when you have asked libcurl to follow redirects, it may not be the same
value you set with \fICURLOPT_URL(3)\fP.
-The \fBurlp\fP pointer will be NULL or pointing to private memory you MUST NOT
-free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
-corresponding CURL handle.
+The \fBurlp\fP pointer is NULL or points to private memory. You MUST NOT free
+- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding
+CURL handle.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
You must tell libcurl to collect this information before the transfer is made,
by using the \fICURLOPT_FILETIME(3)\fP option to \fIcurl_easy_setopt(3)\fP or
-you will unconditionally get a -1 back.
+you this unconditionally gets a -1 back.
Consider using \fICURLINFO_FILETIME_T(3)\fP to be able to extract dates beyond
-the year 2038 on systems using 32 bit longs.
+the year 2038 on systems using 32 bit longs (Windows).
.SH PROTOCOLS
HTTP(S), FTP(S), SFTP
.SH EXAMPLE
You must ask libcurl to collect this information before the transfer is made,
by using the \fICURLOPT_FILETIME(3)\fP option to \fIcurl_easy_setopt(3)\fP or
-you will unconditionally get a -1 back.
+you unconditionally get a -1 back.
This option is an alternative to \fICURLINFO_FILETIME(3)\fP to allow systems
with 32 bit long variables to extract dates outside of the 32bit timestamp
logging on to the remote FTP server. This stores a NULL as pointer if
something is wrong.
-The \fBpath\fP pointer will be NULL or pointing to private memory you MUST NOT
-free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
-corresponding CURL handle.
+The \fBpath\fP pointer is NULL or points to private memory. You MUST NOT free
+- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding
+CURL handle.
.SH PROTOCOLS
FTP(S) and SFTP
.SH EXAMPLE
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the last received HTTP proxy response code
-to a CONNECT request. The returned value will be zero if no such response code
-was available.
+to a CONNECT request. The returned value is zero if no such response code was
+available.
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the version used in the last http
-connection. The returned value will be CURL_HTTP_VERSION_1_0,
-CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, CURL_HTTP_VERSION_3 or 0 if the
-version cannot be determined.
+connection done using this handle. The returned value is
+CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0,
+CURL_HTTP_VERSION_3 or 0 if the version cannot be determined.
.SH PROTOCOLS
HTTP
.SH EXAMPLE
Pass a pointer to a char pointer to receive the pointer to a null-terminated
string holding the IP address of the local end of most recent connection done
with this \fBcurl\fP handle. This string may be IPv6 when that is
-enabled. Note that you get a pointer to a memory area that will be re-used at
-next request so you need to copy the string if you want to keep the
-information.
+enabled. Note that you get a pointer to a memory area that is reused at next
+request so you need to copy the string if you want to keep the information.
-The \fBip\fP pointer will be NULL or pointing to private memory you MUST NOT
-free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
-corresponding CURL handle.
+The \fBip\fP pointer is NULL or points to private memory. You MUST NOT free -
+it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding
+CURL handle.
.SH PROTOCOLS
All
.SH EXAMPLE
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
- /* Perform the request, res will get the return code */
+ /* Perform the transfer */
res = curl_easy_perform(curl);
/* Check for errors */
if((res == CURLE_OK) &&
Pass a pointer to a char pointer to receive the pointer to a null-terminated
string holding the IP address of the most recent connection done with this
\fBcurl\fP handle. This string may be IPv6 when that is enabled. Note that you
-get a pointer to a memory area that will be re-used at next request so you
-need to copy the string if you want to keep the information.
+get a pointer to a memory area that is reused at next request so you need to
+copy the string if you want to keep the information.
-The \fBip\fP pointer will be NULL or pointing to private memory you MUST NOT
-free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
-corresponding CURL handle.
+The \fBip\fP pointer is NULL or points to private memory. You MUST NOT free -
+it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding
+CURL handle.
.SH PROTOCOLS
All network based ones
.SH EXAMPLE
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
- /* Perform the request, res will get the return code */
+ /* Perform the transfer */
res = curl_easy_perform(curl);
/* Check for errors */
if((res == CURLE_OK) &&
possible protocols!
Pass a pointer to a long to receive the version used in the last http
-connection. The returned value will be exactly one of the CURLPROTO_* values:
+connection. The returned value is set to one of the CURLPROTO_* values:
.nf
CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_FTP, CURLPROTO_FTPS,
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive a detailed error code when the most recent
-transfer returned a \fBCURLE_PROXY\fP error. That error code will match the
+transfer returned a \fBCURLE_PROXY\fP error. That error code matches the
\fBCURLproxycode\fP set.
-The error code will be zero (\fBCURLPX_OK\fP) if no response code was
-available.
+The error code is zero (\fBCURLPX_OK\fP) if no response code was available.
.SH PROTOCOLS
All that can be done over SOCKS
.SH EXAMPLE
.SH DESCRIPTION
Pass in a pointer to a char pointer and get the referrer header.
-The \fBhdrp\fP pointer will be NULL or pointing to private memory you MUST NOT
-free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
-corresponding CURL handle.
+The \fBhdrp\fP pointer is NULL or points to private memory you MUST NOT free -
+it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding
+CURL handle.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RESPONSE_CODE, long *codep);
.fi
.SH DESCRIPTION
-Pass a pointer to a long to receive the last received HTTP, FTP, SMTP or
-LDAP (OpenLDAP only) response code. This option was previously known as
-CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier.
-The stored value will be zero if no server response code has been received.
-Note that a proxy's CONNECT response should
-be read with \fICURLINFO_HTTP_CONNECTCODE(3)\fP and not this.
+Pass a pointer to a long to receive the last received HTTP, FTP, SMTP or LDAP
+(OpenLDAP only) response code. This option was previously known as
+CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. The stored value is zero if
+no server response code has been received.
+
+Note that a proxy's CONNECT response should be read with
+\fICURLINFO_HTTP_CONNECTCODE(3)\fP and not this.
.SH PROTOCOLS
HTTP, FTP, SMTP and LDAP
.SH EXAMPLE
issued. The information from the "Retry-After:" header.
While the HTTP header might contain a fixed date string, the
-\fICURLINFO_RETRY_AFTER(3)\fP will always return number of seconds to wait -
+\fICURLINFO_RETRY_AFTER(3)\fP always returns the number of seconds to wait -
or zero if there was no header or the header could not be parsed.
.SH DEFAULT
Returns zero delay if there was no header.
long *cseq);
.fi
.SH DESCRIPTION
-Pass a pointer to a long to receive the next CSeq that will be used by the
-application.
+Pass a pointer to a long to receive the next CSeq that is expected to be used
+by the application.
.SH PROTOCOLS
RTSP
.SH EXAMPLE
long *cseq);
.fi
.SH DESCRIPTION
-Pass a pointer to a long to receive the next CSeq that will be expected by the
-application.
+Pass a pointer to a long to receive the next CSeq that is expected to be used
+by the application.
Listening for server initiated requests is not implemented!
Applications wishing to resume an RTSP session on another connection should
retrieve this info before closing the active connection.
-The \fBid\fP pointer will be NULL or pointing to private memory you MUST NOT
-free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
-corresponding CURL handle.
+The \fBid\fP pointer is NULL or points to private memory. You MUST NOT free -
+it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding
+CURL handle.
.SH PROTOCOLS
RTSP
.SH EXAMPLE
string holding the URL scheme used for the most recent connection done with
this CURL \fBhandle\fP.
-The \fBscheme\fP pointer will be NULL or pointing to private memory you MUST
-NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
+The \fBscheme\fP pointer is NULL or points to private memory. You MUST NOT
+free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
All
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the total amount of bytes that were
-downloaded. The amount is only for the latest transfer and will be reset
-again for each new transfer. This counts actual payload data, what's also
-commonly called body. All meta and header data are excluded and will not be
-counted in this number.
+downloaded. The amount is only for the latest transfer and gets reset again
+for each new transfer. This counts actual payload data, what's also commonly
+called body. All meta and header data is excluded and not included in this
+number.
\fICURLINFO_SIZE_DOWNLOAD_T(3)\fP is a newer replacement that returns a more
sensible variable type.
.fi
.SH DESCRIPTION
Pass a pointer to a \fIcurl_off_t\fP to receive the total amount of bytes that
-were downloaded. The amount is only for the latest transfer and will be reset
+were downloaded. The amount is only for the latest transfer and gets reset
again for each new transfer. This counts actual payload data, what's also
-commonly called body. All meta and header data are excluded and will not be
-counted in this number.
+commonly called body. All meta and header data is excluded from this amount.
.SH PROTOCOLS
All
.SH EXAMPLE
OpenSSL crypto-engines supported. Note that engines are normally implemented
in separate dynamic libraries. Hence not all the returned engines may be
available at runtime. \fBNOTE:\fP you must call \fIcurl_slist_free_all(3)\fP
-on the list pointer once you are done with it, as libcurl will not free the
+on the list pointer once you are done with it, as libcurl does not free this
data for you.
.SH PROTOCOLS
All TLS based ones.
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION,
struct curl_tlssessioninfo **session);
.SH DESCRIPTION
-Pass a pointer to a \fIstruct curl_tlssessioninfo *\fP. The pointer will be
-initialized to refer to a \fIstruct curl_tlssessioninfo *\fP that will contain
-an enum indicating the SSL library used for the handshake and a pointer to the
+Pass a pointer to a \fIstruct curl_tlssessioninfo *\fP. The pointer is
+initialized to refer to a \fIstruct curl_tlssessioninfo *\fP that contains an
+enum indicating the SSL library used for the handshake and a pointer to the
respective internal TLS session structure of this underlying SSL library.
This option may be useful for example to extract certificate information in a
CURLSSLBACKEND_SCHANNEL or CURLSSLBACKEND_MESALINK. (Note that the OpenSSL
forks are all reported as just OpenSSL here.)
-The \fIinternals\fP struct member will point to a TLS library specific pointer
-for the active ("in use") SSL connection, with the following underlying types:
+The \fIinternals\fP struct member points to a TLS library specific pointer for
+the active ("in use") SSL connection, with the following underlying types:
.RS
.IP GnuTLS
\fBgnutls_session_t\fP
This option has not been thoroughly tested with clear text protocols that can
be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with
-\fICURLOPT_USE_SSL(3)\fP. Though you will be able to retrieve the SSL pointer,
-it's possible that before you can do that data (including auth) may have
-already been sent over a connection after it was upgraded.
+\fICURLOPT_USE_SSL(3)\fP. Though you can to retrieve the SSL pointer, it's
+possible that before you can do that, data (including auth) may have already
+been sent over a connection after it was upgraded.
Renegotiation. If unsafe renegotiation or renegotiation in a way that the
certificate is allowed to change is allowed by your SSL library this may occur
Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is
currently processing a chunked (Transfer-encoding: chunked) request with a
current chunk length larger than \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP,
-that pipeline will not be considered for additional requests, even if it is
-shorter than \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP.
+that pipeline is not considered for additional requests, even if it is shorter
+than \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP.
.SH DEFAULT
The default value is 0, which means that the penalization is inactive.
.SH PROTOCOLS
Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is
currently processing a request with a Content-Length larger than this
-\fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP, that pipeline will then not be
-considered for additional requests, even if it is shorter than
+\fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP, that pipeline is not considered
+for additional requests, even if it is shorter than
\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP.
.SH DEFAULT
The default value is 0, which means that the size penalization is inactive.
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAXCONNECTS, long max);
.fi
.SH DESCRIPTION
-Pass a long indicating the \fBmax\fP. The set number will be used as the
-maximum amount of simultaneously open connections that libcurl may keep in its
-connection cache after completed use. By default libcurl will enlarge the size
-for each added easy handle to make it fit 4 times the number of added easy
+Pass a long indicating the \fBmax\fP. The set number is used as the maximum
+amount of simultaneously open connections that libcurl may keep in its
+connection cache after completed use. By default libcurl enlarges the size for
+each added easy handle to make it fit 4 times the number of added easy
handles.
By setting this option, you can prevent the cache size from growing beyond the
long max);
.fi
.SH DESCRIPTION
-Pass a long indicating the \fBmax\fP. The set number will be used as the
-maximum number of concurrent streams for a connections that libcurl should
-support on connections done using HTTP/2.
+Pass a long indicating the \fBmax\fP. The set number is used as the maximum
+number of concurrent streams for a connections that libcurl should support on
+connections done using HTTP/2.
Valid values range from 1 to 2147483647 (2^31 - 1) and defaults to 100. The
value passed here would be honored based on other system resources properties.
long max);
.fi
.SH DESCRIPTION
-Pass a long to indicate \fBmax\fP. The set number will be used as the maximum
+Pass a long to indicate \fBmax\fP. The set number is used as the maximum
amount of simultaneously open connections to a single host (a host being the
same as a host name + port number pair). For each new session to a host,
-libcurl will open a new connection up to the limit set by
-\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. When the limit is reached, the
-sessions will be pending until a connection becomes available. If
-\fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to pipeline if the
-host is capable of it.
+libcurl might open a new connection up to the limit set by
+\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. When the limit is reached, new
+sessions are kept pending until a connection becomes available.
-The default \fBmax\fP value is 0, unlimited. However, for backwards
-compatibility, setting it to 0 when \fICURLMOPT_PIPELINING(3)\fP is 1 will not
-be treated as unlimited. Instead it will open only 1 connection and try to
-pipeline on it.
-
-This set limit is also used for proxy connections, and then the proxy is
-considered to be the host for which this limit counts.
+The default \fBmax\fP value is 0, unlimited. This set limit is also used for
+proxy connections, and then the proxy is considered to be the host for which
+this limit counts.
When more transfers are added to the multi handle than what can be performed
-due to the set limit, they will be queued up waiting for their chance. When
-that happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout will be counted
-inclusive of the waiting time, meaning that if you set a too narrow timeout in
-such a case the transfer might never even start before it times out.
+due to the set limit, they are queued up waiting for their chance. When that
+happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is inclusive of the waiting
+time, meaning that if you set a too narrow timeout in such a case the transfer
+might never even start before it times out.
Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
timeout is however treated as a per-connect timeout.
.SH DESCRIPTION
No function since pipelining was removed in 7.62.0.
-Pass a long. The set \fBmax\fP number will be used as the maximum amount of
+Pass a long. The set \fBmax\fP number is used as the maximum amount of
outstanding requests in an HTTP/1.1 pipeline. This option is only used for
HTTP/1.1 pipelining, not for HTTP/2 multiplexing.
-When this limit is reached, libcurl will use another connection to the same
+When this limit is reached, libcurl creates another connection to the same
host (see \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP), or queue the request until
one of the pipelines to the host is ready to accept a request. Thus, the
total number of requests in-flight is \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP *
long amount);
.fi
.SH DESCRIPTION
-Pass a long for the \fBamount\fP. The set number will be used as the maximum
-number of simultaneously open connections in total using this multi
-handle. For each new session, libcurl will open a new connection up to the
-limit set by \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. When the limit is
-reached, the sessions will be pending until there are available
-connections. If \fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to
-use multiplexing if the host is capable of it.
+Pass a long for the \fBamount\fP. The set number is used as the maximum number
+of simultaneously open connections in total using this multi handle. For each
+new session, libcurl might open a new connection up to the limit set by
+\fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. When the limit is reached, new
+sessions are held pending until there are available connections. If
+\fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl can try multiplexing if the
+host is capable of it.
When more transfers are added to the multi handle than what can be performed
-due to the set limit, they will be queued up waiting for their chance. When
-that happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout will be counted
-inclusive of the waiting time, meaning that if you set a too narrow timeout in
-such a case the transfer might never even start before it times out.
+due to the set limit, they get queued up waiting for their chance. When that
+happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is counted inclusive of the
+waiting time, meaning that if you set a too narrow timeout in such a case the
+transfer might never even start before it times out.
Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
timeout is however treated as a per-connect timeout.
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, long bitmask);
.fi
.SH DESCRIPTION
-Pass in the \fBbitmask\fP parameter to instruct libcurl to enable HTTP
-pipelining and/or HTTP/2 multiplexing for this multi handle.
+Pass in the correct value in the \fBbitmask\fP parameter to instruct libcurl
+to enable multiplexing for this multi handle.
-When enabled, libcurl will attempt to use those protocol features when doing
-parallel requests to the same hosts.
+With multiplexing enabled, libcurl attempts to do multiple transfers over the
+same connection when doing parallel transfers to the same hosts.
-For pipelining, this means that if you add a second request that can use an
-already existing connection, the second request will be \&"piped" on the same
-connection rather than being executed in parallel.
-
-For multiplexing, this means that follow-up requests can re-use an existing
-connection and send the new request multiplexed over that at the same time as
-other transfers are already using that single connection.
-
-There are several other related options that are interesting to tweak and
-adjust to alter how libcurl spreads out requests on different connections or
-not etc.
-
-Before 7.43.0, this option was set to 1 and 0 to enable and disable HTTP/1.1
-pipelining.
-
-Starting in 7.43.0, \fBbitmask\fP's second bit also has a meaning, and you can
-ask for pipelining and multiplexing independently of each other by toggling
-the correct bits.
.IP CURLPIPE_NOTHING (0)
-Default, which means doing no attempts at pipelining or multiplexing.
+Default, which means doing no attempts at multiplexing.
.IP CURLPIPE_HTTP1 (1)
-If this bit is set, libcurl will try to pipeline HTTP/1.1 requests on
-connections that are already established and in use to hosts.
-
This bit is deprecated and has no effect since version 7.62.0.
.IP CURLPIPE_MULTIPLEX (2)
-If this bit is set, libcurl will try to multiplex the new transfer over an
-existing connection if possible. This requires HTTP/2.
+If this bit is set, libcurl tries to multiplex the new transfer over an
+existing connection if possible. This requires HTTP/2 or HTTP/3.
.SH DEFAULT
Since 7.62.0, \fBCURLPIPE_MULTIPLEX\fP is enabled by default.
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHDATA, void *pointer);
.fi
.SH DESCRIPTION
-Set \fIpointer\fP to pass as the last argument to the
-\fICURLMOPT_PUSHFUNCTION(3)\fP callback. The pointer will not be touched or
-used by libcurl itself, only passed on to the callback function.
+Set a \fIpointer\fP to pass as the last argument to the
+\fICURLMOPT_PUSHFUNCTION(3)\fP callback. The pointer is not touched or used by
+libcurl itself, only passed on to the callback function.
.SH DEFAULT
NULL
.SH PROTOCOLS
.SH DESCRIPTION
This callback gets called when a new HTTP/2 stream is being pushed by the
server (using the PUSH_PROMISE frame). If no push callback is set, all offered
-pushes will be denied automatically.
+pushes are denied automatically.
.SH CALLBACK DESCRIPTION
The callback gets its arguments like this:
\fIheaders\fP is a handle used to access push headers using the accessor
functions described below. This only accesses and provides the PUSH_PROMISE
-headers, the normal response headers will be provided in the header callback
-as usual.
+headers, the normal response headers are provided in the header callback as
+usual.
\fIclientp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP
-If the callback returns CURL_PUSH_OK, the 'easy' handle will be added to the
+If the callback returns CURL_PUSH_OK, the new easy handle is added to the
multi handle, the callback must not do that by itself.
The callback can access PUSH_PROMISE headers with two accessor
functions. These functions can only be used from within this callback and they
can only access the PUSH_PROMISE headers: \fIcurl_pushheader_byname(3)\fP and
-\fIcurl_pushheader_bynum(3)\fP. The normal response headers will be passed to
-the header callback for pushed streams just as for normal streams.
+\fIcurl_pushheader_bynum(3)\fP. The normal response headers are passed to the
+header callback for pushed streams just as for normal streams.
The header fields can also be accessed with \fIcurl_easy_header(3)\fP,
introduced in later libcurl versions.
The application has accepted the stream and it can now start receiving data,
the ownership of the CURL handle has been taken over by the application.
.IP "CURL_PUSH_DENY (1)"
-The callback denies the stream and no data for this will reach the
-application, the easy handle will be destroyed by libcurl.
+The callback denies the stream and no data reaches the application, the easy
+handle is destroyed by libcurl.
.IP "CURL_PUSH_ERROROUT (2)"
-Returning this will reject the pushed stream and return an error back on the
+Returning this code rejects the pushed stream and returns an error back on the
parent stream making it get closed with an error. (Added in 7.72.0)
.IP *
All other return codes are reserved for future use.
A data \fIpointer\fP to pass to the socket callback set with the
\fICURLMOPT_SOCKETFUNCTION(3)\fP option.
-This pointer will not be touched by libcurl but will only be passed in to the
-socket callbacks's \fBclientp\fP argument.
+This pointer is not touched by libcurl but is only passed in as the socket
+callbacks's \fBclientp\fP argument.
.SH DEFAULT
NULL
.SH PROTOCOLS
descriptor) status by doing none, one, or multiple calls to the
\fBsocket_callback\fP. The callback function gets status updates with changes
since the previous time the callback was called. If the given callback pointer
-is set to NULL, no callback will be called.
+is set to NULL, no callback is called.
libcurl then expects the application to monitor the sockets for the specific
activities and tell libcurl again when something happens on one of them. Tell
The socket callback should return 0 on success, and -1 on error. If this
callback returns error, \fBall\fP transfers currently in progress in this
-multi handle will be aborted and fail.
+multi handle are aborted and made to fail.
\fBclientp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP.
-\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or will be NULL.
+\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or NULL.
The \fBwhat\fP parameter informs the callback on the status of the given
socket. It can hold one of these values:
A data \fBpointer\fP to pass to the timer callback set with the
\fICURLMOPT_TIMERFUNCTION(3)\fP option.
-This pointer will not be touched by libcurl but will only be passed in to the
-timer callbacks's \fBclientp\fP argument.
+This pointer is not touched by libcurl but is only be passed in to the timer
+callbacks's \fBclientp\fP argument.
.SH DEFAULT
NULL
.SH PROTOCOLS
A \fBtimeout_ms\fP value of -1 passed to this callback means you should delete
the timer. All other values are valid expire times in number of milliseconds.
-The \fBtimer_callback\fP will only be called when the timeout expire time is
-changed.
+The \fBtimer_callback\fP is called when the timeout expire time is changed.
The \fBclientp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP.
The timer callback should return 0 on success, and -1 on error. If this
callback returns error, \fBall\fP transfers currently in progress in this
-multi handle will be aborted and fail.
+multi handle are aborted and made to fail.
This callback can be used instead of, or in addition to,
\fIcurl_multi_timeout(3)\fP.
.SH DESCRIPTION
Enables the use of an abstract Unix domain socket instead of establishing a
TCP connection to a host. The parameter should be a char * to a
-null-terminated string holding the path of the socket. The path will be set to
-\fIpath\fP prefixed by a NULL byte (this is the convention for abstract
+null-terminated string holding the path of the socket. The path is set to
+\fIpath\fP prefixed by a NULL byte. This is the convention for abstract
sockets, however it should be stressed that the path passed to this function
-should not contain a leading NULL).
+should not contain a leading NULL byte.
-On non-supporting platforms, the abstract address will be interpreted as an
-empty string and fail gracefully, generating a runtime error.
+On non-supporting platforms, the abstract address is interpreted as an empty
+string and fails gracefully, generating a runtime error.
This option shares the same semantics as \fICURLOPT_UNIX_SOCKET_PATH(3)\fP in
which documentation more details can be found. Internally, these two options
contents automatically.
You can also opt to just include the Accept-Encoding: header in your request
-with \fICURLOPT_HTTPHEADER(3)\fP but then there will be no automatic
-decompressing when receiving data.
+with \fICURLOPT_HTTPHEADER(3)\fP but then there is no automatic decompressing
+when receiving data.
This is a request, not an order; the server may or may not do it. This option
must be set (to any non-NULL value) or else any unsolicited encoding done by
libcurl how to handle Alt-Svc for the transfers using this handle.
libcurl only accepts Alt-Svc headers over a secure transport, meaning
-HTTPS. It will also only complete a request to an alternative origin if that
+HTTPS. It also only completes a request to an alternative origin if that
origin is properly hosted over HTTPS. These requirements are there to make
sure both the source and the destination are legitimate.
Alternative services are only used when setting up new connections. If there
-exists an existing connection to the host in the connection pool, then that
-will be preferred.
+exists an existing connection to the host in the connection pool, then that is
+preferred.
-Setting any bit will enable the alt-svc engine.
+Setting any bit enables the alt-svc engine.
.IP "CURLALTSVC_READONLYFILE"
Do not write the alt-svc cache back to the file specified with
\fICURLOPT_ALTSVC(3)\fP even if it gets updated. By default a file specified
-with that option will be read and written to as deemed necessary.
+with that option is read and written to as deemed necessary.
.IP "CURLALTSVC_H1"
Accept alternative services offered over HTTP/1.1.
.IP "CURLALTSVC_H2"
-Accept alternative services offered over HTTP/2. This will only be used if
-libcurl was also built to actually support HTTP/2, otherwise this bit will be
-ignored.
+Accept alternative services offered over HTTP/2. This is only used if libcurl
+was also built to actually support HTTP/2, otherwise this bit is ignored.
.IP "CURLALTSVC_H3"
-Accept alternative services offered over HTTP/3. This will only be used if
-libcurl was also built to actually support HTTP/3, otherwise this bit will be
-ignored.
+Accept alternative services offered over HTTP/3. This is only used if libcurl
+was also built to actually support HTTP/3, otherwise this bit is ignored.
.SH DEFAULT
Alt-Svc handling is disabled by default. If \fICURLOPT_ALTSVC(3)\fP is set,
\fICURLOPT_ALTSVC_CTRL(3)\fP has a default value corresponding to
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AUTOREFERER, long autorefer);
.fi
.SH DESCRIPTION
-Pass a long parameter set to 1 to enable this. When enabled, libcurl will
-automatically set the Referer: header field in HTTP requests to the full URL
-where it follows a Location: redirect.
+Pass a long parameter set to 1 to enable this. When enabled, libcurl
+automatically sets the Referer: header field in HTTP requests to the full URL
+when it follows a Location: redirect to a new destination.
The automatic referer is set to the full previous URL even when redirects are
done cross-origin or following redirects to insecure protocols. This is
Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same
as calling this with \fB"aws:amz"\fP in parameter.
.PP
-Example with "Test:Try", when curl will do the algorithm, it will generate
+Example with "Test:Try", when curl uses the algorithm, it generates
\fB"TEST-HMAC-SHA256"\fP for "Algorithm", \fB"x-try-date"\fP and
\fB"X-Try-Date"\fP for "date", \fB"test4_request"\fP for "request type",
\fB"SignedHeaders=content-type;host;x-try-date"\fP for "signed headers"
.PP
-If you use just "test", instead of "test:try",
-test will be use for every strings generated
+If you use just "test", instead of "test:try", test is used for every
+generated string.
.SH DEFAULT
By default, the value of this parameter is NULL.
Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same
Pass a long specifying your preferred \fIsize\fP (in bytes) for the receive
buffer in libcurl. The main point of this would be that the write callback
gets called more often and with smaller chunks. Secondly, for some protocols,
-there's a benefit of having a larger buffer for performance.
+there is a benefit of having a larger buffer for performance.
This is just treated as a request, not an order. You cannot be guaranteed to
actually get the given size.
certificate bundle is assumed to be stored, as established at build time.
(iOS and macOS) When curl uses Secure Transport this option is supported. If
-the option is not set, then curl will use the certificates in the system and
-user Keychain to verify the peer.
+the option is not set, then curl uses the certificates in the system and user
+Keychain to verify the peer.
(Schannel) This option is supported for Schannel in Windows 7 or later but we
recommend not using it until Windows 8 since it works better starting then.
-If the option is not set, then curl will use the certificates in the Windows'
+If the option is not set, then curl uses the certificates in the Windows'
store of root certificates (the default for Schannel).
The application does not have to keep the string around after setting this
Pass a long, this sets the timeout in seconds. This tells libcurl the maximum
time any cached certificate store it has in memory may be kept and reused for
new connections. Once the timeout has expired, a subsequent fetch requiring a
-certificate store will have to build a new one.
+certificate has to reload it.
Building a certificate store from a \fICURLOPT_CAINFO\fP file is a slow
operation so curl may cache the generated certificate store internally to speed
ret = curl_easy_perform(curl);
- /* in this second request, the cache will not be used if more than
- sixty seconds have passed since the previous connection */
+ /* in this second request, the cache is not used if more than
+ sixty seconds passed since the previous connection */
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
.fi
.SH DESCRIPTION
Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With
-this enabled, libcurl will extract lots of information and data about the
+this enabled, libcurl extracts lots of information and data about the
certificates in the certificate chain used in the SSL connection. This data
may then be retrieved after a transfer using \fIcurl_easy_getinfo(3)\fP and
its option \fICURLINFO_CERTINFO(3)\fP.
This callback function gets called by libcurl before a part of the stream is
going to be transferred (if the transfer supports chunks).
-The \fItransfer_info\fP pointer will point to a \fBcurl_fileinfo\fP struct
-with details about the file that is about to get transferred.
+The \fItransfer_info\fP pointer points to a \fBcurl_fileinfo\fP struct with
+details about the file that is about to get transferred.
This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH(3)\fP
option for now.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_DATA, void *pointer);
.fi
.SH DESCRIPTION
-Pass a \fIpointer\fP that will be untouched by libcurl and passed as the ptr
+Pass a \fIpointer\fP that is untouched by libcurl and passed as the ptr
argument to the \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP and
\fICURLOPT_CHUNK_END_FUNCTION(3)\fP.
.SH DEFAULT
void *pointer);
.fi
.SH DESCRIPTION
-Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
+Pass a \fIpointer\fP that remains untouched by libcurl and passed as the first
argument in the closesocket callback set with
\fICURLOPT_CLOSESOCKETFUNCTION(3)\fP.
.SH DEFAULT
\fICURLOPT_CONNECTTIMEOUT_MS(3)\fP is the same function but set in milliseconds.
If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
-are set, the value set last will be used.
+are set, the value set last is used.
The "connection phase" is considered complete when the requested TCP, TLS or
QUIC handshakes are done.
the application can obtain the most recently used socket for special data
transfers.
-Since 7.86.0, this option can be set to '2' and if HTTP or WebSocket are
-used, libcurl will do the request and read all response headers before handing
+Since 7.86.0, this option can be set to '2' and if HTTP or WebSocket are used,
+libcurl performs the request and reads all response headers before handing
over control to the application.
-Transfers marked connect only will not reuse any existing connections and
-connections marked connect only will not be allowed to get reused.
+Transfers marked connect only do not reuse any existing connections and
+connections marked connect only are not allowed to get reused.
If the connect only transfer is done using the multi interface, the particular
easy handle must remain added to the multi handle for as long as the
A numerical IPv6 address must be written within [brackets].
Any of the four values may be empty. When the HOST or PORT is empty, the host
-or port will always match (the request's host or port is ignored).
-When CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to" feature
-will be disabled for the host or port, and the request's host or port will be
-used to establish the network connection.
+or port always match (the request's host or port is ignored). When
+CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to" feature is
+disabled for the host or port, and the request's host or port are used to
+establish the network connection.
This option is suitable to direct the request at a specific server, e.g. at a
specific cluster node in a cluster of servers.
specific request. This is necessary because it is not possible to connect to a
specific host or port in normal (non-tunnel) mode.
-When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl will not copy
-the entire list so you \fBmust\fP keep it around until you no longer use this
+When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy
+the list so you \fBmust\fP keep it around until you no longer use this
\fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on
the list.
Pass a pointer to your callback function, which should match the prototype
shown above.
-Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the
+Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP returns the
\fBCURL_VERSION_CONV\fP feature bit set if this option is provided.
The data to be converted is in a buffer pointed to by the \fIptr\fP parameter.
the network.
If you set a callback pointer to NULL, or do not set it at all, the built-in
-libcurl iconv functions will be used. If HAVE_ICONV was not defined when
-libcurl was built, and no callback has been established, conversion will
-return the \fBCURLE_CONV_REQD\fP error code.
+libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl
+was built, and no callback has been established, the conversion returns the
+\fBCURLE_CONV_REQD\fP error code.
If \fBHAVE_ICONV\fP is defined, \fBCURL_ICONV_CODESET_OF_HOST\fP must also be
defined. For example:
\&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
-The iconv code in libcurl will default the network and UTF8 codeset names as
+The iconv code in libcurl defaults the network and UTF8 codeset names as
follows:
\&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
\&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
-You will need to override these definitions if they are different on your
-system.
+You need to override these definitions if they are different on your system.
.SH DEFAULT
NULL
.SH PROTOCOLS
Pass a pointer to your callback function, which should match the prototype
shown above.
-Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the
+Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP returns the
CURL_VERSION_CONV feature bit set if this option is provided.
The data to be converted is in a buffer pointed to by the \fIptr\fP parameter.
encoding. It is required only for SSL processing.
If you set a callback pointer to NULL, or do not set it at all, the built-in
-libcurl iconv functions will be used. If HAVE_ICONV was not defined when
-libcurl was built, and no callback has been established, conversion will
-return the CURLE_CONV_REQD error code.
+libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl
+was built, and no callback has been established, the conversion returns the
+CURLE_CONV_REQD error code.
If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined.
For example:
\&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
-The iconv code in libcurl will default the network and UTF8 codeset names as
+The iconv code in libcurl defaults the network and UTF8 codeset names as
follows:
\&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
\&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
-You will need to override these definitions if they are different on your
-system.
+You need to override these definitions if they are different on your system.
.SH DEFAULT
NULL
.SH PROTOCOLS
Pass a pointer to your callback function, which should match the prototype
shown above.
-Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the
+Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP returns the
CURL_VERSION_CONV feature bit set if this option is provided.
The data to be converted is in a buffer pointed to by the \fIptr\fP parameter.
network.
If you set a callback pointer to NULL, or do not set it at all, the built-in
-libcurl iconv functions will be used. If HAVE_ICONV was not defined when
-libcurl was built, and no callback has been established, conversion will
-return the CURLE_CONV_REQD error code.
+libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl
+was built, and no callback has been established, the conversion returns the
+CURLE_CONV_REQD error code.
If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined.
For example:
\&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
-The iconv code in libcurl will default the network and UTF8 codeset names as
+The iconv code in libcurl defaults the network and UTF8 codeset names as
follows:
\&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
\&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
-You will need to override these definitions if they are different on your
-system.
+You need to override these definitions if they are different on your system.
.SH DEFAULT
NULL
.SH PROTOCOLS
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIE, char *cookie);
.fi
.SH DESCRIPTION
-Pass a pointer to a null-terminated string as parameter. It will be used to
-set a cookie in the HTTP request. The format of the string should be
+Pass a pointer to a null-terminated string as parameter. It is used to set one
+or more cookies in the HTTP request. The format of the string should be
NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie
should contain.
-If you need to set multiple cookies, set them all using a single option
-concatenated like this: "name1=content1; name2=content2;" etc.
+To set multiple cookies, set them all using a single option concatenated like
+this: "name1=content1; name2=content2;" etc.
This option sets the cookie header explicitly in the outgoing request(s). If
multiple requests are done due to authentication, followed redirections or
-similar, they will all get this cookie passed on.
+similar, they all get this cookie passed on.
The cookies set by this option are separate from the internal cookie storage
-held by the cookie engine and will not be modified by it. If you enable the
-cookie engine and either you have imported a cookie of the same name (e.g. 'foo')
-or the server has set one, it will have no effect on the cookies you set here.
-A request to the server will send both the 'foo' held by the cookie engine and
-the 'foo' held by this option. To set a cookie that is instead held by the
-cookie engine and can be modified by the server use
+held by the cookie engine and they are not be modified by it. If you enable
+the cookie engine and either you have imported a cookie of the same name
+(e.g. 'foo') or the server has set one, it has no effect on the cookies you
+set here. A request to the server sends both the 'foo' held by the cookie
+engine and the 'foo' held by this option. To set a cookie that is instead held
+by the cookie engine and can be modified by the server use
\fICURLOPT_COOKIELIST(3)\fP.
-Using this option multiple times will only make the latest string override the
+Using this option multiple times makes the last set string override the
previous ones.
-This option will not enable the cookie engine. Use \fICURLOPT_COOKIEFILE(3)\fP
+This option does not enable the cookie engine. Use \fICURLOPT_COOKIEFILE(3)\fP
or \fICURLOPT_COOKIEJAR(3)\fP to enable parsing and sending cookies
automatically.
By passing the empty string ("") to this option, you enable the cookie engine
without reading any initial cookies. If you tell libcurl the file name is "-"
-(just a single minus sign), libcurl will instead read from stdin.
+(just a single minus sign), libcurl instead reads from stdin.
This option only \fBreads\fP cookies. To make libcurl write cookies to file,
see \fICURLOPT_COOKIEJAR(3)\fP.
-If you use the Set-Cookie file format and do not specify a domain then the
-cookie is not sent since the domain will never match. To address this, set a
-domain in Set-Cookie line (doing that will include sub-domains) or preferably:
-use the Netscape format.
+If you read cookies from a plain HTTP headers file and it does not specify a
+domain in the Set-Cookie line, then the cookie is not sent since the cookie
+domain cannot match the target URL's. To address this, set a domain in
+Set-Cookie line (doing that includes sub-domains) or preferably: use the
+Netscape format.
-If you use this option multiple times, you just add more files to read.
-Subsequent files will add more cookies.
+If you use this option multiple times, you add more files to read cookies
+from.
The application does not have to keep the string around after setting this
option.
-Setting this option to NULL will (since 7.77.0) explicitly disable the cookie
-engine and clear the list of files to read cookies from.
+Setting this option to NULL (since 7.77.0) explicitly disables the cookie
+engine and clears the list of files to read cookies from.
.SH SECURITY
This document previously mentioned how specifying a non-existing file can also
enable the cookie engine. While true, we strongly advise against using that
-method as it is too hard to be sure what files will stay that way in the long
+method as it is too hard to be sure that files that stay that way in the long
run.
.SH DEFAULT
NULL
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEJAR, char *filename);
.fi
.SH DESCRIPTION
-Pass a \fIfilename\fP as char *, null-terminated. This will make libcurl write
+Pass a \fIfilename\fP as a char *, null-terminated. This makes libcurl write
all internally known cookies to the specified file when
-\fIcurl_easy_cleanup(3)\fP is called. If no cookies are known, no file will be
-created. Specify "-" as filename to instead have the cookies written to
-stdout. Using this option also enables cookies for this session, so if you for
-example follow a location it will make matching cookies get sent accordingly.
+\fIcurl_easy_cleanup(3)\fP is called. If no cookies are kept in memory at that
+time, no file is created. Specify "-" as filename to instead have the cookies
+written to stdout. Using this option also enables cookies for this session, so
+if you for example follow a redirect it makes matching cookies get sent
+accordingly.
-Note that libcurl does not read any cookies from the cookie jar. If you want to
-read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP.
+Note that libcurl does not read any cookies from the cookie jar specified with
+this option. To read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP.
If the cookie jar file cannot be created or written to (when the
-\fIcurl_easy_cleanup(3)\fP is called), libcurl will not and cannot report an
+\fIcurl_easy_cleanup(3)\fP is called), libcurl does not and cannot report an
error for this. Using \fICURLOPT_VERBOSE(3)\fP or
-\fICURLOPT_DEBUGFUNCTION(3)\fP will get a warning to display, but that is the
-only visible feedback you get about this possibly lethal situation.
+\fICURLOPT_DEBUGFUNCTION(3)\fP displays a warning, but that is the only
+visible feedback you get about this possibly lethal situation.
-Since 7.43.0 cookies that were imported in the Set-Cookie format without a
-domain name are not exported by this option.
+Cookies are imported in the Set-Cookie format without a domain name are not
+exported by this option.
The application does not have to keep the string around after setting this
option.
Pass a char * to a \fIcookie\fP string.
Such a cookie can be either a single line in Netscape / Mozilla format or just
-regular HTTP-style header (Set-Cookie: ...) format. This will also enable the
-cookie engine. This adds that single cookie to the internal cookie store.
-
-Exercise caution if you are using this option and multiple transfers may occur.
-If you use the Set-Cookie format and do not specify a domain then the cookie is
-sent for any domain (even after redirects are followed) and cannot be modified
-by a server-set cookie. If a server sets a cookie of the same name (or maybe
-you have imported one) then both will be sent on a future transfer to that
-server, likely not what you intended. To address these issues set a domain in
-Set-Cookie (doing that will include sub-domains) or use the Netscape format as
-shown in EXAMPLE.
+regular HTTP-style header (Set-Cookie: ...) format. This option also enables
+the cookie engine. This adds that single cookie to the internal cookie store.
+
+We strongly advice against loading cookies from a HTTP header file, as that is
+an inferior data exchange format.
+
+Exercise caution if you are using this option and multiple transfers may
+occur. If you use the Set-Cookie format and the string does not specify a
+domain, then the cookie is sent for any domain (even after redirects are
+followed) and cannot be modified by a server-set cookie. If a server sets a
+cookie of the same name (or maybe you have imported one) then both are sent on
+future transfers to that server, likely not what you intended. To address
+these issues set a domain in Set-Cookie (doing that includes sub-domains) or
+much better: use the Netscape file format.
Additionally, there are commands available that perform actions if you pass in
these exact strings:
HTTP
.SH EXAMPLE
.nf
-/* This example shows an inline import of a cookie in Netscape format.
-You can set the cookie as HttpOnly to prevent XSS attacks by prepending
-#HttpOnly_ to the hostname. That may be useful if the cookie will later
-be imported by a browser.
-*/
+/* an inline import of a cookie in Netscape format. */
#define SEP "\\t" /* Tab separates the fields */
SEP "foo" /* Name */
SEP "bar"; /* Value */
-/* my_cookie is imported immediately via CURLOPT_COOKIELIST.
-*/
+/* my_cookie is imported immediately via CURLOPT_COOKIELIST. */
curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie);
-/* The list of cookies in cookies.txt will not be imported until right
-before a transfer is performed. Cookies in the list that have the same
-hostname, path and name as in my_cookie are skipped. That is because
-libcurl has already imported my_cookie and it's considered a "live"
-cookie. A live cookie will not be replaced by one read from a file.
+/* The list of cookies in cookies.txt are not be imported until right
+ before a transfer is performed. Cookies in the list that have the same
+ hostname, path and name as in my_cookie are skipped. That is because
+ libcurl has already imported my_cookie and it's considered a "live"
+ cookie. A live cookie is not replaced by one read from a file.
*/
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt"); /* import */
/* Cookies are exported after curl_easy_cleanup is called. The server
-may have added, deleted or modified cookies by then. The cookies that
-were skipped on import are not exported.
+ may have added, deleted or modified cookies by then. The cookies that
+ were skipped on import are not exported.
*/
curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt"); /* export */
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIESESSION, long init);
.fi
.SH DESCRIPTION
-Pass a long set to 1 to mark this as a new cookie "session". It will force
-libcurl to ignore all cookies it is about to load that are "session cookies"
-from the previous session. By default, libcurl always stores and loads all
-cookies, independent if they are session cookies or not. Session cookies are
-cookies without expiry date and they are meant to be alive and existing for
-this "session" only.
+Pass a long set to 1 to mark this as a new cookie "session". It forces libcurl
+to ignore all cookies it is about to load that are "session cookies" from the
+previous session. By default, libcurl always loads all cookies, independent if
+they are session cookies or not. Session cookies are cookies without expiry
+date and they are meant to be alive and existing for this "session" only.
A "session" is usually defined in browser land for as long as you have your
-browser up, more or less.
+browser up, more or less. libcurl needs the application to use this option to
+tell it when a new session starts, otherwise it assumes everything is still in
+the same session.
.SH DEFAULT
0
.SH PROTOCOLS
When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and
X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the
elements of the certificate chain if a CRL file is passed. Also note that
-\fICURLOPT_CRLFILE(3)\fP will imply \fBCURLSSLOPT_NO_PARTIALCHAIN\fP (see
+\fICURLOPT_CRLFILE(3)\fP implies \fBCURLSSLOPT_NO_PARTIALCHAIN\fP (see
\fICURLOPT_SSL_OPTIONS(3)\fP) since curl 7.71.0 due to an OpenSSL bug.
This option makes sense only when used in combination with the
.nf
#include <curl/curl.h>
-CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CURLU, void *pointer);
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CURLU, CURLU *pointer);
.fi
.SH DESCRIPTION
-Pass in a pointer to the \fIURL\fP to work with. The parameter should be a
-\fICURLU *\fP. Setting \fICURLOPT_CURLU(3)\fP will explicitly override
+Pass in a pointer to the \fIURL\fP handle to work with. The parameter should
+be a \fICURLU *\fP. Setting \fICURLOPT_CURLU(3)\fP explicitly overrides
\fICURLOPT_URL(3)\fP.
\fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a
transfer is started.
-libcurl will use this handle and its contents read-only and will not change
-its contents. An application can update the contents of the URL handle after a
-transfer is done and if the same handle is then used in a subsequent request
-the updated contents will then be used.
+libcurl uses this handle and its contents read-only and does not change its
+contents. An application can update the contents of the URL handle after a
+transfer is done and if the same handle is used in a subsequent request the
+updated contents is used.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
.nf
#include <curl/curl.h>
-CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *request);
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *method);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter.
-When you change the request method by setting \fICURLOPT_CUSTOMREQUEST(3)\fP
-to something, you do not actually change how libcurl behaves or acts in regards
-to the particular request method, it will only change the actual string sent
-in the request.
+When you change the request \fImethod\fP by setting
+\fICURLOPT_CUSTOMREQUEST(3)\fP to something, you do not actually change how
+libcurl behaves or acts in regards to the particular request method, it only
+changes the actual string sent in the request.
Restore to the internal default by setting this to NULL.
For example:
When you tell libcurl to do a HEAD request, but then specify a GET though a
-custom request libcurl will still act as if it sent a HEAD. To switch to a
-proper HEAD use \fICURLOPT_NOBODY(3)\fP, to switch to a proper POST use
+custom request libcurl still acts as if it sent a HEAD. To switch to a proper
+HEAD use \fICURLOPT_NOBODY(3)\fP, to switch to a proper POST use
\fICURLOPT_POST(3)\fP or \fICURLOPT_POSTFIELDS(3)\fP and to switch to a proper
GET use \fICURLOPT_HTTPGET(3)\fP.
Many people have wrongly used this option to replace the entire request with
their own, including multiple headers and POST contents. While that might work
-in many cases, it will cause libcurl to send invalid requests and it could
+in many cases, it might cause libcurl to send invalid requests and it could
possibly confuse the remote server badly. Use \fICURLOPT_POST(3)\fP and
\fICURLOPT_POSTFIELDS(3)\fP to set POST data. Use \fICURLOPT_HTTPHEADER(3)\fP
to replace or extend the set of headers sent by libcurl. Use
For example:
-When you tell libcurl to use a custom request it will behave like a LIST or
-RETR command was sent where it expects data to be returned by the server. As
-such \fICURLOPT_NOBODY(3)\fP should be used when specifying commands such as
+When you tell libcurl to use a custom request it behaves like a LIST or RETR
+command was sent where it expects data to be returned by the server. As such
+\fICURLOPT_NOBODY(3)\fP should be used when specifying commands such as
\fBDELE\fP and \fBNOOP\fP for example.
.IP SMTP
Instead of a \fBHELP\fP or \fBVRFY\fP when issuing SMTP based requests.
\fICURLOPT_DEBUGFUNCTION(3)\fP replaces the standard debug function used when
\fICURLOPT_VERBOSE(3)\fP is in effect. This callback receives debug
information, as specified in the \fItype\fP argument. This function must
-return 0. The \fIdata\fP pointed to by the char * passed to this function WILL
-NOT be null-terminated, but will be exactly of the \fIsize\fP as told by the
+return 0. The \fIdata\fP pointed to by the char * passed to this function is
+not null-terminated, but is exactly of the \fIsize\fP as told by the
\fIsize\fP argument.
The \fIclientp\fP argument is the pointer set with \fICURLOPT_DEBUGDATA(3)\fP.
The data is header (or header-like) data sent to the peer.
.IP CURLINFO_DATA_IN
The data is the unprocessed protocol data received from the peer. Even if the
-data is encoded or compressed, it will not be provided decoded nor
-decompressed to this callback. If you need the data in decoded and
-decompressed form, use \fICURLOPT_WRITEFUNCTION(3)\fP.
+data is encoded or compressed, it is not not provided decoded nor decompressed
+to this callback. If you need the data in decoded and decompressed form, use
+\fICURLOPT_WRITEFUNCTION(3)\fP.
.IP CURLINFO_DATA_OUT
The data is protocol data sent to the peer.
.IP CURLINFO_SSL_DATA_OUT
An unknown or unsupported protocol causes error
\fICURLE_UNSUPPORTED_PROTOCOL\fP when libcurl parses a URL without a
scheme. Parsing happens when \fIcurl_easy_perform(3)\fP or
-\fIcurl_multi_perform(3)\fP is called. The protocols supported by libcurl will
+\fIcurl_multi_perform(3)\fP is called. The protocol set supported by libcurl
vary depending on how it was built. Use \fIcurl_version_info(3)\fP if you need
a list of protocol names supported by the build of libcurl that you are using.
Setting this option to 1 also implies a directory listing even if the URL
does not end with a slash, which otherwise is necessary.
-Do NOT use this option if you also use \fICURLOPT_WILDCARDMATCH(3)\fP as it
-will effectively break that feature then.
+Do not use this option if you also use \fICURLOPT_WILDCARDMATCH(3)\fP as it
+effectively breaks that feature.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
.SH DESCRIPTION
A long parameter set to 1 tells the library to not allow URLs that include a
username.
+
+This is the equivalent to the \fICURLU_DISALLOW_USER\fP flag for the
+\fIcurl_url_set(3)\fP function.
.SH DEFAULT
0 (disabled) - user names are allowed by default.
.SH PROTOCOLS
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
-curl_easy_perform() will return CURLE_LOGIN_DENIED if this option is enabled
-and a URL containing a username is specified.
+curl_easy_perform() returns CURLE_LOGIN_DENIED if this option is enabled and a
+URL containing a username is specified.
.SH "SEE ALSO"
-.BR libcurl-security "(3), ", CURLOPT_PROTOCOLS "(3)"
+.BR libcurl-security "(3), ", CURLOPT_PROTOCOLS "(3), "
+.BR curl_url_set "(3), "
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age);
.fi
.SH DESCRIPTION
-Pass a long, this sets the timeout in seconds. Name resolves will be kept in
-memory and used for this number of seconds. Set to zero to completely disable
-caching, or set to -1 to make the cached entries remain forever. By default,
-libcurl caches this info for 60 seconds.
+Pass a long, this sets the timeout in seconds. Name resolve results are kept
+in memory and used for this number of seconds. Set to zero to completely
+disable caching, or set to -1 to make the cached entries remain forever. By
+default, libcurl caches this info for 60 seconds.
We recommend users not to tamper with this option unless strictly necessary.
If you do, be careful of using large values that can make the cache size grow
to the casual libcurl-app user.
DNS entries have a "TTL" property but libcurl does not use that. This DNS
-cache timeout is entirely speculative that a name will resolve to the same
-address for a certain small amount of time into the future.
+cache timeout is entirely speculative that a name resolves to the same address
+for a small amount of time into the future.
Since version 8.1.0, libcurl prunes entries from the DNS cache if it exceeds
30,000 entries no matter which timeout value is used.
ret = curl_easy_perform(curl);
- /* in this second request, the cache will not be used if more than
+ /* in this second request, the cache is not be used if more than
two seconds have passed since the previous name resolve */
ret = curl_easy_perform(curl);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SHUFFLE_ADDRESSES, long onoff);
.fi
.SH DESCRIPTION
-When a name is resolved and more than one IP address is returned, shuffle the
-order of all returned addresses so that they will be used in a random order.
-This is similar to the ordering behavior of gethostbyname which is no longer
-used on most platforms.
+Pass a long set to 1 to enable this option.
-Addresses will not be reshuffled if a name resolution is completed using the
-DNS cache. \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP can be used together with this
+When a name is resolved and more than one IP address is returned, this
+function shuffles the order of all returned addresses so that they are used in
+a random order. This is similar to the ordering behavior of the legacy
+gethostbyname function which is no longer used on most platforms.
+
+Addresses are not reshuffled if name resolution is completed using the DNS
+cache. \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP can be used together with this
option to reduce DNS cache timeout or disable caching entirely if frequent
reshuffling is needed.
-Since the addresses returned will be reordered randomly, their order will not
-be in accordance with RFC 3484 or any other deterministic order that may be
+Since the addresses returned are randomly reordered, the order is not in
+accordance with RFC 3484 or any other deterministic order that may be
generated by the system's name resolution implementation. This may have
performance impacts and may cause IPv4 to be used before IPv6 or vice versa.
.SH DEFAULT
Has no function since 7.62.0. Do not use!
Pass a long. If the \fIenable\fP value is 1, it tells curl to use a global DNS
-cache that will survive between easy handle creations and deletions. This is
-not thread-safe and this will use a global variable.
+cache that survives between easy handle creations and deletions. This is not
+thread-safe and this uses a global variable.
-\fBWARNING:\fP this option is considered obsolete. Stop using it. Switch over
-to using the share interface instead! See \fICURLOPT_SHARE(3)\fP and
-\fIcurl_share_init(3)\fP.
+See \fICURLOPT_SHARE(3)\fP and \fIcurl_share_init(3)\fP for the correct way to
+share DNS cache between transfers.
.SH DEFAULT
0
.SH PROTOCOLS
This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYSTATUS(3)\fP and
only affects requests to the DoH server.
-Note that if this option is enabled but the server does not support the TLS
-extension, the verification will fail.
+If this option is enabled and the server does not support the TLS extension,
+the verification fails.
.SH DEFAULT
0
.SH PROTOCOLS
must be URL-encoded in the following format: "https://host:port/path". It MUST
specify an HTTPS URL.
-libcurl does not validate the syntax or use this variable until the transfer is
-issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will
-still return \fICURLE_OK\fP.
+libcurl does not validate the syntax or use this variable until the transfer
+is issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP still
+returns \fICURLE_OK\fP.
curl sends POST requests to the given DNS-over-HTTPS URL.
To find the DoH server itself, which might be specified using a name, libcurl
-will use the default name lookup function. You can bootstrap that by providing
-the address for the DoH server with \fICURLOPT_RESOLVE(3)\fP.
+uses the default name lookup function. You can bootstrap that by providing the
+address for the DoH server with \fICURLOPT_RESOLVE(3)\fP.
Disable DoH use again by setting this option to NULL.
.SH "INHERIT OPTIONS"
\fICURLOPT_FTPPORT(3)\fP, a proxy type set to \fBCURLPROXY_SOCKS4\fP or
\fBCURLPROXY_SOCKS5\fP and probably some more.
.SH DEFAULT
-NULL - there is no default DoH URL. If this option is not set, libcurl will use
+NULL - there is no default DoH URL. If this option is not set, libcurl uses
the default name resolver.
.SH PROTOCOLS
All
Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
heap space.
-Note that \fIcurl_easy_setopt(3)\fP will not immediately parse the given
-string so when given a bad DoH URL, libcurl might not detect the problem until
-it later tries to resolve a name with it.
+Note that \fIcurl_easy_setopt(3)\fP does immediately parse the given string so
+when given a bad DoH URL, libcurl might not detect the problem until it later
+tries to resolve a name with it.
.SH "SEE ALSO"
.BR CURLOPT_VERBOSE "(3), " CURLOPT_RESOLVE "(3), "
Deprecated option. It serves no purpose anymore.
Pass a char * to the null-terminated path name to the Entropy Gathering Daemon
-socket. It will be used to seed the random engine for TLS.
+socket. It is used to seed the random engine for TLS.
The application does not have to keep the string around after setting this
option.
}
.fi
.SH AVAILABILITY
-If built with TLS enabled. Only the OpenSSL backend will use this, and only
-with OpenSSL versions before 1.1.0.
+If built with TLS enabled. Only the OpenSSL backend uses this, and only with
+OpenSSL versions before 1.1.0.
This option was deprecated in 7.84.0.
.SH RETURN VALUE
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ERRORBUFFER, char *buf);
.fi
.SH DESCRIPTION
-Pass a char * to a buffer that libcurl \fBmay\fP store human readable error
+Pass a char * to a buffer that libcurl may use to store human readable error
messages on failures or problems. This may be more helpful than just the
return code from \fIcurl_easy_perform(3)\fP and related functions. The buffer
-\fBmust be at least CURL_ERROR_SIZE bytes big\fP.
+must be at least \fBCURL_ERROR_SIZE\fP bytes big.
You must keep the associated buffer available until libcurl no longer needs
-it. Failing to do so will cause odd behavior or even crashes. libcurl will
+it. Failing to do so might cause odd behavior or even crashes. libcurl might
need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same option
again to use a different pointer.
Do not rely on the contents of the buffer unless an error code was returned.
-Since 7.60.0 libcurl will initialize the contents of the error buffer to an
-empty string before performing the transfer. For earlier versions if an error
-code was returned but there was no error detail then the buffer is untouched.
+Since 7.60.0 libcurl initializes the contents of the error buffer to an empty
+string before performing the transfer. For earlier versions if an error code
+was returned but there was no error detail then the buffer was untouched.
Consider \fICURLOPT_VERBOSE(3)\fP and \fICURLOPT_DEBUGFUNCTION(3)\fP to better
debug and trace why errors happen.
return the page normally, ignoring that code.
This method is not fail-safe and there are occasions where non-successful
-response codes will slip through, especially when authentication is involved
+response codes slip through, especially when authentication is involved
(response codes 401 and 407).
You might get some amounts of headers transferred before this situation is
detected, like when a "100-continue" is received as a response to a POST/PUT
and a 401 or 407 is received immediately afterwards.
-When this option is used and an error is detected, it will cause the
-connection to get closed and \fICURLE_HTTP_RETURNED_ERROR\fP is returned.
+When this option is used and an error is detected, it causes the connection to
+get closed and \fICURLE_HTTP_RETURNED_ERROR\fP is returned.
.SH DEFAULT
0, do not fail on error
.SH PROTOCOLS
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FILETIME, long gettime);
.fi
.SH DESCRIPTION
-Pass a long. If it is 1, libcurl will attempt to get the modification time of
-the remote document in this operation. This requires that the remote server
-sends the time or replies to a time querying command. The
-\fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME(3)\fP
-argument can be used after a transfer to extract the received time (if any).
+Pass a long. If it is 1, libcurl attempts to get the modification time of the
+remote document in this operation. This requires that the remote server sends
+the time or replies to a time querying command. The \fIcurl_easy_getinfo(3)\fP
+function with the \fICURLINFO_FILETIME(3)\fP argument can be used after a
+transfer to extract the received time (if any).
.SH DEFAULT
0
.SH PROTOCOLS
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_DATA,
void *pointer);
.SH DESCRIPTION
-Pass a pointer that will be untouched by libcurl and passed as the ptr
-argument to the \fICURLOPT_FNMATCH_FUNCTION(3)\fP.
+Pass a pointer that is untouched by libcurl and passed as the ptr argument to
+the \fICURLOPT_FNMATCH_FUNCTION(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
.fi
.SH DESCRIPTION
A long parameter set to 1 tells the library to follow any Location: header
-that the server sends as part of an HTTP header in a 3xx response. The
-Location: header can specify a relative or an absolute URL to follow.
+redirects that a HTTP server sends in a 30x response. The Location: header can
+specify a relative or an absolute URL to follow.
-libcurl will issue another request for the new URL and follow new Location:
-headers all the way until no more such headers are returned.
-\fICURLOPT_MAXREDIRS(3)\fP can be used to limit the number of redirects
-libcurl will follow.
+libcurl issues another request for the new URL and follows subsequent new
+Location: redirects all the way until no more such headers are returned or the
+maximum limit is reached. \fICURLOPT_MAXREDIRS(3)\fP is used to limit the
+number of redirects libcurl follows.
-libcurl limits what protocols it automatically follows to. The accepted
-protocols are set with \fICURLOPT_REDIR_PROTOCOLS(3)\fP. By default libcurl
-will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). Older versions of
-libcurl allowed all protocols on redirect except those disabled for security
-reasons: Since 7.19.4 FILE and SCP are disabled, and since 7.40.0 SMB and SMBS
-are also disabled.
+libcurl restricts what protocols it automatically follow redirects to. The
+accepted target protocols are set with \fICURLOPT_REDIR_PROTOCOLS(3)\fP. By
+default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects.
-When following a Location:, the 3xx response code that redirected it also
-dictates which request method it will use in the subsequent request: For 301,
-302 and 303 responses libcurl will switch method from POST to GET unless
-\fICURLOPT_POSTREDIR(3)\fP instructs libcurl otherwise. All other 3xx codes
-will make libcurl send the same method again.
+When following a redirect, the specific 30x response code also dictates which
+request method libcurl uses in the subsequent request: For 301, 302 and 303
+responses libcurl switches method from POST to GET unless
+\fICURLOPT_POSTREDIR(3)\fP instructs libcurl otherwise. All other redirect
+response codes make libcurl use the same method again.
For users who think the existing location following is too naive, too simple
or just lacks features, it is easy to instead implement your own redirect
follow logic with the use of \fIcurl_easy_getinfo(3)\fP's
\fICURLINFO_REDIRECT_URL(3)\fP option instead of using
\fICURLOPT_FOLLOWLOCATION(3)\fP.
+.SH NOTE
+Since libcurl changes method or not based on the specific HTTP response code,
+setting \fICURLOPT_CUSTOMREQUEST(3)\fP while following redirects may change
+what libcurl would otherwise do and if not that carefully may even make it
+misbehave since \fICURLOPT_CUSTOMREQUEST(3)\fP overrides the method libcurl
+would otherwise select internally.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
Pass a long. Set \fIclose\fP to 1 to make libcurl explicitly close the
connection when done with the transfer. Normally, libcurl keeps all
connections alive when done with one transfer in case a succeeding one follows
-that can re-use them. This option should be used with caution and only if you
+that can reuse them. This option should be used with caution and only if you
understand what it does as it can seriously impact performance.
-Set to 0 to have libcurl keep the connection open for possible later re-use
+Set to 0 to have libcurl keep the connection open for possible later reuse
(default behavior).
.SH DEFAULT
0
.fi
.SH DESCRIPTION
Pass a long. Set to 1 to make the next transfer use a new (fresh) connection
-by force instead of trying to re-use an existing one. This option should be
-used with caution and only if you understand what it does as it may seriously
-impact performance.
+by force instead of trying to reuse an existing one. This option should be
+used with caution and only if you understand what it does as it may impact
+performance negatively.
Related functionality is \fICURLOPT_FORBID_REUSE(3)\fP which makes sure the
-connection is closed after use so that it will not be re-used.
+connection is closed after use so that it cannot be reused.
-Set \fIfresh\fP to 0 to have libcurl attempt re-using an existing connection
+Set \fIfresh\fP to 0 to have libcurl attempt reusing an existing connection
(default behavior).
.SH DEFAULT
0
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. It specifies that the
-FTP transfer will be made actively and the given string will be used to get
-the IP address to use for the FTP PORT instruction.
+FTP transfer should be made actively and the given string is used to get the
+IP address to use for the FTP PORT instruction.
-The PORT instruction tells the remote server to connect to our specified IP
-address. The string may be a plain IP address, a host name, a network
-interface name (under Unix) or just a '-' symbol to let the library use your
-system's default IP address. Default FTP operations are passive, and thus
-will not use PORT.
+The PORT instruction tells the remote server to do a TCP connect to our
+specified IP address. The string may be a plain IP address, a host name, a
+network interface name (under Unix) or just a '-' symbol to let the library
+use your system's default IP address. Default FTP operations are passive, and
+does not use the PORT command.
The address can be followed by a ':' to specify a port, optionally followed by
a '-' to specify a port range. If the port specified is 0, the operating
-system will pick a free port. If a range is provided and all ports in the
-range are not available, libcurl will report CURLE_FTP_PORT_FAILED for the
+system picks a free port. If a range is provided and all ports in the range
+are not available, libcurl reports CURLE_FTP_PORT_FAILED for the
handle. Invalid port/range settings are ignored. IPv6 addresses followed by a
port or port range have to be in brackets. IPv6 addresses without port/range
specifier can be in brackets.
We strongly advise against specifying the address with a name, as it causes
libcurl to do a blocking name resolve call to retrieve the IP address. That
-name resolve operation will \fBnot\fP use DNS-over-HTTPS even if
+name resolve operation does \fBnot\fP use DNS-over-HTTPS even if
\fICURLOPT_DOH_URL(3)\fP is set.
+Using anything else than "-" for this option should typically only be done if
+you have special knowledge and confirmation that it works.
+
You disable PORT again and go back to using the passive version by setting
this option to NULL.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ALTERNATIVE_TO_USER,
char *cmd);
.SH DESCRIPTION
-Pass a char * as parameter, pointing to a string which will be used to
-authenticate if the usual FTP "USER user" and "PASS password" negotiation
-fails. This is currently only known to be required when connecting to
-Tumbleweed's Secure Transport FTPS server using client certificates for
-authentication.
+Pass a char * as parameter, pointing to a string which is used to authenticate
+if the usual FTP "USER user" and "PASS password" negotiation fails. This is
+currently only known to be required when connecting to Tumbleweed's Secure
+Transport FTPS server using client certificates for authentication.
The application does not have to keep the string around after setting this
option.
long create);
.SH DESCRIPTION
Pass a long telling libcurl to \fIcreate\fP the dir. If the value is
-\fICURLFTP_CREATE_DIR\fP (1), libcurl will attempt to create any remote
-directory that it fails to "move" into.
+\fICURLFTP_CREATE_DIR\fP (1), libcurl may create any remote directory that it
+fails to "move" into.
For FTP requests, that means a CWD command fails. CWD being the command that
changes working directory.
-For SFTP requests, libcurl will attempt to create the remote directory if it
-cannot obtain a handle to the target-location. The creation will fail if a file
-of the same name as the directory to create already exists or lack of
-permissions prevents creation.
+For SFTP requests, libcurl may create the remote directory if it cannot obtain
+a handle to the target-location. The creation fails if a file of the same name
+as the directory to create already exists or lack of permissions prevents
+creation.
Setting \fIcreate\fP to \fICURLFTP_CREATE_DIR_RETRY\fP (2), tells libcurl to
retry the CWD command again if the subsequent \fBMKD\fP command fails. This is
deep hierarchies this means many commands. This is how RFC 1738 says it should
be done. This is the default but the slowest behavior.
.IP CURLFTPMETHOD_NOCWD
-libcurl does no CWD at all. libcurl will do SIZE, RETR, STOR etc and give a
-full path to the server for all these commands. This is the fastest behavior.
+libcurl makes no CWD at all. libcurl does SIZE, RETR, STOR etc and gives a
+full path to the server for all these commands. This is the fastest behavior
+since it skips having to change directories.
.IP CURLFTPMETHOD_SINGLECWD
libcurl does one CWD with the full target directory and then operates on the
file \&"normally" (like in the multicwd case). This is somewhat more standards
.SH DESCRIPTION
Pass a long. If \fIskip\fP is set to 1, it instructs libcurl to not use the IP
address the server suggests in its 227-response to libcurl's PASV command when
-libcurl connects the data connection. Instead libcurl will re-use the same IP
-address it already uses for the control connection. But it will use the port
+libcurl connects the data connection. Instead libcurl reuses the same IP
+address it already uses for the control connection. It still uses the port
number from the 227-response.
-This option thus allows libcurl to work around broken server installations
-that due to NATs, firewalls or incompetence report the wrong IP address
-back. Setting the option also reduces the risk for various sorts of client
+This option allows libcurl to work around broken server installations or funny
+network setups that due to NATs, firewalls or incompetence report the wrong IP
+address. Setting this option also reduces the risk for various sorts of client
abuse by malicious servers.
This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
.SH DESCRIPTION
If enabled, this option makes libcurl use CCC (Clear Command Channel). It
shuts down the SSL/TLS layer after authenticating. The rest of the control
-channel communication will be unencrypted. This allows NAT routers to follow
+channel communication remains unencrypted. This allows NAT routers to follow
the FTP transaction. Pass a long using one of the values below
.IP CURLFTPSSL_CCC_NONE
do not attempt to use CCC.
.SH DESCRIPTION
Pass a long. If the value is 1, it tells curl to use the EPRT command when
doing active FTP downloads (which is enabled by
-\fICURLOPT_FTPPORT(3)\fP). Using EPRT means that it will first attempt to use
-EPRT before using PORT, but if you pass zero to this option, it will not try
-using EPRT, only plain PORT.
+\fICURLOPT_FTPPORT(3)\fP). Using EPRT means that libcurl first attempts to use
+EPRT before using PORT, but if you pass zero to this option, it avoids using
+EPRT, only plain PORT.
-If the server is an IPv6 host, this option will have no effect as EPRT is
-necessary then.
+The EPRT command is a slightly newer addition to the FTP protocol than PORT
+and is the preferred command to use since it enables IPv6 to be used. Very old
+FTP servers might not support it, which is why libcurl has a fallback
+mechanism. Sometimes that fallback is not enough and then this option might
+come handy.
+
+If the server is an IPv6 host, this option has no effect as EPRT is necessary
+then.
.SH DEFAULT
.SH PROTOCOLS
.SH EXAMPLE
.SH DESCRIPTION
Pass \fIepsv\fP as a long. If the value is 1, it tells curl to use the EPSV
command when doing passive FTP downloads (which it does by default). Using
-EPSV means that it will first attempt to use EPSV before using PASV, but if
-you pass zero to this option, it will not try using EPSV, only plain PASV.
+EPSV means that libcurl first attempts to use the EPSV command before using
+PASV. If you pass zero to this option, it does not use EPSV, only plain PASV.
-If the server is an IPv6 host, this option will have no effect as of 7.12.3.
+The EPSV command is a slightly newer addition to the FTP protocol than PASV
+and is the preferred command to use since it enables IPv6 to be used. Very old
+FTP servers might not support it, which is why libcurl has a fallback
+mechanism. Sometimes that fallback is not enough and then this option might
+come handy.
+
+If the server is an IPv6 host, this option has no effect.
.SH DEFAULT
1
.SH PROTOCOLS
char *client_ip);
.fi
.SH DESCRIPTION
-When this parameter is set to a valid IPv4 or IPv6, the library will
-not send this address in the HAProxy PROXY protocol
-v1 header at beginning of the connection.
-
-This option is primarily useful when sending test requests to verify that
-a service is working as intended.
+When this parameter is set to a valid IPv4 or IPv6 numerical address, the
+library sends this address as client address in the HAProxy PROXY protocol v1
+header at beginning of the connection.
+This option is an alternative to \fICURLOPT_HAPROXYPROTOCOL(3)\fP as that one
+cannot use a specified address.
.SH DEFAULT
-no HAProxy header will be sent
+NULL, no HAProxy header is sent
.SH PROTOCOLS
HTTP, HAProxy PROTOCOL
.SH EXAMPLE
to.
If \fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP is used,
-\fIpointer\fP will be passed in to the respective callback.
+\fIpointer\fP is passed in to the respective callback.
If neither of those options are set, \fIpointer\fP must be a valid FILE * and
-it will be used by a plain fwrite() to write headers to.
+it is used by a plain fwrite() to write headers to.
If you are using libcurl as a win32 DLL, you \fBMUST\fP use a
\fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP if you set
-this option or you will experience crashes.
+this option or you might experience crashes.
.SH DEFAULT
NULL
.SH PROTOCOLS
Pass a pointer to your callback function, which should match the prototype
shown above.
-This function gets called by libcurl as soon as it has received header
-data. The header callback will be called once for each header and only
+This callback function gets invoked by libcurl as soon as it has received
+header data. The header callback is called once for each header and only
complete header lines are passed on to the callback. Parsing headers is easy
to do using this callback. \fIbuffer\fP points to the delivered data, and the
-size of that data is \fInitems\fP; \fIsize\fP is always 1. Do not assume that
-the header line is null-terminated!
+size of that data is \fInitems\fP; \fIsize\fP is always 1. The provide header
+line is not null-terminated!
The pointer named \fIuserdata\fP is the one you set with the
\fICURLOPT_HEADERDATA(3)\fP option.
Your callback should return the number of bytes actually taken care of. If
-that amount differs from the amount passed to your callback function, it will
-signal an error condition to the library. This will cause the transfer to get
-aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
+that amount differs from the amount passed to your callback function, it
+signals an error condition to the library. This causes the transfer to get
+aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP.
You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0)
If this option is not set, or if it is set to NULL, but
\fICURLOPT_HEADERDATA(3)\fP is set to anything but NULL, the function used to
-accept response data will be used instead. That is, it will be the function
-specified with \fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or
-NULL - the default, stream-writing function.
+accept response data is used instead. That is the function specified with
+\fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or NULL - the
+default, stream-writing function.
-It's important to note that the callback will be invoked for the headers of
-all responses received after initiating a request and not just the final
+It's important to note that the callback is invoked for the headers of all
+responses received after initiating a request and not just the final
response. This includes all responses which occur during authentication
negotiation. If you need to operate on only the headers from the final
-response, you will need to collect headers in the callback yourself and use
-HTTP status lines, for example, to delimit response boundaries.
+response, you need to collect headers in the callback yourself and use HTTP
+status lines, for example, to delimit response boundaries.
For an HTTP transfer, the status line and the blank line preceding the response
body are both included as headers and passed to this function.
header among the regular response-headers mention what header(s) to expect in
the trailer.
-For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get
-called with the server responses to the commands that libcurl sends.
+For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function gets called
+with the server responses to the commands that libcurl sends.
+
+A more convenient way to get HTTP headers might be to use
+\fIcurl_easy_header(3)\fP.
.SH LIMITATIONS
libcurl does not unfold HTTP "folded headers" (deprecated since RFC 7230). A
folded header is a header that continues on a subsequent line and starts with
-a whitespace. Such folds will be passed to the header callback as a separate
-one, although strictly it is just a continuation of the previous line.
+a whitespace. Such folds are passed to the header callback as separate ones,
+although strictly they are just continuations of the previous lines.
.SH DEFAULT
Nothing.
.SH PROTOCOLS
mutually exclusive options are:
\fBCURLHEADER_UNIFIED\fP - the headers specified in
-\fICURLOPT_HTTPHEADER(3)\fP will be used in requests both to servers and
-proxies. With this option enabled, \fICURLOPT_PROXYHEADER(3)\fP will not have
+\fICURLOPT_HTTPHEADER(3)\fP are used in requests both to servers and
+proxies. With this option enabled, \fICURLOPT_PROXYHEADER(3)\fP does not have
any effect.
\fBCURLHEADER_SEPARATE\fP - makes \fICURLOPT_HTTPHEADER(3)\fP headers only get
sent to a server and not to a proxy. Proxy headers must be set with
\fICURLOPT_PROXYHEADER(3)\fP to get used. Note that if a non-CONNECT request
-is sent to a proxy, libcurl will send both server headers and proxy
-headers. When doing CONNECT, libcurl will send \fICURLOPT_PROXYHEADER(3)\fP
-headers only to the proxy and then \fICURLOPT_HTTPHEADER(3)\fP headers only to
-the server.
+is sent to a proxy, libcurl sends both server headers and proxy headers. When
+doing CONNECT, libcurl sends \fICURLOPT_PROXYHEADER(3)\fP headers only to the
+proxy and then \fICURLOPT_HTTPHEADER(3)\fP headers only to the server.
.SH DEFAULT
CURLHEADER_SEPARATE (changed in 7.42.1, used CURLHEADER_UNIFIED before then)
.SH PROTOCOLS
.SH DESCRIPTION
Make the \fIfilename\fP point to a file name to load an existing HSTS cache
from, and to store the cache in when the easy handle is closed. Setting a file
-name with this option will also enable HSTS for this handle (the equivalent of
+name with this option also enables HSTS for this handle (the equivalent of
setting \fICURLHSTS_ENABLE\fP with \fICURLOPT_HSTS_CTRL(3)\fP).
If the given file does not exist or contains no HSTS entries at startup, the
-HSTS cache will simply start empty. Setting the file name to NULL or "" will
-only enable HSTS without reading from or writing to any file.
+HSTS cache simply starts empty. Setting the file name to NULL or "" only
+enables HSTS without reading from or writing to any file.
-If this option is set multiple times, libcurl will load cache entries from
-each given file but will only store the last used name for later writing.
+If this option is set multiple times, libcurl loads cache entries from each
+given file but only stores the last used name for later writing.
.SH "FILE FORMAT"
The HSTS cache is saved to and loaded from a text file with one entry per
physical line. Each line in the file has the following format:
.fi
.SH DESCRIPTION
Data \fIpointer\fP to pass to the HSTS read function. If you use the
-\fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you will get as
-input in the 3rd argument to the callback.
+\fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you get as input
+in the 3rd argument to the callback.
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
-This will return CURLE_OK.
+This returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSREADFUNCTION "(3), " CURLOPT_HSTSWRITEDATA "(3), "
.BR CURLOPT_HSTSWRITEFUNCTION "(3), "
in-memory HSTS cache.
Set the \fIclientp\fP argument with the \fICURLOPT_HSTSREADDATA(3)\fP option
-or it will be NULL.
+or it is NULL.
When this callback is invoked, the \fIsts\fP pointer points to a populated
struct: Copy the host name to \fIname\fP (no longer than \fInamelen\fP
The callback should return \fICURLSTS_OK\fP if it returns a name and is
prepared to be called again (for another host) or \fICURLSTS_DONE\fP if it has
no entry to return. It can also return \fICURLSTS_FAIL\fP to signal
-error. Returning \fICURLSTS_FAIL\fP will stop the transfer from being
-performed and make \fICURLE_ABORTED_BY_CALLBACK\fP get returned.
+error. Returning \fICURLSTS_FAIL\fP stops the transfer from being performed
+and make \fICURLE_ABORTED_BY_CALLBACK\fP get returned.
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
-This will return CURLE_OK.
+This returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSREADDATA "(3), " CURLOPT_HSTSWRITEFUNCTION "(3), "
.BR CURLOPT_HSTS "(3), " CURLOPT_HSTS_CTRL "(3), "
.fi
.SH DESCRIPTION
Data \fIpointer\fP to pass to the HSTS write function. If you use the
-\fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you will get as
+\fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you get as
input in the fourth argument to the callback.
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
-This will return CURLE_OK.
+This returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSWRITEFUNCTION "(3), " CURLOPT_HSTSREADDATA "(3), "
.BR CURLOPT_HSTSREADFUNCTION "(3), "
it.
Set the \fIclientp\fP argument with the \fICURLOPT_HSTSWRITEDATA(3)\fP option
-or it will be NULL.
-
+or it is NULL.
When the callback is invoked, the \fIsts\fP pointer points to a populated
struct: Read the host name to 'name' (it is \fInamelen\fP bytes long and null
terminated. The \fIincludeSubDomains\fP field is non-zero if the entry matches
using the syntax YYYYMMDD HH:MM:SS.
The callback should return \fICURLSTS_OK\fP if it succeeded and is prepared to
-be called again (for another host) or \fICURLSTS_DONE\fP if there's nothing
+be called again (for another host) or \fICURLSTS_DONE\fP if there is nothing
more to do. It can also return \fICURLSTS_FAIL\fP to signal error.
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
-This will return CURLE_OK.
+This returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSWRITEDATA "(3), " CURLOPT_HSTSWRITEFUNCTION "(3), "
.BR CURLOPT_HSTS "(3), " CURLOPT_HSTS_CTRL "(3), "
.SH DESCRIPTION
HSTS (HTTP Strict Transport Security) means that an HTTPS server can instruct
the client to not contact it again over clear-text HTTP for a certain period
-into the future. libcurl will then automatically redirect HTTP attempts to
-such hosts to instead use HTTPS. This is done by libcurl retaining this
-knowledge in an in-memory cache.
+into the future. libcurl then automatically redirects HTTP attempts to such
+hosts to instead use HTTPS. This is done by libcurl retaining this knowledge
+in an in-memory cache.
Populate the long \fIbitmask\fP with the correct set of features to instruct
libcurl how to handle HSTS for the transfers using this handle.
Pass a pointer to a linked list of \fIaliases\fP to be treated as valid HTTP
200 responses. Some servers respond with a custom header response line. For
example, SHOUTcast servers respond with "ICY 200 OK". Also some old Icecast
-1.3.x servers will respond like that for certain user agent headers or in
-absence of such. By including this string in your list of aliases, the
-response will be treated as a valid HTTP header line such as "HTTP/1.0 200
-OK".
+1.3.x servers respond like that for certain user agent headers or in absence
+of such. By including this string in your list of aliases, the response gets
+treated as a valid HTTP header line such as "HTTP/1.0 200 OK".
The linked list should be a fully valid list of struct curl_slist structs, and
be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and
Pass a long as parameter, which is set to a bitmask, to tell libcurl which
authentication method(s) you want it to use speaking to the remote server.
-The available bits are listed below. If more than one bit is set, libcurl will
-first query the site to see which authentication methods it supports and then
-pick the best one you allow it to use. For some methods, this will induce an
+The available bits are listed below. If more than one bit is set, libcurl
+first queries the host to see which authentication methods it supports and
+then picks the best one you allow it to use. For some methods, this induces an
extra network round-trip. Set the actual name and password with the
\fICURLOPT_USERPWD(3)\fP option or with the \fICURLOPT_USERNAME(3)\fP and the
\fICURLOPT_PASSWORD(3)\fP options.
HTTP Digest authentication with an IE flavor. Digest authentication is
defined in RFC 2617 and is a more secure way to do authentication over public
networks than the regular old-fashioned Basic method. The IE flavor is simply
-that libcurl will use a special "quirk" that IE is known to have used before
+that libcurl uses a special "quirk" that IE is known to have used before
version 7 and that some servers require the client to use.
.IP CURLAUTH_BEARER
HTTP Bearer token authentication, used primarily in OAuth 2.0 protocol.
binary application that is executed when needed. The name of the application
is specified at compile time but is typically \fB/usr/bin/ntlm_auth\fP.
-Note that libcurl will fork when necessary to run the winbind application and
-kill it when complete, calling \fBwaitpid()\fP to await its exit when done. On
-POSIX operating systems, killing the process will cause a SIGCHLD signal to be
+Note that libcurl forks when necessary to run the winbind application and kill
+it when complete, calling \fBwaitpid()\fP to await its exit when done. On
+POSIX operating systems, killing the process causes a SIGCHLD signal to be
raised (regardless of whether \fICURLOPT_NOSIGNAL(3)\fP is set), which must be
handled intelligently by the application. In particular, the application must
not unconditionally call wait() in its SIGCHLD signal handler to avoid being
versions of libcurl.
.IP CURLAUTH_ANY
This is a convenience macro that sets all bits and thus makes libcurl pick any
-it finds suitable. libcurl will automatically select the one it finds most
-secure.
+it finds suitable. libcurl automatically selects the one it finds most secure.
.IP CURLAUTH_ANYSAFE
This is a convenience macro that sets all bits except Basic and thus makes
-libcurl pick any it finds suitable. libcurl will automatically select the one
-it finds most secure.
+libcurl pick any it finds suitable. libcurl automatically selects the one it
+finds most secure.
.IP CURLAUTH_ONLY
This is a meta symbol. OR this value together with a single specific auth
value to force libcurl to probe for unrestricted auth and if not, only that
using GET. Usable if a POST, HEAD, PUT, etc has been used previously using the
same curl \fIhandle\fP.
-When setting \fICURLOPT_HTTPGET(3)\fP to 1, it will automatically set
+When setting \fICURLOPT_HTTPGET(3)\fP to 1, libcurl automatically sets
\fICURLOPT_NOBODY(3)\fP to 0 and \fICURLOPT_UPLOAD(3)\fP to 0.
Setting this option to zero has no effect. Applications need to explicitly
structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list
and \fIcurl_slist_free_all(3)\fP to clean up an entire list. If you add a
header that is otherwise generated and used by libcurl internally, your added
-one will be used instead. If you add a header with no content as in 'Accept:'
-(no data on the right side of the colon), the internally used header will get
-disabled. With this option you can add new headers, replace internal headers
-and remove internal headers. To add a header with no content (nothing to the
-right side of the colon), use the form 'name;' (note the ending semicolon).
+header is used instead. If you add a header with no content as in 'Accept:'
+(no data on the right side of the colon), the internally used header is
+disabled/removed. With this option you can add new headers, replace internal
+headers and remove internal headers. To add a header with no content (nothing
+to the right side of the colon), use the form 'name;' (note the ending
+semicolon).
The headers included in the linked list \fBmust not\fP be CRLF-terminated,
-because libcurl adds CRLF after each header item. Failure to comply with this
-will result in strange bugs because the server will most likely ignore part of
-the headers you specified.
+because libcurl adds CRLF after each header item itself. Failure to comply
+with this might result in strange behavior.
The first line in an HTTP request (containing the method, usually a GET or
POST) is not a header and cannot be replaced using this option. Only the lines
following the request-line are headers. Adding this method line in this list
-of headers will only cause your request to send an invalid header. Use
+of headers only causes your request to send an invalid header. Use
\fICURLOPT_CUSTOMREQUEST(3)\fP to change the method.
-When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl will not copy
+When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy
the entire list so you \fBmust\fP keep it around until you no longer use this
\fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on
the list.
\fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP and
\fICURLOPT_REFERER(3)\fP. We recommend using those.
-There's an alternative option that sets or replaces headers only for requests
+There is an alternative option that sets or replaces headers only for requests
that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER(3)\fP. Use
\fICURLOPT_HEADEROPT(3)\fP to control the behavior.
.SH SPECIFIC HTTP HEADERS
-Setting some specific headers will cause libcurl to act differently.
+Setting some specific headers causes libcurl to act differently.
.IP "Host:"
-The specified host name will be used for cookie matching if the cookie engine
-is also enabled for this transfer. If the request is done over HTTP/2 or
-HTTP/3, the custom host name will instead be used in the ":authority" header
-field and Host: will not be sent at all over the wire.
+The specified host name is used for cookie matching if the cookie engine is
+also enabled for this transfer. If the request is done over HTTP/2 or HTTP/3,
+the custom host name is instead used in the ":authority" header field and
+Host: is not sent at all over the wire.
.IP "Transfer-Encoding: chunked"
Tells libcurl the upload is to be done using this chunked encoding instead of
providing the Content-Length: field in the request.
Use \fICURLOPT_HEADEROPT(3)\fP to make the headers only get sent to where you
intend them to get sent.
-Custom headers are sent in all requests done by the easy handles, which
-implies that if you tell libcurl to follow redirects
-(\fICURLOPT_FOLLOWLOCATION(3)\fP), the same set of custom headers will be sent
-in the subsequent request. Redirects can of course go to other hosts and thus
-those servers will get all the contents of your custom headers too.
+Custom headers are sent in all requests done by the easy handle, which implies
+that if you tell libcurl to follow redirects
+(\fICURLOPT_FOLLOWLOCATION(3)\fP), the same set of custom headers is sent in
+the subsequent request. Redirects can of course go to other hosts and thus
+those servers get all the contents of your custom headers too.
-Starting in 7.58.0, libcurl will specifically prevent "Authorization:" headers
+Starting in 7.58.0, libcurl specifically prevents "Authorization:" headers
from being sent to other hosts than the first used one, unless specifically
permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option.
-Starting in 7.64.0, libcurl will specifically prevent "Cookie:" headers
-from being sent to other hosts than the first used one, unless specifically
-permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option.
+Starting in 7.64.0, libcurl specifically prevents "Cookie:" headers from being
+sent to other hosts than the first used one, unless specifically permitted
+with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option.
.SH DEFAULT
NULL
.SH PROTOCOLS
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP.
-When setting \fICURLOPT_HTTPPOST(3)\fP, it will automatically set
+When setting \fICURLOPT_HTTPPOST(3)\fP, libcurl automatically sets
\fICURLOPT_NOBODY(3)\fP to 0.
.SH DEFAULT
NULL
HTTP proxies can generally only speak HTTP (for obvious reasons), which makes
libcurl convert non-HTTP requests to HTTP when using an HTTP proxy without
this tunnel option set. For example, asking for an FTP URL and specifying an
-HTTP proxy will make libcurl send an FTP URL in an HTTP GET request to the
+HTTP proxy makes libcurl send an FTP URL in an HTTP GET request to the
proxy. By instead tunneling through the proxy, you avoid that conversion (that
rarely works through the proxy anyway).
.SH DEFAULT
long enabled);
.SH DESCRIPTION
Pass a long to tell libcurl how to act on content decoding. If set to zero,
-content decoding will be disabled. If set to 1 it is enabled. Libcurl has no
+content decoding is disabled. If set to 1 it is enabled. Libcurl has no
default content decoding but requires you to use
\fICURLOPT_ACCEPT_ENCODING(3)\fP for that.
.SH DEFAULT
long enabled);
.SH DESCRIPTION
Pass a long to tell libcurl how to act on transfer decoding. If set to zero,
-transfer decoding will be disabled, if set to 1 it is enabled
-(default). libcurl does chunked transfer decoding by default unless this
-option is set to zero.
+transfer decoding is disabled, if set to 1 it is enabled (default). libcurl
+does chunked transfer decoding by default unless this option is set to zero.
.SH DEFAULT
1
.SH PROTOCOLS
}
.fi
.SH AVAILABILITY
-Added in 7.16.2 Does not work with the hyper backend (it will always have
-transfer decoding enabled).
+Added in 7.16.2 Does not work with the hyper backend (it always has transfer
+decoding enabled).
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
Pass \fIversion\fP a long, set to one of the values described below. They ask
libcurl to use the specific HTTP versions.
-Note that the HTTP version is just a request. libcurl will still prioritize to
-re-use an existing connection so it might then re-use a connection using a
-HTTP version you have not asked for.
+Note that the HTTP version is just a request. libcurl still prioritizes to
+reuse existing connections so it might then reuse a connection using a HTTP
+version you have not asked for.
.IP CURL_HTTP_VERSION_NONE
-We do not care about what version the library uses. libcurl will use whatever
-it thinks fit.
+We do not care about what version the library uses. libcurl uses whatever it
+thinks fit.
.IP CURL_HTTP_VERSION_1_0
Enforce HTTP 1.0 requests.
.IP CURL_HTTP_VERSION_1_1
Enforce HTTP 1.1 requests.
.IP CURL_HTTP_VERSION_2_0
-Attempt HTTP 2 requests. libcurl will fall back to HTTP 1.1 if HTTP 2 cannot be
+Attempt HTTP 2 requests. libcurl falls back to HTTP 1.1 if HTTP 2 cannot be
negotiated with the server. (Added in 7.33.0)
When libcurl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or
The alias \fICURL_HTTP_VERSION_2\fP was added in 7.43.0 to better reflect the
actual protocol name.
.IP CURL_HTTP_VERSION_2TLS
-Attempt HTTP 2 over TLS (HTTPS) only. libcurl will fall back to HTTP 1.1 if
-HTTP 2 cannot be negotiated with the HTTPS server. For clear text HTTP servers,
-libcurl will use 1.1. (Added in 7.47.0)
+Attempt HTTP 2 over TLS (HTTPS) only. libcurl falls back to HTTP 1.1 if HTTP 2
+cannot be negotiated with the HTTPS server. For clear text HTTP servers,
+libcurl uses 1.1. (Added in 7.47.0)
.IP CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE
Issue non-TLS HTTP requests using HTTP/2 without HTTP/1.1 Upgrade. It requires
prior knowledge that the server supports HTTP/2 straight away. HTTPS requests
-will still do HTTP/2 the standard way with negotiated protocol version in the
-TLS handshake. (Added in 7.49.0)
+still do HTTP/2 the standard way with negotiated protocol version in the TLS
+handshake. (Added in 7.49.0)
.IP CURL_HTTP_VERSION_3
(Added in 7.66.0) This option makes libcurl attempt to use HTTP/3 to the host
given in the URL, with fallback to earlier HTTP versions if needed.
.IP CURL_HTTP_VERSION_3ONLY
-(Added in 7.88.0) Setting this value will make libcurl attempt to use HTTP/3
-directly to server given in the URL but will not downgrade to earlier HTTP
-version if the server does not support HTTP/3.
+(Added in 7.88.0) Setting this makes libcurl attempt to use HTTP/3 directly to
+server given in the URL and does not downgrade to earlier HTTP version if the
+server does not support HTTP/3.
.SH DEFAULT
Since curl 7.62.0: CURL_HTTP_VERSION_2TLS
If \fIignore\fP is set to 1L, ignore the Content-Length header in the HTTP
response and ignore asking for or relying on it for FTP transfers.
-This is useful for HTTP with Apache 1.x (and similar servers) which will
-report incorrect content length for files over 2 gigabytes. If this option is
-used, curl will not be able to accurately report progress, and will simply
-stop the download when the server ends the connection.
+This is useful for doing HTTP transfers with ancient web servers which report
+incorrect content length for files over 2 gigabytes. If this option is used,
+curl cannot accurately report progress, and it instead stops the download when
+the server ends the connection.
It is also useful with FTP when for example the file is growing while the
-transfer is in progress which otherwise will unconditionally cause libcurl to
+transfer is in progress which otherwise unconditionally causes libcurl to
report error.
Only use this option if strictly necessary.
When sending emails using SMTP, this command can be used to specify the
optional SIZE parameter for the MAIL FROM command.
-This option does not limit how much data libcurl will actually send, as that
-is controlled entirely by what the read callback returns, but telling one
-value and sending a different amount may lead to errors.
+This option does not limit how much data libcurl actually sends, as that is
+controlled entirely by what the read callback returns, but telling one value
+and sending a different amount may lead to errors.
.SH DEFAULT
Unset
.SH PROTOCOLS
When sending emails using SMTP, this command can be used to specify the
optional SIZE parameter for the MAIL FROM command.
-This option does not limit how much data libcurl will actually send, as that
-is controlled entirely by what the read callback returns, but telling one
-value and sending a different amount may lead to errors.
+This option does not limit how much data libcurl actually sends, as that is
+controlled entirely by what the read callback returns, but telling one value
+and sending a different amount may lead to errors.
.SH DEFAULT
Unset
.SH PROTOCOLS
outgoing network interface. The name can be an interface name, an IP address,
or a host name.
-If the parameter starts with "if!" then it is treated as only as interface
-name and no attempt will ever be named to do treat it as an IP address or to
-do name resolution on it. If the parameter starts with \&"host!" it is treated
-as either an IP address or a hostname.
+If the parameter starts with "if!" then it is treated only as an interface
+name. If the parameter starts with \&"host!" it is treated as either an IP
+address or a hostname.
If "if!" is specified but the parameter does not match an existing interface,
\fICURLE_INTERFACE_FAILED\fP is returned from the libcurl function used to
We strongly advise against specifying the interface with a hostname, as it
causes libcurl to do a blocking name resolve call to retrieve the IP
-address. That name resolve operation will \fBnot\fP use DNS-over-HTTPS even if
+address. That name resolve operation does \fBnot\fP use DNS-over-HTTPS even if
\fICURLOPT_DOH_URL(3)\fP is set.
The application does not have to keep the string around after setting this
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEDATA, void *pointer);
.fi
.SH DESCRIPTION
-This is the userdata \fIpointer\fP that will be passed to
+This is the userdata \fIpointer\fP that is passed to
\fICURLOPT_INTERLEAVEFUNCTION(3)\fP when interleaved RTP data is received. If
the interleave function callback is not set, this pointer is not used
anywhere.
first byte is always an ASCII dollar sign. The dollar sign is followed by a
one byte channel identifier and then a 2 byte integer length in network byte
order. See RFC 2326 Section 10.12 for more information on how RTP interleaving
-behaves. If unset or set to NULL, curl will use the default write function.
+behaves. If unset or set to NULL, curl uses the default write function.
Interleaved RTP poses some challenges for the client application. Since the
stream data is sharing the RTSP control connection, it is critical to service
subsequent response processing may become unreasonably delayed and the
connection may close. The application may use \fICURL_RTSPREQ_RECEIVE\fP to
service RTP data when no requests are desired. If the application makes a
-request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler will
-process any pending RTP data before marking the request as finished.
+request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler processes
+any pending RTP data before marking the request as finished.
The \fICURLOPT_INTERLEAVEDATA(3)\fP is passed in the \fIuserdata\fP argument in
the callback.
Your callback should return the number of bytes actually taken care of. If
-that amount differs from the amount passed to your callback function, it will
-signal an error condition to the library. This will cause the transfer to get
-aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
+that amount differs from the amount passed to your callback function, it
+signals an error condition to the library. This causes the transfer to abort
+and the libcurl function used returns \fICURLE_WRITE_ERROR\fP.
You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0)
.SH DEFAULT
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLDATA, void *pointer);
.fi
.SH DESCRIPTION
-Pass the \fIpointer\fP that will be untouched by libcurl and passed as the 3rd
+Pass the \fIpointer\fP that is untouched by libcurl and passed as the 3rd
argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION(3)\fP.
.SH DEFAULT
By default, the value of this parameter is NULL.
This option is deprecated! Do not use it. Use \fICURLOPT_SEEKFUNCTION(3)\fP
instead to provide seeking! If \fICURLOPT_SEEKFUNCTION(3)\fP is set, this
-parameter will be ignored when seeking.
+parameter is ignored when seeking.
.SH DEFAULT
By default, this parameter is set to NULL. Not used.
.SH PROTOCOLS
.SH DESCRIPTION
Allows an application to select what kind of IP addresses to use when
establishing a connection or choosing one from the connection pool. This is
-interesting when using host names that resolve to more than one version of IP.
+interesting when using host names that resolve to more than one IP family.
If the URL provided for a transfer contains a numerical IP version as a host
-name, this option will not override or prohibit libcurl from using that IP
+name, this option does not override or prohibit libcurl from using that IP
version.
Available values for this option are:
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEYPASSWD, char *pwd);
.fi
.SH DESCRIPTION
-Pass a pointer to a null-terminated string as parameter. It will be used as
-the password required to use the \fICURLOPT_SSLKEY(3)\fP or
+Pass a pointer to a null-terminated string as parameter. It is used as the
+password required to use the \fICURLOPT_SSLKEY(3)\fP or
\fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP private key. You never need a pass
phrase to load a certificate but you need one to load your private key.
.SH DESCRIPTION
Pass a char * as parameter. Set the kerberos security level for FTP; this also
enables kerberos awareness. This is a string that should match one of the
-following: \&'clear', \&'safe', \&'confidential' or \&'private'. If the
-string is set but does not match one of these, 'private' will be used. Set the
-string to NULL to disable kerberos support for FTP.
+following: \&'clear', \&'safe', \&'confidential' or \&'private'. If the string
+is set but does not match one of these, 'private' is used. Set the string to
+NULL to disable kerberos support for FTP.
The application does not have to keep the string around after setting this
option.
long range);
.fi
.SH DESCRIPTION
-Pass a long. The \fIrange\fP argument is the number of attempts libcurl will
-make to find a working local port number. It starts with the given
+Pass a long. The \fIrange\fP argument is the number of attempts libcurl makes
+to find a working local port number. It starts with the given
\fICURLOPT_LOCALPORT(3)\fP and adds one to the number for each retry. Setting
-this option to 1 or below will make libcurl do only one try for the exact port
-number. Port numbers by nature are scarce resources that will be busy at times
-so setting this value to something too low might cause unnecessary connection
+this option to 1 or below makes libcurl only do one try for the exact port
+number. Port numbers by nature are scarce resources that are busy at times so
+setting this value to something too low might cause unnecessary connection
setup failures.
.SH DEFAULT
1
option.
Since 8.2.0, IMAP supports the login option "AUTH=+LOGIN". With this option,
-curl uses the plain (not SASL) LOGIN IMAP command even if the server advertises
-SASL authentication. Care should be taken in using this option, as it will send
-out your password in plain text. This will not work if the IMAP server disables
-the plain LOGIN (e.g. to prevent password snooping).
+curl uses the plain (not SASL) LOGIN IMAP command even if the server
+advertises SASL authentication. Care should be taken in using this option, as
+it sends your password in plain text. This does not work if the IMAP server
+disables the plain LOGIN (e.g. to prevent password snooping).
The application does not have to keep the string around after setting this
option.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_AUTH, char *auth);
.fi
.SH DESCRIPTION
-Pass a pointer to a null-terminated string as parameter. This will be used to
+Pass a pointer to a null-terminated string as parameter. This is used to
specify the authentication address (identity) of a submitted message that is
being relayed to another server.
Unlike \fICURLOPT_MAIL_FROM(3)\fP and \fICURLOPT_MAIL_RCPT(3)\fP, the address
should not be specified within a pair of angled brackets (<>). However, if an
-empty string is used then a pair of brackets will be sent by libcurl as
-required by RFC 2554.
+empty string is used then a pair of brackets are sent by libcurl as required
+by RFC 2554.
The application does not have to keep the string around after setting this
option.
to specify the sender's email address when sending SMTP mail with libcurl.
An originator email address should be specified with angled brackets (<>)
-around it, which if not specified will be added automatically.
+around it, which if not specified are added automatically.
-If this parameter is not specified then an empty address will be sent to the
-mail server which may cause the email to be rejected.
+If this parameter is not specified then an empty address is sent to the SMTP
+server which might cause the email to be rejected.
The application does not have to keep the string around after setting this
option.
When performing a mail transfer, each recipient should be specified within a
pair of angled brackets (<>), however, should you not use an angled bracket as
-the first character libcurl will assume you provided a single email address
-and enclose that address within brackets for you.
+the first character libcurl assumes you provided a single email address and
+encloses that address within brackets for you.
When performing an address verification (\fBVRFY\fP command), each recipient
should be specified as the user name or user name and domain (as per Section
.SH DESCRIPTION
If \fIallow\fP is set to 1L, allow RCPT TO command to fail for some recipients.
-When sending data to multiple recipients, by default curl will abort SMTP
-conversation if at least one of the recipients causes RCPT TO command to
+When sending data to multiple recipients, by default curl aborts the SMTP
+conversation if either one of the recipients causes the RCPT TO command to
return an error.
-The default behavior can be changed by setting \fIignore\fP to 1L which will
-make curl ignore errors and proceed with the remaining valid recipients.
+The default behavior can be changed by setting \fIallow\fP to 1L which makes
+libcurl ignore errors for individual recipients and proceed with the remaining
+accepted recipients.
If all recipients trigger RCPT TO failures and this flag is specified, curl
-will still abort the SMTP conversation and return the error received from to
-the last RCPT TO command.
+aborts the SMTP conversation and returns the error received from to the last
+RCPT TO command.
.SH DEFAULT
0
.SH PROTOCOLS
.fi
.SH DESCRIPTION
Pass a long as parameter containing \fIage\fP - the maximum time in seconds
-that you allow an existing connection to have been idle to be considered for
+allowed for an existing connection to have been idle to be considered for
reuse for this request.
-The "connection cache" that holds previously used connections. When a new
-request is to be done, it will consider any connection that matches for
-reuse. The \fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too
-old connections for reuse, since old connections have a high risk of not
-working and thus trying them is a performance loss and sometimes service loss
-due to the difficulties to figure out the situation. If a connection is found
-in the cache that is older than this set \fIage\fP, it will instead be closed.
+The "connection cache" holds previously used connections. When a new request
+is to be done, libcurl considers any connection that matches for reuse. The
+\fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too old
+connections for reuse, since old connections have a higher risk of not working
+and thus trying them is a performance loss and sometimes service loss due to
+the difficulties to figure out the situation. If a connection is found in the
+cache that is older than this set \fIage\fP, it is closed instead.
.SH DEFAULT
Default maximum age is set to 118 seconds.
.SH PROTOCOLS
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXCONNECTS, long amount);
.fi
.SH DESCRIPTION
-Pass a long. The set \fIamount\fP will be the maximum number of simultaneously
-open persistent connections that libcurl may cache in the pool associated with
-this handle. The default is 5, and there is not much point in changing this
-value unless you are perfectly aware of how this works and changes libcurl's
-behavior. This concerns connections using any of the protocols that support
-persistent connections.
+Pass a long. The set \fIamount\fP is the maximum number of simultaneously open
+persistent connections that libcurl may cache in the pool associated with this
+handle. The default is 5, and there is not much point in changing this value
+unless you are perfectly aware of how this works. This concerns connections
+using any of the protocols that support persistent connections.
When reaching the maximum limit, curl closes the oldest one in the cache to
prevent increasing the number of open connections.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE, long size);
.fi
.SH DESCRIPTION
-Pass a long as parameter. This allows you to specify the maximum \fIsize\fP
-(in bytes) of a file to download. If the file requested is found larger than
-this value, the transfer will not start and \fICURLE_FILESIZE_EXCEEDED\fP will
-be returned.
+Pass a long as parameter. This specifies the maximum accepted \fIsize\fP (in
+bytes) of a file to download. If the file requested is found larger than this
+value, the transfer is aborted and \fICURLE_FILESIZE_EXCEEDED\fP is returned.
-The file size is not always known prior to download, and for such files this
-option has no effect even if the file transfer ends up being larger than this
-given limit.
+The file size is not always known prior to the download start, and for such
+transfers this option has no effect - even if the file transfer eventually
+ends up being larger than this given limit.
If you want a limit above 2GB, use \fICURLOPT_MAXFILESIZE_LARGE(3)\fP.
.SH DEFAULT
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE_LARGE,
curl_off_t size);
.SH DESCRIPTION
-Pass a curl_off_t as parameter. This allows you to specify the maximum
-\fIsize\fP (in bytes) of a file to download. If the file requested is found
-larger than this value, the transfer will not start and
-\fICURLE_FILESIZE_EXCEEDED\fP will be returned.
+Pass a curl_off_t as parameter. This specifies the maximum accepted \fIsize\fP
+(in bytes) of a file to download. If the file requested is found larger than
+this value, the transfer is aborted and \fICURLE_FILESIZE_EXCEEDED\fP is
+returned.
-The file size is not always known prior to download, and for such files this
-option has no effect even if the file transfer ends up being larger than this
-given limit.
+The file size is not always known prior to the download start, and for such
+transfers this option has no effect - even if the file transfer eventually
+ends up being larger than this given limit.
.SH DEFAULT
None
.SH PROTOCOLS
connection to have to be considered for reuse for this request.
libcurl features a connection cache that holds previously used connections.
-When a new request is to be done, it will consider any connection that matches
-for reuse. The \fICURLOPT_MAXLIFETIME_CONN(3)\fP limit prevents libcurl from
-trying too old connections for reuse. This can be used for client-side load
-balancing. If a connection is found in the cache that is older than this set
-\fImaxlifetime\fP, it will instead be closed once any in-progress transfers
-complete.
+When a new request is to be done, libcurl considers any connection that
+matches for reuse. The \fICURLOPT_MAXLIFETIME_CONN(3)\fP limit prevents
+libcurl from trying too old connections for reuse. This can be used for
+client-side load balancing. If a connection is found in the cache that is
+older than this set \fImaxlifetime\fP, it is instead marked for closure.
If set to 0, this behavior is disabled: all connections are eligible for reuse.
.SH DEFAULT
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXREDIRS, long amount);
.fi
.SH DESCRIPTION
-Pass a long. The set number will be the redirection limit \fIamount\fP. If
-that many redirections have been followed, the next redirect will cause an
-error (\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the
+Pass a long. The set number is the redirection limit \fIamount\fP. If that
+many redirections have been followed, the next redirect triggers the error
+(\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the
\fICURLOPT_FOLLOWLOCATION(3)\fP is used at the same time.
-Setting the limit to 0 will make libcurl refuse any redirect.
+Setting the limit to 0 makes libcurl refuse any redirect.
-Set it to -1 for an infinite number of redirects.
+Set it to -1 for an infinite number of redirects. This allows your application
+to get stuck in never-ending redirect loops.
.SH DEFAULT
30 (since 8.3.0), it was previously unlimited.
.SH PROTOCOLS
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_RECV_SPEED_LARGE,
curl_off_t maxspeed);
.SH DESCRIPTION
-Pass a curl_off_t as parameter. If a download exceeds this \fImaxspeed\fP
-(counted in bytes per second) the transfer will pause to keep the speed less
-than or equal to the parameter value. Defaults to unlimited speed.
+Pass a curl_off_t as parameter. If a download exceeds this \fImaxspeed\fP
+(counted in bytes per second) the transfer pauses to keep the average speed
+less than or equal to the parameter value. Defaults to unlimited speed.
This is not an exact science. libcurl attempts to keep the average speed below
the given threshold over a period time.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_SEND_SPEED_LARGE,
curl_off_t maxspeed);
.SH DESCRIPTION
-Pass a curl_off_t as parameter with the \fImaxspeed\fP. If an upload exceeds
-this speed (counted in bytes per second) the transfer will pause to keep the
-speed less than or equal to the parameter value. Defaults to unlimited
+Pass a curl_off_t as parameter with the \fImaxspeed\fP. If an upload exceeds
+this speed (counted in bytes per second) the transfer pauses to keep the
+average speed less than or equal to the parameter value. Defaults to unlimited
speed.
This is not an exact science. libcurl attempts to keep the average speed below
.SH AVAILABILITY
Added in 7.56.0
.SH RETURN VALUE
-This will return CURLE_OK.
+This returns CURLE_OK.
.SH "SEE ALSO"
.BR curl_mime_init "(3)"
user names and passwords from your \fI~/.netrc\fP file, relative to user names
and passwords in the URL supplied with \fICURLOPT_URL(3)\fP.
-On Windows, libcurl will use the file as \fI%HOME%/_netrc\fP. If \fI%HOME%\fP
-is not set on Windows, libcurl falls back to \fI%USERPROFILE%\fP.
+On Windows, libcurl uses the file as \fI%HOME%/_netrc\fP. If \fI%HOME%\fP is
+not set on Windows, libcurl falls back to \fI%USERPROFILE%\fP.
You can also tell libcurl a different file name to use with
\fICURLOPT_NETRC_FILE(3)\fP.
\fIlevel\fP is a long that should be set to one of the values described below.
.IP "CURL_NETRC_IGNORED (0)"
-The library will ignore the \fI.netrc\fP file. This is the default.
+libcurl ignores the \fI.netrc\fP file. This is the default.
.IP "CURL_NETRC_OPTIONAL (1)"
The use of the \fI.netrc\fP file is optional, and information in the URL is to
-be preferred. The file will be scanned for the host and user name (to find
-the password only) or for the host only, to find the first user name and
-password after that \fImachine\fP, which ever information is not specified.
+be preferred. The file is scanned for the host and user name (to find the
+password only) or for the host only, to find the first user name and password
+after that \fImachine\fP, which ever information is not specified.
.IP "CURL_NETRC_REQUIRED (2)"
The use of the \fI.netrc\fP file is required, and any credential information
-present in the URL is ignored. The file will be scanned for the host and user
-name (to find the password only) or for the host only, to find the first user
-name and password after that \fImachine\fP, which ever information is not
+present in the URL is ignored. The file is scanned for the host and user name
+(to find the password only) or for the host only, to find the first user name
+and password after that \fImachine\fP, which ever information is not
specified.
.SH FILE FORMAT
The \fB.netrc\fP file format is simple: you specify lines with a machine name
.IP "login <name>"
The user name string for the remote machine.
.IP "password <secret>"
-Supply a password. If this token is present, curl will supply the specified
+Supply a password. If this token is present, curl supplies the specified
string if the remote server requires a password as part of the login process.
Note that if this token is present in the .netrc file you really should make
sure the file is not readable by anyone besides the user.
.IP "macdef <name>"
Define a macro. This feature is not supported by libcurl. In order for the
-rest of the .netrc to still work fine, libcurl will properly skip every
-definition done with "macdef" that it finds.
+rest of the .netrc to still work fine, libcurl properly skips every definition
+done with "macdef" that it finds.
.SH DEFAULT
CURL_NETRC_IGNORED
.SH PROTOCOLS
Pass a char * as parameter, pointing to a null-terminated string containing
the full path name to the \fIfile\fP you want libcurl to use as .netrc
file. If this option is omitted, and \fICURLOPT_NETRC(3)\fP is set, libcurl
-will attempt to find a .netrc file in the current user's home
-directory.
+checks for a .netrc file in the current user's home directory.
The application does not have to keep the string around after setting this
option.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_DIRECTORY_PERMS,
long mode);
.SH DESCRIPTION
-Pass a long as a parameter, containing the value of the permissions that will
-be assigned to newly created directories on the remote server. The default value is
+Pass a long as a parameter, containing the value of the permissions that is
+set on newly created directories on the remote server. The default value is
\fI0755\fP, but any valid value can be used. The only protocols that can use
this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP.
.SH DEFAULT
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_FILE_PERMS,
long mode);
.SH DESCRIPTION
-Pass a long as a parameter, containing the value of the permissions that will
-be assigned to newly created files on the remote server. The default value is
+Pass a long as a parameter, containing the value of the permissions that are
+set on newly created files on the remote server. The default value is
\fI0644\fP, but any valid value can be used. The only protocols that can use
this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP.
.SH DEFAULT
to transfer the body data.
For HTTP operations when \fICURLOPT_NOBODY(3)\fP has been set, disabling this
-option (with 0) will make it a GET again - only if the method is still set to
-be HEAD. The proper way to get back to a GET request is to set
+option (with 0) makes it a GET again - only if the method is still set to be
+HEAD. The proper way to get back to a GET request is to set
\fICURLOPT_HTTPGET(3)\fP and for other methods, use the POST or UPLOAD
options.
Enabling \fICURLOPT_NOBODY(3)\fP means asking for a download without a body.
-If you do a transfer with HTTP that involves a method other than HEAD, you
-will get a body (unless the resource and server sends a zero byte body for the
-specific URL you request).
+If you do a transfer with HTTP that involves a method other than HEAD, you get
+a body (unless the resource and server sends a zero byte body for the specific
+URL you request).
.SH DEFAULT
0, the body is transferred
.SH PROTOCOLS
.fi
.SH DESCRIPTION
If \fIonoff\fP is to 1, it tells the library to shut off the progress meter
-completely for requests done with this \fIhandle\fP. It will also prevent the
+completely for requests done with this \fIhandle\fP. It also prevents the
\fICURLOPT_XFERINFOFUNCTION(3)\fP or \fICURLOPT_PROGRESSFUNCTION(3)\fP from
getting called.
.SH DEFAULT
hostname itself. For example, "ample.com" would match ample.com, ample.com:80,
and www.ample.com, but not www.example.com or ample.com.org.
-Setting the \fInoproxy\fP string to "" (an empty string) will explicitly
-enable the proxy for all host names, even if there is an environment variable
-set for it.
+Setting the \fInoproxy\fP string to "" (an empty string) explicitly enables
+the proxy for all host names, even if there is an environment variable set for
+it.
Enter IPv6 numerical addresses in the list of host names without enclosing
brackets:
The application does not have to keep the string around after setting this
option.
.SH "Environment variables"
-If there's an environment variable called \fBno_proxy\fP (or \fBNO_PROXY\fP),
-it will be used if the \fICURLOPT_NOPROXY(3)\fP option is not set. It works
-exactly the same way.
+If there is an environment variable called \fBno_proxy\fP (or \fBNO_PROXY\fP),
+it is used if the \fICURLOPT_NOPROXY(3)\fP option is not set. It works exactly
+the same way.
.SH DEFAULT
NULL
.SH PROTOCOLS
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOSIGNAL, long onoff);
.fi
.SH DESCRIPTION
-If \fIonoff\fP is 1, libcurl will not use any functions that install signal
-handlers or any functions that cause signals to be sent to the process. This
-option is here to allow multi-threaded unix applications to still set/use all
-timeout options etc, without risking getting signals.
+If \fIonoff\fP is 1, libcurl uses no functions that install signal handlers or
+any functions that cause signals to be sent to the process. This option is
+here to allow multi-threaded unix applications to still set/use all timeout
+options etc, without risking getting signals.
If this option is set and libcurl has been built with the standard name
-resolver, timeouts will not occur while the name resolve takes place.
-Consider building libcurl with the c-ares or threaded resolver backends to
-enable asynchronous DNS lookups, to enable timeouts for name resolves without
-the use of signals.
+resolver, timeouts cannot occur while the name resolve takes place. Consider
+building libcurl with the c-ares or threaded resolver backends to enable
+asynchronous DNS lookups, to enable timeouts for name resolves without the use
+of signals.
Setting \fICURLOPT_NOSIGNAL(3)\fP to 1 makes libcurl NOT ask the system to
ignore SIGPIPE signals, which otherwise are sent by the system when trying to
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETDATA, void *pointer);
.fi
.SH DESCRIPTION
-Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
+Pass a \fIpointer\fP that is untouched by libcurl and passed as the first
argument in the open socket callback set with
\fICURLOPT_OPENSOCKETFUNCTION(3)\fP.
.SH DEFAULT
curl = curl_easy_init();
if(curl) {
- /* libcurl will internally think that you connect to the host
+ /* libcurl thinks that you connect to the host
* and port that you specify in the URL option. */
curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
/* call this function to get a socket */
function should return the newly created socket or \fICURL_SOCKET_BAD\fP in
case no connection could be established or another error was detected. Any
additional \fIsetsockopt(2)\fP calls can of course be done on the socket at
-the user's discretion. A \fICURL_SOCKET_BAD\fP return value from the callback
-function will signal an unrecoverable error to libcurl and it will return
+the user's discretion. A \fICURL_SOCKET_BAD\fP return value from the callback
+function signals an unrecoverable error to libcurl and it returns
\fICURLE_COULDNT_CONNECT\fP from the function that triggered this callback.
This return code can be used for IP address block listing.
curl = curl_easy_init();
if(curl) {
- /* libcurl will internally think that you connect to the host
+ /* libcurl thinks that you connect to the host
* and port that you specify in the URL option. */
curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
/* call this function to get a socket */
sequences to remain in the path and some clients want to pass these on in
order to try out server implementations.
-By default libcurl will merge such sequences before using the path.
+By default libcurl normalizes such sequences before using the path.
+
+The corresponding flag for the \fIcurl_url_set(3)\fP function is called
+\fBCURLU_PATH_AS_IS\fP.
.SH DEFAULT
0
.SH PROTOCOLS
When negotiating a TLS or SSL connection, the server sends a certificate
indicating its identity. A public key is extracted from this certificate and
-if it does not exactly match the public key provided to this option, curl will
-abort the connection before sending or receiving any data.
+if it does not exactly match the public key provided to this option, curl
+aborts the connection before sending or receiving any data.
On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned.
.\"
.TH CURLOPT_PIPEWAIT 3 "12 May 2015" libcurl libcurl
.SH NAME
-CURLOPT_PIPEWAIT \- wait for pipelining/multiplexing
+CURLOPT_PIPEWAIT \- wait for multiplexing
.SH SYNOPSIS
.nf
#include <curl/curl.h>
.fi
.SH DESCRIPTION
Set \fIwait\fP to 1L to tell libcurl to prefer to wait for a connection to
-confirm or deny that it can do pipelining or multiplexing before continuing.
+confirm or deny that it can do multiplexing before continuing.
-When about to perform a new transfer that allows pipelining or multiplexing,
-libcurl will check for existing connections to re-use and pipeline on. If no
-such connection exists it will immediately continue and create a fresh new
-connection to use.
+When about to perform a new transfer that allows multiplexing, libcurl checks
+for existing connections to use. If no such connection exists it immediately
+continues and creates a fresh new connection to use.
By setting this option to 1 - and having \fICURLMOPT_PIPELINING(3)\fP enabled
-for the multi handle this transfer is associated with - libcurl will instead
-wait for the connection to reveal if it is possible to pipeline/multiplex on
-before it continues. This enables libcurl to much better keep the number of
-connections to a minimum when using pipelining or multiplexing protocols.
+for the multi handle this transfer is associated with - libcurl instead waits
+for the connection to reveal if it is possible to multiplex on before it
+continues. This enables libcurl to much better keep the number of connections
+to a minimum when using multiplexing protocols.
-The effect thus becomes that with this option set, libcurl prefers to wait and
-re-use an existing connection for pipelining rather than the opposite: prefer
-to open a new connection rather than waiting.
+With this option set, libcurl prefers to wait and reuse an existing connection
+for multiplexing rather than the opposite: prefer to open a new connection
+rather than waiting.
The waiting time is as long as it takes for the connection to get up and for
libcurl to get the necessary response back that informs it about its protocol
application to override that.
While this option accepts a 'long', a port number is an unsigned 16 bit number
-and therefore using a port number lower than zero or over 65535 will cause a
+and therefore using a port number lower than zero or over 65535 causes a
\fBCURLE_BAD_FUNCTION_ARGUMENT\fP error.
.SH DEFAULT
By default this is 0 which makes it not used. This also makes port number zero
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POST, long post);
.fi
.SH DESCRIPTION
-A parameter set to 1 tells libcurl to do a regular HTTP post. This will also
-make the library use a "Content-Type: application/x-www-form-urlencoded"
-header. (This is by far the most commonly used POST method).
+A parameter set to 1 tells libcurl to do a regular HTTP post. This also makes
+libcurl use a "Content-Type: application/x-www-form-urlencoded" header. This
+is the most commonly used POST method.
Use one of \fICURLOPT_POSTFIELDS(3)\fP or \fICURLOPT_COPYPOSTFIELDS(3)\fP
options to specify what data to post and \fICURLOPT_POSTFIELDSIZE(3)\fP or
size before starting the POST if you use chunked encoding. You enable this by
adding a header like "Transfer-Encoding: chunked" with
\fICURLOPT_HTTPHEADER(3)\fP. With HTTP 1.0 or without chunked transfer, you
-must specify the size in the request. (Since 7.66.0, libcurl will
-automatically use chunked encoding for POSTs if the size is unknown.)
+must specify the size in the request. (Since 7.66.0, libcurl automatically
+uses chunked encoding for POSTs if the size is unknown.)
-When setting \fICURLOPT_POST(3)\fP to 1, libcurl will automatically set
+When setting \fICURLOPT_POST(3)\fP to 1, libcurl automatically sets
\fICURLOPT_NOBODY(3)\fP and \fICURLOPT_HTTPGET(3)\fP to 0.
If you issue a POST request and then want to make a HEAD or GET using the same
-re-used handle, you must explicitly set the new request type using
+reused handle, you must explicitly set the new request type using
\fICURLOPT_NOBODY(3)\fP or \fICURLOPT_HTTPGET(3)\fP or similar.
When setting \fICURLOPT_POST(3)\fP to 0, libcurl resets the request type to
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata);
.fi
.SH DESCRIPTION
-Pass a char * as parameter, pointing to the full data to send in an HTTP POST
-operation. You must make sure that the data is formatted the way you want the
-server to receive it. libcurl will not convert or encode it for you in any
-way. For example, the web server may assume that this data is URL encoded.
+Pass a char * as parameter, pointing to the data buffer to use in an HTTP POST
+operation. The data must be formatted and encoded the way you want the server
+to receive it. libcurl does not convert or encode it in any way. For example,
+the web server may assume that this data is URL encoded.
The data pointed to is NOT copied by the library: as a consequence, it must be
preserved by the calling application until the associated transfer finishes.
-This behavior can be changed (so libcurl does copy the data) by setting the
-\fICURLOPT_COPYPOSTFIELDS(3)\fP option.
+This behavior can be changed (so libcurl does copy the data) by instead using
+the \fICURLOPT_COPYPOSTFIELDS(3)\fP option.
This POST is a normal \fBapplication/x-www-form-urlencoded\fP kind (and
-libcurl will set that Content-Type by default when this option is used), which
-is commonly used by HTML forms. Change Content-Type with
+libcurl sets that Content-Type by default when this option is used), which is
+commonly used by HTML forms. Change Content-Type with
\fICURLOPT_HTTPHEADER(3)\fP.
You can use \fIcurl_easy_escape(3)\fP to URL encode your data, if
Using \fICURLOPT_POSTFIELDS(3)\fP implies setting \fICURLOPT_POST(3)\fP to 1.
-If \fICURLOPT_POSTFIELDS(3)\fP is explicitly set to NULL then libcurl will get
-the POST data from the read callback. If you want to send a zero-byte POST set
-\fICURLOPT_POSTFIELDS(3)\fP to an empty string, or set \fICURLOPT_POST(3)\fP to
-1 and \fICURLOPT_POSTFIELDSIZE(3)\fP to 0.
+If \fICURLOPT_POSTFIELDS(3)\fP is explicitly set to NULL then libcurl gets the
+POST data from the read callback. If you want to send a zero-byte POST set
+\fICURLOPT_POSTFIELDS(3)\fP to an empty string, or set \fICURLOPT_POST(3)\fP
+to 1 and \fICURLOPT_POSTFIELDSIZE(3)\fP to 0.
-libcurl will use assume this option points to a null-terminated string unless
-you also set \fICURLOPT_POSTFIELDSIZE(3)\fP to specify the length of the
-provided data, which then is strictly required if you want to send off null
-bytes included in the data.
+libcurl assumes this option points to a null-terminated string unless you also
+set \fICURLOPT_POSTFIELDSIZE(3)\fP to specify the length of the provided data,
+which then is strictly required if you want to send off null bytes included in
+the data.
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header,
-and libcurl will add that header automatically if the POST is either known to
-be larger than 1MB or if the expected size is unknown. You can disable this
+and libcurl adds that header automatically if the POST is either known to be
+larger than 1MB or if the expected size is unknown. You can disable this
header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
To make \fBmultipart/formdata\fP posts, check out the
HTTP
.SH EXAMPLE
.nf
+/* send an application/x-www-form-urlencoded POST */
CURL *curl = curl_easy_init();
if(curl) {
const char *data = "data to send";
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
- /* size of the POST data */
+ /* size of the POST data if strlen() is not good enough */
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L);
- /* pass in a pointer to the data - libcurl will not copy */
+ /* pass in a pointer to the data - libcurl does not copy */
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
curl_easy_perform(curl);
}
+
+/* send an application/json POST */
+CURL *curl = curl_easy_init();
+if(curl) {
+ const char *json = "{\"name\": \"daniel\"}";
+ struct curl_slist *slist1 = NULL;
+ slist1 = curl_slist_append(slist1, "Content-Type: application/json");
+ slist1 = curl_slist_append(slist1, "Accept: application/json");
+
+ /* set custom headers */
+ curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, slist1);
+
+ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+ /* pass in a pointer to the data - libcurl does not copy */
+ curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json);
+
+ curl_easy_perform(curl);
+}
+
.fi
.SH AVAILABILITY
Always
If you want to post static data to the server without having libcurl do a
strlen() to measure the data size, this option must be used. When this option
is used you can post fully binary data, which otherwise is likely to fail. If
-this size is set to -1, the library will use strlen() to get the size or rely
-on the \fICURLOPT_READFUNCTION\fP (if used) to signal the end of data.
+this size is set to -1, libcurl uses strlen() to get the size or relies on the
+\fICURLOPT_READFUNCTION\fP (if used) to signal the end of data.
If you post more than 2GB, use \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP.
.SH DEFAULT
If you want to post static data to the server without having libcurl do a
strlen() to measure the data size, this option must be used. When this option
is used you can post fully binary data, which otherwise is likely to fail. If
-this size is set to -1, the library will use strlen() to get the size or rely
-on the \fICURLOPT_READFUNCTION\fP (if used) to signal the end of data.
+this size is set to -1, libcurl uses strlen() to get the size or relies on the
+\fICURLOPT_READFUNCTION\fP (if used) to signal the end of data.
.SH DEFAULT
-1
.SH PROTOCOLS
.fi
.SH DESCRIPTION
Pass a pointer to a linked list of FTP or SFTP commands to pass to the server
-after your FTP transfer request. The commands will only be run if no error
-occurred. The linked list should be a fully valid list of struct curl_slist
+after your FTP transfer request. The commands are only issues if no error
+occur. The linked list should be a fully valid list of struct curl_slist
structs properly filled in as described for \fICURLOPT_QUOTE(3)\fP.
Disable this operation again by setting a NULL to this option.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, void *pointer);
.fi
.SH DESCRIPTION
-Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
-argument in the pre-request callback set with
-\fICURLOPT_PREREQFUNCTION(3)\fP.
+Pass a \fIpointer\fP that is untouched by libcurl and passed as the first
+argument in the pre-request callback set with \fICURLOPT_PREREQFUNCTION(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
To specify port number in this string, append :[port] to the end of the host
name. The proxy's port number may optionally be specified with the separate
-option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl will default to
-using port 1080 for proxies.
+option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl defaults to using
+port 1080 for proxies.
A pre proxy is a SOCKS proxy that curl connects to before it connects to the
HTTP(S) proxy specified in the \fICURLOPT_PROXY\fP option. The pre proxy can
\fICURLPROXY_SOCKS5_HOSTNAME\fP type) to request the specific SOCKS version to
be used. Otherwise SOCKS4 is used as default.
-Setting the pre proxy string to "" (an empty string) will explicitly disable
-the use of a pre proxy.
+Setting the pre proxy string to "" (an empty string) explicitly disables the
+use of a pre proxy.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
Default is NULL, meaning no pre proxy is used.
-When you set a host name to use, do not assume that there's any particular
+When you set a host name to use, do not assume that there is any particular
single port number used widely for proxies. Specify it!
.SH PROTOCOLS
All except file://. Note that some protocols do not work well over proxy.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSDATA, void *pointer);
.fi
.SH DESCRIPTION
-Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
+Pass a \fIpointer\fP that is untouched by libcurl and passed as the first
argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
newer \fICURLOPT_XFERINFOFUNCTION(3)\fP instead, if you can.
This function gets called by libcurl instead of its internal equivalent with a
-frequent interval. While data is being transferred it will be called
-frequently, and during slow periods like when nothing is being transferred it
-can slow down to about one call per second.
+frequent interval. While data is being transferred it is invoked frequently,
+and during slow periods like when nothing is being transferred it can slow
+down to about one call per second.
\fIclientp\fP is the pointer set with \fICURLOPT_PROGRESSDATA(3)\fP, it is not
used by libcurl but is only passed along from the application to the callback.
-The callback gets told how much data libcurl will transfer and has
+The callback gets told how much data libcurl is about to transfer and has
transferred, in number of bytes. \fIdltotal\fP is the total number of bytes
libcurl expects to download in this transfer. \fIdlnow\fP is the number of
bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl
expects to upload in this transfer. \fIulnow\fP is the number of bytes
uploaded so far.
-Unknown/unused argument values passed to the callback will be set to zero
-(like if you only download data, the upload size will remain 0). Many times
-the callback will be called one or more times first, before it knows the data
-sizes so a program must be made to handle that.
+Unknown/unused argument values passed to the callback are be set to zero (like
+if you only download data, the upload size remains 0). Many times the callback
+is called one or more times first, before it knows the data sizes so a program
+must be made to handle that.
-If your callback function returns CURL_PROGRESSFUNC_CONTINUE it will cause
-libcurl to continue executing the default progress function.
+If your callback function returns CURL_PROGRESSFUNC_CONTINUE it causes libcurl
+to continue executing the default progress function.
-Returning any other non-zero value from this callback will cause libcurl to
-abort the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
+Returning any other non-zero value from this callback makes libcurl abort the
+transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
-If you transfer data with the multi interface, this function will not be
-called during periods of idleness unless you call the appropriate libcurl
-function that performs transfers.
+If you transfer data with the multi interface, this function is not called
+during periods of idleness unless you call the appropriate libcurl function
+that performs transfers.
\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually
get called.
Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask
limits what protocols libcurl may use in the transfer. This allows you to have
a libcurl built to support a wide range of protocols but still limit specific
-transfers to only be allowed to use a subset of them. By default libcurl will
-accept all protocols it supports (\fICURLPROTO_ALL\fP). See also
+transfers to only be allowed to use a subset of them. By default libcurl
+accepts all protocols it supports (\fICURLPROTO_ALL\fP). See also
\fICURLOPT_REDIR_PROTOCOLS(3)\fP.
These are the available protocol defines:
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy);
.fi
.SH DESCRIPTION
-Set the \fIproxy\fP to use for the upcoming request. The parameter should be a
-char * to a null-terminated string holding the host name or dotted numerical
-IP address. A numerical IPv6 address must be written within [brackets].
+Set the \fIproxy\fP to use for transfers with this easy handle. The parameter
+should be a char * to a null-terminated string holding the host name or dotted
+numerical IP address. A numerical IPv6 address must be written within
+[brackets].
To specify port number in this string, append :[port] to the end of the host
-name. The proxy's port number may optionally be specified with the separate
-option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl will default to
-using port 1080 for proxies.
+name. The proxy's port number may optionally (but discouraged) be specified
+with the separate option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl
+defaults to using port 1080 for proxies.
The proxy string may be prefixed with [scheme]:// to specify which kind of
proxy is used.
also works for BearSSL, mbedTLS, rustls, Schannel, Secure Transport and
wolfSSL.)
-This will use HTTP/1 by default. Setting \fICURLOPT_PROXYTYPE(3)\fP to
+This uses HTTP/1 by default. Setting \fICURLOPT_PROXYTYPE(3)\fP to
\fBCURLPROXY_HTTPS2\fP allows libcurl to negotiate using HTTP/2 with proxy.
.IP socks4://
SOCKS4 Proxy.
Without a scheme prefix, \fICURLOPT_PROXYTYPE(3)\fP can be used to specify
which kind of proxy the string identifies.
-When you tell the library to use an HTTP proxy, libcurl will transparently
-convert operations to HTTP even if you specify an FTP URL etc. This may have
-an impact on what other features of the library you can use, such as
+When you tell the library to use an HTTP proxy, libcurl transparently converts
+operations to HTTP even if you specify an FTP URL etc. This may have an impact
+on what other features of the library you can use, such as
\fICURLOPT_QUOTE(3)\fP and similar FTP specifics that do not work unless you
tunnel through the HTTP proxy. Such tunneling is activated with
\fICURLOPT_HTTPPROXYTUNNEL(3)\fP.
-Setting the proxy string to "" (an empty string) will explicitly disable the
-use of a proxy, even if there is an environment variable set for it.
+Setting the proxy string to "" (an empty string) explicitly disables the use
+of a proxy, even if there is an environment variable set for it.
A proxy host string can also include protocol scheme (http://) and embedded
user + password.
cannot be used.
.SH "Environment variables"
libcurl respects the proxy environment variables named \fBhttp_proxy\fP,
-\fBftp_proxy\fP, \fBsftp_proxy\fP etc. If set, libcurl will use the specified
+\fBftp_proxy\fP, \fBsftp_proxy\fP etc. If set, libcurl uses the specified
proxy for that URL scheme. So for a "FTP://" URL, the \fBftp_proxy\fP is
considered. \fBall_proxy\fP is used if no protocol specific proxy was set.
.SH DEFAULT
Default is NULL, meaning no proxy is used.
-When you set a host name to use, do not assume that there's any particular
+When you set a host name to use, do not assume that there is any particular
single port number used widely for proxies. Specify it!
.SH PROTOCOLS
All except file://. Note that some protocols do not work well over proxy.
.SH DESCRIPTION
Pass a long as parameter, which is set to a bitmask, to tell libcurl which
HTTP authentication method(s) you want it to use for your proxy
-authentication. If more than one bit is set, libcurl will first query the
-site to see what authentication methods it supports and then pick the best one
-you allow it to use. For some methods, this will induce an extra network
-round-trip. Set the actual name and password with the
-\fICURLOPT_PROXYUSERPWD(3)\fP option.
+authentication. If more than one bit is set, libcurl first queries the site to
+see what authentication methods it supports and then it picks the best one you
+allow it to use. For some methods, this induces an extra network round-trip.
+Set the actual name and password with the \fICURLOPT_PROXYUSERPWD(3)\fP
+option.
The bitmask can be constructed by the bits listed and described in the
\fICURLOPT_HTTPAUTH(3)\fP man page.
\fICURLOPT_HTTPHEADER(3)\fP option's.
The headers set with this option is only ever used in requests sent to a proxy
-- when there's also a request sent to a host.
+- when there is also a request sent to a host.
The first line in a request (containing the method, usually a GET or POST) is
NOT a header and cannot be replaced using this option. Only the lines
following the request-line are headers. Adding this method line in this list
-of headers will only cause your request to send an invalid header.
+of headers causes your request to send an invalid header.
Pass a NULL to this to reset back to no custom headers.
.SH DEFAULT
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should be [user name]:[password] to use for
-the connection to the HTTP proxy. Both the name and the password will be URL
-decoded before use, so to include for example a colon in the user name you
+the connection to the HTTP proxy. Both the name and the password are URL
+decoded before used, so to include for example a colon in the user name you
should encode it as %3A. (This is different to how \fICURLOPT_USERPWD(3)\fP is
used - beware.)
(iOS and macOS only) If curl is built against Secure Transport, then this
option is supported for backward compatibility with other SSL engines, but it
-should not be set. If the option is not set, then curl will use the
-certificates in the system and user Keychain to verify the peer, which is the
-preferred method of verifying the peer's certificate chain.
+should not be set. If the option is not set, then curl uses the certificates
+in the system and user Keychain to verify the peer, which is the preferred
+method of verifying the peer's certificate chain.
The application does not have to keep the string around after setting this
option.
.SH DESCRIPTION
This option is for connecting to an HTTPS proxy, not an HTTPS server.
-Pass a pointer to a null-terminated string as parameter. It will be used as
-the password required to use the \fICURLOPT_PROXY_SSLKEY(3)\fP private key.
-You never need a pass phrase to load a certificate but you need one to load
-your private key.
+Pass a pointer to a null-terminated string as parameter. It is used as the
+password required to use the \fICURLOPT_PROXY_SSLKEY(3)\fP private key. You
+never need a pass phrase to load a certificate but you need one to load your
+private key.
The application does not have to keep the string around after setting this
option.
When negotiating a TLS or SSL connection, the https proxy sends a certificate
indicating its identity. A public key is extracted from this certificate and
-if it does not exactly match the public key provided to this option, curl will
-abort the connection before sending or receiving any data.
+if it does not exactly match the public key provided to this option, libcurl
+aborts the connection before sending or receiving any data.
On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned.
Use one of the available defines for this purpose. The available options are:
.RS
.IP CURL_SSLVERSION_DEFAULT
-The default action. This will attempt to figure out the remote SSL protocol
+The default action. This attempts to figure out the remote SSL protocol
version.
.IP CURL_SSLVERSION_TLSv1
TLSv1.x
With BearSSL you do not add/remove ciphers. If one uses this option then all
known ciphers are disabled and only those passed in are enabled.
-you will find more details about cipher lists on this URL:
+Find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
7.44.0)
.IP CURLSSLOPT_NO_PARTIALCHAIN
Tells libcurl to not accept "partial" certificate chains, which it otherwise
-does by default. This option is only supported for OpenSSL and will fail the
+does by default. This option is only supported for OpenSSL and fails the
certificate verification if the chain ends with an intermediate certificate
and not with a root cert. (Added in 7.68.0)
.IP CURLSSLOPT_REVOKE_BEST_EFFORT
syntactically correct, it consists of one or more cipher suite strings
separated by colons.
-you will find more details about cipher lists on this URL:
+Find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
.fi
.SH DESCRIPTION
Pass a pointer to a linked list of FTP or SFTP commands to pass to the server
-prior to your request. This will be done before any other commands are issued
-(even before the CWD command for FTP). The linked list should be a fully valid
-list of 'struct curl_slist' structs properly filled in with text strings. Use
+prior to your request. This is done before any other commands are issued (even
+before the CWD command for FTP). The linked list should be a fully valid list
+of 'struct curl_slist' structs properly filled in with text strings. Use
\fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear
the entire list afterwards with \fIcurl_slist_free_all(3)\fP.
Disable this operation again by setting a NULL to this option.
When speaking to an FTP server, prefix the command with an asterisk (*) to
-make libcurl continue even if the command fails as by default libcurl will
-stop at first failure.
+make libcurl continue even if the command fails as by default libcurl stops at
+first failure.
The set of valid FTP commands depends on the server (see RFC 959 for a list of
mandatory commands).
libcurl does not inspect, parse or "understand" the commands passed to the
server using this option. If you change connection state, working directory or
-similar using quote commands, libcurl will not know about it.
+similar using quote commands, libcurl does not know about it.
The valid SFTP commands are:
.RS
}
.fi
.SH AVAILABILITY
-If built with TLS enabled. Only the OpenSSL backend will use this, and only
-with OpenSSL versions before 1.1.0.
+If built with TLS enabled. Only the OpenSSL backend uses this, and only with
+OpenSSL versions before 1.1.0.
This option was deprecated in 7.84.0.
.SH RETURN VALUE
out and X and Y are byte indexes.
HTTP transfers also support several intervals, separated with commas as in
-\fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP
-server to send the response document in pieces (using standard MIME separation
+\fI"X-Y,N-M"\fP. Using this kind of multiple intervals causes the HTTP server
+to send the response document in pieces (using standard MIME separation
techniques). Unfortunately, the HTTP standard (RFC 7233 section 3.1) allows
servers to ignore range requests so even when you set \fICURLOPT_RANGE(3)\fP
for a request, you may end up getting the full response sent back.
.fi
.SH DESCRIPTION
Data \fIpointer\fP to pass to the file read function. If you use the
-\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you will get as
-input in the fourth argument to the callback.
+\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you get as input in
+the fourth argument to the callback.
If you do not specify a read callback but instead rely on the default internal
read function, this data must be a valid readable FILE * (cast to 'void *').
-If you are using libcurl as a win32 DLL, you \fBMUST\fP use a
-\fICURLOPT_READFUNCTION(3)\fP if you set this option or you will experience
-crashes.
+If you are using libcurl as a DLL on Windows, you must use the
+\fICURLOPT_READFUNCTION(3)\fP callback if you set this option, otherwise you
+might experience crashes.
.SH DEFAULT
By default, this is a FILE * to stdin.
.SH PROTOCOLS
This option was once known by the older name CURLOPT_INFILE, the name
\fICURLOPT_READDATA(3)\fP was introduced in 7.9.7.
.SH RETURN VALUE
-This will return CURLE_OK.
+This returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_READFUNCTION "(3), " CURLOPT_WRITEDATA "(3), "
Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option.
-Your function must return the actual number of bytes that it stored in the data
-area pointed at by the pointer \fIbuffer\fP. Returning 0 will signal
-end-of-file to the library and cause it to stop the current transfer.
+Your function must return the actual number of bytes that it stored in the
+data area pointed at by the pointer \fIbuffer\fP. Returning 0 signals
+end-of-file to the library and causes it to stop the current transfer.
If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
-server expected it, like when you have said you will upload N bytes and you
+server expected it, like when you have said you would upload N bytes and you
upload less than N bytes), you may experience that the server "hangs" waiting
-for the rest of the data that will not come.
+for the rest of the data that is not sent.
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
\fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data
-that the callback wants, or it will be considered the final packet by the
-server end and the transfer will end there.
+that the callback wants, or it is considered the final packet by the server
+end and the transfer ends there.
If you set this callback pointer to NULL, or do not set it at all, the default
-internal read function will be used. It is doing an fread() on the FILE *
-userdata set with \fICURLOPT_READDATA(3)\fP.
+internal read function is used. It is doing an fread() on the FILE * userdata
+set with \fICURLOPT_READDATA(3)\fP.
You can set the total size of the data you are sending by using
\fICURLOPT_INFILESIZE_LARGE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP,
CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT
was added in 7.12.1.
.SH RETURN VALUE
-This will return CURLE_OK.
+This returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_READDATA "(3), " CURLOPT_WRITEFUNCTION "(3), "
.BR CURLOPT_SEEKFUNCTION "(3), " CURLOPT_UPLOAD "(3), " CURLOPT_POST "(3), "
Protocols denied by \fICURLOPT_PROTOCOLS(3)\fP are not overridden by this
option.
-By default libcurl will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2).
-Older versions of libcurl allowed all protocols on redirect except several
-disabled for security reasons: Since 7.19.4 FILE and SCP are disabled, and
-since 7.40.0 SMB and SMBS are also disabled. \fICURLPROTO_ALL\fP enables all
-protocols on redirect, including those disabled for security.
+By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirect (7.65.2).
+\fICURLPROTO_ALL\fP enables all protocols on redirect, including those
+otherwise disabled for security.
These are the available protocol defines:
.nf
Protocols denied by \fICURLOPT_PROTOCOLS_STR(3)\fP are not overridden by this
option.
-By default libcurl will allow HTTP, HTTPS, FTP and FTPS on redirects (since
-7.65.2). Older versions of libcurl allowed all protocols on redirect except
-several disabled for security reasons: Since 7.19.4 FILE and SCP are disabled,
-and since 7.40.0 SMB and SMBS are also disabled.
+By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects (since
+7.65.2).
These are the available protocols:
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REFERER, char *where);
.fi
.SH DESCRIPTION
-Pass a pointer to a null-terminated string as parameter. It will be used to
-set the Referer: header in the http request sent to the remote server. This
-can be used to fool servers or scripts. You can also set any custom header
-with \fICURLOPT_HTTPHEADER(3)\fP.
+Pass a pointer to a null-terminated string as parameter. It is used to set the
+Referer: header field in the HTTP request sent to the remote server. You can
+set any custom header with \fICURLOPT_HTTPHEADER(3)\fP.
The application does not have to keep the string around after setting this
option.
[+]HOST:PORT:ADDRESS[,ADDRESS]
.fi
-\&... where HOST is the name libcurl will try to resolve, PORT is the port
-number of the service where libcurl wants to connect to the HOST and ADDRESS
-is one or more numerical IP addresses. If you specify multiple IP addresses
-they need to be separated by comma. If libcurl is built to support IPv6, each
-of the ADDRESS entries can of course be either IPv4 or IPv6 style addressing.
+HOST is the name libcurl wants to resolve, PORT is the port number of the
+service where libcurl wants to connect to the HOST and ADDRESS is one or more
+numerical IP addresses. If you specify multiple IP addresses they need to be
+separated by comma. If libcurl is built to support IPv6, each of the ADDRESS
+entries can of course be either IPv4 or IPv6 style addressing.
-This option effectively pre-populates the DNS cache with entries for the
-host+port pair so redirects and everything that operations against the
-HOST+PORT will instead use your provided ADDRESS.
+This option effectively populates the DNS cache with entries for the host+port
+pair so redirects and everything that operations against the HOST+PORT instead
+use your provided ADDRESS.
The optional leading "+" specifies that the new entry should time-out. Entries
-added without the leading plus character will never time-out whereas entries
-added with "+HOST:..." will time-out just like ordinary DNS cache entries.
+added without the leading plus character never times out whereas entries added
+with "+HOST:..." times out just like ordinary DNS cache entries.
If the DNS cache already has an entry for the given host+port pair, the new
-entry will override the former one.
+entry overrides the former one.
-An ADDRESS provided by this option will only be used if not restricted by the
+An ADDRESS provided by this option is only used if not restricted by the
setting of \fICURLOPT_IPRESOLVE(3)\fP to a different IP version.
To remove names from the DNS cache again, to stop providing these fake
void *pointer);
.fi
.SH DESCRIPTION
-Pass a \fIpointer\fP that will be untouched by libcurl and passed as the third
+Pass a \fIpointer\fP is be untouched by libcurl and passed as the third
argument in the resolver start callback set with
\fICURLOPT_RESOLVER_START_FUNCTION(3)\fP.
.SH DEFAULT
\fIuserdata\fP is the user pointer set with the
\fICURLOPT_RESOLVER_START_DATA(3)\fP option.
-The callback must return 0 on success. Returning a non-zero value will cause
-the resolve to fail.
+The callback must return 0 on success. Returning a non-zero value causes the
+resolve to fail.
.SH DEFAULT
NULL (No callback)
.SH PROTOCOLS
(useful to continue an interrupted upload).
When doing uploads with FTP, the resume position is where in the local/source
-file libcurl should try to resume the upload from and it will then append the
+file libcurl should try to resume the upload from and it then appends the
source file to the remote target file.
If you need to resume a transfer beyond the 2GB limit, use
(useful to continue an interrupted upload).
When doing uploads with FTP, the resume position is where in the local/source
-file libcurl should try to resume the upload from and it will then append the
-source file to the remote target file.
+file libcurl should try to resume the upload from and it appends the source
+file to the remote target file.
.SH DEFAULT
0, not used
.SH PROTOCOLS
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_CLIENT_CSEQ, long cseq);
.fi
.SH DESCRIPTION
-Pass a long to set the CSEQ number to issue for the next RTSP
-request. Useful if the application is resuming a previously broken
-connection. The CSEQ will increment from this new number henceforth.
+Pass a long to set the CSEQ number to issue for the next RTSP request. Useful
+if the application is resuming a previously broken connection. The CSEQ
+increments from this new number henceforth.
.SH DEFAULT
0
.SH PROTOCOLS
.IP CURL_RTSPREQ_DESCRIBE
Used to get the low level description of a stream. The application should note
what formats it understands in the \fI'Accept:'\fP header. Unless set
-manually, libcurl will automatically fill in \fI'Accept: application/sdp'\fP.
-Time-condition headers will be added to Describe requests if the
-\fICURLOPT_TIMECONDITION(3)\fP option is active. \fB(The session ID is not
+manually, libcurl automatically adds in \fI'Accept: application/sdp'\fP.
+Time-condition headers are added to Describe requests if the
+\fICURLOPT_TIMECONDITION(3)\fP option is used. \fB(The session ID is not
needed for this method)\fP
.IP CURL_RTSPREQ_ANNOUNCE
When sent by a client, this method changes the description of the session. For
Setup is used to initialize the transport layer for the session. The
application must set the desired Transport options for a session by using the
\fICURLOPT_RTSP_TRANSPORT(3)\fP option prior to calling setup. If no session
-ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl will
-extract and use the session ID in the response to this request. The session ID
-is not needed for this method.
+ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl extracts
+and uses the session ID in the response to this request. The session ID is not
+needed for this method.
.IP CURL_RTSPREQ_PLAY
Send a Play command to the server. Use the \fICURLOPT_RANGE(3)\fP option to
modify the playback time (e.g. \fInpt=10-15\fP).
terminate the RTSP session since it is valid to control an RTSP session over
different connections.
.IP CURL_RTSPREQ_GET_PARAMETER
-Retrieve a parameter from the server. By default, libcurl will automatically
-include a \fIContent-Type: text/parameters\fP header on all non-empty requests
-unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST
-(see \fICURL_RTSPREQ_SET_PARAMETER\fP).
-Applications wishing to send a heartbeat message (e.g. in the presence of a
-server-specified timeout) should send use an empty GET_PARAMETER request.
+Retrieve a parameter from the server. By default, libcurl adds a
+\fIContent-Type: text/parameters\fP header on all non-empty requests unless a
+custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see
+\fICURL_RTSPREQ_SET_PARAMETER\fP). Applications wishing to send a heartbeat
+message (e.g. in the presence of a server-specified timeout) should send use
+an empty GET_PARAMETER request.
.IP CURL_RTSPREQ_SET_PARAMETER
-Set a parameter on the server. By default, libcurl will automatically include
-a \fIContent-Type: text/parameters\fP header unless a custom one is set. The
-interaction with SET_PARAMETER is much like an HTTP PUT or POST. An application
-may either use \fICURLOPT_UPLOAD(3)\fP with \fICURLOPT_READDATA(3)\fP like a
-HTTP PUT, or it may use \fICURLOPT_POSTFIELDS(3)\fP like an HTTP POST. No
-chunked transfers are allowed, so the application must set the
-\fICURLOPT_INFILESIZE(3)\fP in the former and \fICURLOPT_POSTFIELDSIZE(3)\fP
-in the latter. Also, there is no use of multi-part POSTs within RTSP.
+Set a parameter on the server. By default, libcurl uses a
+\fIContent-Type: text/parameters\fP header unless a custom one is set.
+The interaction with SET_PARAMETER is much like an HTTP PUT or POST. An
+application may either use \fICURLOPT_UPLOAD(3)\fP with
+\fICURLOPT_READDATA(3)\fP like a HTTP PUT, or it may use
+\fICURLOPT_POSTFIELDS(3)\fP like an HTTP POST. No chunked transfers are
+allowed, so the application must set the \fICURLOPT_INFILESIZE(3)\fP in the
+former and \fICURLOPT_POSTFIELDSIZE(3)\fP in the latter. Also, there is no use
+of multi-part POSTs within RTSP.
.IP CURL_RTSPREQ_RECORD
Used to tell the server to record a session. Use the \fICURLOPT_RANGE(3)\fP
option to modify the record time.
.IP CURL_RTSPREQ_RECEIVE
This is a special request because it does not send any data to the server. The
application may call this function in order to receive interleaved RTP
-data. It will return after processing one read buffer of data in order to give
-the application a chance to run.
+data. It returns after processing one read buffer of data in order to give the
+application a chance to run.
.SH DEFAULT
.SH PROTOCOLS
RTSP
.SH DESCRIPTION
Pass a char * as a parameter to set the value of the current RTSP Session ID
for the handle. Useful for resuming an in-progress session. Once this value is
-set to any non-NULL value, libcurl will return \fICURLE_RTSP_SESSION_ERROR\fP
-if ID received from the server does not match. If unset (or set to NULL),
-libcurl will automatically set the ID the first time the server sets it in a
-response.
+set to any non-NULL value, libcurl returns \fICURLE_RTSP_SESSION_ERROR\fP if
+ID received from the server does not match. If unset (or set to NULL), libcurl
+automatically sets the ID the first time the server sets it in a response.
The application does not have to keep the string around after setting this
option.
Set the stream \fIURI\fP to operate on by passing a char * . For example, a
single session may be controlling \fIrtsp://foo/twister/audio\fP and
\fIrtsp://foo/twister/video\fP and the application can switch to the
-appropriate stream using this option. If unset, libcurl will default to
-operating on generic server options by passing '*' in the place of the RTSP
-Stream URI. This option is distinct from \fICURLOPT_URL(3)\fP. When working
-with RTSP, the \fICURLOPT_RTSP_STREAM_URI(3)\fP indicates what URL to send to
-the server in the request header while the \fICURLOPT_URL(3)\fP indicates
-where to make the connection to. (e.g. the \fICURLOPT_URL(3)\fP for the above
-examples might be set to \fIrtsp://foo/twister\fP
+appropriate stream using this option. If unset, libcurl defaults to operating
+on generic server options by passing '*' in the place of the RTSP Stream
+URI. This option is distinct from \fICURLOPT_URL(3)\fP. When working with
+RTSP, the \fICURLOPT_RTSP_STREAM_URI(3)\fP indicates what URL to send to the
+server in the request header while the \fICURLOPT_URL(3)\fP indicates where to
+make the connection to. (e.g. the \fICURLOPT_URL(3)\fP for the above examples
+might be set to \fIrtsp://foo/twister\fP
The application does not have to keep the string around after setting this
option.
the PLAIN SASL authentication mechanism where it is optional.
When not specified only the authentication identity (\fIauthcid\fP) as
-specified by the username will be sent to the server, along with the
-password. The server will derive a \fIauthzid\fP from the \fIauthcid\fP when
-not provided, which it will then uses internally.
+specified by the username is sent to the server, along with the password. The
+server derives a \fIauthzid\fP from the \fIauthcid\fP when not provided, which
+it then uses internally.
When the \fIauthzid\fP is specified, the use of which is server dependent, it
can be used to access another user's inbox, that the user has been granted
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_IR, long enable);
.fi
.SH DESCRIPTION
-Pass a long. If the value is 1, curl will send the initial response to the
-server in the first authentication packet in order to reduce the number of
-ping pong requests. Only applicable to the following supporting SASL
-authentication mechanisms:
+Pass a long. If the value is 1, curl sends the initial response to the server
+in the first authentication packet in order to reduce the number of ping pong
+requests. Only applicable to the following supporting SASL authentication
+mechanisms:
* Login
* Plain
.fi
.SH DESCRIPTION
Data \fIpointer\fP to pass to the seek callback function. If you use the
-\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you will get as
-input.
+\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you get as input.
.SH DEFAULT
If you do not set this, NULL is passed to the callback.
.SH PROTOCOLS
.SH DESCRIPTION
Pass a \fIshare\fP handle as a parameter. The share handle must have been
created by a previous call to \fIcurl_share_init(3)\fP. Setting this option,
-will make this curl handle use the data from the shared handle instead of
-keeping the data to itself. This enables several curl handles to share
-data. If the curl handles are used simultaneously in multiple threads, you
-\fBMUST\fP use the locking methods in the share handle. See
-\fIcurl_share_setopt(3)\fP for details.
+makes this curl handle use the data from the shared handle instead of keeping
+the data to itself. This enables several curl handles to share data. If the
+curl handles are used simultaneously in multiple threads, you \fBMUST\fP use
+the locking methods in the share handle. See \fIcurl_share_setopt(3)\fP for
+details.
-If you add a share that is set to share cookies, your easy handle will use
-that cookie cache and get the cookie engine enabled. If you stop sharing an
-object that was using cookies (or change to another object that does not share
-cookies), the easy handle will get its cookie engine disabled.
+If you add a share that is set to share cookies, your easy handle uses that
+cookie cache and get the cookie engine enabled. If you stop sharing an object
+that was using cookies (or change to another object that does not share
+cookies), the easy handle gets its cookie engine disabled.
-Data that the share object is not set to share will be dealt with the usual
-way, as if no share was used.
+Data that the share object is not set to share is dealt with the usual way, as
+if no share was used.
Set this option to NULL again to stop using that share object.
.SH DEFAULT
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTDATA, void *pointer);
.fi
.SH DESCRIPTION
-Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
+Pass a \fIpointer\fP that is untouched by libcurl and passed as the first
argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
Return \fICURL_SOCKOPT_OK\fP from the callback on success. Return
\fICURL_SOCKOPT_ERROR\fP from the callback function to signal an unrecoverable
-error to the library and it will close the socket and return
-\fICURLE_COULDNT_CONNECT\fP.
-Alternatively, the callback function can return
+error to the library and it closes the socket and returns
+\fICURLE_COULDNT_CONNECT\fP. Alternatively, the callback function can return
\fICURL_SOCKOPT_ALREADY_CONNECTED\fP, to tell libcurl that the socket is
-already connected and then libcurl will not attempt to connect it. This allows
-an application to pass in an already connected socket with
+already connected and then libcurl does no attempt to connect. This allows an
+application to pass in an already connected socket with
\fICURLOPT_OPENSOCKETFUNCTION(3)\fP and then have this function make libcurl
not attempt to connect (again).
.SH DEFAULT
curl = curl_easy_init();
if(curl) {
- /* libcurl will internally think that you connect to the host
+ /* libcurl thinks that you connect to the host
* and port that you specify in the URL option. */
curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
/* call this function to get a socket */
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOSTKEYDATA, void *pointer);
.fi
.SH DESCRIPTION
-Pass a void * as parameter. This \fIpointer\fP will be passed along verbatim
-to the callback set with \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP.
+Pass a void * as parameter. This \fIpointer\fP is passed along untouched to
+the callback set with \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
.SH DESCRIPTION
Pass a char * pointing to a string containing 32 hexadecimal digits. The
string should be the 128 bit MD5 checksum of the remote host's public key, and
-libcurl will reject the connection to the host unless the MD5 checksum match.
+libcurl aborts the connection to the host unless the MD5 checksum match.
+
+MD5 is a weak algorithm. We strongly recommend using
+\fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP instead.
The application does not have to keep the string around after setting this
option.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256,
char *sha256);
.SH DESCRIPTION
-Pass a char * pointing to a string containing a Base64-encoded SHA256
-hash of the remote host's public key.
-The transfer will fail if the given hash does not match the hash the
-remote host provides.
+Pass a char * pointing to a string containing a Base64-encoded SHA256 hash of
+the remote host's public key. The transfer fails if the given hash does not
+match the hash the remote host provides.
.SH DEFAULT
NULL
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYDATA, void *pointer);
.fi
.SH DESCRIPTION
-Pass a void * as parameter. This \fIpointer\fP will be passed along verbatim
-to the callback set with \fICURLOPT_SSH_KEYFUNCTION(3)\fP.
+Pass a void * as parameter. This \fIpointer\fP is passed along verbatim to the
+callback set with \fICURLOPT_SSH_KEYFUNCTION(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
CURLKHSTAT_REJECT, /* reject the connection, return an error */
CURLKHSTAT_DEFER, /* do not accept it, but we cannot answer right
now. Causes a CURLE_PEER_FAILED_VERIFICATION error but
- the connection will be left intact */
+ the connection is left intact */
CURLKHSTAT_FINE_REPLACE
};
shown above.
It gets called when the known_host matching has been done, to allow the
-application to act and decide for libcurl how to proceed. The callback will
-only be called if \fICURLOPT_SSH_KNOWNHOSTS(3)\fP is also set.
+application to act and decide for libcurl how to proceed. The callback is only
+called if \fICURLOPT_SSH_KNOWNHOSTS(3)\fP is also set.
This callback function gets passed the CURL handle, the key from the
known_hosts file \fIknownkey\fP, the key from the remote site \fIfoundkey\fP,
\fICURLOPT_SSH_KEYDATA(3)\fP). It MUST return one of the following return
codes to tell libcurl how to act:
.IP CURLKHSTAT_FINE_REPLACE
-The new host+key is accepted and libcurl will replace the old host+key into
-the known_hosts file before continuing with the connection. This will also
-add the new host+key combo to the known_host pool kept in memory if it was not
-already present there. The adding of data to the file is done by completely
-replacing the file with a new copy, so the permissions of the file must allow
+The new host+key is accepted and libcurl replaces the old host+key into the
+known_hosts file before continuing with the connection. This also adds the new
+host+key combo to the known_host pool kept in memory if it was not already
+present there. The adding of data to the file is done by completely replacing
+the file with a new copy, so the permissions of the file must allow
this. (Added in 7.73.0)
.IP CURLKHSTAT_FINE_ADD_TO_FILE
-The host+key is accepted and libcurl will append it to the known_hosts file
-before continuing with the connection. This will also add the host+key combo
-to the known_host pool kept in memory if it was not already present there. The
-adding of data to the file is done by completely replacing the file with a new
-copy, so the permissions of the file must allow this.
+The host+key is accepted and libcurl appends it to the known_hosts file before
+continuing with the connection. This also adds the host+key combo to the
+known_host pool kept in memory if it was not already present there. The adding
+of data to the file is done by completely replacing the file with a new copy,
+so the permissions of the file must allow this.
.IP CURLKHSTAT_FINE
-The host+key is accepted libcurl will continue with the connection. This will
-also add the host+key combo to the known_host pool kept in memory if it was not
-already present there.
+The host+key is accepted libcurl continues with the connection. This also adds
+the host+key combo to the known_host pool kept in memory if it was not already
+present there.
.IP CURLKHSTAT_REJECT
-The host+key is rejected. libcurl will deny the connection to continue and it
-will be closed.
+The host+key is rejected. libcurl denies the connection to continue and it is
+closed.
.IP CURLKHSTAT_DEFER
The host+key is rejected, but the SSH connection is asked to be kept alive.
This feature could be used when the app wants to somehow return back and act
.SH DESCRIPTION
Pass a pointer to a null-terminated string holding the file name of the
known_host file to use. The known_hosts file should use the OpenSSH file
-format as supported by libssh2. If this file is specified, libcurl will only
-accept connections with hosts that are known and present in that file, with a
+format as supported by libssh2. If this file is specified, libcurl only
+accepts connections with hosts that are known and present in that file, with a
matching public key. Use \fICURLOPT_SSH_KEYFUNCTION(3)\fP to alter the default
behavior on host and key matches and mismatches.
variable is set, and just "id_dsa.pub" in the current directory if HOME is not
set.
-If NULL (or an empty string) is passed, libcurl will pass no public key to
-libssh2, which then tries to compute it from the private key. This is known
-to work with libssh2 1.4.0+ linked against OpenSSL.
+If NULL (or an empty string) is passed, libcurl passes no public key to
+libssh2, which then computes it from the private key. This is known to work
+with libssh2 1.4.0+ linked against OpenSSL.
The application does not have to keep the string around after setting this
option.
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE, char *id);
.fi
.SH DESCRIPTION
-Pass a pointer to a null-terminated string as parameter. It will be used as
-the identifier for the crypto engine you want to use for your private key.
+Pass a pointer to a null-terminated string as parameter. It is used as the
+identifier for the crypto engine you want to use for your private key.
The application does not have to keep the string around after setting this
option.
.RS
.IP CURL_SSLVERSION_MAX_DEFAULT
The flag defines the maximum supported TLS version by libcurl, or the default
-value from the SSL library is used. libcurl will use a sensible default
-maximum, which was TLS v1.2 up to before 7.61.0 and is TLS v1.3 since then -
-assuming the TLS library support it. (Added in 7.54.0)
+value from the SSL library is used. libcurl uses a sensible default maximum,
+which was TLS v1.2 up to before 7.61.0 and is TLS v1.3 since then - assuming
+the TLS library support it. (Added in 7.54.0)
.IP CURL_SSLVERSION_MAX_TLSv1_0
The flag defines maximum supported TLS version as TLS v1.0.
(Added in 7.54.0)
For Schannel, you can use this option to set algorithms but not specific cipher
suites. Refer to the ciphers lists document for algorithms.
-You will find more details about cipher lists on this URL:
+Find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
.fi
.SH DESCRIPTION
Data \fIpointer\fP to pass to the ssl context callback set by the option
-\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you will get as third
+\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you get as third
parameter.
.SH DEFAULT
NULL
curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L);
curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/");
- /* Retrieve page using cacerts' certificate -> will succeed
- * load the certificate by installing a function doing the necessary
- * "modifications" to the SSL CONTEXT just before link init
- */
curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function);
curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem);
rv = curl_easy_perform(ch);
\fImbedtls_ssl_config\fP for mbedTLS or a pointer to
\fIbr_ssl_client_context\fP for BearSSL. If an error is returned from the
callback no attempt to establish a connection is made and the perform
-operation will return the callback's error code. Set the \fIclientp\fP
-argument with the \fICURLOPT_SSL_CTX_DATA(3)\fP option.
+operation returns the callback's error code. Set the \fIclientp\fP argument
+with the \fICURLOPT_SSL_CTX_DATA(3)\fP option.
-This function will get called on all new connections made to a server, during
-the SSL negotiation. The \fIssl_ctx\fP will point to a newly initialized object
-each time, but note the pointer may be the same as from a prior call.
+This function gets called on all new connections made to a server, during the
+SSL negotiation. The \fIssl_ctx\fP points to a newly initialized object each
+time, but note the pointer may be the same as from a prior call.
To use this properly, a non-trivial amount of knowledge of your SSL library is
necessary. For example, you can use this function to call library-specific
you may set \fICURLOPT_FORBID_REUSE(3)\fP from the callback function.
WARNING: If you are using DNS-over-HTTPS (DoH) via \fICURLOPT_DOH_URL(3)\fP
-then this callback will also be called for those transfers and the curl handle
-is set to an internal handle. \fBThis behavior is subject to change.\fP We
+then this callback is also called for those transfers and the curl handle is
+set to an internal handle. \fBThis behavior is subject to change.\fP We
recommend before performing your transfer set \fICURLOPT_PRIVATE(3)\fP on your
curl handle so you can identify it in the context callback. If you have a
reason to modify DoH SSL context please let us know on the curl-library
curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L);
curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/");
- /* Retrieve page using cacerts' certificate -> will succeed
- * load the certificate by installing a function doing the necessary
- * "modifications" to the SSL CONTEXT just before link init
- */
curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function);
curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem);
rv = curl_easy_perform(ch);
Pass a long as parameter set to 1L to enable or 0 to disable.
This option determines whether libcurl should use false start during the TLS
-handshake. False start is a mode where a TLS client will start sending
-application data before verifying the server's Finished message, thus saving a
-round trip when performing a full handshake.
+handshake. False start is a mode where a TLS client starts sending application
+data before verifying the server's Finished message, thus saving a round trip
+when performing a full handshake.
.SH DEFAULT
0
.SH PROTOCOLS
7.44.0)
.IP CURLSSLOPT_NO_PARTIALCHAIN
Tells libcurl to not accept "partial" certificate chains, which it otherwise
-does by default. This option is only supported for OpenSSL and will fail the
+does by default. This option is only supported for OpenSSL and fails the
certificate verification if the chain ends with an intermediate certificate
and not with a root cert. (Added in 7.68.0)
.IP CURLSSLOPT_REVOKE_BEST_EFFORT
using the "Certificate Status Request" TLS extension (aka. OCSP stapling).
Note that if this option is enabled but the server does not support the TLS
-extension, the verification will fail.
+extension, the verification fails.
.SH DEFAULT
0
.SH PROTOCOLS
stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE(3)\fP
data.
-If you are using libcurl as a win32 DLL, this option will cause an exception
-and crash in the library since it cannot access a FILE * passed on from the
+If you are using libcurl as a Windows DLL, this option causes an exception and
+a crash in the library since it cannot access a FILE * passed on from the
application. A work-around is to instead use \fICURLOPT_DEBUGFUNCTION(3)\fP.
.SH DEFAULT
stderr
This option can be set during transfer.
-\fIdephandle\fP must not be the same as \fIhandle\fP, that will cause this
-function to return an error. It must be another easy handle, and it also needs
-to be a handle of a transfer that will be sent over the same HTTP/2 connection
+\fIdephandle\fP must not be the same as \fIhandle\fP, that makes this function
+return an error. It must be another easy handle, and it also needs to be a
+handle of a transfer that is about to be sent over the same HTTP/2 connection
for this option to have an actual effect.
.SH DEFAULT
NULL
This option can be set during transfer.
-\fIdephandle\fP must not be the same as \fIhandle\fP, that will cause this
-function to return an error. It must be another easy handle, and it also needs
-to be a handle of a transfer that will be sent over the same HTTP/2 connection
+\fIdephandle\fP must not be the same as \fIhandle\fP, that makes this function
+return an error. It must be another easy handle, and it also needs to be a
+handle of a transfer that is about to be sent over the same HTTP/2 connection
for this option to have an actual effect.
.SH DEFAULT
NULL
sense and is only usable when doing multiple streams over the same
connections, which thus implies that you use \fICURLMOPT_PIPELINING(3)\fP.
-This option can be set during transfer and will then cause the updated weight
-info get sent to the server the next time an HTTP/2 frame is sent to the
-server.
+This option can be set during transfer and causes the updated weight info get
+sent to the server the next time an HTTP/2 frame is sent to the server.
See section 5.3 of RFC 7540 for protocol details.
Streams with the same parent should be allocated resources proportionally
based on their weight. So if you have two streams going, stream A with weight
-16 and stream B with weight 32, stream B will get two thirds (32/48) of the
+16 and stream B with weight 32, stream B gets two thirds (32/48) of the
available bandwidth (assuming the server can send off the data equally for
both streams).
.SH DEFAULT
-If nothing is set, the HTTP/2 protocol itself will use its own default which
-is 16.
+If nothing is set, the HTTP/2 protocol itself uses its own default which is
+16.
.SH PROTOCOLS
HTTP/2
.SH EXAMPLE
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPALIVE, long probe);
.fi
.SH DESCRIPTION
-Pass a long. If set to 1, TCP keepalive probes will be sent. The delay and
+Pass a long. If set to 1, TCP keepalive probes are used. The delay and
frequency of these probes can be controlled by the
\fICURLOPT_TCP_KEEPIDLE(3)\fP and \fICURLOPT_TCP_KEEPINTVL(3)\fP options,
provided the operating system supports them. Set to 0 (default behavior) to
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPIDLE, long delay);
.fi
.SH DESCRIPTION
-Pass a long. Sets the \fIdelay\fP, in seconds, that the operating system will
-wait while the connection is idle before sending keepalive probes. Not all
-operating systems support this option.
+Pass a long. Sets the \fIdelay\fP, in seconds, to wait while the connection is
+idle before sending keepalive probes. Not all operating systems support this
+option.
-The maximum value this accepts is 2147483648. Any larger value will be capped
-to this amount.
+The maximum value this accepts is 2147483648. Any larger value is capped to
+this amount.
.SH DEFAULT
60
.SH PROTOCOLS
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPINTVL, long interval);
.fi
.SH DESCRIPTION
-Pass a long. Sets the interval, in seconds, that the operating system will
-wait between sending keepalive probes. Not all operating systems support this
-option. (Added in 7.25.0)
+Pass a long. Sets the interval, in seconds, to wait between sending keepalive
+probes. Not all operating systems support this option. (Added in 7.25.0)
-The maximum value this accepts is 2147483648. Any larger value will be capped
-to this amount.
+The maximum value this accepts is 2147483648. Any larger value is capped to
+this amount.
.SH DEFAULT
60
.SH PROTOCOLS
.fi
.SH DESCRIPTION
Pass a long specifying whether the \fITCP_NODELAY\fP option is to be set or
-cleared (1L = set, 0 = clear). The option is set by default. This will have no
+cleared (1L = set, 0 = clear). The option is set by default. This has no
effect after the connection has been established.
-Setting this option to 1L will disable TCP's Nagle algorithm on this
-connection. The purpose of this algorithm is to try to minimize the number of
-small packets on the network (where "small packets" means TCP segments less
-than the Maximum Segment Size for the network).
+Setting this option to 1L disables TCP's Nagle algorithm on connections
+created using this handle. The purpose of this algorithm is to try to minimize
+the number of small packets on the network (where "small packets" means TCP
+segments less than the Maximum Segment Size for the network).
Maximizing the amount of data sent per TCP segment is good because it
amortizes the overhead of the send. However, in some cases small segments may
.fi
.SH DESCRIPTION
Specify \fIblocksize\fP to use for TFTP data transmission. Valid range as per
-RFC 2348 is 8-65464 bytes. The default of 512 bytes will be used if this option
-is not specified. The specified block size will only be used pending support
-by the remote server. If the server does not return an option acknowledgment
-or returns an option acknowledgment with no block size, the default of 512
-bytes will be used.
+RFC 2348 is 8-65464 bytes. The default of 512 bytes is used if this option is
+not specified. The specified block size is only used if supported by the
+remote server. If the server does not return an option acknowledgment or
+returns an option acknowledgment with no block size, the default of 512 bytes
+is used.
.SH DEFAULT
512
.SH PROTOCOLS
or \fICURL_TIMECOND_IFUNMODSINCE\fP.
The last modification time of a file is not always known and in such instances
-this feature will have no effect even if the given time condition would not
-have been met. \fIcurl_easy_getinfo(3)\fP with the
-\fICURLINFO_CONDITION_UNMET\fP option can be used after a transfer to learn if
-a zero-byte successful "transfer" was due to this condition not matching.
+this feature has no effect even if the given time condition would not have
+been met. \fIcurl_easy_getinfo(3)\fP with the \fICURLINFO_CONDITION_UNMET\fP
+option can be used after a transfer to learn if a zero-byte successful
+"transfer" was due to this condition not matching.
.SH DEFAULT
CURL_TIMECOND_NONE (0)
.SH PROTOCOLS
\fICURLOPT_TIMEOUT_MS(3)\fP is the same function but set in milliseconds.
If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the
-value set last will be used.
+value set last is used.
Since this option puts a hard limit on how long time a request is allowed to
take, it has limited use in dynamic use cases with varying transfer
.fi
.SH DESCRIPTION
Pass a long \fIval\fP as parameter. This should be the time counted as seconds
-since 1 Jan 1970, and the time will be used in a condition as specified with
+since 1 Jan 1970, and the time is used in a condition as specified with
\fICURLOPT_TIMECONDITION(3)\fP.
-On systems with 32 bit 'long' variables, this option cannot set dates beyond
-the year 2038. Consider \fICURLOPT_TIMEVALUE_LARGE(3)\fP instead.
+On systems with 32 bit 'long' variables (such as Windows), this option cannot
+set dates beyond the year 2038. Consider \fICURLOPT_TIMEVALUE_LARGE(3)\fP
+instead.
.SH DEFAULT
0
.SH PROTOCOLS
.fi
.SH DESCRIPTION
Pass a curl_off_t \fIval\fP as parameter. This should be the time counted as
-seconds since 1 Jan 1970, and the time will be used in a condition as
-specified with \fICURLOPT_TIMECONDITION(3)\fP.
+seconds since 1 Jan 1970, and the time is used in a condition as specified
+with \fICURLOPT_TIMECONDITION(3)\fP.
The difference between this option and \fICURLOPT_TIMEVALUE(3)\fP is the type
of the argument. On systems where 'long' is only 32 bit wide, this option has
suites to use for the TLS 1.3 connection. The list must be syntactically
correct, it consists of one or more cipher suite strings separated by colons.
-You will find more details about cipher lists on this URL:
+Find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
.SH DESCRIPTION
Pass a pointer to a callback function.
-This callback function will be called once right before sending the final
-CR LF in an HTTP chunked transfer to fill a list of trailing headers to be
-sent before finishing the HTTP transfer.
+This callback function is called once right before sending the final CR LF in
+an HTTP chunked transfer to fill a list of trailing headers to be sent before
+finishing the HTTP transfer.
You can set the userdata argument with the \fICURLOPT_TRAILERDATA(3)\fP
option.
The trailing headers included in the linked list must not be CRLF-terminated,
-because libcurl will add the appropriate line termination characters after
-each header item.
+because libcurl adds the appropriate line termination characters after each
+header item.
If you use curl_slist_append to add trailing headers to the curl_slist then
-libcurl will duplicate the strings, and will free the curl_slist and the
-duplicates once the trailers have been sent.
+libcurl duplicates the strings, and frees the curl_slist and the duplicates
+once the trailers have been sent.
-If one of the trailing header fields is not formatted correctly it will be
-ignored and an info message will be emitted.
+If one of the trailing header fields is not formatted correctly it is ignored
+and an info message is emitted.
The return value can either be \fBCURL_TRAILERFUNC_OK\fP or
\fBCURL_TRAILERFUNC_ABORT\fP which would respectively instruct libcurl to
static int trailer_cb(struct curl_slist **tr, void *data)
{
- /* libcurl will free the list */
+ /* libcurl frees the list */
*tr = curl_slist_append(*tr, "My-super-awesome-trailer: trailer-stuff");
return CURL_TRAILERFUNC_OK;
}
/* Now set it as a put */
curl_easy_setopt(curl, CURLOPT_PUT, 1L);
- /* Assuming we have a function that will return the data to be pushed
+ /* Assuming we have a function that returns the data to be pushed
Let that function be read_cb */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb);
/* Set the trailers filling callback */
curl_easy_setopt(curl, CURLOPT_TRAILERFUNCTION, trailer_cb);
- /* Perform the request, res will get the return code */
+ /* Perform the transfer */
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
Adds a request for compressed Transfer Encoding in the outgoing HTTP
request. If the server supports this and so desires, it can respond with the
-HTTP response sent using a compressed Transfer-Encoding that will be
-automatically uncompressed by libcurl on reception.
+HTTP response sent using a compressed Transfer-Encoding that is automatically
+uncompressed by libcurl on reception.
Transfer-Encoding differs slightly from the Content-Encoding you ask for with
\fICURLOPT_ACCEPT_ENCODING(3)\fP in that a Transfer-Encoding is strictly meant
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNIX_SOCKET_PATH, char *path);
.fi
.SH DESCRIPTION
-Enables the use of Unix domain sockets as connection endpoint and sets the path
-to \fIpath\fP. If \fIpath\fP is NULL, then Unix domain sockets are disabled. An
-empty string will result in an error at some point, it will not disable use of
-Unix domain sockets.
+Enables the use of Unix domain sockets as connection endpoint and sets the
+path to \fIpath\fP. If \fIpath\fP is NULL, then Unix domain sockets are
+disabled.
-When enabled, curl will connect to the Unix domain socket instead of
-establishing a TCP connection to a host. Since no TCP connection is created,
-curl does not need to resolve the DNS hostname in the URL.
+When enabled, curl connects to the Unix domain socket instead of establishing
+a TCP connection to the host. Since no network connection is created, curl
+does not resolve the DNS hostname in the URL.
The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms
it might be even less.
hostname changed. This option is meaningful only when setting
\fICURLOPT_FOLLOWLOCATION(3)\fP.
-Further, when this option is not used or set to \fB0L\fP, libcurl will not
-send custom set nor internally generated Authentication: headers on requests
-done to other hosts than the one used for the initial URL.
+Further, when this option is not used or set to \fB0L\fP, libcurl does not
+send custom nor internally generated Authentication: headers on requests done
+to other hosts than the one used for the initial URL.
-By default, libcurl will only send credentials and Authentication headers to
-the initial host name as given in the original URL, to avoid leaking username
-+ password to other sites.
+By default, libcurl only sends credentials and Authentication headers to the
+initial host name as given in the original URL, to avoid leaking username +
+password to other sites.
This option should be used with caution: when curl follows redirects it
blindly fetches the next URL as instructed by the server. Setting
-\fICURLOPT_UNRESTRICTED_AUTH(3)\fP to 1L will therefore also make curl trust
-the server and send possibly sensitive credentials to a host the server points
-out.
+\fICURLOPT_UNRESTRICTED_AUTH(3)\fP to 1L therefore also makes curl trust the
+server and sends possibly sensitive credentials to any host the server points
+out. And then maybe again and again as the following hosts can keep
+redirecting to new hosts.
.SH DEFAULT
0
.SH PROTOCOLS
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FOLLOWLOCATION "(3), " CURLOPT_USERPWD "(3), "
+.BR CURLOPT_MAXREDIRS "(3), "
+.BR CURLOPT_REDIR_PROTOCOLS_STR "(3), "
Pass a long specifying your preferred \fIsize\fP (in bytes) for the upload
buffer in libcurl. It makes libcurl uses a larger buffer that gets passed to
the next layer in the stack to get sent off. In some setups and for some
-protocols, there's a huge performance benefit of having a larger upload
+protocols, there is a huge performance benefit of having a larger upload
buffer.
This is just treated as a request, not an order. You cannot be guaranteed to
allowed to be set is 2 megabytes. The minimum buffer size allowed to be set is
16 kilobytes.
-Since curl 7.61.1 the upload buffer is allocated on-demand - so if the handle
-is not used for upload, this buffer will not be allocated at all.
+The upload buffer is allocated on-demand - so if the handle is not used for
+upload, this buffer is not allocated at all.
DO NOT set this option on a handle that is currently used for an active
transfer as that may lead to unintended consequences.
For a greater explanation of the format please see RFC 3986.
-libcurl does not validate the syntax or use this variable until the transfer is
-issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will
+libcurl does not validate the syntax or use the URL until the transfer is
+started. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP might
still return \fICURLE_OK\fP.
If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
-then libcurl will make a guess based on the host. If the outermost sub-domain
-name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be
-used, otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by
-setting a default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details.
-
-Should the protocol, either that specified by the scheme or deduced by libcurl
-from the host name, not be supported by libcurl then
-\fICURLE_UNSUPPORTED_PROTOCOL\fP will be returned from either the
+then libcurl guesses based on the host. If the outermost sub-domain name
+matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol gets used,
+otherwise HTTP is used. Since 7.45.0 guessing can be disabled by setting a
+default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details.
+
+Should the protocol, either as specified by the URL scheme or deduced by
+libcurl from the host name, not be supported by libcurl then
+\fICURLE_UNSUPPORTED_PROTOCOL\fP is returned from either the
\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you
call them. Use \fIcurl_version_info(3)\fP for detailed information of which
protocols are supported by the build of libcurl you are using.
-\fICURLOPT_PROTOCOLS(3)\fP can be used to limit what protocols libcurl will
+\fICURLOPT_PROTOCOLS_STR(3)\fP can be used to limit what protocols libcurl may
use for this transfer, independent of what libcurl has been compiled to
support. That may be useful if you accept the URL from an external source and
want to limit the accessibility.
-The \fICURLOPT_URL(3)\fP string will be ignored if \fICURLOPT_CURLU(3)\fP is
-set.
+The \fICURLOPT_URL(3)\fP string is ignored if \fICURLOPT_CURLU(3)\fP is set.
-\fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a
+Either \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP must be set before a
transfer is started.
The application does not have to keep the string around after setting this
Applications may at times find it convenient to allow users to specify URLs
for various purposes and that string would then end up fed to this option.
-Getting a URL from an external untrusted party will bring reasons for several
-security concerns:
+Getting a URL from an external untrusted party brings several security
+concerns:
If you have an application that runs as or in a server application, getting an
unfiltered URL can easily trick your application to access a local resource
Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
heap space.
-Note that \fIcurl_easy_setopt(3)\fP will not actually parse the given string so
-given a bad URL, it will not be detected until \fIcurl_easy_perform(3)\fP or
-similar is called.
+Note that \fIcurl_easy_setopt(3)\fP does not parse the given string so given a
+bad URL, it is not detected until \fIcurl_easy_perform(3)\fP or similar is
+called.
.SH "SEE ALSO"
.BR CURLOPT_VERBOSE "(3), " CURLOPT_PROTOCOLS "(3), "
.BR CURLOPT_FORBID_REUSE "(3), " CURLOPT_FRESH_CONNECT "(3), "
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERAGENT, char *ua);
.fi
.SH DESCRIPTION
-Pass a pointer to a null-terminated string as parameter. It will be used to
-set the User-Agent: header in the HTTP request sent to the remote server. This
-can be used to fool servers or scripts. You can also set any custom header
-with \fICURLOPT_HTTPHEADER(3)\fP.
+Pass a pointer to a null-terminated string as parameter. It is used to set the
+User-Agent: header field in the HTTP request sent to the remote server. You
+can also set any custom header with \fICURLOPT_HTTPHEADER(3)\fP.
The application does not have to keep the string around after setting this
option.
authentication as well.
When using HTTP and \fICURLOPT_FOLLOWLOCATION(3)\fP, libcurl might perform
-several requests to possibly different hosts. libcurl will only send this user
-and password information to hosts using the initial host name (unless
-\fICURLOPT_UNRESTRICTED_AUTH(3)\fP is set), so if libcurl follows locations to
-other hosts it will not send the user and password to those. This is enforced
+several requests to possibly different hosts. libcurl only sends this user and
+password information to hosts using the initial host name (unless
+\fICURLOPT_UNRESTRICTED_AUTH(3)\fP is set), so if libcurl follows redirects to
+other hosts, it does not send the user and password to those. This is enforced
to prevent accidental information leakage.
Use \fICURLOPT_HTTPAUTH(3)\fP to specify the authentication method for HTTP
based connections or \fICURLOPT_LOGIN_OPTIONS(3)\fP to control IMAP, POP3 and
SMTP options.
-The user and password strings are not URL decoded, so there's no way to send
+The user and password strings are not URL decoded, so there is no way to send
in a user name containing a colon using this option. Use
\fICURLOPT_USERNAME(3)\fP for that, or include it in the URL.
Set the \fIonoff\fP parameter to 1 to make the library display a lot of
verbose information about its operations on this \fIhandle\fP. Useful for
libcurl and/or protocol debugging and understanding. The verbose information
-will be sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP.
+is sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP.
-You hardly ever want this set in production use, you will almost always want
-this when you debug/report problems.
+You hardly ever want this enabled in production use, you almost always want
+this used when you debug/report problems.
To also get all the protocol data sent and received, consider using the
\fICURLOPT_DEBUGFUNCTION(3)\fP.
.fi
.SH DESCRIPTION
A data \fIpointer\fP to pass to the write callback. If you use the
-\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you will get in
-that callback's fourth and last argument. If you do not use a write callback,
-you must make \fIpointer\fP a 'FILE *' (cast to 'void *') as libcurl will pass
-this to \fIfwrite(3)\fP when writing data.
+\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you get in that
+callback's fourth and last argument. If you do not use a write callback, you
+must make \fIpointer\fP a 'FILE *' (cast to 'void *') as libcurl passes this
+to \fIfwrite(3)\fP when writing data.
-The internal \fICURLOPT_WRITEFUNCTION(3)\fP will write the data to the FILE *
+The internal \fICURLOPT_WRITEFUNCTION(3)\fP writes the data to the FILE *
given with this option, or to stdout if this option has not been set.
-If you are using libcurl as a win32 DLL, you \fBMUST\fP use a
-\fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you will experience
+If you are using libcurl as a Windows DLL, you \fBMUST\fP use a
+\fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you might experience
crashes.
.SH DEFAULT
By default, this is a FILE * to stdout.
\fICURLOPT_FILE\fP, the name \fICURLOPT_WRITEDATA(3)\fP was introduced in
7.9.7.
.SH RETURN VALUE
-This will return CURLE_OK.
+This returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_WRITEFUNCTION "(3), " CURLOPT_READDATA "(3), "
the delivered data, and the size of that data is \fInmemb\fP; \fIsize\fP is
always 1.
-The callback function will be passed as much data as possible in all invokes,
-but you must not make any assumptions. It may be one byte, it may be
-thousands. The maximum amount of body data that will be passed to the write
+The callback function is passed as much data as possible in all invokes, but
+you must not make any assumptions. It may be one byte, it may be
+thousands. The maximum amount of body data that is be passed to the write
callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the
usual default is 16K). If \fICURLOPT_HEADER(3)\fP is enabled, which makes
header data get passed to the write callback, you can get up to
This function may be called with zero bytes data if the transferred file is
empty.
-The data passed to this function will not be null-terminated!
+The data passed to this function is not null-terminated!
Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option.
Your callback should return the number of bytes actually taken care of. If
-that amount differs from the amount passed to your callback function, it will
-signal an error condition to the library. This will cause the transfer to get
-aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
+that amount differs from the amount passed to your callback function, it
+signals an error condition to the library. This causes the transfer to get
+aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP.
You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0)
-If your callback function returns CURL_WRITEFUNC_PAUSE it will cause this
-transfer to become paused. See \fIcurl_easy_pause(3)\fP for further details.
+If the callback function returns CURL_WRITEFUNC_PAUSE it pauses this
+transfer. See \fIcurl_easy_pause(3)\fP for further details.
Set this option to NULL to get the internal default function used instead of
-your callback. The internal default function will write the data to the FILE *
+your callback. The internal default function writes the data to the FILE *
given with \fICURLOPT_WRITEDATA(3)\fP.
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
-libcurl will use 'fwrite' as a callback by default.
+libcurl uses 'fwrite' as a callback by default.
.SH PROTOCOLS
For all protocols
.SH EXAMPLE
.SH AVAILABILITY
Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
.SH RETURN VALUE
-This will return CURLE_OK.
+This returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_WRITEDATA "(3), " CURLOPT_READFUNCTION "(3), "
.BR CURLOPT_HEADERFUNCTION "(3), "
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFODATA, void *pointer);
.fi
.SH DESCRIPTION
-Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
+Pass a \fIpointer\fP that is untouched by libcurl and passed as the first
argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION(3)\fP.
This is an alias for \fICURLOPT_PROGRESSDATA(3)\fP.
shown above.
This function gets called by libcurl instead of its internal equivalent with a
-frequent interval. While data is being transferred it will be called
-frequently, and during slow periods like when nothing is being transferred it
-can slow down to about one call per second.
+frequent interval. While data is being transferred it gets called frequently,
+and during slow periods like when nothing is being transferred it can slow
+down to about one call per second.
\fIclientp\fP is the pointer set with \fICURLOPT_XFERINFODATA(3)\fP, it is not
used by libcurl but is only passed along from the application to the callback.
-The callback gets told how much data libcurl will transfer and has
-transferred, in number of bytes. \fIdltotal\fP is the total number of bytes
-libcurl expects to download in this transfer. \fIdlnow\fP is the number of
-bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl
+The callback gets told how much data libcurl is about to transfer and has
+already transferred, in number of bytes. \fIdltotal\fP is the total number of
+bytes libcurl expects to download in this transfer. \fIdlnow\fP is the number
+of bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl
expects to upload in this transfer. \fIulnow\fP is the number of bytes
uploaded so far.
-Unknown/unused argument values passed to the callback will be set to zero
-(like if you only download data, the upload size will remain 0). Many times
-the callback will be called one or more times first, before it knows the data
-sizes so a program must be made to handle that.
+Unknown/unused argument values passed to the callback are set to zero (like if
+you only download data, the upload size remains 0). Many times the callback is
+called one or more times first, before it knows the data sizes so a program
+must be made to handle that.
-If your callback function returns CURL_PROGRESSFUNC_CONTINUE it will cause
-libcurl to continue executing the default progress function.
+If your callback function returns CURL_PROGRESSFUNC_CONTINUE it makes libcurl
+to continue executing the default progress function.
-Returning any other non-zero value from this callback will cause libcurl to
-abort the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
+Returning any other non-zero value from this callback makes libcurl abort the
+transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
-If you transfer data with the multi interface, this function will not be
-called during periods of idleness unless you call the appropriate libcurl
-function that performs transfers.
+If you transfer data with the multi interface, this function is not called
+during periods of idleness unless you call the appropriate libcurl function
+that performs transfers.
\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually
get called.
.fi
.SH DESCRIPTION
Set a mutex lock callback for the share object, to allow it to get used by
-multiple threads concurrently. There's a corresponding
+multiple threads concurrently. There is a corresponding
\fICURLSHOPT_UNLOCKFUNC(3)\fP callback called when the mutex is again released.
The \fIlockcb\fP argument must be a pointer to a function matching the
the share object share multiple types of data. Unset a type again by setting
\fICURLSHOPT_UNSHARE(3)\fP.
.IP CURL_LOCK_DATA_COOKIE
-Cookie data will be shared across the easy handles using this shared object.
-Note that this does not activate an easy handle's cookie handling. You can do
-that separately by using \fICURLOPT_COOKIEFILE(3)\fP for example.
+Cookie data is shared across the easy handles using this shared object. Note
+that this does not activate an easy handle's cookie handling. You can do that
+separately by using \fICURLOPT_COOKIEFILE(3)\fP for example.
.IP CURL_LOCK_DATA_DNS
-Cached DNS hosts will be shared across the easy handles using this shared
+Cached DNS hosts are shared across the easy handles using this shared
object. Note that when you use the multi interface, all easy handles added to
-the same multi handle will share DNS cache by default without using this
-option.
+the same multi handle share DNS cache by default without using this option.
.IP CURL_LOCK_DATA_SSL_SESSION
-SSL session IDs will be shared across the easy handles using this shared
-object. This will reduce the time spent in the SSL handshake when reconnecting
-to the same server. Note SSL session IDs are reused within the same easy
-handle by default. Note this symbol was added in 7.10.3 but was not
-implemented until 7.23.0.
+SSL session IDs are shared across the easy handles using this shared
+object. This reduces the time spent in the SSL handshake when reconnecting to
+the same server. Note SSL session IDs are reused within the same easy handle
+by default. Note this symbol was added in 7.10.3 but was not implemented until
+7.23.0.
.IP CURL_LOCK_DATA_CONNECT
Put the connection cache in the share object and make all easy handles using
this share object share the connection cache.
existed before this.
Note that when you use the multi interface, all easy handles added to the same
-multi handle will share connection cache by default without using this option.
+multi handle shares connection cache by default without using this option.
.IP CURL_LOCK_DATA_PSL
The Public Suffix List stored in the share object is made available to all
easy handle bound to the later. Since the Public Suffix List is periodically
Added in 7.61.0.
Note that when you use the multi interface, all easy handles added to the same
-multi handle will share PSL cache by default without using this option.
+multi handle shares PSL cache by default without using this option.
.IP CURL_LOCK_DATA_HSTS
The in-memory HSTS cache.
CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNLOCKFUNC, unlockcb);
.fi
.SH DESCRIPTION
-Set a mutex unlock callback for the share object. There's a corresponding
+Set a mutex unlock callback for the share object. There is a corresponding
\fICURLSHOPT_LOCKFUNC(3)\fP callback called when the mutex is first locked.
The \fIunlockcb\fP argument must be a pointer to a function matching the
data arguments to remove multiple types from the shared object. Add data to
share again with \fICURLSHOPT_SHARE(3)\fP.
.IP CURL_LOCK_DATA_COOKIE
-Cookie data will no longer be shared across the easy handles using this shared
+Cookie data is no longer shared across the easy handles using this shared
object.
.IP CURL_LOCK_DATA_DNS
-Cached DNS hosts will be no longer be shared across the easy handles using
-this shared object.
-.IP CURL_LOCK_DATA_SSL_SESSION
-SSL session IDs will no longer be shared across the easy handles using this
+Cached DNS hosts are no longer shared across the easy handles using this
shared object.
+.IP CURL_LOCK_DATA_SSL_SESSION
+SSL session IDs are no longer shared across the easy handles using this shared
+object.
.IP CURL_LOCK_DATA_CONNECT
The connection cache is no longer shared.
.IP CURL_LOCK_DATA_PSL
projects / thirdparty / curl.git / commitdiff
