mirror of
https://github.com/curl/curl.git
synced 2026-08-25 19:03:33 +03:00
stop using the word 'just'
Everywhere. In documentation and code comments. It is almost never a good word and almost always a filler that should be avoided. Closes #20793
This commit is contained in:
parent
4b583b7585
commit
b4dba346cd
213 changed files with 727 additions and 772 deletions
|
|
@ -15,7 +15,7 @@ sizes/defines and more.
|
|||
## Upgrades
|
||||
|
||||
A libcurl upgrade does not break the ABI or change established and documented
|
||||
behavior. Your application can remain using libcurl just as before, only with
|
||||
behavior. Your application can remain using libcurl like before, only with
|
||||
fewer bugs and possibly with added new features.
|
||||
|
||||
## Version Numbers
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ to the function is encoded correctly.
|
|||
# URLs
|
||||
|
||||
URLs are by definition *URL encoded*. To create a proper URL from a set of
|
||||
components that may not be URL encoded already, you cannot just URL encode the
|
||||
components that may not be URL encoded already, you cannot URL encode the
|
||||
entire URL string with curl_easy_escape(3), because it then also converts
|
||||
colons, slashes and other symbols that you probably want untouched.
|
||||
|
||||
|
|
|
|||
|
|
@ -196,16 +196,15 @@ In microseconds. (Added in 8.10.0) See CURLINFO_POSTTRANSFER_TIME_T(3)
|
|||
|
||||
## CURLINFO_PRETRANSFER_TIME
|
||||
|
||||
The time it took from the start until the file transfer is just about to
|
||||
begin. This includes all pre-transfer commands and negotiations that are
|
||||
specific to the particular protocol(s) involved. See
|
||||
CURLINFO_PRETRANSFER_TIME(3)
|
||||
The time it took from the start until the file transfer is about to begin.
|
||||
This includes all pre-transfer commands and negotiations that are specific to
|
||||
the particular protocol(s) involved. See CURLINFO_PRETRANSFER_TIME(3)
|
||||
|
||||
## CURLINFO_PRETRANSFER_TIME_T
|
||||
|
||||
The time it took from the start until the file transfer is just about to
|
||||
begin. This includes all pre-transfer commands and negotiations that are
|
||||
specific to the particular protocol(s) involved. In microseconds. See
|
||||
The time it took from the start until the file transfer is about to begin.
|
||||
This includes all pre-transfer commands and negotiations that are specific to
|
||||
the particular protocol(s) involved. In microseconds. See
|
||||
CURLINFO_PRETRANSFER_TIME_T(3)
|
||||
|
||||
## CURLINFO_PRIMARY_IP
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ void curl_easy_reset(CURL *handle);
|
|||
|
||||
Re-initializes all options previously set on a specified curl handle to the
|
||||
default values. This puts back the handle to the same state as it was in when
|
||||
it was just created with curl_easy_init(3).
|
||||
it was created with curl_easy_init(3).
|
||||
|
||||
It does not change the following information kept in the handle: live
|
||||
connections, the Session ID cache, the DNS cache, the cookies, the shares or
|
||||
|
|
|
|||
|
|
@ -708,7 +708,7 @@ How to act on redirects after POST. See CURLOPT_POSTREDIR(3)
|
|||
|
||||
## CURLOPT_PREQUOTE
|
||||
|
||||
Commands to run just before transfer. See CURLOPT_PREQUOTE(3)
|
||||
Commands to run immediately before transfer. See CURLOPT_PREQUOTE(3)
|
||||
|
||||
## CURLOPT_PREREQDATA
|
||||
|
||||
|
|
|
|||
|
|
@ -83,8 +83,7 @@ a cryptographic hash of the salt and **session_key**. The salt is generated
|
|||
for every session individually. Storing **shmac** is recommended when
|
||||
placing session tickets in a file, for example.
|
||||
|
||||
A third party may brute-force known hostnames, but cannot just "grep" for
|
||||
them.
|
||||
A third party may brute-force known hostnames, but cannot "grep" for them.
|
||||
|
||||
## Session Data
|
||||
|
||||
|
|
|
|||
|
|
@ -37,11 +37,11 @@ curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set
|
|||
(most platforms).
|
||||
|
||||
If this is not thread-safe, you must not call this function when any other
|
||||
thread in the program (i.e. a thread sharing the same memory) is running.
|
||||
This does not just mean no other thread that is using libcurl. Because
|
||||
curl_global_cleanup(3) calls functions of other libraries that are
|
||||
similarly thread-unsafe, it could conflict with any other thread that uses
|
||||
these other libraries.
|
||||
thread in the program (i.e. a thread sharing the same memory) is running. This
|
||||
does not only mean other threads that use libcurl. Because
|
||||
curl_global_cleanup(3) calls functions of other libraries that are similarly
|
||||
thread-unsafe, it could conflict with any other thread that uses these other
|
||||
libraries.
|
||||
|
||||
See the description in libcurl(3) of global environment requirements for
|
||||
details of how to use this function.
|
||||
|
|
|
|||
|
|
@ -50,10 +50,10 @@ the `threadsafe` feature set (added in 7.84.0).
|
|||
|
||||
If this is not thread-safe (the bit mentioned above is not set), you must not
|
||||
call this function when any other thread in the program (i.e. a thread sharing
|
||||
the same memory) is running. This does not just mean no other thread that is
|
||||
using libcurl. Because curl_global_init(3) calls functions of other libraries
|
||||
that are similarly thread-unsafe, it could conflict with any other thread that
|
||||
uses these other libraries.
|
||||
the same memory) is running. This does not only mean other threads that use
|
||||
libcurl. Because curl_global_init(3) calls functions of other libraries that
|
||||
are similarly thread-unsafe, it could conflict with any other thread that uses
|
||||
these other libraries.
|
||||
|
||||
If you are initializing libcurl from a Windows DLL you should not initialize
|
||||
it from *DllMain* or a static initializer because Windows holds the loader
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ curl_version_info(3) has the CURL_VERSION_THREADSAFE feature bit set
|
|||
|
||||
If this is not thread-safe, you must not call this function when any other
|
||||
thread in the program (i.e. a thread sharing the same memory) is running.
|
||||
This does not just mean no other thread that is using libcurl.
|
||||
This does not only mean no other thread that is using libcurl.
|
||||
|
||||
# Names
|
||||
|
||||
|
|
@ -72,7 +72,7 @@ Schannel, wolfSSL
|
|||
The name "OpenSSL" is used for all versions of OpenSSL and its associated
|
||||
forks/flavors in this function. OpenSSL, BoringSSL, LibreSSL, quictls and
|
||||
AmiSSL are all supported by libcurl, but in the eyes of curl_global_sslset(3)
|
||||
they are all just "OpenSSL". They all mostly provide the same API.
|
||||
they are all called "OpenSSL". They all mostly provide the same API.
|
||||
curl_version_info(3) can return more specific info about the exact OpenSSL
|
||||
flavor and version number in use.
|
||||
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ the CURL_VERSION_THREADSAFE feature bit set (most platforms).
|
|||
|
||||
If this is not thread-safe, you must not call this function when any other
|
||||
thread in the program (i.e. a thread sharing the same memory) is running. This
|
||||
does not just mean no other thread that is using libcurl. Because
|
||||
does not only mean no other thread that is using libcurl. Because
|
||||
curl_global_init(3) may call functions of other libraries that are similarly
|
||||
thread-unsafe, it could conflict with any other thread that uses these other
|
||||
libraries.
|
||||
|
|
|
|||
|
|
@ -159,14 +159,14 @@ An optional precision in the form of a period ('.') followed by an optional
|
|||
decimal digit string. Instead of a decimal digit string one may write "*" or
|
||||
"*m$" (for some decimal integer m) to specify that the precision is given in
|
||||
the next argument, or in the *m-th* argument, respectively, which must be of
|
||||
type int. If the precision is given as just '.', the precision is taken to be
|
||||
zero. A negative precision is taken as if the precision were omitted. This
|
||||
gives the minimum number of digits to appear for **d**, **i**, **o**,
|
||||
**u**, **x**, and **X** conversions, the number of digits to appear
|
||||
after the radix character for **a**, **A**, **e**, **E**, **f**, and
|
||||
**F** conversions, the maximum number of significant digits for **g** and
|
||||
**G** conversions, or the maximum number of characters to be printed from a
|
||||
string for **s** and **S** conversions.
|
||||
type int. If the precision is given as a single '.', the precision is taken to
|
||||
be zero. A negative precision is taken as if the precision were omitted. This
|
||||
gives the minimum number of digits to appear for **d**, **i**, **o**, **u**,
|
||||
**x**, and **X** conversions, the number of digits to appear after the radix
|
||||
character for **a**, **A**, **e**, **E**, **f**, and **F** conversions, the
|
||||
maximum number of significant digits for **g** and **G** conversions, or the
|
||||
maximum number of characters to be printed from a string for **s** and **S**
|
||||
conversions.
|
||||
|
||||
# Length modifier
|
||||
|
||||
|
|
|
|||
|
|
@ -41,11 +41,6 @@ libcurl only keeps one single pointer associated with a socket, so calling
|
|||
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 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.
|
||||
|
||||
# %PROTOCOLS%
|
||||
|
|
|
|||
|
|
@ -27,10 +27,10 @@ CURLMsg *curl_multi_info_read(CURLM *multi_handle, int *msgs_in_queue);
|
|||
|
||||
# DESCRIPTION
|
||||
|
||||
Ask the multi handle if there are any messages from the individual
|
||||
transfers. Messages may include information such as an error code from the
|
||||
transfer or just the fact that a transfer is completed. More details on these
|
||||
should be written down as well.
|
||||
Ask the multi handle if there are any messages from the individual transfers.
|
||||
Messages may include information such as an error code from the transfer or
|
||||
the fact that a transfer is completed. More details on these should be written
|
||||
down as well.
|
||||
|
||||
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
|
||||
|
|
@ -63,7 +63,7 @@ struct CURLMsg {
|
|||
~~~
|
||||
When **msg** is *CURLMSG_DONE*, the message identifies a transfer that
|
||||
is done, and then **result** contains the return code for the easy handle
|
||||
that just completed.
|
||||
that completed.
|
||||
|
||||
At this point, there are no other **msg** types defined.
|
||||
|
||||
|
|
|
|||
|
|
@ -40,8 +40,8 @@ or a timeout has elapsed, the application should call this function to
|
|||
read/write whatever there is to read or write right now etc.
|
||||
curl_multi_perform(3) 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 stores
|
||||
the number of handles that still transfer data in the second argument's
|
||||
reading or that data can be written, it can be called as a precaution. It
|
||||
stores the number of handles that still transfer data in the second argument's
|
||||
integer-pointer.
|
||||
|
||||
If the amount of *running_handles* is changed from the previous call (or
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ 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
|
||||
It is fine to remove a handle at any time during a transfer, but not from
|
||||
within any libcurl callback function.
|
||||
|
||||
Removing an easy handle from the multi handle before the corresponding
|
||||
|
|
|
|||
|
|
@ -38,8 +38,8 @@ still running easy handles within the multi handle. When this number reaches
|
|||
zero, all transfers are complete/done.
|
||||
|
||||
Force libcurl to (re-)check all its internal sockets and transfers instead of
|
||||
just a single one by calling curl_multi_socket_all(3). Note that there should
|
||||
not be any reason to use this function.
|
||||
a single one by calling curl_multi_socket_all(3). Note that there should not
|
||||
be any reason to use this function.
|
||||
|
||||
# %PROTOCOLS%
|
||||
|
||||
|
|
|
|||
|
|
@ -45,9 +45,9 @@ An application that uses the *multi_socket* API should not use this function.
|
|||
It should instead use the CURLMOPT_TIMERFUNCTION(3) option for proper and
|
||||
desired behavior.
|
||||
|
||||
Note: if libcurl returns a -1 timeout here, it just means that libcurl
|
||||
currently has no stored timeout value. You must not wait too long (more than a
|
||||
few seconds perhaps) before you call curl_multi_perform(3) again.
|
||||
Note: if libcurl returns a -1 timeout here, it means that libcurl currently
|
||||
has no stored timeout value. You must not wait too long (more than a few
|
||||
seconds perhaps) before you call curl_multi_perform(3) again.
|
||||
|
||||
# %PROTOCOLS%
|
||||
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ If the *fd_count* argument is not a null pointer, it points to a variable
|
|||
that on return specifies the number of descriptors used by the multi_handle to
|
||||
be checked for being ready to read or write.
|
||||
|
||||
The client code can pass *size* equal to zero just to get the number of the
|
||||
The client code can pass *size* equal to zero to get the number of the
|
||||
descriptors and allocate appropriate storage for them to be used in a
|
||||
subsequent function call. In this case, *fd_count* receives a number greater
|
||||
than or equal to the number of descriptors.
|
||||
|
|
|
|||
|
|
@ -187,8 +187,8 @@ If the hostname is a numeric IPv6 address, this field might also be set.
|
|||
|
||||
## CURLUPART_PORT
|
||||
|
||||
A port cannot be URL decoded on get. This number is returned in a string just
|
||||
like all other parts. That string is guaranteed to hold a valid port number in
|
||||
A port cannot be URL decoded on get. This number is returned in a string like
|
||||
all other parts. That string is guaranteed to hold a valid port number in
|
||||
ASCII using base 10.
|
||||
|
||||
## CURLUPART_PATH
|
||||
|
|
|
|||
|
|
@ -116,7 +116,7 @@ new the libcurl you are using is. You are however guaranteed to get a struct
|
|||
that you have a matching struct for in the header, as you tell libcurl your
|
||||
"age" with the input argument.
|
||||
|
||||
*version* is just an ASCII string for the libcurl version.
|
||||
*version* is an ASCII string for the libcurl version.
|
||||
|
||||
*version_num* is a 24-bit number created like this: \<8 bits major number\> |
|
||||
\<8 bits minor number\> | \<8 bits patch number\>. Version 7.9.8 is therefore
|
||||
|
|
|
|||
|
|
@ -29,11 +29,10 @@ Why they occur and possibly what you can do to fix the problem are also included
|
|||
# CURLcode
|
||||
|
||||
Almost all "easy" interface functions return a CURLcode error code. No matter
|
||||
what, using the curl_easy_setopt(3) option CURLOPT_ERRORBUFFER(3)
|
||||
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.
|
||||
curl_easy_strerror(3) can be called to get an error string from a given
|
||||
CURLcode number.
|
||||
what, using the curl_easy_setopt(3) option CURLOPT_ERRORBUFFER(3) 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 the error code alone. curl_easy_strerror(3)
|
||||
can be called to get an error string from a given CURLcode number.
|
||||
|
||||
CURLcode is one of the following:
|
||||
|
||||
|
|
@ -45,8 +44,7 @@ All fine. Proceed as usual.
|
|||
|
||||
The URL you passed to libcurl used a protocol that this libcurl does not
|
||||
support. The support might be a compile-time option that you did not use, it
|
||||
can be a misspelled protocol string or just a protocol libcurl has no code
|
||||
for.
|
||||
can be a misspelled protocol string or a protocol libcurl has no code for.
|
||||
|
||||
## CURLE_FAILED_INIT (2)
|
||||
|
||||
|
|
|
|||
|
|
@ -130,13 +130,12 @@ using large numbers of simultaneous connections.
|
|||
curl_multi_socket_action(3) is then used instead of
|
||||
curl_multi_perform(3).
|
||||
|
||||
When using this API, you add easy handles to the multi handle just as with the
|
||||
When using this API, you add easy handles to the multi handle like with the
|
||||
normal multi interface. Then you also set two callbacks with the
|
||||
CURLMOPT_SOCKETFUNCTION(3) and CURLMOPT_TIMERFUNCTION(3) options
|
||||
to curl_multi_setopt(3). They are two callback functions that libcurl
|
||||
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.
|
||||
CURLMOPT_SOCKETFUNCTION(3) and CURLMOPT_TIMERFUNCTION(3) options to
|
||||
curl_multi_setopt(3). They are two callback functions that libcurl 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)
|
||||
|
|
|
|||
|
|
@ -64,8 +64,8 @@ plain text anywhere.
|
|||
|
||||
Many of the protocols libcurl supports send name and password unencrypted as
|
||||
clear text (HTTP Basic authentication, FTP, TELNET etc). It is easy for anyone
|
||||
on your network or a network nearby yours to just fire up a network analyzer
|
||||
tool and eavesdrop on your passwords. Do not let the fact that HTTP Basic uses
|
||||
on your network or a network nearby yours to fire up a network analyzer tool
|
||||
and eavesdrop on your passwords. Do not let the fact that HTTP Basic uses
|
||||
base64 encoded passwords fool you. They may not look readable at a first
|
||||
glance, but they are easily "deciphered" by anyone within seconds.
|
||||
|
||||
|
|
@ -118,11 +118,11 @@ transfers require a new connection with validation performed again.
|
|||
|
||||
# Redirects
|
||||
|
||||
The CURLOPT_FOLLOWLOCATION(3) option automatically follows HTTP
|
||||
redirects sent by a remote server. These redirects can refer to any kind of
|
||||
URL, not just HTTP. libcurl restricts the protocols allowed to be used in
|
||||
redirects for security reasons: only HTTP, HTTPS, FTP and FTPS are
|
||||
enabled by default. Applications may opt to restrict that set further.
|
||||
The CURLOPT_FOLLOWLOCATION(3) option automatically follows HTTP redirects sent
|
||||
by a remote server. These redirects can refer to any kind of URL, not only
|
||||
HTTP. libcurl restricts the protocols allowed to be used in redirects for
|
||||
security reasons: only HTTP, HTTPS, FTP and FTPS are enabled by default.
|
||||
Applications may opt to restrict that set further.
|
||||
|
||||
A redirect to a file: URL would cause the libcurl to read (or write) arbitrary
|
||||
files from the local file system. If the application returns the data back to
|
||||
|
|
@ -131,8 +131,8 @@ leverage this to read otherwise forbidden data (e.g.
|
|||
**file://localhost/etc/passwd**).
|
||||
|
||||
If authentication credentials are stored in the ~/.netrc file, or Kerberos is
|
||||
in use, any other URL type (not just file:) that requires authentication is
|
||||
also at risk. A redirect such as **ftp://some-internal-server/private-file** would
|
||||
in use, any other URL type (except file:) that requires authentication is also
|
||||
at risk. A redirect such as **ftp://some-internal-server/private-file** would
|
||||
then return data even when the server is password protected.
|
||||
|
||||
In the same way, if an unencrypted SSH private key has been configured for the
|
||||
|
|
@ -178,7 +178,7 @@ of a server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Applications can
|
|||
mitigate against this by setting a CURLOPT_OPENSOCKETFUNCTION(3) or
|
||||
CURLOPT_PREREQFUNCTION(3) and checking the address before a connection.
|
||||
|
||||
All the malicious scenarios regarding redirected URLs apply just as well to
|
||||
All the malicious scenarios regarding redirected URLs apply equally to
|
||||
non-redirected URLs, if the user is allowed to specify an arbitrary URL that
|
||||
could point to a private resource. For example, a web app providing a
|
||||
translation service might happily translate **file://localhost/etc/passwd**
|
||||
|
|
@ -211,15 +211,15 @@ or a mix of decimal, octal or hexadecimal encoding.
|
|||
|
||||
# IPv6 Addresses
|
||||
|
||||
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 **::1**,
|
||||
**::**, **0:00::0:1**, **::127.0.0.1** and **::ffff:7f00:1** supplied
|
||||
somehow by an attacker would all bypass a naive filter and could allow access
|
||||
to undesired local resources. IPv6 also has special address blocks like
|
||||
link-local and site-local that generally should not be accessed by a
|
||||
server-side libcurl-using application. A poorly configured firewall installed
|
||||
in a data center, organization or server may also be configured to limit IPv4
|
||||
libcurl handles IPv6 addresses transparently and as easily as IPv4 addresses.
|
||||
That means that a sanitizing function that filters out addresses like
|
||||
127.0.0.1 is not sufficient - the equivalent IPv6 addresses **::1**, **::**,
|
||||
**0:00::0:1**, **::127.0.0.1** and **::ffff:7f00:1** supplied somehow by an
|
||||
attacker would all bypass a naive filter and could allow access to undesired
|
||||
local resources. IPv6 also has special address blocks like link-local and
|
||||
site-local that generally should not be accessed by a server-side
|
||||
libcurl-using application. A poorly configured firewall installed in a data
|
||||
center, organization or server may also be configured to limit IPv4
|
||||
connections but leave IPv6 connections wide open. In some cases, setting
|
||||
CURLOPT_IPRESOLVE(3) to CURL_IPRESOLVE_V4 can be used to limit resolved
|
||||
addresses to IPv4 only and bypass these issues.
|
||||
|
|
@ -294,7 +294,7 @@ system.
|
|||
|
||||
The conclusion we have come to is that this is a weakness or feature in the
|
||||
Windows operating system itself, that we as an application cannot safely
|
||||
protect users against. It would just be a whack-a-mole race we do not want to
|
||||
protect users against. It would make a whack-a-mole race we do not want to
|
||||
participate in. There are too many ways to do it and there is no knob we can
|
||||
use to turn off the practice.
|
||||
|
||||
|
|
@ -333,8 +333,8 @@ libcurl programs can use CURLOPT_PROTOCOLS_STR(3) to limit what URL schemes it a
|
|||
|
||||
## consider not allowing the user to set the full URL
|
||||
|
||||
Maybe just let the user provide data for parts of it? Or maybe filter input to
|
||||
only allow specific choices? Remember that the naive approach of appending a
|
||||
Maybe let the user provide data for parts of it? Or maybe filter input to only
|
||||
allow specific choices? Remember that the naive approach of appending a
|
||||
user-specified string to a base URL could still allow unexpected results
|
||||
through use of characters like ../ or ? or Unicode characters or hiding
|
||||
characters using various escaping means.
|
||||
|
|
@ -396,10 +396,10 @@ using a SOCKS or HTTP proxy in between curl and the target server.
|
|||
# Denial of Service
|
||||
|
||||
A malicious server could cause libcurl to effectively hang by sending data
|
||||
slowly, or even no data at all but just keeping the TCP connection open. This
|
||||
could effectively result in a denial-of-service attack. The
|
||||
CURLOPT_TIMEOUT(3) and/or CURLOPT_LOW_SPEED_LIMIT(3) options can
|
||||
be used to mitigate against this.
|
||||
slowly, or even no data at all but keeping the TCP connection open. This could
|
||||
effectively result in a denial-of-service attack. The CURLOPT_TIMEOUT(3)
|
||||
and/or CURLOPT_LOW_SPEED_LIMIT(3) options can be used to mitigate against
|
||||
this.
|
||||
|
||||
A malicious server could cause libcurl to download an infinite amount of data,
|
||||
potentially causing system resources to be exhausted resulting in a system or
|
||||
|
|
@ -455,8 +455,8 @@ passwords, things like URLs, cookies or even filenames could also hold
|
|||
sensitive data.
|
||||
|
||||
To avoid this problem, you must of course use your common sense. Often, you
|
||||
can just edit out the sensitive data or just search/replace your true
|
||||
information with faked data.
|
||||
can edit out the sensitive data or search/replace your true information with
|
||||
faked data.
|
||||
|
||||
# setuid applications using libcurl
|
||||
|
||||
|
|
@ -515,6 +515,6 @@ cookies.
|
|||
|
||||
# Report Security Problems
|
||||
|
||||
Should you detect or just suspect a security problem in libcurl or curl,
|
||||
contact the project curl security team immediately. See
|
||||
Should you detect or suspect a security problem in libcurl or curl, contact
|
||||
the project curl security team immediately. See
|
||||
https://curl.se/dev/secprocess.html for details.
|
||||
|
|
|
|||
|
|
@ -92,9 +92,9 @@ The people behind libcurl have put a considerable effort to make libcurl work
|
|||
on a large amount of different operating systems and environments.
|
||||
|
||||
You program libcurl the same way on all platforms that libcurl runs on. There
|
||||
are only a few minor details that differ. If you just make sure to write your
|
||||
code portable enough, you can create a portable program. libcurl should not
|
||||
stop you from that.
|
||||
are only a few minor details that differ. If you make sure to write your code
|
||||
portable enough, you can create a portable program. libcurl should not stop
|
||||
you from that.
|
||||
|
||||
# Global Preparation
|
||||
|
||||
|
|
@ -171,7 +171,7 @@ Get an easy handle with
|
|||
handle = curl_easy_init();
|
||||
~~~
|
||||
It returns an easy handle. Using that you proceed to the next step: setting
|
||||
up your preferred actions. A handle is just a logic entity for the upcoming
|
||||
up your preferred actions. A handle is a logic entity for the upcoming
|
||||
transfer or series of transfers.
|
||||
|
||||
You set properties and options for this handle using
|
||||
|
|
@ -311,8 +311,8 @@ 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 reuse one existing
|
||||
one. Then you set the URL to operate on just like before. This is the remote
|
||||
URL, that we now upload.
|
||||
one. Then you set the URL to operate on like before. This is the remote 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
|
||||
|
|
@ -620,15 +620,17 @@ handle:
|
|||
~~~
|
||||
|
||||
Since all options on an easy handle are "sticky", they remain the same until
|
||||
changed even if you do call curl_easy_perform(3), you may need to tell
|
||||
curl to go back to a plain GET request if you intend to do one as your next
|
||||
request. You force an easy handle to go back to GET by using the
|
||||
CURLOPT_HTTPGET(3) option:
|
||||
changed even if you do call curl_easy_perform(3), you may need to tell curl to
|
||||
go back to a plain GET request if you intend to do one as your next request.
|
||||
You force an easy handle to go back to GET by using the CURLOPT_HTTPGET(3)
|
||||
option:
|
||||
|
||||
~~~c
|
||||
curl_easy_setopt(handle, CURLOPT_HTTPGET, 1L);
|
||||
~~~
|
||||
Just setting CURLOPT_POSTFIELDS(3) to "" or NULL does *not* stop libcurl
|
||||
from doing a POST. It just makes it POST without any data to send!
|
||||
|
||||
Setting CURLOPT_POSTFIELDS(3) to "" or NULL does *not* stop libcurl from doing
|
||||
a POST. It makes it POST without any data to send!
|
||||
|
||||
# Converting from deprecated form API to MIME API
|
||||
|
||||
|
|
@ -956,10 +958,10 @@ Mozilla JavaScript engine in the past.
|
|||
Re-cycling the same easy handle several times when doing multiple requests is
|
||||
the way to go.
|
||||
|
||||
After each single curl_easy_perform(3) 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.
|
||||
After each single curl_easy_perform(3) operation, libcurl keeps the connection
|
||||
alive and open. A subsequent request using the same easy handle to the same
|
||||
host might be able to reuse 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, benefit from libcurl's session ID cache that drastically reduces
|
||||
|
|
@ -978,9 +980,9 @@ may also be added in the future.
|
|||
|
||||
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 CURLOPT_MAXCONNECTS(3) 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.
|
||||
the CURLOPT_MAXCONNECTS(3) option. Default is 5. There is rarely any point in
|
||||
changing this value, and if you think of changing this it is often a reason to
|
||||
think again.
|
||||
|
||||
To force your upcoming request to not use an already existing connection, you
|
||||
can do that by setting CURLOPT_FRESH_CONNECT(3) to 1. In a similar
|
||||
|
|
@ -1025,9 +1027,9 @@ libcurl is your friend here too.
|
|||
|
||||
## CURLOPT_CUSTOMREQUEST
|
||||
|
||||
If just changing the actual HTTP request keyword is what you want, like when
|
||||
GET, HEAD or POST is not good enough for you, CURLOPT_CUSTOMREQUEST(3)
|
||||
is there for you. It is simple to use:
|
||||
If changing the actual HTTP request keyword is what you want, like when GET,
|
||||
HEAD or POST is not good enough for you, CURLOPT_CUSTOMREQUEST(3) is there for
|
||||
you. It is simple to use:
|
||||
|
||||
~~~c
|
||||
curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST");
|
||||
|
|
@ -1152,8 +1154,8 @@ content transfer is performed.
|
|||
## FTP Custom CURLOPT_CUSTOMREQUEST
|
||||
|
||||
If you do want to list the contents of an FTP directory using your own defined
|
||||
FTP command, CURLOPT_CUSTOMREQUEST(3) does just that. "NLST" is the default
|
||||
one for listing directories but you are free to pass in your idea of a good
|
||||
FTP command, CURLOPT_CUSTOMREQUEST(3) does that. "NLST" is the default one for
|
||||
listing directories but you are free to pass in your idea of a good
|
||||
alternative.
|
||||
|
||||
# Cookies Without Chocolate Chips
|
||||
|
|
@ -1170,8 +1172,8 @@ update them. Server use cookies to "track" users and to keep "sessions".
|
|||
Cookies are sent from server to clients with the header Set-Cookie: and
|
||||
they are sent from clients to servers with the Cookie: header.
|
||||
|
||||
To just send whatever cookie you want to a server, you can use
|
||||
CURLOPT_COOKIE(3) to set a cookie string like this:
|
||||
To send whatever cookie you want to a server, you can use CURLOPT_COOKIE(3) to
|
||||
set a cookie string like this:
|
||||
|
||||
~~~c
|
||||
curl_easy_setopt(handle, CURLOPT_COOKIE, "name1=var1; name2=var2;");
|
||||
|
|
@ -1186,16 +1188,15 @@ when you make a request, you tell libcurl to read the previous headers to
|
|||
figure out which cookies to use. Set the header file to read cookies from with
|
||||
CURLOPT_COOKIEFILE(3).
|
||||
|
||||
The CURLOPT_COOKIEFILE(3) option also automatically enables the cookie
|
||||
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
|
||||
The CURLOPT_COOKIEFILE(3) option also automatically enables the cookie parser
|
||||
in libcurl. Until the cookie parser is enabled, libcurl does not parse or
|
||||
understand incoming cookies and they are instead 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 CURLOPT_COOKIEFILE(3)
|
||||
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.
|
||||
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 CURLOPT_COOKIEFILE(3) does not have to
|
||||
exist to enable the parser, so a common way to 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
|
||||
|
|
@ -1370,9 +1371,9 @@ multiple transfers at the same time by adding up multiple easy handles into
|
|||
a "multi stack".
|
||||
|
||||
You create the easy handles you want, one for each concurrent transfer, and
|
||||
you set all the options just like you learned above, and then you create a
|
||||
multi handle with curl_multi_init(3) and add all those easy handles to
|
||||
that multi handle with curl_multi_add_handle(3).
|
||||
you set all the options like you learned above, and then you create a multi
|
||||
handle with curl_multi_init(3) and add all those easy handles to that multi
|
||||
handle with curl_multi_add_handle(3).
|
||||
|
||||
When you have added the handles you have for the moment (you can still add new
|
||||
ones at any time), you start the transfers by calling
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ When done with it, clean it up with curl_url_cleanup(3)
|
|||
|
||||
# DUPLICATE
|
||||
|
||||
When you need a copy of a handle, just duplicate it with curl_url_dup(3):
|
||||
When you need a copy of a handle, duplicate it with curl_url_dup(3):
|
||||
~~~c
|
||||
CURLU *nh = curl_url_dup(h);
|
||||
~~~
|
||||
|
|
|
|||
|
|
@ -219,7 +219,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG],
|
|||
|
||||
if test -z "$_libcurl_protocols"; then
|
||||
|
||||
# We do not have --protocols, so just assume that all
|
||||
# We do not have --protocols; assume that all
|
||||
# protocols are available
|
||||
_libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP"
|
||||
|
||||
|
|
|
|||
|
|
@ -192,8 +192,8 @@ libcurl at all. Call curl_global_cleanup(3) immediately before the
|
|||
program exits, when the program is again only one thread and after its last
|
||||
use of libcurl.
|
||||
|
||||
It is not actually required that the functions be called at the beginning
|
||||
and end of the program -- that is just usually the easiest way to do it.
|
||||
It is not actually required that the functions be called at the beginning and
|
||||
end of the program -- that is usually the easiest way to do it.
|
||||
|
||||
You can call both of these multiple times, as long as all calls meet
|
||||
these requirements and the number of calls to each is the same.
|
||||
|
|
@ -205,13 +205,13 @@ other parts of the program -- it does not know whether they use libcurl or
|
|||
not. Its code does not necessarily run at the start and end of the whole
|
||||
program.
|
||||
|
||||
A module like this must have global constant functions of its own, just like
|
||||
curl_global_init(3) and curl_global_cleanup(3). 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 separately call the libcurl functions, and that is OK because only the
|
||||
first curl_global_init(3) and the last curl_global_cleanup(3) in a
|
||||
program change anything. (libcurl uses a reference count in static memory).
|
||||
A module like this must have global constant functions of its own, like
|
||||
curl_global_init(3) and curl_global_cleanup(3). 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 separately
|
||||
call the libcurl functions, and that is OK because only the first
|
||||
curl_global_init(3) and the last curl_global_cleanup(3) 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
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRETRANSFER_TIME,
|
|||
# DESCRIPTION
|
||||
|
||||
Pass a pointer to a double to receive the time, in seconds, it took from the
|
||||
start until the file transfer is just about to begin.
|
||||
start until the file transfer is about to begin.
|
||||
|
||||
This time-stamp includes all pre-transfer commands and negotiations that are
|
||||
specific to the particular protocol(s) involved. It includes the sending of
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRETRANSFER_TIME_T,
|
|||
# DESCRIPTION
|
||||
|
||||
Pass a pointer to a curl_off_t to receive the time, in microseconds, it took
|
||||
from the start until the file transfer is just about to begin.
|
||||
from the start until the file transfer is about to begin.
|
||||
|
||||
This time-stamp includes all pre-transfer commands and negotiations that are
|
||||
specific to the particular protocol(s) involved. It includes the sending of
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ The *backend* struct member is one of these defines: CURLSSLBACKEND_NONE (when
|
|||
built without TLS support), CURLSSLBACKEND_WOLFSSL,
|
||||
CURLSSLBACKEND_SECURETRANSPORT, CURLSSLBACKEND_GNUTLS, CURLSSLBACKEND_MBEDTLS,
|
||||
CURLSSLBACKEND_NSS, CURLSSLBACKEND_OPENSSL or CURLSSLBACKEND_SCHANNEL. (Note
|
||||
that the OpenSSL forks are all reported as just OpenSSL here.)
|
||||
that the OpenSSL forks are all reported as OpenSSL here.)
|
||||
|
||||
The *internals* struct member points to a TLS library specific pointer for
|
||||
the active ("in use") SSL connection, with the following underlying types:
|
||||
|
|
|
|||
|
|
@ -63,11 +63,11 @@ usual.
|
|||
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: curl_pushheader_byname(3) and
|
||||
curl_pushheader_bynum(3). The normal response headers are passed to the
|
||||
header callback for pushed streams just as for normal streams.
|
||||
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: curl_pushheader_byname(3) and
|
||||
curl_pushheader_bynum(3). The normal response headers are passed to the header
|
||||
callback for pushed streams like for normal streams.
|
||||
|
||||
The header fields can also be accessed with curl_easy_header(3),
|
||||
introduced in later libcurl versions.
|
||||
|
|
|
|||
|
|
@ -52,8 +52,8 @@ Set CURLOPT_ACCEPT_ENCODING(3) to NULL to explicitly disable it, which makes
|
|||
libcurl not send an Accept-Encoding: header and not decompress received
|
||||
contents automatically.
|
||||
|
||||
You can also opt to just include the Accept-Encoding: header in your request
|
||||
with CURLOPT_HTTPHEADER(3) but then there is no automatic decompressing when
|
||||
You can also opt to include the `Accept-Encoding:` header in your request with
|
||||
CURLOPT_HTTPHEADER(3) but then there is no automatic decompressing when
|
||||
receiving data.
|
||||
|
||||
Setting this option is a request, not an order; the server may or may not do
|
||||
|
|
|
|||
|
|
@ -62,8 +62,8 @@ Example with "Test:Try", when curl uses the algorithm, it generates
|
|||
for "date", **"test4_request"** for "request type",
|
||||
**"SignedHeaders=content-type;host;x-try-date"** for "signed headers"
|
||||
|
||||
If you use just "test", instead of "test:try", test is used for every
|
||||
generated string.
|
||||
If you use "test", instead of "test:try", test is used for every generated
|
||||
string.
|
||||
|
||||
Setting CURLOPT_HTTPAUTH(3) with the CURLAUTH_AWS_SIGV4 bit set is the same as
|
||||
setting this option with a **"aws:amz"** parameter.
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ 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
|
||||
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
|
||||
This is treated as a request, not an order. You cannot be guaranteed to
|
||||
actually get the given size.
|
||||
|
||||
This buffer size is by default *CURL_MAX_WRITE_SIZE* (16kB). The maximum
|
||||
|
|
@ -45,10 +45,10 @@ transfer as that may lead to unintended consequences.
|
|||
|
||||
The maximum size was 512kB until 7.88.0.
|
||||
|
||||
Starting in libcurl 8.7.0, there is just a single transfer buffer allocated
|
||||
per multi handle. This buffer is used by all easy handles added to a multi
|
||||
handle no matter how many parallel transfers there are. The buffer remains
|
||||
allocated as long as there are active transfers.
|
||||
Starting in libcurl 8.7.0, there is a single transfer buffer allocated per
|
||||
multi handle. This buffer is used by all easy handles added to a multi handle
|
||||
no matter how many parallel transfers there are. The buffer remains allocated
|
||||
as long as there are active transfers.
|
||||
|
||||
# DEFAULT
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEFILE, char *filename);
|
|||
|
||||
Pass a pointer to a null-terminated string as parameter. It should point to
|
||||
the filename of your file holding cookie data to read. The cookie data can be
|
||||
in either the old Netscape / Mozilla cookie data format or just regular HTTP
|
||||
in either the old Netscape / Mozilla cookie data format or regular HTTP
|
||||
headers (Set-Cookie style) dumped to a file.
|
||||
|
||||
It also enables the cookie engine, making libcurl parse and send cookies on
|
||||
|
|
@ -37,7 +37,7 @@ subsequent requests with this handle.
|
|||
|
||||
By passing the empty string ("") to this option, you enable the cookie engine
|
||||
without reading any initial cookies. If you tell libcurl the filename is "-"
|
||||
(just a single minus sign), libcurl instead reads from stdin.
|
||||
(a single minus sign), libcurl instead reads from stdin.
|
||||
|
||||
This option only **reads** cookies. To make libcurl write cookies to file,
|
||||
see CURLOPT_COOKIEJAR(3).
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST,
|
|||
|
||||
Pass a char pointer to a *cookie* string.
|
||||
|
||||
Such a cookie can be either a single line in Netscape / Mozilla format or just
|
||||
Such a cookie can be either a single line in Netscape / Mozilla format or
|
||||
regular HTTP-style header (`Set-Cookie:`) format. This option also enables the
|
||||
cookie engine. This adds that single cookie to the internal cookie store.
|
||||
|
||||
|
|
|
|||
|
|
@ -64,9 +64,9 @@ is done independently of the CURLOPT_DOH_SSL_VERIFYPEER(3) option.
|
|||
|
||||
**WARNING:** disabling verification of the certificate allows bad guys to
|
||||
man-in-the-middle the communication without you knowing it. Disabling
|
||||
verification makes the communication insecure. Just having encryption on a
|
||||
transfer is not enough as you cannot be sure that you are communicating with
|
||||
the correct end-point.
|
||||
verification makes the communication insecure. Having encryption on a transfer
|
||||
is not enough as you cannot be sure that you are communicating with the
|
||||
correct end-point.
|
||||
|
||||
# DEFAULT
|
||||
|
||||
|
|
|
|||
|
|
@ -31,9 +31,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ERRORBUFFER, char *buf);
|
|||
# DESCRIPTION
|
||||
|
||||
Pass a char pointer 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 curl_easy_perform(3) and related functions. The buffer must
|
||||
be at least **CURL_ERROR_SIZE** bytes big.
|
||||
error messages on failures or problems. This may be more helpful than the
|
||||
single return code from curl_easy_perform(3) and related functions. The buffer
|
||||
must be at least **CURL_ERROR_SIZE** bytes big.
|
||||
|
||||
You must keep the associated buffer available until libcurl no longer needs
|
||||
it. Failing to do so might cause odd behavior or even crashes. libcurl might
|
||||
|
|
|
|||
|
|
@ -59,9 +59,9 @@ request the same way as the previous one; including the request body if one
|
|||
was provided.
|
||||
|
||||
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 curl_easy_getinfo(3)'s CURLINFO_REDIRECT_URL(3)
|
||||
option instead of using CURLOPT_FOLLOWLOCATION(3).
|
||||
or lacking features, it is easy to instead implement your own redirect follow
|
||||
logic with the use of curl_easy_getinfo(3)'s CURLINFO_REDIRECT_URL(3) option
|
||||
instead of using CURLOPT_FOLLOWLOCATION(3).
|
||||
|
||||
By default, libcurl only sends `Authorization:` or explicitly set `Cookie:`
|
||||
headers to the initial host given in the original URL, to avoid leaking
|
||||
|
|
@ -77,9 +77,9 @@ Pick one of the following modes:
|
|||
|
||||
## CURLFOLLOW_ALL (1)
|
||||
|
||||
Before 8.13.0 this bit had no name and 1L was just the value to enable this
|
||||
option. This makes a set custom method be used in all HTTP requests, even
|
||||
after redirects.
|
||||
Before 8.13.0 this bit had no name and 1L was the value to enable this option.
|
||||
This makes a set custom method be used in all HTTP requests, even after
|
||||
redirects.
|
||||
|
||||
## CURLFOLLOW_OBEYCODE (2)
|
||||
|
||||
|
|
|
|||
|
|
@ -33,9 +33,9 @@ IP address to use for the FTP PORT instruction.
|
|||
|
||||
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 hostname, 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.
|
||||
network interface name (under Unix) or 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
|
||||
|
|
|
|||
|
|
@ -67,11 +67,11 @@ CURLOPT_WRITEFUNCTION(3), or if it is not specified or NULL - the
|
|||
default, stream-writing function.
|
||||
|
||||
It is 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 need to collect headers in the callback yourself and use HTTP
|
||||
status lines, for example, to delimit response boundaries.
|
||||
responses received after initiating a request and not 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 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.
|
||||
|
|
@ -95,7 +95,7 @@ curl_easy_header(3).
|
|||
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 are passed to the header callback as separate ones,
|
||||
although strictly they are just continuations of the previous lines.
|
||||
although strictly they are continuations of the previous lines.
|
||||
|
||||
# DEFAULT
|
||||
|
||||
|
|
|
|||
|
|
@ -33,8 +33,8 @@ difference between using a proxy and to tunnel through it.
|
|||
|
||||
Tunneling means that an HTTP CONNECT request is sent to the proxy, asking it
|
||||
to connect to a remote host on a specific port number and then the traffic is
|
||||
just passed through the proxy. Proxies tend to white-list specific port numbers
|
||||
it allows CONNECT requests to and often only port 80 and 443 are allowed.
|
||||
passed through the proxy. Proxies tend to white-list specific port numbers it
|
||||
allows CONNECT requests to and often only port 80 and 443 are allowed.
|
||||
|
||||
To suppress proxy CONNECT response headers from user callbacks use
|
||||
CURLOPT_SUPPRESS_CONNECT_HEADERS(3).
|
||||
|
|
|
|||
|
|
@ -31,9 +31,9 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_VERSION, long version);
|
|||
Pass *version* 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 still prioritizes to
|
||||
reuse existing connections so it might then reuse a connection using an HTTP
|
||||
version you have not asked for.
|
||||
Note that the HTTP version is a request. libcurl still prioritizes to reuse
|
||||
existing connections so it might then reuse a connection using an HTTP version
|
||||
you have not asked for.
|
||||
|
||||
## CURL_HTTP_VERSION_NONE
|
||||
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOBODY, long opt);
|
|||
|
||||
A long parameter set to 1 tells libcurl to not include the body-part in the
|
||||
output when doing what would otherwise be a download. For HTTP(S), this makes
|
||||
libcurl do a HEAD request. For most other protocols it means just not asking
|
||||
to transfer the body data.
|
||||
libcurl do a HEAD request. For most other protocols it means not asking to
|
||||
transfer the body data.
|
||||
|
||||
For HTTP operations when CURLOPT_NOBODY(3) has been set, disabling this
|
||||
option (with 0) makes it a GET again - only if the method is still set to be
|
||||
|
|
|
|||
|
|
@ -93,7 +93,7 @@ server's certificate.
|
|||
# Windows-specific:
|
||||
# - Use NUL instead of /dev/null.
|
||||
# - OpenSSL may wait for input instead of disconnecting. Hit enter.
|
||||
# - If you do not have sed, then just copy the certificate into a file:
|
||||
# - If you do not have sed, then copy the certificate into a file:
|
||||
# Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
|
||||
#
|
||||
openssl s_client -servername www.example.com -connect www.example.com:443 \
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ This option sets *number* to be the remote port number to connect to,
|
|||
instead of the one specified in the URL or the default port for the used
|
||||
protocol.
|
||||
|
||||
Usually, you just let the URL decide which port to use but this allows the
|
||||
Usually, you let the URL decide which port to use but this allows the
|
||||
application to override that.
|
||||
|
||||
While this option accepts a 'long', a port number is an unsigned 16-bit number
|
||||
|
|
|
|||
|
|
@ -91,7 +91,7 @@ from the https proxy server's certificate.
|
|||
# Windows-specific:
|
||||
# - Use NUL instead of /dev/null.
|
||||
# - OpenSSL may wait for input instead of disconnecting. Hit enter.
|
||||
# - If you do not have sed, then just copy the certificate into a file:
|
||||
# - If you do not have sed, then copy the certificate into a file:
|
||||
# Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
|
||||
#
|
||||
openssl s_client -servername www.example.com -connect www.example.com:443 \
|
||||
|
|
|
|||
|
|
@ -59,9 +59,9 @@ done independently of the CURLOPT_PROXY_SSL_VERIFYPEER(3) option.
|
|||
|
||||
**WARNING:** disabling verification of the certificate allows bad guys to
|
||||
man-in-the-middle the communication without you knowing it. Disabling
|
||||
verification makes the communication insecure. Just having encryption on a
|
||||
transfer is not enough as you cannot be sure that you are communicating with
|
||||
the correct end-point.
|
||||
verification makes the communication insecure. Having encryption on a transfer
|
||||
is not enough as you cannot be sure that you are communicating with the
|
||||
correct end-point.
|
||||
|
||||
# DEFAULT
|
||||
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ use your provided ADDRESS.
|
|||
|
||||
The optional leading plus (`+`) specifies that the new entry should timeout.
|
||||
Entries added without the leading plus character never times out whereas
|
||||
entries added with `+HOST:...` times out just like ordinary DNS cache entries.
|
||||
entries added with `+HOST:...` times out like ordinary DNS cache entries.
|
||||
|
||||
If the DNS cache already has an entry for the given host+port pair, the new
|
||||
entry overrides the former one.
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ option is used. (The session ID is not needed for this method)
|
|||
When sent by a client, this method changes the description of the session. For
|
||||
example, if a client is using the server to record a meeting, the client can
|
||||
use Announce to inform the server of all the meta-information about the
|
||||
session. ANNOUNCE acts like an HTTP PUT or POST just like
|
||||
session. ANNOUNCE acts like an HTTP PUT or POST like
|
||||
*CURL_RTSPREQ_SET_PARAMETER*
|
||||
|
||||
## CURL_RTSPREQ_SETUP
|
||||
|
|
@ -82,7 +82,7 @@ different connections.
|
|||
|
||||
Retrieve a parameter from the server. By default, libcurl adds a
|
||||
*Content-Type: text/parameters* header on all non-empty requests unless a
|
||||
custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see
|
||||
custom one is set. GET_PARAMETER acts like an HTTP PUT or POST (see
|
||||
*CURL_RTSPREQ_SET_PARAMETER*). 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.
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PUBLIC_KEYFILE,
|
|||
|
||||
Pass a char pointer pointing to a *filename* for your public key. If not used,
|
||||
libcurl defaults to **$HOME/.ssh/id_dsa.pub** if the HOME environment variable
|
||||
is set, and just "id_dsa.pub" in the current directory if HOME is not set.
|
||||
is set, and "id_dsa.pub" in the current directory if HOME is not set.
|
||||
|
||||
If NULL (or an empty string) is passed to this option, libcurl passes no
|
||||
public key to the SSH library, which then rather derives it from the private
|
||||
|
|
|
|||
|
|
@ -40,13 +40,13 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION,
|
|||
Pass a pointer to your callback function, which should match the prototype
|
||||
shown above.
|
||||
|
||||
This callback function gets called by libcurl just before the initialization
|
||||
of an SSL connection after having processed all other SSL related options to
|
||||
give a last chance to an application to modify the behavior of the SSL
|
||||
initialization. The *ssl_ctx* parameter is a pointer to the SSL library's
|
||||
*SSL_CTX* for OpenSSL or wolfSSL, a pointer to *mbedtls_ssl_config* for
|
||||
mbedTLS. If an error is returned from the callback no attempt to establish a
|
||||
connection is made and the perform operation returns the callback's error
|
||||
This callback function gets called by libcurl immediately before the
|
||||
initialization of an SSL connection after having processed all other SSL
|
||||
related options to give a last chance to an application to modify the behavior
|
||||
of the SSL initialization. The *ssl_ctx* parameter is a pointer to the SSL
|
||||
library's *SSL_CTX* for OpenSSL or wolfSSL, a pointer to *mbedtls_ssl_config*
|
||||
for mbedTLS. If an error is returned from the callback no attempt to establish
|
||||
a connection is made and the perform operation returns the callback's error
|
||||
code. Set the *clientp* argument passed in to this callback with the
|
||||
CURLOPT_SSL_CTX_DATA(3) option.
|
||||
|
||||
|
|
|
|||
|
|
@ -55,9 +55,9 @@ the certificate is signed by a trusted Certificate Authority.
|
|||
|
||||
**WARNING:** disabling verification of the certificate allows bad guys to
|
||||
man-in-the-middle the communication without you knowing it. Disabling
|
||||
verification makes the communication insecure. Just having encryption on a
|
||||
transfer is not enough as you cannot be sure that you are communicating with
|
||||
the correct end-point.
|
||||
verification makes the communication insecure. Having encryption on a transfer
|
||||
is not enough as you cannot be sure that you are communicating with the
|
||||
correct end-point.
|
||||
|
||||
When libcurl uses secure protocols it trusts responses and allows for example
|
||||
HSTS and Alt-Svc information to be stored and used subsequently. Disabling
|
||||
|
|
|
|||
|
|
@ -60,9 +60,9 @@ done independently of the CURLOPT_SSL_VERIFYPEER(3) option.
|
|||
|
||||
**WARNING:** disabling verification of the certificate allows bad guys to
|
||||
man-in-the-middle the communication without you knowing it. Disabling
|
||||
verification makes the communication insecure. Just having encryption on a
|
||||
transfer is not enough as you cannot be sure that you are communicating with
|
||||
the correct end-point.
|
||||
verification makes the communication insecure. Having encryption on a transfer
|
||||
is not enough as you cannot be sure that you are communicating with the
|
||||
correct end-point.
|
||||
|
||||
When libcurl uses secure protocols it trusts responses and allows for example
|
||||
HSTS and Alt-Svc information to be stored and used subsequently. Disabling
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ the next layer in the stack to get sent off. In some setups and for some
|
|||
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
|
||||
This is treated as a request, not an order. You cannot be guaranteed to
|
||||
actually get the given size.
|
||||
|
||||
The upload buffer size is by default 64 kilobytes. The maximum buffer size
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue