generic-library/curl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

lib man pages: update easy setopt option references

Browse Source 
... by using the "\fIopt(3)\fP" syntax they will be linked properly when
the web version of the page is generated.
This commit is contained in:
Daniel Stenberg
2014-06-21 20:21:47 +02:00
parent 7d618c477f
commit c7e491f9c2
14 changed files with 262 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/libcurl/curl_easy_getinfo.3
View File

@@ -60,9 +60,9 @@ Pass a pointer to a long to receive the remote time of the retrieved document
-1, it can be because of many reasons (unknown, the server hides it or the -1, it can be because of many reasons (unknown, the server hides it or the
server doesn't support the command that tells document time etc) and the time server doesn't support the command that tells document time etc) and the time
of the document is unknown. Note that you must tell the server to collect this of the document is unknown. Note that you must tell the server to collect this
information before the transfer is made, by using the CURLOPT_FILETIME option information before the transfer is made, by using the
to \fIcurl_easy_setopt(3)\fP or you will unconditionally get a -1 back. (Added \fICURLOPT_FILETIME(3)\fP option to \fIcurl_easy_setopt(3)\fP or you will
in 7.5) unconditionally get a -1 back. (Added in 7.5)
.IP CURLINFO_TOTAL_TIME .IP CURLINFO_TOTAL_TIME
Pass a pointer to a double to receive the total time in seconds for the Pass a pointer to a double to receive the total time in seconds for the
previous transfer, including name resolving, TCP connect etc. previous transfer, including name resolving, TCP connect etc.
@@ -99,10 +99,10 @@ Pass a pointer to a long to receive the total number of redirections that were
actually followed. (Added in 7.9.7) actually followed. (Added in 7.9.7)
.IP CURLINFO_REDIRECT_URL .IP CURLINFO_REDIRECT_URL
Pass a pointer to a char pointer to receive the URL a redirect \fIwould\fP Pass a pointer to a char pointer to receive the URL a redirect \fIwould\fP
take you to if you would enable CURLOPT_FOLLOWLOCATION. This can come very take you to if you would enable \fICURLOPT_FOLLOWLOCATION(3)\fP. This can come
handy if you think using the built-in libcurl redirect logic isn't good enough very handy if you think using the built-in libcurl redirect logic isn't good
for you but you would still prefer to avoid implementing all the magic of enough for you but you would still prefer to avoid implementing all the magic
figuring out the new URL. (Added in 7.18.2) of figuring out the new URL. (Added in 7.18.2)
.IP CURLINFO_SIZE_UPLOAD .IP CURLINFO_SIZE_UPLOAD
Pass a pointer to a double to receive the total amount of bytes that were Pass a pointer to a double to receive the total amount of bytes that were
uploaded. uploaded.
@@ -127,8 +127,8 @@ requests. This is so far only for HTTP requests. Note that this may be more
than one request if FOLLOWLOCATION is true. than one request if FOLLOWLOCATION is true.
.IP CURLINFO_SSL_VERIFYRESULT .IP CURLINFO_SSL_VERIFYRESULT
Pass a pointer to a long to receive the result of the certification Pass a pointer to a long to receive the result of the certification
verification that was requested (using the CURLOPT_SSL_VERIFYPEER option to verification that was requested (using the \fICURLOPT_SSL_VERIFYPEER(3)\fP
\fIcurl_easy_setopt(3)\fP). option to \fIcurl_easy_setopt(3)\fP).
.IP CURLINFO_SSL_ENGINES .IP CURLINFO_SSL_ENGINES
Pass the address of a 'struct curl_slist *' to receive a linked-list of Pass the address of a 'struct curl_slist *' to receive a linked-list of
OpenSSL crypto-engines supported. Note that engines are normally implemented OpenSSL crypto-engines supported. Note that engines are normally implemented
@@ -150,14 +150,15 @@ it means that the server didn't send a valid Content-Type header or that the
protocol used doesn't support this. protocol used doesn't support this.
.IP CURLINFO_PRIVATE .IP CURLINFO_PRIVATE
Pass a pointer to a char pointer to receive the pointer to the private data Pass a pointer to a char pointer to receive the pointer to the private data
associated with the curl handle (set with the CURLOPT_PRIVATE option to associated with the curl handle (set with the \fICURLOPT_PRIVATE(3)\fP option
\fIcurl_easy_setopt(3)\fP). Please note that for internal reasons, the to \fIcurl_easy_setopt(3)\fP). Please note that for internal reasons, the
value is returned as a char pointer, although effectively being a 'void *'. value is returned as a char pointer, although effectively being a 'void *'.
(Added in 7.10.3) (Added in 7.10.3)
.IP CURLINFO_HTTPAUTH_AVAIL .IP CURLINFO_HTTPAUTH_AVAIL
Pass a pointer to a long to receive a bitmask indicating the authentication Pass a pointer to a long to receive a bitmask indicating the authentication
method(s) available. The meaning of the bits is explained in the method(s) available. The meaning of the bits is explained in the
CURLOPT_HTTPAUTH option for \fIcurl_easy_setopt(3)\fP. (Added in 7.10.8) \fICURLOPT_HTTPAUTH(3)\fP option for \fIcurl_easy_setopt(3)\fP. (Added in
7.10.8)
.IP CURLINFO_PROXYAUTH_AVAIL .IP CURLINFO_PROXYAUTH_AVAIL
Pass a pointer to a long to receive a bitmask indicating the authentication Pass a pointer to a long to receive a bitmask indicating the authentication
method(s) available for your proxy authentication. (Added in 7.10.8) method(s) available for your proxy authentication. (Added in 7.10.8)
@@ -201,8 +202,8 @@ Pass a pointer to a long to receive the last socket used by this curl
session. If the socket is no longer valid, -1 is returned. When you finish session. If the socket is no longer valid, -1 is returned. When you finish
working with the socket, you must call curl_easy_cleanup() as usual and let working with the socket, you must call curl_easy_cleanup() as usual and let
libcurl close the socket and cleanup other resources associated with the libcurl close the socket and cleanup other resources associated with the
handle. This is typically used in combination with \fICURLOPT_CONNECT_ONLY\fP. handle. This is typically used in combination with
(Added in 7.15.2) \fICURLOPT_CONNECT_ONLY(3)\fP. (Added in 7.15.2)
NOTE: this API is not really working on win64, since the SOCKET type on win64 NOTE: this API is not really working on win64, since the SOCKET type on win64
is 64 bit large while its 'long' is only 32 bits. is 64 bit large while its 'long' is only 32 bits.
@@ -216,13 +217,13 @@ Also works for SFTP since 7.21.4
.IP CURLINFO_CERTINFO .IP CURLINFO_CERTINFO
Pass a pointer to a 'struct curl_certinfo *' and you'll get it set to point to Pass a pointer to a 'struct curl_certinfo *' and you'll get it set to point to
struct that holds a number of linked lists with info about the certificate struct that holds a number of linked lists with info about the certificate
chain, assuming you had CURLOPT_CERTINFO enabled when the previous request was chain, assuming you had \fICURLOPT_CERTINFO(3)\fP enabled when the previous
done. The struct reports how many certs it found and then you can extract info request was done. The struct reports how many certs it found and then you can
for each of those certs by following the linked lists. The info chain is extract info for each of those certs by following the linked lists. The info
provided in a series of data in the format "name:content" where the content is chain is provided in a series of data in the format "name:content" where the
for the specific named data. See also the certinfo.c example. NOTE: this content is for the specific named data. See also the certinfo.c example. NOTE:
option is only available in libcurl built with OpenSSL, NSS, GSKit or QsoSSL this option is only available in libcurl built with OpenSSL, NSS, GSKit or
support. (Added in 7.19.1) QsoSSL support. (Added in 7.19.1)
.IP CURLINFO_TLS_SESSION .IP CURLINFO_TLS_SESSION
Pass a pointer to a 'struct curl_tlsinfo *'. The pointer will be initialized Pass a pointer to a 'struct curl_tlsinfo *'. The pointer will be initialized
to refer to a 'struct curl_tlsinfo *' that will contain an enum indicating the to refer to a 'struct curl_tlsinfo *' that will contain an enum indicating the
@@ -237,8 +238,8 @@ this does not mean that no SSL backend was used. (Added in 7.34.0)
.IP CURLINFO_CONDITION_UNMET .IP CURLINFO_CONDITION_UNMET
Pass a pointer to a long to receive the number 1 if the condition provided in Pass a pointer to a long to receive the number 1 if the condition provided in
the previous request didn't match (see \fICURLOPT_TIMECONDITION\fP). Alas, if the previous request didn't match (see \fICURLOPT_TIMECONDITION(3)\fP). Alas,
this returns a 1 you know that the reason you didn't get data in return is if this returns a 1 you know that the reason you didn't get data in return is
because it didn't fulfill the condition. The long ths argument points to will because it didn't fulfill the condition. The long ths argument points to will
get a zero stored if the condition instead was met. (Added in 7.19.4) get a zero stored if the condition instead was met. (Added in 7.19.4)
.IP CURLINFO_RTSP_SESSION_ID .IP CURLINFO_RTSP_SESSION_ID

10
docs/libcurl/curl_easy_pause.3
View File

@@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___ .\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____| .\" * \___|\___/|_| \_\_____|
.\" * .\" *
.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * .\" *
.\" * This software is licensed as described in the file COPYING, which .\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms .\" * you should have received as part of this distribution. The terms
@@ -41,8 +41,8 @@ the writing is later unpaused.
While it may feel tempting, take care and notice that you cannot call this 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 function from another thread. To unpause, you may for example call it from the
progress callback (see \fIcurl_easy_setopt(3)\fP's progress callback (see \fIcurl_easy_setopt(3)\fP's
\fICURLOPT_PROGRESSFUNCTION\fP), which gets called at least once per second, \fICURLOPT_PROGRESSFUNCTION(3)\fP), which gets called at least once per
even if the connection is paused. second, even if the connection is paused.
When this function is called to unpause reading, the chance is high that you When this function is called to unpause reading, the chance is high that you
will get your write callback called before this function returns. will get your write callback called before this function returns.
@@ -55,11 +55,11 @@ connection. The following bits can be used:
.IP CURLPAUSE_RECV .IP CURLPAUSE_RECV
Pause receiving data. There will be no data received on this connection until 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 this function is called again without this bit set. Thus, the write callback
(\fICURLOPT_WRITEFUNCTION\fP) won't be called. (\fICURLOPT_WRITEFUNCTION(3)\fP) won't be called.
.IP CURLPAUSE_SEND .IP CURLPAUSE_SEND
Pause sending data. There will be no data sent on this connection until this Pause sending data. There will be no data sent on this connection until this
function is called again without this bit set. Thus, the read callback function is called again without this bit set. Thus, the read callback
(\fICURLOPT_READFUNCTION\fP) won't be called. (\fICURLOPT_READFUNCTION(3)\fP) won't be called.
.IP CURLPAUSE_ALL .IP CURLPAUSE_ALL
Convenience define that pauses both directions. Convenience define that pauses both directions.
.IP CURLPAUSE_CONT .IP CURLPAUSE_CONT

