           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 carefully as bad input values may cause libcurl  to
           behave  badly!   You can only set one option in each func-
           tion   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.
           libcurl  will need them until you call curl_easy_cleanup()
           or you set the  same  option  again  to  use  a  different
           pointer.

           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  trans-
           fers  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
               display a lot of verbose information about its  opera-
               tions.  Very useful for libcurl and/or protocol debug-
               ging and understanding.

               You hardly ever want this set in production  use,  you
               will  almost  always  want  this when you debug/report
               problems. Another neat option  for  debugging  is  the
               CURLOPT_DEBUGFUNCTION.

           CURLOPT_HEADER
               A  non-zero parameter tells the library to include 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  pro-
               cess.  This  option  is  mainly  here  to allow multi-
               threaded unix applications to still set/use all  time-
               out  options  etc,  without  risking  getting signals.
               (Added in 7.10)

## CALLBACK OPTIONS

           CURLOPT_WRITEFUNCTION
               Function pointer that should match the following  pro-
               totype:  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, it will not be zero
               terminated. Return the number of bytes actually  taken
               care of. If that amount differs from the amount passed
               to your function, it'll signal an error to the library
               and   it   will   abort   the   transfer   and  return
               CURLE_WRITE_ERROR.

               Set the stream  argument  with  the  CURLOPT_WRITEDATA
               option.

               NOTE:  you  will be passed as much data as possible in
               all invokes, but you cannot possibly make any  assump-
               tions.  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
               LOPT_FILE,  the  name CURLOPT_WRITEDATA was introduced
               in 7.9.7.

           CURLOPT_READFUNCTION
               Function pointer that should match the following  pro-
               totype:  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 multi-
               plied with nmemb number of bytes. Your  function  must
               return  the  actual number of bytes that you stored in
               that memory area. Returning 0 will signal  end-of-file
               to the library and cause it to stop the current trans-
               fer.

           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  argu-
               ment  values  will  be  set  to zero (like if you only
               download data, the upload size will remain 0). Return-
               ing  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_HEADERFUNCTION
               Function pointer that should match the following  pro-
               totype:  size_t  function(  void  *ptr,  size_t  size,
               data that needs to be written down.  The  headers  are
               guaranteed  to be written one-by-one and only complete
               lines are written.  Parsing  headers  should  be  easy
               enough  using this. 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).

           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  call-
               back to take care of the writing, this must be a valid
               FILE *. See  also  the  CURLOPT_HEADERFUNCTION  option
               above on how to set a custom get-all-headers callback.

           CURLOPT_DEBUGFUNCTION
               Function pointer that should match the following  pro-
               totype:  int  curl_debug_callback  (CURL *, curl_info-
               type, char *, size_t, void  *);  CURLOPT_DEBUGFUNCTION
               replaces  the  standard  debug function used when CUR-
               LOPT_VERBOSE is  in  effect.  This  callback  receives
               debug information, as specified with the curl_infotype
               argument.  This  funtion  must  return  0.   The  data
               pointed  to by the char * passed to this function WILL
               NOT be zero terminated, but will  be  exactly  of  the
               size as told by the size_t argument.

               Available curl_infotype values:

               CURLINFO_TEXT
                    The data is informational text.

               CURLINFO_HEADER_IN
                    The data is header (or header-like) data received
                    from the peer.

               CURLINFO_HEADER_OUT
                    The data is header (or header-like) data sent  to
                    the peer.

               CURLINFO_DATA_IN
                    The data is protocol data received from the peer.

               CURLINFO_DATA_OUT
                    The data is protocol data sent to the peer.

           CURLOPT_DEBUGDATA
               Pass a pointer to whatever you want passed in to  your
               CURLOPT_DEBUGFUNCTION  in  the  last  void * argument.

