curl_easy_setopt.3

.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at http://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * $Id$
.\" **************************************************************************
.\"
.TH curl_easy_setopt 3 "11 Dec 2008" "libcurl 7.19.3" "libcurl Manual"
.SH NAME
curl_easy_setopt \- set options for a curl easy handle
.SH SYNOPSIS
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
.SH DESCRIPTION
curl_easy_setopt() is used to tell libcurl how to behave. By using the
appropriate options to \fIcurl_easy_setopt\fP, you can change libcurl's
behavior.  All options are set with the \fIoption\fP followed by a
\fIparameter\fP. That parameter can be a \fBlong\fP, a \fBfunction pointer\fP,
an \fBobject pointer\fP or a \fBcurl_off_t\fP, depending on what the specific
option expects. Read this manual carefully as bad input values may cause
libcurl to behave badly!  You can only set one option in each function call. A
typical application uses many curl_easy_setopt() calls in the setup phase.

Options set with this function call are valid for all forthcoming transfers
performed using this \fIhandle\fP.  The options are not in any way reset
between transfers, so if you want subsequent transfers with different options,
you must change them between the transfers. You can optionally reset all
options back to internal default with \fIcurl_easy_reset(3)\fP.

Strings passed to libcurl as 'char *' arguments, are copied by the library;
thus the string storage associated to the pointer argument may be overwritten
after curl_easy_setopt() returns. Exceptions to this rule are described in
the option details below.

NOTE: before 7.17.0 strings were not copied. Instead the user was forced keep
them available until libcurl no longer needed them.

The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or
\fIcurl_easy_duphandle(3)\fP call.
.SH BEHAVIOR OPTIONS
.IP CURLOPT_VERBOSE
Set the parameter to 1 to get the library to display a lot of verbose
information about its operations. Very useful for libcurl and/or protocol
debugging and understanding. The verbose information will be sent to stderr,
or the stream set with \fICURLOPT_STDERR\fP.

You hardly ever want this set in production use, you will almost always want
this when you debug/report problems. Another neat option for debugging is the
\fICURLOPT_DEBUGFUNCTION\fP.
.IP CURLOPT_HEADER
A parameter set to 1 tells the library to include the header in the body
output. This is only relevant for protocols that actually have headers
preceding the data (like HTTP).
.IP CURLOPT_NOPROGRESS
A parameter set to 1 tells the library to shut off the built-in progress meter
completely.

Future versions of libcurl are likely to not have any built-in progress meter
at all.
.IP CURLOPT_NOSIGNAL
Pass a long. If it is 1, libcurl will not use any functions that
install signal handlers or any functions that cause signals to be sent to the
process. This option is mainly here to allow multi-threaded unix applications
to still set/use all timeout options etc, without risking getting signals.
(Added in 7.10)

If this option is set and libcurl has been built with the standard name
resolver, timeouts will not occur while the name resolve takes place.
Consider building libcurl with c-ares support to enable asynchronous DNS
lookups, which enables nice timeouts for name resolves without signals.
.PP
.SH CALLBACK OPTIONS
.IP CURLOPT_WRITEFUNCTION
Function pointer that should match the following prototype: \fBsize_t
function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This
function gets called by libcurl as soon as there is data received that needs
to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP
multiplied with \fInmemb\fP, it will not be zero terminated. Return the number
of bytes actually taken care of. If that amount differs from the amount passed
to your function, it'll signal an error to the library and it will abort the
transfer and return \fICURLE_WRITE_ERROR\fP.

From 7.18.0, the function can return CURL_WRITEFUNC_PAUSE which then will
cause writing to this connection to become paused. See
\fIcurl_easy_pause(3)\fP for further details.

This function may be called with zero bytes data if the transferred file is
empty.

Set this option to NULL to get the internal default function. The internal
default function will write the data to the FILE * given with
\fICURLOPT_WRITEDATA\fP.

Set the \fIstream\fP argument with the \fICURLOPT_WRITEDATA\fP option.

The callback function will be passed as much data as possible in all invokes,
but you cannot possibly make any assumptions. It may be one byte, it may be
thousands. The maximum amount of data that can be passed to the write callback
is defined in the curl.h header file: CURL_MAX_WRITE_SIZE.
.IP CURLOPT_WRITEDATA
Data pointer to pass to the file write function. If you use the
\fICURLOPT_WRITEFUNCTION\fP option, this is the pointer you'll get as
input. If you don't use a callback, you must pass a 'FILE *' as libcurl will
pass this to fwrite() when writing data.

The internal \fICURLOPT_WRITEFUNCTION\fP will write the data to the FILE *
given with this option, or to stdout if this option hasn't been set.

If you're using libcurl as a win32 DLL, you \fBMUST\fP use the
\fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience
crashes.

This option is also known with the older name \fICURLOPT_FILE\fP, the name
\fICURLOPT_WRITEDATA\fP was introduced in 7.9.7.
.IP CURLOPT_READFUNCTION
Function pointer that should match the following prototype: \fBsize_t
function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This
function gets called by libcurl as soon as it needs to read data in order to
send it to the peer. The data area pointed at by the pointer \fIptr\fP may be
filled with at most \fIsize\fP multiplied with \fInmemb\fP number of
bytes. Your function must return the actual number of bytes that you stored in
that memory area. Returning 0 will signal end-of-file to the library and cause
it to stop the current transfer.

If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
server expected it, like when you've said you will upload N bytes and you
upload less than N bytes), you may experience that the server "hangs" waiting
for the rest of the data that won't come.

The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
code from the transfer (Added in 7.12.1)

From 7.18.0, the function can return CURL_READFUNC_PAUSE which then will cause
reading from this connection to become paused. See \fIcurl_easy_pause(3)\fP
for further details.

