NAME

     curl_easy_setopt - set options for a curl easy handle


SYNOPSIS

     #include <curl/curl.h>

     CURLcode  curl_easy_setopt(CURL  *handle, CURLoption option,
     parameter);


DESCRIPTION

     curl_easy_setopt() is used to tell libcurl how to behave. By
     using  the  appropriate options to curl_easy_setopt, 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 or an object pointer, all depending
     on  what the specific option expects. Read this manual care­
     fully 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 behavior or even crashes.

     NOTE2: 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 a curl_easy_init(3) or
     curl_easy_duphandle(3) call.


BEHAVIOR OPTIONS

     CURLOPT_VERBOSE
         Set the parameter to non-zero to get the library to dis­
         play  a lot of verbose information about its operations.
         Very useful for libcurl and/or  protocol  debugging  and
         understanding.

         You  hardly  ever  want  this set in production use, you
         will almost always want this when you debug/report prob­
         lems.  Another  neat  option  for  debugging is the CUR­
         LOPT_DEBUGFUNCTION.

     CURLOPT_HEADER
         A non-zero parameter tells the library  to  include  the
         header  in  the  body  output. This is only relevant for
         protocols that actually have headers preceding the  data
         (like HTTP).

     CURLOPT_NOPROGRESS
         A  non-zero  parameter  tells the library to shut of the
         built-in progress meter completely.

         NOTE: future versions of libcurl is likely to  not  have
         any built-in progress meter at all.

     CURLOPT_NOSIGNAL
         Pass a long. If it is non-zero, libcurl will not use any
         functions that install signal handlers or any  functions
         that  cause  signals  to  be  sent  to the process. This
         option is  mainly  here  to  allow  multi-threaded  unix
         applications  to  still set/use all timeout options etc,
         without risking getting signals.  (Added in 7.10)


CALLBACK OPTIONS

     CURLOPT_WRITEFUNCTION
         Function pointer that should match the following  proto­
         type:  size_t  function(  void *ptr, size_t size, size_t
         nmemb, void  *stream);  This  function  gets  called  by
         libcurl  as soon as there is data reveiced that needs to
         be saved. The size of the data pointed to by ptr is size
         multiplied with nmemb.  Return the number of bytes actu­
         ally 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
         CURLE_WRITE_ERROR.

         Set the stream argument with the CURLOPT_FILE option.

         NOTE: you will be passed as much data as possible in all
         invokes, but you cannot possibly make  any  assumptions.
         It  may  be  one  byte, it may be thousands. The maximum
         amount of data that can be passed to the write  callback
         is     defined    in    the    curl.h    header    file:
         CURL_MAX_WRITE_SIZE.

     CURLOPT_WRITEDATA
         Data pointer to pass to the 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 will pass
         this 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 or
         you will experience crashes.

         This option is also  known  with  the  older  name  CUR­
         LOPT_FILE,  the name CURLOPT_WRITEDATA was introduced in
         7.9.7.

     CURLOPT_READFUNCTION
         Function pointer that should match the following  proto­
         type:  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 mem­
         ory area. Returning 0 will  signal  end-of-file  to  the
         library and cause it to stop the current transfer.

     CURLOPT_READDATA
         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.

         This  option  is  also  known  with  the older name CUR­
         LOPT_INFILE, the name CURLOPT_READDATA was introduced in
         7.9.7.

     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 with a frequent interval during data
         transfer.  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.

         Also  note  that CURLOPT_NOPROGRESS must be set to FALSE
         to make this function actually get called.

     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_PASSWDFUNCTION
         Pass a pointer to a curl_passwd_callback  function  that
         will  be  called  instead of the internal one if libcurl
         requests a password. The function must match this proto­
         type:  int  getpass(void  *client,  char  *prompt, char*
         buffer, int buflen );.  If set to NULL, it sets back the
         function  to  the  internal default one. 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   CUR­
         LOPT_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_HEADERFUNCTION
         Function  pointer that should match the following proto­
         type: 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 headers are guaranteed to
         be written one-by-one and only complete lines are  writ­
         ten.  Parsing  headers should be easy enough using this.
         The size of the data pointed to by ptr  is  size  multi­
         plied  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 7.7.2)

     CURLOPT_WRITEHEADER
         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 CURLOPT_HEADERFUNCTION option below on
         how to set a custom get-all-headers callback.

     CURLOPT_DEBUGFUNCTION
         Function pointer that should match the following  proto­
         type:  int  curl_debug_callback  (CURL *, curl_infotype,
         char *, size_t, void  *);  This  function  will  receive
         debug  information  if  CURLOPT_VERBOSE  is enabled. The
         curl_infotype argument specifies what kind  of  informa­
         tion it is. This funtion must return 0.

     CURLOPT_DEBUGDATA
         Pass  a  pointer  to whatever you want passed in to your
         CURLOPT_DEBUGFUNCTION in the last void * argument.  This
         pointer is not used by libcurl, it is only passed to the
         callback.


