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  ques­
       tion expects. Read this manual carefully as bad input val­
       ues 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  per­
       formed  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
       figure 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

               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 multi­
               plied 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  trans­
               fer 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 immedi­
               ately (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

               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 [pro­
               tocol]:// 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 dif­
               ference  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
               operations. 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 preceed­
               ing 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.

               A non-zero parameter tells the  library  to  do  a
               regular HTTP post. This is a normal application/x-
               www-form-urlencoded kind, which is the  most  com­
               monly  used  one  by  HTML  forms.  See  the  CUR­
               LOPT_POSTFIELDS option for how to specify the data
               to  post  and  CURLOPT_POSTFIELDSIZE in how to set
               the data size.

       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 similar 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 differ­
               ent views on certain characters, 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.

               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,  sepa­
               rated  with commas 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 trans­
               fer operation to take. Do note that normally, name
               lookups  maky  take  a  considerable time and that
               limiting the operation 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.

       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.

       CURLOPT_POSTFIELDSIZE
               If  you  want  to  post data to the server without
               letting libcurl do a strlen() to measure the  data
               size,  this  option  must be used. 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
               parameter. It will be used  to  set  the  referer:
               header  in  the  http  request  sent to the remote

               scripts.

       CURLOPT_USERAGENT
               Pass  a  pointer  to  a  zero terminated string as
               parameter. It will be used to set the  user-agent:
               header  in  the  http  request  sent to the remote
               server. This  can  be  used  to  fool  servers  or
               scripts.

       CURLOPT_FTPPORT
               Pass  a  pointer  to  a  zero terminated string as
               parameter. 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  inter­
               face name (under unix) or just a '-' letter to let
               the library use your systems 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
               parameter.  It will be used to set a cookie in the
               http request. The format of the string  should  be
               [NAME]=[CONTENTS];  Where NAME is the cookie name.

       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

               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 Http­
               Post'  structs  properly  filled  in. The best and
               most elegant way to do this, is to use  curl_form­
               parse(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
               parameter. The string should be the file  name  of
               your certficicate in PEM format.

       CURLOPT_SSLCERTPASSWD
               Pass  a  pointer  to  a  zero terminated string as
               parameter.  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  (com­
               mands)  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 call­
               back 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.

               See also the CURLOPT_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  function  will be called once for each
               header with a complete 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
               parameter. It should contain the name of your file
               holding cookie data. The cookie  data  may  be  in
               Netscape / Mozilla cookie data format or just reg­
               ular 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
               CURLOPT_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
               parameter.  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


       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 substituted 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
               callback 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  cer­
               tificate  to verify against must be specified with
               the CURLOPT_CAINFO option. (Added in 7.4.2)

               Pass a char * to a  zero  terminated  file  naming
               holding  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_PASSWORD_ENTERED)  will  be   returned.
               client  is  a generic pointer, see CURLOPT_PASSWD­
               DATA.  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_get­
               info()  function  with the CURLINFO_FILETIME argu­
               ment 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 redirec­
               tion limit. If that many  redirections  have  been
               followed,  the  next redirect will cause an error.
               This option only makes sense if  the  CURLOPT_FOL­
               LOWLOCATION  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

               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  CURLCLOSE­
               POLICY_LEAST_RECENTLY_USED  to  make libcurl close
               the connection that was least recently used,  that
               connection  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
               transfer  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 caution and only if you understand what
               it does. Set to 0 to have libcurl  attempt  re-use
               of an existing connection.  (Added in 7.7)

       CURLOPT_FORBID_REUSE
               Pass  a  long.  Set  to  non-zero to make the next
               transfer  explicitly  close  the  connection  when
               done. Normally, 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 under­
               stand  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


       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 time­
               out (it will then only  timeout  on  the  system's
               internal  timeouts).  See also the CURLOPT_TIMEOUT
               option.


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