If you set the callback pointer to NULL, or don't set it at all, the default
internal read function will be used. It is simply doing an fread() on the FILE
* stream set with \fICURLOPT_READDATA\fP.
.IP CURLOPT_READDATA
Data pointer to pass to the file read function. If you use the
\fICURLOPT_READFUNCTION\fP option, this is the pointer you'll get as input. If
you don't specify a read callback but instead rely on the default internal
read function, this data must be a valid readable FILE *.

If you're using libcurl as a win32 DLL, you MUST use a
\fICURLOPT_READFUNCTION\fP if you set this option.

This option was also known by the older name \fICURLOPT_INFILE\fP, the name
\fICURLOPT_READDATA\fP was introduced in 7.9.7.
.IP CURLOPT_IOCTLFUNCTION
Function pointer that should match the \fIcurl_ioctl_callback\fP prototype
found in \fI<curl/curl.h>\fP. This function gets called by libcurl when
something special I/O-related needs to be done that the library can't do by
itself. For now, rewinding the read data stream is the only action it can
request. The rewinding of the read data stream may be necessary when doing a
HTTP PUT or POST with a multi-pass authentication method.  (Option added in
7.12.3).

Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking!
.IP CURLOPT_IOCTLDATA
Pass a pointer that will be untouched by libcurl and passed as the 3rd
argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP.  (Option
added in 7.12.3)
.IP CURLOPT_SEEKFUNCTION
Function pointer that should match the following prototype: \fIint
function(void *instream, curl_off_t offset, int origin);\fP This function gets
called by libcurl to seek to a certain position in the input stream and can be
used to fast forward a file in a resumed upload (instead of reading all
uploaded bytes with the normal read function/callback). It is also called to
rewind a stream when doing a HTTP PUT or POST with a multi-pass authentication
method. The function shall work like "fseek" or "lseek" and accepted SEEK_SET,
SEEK_CUR and SEEK_END as argument for origin, although (in 7.18.0) libcurl
only passes SEEK_SET. The callback must return 0 (CURL_SEEKFUNC_OK) on
success, 1 (CURL_SEEKFUNC_FAIL) to cause the upload operation to fail or 2
(CURL_SEEKFUNC_CANTSEEK) to indicate that while the seek failed, libcurl is
free to work around the problem if possible. The latter can sometimes be done
by instead reading from the input or similar.

If you forward the input arguments directly to "fseek" or "lseek", note that
the data type for \fIoffset\fP is not the same as defined for curl_off_t on
many systems! (Option added in 7.18.0)
.IP CURLOPT_SEEKDATA
Data pointer to pass to the file read function. If you use the
\fICURLOPT_SEEKFUNCTION\fP option, this is the pointer you'll get as input. If
you don't specify a seek callback, NULL is passed. (Option added in 7.18.0)
.IP CURLOPT_SOCKOPTFUNCTION
Function pointer that should match the \fIcurl_sockopt_callback\fP prototype
found in \fI<curl/curl.h>\fP. This function gets called by libcurl after the
socket() call but before the connect() call. The callback's \fIpurpose\fP
argument identifies the exact purpose for this particular socket, and
currently only one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the
primary connection (meaning the control connection in the FTP case). Future
versions of libcurl may support more purposes. It passes the newly created
socket descriptor so additional setsockopt() calls can be done at the user's
discretion.  Return 0 (zero) from the callback on success. Return 1 from the
callback function to signal an unrecoverable error to the library and it will
close the socket and return \fICURLE_COULDNT_CONNECT\fP.  (Option added in
7.15.6.)
.IP CURLOPT_SOCKOPTDATA
Pass a pointer that will be untouched by libcurl and passed as the first
argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP.
(Option added in 7.15.6.)
.IP CURLOPT_OPENSOCKETFUNCTION
Function pointer that should match the \fIcurl_opensocket_callback\fP
prototype found in \fI<curl/curl.h>\fP. This function gets called by libcurl
instead of the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument
identifies the exact purpose for this particular socket, and currently only
one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the primary connection
(meaning the control connection in the FTP case). Future versions of libcurl
may support more purposes. It passes the resolved peer address as a
\fIaddress\fP argument so the callback can modify the address or refuse to
connect at all. The callback function should return the socket or
\fICURL_SOCKET_BAD\fP in case no connection should be established or any error
detected. Any additional \fIsetsockopt(2)\fP calls can be done on the socket
at the user's discretion.  \fICURL_SOCKET_BAD\fP return value from the
callback function will signal an unrecoverable error to the library and it
will return \fICURLE_COULDNT_CONNECT\fP.  This return code can be used for IP
address blacklisting.  The default behavior is:
.nf
   return socket(addr->family, addr->socktype, addr->protocol);
.fi
(Option added in 7.17.1.)
.IP CURLOPT_OPENSOCKETDATA
Pass a pointer that will be untouched by libcurl and passed as the first
argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION\fP.
(Option added in 7.17.1.)
.IP CURLOPT_PROGRESSFUNCTION
Function pointer that should match the \fIcurl_progress_callback\fP prototype
found in \fI<curl/curl.h>\fP. This function gets called by libcurl instead of
its internal equivalent with a frequent interval during operation (roughly
once per second) no matter if data is being transfered or not.  Unknown/unused
argument values passed to the callback will be set to zero (like if you only
download data, the upload size will remain 0). Returning a non-zero value from
this callback will cause libcurl to abort the transfer and return
\fICURLE_ABORTED_BY_CALLBACK\fP.

If you transfer data with the multi interface, this function will not be
called during periods of idleness unless you call the appropriate libcurl
function that performs transfers.

\fICURLOPT_NOPROGRESS\fP must be set to 0 to make this function actually
get called.
.IP CURLOPT_PROGRESSDATA
Pass a pointer that will be untouched by libcurl and passed as the first
argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP.
.IP CURLOPT_HEADERFUNCTION
Function pointer that should match the following prototype: \fIsize_t
function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This
function gets called by libcurl as soon as it has received header data. The
header callback will be called once for each header and only complete header
lines are passed on to the callback. Parsing headers should be easy enough
using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP
multiplied with \fInmemb\fP. Do not assume that the header line is zero
terminated! The pointer named \fIstream\fP is the one you set with the
\fICURLOPT_WRITEHEADER\fP option. The callback function must return the number
of bytes actually taken care of, or return -1 to signal error to the library
(it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return
code).