## ERROR OPTIONS

           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.

               Use CURLOPT_VERBOSE and CURLOPT_DEBUGFUNCTION to  bet-
               ter 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 normally, 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 sepa-
               rate 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
               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_PROXYTYPE
               Pass a long with this option to set type of the proxy.
               Available options  for  this  are  CURLPROXY_HTTP  and
               CURLPROXY_SOCKS5,  with  the  HTTP  one being default.
               (Added in 7.10)

           CURLOPT_HTTPPROXYTUNNEL
               Set the parameter to non-zero to get  the  library  to
               tunnel 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.

           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.

           CURLOPT_DNS_CACHE_TIMEOUT
               Pass a long, this sets the timeout  in  seconds.  Name
               resolves  will  be  kept  in memory for this number of
               seconds.  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.

           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.

           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)

           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
               correct 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  both
               the  colon  and  password  is  left  out,  you will be
               prompted for it while using a colon with  no  password
               will make libcurl use an empty password. CURLOPT_PASS-
               WDFUNCTION can be used to set your  own  prompt  func-
               tion.
               might perform several requests to  possibly  different
               hosts.  libcurl  will only send this user and password
               information to  hosts  using  the  initial  host  name
               (unless   CURLOPT_UNRESTRICTED_AUTH  is  set),  so  if
               libcurl follows locations to other hosts it  will  not
               send  the user and password to those. This is enforced
               to prevent accidental information leakage.

           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_HTTPAUTH
               Pass a long as parameter, which is set to  a  bitmask,
               to tell libcurl what authentication method(s) you want
               it to use. The available bits  are  listed  below.  If
               more than one bit is set, libcurl will first query the
               site to see what authentication  methods  it  supports
               and  then  pick the best one you allow it to use. Note
               that for some methods, this will induce an extra  net-
               work round-trip. Set the actual name and password with
               the CURLOPT_USERPWD option. (Added in 7.10.6)

               CURLAUTH_BASIC
                    HTTP Basic authentication. This  is  the  default
                    choice,  and  the  only  method  that is in wide-
                    spread use and  supported  virtually  everywhere.
                    This  is  sending the user name and password over
                    the network in plain  text,  easily  captured  by
                    others.

               CURLAUTH_DIGEST
                    HTTP  Digest  authentication.  Digest authentica-
                    tion is defined in RFC2617 and is a  more  secure
                    way  to  do  authentication  over public networks
                    than the regular old-fashioned Basic method.

               CURLAUTH_GSSNEGOTIATE
                    HTTP GSS-Negotiate authentication. The  GSS-Nego-
                    tiate  method  was  designed  by Microsoft and is
                    used in their web aplications.  It  is  primarily
                    meant  as  a support for Kerberos5 authentication
                    but may be also used along with another authenti-
                    cation  methods.  For  more  information see IETF
                    draft draft-brezak-spnego-http-04.txt.

               CURLAUTH_NTLM
                    HTTP NTLM authentication. A proprietary  protocol
                    invented  and  used by Microsoft. It uses a chal-

               CURLAUTH_ANY
                    This  is  a  convenience macro that sets all bits
                    and thus makes libcurl pick any  it  finds  suit-
                    able.  libcurl will automaticly select the one it
                    finds most secure.

               CURLAUTH_ANYSAFE
                    This is a convenience macro that  sets  all  bits
                    except  Basic  and thus makes libcurl pick any it
                    finds suitable. libcurl will  automaticly  select
                    the one it finds most secure.

           CURLOPT_PROXYAUTH
               Pass  a  long as parameter, which is set to a bitmask,
               to tell libcurl what authentication method(s) you want
               it to use for your proxy authentication.  If more than
               one bit is set, libcurl will first query the  site  to
               see  what  authentication methods it supports and then
               pick the best one you allow it to use. Note  that  for
               some methods, this will induce an extra network round-
               trip. Set the actual name and password with  the  CUR-
               LOPT_PROXYUSERPWD  option.  The  bitmask  can  be con-
               structed by or'ing together the bits listed above  for
               the  CURLOPT_HTTPAUTH option. As of this writing, only
               Basic and NTLM work. (Added in 7.10.7)

