NAME
curl_easy_setopt - Set curl easy-session options
SYNOPSIS
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLoption option,
...);
DESCRIPTION
curl_easy_setopt() is called to tell libcurl how to behave
in a number of ways. Most operations in libcurl have default
actions, and by using the appropriate options you can make
them behave differently (as documented). All options are
set with the option followed by a parameter. That parameter
can be a long, a function pointer or an object pointer, all
depending on what the option in question 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.
NOTE: strings passed to libcurl as 'char *' arguments, will
not be copied by the library. Instead you should keep them
available until libcurl no longer needs them. Failing to do
so will cause very odd behaviour or even crashes.
More note: the options set with this function call are valid
for the forthcoming data transfers that are performed when
you invoke curl_easy_perform . 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.
The handle is the return code from the curl_easy_init call.
OPTIONS
These options are in a bit of random order, but you'll fig
ure it out!
CURLOPT_FILE
Data pointer to pass to file write function. Note
that if you specify the CURLOPT_WRITEFUNCTION , this
is the pointer you'll get as input. If you don't use
a callback, you must pass a 'FILE *' as libcurl
passes it to fwrite() when writing data.
NOTE: If you're using libcurl as a win32 DLL, you
MUST use the CURLOPT_WRITEFUNCTION if you set this
option.
CURLOPT_WRITEFUNCTION
Function pointer that should match the following
prototype: size_t function( void *ptr, size_t size,
size_t nmemb, void *stream); This function gets
called by libcurl as soon as there is received data
that needs to be written down. The size of the data
pointed to by ptr is size multiplied with nmemb.
Return the number of bytes actually written or
return -1 to signal error to the library (it will
cause it to abort the transfer with
CURLE_WRITE_ERROR).
Set the stream argument with the CURLOPT_FILE
option.
CURLOPT_INFILE
Data pointer to pass to the file read function. Note
that if you specify the CURLOPT_READFUNCTION, this
is the pointer you'll get as input. If you don't
specify a read callback, this must be a valid FILE
*.
NOTE: If you're using libcurl as a win32 DLL, you
MUST use a CURLOPT_READFUNCTION if you set this
option.
CURLOPT_READFUNCTION
Function pointer that should match the following
prototype: size_t function( void *ptr, size_t size,
size_t nmemb, void *stream); 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 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 -1
will signal an error to the library and cause it to
abort the current transfer immediately (with a
CURLE_READ_ERROR return code).
CURLOPT_INFILESIZE
When uploading a file to a remote site, this option
should be used to tell libcurl what the expected
size of the infile is.
CURLOPT_URL
The actual URL to deal with. The parameter should be
a char * to a zero terminated string. The string
must remain present until curl no longer needs it,
as it doesn't copy the string. NOTE: this option is
required to be set before curl_easy_perform() is
called.
CURLOPT_PROXY
If you need libcurl to use a http proxy to access
the outside world, set the proxy string with this
option. The parameter should be a char * to a zero
terminated string. 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.
CURLOPT_PROXYPORT
Set this long with this option to set the proxy port
to use unless it is specified in the proxy string
CURLOPT_PROXY.
CURLOPT_HTTPPROXYTUNNEL
Set the parameter to non-zero to get the library to
tunnel all non-HTTP operations through the given
HTTP proxy. Do note that there is a big difference
to use a proxy and to tunnel through it. If you
don't know what this means, you probably don't want
this tunnel option. (Added in libcurl 7.3)
CURLOPT_VERBOSE
Set the parameter to non-zero to get the library to
display a lot of verbose information about its oper
ations. Very useful for libcurl and/or protocl
debugging and understanding.
CURLOPT_HEADER
A non-zero parameter tells the library to include
the header in the output. This is only relevant for
protocols that actually has a header preceeding the
data (like HTTP).
CURLOPT_NOPROGRESS
A non-zero parameter tells the library to shut of
the built-in progress meter completely. (NOTE:
future versions of the lib is likely to not have any
built-in progress meter at all).
CURLOPT_NOBODY
A non-zero parameter tells the library to not
include the body-part in the output. This is only
relevant for protocols that have a separate header
and body part.
CURLOPT_FAILONERROR
A non-zero parameter tells the library to fail
silently if the HTTP code returned is equal or
larger than 300. The default action would be to
return the page normally, ignoring that code.
CURLOPT_UPLOAD
A non-zero parameter tells the library to prepare
for an upload. The CURLOPT_INFILE and CUR
LOPT_INFILESIZE are also interesting for uploads.
CURLOPT_POST
A non-zero parameter tells the library to do a regu
lar HTTP post. This is a normal application/x-www-
form-urlencoded kind, which is the most commonly
used one by HTML forms. See the CURLOPT_POSTFIELDS
option for how to specify the data to post and CUR
LOPT_POSTFIELDSIZE in how to set the data size.
Starting with libcurl 7.8, this option is obsolete.
Using the CURLOPT_POSTFIELDS option will imply this
option.
CURLOPT_FTPLISTONLY
A non-zero parameter tells the library to just list
the names of an ftp directory, instead of doing a
full directory listin that would include file sizes,
dates etc.
CURLOPT_FTPAPPEND
A non-zero parameter tells the library to append to
the remote file instead of overwrite it. This is
only useful when uploading to a ftp site.
CURLOPT_NETRC
A non-zero parameter tells the library to scan your
~/.netrc file to find user name and password for the
remote site you are about to access. Do note that
curl does not verify that the file has the correct
properties set (as the standard unix ftp client
does), and that only machine name, user name and
password is taken into account (init macros and sim
ilar things aren't supported).
CURLOPT_FOLLOWLOCATION
A non-zero parameter tells the library to follow any
Location: header that the server sends as part of a
HTTP header. NOTE that this means that the library
will resend the same request on the new location and
follow new Location: headers all the way until no
more such headers are returned.
CURLOPT_TRANSFERTEXT
A non-zero parameter tells the library to use ASCII
mode for ftp transfers, instead of the default
binary transfer. For LDAP transfers it gets the data
in plain text instead of HTML and for win32 systems
it does not set the stdout to binary mode. This
option can be useable when transfering text data
between system with different views on certain char
acters, such as newlines or similar.
CURLOPT_PUT
A non-zero parameter tells the library to use HTTP
PUT a file. The file to put must be set with CUR
LOPT_INFILE and CURLOPT_INFILESIZE.
CURLOPT_USERPWD
Pass a char * as parameter, which should be [user
name]:[password] to use for the connection. If the
password is left out, you will be prompted for it.
CURLOPT_PROXYUSERPWD
Pass a char * as parameter, which should be [user
name]:[password] to use for the connection to the
HTTP proxy. If the password is left out, you will be
prompted for it.
CURLOPT_RANGE
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. HTTP transfers
also support several intervals, separated with com
mas as in X-Y,N-M response document in pieces.
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 the library.
The buffer must be at least CURL_ERROR_SIZE big.
CURLOPT_TIMEOUT
Pass a long as parameter containing the maximum time
in seconds that you allow the libcurl transfer oper
ation 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 timeouting system calls. NOTE
that this does not work in multi-threaded programs!
CURLOPT_POSTFIELDS
Pass a char * as parameter, which should be the full
data to post in a HTTP post operation. See also the
CURLOPT_POST. Since 7.8, using CURLOPT_POSTFIELDS
implies CURLOPT_POST.
CURLOPT_POSTFIELDSIZE
If you want to post data to the server without let
ting libcurl do a strlen() to measure the data size,
this option must be used. Also, when this option is
used, you can post fully binary data which otherwise
is likely to fail. If this size is set to zero, the
library will use strlen() to get the data size.
(Added in libcurl 7.2)
CURLOPT_REFERER
Pass a pointer to a zero terminated string as param
eter. 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.
CURLOPT_USERAGENT
Pass a pointer to a zero terminated string as param
eter. 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.
CURLOPT_FTPPORT
Pass a pointer to a zero terminated string as param
eter. 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, an network interface name (under unix) or
just a '-' letter to let the library use your sys
tems default IP address.
CURLOPT_LOW_SPEED_LIMIT
Pass a long as parameter. It contains the transfer
speed in bytes per second that the transfer should
be below during CURLOPT_LOW_SPEED_TIME seconds for
the library to consider it too slow and abort.
CURLOPT_LOW_SPEED_TIME
Pass a long as parameter. It contains the time in
seconds that the transfer should be below the CUR
LOPT_LOW_SPEED_LIMIT for the library to consider it
too slow and abort.
CURLOPT_RESUME_FROM
Pass a long as parameter. It contains the offset in
number of bytes that you want the transfer to start
from.
CURLOPT_COOKIE
Pass a pointer to a zero terminated string as param
eter. 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.
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 'struct
curl_slist' structs properly filled in. Use
curl_slist_append(3) to create the list and
curl_slist_free_all(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 contents
as in 'Accept:', the internally used header will
just get disabled. Thus, using this option you can
add new headers, replace internal headers and remove
internal headers.
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 HTTP post structs as parameter. The linked list
should be a fully valid list of 'struct HttpPost'
structs properly filled in. The best and most ele
gant way to do this, is to use curl_formadd(3) as
documented. The data in this list must remained
intact until you close this curl handle again with
curl_easy_cleanup().
CURLOPT_SSLCERT
Pass a pointer to a zero terminated string as param
eter. The string should be the file name of your
certficicate in PEM format.
CURLOPT_SSLCERTPASSWD
Pass a pointer to a zero terminated string as param
eter. It will be used as the password required to
use the CURLOPT_SSLCERT certificate. If the password
is not supplied, you will be prompted for it.
CURLOPT_CRLF
Convert unix newlines to CRLF newlines on FTP
uploads.
CURLOPT_QUOTE
Pass a pointer to a linked list of FTP commands to
pass to the server prior to your ftp request. The
linked list should be a fully valid list of 'struct
curl_slist' structs properly filled in. Use
curl_slist_append(3) to append strings (commands) to
the list, and clear the entire list afterwards with
curl_slist_free_all(3)
CURLOPT_POSTQUOTE
Pass a pointer to a linked list of FTP commands to
pass to the server after your ftp transfer request.
The linked list should be a fully valid list of
struct curl_slist structs properly filled in as
described for CURLOPT_QUOTE
CURLOPT_WRITEHEADER
Pass a pointer to be used to write the header part
of the received data to. If you don't use a callback
to take care of the writing, this must be a FILE *.
The headers are guaranteed to be written one-by-one
and only complete lines are written. Parsing headers
should be easy enough using this. See also the CUR
LOPT_HEADERFUNCTION option.
CURLOPT_HEADERFUNCTION
Function pointer that should match the following
prototype: size_t function( void *ptr, size_t size,
size_t nmemb, void *stream); This function gets
called by libcurl as soon as there is received
header data that needs to be written down. The func
tion will be called once for each header with a com
plete header line in each invoke. The size of the
data pointed to by ptr is size multiplied with
nmemb. The pointer named stream will be the one you
passed to libcurl with the CURLOPT_WRITEHEADER
option. Return the number of bytes actually written
or return -1 to signal error to the library (it will
cause it to abort the transfer with a
CURLE_WRITE_ERROR return code). (Added in libcurl
7.7.2)
CURLOPT_COOKIEFILE
Pass a pointer to a zero terminated string as param
eter. It should contain the name of your file hold
ing cookie data. The cookie data may be in Netscape
/ Mozilla cookie data format or just regular HTTP-
style headers dumped to a file.
CURLOPT_SSLVERSION
Pass a long as parameter. Set what version of SSL to
attempt to use, 2 or 3. By default, the SSL library
will try to solve this by itself although some
servers make this difficult why you at times will
have to use this option.
CURLOPT_TIMECONDITION
Pass a long as parameter. This defines how the CUR
LOPT_TIMEVALUE time value is treated. You can set
this parameter to TIMECOND_IFMODSINCE or TIME
COND_IFUNMODSINCE. This is aa HTTP-only feature.
(TBD)
CURLOPT_TIMEVALUE
Pass a long as parameter. This should be the time in
seconds since 1 jan 1970, and the time will be used
as specified in CURLOPT_TIMECONDITION or if that
isn't used, it will be TIMECOND_IFMODSINCE by
default.
CURLOPT_CUSTOMREQUEST
Pass a pointer to a zero terminated string as param
eter. It will be user instead of GET or HEAD when
doing the HTTP request. This is useful for doing
DELETE or other more obscure HTTP requests. Don't do
this at will, make sure your server supports the
command first.
CURLOPT_STDERR
Pass a FILE * as parameter. This is the stream to
use instead of stderr internally when reporting
errors.
CURLOPT_INTERFACE
Pass a char * as parameter. This set the interface
name to use as outgoing network interface. The name
can be an interface name, an IP address or a host
name. (Added in libcurl 7.3)
CURLOPT_KRB4LEVEL
Pass a char * as parameter. Set the krb4 security
level, this also enables krb4 awareness. This is a
string, 'clear', 'safe', 'confidential' or 'pri
vate'. If the string is set but doesn't match one
of these, 'private' will be used. Set the string to
NULL to disable kerberos4. The kerberos support only
works for FTP. (Added in libcurl 7.3)
CURLOPT_WRITEINFO
(NOT PRESENT IN 7.4 or later!) Pass a pointer to a
zero terminated string as parameter. It will be used
to report information after a successful request.
This string may contain variables that will be sub
stituted by their contents when output. Described
elsewhere.
CURLOPT_PROGRESSFUNCTION
Function pointer that should match the
curl_progress_callback prototype found in
<curl/curl.h> This function gets called by libcurl
instead of its internal equivalent. Unknown/unused
argument values 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
CURLE_ABORTED_BY_CALLBACK.
CURLOPT_PROGRESSDATA
Pass a pointer that will be untouched by libcurl and
passed as the first argument in the progress call
back set with CURLOPT_PROGRESSFUNCTION
.
CURLOPT_SSL_VERIFYPEER
Pass a long that is set to a non-zero value to make
curl verify the peer's certificate. The certificate
to verify against must be specified with the CUR
LOPT_CAINFO option. (Added in 7.4.2)
CURLOPT_CAINFO
Pass a char * to a zero terminated file naming hold
ing the certificate to verify the peer with. This
only makes sense when used in combination with the
CURLOPT_SSL_VERIFYPEER option. (Added in 7.4.2)
CURLOPT_PASSWDFUNCTION
Pass a pointer to a curl_passwd_callback function
that will then be called instead of the internal one
if libcurl requests a password. The function must
match this prototype: int my_getpass(void *client,
char *prompt, char* buffer, int buflen ); If set to
NULL, it equals to making the function always fail.
If the function returns a non-zero value, it will
abort the operation and an error (CURLE_BAD_PASS
WORD_ENTERED) will be returned. client is a generic
pointer, see CURLOPT_PASSWDDATA. prompt is a zero-
terminated string that is text that prefixes the
input request. buffer is a pointer to data where
the entered password should be stored and buflen is
the maximum number of bytes that may be written in
the buffer. (Added in 7.4.2)
CURLOPT_PASSWDDATA
Pass a void * to whatever data you want. The passed
pointer will be the first argument sent to the
specifed CURLOPT_PASSWDFUNCTION function. (Added in
7.4.2)
CURLOPT_FILETIME
Pass a long. If it is a non-zero value, 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 curl_easy_getinfo() function
with the CURLINFO_FILETIME argument can be used
after a transfer to extract the received time (if
any). (Added in 7.5)
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. This option
only makes sense if the CURLOPT_FOLLOWLOCATION is
used at the same time. (Added in 7.5)
CURLOPT_MAXCONNECTS
Pass a long. The set number will be the persistant
connection cache size. The set amount will be the
maximum amount of simultaneous connections that
libcurl may cache between file transfers. Default is
5, and there isn't much point in changing this value
unless you are perfectly aware of how this work and
changes libcurl's behaviour. Note: if you have
already performed transfers with this curl handle,
setting a smaller MAXCONNECTS than before may cause
open connections to unnecessarily get closed. (Added
in 7.7)
CURLOPT_CLOSEPOLICY
Pass a long. This option sets what policy libcurl
should use when the connection cache is filled and
one of the open connections has to be closed to make
room for a new connection. This must be one of the
CURLCLOSEPOLICY_* defines. Use CURLCLOSEPOL
ICY_LEAST_RECENTLY_USED to make libcurl close the
connection that was least recently used, that con
nection is also least likely to be capable of re-
use. Use CURLCLOSEPOLICY_OLDEST to make libcurl
close the oldest connection, the one that was cre
ated first among the ones in the connection cache.
The other close policies are not support yet. (Added
in 7.7)
CURLOPT_FRESH_CONNECT
Pass a long. Set to non-zero to make the next trans
fer use a new connection by force. If the connection
cache is full before this connection, one of the
existinf connections will be closed as according to
the set policy. This option should be used with cau
tion and only if you understand what it does. Set to
0 to have libcurl attempt re-use of an existing con
nection. (Added in 7.7)
CURLOPT_FORBID_REUSE
Pass a long. Set to non-zero to make the next trans
fer explicitly close the connection when done. Nor
mally, libcurl keep all connections alive when done
with one transfer in case there comes a succeeding
one 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 possibly later re-use. (Added in 7.7)
CURLOPT_RANDOM_FILE
Pass a char * to a zero terminated file name. The
file will be used to read from to seed the random
engine for SSL. The more random the specified file
is, the more secure will the SSL connection become.
CURLOPT_EGDSOCKET
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 SSL.
CURLOPT_CONNECTTIMEOUT
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 CURLOPT_TIMEOUT option.
NOTE that this does not work in multi-threaded pro
grams!
CURLOPT_HTTPGET
Pass a long. If the long is non-zero, this forces
the HTTP request to get back to GET. Only really
usable if POST, PUT or a custom request have been
used previously using the same curl handle. (Added
in 7.8.1)
CURLOPT_SSL_VERIFYHOST
Pass a long. Set if we should verify the Common name
from the peer certificate in the SSL handshake, set
1 to check existence, 2 to ensure that it matches
the provided hostname. (Added in 7.8.1)
CURLOPT_COOKIEJAR
Pass a file name as char *, zero terminated. This
will make libcurl dump all internally known cookies
to the specified file when curl_easy_cleanup() is
called. If no cookies are known, no file will be
created. Specify "-" to instead have the cookies
written to stdout.
CURLOPT_SSL_CIPHER_LIST
Pass a char *, pointing to a zero terminated string
holding the list of ciphers to use for the SSL con
nection. The list must be syntactly correct, it con
sists of one or more cipher strings separated by
colons. Commas or spaces are also acceptable separa
tors but colons are normally used, , - and + can be
used as operators. Valid examples of cipher lists
include 'RC4-SHA', ´SHA1+DES´, 'TLSv1' and
'DEFAULT'. The default list is normally set when you
compile OpenSSL.
You'll find all details about cipher lists on this
URL: http://www.openssl.org/docs/apps/ciphers.html
RETURN VALUE
0 means the option was set properly, non-zero means an error
as <curl/curl.h> defines
SEE ALSO
curl_easy_init(3), curl_easy_cleanup(3),
BUGS
Surely there are some, you tell me!
Man(1) output converted with
man2html