1curl_easy_setopt(3) libcurl Manual curl_easy_setopt(3)
2
6 curl_easy_setopt - set options for a curl easy handle
7
9 #include <curl/curl.h>
10 CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
12
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 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 Strings passed to libcurl as 'char *' arguments, are copied by the
31 library; thus the string storage associated to the pointer argument may
32 be overwritten after curl_easy_setopt() returns. Exceptions to this
33 rule are described in the option details below.
34 NOTE: before 7.17.0 strings were not copied. Instead the user was
36 forced keep them available until libcurl no longer needed them.
37 The handle is the return code from a curl_easy_init(3) or
39 curl_easy_duphandle(3) call.
40
42 CURLOPT_VERBOSE
43 Set the parameter to 1 to get the library to display a lot of
44 verbose information about its operations. Very useful for
45 libcurl and/or protocol debugging and understanding. The verbose
46 information will be sent to stderr, or the stream set with CUR‐
47 LOPT_STDERR.
48 You hardly ever want this set in production use, you will almost
50 always want this when you debug/report problems. Another neat
51 option for debugging is the CURLOPT_DEBUGFUNCTION.
52 CURLOPT_HEADER
54 A parameter set to 1 tells the library to include the header in
55 the body output. This is only relevant for protocols that actu‐
56 ally have headers preceding the data (like HTTP).
57 CURLOPT_NOPROGRESS
59 A parameter set to 1 tells the library to shut off the built-in
60 progress meter completely.
61 Future versions of libcurl are likely to not have any built-in
63 progress meter at all.
64 CURLOPT_NOSIGNAL
66 Pass a long. If it is 1, libcurl will not use any functions that
67 install signal handlers or any functions that cause signals to
68 be sent to the process. This option is mainly here to allow
69 multi-threaded unix applications to still set/use all timeout
70 options etc, without risking getting signals. (Added in 7.10)
71 If this option is set and libcurl has been built with the stan‐
73 dard name resolver, timeouts will not occur while the name
74 resolve takes place. Consider building libcurl with c-ares sup‐
75 port to enable asynchronous DNS lookups, which enables nice
76 timeouts for name resolves without signals.
77
79 CURLOPT_WRITEFUNCTION
80 Function pointer that should match the following prototype:
81 size_t function( void *ptr, size_t size, size_t nmemb, void
82 *stream); This function gets called by libcurl as soon as there
83 is data received that needs to be saved. The size of the data
84 pointed to by ptr is size multiplied with nmemb, it will not be
85 zero terminated. Return the number of bytes actually taken care
86 of. If that amount differs from the amount passed to your func‐
87 tion, it'll signal an error to the library and it will abort the
88 transfer and return CURLE_WRITE_ERROR.
89 From 7.18.0, the function can return CURL_WRITEFUNC_PAUSE which
91 then will cause writing to this connection to become paused. See
92 curl_easy_pause(3) for further details.
93 This function may be called with zero bytes data if the trans‐
95 ferred file is empty.
96 Set this option to NULL to get the internal default function.
98 The internal default function will write the data to the FILE *
99 given with CURLOPT_WRITEDATA.
100 Set the stream argument with the CURLOPT_WRITEDATA option.
102 The callback function will be passed as much data as possible in
104 all invokes, but you cannot possibly make any assumptions. It
105 may be one byte, it may be thousands. The maximum amount of data
106 that can be passed to the write callback is defined in the
107 curl.h header file: CURL_MAX_WRITE_SIZE.
108 CURLOPT_WRITEDATA
110 Data pointer to pass to the file write function. If you use the
111 CURLOPT_WRITEFUNCTION option, this is the pointer you'll get as
112 input. If you don't use a callback, you must pass a 'FILE *' as
113 libcurl will pass this to fwrite() when writing data.
114 The internal CURLOPT_WRITEFUNCTION will write the data to the
116 FILE * given with this option, or to stdout if this option
117 hasn't been set.
118 If you're using libcurl as a win32 DLL, you MUST use the CUR‐
120 LOPT_WRITEFUNCTION if you set this option or you will experience
121 crashes.
122 This option is also known with the older name CURLOPT_FILE, the
124 name CURLOPT_WRITEDATA was introduced in 7.9.7.
125 CURLOPT_READFUNCTION
127 Function pointer that should match the following prototype:
128 size_t function( void *ptr, size_t size, size_t nmemb, void
129 *stream); This function gets called by libcurl as soon as it
130 needs to read data in order to send it to the peer. The data
131 area pointed at by the pointer ptr may be filled with at most
132 size multiplied with nmemb number of bytes. Your function must
133 return the actual number of bytes that you stored in that memory
134 area. Returning 0 will signal end-of-file to the library and
135 cause it to stop the current transfer.
136 If you stop the current transfer by returning 0 "pre-maturely"
138 (i.e before the server expected it, like when you've said you
139 will upload N bytes and you upload less than N bytes), you may
140 experience that the server "hangs" waiting for the rest of the
141 data that won't come.
142 The read callback may return CURL_READFUNC_ABORT to stop the
144 current operation immediately, resulting in a
145 CURLE_ABORTED_BY_CALLBACK error code from the transfer (Added in
146 7.12.1)
147 From 7.18.0, the function can return CURL_READFUNC_PAUSE which
149 then will cause reading from this connection to become paused.
150 See curl_easy_pause(3) for further details.
151 If you set the callback pointer to NULL, or don't set it at all,
153 the default internal read function will be used. It is simply
154 doing an fread() on the FILE * stream set with CURLOPT_READDATA.
155 CURLOPT_READDATA
157 Data pointer to pass to the file read function. If you use the
158 CURLOPT_READFUNCTION option, this is the pointer you'll get as
159 input. If you don't specify a read callback but instead rely on
160 the default internal read function, this data must be a valid
161 readable FILE *.
162 If you're using libcurl as a win32 DLL, you MUST use a CUR‐
164 LOPT_READFUNCTION if you set this option.
165 This option was also known by the older name CURLOPT_INFILE, the
167 name CURLOPT_READDATA was introduced in 7.9.7.
168 CURLOPT_IOCTLFUNCTION
170 Function pointer that should match the curl_ioctl_callback pro‐
171 totype found in <curl/curl.h>. This function gets called by
172 libcurl when something special I/O-related needs to be done that
173 the library can't do by itself. For now, rewinding the read data
174 stream is the only action it can request. The rewinding of the
175 read data stream may be necessary when doing a HTTP PUT or POST
176 with a multi-pass authentication method. (Option added in
177 7.12.3).
178 Use CURLOPT_SEEKFUNCTION instead to provide seeking!
180 CURLOPT_IOCTLDATA
182 Pass a pointer that will be untouched by libcurl and passed as
183 the 3rd argument in the ioctl callback set with CURLOPT_IOCTL‐
184 FUNCTION. (Option added in 7.12.3)
185 CURLOPT_SEEKFUNCTION
187 Function pointer that should match the following prototype: int
188 function(void *instream, curl_off_t offset, int origin); This
189 function gets called by libcurl to seek to a certain position in
190 the input stream and can be used to fast forward a file in a
191 resumed upload (instead of reading all uploaded bytes with the
192 normal read function/callback). It is also called to rewind a
193 stream when doing a HTTP PUT or POST with a multi-pass authenti‐
194 cation method. The function shall work like "fseek" or "lseek"
195 and accepted SEEK_SET, SEEK_CUR and SEEK_END as argument for
196 origin, although (in 7.18.0) libcurl only passes SEEK_SET. The
197 callback must return 0 (CURL_SEEKFUNC_OK) on success, 1
198 (CURL_SEEKFUNC_FAIL) to cause the upload operation to fail or 2
199 (CURL_SEEKFUNC_CANTSEEK) to indicate that while the seek failed,
200 libcurl is free to work around the problem if possible. The lat‐
201 ter can sometimes be done by instead reading from the input or
202 similar.
203 If you forward the input arguments directly to "fseek" or
205 "lseek", note that the data type for offset is not the same as
206 defined for curl_off_t on many systems! (Option added in 7.18.0)
207 CURLOPT_SEEKDATA
209 Data pointer to pass to the file read function. If you use the
210 CURLOPT_SEEKFUNCTION option, this is the pointer you'll get as
211 input. If you don't specify a seek callback, NULL is passed.
212 (Option added in 7.18.0)
213 CURLOPT_SOCKOPTFUNCTION
215 Function pointer that should match the curl_sockopt_callback
216 prototype found in <curl/curl.h>. This function gets called by
217 libcurl after the socket() call but before the connect() call.
218 The callback's purpose argument identifies the exact purpose for
219 this particular socket, and currently only one value is sup‐
220 ported: CURLSOCKTYPE_IPCXN for the primary connection (meaning
221 the control connection in the FTP case). Future versions of
222 libcurl may support more purposes. It passes the newly created
223 socket descriptor so additional setsockopt() calls can be done
224 at the user's discretion. Return 0 (zero) from the callback on
225 success. Return 1 from the callback function to signal an unre‐
226 coverable error to the library and it will close the socket and
227 return CURLE_COULDNT_CONNECT. (Option added in 7.15.6.)
228 CURLOPT_SOCKOPTDATA
230 Pass a pointer that will be untouched by libcurl and passed as
231 the first argument in the sockopt callback set with CUR‐
232 LOPT_SOCKOPTFUNCTION. (Option added in 7.15.6.)
233 CURLOPT_OPENSOCKETFUNCTION
235 Function pointer that should match the curl_opensocket_callback
236 prototype found in <curl/curl.h>. This function gets called by
237 libcurl instead of the socket(2) call. The callback's purpose
238 argument identifies the exact purpose for this particular
239 socket, and currently only one value is supported: CURLSOCK‐
240 TYPE_IPCXN for the primary connection (meaning the control con‐
241 nection in the FTP case). Future versions of libcurl may support
242 more purposes. It passes the resolved peer address as a address
243 argument so the callback can modify the address or refuse to
244 connect at all. The callback function should return the socket
245 or CURL_SOCKET_BAD in case no connection should be established
246 or any error detected. Any additional setsockopt(2) calls can be
247 done on the socket at the user's discretion. CURL_SOCKET_BAD
248 return value from the callback function will signal an unrecov‐
249 erable error to the library and it will return
250 CURLE_COULDNT_CONNECT. This return code can be used for IP
251 address blacklisting. The default behavior is:
252 return socket(addr->family, addr->socktype, addr->protocol);
253 (Option added in 7.17.1.)
254 CURLOPT_OPENSOCKETDATA
256 Pass a pointer that will be untouched by libcurl and passed as
257 the first argument in the opensocket callback set with CUR‐
258 LOPT_OPENSOCKETFUNCTION. (Option added in 7.17.1.)
259 CURLOPT_PROGRESSFUNCTION
261 Function pointer that should match the curl_progress_callback
262 prototype found in <curl/curl.h>. This function gets called by
263 libcurl instead of its internal equivalent with a frequent
264 interval during operation (roughly once per second) no matter if
265 data is being transferred or not. Unknown/unused argument val‐
266 ues passed to the callback will be set to zero (like if you only
267 download data, the upload size will remain 0). Returning a non-
268 zero value from this callback will cause libcurl to abort the
269 transfer and return CURLE_ABORTED_BY_CALLBACK.
270 If you transfer data with the multi interface, this function
272 will not be called during periods of idleness unless you call
273 the appropriate libcurl function that performs transfers.
274 CURLOPT_NOPROGRESS must be set to 0 to make this function actu‐
276 ally get called.
277 CURLOPT_PROGRESSDATA
279 Pass a pointer that will be untouched by libcurl and passed as
280 the first argument in the progress callback set with CUR‐
281 LOPT_PROGRESSFUNCTION.
282 CURLOPT_HEADERFUNCTION
284 Function pointer that should match the following prototype:
285 size_t function( void *ptr, size_t size, size_t nmemb, void
286 *stream);. This function gets called by libcurl as soon as it
287 has received header data. The header callback will be called
288 once for each header and only complete header lines are passed
289 on to the callback. Parsing headers should be easy enough using
290 this. The size of the data pointed to by ptr is size multiplied
291 with nmemb. Do not assume that the header line is zero termi‐
292 nated! The pointer named stream is the one you set with the CUR‐
293 LOPT_WRITEHEADER option. The callback function must return the
294 number of bytes actually taken care of, or return -1 to signal
295 error to the library (it will cause it to abort the transfer
296 with a CURLE_WRITE_ERROR return code).
297 If this option is not set, or if it is set to NULL, but CUR‐
299 LOPT_HEADERDATA (CURLOPT_WRITEHEADER) is set to anything but
300 NULL, the function used to accept response data will be used
301 instead. That is, it will be the function specified with CUR‐
302 LOPT_WRITEFUNCTION, or if it is not specified or NULL - the
303 default, stream-writing function.
304 It's important to note that the callback will be invoked for the
306 headers of all responses received after initiating a request and
307 not just the final response. This includes all responses which
308 occur during authentication negotiation. If you need to operate
309 on only the headers from the final response, you will need to
310 collect headers in the callback yourself and use HTTP status
311 lines, for example, to delimit response boundaries.
312 Since 7.14.1: When a server sends a chunked encoded transfer, it
314 may contain a trailer. That trailer is identical to a HTTP
315 header and if such a trailer is received it is passed to the
316 application using this callback as well. There are several ways
317 to detect it being a trailer and not an ordinary header: 1) it
318 comes after the response-body. 2) it comes after the final
319 header line (CR LF) 3) a Trailer: header among the response-
320 headers mention what header to expect in the trailer.
321 CURLOPT_WRITEHEADER
323 (This option is also known as CURLOPT_HEADERDATA) Pass a pointer
324 to be used to write the header part of the received data to. If
325 you don't use your own callback to take care of the writing,
326 this must be a valid FILE *. See also the CURLOPT_HEADERFUNCTION
327 option above on how to set a custom get-all-headers callback.
328 CURLOPT_DEBUGFUNCTION
330 Function pointer that should match the following prototype: int
331 curl_debug_callback (CURL *, curl_infotype, char *, size_t, void
332 *); CURLOPT_DEBUGFUNCTION replaces the standard debug function
333 used when CURLOPT_VERBOSE is in effect. This callback receives
334 debug information, as specified with the curl_infotype argument.
335 This function must return 0. The data pointed to by the char *
336 passed to this function WILL NOT be zero terminated, but will be
337 exactly of the size as told by the size_t argument.
338 Available curl_infotype values:
340 CURLINFO_TEXT
342 The data is informational text.
343 CURLINFO_HEADER_IN
345 The data is header (or header-like) data received from
346 the peer.
347 CURLINFO_HEADER_OUT
349 The data is header (or header-like) data sent to the
350 peer.
351 CURLINFO_DATA_IN
353 The data is protocol data received from the peer.
354 CURLINFO_DATA_OUT
356 The data is protocol data sent to the peer.
357 CURLOPT_DEBUGDATA
359 Pass a pointer to whatever you want passed in to your CUR‐
360 LOPT_DEBUGFUNCTION in the last void * argument. This pointer is
361 not used by libcurl, it is only passed to the callback.
362 CURLOPT_SSL_CTX_FUNCTION
364 This option does only function for libcurl powered by OpenSSL.
365 If libcurl was built against another SSL library, this function‐
366 ality is absent.
367 Function pointer that should match the following prototype:
369 CURLcode sslctxfun(CURL *curl, void *sslctx, void *parm); This
370 function gets called by libcurl just before the initialization
371 of an SSL connection after having processed all other SSL
372 related options to give a last chance to an application to mod‐
373 ify the behaviour of openssl's ssl initialization. The sslctx
374 parameter is actually a pointer to an openssl SSL_CTX. If an
375 error is returned no attempt to establish a connection is made
376 and the perform operation will return the error code from this
377 callback function. Set the parm argument with the CUR‐
378 LOPT_SSL_CTX_DATA option. This option was introduced in 7.11.0.
379 This function will get called on all new connections made to a
381 server, during the SSL negotiation. The SSL_CTX pointer will be
382 a new one every time.
383 To use this properly, a non-trivial amount of knowledge of the
385 openssl libraries is necessary. For example, using this function
386 allows you to use openssl callbacks to add additional validation
387 code for certificates, and even to change the actual URI of an
388 HTTPS request (example used in the lib509 test case). See also
389 the example section for a replacement of the key, certificate
390 and trust file settings.
391 CURLOPT_SSL_CTX_DATA
393 Data pointer to pass to the ssl context callback set by the
394 option CURLOPT_SSL_CTX_FUNCTION, this is the pointer you'll get
395 as third parameter, otherwise NULL. (Added in 7.11.0)
396 CURLOPT_CONV_TO_NETWORK_FUNCTION
398 CURLOPT_CONV_FROM_NETWORK_FUNCTION
400 CURLOPT_CONV_FROM_UTF8_FUNCTION
402 Function pointers that should match the following prototype:
403 CURLcode function(char *ptr, size_t length);
404 These three options apply to non-ASCII platforms only. They are
406 available only if CURL_DOES_CONVERSIONS was defined when libcurl
407 was built. When this is the case, curl_version_info(3) will
408 return the CURL_VERSION_CONV feature bit set.
409 The data to be converted is in a buffer pointed to by the ptr
411 parameter. The amount of data to convert is indicated by the
412 length parameter. The converted data overlays the input data in
413 the buffer pointed to by the ptr parameter. CURLE_OK should be
414 returned upon successful conversion. A CURLcode return value
415 defined by curl.h, such as CURLE_CONV_FAILED, should be returned
416 if an error was encountered.
417 CURLOPT_CONV_TO_NETWORK_FUNCTION and CURLOPT_CONV_FROM_NET‐
419 WORK_FUNCTION convert between the host encoding and the network
420 encoding. They are used when commands or ASCII data are
421 sent/received over the network.
422 CURLOPT_CONV_FROM_UTF8_FUNCTION is called to convert from UTF8
424 into the host encoding. It is required only for SSL processing.
425 If you set a callback pointer to NULL, or don't set it at all,
427 the built-in libcurl iconv functions will be used. If
428 HAVE_ICONV was not defined when libcurl was built, and no call‐
429 back has been established, conversion will return the
430 CURLE_CONV_REQD error code.
431 If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also
433 be defined. For example:
434 #define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
436 The iconv code in libcurl will default the network and UTF8
438 codeset names as follows:
439 #define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
441 #define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
443 You will need to override these definitions if they are differ‐
445 ent on your system.
446
448 CURLOPT_ERRORBUFFER
449 Pass a char * to a buffer that the libcurl may store human read‐
450 able error messages in. This may be more helpful than just the
451 return code from curl_easy_perform. The buffer must be at least
452 CURL_ERROR_SIZE big. Although this argument is a 'char *', it
453 does not describe an input string. Therefore the (probably
454 undefined) contents of the buffer is NOT copied by the library.
455 You should keep the associated storage available until libcurl
456 no longer needs it. Failing to do so will cause very odd behav‐
457 ior or even crashes. libcurl will need it until you call
458 curl_easy_cleanup(3) or you set the same option again to use a
459 different pointer.
460 Use CURLOPT_VERBOSE and CURLOPT_DEBUGFUNCTION to better
462 debug/trace why errors happen.
463 If the library does not return an error, the buffer may not have
465 been touched. Do not rely on the contents in those cases.
466 CURLOPT_STDERR
469 Pass a FILE * as parameter. Tell libcurl to use this stream
470 instead of stderr when showing the progress meter and displaying
471 CURLOPT_VERBOSE data.
472 CURLOPT_FAILONERROR
474 A parameter set to 1 tells the library to fail silently if the
475 HTTP code returned is equal to or larger than 400. The default
476 action would be to return the page normally, ignoring that code.
477 This method is not fail-safe and there are occasions where non-
479 successful response codes will slip through, especially when
480 authentication is involved (response codes 401 and 407).
481 You might get some amounts of headers transferred before this
483 situation is detected, like when a "100-continue" is received as
484 a response to a POST/PUT and a 401 or 407 is received immedi‐
485 ately afterwards.
486
488 CURLOPT_URL
489 The actual URL to deal with. The parameter should be a char * to
490 a zero terminated string.
491 If the given URL lacks the protocol part ("http://" or "ftp://"
493 etc), it will attempt to guess which protocol to use based on
494 the given host name. If the given protocol of the set URL is not
495 supported, libcurl will return on error (CURLE_UNSUPPORTED_PRO‐
496 TOCOL) when you call curl_easy_perform(3) or curl_multi_per‐
497 form(3). Use curl_version_info(3) for detailed info on which
498 protocols are supported.
499 The string given to CURLOPT_URL must be url-encoded and follow
501 RFC 2396 (http://curl.haxx.se/rfc/rfc2396.txt).
502 CURLOPT_URL is the only option that must be set before
504 curl_easy_perform(3) is called.
505 CURLOPT_PROTOCOLS can be used to limit what protocols libcurl
507 will use for this transfer, independent of what libcurl has been
508 compiled to support. That may be useful if you accept the URL
509 from an external source and want to limit the accessibility.
510 CURLOPT_PROTOCOLS
512 Pass a long that holds a bitmask of CURLPROTO_* defines. If
513 used, this bitmask limits what protocols libcurl may use in the
514 transfer. This allows you to have a libcurl built to support a
515 wide range of protocols but still limit specific transfers to
516 only be allowed to use a subset of them. By default libcurl will
517 accept all protocols it supports. See also CURLOPT_REDIR_PROTO‐
518 COLS. (Added in 7.19.4)
519 CURLOPT_REDIR_PROTOCOLS
521 Pass a long that holds a bitmask of CURLPROTO_* defines. If
522 used, this bitmask limits what protocols libcurl may use in a
523 transfer that it follows to in a redirect when CURLOPT_FOLLOWLO‐
524 CATION is enabled. This allows you to limit specific transfers
525 to only be allowed to use a subset of protocols in redirections.
526 By default libcurl will allow all protocols except for FILE and
527 SCP. This is a difference compared to pre-7.19.4 versions which
528 unconditionally would follow to all protocols supported. (Added
529 in 7.19.4)
530 CURLOPT_PROXY
532 Set HTTP proxy to use. The parameter should be a char * to a
533 zero terminated string holding the host name or dotted IP
534 address. To specify port number in this string, append :[port]
535 to the end of the host name. The proxy string may be prefixed
536 with [protocol]:// since any such prefix will be ignored. The
537 proxy's port number may optionally be specified with the sepa‐
538 rate option. If not specified, libcurl will default to using
539 port 1080 for proxies. CURLOPT_PROXYPORT.
540 When you tell the library to use an HTTP proxy, libcurl will
542 transparently convert operations to HTTP even if you specify an
543 FTP URL etc. This may have an impact on what other features of
544 the library you can use, such as CURLOPT_QUOTE and similar FTP
545 specifics that don't work unless you tunnel through the HTTP
546 proxy. Such tunneling is activated with CURLOPT_HTTPPROXYTUNNEL.
547 libcurl respects the environment variables http_proxy,
549 ftp_proxy, all_proxy etc, if any of those are set. The CUR‐
550 LOPT_PROXY option does however override any possibly set envi‐
551 ronment variables.
552 Setting the proxy string to "" (an empty string) will explicitly
554 disable the use of a proxy, even if there is an environment
555 variable set for it.
556 Since 7.14.1, the proxy host string given in environment vari‐
558 ables can be specified the exact same way as the proxy can be
559 set with CURLOPT_PROXY, include protocol prefix (http://) and
560 embedded user + password.
561 CURLOPT_PROXYPORT
563 Pass a long with this option to set the proxy port to connect to
564 unless it is specified in the proxy string CURLOPT_PROXY.
565 CURLOPT_PROXYTYPE
567 Pass a long with this option to set type of the proxy. Available
568 options for this are CURLPROXY_HTTP, CURLPROXY_HTTP_1_0 (added
569 in 7.19.4), CURLPROXY_SOCKS4 (added in 7.15.2), CURL‐
570 PROXY_SOCKS5, CURLPROXY_SOCKS4A (added in 7.18.0) and CURL‐
571 PROXY_SOCKS5_HOSTNAME (added in 7.18.0). The HTTP type is
572 default. (Added in 7.10)
573 CURLOPT_NOPROXY
575 Pass a pointer to a zero terminated string. The should be a
576 comma- separated list of hosts which do not use a proxy, if one
577 is specified. The only wildcard is a single * character, which
578 matches all hosts, and effectively disables the proxy. Each name
579 in this list is matched as either a domain which contains the
580 hostname, or the hostname itself. For example, local.com would
581 match local.com, local.com:80, and www.local.com, but not
582 www.notlocal.com. (Added in 7.19.4)
583 CURLOPT_HTTPPROXYTUNNEL
585 Set the parameter to 1 to make the library tunnel all operations
586 through a given HTTP proxy. There is a big difference between
587 using a proxy and to tunnel through it. If you don't know what
588 this means, you probably don't want this tunneling option.
589 CURLOPT_SOCKS5_GSSAPI_SERVICE
591 Pass a char * as parameter to a string holding the name of the
592 service. The default service name for a SOCKS5 server is
593 rcmd/server-fqdn. This option allows you to change it. (Added in
594 7.19.4)
595 CURLOPT_SOCKS5_GSSAPI_NEC
597 Pass a long set to 1 to enable or 0 to disable. As part of the
598 gssapi negotiation a protection mode is negotiated. The rfc1961
599 says in section 4.3/4.4 it should be protected, but the NEC ref‐
600 erence implementation does not. If enabled, this option allows
601 the unprotected exchange of the protection mode negotiation.
602 (Added in 7.19.4).
603 CURLOPT_INTERFACE
605 Pass a char * as parameter. This sets the interface name to use
606 as outgoing network interface. The name can be an interface
607 name, an IP address, or a host name.
608 CURLOPT_LOCALPORT
610 Pass a long. This sets the local port number of the socket used
611 for connection. This can be used in combination with CUR‐
612 LOPT_INTERFACE and you are recommended to use CURLOPT_LOCALPOR‐
613 TRANGE as well when this is set. Note that the only valid port
614 numbers are 1 - 65535. (Added in 7.15.2)
615 CURLOPT_LOCALPORTRANGE
617 Pass a long. This is the number of attempts libcurl should make
618 to find a working local port number. It starts with the given
619 CURLOPT_LOCALPORT and adds one to the number for each retry.
620 Setting this to 1 or below will make libcurl do only one try for
621 the exact port number. Note that port numbers by nature are
622 scarce resources that will be busy at times so setting this
623 value to something too low might cause unnecessary connection
624 setup failures. (Added in 7.15.2)
625 CURLOPT_DNS_CACHE_TIMEOUT
627 Pass a long, this sets the timeout in seconds. Name resolves
628 will be kept in memory for this number of seconds. Set to zero
629 to completely disable caching, or set to -1 to make the cached
630 entries remain forever. By default, libcurl caches this info for
631 60 seconds.
632 NOTE: the name resolve functions of various libc implementations
634 don't re-read name server information unless explicitly told so
635 (for example, by calling res_init(3)). This may cause libcurl to
636 keep using the older server even if DHCP has updated the server
637 info, and this may look like a DNS cache issue to the casual
638 libcurl-app user.
639 CURLOPT_DNS_USE_GLOBAL_CACHE
641 Pass a long. If the value is 1, it tells curl to use a global
642 DNS cache that will survive between easy handle creations and
643 deletions. This is not thread-safe and this will use a global
644 variable.
645 WARNING: this option is considered obsolete. Stop using it.
647 Switch over to using the share interface instead! See CUR‐
648 LOPT_SHARE and curl_share_init(3).
649 CURLOPT_BUFFERSIZE
651 Pass a long specifying your preferred size (in bytes) for the
652 receive buffer in libcurl. The main point of this would be that
653 the write callback gets called more often and with smaller
654 chunks. This is just treated as a request, not an order. You
655 cannot be guaranteed to actually get the given size. (Added in
656 7.10)
657 This size is by default set as big as possible
659 (CURL_MAX_WRITE_SIZE), so it only makes sense to use this option
660 if you want it smaller.
661 CURLOPT_PORT
663 Pass a long specifying what remote port number to connect to,
664 instead of the one specified in the URL or the default port for
665 the used protocol.
666 CURLOPT_TCP_NODELAY
668 Pass a long specifying whether the TCP_NODELAY option should be
669 set or cleared (1 = set, 0 = clear). The option is cleared by
670 default. This will have no effect after the connection has been
671 established.
672 Setting this option will disable TCP's Nagle algorithm. The pur‐
674 pose of this algorithm is to try to minimize the number of small
675 packets on the network (where "small packets" means TCP segments
676 less than the Maximum Segment Size (MSS) for the network).
677 Maximizing the amount of data sent per TCP segment is good
679 because it amortizes the overhead of the send. However, in some
680 cases (most notably telnet or rlogin) small segments may need to
681 be sent without delay. This is less efficient than sending
682 larger amounts of data at a time, and can contribute to conges‐
683 tion on the network if overdone.
684 CURLOPT_ADDRESS_SCOPE
686 Pass a long specifying the scope_id value to use when connecting
687 to IPv6 link-local or site-local addresses. (Added in 7.19.0)
688
690 CURLOPT_NETRC
691 This parameter controls the preference of libcurl between using
692 user names and passwords from your ~/.netrc file, relative to
693 user names and passwords in the URL supplied with CURLOPT_URL.
694 libcurl uses a user name (and supplied or prompted password)
696 supplied with CURLOPT_USERPWD in preference to any of the
697 options controlled by this parameter.
698 Pass a long, set to one of the values described below.
700 CURL_NETRC_OPTIONAL
702 The use of your ~/.netrc file is optional, and informa‐
703 tion in the URL is to be preferred. The file will be
704 scanned for the host and user name (to find the password
705 only) or for the host only, to find the first user name
706 and password after that machine, which ever information
707 is not specified in the URL.
708 Undefined values of the option will have this effect.
710 CURL_NETRC_IGNORED
712 The library will ignore the file and use only the infor‐
713 mation in the URL.
714 This is the default.
716 CURL_NETRC_REQUIRED
718 This value tells the library that use of the file is
719 required, to ignore the information in the URL, and to
720 search the file for the host only.
721 Only machine name, user name and password are taken into account (init
722 macros and similar things aren't supported).
723 libcurl does not verify that the file has the correct properties set
725 (as the standard Unix ftp client does). It should only be readable by
726 user.
727 CURLOPT_NETRC_FILE
729 Pass a char * as parameter, pointing to a zero terminated string
730 containing the full path name to the file you want libcurl to
731 use as .netrc file. If this option is omitted, and CURLOPT_NETRC
732 is set, libcurl will attempt to find a .netrc file in the cur‐
733 rent user's home directory. (Added in 7.10.9)
734 CURLOPT_USERPWD
736 Pass a char * as parameter, which should be [user name]:[pass‐
737 word] to use for the connection. Use CURLOPT_HTTPAUTH to decide
738 the authentication method.
739 When using NTLM, you can set the domain by prepending it to the
741 user name and separating the domain and name with a forward (/)
742 or backward slash (\). Like this: "domain/user:password" or
743 "domain\user:password". Some HTTP servers (on Windows) support
744 this style even for Basic authentication.
745 When using HTTP and CURLOPT_FOLLOWLOCATION, libcurl might per‐
747 form several requests to possibly different hosts. libcurl will
748 only send this user and password information to hosts using the
749 initial host name (unless CURLOPT_UNRESTRICTED_AUTH is set), so
750 if libcurl follows locations to other hosts it will not send the
751 user and password to those. This is enforced to prevent acciden‐
752 tal information leakage.
753 CURLOPT_PROXYUSERPWD
755 Pass a char * as parameter, which should be [user name]:[pass‐
756 word] to use for the connection to the HTTP proxy. Use CUR‐
757 LOPT_PROXYAUTH to decide the authentication method.
758 CURLOPT_USERNAME
760 Pass a char * as parameter, which should be pointing to the zero
761 terminated user name to use for the transfer.
762 CURLOPT_USERNAME sets the user name to be used in protocol
764 authentication. You should not use this option together with the
765 (older) CURLOPT_USERPWD option.
766 In order to specify the password to be used in conjunction with
768 the user name use the CURLOPT_PASSWORD option. (Added in
769 7.19.1)
770 CURLOPT_PASSWORD
772 Pass a char * as parameter, which should be pointing to the zero
773 terminated password to use for the transfer.
774 The CURLOPT_PASSWORD option should be used in conjunction with
776 the CURLOPT_USERNAME option. (Added in 7.19.1)
777 CURLOPT_PROXYUSERNAME
779 Pass a char * as parameter, which should be pointing to the zero
780 terminated user name to use for the transfer while connecting to
781 Proxy.
782 The CURLOPT_PROXYUSERNAME option should be used in same way as
784 the CURLOPT_PROXYUSERPWD is used. In comparison to CUR‐
785 LOPT_PROXYUSERPWD the CURLOPT_PROXYUSERNAME allows the username
786 to contain a colon, like in the following example:
787 "sip:user@example.com". Note the CURLOPT_PROXYUSERNAME option
788 is an alternative way to set the user name while connecting to
789 Proxy. There is no meaning to use it together with the CUR‐
790 LOPT_PROXYUSERPWD option.
791 In order to specify the password to be used in conjunction with
793 the user name use the CURLOPT_PROXYPASSWORD option. (Added in
794 7.19.1)
795 CURLOPT_PROXYPASSWORD
797 Pass a char * as parameter, which should be pointing to the zero
798 terminated password to use for the transfer while connecting to
799 Proxy.
800 The CURLOPT_PROXYPASSWORD option should be used in conjunction
802 with the CURLOPT_PROXYUSERNAME option. (Added in 7.19.1)
803 CURLOPT_HTTPAUTH
805 Pass a long as parameter, which is set to a bitmask, to tell
806 libcurl which authentication method(s) you want it to use. The
807 available bits are listed below. If more than one bit is set,
808 libcurl will first query the site to see which authentication
809 methods it supports and then pick the best one you allow it to
810 use. For some methods, this will induce an extra network round-
811 trip. Set the actual name and password with the CURLOPT_USERPWD
812 option or with the CURLOPT_USERNAME and the CURLOPT_USERPASSWORD
813 options. (Added in 7.10.6)
814 CURLAUTH_BASIC
816 HTTP Basic authentication. This is the default choice,
817 and the only method that is in wide-spread use and sup‐
818 ported virtually everywhere. This sends the user name and
819 password over the network in plain text, easily captured
820 by others.
821 CURLAUTH_DIGEST
823 HTTP Digest authentication. Digest authentication is
824 defined in RFC2617 and is a more secure way to do authen‐
825 tication over public networks than the regular old-fash‐
826 ioned Basic method.
827 CURLAUTH_DIGEST_IE
829 HTTP Digest authentication with an IE flavor. Digest
830 authentication is defined in RFC2617 and is a more secure
831 way to do authentication over public networks than the
832 regular old-fashioned Basic method. The IE flavor is sim‐
833 ply that libcurl will use a special "quirk" that IE is
834 known to have used before version 7 and that some servers
835 require the client to use. (This define was added in
836 7.19.3)
837 CURLAUTH_GSSNEGOTIATE
839 HTTP GSS-Negotiate authentication. The GSS-Negotiate
840 (also known as plain "Negotiate") method was designed by
841 Microsoft and is used in their web applications. It is
842 primarily meant as a support for Kerberos5 authentication
843 but may also be used along with other authentication
844 methods. For more information see IETF draft draft-
845 brezak-spnego-http-04.txt.
846 You need to build libcurl with a suitable GSS-API library
848 for this to work.
849 CURLAUTH_NTLM
851 HTTP NTLM authentication. A proprietary protocol invented
852 and used by Microsoft. It uses a challenge-response and
853 hash concept similar to Digest, to prevent the password
854 from being eavesdropped.
855 You need to build libcurl with OpenSSL support for this
857 option to work, or build libcurl on Windows.
858 CURLAUTH_ANY
860 This is a convenience macro that sets all bits and thus
861 makes libcurl pick any it finds suitable. libcurl will
862 automatically select the one it finds most secure.
863 CURLAUTH_ANYSAFE
865 This is a convenience macro that sets all bits except
866 Basic and thus makes libcurl pick any it finds suitable.
867 libcurl will automatically select the one it finds most
868 secure.
869 CURLOPT_PROXYAUTH
871 Pass a long as parameter, which is set to a bitmask, to tell
872 libcurl which authentication method(s) you want it to use for
873 your proxy authentication. If more than one bit is set, libcurl
874 will first query the site to see what authentication methods it
875 supports and then pick the best one you allow it to use. For
876 some methods, this will induce an extra network round-trip. Set
877 the actual name and password with the CURLOPT_PROXYUSERPWD
878 option. The bitmask can be constructed by or'ing together the
879 bits listed above for the CURLOPT_HTTPAUTH option. As of this
880 writing, only Basic, Digest and NTLM work. (Added in 7.10.7)
881
883 CURLOPT_AUTOREFERER
884 Pass a parameter set to 1 to enable this. When enabled, libcurl
885 will automatically set the Referer: field in requests where it
886 follows a Location: redirect.
887 CURLOPT_ENCODING
889 Sets the contents of the Accept-Encoding: header sent in an HTTP
890 request, and enables decoding of a response when a Content-
891 Encoding: header is received. Three encodings are supported:
892 identity, which does nothing, deflate which requests the server
893 to compress its response using the zlib algorithm, and gzip
894 which requests the gzip algorithm. If a zero-length string is
895 set, then an Accept-Encoding: header containing all supported
896 encodings is sent.
897 This is a request, not an order; the server may or may not do
899 it. This option must be set (to any non-NULL value) or else any
900 unsolicited encoding done by the server is ignored. See the spe‐
901 cial file lib/README.encoding for details.
902 CURLOPT_FOLLOWLOCATION
904 A parameter set to 1 tells the library to follow any Location:
905 header that the server sends as part of an HTTP header.
906 This means that the library will re-send the same request on the
908 new location and follow new Location: headers all the way until
909 no more such headers are returned. CURLOPT_MAXREDIRS can be used
910 to limit the number of redirects libcurl will follow.
911 NOTE: since 7.19.4, libcurl can limit to what protocols it will
913 automatically follow. The accepted protocols are set with CUR‐
914 LOPT_REDIR_PROTOCOLS and it excludes the FILE protocol by
915 default.
916 CURLOPT_UNRESTRICTED_AUTH
918 A parameter set to 1 tells the library it can continue to send
919 authentication (user+password) when following locations, even
920 when hostname changed. This option is meaningful only when set‐
921 ting CURLOPT_FOLLOWLOCATION.
922 CURLOPT_MAXREDIRS
924 Pass a long. The set number will be the redirection limit. If
925 that many redirections have been followed, the next redirect
926 will cause an error (CURLE_TOO_MANY_REDIRECTS). This option only
927 makes sense if the CURLOPT_FOLLOWLOCATION is used at the same
928 time. Added in 7.15.1: Setting the limit to 0 will make libcurl
929 refuse any redirect. Set it to -1 for an infinite number of
930 redirects (which is the default)
931 CURLOPT_POSTREDIR
933 Pass a bitmask to control how libcurl acts on redirects after
934 POSTs that get a 301 or 302 response back. A parameter with bit
935 0 set (value CURL_REDIR_POST_301) tells the library to respect
936 RFC 2616/10.3.2 and not convert POST requests into GET requests
937 when following a 301 redirection. Setting bit 1 (value
938 CURL_REDIR_POST_302) makes libcurl maintain the request method
939 after a 302 redirect. CURL_REDIR_POST_ALL is a convenience
940 define that sets both bits.
941 The non-RFC behaviour is ubiquitous in web browsers, so the
943 library does the conversion by default to maintain consistency.
944 However, a server may require a POST to remain a POST after such
945 a redirection. This option is meaningful only when setting CUR‐
946 LOPT_FOLLOWLOCATION. (Added in 7.17.1) (This option was known
947 as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 way
948 before then)
949 CURLOPT_PUT
951 A parameter set to 1 tells the library to use HTTP PUT to trans‐
952 fer data. The data should be set with CURLOPT_READDATA and CUR‐
953 LOPT_INFILESIZE.
954 This option is deprecated and starting with version 7.12.1 you
956 should instead use CURLOPT_UPLOAD.
957 CURLOPT_POST
959 A parameter set to 1 tells the library to do a regular HTTP
960 post. This will also make the library use a "Content-Type:
961 application/x-www-form-urlencoded" header. (This is by far the
962 most commonly used POST method).
963 Use one of CURLOPT_POSTFIELDS or CURLOPT_COPYPOSTFIELDS options
965 to specify what data to post and CURLOPT_POSTFIELDSIZE or CUR‐
966 LOPT_POSTFIELDSIZE_LARGE to set the data size.
967 Optionally, you can provide data to POST using the CURLOPT_READ‐
969 FUNCTION and CURLOPT_READDATA options but then you must make
970 sure to not set CURLOPT_POSTFIELDS to anything but NULL. When
971 providing data with a callback, you must transmit it using chun‐
972 ked transfer-encoding or you must set the size of the data with
973 the CURLOPT_POSTFIELDSIZE or CURLOPT_POSTFIELDSIZE_LARGE option.
974 To enable chunked encoding, you simply pass in the appropriate
975 Transfer-Encoding header, see the post-callback.c example.
976 You can override the default POST Content-Type: header by set‐
978 ting your own with CURLOPT_HTTPHEADER.
979 Using POST with HTTP 1.1 implies the use of a "Expect: 100-con‐
981 tinue" header. You can disable this header with CURLOPT_HTTP‐
982 HEADER as usual.
983 If you use POST to a HTTP 1.1 server, you can send data without
985 knowing the size before starting the POST if you use chunked
986 encoding. You enable this by adding a header like "Transfer-
987 Encoding: chunked" with CURLOPT_HTTPHEADER. With HTTP 1.0 or
988 without chunked transfer, you must specify the size in the
989 request.
990 When setting CURLOPT_POST to 1, it will automatically set CUR‐
992 LOPT_NOBODY to 0 (since 7.14.1).
993 If you issue a POST request and then want to make a HEAD or GET
995 using the same re-used handle, you must explicitly set the new
996 request type using CURLOPT_NOBODY or CURLOPT_HTTPGET or similar.
997 CURLOPT_POSTFIELDS
999 Pass a void * as parameter, which should be the full data to
1000 post in an HTTP POST operation. You must make sure that the data
1001 is formatted the way you want the server to receive it. libcurl
1002 will not convert or encode it for you. Most web servers will
1003 assume this data to be url-encoded. Take note.
1004 The pointed data are NOT copied by the library: as a conse‐
1006 quence, they must be preserved by the calling application until
1007 the transfer finishes.
1008 This POST is a normal application/x-www-form-urlencoded kind
1010 (and libcurl will set that Content-Type by default when this
1011 option is used), which is the most commonly used one by HTML
1012 forms. See also the CURLOPT_POST. Using CURLOPT_POSTFIELDS
1013 implies CURLOPT_POST.
1014 If you want to do a zero-byte POST, you need to set CUR‐
1016 LOPT_POSTFIELDSIZE explicitly to zero, as simply setting CUR‐
1017 LOPT_POSTFIELDS to NULL or "" just effectively disables the
1018 sending of the specified string. libcurl will instead assume
1019 that you'll send the POST data using the read callback!
1020 Using POST with HTTP 1.1 implies the use of a "Expect: 100-con‐
1022 tinue" header. You can disable this header with CURLOPT_HTTP‐
1023 HEADER as usual.
1024 To make multipart/formdata posts (aka RFC2388-posts), check out
1026 the CURLOPT_HTTPPOST option.
1027 CURLOPT_POSTFIELDSIZE
1029 If you want to post data to the server without letting libcurl
1030 do a strlen() to measure the data size, this option must be
1031 used. When this option is used you can post fully binary data,
1032 which otherwise is likely to fail. If this size is set to -1,
1033 the library will use strlen() to get the size.
1034 CURLOPT_POSTFIELDSIZE_LARGE
1036 Pass a curl_off_t as parameter. Use this to set the size of the
1037 CURLOPT_POSTFIELDS data to prevent libcurl from doing strlen()
1038 on the data to figure out the size. This is the large file ver‐
1039 sion of the CURLOPT_POSTFIELDSIZE option. (Added in 7.11.1)
1040 CURLOPT_COPYPOSTFIELDS
1042 Pass a char * as parameter, which should be the full data to
1043 post in an HTTP POST operation. It behaves as the CURLOPT_POST‐
1044 FIELDS option, but the original data are copied by the library,
1045 allowing the application to overwrite the original data after
1046 setting this option.
1047 Because data are copied, care must be taken when using this
1049 option in conjunction with CURLOPT_POSTFIELDSIZE or CUR‐
1050 LOPT_POSTFIELDSIZE_LARGE: If the size has not been set prior to
1051 CURLOPT_COPYPOSTFIELDS, the data are assumed to be a NUL-termi‐
1052 nated string; else the stored size informs the library about the
1053 data byte count to copy. In any case, the size must not be
1054 changed after CURLOPT_COPYPOSTFIELDS, unless another CUR‐
1055 LOPT_POSTFIELDS or CURLOPT_COPYPOSTFIELDS option is issued.
1056 (Added in 7.17.1)
1057 CURLOPT_HTTPPOST
1059 Tells libcurl you want a multipart/formdata HTTP POST to be made
1060 and you instruct what data to pass on to the server. Pass a
1061 pointer to a linked list of curl_httppost structs as parameter.
1062 The easiest way to create such a list, is to use curl_formadd(3)
1063 as documented. The data in this list must remain intact until
1064 you close this curl handle again with curl_easy_cleanup(3).
1065 Using POST with HTTP 1.1 implies the use of a "Expect: 100-con‐
1067 tinue" header. You can disable this header with CURLOPT_HTTP‐
1068 HEADER as usual.
1069 When setting CURLOPT_HTTPPOST, it will automatically set CUR‐
1071 LOPT_NOBODY to 0 (since 7.14.1).
1072 CURLOPT_REFERER
1074 Pass a pointer to a zero terminated string as parameter. It will
1075 be used to set the Referer: header in the http request sent to
1076 the remote server. This can be used to fool servers or scripts.
1077 You can also set any custom header with CURLOPT_HTTPHEADER.
1078 CURLOPT_USERAGENT
1080 Pass a pointer to a zero terminated string as parameter. It will
1081 be used to set the User-Agent: header in the http request sent
1082 to the remote server. This can be used to fool servers or
1083 scripts. You can also set any custom header with CURLOPT_HTTP‐
1084 HEADER.
1085 CURLOPT_HTTPHEADER
1087 Pass a pointer to a linked list of HTTP headers to pass to the
1088 server in your HTTP request. The linked list should be a fully
1089 valid list of struct curl_slist structs properly filled in. Use
1090 curl_slist_append(3) to create the list and
1091 curl_slist_free_all(3) to clean up an entire list. If you add a
1092 header that is otherwise generated and used by libcurl inter‐
1093 nally, your added one will be used instead. If you add a header
1094 with no content as in 'Accept:' (no data on the right side of
1095 the colon), the internally used header will get disabled. Thus,
1096 using this option you can add new headers, replace internal
1097 headers and remove internal headers. To add a header with no
1098 content, make the content be two quotes: "". The headers
1099 included in the linked list must not be CRLF-terminated, because
1100 curl adds CRLF after each header item. Failure to comply with
1101 this will result in strange bugs because the server will most
1102 likely ignore part of the headers you specified.
1103 The first line in a request (containing the method, usually a
1105 GET or POST) is not a header and cannot be replaced using this
1106 option. Only the lines following the request-line are headers.
1107 Adding this method line in this list of headers will only cause
1108 your request to send an invalid header.
1109 Pass a NULL to this to reset back to no custom headers.
1111 The most commonly replaced headers have "shortcuts" in the
1113 options CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER.
1114 CURLOPT_HTTP200ALIASES
1116 Pass a pointer to a linked list of aliases to be treated as
1117 valid HTTP 200 responses. Some servers respond with a custom
1118 header response line. For example, IceCast servers respond with
1119 "ICY 200 OK". By including this string in your list of aliases,
1120 the response will be treated as a valid HTTP header line such as
1121 "HTTP/1.0 200 OK". (Added in 7.10.3)
1122 The linked list should be a fully valid list of struct
1124 curl_slist structs, and be properly filled in. Use
1125 curl_slist_append(3) to create the list and
1126 curl_slist_free_all(3) to clean up an entire list.
1127 The alias itself is not parsed for any version strings. Before
1129 libcurl 7.16.3, Libcurl used the value set by option CUR‐
1130 LOPT_HTTP_VERSION, but starting with 7.16.3 the protocol is
1131 assumed to match HTTP 1.0 when an alias matched.
1132 CURLOPT_COOKIE
1134 Pass a pointer to a zero terminated string as parameter. It will
1135 be used to set a cookie in the http request. The format of the
1136 string should be NAME=CONTENTS, where NAME is the cookie name
1137 and CONTENTS is what the cookie should contain.
1138 If you need to set multiple cookies, you need to set them all
1140 using a single option and thus you need to concatenate them all
1141 in one single string. Set multiple cookies in one string like
1142 this: "name1=content1; name2=content2;" etc.
1143 Note that this option sets the cookie header explicitly in the
1145 outgoing request(s). If multiple requests are done due to
1146 authentication, followed redirections or similar, they will all
1147 get this cookie passed on.
1148 Using this option multiple times will only make the latest
1150 string override the previous ones.
1151 CURLOPT_COOKIEFILE
1153 Pass a pointer to a zero terminated string as parameter. It
1154 should contain the name of your file holding cookie data to
1155 read. The cookie data may be in Netscape / Mozilla cookie data
1156 format or just regular HTTP-style headers dumped to a file.
1157 Given an empty or non-existing file or by passing the empty
1159 string (""), this option will enable cookies for this curl han‐
1160 dle, making it understand and parse received cookies and then
1161 use matching cookies in future requests.
1162 If you use this option multiple times, you just add more files
1164 to read. Subsequent files will add more cookies.
1165 CURLOPT_COOKIEJAR
1167 Pass a file name as char *, zero terminated. This will make
1168 libcurl write all internally known cookies to the specified file
1169 when curl_easy_cleanup(3) is called. If no cookies are known, no
1170 file will be created. Specify "-" to instead have the cookies
1171 written to stdout. Using this option also enables cookies for
1172 this session, so if you for example follow a location it will
1173 make matching cookies get sent accordingly.
1174 If the cookie jar file can't be created or written to (when the
1176 curl_easy_cleanup(3) is called), libcurl will not and cannot
1177 report an error for this. Using CURLOPT_VERBOSE or CUR‐
1178 LOPT_DEBUGFUNCTION will get a warning to display, but that is
1179 the only visible feedback you get about this possibly lethal
1180 situation.
1181 CURLOPT_COOKIESESSION
1183 Pass a long set to 1 to mark this as a new cookie "session". It
1184 will force libcurl to ignore all cookies it is about to load
1185 that are "session cookies" from the previous session. By
1186 default, libcurl always stores and loads all cookies, indepen‐
1187 dent if they are session cookies or not. Session cookies are
1188 cookies without expiry date and they are meant to be alive and
1189 existing for this "session" only.
1190 CURLOPT_COOKIELIST
1192 Pass a char * to a cookie string. Cookie can be either in Net‐
1193 scape / Mozilla format or just regular HTTP-style header (Set-
1194 Cookie: ...) format. If cURL cookie engine was not enabled it
1195 will enable its cookie engine. Passing a magic string "ALL"
1196 will erase all cookies known by cURL. (Added in 7.14.1) Passing
1197 the special string "SESS" will only erase all session cookies
1198 known by cURL. (Added in 7.15.4) Passing the special string
1199 "FLUSH" will write all cookies known by cURL to the file speci‐
1200 fied by CURLOPT_COOKIEJAR. (Added in 7.17.1)
1201 CURLOPT_HTTPGET
1203 Pass a long. If the long is 1, this forces the HTTP request to
1204 get back to GET. Usable if a POST, HEAD, PUT, or a custom
1205 request has been used previously using the same curl handle.
1206 When setting CURLOPT_HTTPGET to 1, it will automatically set
1208 CURLOPT_NOBODY to 0 (since 7.14.1).
1209 CURLOPT_HTTP_VERSION
1211 Pass a long, set to one of the values described below. They
1212 force libcurl to use the specific HTTP versions. This is not
1213 sensible to do unless you have a good reason.
1214 CURL_HTTP_VERSION_NONE
1216 We don't care about what version the library uses.
1217 libcurl will use whatever it thinks fit.
1218 CURL_HTTP_VERSION_1_0
1220 Enforce HTTP 1.0 requests.
1221 CURL_HTTP_VERSION_1_1
1223 Enforce HTTP 1.1 requests.
1224 CURLOPT_IGNORE_CONTENT_LENGTH
1226 Ignore the Content-Length header. This is useful for Apache 1.x
1227 (and similar servers) which will report incorrect content length
1228 for files over 2 gigabytes. If this option is used, curl will
1229 not be able to accurately report progress, and will simply stop
1230 the download when the server ends the connection. (added in
1231 7.14.1)
1232 CURLOPT_HTTP_CONTENT_DECODING
1234 Pass a long to tell libcurl how to act on content decoding. If
1235 set to zero, content decoding will be disabled. If set to 1 it
1236 is enabled. Note however that libcurl has no default content
1237 decoding but requires you to use CURLOPT_ENCODING for that.
1238 (added in 7.16.2)
1239 CURLOPT_HTTP_TRANSFER_DECODING
1241 Pass a long to tell libcurl how to act on transfer decoding. If
1242 set to zero, transfer decoding will be disabled, if set to 1 it
1243 is enabled (default). libcurl does chunked transfer decoding by
1244 default unless this option is set to zero. (added in 7.16.2)
1245
1247 CURLOPT_TFTPBLKSIZE
1248 Specify block size to use for TFTP data transmission. Valid
1249 range as per RFC 2348 is 8-65464 bytes. The default of 512 bytes
1250 will be used if this option is not specified. The specified
1251 block size will only be used pending support by the remote
1252 server. If the server does not return an option acknowledgment
1253 or returns an option acknowledgment with no blksize, the default
1254 of 512 bytes will be used. (added in 7.19.4)
1255
1257 CURLOPT_FTPPORT
1258 Pass a pointer to a zero terminated string as parameter. It will
1259 be used to get the IP address to use for the FTP PORT instruc‐
1260 tion. The PORT instruction tells the remote server to connect to
1261 our specified IP address. The string may be a plain IP address,
1262 a host name, a network interface name (under Unix) or just a '-'
1263 symbol to let the library use your system's default IP address.
1264 Default FTP operations are passive, and thus won't use PORT.
1265 The address can be followed by a ':' to specify a port, option‐
1267 ally followed by a '-' to specify a port range. If the port
1268 specified is 0, the operating system will pick a free port. If
1269 a range is provided and all ports in the range are not avail‐
1270 able, libcurl will report CURLE_FTP_PORT_FAILED for the handle.
1271 Invalid port/range settings are ignored. IPv6 addresses fol‐
1272 lowed by a port or portrange have to be in brackets. IPv6
1273 addresses without port/range specifier can be in brackets.
1274 (added in 7.19.5)
1275 Examples with specified ports:
1277 eth0:0
1279 192.168.1.2:32000-33000
1280 curl.se:32123
1281 [::1]:1234-4567
1282 You disable PORT again and go back to using the passive version
1284 by setting this option to NULL.
1285 CURLOPT_QUOTE
1287 Pass a pointer to a linked list of FTP or SFTP commands to pass
1288 to the server prior to your FTP request. This will be done
1289 before any other commands are issued (even before the CWD com‐
1290 mand for FTP). The linked list should be a fully valid list of
1291 'struct curl_slist' structs properly filled in with text
1292 strings. Use curl_slist_append(3) to append strings (commands)
1293 to the list, and clear the entire list afterwards with
1294 curl_slist_free_all(3). Disable this operation again by setting
1295 a NULL to this option. The set of valid FTP commands depends on
1296 the server (see RFC959 for a list of mandatory commands). The
1297 valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd,
1298 rename, rm, rmdir, symlink (see curl(1)) (SFTP support added in
1299 7.16.3)
1300 CURLOPT_POSTQUOTE
1302 Pass a pointer to a linked list of FTP or SFTP commands to pass
1303 to the server after your FTP transfer request. The commands will
1304 only be run if no error occurred. The linked list should be a
1305 fully valid list of struct curl_slist structs properly filled in
1306 as described for CURLOPT_QUOTE. Disable this operation again by
1307 setting a NULL to this option.
1308 CURLOPT_PREQUOTE
1310 Pass a pointer to a linked list of FTP commands to pass to the
1311 server after the transfer type is set. The linked list should be
1312 a fully valid list of struct curl_slist structs properly filled
1313 in as described for CURLOPT_QUOTE. Disable this operation again
1314 by setting a NULL to this option. Before version 7.15.6, if you
1315 also set CURLOPT_NOBODY to 1, this option didn't work.
1316 CURLOPT_DIRLISTONLY
1318 A parameter set to 1 tells the library to just list the names of
1319 files in a directory, instead of doing a full directory listing
1320 that would include file sizes, dates etc. This works for FTP and
1321 SFTP URLs.
1322 This causes an FTP NLST command to be sent on an FTP server.
1324 Beware that some FTP servers list only files in their response
1325 to NLST; they might not include subdirectories and symbolic
1326 links.
1327 (This option was known as CURLOPT_FTPLISTONLY up to 7.16.4)
1329 CURLOPT_APPEND
1331 A parameter set to 1 tells the library to append to the remote
1332 file instead of overwrite it. This is only useful when uploading
1333 to an FTP site.
1334 (This option was known as CURLOPT_FTPAPPEND up to 7.16.4)
1336 CURLOPT_FTP_USE_EPRT
1338 Pass a long. If the value is 1, it tells curl to use the EPRT
1339 (and LPRT) command when doing active FTP downloads (which is
1340 enabled by CURLOPT_FTPPORT). Using EPRT means that it will first
1341 attempt to use EPRT and then LPRT before using PORT, but if you
1342 pass zero to this option, it will not try using EPRT or LPRT,
1343 only plain PORT. (Added in 7.10.5)
1344 If the server is an IPv6 host, this option will have no effect
1346 as of 7.12.3.
1347 CURLOPT_FTP_USE_EPSV
1349 Pass a long. If the value is 1, it tells curl to use the EPSV
1350 command when doing passive FTP downloads (which it always does
1351 by default). Using EPSV means that it will first attempt to use
1352 EPSV before using PASV, but if you pass zero to this option, it
1353 will not try using EPSV, only plain PASV.
1354 If the server is an IPv6 host, this option will have no effect
1356 as of 7.12.3.
1357 CURLOPT_FTP_CREATE_MISSING_DIRS
1359 Pass a long. If the value is 1, curl will attempt to create any
1360 remote directory that it fails to CWD into. CWD is the command
1361 that changes working directory. (Added in 7.10.7)
1362 This setting also applies to SFTP-connections. curl will attempt
1364 to create the remote directory if it can't obtain a handle to
1365 the target-location. The creation will fail if a file of the
1366 same name as the directory to create already exists or lack of
1367 permissions prevents creation. (Added in 7.16.3)
1368 Starting with 7.19.4, you can also set this value to 2, which
1370 will make libcurl retry the CWD command again if the subsequent
1371 MKD command fails. This is especially useful if you're doing
1372 many simultaneous connections against the same server and they
1373 all have this option enabled, as then CWD may first fail but
1374 then another connection does MKD before this connection and thus
1375 MKD fails but trying CWD works! 7.19.4 also introduced the
1376 CURLFTP_CREATE_DIR and CURLFTP_CREATE_DIR_RETRY enum names for
1377 these arguments.
1378 Before version 7.19.4, libcurl will simply ignore arguments set
1380 to 2 and act as if 1 was selected.
1381 CURLOPT_FTP_RESPONSE_TIMEOUT
1383 Pass a long. Causes curl to set a timeout period (in seconds)
1384 on the amount of time that the server is allowed to take in
1385 order to generate a response message for a command before the
1386 session is considered hung. While curl is waiting for a
1387 response, this value overrides CURLOPT_TIMEOUT. It is recom‐
1388 mended that if used in conjunction with CURLOPT_TIMEOUT, you set
1389 CURLOPT_FTP_RESPONSE_TIMEOUT to a value smaller than CUR‐
1390 LOPT_TIMEOUT. (Added in 7.10.8)
1391 CURLOPT_FTP_ALTERNATIVE_TO_USER
1393 Pass a char * as parameter, pointing to a string which will be
1394 used to authenticate if the usual FTP "USER user" and "PASS
1395 password" negotiation fails. This is currently only known to be
1396 required when connecting to Tumbleweed's Secure Transport FTPS
1397 server using client certificates for authentication. (Added in
1398 7.15.5)
1399 CURLOPT_FTP_SKIP_PASV_IP
1401 Pass a long. If set to 1, it instructs libcurl to not use the IP
1402 address the server suggests in its 227-response to libcurl's
1403 PASV command when libcurl connects the data connection. Instead
1404 libcurl will re-use the same IP address it already uses for the
1405 control connection. But it will use the port number from the
1406 227-response. (Added in 7.14.2)
1407 This option has no effect if PORT, EPRT or EPSV is used instead
1409 of PASV.
1410 CURLOPT_USE_SSL
1412 Pass a long using one of the values from below, to make libcurl
1413 use your desired level of SSL for the FTP transfer. (Added in
1414 7.11.0)
1415 (This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the
1417 constants were known as CURLFTPSSL_*)
1418 CURLUSESSL_NONE
1420 Don't attempt to use SSL.
1421 CURLUSESSL_TRY
1423 Try using SSL, proceed as normal otherwise.
1424 CURLUSESSL_CONTROL
1426 Require SSL for the control connection or fail with
1427 CURLE_USE_SSL_FAILED.
1428 CURLUSESSL_ALL
1430 Require SSL for all communication or fail with
1431 CURLE_USE_SSL_FAILED.
1432 CURLOPT_FTPSSLAUTH
1434 Pass a long using one of the values from below, to alter how
1435 libcurl issues "AUTH TLS" or "AUTH SSL" when FTP over SSL is
1436 activated (see CURLOPT_USE_SSL). (Added in 7.12.2)
1437 CURLFTPAUTH_DEFAULT
1439 Allow libcurl to decide.
1440 CURLFTPAUTH_SSL
1442 Try "AUTH SSL" first, and only if that fails try "AUTH
1443 TLS".
1444 CURLFTPAUTH_TLS
1446 Try "AUTH TLS" first, and only if that fails try "AUTH
1447 SSL".
1448 CURLOPT_FTP_SSL_CCC
1450 If enabled, this option makes libcurl use CCC (Clear Command
1451 Channel). It shuts down the SSL/TLS layer after authenticating.
1452 The rest of the control channel communication will be unen‐
1453 crypted. This allows NAT routers to follow the FTP transaction.
1454 Pass a long using one of the values below. (Added in 7.16.1)
1455 CURLFTPSSL_CCC_NONE
1457 Don't attempt to use CCC.
1458 CURLFTPSSL_CCC_PASSIVE
1460 Do not initiate the shutdown, but wait for the server to
1461 do it. Do not send a reply.
1462 CURLFTPSSL_CCC_ACTIVE
1464 Initiate the shutdown and wait for a reply.
1465 CURLOPT_FTP_ACCOUNT
1467 Pass a pointer to a zero-terminated string (or NULL to disable).
1468 When an FTP server asks for "account data" after user name and
1469 password has been provided, this data is sent off using the ACCT
1470 command. (Added in 7.13.0)
1471 CURLOPT_FTP_FILEMETHOD
1473 Pass a long that should have one of the following values. This
1474 option controls what method libcurl should use to reach a file
1475 on a FTP(S) server. The argument should be one of the following
1476 alternatives:
1477 CURLFTPMETHOD_MULTICWD
1479 libcurl does a single CWD operation for each path part in
1480 the given URL. For deep hierarchies this means many com‐
1481 mands. This is how RFC1738 says it should be done. This
1482 is the default but the slowest behavior.
1483 CURLFTPMETHOD_NOCWD
1485 libcurl does no CWD at all. libcurl will do SIZE, RETR,
1486 STOR etc and give a full path to the server for all these
1487 commands. This is the fastest behavior.
1488 CURLFTPMETHOD_SINGLECWD
1490 libcurl does one CWD with the full target directory and
1491 then operates on the file "normally" (like in the multi‐
1492 cwd case). This is somewhat more standards compliant than
1493 'nocwd' but without the full penalty of 'multicwd'.
1494 (Added in 7.15.1)
1495
1497 CURLOPT_TRANSFERTEXT
1498 A parameter set to 1 tells the library to use ASCII mode for FTP
1499 transfers, instead of the default binary transfer. For win32
1500 systems it does not set the stdout to binary mode. This option
1501 can be usable when transferring text data between systems with
1502 different views on certain characters, such as newlines or simi‐
1503 lar.
1504 libcurl does not do a complete ASCII conversion when doing ASCII
1506 transfers over FTP. This is a known limitation/flaw that nobody
1507 has rectified. libcurl simply sets the mode to ASCII and per‐
1508 forms a standard transfer.
1509 CURLOPT_PROXY_TRANSFER_MODE
1511 Pass a long. If the value is set to 1 (one), it tells libcurl to
1512 set the transfer mode (binary or ASCII) for FTP transfers done
1513 via an HTTP proxy, by appending ;type=a or ;type=i to the URL.
1514 Without this setting, or it being set to 0 (zero, the default),
1515 CURLOPT_TRANSFERTEXT has no effect when doing FTP via a proxy.
1516 Beware that not all proxies support this feature. (Added in
1517 7.18.0)
1518 CURLOPT_CRLF
1520 Convert Unix newlines to CRLF newlines on transfers.
1521 CURLOPT_RANGE
1523 Pass a char * as parameter, which should contain the specified
1524 range you want. It should be in the format "X-Y", where X or Y
1525 may be left out. HTTP transfers also support several intervals,
1526 separated with commas as in "X-Y,N-M". Using this kind of multi‐
1527 ple intervals will cause the HTTP server to send the response
1528 document in pieces (using standard MIME separation techniques).
1529 Pass a NULL to this option to disable the use of ranges.
1530 Ranges work on HTTP, FTP and FILE (since 7.18.0) transfers only.
1532 CURLOPT_RESUME_FROM
1534 Pass a long as parameter. It contains the offset in number of
1535 bytes that you want the transfer to start from. Set this option
1536 to 0 to make the transfer start from the beginning (effectively
1537 disabling resume). For FTP, set this option to -1 to make the
1538 transfer start from the end of the target file (useful to con‐
1539 tinue an interrupted upload).
1540 CURLOPT_RESUME_FROM_LARGE
1542 Pass a curl_off_t as parameter. It contains the offset in number
1543 of bytes that you want the transfer to start from. (Added in
1544 7.11.0)
1545 CURLOPT_CUSTOMREQUEST
1547 Pass a pointer to a zero terminated string as parameter. It will
1548 be used instead of GET or HEAD when doing an HTTP request, or
1549 instead of LIST or NLST when doing a FTP directory listing. This
1550 is useful for doing DELETE or other more or less obscure HTTP
1551 requests. Don't do this at will, make sure your server supports
1552 the command first.
1553 When you change the request method by setting CURLOPT_CUSTOMRE‐
1555 QUEST to something, you don't actually change how libcurl
1556 behaves or acts in regards to the particular request method, it
1557 will only change the actual string sent in the request.
1558 For example: if you tell libcurl to do a HEAD request, but then
1560 change the request to a "GET" with CURLOPT_CUSTOMREQUEST you'll
1561 still see libcurl act as if it sent a HEAD even when it does
1562 send a GET.
1563 To switch to a proper HEAD, use CURLOPT_NOBODY, to switch to a
1565 proper POST, use CURLOPT_POST or CURLOPT_POSTFIELDS and so on.
1566 Restore to the internal default by setting this to NULL.
1568 Many people have wrongly used this option to replace the entire
1570 request with their own, including multiple headers and POST con‐
1571 tents. While that might work in many cases, it will cause
1572 libcurl to send invalid requests and it could possibly confuse
1573 the remote server badly. Use CURLOPT_POST and CURLOPT_POSTFIELDS
1574 to set POST data. Use CURLOPT_HTTPHEADER to replace or extend
1575 the set of headers sent by libcurl. Use CURLOPT_HTTP_VERSION to
1576 change HTTP version.
1577 CURLOPT_FILETIME
1579 Pass a long. If it is 1, libcurl will attempt to get the modifi‐
1580 cation date of the remote document in this operation. This
1581 requires that the remote server sends the time or replies to a
1582 time querying command. The curl_easy_getinfo(3) function with
1583 the CURLINFO_FILETIME argument can be used after a transfer to
1584 extract the received time (if any).
1585 CURLOPT_NOBODY
1587 A parameter set to 1 tells the library to not include the body-
1588 part in the output. This is only relevant for protocols that
1589 have separate header and body parts. On HTTP(S) servers, this
1590 will make libcurl do a HEAD request.
1591 To change request to GET, you should use CURLOPT_HTTPGET. Change
1593 request to POST with CURLOPT_POST etc.
1594 CURLOPT_INFILESIZE
1596 When uploading a file to a remote site, this option should be
1597 used to tell libcurl what the expected size of the infile is.
1598 This value should be passed as a long. See also CURLOPT_INFILE‐
1599 SIZE_LARGE.
1600 For uploading using SCP, this option or CURLOPT_INFILESIZE_LARGE
1602 is mandatory.
1603 Note that this option does not limit how much data libcurl will
1605 actually send, as that is controlled entirely by what the read
1606 callback returns.
1607 CURLOPT_INFILESIZE_LARGE
1609 When uploading a file to a remote site, this option should be
1610 used to tell libcurl what the expected size of the infile is.
1611 This value should be passed as a curl_off_t. (Added in 7.11.0)
1612 For uploading using SCP, this option or CURLOPT_INFILESIZE is
1614 mandatory.
1615 Note that this option does not limit how much data libcurl will
1617 actually send, as that is controlled entirely by what the read
1618 callback returns.
1619 CURLOPT_UPLOAD
1621 A parameter set to 1 tells the library to prepare for an upload.
1622 The CURLOPT_READDATA and CURLOPT_INFILESIZE or CURLOPT_INFILE‐
1623 SIZE_LARGE options are also interesting for uploads. If the pro‐
1624 tocol is HTTP, uploading means using the PUT request unless you
1625 tell libcurl otherwise.
1626 Using PUT with HTTP 1.1 implies the use of a "Expect: 100-con‐
1628 tinue" header. You can disable this header with CURLOPT_HTTP‐
1629 HEADER as usual.
1630 If you use PUT to a HTTP 1.1 server, you can upload data without
1632 knowing the size before starting the transfer if you use chunked
1633 encoding. You enable this by adding a header like "Transfer-
1634 Encoding: chunked" with CURLOPT_HTTPHEADER. With HTTP 1.0 or
1635 without chunked transfer, you must specify the size.
1636 CURLOPT_MAXFILESIZE
1638 Pass a long as parameter. This allows you to specify the maximum
1639 size (in bytes) of a file to download. If the file requested is
1640 larger than this value, the transfer will not start and
1641 CURLE_FILESIZE_EXCEEDED will be returned.
1642 The file size is not always known prior to download, and for
1644 such files this option has no effect even if the file transfer
1645 ends up being larger than this given limit. This concerns both
1646 FTP and HTTP transfers.
1647 CURLOPT_MAXFILESIZE_LARGE
1649 Pass a curl_off_t as parameter. This allows you to specify the
1650 maximum size (in bytes) of a file to download. If the file
1651 requested is larger than this value, the transfer will not start
1652 and CURLE_FILESIZE_EXCEEDED will be returned. (Added in 7.11.0)
1653 The file size is not always known prior to download, and for
1655 such files this option has no effect even if the file transfer
1656 ends up being larger than this given limit. This concerns both
1657 FTP and HTTP transfers.
1658 CURLOPT_TIMECONDITION
1660 Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE
1661 time value is treated. You can set this parameter to CURL_TIME‐
1662 COND_IFMODSINCE or CURL_TIMECOND_IFUNMODSINCE. This feature
1663 applies to HTTP and FTP.
1664 The last modification time of a file is not always known and in
1666 such instances this feature will have no effect even if the
1667 given time condition would not have been met. curl_easy_get‐
1668 info(3) with the CURLINFO_CONDITION_UNMET option can be used
1669 after a transfer to learn if a zero-byte successful "transfer"
1670 was due to this condition not matching.
1671 CURLOPT_TIMEVALUE
1673 Pass a long as parameter. This should be the time in seconds
1674 since 1 Jan 1970, and the time will be used in a condition as
1675 specified with CURLOPT_TIMECONDITION.
1676
1678 CURLOPT_TIMEOUT
1679 Pass a long as parameter containing the maximum time in seconds
1680 that you allow the libcurl transfer operation to take. Normally,
1681 name lookups can take a considerable time and limiting opera‐
1682 tions to less than a few minutes risk aborting perfectly normal
1683 operations. This option will cause curl to use the SIGALRM to
1684 enable time-outing system calls.
1685 In unix-like systems, this might cause signals to be used unless
1687 CURLOPT_NOSIGNAL is set.
1688 CURLOPT_TIMEOUT_MS
1690 Like CURLOPT_TIMEOUT but takes number of milliseconds instead.
1691 If libcurl is built to use the standard system name resolver,
1692 that portion of the transfer will still use full-second resolu‐
1693 tion for timeouts with a minimum timeout allowed of one second.
1694 (Added in 7.16.2)
1695 CURLOPT_LOW_SPEED_LIMIT
1697 Pass a long as parameter. It contains the transfer speed in
1698 bytes per second that the transfer should be below during CUR‐
1699 LOPT_LOW_SPEED_TIME seconds for the library to consider it too
1700 slow and abort.
1701 CURLOPT_LOW_SPEED_TIME
1703 Pass a long as parameter. It contains the time in seconds that
1704 the transfer should be below the CURLOPT_LOW_SPEED_LIMIT for the
1705 library to consider it too slow and abort.
1706 CURLOPT_MAX_SEND_SPEED_LARGE
1708 Pass a curl_off_t as parameter. If an upload exceeds this speed
1709 (counted in bytes per second) on cumulative average during the
1710 transfer, the transfer will pause to keep the average rate less
1711 than or equal to the parameter value. Defaults to unlimited
1712 speed. (Added in 7.15.5)
1713 CURLOPT_MAX_RECV_SPEED_LARGE
1715 Pass a curl_off_t as parameter. If a download exceeds this
1716 speed (counted in bytes per second) on cumulative average during
1717 the transfer, the transfer will pause to keep the average rate
1718 less than or equal to the parameter value. Defaults to unlimited
1719 speed. (Added in 7.15.5)
1720 CURLOPT_MAXCONNECTS
1722 Pass a long. The set number will be the persistent connection
1723 cache size. The set amount will be the maximum amount of simul‐
1724 taneously open connections that libcurl may cache in this easy
1725 handle. Default is 5, and there isn't much point in changing
1726 this value unless you are perfectly aware of how this works and
1727 changes libcurl's behaviour. This concerns connections using any
1728 of the protocols that support persistent connections.
1729 When reaching the maximum limit, curl closes the oldest one in
1731 the cache to prevent increasing the number of open connections.
1732 If you already have performed transfers with this curl handle,
1734 setting a smaller MAXCONNECTS than before may cause open connec‐
1735 tions to get closed unnecessarily.
1736 Note that if you add this easy handle to a multi handle, this
1738 setting is not acknowledged, and you must instead use
1739 curl_multi_setopt(3) and the CURLMOPT_MAXCONNECTS option.
1740 CURLOPT_CLOSEPOLICY
1742 (Obsolete) This option does nothing.
1743 CURLOPT_FRESH_CONNECT
1745 Pass a long. Set to 1 to make the next transfer use a new
1746 (fresh) connection by force. If the connection cache is full
1747 before this connection, one of the existing connections will be
1748 closed as according to the selected or default policy. This
1749 option should be used with caution and only if you understand
1750 what it does. Set this to 0 to have libcurl attempt re-using an
1751 existing connection (default behavior).
1752 CURLOPT_FORBID_REUSE
1754 Pass a long. Set to 1 to make the next transfer explicitly close
1755 the connection when done. Normally, libcurl keeps all connec‐
1756 tions alive when done with one transfer in case a succeeding one
1757 follows that can re-use them. This option should be used with
1758 caution and only if you understand what it does. Set to 0 to
1759 have libcurl keep the connection open for possible later re-use
1760 (default behavior).
1761 CURLOPT_CONNECTTIMEOUT
1763 Pass a long. It should contain the maximum time in seconds that
1764 you allow the connection to the server to take. This only lim‐
1765 its the connection phase, once it has connected, this option is
1766 of no more use. Set to zero to disable connection timeout (it
1767 will then only timeout on the system's internal timeouts). See
1768 also the CURLOPT_TIMEOUT option.
1769 In unix-like systems, this might cause signals to be used unless
1771 CURLOPT_NOSIGNAL is set.
1772 CURLOPT_CONNECTTIMEOUT_MS
1774 Like CURLOPT_CONNECTTIMEOUT but takes the number of milliseconds
1775 instead. If libcurl is built to use the standard system name
1776 resolver, that portion of the connect will still use full-second
1777 resolution for timeouts with a minimum timeout allowed of one
1778 second. (Added in 7.16.2)
1779 CURLOPT_IPRESOLVE
1781 Allows an application to select what kind of IP addresses to use
1782 when resolving host names. This is only interesting when using
1783 host names that resolve addresses using more than one version of
1784 IP. The allowed values are:
1785 CURL_IPRESOLVE_WHATEVER
1787 Default, resolves addresses to all IP versions that your
1788 system allows.
1789 CURL_IPRESOLVE_V4
1791 Resolve to IPv4 addresses.
1792 CURL_IPRESOLVE_V6
1794 Resolve to IPv6 addresses.
1795 CURLOPT_CONNECT_ONLY
1797 Pass a long. If the parameter equals 1, it tells the library to
1798 perform all the required proxy authentication and connection
1799 setup, but no data transfer. This option is useful only on HTTP
1800 URLs.
1801 This option is useful with the CURLINFO_LASTSOCKET option to
1803 curl_easy_getinfo(3). The library can set up the connection and
1804 then the application can obtain the most recently used socket
1805 for special data transfers. (Added in 7.15.2)
1806
1808 CURLOPT_SSLCERT
1809 Pass a pointer to a zero terminated string as parameter. The
1810 string should be the file name of your certificate. The default
1811 format is "PEM" and can be changed with CURLOPT_SSLCERTTYPE.
1812 With NSS this can also be the nickname of the certificate you
1814 wish to authenticate with. If you want to use a file from the
1815 current directory, please precede it with "./" prefix, in order
1816 to avoid confusion with a nickname.
1817 CURLOPT_SSLCERTTYPE
1819 Pass a pointer to a zero terminated string as parameter. The
1820 string should be the format of your certificate. Supported for‐
1821 mats are "PEM" and "DER". (Added in 7.9.3)
1822 CURLOPT_SSLKEY
1824 Pass a pointer to a zero terminated string as parameter. The
1825 string should be the file name of your private key. The default
1826 format is "PEM" and can be changed with CURLOPT_SSLKEYTYPE.
1827 CURLOPT_SSLKEYTYPE
1829 Pass a pointer to a zero terminated string as parameter. The
1830 string should be the format of your private key. Supported for‐
1831 mats are "PEM", "DER" and "ENG".
1832 The format "ENG" enables you to load the private key from a
1834 crypto engine. In this case CURLOPT_SSLKEY is used as an identi‐
1835 fier passed to the engine. You have to set the crypto engine
1836 with CURLOPT_SSLENGINE. "DER" format key file currently does
1837 not work because of a bug in OpenSSL.
1838 CURLOPT_KEYPASSWD
1840 Pass a pointer to a zero terminated string as parameter. It will
1841 be used as the password required to use the CURLOPT_SSLKEY or
1842 CURLOPT_SSH_PRIVATE_KEYFILE private key. You never needed a
1843 pass phrase to load a certificate but you need one to load your
1844 private key.
1845 (This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and
1847 CURLOPT_SSLCERTPASSWD up to 7.9.2)
1848 CURLOPT_SSLENGINE
1850 Pass a pointer to a zero terminated string as parameter. It will
1851 be used as the identifier for the crypto engine you want to use
1852 for your private key.
1853 If the crypto device cannot be loaded, CURLE_SSL_ENGINE_NOTFOUND
1855 is returned.
1856 CURLOPT_SSLENGINE_DEFAULT
1858 Sets the actual crypto engine as the default for (asymmetric)
1859 crypto operations.
1860 If the crypto device cannot be set, CURLE_SSL_ENGINE_SETFAILED
1862 is returned.
1863 Note that even though this option doesn't need any parameter, in
1865 some configurations curl_easy_setopt might be defined as a macro
1866 taking exactly three arguments. Therefore, it's recommended to
1867 pass 1 as parameter to this option.
1868 CURLOPT_SSLVERSION
1870 Pass a long as parameter to control what version of SSL/TLS to
1871 attempt to use. The available options are:
1872 CURL_SSLVERSION_DEFAULT
1874 The default action. This will attempt to figure out the
1875 remote SSL protocol version, i.e. either SSLv3 or TLSv1
1876 (but not SSLv2, which became disabled by default with
1877 7.18.1).
1878 CURL_SSLVERSION_TLSv1
1880 Force TLSv1.x
1881 CURL_SSLVERSION_SSLv2
1883 Force SSLv2
1884 CURL_SSLVERSION_SSLv3
1886 Force SSLv3
1887 CURL_SSLVERSION_TLSv1_0
1889 Force TLSv1.0
1890 CURL_SSLVERSION_TLSv1_1
1892 Force TLSv1.1
1893 CURL_SSLVERSION_TLSv1_2
1895 Force TLSv1.2
1896 CURLOPT_SSL_VERIFYPEER
1898 Pass a long as parameter.
1899 This option determines whether curl verifies the authenticity of
1901 the peer's certificate. A value of 1 means curl verifies; zero
1902 means it doesn't. The default is nonzero, but before 7.10, it
1903 was zero.
1904 When negotiating an SSL connection, the server sends a certifi‐
1906 cate indicating its identity. Curl verifies whether the cer‐
1907 tificate is authentic, i.e. that you can trust that the server
1908 is who the certificate says it is. This trust is based on a
1909 chain of digital signatures, rooted in certification authority
1910 (CA) certificates you supply. As of 7.10, curl installs a
1911 default bundle of CA certificates and you can specify alternate
1912 certificates with the CURLOPT_CAINFO option or the CURLOPT_CAP‐
1913 ATH option.
1914 When CURLOPT_SSL_VERIFYPEER is nonzero, and the verification
1916 fails to prove that the certificate is authentic, the connection
1917 fails. When the option is zero, the connection succeeds regard‐
1918 less.
1919 Authenticating the certificate is not by itself very useful.
1921 You typically want to ensure that the server, as authentically
1922 identified by its certificate, is the server you mean to be
1923 talking to. Use CURLOPT_SSL_VERIFYHOST to control that.
1924 CURLOPT_CAINFO
1926 Pass a char * to a zero terminated string naming a file holding
1927 one or more certificates to verify the peer with. This makes
1928 sense only when used in combination with the CURLOPT_SSL_VERI‐
1929 FYPEER option. If CURLOPT_SSL_VERIFYPEER is zero, CUR‐
1930 LOPT_CAINFO need not even indicate an accessible file.
1931 Note that option is by default set to the system path where
1933 libcurl's cacert bundle is assumed to be stored, as established
1934 at build time.
1935 If curl is built against the NSS SSL library, the NSS PEM
1937 PKCS#11 module (libnsspem.so) needs to be available for this
1938 option to work properly.
1939 CURLOPT_ISSUERCERT
1941 Pass a char * to a zero terminated string naming a file holding
1942 a CA certificate in PEM format. If the option is set, an addi‐
1943 tional check against the peer certificate is performed to verify
1944 the issuer is indeed the one associated with the certificate
1945 provided by the option. This additional check is useful in
1946 multi-level PKI where one needs to enforce that the peer cer‐
1947 tificate is from a specific branch of the tree.
1948 This option makes sense only when used in combination with the
1950 CURLOPT_SSL_VERIFYPEER option. Otherwise, the result of the
1951 check is not considered as failure.
1952 A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with
1954 the option, which is returned if the setup of the SSL/TLS ses‐
1955 sion has failed due to a mismatch with the issuer of peer cer‐
1956 tificate (CURLOPT_SSL_VERIFYPEER has to be set too for the check
1957 to fail). (Added in 7.19.0)
1958 CURLOPT_CAPATH
1960 Pass a char * to a zero terminated string naming a directory
1961 holding multiple CA certificates to verify the peer with. This
1962 makes sense only when used in combination with the CUR‐
1963 LOPT_SSL_VERIFYPEER option. If CURLOPT_SSL_VERIFYPEER is zero,
1964 CURLOPT_CAPATH need not even indicate an accessible path. The
1965 CURLOPT_CAPATH function apparently does not work in Windows due
1966 to some limitation in openssl. This option is OpenSSL-specific
1967 and does nothing if libcurl is built to use GnuTLS.
1968 CURLOPT_CRLFILE
1970 Pass a char * to a zero terminated string naming a file with the
1971 concatenation of CRL (in PEM format) to use in the certificate
1972 validation that occurs during the SSL exchange.
1973 When curl is built to use NSS or GnuTLS, there is no way to
1975 influence the use of CRL passed to help in the verification
1976 process. When libcurl is built with OpenSSL support,
1977 X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both
1978 set, requiring CRL check against all the elements of the cer‐
1979 tificate chain if a CRL file is passed.
1980 This option makes sense only when used in combination with the
1982 CURLOPT_SSL_VERIFYPEER option.
1983 A specific error code (CURLE_SSL_CRL_BADFILE) is defined with
1985 the option. It is returned when the SSL exchange fails because
1986 the CRL file cannot be loaded. Note that a failure in certifi‐
1987 cate verification due to a revocation information found in the
1988 CRL does not trigger this specific error. (Added in 7.19.0)
1989 CURLOPT_CERTINFO
1991 Pass a long set to 1 to enable libcurl's certificate chain info
1992 gatherer. With this enabled, libcurl (if built with OpenSSL)
1993 will extract lots of information and data about the certificates
1994 in the certificate chain used in the SSL connection. This data
1995 is then possible to extract after a transfer using
1996 curl_easy_getinfo(3) and its option CURLINFO_CERTINFO. (Added in
1997 7.19.1)
1998 CURLOPT_RANDOM_FILE
2000 Pass a char * to a zero terminated file name. The file will be
2001 used to read from to seed the random engine for SSL. The more
2002 random the specified file is, the more secure the SSL connection
2003 will become.
2004 CURLOPT_EGDSOCKET
2006 Pass a char * to the zero terminated path name to the Entropy
2007 Gathering Daemon socket. It will be used to seed the random
2008 engine for SSL.
2009 CURLOPT_SSL_VERIFYHOST
2011 Pass a long as parameter.
2012 This option determines whether libcurl verifies that the server
2014 cert is for the server it is known as.
2015 When negotiating a SSL connection, the server sends a certifi‐
2017 cate indicating its identity.
2018 When CURLOPT_SSL_VERIFYHOST is 2, that certificate must indicate
2020 that the server is the server to which you meant to connect, or
2021 the connection fails.
2022 Curl considers the server the intended one when the Common Name
2024 field or a Subject Alternate Name field in the certificate
2025 matches the host name in the URL to which you told Curl to con‐
2026 nect.
2027 When the value is 1, the certificate must contain a Common Name
2029 field, but it doesn't matter what name it says. (This is not
2030 ordinarily a useful setting).
2031 When the value is 0, the connection succeeds regardless of the
2033 names in the certificate.
2034 The default, since 7.10, is 2.
2036 This makes sense only when used in combination with the CUR‐
2038 LOPT_SSL_VERIFYPEER option. If CURLOPT_SSL_VERIFYPEER is zero,
2039 CURLOPT_SSL_VERIFYHOST is ignored.
2040 CURLOPT_SSL_CIPHER_LIST
2042 Pass a char *, pointing to a zero terminated string holding the
2043 list of ciphers to use for the SSL connection. The list must be
2044 syntactically correct, it consists of one or more cipher strings
2045 separated by colons. Commas or spaces are also acceptable sepa‐
2046 rators but colons are normally used, !, - and + can be used as
2047 operators.
2048 For OpenSSL and GnuTLS valid examples of cipher lists include
2050 'RC4-SHA', ´SHA1+DES´, 'TLSv1' and 'DEFAULT'. The default list
2051 is normally set when you compile OpenSSL.
2052 You'll find more details about cipher lists on this URL:
2054 http://www.openssl.org/docs/apps/ciphers.html
2055 For NSS, valid examples of cipher lists include
2057 'rsa_rc4_128_md5', ´rsa_aes_128_sha´, etc. With NSS you don't
2058 add/remove ciphers. If one uses this option then all known
2059 ciphers are disabled and only those passed in are enabled.
2060 You'll find more details about the NSS cipher lists on this URL:
2062 http://git.fedora‐
2063 hosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives
2064 CURLOPT_SSL_SESSIONID_CACHE
2067 Pass a long set to 0 to disable libcurl's use of SSL session-ID
2068 caching. Set this to 1 to enable it. By default all transfers
2069 are done using the cache. Note that while nothing ever should
2070 get hurt by attempting to reuse SSL session-IDs, there seem to
2071 be broken SSL implementations in the wild that may require you
2072 to disable this in order for you to succeed. (Added in 7.16.0)
2073 CURLOPT_KRBLEVEL
2075 Pass a char * as parameter. Set the kerberos security level for
2076 FTP; this also enables kerberos awareness. This is a string,
2077 'clear', 'safe', 'confidential' or 'private'. If the string is
2078 set but doesn't match one of these, 'private' will be used. Set
2079 the string to NULL to disable kerberos support for FTP.
2080 (This option was known as CURLOPT_KRB4LEVEL up to 7.16.3)
2082 CURLOPT_GSSAPI_DELEGATION
2084 Set the parameter to CURLGSSAPI_DELEGATION_FLAG to allow uncon‐
2085 ditional GSSAPI credential delegation. The delegation is dis‐
2086 abled by default since 7.21.7. Set the parameter to CURLGSS‐
2087 API_DELEGATION_POLICY_FLAG to delegate only if the OK-AS-DELE‐
2088 GATE flag is set in the service ticket in case this feature is
2089 supported by the GSSAPI implementation and the definition of
2090 GSS_C_DELEG_POLICY_FLAG was available at compile-time. (Added
2091 in 7.21.8)
2092
2094 CURLOPT_SSH_AUTH_TYPES
2095 Pass a long set to a bitmask consisting of one or more of
2096 CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD,
2097 CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY
2098 to let libcurl pick one. (Added in 7.16.1)
2099 CURLOPT_SSH_HOST_PUBLIC_KEY_MD5
2101 Pass a char * pointing to a string containing 32 hexadecimal
2102 digits. The string should be the 128 bit MD5 checksum of the
2103 remote host's public key, and libcurl will reject the connection
2104 to the host unless the md5sums match. This option is only for
2105 SCP and SFTP transfers. (Added in 7.17.1)
2106 CURLOPT_SSH_PUBLIC_KEYFILE
2108 Pass a char * pointing to a file name for your public key. If
2109 not used, libcurl defaults to using ~/.ssh/id_dsa.pub. (Added
2110 in 7.16.1) If NULL (or an empty string) is passed, libcurl will
2111 pass no public key to libssh2, which then tries to compute it
2112 from the private key. This is known to work with libssh2 1.4.0+
2113 linked against OpenSSL. (Added in 7.26.0)
2114 CURLOPT_SSH_PRIVATE_KEYFILE
2116 Pass a char * pointing to a file name for your private key. If
2117 not used, libcurl defaults to using ~/.ssh/id_dsa. If the file
2118 is password-protected, set the password with CURLOPT_KEYPASSWD.
2119 (Added in 7.16.1)
2120 CURLOPT_SSH_KNOWNHOSTS
2122 Pass a pointer to a zero terminated string holding the file name
2123 of the known_host file to use. The known_hosts file should use
2124 the OpenSSH file format as supported by libssh2. If this file is
2125 specified, libcurl will only accept connections with hosts that
2126 are known and present in that file, with a matching public key.
2127 Use CURLOPT_SSH_KEYFUNCTION to alter the default behavior on
2128 host and key (mis)matching. (Added in 7.19.6)
2129 CURLOPT_SSH_KEYFUNCTION
2131 Pass a pointer to a curl_sshkeycallback function. It gets called
2132 when the known_host matching has been done, to allow the appli‐
2133 cation to act and decide for libcurl how to proceed. It gets
2134 passed the CURL handle, the key from the known_hosts file, the
2135 key from the remote site, info from libcurl on the matching sta‐
2136 tus and a custom pointer (set with CURLOPT_SSH_KEYDATA). It MUST
2137 return one of the following return codes to tell libcurl how to
2138 act:
2139 CURLKHSTAT_FINE_ADD_TO_FILE
2141 The host+key is accepted and libcurl will append it to
2142 the known_hosts file before continuing with the connec‐
2143 tion. This will also add the host+key combo to the
2144 known_host pool kept in memory if it wasn't already
2145 present there. Note that the adding of data to the file
2146 is done by completely replacing the file with a new copy,
2147 so the permissions of the file must allow this.
2148 CURLKHSTAT_FINE
2150 The host+key is accepted libcurl will continue with the
2151 connection. This will also add the host+key combo to the
2152 known_host pool kept in memory if it wasn't already
2153 present there.
2154 CURLKHSTAT_REJECT
2156 The host+key is rejected. libcurl will deny the connec‐
2157 tion to continue and it will be closed.
2158 CURLKHSTAT_DEFER
2160 The host+key is rejected, but the SSH connection is asked
2161 to be kept alive. This feature could be used when the
2162 app wants to somehow return back and act on the host+key
2163 situation and then retry without needing the overhead of
2164 setting it up from scratch again.
2165 (Added in 7.19.6)
2166 CURLOPT_SSH_KEYDATA
2168 Pass a void * as parameter. This pointer will be passed along
2169 verbatim to the callback set with CURLOPT_SSH_KEYFUNCTION.
2170 (Added in 7.19.6)
2171
2173 CURLOPT_PRIVATE
2174 Pass a void * as parameter, pointing to data that should be
2175 associated with this curl handle. The pointer can subsequently
2176 be retrieved using curl_easy_getinfo(3) with the CURLINFO_PRI‐
2177 VATE option. libcurl itself does nothing with this data. (Added
2178 in 7.10.3)
2179 CURLOPT_SHARE
2181 Pass a share handle as a parameter. The share handle must have
2182 been created by a previous call to curl_share_init(3). Setting
2183 this option, will make this curl handle use the data from the
2184 shared handle instead of keeping the data to itself. This
2185 enables several curl handles to share data. If the curl handles
2186 are used simultaneously in multiple threads, you MUST use the
2187 locking methods in the share handle. See curl_share_setopt(3)
2188 for details.
2189 If you add a share that is set to share cookies, your easy han‐
2191 dle will use that cookie cache and get the cookie engine
2192 enabled. If you unshare an object that was using cookies (or
2193 change to another object that doesn't share cookies), the easy
2194 handle will get its cookie engine disabled.
2195 Data that the share object is not set to share will be dealt
2197 with the usual way, as if no share was used.
2198 CURLOPT_NEW_FILE_PERMS
2200 Pass a long as a parameter, containing the value of the permis‐
2201 sions that will be assigned to newly created files on the remote
2202 server. The default value is 0644, but any valid value can be
2203 used. The only protocols that can use this are sftp://, scp://,
2204 and file://. (Added in 7.16.4)
2205 CURLOPT_NEW_DIRECTORY_PERMS
2207 Pass a long as a parameter, containing the value of the permis‐
2208 sions that will be assigned to newly created directories on the
2209 remote server. The default value is 0755, but any valid value
2210 can be used. The only protocols that can use this are sftp://,
2211 scp://, and file://. (Added in 7.16.4)
2212
2214 CURLOPT_TELNETOPTIONS
2215 Provide a pointer to a curl_slist with variables to pass to the
2216 telnet negotiations. The variables should be in the format
2217 <option=value>. libcurl supports the options 'TTYPE', 'XDISPLOC'
2218 and 'NEW_ENV'. See the TELNET standard for details.
2219
2221 CURLE_OK (zero) means that the option was set properly, non-zero means
2222 an error occurred as <curl/curl.h> defines. See the libcurl-errors(3)
2223 man page for the full list with descriptions.
2224 If you try to set an option that libcurl doesn't know about, perhaps
2226 because the library is too old to support it or the option was removed
2227 in a recent version, this function will return CURLE_FAILED_INIT.
2228
2230 curl_easy_init(3), curl_easy_cleanup(3), curl_easy_reset(3)
2231libcurl 7.19.3 11 Dec 2008 curl_easy_setopt(3)