2
docs/libcurl/curl_easy_perform.3
View File

@@ -55,7 +55,7 @@ While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by
.SH RETURN VALUE .SH RETURN VALUE
CURLE_OK (0) means everything was ok, non-zero means an error occurred as CURLE_OK (0) means everything was ok, non-zero means an error occurred as
.I <curl/curl.h> .I <curl/curl.h>
defines - see \fIlibcurl-errors(3)\fP. If the \fBCURLOPT_ERRORBUFFER\fP was defines - see \fIlibcurl-errors(3)\fP. If the \fBCURLOPT_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 will be a readable error message in
the error buffer when non-zero is returned. the error buffer when non-zero is returned.
.SH "SEE ALSO" .SH "SEE ALSO"

4
docs/libcurl/curl_easy_recv.3
View File

@@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___ .\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____| .\" * \___|\___/|_| \_\_____|
.\" * .\" *
.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * .\" *
.\" * This software is licensed as described in the file COPYING, which .\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms .\" * you should have received as part of this distribution. The terms
@@ -41,7 +41,7 @@ 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 buffer. The variable \fBn\fP points to will receive the number of received
bytes. bytes.
To establish the connection, set \fBCURLOPT_CONNECT_ONLY\fP option before To establish the connection, set \fBCURLOPT_CONNECT_ONLY(3)\fP option before
calling \fIcurl_easy_perform(3)\fP. Note that \fIcurl_easy_recv(3)\fP does not calling \fIcurl_easy_perform(3)\fP. Note that \fIcurl_easy_recv(3)\fP does not
work on connections that were created without this option. work on connections that were created without this option.

4
docs/libcurl/curl_easy_send.3
View File

@@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___ .\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____| .\" * \___|\___/|_| \_\_____|
.\" * .\" *
.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * .\" *
.\" * This software is licensed as described in the file COPYING, which .\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms .\" * you should have received as part of this distribution. The terms
@@ -39,7 +39,7 @@ connection set-up.
\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want sent. \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. The variable \fBn\fP points to will receive the number of sent bytes.
To establish the connection, set \fBCURLOPT_CONNECT_ONLY\fP option before To establish the connection, set \fBCURLOPT_CONNECT_ONLY(3)\fP option before
calling \fIcurl_easy_perform(3)\fP. Note that \fIcurl_easy_send(3)\fP will not calling \fIcurl_easy_perform(3)\fP. Note that \fIcurl_easy_send(3)\fP will not
work on connections that were created without this option. work on connections that were created without this option.

6
docs/libcurl/curl_easy_setopt.3
View File

@@ -46,9 +46,9 @@ options back to internal default with \fIcurl_easy_reset(3)\fP.
Strings passed to libcurl as 'char *' arguments, are copied by the library; Strings passed to libcurl as 'char *' arguments, are copied by the library;
thus the string storage associated to the pointer argument may be overwritten thus the string storage associated to the pointer argument may be overwritten
after curl_easy_setopt() returns. The only exception to this rule is really after curl_easy_setopt() returns. The only exception to this rule is really
\fICURLOPT_POSTFIELDS\fP, but the alternative that copies the string \fICURLOPT_POSTFIELDS(3)\fP, but the alternative that copies the string
\fICURLOPT_COPYPOSTFIELDS\fP has some usage characteristics you need to read \fICURLOPT_COPYPOSTFIELDS(3)\fP has some usage characteristics you need to
up on. read up on.
Before version 7.17.0, strings were not copied. Instead the user was forced Before version 7.17.0, strings were not copied. Instead the user was forced
keep them available until libcurl no longer needed them. keep them available until libcurl no longer needed them.

21
docs/libcurl/curl_formadd.3
View File

@@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___ .\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____| .\" * \___|\___/|_| \_\_____|
.\" * .\" *
.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * .\" *
.\" * This software is licensed as described in the file COPYING, which .\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms .\" * you should have received as part of this distribution. The terms
@@ -32,7 +32,7 @@ curl_formadd - add a section to a multipart/formdata HTTP POST
curl_formadd() is used to append sections when building a multipart/formdata curl_formadd() is used to append sections when building a multipart/formdata
HTTP POST (sometimes referred to as RFC2388-style posts). Append one section HTTP POST (sometimes referred to as RFC2388-style posts). Append one section
at a time until you've added all the sections you want included and then you at a time until you've added all the sections you want included and then you
pass the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. pass the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST(3)\fP.
\fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated \fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated
invokes it should be left as set to allow repeated invokes to find the end of invokes it should be left as set to allow repeated invokes to find the end of
the list faster. the list faster.
@@ -45,7 +45,7 @@ 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. \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. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
First, there are some basics you need to understand about multipart/formdata First, there are some basics you need to understand about multipart/formdata
posts. Each part consists of at least a NAME and a CONTENTS part. If the part posts. Each part consists of at least a NAME and a CONTENTS part. If the part
@@ -121,12 +121,13 @@ to the buffer to be uploaded. This buffer must not be freed until after
is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
long which gives the length of the buffer. long which gives the length of the buffer.
.IP CURLFORM_STREAM .IP CURLFORM_STREAM
Tells libcurl to use the \fICURLOPT_READFUNCTION\fP callback to get data. The Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on to the data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on
read callback's fourth argument. If you want the part to look like a file to the read callback's fourth argument. If you want the part to look like a
upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that when file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that
using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be set when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
with the total expected length of the part. (Option added in libcurl 7.18.2) set with the total expected length of the part. (Option added in libcurl
7.18.2)
.IP CURLFORM_ARRAY .IP CURLFORM_ARRAY
Another possibility to send options to curl_formadd() is the Another possibility to send options to curl_formadd() is the
\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
@@ -142,7 +143,7 @@ the POST occurs, if you free it before the post completes you may experience
problems. problems.
When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
the \fICURLOPT_HTTPPOST\fP option), you must not free the list until after the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
you've called \fIcurl_easy_cleanup(3)\fP for the curl handle. you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
See example below. See example below.