ERROR OPTIONS

     CURLOPT_ERRORBUFFER
         Pass a char * to a buffer that  the  libcurl  may  store
         human readable error messages in. This may be more help­
         ful than just the return  code  from  the  library.  The
         buffer must be at least CURL_ERROR_SIZE big.

         Use  CURLOPT_VERBOSE and CURLOPT_DEBUGFUNCTION to better
         debug/trace why errors happen.

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

     CURLOPT_STDERR
         Pass a FILE * as parameter. This is the  stream  to  use
         instead of stderr internally when reporting errors.

     CURLOPT_FAILONERROR
         A  non-zero parameter tells the library to fail silently
         if the HTTP code returned is equal  to  or  larger  than
         300. The default action would be to return the page nor­
         mally, ignoring that code.


NETWORK OPTIONS

     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 (the only one) required to be set
         before curl_easy_perform(3) is called.

     CURLOPT_PROXY
         Set HTTP proxy to use. The parameter should be a char  *
         to  a  zero  terminated  string holding the host name or
         dotted IP  address.  To  specify  port  number  in  this
         string,  append :[port] to the end of the host name. The
         proxy string may be prefixed  with  [protocol]://  since
         any such prefix will be ignored. The proxy's port number
         may optionally be specified  with  the  separate  option
         CURLOPT_PROXYPORT.

         NOTE:  when  you  tell  the library to use a HTTP proxy,
         libcurl will transparently convert  operations  to  HTTP
         even  if  you  specify  a  FTP URL etc. This may have an
         impact on what other features of  the  library  you  can
         use,  such  as  CURLOPT_QUOTE  and similar FTP specifics
         that don't work  unless  you  tunnel  through  the  HTTP
         proxy.  Such  tunneling  is activated with CURLOPT_HTTP­
         PROXYTUNNEL.
         NOTE2:  libcurl  respects  the   environment   variables
         http_proxy, ftp_proxy, all_proxy etc, if any of those is
         set.

     CURLOPT_PROXYPORT
         Pass a long with this option to set the  proxy  port  to
         connect  to  unless  it is specified in the proxy string
         CURLOPT_PROXY.

     CURLOPT_PROXTYPE
         Pass a long with this option to set type of  the  proxy.
         Available  options for this are CURLPROXY_HTTP and CURL­
         PROXY_SOCKS5, with the HTTP one being default. (Added in
         7.10)

     CURLOPT_HTTPPROXYTUNNEL
         Set the parameter to non-zero to get the library to tun­
         nel all operations through a given HTTP proxy. Note that
         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. (Added in
         7.3)

     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
         7.3)

     CURLOPT_DNS_CACHE_TIMEOUT
         Pass  a  long,  this  sets  the timeout in seconds. Name
         resolves will be kept in memory for this number of  sec­
         onds.  Set to zero (0) to completely disable caching, or
         set to -1 to make the cached entries remain forever.  By
         default,  libcurl  caches info for 60 seconds. (Added in
         7.9.3)

     CURLOPT_DNS_USE_GLOBAL_CACHE
         Pass a long. If the value is non-zero, 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 varible. (Added in 7.9.3)

     CURLOPT_BUFFERSIZE
         Pass  a  long  specifying  your  prefered  size  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)