If this option is not set, or if it is set to NULL, but
\fICURLOPT_HEADERDATA\fP (\fICURLOPT_WRITEHEADER\fP) is set to anything but
NULL, the function used to accept response data will be used instead. That is,
it will be the function specified with \fICURLOPT_WRITEFUNCTION\fP, or if it
is not specified or NULL - the default, stream-writing function.

It's important to note that the callback will be invoked for the headers of
all responses received after initiating a request and not just the final
response. This includes all responses which occur during authentication
negotiation. If you need to operate on only the headers from the final
response, you will need to collect headers in the callback yourself and use
HTTP status lines, for example, to delimit response boundaries.

Since 7.14.1: When a server sends a chunked encoded transfer, it may contain a
trailer. That trailer is identical to a HTTP header and if such a trailer is
received it is passed to the application using this callback as well. There
are several ways to detect it being a trailer and not an ordinary header: 1)
it comes after the response-body. 2) it comes after the final header line (CR
LF) 3) a Trailer: header among the response-headers mention what header to
expect in the trailer.
.IP CURLOPT_WRITEHEADER
(This option is also known as \fBCURLOPT_HEADERDATA\fP) Pass a pointer to be
used to write the header part of the received data to. If you don't use your
own callback to take care of the writing, this must be a valid FILE *. See
also the \fICURLOPT_HEADERFUNCTION\fP option above on how to set a custom
get-all-headers callback.
.IP CURLOPT_DEBUGFUNCTION
Function pointer that should match the following prototype: \fIint
curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP
\fICURLOPT_DEBUGFUNCTION\fP replaces the standard debug function used when
\fICURLOPT_VERBOSE \fP is in effect. This callback receives debug information,
as specified with the \fBcurl_infotype\fP argument. This function must return
0.  The data pointed to by the char * passed to this function WILL NOT be zero
terminated, but will be exactly of the size as told by the size_t argument.

Available curl_infotype values:
.RS
.IP CURLINFO_TEXT
The data is informational text.
.IP CURLINFO_HEADER_IN
The data is header (or header-like) data received from the peer.
.IP CURLINFO_HEADER_OUT
The data is header (or header-like) data sent to the peer.
.IP CURLINFO_DATA_IN
The data is protocol data received from the peer.
.IP CURLINFO_DATA_OUT
The data is protocol data sent to the peer.
.RE
.IP CURLOPT_DEBUGDATA
Pass a pointer to whatever you want passed in to your
\fICURLOPT_DEBUGFUNCTION\fP in the last void * argument. This pointer is not
used by libcurl, it is only passed to the callback.
.IP CURLOPT_SSL_CTX_FUNCTION
This option does only function for libcurl powered by OpenSSL. If libcurl was
built against another SSL library, this functionality is absent.

Function pointer that should match the following prototype: \fBCURLcode
sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This 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 behaviour of openssl's ssl initialization. The
\fIsslctx\fP parameter is actually a pointer to an openssl \fISSL_CTX\fP. If
an error is returned no attempt to establish a connection is made and the
perform operation will return the error code from this callback function.  Set
the \fIparm\fP argument with the \fICURLOPT_SSL_CTX_DATA\fP option. This
option was introduced in 7.11.0.

This function will get called on all new connections made to a server, during
the SSL negotiation. The SSL_CTX pointer will be a new one every time.

To use this properly, a non-trivial amount of knowledge of the openssl
libraries is necessary. For example, using this function allows you to use openssl
callbacks to add additional validation code for certificates, and even to
change the actual URI of an HTTPS request (example used in the lib509 test
case).  See also the example section for a replacement of the key, certificate
and trust file settings.
.IP CURLOPT_SSL_CTX_DATA
Data pointer to pass to the ssl context callback set by the option
\fICURLOPT_SSL_CTX_FUNCTION\fP, this is the pointer you'll get as third
parameter, otherwise \fBNULL\fP. (Added in 7.11.0)
.IP CURLOPT_CONV_TO_NETWORK_FUNCTION
.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION
.IP CURLOPT_CONV_FROM_UTF8_FUNCTION
Function pointers that should match the following prototype: CURLcode
function(char *ptr, size_t length);

These three options apply to non-ASCII platforms only.  They are available
only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. When
this is the case, \fIcurl_version_info(3)\fP will return the CURL_VERSION_CONV
feature bit set.

The data to be converted is in a buffer pointed to by the ptr parameter.  The
amount of data to convert is indicated by the length parameter.  The converted
data overlays the input data in the buffer pointed to by the ptr parameter.
CURLE_OK should be returned upon successful conversion.  A CURLcode return
value defined by curl.h, such as CURLE_CONV_FAILED, should be returned if an
error was encountered.

\fBCURLOPT_CONV_TO_NETWORK_FUNCTION\fP and
\fBCURLOPT_CONV_FROM_NETWORK_FUNCTION\fP convert between the host encoding and
the network encoding.  They are used when commands or ASCII data are
sent/received over the network.

\fBCURLOPT_CONV_FROM_UTF8_FUNCTION\fP is called to convert from UTF8 into the
host encoding.  It is required only for SSL processing.

If you set a callback pointer to NULL, or don't set it at all, the built-in
libcurl iconv functions will be used.  If HAVE_ICONV was not defined when
libcurl was built, and no callback has been established, conversion will
return the CURLE_CONV_REQD error code.

If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined.
For example:

 \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"

The iconv code in libcurl will default the network and UTF8 codeset names as
follows:

 \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"

 \&#define CURL_ICONV_CODESET_FOR_UTF8   "UTF-8"

