1curl_easy_setopt(3)             libcurl Manual             curl_easy_setopt(3)
2
3
4

NAME

6       curl_easy_setopt - set options for a curl easy handle
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
12

DESCRIPTION

14       curl_easy_setopt()  is used to tell libcurl how to behave. By using the
15       appropriate options  to  curl_easy_setopt,  you  can  change  libcurl's
16       behavior.  All options are set with the option followed by a parameter.
17       That parameter can be a long, a function pointer, an object pointer  or
18       a  curl_off_t, depending on what the specific option expects. Read this
19       manual carefully as bad input values may cause libcurl to behave badly!
20       You  can  only set one option in each function call. A typical applica‐
21       tion uses many curl_easy_setopt() calls in the setup phase.
22
23       Options set with this function  call  are  valid  for  all  forthcoming
24       transfers  performed using this handle.  The options are not in any way
25       reset between transfers, so if you want subsequent transfers with  dif‐
26       ferent  options,  you  must  change them between the transfers. You can
27       optionally  reset  all  options   back   to   internal   default   with
28       curl_easy_reset(3).
29
30       Strings  passed to libcurl as 'char *' arguments, will not be copied by
31       the library. Instead you should keep them available  until  libcurl  no
32       longer  needs  them.  Failing  to do so will cause very odd behavior or
33       even   crashes.   libcurl   will   need    them    until    you    call
34       curl_easy_cleanup(3)  or you set the same option again to use a differ‐
35       ent pointer.
36
37       The  handle  is  the  return   code   from   a   curl_easy_init(3)   or
38       curl_easy_duphandle(3) call.
39

BEHAVIOR OPTIONS

41       CURLOPT_VERBOSE
42              Set  the  parameter  to non-zero to get the library to display a
43              lot of verbose information about its operations. Very useful for
44              libcurl and/or protocol debugging and understanding. The verbose
45              information will be sent to stderr, or the stream set with  CUR‐
46              LOPT_STDERR.
47
48              You hardly ever want this set in production use, you will almost
49              always want this when you debug/report  problems.  Another  neat
50              option for debugging is the CURLOPT_DEBUGFUNCTION.
51
52       CURLOPT_HEADER
53              A  non-zero parameter tells the library to include the header in
54              the body output. This is only relevant for protocols that  actu‐
55              ally have headers preceding the data (like HTTP).
56
57       CURLOPT_NOPROGRESS
58              A  non-zero parameter tells the library to shut off the built-in
59              progress meter completely.
60
61              Future versions of libcurl is likely to not  have  any  built-in
62              progress meter at all.
63
64       CURLOPT_NOSIGNAL
65              Pass  a  long. If it is non-zero, libcurl will not use any func‐
66              tions that install signal handlers or any functions  that  cause
67              signals to be sent to the process. This option is mainly here to
68              allow multi-threaded unix  applications  to  still  set/use  all
69              timeout options etc, without risking getting signals.  (Added in
70              7.10)
71
72              Consider building libcurl with ares support to enable  asynchro‐
73              nous  DNS  lookups.  It  enables nice timeouts for name resolves
74              without signals.
75

CALLBACK OPTIONS

77       CURLOPT_WRITEFUNCTION
78              Function pointer that  should  match  the  following  prototype:
79              size_t  function(  void  *ptr,  size_t  size, size_t nmemb, void
80              *stream); This function gets called by libcurl as soon as  there
81              is  data  received  that needs to be saved. The size of the data
82              pointed to by ptr is size multiplied with nmemb, it will not  be
83              zero  terminated. Return the number of bytes actually taken care
84              of. If that amount differs from the amount passed to your  func‐
85              tion, it'll signal an error to the library and it will abort the
86              transfer and return CURLE_WRITE_ERROR.
87
88              This function may be called with zero bytes data if  the  trans‐
89              fered file is empty.
90
91              Set  this  option  to NULL to get the internal default function.
92              The internal default function will write the data to the FILE  *
93              given with CURLOPT_WRITEDATA.
94
95              Set the stream argument with the CURLOPT_WRITEDATA option.
96
97              The callback function will be passed as much data as possible in
98              all invokes, but you cannot possibly make  any  assumptions.  It
99              may be one byte, it may be thousands. The maximum amount of data
100              that can be passed to the  write  callback  is  defined  in  the
101              curl.h header file: CURL_MAX_WRITE_SIZE.
102
103       CURLOPT_WRITEDATA
104              Data  pointer to pass to the file write function. If you use the
105              CURLOPT_WRITEFUNCTION option, this is the pointer you'll get  as
106              input.  If you don't use a callback, you must pass a 'FILE *' as
107              libcurl will pass this to fwrite() when writing data.
108
109              The internal CURLOPT_WRITEFUNCTION will write the  data  to  the
110              FILE  *  given  with  this  option,  or to stdout if this option
111              hasn't been set.
112
113              If you're using libcurl as a win32 DLL, you MUST  use  the  CUR‐
114              LOPT_WRITEFUNCTION if you set this option or you will experience
115              crashes.
116
117              This option is also known with the older name CURLOPT_FILE,  the
118              name CURLOPT_WRITEDATA was introduced in 7.9.7.
119
120       CURLOPT_READFUNCTION
121              Function  pointer  that  should  match  the following prototype:
122              size_t function( void *ptr,  size_t  size,  size_t  nmemb,  void
123              *stream);  This  function  gets  called by libcurl as soon as it
124              needs to read data in order to send it to  the  peer.  The  data
125              area  pointed  at  by the pointer ptr may be filled with at most
126              size multiplied with nmemb number of bytes. Your  function  must
127              return the actual number of bytes that you stored in that memory
128              area. Returning 0 will signal end-of-file  to  the  library  and
129              cause it to stop the current transfer.
130
131              If  you  stop the current transfer by returning 0 "pre-maturely"
132              (i.e before the server expected it, like when  you've  told  you
133              will  upload  N bytes and you upload less than N bytes), you may
134              experience that the server "hangs" waiting for the rest  of  the
135              data that won't come.
136
137              The  read  callback  may  return CURL_READFUNC_ABORT to stop the
138              current    operation     immediately,     resulting     in     a
139              CURLE_ABORTED_BY_CALLBACK error code from the transfer (Added in
140              7.12.1)
141
142              If you set the callback pointer to NULL, or doesn't  set  it  at
143              all, the default internal read function will be used. It is sim‐
144              ply doing an fread() on the FILE * stream set with CURLOPT_READ‐
145              DATA.
146
147       CURLOPT_READDATA
148              Data  pointer  to pass to the file read function. If you use the
149              CURLOPT_READFUNCTION option, this is the pointer you'll  get  as
150              input.  If you don't specify a read callback but instead rely on
151              the default internal read function, this data must  be  a  valid
152              readable FILE *.
153
154              If  you're  using  libcurl  as  a win32 DLL, you MUST use a CUR‐
155              LOPT_READFUNCTION if you set this option.
156
157              This option is also known with the  older  name  CURLOPT_INFILE,
158              the name CURLOPT_READDATA was introduced in 7.9.7.
159
160       CURLOPT_IOCTLFUNCTION
161              Function  pointer that should match the curl_ioctl_callback pro‐
162              totype found in <curl/curl.h>.  This  function  gets  called  by
163              libcurl when something special I/O-related needs to be done that
164              the library can't do by itself. For now, rewinding the read data
165              stream  is  the only action it can request. The rewinding of the
166              read data stream may be necessary when doing a HTTP PUT or  POST
167              with  a  multi-pass  authentication  method.   (Option  added in
168              7.12.3)
169
170       CURLOPT_IOCTLDATA
171              Pass a pointer that will be untouched by libcurl and  passed  as
172              the  3rd  argument in the ioctl callback set with CURLOPT_IOCTL‐
173              FUNCTION.  (Option added in 7.12.3)
174
175       CURLOPT_SOCKOPTFUNCTION
176              Function pointer that  should  match  the  curl_sockopt_callback
177              prototype  found  in <curl/curl.h>. This function gets called by
178              libcurl after the socket() call but before the  connect()  call.
179              The callback's purpose argument identifies the exact purpose for
180              this particular socket, and currently only  one  value  is  sup‐
181              ported:  CURLSOCKTYPE_IPCXN  for the primary connection (meaning
182              the control connection in the  FTP  case).  Future  versions  of
183              libcurl  may  support more purposes. It passes the newly created
184              socket descriptor so additional setsockopt() calls can  be  done
185              at the user's discretion.  A non-zero return code from the call‐
186              back function will signal an unrecoverable error to the  library
187              and  it  will close the socket and return CURLE_COULDNT_CONNECT.
188              (Option added in 7.15.6.)
189
190       CURLOPT_SOCKOPTDATA
191              Pass a pointer that will be untouched by libcurl and  passed  as
192              the  first  argument  in  the  sockopt  callback  set  with CUR‐
193              LOPT_SOCKOPTFUNCTION.  (Option added in 7.15.6.)
194
195       CURLOPT_PROGRESSFUNCTION
196              Function pointer that should  match  the  curl_progress_callback
197              prototype  found  in <curl/curl.h>. This function gets called by
198              libcurl instead of  its  internal  equivalent  with  a  frequent
199              interval during operation (roughly once per second) no matter if
200              data is being transfered or not.  Unknown/unused argument values
201              passed  to  the  callback  will be set to zero (like if you only
202              download data, the upload size will remain 0). Returning a  non-
203              zero  value  from  this callback will cause libcurl to abort the
204              transfer and return CURLE_ABORTED_BY_CALLBACK.
205
206              If you transfer data with the  multi  interface,  this  function
207              will  not  be  called during periods of idleness unless you call
208              the appropriate libcurl function that performs transfers.  Usage
209              of the CURLOPT_PROGRESSFUNCTION callback is not recommended when
210              using the multi interface.
211
212              CURLOPT_NOPROGRESS must be set to FALSE to  make  this  function
213              actually get called.
214
215       CURLOPT_PROGRESSDATA
216              Pass  a  pointer that will be untouched by libcurl and passed as
217              the first argument  in  the  progress  callback  set  with  CUR‐
218              LOPT_PROGRESSFUNCTION.
219
220       CURLOPT_HEADERFUNCTION
221              Function  pointer  that  should  match  the following prototype:
222              size_t function( void *ptr,  size_t  size,  size_t  nmemb,  void
223              *stream);.  This  function  gets called by libcurl as soon as it
224              has received header data. The header  callback  will  be  called
225              once  for  each header and only complete header lines are passed
226              on to the callback. Parsing headers should be easy enough  using
227              this.  The size of the data pointed to by ptr is size multiplied
228              with nmemb. Do not assume that the header line  is  zero  termi‐
229              nated! The pointer named stream is the one you set with the CUR‐
230              LOPT_WRITEHEADER option. The callback function must  return  the
231              number  of  bytes actually taken care of, or return -1 to signal
232              error to the library (it will cause it  to  abort  the  transfer
233              with a CURLE_WRITE_ERROR return code).
234
235              Since 7.14.1: When a server sends a chunked encoded transfer, it
236              may contain a trailer. That  trailer  is  identical  to  a  HTTP
237              header  and  if  such  a trailer is received it is passed to the
238              application using this callback as well. There are several  ways
239              to  detect  it being a trailer and not an ordinary header: 1) it
240              comes after the response-body.  2)  it  comes  after  the  final
241              header  line  (CR  LF)  3) a Trailer: header among the response-
242              headers mention what header to expect in the trailer.
243
244       CURLOPT_WRITEHEADER
245              (This option is also known as CURLOPT_HEADERDATA) Pass a pointer
246              to  be used to write the header part of the received data to. If
247              you don't use your own callback to take  care  of  the  writing,
248              this must be a valid FILE *. See also the CURLOPT_HEADERFUNCTION
249              option above on how to set a custom get-all-headers callback.
250
251       CURLOPT_DEBUGFUNCTION
252              Function pointer that should match the following prototype:  int
253              curl_debug_callback (CURL *, curl_infotype, char *, size_t, void
254              *); CURLOPT_DEBUGFUNCTION replaces the standard  debug  function
255              used  when CURLOPT_VERBOSE  is in effect. This callback receives
256              debug information, as specified with the curl_infotype argument.
257              This  function must return 0.  The data pointed to by the char *
258              passed to this function WILL NOT be zero terminated, but will be
259              exactly of the size as told by the size_t argument.
260
261              Available curl_infotype values:
262
263              CURLINFO_TEXT
264                     The data is informational text.
265
266              CURLINFO_HEADER_IN
267                     The  data  is  header (or header-like) data received from
268                     the peer.
269
270              CURLINFO_HEADER_OUT
271                     The data is header (or  header-like)  data  sent  to  the
272                     peer.
273
274              CURLINFO_DATA_IN
275                     The data is protocol data received from the peer.
276
277              CURLINFO_DATA_OUT
278                     The data is protocol data sent to the peer.
279
280       CURLOPT_DEBUGDATA
281              Pass  a  pointer  to  whatever  you  want passed in to your CUR‐
282              LOPT_DEBUGFUNCTION in the last void * argument. This pointer  is
283              not used by libcurl, it is only passed to the callback.
284
285       CURLOPT_SSL_CTX_FUNCTION
286              Function  pointer  that  should  match  the following prototype:
287              CURLcode sslctxfun(CURL *curl, void *sslctx, void  *parm);  This
288              function  gets  called by libcurl just before the initialization
289              of an SSL  connection  after  having  processed  all  other  SSL
290              related  options to give a last chance to an application to mod‐
291              ify the behaviour of openssl's ssl  initialization.  The  sslctx
292              parameter  is  actually  a  pointer to an openssl SSL_CTX. If an
293              error is returned no attempt to establish a connection  is  made
294              and  the  perform operation will return the error code from this
295              callback  function.   Set  the  parm  argument  with  the   CUR‐
296              LOPT_SSL_CTX_DATA option. This option was introduced in 7.11.0.
297
298              This  function  will get called on all new connections made to a
299              server, during the SSL negotiation. The SSL_CTX pointer will  be
300              a new one every time.
301
302              To  use  this properly, a non-trivial amount of knowledge of the
303              openssl libraries is necessary. Using this function  allows  for
304              example  to  use  openssl callbacks to add additional validation
305              code for certificates, and even to change the actual URI  of  an
306              HTTPS  request (example used in the lib509 test case).  See also
307              the example section for a replacement of  the  key,  certificate
308              and trust file settings.
309
310       CURLOPT_SSL_CTX_DATA
311              Data  pointer  to  pass  to  the ssl context callback set by the
312              option CURLOPT_SSL_CTX_FUNCTION, this is the pointer you'll  get
313              as third parameter, otherwise NULL. (Added in 7.11.0)
314
315       CURLOPT_CONV_TO_NETWORK_FUNCTION
316
317       CURLOPT_CONV_FROM_NETWORK_FUNCTION
318
319       CURLOPT_CONV_FROM_UTF8_FUNCTION
320              Function  pointers  that  should  match the following prototype:
321              CURLcode function(char *ptr, size_t length);
322
323              These three options apply to non-ASCII platforms only.  They are
324              available only if CURL_DOES_CONVERSIONS was defined when libcurl
325              was built. When this  is  the  case,  curl_version_info(3)  will
326              return the CURL_VERSION_CONV feature bit set.
327
328              The  data  to  be converted is in a buffer pointed to by the ptr
329              parameter.  The amount of data to convert is  indicated  by  the
330              length parameter.  The converted data overlays the input data in
331              the buffer pointed to by the ptr parameter.  CURLE_OK should  be
332              returned  upon  successful  conversion.  A CURLcode return value
333              defined by curl.h, such as CURLE_CONV_FAILED, should be returned
334              if an error was encountered.
335
336              CURLOPT_CONV_TO_NETWORK_FUNCTION    and   CURLOPT_CONV_FROM_NET‐
337              WORK_FUNCTION convert between the host encoding and the  network
338              encoding.   They  are  used  when  commands  or  ASCII  data are
339              sent/received over the network.
340
341              CURLOPT_CONV_FROM_UTF8_FUNCTION is called to convert  from  UTF8
342              into the host encoding.  It is required only for SSL processing.
343
344              If  you  set a callback pointer to NULL, or don't set it at all,
345              the  built-in  libcurl  iconv  functions  will  be   used.    If
346              HAVE_ICONV  was not defined when libcurl was built, and no call‐
347              back  has  been  established,   conversion   will   return   the
348              CURLE_CONV_REQD error code.
349
350              If  HAVE_ICONV  is defined, CURL_ICONV_CODESET_OF_HOST must also
351              be defined.  For example:
352
353               #define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
354
355              The iconv code in libcurl will  default  the  network  and  UTF8
356              codeset names as follows:
357
358               #define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
359
360               #define CURL_ICONV_CODESET_FOR_UTF8   "UTF-8"
361
362              You  will need to override these definitions if they are differ‐
363              ent on your system.
364