## HTTP OPTIONS

           CURLOPT_ENCODING
               Sets the contents of the Accept-Encoding: header  sent
               in an HTTP request, and enables decoding of a response
               when a Content-Encoding: header  is  received.   Three
               encodings are supported: identity, which does nothing,
               deflate which requests  the  server  to  compress  its
               response  using  the  zlib  algorithm,  and gzip which
               requests the gzip algorithm.  If a zero-length  string
               is set, then an Accept-Encoding: header containing all
               supported encodings is sent.

               This is a request, not an order; the server may or may
               not  do  it.  This option must be set (to any non-NULL
               value) or else any unsolicited encoding  done  by  the
               server    is    ignored.    See   the   special   file
               lib/README.encoding for details.

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

           CURLOPT_UNRESTRICTED_AUTH
               A non-zero parameter tells the library it can continue
               to  send authentication (user+password) when following
               locations, even when hostname changed. Note that  this
               is  meaningful  only  when setting CURLOPT_FOLLOWLOCA-
               TION.

           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_REDIRECTS).  This  option  only  makes
               sense if the CURLOPT_FOLLOWLOCATION  is  used  at  the
               same time.

           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_POSTFIELD-
               SIZE in how  to  set  the  data  size.  Starting  with
               libcurl  7.8,  this option is obsolete. Using the CUR-
               LOPT_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. You need to
               make sure that the data is formatted the way you  want
               the  server to receive it. libcurl will not convert or
               encode it for you. Most web servers will  assume  this
               data to be url-encoded. Take note.

               This  POST  is  a normal application/x-www-form-urlen-
               coded kind (and libcurl will set that Content-Type  by
               default  when  this option is used), which is the most
               commonly used one by HTML forms.  See  also  the  CUR-
               LOPT_POST.   Using   CURLOPT_POSTFIELDS  implies  CUR-
               LOPT_POST.

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

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

           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 prop-
               erly 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 parame-
               ter. It will be used to set the Referer: header in the
               http  request  sent  to the remote server. This can be
               used to fool servers or scripts. You can also set  any
               custom header with CURLOPT_HTTPHEADER.

           CURLOPT_USERAGENT
               Pass  a pointer to a zero terminated string as parame-
               ter. It will be used to set the User-Agent: header  in
               the  http  request sent to the remote server. This can
               be used to fool servers or scripts. You can  also  set
               any custom header with 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  other-
               wise  generated  and  used by libcurl internally, your
               added one will be used instead. If you  add  a  header
               with no contents 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.  The headers included in the linked list must
               not be CRLF-terminated, because curl adds  CRLF  after
               each  header  item.  Failure  to comply with this will
               result in strange bugs because the  server  will  most
               likely ignore part of the headers you specified.

               The  first line in a request (usually containing a GET
               or POST) is not a header and cannot be replaced  using
               this option. Only the lines following the request-line
               cuts" in the options CURLOPT_COOKIE, CURLOPT_USERAGENT
               and CURLOPT_REFERER.

           CURLOPT_HTTP200ALIASES
               Pass a pointer to a  linked  list  of  aliases  to  be
               treated  as  valid  HTTP  200 responses.  Some servers
               respond with a custom header response line.  For exam-
               ple,  IceCast  servers  respond with "ICY 200 OK".  By
               including this string in your  list  of  aliases,  the
               response  will  be treated as a valid HTTP header line
               such as "HTTP/1.0 200 OK". (Added in 7.10.3)

               The linked list should be a fully valid list of struct
               curl_slist  structs,  and  be properly filled in.  Use
               curl_slist_append(3)   to   create   the   list    and
               curl_slist_free_all(3) to clean up an entire list.

               NOTE:The  alias  itself  is not parsed for any version
               strings.  So if your alias  is  "MYHTTP/9.9",  Libcurl
               will not treat the server as responding with HTTP ver-
               sion 9.9.  Instead Libcurl will use the value  set  by
               option CURLOPT_HTTP_VERSION.

           CURLOPT_COOKIE
               Pass  a pointer to a zero terminated string as parame-
               ter. It will be used to  set  a  cookie  in  the  http
               request.  The format of the string should be NAME=CON-
               TENTS, 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
               concat  them  all  in  one single string. Set multiple
               cookies in  one  string  like  this:  "name1=content1;
               name2=content2;" etc.

               Using  this  option  multiple times will only make the
               latest string override the previously ones.

           CURLOPT_COOKIEFILE
               Pass a pointer to a zero terminated string as  parame-
               ter.  It  should contain the name of your file holding
               cookie data  to  read.  The  cookie  data  may  be  in
               Netscape  / Mozilla cookie data format or just regular
               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
               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  ses-
               sion,  so if you for example follow a location it will
               make matching cookies get sent accordingly.

               NOTE If the cookie jar file can't be created or  writ-
               ten  to  (when  the  curl_easy_cleanup()  is  called),
               libcurl will not and cannot report an error for  this.
               Using  CURLOPT_VERBOSE  or  CURLOPT_DEBUGFUNCTION will
               get a warning to display, but that is the only visible
               feedback you get about this possibly lethal situation.

           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 previ-
               ously using the same curl handle.

           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  parame-
               ter.  It will be used to get the IP address to use for
               address. The string may be a plain IP address, a  host
               name, an network interface name (under Unix) or just a
               '-' letter to let the library use your systems default
               IP  address.  Default  FTP operations are passive, and
               thus won't use PORT.

               You disable PORT again and go back to using  the  pas-
               sive version by setting this option to NULL.

           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
               CURLOPT_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 subdirecto-
               ries 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_EPRT
               FTP downloads (which is enabled  by  CURLOPT_FTPPORT).
               Using  EPRT  means  that  it will first attempt to use
               EPRT and then LPRT before using PORT, but if you  pass
               FALSE  (zero)  to  this  option, it will not try using
               EPRT or LPRT, only plain PORT. (Added in 7.10.5)

           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 down-
               loads (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.

           CURLOPT_FTP_CREATE_MISSING_DIRS
               Pass  a  long.  If  the  value  is non-zero, curl will
               attempt to create any remote directory that  it  fails
               to  CWD  into. CWD is the command that changes working
               directory. (Added in 7.10.7)

           CURLOPT_FTP_RESPONSE_TIMEOUT
               Pass a long.  Causes curl to set a timeout period  (in
               seconds)  on  the  amount  of  time that the server is
               allowed to take in order to generate a  response  mes-
               sage  for  a  command before the session is considered
               hung.  Note that while curl is waiting for a response,
               this  value  overrides  CURLOPT_TIMEOUT.  It is recom-
               mended that if used in conjunction with  CURLOPT_TIME-
               OUT,  you  set CURLOPT_FTP_RESPONSE_TIMEOUT to a value
               smaller than CURLOPT_TIMEOUT.  (Added in 7.10.8)

## PROTOCOL OPTIONS

           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
               usable  when  transferring  text  data between systems
               with different 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
               techniques).

           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_CUSTOMREQUEST
               Pass a pointer to a zero terminated string as  parame-
               ter. It will be user instead of GET or HEAD when doing
               a HTTP request, or instead of LIST or NLST when  doing
               an  ftp  directory  listing.  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.

               NOTE: many people have wrongly  used  this  option  to
               replace  the  entire request with their own, including
               multiple headers and POST contents. While  that  might
               work  in  many  cases,  it  will cause libcurl to send
               invalid requests and it  could  possibly  confuse  the
               remote   server   badly.  Use  CURLOPT_POST  and  CUR-
               LOPT_POSTFIELDS to set POST  data.  Use  CURLOPT_HTTP-
               HEADER to replace or extend the set of headers sent by
               libcurl. Use CURLOPT_HTTP_VERSION to change HTTP  ver-
               sion.

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

           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. On
               HTTP(S) servers, this will  make  libcurl  do  a  HEAD
               request.

           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.
               Pass  a  long as parameter. This allows you to specify
               the maximum size (in bytes) of a file to download.  If
               the  file  requested  is  larger  than this value, the
               transfer will not  start  and  CURLE_FILESIZE_EXCEEDED
               will be returned.

               NOTE: The file size is not always known prior to down-
               load, and for such files this  option  has  no  effect
               even  if  the  file transfer ends up being larger than
               this given limit. This  concerns  both  FTP  and  HTTP
               transfers.

