NAME

     curl_easy_setopt - Set curl easy-session options


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.
     Most  operations  in  libcurl  have  default actions, and by
     using the appropriate options to curl_easy_setopt,  you  can
     change  them.   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 spe­
     cific option expects. Read  this  manual  carefully  as  bad
     input  values  may  cause  libcurl to behave badly!  You can
     only set one option in each function call. A typical  appli­
     cation  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.


OPTIONS

     The options are listed in a sort of random order, but you'll
     figure it out!

     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.

     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 available 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_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.

     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_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 (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_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
         libcurl 7.3)

     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.

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

     CURLOPT_UPLOAD
         A non-zero parameter tells the library to prepare for an
         upload. The CURLOPT_INFILE  and  CURLOPT_INFILESIZE  are
         also interesting for uploads.

     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_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  do  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_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_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_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_PUT
         A  non-zero  parameter tells the library to use HTTP PUT
         to transfer data. The  data  should  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 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.

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

         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_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 does not work  in  Unix  multi-threaded  pro­
         grams, as it uses signals.

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

         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_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_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  remained  intact  until you close this curl handle
         again with curl_easy_cleanup(3).

     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_SSLKEYASSWD
         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_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). Dis­
         able 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_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_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 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  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 may  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  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_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_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 '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 libcurl 7.3)

     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.

     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 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_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 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_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 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_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_MAXCONNECTS
         Pass a long. The set number will be the persistant  con­
         nection  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 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_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  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 does not work  in  unix  multi-threaded  pro­
         grams, as it uses signals.

     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  pro­
         vided 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(3) 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  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_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.

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

     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
         libcurl 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
         handles creations and deletions. This is not thread-safe
         and  this  will  use a global varible. (Added in libcurl
         7.9.3)

     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.


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