ERROR OPTIONS

366       CURLOPT_ERRORBUFFER
367              Pass a char * to a buffer that the libcurl may store human read‐
368              able  error  messages in. This may be more helpful than just the
369              return code from curl_easy_perform. The buffer must be at  least
370              CURL_ERROR_SIZE big.
371
372              Use   CURLOPT_VERBOSE   and   CURLOPT_DEBUGFUNCTION   to  better
373              debug/trace why errors happen.
374
375              If the library does not return an error, the buffer may not have
376              been touched. Do not rely on the contents in those cases.
377
378
379       CURLOPT_STDERR
380              Pass  a  FILE  *  as  parameter. Tell libcurl to use this stream
381              instead of stderr when showing the progress meter and displaying
382              CURLOPT_VERBOSE data.
383
384       CURLOPT_FAILONERROR
385              A  non-zero  parameter tells the library to fail silently if the
386              HTTP code returned is equal to or larger than 400.  The  default
387              action would be to return the page normally, ignoring that code.
388
389              This  method is not fail-safe and there are occasions where non-
390              successful response codes will  slip  through,  especially  when
391              authentication is involved (response codes 401 and 407).
392
393              You  might  get  some amounts of headers transferred before this
394              situation  is  detected,  like  for  when  a  "100-continue"  is
395              received  as  a  response  to  a  POST/PUT  and  a 401 or 407 is
396              received immediately afterwards.
397

NETWORK OPTIONS