## CONNECTION OPTIONS

           CURLOPT_TIMEOUT
               Pass  a  long as parameter containing the maximum time
               in seconds that you allow the libcurl transfer  opera-
               tion  to  take. Normally, name lookups can take a con-
               siderable 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 above) 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
               connection cache size. The set amount will be the max-
               imum  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  concerns 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
               this curl handle, setting a smaller  MAXCONNECTS  than
               before may cause open connections to get closed unnec-
               essarily.

           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 CURL-
               CLOSEPOLICY_*     defines.      Use      CURLCLOSEPOL-
               ICY_LEAST_RECENTLY_USED to make libcurl close the con-
               nection 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  old-
               est  connection,  the one that was created first among
               the ones in the  connection  cache.  The  other  close
               policies are not support yet.

           CURLOPT_FRESH_CONNECT
               Pass a long. Set to non-zero to make the next transfer
               use a new (fresh) connection by force. If the  connec-
               tion  cache is full before this connection, one of the
               existing connections will be closed  as  according  to
               the  selected or default policy. This option should be
               used with caution and only if you understand  what  it
               does.  Set  this to 0 to have libcurl attempt re-using
               an existing connection (default behavior).

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

           CURLOPT_CONNECTTIMEOUT
               Pass  a  long.  It  should contain the maximum time in
               seconds that you allow the connection to the server to
               take.   This only limits the connection phase, once it
               has connected, this option is of no more use.  Set  to
               zero  to disable connection timeout (it will then only
               timeout on the system's internal timeouts).  See  also
               the CURLOPT_TIMEOUT option.

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

           CURLOPT_SSLCERT
               Pass  a pointer to a zero terminated string as parame-
               ter. The string should be the file name of  your  cer-
               tificate.  The  default  format  is  "PEM"  and can be
               changed with CURLOPT_SSLCERTTYPE.

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

           CURLOPT_SSLCERTPASSWD
               Pass  a pointer to a zero terminated string as parame-
               ter. 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.  CUR-
               LOPT_PASSWDFUNCTION 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 parame-
               ter. The string should be the file name of  your  pri-
               vate  key.  The  default  format  is  "PEM" and can be
               changed with CURLOPT_SSLKEYTYPE.

           CURLOPT_SSLKEYTYPE
               Pass a pointer to a zero terminated string as  parame-
               ter.  The  string should be the format of your private
               key. Supported formats are "PEM", "DER" and "ENG".

               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  parame-
               ter.  It  will be used as the password required to use
               the CURLOPT_SSLKEY private key. If the password is not
               supplied, you will be prompted for it. CURLOPT_PASSWD-
               FUNCTION can be used to set your own prompt  function.

           CURLOPT_SSL_ENGINE
               Pass  a pointer to a zero terminated string as parame-
               ter. It will be used as the identifier for the  crypto
               engine you want to use for your private key.
               CURLE_SSL_ENGINE_NOTFOUND is returned.

           CURLOPT_SSL_ENGINEDEFAULT
               Sets the actual crypto engine as the default for (asy-
               metric) crypto operations.

               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 zero value to  stop  curl
               from  verifying  the peer's certificate (7.10 starting
               setting this option to TRUE  by  default).   Alternate
               certificates  to  verify against can be specified with
               the CURLOPT_CAINFO option or a  certificate  directory
               can be specified with the CURLOPT_CAPATH option (Added
               in 7.9.8).  As of 7.10, curl installs a  default  bun-
               dle.   CURLOPT_SSL_VERIFYHOST  may also need to be set
               to 1 or 0 if CURLOPT_SSL_VERIFYPEER  is  disabled  (it
               defaults to 2).

           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 combina-
               tion with the CURLOPT_SSL_VERIFYPEER option.

           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  pre-
               pared  using  the  openssl c_rehash utility. This only
               makes sense when used in  combination  with  the  CUR-
               LOPT_SSL_VERIFYPEER option. The CAPATH function appar-
               ently 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

           CURLOPT_SSL_VERIFYHOST
               Pass a long. Set if we should verify the  Common  name
               from  the peer certificate in the SSL handshake, set 1
               to check existence, 2 to ensure that  it  matches  the
               provided  hostname.  This  is  by  default  set  to 2.
               (default changed in 7.10)

           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 dis-
               able  kerberos4.  The  kerberos support only works for
               FTP.

## OTHER OPTIONS

           CURLOPT_PRIVATE
               Pass a char * as  parameter,  pointing  to  data  that
               should  be  associated  with  the  curl  handle.   The
               pointer  can  be  subsequently  retrieved  using   the
               CURLINFO_PRIVATE  options to curl_easy_getinfo. (Added
               in 7.10.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),