6
docs/libcurl/curl_formfree.3
View File

@@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___ .\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____| .\" * \___|\___/|_| \_\_____|
.\" * .\" *
.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * .\" *
.\" * This software is licensed as described in the file COPYING, which .\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms .\" * you should have received as part of this distribution. The terms
@@ -33,8 +33,8 @@ curl_formfree() is used to clean up data previously built/appended with
typically means after \fIcurl_easy_perform(3)\fP has been called. typically means after \fIcurl_easy_perform(3)\fP has been called.
The pointer to free is the same pointer you passed to the The pointer to free is the same pointer you passed to the
\fBCURLOPT_HTTPPOST\fP option, which is the \fIfirstitem\fP pointer from the \fBCURLOPT_HTTPPOST(3)\fP option, which is the \fIfirstitem\fP pointer from
\fIcurl_formadd(3)\fP invoke(s). the \fIcurl_formadd(3)\fP invoke(s).
\fBform\fP is the pointer as returned from a previous call to \fBform\fP is the pointer as returned from a previous call to
\fIcurl_formadd(3)\fP and may be NULL. \fIcurl_formadd(3)\fP and may be NULL.

8
docs/libcurl/curl_multi_add_handle.3
View File

@@ -38,10 +38,10 @@ use \fIcurl_easy_perform(3)\fP on that handle. After having removed the handle
from the multi stack again, it is perfectly fine to use it with the easy from the multi stack again, it is perfectly fine to use it with the easy
interface again. interface again.
If the easy handle is not set to use a shared (CURLOPT_SHARE) or global DNS If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) or
cache (CURLOPT_DNS_USE_GLOBAL_CACHE), it will be made to use the DNS cache global DNS cache (\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP), it will be made to
that is shared between all easy handles within the multi handle when use the DNS cache that is shared between all easy handles within the multi
\fIcurl_multi_add_handle(3)\fP is called. handle when \fIcurl_multi_add_handle(3)\fP is called.
If you have CURLMOPT_TIMERFUNCTION set in the multi handle (and you really If you have CURLMOPT_TIMERFUNCTION set in the multi handle (and you really
should if you're working event-based with \fIcurl_multi_socket_action(3)\fP should if you're working event-based with \fIcurl_multi_socket_action(3)\fP

2
docs/libcurl/curl_multi_setopt.3
View File

@@ -92,7 +92,7 @@ When the cache is full, curl closes the oldest one in the cache to prevent the
number of open connections from increasing. number of open connections from increasing.
This option is for the multi handle's use only, when using the easy interface This option is for the multi handle's use only, when using the easy interface
you should instead use the \fICURLOPT_MAXCONNECTS\fP option. you should instead use the \fICURLOPT_MAXCONNECTS(3)\fP option.
See \fICURLMOPT_MAX_TOTAL_CONNECTIONS\fP for limiting the number of active See \fICURLMOPT_MAX_TOTAL_CONNECTIONS\fP for limiting the number of active
connections. connections.

8
docs/libcurl/curl_share_init.3
View File

@@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___ .\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____| .\" * \___|\___/|_| \_\_____|
.\" * .\" *
.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * .\" *
.\" * This software is licensed as described in the file COPYING, which .\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms .\" * you should have received as part of this distribution. The terms
@@ -33,9 +33,9 @@ share-functions, sometimes referred to as a share handle in some places in the
documentation. This init call MUST have a corresponding call to documentation. This init call MUST have a corresponding call to
\fIcurl_share_cleanup\fP when all operations using the share are complete. \fIcurl_share_cleanup\fP when all operations using the share are complete.
This \fIshare handle\fP is what you pass to curl using the \fICURLOPT_SHARE\fP This \fIshare handle\fP is what you pass to curl using the
option with \fIcurl_easy_setopt(3)\fP, to make that specific curl handle use \fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, to make that
the data in this share. specific curl handle use the data in this share.
.SH RETURN VALUE .SH RETURN VALUE
If this function returns NULL, something went wrong (out of memory, etc.) If this function returns NULL, something went wrong (out of memory, etc.)
and therefore the share object was not created. and therefore the share object was not created.

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

@@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___ .\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____| .\" * \___|\___/|_| \_\_____|
.\" * .\" *
.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * .\" *
.\" * This software is licensed as described in the file COPYING, which .\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms .\" * you should have received as part of this distribution. The terms
@@ -28,11 +28,11 @@ This man page includes most, if not all, available error codes in libcurl.
Why they occur and possibly what you can do to fix the problem are also included. Why they occur and possibly what you can do to fix the problem are also included.
.SH "CURLcode" .SH "CURLcode"
Almost all "easy" interface functions return a CURLcode error code. No matter Almost all "easy" interface functions return a CURLcode error code. No matter
what, using the \fIcurl_easy_setopt(3)\fP option \fICURLOPT_ERRORBUFFER\fP is what, using the \fIcurl_easy_setopt(3)\fP option \fICURLOPT_ERRORBUFFER(3)\fP
a good idea as it will give you a human readable error string that may offer is a good idea as it will give you a human readable error string that may
more details about the cause of the error than just the error code. 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 \fIcurl_easy_strerror(3)\fP can be called to get an error string from a given
given CURLcode number. CURLcode number.
CURLcode is one of the following: CURLcode is one of the following:
.IP "CURLE_OK (0)" .IP "CURLE_OK (0)"
@@ -74,7 +74,7 @@ After having sent the FTP password to the server, libcurl expects a proper
reply. This error code indicates that an unexpected code was returned. reply. This error code indicates that an unexpected code was returned.
.IP "CURLE_FTP_ACCEPT_TIMEOUT (12)" .IP "CURLE_FTP_ACCEPT_TIMEOUT (12)"
During an active FTP session while waiting for the server to connect, the During an active FTP session while waiting for the server to connect, the
\fICURLOPT_ACCEPTTIMOUT_MS\fP (or the internal default) timeout expired. \fICURLOPT_ACCEPTTIMOUT_MS(3)\fP (or the internal default) timeout expired.
.IP "CURLE_FTP_WEIRD_PASV_REPLY (13)" .IP "CURLE_FTP_WEIRD_PASV_REPLY (13)"
libcurl failed to get a sensible result back from the server as a response to libcurl failed to get a sensible result back from the server as a response to
either a PASV or a EPSV command. The server is flawed. either a PASV or a EPSV command. The server is flawed.
@@ -97,8 +97,8 @@ When sending custom "QUOTE" commands to the remote server, one of the commands
returned an error code that was 400 or higher (for FTP) or otherwise returned an error code that was 400 or higher (for FTP) or otherwise
indicated unsuccessful completion of the command. indicated unsuccessful completion of the command.
.IP "CURLE_HTTP_RETURNED_ERROR (22)" .IP "CURLE_HTTP_RETURNED_ERROR (22)"
This is returned if CURLOPT_FAILONERROR is set TRUE and the HTTP server This is returned if \fICURLOPT_FAILONERROR(3)\fP is set TRUE and the HTTP
returns an error code that is >= 400. server returns an error code that is >= 400.
.IP "CURLE_WRITE_ERROR (23)" .IP "CURLE_WRITE_ERROR (23)"
An error occurred when writing received data to a local file, or an error was An error occurred when writing received data to a local file, or an error was
returned to libcurl from a write callback. returned to libcurl from a write callback.
@@ -116,7 +116,8 @@ Operation timeout. The specified time-out period was reached according to the
conditions. conditions.
.IP "CURLE_FTP_PORT_FAILED (30)" .IP "CURLE_FTP_PORT_FAILED (30)"
The FTP PORT command returned error. This mostly happens when you haven't The FTP PORT command returned error. This mostly happens when you haven't
specified a good enough address for libcurl to use. See \fICURLOPT_FTPPORT\fP. specified a good enough address for libcurl to use. See
\fICURLOPT_FTPPORT(3)\fP.
.IP "CURLE_FTP_COULDNT_USE_REST (31)" .IP "CURLE_FTP_COULDNT_USE_REST (31)"
The FTP REST command returned error. This should never happen if the server is The FTP REST command returned error. This should never happen if the server is
sane. sane.
@@ -148,10 +149,10 @@ Internal error. A function was called with a bad parameter.
.IP "CURLE_INTERFACE_FAILED (45)" .IP "CURLE_INTERFACE_FAILED (45)"
Interface error. A specified outgoing interface could not be used. Set which Interface error. A specified outgoing interface could not be used. Set which
interface to use for outgoing connections' source IP address with interface to use for outgoing connections' source IP address with
CURLOPT_INTERFACE. \fICURLOPT_INTERFACE(3)\fP.
.IP "CURLE_TOO_MANY_REDIRECTS (47)" .IP "CURLE_TOO_MANY_REDIRECTS (47)"
Too many redirects. When following redirects, libcurl hit the maximum amount. Too many redirects. When following redirects, libcurl hit the maximum amount.
Set your limit with CURLOPT_MAXREDIRS. Set your limit with \fICURLOPT_MAXREDIRS(3)\fP.
.IP "CURLE_UNKNOWN_OPTION (48)" .IP "CURLE_UNKNOWN_OPTION (48)"
An option passed to libcurl is not recognized/known. Refer to the appropriate An option passed to libcurl is not recognized/known. Refer to the appropriate
documentation. This is most likely a problem in the program that uses documentation. This is most likely a problem in the program that uses
@@ -229,7 +230,7 @@ Failed to load CRL file (Added in 7.19.0)
Issuer check failed (Added in 7.19.0) Issuer check failed (Added in 7.19.0)
.IP "CURLE_FTP_PRET_FAILED (84)" .IP "CURLE_FTP_PRET_FAILED (84)"
The FTP server does not understand the PRET command at all or does not support The FTP server does not understand the PRET command at all or does not support
the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST\fP, a the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST(3)\fP, a
custom LIST command will be sent with PRET CMD before PASV as well. (Added in custom LIST command will be sent with PRET CMD before PASV as well. (Added in
7.20.0) 7.20.0)
.IP "CURLE_RTSP_CSEQ_ERROR (85)" .IP "CURLE_RTSP_CSEQ_ERROR (85)"

9
docs/libcurl/libcurl-share.3
View File

@@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___ .\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____| .\" * \___|\___/|_| \_\_____|
.\" * .\" *
.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * .\" *
.\" * This software is licensed as described in the file COPYING, which .\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms .\" * you should have received as part of this distribution. The terms
@@ -51,11 +51,12 @@ using this multi-threaded. You set lock and unlock functions with
\fIcurl_share_setopt(3)\fP too. \fIcurl_share_setopt(3)\fP too.
Then, you make an easy handle to use this share, you set the Then, you make an easy handle to use this share, you set the
\fICURLOPT_SHARE\fP option with \fIcurl_easy_setopt(3)\fP, and pass in share \fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, and pass in
handle. You can make any number of easy handles share the same share handle. share handle. You can make any number of easy handles share the same share
handle.
To make an easy handle stop using that particular share, you set To make an easy handle stop using that particular share, you set
\fICURLOPT_SHARE\fP to NULL for that easy handle. To make a handle stop \fICURLOPT_SHARE(3)\fP to NULL for that easy handle. To make a handle stop
sharing a particular data, you can \fICURLSHOPT_UNSHARE\fP it. sharing a particular data, you can \fICURLSHOPT_UNSHARE\fP it.
When you're done using the share, make sure that no easy handle is still using When you're done using the share, make sure that no easy handle is still using

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

@@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___ .\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____| .\" * \___|\___/|_| \_\_____|
.\" * .\" *
.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * .\" *
.\" * This software is licensed as described in the file COPYING, which .\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms .\" * you should have received as part of this distribution. The terms
@@ -170,8 +170,8 @@ terminated with a zero byte. When you set strings with
\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they don't \fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they don't
need to be kept around in your application after being set[4]. need to be kept around in your application after being set[4].
One of the most basic properties to set in the handle is the URL. You set One of the most basic properties to set in the handle is the URL. You set your
your preferred URL to transfer with CURLOPT_URL in a manner similar to: preferred URL to transfer with \fICURLOPT_URL(3)\fP in a manner similar to:
.nf .nf
curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/"); curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/");
@@ -197,27 +197,27 @@ by setting another property:
Using that property, you can easily pass local data between your application Using that property, you can easily pass local data between your application
and the function that gets invoked by libcurl. libcurl itself won't touch the and the function that gets invoked by libcurl. libcurl itself won't touch the
data you pass with \fICURLOPT_WRITEDATA\fP. data you pass with \fICURLOPT_WRITEDATA(3)\fP.
libcurl offers its own default internal callback that will take care of the data libcurl offers its own default internal callback that will take care of the
if you don't set the callback with \fICURLOPT_WRITEFUNCTION\fP. It will then data if you don't set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It
simply output the received data to stdout. You can have the default callback will then simply output the received data to stdout. You can have the default
write the data to a different file handle by passing a 'FILE *' to a file callback write the data to a different file handle by passing a 'FILE *' to a
opened for writing with the \fICURLOPT_WRITEDATA\fP option. 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 have a deep breath. Here's one of those
rare platform-dependent nitpicks. Did you spot it? On some platforms[2], rare platform-dependent nitpicks. Did you spot it? On some platforms[2],
libcurl won't be able to operate on files opened by the program. Thus, if you libcurl won't be able to operate on files opened by the program. Thus, if you
use the default callback and pass in an open file with use the default callback and pass in an open file with
\fICURLOPT_WRITEDATA\fP, it will crash. You should therefore avoid this to \fICURLOPT_WRITEDATA(3)\fP, it will crash. You should therefore avoid this to
make your program run fine virtually everywhere. make your program run fine virtually everywhere.
(\fICURLOPT_WRITEDATA\fP was formerly known as \fICURLOPT_FILE\fP. Both names (\fICURLOPT_WRITEDATA(3)\fP was formerly known as \fICURLOPT_FILE\fP. Both
still work and do the same thing). names still work and do the same thing).
If you're using libcurl as a win32 DLL, you MUST use the If you're using libcurl as a win32 DLL, you MUST use the
\fICURLOPT_WRITEFUNCTION\fP if you set \fICURLOPT_WRITEDATA\fP - or you will \fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP - or you
experience crashes. will experience crashes.
There are of course many more options you can set, and we'll get back to a few There are of course many more options you can set, and we'll get back to a few
of them later. Let's instead continue to the actual transfer: of them later. Let's instead continue to the actual transfer:
@@ -234,8 +234,8 @@ passed to it, libcurl will abort the operation and return with an error code.
When the transfer is complete, the function returns a return code that informs 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 isn't enough for you if it succeeded in its mission or not. If a return code isn't enough for
you, you can use the CURLOPT_ERRORBUFFER to point libcurl to a buffer of yours you, you can use the \fICURLOPT_ERRORBUFFER(3)\fP to point libcurl to a buffer
where it'll store a human readable error message as well. of yours where it'll store a human readable error message as well.
If you then want to transfer another file, the handle is ready to be used 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 again. Mind you, it is even preferred that you re-use an existing handle if
@@ -293,14 +293,14 @@ Secure Transport
The engine is fully thread-safe, and no additional steps are required. The engine is fully thread-safe, and no additional steps are required.
When using multiple threads you should set the CURLOPT_NOSIGNAL option to 1 When using multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP
for all handles. Everything will or might work fine except that timeouts are option to 1 for all handles. Everything will or might work fine except that
not honored during the DNS lookup - which you can work around by building timeouts are not honored during the DNS lookup - which you can work around by
libcurl with c-ares support. c-ares is a library that provides asynchronous building libcurl with c-ares support. c-ares is a library that provides
name resolves. On some platforms, libcurl simply will not function properly asynchronous name resolves. On some platforms, libcurl simply will not
multi-threaded unless this option is set. function properly multi-threaded unless this option is set.
Also, note that CURLOPT_DNS_USE_GLOBAL_CACHE is not thread-safe. Also, note that \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread-safe.
.SH "When It Doesn't Work" .SH "When It Doesn't Work"
There will always be times when the transfer fails for some reason. You might There will always be times when the transfer fails for some reason. You might
@@ -308,23 +308,23 @@ have set the wrong libcurl option or misunderstood what the libcurl option
actually does, or the remote server might return non-standard replies that actually does, or the remote server might return non-standard replies that
confuse the library which then confuses your program. confuse the library which then confuses your program.
There's one golden rule when these things occur: set the CURLOPT_VERBOSE There's one golden rule when these things occur: set the
option to 1. It'll cause the library to spew out the entire protocol \fICURLOPT_VERBOSE(3)\fP option to 1. It'll cause the library to spew out the
details it sends, some internal info and some received protocol data as well entire protocol details it sends, some internal info and some received
(especially when using FTP). If you're using HTTP, adding the headers in the protocol data as well (especially when using FTP). If you're using HTTP,
received output to study is also a clever way to get a better understanding adding the headers in the received output to study is also a clever way to get
why the server behaves the way it does. Include headers in the normal body a better understanding why the server behaves the way it does. Include headers
output with CURLOPT_HEADER set 1. in the normal body output with \fICURLOPT_HEADER(3)\fP set 1.
Of course, there are bugs left. We need to know about them to be able Of course, there are bugs left. We need to know about them to be able to fix
to fix them, so we're quite dependent on your bug reports! When you do report them, so we're quite dependent on your bug reports! When you do report
suspected bugs in libcurl, please include as many details as you possibly can: a suspected bugs in libcurl, please include as many details as you possibly can:
protocol dump that CURLOPT_VERBOSE produces, library version, as much as a protocol dump that \fICURLOPT_VERBOSE(3)\fP produces, library version, as
possible of your code that uses libcurl, operating system name and version, much as possible of your code that uses libcurl, operating system name and
compiler name and version etc. version, compiler name and version etc.
If CURLOPT_VERBOSE is not enough, you increase the level of debug data your If \fICURLOPT_VERBOSE(3)\fP is not enough, you increase the level of debug
application receive by using the CURLOPT_DEBUGFUNCTION. data your application receive by using the \fICURLOPT_DEBUGFUNCTION(3)\fP.
Getting some in-depth knowledge about the protocols involved is never wrong, Getting some in-depth knowledge about the protocols involved is never wrong,
and if you're trying to do funny things, you might very well understand and if you're trying to do funny things, you might very well understand
@@ -363,7 +363,7 @@ Tell libcurl that we want to upload:
A few protocols won't behave properly when uploads are done without any prior A few protocols won't behave properly when uploads are done without any prior
knowledge of the expected file size. So, set the upload file size using the knowledge of the expected file size. So, set the upload file size using the
CURLOPT_INFILESIZE_LARGE for all known file sizes like this[1]: \fICURLOPT_INFILESIZE_LARGE(3)\fP for all known file sizes like this[1]:
.nf .nf
/* in this example, file_size must be an curl_off_t variable */ /* in this example, file_size must be an curl_off_t variable */
@@ -393,15 +393,15 @@ them URL encoded, as %XX where XX is a two-digit hexadecimal number.
libcurl also provides options to set various passwords. The user name and libcurl also provides options to set various passwords. The user name and
password as shown embedded in the URL can instead get set with the password as shown embedded in the URL can instead get set with the
CURLOPT_USERPWD option. The argument passed to libcurl should be a char * to \fICURLOPT_USERPWD(3)\fP option. The argument passed to libcurl should be a
a string in the format "user:password". In a manner like this: char * to a string in the format "user:password". In a manner like this:
curl_easy_setopt(easyhandle, CURLOPT_USERPWD, "myname:thesecret"); curl_easy_setopt(easyhandle, CURLOPT_USERPWD, "myname:thesecret");
Another case where name and password might be needed at times, is for those Another case where name and password might be needed at times, is for those
users who need to authenticate themselves to a proxy they use. libcurl offers users who need to authenticate themselves to a proxy they use. libcurl offers
another option for this, the CURLOPT_PROXYUSERPWD. It is used quite similar another option for this, the \fICURLOPT_PROXYUSERPWD(3)\fP. It is used quite
to the CURLOPT_USERPWD option like this: similar to the \fICURLOPT_USERPWD(3)\fP option like this:
curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
@@ -412,7 +412,7 @@ chapter), as it might contain the password in plain text. libcurl has the
ability to use this file to figure out what set of user name and password to ability to use this file to figure out what set of user name and password to
use for a particular host. As an extension to the normal functionality, use for a particular host. As an extension to the normal functionality,
libcurl also supports this file for non-FTP protocols such as HTTP. To make libcurl also supports this file for non-FTP protocols such as HTTP. To make
curl use this file, use the CURLOPT_NETRC option: curl use this file, use the \fICURLOPT_NETRC(3)\fP option:
curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L); curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L);
@@ -443,12 +443,12 @@ 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, At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM,
Negotiate, GSS-Negotiate and SPNEGO. You can tell libcurl which one to use Negotiate, GSS-Negotiate and SPNEGO. You can tell libcurl which one to use
with CURLOPT_HTTPAUTH as in: with \fICURLOPT_HTTPAUTH(3)\fP as in:
curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST); curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
And when you send authentication to a proxy, you can also set authentication And when you send authentication to a proxy, you can also set authentication
type the same way but instead with CURLOPT_PROXYAUTH: type the same way but instead with \fICURLOPT_PROXYAUTH(3)\fP:
curl_easy_setopt(easyhandle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM); curl_easy_setopt(easyhandle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM);
@@ -484,8 +484,8 @@ libcurl to post it all to the remote site:
.fi .fi
Simple enough, huh? Since you set the POST options with the Simple enough, huh? Since you set the POST options with the
CURLOPT_POSTFIELDS, this automatically switches the handle to use POST in the \fICURLOPT_POSTFIELDS(3)\fP, this automatically switches the handle to use
upcoming request. POST in the upcoming request.
Ok, so what if you want to post binary data that also requires you to set the Ok, so what if you want to post binary data that also requires you to set the
Content-Type: header of the post? Well, binary posts prevent libcurl from Content-Type: header of the post? Well, binary posts prevent libcurl from
@@ -576,14 +576,14 @@ post handle:
Since all options on an easyhandle are "sticky", they remain the same until Since all options on an easyhandle are "sticky", they remain the same until
changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell
curl to go back to a plain GET request if you intend to do one as your curl to go back to a plain GET request if you intend to do one as your next
next request. You force an easyhandle to go back to GET by using the request. You force an easyhandle to go back to GET by using the
CURLOPT_HTTPGET option: \fICURLOPT_HTTPGET(3)\fP option:
curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L); curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L);
Just setting CURLOPT_POSTFIELDS to "" or NULL will *not* stop libcurl from Just setting \fICURLOPT_POSTFIELDS(3)\fP to "" or NULL will *not* stop libcurl
doing a POST. It will just make it POST without any data to send! from doing a POST. It will just make it POST without any data to send!
.SH "Showing Progress" .SH "Showing Progress"
@@ -591,16 +591,16 @@ For historical and traditional reasons, libcurl has a built-in progress meter
that can be switched on and then makes it present a progress meter in your that can be switched on and then makes it present a progress meter in your
terminal. terminal.
Switch on the progress meter by, oddly enough, setting CURLOPT_NOPROGRESS to Switch on the progress meter by, oddly enough, setting
zero. This option is set to 1 by default. \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 For most applications however, the built-in progress meter is useless and
what instead is interesting is the ability to specify a progress what instead is interesting is the ability to specify a progress
callback. The function pointer you pass to libcurl will then be called on callback. The function pointer you pass to libcurl will then be called on
irregular intervals with information about the current transfer. irregular intervals with information about the current transfer.
Set the progress callback by using CURLOPT_PROGRESSFUNCTION. And pass a Set the progress callback by using \fICURLOPT_PROGRESSFUNCTION(3)\fP. And pass
pointer to a function that matches this prototype: a pointer to a function that matches this prototype:
.nf .nf
int progress_callback(void *clientp, int progress_callback(void *clientp,
@@ -612,7 +612,7 @@ pointer to a function that matches this prototype:
If any of the input arguments is unknown, a 0 will be passed. The first 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 argument, the 'clientp' is the pointer you pass to libcurl with
CURLOPT_PROGRESSDATA. libcurl won't touch it. \fICURLOPT_PROGRESSDATA(3)\fP. libcurl won't touch it.
.SH "libcurl with C++" .SH "libcurl with C++"
@@ -671,11 +671,12 @@ pass that information similar to this:
curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "user:password"); curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "user:password");
If you want to, you can specify the host name only in the CURLOPT_PROXY If you want to, you can specify the host name only in the
option, and set the port number separately with CURLOPT_PROXYPORT. \fICURLOPT_PROXY(3)\fP option, and set the port number separately with
\fICURLOPT_PROXYPORT(3)\fP.
Tell libcurl what kind of proxy it is with CURLOPT_PROXYTYPE (if not, it will Tell libcurl what kind of proxy it is with \fICURLOPT_PROXYTYPE(3)\fP (if not,
default to assume a HTTP proxy): it will default to assume a HTTP proxy):
curl_easy_setopt(easyhandle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4); curl_easy_setopt(easyhandle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4);
@@ -704,7 +705,8 @@ variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all
hosts. hosts.
To explicitly disable libcurl's checking for and using the proxy environment To explicitly disable libcurl's checking for and using the proxy environment
variables, set the proxy name to "" - an empty string - with CURLOPT_PROXY. variables, set the proxy name to "" - an empty string - with
\fICURLOPT_PROXY(3)\fP.
.IP "SSL and Proxies" .IP "SSL and Proxies"
SSL is for secure point-to-point connections. This involves strong encryption SSL is for secure point-to-point connections. This involves strong encryption
@@ -800,21 +802,21 @@ may also be added in the future.
Each easy handle will attempt to keep the last few connections alive for a 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" while in case they are to be used again. You can set the size of this "cache"
with the CURLOPT_MAXCONNECTS option. Default is 5. There is very seldom any with the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is very
point in changing this value, and if you think of changing this it is often seldom any point in changing this value, and if you think of changing this it
just a matter of thinking again. is often just a matter of thinking again.
To force your upcoming request to not use an already existing connection (it 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 will even close one first if there happens to be one alive to the same host
you're about to operate on), you can do that by setting CURLOPT_FRESH_CONNECT you're about to operate on), you can do that by setting
to 1. In a similar spirit, you can also forbid the upcoming request to be \fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar spirit, you can also forbid
"lying" around and possibly get re-used after the request by setting the upcoming request to be "lying" around and possibly get re-used after the
CURLOPT_FORBID_REUSE to 1. request by setting \fICURLOPT_FORBID_REUSE(3)\fP to 1.
.SH "HTTP Headers Used by libcurl" .SH "HTTP Headers Used by libcurl"
When you use libcurl to do HTTP requests, it'll pass along a series of headers When you use libcurl to do HTTP requests, it'll pass along a series of headers
automatically. It might be good for you to know and understand these. You automatically. It might be good for you to know and understand these. You
can replace or remove them by using the CURLOPT_HTTPHEADER option. can replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option.
.IP "Host" .IP "Host"
This header is required by HTTP 1.1 and even many 1.0 servers and should be This header is required by HTTP 1.1 and even many 1.0 servers and should be
@@ -843,8 +845,8 @@ libcurl is your friend here too.
.IP CUSTOMREQUEST .IP CUSTOMREQUEST
If just changing the actual HTTP request keyword is what you want, like when 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 is there GET, HEAD or POST is not good enough for you, \fICURLOPT_CUSTOMREQUEST(3)\fP
for you. It is very simple to use: is there for you. It is very simple to use:
curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST"); curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST");
@@ -939,28 +941,29 @@ A little example that deletes a given file before an operation:
If you would instead want this operation (or chain of operations) to happen If you would instead want this operation (or chain of operations) to happen
_after_ the data transfer took place the option to \fIcurl_easy_setopt(3)\fP _after_ the data transfer took place the option to \fIcurl_easy_setopt(3)\fP
would instead be called CURLOPT_POSTQUOTE and used the exact same way. 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 command will be 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 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 server, no more commands will be issued and libcurl will bail out with an
error code (CURLE_QUOTE_ERROR). Note that if you use CURLOPT_QUOTE to send error code (CURLE_QUOTE_ERROR). Note that if you use \fICURLOPT_QUOTE(3)\fP to
commands before a transfer, no transfer will actually take place when a quote send commands before a transfer, no transfer will actually take place when a
command has failed. quote command has failed.
If you set the CURLOPT_HEADER to 1, you will tell libcurl to get If you set the \fICURLOPT_HEADER(3)\fP to 1, you will tell libcurl to get
information about the target file and output "headers" about it. The headers information about the target file and output "headers" about it. The headers
will be in "HTTP-style", looking like they do in HTTP. will be in "HTTP-style", looking like they do in HTTP.
The option to enable headers or to run custom FTP commands may be useful to The option to enable headers or to run custom FTP commands may be useful to
combine with CURLOPT_NOBODY. If this option is set, no actual file content combine with \fICURLOPT_NOBODY(3)\fP. If this option is set, no actual file
transfer will be performed. content transfer will be performed.
.IP "FTP Custom CUSTOMREQUEST" .IP "FTP Custom CUSTOMREQUEST"
If you do want to list the contents of a FTP directory using your own defined FTP If you do want to list the contents of a FTP directory using your own defined
command, CURLOPT_CUSTOMREQUEST will do just that. "NLST" is the default one FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP will do just that. "NLST" is the
for listing directories but you're free to pass in your idea of a good default one for listing directories but you're free to pass in your idea of a
alternative. good alternative.
.SH "Cookies Without Chocolate Chips" .SH "Cookies Without Chocolate Chips"
In the HTTP sense, a cookie is a name with an associated value. A server sends In the HTTP sense, a cookie is a name with an associated value. A server sends
@@ -975,8 +978,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 Cookies are sent from server to clients with the header Set-Cookie: and
they're sent from clients to servers with the Cookie: header. they're sent from clients to servers with the Cookie: header.
To just send whatever cookie you want to a server, you can use CURLOPT_COOKIE To just send whatever cookie you want to a server, you can use
to set a cookie string like this: \fICURLOPT_COOKIE(3)\fP to set a cookie string like this:
curl_easy_setopt(easyhandle, CURLOPT_COOKIE, "name1=var1; name2=var2;"); curl_easy_setopt(easyhandle, CURLOPT_COOKIE, "name1=var1; name2=var2;");
@@ -987,29 +990,30 @@ are then used accordingly on later requests.
One way to do this, is to save all headers you receive in a plain file and One way to do this, is to save all headers you receive in a plain file and
when you make a request, you tell libcurl to read the previous headers to 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 figure out which cookies to use. Set the header file to read cookies from with
CURLOPT_COOKIEFILE. \fICURLOPT_COOKIEFILE(3)\fP.
The CURLOPT_COOKIEFILE option also automatically enables the cookie parser in The \fICURLOPT_COOKIEFILE(3)\fP option also automatically enables the cookie
libcurl. Until the cookie parser is enabled, libcurl will not parse or parser in libcurl. Until the cookie parser is enabled, libcurl will not parse
understand incoming cookies and they will just be ignored. However, when the or understand incoming cookies and they will just be ignored. However, when
parser is enabled the cookies will be understood and the cookies will be kept the parser is enabled the cookies will be understood and the cookies will be
in memory and used properly in subsequent requests when the same handle is kept in memory and used properly in subsequent requests when the same handle
used. Many times this is enough, and you may not have to save the cookies to is used. Many times this is enough, and you may not have to save the cookies
disk at all. Note that the file you specify to CURLOPT_COOKIEFILE doesn't have to disk at all. Note that the file you specify to \ICURLOPT_COOKIEFILE(3)\fP
to exist to enable the parser, so a common way to just enable the parser and doesn't have to exist to enable the parser, so a common way to just enable the
not read any cookies is to use the name of a file you know doesn't exist. parser and not read any cookies is to use the name of a file you know doesn't
exist.
If you would rather use existing cookies that you've previously received with If you would rather use existing cookies that you've previously received with
your Netscape or Mozilla browsers, you can make libcurl use that cookie file your Netscape or Mozilla browsers, you can make libcurl use that cookie file
as input. The CURLOPT_COOKIEFILE is used for that too, as libcurl will as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as libcurl
automatically find out what kind of file it is and act accordingly. will automatically find out what kind of file it is and act accordingly.
Perhaps the most advanced cookie operation libcurl offers, is saving the Perhaps the most advanced cookie operation libcurl offers, is saving the
entire internal cookie state back into a Netscape/Mozilla formatted cookie 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 file. We call that the cookie-jar. When you set a file name with
CURLOPT_COOKIEJAR, that file name will be created and all received cookies \fICURLOPT_COOKIEJAR(3)\fP, that file name will be created and all received
will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enables cookies will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This
cookies to get passed on properly between multiple handles without any enables cookies to get passed on properly between multiple handles without any
information getting lost. information getting lost.
.SH "FTP Peculiarities We Need" .SH "FTP Peculiarities We Need"
@@ -1028,36 +1032,36 @@ work it tries PASV instead. (EPSV is an extension to the original FTP spec
and does not exist nor work on all FTP servers.) and does not exist nor work on all FTP servers.)
You can prevent libcurl from first trying the EPSV command by setting You can prevent libcurl from first trying the EPSV command by setting
CURLOPT_FTP_USE_EPSV to zero. \fICURLOPT_FTP_USE_EPSV(3)\fP to zero.
In some cases, you will prefer to have the server connect back to you for the 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 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 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. informs the remote server which IP address and port number to connect to.
This is made with the CURLOPT_FTPPORT option. If you set it to "-", libcurl This is made with the \fICURLOPT_FTPPORT(3)\fP option. If you set it to "-",
will use your system's "default IP address". If you want to use a particular libcurl will use your system's "default IP address". If you want to use a
IP, you can set the full IP address, a host name to resolve to an IP address particular IP, you can set the full IP address, a host name to resolve to an
or even a local network interface name that libcurl will get the IP address IP address or even a local network interface name that libcurl will get the IP
from. address from.
When doing the "PORT" approach, libcurl will attempt to use the EPRT and the 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 LPRT before trying PORT, as they work with more protocols. You can disable
this behavior by setting CURLOPT_FTP_USE_EPRT to zero. this behavior by setting \fICURLOPT_FTP_USE_EPRT(3)\fP to zero.
.SH "Headers Equal Fun" .SH "Headers Equal Fun"
Some protocols provide "headers", meta-data separated from the normal Some protocols provide "headers", meta-data separated from the normal
data. These headers are by default not included in the normal data stream, data. These headers are by default not included in the normal data stream, but
but you can make them appear in the data stream by setting CURLOPT_HEADER to you can make them appear in the data stream by setting \fICURLOPT_HEADER(3)\fP
1. to 1.
What might be even more useful, is libcurl's ability to separate the headers What might be even more useful, is libcurl's ability to separate the headers
from the data and thus make the callbacks differ. You can for example set a from the data and thus make the callbacks differ. You can for example set a
different pointer to pass to the ordinary write callback by setting different pointer to pass to the ordinary write callback by setting
CURLOPT_WRITEHEADER. \fICURLOPT_WRITEHEADER(3)\fP.
Or, you can set an entirely separate function to receive the headers, by Or, you can set an entirely separate function to receive the headers, by using
using CURLOPT_HEADERFUNCTION. \fICURLOPT_HEADERFUNCTION(3)\fP.
The headers are passed to the callback function one by one, and you can The headers are passed to the callback function one by one, and you can
depend on that fact. It makes it easier for you to add custom header parsers depend on that fact. It makes it easier for you to add custom header parsers
@@ -1123,13 +1127,13 @@ don't let snoopers see your password: HTTP with Digest, NTLM or GSS
authentication, HTTPS, FTPS, SCP, SFTP and FTP-Kerberos are a few examples. authentication, HTTPS, FTPS, SCP, SFTP and FTP-Kerberos are a few examples.
.IP "Redirects" .IP "Redirects"
The CURLOPT_FOLLOWLOCATION option automatically follows HTTP redirects sent The \fICURLOPT_FOLLOWLOCATION(3)\fP option automatically follows HTTP
by a remote server. These redirects can refer to any kind of URL, not just redirects sent by a remote server. These redirects can refer to any kind of
HTTP. A redirect to a file: URL would cause the libcurl to read (or write) URL, not just HTTP. A redirect to a file: URL would cause the libcurl to read
arbitrary files from the local filesystem. If the application returns (or write) arbitrary files from the local filesystem. If the application
the data back to the user (as would happen in some kinds of CGI scripts), returns the data back to the user (as would happen in some kinds of CGI
an attacker could leverage this to read otherwise forbidden data (e.g. scripts), an attacker could leverage this to read otherwise forbidden data
file://localhost/etc/passwd). (e.g. file://localhost/etc/passwd).
If authentication credentials are stored in the ~/.netrc file, or Kerberos If authentication credentials are stored in the ~/.netrc file, or Kerberos
is in use, any other URL type (not just file:) that requires is in use, any other URL type (not just file:) that requires
@@ -1142,19 +1146,20 @@ the user running the libcurl application, SCP: or SFTP: URLs could access
password or private-key protected resources, password or private-key protected resources,
e.g. sftp://user@some-internal-server/etc/passwd e.g. sftp://user@some-internal-server/etc/passwd
The CURLOPT_REDIR_PROTOCOLS and CURLOPT_NETRC options can be used to The \fICURLOPT_REDIR_PROTOCOLS(3)\fP and \fICURLOPT_NETRC(3)\fP options can be
mitigate against this kind of attack. used to mitigate against this kind of attack.
A redirect can also specify a location available only on the machine running A redirect can also specify a location available only on the machine running
libcurl, including servers hidden behind a firewall from the attacker. libcurl, including servers hidden behind a firewall from the attacker.
e.g. http://127.0.0.1/ or http://intranet/delete-stuff.cgi?delete=all or e.g. http://127.0.0.1/ or http://intranet/delete-stuff.cgi?delete=all or
tftp://bootp-server/pc-config-data tftp://bootp-server/pc-config-data
Apps can mitigate against this by disabling CURLOPT_FOLLOWLOCATION and Apps can mitigate against this by disabling \fICURLOPT_FOLLOWLOCATION(3)\fP
handling redirects itself, sanitizing URLs as necessary. Alternately, an and handling redirects itself, sanitizing URLs as necessary. Alternately, an
app could leave CURLOPT_FOLLOWLOCATION enabled but set CURLOPT_REDIR_PROTOCOLS app could leave \fICURLOPT_FOLLOWLOCATION(3)\fP enabled but set
and install a CURLOPT_OPENSOCKETFUNCTION callback function in which addresses \fICURLOPT_REDIR_PROTOCOLS(3)\fP and install a
are sanitized before use. \fICURLOPT_OPENSOCKETFUNCTION(3)\fP callback function in which addresses are
sanitized before use.
.IP "Private Resources" .IP "Private Resources"
A user who can control the DNS server of a domain being passed in within a URL A user who can control the DNS server of a domain being passed in within a URL
@@ -1162,21 +1167,21 @@ can change the address of the host to a local, private address which a
server-side libcurl-using application could then use. e.g. the innocuous URL server-side libcurl-using application could then use. e.g. the innocuous URL
http://fuzzybunnies.example.com/ could actually resolve to the IP address of a http://fuzzybunnies.example.com/ could actually resolve to the IP address of a
server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Apps can mitigate server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Apps can mitigate
against this by setting a CURLOPT_OPENSOCKETFUNCTION and checking the address against this by setting a \fICURLOPT_OPENSOCKETFUNCTION(3)\fP and checking the
before a connection. address before a connection.
All the malicious scenarios regarding redirected URLs apply just as well All the malicious scenarios regarding redirected URLs apply just as well to
to non-redirected URLs, if the user is allowed to specify an arbitrary URL non-redirected URLs, if the user is allowed to specify an arbitrary URL that
that could point to a private resource. For example, a web app providing could point to a private resource. For example, a web app providing a
a translation service might happily translate file://localhost/etc/passwd translation service might happily translate file://localhost/etc/passwd and
and display the result. Apps can mitigate against this with the display the result. Apps can mitigate against this with the
CURLOPT_PROTOCOLS option as well as by similar mitigation techniques for \fICURLOPT_PROTOCOLS(3)\fP option as well as by similar mitigation techniques
redirections. for redirections.
A malicious FTP server could in response to the PASV command return an A malicious FTP server could in response to the PASV command return an IP
IP address and port number for a server local to the app running libcurl address and port number for a server local to the app running libcurl but
but behind a firewall. Apps can mitigate against this by using the behind a firewall. Apps can mitigate against this by using the
CURLOPT_FTP_SKIP_PASV_IP option or CURLOPT_FTPPORT. \fICURLOPT_FTP_SKIP_PASV_IP(3)\fP option or \fICURLOPT_FTPPORT(3)\fP.
.IP "IPv6 Addresses" .IP "IPv6 Addresses"
libcurl will normally handle IPv6 addresses transparently and just as easily libcurl will normally handle IPv6 addresses transparently and just as easily
@@ -1193,25 +1198,25 @@ can be used to limit resolved addresses to IPv4 only and bypass these issues.
.IP Uploads .IP Uploads
When uploading, a redirect can cause a local (or remote) file to be When uploading, a redirect can cause a local (or remote) file to be
overwritten. Apps must not allow any unsanitized URL to be passed in overwritten. Apps must not allow any unsanitized URL to be passed in for
for uploads. Also, CURLOPT_FOLLOWLOCATION should not be used on uploads. uploads. Also, \fICURLOPT_FOLLOWLOCATION(3)\fP should not be used on uploads.
Instead, the app should handle redirects itself, sanitizing each URL first. Instead, the app should handle redirects itself, sanitizing each URL first.
.IP Authentication .IP Authentication
Use of CURLOPT_UNRESTRICTED_AUTH could cause authentication information to Use of \fICURLOPT_UNRESTRICTED_AUTH(3)\fP could cause authentication
be sent to an unknown second server. Apps can mitigate against this information to be sent to an unknown second server. Apps can mitigate against
by disabling CURLOPT_FOLLOWLOCATION and handling redirects itself, this by disabling \fICURLOPT_FOLLOWLOCATION(3)\fP and handling redirects
sanitizing where necessary. itself, sanitizing where necessary.
Use of the CURLAUTH_ANY option to CURLOPT_HTTPAUTH could result in user Use of the CURLAUTH_ANY option to \fICURLOPT_HTTPAUTH(3)\fP could result in
name and password being sent in clear text to an HTTP server. Instead, user name and password being sent in clear text to an HTTP server. Instead,
use CURLAUTH_ANYSAFE which ensures that the password is encrypted over use CURLAUTH_ANYSAFE which ensures that the password is encrypted over the
the network, or else fail the request. network, or else fail the request.
Use of the CURLUSESSL_TRY option to CURLOPT_USE_SSL could result in user Use of the CURLUSESSL_TRY option to \fICURLOPT_USE_SSL(3)\fP could result in
name and password being sent in clear text to an FTP server. Instead, user name and password being sent in clear text to an FTP server. Instead,
use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else
else fail the request. fail the request.
.IP Cookies .IP Cookies
If cookies are enabled and cached, then a user could craft a URL which If cookies are enabled and cached, then a user could craft a URL which
@@ -1227,34 +1232,35 @@ scp://user:pass@host/a;date >/tmp/test;
Apps must not allow unsanitized SCP: URLs to be passed in for downloads. Apps must not allow unsanitized SCP: URLs to be passed in for downloads.
.IP "Denial of Service" .IP "Denial of Service"
A malicious server could cause libcurl to effectively hang by sending A malicious server could cause libcurl to effectively hang by sending a
a trickle of data through, or even no data at all but just keeping the TCP trickle of data through, or even no data at all but just keeping the TCP
connection open. This could result in a denial-of-service attack. The connection open. This could result in a denial-of-service attack. The
CURLOPT_TIMEOUT and/or CURLOPT_LOW_SPEED_LIMIT options can be used to \fICURLOPT_TIMEOUT(3)\fP and/or \fICURLOPT_LOW_SPEED_LIMIT(3)\fP options can
mitigate against this. be used to mitigate against this.
A malicious server could cause libcurl to effectively hang by starting to A malicious server could cause libcurl to effectively hang by starting to send
send data, then severing the connection without cleanly closing the data, then severing the connection without cleanly closing the TCP connection.
TCP connection. The app could install a CURLOPT_SOCKOPTFUNCTION callback The app could install a \fICURLOPT_SOCKOPTFUNCTION(3)\fP callback function and
function and set the TCP SO_KEEPALIVE option to mitigate against this. set the TCP SO_KEEPALIVE option to mitigate against this. Setting one of the
Setting one of the timeout options would also work against this attack. timeout options would also work against this attack.
A malicious server could cause libcurl to download an infinite amount of A malicious server could cause libcurl to download an infinite amount of data,
data, potentially causing all of memory or disk to be filled. Setting potentially causing all of memory or disk to be filled. Setting the
the CURLOPT_MAXFILESIZE_LARGE option is not sufficient to guard against this. \fICURLOPT_MAXFILESIZE_LARGE(3)\fP option is not sufficient to guard against
Instead, the app should monitor the amount of data received within the this. Instead, the app should monitor the amount of data received within the
write or progress callback and abort once the limit is reached. write or progress callback and abort once the limit is reached.
A malicious HTTP server could cause an infinite redirection loop, causing a A malicious HTTP server could cause an infinite redirection loop, causing a
denial-of-service. This can be mitigated by using the CURLOPT_MAXREDIRS denial-of-service. This can be mitigated by using the
option. \fICURLOPT_MAXREDIRS(3)\fP option.
.IP "Arbitrary Headers" .IP "Arbitrary Headers"
User-supplied data must be sanitized when used in options like User-supplied data must be sanitized when used in options like
CURLOPT_USERAGENT, CURLOPT_HTTPHEADER, CURLOPT_POSTFIELDS and others that \fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_HTTPHEADER(3)\fP,
are used to generate structured data. Characters like embedded carriage \fICURLOPT_POSTFIELDS(3)\fP and others that are used to generate structured
returns or ampersands could allow the user to create additional headers or data. Characters like embedded carriage returns or ampersands could allow the
fields that could cause malicious transactions. user to create additional headers or fields that could cause malicious
transactions.
.IP "Server-supplied Names" .IP "Server-supplied Names"
A server can supply data which the application may, in some cases, use as A server can supply data which the application may, in some cases, use as
@@ -1266,9 +1272,9 @@ names to avoid the possibility of a malicious server supplying one like
"/etc/passwd", "\\autoexec.bat", "prn:" or even ".bashrc". "/etc/passwd", "\\autoexec.bat", "prn:" or even ".bashrc".
.IP "Server Certificates" .IP "Server Certificates"
A secure application should never use the CURLOPT_SSL_VERIFYPEER option to A secure application should never use the \fICURLOPT_SSL_VERIFYPEER(3)\fP
disable certificate validation. There are numerous attacks that are enabled option to disable certificate validation. There are numerous attacks that are
by apps that fail to properly validate server TLS/SSL certificates, enabled by apps that fail to properly validate server TLS/SSL certificates,
thus enabling a malicious server to spoof a legitimate one. HTTPS without thus enabling a malicious server to spoof a legitimate one. HTTPS without
validated certificates is potentially as insecure as a plain HTTP connection. validated certificates is potentially as insecure as a plain HTTP connection.