libcurl Manual curleasysetopt(3)
NAME
curleasysetopt - set options for a curl easy handle
SYNOPSIS
#include
CURLcode curleasysetopt(CURL *handle, CURLoption option,
parameter);
DESCRIPTION
curleasysetopt() is used to tell libcurl how to behave. By
using the appropriate options to curleasysetopt, you can
change libcurl's behavior. All options are set with the
option followed by a parameter. That parameter can be a
long, a function pointer, an object pointer or a curlofft,
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 curleasysetopt()
calls in the setup phase.
Options set with this function call are valid for all forth-
coming transfers performed using this handle. 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 curleasyreset(3).
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 curleasysetopt()
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 handle is the return code from a curleasyinit(3) or
curleasyduphandle(3) call.
BEHAVIOR OPTIONS
CURLOPTVERBOSE
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 under-
standing. The verbose information will be sent to
stderr, or the stream set with CURLOPTSTDER.
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
libcurl 7.19.3 Last change: 11 Dec 2008 1
libcurl Manual curleasysetopt(3)
CURLOPTDEBUGFUNCTION.
CURLOPTHEADER
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 HTP).
CURLOPTNOPROGRES
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.
CURLOPTNOSIGNAL
Pass a long. If it is 1, libcurl will not use any func-
tions 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.
CALBACK OPTIONS
CURLOPTWRITEFUNCTION
Function pointer that should match the following proto-
type: sizet function( void *ptr, sizet size, sizet
nmemb, void *stream); This function gets called by lib-
curl as soon as there is data received that needs to be
saved. The size of the data pointed to by ptr is size
multiplied with nmemb, 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 CURLEWRITEROR.
From 7.18.0, the function can return
CURLWRITEFUNCPAUSE which then will cause writing to
this connection to become paused. See
curleasypause(3) for further details.
This function may be called with zero bytes data if the
transferred file is empty.
Set this option to NUL to get the internal default
libcurl 7.19.3 Last change: 11 Dec 2008 2
libcurl Manual curleasysetopt(3)
function. The internal default function will write the
data to the FILE * given with CURLOPTWRITEDATA.
Set the stream argument with the CURLOPTWRITEDATA
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: CURLMAXWRITESIZE.
CURLOPTWRITEDATA
Data pointer to pass to the file write function. If you
use the CURLOPTWRITEFUNCTION option, this is the
pointer you'll get as input. If you don't use a call-
back, you must pass a 'FILE *' as libcurl will pass
this to fwrite() when writing data.
The internal CURLOPTWRITEFUNCTION 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 DL, you MUST use
the CURLOPTWRITEFUNCTION if you set this option or you
will experience crashes.
This option is also known with the older name
CURLOPTFILE, the name CURLOPTWRITEDATA was introduced
in 7.9.7.
CURLOPTREADFUNCTION
Function pointer that should match the following proto-
type: sizet function( void *ptr, sizet size, sizet
nmemb, void *stream); This function gets called by lib-
curl as soon as it needs to read data in order to send
it to the peer. The data area pointed at by the pointer
ptr may be filled with at most size multiplied with
nmemb 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 CURLREADFUNCABORT to
libcurl 7.19.3 Last change: 11 Dec 2008 3
libcurl Manual curleasysetopt(3)
stop the current operation immediately, resulting in a
CURLEABORTEDBYCALBACK error code from the transfer
(Added in 7.12.1)
From 7.18.0, the function can return
CURLREADFUNCPAUSE which then will cause reading from
this connection to become paused. See
curleasypause(3) for further details.
If you set the callback pointer to NUL, 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 CURLOPTREADATA.
CURLOPTREADATA
Data pointer to pass to the file read function. If you
use the CURLOPTREADFUNCTION 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 DL, you MUST use a
CURLOPTREADFUNCTION if you set this option.
This option was also known by the older name
CURLOPTINFILE, the name CURLOPTREADATA was intro-
duced in 7.9.7.
CURLOPTIOCTLFUNCTION
Function pointer that should match the
curlioctlcallback prototype found in .
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
HTP PUT or POST with a multi-pass authentication
method. (Option added in 7.12.3).
Use CURLOPTSEKFUNCTION instead to provide seeking!
CURLOPTIOCTLDATA
Pass a pointer that will be untouched by libcurl and
passed as the 3rd argument in the ioctl callback set
with CURLOPTIOCTLFUNCTION. (Option added in 7.12.3)
CURLOPTSEKFUNCTION
Function pointer that should match the following proto-
type: int function(void *instream, curlofft offset,
int origin); This function gets called by libcurl to
seek to a certain position in the input stream and can
libcurl 7.19.3 Last change: 11 Dec 2008 4
libcurl Manual curleasysetopt(3)
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 HTP PUT or POST with a multi-pass
authentication method. The function shall work like
"fseek" or "lseek" and accepted SEKSET, SEKCUR and
SEKEND as argument for origin, although (in 7.18.0)
libcurl only passes SEKSET. The callback must return
0 on success as returning something else will cause the
upload operation to fail.
If you forward the input arguments directly to "fseek"
or "lseek", note that the data type for offset is not
the same as defined for curlofft on many systems!
(Option added in 7.18.0)
CURLOPTSEKDATA
Data pointer to pass to the file read function. If you
use the CURLOPTSEKFUNCTION option, this is the
pointer you'll get as input. If you don't specify a
seek callback, NUL is passed. (Option added in 7.18.0)
CURLOPTSOCKOPTFUNCTION
Function pointer that should match the
curlsockoptcallback prototype found in .
This function gets called by libcurl after the socket()
call but before the connect() call. The callback's pur-
pose argument identifies the exact purpose for this
particular socket, and currently only one value is sup-
ported: CURLSOCKTYPEIPCXN 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 addi-
tional setsockopt() calls can be done at the user's
discretion. A non-zero return code from the callback
function will signal an unrecoverable error to the
library and it will close the socket and return
CURLECOULDNTCONECT. (Option added in 7.15.6.)
CURLOPTSOCKOPTDATA
Pass a pointer that will be untouched by libcurl and
passed as the first argument in the sockopt callback
set with CURLOPTSOCKOPTFUNCTION. (Option added in
7.15.6.)
CURLOPTOPENSOCKETFUNCTION
Function pointer that should match the
curlopensocketcallback prototype found in
. This function gets called by libcurl
instead of the socket(2) call. The callback's purpose
argument identifies the exact purpose for this particu-
lar socket, and currently only one value is supported:
libcurl 7.19.3 Last change: 11 Dec 2008 5
libcurl Manual curleasysetopt(3)
CURLSOCKTYPEIPCXN for the primary connection (meaning
the control connection in the FTP case). Future ver-
sions of libcurl may support more purposes. It passes
the resolved peer address as a address argument so the
callback can modify the address or refuse to connect at
all. The callback function should return the socket or
CURLSOCKETBAD in case no connection should be esta-
blished or any error detected. Any additional set-
sockopt(2) calls can be done on the socket at the
user's discretion. CURLSOCKETBAD return value from
the callback function will signal an unrecoverable
error to the library and it will return
CURLECOULDNTCONECT. This return code can be used
for IP address blacklisting. The default behavior is:
return socket(addr->family, addr->socktype, addr-
>protocol); (Option added in 7.17.1.)
CURLOPTOPENSOCKETDATA
Pass a pointer that will be untouched by libcurl and
passed as the first argument in the opensocket callback
set with CURLOPTOPENSOCKETFUNCTION. (Option added in
7.17.1.)
CURLOPTPROGRESFUNCTION
Function pointer that should match the
curlprogresscallback prototype found in
. 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 CURLEABORTEDBYCALBACK.
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.
CURLOPTNOPROGRES must be set to 0 to make this func-
tion actually get called.
CURLOPTPROGRESDATA
Pass a pointer that will be untouched by libcurl and
passed as the first argument in the progress callback
set with CURLOPTPROGRESFUNCTION.
CURLOPTHEADERFUNCTION
Function pointer that should match the following proto-
type: sizet function( void *ptr, sizet size, sizet
libcurl 7.19.3 Last change: 11 Dec 2008 6
libcurl Manual curleasysetopt(3)
nmemb, void *stream);. 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 call-
back. Parsing headers should be easy enough using this.
The size of the data pointed to by ptr is size multi-
plied with nmemb. Do not assume that the header line is
zero terminated! The pointer named stream is the one
you set with the CURLOPTWRITEHEADER option. The call-
back 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
CURLEWRITEROR return code).
If this option is not set, or if it is set to NUL, but
CURLOPTHEADERDATA (CURLOPTWRITEHEADER) is set to any-
thing but NUL, the function used to accept response
data will be used instead. That is, it will be the
function specified with CURLOPTWRITEFUNCTION, or if it
is not specified or NUL - the default, stream-writing
function.
Since 7.14.1: When a server sends a chunked encoded
transfer, it may contain a trailer. That trailer is
identical to a HTP 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.
CURLOPTWRITEHEADER
(This option is also known as CURLOPTHEADERDATA) 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 CURLOPTHEADERFUNCTION option above on how
to set a custom get-all-headers callback.
CURLOPTDEBUGFUNCTION
Function pointer that should match the following proto-
type: int curldebugcallback (CURL *, curlinfotype,
char *, sizet, void *); CURLOPTDEBUGFUNCTION replaces
the standard debug function used when CURLOPTVERBOSE
is in effect. This callback receives debug information,
as specified with the curlinfotype argument. This
function must return 0. The data pointed to by the
char * passed to this function WIL NOT be zero ter-
minated, but will be exactly of the size as told by the
sizet argument.
libcurl 7.19.3 Last change: 11 Dec 2008 7
libcurl Manual curleasysetopt(3)
Available curlinfotype values:
CURLINFOTEXT
The data is informational text.
CURLINFOHEADERIN
The data is header (or header-like) data received
from the peer.
CURLINFOHEADEROUT
The data is header (or header-like) data sent to
the peer.
CURLINFODATAIN
The data is protocol data received from the peer.
CURLINFODATAOUT
The data is protocol data sent to the peer.
CURLOPTDEBUGDATA
Pass a pointer to whatever you want passed in to your
CURLOPTDEBUGFUNCTION in the last void * argument. This
pointer is not used by libcurl, it is only passed to
the callback.
CURLOPTSLCTXFUNCTION
This option does only function for libcurl powered by
OpenSL. If libcurl was built against another SL
library, this functionality is absent.
Function pointer that should match the following proto-
type: CURLcode sslctxfun(CURL *curl, void *sslctx, void
*parm); This function gets called by libcurl just
before the initialization of an SL connection after
having processed all other SL related options to give
a last chance to an application to modify the behaviour
of openssl's ssl initialization. The sslctx parameter
is actually a pointer to an openssl SLCTX. 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 parm argu-
ment with the CURLOPTSLCTXDATA option. This option
was introduced in 7.11.0.
This function will get called on all new connections
made to a server, during the SL negotiation. The
SLCTX 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
libcurl 7.19.3 Last change: 11 Dec 2008 8
libcurl Manual curleasysetopt(3)
even to change the actual URI of an HTPS request
(example used in the lib509 test case). See also the
example section for a replacement of the key, certifi-
cate and trust file settings.
CURLOPTSLCTXDATA
Data pointer to pass to the ssl context callback set by
the option CURLOPTSLCTXFUNCTION, this is the
pointer you'll get as third parameter, otherwise NUL.
(Added in 7.11.0)
CURLOPTCONVTONETWORKFUNCTION
CURLOPTCONVFROMNETWORKFUNCTION
CURLOPTCONVFROMUTF8FUNCTION
Function pointers that should match the following pro-
totype: CURLcode function(char *ptr, sizet length);
These three options apply to non-ASCI platforms only.
They are available only if CURLDOESCONVERSIONS was
defined when libcurl was built. When this is the case,
curlversioninfo(3) will return the CURLVERSIONCONV
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. CURLEOK should be returned upon suc-
cessful conversion. A CURLcode return value defined by
curl.h, such as CURLECONVFAILED, should be returned
if an error was encountered.
CURLOPTCONVTONETWORKFUNCTION and
CURLOPTCONVFROMNETWORKFUNCTION convert between the
host encoding and the network encoding. They are used
when commands or ASCI data are sent/received over the
network.
CURLOPTCONVFROMUTF8FUNCTION is called to convert
from UTF8 into the host encoding. It is required only
for SL processing.
If you set a callback pointer to NUL, or don't set it
at all, the built-in libcurl iconv functions will be
used. If HAVEICONV was not defined when libcurl was
built, and no callback has been established, conversion
will return the CURLECONVREQD error code.
If HAVEICONV is defined, CURLICONVCODESETOFHOST
must also be defined. For example:
libcurl 7.19.3 Last change: 11 Dec 2008 9
libcurl Manual curleasysetopt(3)
#define CURLICONVCODESETOFHOST "IBM-1047"
The iconv code in libcurl will default the network and
UTF8 codeset names as follows:
#define CURLICONVCODESETOFNETWORK "ISO8859-1"
#define CURLICONVCODESETFORUTF8 "UTF-8"
You will need to override these definitions if they are
different on your system.
EROR OPTIONS
CURLOPTERORBUFER
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
curleasyperform. The buffer must be at least
CURLERORSIZE 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
curleasycleanup(3) or you set the same option again
to use a different pointer.
Use CURLOPTVERBOSE and CURLOPTDEBUGFUNCTION 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.
CURLOPTSTDER
Pass a FILE * as parameter. Tell libcurl to use this
stream instead of stderr when showing the progress
meter and displaying CURLOPTVERBOSE data.
CURLOPTFAILONEROR
A parameter set to 1 tells the library to fail silently
if the HTP 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).
libcurl 7.19.3 Last change: 11 Dec 2008 10
libcurl Manual curleasysetopt(3)
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.
NETWORK OPTIONS
CURLOPTURL
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 pro-
tocol of the set URL is not supported, libcurl will
return on error (CURLEUNSUPORTEDPROTOCOL) when you
call curleasyperform(3) or curlmultiperform(3). Use
curlversioninfo(3) for detailed info on which proto-
cols are supported.
The string given to CURLOPTURL must be url-encoded and
follow RFC 2396 (http:/curl.haxx.se/rfc/rfc2396.txt).
CURLOPTURL is the only option that must be set before
curleasyperform(3) is called.
CURLOPTPROTOCOLS 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 use-
ful if you accept the URL from an external source and
want to limit the accessibility.
CURLOPTPROTOCOLS
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 proto-
cols 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
CURLOPTREDIRPROTOCOLS. (Added in 7.19.4)
CURLOPTREDIRPROTOCOLS
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 CURLOPTFOLOWLOCATION 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)
libcurl 7.19.3 Last change: 11 Dec 2008 11
libcurl Manual curleasysetopt(3)
CURLOPTPROXY
Set HTP 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. CURLOPTPROXYPORT.
When you tell the library to use an HTP proxy, libcurl
will transparently convert operations to HTP 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
CURLOPTQUOTE and similar FTP specifics that don't work
unless you tunnel through the HTP proxy. Such tunnel-
ing is activated with CURLOPTHTPROXYTUNEL.
libcurl respects the environment variables httpproxy,
ftpproxy, allproxy etc, if any of those are set. The
CURLOPTPROXY 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 environ-
ment variables can be specified the exact same way as
the proxy can be set with CURLOPTPROXY, include proto-
col prefix (http:/) and embedded user ] password.
CURLOPTPROXYPORT
Pass a long with this option to set the proxy port to
connect to unless it is specified in the proxy string
CURLOPTPROXY.
CURLOPTPROXYTYPE
Pass a long with this option to set type of the proxy.
Available options for this are CURLPROXYHTP,
CURLPROXYHTP10 (added in 7.19.4), CURLPROXYSOCKS4
(added in 7.15.2), CURLPROXYSOCKS5, CURLPROXYSOCKS4A
(added in 7.18.0) and CURLPROXYSOCKS5HOSTNAME (added
in 7.18.0). The HTP type is default. (Added in 7.10)
CURLOPTNOPROXY
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 effec-
tively disables the proxy. Each name in this list is
libcurl 7.19.3 Last change: 11 Dec 2008 12
libcurl Manual curleasysetopt(3)
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)
CURLOPTHTPROXYTUNEL
Set the parameter to 1 to make the library tunnel all
operations through a given HTP 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.
CURLOPTSOCKS5GSAPISERVICE
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)
CURLOPTSOCKS5GSAPINEC
Pass a long set to 1 to enable or 0 to disable. As part
of the gssapi negotiation a protection mode is nego-
tiated. 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).
CURLOPTINTERFACE
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.
CURLOPTLOCALPORT
Pass a long. This sets the local port number of the
socket used for connection. This can be used in combi-
nation with CURLOPTINTERFACE and you are recommended
to use CURLOPTLOCALPORTRANGE as well when this is set.
Note that the only valid port numbers are 1 - 65535.
(Added in 7.15.2)
CURLOPTLOCALPORTRANGE
Pass a long. This is the number of attempts libcurl
should make to find a working local port number. It
starts with the given CURLOPTLOCALPORT 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 con-
nection setup failures. (Added in 7.15.2)
CURLOPTDNSCACHETIMEOUT
libcurl 7.19.3 Last change: 11 Dec 2008 13
libcurl Manual curleasysetopt(3)
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 imple-
mentations don't re-read name server information unless
explicitly told so (for example, by calling
resinit(3)). 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.
CURLOPTDNSUSEGLOBALCACHE
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.
WARNING: this option is considered obsolete. Stop using
it. Switch over to using the share interface instead!
See CURLOPTSHARE and curlshareinit(3).
CURLOPTBUFERSIZE
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
(CURLMAXWRITESIZE), so it only makes sense to use
this option if you want it smaller.
CURLOPTPORT
Pass a long specifying what remote port number to con-
nect to, instead of the one specified in the URL or the
default port for the used protocol.
CURLOPTCPNODELAY
Pass a long specifying whether the TCPNODELAY 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 Seg-
ment Size (MS) for the network).
libcurl 7.19.3 Last change: 11 Dec 2008 14
libcurl Manual curleasysetopt(3)
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 net-
work if overdone.
CURLOPTADRESCOPE
Pass a long specifying the scopeid value to use when
connecting to IPv6 link-local or site-local addresses.
(Added in 7.19.0)
NAMES and PASWORDS OPTIONS (Authentication)
CURLOPTNETRC
This parameter controls the preference of libcurl
between using user names and passwords from your
~/.netrc file, relative to user names and passwords in
the URL supplied with CURLOPTURL.
libcurl uses a user name (and supplied or prompted
password) supplied with CURLOPTUSERPWD in preference
to any of the options controlled by this parameter.
Pass a long, set to one of the values described below.
CURLNETRCOPTIONAL
The use of your ~/.netrc 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 machine, which ever information is not speci-
fied in the URL.
Undefined values of the option will have this
effect.
CURLNETRCIGNORED
The library will ignore the file and use only the
information in the URL.
This is the default.
CURLNETRCREQUIRED
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.
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
libcurl 7.19.3 Last change: 11 Dec 2008 15
libcurl Manual curleasysetopt(3)
properties set (as the standard Unix ftp client does). It
should only be readable by user.
CURLOPTNETRCFILE
Pass a char * as parameter, pointing to a zero ter-
minated string containing the full path name to the
file you want libcurl to use as .netrc file. If this
option is omitted, and CURLOPTNETRC is set, libcurl
will attempt to find a .netrc file in the current
user's home directory. (Added in 7.10.9)
CURLOPTUSERPWD
Pass a char * as parameter, which should be [user
name]:[password] to use for the connection. Use
CURLOPTHTPAUTH 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
HTP servers (on Windows) support this style even for
Basic authentication.
When using HTP and CURLOPTFOLOWLOCATION, 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 CURLOPTUNRESTRICTEDAUTH is set), so if lib-
curl follows locations to other hosts it will not send
the user and password to those. This is enforced to
prevent accidental information leakage.
CURLOPTPROXYUSERPWD
Pass a char * as parameter, which should be [user
name]:[password] to use for the connection to the HTP
proxy. Use CURLOPTPROXYAUTH to decide the authentica-
tion method.
CURLOPTUSERNAME
Pass a char * as parameter, which should be pointing to
the zero terminated user name to use for the transfer.
CURLOPTUSERNAME sets the user name to be used in pro-
tocol authentication. You should not use this option
together with the (older) CURLOPTUSERPWD option.
In order to specify the password to be used in conjunc-
tion with the user name use the CURLOPTPASWORD
option. (Added in 7.19.1)
CURLOPTPASWORD
Pass a char * as parameter, which should be pointing to
libcurl 7.19.3 Last change: 11 Dec 2008 16
libcurl Manual curleasysetopt(3)
the zero terminated password to use for the transfer.
The CURLOPTPASWORD option should be used in conjunc-
tion with the CURLOPTUSERNAME option. (Added in
7.19.1)
CURLOPTPROXYUSERNAME
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 CURLOPTPROXYUSERNAME option should be used in same
way as the CURLOPTPROXYUSERPWD is used. In comparison
to CURLOPTPROXYUSERPWD the CURLOPTPROXYUSERNAME
allows the username to contain a colon, like in the
following example: "sip:user@example.com". Note the
CURLOPTPROXYUSERNAME option is an alternative way to
set the user name while connecting to Proxy. There is
no meaning to use it together with the
CURLOPTPROXYUSERPWD option.
In order to specify the password to be used in conjunc-
tion with the user name use the CURLOPTPROXYPASWORD
option. (Added in 7.19.1)
CURLOPTPROXYPASWORD
Pass a char * as parameter, which should be pointing to
the zero terminated password to use for the transfer
while connecting to Proxy.
The CURLOPTPROXYPASWORD option should be used in con-
junction with the CURLOPTPROXYUSERNAME option. (Added
in 7.19.1)
CURLOPTHTPAUTH
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
CURLOPTUSERPWD option or with the CURLOPTUSERNAME and
the CURLOPTUSERPASWORD options. (Added in 7.10.6)
CURLAUTHBASIC
HTP 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.
libcurl 7.19.3 Last change: 11 Dec 2008 17
libcurl Manual curleasysetopt(3)
CURLAUTHDIGEST
HTP 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.
CURLAUTHDIGESTIE
HTP 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)
CURLAUTHGSNEGOTIATE
HTP GS-Negotiate authentication. The GS-
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 GS-API
library for this to work.
CURLAUTHNTLM
HTP 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 eaves-
dropped.
You need to build libcurl with OpenSL support for
this option to work, or build libcurl on Windows.
CURLAUTHANY
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.
CURLAUTHANYSAFE
This is a convenience macro that sets all bits
except Basic and thus makes libcurl pick any it
finds suitable. libcurl will automatically select
the one it finds most secure.
libcurl 7.19.3 Last change: 11 Dec 2008 18
libcurl Manual curleasysetopt(3)
CURLOPTPROXYAUTH
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 CURLOPTPROXYUSERPWD
option. The bitmask can be constructed by or'ing
together the bits listed above for the CURLOPTHTPAUTH
option. As of this writing, only Basic, Digest and NTLM
work. (Added in 7.10.7)
HTP OPTIONS
CURLOPTAUTOREFERER
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.
CURLOPTENCODING
Sets the contents of the Accept-Encoding: header sent
in an HTP request, and enables decoding of a response
when a Content-Encoding: header is received. Three
encodings are supported: identity, which does nothing,
deflate which requests the server to compress its
response using the zlib algorithm, and gzip 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-NUL
value) or else any unsolicited encoding done by the
server is ignored. See the special file
lib/README.encoding for details.
CURLOPTFOLOWLOCATION
A parameter set to 1 tells the library to follow any
Location: header that the server sends as part of an
HTP 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. CURLOPTMAXREDIRS 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 CURLOPTREDIRPROTOCOLS and it excludes
the FILE protocol by default.
libcurl 7.19.3 Last change: 11 Dec 2008 19
libcurl Manual curleasysetopt(3)
CURLOPTUNRESTRICTEDAUTH
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 CURLOPTFOLOWLOCATION.
CURLOPTMAXREDIRS
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
(CURLETOMANYREDIRECTS). This option only makes
sense if the CURLOPTFOLOWLOCATION 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)
CURLOPTPOSTREDIR
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 CURLREDIRPOST301)
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
CURLREDIRPOST302) makes libcurl maintain the request
method after a 302 redirect. CURLREDIRPOSTAL 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 CURLOPTFOLOWLOCATION.
(Added in 7.17.1) (This option was known as
CURLOPTPOST301 up to 7.19.0 as it only supported the
301 way before then)
CURLOPTPUT
A parameter set to 1 tells the library to use HTP PUT
to transfer data. The data should be set with
CURLOPTREADATA and CURLOPTINFILESIZE.
This option is deprecated and starting with version
7.12.1 you should instead use CURLOPTUPLOAD.
CURLOPTPOST
A parameter set to 1 tells the library to do a regular
HTP 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 CURLOPTPOSTFIELDS or CURLOPTCOPYPOSTFIELDS
libcurl 7.19.3 Last change: 11 Dec 2008 20
libcurl Manual curleasysetopt(3)
options to specify what data to post and
CURLOPTPOSTFIELDSIZE or CURLOPTPOSTFIELDSIZELARGE to
set the data size.
Optionally, you can provide data to POST using the
CURLOPTREADFUNCTION and CURLOPTREADATA options but
then you must make sure to not set CURLOPTPOSTFIELDS
to anything but NUL. When providing data with a call-
back, you must transmit it using chunked transfer-
encoding or you must set the size of the data with the
CURLOPTPOSTFIELDSIZE or CURLOPTPOSTFIELDSIZELARGE
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 CURLOPTHTPHEADER.
Using POST with HTP 1.1 implies the use of a "Expect:
100-continue" header. You can disable this header with
CURLOPTHTPHEADER as usual.
If you use POST to a HTP 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
CURLOPTHTPHEADER. With HTP 1.0 or without chunked
transfer, you must specify the size in the request.
When setting CURLOPTPOST to 1, it will automatically
set CURLOPTNOBODY 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
CURLOPTNOBODY or CURLOPTHTPGET or similar.
CURLOPTPOSTFIELDS
Pass a void * as parameter, which should be the full
data to post in an HTP 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
libcurl 7.19.3 Last change: 11 Dec 2008 21
libcurl Manual curleasysetopt(3)
used one by HTML forms. See also the CURLOPTPOST.
Using CURLOPTPOSTFIELDS implies CURLOPTPOST.
If you want to do a zero-byte POST, you need to set
CURLOPTPOSTFIELDSIZE explicitly to zero, as simply
setting CURLOPTPOSTFIELDS to NUL or "" just effec-
tively 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 HTP 1.1 implies the use of a "Expect:
100-continue" header. You can disable this header with
CURLOPTHTPHEADER as usual.
To make multipart/formdata posts (aka rfc1867-posts),
check out the CURLOPTHTPOST option.
CURLOPTPOSTFIELDSIZE
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.
CURLOPTPOSTFIELDSIZELARGE
Pass a curlofft as parameter. Use this to set the
size of the CURLOPTPOSTFIELDS data to prevent libcurl
from doing strlen() on the data to figure out the size.
This is the large file version of the
CURLOPTPOSTFIELDSIZE option. (Added in 7.11.1)
CURLOPTCOPYPOSTFIELDS
Pass a char * as parameter, which should be the full
data to post in an HTP POST operation. It behaves as
the CURLOPTPOSTFIELDS 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 CURLOPTPOSTFIELDSIZE
or CURLOPTPOSTFIELDSIZELARGE: If the size has not
been set prior to CURLOPTCOPYPOSTFIELDS, 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
CURLOPTCOPYPOSTFIELDS, unless another
CURLOPTPOSTFIELDS or CURLOPTCOPYPOSTFIELDS option is
issued. (Added in 7.17.1)
CURLOPTHTPOST
Tells libcurl you want a multipart/formdata HTP POST
libcurl 7.19.3 Last change: 11 Dec 2008 22
libcurl Manual curleasysetopt(3)
to be made and you instruct what data to pass on to the
server. Pass a pointer to a linked list of
curlhttppost structs as parameter. The easiest way to
create such a list, is to use curlformadd(3) as docu-
mented. The data in this list must remain intact until
you close this curl handle again with
curleasycleanup(3).
Using POST with HTP 1.1 implies the use of a "Expect:
100-continue" header. You can disable this header with
CURLOPTHTPHEADER as usual.
When setting CURLOPTHTPOST, it will automatically
set CURLOPTNOBODY to 0 (since 7.14.1).
CURLOPTREFERER
Pass a pointer to a zero terminated string as parame-
ter. 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 CURLOPTHTPHEADER.
CURLOPTUSERAGENT
Pass a pointer to a zero terminated string as parame-
ter. 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 CURLOPTHTPHEADER.
CURLOPTHTPHEADER
Pass a pointer to a linked list of HTP headers to pass
to the server in your HTP request. The linked list
should be a fully valid list of struct curlslist
structs properly filled in. Use curlslistappend(3) to
create the list and curlslistfreeall(3) 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 dis-
abled. 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
libcurl 7.19.3 Last change: 11 Dec 2008 23
libcurl Manual curleasysetopt(3)
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 NUL to this to reset back to no custom headers.
The most commonly replaced headers have "shortcuts" in
the options CURLOPTCOKIE, CURLOPTUSERAGENT and
CURLOPTREFERER.
CURLOPTHTP200ALIASES
Pass a pointer to a linked list of aliases to be
treated as valid HTP 200 responses. Some servers
respond with a custom header response line. For exam-
ple, IceCast servers respond with "ICY 200 OK". By
including this string in your list of aliases, the
response will be treated as a valid HTP header line
such as "HTP/1.0 200 OK". (Added in 7.10.3)
The linked list should be a fully valid list of struct
curlslist structs, and be properly filled in. Use
curlslistappend(3) to create the list and
curlslistfreeall(3) 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 CURLOPTHTPVERSION, but starting with 7.16.3
the protocol is assumed to match HTP 1.0 when an alias
matched.
CURLOPTCOKIE
Pass a pointer to a zero terminated string as parame-
ter. 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 CON-
TENTS 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.
CURLOPTCOKIEFILE
libcurl 7.19.3 Last change: 11 Dec 2008 24
libcurl Manual curleasysetopt(3)
Pass a pointer to a zero terminated string as parame-
ter. 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 HTP-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.
CURLOPTCOKIEJAR
Pass a file name as char *, zero terminated. This will
make libcurl write all internally known cookies to the
specified file when curleasycleanup(3) 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 ses-
sion, 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 curleasycleanup(3) is called), libcurl will
not and cannot report an error for this. Using
CURLOPTVERBOSE or CURLOPTDEBUGFUNCTION will get a
warning to display, but that is the only visible feed-
back you get about this possibly lethal situation.
CURLOPTCOKIESESION
Pass a long set to 1 to mark this as a new cookie "ses-
sion". It will force libcurl to ignore all cookies it
is about to load that are "session cookies" from the
previous session. By default, libcurl always stores and
loads all cookies, independent if they are session
cookies or not. Session cookies are cookies without
expiry date and they are meant to be alive and existing
for this "session" only.
CURLOPTCOKIELIST
Pass a char * to a cookie string. Cookie can be either
in Netscape / Mozilla format or just regular HTP-style
header (Set-Cookie: ...) format. If cURL cookie engine
was not enabled it will enable its cookie engine.
Passing a magic string "AL" will erase all cookies
known by cURL. (Added in 7.14.1) Passing the special
string "SES" will only erase all session cookies known
by cURL. (Added in 7.15.4) Passing the special string
libcurl 7.19.3 Last change: 11 Dec 2008 25
libcurl Manual curleasysetopt(3)
"FLUSH" will write all cookies known by cURL to the
file specified by CURLOPTCOKIEJAR. (Added in 7.17.1)
CURLOPTHTPGET
Pass a long. If the long is 1, this forces the HTP
request to get back to GET. Usable if a POST, HEAD,
PUT, or a custom request has been used previously using
the same curl handle.
When setting CURLOPTHTPGET to 1, it will automati-
cally set CURLOPTNOBODY to 0 (since 7.14.1).
CURLOPTHTPVERSION
Pass a long, set to one of the values described below.
They force libcurl to use the specific HTP versions.
This is not sensible to do unless you have a good rea-
son.
CURLHTPVERSIONONE
We don't care about what version the library uses.
libcurl will use whatever it thinks fit.
CURLHTPVERSION10
Enforce HTP 1.0 requests.
CURLHTPVERSION11
Enforce HTP 1.1 requests.
CURLOPTIGNORECONTENTLENGTH
Ignore the Content-Length header. This is useful for
Apache 1.x (and similar servers) which will report
incorrect content length for files over 2 gigabytes. If
this option is used, curl will not be able to accu-
rately report progress, and will simply stop the down-
load when the server ends the connection. (added in
7.14.1)
CURLOPTHTPCONTENTDECODING
Pass a long to tell libcurl how to act on content
decoding. If set to zero, content decoding will be dis-
abled. If set to 1 it is enabled. Note however that
libcurl has no default content decoding but requires
you to use CURLOPTENCODING for that. (added in 7.16.2)
CURLOPTHTPTRANSFERDECODING
Pass a long to tell libcurl how to act on transfer
decoding. If set to zero, transfer decoding will be
disabled, if set to 1 it is enabled (default). libcurl
does chunked transfer decoding by default unless this
option is set to zero. (added in 7.16.2)
libcurl 7.19.3 Last change: 11 Dec 2008 26
libcurl Manual curleasysetopt(3)
TFTP OPTIONS
CURLOPTFTPBLKSIZE
Specify block size to use for TFTP data transmission.
Valid range as per RFC 2348 is 8-65464 bytes. The
default of 512 bytes will be used if this option is not
specified. The specified block size will only be used
pending support by the remote server. If the server
does not return an option acknowledgement or returns an
option acknowledgement with no blksize, the default of
512 bytes will be used. (added in 7.19.4)
FTP OPTIONS
CURLOPTFTPORT
Pass a pointer to a zero terminated string as parame-
ter. It will be used to get the IP address to use for
the FTP PORT instruction. The PORT instruction tells
the remote server to connect to our specified IP
address. The string may be a plain IP address, a host
name, a network interface name (under Unix) or just a
'-' symbol to let the library use your system's default
IP address. Default FTP operations are passive, and
thus won't use PORT.
You disable PORT again and go back to using the passive
version by setting this option to NUL.
CURLOPTQUOTE
Pass a pointer to a linked list of FTP or SFTP commands
to pass to the server prior to your FTP request. This
will be done before any other commands are issued (even
before the CWD command for FTP). The linked list should
be a fully valid list of 'struct curlslist' structs
properly filled in with text strings. Use
curlslistappend(3) to append strings (commands) to
the list, and clear the entire list afterwards with
curlslistfreeall(3). Disable this operation again by
setting a NUL to this option. The set of valid FTP
commands depends on the server (see RFC959 for a list
of mandatory commands). The valid SFTP commands are:
chgrp, chmod, chown, ln, mkdir, pwd, rename, rm, rmdir,
symlink (see curl(1)) (SFTP support added in 7.16.3)
CURLOPTPOSTQUOTE
Pass a pointer to a linked list of FTP or SFTP commands
to pass to the server after your FTP transfer request.
The linked list should be a fully valid list of struct
curlslist structs properly filled in as described for
CURLOPTQUOTE. Disable this operation again by setting
a NUL to this option.
CURLOPTPREQUOTE
Pass a pointer to a linked list of FTP commands to pass
libcurl 7.19.3 Last change: 11 Dec 2008 27
libcurl Manual curleasysetopt(3)
to the server after the transfer type is set. The
linked list should be a fully valid list of struct
curlslist structs properly filled in as described for
CURLOPTQUOTE. Disable this operation again by setting
a NUL to this option. Before version 7.15.6, if you
also set CURLOPTNOBODY to 1, this option didn't work.
CURLOPTDIRLISTONLY
A parameter set to 1 tells the library to just list the
names of files in a directory, instead of doing a full
directory listing that would include file sizes, dates
etc. This works for FTP and SFTP URLs.
This causes an FTP NLST command to be sent on an FTP
server. Beware that some FTP servers list only files
in their response to NLST; they might not include sub-
directories and symbolic links.
(This option was known as CURLOPTFTPLISTONLY up to
7.16.4)
CURLOPTAPEND
A parameter set to 1 tells the library to append to the
remote file instead of overwrite it. This is only use-
ful when uploading to an FTP site.
(This option was known as CURLOPTFTPAPEND up to
7.16.4)
CURLOPTFTPUSEPRT
Pass a long. If the value is 1, it tells curl to use
the EPRT (and LPRT) command when doing active FTP down-
loads (which is enabled by CURLOPTFTPORT). Using EPRT
means that it will first attempt to use EPRT and then
LPRT before using PORT, but if you pass zero to this
option, it will not try using EPRT or LPRT, only plain
PORT. (Added in 7.10.5)
If the server is an IPv6 host, this option will have no
effect as of 7.12.3.
CURLOPTFTPUSEPSV
Pass a long. If the value is 1, it tells curl to use
the EPSV command when doing passive FTP downloads
(which it always does by default). Using EPSV means
that it will first attempt to use EPSV before using
PASV, but if you pass zero to this option, it will not
try using EPSV, only plain PASV.
If the server is an IPv6 host, this option will have no
effect as of 7.12.3.
libcurl 7.19.3 Last change: 11 Dec 2008 28
libcurl Manual curleasysetopt(3)
CURLOPTFTPCREATEMISINGDIRS
Pass a long. If the value is 1, curl will attempt to
create any remote directory that it fails to CWD into.
CWD is the command that changes working directory.
(Added in 7.10.7)
This setting also applies to SFTP-connections. curl
will attempt to create the remote directory if it can't
obtain a handle to the target-location. The creation
will fail if a file of the same name as the directory
to create already exists or lack of permissions
prevents creation. (Added in 7.16.3)
Starting with 7.19.4, you can also set this value to 2,
which will make libcurl retry the CWD command again if
the subsequent MKD command fails. This is especially
useful if you're doing many simultanoes connections
against the same server and they all have this option
enabled, as then CWD may first fail but then another
connection does MKD before this connection and thus MKD
fails but trying CWD works! 7.19.4 also introduced the
CURLFTPCREATEDIR and CURLFTPCREATEDIRETRY enum
names for these arguments.
Before version 7.19.4, libcurl will simply ignore argu-
ments set to 2 and act as if 1 was selected.
CURLOPTFTPRESPONSETIMEOUT
Pass a long. Causes curl to set a timeout period (in
seconds) on the amount of time that the server is
allowed to take in order to generate a response message
for a command before the session is considered hung.
While curl is waiting for a response, this value over-
rides CURLOPTIMEOUT. It is recommended that if used
in conjunction with CURLOPTIMEOUT, you set
CURLOPTFTPRESPONSETIMEOUT to a value smaller than
CURLOPTIMEOUT. (Added in 7.10.8)
CURLOPTFTPALTERNATIVETOUSER
Pass a char * as parameter, pointing to a string which
will be used to authenticate if the usual FTP "USER
user" and "PAS password" negotiation fails. This is
currently only known to be required when connecting to
Tumbleweed's Secure Transport FTPS server using client
certificates for authentication. (Added in 7.15.5)
CURLOPTFTPSKIPASVIP
Pass a long. If set to 1, it instructs libcurl to not
use the IP address the server suggests in its 227-
response to libcurl's PASV command when libcurl con-
nects the data connection. Instead libcurl will re-use
the same IP address it already uses for the control
libcurl 7.19.3 Last change: 11 Dec 2008 29
libcurl Manual curleasysetopt(3)
connection. But it will use the port number from the
227-response. (Added in 7.14.2)
This option has no effect if PORT, EPRT or EPSV is used
instead of PASV.
CURLOPTUSESL
Pass a long using one of the values from below, to make
libcurl use your desired level of SL for the FTP
transfer. (Added in 7.11.0)
(This option was known as CURLOPTFTPSL up to 7.16.4,
and the constants were known as CURLFTPSL*)
CURLUSESLNONE
Don't attempt to use SL.
CURLUSESLTRY
Try using SL, proceed as normal otherwise.
CURLUSESLCONTROL
Require SL for the control connection or fail
with CURLEUSESLFAILED.
CURLUSESLAL
Require SL for all communication or fail with
CURLEUSESLFAILED.
CURLOPTFTPSLAUTH
Pass a long using one of the values from below, to
alter how libcurl issues "AUTH TLS" or "AUTH SL" when
FTP over SL is activated (see CURLOPTUSESL). (Added
in 7.12.2)
CURLFTPAUTHDEFAULT
Allow libcurl to decide.
CURLFTPAUTHSL
Try "AUTH SL" first, and only if that fails try
"AUTH TLS".
CURLFTPAUTHTLS
Try "AUTH TLS" first, and only if that fails try
"AUTH SL".
CURLOPTFTPSLC
If enabled, this option makes libcurl use C (Clear
Command Channel). It shuts down the SL/TLS layer after
authenticating. The rest of the control channel commun-
ication will be unencrypted. This allows NAT routers to
follow the FTP transaction. Pass a long using one of
the values below. (Added in 7.16.1)
libcurl 7.19.3 Last change: 11 Dec 2008 30
libcurl Manual curleasysetopt(3)
CURLFTPSLCNONE
Don't attempt to use C.
CURLFTPSLCPASIVE
Do not initiate the shutdown, but wait for the
server to do it. Do not send a reply.
CURLFTPSLCACTIVE
Initiate the shutdown and wait for a reply.
CURLOPTFTPACOUNT
Pass a pointer to a zero-terminated string (or NUL to
disable). When an FTP server asks for "account data"
after user name and password has been provided, this
data is sent off using the ACT command. (Added in
7.13.0)
CURLOPTFTPFILEMETHOD
Pass a long that should have one of the following
values. This option controls what method libcurl should
use to reach a file on a FTP(S) server. The argument
should be one of the following alternatives:
CURLFTPMETHODMULTICWD
libcurl does a single CWD operation for each path
part in the given URL. For deep hierarchies this
means many commands. This is how RFC1738 says it
should be done. This is the default but the
slowest behavior.
CURLFTPMETHODNOCWD
libcurl does no CWD at all. libcurl will do SIZE,
RETR, STOR etc and give a full path to the server
for all these commands. This is the fastest
behavior.
CURLFTPMETHODSINGLECWD
libcurl does one CWD with the full target direc-
tory and then operates on the file "normally"
(like in the multicwd case). This is somewhat more
standards compliant than 'nocwd' but without the
full penalty of 'multicwd'.
(Added in 7.15.1)
PROTOCOL OPTIONS
CURLOPTRANSFERTEXT
A parameter set to 1 tells the library to use ASCI
mode for FTP transfers, instead of the default binary
transfer. For win32 systems it does not set the stdout
to binary mode. This option can be usable when
transferring text data between systems with different
views on certain characters, such as newlines or
libcurl 7.19.3 Last change: 11 Dec 2008 31
libcurl Manual curleasysetopt(3)
similar.
libcurl does not do a complete ASCI conversion when
doing ASCI transfers over FTP. This is a known
limitation/flaw that nobody has rectified. libcurl sim-
ply sets the mode to ASCI and performs a standard
transfer.
CURLOPTPROXYTRANSFERMODE
Pass a long. If the value is set to 1 (one), it tells
libcurl to set the transfer mode (binary or ASCI) for
FTP transfers done via an HTP proxy, by appending
;type=a or ;type=i to the URL. Without this setting, or
it being set to 0 (zero, the default),
CURLOPTRANSFERTEXT has no effect when doing FTP via a
proxy. Beware that not all proxies support this
feature. (Added in 7.18.0)
CURLOPTCRLF
Convert Unix newlines to CRLF newlines on transfers.
CURLOPTRANGE
Pass a char * as parameter, which should contain the
specified range you want. It should be in the format
"X-Y", where X or Y may be left out. HTP transfers
also support several intervals, separated with commas
as in "X-Y,N-M". Using this kind of multiple intervals
will cause the HTP server to send the response docu-
ment in pieces (using standard MIME separation tech-
niques). Pass a NUL to this option to disable the use
of ranges.
Ranges work on HTP, FTP and FILE (since 7.18.0)
transfers only.
CURLOPTRESUMEFROM
Pass a long as parameter. It contains the offset in
number of bytes that you want the transfer to start
from. Set this option to 0 to make the transfer start
from the beginning (effectively disabling resume). For
FTP, set this option to -1 to make the transfer start
from the end of the target file (useful to continue an
interrupted upload).
CURLOPTRESUMEFROMLARGE
Pass a curlofft as parameter. It contains the offset
in number of bytes that you want the transfer to start
from. (Added in 7.11.0)
CURLOPTCUSTOMREQUEST
Pass a pointer to a zero terminated string as parame-
ter. It will be used instead of GET or HEAD when doing
libcurl 7.19.3 Last change: 11 Dec 2008 32
libcurl Manual curleasysetopt(3)
an HTP request, or instead of LIST or NLST when doing
a FTP directory listing. This is useful for doing
DELETE or other more or less obscure HTP requests.
Don't do this at will, make sure your server supports
the command first.
When you change the request method by setting
CURLOPTCUSTOMREQUEST to something, you don't actually
change how libcurl behaves or acts in regards to the
particular request method, it will only change the
actual string sent in the request.
For example: if you tell libcurl to do a HEAD request,
but then change the request to a "GET" with
CURLOPTCUSTOMREQUEST you'll still see libcurl act as
if it sent a HEAD even when it does send a GET.
To switch to a proper HEAD, use CURLOPTNOBODY, to
switch to a proper POST, use CURLOPTPOST or
CURLOPTPOSTFIELDS and so on.
Restore to the internal default by setting this to
NUL.
Many people have wrongly used this option to replace
the entire request with their own, including multiple
headers and POST contents. While that might work in
many cases, it will cause libcurl to send invalid
requests and it could possibly confuse the remote
server badly. Use CURLOPTPOST and CURLOPTPOSTFIELDS
to set POST data. Use CURLOPTHTPHEADER to replace or
extend the set of headers sent by libcurl. Use
CURLOPTHTPVERSION to change HTP version.
CURLOPTFILETIME
Pass a long. If it is 1, libcurl will attempt to get
the modification date of the remote document in this
operation. This requires that the remote server sends
the time or replies to a time querying command. The
curleasygetinfo(3) function with the
CURLINFOFILETIME argument can be used after a transfer
to extract the received time (if any).
CURLOPTNOBODY
A parameter set to 1 tells the library to not include
the body-part in the output. This is only relevant for
protocols that have separate header and body parts. On
HTP(S) servers, this will make libcurl do a HEAD
request.
To change request to GET, you should use
CURLOPTHTPGET. Change request to POST with
libcurl 7.19.3 Last change: 11 Dec 2008 33
libcurl Manual curleasysetopt(3)
CURLOPTPOST etc.
CURLOPTINFILESIZE
When uploading a file to a remote site, this option
should be used to tell libcurl what the expected size
of the infile is. This value should be passed as a
long. See also CURLOPTINFILESIZELARGE.
For uploading using SCP, this option or
CURLOPTINFILESIZELARGE is mandatory.
Note that this option does not limit how much data lib-
curl will actually send, as that is controlled entirely
by what the read callback returns.
CURLOPTINFILESIZELARGE
When uploading a file to a remote site, this option
should be used to tell libcurl what the expected size
of the infile is. This value should be passed as a
curlofft. (Added in 7.11.0)
For uploading using SCP, this option or
CURLOPTINFILESIZE is mandatory.
Note that this option does not limit how much data lib-
curl will actually send, as that is controlled entirely
by what the read callback returns.
CURLOPTUPLOAD
A parameter set to 1 tells the library to prepare for
an upload. The CURLOPTREADATA and CURLOPTINFILESIZE
or CURLOPTINFILESIZELARGE options are also interest-
ing for uploads. If the protocol is HTP, uploading
means using the PUT request unless you tell libcurl
otherwise.
Using PUT with HTP 1.1 implies the use of a "Expect:
100-continue" header. You can disable this header with
CURLOPTHTPHEADER as usual.
If you use PUT to a HTP 1.1 server, you can upload
data without knowing the size before starting the
transfer if you use chunked encoding. You enable this
by adding a header like "Transfer-Encoding: chunked"
with CURLOPTHTPHEADER. With HTP 1.0 or without
chunked transfer, you must specify the size.
CURLOPTMAXFILESIZE
Pass a long as parameter. This allows you to specify
the maximum size (in bytes) of a file to download. If
the file requested is larger than this value, the
transfer will not start and CURLEFILESIZEXCEDED
libcurl 7.19.3 Last change: 11 Dec 2008 34
libcurl Manual curleasysetopt(3)
will be returned.
The file size is not always known prior to download,
and for such files this option has no effect even if
the file transfer ends up being larger than this given
limit. This concerns both FTP and HTP transfers.
CURLOPTMAXFILESIZELARGE
Pass a curlofft as parameter. This allows you to
specify the maximum size (in bytes) of a file to down-
load. If the file requested is larger than this value,
the transfer will not start and CURLEFILESIZEXCEDED
will be returned. (Added in 7.11.0)
The file size is not always known prior to download,
and for such files this option has no effect even if
the file transfer ends up being larger than this given
limit. This concerns both FTP and HTP transfers.
CURLOPTIMECONDITION
Pass a long as parameter. This defines how the
CURLOPTIMEVALUE time value is treated. You can set
this parameter to CURLTIMECONDIFMODSINCE or
CURLTIMECONDIFUNMODSINCE. This feature applies to
HTP and FTP.
The last modification time of a file is not always
known and in such instances this feature will have no
effect even if the given time condition would not have
been met. curleasygetinfo(3) with the
CURLINFOCONDITIONUNMET option can be used after a
transfer to learn if a zero-byte successful "transfer"
was due to this condition not matching.
CURLOPTIMEVALUE
Pass a long as parameter. This should be the time in
seconds since 1 Jan 1970, and the time will be used in
a condition as specified with CURLOPTIMECONDITION.
CONECTION OPTIONS
CURLOPTIMEOUT
Pass a long as parameter containing the maximum time in
seconds that you allow the libcurl transfer operation
to take. Normally, name lookups can take a considerable
time and limiting operations to less than a few minutes
risk aborting perfectly normal operations. This option
will cause curl to use the SIGALRM to enable time-
outing system calls.
In unix-like systems, this might cause signals to be
used unless CURLOPTNOSIGNAL is set.
libcurl 7.19.3 Last change: 11 Dec 2008 35
libcurl Manual curleasysetopt(3)
CURLOPTIMEOUTMS
Like CURLOPTIMEOUT but takes number of milliseconds
instead. If libcurl is built to use the standard system
name resolver, that portion of the transfer will still
use full-second resolution for timeouts with a minimum
timeout allowed of one second. (Added in 7.16.2)
CURLOPTLOWSPEDLIMIT
Pass a long as parameter. It contains the transfer
speed in bytes per second that the transfer should be
below during CURLOPTLOWSPEDTIME seconds for the
library to consider it too slow and abort.
CURLOPTLOWSPEDTIME
Pass a long as parameter. It contains the time in
seconds that the transfer should be below the
CURLOPTLOWSPEDLIMIT for the library to consider it
too slow and abort.
CURLOPTMAXSENDSPEDLARGE
Pass a curlofft as parameter. If an upload exceeds
this speed (counted in bytes per second) on cumulative
average during the transfer, the transfer will pause to
keep the average rate less than or equal to the parame-
ter value. Defaults to unlimited speed. (Added in
7.15.5)
CURLOPTMAXRECVSPEDLARGE
Pass a curlofft as parameter. If a download exceeds
this speed (counted in bytes per second) on cumulative
average during the transfer, the transfer will pause to
keep the average rate less than or equal to the parame-
ter value. Defaults to unlimited speed. (Added in
7.15.5)
CURLOPTMAXCONECTS
Pass a long. The set number will be the persistent con-
nection cache size. The set amount will be the maximum
amount of simultaneously open connections that libcurl
may cache in this easy handle. Default is 5, and there
isn't much point in changing this value unless you are
perfectly aware of how this works and changes libcurl's
behaviour. This concerns connections using any of the
protocols that support persistent connections.
When reaching the maximum limit, curl closes the oldest
one in the cache to prevent increasing the number of
open connections.
If you already have performed transfers with this curl
handle, setting a smaller MAXCONECTS than before may
cause open connections to get closed unnecessarily.
libcurl 7.19.3 Last change: 11 Dec 2008 36
libcurl Manual curleasysetopt(3)
Note that if you add this easy handle to a multi han-
dle, this setting is not acknowledged, and you must
instead use curlmultisetopt(3) and the
CURLMOPTMAXCONECTS option.
CURLOPTCLOSEPOLICY
(Obsolete) This option does nothing.
CURLOPTFRESHCONECT
Pass a long. Set to 1 to make the next transfer use a
new (fresh) connection by force. If the connection
cache is full before this connection, one of the exist-
ing connections will be closed as according to the
selected or default policy. This option should be used
with caution and only if you understand what it does.
Set this to 0 to have libcurl attempt re-using an
existing connection (default behavior).
CURLOPTFORBIDREUSE
Pass a long. Set to 1 to make the next transfer expli-
citly close the connection when done. Normally, libcurl
keeps all connections alive when done with one transfer
in case a succeeding one follows that can re-use them.
This option should be used with caution and only if you
understand what it does. Set to 0 to have libcurl keep
the connection open for possible later re-use (default
behavior).
CURLOPTCONECTIMEOUT
Pass a long. It should contain the maximum time in
seconds that you allow the connection to the server to
take. This only limits the connection phase, once it
has connected, this option is of no more use. Set to
zero to disable connection timeout (it will then only
timeout on the system's internal timeouts). See also
the CURLOPTIMEOUT option.
In unix-like systems, this might cause signals to be
used unless CURLOPTNOSIGNAL is set.
CURLOPTCONECTIMEOUTMS
Like CURLOPTCONECTIMEOUT but takes the number of
milliseconds instead. If libcurl is built to use the
standard system name resolver, that portion of the con-
nect will still use full-second resolution for timeouts
with a minimum timeout allowed of one second. (Added
in 7.16.2)
CURLOPTIPRESOLVE
Allows an application to select what kind of IP
addresses to use when resolving host names. This is
only interesting when using host names that resolve
libcurl 7.19.3 Last change: 11 Dec 2008 37
libcurl Manual curleasysetopt(3)
addresses using more than one version of IP. The
allowed values are:
CURLIPRESOLVEWHATEVER
Default, resolves addresses to all IP versions
that your system allows.
CURLIPRESOLVEV4
Resolve to IPv4 addresses.
CURLIPRESOLVEV6
Resolve to IPv6 addresses.
CURLOPTCONECTONLY
Pass a long. If the parameter equals 1, it tells the
library to perform all the required proxy authentica-
tion and connection setup, but no data transfer. This
option is useful only on HTP URLs.
This option is useful with the CURLINFOLASTSOCKET
option to curleasygetinfo(3). The library can set up
the connection and then the application can obtain the
most recently used socket for special data transfers.
(Added in 7.15.2)
SL and SECURITY OPTIONS
CURLOPTSLCERT
Pass a pointer to a zero terminated string as parame-
ter. The string should be the file name of your certi-
ficate. The default format is "PEM" and can be changed
with CURLOPTSLCERTYPE.
With NS this is the nickname of the certificate you
wish to authenticate with.
CURLOPTSLCERTYPE
Pass a pointer to a zero terminated string as parame-
ter. The string should be the format of your certifi-
cate. Supported formats are "PEM" and "DER". (Added in
7.9.3)
CURLOPTSLKEY
Pass a pointer to a zero terminated string as parame-
ter. The string should be the file name of your private
key. The default format is "PEM" and can be changed
with CURLOPTSLKEYTYPE.
CURLOPTSLKEYTYPE
Pass a pointer to a zero terminated string as parame-
ter. The string should be the format of your private
key. Supported formats are "PEM", "DER" and "ENG".
libcurl 7.19.3 Last change: 11 Dec 2008 38
libcurl Manual curleasysetopt(3)
The format "ENG" enables you to load the private key
from a crypto engine. In this case CURLOPTSLKEY is
used as an identifier passed to the engine. You have to
set the crypto engine with CURLOPTSLENGINE. "DER"
format key file currently does not work because of a
bug in OpenSL.
CURLOPTKEYPASWD
Pass a pointer to a zero terminated string as parame-
ter. It will be used as the password required to use
the CURLOPTSLKEY or CURLOPTSHPRIVATEKEYFILE
private key. You never needed a pass phrase to load a
certificate but you need one to load your private key.
(This option was known as CURLOPTSLKEYPASWD up to
7.16.4 and CURLOPTSLCERTPASWD up to 7.9.2)
CURLOPTSLENGINE
Pass a pointer to a zero terminated string as parame-
ter. It will be used as the identifier for the crypto
engine you want to use for your private key.
If the crypto device cannot be loaded,
CURLESLENGINENOTFOUND is returned.
CURLOPTSLENGINEDEFAULT
Sets the actual crypto engine as the default for (asym-
metric) crypto operations.
If the crypto device cannot be set,
CURLESLENGINESETFAILED is returned.
Note that even though this option doesn't need any
parameter, in some configurations curleasysetopt
might be defined as a macro taking exactly three argu-
ments. Therefore, it's recommended to pass 1 as parame-
ter to this option.
CURLOPTSLVERSION
Pass a long as parameter to control what version of
SL/TLS to attempt to use. The available options are:
CURLSLVERSIONDEFAULT
The default action. This will attempt to figure
out the remote SL protocol version, i.e. either
SLv3 or TLSv1 (but not SLv2, which became dis-
abled by default with 7.18.1).
CURLSLVERSIONTLSv1
Force TLSv1
CURLSLVERSIONSLv2
libcurl 7.19.3 Last change: 11 Dec 2008 39
libcurl Manual curleasysetopt(3)
Force SLv2
CURLSLVERSIONSLv3
Force SLv3
CURLOPTSLVERIFYPER
Pass a long as parameter.
This option determines whether curl verifies the
authenticity of the peer's certificate. A value of 1
means curl verifies; zero means it doesn't. The
default is nonzero, but before 7.10, it was zero.
When negotiating an SL connection, the server sends a
certificate indicating its identity. Curl verifies
whether the certificate is authentic, i.e. that you can
trust that the server is who the certificate says it
is. This trust is based on a chain of digital signa-
tures, rooted in certification authority (CA) certifi-
cates you supply. As of 7.10, curl installs a default
bundle of CA certificates and you can specify alternate
certificates with the CURLOPTCAINFO option or the
CURLOPTCAPATH option.
When CURLOPTSLVERIFYPER is nonzero, and the verifi-
cation fails to prove that the certificate is authen-
tic, the connection fails. When the option is zero,
the connection succeeds regardless.
Authenticating the certificate is not by itself very
useful. You typically want to ensure that the server,
as authentically identified by its certificate, is the
server you mean to be talking to. Use
CURLOPTSLVERIFYHOST to control that.
CURLOPTCAINFO
Pass a char * to a zero terminated string naming a file
holding one or more certificates to verify the peer
with. This makes sense only when used in combination
with the CURLOPTSLVERIFYPER option. If
CURLOPTSLVERIFYPER is zero, CURLOPTCAINFO need not
even indicate an accessible file.
Note that option is by default set to the system path
where libcurl's cacert bundle is assumed to be stored,
as established at build time.
When built against NS, this is the directory that the
NS certificate database resides in.
CURLOPTISUERCERT
Pass a char * to a zero terminated string naming a file
libcurl 7.19.3 Last change: 11 Dec 2008 40
libcurl Manual curleasysetopt(3)
holding a CA certificate in PEM format. If the option
is set, an additional check against the peer certifi-
cate is performed to verify the issuer is indeed the
one associated with the certificate provided by the
option. This additional check is useful in multi-level
PKI where one needs to enforce that the peer certifi-
cate is from a specific branch of the tree.
This option makes sense only when used in combination
with the CURLOPTSLVERIFYPER option. Otherwise, the
result of the check is not considered as failure.
A specific error code (CURLESLISUEREROR) is
defined with the option, which is returned if the setup
of the SL/TLS session has failed due to a mismatch
with the issuer of peer certificate
(CURLOPTSLVERIFYPER has to be set too for the check
to fail). (Added in 7.19.0)
CURLOPTCAPATH
Pass a char * to a zero terminated string naming a
directory holding multiple CA certificates to verify
the peer with. The certificate directory must be
prepared using the openssl crehash utility. This makes
sense only when used in combination with the
CURLOPTSLVERIFYPER option. If
CURLOPTSLVERIFYPER is zero, CURLOPTCAPATH need not
even indicate an accessible path. The CURLOPTCAPATH
function apparently does not work in Windows due to
some limitation in openssl. This option is OpenSL-
specific and does nothing if libcurl is built to use
GnuTLS.
CURLOPTCRLFILE
Pass a char * to a zero terminated string naming a file
with the concatenation of CRL (in PEM format) to use in
the certificate validation that occurs during the SL
exchange.
When curl is built to use NS or GnuTLS, there is no
way to influence the use of CRL passed to help in the
verification process. When libcurl is built with
OpenSL support, X509VFLAGCRLCHECK and
X509VFLAGCRLCHECKAL are both set, requiring CRL
check against all the elements of the certificate chain
if a CRL file is passed.
This option makes sense only when used in combination
with the CURLOPTSLVERIFYPER option.
A specific error code (CURLESLCRLBADFILE) is
defined with the option. It is returned when the SL
libcurl 7.19.3 Last change: 11 Dec 2008 41
libcurl Manual curleasysetopt(3)
exchange fails because the CRL file cannot be loaded.
Note that a failure in certificate verification due to
a revocation information found in the CRL does not
trigger this specific error. (Added in 7.19.0)
CURLOPTCERTINFO
Pass a long set to 1 to enable libcurl's certificate
chain info gatherer. With this enabled, libcurl (if
built with OpenSL) will extract lots of information
and data about the certificates in the certificate
chain used in the SL connection. This data is then
possible to extract after a transfer using
curleasygetinfo(3) and its option CURLINFOCERTINFO.
(Added in 7.19.1)
CURLOPTRANDOMFILE
Pass a char * to a zero terminated file name. The file
will be used to read from to seed the random engine for
SL. The more random the specified file is, the more
secure the SL connection will become.
CURLOPTEGDSOCKET
Pass a char * to the zero terminated path name to the
Entropy Gathering Daemon socket. It will be used to
seed the random engine for SL.
CURLOPTSLVERIFYHOST
Pass a long as parameter.
This option determines whether libcurl verifies that
the server cert is for the server it is known as.
When negotiating a SL connection, the server sends a
certificate indicating its identity.
When CURLOPTSLVERIFYHOST is 2, that certificate must
indicate that the server is the server to which you
meant to connect, or the connection fails.
Curl considers the server the intended one when the
Common Name field or a Subject Alternate Name field in
the certificate matches the host name in the URL to
which you told Curl to connect.
When the value is 1, the certificate must contain a
Common Name field, but it doesn't matter what name it
says. (This is not ordinarily a useful setting).
When the value is 0, the connection succeeds regardless
of the names in the certificate.
The default, since 7.10, is 2.
libcurl 7.19.3 Last change: 11 Dec 2008 42
libcurl Manual curleasysetopt(3)
This option controls checking the server's claimed
identity. The server could be lying. To control
lying, see CURLOPTSLVERIFYPER.
CURLOPTSLCIPHERLIST
Pass a char *, pointing to a zero terminated string
holding the list of ciphers to use for the SL connec-
tion. The list must be syntactically correct, it con-
sists of one or more cipher strings separated by
colons. Commas or spaces are also acceptable separators
but colons are normally used, !, - and ] can be used as
operators.
For OpenSL and GnuTLS valid examples of cipher lists
include 'RC4-SHA', 'SHA1]DES', 'TLSv1' and 'DEFAULT'.
The default list is normally set when you compile
OpenSL.
You'll find more details about cipher lists on this
URL: http:/www.openssl.org/docs/apps/ciphers.html
For NS, valid examples of cipher lists include
'rsarc4128md5', 'rsaaes128sha', etc. With NS you
don't add/remove ciphers. If one uses this option then
all known ciphers are disabled and only those passed in
are enabled.
You'll find more details about the NS cipher lists on
this URL:
http:/directory.fedora.redhat.com/docs/modnss.html#Directives
CURLOPTSLSESIONIDCACHE
Pass a long set to 0 to disable libcurl's use of SL
session-ID caching. Set this to 1 to enable it. By
default all transfers are done using the cache. Note
that while nothing ever should get hurt by attempting
to reuse SL session-IDs, there seem to be broken SL
implementations in the wild that may require you to
disable this in order for you to succeed. (Added in
7.16.0)
CURLOPTKRBLEVEL
Pass a char * as parameter. Set the kerberos security
level for FTP; this also enables kerberos awareness.
This is a string, 'clear', 'safe', 'confidential' or
'private'. If the string is set but doesn't match one
of these, 'private' will be used. Set the string to
NUL to disable kerberos support for FTP.
(This option was known as CURLOPTKRB4LEVEL up to
7.16.3)
libcurl 7.19.3 Last change: 11 Dec 2008 43
libcurl Manual curleasysetopt(3)
SH OPTIONS
CURLOPTSHAUTHTYPES
Pass a long set to a bitmask consisting of one or more
of CURLSHAUTHPUBLICKEY, CURLSHAUTHPASWORD,
CURLSHAUTHOST, CURLSHAUTHKEYBOARD. Set
CURLSHAUTHANY to let libcurl pick one. (Added in
7.16.1)
CURLOPTSHOSTPUBLICKEYMD5
Pass a char * pointing to a string containing 32 hexa-
decimal digits. The string should be the 128 bit MD5
checksum of the remote host's public key, and libcurl
will reject the connection to the host unless the
md5sums match. This option is only for SCP and SFTP
transfers. (Added in 7.17.1)
CURLOPTSHPUBLICKEYFILE
Pass a char * pointing to a file name for your public
key. If not used, libcurl defaults to using
~/.ssh/iddsa.pub. (Added in 7.16.1)
CURLOPTSHPRIVATEKEYFILE
Pass a char * pointing to a file name for your private
key. If not used, libcurl defaults to using
~/.ssh/iddsa. If the file is password-protected, set
the password with CURLOPTKEYPASWD. (Added in 7.16.1)
OTHER OPTIONS
CURLOPTPRIVATE
Pass a void * as parameter, pointing to data that
should be associated with this curl handle. The
pointer can subsequently be retrieved using
curleasygetinfo(3) with the CURLINFOPRIVATE option.
libcurl itself does nothing with this data. (Added in
7.10.3)
CURLOPTSHARE
Pass a share handle as a parameter. The share handle
must have been created by a previous call to
curlshareinit(3). Setting this option, will make this
curl handle use the data from the shared handle instead
of keeping the data to itself. This enables several
curl handles to share data. If the curl handles are
used simultaneously, you MUST use the locking methods
in the share handle. See curlsharesetopt(3) for
details.
If you add a share that is set to share cookies, your
easy handle will use that cookie cache and get the
cookie engine enabled. If you unshare an object that
was using cookies (or change to another object that
doesn't share cookies), the easy handle will get its
libcurl 7.19.3 Last change: 11 Dec 2008 44
libcurl Manual curleasysetopt(3)
cookie engine disabled.
Data that the share object is not set to share will be
dealt with the usual way, as if no share was used.
CURLOPTNEWFILEPERMS
Pass a long as a parameter, containing the value of the
permissions that will be assigned to newly created
files on the remote server. The default value is 0644,
but any valid value can be used. The only protocols
that can use this are sftp:/, scp:/, and file:/.
(Added in 7.16.4)
CURLOPTNEWDIRECTORYPERMS
Pass a long as a parameter, containing the value of the
permissions that will be assigned to newly created
directories on the remote server. The default value is
0755, but any valid value can be used. The only proto-
cols that can use this are sftp:/, scp:/, and
file:/. (Added in 7.16.4)
TELNET OPTIONS
CURLOPTELNETOPTIONS
Provide a pointer to a curlslist with variables to
pass to the telnet negotiations. The variables should
be in the format . libcurl supports the
options 'TYPE', 'XDISPLOC' and 'NEWENV'. See the TEL-
NET standard for details.
RETURN VALUE
CURLEOK (zero) means that the option was set properly,
non-zero means an error occurred as defines.
See the libcurl-errors(3) man page for the full list with
descriptions.
If you try to set an option that libcurl doesn't know about,
perhaps because the library is too old to support it or the
option was removed in a recent version, this function will
return CURLEFAILEDINIT.
SEE ALSO
curleasyinit(3), curleasycleanup(3), curleasyreset(3)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
libcurl 7.19.3 Last change: 11 Dec 2008 45
libcurl Manual curleasysetopt(3)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcurl
Interface Stability Uncommitted
NOTES
Source for C-URL is available on http:/opensolaris.org.
libcurl 7.19.3 Last change: 11 Dec 2008 46
|