You will need to override these definitions if they are different on your
system.
.SH ERROR OPTIONS
.IP CURLOPT_ERRORBUFFER
Pass a char * to a buffer that the libcurl may store human readable error
messages in. This may be more helpful than just the return code from
\fIcurl_easy_perform\fP. The buffer must be at least CURL_ERROR_SIZE big.
Although this argument is a 'char *', it does not describe an input string.
Therefore the (probably undefined) contents of the buffer is NOT copied
by the library. You should keep the associated storage available until
libcurl no longer needs it. Failing to do so will cause very odd behavior
or even crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP
or you set the same option again to use a different pointer. 

Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better
debug/trace why errors happen.

If the library does not return an error, the buffer may not have been
touched. Do not rely on the contents in those cases.

.IP CURLOPT_STDERR
Pass a FILE * as parameter. Tell libcurl to use this stream instead of stderr
when showing the progress meter and displaying \fICURLOPT_VERBOSE\fP data.
.IP CURLOPT_FAILONERROR
A parameter set to 1 tells the library to fail silently if the HTTP code
returned is equal to or larger than 400. The default action would be to return
the page normally, ignoring that code.

This method is not fail-safe and there are occasions where non-successful
response codes will slip through, especially when authentication is involved
(response codes 401 and 407).

You might get some amounts of headers transferred before this situation is
detected, like when a "100-continue" is received as a response to a
POST/PUT and a 401 or 407 is received immediately afterwards.
.SH NETWORK OPTIONS
.IP CURLOPT_URL
The actual URL to deal with. The parameter should be a char * to a zero
terminated string.

If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will
attempt to guess which protocol to use based on the given host name. If the
given protocol of the set URL is not supported, libcurl will return on error
(\fICURLE_UNSUPPORTED_PROTOCOL\fP) when you call \fIcurl_easy_perform(3)\fP or
\fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed info
on which protocols are supported.