399       CURLOPT_URL
400              The actual URL to deal with. The parameter should be a char * to
401              a  zero  terminated string. The string must remain present until
402              curl no longer needs it, as it doesn't copy the string.
403
404              If the given URL lacks the protocol part ("http://" or  "ftp://"
405              etc),  it  will  attempt to guess which protocol to use based on
406              the given host name. If the given protocol of the set URL is not
407              supported,  libcurl will return on error (CURLE_UNSUPPORTED_PRO‐
408              TOCOL) when you  call  curl_easy_perform(3)  or  curl_multi_per‐
409              form(3).  Use  curl_version_info(3)  for  detailed info on which
410              protocols that are supported.
411
412              The string given to CURLOPT_URL must be url-encoded and  follow‐
413              ing the RFC 2396 (http://curl.haxx.se/rfc/rfc2396.txt).
414
415              CURLOPT_URL   is  the  only  option  that  must  be  set  before
416              curl_easy_perform(3) is called.
417
418       CURLOPT_PROXY
419              Set HTTP proxy to use. The parameter should be a  char  *  to  a
420              zero  terminated  string  holding  the  host  name  or dotted IP
421              address. To specify port number in this string,  append  :[port]
422              to  the  end  of the host name. The proxy string may be prefixed
423              with [protocol]:// since any such prefix will  be  ignored.  The
424              proxy's  port  number may optionally be specified with the sepa‐
425              rate option CURLOPT_PROXYPORT.
426
427              When you tell the library to use an  HTTP  proxy,  libcurl  will
428              transparently  convert operations to HTTP even if you specify an
429              FTP URL etc. This may have an impact on what other  features  of
430              the  library  you can use, such as CURLOPT_QUOTE and similar FTP
431              specifics that don't work unless you  tunnel  through  the  HTTP
432              proxy. Such tunneling is activated with CURLOPT_HTTPPROXYTUNNEL.
433
434              libcurl   respects   the   environment   variables   http_proxy,
435              ftp_proxy, all_proxy etc, if any  of  those  is  set.  The  CUR‐
436              LOPT_PROXY  option  does however override any possibly set envi‐
437              ronment variables.
438
439              Setting the proxy string to "" (an empty string) will explicitly
440              disable  the  use  of  a  proxy, even if there is an environment
441              variable set for it.
442
443              Since 7.14.1, the proxy host string given in  environment  vari‐
444              ables  can  be  specified the exact same way as the proxy can be
445              set with CURLOPT_PROXY, include protocol  prefix  (http://)  and
446              embedded user + password.
447
448       CURLOPT_PROXYPORT
449              Pass a long with this option to set the proxy port to connect to
450              unless it is specified in the proxy string CURLOPT_PROXY.
451
452       CURLOPT_PROXYTYPE
453              Pass a long with this option to set type of the proxy. Available
454              options  for this are CURLPROXY_HTTP, CURLPROXY_SOCKS4 (added in
455              7.15.2) CURLPROXY_SOCKS5. The HTTP type is  default.  (Added  in
456              7.10)
457
458       CURLOPT_HTTPPROXYTUNNEL
459              Set  the  parameter to non-zero to get the library to tunnel all
460              operations through a given HTTP proxy. There is a big difference
461              between  using  a  proxy  and to tunnel through it. If you don't
462              know what this means, you probably  don't  want  this  tunneling
463              option.
464
465       CURLOPT_INTERFACE
466              Pass  a  char * as parameter. This set the interface name to use
467              as outgoing network interface. The  name  can  be  an  interface
468              name, an IP address or a host name.
469
470       CURLOPT_LOCALPORT
471              Pass  a long. This sets the local port number of the socket used
472              for connection. This  can  be  used  in  combination  with  CUR‐
473              LOPT_INTERFACE  and you are recommended to use CURLOPT_LOCALPOR‐
474              TRANGE as well when this is set. Note that port numbers are only
475              valid 1 - 65535. (Added in 7.15.2)
476
477       CURLOPT_LOCALPORTRANGE
478              Pass a long. This is the number of attempts libcurl should do to
479              find a working local port number. It starts with the given  CUR‐
480              LOPT_LOCALPORT  and  adds one to the number for each retry. Set‐
481              ting this value to 1 or below will make libcurl do only one  try
482              for  exact  port  number.  Note that port numbers by nature is a
483              scarce resource that will be busy at times so setting this value
484              to  something  too  low might cause unnecessary connection setup
485              failures. (Added in 7.15.2)
486
487       CURLOPT_DNS_CACHE_TIMEOUT
488              Pass a long, this sets the timeout  in  seconds.  Name  resolves
489              will  be  kept in memory for this number of seconds. Set to zero
490              (0) to completely disable caching, or set  to  -1  to  make  the
491              cached  entries  remain forever. By default, libcurl caches this
492              info for 60 seconds.
493
494       CURLOPT_DNS_USE_GLOBAL_CACHE
495              Pass a long. If the value is non-zero, it tells curl  to  use  a
496              global DNS cache that will survive between easy handle creations
497              and deletions. This is not  thread-safe  and  this  will  use  a
498              global variable.
499
500              WARNING:  this  option  is  considered  obsolete. Stop using it.
501              Switch over to using  the  share  interface  instead!  See  CUR‐
502              LOPT_SHARE and curl_share_init(3).
503
504       CURLOPT_BUFFERSIZE
505              Pass  a  long  specifying your preferred size (in bytes) for the
506              receive buffer in libcurl.  The main point of this would be that
507              the  write  callback  gets  called  more  often and with smaller
508              chunks. This is just treated as a request,  not  an  order.  You
509              cannot  be  guaranteed to actually get the given size. (Added in
510              7.10)
511
512              This   size   is   by   default   set   as   big   as   possible
513              (CURL_MAX_WRITE_SIZE), so it only makes sense to use this option
514              if you want it smaller.
515
516       CURLOPT_PORT
517              Pass a long specifying what remote port number  to  connect  to,
518              instead  of the one specified in the URL or the default port for
519              the used protocol.
520
521       CURLOPT_TCP_NODELAY
522              Pass a long specifying whether the TCP_NODELAY option should  be
523              set  or  cleared  (1 = set, 0 = clear). The option is cleared by
524              default. This will have no effect after the connection has  been
525              established.
526
527              Setting this option will disable TCP's Nagle algorithm. The pur‐
528              pose of this algorithm is to try to minimize the number of small
529              packets on the network (where "small packets" means TCP segments
530              less than the Maximum Segment Size (MSS) for the network).
531
532              Maximizing the amount of data  sent  per  TCP  segment  is  good
533              because  it amortizes the overhead of the send. However, in some
534              cases (most notably telnet or rlogin) small segments may need to
535              be  sent  without  delay.  This  is  less efficient than sending
536              larger amounts of data at a time, and can contribute to  conges‐
537              tion on the network if overdone.
538

NAMES and PASSWORDS OPTIONS (Authentication)

540       CURLOPT_NETRC
541              This  parameter controls the preference of libcurl between using
542              user names and passwords from your ~/.netrc  file,  relative  to
543              user names and passwords in the URL supplied with CURLOPT_URL.
544
545              libcurl  uses  a  user  name (and supplied or prompted password)
546              supplied with  CURLOPT_USERPWD  in  preference  to  any  of  the
547              options controlled by this parameter.
548
549              Pass a long, set to one of the values described below.
550
551              CURL_NETRC_OPTIONAL
552                     The  use  of your ~/.netrc file is optional, and informa‐
553                     tion in the URL is to be preferred.   The  file  will  be
554                     scanned with the host and user name (to find the password
555                     only) or with the host only, to find the first user  name
556                     and  password  after that machine, which ever information
557                     is not specified in the URL.
558
559                     Undefined values of the option will have this effect.
560
561              CURL_NETRC_IGNORED
562                     The library will ignore the file and use only the  infor‐
563                     mation in the URL.
564
565                     This is the default.
566
567              CURL_NETRC_REQUIRED
568                     This  value  tells  the  library  that use of the file is
569                     required, to ignore the information in the  URL,  and  to
570                     search the file with the host only.
571       Only  machine name, user name and password are taken into account (init
572       macros and similar things aren't supported).
573
574       libcurl does not verify that the file has the  correct  properties  set
575       (as  the  standard Unix ftp client does). It should only be readable by
576       user.
577
578       CURLOPT_NETRC_FILE
579              Pass a char * as parameter, pointing to a zero terminated string
580              containing  the  full  path name to the file you want libcurl to
581              use as .netrc file. If this option is omitted, and CURLOPT_NETRC
582              is  set,  libcurl  will attempt to find the a .netrc file in the
583              current user's home directory. (Added in 7.10.9)
584
585       CURLOPT_USERPWD
586              Pass a char * as parameter, which should be  [user  name]:[pass‐
587              word]  to use for the connection. Use CURLOPT_HTTPAUTH to decide
588              authentication method.
589
590              When using NTLM, you can set domain by prepending it to the user
591              name  and  separating  the domain and name with a forward (/) or
592              backward  slash  (\).  Like  this:   "domain/user:password"   or
593              "domain\user:password".  Some  HTTP servers (on Windows) support
594              this style even for Basic authentication.
595
596              When using HTTP and CURLOPT_FOLLOWLOCATION, libcurl  might  per‐
597              form  several requests to possibly different hosts. libcurl will
598              only send this user and password information to hosts using  the
599              initial  host name (unless CURLOPT_UNRESTRICTED_AUTH is set), so
600              if libcurl follows locations to other hosts it will not send the
601              user and password to those. This is enforced to prevent acciden‐
602              tal information leakage.
603
604       CURLOPT_PROXYUSERPWD
605              Pass a char * as parameter, which should be  [user  name]:[pass‐
606              word]  to  use  for  the connection to the HTTP proxy.  Use CUR‐
607              LOPT_PROXYAUTH to decide authentication method.
608
609       CURLOPT_HTTPAUTH
610              Pass a long as parameter, which is set to  a  bitmask,  to  tell
611              libcurl  what  authentication  method(s) you want it to use. The
612              available bits are listed below. If more than one  bit  is  set,
613              libcurl  will  first  query  the site to see what authentication
614              methods it supports and then pick the best one you allow  it  to
615              use.  For some methods, this will induce an extra network round-
616              trip. Set the actual name and password with the  CURLOPT_USERPWD
617              option. (Added in 7.10.6)
618
619              CURLAUTH_BASIC
620                     HTTP  Basic  authentication.  This is the default choice,
621                     and the only method that is in wide-spread use  and  sup‐
622                     ported  virtually  everywhere.  This  is sending the user
623                     name and password over the network in plain text,  easily
624                     captured by others.
625
626              CURLAUTH_DIGEST
627                     HTTP  Digest  authentication.   Digest  authentication is
628                     defined in RFC2617 and is a more secure way to do authen‐
629                     tication  over public networks than the regular old-fash‐
630                     ioned Basic method.
631
632              CURLAUTH_GSSNEGOTIATE
633                     HTTP  GSS-Negotiate  authentication.  The   GSS-Negotiate
634                     (also  known as plain "Negotiate") method was designed by
635                     Microsoft and is used in their web  applications.  It  is
636                     primarily meant as a support for Kerberos5 authentication
637                     but may be also used along  with  another  authentication
638                     methods.  For  more  information  see  IETF  draft draft-
639                     brezak-spnego-http-04.txt.
640
641                     You need to build libcurl with a suitable GSS-API library
642                     for this to work.
643
644              CURLAUTH_NTLM
645                     HTTP NTLM authentication. A proprietary protocol invented
646                     and used by Microsoft. It uses a  challenge-response  and
647                     hash  concept  similar to Digest, to prevent the password
648                     from being eavesdropped.
649
650                     You need to build libcurl with OpenSSL support  for  this
651                     option to work, or build libcurl on Windows.
652
653              CURLAUTH_ANY
654                     This  is  a convenience macro that sets all bits and thus
655                     makes libcurl pick any it finds  suitable.  libcurl  will
656                     automatically select the one it finds most secure.
657
658              CURLAUTH_ANYSAFE
659                     This  is  a  convenience  macro that sets all bits except
660                     Basic and thus makes libcurl pick any it finds  suitable.
661                     libcurl  will  automatically select the one it finds most
662                     secure.
663
664       CURLOPT_PROXYAUTH
665              Pass a long as parameter, which is set to  a  bitmask,  to  tell
666              libcurl  what  authentication  method(s)  you want it to use for
667              your proxy authentication.  If more than one bit is set, libcurl
668              will  first query the site to see what authentication methods it
669              supports and then pick the best one you allow  it  to  use.  For
670              some  methods, this will induce an extra network round-trip. Set
671              the actual  name  and  password  with  the  CURLOPT_PROXYUSERPWD
672              option.  The  bitmask  can be constructed by or'ing together the
673              bits listed above for the CURLOPT_HTTPAUTH option.  As  of  this
674              writing, only Basic, Digest and NTLM work. (Added in 7.10.7)
675

HTTP OPTIONS

677       CURLOPT_AUTOREFERER
678              Pass  a non-zero parameter to enable this. When enabled, libcurl
679              will automatically set the Referer: field in requests  where  it
680              follows a Location: redirect.
681
682       CURLOPT_ENCODING
683              Sets the contents of the Accept-Encoding: header sent in an HTTP
684              request, and enables decoding of  a  response  when  a  Content-
685              Encoding:  header  is  received.  Three encodings are supported:
686              identity, which does nothing, deflate which requests the  server
687              to  compress  its  response  using  the zlib algorithm, and gzip
688              which requests the gzip algorithm.  If a zero-length  string  is
689              set,  then  an  Accept-Encoding: header containing all supported
690              encodings is sent.
691
692              This is a request, not an order; the server may or  may  not  do
693              it.  This option must be set (to any non-NULL value) or else any
694              unsolicited encoding done by the server is ignored. See the spe‐
695              cial file lib/README.encoding for details.
696
697       CURLOPT_FOLLOWLOCATION
698              A  non-zero  parameter tells the library to follow any Location:
699              header that the server sends as part of an HTTP header.
700
701              This means that the library will re-send the same request on the
702              new  location and follow new Location: headers all the way until
703              no more such headers are returned. CURLOPT_MAXREDIRS can be used
704              to limit the number of redirects libcurl will follow.
705
706       CURLOPT_UNRESTRICTED_AUTH
707              A  non-zero  parameter tells the library it can continue to send
708              authentication (user+password) when  following  locations,  even
709              when  hostname changed. This option is meaningful only when set‐
710              ting CURLOPT_FOLLOWLOCATION.
711
712       CURLOPT_MAXREDIRS
713              Pass a long. The set number will be the  redirection  limit.  If
714              that  many  redirections  have  been followed, the next redirect
715              will cause an error (CURLE_TOO_MANY_REDIRECTS). This option only
716              makes  sense  if  the CURLOPT_FOLLOWLOCATION is used at the same
717              time. Added in 7.15.1: Setting the limit to 0 will make  libcurl
718              refuse  any  redirect.  Set  it  to -1 for an infinite number of
719              redirects (which is the default)
720
721       CURLOPT_PUT
722              A non-zero parameter tells the library to use HTTP PUT to trans‐
723              fer  data. The data should be set with CURLOPT_READDATA and CUR‐
724              LOPT_INFILESIZE.
725
726              This option is deprecated and starting with version  7.12.1  you
727              should instead use CURLOPT_UPLOAD.
728
729       CURLOPT_POST
730              A  non-zero  parameter  tells  the  library to do a regular HTTP
731              post. This will also make the library use the  a  "Content-Type:
732              application/x-www-form-urlencoded"  header.  (This is by far the
733              most commonly used POST method).
734
735              Use the CURLOPT_POSTFIELDS option to specify what data  to  post
736              and CURLOPT_POSTFIELDSIZE to set the data size.
737
738              Optionally, you can provide data to POST using the CURLOPT_READ‐
739              FUNCTION and CURLOPT_READDATA options but  then  you  must  make
740              sure  to  not  set CURLOPT_POSTFIELDS to anything but NULL. When
741              providing data with a callback, you must transmit it using chun‐
742              ked  transfer-encoding or you must set the size of the data with
743              the CURLOPT_POSTFIELDSIZE option.
744
745              You can override the default POST Content-Type: header  by  set‐
746              ting your own with CURLOPT_HTTPHEADER.
747
748              Using  POST with HTTP 1.1 implies the use of a "Expect: 100-con‐
749              tinue" header.  You can disable this header  with  CURLOPT_HTTP‐
750              HEADER as usual.
751
752              If  you use POST to a HTTP 1.1 server, you can send data without
753              knowing the size before starting the POST  if  you  use  chunked
754              encoding.  You  enable  this  by adding a header like "Transfer-
755              Encoding: chunked" with CURLOPT_HTTPHEADER.  With  HTTP  1.0  or
756              without  chunked  transfer,  you  must  specify  the size in the
757              request.
758
759              When setting CURLOPT_POST to a non-zero value, it will automati‐
760              cally set CURLOPT_NOBODY to 0 (since 7.14.1).
761
762              If  you issue a POST request and then want to make a HEAD or GET
763              using the same re-used handle, you must explicitly set  the  new
764              request type using CURLOPT_NOBODY or CURLOPT_HTTPGET or similar.
765
766       CURLOPT_POSTFIELDS
767              Pass  a  char  *  as parameter, which should be the full data to
768              post in an HTTP POST operation. You must make sure that the data
769              is  formatted the way you want the server to receive it. libcurl
770              will not convert or encode it for you.  Most  web  servers  will
771              assume this data to be url-encoded. Take note.
772
773              This  POST  is  a  normal application/x-www-form-urlencoded kind
774              (and libcurl will set that Content-Type  by  default  when  this
775              option  is  used),  which  is the most commonly used one by HTML
776              forms.  See  also  the  CURLOPT_POST.  Using  CURLOPT_POSTFIELDS
777              implies CURLOPT_POST.
778
779              Using  POST with HTTP 1.1 implies the use of a "Expect: 100-con‐
780              tinue" header.  You can disable this header  with  CURLOPT_HTTP‐
781              HEADER as usual.
782
783              To  make multipart/formdata posts (aka rfc1867-posts), check out
784              the CURLOPT_HTTPPOST option.
785
786       CURLOPT_POSTFIELDSIZE
787              If you want to post data to the server without  letting  libcurl
788              do  a  strlen()  to  measure  the data size, this option must be
789              used. When this option is used you can post fully  binary  data,
790              which  otherwise  is  likely to fail. If this size is set to -1,
791              the library will use strlen() to get the size.
792
793       CURLOPT_POSTFIELDSIZE_LARGE
794              Pass a curl_off_t as parameter. Use this to set the size of  the
795              CURLOPT_POSTFIELDS  data  to prevent libcurl from doing strlen()
796              on the data to figure out the size. This is the large file  ver‐
797              sion of the CURLOPT_POSTFIELDSIZE option. (Added in 7.11.1)
798
799       CURLOPT_HTTPPOST
800              Tells libcurl you want a multipart/formdata HTTP POST to be made
801              and you instruct what data to pass on to  the  server.   Pass  a
802              pointer  to a linked list of curl_httppost structs as parameter.
803              . The easiest way to create such a list,  is  to  use  curl_for‐
804              madd(3)  as documented. The data in this list must remain intact
805              until    you    close    this    curl    handle    again    with
806              curl_easy_cleanup(3).
807
808              Using  POST with HTTP 1.1 implies the use of a "Expect: 100-con‐
809              tinue" header.  You can disable this header  with  CURLOPT_HTTP‐
810              HEADER as usual.
811
812              When  setting  CURLOPT_HTTPPOST,  it will automatically set CUR‐
813              LOPT_NOBODY to 0 (since 7.14.1).
814
815       CURLOPT_REFERER
816              Pass a pointer to a zero terminated string as parameter. It will
817              be  used  to set the Referer: header in the http request sent to
818              the remote server. This can be used to fool servers or  scripts.
819              You can also set any custom header with CURLOPT_HTTPHEADER.
820
821       CURLOPT_USERAGENT
822              Pass a pointer to a zero terminated string as parameter. It will
823              be used to set the User-Agent: header in the http  request  sent
824              to  the  remote  server.  This  can  be  used to fool servers or
825              scripts. You can also set any custom header  with  CURLOPT_HTTP‐
826              HEADER.
827
828       CURLOPT_HTTPHEADER
829              Pass  a  pointer to a linked list of HTTP headers to pass to the
830              server in your HTTP request. The linked list should be  a  fully
831              valid  list of struct curl_slist structs properly filled in. Use
832              curl_slist_append(3)     to     create     the     list      and
833              curl_slist_free_all(3)  to clean up an entire list. If you add a
834              header that is otherwise generated and used  by  libcurl  inter‐
835              nally,  your added one will be used instead. If you add a header
836              with no contents as in 'Accept:' (no data on the right  side  of
837              the  colon), the internally used header will get disabled. Thus,
838              using this option you can  add  new  headers,  replace  internal
839              headers  and  remove  internal  headers. To add a header with no
840              contents, make the contents  be  two  quotes:  "".  The  headers
841              included in the linked list must not be CRLF-terminated, because
842              curl adds CRLF after each header item. Failure  to  comply  with
843              this  will  result  in strange bugs because the server will most
844              likely ignore part of the headers you specified.
845
846              The first line in a request (containing the  method,  usually  a
847              GET  or  POST) is not a header and cannot be replaced using this
848              option. Only the lines following the request-line  are  headers.
849              Adding  this method line in this list of headers will only cause
850              your request to send an invalid header.
851
852              Pass a NULL to this to reset back to no custom headers.
853
854              The most commonly  replaced  headers  have  "shortcuts"  in  the
855              options CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER.
856
857       CURLOPT_HTTP200ALIASES
858              Pass  a  pointer  to  a  linked list of aliases to be treated as
859              valid HTTP 200 responses.  Some servers respond  with  a  custom
860              header response line.  For example, IceCast servers respond with
861              "ICY 200 OK".  By including this string in your list of aliases,
862              the response will be treated as a valid HTTP header line such as
863              "HTTP/1.0 200 OK". (Added in 7.10.3)
864
865              The  linked  list  should  be  a  fully  valid  list  of  struct
866              curl_slist   structs,   and   be   properly   filled   in.   Use
867              curl_slist_append(3)     to     create     the     list      and
868              curl_slist_free_all(3) to clean up an entire list.
869
870              The  alias  itself is not parsed for any version strings. Before
871              libcurl 7.16.3, Libcurl  used  the  value  set  by  option  CUR‐
872              LOPT_HTTP_VERSION,  but  starting  with  7.16.3  the protocol is
873              assumed to match HTTP 1.0 when an alias matched.
874
875       CURLOPT_COOKIE
876              Pass a pointer to a zero terminated string as parameter. It will
877              be  used  to set a cookie in the http request. The format of the
878              string should be NAME=CONTENTS, where NAME is  the  cookie  name
879              and CONTENTS is what the cookie should contain.
880
881              If  you  need  to set multiple cookies, you need to set them all
882              using a single option and thus you need to concatenate them  all
883              in  one  single  string. Set multiple cookies in one string like
884              this: "name1=content1; name2=content2;" etc.
885
886              Using this option multiple  times  will  only  make  the  latest
887              string override the previously ones.
888
889       CURLOPT_COOKIEFILE
890              Pass  a  pointer  to  a  zero terminated string as parameter. It
891              should contain the name of your  file  holding  cookie  data  to
892              read.  The  cookie data may be in Netscape / Mozilla cookie data
893              format or just regular HTTP-style headers dumped to a file.
894
895              Given an empty or non-existing file  or  by  passing  the  empty
896              string  (""), this option will enable cookies for this curl han‐
897              dle, making it understand and parse received  cookies  and  then
898              use matching cookies in future request.
899
900              If  you  use this option multiple times, you just add more files
901              to read.  Subsequent files will add more cookies.
902
903       CURLOPT_COOKIEJAR
904              Pass a file name as char *,  zero  terminated.  This  will  make
905              libcurl write all internally known cookies to the specified file
906              when curl_easy_cleanup(3) is called. If no cookies are known, no
907              file  will  be  created. Specify "-" to instead have the cookies
908              written to stdout. Using this option also  enables  cookies  for
909              this  session,  so  if you for example follow a location it will
910              make matching cookies get sent accordingly.
911
912              If the cookie jar file can't be created or written to (when  the
913              curl_easy_cleanup(3)  is  called),  libcurl  will not and cannot
914              report  an  error  for  this.  Using  CURLOPT_VERBOSE  or   CUR‐
915              LOPT_DEBUGFUNCTION  will  get  a warning to display, but that is
916              the only visible feedback you get  about  this  possibly  lethal
917              situation.
918
919       CURLOPT_COOKIESESSION
920              Pass  a  long set to non-zero to mark this as a new cookie "ses‐
921              sion". It will force libcurl to ignore all cookies it  is  about
922              to load that are "session cookies" from the previous session. By
923              default, libcurl always stores and loads all  cookies,  indepen‐
924              dent  if  they  are session cookies are not. Session cookies are
925              cookies without expiry date and they are meant to be  alive  and
926              existing for this "session" only.
927
928       CURLOPT_COOKIELIST
929              Pass  a  char * to a cookie string. Cookie can be either in Net‐
930              scape / Mozilla format or just regular HTTP-style  header  (Set-
931              Cookie:  ...)  format.  If cURL cookie engine was not enabled it
932              will enable its cookie engine.  Passing  a  magic  string  "ALL"
933              will  erase all cookies known by cURL. (Added in 7.14.1) Passing
934              the special string "SESS" will only erase  all  session  cookies
935              known by cURL. (Added in 7.15.4)
936
937       CURLOPT_HTTPGET
938              Pass  a  long.  If  the  long  is non-zero, this forces the HTTP
939              request to get back to GET. usable if a POST,  HEAD,  PUT  or  a
940              custom  request  have  been  used previously using the same curl
941              handle.
942
943              When setting CURLOPT_HTTPGET to a non-zero value, it will  auto‐
944              matically set CURLOPT_NOBODY to 0 (since 7.14.1).
945
946       CURLOPT_HTTP_VERSION
947              Pass  a  long,  set  to  one of the values described below. They
948              force libcurl to use the specific HTTP  versions.  This  is  not
949              sensible to do unless you have a good reason.
950
951              CURL_HTTP_VERSION_NONE
952                     We  don't  care  about  what  version  the  library uses.
953                     libcurl will use whatever it thinks fit.
954
955              CURL_HTTP_VERSION_1_0
956                     Enforce HTTP 1.0 requests.
957
958              CURL_HTTP_VERSION_1_1
959                     Enforce HTTP 1.1 requests.
960
961       CURLOPT_IGNORE_CONTENT_LENGTH
962              Ignore the Content-Length header. This is useful for Apache  1.x
963              (and similar servers) which will report incorrect content length
964              for files over 2 gigabytes. If this option is  used,  curl  will
965              not  be able to accurately report progress, and will simply stop
966              the download when the server  ends  the  connection.  (added  in
967              7.14.1)
968
969       CURLOPT_HTTP_CONTENT_DECODING
970              Pass  a  long to tell libcurl how to act on content decoding. If
971              set to zero, content decoding will be disabled. If set to  1  it
972              is  enabled.  Note  however  that libcurl has no default content
973              decoding but requires you  to  use  CURLOPT_ENCODING  for  that.
974              (added in 7.16.2)
975
976       CURLOPT_HTTP_TRANSFER_DECODING
977              Pass  a long to tell libcurl how to act on transfer decoding. If
978              set to zero, transfer decoding will be disabled, if set to 1  it
979              is  enabled (default). libcurl does chunked transfer decoding by
980              default unless this option is set to zero. (added in 7.16.2)
981

FTP OPTIONS

983       CURLOPT_FTPPORT
984              Pass a pointer to a zero terminated string as parameter. It will
985              be  used  to get the IP address to use for the ftp PORT instruc‐
986              tion. The PORT instruction tells the remote server to connect to
987              our  specified IP address. The string may be a plain IP address,
988              a host name, an network interface name (under Unix)  or  just  a
989              '-'  letter  to  let  the  library  use  your systems default IP
990              address. Default FTP operations are passive, and thus won't  use
991              PORT.
992
993              You  disable PORT again and go back to using the passive version
994              by setting this option to NULL.
995
996       CURLOPT_QUOTE
997              Pass a pointer to a linked list of FTP or SFTP commands to  pass
998              to  the  server  prior  to  your  ftp request. This will be done
999              before any other commands are issued (even before the  CWD  com‐
1000              mand  for  FTP). The linked list should be a fully valid list of
1001              'struct  curl_slist'  structs  properly  filled  in  with   text
1002              strings.  Use  curl_slist_append(3) to append strings (commands)
1003              to  the  list,  and  clear  the  entire  list  afterwards   with
1004              curl_slist_free_all(3).  Disable this operation again by setting
1005              a NULL to this option.
1006
1007       CURLOPT_POSTQUOTE
1008              Pass a pointer to a linked list of FTP or SFTP commands to  pass
1009              to  the  server after your ftp transfer request. The linked list
1010              should be a fully valid list of struct curl_slist structs  prop‐
1011              erly  filled  in  as  described  for CURLOPT_QUOTE. Disable this
1012              operation again by setting a NULL to this option.
1013
1014       CURLOPT_PREQUOTE
1015              Pass a pointer to a linked list of FTP commands to pass  to  the
1016              server after the transfer type is set. The linked list should be
1017              a fully valid list of struct curl_slist structs properly  filled
1018              in  as described for CURLOPT_QUOTE. Disable this operation again
1019              by setting a NULL to this option. Before version 7.15.6, if  you
1020              also set CURLOPT_NOBODY non-zero, this option didn't work.
1021
1022       CURLOPT_FTPLISTONLY
1023              A non-zero parameter tells the library to just list the names of
1024              an ftp directory, instead of doing a full directory listing that
1025              would include file sizes, dates etc.
1026
1027              This  causes  an  FTP NLST command to be sent.  Beware that some
1028              FTP servers list only files in  their  response  to  NLST;  they
1029              might not include subdirectories and symbolic links.
1030
1031       CURLOPT_FTPAPPEND
1032              A  non-zero  parameter tells the library to append to the remote
1033              file instead of overwrite it. This is only useful when uploading
1034              to an ftp site.
1035
1036       CURLOPT_FTP_USE_EPRT
1037              Pass  a long. If the value is non-zero, it tells curl to use the
1038              EPRT (and LPRT) command when doing active FTP  downloads  (which
1039              is  enabled  by  CURLOPT_FTPPORT). Using EPRT means that it will
1040              first attempt to use EPRT and then LPRT before using  PORT,  but
1041              if  you  pass FALSE (zero) to this option, it will not try using
1042              EPRT or LPRT, only plain PORT. (Added in 7.10.5)
1043
1044              If the server is an IPv6 host, this option will have  no  effect
1045              as of 7.12.3.
1046
1047       CURLOPT_FTP_USE_EPSV
1048              Pass  a long. If the value is non-zero, it tells curl to use the
1049              EPSV command when doing passive FTP downloads (which  it  always
1050              does by default). Using EPSV means that it will first attempt to
1051              use EPSV before using PASV, but if you pass FALSE (zero) to this
1052              option, it will not try using EPSV, only plain PASV.
1053
1054              If  the  server is an IPv6 host, this option will have no effect
1055              as of 7.12.3.
1056
1057       CURLOPT_FTP_CREATE_MISSING_DIRS
1058              Pass a long. If the value is non-zero, curl will attempt to cre‐
1059              ate  any  remote directory that it fails to CWD into. CWD is the
1060              command that changes working directory. (Added in 7.10.7)
1061
1062              This setting also applies to SFTP-connections. curl will attempt
1063              to  create  the  remote directory if it can't obtain a handle to
1064              the target-location. The creation will fail if  a  file  of  the
1065              same  name  as the directory to create already exists or lack of
1066              permissions prevents creation. (Added in 7.16.3)
1067
1068       CURLOPT_FTP_RESPONSE_TIMEOUT
1069              Pass a long.  Causes curl to set a timeout period  (in  seconds)
1070              on  the  amount  of  time  that the server is allowed to take in
1071              order to generate a response message for a  command  before  the
1072              session  is  considered  hung.   While  curl  is  waiting  for a
1073              response, this value overrides  CURLOPT_TIMEOUT.  It  is  recom‐
1074              mended that if used in conjunction with CURLOPT_TIMEOUT, you set
1075              CURLOPT_FTP_RESPONSE_TIMEOUT  to  a  value  smaller  than   CUR‐
1076              LOPT_TIMEOUT.  (Added in 7.10.8)
1077
1078       CURLOPT_FTP_ALTERNATIVE_TO_USER
1079              Pass  a  char * as parameter, pointing to a string which will be
1080              used to authenticate if the usual  FTP  "USER  user"  and  "PASS
1081              password"  negotiation fails. This is currently only known to be
1082              required when connecting to Tumbleweed's Secure  Transport  FTPS
1083              server  using  client certificates for authentication. (Added in
1084              7.15.5)
1085
1086       CURLOPT_FTP_SKIP_PASV_IP
1087              Pass a long. If set to a non-zero value, it instructs libcurl to
1088              not  use  the IP address the server suggests in its 227-response
1089              to libcurl's PASV command when libcurl connects the data connec‐
1090              tion. Instead libcurl will re-use the same IP address it already
1091              uses for the control connection. But it will use the port number
1092              from the 227-response. (Added in 7.14.2)
1093
1094              This  option has no effect if PORT, EPRT or EPSV is used instead
1095              of PASV.
1096
1097       CURLOPT_FTP_SSL
1098              Pass a long using one of the values from below, to make  libcurl
1099              use  your  desired  level of SSL for the ftp transfer. (Added in
1100              7.11.0)
1101
1102              CURLFTPSSL_NONE
1103                     Don't attempt to use SSL.
1104
1105              CURLFTPSSL_TRY
1106                     Try using SSL, proceed as normal otherwise.
1107
1108              CURLFTPSSL_CONTROL
1109                     Require SSL for  the  control  connection  or  fail  with
1110                     CURLE_FTP_SSL_FAILED.
1111
1112              CURLFTPSSL_ALL
1113                     Require   SSL   for   all   communication  or  fail  with
1114                     CURLE_FTP_SSL_FAILED.
1115
1116       CURLOPT_FTPSSLAUTH
1117              Pass a long using one of the values from  below,  to  alter  how
1118              libcurl  issues  "AUTH  TLS"  or "AUTH SSL" when FTP over SSL is
1119              activated (see CURLOPT_FTP_SSL). (Added in 7.12.2)
1120
1121              CURLFTPAUTH_DEFAULT
1122                     Allow libcurl to decide
1123
1124              CURLFTPAUTH_SSL
1125                     Try "AUTH SSL" first, and only if that  fails  try  "AUTH
1126                     TLS"
1127
1128              CURLFTPAUTH_TLS
1129                     Try  "AUTH  TLS"  first, and only if that fails try "AUTH
1130                     SSL"
1131
1132       CURLOPT_FTP_SSL_CCC
1133              If enabled, this option makes libcurl  use  CCC  (Clear  Command
1134              Channel).  It shuts down the SSL/TLS layer after authenticating.
1135              The rest of the control  channel  communication  will  be  unen‐
1136              crypted.  This allows NAT routers to follow the FTP transaction.
1137              Pass a long using one of the values below.  (Added in 7.16.1)
1138
1139              CURLFTPSSL_CCC_NONE
1140                     Don't attempt to use CCC.
1141
1142              CURLFTPSSL_CCC_PASSIVE
1143                     Do not initiate the shutdown, but wait for the server  to
1144                     do it. Do not send a reply.
1145
1146              CURLFTPSSL_CCC_ACTIVE
1147                     Initiate the shutdown and wait for a reply.
1148
1149       CURLOPT_FTP_ACCOUNT
1150              Pass a pointer to a zero-terminated string (or NULL to disable).
1151              When an FTP server asks for "account data" after user  name  and
1152              password has been provided, this data is sent off using the ACCT
1153              command. (Added in 7.13.0)
1154
1155       CURLOPT_FTP_FILEMETHOD
1156              Pass a long that should have one of the following  values.  This
1157              option  controls  what method libcurl should use to reach a file
1158              on a FTP(S) server. The argument should be one of the  following
1159              alternatives:
1160
1161              CURLFTPMETHOD_MULTICWD
1162                     libcurl does a single CWD operation for each path part in
1163                     the given URL. For deep hierarchies this means very  many
1164                     commands.  This  is  how  RFC1738 says it should be done.
1165                     This is the default but the slowest behavior.
1166
1167              CURLFTPMETHOD_NOCWD
1168                     libcurl does no CWD at all. libcurl will do  SIZE,  RETR,
1169                     STOR etc and give a full path to the server for all these
1170                     commands. This is the fastest behavior.
1171
1172              CURLFTPMETHOD_SINGLECWD
1173                     libcurl does one CWD with the full target  directory  and
1174                     then  operates on the file "normally" (like in the multi‐
1175                     cwd case). This is somewhat more standards compliant than
1176                     'nocwd' but without the full penalty of 'multicwd'.
1177

PROTOCOL OPTIONS

1179       CURLOPT_TRANSFERTEXT
1180              A non-zero parameter tells the library to use ASCII mode for ftp
1181              transfers, instead of the default  binary  transfer.  For  win32
1182              systems  it  does not set the stdout to binary mode. This option
1183              can be usable when transferring text data between  systems  with
1184              different views on certain characters, such as newlines or simi‐
1185              lar.
1186
1187              libcurl does not do a complete ASCII conversion when doing ASCII
1188              transfers  over FTP. This is a known limitation/flaw that nobody
1189              has rectified. libcurl simply sets the mode to  ascii  and  per‐
1190              forms a standard transfer.
1191
1192       CURLOPT_CRLF
1193              Convert Unix newlines to CRLF newlines on transfers.
1194
1195       CURLOPT_RANGE
1196              Pass  a  char * as parameter, which should contain the specified
1197              range you want. It should be in the format "X-Y", where X  or  Y
1198              may  be left out. HTTP transfers also support several intervals,
1199              separated with commas as in "X-Y,N-M". Using this kind of multi‐
1200              ple  intervals  will  cause the HTTP server to send the response
1201              document in pieces (using standard MIME separation  techniques).
1202              Pass a NULL to this option to disable the use of ranges.
1203
1204       CURLOPT_RESUME_FROM
1205              Pass  a  long  as parameter. It contains the offset in number of
1206              bytes that you want the transfer to start from. Set this  option
1207              to  0 to make the transfer start from the beginning (effectively
1208              disabling resume). For FTP, set this option to -1  to  make  the
1209              transfer  start  from the end of the target file (useful to con‐
1210              tinue an interrupted upload).
1211
1212       CURLOPT_RESUME_FROM_LARGE
1213              Pass a curl_off_t as parameter. It contains the offset in number
1214              of  bytes  that  you  want the transfer to start from. (Added in
1215              7.11.0)
1216
1217       CURLOPT_CUSTOMREQUEST
1218              Pass a pointer to a zero terminated string as parameter. It will
1219              be  user  instead  of GET or HEAD when doing an HTTP request, or
1220              instead of LIST or NLST when doing  an  ftp  directory  listing.
1221              This  is  useful  for doing DELETE or other more or less obscure
1222              HTTP requests. Don't do this at will, make sure your server sup‐
1223              ports the command first.
1224
1225              Restore to the internal default by setting this to NULL.
1226
1227              Many  people have wrongly used this option to replace the entire
1228              request with their own, including multiple headers and POST con‐
1229              tents.  While  that  might  work  in  many  cases, it will cause
1230              libcurl to send invalid requests and it could  possibly  confuse
1231              the remote server badly. Use CURLOPT_POST and CURLOPT_POSTFIELDS
1232              to set POST data. Use CURLOPT_HTTPHEADER to  replace  or  extend
1233              the  set of headers sent by libcurl. Use CURLOPT_HTTP_VERSION to
1234              change HTTP version.
1235
1236       CURLOPT_FILETIME
1237              Pass a long. If it is a non-zero value, libcurl will attempt  to
1238              get  the modification date of the remote document in this opera‐
1239              tion. This requires that the remote server  sends  the  time  or
1240              replies  to  a  time  querying command. The curl_easy_getinfo(3)
1241              function with the CURLINFO_FILETIME argument can be used after a
1242              transfer to extract the received time (if any).
1243
1244       CURLOPT_NOBODY
1245              A  non-zero parameter tells the library to not include the body-
1246              part in the output. This is only  relevant  for  protocols  that
1247              have  separate  header  and body parts. On HTTP(S) servers, this
1248              will make libcurl do a HEAD request.
1249
1250              To change request to GET, you should use CURLOPT_HTTPGET. Change
1251              request to POST with CURLOPT_POST etc.
1252
1253       CURLOPT_INFILESIZE
1254              When  uploading  a  file to a remote site, this option should be
1255              used to tell libcurl what the expected size of  the  infile  is.
1256              This  value should be passed as a long. See also CURLOPT_INFILE‐
1257              SIZE_LARGE.
1258
1259              For uploading using SCP, this option or CURLOPT_INFILESIZE_LARGE
1260              is mandatory.
1261
1262              Note  that this option does not limit how much data libcurl will
1263              actually send, as that is controlled entirely by what  the  read
1264              callback returns.
1265
1266       CURLOPT_INFILESIZE_LARGE
1267              When  uploading  a  file to a remote site, this option should be
1268              used to tell libcurl what the expected size of  the  infile  is.
1269              This value should be passed as a curl_off_t. (Added in 7.11.0)
1270
1271              For  uploading  using  SCP, this option or CURLOPT_INFILESIZE is
1272              mandatory.
1273
1274              Note that this option does not limit how much data libcurl  will
1275              actually  send,  as that is controlled entirely by what the read
1276              callback returns.
1277
1278       CURLOPT_UPLOAD
1279              A non-zero parameter tells the library to prepare for an upload.
1280              The  CURLOPT_READDATA  and CURLOPT_INFILESIZE or CURLOPT_INFILE‐
1281              SIZE_LARGE options are also interesting for uploads. If the pro‐
1282              tocol  is HTTP, uploading means using the PUT request unless you
1283              tell libcurl otherwise.
1284
1285              Using PUT with HTTP 1.1 implies the use of a  "Expect:  100-con‐
1286              tinue"  header.   You can disable this header with CURLOPT_HTTP‐
1287              HEADER as usual.
1288
1289              If you use PUT to a HTTP 1.1 server, you can upload data without
1290              knowing the size before starting the transfer if you use chunked
1291              encoding. You enable this by adding  a  header  like  "Transfer-
1292              Encoding:  chunked"  with  CURLOPT_HTTPHEADER.  With HTTP 1.0 or
1293              without chunked transfer, you must specify the size.
1294
1295       CURLOPT_MAXFILESIZE
1296              Pass a long as parameter. This allows you to specify the maximum
1297              size  (in bytes) of a file to download. If the file requested is
1298              larger  than  this  value,  the  transfer  will  not  start  and
1299              CURLE_FILESIZE_EXCEEDED will be returned.
1300
1301              The  file  size  is  not always known prior to download, and for
1302              such files this option has no effect even if the  file  transfer
1303              ends  up  being larger than this given limit. This concerns both
1304              FTP and HTTP transfers.
1305
1306       CURLOPT_MAXFILESIZE_LARGE
1307              Pass a curl_off_t as parameter. This allows you to  specify  the
1308              maximum  size  (in  bytes)  of  a  file to download. If the file
1309              requested is larger than this value, the transfer will not start
1310              and CURLE_FILESIZE_EXCEEDED will be returned. (Added in 7.11.0)
1311
1312              The  file  size  is  not always known prior to download, and for
1313              such files this option has no effect even if the  file  transfer
1314              ends  up  being larger than this given limit. This concerns both
1315              FTP and HTTP transfers.
1316
1317       CURLOPT_TIMECONDITION
1318              Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE
1319              time  value is treated. You can set this parameter to CURL_TIME‐
1320              COND_IFMODSINCE  or  CURL_TIMECOND_IFUNMODSINCE.  This   feature
1321              applies to HTTP and FTP.
1322
1323              The  last modification time of a file is not always known and in
1324              such instances this feature will have  no  effect  even  if  the
1325              given time condition would have not been met.
1326
1327       CURLOPT_TIMEVALUE
1328              Pass  a  long  as  parameter. This should be the time in seconds
1329              since 1 jan 1970, and the time will be used in  a  condition  as
1330              specified with CURLOPT_TIMECONDITION.
1331

CONNECTION OPTIONS

1333       CURLOPT_TIMEOUT
1334              Pass  a long as parameter containing the maximum time in seconds
1335              that you allow the libcurl transfer operation to take. Normally,
1336              name  lookups  can  take a considerable time and limiting opera‐
1337              tions to less than a few minutes risk aborting perfectly  normal
1338              operations.  This  option  will cause curl to use the SIGALRM to
1339              enable time-outing system calls.
1340
1341              In unix-like systems, this might cause signals to be used unless
1342              CURLOPT_NOSIGNAL is set.
1343
1344       CURLOPT_TIMEOUT_MS
1345              Like  CURLOPT_TIMEOUT  but takes number of milliseconds instead.
1346              If libcurl is built to use the standard  system  name  resolver,
1347              that  part  will  still use full-second resolution for timeouts.
1348              (Added in 7.16.2)
1349
1350       CURLOPT_LOW_SPEED_LIMIT
1351              Pass a long as parameter. It  contains  the  transfer  speed  in
1352              bytes  per  second that the transfer should be below during CUR‐
1353              LOPT_LOW_SPEED_TIME seconds for the library to consider  it  too
1354              slow and abort.
1355
1356       CURLOPT_LOW_SPEED_TIME
1357              Pass  a  long as parameter. It contains the time in seconds that
1358              the transfer should be below the CURLOPT_LOW_SPEED_LIMIT for the
1359              library to consider it too slow and abort.
1360
1361       CURLOPT_MAX_SEND_SPEED_LARGE
1362              Pass a curl_off_t as parameter.  If an upload exceeds this speed
1363              on cumulative average during the  transfer,  the  transfer  will
1364              pause to keep the average rate less than or equal to the parame‐
1365              ter value.  Defaults to unlimited speed. (Added in 7.15.5)
1366
1367       CURLOPT_MAX_RECV_SPEED_LARGE
1368              Pass a curl_off_t as parameter.   If  a  download  exceeds  this
1369              speed  on  cumulative  average during the transfer, the transfer
1370              will pause to keep the average rate less than or  equal  to  the
1371              parameter value. Defaults to unlimited speed. (Added in 7.15.5)
1372
1373       CURLOPT_MAXCONNECTS
1374              Pass  a  long.  The set number will be the persistent connection
1375              cache size. The set amount will be the maximum amount of  simul‐
1376              taneously  open  connections that libcurl may cache in this easy
1377              handle. Default is 5, and there isn't  much  point  in  changing
1378              this  value  unless you are perfectly aware of how this work and
1379              changes libcurl's behaviour. This concerns connection using  any
1380              of the protocols that support persistent connections.
1381
1382              When  reaching  the maximum limit, curl closes the oldest one in
1383              the cache to prevent the number of open connections to increase.
1384
1385              If you already have performed transfers with this  curl  handle,
1386              setting a smaller MAXCONNECTS than before may cause open connec‐
1387              tions to get closed unnecessarily.
1388
1389              Note that if you add this easy handle to a  multi  handle,  this
1390              setting  is  not  being  acknowledged,  but you must instead use
1391              curl_multi_setopt(3) and the CURLMOPT_MAXCONNECTS option.
1392
1393       CURLOPT_CLOSEPOLICY
1394              (Obsolete) This option does nothing.
1395
1396       CURLOPT_FRESH_CONNECT
1397              Pass a long. Set to non-zero to make the next transfer use a new
1398              (fresh)  connection  by  force.  If the connection cache is full
1399              before this connection, one of the existing connections will  be
1400              closed  as  according  to  the  selected or default policy. This
1401              option should be used with caution and only  if  you  understand
1402              what  it does. Set this to 0 to have libcurl attempt re-using an
1403              existing connection (default behavior).
1404
1405       CURLOPT_FORBID_REUSE
1406              Pass a long. Set to non-zero to make the next  transfer  explic‐
1407              itly  close the connection when done. Normally, libcurl keep all
1408              connections alive when done with  one  transfer  in  case  there
1409              comes a succeeding one that can re-use them.  This option should
1410              be used with caution and only if you understand  what  it  does.
1411              Set  to  0 to have libcurl keep the connection open for possibly
1412              later re-use (default behavior).
1413
1414       CURLOPT_CONNECTTIMEOUT
1415              Pass a long. It should contain the maximum time in seconds  that
1416              you  allow the connection to the server to take.  This only lim‐
1417              its the connection phase, once it has connected, this option  is
1418              of  no  more  use. Set to zero to disable connection timeout (it
1419              will then only timeout on the system's internal  timeouts).  See
1420              also the CURLOPT_TIMEOUT option.
1421
1422              In unix-like systems, this might cause signals to be used unless
1423              CURLOPT_NOSIGNAL is set.
1424
1425       CURLOPT_CONNECTTIMEOUT_MS
1426              Like CURLOPT_CONNECTTIMEOUT but  takes  number  of  milliseconds
1427              instead.  If  libcurl  is  built to use the standard system name
1428              resolver, that part will still use  full-second  resolution  for
1429              timeouts. (Added in 7.16.2)
1430
1431       CURLOPT_IPRESOLVE
1432              Allows an application to select what kind of IP addresses to use
1433              when resolving host names. This is only interesting  when  using
1434              host names that resolve addresses using more than one version of
1435              IP. The allowed values are:
1436
1437              CURL_IPRESOLVE_WHATEVER
1438                     Default, resolves addresses to all IP versions that  your
1439                     system allows.
1440
1441              CURL_IPRESOLVE_V4
1442                     Resolve to ipv4 addresses.
1443
1444              CURL_IPRESOLVE_V6
1445                     Resolve to ipv6 addresses.
1446
1447       CURLOPT_CONNECT_ONLY
1448              Pass  a  long. A non-zero parameter tells the library to perform
1449              any required proxy authentication and connection setup,  but  no
1450              data transfer.
1451
1452              This  option  is  useful  with the CURLINFO_LASTSOCKET option to
1453              curl_easy_getinfo(3). The library can set up the connection  and
1454              then  the  application  can obtain the most recently used socket
1455              for special data transfers. (Added in 7.15.2)
1456

SSL and SECURITY OPTIONS

1458       CURLOPT_SSLCERT
1459              Pass a pointer to a zero terminated  string  as  parameter.  The
1460              string  should be the file name of your certificate. The default
1461              format is "PEM" and can be changed with CURLOPT_SSLCERTTYPE.
1462
1463              With NSS this is the nickname of the  certificate  you  wish  to
1464              authenticate with.
1465
1466       CURLOPT_SSLCERTTYPE
1467              Pass  a  pointer  to  a zero terminated string as parameter. The
1468              string should be the format of your certificate. Supported  for‐
1469              mats are "PEM" and "DER".  (Added in 7.9.3)
1470
1471       CURLOPT_SSLCERTPASSWD
1472              Pass a pointer to a zero terminated string as parameter. It will
1473              be used as the password required to use the CURLOPT_SSLCERT cer‐
1474              tificate.
1475
1476              This  option is replaced by CURLOPT_SSLKEYPASSWD and should only
1477              be used for backward compatibility.  You  never  needed  a  pass
1478              phrase  to load a certificate but you need one to load your pri‐
1479              vate key.
1480
1481       CURLOPT_SSLKEY
1482              Pass a pointer to a zero terminated  string  as  parameter.  The
1483              string  should be the file name of your private key. The default
1484              format is "PEM" and can be changed with CURLOPT_SSLKEYTYPE.
1485
1486       CURLOPT_SSLKEYTYPE
1487              Pass a pointer to a zero terminated  string  as  parameter.  The
1488              string  should be the format of your private key. Supported for‐
1489              mats are "PEM", "DER" and "ENG".
1490
1491              The format "ENG" enables you to load  the  private  key  from  a
1492              crypto engine. In this case CURLOPT_SSLKEY is used as an identi‐
1493              fier passed to the engine. You have to  set  the  crypto  engine
1494              with  CURLOPT_SSLENGINE.   "DER"  format key file currently does
1495              not work because of a bug in OpenSSL.
1496
1497       CURLOPT_SSLKEYPASSWD
1498              Pass a pointer to a zero terminated string as parameter. It will
1499              be  used  as  the password required to use the CURLOPT_SSLKEY or
1500              CURLOPT_SSH_PRIVATE_KEYFILE private key.
1501
1502       CURLOPT_SSLENGINE
1503              Pass a pointer to a zero terminated string as parameter. It will
1504              be  used as the identifier for the crypto engine you want to use
1505              for your private key.
1506
1507              If the crypto device cannot be loaded, CURLE_SSL_ENGINE_NOTFOUND
1508              is returned.
1509
1510       CURLOPT_SSLENGINE_DEFAULT
1511              Sets  the  actual  crypto engine as the default for (asymmetric)
1512              crypto operations.
1513
1514              If the crypto device cannot be  set,  CURLE_SSL_ENGINE_SETFAILED
1515              is returned.
1516
1517       CURLOPT_SSLVERSION
1518              Pass  a  long as parameter to control what version of SSL/TLS to
1519              attempt to use.  The available options are:
1520
1521              CURL_SSLVERSION_DEFAULT
1522                     The default action. When libcurl built  with  OpenSSL  or
1523                     NSS,  this will attempt to figure out the remote SSL pro‐
1524                     tocol version. Unfortunately there are a lot  of  ancient
1525                     and  broken servers in use which cannot handle this tech‐
1526                     nique and will fail to connect.  When  libcurl  is  built
1527                     with GnuTLS, this will mean SSLv3.
1528
1529              CURL_SSLVERSION_TLSv1
1530                     Force TLSv1
1531
1532              CURL_SSLVERSION_SSLv2
1533                     Force SSLv2
1534
1535              CURL_SSLVERSION_SSLv3
1536                     Force SSLv3
1537
1538       CURLOPT_SSL_VERIFYPEER
1539              Pass a long as parameter.
1540
1541              This option determines whether curl verifies the authenticity of
1542              the peer's certificate.  A nonzero value  means  curl  verifies;
1543              zero means it doesn't.  The default is nonzero, but before 7.10,
1544              it was zero.
1545
1546              When negotiating an SSL connection, the server sends a  certifi‐
1547              cate  indicating  its  identity.  Curl verifies whether the cer‐
1548              tificate is authentic, i.e. that you can trust that  the  server
1549              is  who  the  certificate  says it is.  This trust is based on a
1550              chain of digital signatures, rooted in  certification  authority
1551              (CA)  certificates  you  supply.   As  of  7.10, curl installs a
1552              default bundle of CA certificates and you can specify  alternate
1553              certificates  with the CURLOPT_CAINFO option or the CURLOPT_CAP‐
1554              ATH option.
1555
1556              When CURLOPT_SSL_VERIFYPEER is  nonzero,  and  the  verification
1557              fails to prove that the certificate is authentic, the connection
1558              fails.  When the option is zero, the connection succeeds regard‐
1559              less.
1560
1561              Authenticating  the  certificate  is  not by itself very useful.
1562              You typically want to ensure that the server,  as  authentically
1563              identified  by  its  certificate,  is  the server you mean to be
1564              talking to.  Use CURLOPT_SSL_VERIFYHOST to control that.
1565
1566       CURLOPT_CAINFO
1567              Pass a char * to a zero terminated string naming a file  holding
1568              one  or  more  certificates to verify the peer with.  This makes
1569              sense only when used in combination with  the  CURLOPT_SSL_VERI‐
1570              FYPEER   option.    If   CURLOPT_SSL_VERIFYPEER  is  zero,  CUR‐
1571              LOPT_CAINFO need not even indicate an accessible file.
1572
1573              Note that option is by default set  to  the  system  path  where
1574              libcurl's  cacert bundle is assumed to be stored, as established
1575              at build time.
1576
1577              When built against NSS this is the directory that the  NSS  cer‐
1578              tificate database resides in.
1579
1580       CURLOPT_CAPATH
1581              Pass  a  char  *  to a zero terminated string naming a directory
1582              holding multiple CA certificates to verify the  peer  with.  The
1583              certificate   directory  must  be  prepared  using  the  openssl
1584              c_rehash utility. This makes sense only when used in combination
1585              with  the  CURLOPT_SSL_VERIFYPEER  option.  If CURLOPT_SSL_VERI‐
1586              FYPEER is zero, CURLOPT_CAPATH need not even indicate an  acces‐
1587              sible  path.   The  CURLOPT_CAPATH  function apparently does not
1588              work in Windows due to some limitation in openssl.  This  option
1589              is  OpenSSL-specific and does nothing if libcurl is built to use
1590              GnuTLS.
1591
1592       CURLOPT_RANDOM_FILE
1593              Pass a char * to a zero terminated file name. The file  will  be
1594              used  to  read  from to seed the random engine for SSL. The more
1595              random the specified file is, the more secure the SSL connection
1596              will become.
1597
1598       CURLOPT_EGDSOCKET
1599              Pass  a  char  * to the zero terminated path name to the Entropy
1600              Gathering Daemon socket. It will be  used  to  seed  the  random
1601              engine for SSL.
1602
1603       CURLOPT_SSL_VERIFYHOST
1604              Pass a long as parameter.
1605
1606              This  option determines whether libcurl verifies that the server
1607              cert is for the server it is known as.
1608
1609              When negotiating an SSL connection, the server sends a  certifi‐
1610              cate indicating its identity.
1611
1612              When CURLOPT_SSL_VERIFYHOST is 2, that certificate must indicate
1613              that the server is the server to which you meant to connect,  or
1614              the connection fails.
1615
1616              Curl  considers the server the intended one when the Common Name
1617              field or a Subject  Alternate  Name  field  in  the  certificate
1618              matches  the host name in the URL to which you told Curl to con‐
1619              nect.
1620
1621              When the value is 1, the certificate must contain a Common  Name
1622              field,  but  it  doesn't matter what name it says.  (This is not
1623              ordinarily a useful setting).
1624
1625              When the value is 0, the connection succeeds regardless  of  the
1626              names in the certificate.
1627
1628              The default, since 7.10, is 2.
1629
1630              The  checking  this  option controls is of the identity that the
1631              server claims.  The server could be lying.   To  control  lying,
1632              see CURLOPT_SSL_VERIFYPEER.
1633
1634       CURLOPT_SSL_CIPHER_LIST
1635              Pass  a char *, pointing to a zero terminated string holding the
1636              list of ciphers to use for the SSL connection. The list must  be
1637              syntactically correct, it consists of one or more cipher strings
1638              separated by colons. Commas or spaces are also acceptable  sepa‐
1639              rators  but  colons  are normally used, , - and + can be used as
1640              operators.
1641
1642              For OpenSSL and GnuTLS valid examples of  cipher  lists  include
1643              'RC4-SHA',  ´SHA1+DES´,  'TLSv1' and 'DEFAULT'. The default list
1644              is normally set when you compile OpenSSL.
1645
1646              You'll find  more  details  about  cipher  lists  on  this  URL:
1647              http://www.openssl.org/docs/apps/ciphers.html
1648
1649              For    NSS    valid    examples    of   cipher   lists   include
1650              'rsa_rc4_128_md5', ´rsa_aes_128_sha´, etc. With  NSS  you  don't
1651              add/remove  ciphers.  If  one  uses  this  option then all known
1652              ciphers are disabled and only those passed in are enabled.
1653
1654              You'll find more details about the NSS cipher lists on this URL:
1655              http://directory.fedora.redhat.com/docs/mod_nss.html#Directives
1656
1657
1658       CURLOPT_SSL_SESSIONID_CACHE
1659              Pass  a long set to 0 to disable libcurl's use of SSL session-ID
1660              caching. Set this to 1 to enable it. By  default  all  transfers
1661              are  done  using  the cache. Note that while nothing ever should
1662              get hurt by attempting to reuse SSL session-IDs, there  seem  to
1663              be  broken  SSL implementations in the wild that may require you
1664              to disable this in order for you to succeed. (Added in 7.16.0)
1665
1666       CURLOPT_KRBLEVEL
1667              Pass a char * as parameter. Set the kerberos security level  for
1668              FTP;  this  also  enables kerberos awareness.  This is a string,
1669              'clear', 'safe', of these,  'private'  will  be  used.  Set  the
1670              string to NULL to disable kerberos support for FTP.
1671
1672              (This option was known as CURLOPT_KRB4LEVEL up to 7.16.3)
1673

SSH OPTIONS

1675       CURLOPT_SSH_AUTH_TYPES
1676              Pass  a  long  set  to  a  bitmask  consisting of one or more of
1677              CURLSSH_AUTH_PUBLICKEY,                   CURLSSH_AUTH_PASSWORD,
1678              CURLSSH_AUTH_HOST,  CURLSSH_AUTH_KEYBOARD.  Set CURLSSH_AUTH_ANY
1679              to let libcurl pick one.
1680
1681       CURLOPT_SSH_PUBLIC_KEYFILE
1682              Pass a char * pointing to a file name for your  public  key.  If
1683              not used, libcurl defaults to using ~/.ssh/id_dsa.pub.
1684
1685       CURLOPT_SSH_PRIVATE_KEYFILE
1686              Pass  a  char * pointing to a file name for your private key. If
1687              not used, libcurl defaults to using ~/.ssh/id_dsa.  If the  file
1688              is  password-protected,  set  the  password with CURLOPT_SSLKEY‐
1689              PASSWD.
1690

OTHER OPTIONS

1692       CURLOPT_PRIVATE
1693              Pass a char * as parameter, pointing  to  data  that  should  be
1694              associated  with this curl handle.  The pointer can subsequently
1695              be retrieved using curl_easy_getinfo(3) with  the  CURLINFO_PRI‐
1696              VATE  option. libcurl itself does nothing with this data. (Added
1697              in 7.10.3)
1698
1699       CURLOPT_SHARE
1700              Pass a share handle as a parameter. The share handle  must  have
1701              been  created  by a previous call to curl_share_init(3). Setting
1702              this option, will make this curl handle use the  data  from  the
1703              shared  handle  instead  of  keeping  the  data  to itself. This
1704              enables several curl handles to share data. If the curl  handles
1705              are used simultaneously, you MUST use the locking methods in the
1706              share handle. See curl_share_setopt(3) for details.
1707
1708       CURLOPT_NEW_FILE_PERMS
1709              Pass a long as a parameter, containing the value of the  permis‐
1710              sions that will be assigned to newly created files on the remote
1711              server.  The default value is 0644, but any valid value  can  be
1712              used.   The only protocols that can use this are sftp://, scp://
1713              and file://. (Added in 7.16.4)
1714
1715       CURLOPT_NEW_DIRECTORY_PERMS
1716              Pass a long as a parameter, containing the value of the  permis‐
1717              sions  that will be assigned to newly created directories on the
1718              remote server.  The default value is 0755, but any  valid  value
1719              can  be used.  The only protocols that can use this are sftp://,
1720              scp:// and file://.  (Added in 7.16.4)
1721

TELNET OPTIONS

1723       CURLOPT_TELNETOPTIONS
1724              Provide a pointer to a curl_slist with variables to pass to  the
1725              telnet  negotiations.  The  variables  should  be  in the format
1726              <option=value>. libcurl supports the options 'TTYPE', 'XDISPLOC'
1727              and 'NEW_ENV'. See the TELNET standard for details.
1728

RETURN VALUE

1730       CURLE_OK  (zero) means that the option was set properly, non-zero means
1731       an error occurred as <curl/curl.h> defines. See  the  libcurl-errors(3)
1732       man page for the full list with descriptions.
1733
1734       If  you  try  to set an option that libcurl doesn't know about, perhaps
1735       because the library is too old to support it or the option was  removed
1736       in a recent version, this function will return CURLE_FAILED_INIT.
1737

SEE ALSO

1739       curl_easy_init(3), curl_easy_cleanup(3), curl_easy_reset(3),
1740
1741
1742
1743libcurl 7.16.2                    22 Feb 2007              curl_easy_setopt(3)
Impressum