NAMES and PASSWORDS OPTIONS

     CURLOPT_NETRC
         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 CURLOPT_URL.

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

         Pass a long, set to one of the values described below.

         CURL_NETRC_OPTIONAL
              The  use  of  your  ~/.netrc  file is optional, and
              information in the URL is  to  be  preferred.   The
              file  will  be  scanned with the host and user name
              (to find the password only) or with the host  only,
              to find the first user name and password after that
              machine, which ever information is not specified in
              the URL.

              Undefined  values  of  the  option  will  have this
              effect.

         CURL_NETRC_IGNORED
              The library will ignore the file and use  only  the
              information in the URL.

              This is the default.

         CURL_NETRC_REQUIRED
              This  value  tells the library that use of the file
              is required, to ignore the information in the  URL,
              and to search the file with the host only.

     Only machine name, user name and password are taken into
         account
         (init macros and similar things aren't supported).

         Note: libcurl does not verify that the file has the cor­
         rect  properties  set  (as  the standard Unix ftp client
         does). It should only be readable by user.

     CURLOPT_USERPWD
         Pass a char  *  as  parameter,  which  should  be  [user
         name]:[password] to use for the connection. If the pass­
         word is left out, you will be  prompted  for  it.   CUR­
         LOPT_PASSWDFUNCTION  can  be used to set your own prompt
         function.

     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_PASSWDFUNCTION can be used to set your
         own prompt function.


HTTP OPTIONS

     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: 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.  CURLOPT_MAXREDIRS  can  be  used to limit the
         number of redirects libcurl will follow.

     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  (CURLE_TOO_MANY_REDI­
         RECTS). This option only makes sense if the CURLOPT_FOL­
         LOWLOCATION is used at the same time. (Added in 7.5)

     CURLOPT_PUT
         A non-zero parameter tells the library to use  HTTP  PUT
         to  transfer  data.  The  data  should  be set with CUR­
         LOPT_READDATA and CURLOPT_INFILESIZE.

     CURLOPT_POST
         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 commonly used one  by
         HTML forms. See the CURLOPT_POSTFIELDS option for how to
         specify the data to post  and  CURLOPT_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_POSTFIELDS
         Pass  a  char  *  as parameter, which should be the full
         data to post in a HTTP post operation. This is a  normal
         application/x-www-form-urlencoded  kind,  which  is  the
         most commonly used one by HTML forms. See also the  CUR­
         LOPT_POST.  Since  7.8, using CURLOPT_POSTFIELDS implies
         CURLOPT_POST.

         Note:   to   make    multipart/formdata    posts    (aka
         rfc1867-posts), check out the CURLOPT_HTTPPOST option.

     CURLOPT_POSTFIELDSIZE
         If  you  want to post data to the server without letting
         libcurl do a strlen() to measure  the  data  size,  this
         option  must  be  used. When this option is used you can
         post fully binary data, which  otherwise  is  likely  to
         fail.  If this size is set to zero, the library will use
         strlen() to get the size. (Added in libcurl 7.2)

     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 elegant way to do this, is to use
         curl_formadd(3) as documented. The  data  in  this  list
         must  remain  intact  until  you  close this curl handle
         again with curl_easy_cleanup(3).

     CURLOPT_REFERER
         Pass a pointer to a zero terminated string as parameter.
         It  will  be used to set the Referer: header in the http
         request sent to the remote server. This can be  used  to
         fool  servers  or  scripts.  You can also set any custom
         header with CURLOPT_HTTPHEADER.

     CURLOPT_USERAGENT
         Pass a pointer to a zero terminated string as parameter.
         It  will  be  used  to set the User-Agent: header in the
         http request sent to the remote server. This can be used
         to  fool servers or scripts. You can also set any custom
         header with CURLOPT_HTTPHEADER.

     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 con­
         tents as in 'Accept:' (no data on the right side of  the
         colon),  the  internally  used header will get disabled.
         Thus, using this option you can add new headers, replace
         internal headers and remove internal headers.

         NOTE:The most commonly replaced headers have "shortcuts"
         in the  options  CURLOPT_COOKIE,  CURLOPT_USERAGENT  and
         CURLOPT_REFERER.

     CURLOPT_COOKIE
         Pass a pointer to a zero terminated string as parameter.
         It will be used to set a cookie in the http request. The
         format of the string should be NAME=CONTENTS, where NAME
         is the cookie name  and  CONTENTS  is  what  the  cookie
         should contain.

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

         Using this option multiple times will only make the lat­
         est string override the previously ones.

     CURLOPT_COOKIEFILE
         Pass a pointer to a zero terminated string as parameter.
         It  should  contain the name of your file holding cookie
         data to read. The cookie  data  may  be  in  Netscape  /
         Mozilla  cookie  data  format or just regular HTTP-style
         headers dumped to a file.

         Given an empty or non-existing file,  this  option  will
         enable  cookies  for  this curl handle, making it under­
         stand and parse received cookies and then  use  matching
         cookies in future request.

     CURLOPT_COOKIEJAR
         Pass  a  file name as char *, zero terminated. This will
         make libcurl write all internally known cookies  to  the
         specified  file  when curl_easy_cleanup(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 session, so if
         you  for example follow a location it will make matching
         cookies get sent accordingly. (Added in 7.9)

     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   TIMECOND_IFUN­
         MODSINCE. This is a 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 in a
         condition as specified with CURLOPT_TIMECONDITION.

     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_HTTP_VERSION
         Pass a long, set to one of the values  described  below.
         They  force  libcurl  to use the specific HTTP versions.
         This is not sensible to do unless you have a  good  rea­
         son.

         CURL_HTTP_VERSION_NONE
              We  don't care about what version the library uses.
              libcurl will use whatever it thinks fit.

         CURL_HTTP_VERSION_1_0
              Enforce HTTP 1.0 requests.

         CURL_HTTP_VERSION_1_1
              Enforce HTTP 1.1 requests.


FTP OPTIONS

     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  net­
         work interface name (under Unix) or just a '-' letter to
         let the library use your  systems  default  IP  address.
         Default  FTP  operations are passive, and thus won't use
         PORT.

     CURLOPT_QUOTE
         Pass a pointer to a linked list of FTP commands to  pass
         to  the  server  prior to your ftp request. This will be
         done before any other  FTP  commands  are  issued  (even
         before  the  CWD  command).  The linked list should be a
         fully valid list of to append strings (commands) to  the
         list,   and   clear  the  entire  list  afterwards  with
         curl_slist_free_all(3). Disable this operation again  by
         setting a NULL to this option.

     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. Disable this operation again by setting a
         NULL to this option.

     CURLOPT_PREQUOTE
         Pass a pointer to a linked list of FTP commands to  pass
         to the server after the transfer type is set. The linked
         list should be a fully valid list of  struct  curl_slist
         structs   properly  filled  in  as  described  for  CUR­
         LOPT_QUOTE. Disable this operation again  by  setting  a
         NULL to 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  listing  that would include file sizes, dates
         etc.

         This causes an FTP NLST command to be sent.  Beware that
         some  FTP  servers  list only files in their response to
         NLST; they might not include subdirectories and symbolic
         links.

     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_FTP_USE_EPSV
         Pass  a long. If the value is non-zero, 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 FALSE (zero) to this option, it will not try
         using EPSV, only plain PASV.


PROTOCOL OPTIONS

     CURLOPT_TRANSFERTEXT
         A non-zero parameter tells the library to use ASCII mode
         for  ftp transfers, instead of the default binary trans­
         fer. 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  usable
         when transferring text data between systems with differ­
         ent views on certain characters,  such  as  newlines  or
         similar.

     CURLOPT_CRLF
         Convert Unix newlines to CRLF newlines on transfers.

     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 commas  as  in
         "X-Y,N-M".  Using  this  kind of multiple intervals will
         cause the HTTP server to send the response  document  in
         pieces (using standard MIME separation techniques).

     CURLOPT_RESUME_FROM
         Pass a long as parameter. It contains the offset in num­
         ber of bytes that you want the transfer to start from.

     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  or  less  obscure  HTTP requests. Don't do this at
         will, make sure your server supports the command  first.

     CURLOPT_FILETIME
         Pass  a  long.  If  it is a non-zero value, libcurl will
         attempt to get the modification date of the remote docu­
         ment  in  this  operation. This requires that the remote
         server sends the time or replies to a time querying com­
         mand.   The   curl_easy_getinfo(3)   function  with  the
         CURLINFO_FILETIME argument can be used after a  transfer
         to extract the received time (if any). (Added in 7.5)

     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 separate header and body parts.

     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_UPLOAD
         A non-zero parameter tells the library to prepare for an
         upload. The CURLOPT_READDATA and CURLOPT_INFILESIZE  are
         also interesting for uploads.


CONNECTION OPTIONS

     CURLOPT_TIMEOUT
         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.

         NOTE:  this  is  not  recommended  to use in unix multi-
         threaded  programs,  as  it  uses  signals  unless  CUR­
         LOPT_NOSIGNAL (see below) is set.

     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  sec­
         onds   that  the  transfer  should  be  below  the  CUR­
         LOPT_LOW_SPEED_LIMIT for the library to consider it  too
         slow and abort.

     CURLOPT_MAXCONNECTS
         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. 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. This con­
         cerns connection using any of the protocols that support
         persistent connections.

         When reaching the maximum  limit,  curl  uses  the  CUR­
         LOPT_CLOSEPOLICY  to  figure  out  which of the existing
         connections to close to prevent the number of open  con­
         nections to increase.

         NOTE:  if you already have performed transfers with this
         curl handle, setting a smaller MAXCONNECTS  than  before
         may  cause open connections to get closed unnecessarily.
         (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 CURLCLOSEPOLICY_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  created
         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 (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 exist­
         ing connection (default behavior).  (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 understand what it does.  Set  to  0  to
         have libcurl keep the connection open for possibly later
         re-use (default behavior). (Added in 7.7)

     CURLOPT_CONNECTTIMEOUT
         Pass a long. It should contain the maximum time in  sec­
         onds  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: this is not recommended  to  use  in  unix  multi-
         threaded  programs,  as  it  uses  signals  unless  CUR­
         LOPT_NOSIGNAL (see below) is set.


SSL and SECURITY OPTIONS

     CURLOPT_SSLCERT
         Pass a pointer to a zero terminated string as parameter.
         The  string should be the file name of your certificate.
         The default format is "PEM" and can be changed with CUR­
         LOPT_SSLCERTTYPE.

     CURLOPT_SSLCERTTYPE
         Pass a pointer to a zero terminated string as parameter.
         The string should be the  format  of  your  certificate.
         Supported formats are "PEM" and "DER".  (Added in 7.9.3)

     CURLOPT_SSLCERTPASSWD
         Pass a pointer to a zero terminated string as parameter.
         It will be used as the password required to use the CUR­
         LOPT_SSLCERT certificate. If the password  is  not  sup­
         plied,  you will be prompted for it. CURLOPT_PASSWDFUNC­
         TION can be used to set your own prompt function.

         NOTE:This option is replaced by CURLOPT_SSLKEYPASSWD and
         only cept for backward compatibility. You never needed a
         pass phrase to load a certificate but you  need  one  to
         load your private key.

     CURLOPT_SSLKEY
         Pass a pointer to a zero terminated string as parameter.
         The string should be the file name of your private  key.
         The default format is "PEM" and can be changed with CUR­
         LOPT_SSLKEYTYPE. (Added in 7.9.3)

     CURLOPT_SSLKEYTYPE
         Pass a pointer to a zero terminated string as parameter.
         The  string  should  be  the format of your private key.
         Supported formats are "PEM", "DER" and "ENG".  (Added in
         7.9.3)

         NOTE:The  format  "ENG"  enables you to load the private
         key from a crypto engine. in this case CURLOPT_SSLKEY is
         used  as an identifier passed to the engine. You have to
         set the crypto engine with CURLOPT_SSL_ENGINE.

     CURLOPT_SSLKEYPASSWD
         Pass a pointer to a zero terminated string as parameter.
         It will be used as the password required to use the CUR­
         LOPT_SSLKEY private key. If the  password  is  not  sup­
         plied,  you will be prompted for it. CURLOPT_PASSWDFUNC­
         TION can be  used  to  set  your  own  prompt  function.
         (Added in 7.9.3)

     CURLOPT_SSL_ENGINE
         Pass a pointer to a zero terminated string as parameter.
         It will be used as the identifier for the crypto  engine
         you want to use for your private key. (Added in 7.9.3)

         NOTE:If    the   crypto   device   cannot   be   loaded,
         CURLE_SSL_ENGINE_NOTFOUND is returned.

     CURLOPT_SSL_ENGINEDEFAULT
         Sets the actual crypto engine as the default  for  (asy­
         metric) crypto operations. (Added in 7.9.3)

         NOTE:If    the    crypto    device    cannot   be   set,
         CURLE_SSL_ENGINE_SETFAILED is returned.

     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 may have to use this
         option.

     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 CURLOPT_CAINFO option
         (Added  in  7.4.2)  or  a  certificate directory must be
         specified  with  the  CURLOPT_CAPATH  option  (Added  in
         7.9.8).

     CURLOPT_CAINFO
         Pass  a char * to a zero terminated string naming a file
         holding one or more  certificates  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_CAPATH
         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  c_rehash  utility.  This  only  makes
         sense when used in combination with the CURLOPT_SSL_VER­
         IFYPEER option. The CAPATH function apparently does  not
         work  in  Windows  due  to  some  limitation in openssl.
         (Added in 7.9.8)

     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 the SSL connection will 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_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 pro­
         vided hostname. (Added in 7.8.1)

     CURLOPT_SSL_CIPHER_LIST
         Pass a char *, pointing  to  a  zero  terminated  string
         holding  the  list of ciphers to use for the SSL connec­
         tion. The list must be syntactly correct, it consists 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. 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 more details about cipher lists on this URL:
         http://www.openssl.org/docs/apps/ciphers.html

     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 'private'.  If the
         string is set but doesn't match one of these,  'private'
         will  be  used.  Set  the string to NULL to disable ker­
         beros4. The kerberos support only works for FTP.  (Added
         in 7.3)


RETURN VALUE

     CURLE_OK (zero) means that the option was set properly, non-
     zero means an error occurred as <curl/curl.h>  defines.  See
     the  libcurl-errors.3  man  page  for  the  full  list  with
     descriptions.


SEE ALSO

     curl_easy_init(3), curl_easy_cleanup(3),


BUGS

     If you find any bugs, or just have questions,  subscribe  to
     one of the mailing lists and post. We won't bite.











































Man(1) output converted with man2html