The string given to CURLOPT_URL must be url-encoded and follow RFC 2396
(http://curl.haxx.se/rfc/rfc2396.txt).

\fICURLOPT_URL\fP is the only option that \fBmust\fP be set before
\fIcurl_easy_perform(3)\fP is called.

\fICURLOPT_PROTOCOLS\fP can be used to limit what protocols libcurl will use
for this transfer, independent of what libcurl has been compiled to
support. That may be useful if you accept the URL from an external source and
want to limit the accessibility.
.IP CURLOPT_PROTOCOLS
Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask
limits what protocols libcurl may use in the transfer. This allows you to have
a libcurl built to support a wide range of protocols but still limit specific
transfers to only be allowed to use a subset of them. By default libcurl will
accept all protocols it supports. See also
\fICURLOPT_REDIR_PROTOCOLS\fP. (Added in 7.19.4)
.IP CURLOPT_REDIR_PROTOCOLS
Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask
limits what protocols libcurl may use in a transfer that it follows to in a
redirect when \fICURLOPT_FOLLOWLOCATION\fP is enabled. This allows you to
limit specific transfers to only be allowed to use a subset of protocols in
redirections. By default libcurl will allow all protocols except for FILE and
SCP. This is a difference compared to pre-7.19.4 versions which
unconditionally would follow to all protocols supported. (Added in 7.19.4)
.IP CURLOPT_PROXY
Set HTTP proxy to use. The parameter should be a char * to a zero terminated
string holding the host name or dotted IP address. To specify port number in
this string, append :[port] to the end of the host name. The proxy string may
be prefixed with [protocol]:// since any such prefix will be ignored. The
proxy's port number may optionally be specified with the separate option. If
not specified, libcurl will default to using port 1080 for proxies.
\fICURLOPT_PROXYPORT\fP.

When you tell the library to use an HTTP proxy, libcurl will transparently
convert operations to HTTP even if you specify an FTP URL etc. This may have
an impact on what other features of the library you can use, such as
\fICURLOPT_QUOTE\fP and similar FTP specifics that don't work unless you
tunnel through the HTTP proxy. Such tunneling is activated with
\fICURLOPT_HTTPPROXYTUNNEL\fP.

libcurl respects the environment variables \fBhttp_proxy\fP, \fBftp_proxy\fP,
\fBall_proxy\fP etc, if any of those are set. The \fICURLOPT_PROXY\fP option
does however override any possibly set environment variables.

Setting the proxy string to "" (an empty string) will explicitly disable the
use of a proxy, even if there is an environment variable set for it.

Since 7.14.1, the proxy host string given in environment variables can be
specified the exact same way as the proxy can be set with \fICURLOPT_PROXY\fP,
include protocol prefix (http://) and embedded user + password.
.IP CURLOPT_PROXYPORT
Pass a long with this option to set the proxy port to connect to unless it is
specified in the proxy string \fICURLOPT_PROXY\fP.
.IP CURLOPT_PROXYTYPE
Pass a long with this option to set type of the proxy. Available options for
this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_HTTP_1_0\fP (added in 7.19.4),
\fICURLPROXY_SOCKS4\fP (added in 7.15.2), \fICURLPROXY_SOCKS5\fP,
\fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and \fICURLPROXY_SOCKS5_HOSTNAME\fP
(added in 7.18.0). The HTTP type is default. (Added in 7.10)
.IP CURLOPT_NOPROXY
Pass a pointer to a zero terminated string. The should be a comma- separated
list of hosts which do not use a proxy, if one is specified.  The only
wildcard is a single * character, which matches all hosts, and effectively
disables the proxy. Each name in this list is matched as either a domain which
contains the hostname, or the hostname itself. For example, local.com would
match local.com, local.com:80, and www.local.com, but not www.notlocal.com.
(Added in 7.19.4)
.IP CURLOPT_HTTPPROXYTUNNEL
Set the parameter to 1 to make the library tunnel all operations through a
given HTTP proxy. There is a big difference between using a proxy and to
tunnel through it. If you don't know what this means, you probably don't want
this tunneling option.
.IP CURLOPT_SOCKS5_GSSAPI_SERVICE
Pass a char * as parameter to a string holding the name of the service. The
default service name for a SOCKS5 server is rcmd/server-fqdn. This option
allows you to change it. (Added in 7.19.4)
.IP CURLOPT_SOCKS5_GSSAPI_NEC
Pass a long set to 1 to enable or 0 to disable. As part of the gssapi
negotiation a protection mode is negotiated. The rfc1961 says in section
4.3/4.4 it should be protected, but the NEC reference implementation does not.
If enabled, this option allows the unprotected exchange of the protection mode
negotiation. (Added in 7.19.4).
.IP CURLOPT_INTERFACE
Pass a char * as parameter. This sets the interface name to use as outgoing
network interface. The name can be an interface name, an IP address, or a host
name.
.IP CURLOPT_LOCALPORT
Pass a long. This sets the local port number of the socket used for
connection. This can be used in combination with \fICURLOPT_INTERFACE\fP and
you are recommended to use \fICURLOPT_LOCALPORTRANGE\fP as well when this is
set. Note that the only valid port numbers are 1 - 65535. (Added in 7.15.2)
.IP CURLOPT_LOCALPORTRANGE
Pass a long. This is the number of attempts libcurl should make to find a
working local port number. It starts with the given \fICURLOPT_LOCALPORT\fP
and adds one to the number for each retry. Setting this to 1 or below will
make libcurl do only one try for the exact port number. Note that port numbers
by nature are scarce resources that will be busy at times so setting this
value to something too low might cause unnecessary connection setup
failures. (Added in 7.15.2)
.IP CURLOPT_DNS_CACHE_TIMEOUT
Pass a long, this sets the timeout in seconds. Name resolves will be kept in
memory for this number of seconds. Set to zero to completely disable
caching, or set to -1 to make the cached entries remain forever. By default,
libcurl caches this info for 60 seconds.

NOTE: the name resolve functions of various libc implementations don't re-read
name server information unless explicitly told so (for example, by calling
\fIres_init(3)\fP). This may cause libcurl to keep using the older server even
if DHCP has updated the server info, and this may look like a DNS cache issue
to the casual libcurl-app user.
.IP CURLOPT_DNS_USE_GLOBAL_CACHE
Pass a long. If the value is 1, it tells curl to use a global DNS cache
that will survive between easy handle creations and deletions. This is not
thread-safe and this will use a global variable.

\fBWARNING:\fP this option is considered obsolete. Stop using it. Switch over
to using the share interface instead! See \fICURLOPT_SHARE\fP and
\fIcurl_share_init(3)\fP.
.IP CURLOPT_BUFFERSIZE
Pass a long specifying your preferred size (in bytes) for the receive buffer
in libcurl.  The main point of this would be that the write callback gets
called more often and with smaller chunks. This is just treated as a request,
not an order. You cannot be guaranteed to actually get the given size. (Added
in 7.10)

This size is by default set as big as possible (CURL_MAX_WRITE_SIZE), so it
only makes sense to use this option if you want it smaller.
.IP CURLOPT_PORT
Pass a long specifying what remote port number to connect to, instead of the
one specified in the URL or the default port for the used protocol.
.IP CURLOPT_TCP_NODELAY
Pass a long specifying whether the TCP_NODELAY option should be set or
cleared (1 = set, 0 = clear). The option is cleared by default. This
will have no effect after the connection has been established.

Setting this option will disable TCP's Nagle algorithm. The purpose of
this algorithm is to try to minimize the number of small packets on
the network (where "small packets" means TCP segments less than the
Maximum Segment Size (MSS) for the network).

Maximizing the amount of data sent per TCP segment is good because it
amortizes the overhead of the send. However, in some cases (most
notably telnet or rlogin) small segments may need to be sent
without delay. This is less efficient than sending larger amounts of
data at a time, and can contribute to congestion on the network if
overdone.
.IP CURLOPT_ADDRESS_SCOPE
Pass a long specifying the scope_id value to use when connecting to IPv6
link-local or site-local addresses. (Added in 7.19.0)
.SH NAMES and PASSWORDS OPTIONS (Authentication)
.IP CURLOPT_NETRC
This parameter controls the preference of libcurl between using user names and
passwords from your \fI~/.netrc\fP file, relative to user names and passwords
in the URL supplied with \fICURLOPT_URL\fP.

libcurl uses a user name (and supplied or prompted password) supplied with
\fICURLOPT_USERPWD\fP in preference to any of the options controlled by this
parameter.

Pass a long, set to one of the values described below.
.RS
.IP CURL_NETRC_OPTIONAL
The use of your \fI~/.netrc\fP file is optional, and information in the URL is
to be preferred.  The file will be scanned for the host and user name (to
find the password only) or for the host only, to find the first user name and
password after that \fImachine\fP, which ever information is not specified in
the URL.

Undefined values of the option will have this effect.
.IP CURL_NETRC_IGNORED
The library will ignore the file and use only the information in the URL.

This is the default.
.IP CURL_NETRC_REQUIRED
This value tells the library that use of the file is required, to ignore the
information in the URL, and to search the file for the host only.
.RE
Only machine name, user name and password are taken into account
(init macros and similar things aren't supported).

libcurl does not verify that the file has the correct properties set (as the
standard Unix ftp client does). It should only be readable by user.
.IP CURLOPT_NETRC_FILE
Pass a char * as parameter, pointing to a zero terminated string containing
the full path name to the file you want libcurl to use as .netrc file. If this
option is omitted, and \fICURLOPT_NETRC\fP is set, libcurl will attempt to
find a .netrc file in the current user's home directory. (Added in 7.10.9)
.IP CURLOPT_USERPWD
Pass a char * as parameter, which should be [user name]:[password] to use for
the connection. Use \fICURLOPT_HTTPAUTH\fP to decide the authentication method.

When using NTLM, you can set the domain by prepending it to the user name and
separating the domain and name with a forward (/) or backward slash (\\). Like
this: "domain/user:password" or "domain\\user:password". Some HTTP servers (on
Windows) support this style even for Basic authentication.

When using HTTP and \fICURLOPT_FOLLOWLOCATION\fP, libcurl might perform
several requests to possibly different hosts. libcurl will only send this user
and password information to hosts using the initial host name (unless
\fICURLOPT_UNRESTRICTED_AUTH\fP is set), so if libcurl follows locations to
other hosts it will not send the user and password to those. This is enforced
to prevent accidental information leakage.
.IP CURLOPT_PROXYUSERPWD
Pass a char * as parameter, which should be [user name]:[password] to use for
the connection to the HTTP proxy.  Use \fICURLOPT_PROXYAUTH\fP to decide
the authentication method.
.IP CURLOPT_USERNAME
Pass a char * as parameter, which should be pointing to the zero terminated
user name to use for the transfer.

\fBCURLOPT_USERNAME\fP sets the user name to be used in protocol
authentication. You should not use this option together with the (older)
CURLOPT_USERPWD option.

In order to specify the password to be used in conjunction with the user name
use the \fICURLOPT_PASSWORD\fP option.  (Added in 7.19.1)
.IP CURLOPT_PASSWORD
Pass a char * as parameter, which should be pointing to the zero terminated
password to use for the transfer.

The CURLOPT_PASSWORD option should be used in conjunction with
the \fICURLOPT_USERNAME\fP option. (Added in 7.19.1)
.IP CURLOPT_PROXYUSERNAME
Pass a char * as parameter, which should be pointing to the zero terminated
user name to use for the transfer while connecting to Proxy.

The CURLOPT_PROXYUSERNAME option should be used in same way as the
\fICURLOPT_PROXYUSERPWD\fP is used.  In comparison to \fICURLOPT_PROXYUSERPWD\fP
the CURLOPT_PROXYUSERNAME allows the username to contain a colon,
like in the following example: "sip:user@example.com".
Note the CURLOPT_PROXYUSERNAME option is an alternative way to set the user name
while connecting to Proxy.  There is no meaning to use it together
with the \fICURLOPT_PROXYUSERPWD\fP option.

In order to specify the password to be used in conjunction with the user name
use the \fICURLOPT_PROXYPASSWORD\fP option.  (Added in 7.19.1)
.IP CURLOPT_PROXYPASSWORD
Pass a char * as parameter, which should be pointing to the zero terminated
password to use for the transfer while connecting to Proxy.

The CURLOPT_PROXYPASSWORD option should be used in conjunction with
the \fICURLOPT_PROXYUSERNAME\fP option. (Added in 7.19.1)
.IP CURLOPT_HTTPAUTH
Pass a long as parameter, which is set to a bitmask, to tell libcurl which
authentication method(s) you want it to use. The available bits are listed
below. If more than one bit is set, libcurl will first query the site to see
which authentication methods it supports and then pick the best one you allow
it to use. For some methods, this will induce an extra network round-trip. Set
the actual name and password with the \fICURLOPT_USERPWD\fP option or
with the \fICURLOPT_USERNAME\fP and the \fICURLOPT_USERPASSWORD\fP options.
(Added in 7.10.6)
.RS
.IP CURLAUTH_BASIC
HTTP Basic authentication. This is the default choice, and the only method
that is in wide-spread use and supported virtually everywhere. This sends
the user name and password over the network in plain text, easily captured by
others.
.IP CURLAUTH_DIGEST
HTTP Digest authentication.  Digest authentication is defined in RFC2617 and
is a more secure way to do authentication over public networks than the
regular old-fashioned Basic method.
.IP CURLAUTH_DIGEST_IE
HTTP Digest authentication with an IE flavor.  Digest authentication is
defined in RFC2617 and is a more secure way to do authentication over public
networks than the regular old-fashioned Basic method. The IE flavor is simply
that libcurl will use a special "quirk" that IE is known to have used before
version 7 and that some servers require the client to use. (This define was
added in 7.19.3)
.IP CURLAUTH_GSSNEGOTIATE
HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain
\&"Negotiate") method was designed by Microsoft and is used in their web
applications. It is primarily meant as a support for Kerberos5 authentication
but may also be used along with other authentication methods. For more
information see IETF draft draft-brezak-spnego-http-04.txt.

You need to build libcurl with a suitable GSS-API library for this to work.
.IP CURLAUTH_NTLM
HTTP NTLM authentication. A proprietary protocol invented and used by
Microsoft. It uses a challenge-response and hash concept similar to Digest, to
prevent the password from being eavesdropped.

You need to build libcurl with OpenSSL support for this option to work, or
build libcurl on Windows.
.IP CURLAUTH_ANY
This is a convenience macro that sets all bits and thus makes libcurl pick any
it finds suitable. libcurl will automatically select the one it finds most
secure.
.IP CURLAUTH_ANYSAFE
This is a convenience macro that sets all bits except Basic and thus makes
libcurl pick any it finds suitable. libcurl will automatically select the one it
finds most secure.
.RE
.IP CURLOPT_PROXYAUTH
Pass a long as parameter, which is set to a bitmask, to tell libcurl which
authentication method(s) you want it to use for your proxy authentication.  If
more than one bit is set, libcurl will first query the site to see what
authentication methods it supports and then pick the best one you allow it to
use. For some methods, this will induce an extra network round-trip. Set the
actual name and password with the \fICURLOPT_PROXYUSERPWD\fP option. The
bitmask can be constructed by or'ing together the bits listed above for the
\fICURLOPT_HTTPAUTH\fP option. As of this writing, only Basic, Digest and NTLM
work. (Added in 7.10.7)
.SH HTTP OPTIONS
.IP CURLOPT_AUTOREFERER
Pass a parameter set to 1 to enable this. When enabled, libcurl will
automatically set the Referer: field in requests where it follows a Location:
redirect.
.IP CURLOPT_ENCODING
Sets the contents of the Accept-Encoding: header sent in an HTTP request, and
enables decoding of a response when a Content-Encoding: header is received.
Three encodings are supported: \fIidentity\fP, which does nothing,
\fIdeflate\fP which requests the server to compress its response using the
zlib algorithm, and \fIgzip\fP which requests the gzip algorithm.  If a
zero-length string is set, then an Accept-Encoding: header containing all
supported encodings is sent.

This is a request, not an order; the server may or may not do it.  This option
must be set (to any non-NULL value) or else any unsolicited encoding done by
the server is ignored. See the special file lib/README.encoding for details.
.IP CURLOPT_FOLLOWLOCATION
A parameter set to 1 tells the library to follow any Location: header that the
server sends as part of an HTTP header.

This means that the library will re-send the same request on the new location
and follow new Location: headers all the way until no more such headers are
returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number of redirects
libcurl will follow.

NOTE: since 7.19.4, libcurl can limit to what protocols it will automatically
follow. The accepted protocols are set with \fICURLOPT_REDIR_PROTOCOLS\fP and
it excludes the FILE protocol by default.
.IP CURLOPT_UNRESTRICTED_AUTH
A parameter set to 1 tells the library it can continue to send authentication
(user+password) when following locations, even when hostname changed. This
option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP.
.IP CURLOPT_MAXREDIRS
Pass a long. The set number will be the redirection limit. If that many
redirections have been followed, the next redirect will cause an error
(\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the
\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. Added in 7.15.1:
Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for
an infinite number of redirects (which is the default)
.IP CURLOPT_POSTREDIR
Pass a bitmask to control how libcurl acts on redirects after POSTs that get a
301 or 302 response back.  A parameter with bit 0 set (value
\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 2616/10.3.2 and
not convert POST requests into GET requests when following a 301
redirection. Setting bit 1 (value CURL_REDIR_POST_302) makes libcurl maintain
the request method after a 302 redirect. CURL_REDIR_POST_ALL is a convenience
define that sets both bits.

The non-RFC behaviour is ubiquitous in web browsers, so the library does the
conversion by default to maintain consistency. However, a server may require a
POST to remain a POST after such a redirection. This option is meaningful only
when setting \fICURLOPT_FOLLOWLOCATION\fP.  (Added in 7.17.1) (This option was
known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 way before
then)
.IP CURLOPT_PUT
A parameter set to 1 tells the library to use HTTP PUT to transfer data. The
data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP.

This option is deprecated and starting with version 7.12.1 you should instead
use \fICURLOPT_UPLOAD\fP.
.IP CURLOPT_POST
A parameter set to 1 tells the library to do a regular HTTP post. This will
also make the library use a "Content-Type:
application/x-www-form-urlencoded" header. (This is by far the most commonly
used POST method).

Use one of \fICURLOPT_POSTFIELDS\fP or \fICURLOPT_COPYPOSTFIELDS\fP options to
specify what data to post and \fICURLOPT_POSTFIELDSIZE\fP or
\fICURLOPT_POSTFIELDSIZE_LARGE\fP to set the data size.

Optionally, you can provide data to POST using the \fICURLOPT_READFUNCTION\fP
and \fICURLOPT_READDATA\fP options but then you must make sure to not set
\fICURLOPT_POSTFIELDS\fP to anything but NULL. When providing data with a
callback, you must transmit it using chunked transfer-encoding or you must set
the size of the data with the \fICURLOPT_POSTFIELDSIZE\fP or
\fICURLOPT_POSTFIELDSIZE_LARGE\fP option. To enable chunked encoding, you
simply pass in the appropriate Transfer-Encoding header, see the
post-callback.c example.

You can override the default POST Content-Type: header by setting your own
with \fICURLOPT_HTTPHEADER\fP.

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.

If you use POST to a HTTP 1.1 server, you can send data without knowing the
size before starting the POST if you use chunked encoding. You enable this by
adding a header like "Transfer-Encoding: chunked" with
\fICURLOPT_HTTPHEADER\fP. With HTTP 1.0 or without chunked transfer, you must
specify the size in the request.

When setting \fICURLOPT_POST\fP to 1, it will automatically set
\fICURLOPT_NOBODY\fP to 0 (since 7.14.1).

If you issue a POST request and then want to make a HEAD or GET using the same
re-used handle, you must explicitly set the new request type using
\fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar.
.IP CURLOPT_POSTFIELDS
Pass a void * as parameter, which should be the full data to post in an HTTP
POST operation. You must make sure that the data is formatted the way you want
the server to receive it. libcurl will not convert or encode it for you. Most
web servers will assume this data to be url-encoded. Take note.

The pointed data are NOT copied by the library: as a consequence, they must
be preserved by the calling application until the transfer finishes.

This POST is a normal application/x-www-form-urlencoded kind (and libcurl will
set that Content-Type by default when this option is used), which is the most
commonly used one by HTML forms. See also the \fICURLOPT_POST\fP. Using
\fICURLOPT_POSTFIELDS\fP implies \fICURLOPT_POST\fP.

If you want to do a zero-byte POST, you need to set
\fICURLOPT_POSTFIELDSIZE\fP explicitly to zero, as simply setting
\fICURLOPT_POSTFIELDS\fP to NULL or "" just effectively disables the sending
of the specified string. libcurl will instead assume that you'll send the POST
data using the read callback!

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.

To make multipart/formdata posts (aka RFC2388-posts), check out the
\fICURLOPT_HTTPPOST\fP option.
.IP CURLOPT_POSTFIELDSIZE
If you want to post data to the server without letting libcurl do a strlen()
to measure the data size, this option must be used. When this option is used
you can post fully binary data, which otherwise is likely to fail. If this
size is set to -1, the library will use strlen() to get the size.
.IP CURLOPT_POSTFIELDSIZE_LARGE
Pass a curl_off_t as parameter. Use this to set the size of the
\fICURLOPT_POSTFIELDS\fP data to prevent libcurl from doing strlen() on the
data to figure out the size. This is the large file version of the
\fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1)
.IP CURLOPT_COPYPOSTFIELDS
Pass a char * as parameter, which should be the full data to post in an HTTP
POST operation. It behaves as the \fICURLOPT_POSTFIELDS\fP option, but the
original data are copied by the library, allowing the application to overwrite
the original data after setting this option.

Because data are copied, care must be taken when using this option in
conjunction with \fICURLOPT_POSTFIELDSIZE\fP or
\fICURLOPT_POSTFIELDSIZE_LARGE\fP: If the size has not been set prior to
\fICURLOPT_COPYPOSTFIELDS\fP, the data are assumed to be a NUL-terminated
string; else the stored size informs the library about the data byte count to
copy. In any case, the size must not be changed after
\fICURLOPT_COPYPOSTFIELDS\fP, unless another \fICURLOPT_POSTFIELDS\fP or
\fICURLOPT_COPYPOSTFIELDS\fP option is issued.
(Added in 7.17.1)
.IP CURLOPT_HTTPPOST
Tells libcurl you want a multipart/formdata HTTP POST to be made and you
instruct what data to pass on to the server.  Pass a pointer to a linked list
of curl_httppost structs as parameter.  The easiest way to create such a
list, is to use \fIcurl_formadd(3)\fP as documented. The data in this list
must remain intact until you close this curl handle again with
\fIcurl_easy_cleanup(3)\fP.

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.

When setting \fICURLOPT_HTTPPOST\fP, it will automatically set
\fICURLOPT_NOBODY\fP to 0 (since 7.14.1).
.IP CURLOPT_REFERER
Pass a pointer to a zero terminated string as parameter. It will be used to
set the Referer: header in the http request sent to the remote server. This
can be used to fool servers or scripts. You can also set any custom header
with \fICURLOPT_HTTPHEADER\fP.
.IP CURLOPT_USERAGENT
Pass a pointer to a zero terminated string as parameter. It will be used to
set the User-Agent: header in the http request sent to the remote server. This
can be used to fool servers or scripts. You can also set any custom header
with \fICURLOPT_HTTPHEADER\fP.
.IP CURLOPT_HTTPHEADER
Pass a pointer to a linked list of HTTP headers to pass to the server in your
HTTP request. The linked list should be a fully valid list of \fBstruct
curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to
create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire
list. If you add a header that is otherwise generated and used by libcurl
internally, your added one will be used instead. If you add a header with no
content as in 'Accept:' (no data on the right side of the colon), the
internally used header will get disabled. Thus, using this option you can add
new headers, replace internal headers and remove internal headers. To add a
header with no content, make the content be two quotes: \&"". The headers
included in the linked list must not be CRLF-terminated, because curl adds
CRLF after each header item. Failure to comply with this will result in
strange bugs because the server will most likely ignore part of the headers
you specified.

The first line in a request (containing the method, usually a GET or POST) is
not a header and cannot be replaced using this option. Only the lines
following the request-line are headers. Adding this method line in this list
of headers will only cause your request to send an invalid header.

Pass a NULL to this to reset back to no custom headers.

The most commonly replaced headers have "shortcuts" in the options
\fICURLOPT_COOKIE\fP, \fICURLOPT_USERAGENT\fP and \fICURLOPT_REFERER\fP.
.IP CURLOPT_HTTP200ALIASES
Pass a pointer to a linked list of aliases to be treated as valid HTTP 200
responses.  Some servers respond with a custom header response line.  For
example, IceCast servers respond with "ICY 200 OK".  By including this string
in your list of aliases, the response will be treated as a valid HTTP header
line such as "HTTP/1.0 200 OK". (Added in 7.10.3)

The linked list should be a fully valid list of struct curl_slist structs, and
be properly filled in.  Use \fIcurl_slist_append(3)\fP to create the list and
\fIcurl_slist_free_all(3)\fP to clean up an entire list.

The alias itself is not parsed for any version strings. Before libcurl 7.16.3,
Libcurl used the value set by option \fICURLOPT_HTTP_VERSION\fP, but starting
with 7.16.3 the protocol is assumed to match HTTP 1.0 when an alias matched.
.IP CURLOPT_COOKIE
Pass a pointer to a zero terminated string as parameter. It will be used to
set a cookie in the http request. The format of the string should be
NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie
should contain.

If you need to set multiple cookies, you need to set them all using a single
option and thus you need to concatenate them all in one single string. Set
multiple cookies in one string like this: "name1=content1; name2=content2;"
etc.

Note that this option sets the cookie header explictly in the outgoing
request(s). If multiple requests are done due to authentication, followed
redirections or similar, they will all get this cookie passed on.

Using this option multiple times will only make the latest string override the
previous ones.
.IP CURLOPT_COOKIEFILE
Pass a pointer to a zero terminated string as parameter. It should contain the
name of your file holding cookie data to read. The cookie data may be in
Netscape / Mozilla cookie data format or just regular HTTP-style headers
dumped to a file.

Given an empty or non-existing file or by passing the empty string (""), this
option will enable cookies for this curl handle, making it understand and
parse received cookies and then use matching cookies in future requests.

If you use this option multiple times, you just add more files to read.
Subsequent files will add more cookies.
.IP CURLOPT_COOKIEJAR
Pass a file name as char *, zero terminated. This will make libcurl write all
internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP
is called. If no cookies are known, no file will be created. Specify "-" to
instead have the cookies written to stdout. Using this option also enables
cookies for this session, so if you for example follow a location it will make
matching cookies get sent accordingly.

If the cookie jar file can't be created or written to (when the
\fIcurl_easy_cleanup(3)\fP is called), libcurl will not and cannot report an