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 Before version 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 Custom headers are sent in all requests done by the easy han‐
59 dles, which implies that if you tell libcurl to follow redirects
60 (CURLOPT_FOLLOWLOCATION(3)), the same set of custom headers will
61 be sent in the subsequent request. Redirects can of course go to
62 other hosts and thus those servers will get all the contents of
63 your custom headers too.
64 Starting in 7.58.0, libcurl will specifically prevent "Autho‐
66 rization:" headers from being sent to other hosts than the first
67 used one, unless specifically permitted with the CURLOPT_UNRE‐
68 STRICTED_AUTH(3) option.
69 CURLOPT_NOPROGRESS
71 Pass a long. If set to 1, it tells the library to shut off the
72 progress meter completely. It will also prevent the CURLOPT_PRO‐
73 GRESSFUNCTION from getting called.
74 Future versions of libcurl are likely to not have any built-in
76 progress meter at all.
77 CURLOPT_NOSIGNAL
79 Pass a long. If it is 1, libcurl will not use any functions that
80 install signal handlers or any functions that cause signals to
81 be sent to the process. This option is mainly here to allow
82 multi-threaded unix applications to still set/use all timeout
83 options etc, without risking getting signals. (Added in 7.10)
84 If this option is set and libcurl has been built with the stan‐
86 dard name resolver, timeouts will not occur while the name
87 resolve takes place. Consider building libcurl with c-ares sup‐
88 port to enable asynchronous DNS lookups, which enables nice
89 timeouts for name resolves without signals.
90 Setting CURLOPT_NOSIGNAL to 1 makes libcurl NOT ask the system
92 to ignore SIGPIPE signals, which otherwise are sent by the sys‐
93 tem when trying to send data to a socket which is closed in the
94 other end. libcurl makes an effort to never cause such SIGPIPEs
95 to trigger, but some operating systems have no way to avoid them
96 and even on those that have there are some corner cases when
97 they may still happen, contrary to our desire. In addition,
98 using CURLAUTH_NTLM_WB authentication could cause a SIGCHLD sig‐
99 nal to be raised.
100 CURLOPT_WILDCARDMATCH
102 Set this option to 1 if you want to transfer multiple files
103 according to a file name pattern. The pattern can be specified
104 as part of the CURLOPT_URL option, using an fnmatch-like pattern
105 (Shell Pattern Matching) in the last part of URL (file name).
106 By default, libcurl uses its internal wildcard matching imple‐
108 mentation. You can provide your own matching function by the
109 CURLOPT_FNMATCH_FUNCTION option.
110 This feature is only supported by the FTP download for now.
112 A brief introduction of its syntax follows:
114 * - ASTERISK
116 ftp://example.com/some/path/*.txt (for all txt's from the
117 root directory)
118 ? - QUESTION MARK
120 Question mark matches any (exactly one) character.
121 ftp://example.com/some/path/photo?.jpeg
123 [ - BRACKET EXPRESSION
125 The left bracket opens a bracket expression. The question
126 mark and asterisk have no special meaning in a bracket
127 expression. Each bracket expression ends by the right
128 bracket and matches exactly one character. Some examples
129 follow:
130 [a-zA-Z0-9] or [f-gF-G] - character interval
132 [abc] - character enumeration
134 [^abc] or [!abc] - negation
136 [[:name:]] class expression. Supported classes are
138 alnum,lower, space, alpha, digit, print, upper, blank,
139 graph, xdigit.
140 [][-!^] - special case - matches only '-', ']', '[', '!'
142 or '^'. These characters have no special purpose.
143 [\[\]\\] - escape syntax. Matches '[', ']' or '\'.
145 Using the rules above, a file name pattern can be con‐
147 structed:
148 ftp://example.com/some/path/[a-z[:upper:]\\].jpeg
150 (This was added in 7.21.0)
152
154 CURLOPT_WRITEFUNCTION
155 Pass a pointer to a function that matches the following proto‐
156 type: size_t function( char *ptr, size_t size, size_t nmemb,
157 void *userdata); This function gets called by libcurl as soon as
158 there is data received that needs to be saved. The size of the
159 data pointed to by ptr is size multiplied with nmemb, it will
160 not be zero terminated. Return the number of bytes actually
161 taken care of. If that amount differs from the amount passed to
162 your function, it'll signal an error to the library. This will
163 abort the transfer and return CURLE_WRITE_ERROR.
164 From 7.18.0, the function can return CURL_WRITEFUNC_PAUSE which
166 then will cause writing to this connection to become paused. See
167 curl_easy_pause(3) for further details.
168 This function may be called with zero bytes data if the trans‐
170 ferred file is empty.
171 Set this option to NULL to get the internal default function.
173 The internal default function will write the data to the FILE *
174 given with CURLOPT_WRITEDATA.
175 Set the userdata argument with the CURLOPT_WRITEDATA option.
177 The callback function will be passed as much data as possible in
179 all invokes, but you cannot possibly make any assumptions. It
180 may be one byte, it may be thousands. The maximum amount of body
181 data that can be passed to the write callback is defined in the
182 curl.h header file: CURL_MAX_WRITE_SIZE (the usual default is
183 16K). If you however have CURLOPT_HEADER set, which sends header
184 data to the write callback, you can get up to
185 CURL_MAX_HTTP_HEADER bytes of header data passed into it. This
186 usually means 100K.
187 CURLOPT_WRITEDATA
189 Data pointer to pass to the file write function. If you use the
190 CURLOPT_WRITEFUNCTION option, this is the pointer you'll get as
191 input. If you don't use a callback, you must pass a 'FILE *' as
192 libcurl will pass this to fwrite() when writing data.
193 The internal CURLOPT_WRITEFUNCTION will write the data to the
195 FILE * given with this option, or to stdout if this option
196 hasn't been set.
197 If you're using libcurl as a win32 DLL, you MUST use the CUR‐
199 LOPT_WRITEFUNCTION if you set this option or you will experience
200 crashes.
201 This option is also known with the older name CURLOPT_FILE, the
203 name CURLOPT_WRITEDATA was introduced in 7.9.7.
204 CURLOPT_READFUNCTION
206 Pass a pointer to a function that matches the following proto‐
207 type: size_t function( void *ptr, size_t size, size_t nmemb,
208 void *userdata); This function gets called by libcurl as soon as
209 it needs to read data in order to send it to the peer. The data
210 area pointed at by the pointer ptr may be filled with at most
211 size multiplied with nmemb number of bytes. Your function must
212 return the actual number of bytes that you stored in that memory
213 area. Returning 0 will signal end-of-file to the library and
214 cause it to stop the current transfer.
215 If you stop the current transfer by returning 0 "pre-maturely"
217 (i.e before the server expected it, like when you've said you
218 will upload N bytes and you upload less than N bytes), you may
219 experience that the server "hangs" waiting for the rest of the
220 data that won't come.
221 The read callback may return CURL_READFUNC_ABORT to stop the
223 current operation immediately, resulting in a
224 CURLE_ABORTED_BY_CALLBACK error code from the transfer (Added in
225 7.12.1)
226 From 7.18.0, the function can return CURL_READFUNC_PAUSE which
228 then will cause reading from this connection to become paused.
229 See curl_easy_pause(3) for further details.
230 Bugs: when doing TFTP uploads, you must return the exact amount
232 of data that the callback wants, or it will be considered the
233 final packet by the server end and the transfer will end there.
234 If you set this callback pointer to NULL, or don't set it at
236 all, the default internal read function will be used. It is
237 doing an fread() on the FILE * userdata set with CURLOPT_READ‐
238 DATA.
239 CURLOPT_READDATA
241 Data pointer to pass to the file read function. If you use the
242 CURLOPT_READFUNCTION option, this is the pointer you'll get as
243 input. If you don't specify a read callback but instead rely on
244 the default internal read function, this data must be a valid
245 readable FILE *.
246 If you're using libcurl as a win32 DLL, you MUST use a CUR‐
248 LOPT_READFUNCTION if you set this option.
249 This option was also known by the older name CURLOPT_INFILE, the
251 name CURLOPT_READDATA was introduced in 7.9.7.
252 CURLOPT_IOCTLFUNCTION
254 Pass a pointer to a function that matches the following proto‐
255 type: curlioerr function(CURL *handle, int cmd, void *clientp);.
256 This function gets called by libcurl when something special I/O-
257 related needs to be done that the library can't do by itself.
258 For now, rewinding the read data stream is the only action it
259 can request. The rewinding of the read data stream may be neces‐
260 sary when doing a HTTP PUT or POST with a multi-pass authentica‐
261 tion method. (Option added in 7.12.3).
262 Use CURLOPT_SEEKFUNCTION instead to provide seeking!
264 CURLOPT_IOCTLDATA
266 Pass a pointer that will be untouched by libcurl and passed as
267 the 3rd argument in the ioctl callback set with CURLOPT_IOCTL‐
268 FUNCTION. (Option added in 7.12.3)
269 CURLOPT_SEEKFUNCTION
271 Pass a pointer to a function that matches the following proto‐
272 type: int function(void *instream, curl_off_t offset, int ori‐
273 gin); This function gets called by libcurl to seek to a certain
274 position in the input stream and can be used to fast forward a
275 file in a resumed upload (instead of reading all uploaded bytes
276 with the normal read function/callback). It is also called to
277 rewind a stream when doing a HTTP PUT or POST with a multi-pass
278 authentication method. The function shall work like "fseek" or
279 "lseek" and accepted SEEK_SET, SEEK_CUR and SEEK_END as argument
280 for origin, although (in 7.18.0) libcurl only passes SEEK_SET.
281 The callback must return 0 (CURL_SEEKFUNC_OK) on success, 1
282 (CURL_SEEKFUNC_FAIL) to cause the upload operation to fail or 2
283 (CURL_SEEKFUNC_CANTSEEK) to indicate that while the seek failed,
284 libcurl is free to work around the problem if possible. The lat‐
285 ter can sometimes be done by instead reading from the input or
286 similar.
287 If you forward the input arguments directly to "fseek" or
289 "lseek", note that the data type for offset is not the same as
290 defined for curl_off_t on many systems! (Option added in 7.18.0)
291 CURLOPT_SEEKDATA
293 Data pointer to pass to the file seek function. If you use the
294 CURLOPT_SEEKFUNCTION option, this is the pointer you'll get as
295 input. If you don't specify a seek callback, NULL is passed.
296 (Option added in 7.18.0)
297 CURLOPT_SOCKOPTFUNCTION
299 Pass a pointer to a function that matches the following proto‐
300 type: int function(void *clientp, curl_socket_t curlfd, curl‐
301 socktype purpose);. This function gets called by libcurl after
302 the socket() call but before the connect() call. The callback's
303 purpose argument identifies the exact purpose for this particu‐
304 lar socket:
305 CURLSOCKTYPE_IPCXN for actively created connections or since
307 7.28.0 CURLSOCKTYPE_ACCEPT for FTP when the connection was setup
308 with PORT/EPSV (in earlier versions these sockets weren't passed
309 to this callback).
310 Future versions of libcurl may support more purposes. It passes
312 the newly created socket descriptor so additional setsockopt()
313 calls can be done at the user's discretion. Return 0 (zero)
314 from the callback on success. Return 1 from the callback func‐
315 tion to signal an unrecoverable error to the library and it will
316 close the socket and return CURLE_COULDNT_CONNECT. (Option
317 added in 7.16.0)
318 Added in 7.21.5, the callback function may return CURL_SOCK‐
320 OPT_ALREADY_CONNECTED, which tells libcurl that the socket is in
321 fact already connected and then libcurl will not attempt to con‐
322 nect it.
323 CURLOPT_SOCKOPTDATA
325 Pass a pointer that will be untouched by libcurl and passed as
326 the first argument in the sockopt callback set with CUR‐
327 LOPT_SOCKOPTFUNCTION. (Option added in 7.16.0)
328 CURLOPT_OPENSOCKETFUNCTION
330 Pass a pointer to a function that matches the following proto‐
331 type: curl_socket_t function(void *clientp, curlsocktype pur‐
332 pose, struct curl_sockaddr *address);. This function gets called
333 by libcurl instead of the socket(2) call. The callback's purpose
334 argument identifies the exact purpose for this particular
335 socket: CURLSOCKTYPE_IPCXN is for IP based connections. Future
336 versions of libcurl may support more purposes. It passes the
337 resolved peer address as a address argument so the callback can
338 modify the address or refuse to connect at all. The callback
339 function should return the socket or CURL_SOCKET_BAD in case no
340 connection could be established or another error was detected.
341 Any additional setsockopt(2) calls can be done on the socket at
342 the user's discretion. CURL_SOCKET_BAD return value from the
343 callback function will signal an unrecoverable error to the
344 library and it will return CURLE_COULDNT_CONNECT. This return
345 code can be used for IP address blacklisting. The default
346 behavior is:
347 return socket(addr->family, addr->socktype, addr->protocol);
348 (Option added in 7.17.1.)
349 CURLOPT_OPENSOCKETDATA
351 Pass a pointer that will be untouched by libcurl and passed as
352 the first argument in the opensocket callback set with CUR‐
353 LOPT_OPENSOCKETFUNCTION. (Option added in 7.17.1.)
354 CURLOPT_CLOSESOCKETFUNCTION
356 Pass a pointer to a function that matches the following proto‐
357 type: int function(void *clientp, curl_socket_t item);. This
358 function gets called by libcurl instead of the close(3) or clos‐
359 esocket(3) call when sockets are closed (not for any other file
360 descriptors). This is pretty much the reverse to the CUR‐
361 LOPT_OPENSOCKETFUNCTION option. Return 0 to signal success and 1
362 if there was an error. (Option added in 7.21.7)
363 CURLOPT_CLOSESOCKETDATA
365 Pass a pointer that will be untouched by libcurl and passed as
366 the first argument in the closesocket callback set with CUR‐
367 LOPT_CLOSESOCKETFUNCTION. (Option added in 7.21.7)
368 CURLOPT_PROGRESSFUNCTION
370 Pass a pointer to a function that matches the following proto‐
371 type: int function(void *clientp, double dltotal, double dlnow,
372 double ultotal, double ulnow); . This function gets called by
373 libcurl instead of its internal equivalent with a frequent
374 interval during operation (roughly once per second or sooner) no
375 matter if data is being transferred or not. Unknown/unused
376 argument values passed to the callback will be set to zero (like
377 if you only download data, the upload size will remain 0).
378 Returning a non-zero value from this callback will cause libcurl
379 to abort the transfer and return CURLE_ABORTED_BY_CALLBACK.
380 If you transfer data with the multi interface, this function
382 will not be called during periods of idleness unless you call
383 the appropriate libcurl function that performs transfers.
384 CURLOPT_NOPROGRESS must be set to 0 to make this function actu‐
386 ally get called.
387 CURLOPT_PROGRESSDATA
389 Pass a pointer that will be untouched by libcurl and passed as
390 the first argument in the progress callback set with CUR‐
391 LOPT_PROGRESSFUNCTION.
392 CURLOPT_HEADERFUNCTION
394 Pass a pointer to a function that matches the following proto‐
395 type: size_t function( void *ptr, size_t size, size_t nmemb,
396 void *userdata);. This function gets called by libcurl as soon
397 as it has received header data. The header callback will be
398 called once for each header and only complete header lines are
399 passed on to the callback. Parsing headers is very easy using
400 this. The size of the data pointed to by ptr is size multiplied
401 with nmemb. Do not assume that the header line is zero termi‐
402 nated! The pointer named userdata is the one you set with the
403 CURLOPT_WRITEHEADER option. The callback function must return
404 the number of bytes actually taken care of. If that amount dif‐
405 fers from the amount passed to your function, it'll signal an
406 error to the library. This will abort the transfer and return
407 CURL_WRITE_ERROR.
408 A complete HTTP header that is passed to this function can be up
410 to CURL_MAX_HTTP_HEADER (100K) bytes.
411 If this option is not set, or if it is set to NULL, but CUR‐
413 LOPT_HEADERDATA (CURLOPT_WRITEHEADER) is set to anything but
414 NULL, the function used to accept response data will be used
415 instead. That is, it will be the function specified with CUR‐
416 LOPT_WRITEFUNCTION, or if it is not specified or NULL - the
417 default, stream-writing function.
418 It's important to note that the callback will be invoked for the
420 headers of all responses received after initiating a request and
421 not just the final response. This includes all responses which
422 occur during authentication negotiation. If you need to operate
423 on only the headers from the final response, you will need to
424 collect headers in the callback yourself and use HTTP status
425 lines, for example, to delimit response boundaries.
426 When a server sends a chunked encoded transfer, it may contain a
428 trailer. That trailer is identical to a HTTP header and if such
429 a trailer is received it is passed to the application using this
430 callback as well. There are several ways to detect it being a
431 trailer and not an ordinary header: 1) it comes after the
432 response-body. 2) it comes after the final header line (CR LF)
433 3) a Trailer: header among the regular response-headers mention
434 what header(s) to expect in the trailer.
435 For non-HTTP protocols like FTP, POP3, IMAP and SMTP this func‐
437 tion will get called with the server responses to the commands
438 that libcurl sends.
439 CURLOPT_WRITEHEADER
441 (This option is also known as CURLOPT_HEADERDATA) Pass a pointer
442 to be used to write the header part of the received data to. If
443 you don't use CURLOPT_WRITEFUNCTION or CURLOPT_HEADERFUNCTION to
444 take care of the writing, this must be a valid FILE * as the
445 internal default will then be a plain fwrite(). See also the
446 CURLOPT_HEADERFUNCTION option above on how to set a custom get-
447 all-headers callback.
448 CURLOPT_DEBUGFUNCTION
450 Pass a pointer to a function that matches the following proto‐
451 type: int curl_debug_callback (CURL *, curl_infotype, char *,
452 size_t, void *); CURLOPT_DEBUGFUNCTION replaces the standard
453 debug function used when CURLOPT_VERBOSE is in effect. This
454 callback receives debug information, as specified with the
455 curl_infotype argument. This function must return 0. The data
456 pointed to by the char * passed to this function WILL NOT be
457 zero terminated, but will be exactly of the size as told by the
458 size_t argument.
459 Available curl_infotype values:
461 CURLINFO_TEXT
463 The data is informational text.
464 CURLINFO_HEADER_IN
466 The data is header (or header-like) data received from
467 the peer.
468 CURLINFO_HEADER_OUT
470 The data is header (or header-like) data sent to the
471 peer.
472 CURLINFO_DATA_IN
474 The data is protocol data received from the peer.
475 CURLINFO_DATA_OUT
477 The data is protocol data sent to the peer.
478 CURLOPT_DEBUGDATA
480 Pass a pointer to whatever you want passed in to your CUR‐
481 LOPT_DEBUGFUNCTION in the last void * argument. This pointer is
482 not used by libcurl, it is only passed to the callback.
483 CURLOPT_SSL_CTX_FUNCTION
485 This option does only function for libcurl powered by OpenSSL.
486 If libcurl was built against another SSL library, this function‐
487 ality is absent.
488 Pass a pointer to a function that matches the following proto‐
490 type: CURLcode sslctxfun(CURL *curl, void *sslctx, void *parm);
491 This function gets called by libcurl just before the initializa‐
492 tion of a SSL connection after having processed all other SSL
493 related options to give a last chance to an application to mod‐
494 ify the behaviour of openssl's ssl initialization. The sslctx
495 parameter is actually a pointer to an openssl SSL_CTX. If an
496 error is returned no attempt to establish a connection is made
497 and the perform operation will return the error code from this
498 callback function. Set the parm argument with the CUR‐
499 LOPT_SSL_CTX_DATA option. This option was introduced in 7.11.0.
500 This function will get called on all new connections made to a
502 server, during the SSL negotiation. The SSL_CTX pointer will be
503 a new one every time.
504 To use this properly, a non-trivial amount of knowledge of the
506 openssl libraries is necessary. For example, using this function
507 allows you to use openssl callbacks to add additional validation
508 code for certificates, and even to change the actual URI of a
509 HTTPS request (example used in the lib509 test case). See also
510 the example section for a replacement of the key, certificate
511 and trust file settings.
512 CURLOPT_SSL_CTX_DATA
514 Data pointer to pass to the ssl context callback set by the
515 option CURLOPT_SSL_CTX_FUNCTION, this is the pointer you'll get
516 as third parameter, otherwise NULL. (Added in 7.11.0)
517 CURLOPT_CONV_TO_NETWORK_FUNCTION
519 CURLOPT_CONV_FROM_NETWORK_FUNCTION
521 CURLOPT_CONV_FROM_UTF8_FUNCTION
523 Pass a pointer to a function that matches the following proto‐
524 type: CURLcode function(char *ptr, size_t length);
525 These three options apply to non-ASCII platforms only. They are
527 available only if CURL_DOES_CONVERSIONS was defined when libcurl
528 was built. When this is the case, curl_version_info(3) will
529 return the CURL_VERSION_CONV feature bit set.
530 The data to be converted is in a buffer pointed to by the ptr
532 parameter. The amount of data to convert is indicated by the
533 length parameter. The converted data overlays the input data in
534 the buffer pointed to by the ptr parameter. CURLE_OK should be
535 returned upon successful conversion. A CURLcode return value
536 defined by curl.h, such as CURLE_CONV_FAILED, should be returned
537 if an error was encountered.
538 CURLOPT_CONV_TO_NETWORK_FUNCTION and CURLOPT_CONV_FROM_NET‐
540 WORK_FUNCTION convert between the host encoding and the network
541 encoding. They are used when commands or ASCII data are
542 sent/received over the network.
543 CURLOPT_CONV_FROM_UTF8_FUNCTION is called to convert from UTF8
545 into the host encoding. It is required only for SSL processing.
546 If you set a callback pointer to NULL, or don't set it at all,
548 the built-in libcurl iconv functions will be used. If
549 HAVE_ICONV was not defined when libcurl was built, and no call‐
550 back has been established, conversion will return the
551 CURLE_CONV_REQD error code.
552 If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also
554 be defined. For example:
555 #define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
557 The iconv code in libcurl will default the network and UTF8
559 codeset names as follows:
560 #define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
562 #define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
564 You will need to override these definitions if they are differ‐
566 ent on your system.
567 CURLOPT_INTERLEAVEFUNCTION
569 Pass a pointer to a function that matches the following proto‐
570 type: size_t function( void *ptr, size_t size, size_t nmemb,
571 void *userdata). This function gets called by libcurl as soon as
572 it has received interleaved RTP data. This function gets called
573 for each $ block and therefore contains exactly one upper-layer
574 protocol unit (e.g. one RTP packet). Curl writes the inter‐
575 leaved header as well as the included data for each call. The
576 first byte is always an ASCII dollar sign. The dollar sign is
577 followed by a one byte channel identifier and then a 2 byte
578 integer length in network byte order. See RFC2326 Section 10.12
579 for more information on how RTP interleaving behaves. If unset
580 or set to NULL, curl will use the default write function.
581 Interleaved RTP poses some challenges for the client applica‐
583 tion. Since the stream data is sharing the RTSP control connec‐
584 tion, it is critical to service the RTP in a timely fashion. If
585 the RTP data is not handled quickly, subsequent response pro‐
586 cessing may become unreasonably delayed and the connection may
587 close. The application may use CURL_RTSPREQ_RECEIVE to service
588 RTP data when no requests are desired. If the application makes
589 a request, (e.g. CURL_RTSPREQ_PAUSE) then the response handler
590 will process any pending RTP data before marking the request as
591 finished. (Added in 7.20.0)
592 CURLOPT_INTERLEAVEDATA
594 This is the userdata pointer that will be passed to CUR‐
595 LOPT_INTERLEAVEFUNCTION when interleaved RTP data is received.
596 (Added in 7.20.0)
597 CURLOPT_CHUNK_BGN_FUNCTION
599 Pass a pointer to a function that matches the following proto‐
600 type: long function (const void *transfer_info, void *ptr, int
601 remains). This function gets called by libcurl before a part of
602 the stream is going to be transferred (if the transfer supports
603 chunks).
604 This callback makes sense only when using the CURLOPT_WILDCARD‐
606 MATCH option for now.
607 The target of transfer_info parameter is a "feature depended"
609 structure. For the FTP wildcard download, the target is
610 curl_fileinfo structure (see curl/curl.h). The parameter ptr is
611 a pointer given by CURLOPT_CHUNK_DATA. The parameter remains
612 contains number of chunks remaining per the transfer. If the
613 feature is not available, the parameter has zero value.
614 Return CURL_CHUNK_BGN_FUNC_OK if everything is fine,
616 CURL_CHUNK_BGN_FUNC_SKIP if you want to skip the concrete chunk
617 or CURL_CHUNK_BGN_FUNC_FAIL to tell libcurl to stop if some
618 error occurred. (This was added in 7.21.0)
619 CURLOPT_CHUNK_END_FUNCTION
621 Pass a pointer to a function that matches the following proto‐
622 type: long function(void *ptr). This function gets called by
623 libcurl as soon as a part of the stream has been transferred (or
624 skipped).
625 Return CURL_CHUNK_END_FUNC_OK if everything is fine or
627 CURL_CHUNK_END_FUNC_FAIL to tell the lib to stop if some error
628 occurred. (This was added in 7.21.0)
629 CURLOPT_CHUNK_DATA
631 Pass a pointer that will be untouched by libcurl and passed as
632 the ptr argument to the CURL_CHUNK_BGN_FUNTION and
633 CURL_CHUNK_END_FUNTION. (This was added in 7.21.0)
634 CURLOPT_FNMATCH_FUNCTION
636 Pass a pointer to a function that matches the following proto‐
637 type: int function(void *ptr, const char *pattern, const char
638 *string) prototype (see curl/curl.h). It is used internally for
639 the wildcard matching feature.
640 Return CURL_FNMATCHFUNC_MATCH if pattern matches the string,
642 CURL_FNMATCHFUNC_NOMATCH if not or CURL_FNMATCHFUNC_FAIL if an
643 error occurred. (This was added in 7.21.0)
644 CURLOPT_FNMATCH_DATA
646 Pass a pointer that will be untouched by libcurl and passed as
647 the ptr argument to the CURL_FNMATCH_FUNCTION. (This was added
648 in 7.21.0)
649
651 CURLOPT_ERRORBUFFER
652 Pass a char * to a buffer that the libcurl may store human read‐
653 able error messages in. This may be more helpful than just the
654 return code from curl_easy_perform. The buffer must be at least
655 CURL_ERROR_SIZE big. Although this argument is a 'char *', it
656 does not describe an input string. Therefore the (probably
657 undefined) contents of the buffer is NOT copied by the library.
658 You must keep the associated storage available until libcurl no
659 longer needs it. Failing to do so will cause very odd behavior
660 or even crashes. libcurl will need it until you call
661 curl_easy_cleanup(3) or you set the same option again to use a
662 different pointer.
663 Use CURLOPT_VERBOSE and CURLOPT_DEBUGFUNCTION to better
665 debug/trace why errors happen.
666 If the library does not return an error, the buffer may not have
668 been touched. Do not rely on the contents in those cases.
669 CURLOPT_STDERR
672 Pass a FILE * as parameter. Tell libcurl to use this stream
673 instead of stderr when showing the progress meter and displaying
674 CURLOPT_VERBOSE data.
675 CURLOPT_FAILONERROR
677 A parameter set to 1 tells the library to fail silently if the
678 HTTP code returned is equal to or larger than 400. The default
679 action would be to return the page normally, ignoring that code.
680 This method is not fail-safe and there are occasions where non-
682 successful response codes will slip through, especially when
683 authentication is involved (response codes 401 and 407).
684 You might get some amounts of headers transferred before this
686 situation is detected, like when a "100-continue" is received as
687 a response to a POST/PUT and a 401 or 407 is received immedi‐
688 ately afterwards.
689
691 CURLOPT_URL
692 Pass in a pointer to the actual URL to deal with. The parameter
693 should be a char * to a zero terminated string which must be
694 URL-encoded in the following format:
695 scheme://host:port/path
697 For a greater explanation of the format please see RFC3986.
699 If the given URL lacks the scheme, or protocol, part ("http://"
701 or "ftp://" etc), libcurl will attempt to resolve which protocol
702 to use based on the given host mame. If the protocol is not sup‐
703 ported, libcurl will return (CURLE_UNSUPPORTED_PROTOCOL) when
704 you call curl_easy_perform(3) or curl_multi_perform(3). Use
705 curl_version_info(3) for detailed information on which protocols
706 are supported.
707 The host part of the URL contains the address of the server that
709 you want to connect to. This can be the fully qualified domain
710 name of the server, the local network name of the machine on
711 your network or the IP address of the server or machine repre‐
712 sented by either an IPv4 or IPv6 address. For example:
713 http://www.example.com/
715 http://hostname/
717 http://192.168.0.1/
719 http://[2001:1890:1112:1::20]/
721 It is also possible to specify the user name and password as
723 part of the host, for some protocols, when connecting to servers
724 that require authentication.
725 For example the following types of authentication support this:
727 http://user:password@www.example.com
729 ftp://user:password@ftp.example.com
731 pop3://user:password@mail.example.com
733 The port is optional and when not specified libcurl will use the
735 default port based on the determined or specified protocol: 80
736 for HTTP, 21 for FTP and 25 for SMTP, etc. The following exam‐
737 ples show how to specify the port:
738 http://www.example.com:8080/ - This will connect to a web server
740 using port 8080 rather than 80.
741 smtp://mail.example.com:587/ - This will connect to a SMTP
743 server on the alternative mail port.
744 The path part of the URL is protocol specific and whilst some
746 examples are given below this list is not conclusive:
747 HTTP
749 The path part of a HTTP request specifies the file to retrieve
751 and from what directory. If the directory is not specified then
752 the web server's root directory is used. If the file is omitted
753 then the default document will be retrieved for either the
754 directory specified or the root directory. The exact resource
755 returned for each URL is entirely dependent on the server's con‐
756 figuration.
757 http://www.example.com - This gets the main page from the web
759 server.
760 http://www.example.com/index.html - This returns the main page
762 by explicitly requesting it.
763 http://www.example.com/contactus/ - This returns the default
765 document from the contactus directory.
766 FTP
768 The path part of an FTP request specifies the file to retrieve
770 and from what directory. If the file part is omitted then
771 libcurl downloads the directory listing for the directory speci‐
772 fied. If the directory is omitted then the directory listing for
773 the root / home directory will be returned.
774 ftp://ftp.example.com - This retrieves the directory listing for
776 the root directory.
777 ftp://ftp.example.com/readme.txt - This downloads the file
779 readme.txt from the root directory.
780 ftp://ftp.example.com/libcurl/readme.txt - This downloads
782 readme.txt from the libcurl directory.
783 ftp://user:password@ftp.example.com/readme.txt - This retrieves
785 the readme.txt file from the user's home directory. When a user‐
786 name and password is specified, everything that is specified in
787 the path part is relative to the user's home directory. To
788 retrieve files from the root directory or a directory underneath
789 the root directory then the absolute path must be specified by
790 prepending an additional forward slash to the beginning of the
791 path.
792 ftp://user:password@ftp.example.com//readme.txt - This retrieves
794 the readme.txt from the root directory when logging in as a
795 specified user.
796 SMTP
798 The path part of a SMTP request specifies the host name to
800 present during communication with the mail server. If the path
801 is omitted then libcurl will attempt to resolve the local com‐
802 puter's host name. However, this may not return the fully quali‐
803 fied domain name that is required by some mail servers and spec‐
804 ifying this path allows you to set an alternative name, such as
805 your machine's fully qualified domain name, which you might have
806 obtained from an external function such as gethostname or getad‐
807 drinfo.
808 smtp://mail.example.com - This connects to the mail server at
810 example.com and sends your local computer's host name in the
811 HELO / EHLO command.
812 smtp://mail.example.com/client.example.com - This will send
814 client.example.com in the HELO / EHLO command to the mail server
815 at example.com.
816 POP3
818 The path part of a POP3 request specifies the mailbox (message)
820 to retrieve. If the mailbox is not specified then a list of
821 waiting messages is returned instead.
822 pop3://user:password@mail.example.com - This lists the available
824 messages pop3://user:password@mail.example.com/1 - This
825 retrieves the first message
826 SCP
828 The path part of a SCP request specifies the file to retrieve
830 and from what directory. The file part may not be omitted. The
831 file is taken as an absolute path from the root directory on the
832 server. To specify a path relative to the user's home directory
833 on the server, prepend ~/ to the path portion. If the user name
834 is not embedded in the URL, it can be set with the CURLOPT_USER‐
835 PWD or CURLOPT_USERNAME option.
836 scp://user@example.com/etc/issue - This specifies the file
838 /etc/issue
839 scp://example.com/~/my-file - This specifies the file my-file in
841 the user's home directory on the server
842 SFTP
844 The path part of a SFTP request specifies the file to retrieve
846 and from what directory. If the file part is omitted then
847 libcurl downloads the directory listing for the directory speci‐
848 fied. If the path ends in a / then a directory listing is
849 returned instead of a file. If the path is omitted entirely
850 then the directory listing for the root / home directory will be
851 returned. If the user name is not embedded in the URL, it can
852 be set with the CURLOPT_USERPWD or CURLOPT_USERNAME option.
853 sftp://user:password@example.com/etc/issue - This specifies the
855 file /etc/issue
856 sftp://user@example.com/~/my-file - This specifies the file my-
858 file in the user's home directory
859 sftp://ssh.example.com/~/Documents/ - This requests a directory
861 listing of the Documents directory under the user's home direc‐
862 tory
863 LDAP
865 The path part of a LDAP request can be used to specify the: Dis‐
867 tinguished Name, Attributes, Scope, Filter and Extension for a
868 LDAP search. Each field is separated by a question mark and when
869 that field is not required an empty string with the question
870 mark separator should be included.
871 ldap://ldap.example.com/o=My%20Organisation - This will perform
873 a LDAP search with the DN as My Organisation.
874 ldap://ldap.example.com/o=My%20Organisation?postalAddress - This
876 will perform the same search but will only return postalAddress
877 attributes.
878 ldap://ldap.example.com/?rootDomainNamingContext - This speci‐
880 fies an empty DN and requests information about the rootDomain‐
881 NamingContext attribute for an Active Directory server.
882 For more information about the individual components of a LDAP
884 URL please see RFC4516.
885 NOTES
887 Starting with version 7.20.0, the fragment part of the URI will
889 not be sent as part of the path, which was previously the case.
890 CURLOPT_URL is the only option that must be set before
892 curl_easy_perform(3) is called.
893 CURLOPT_PROTOCOLS can be used to limit what protocols libcurl
895 will use for this transfer, independent of what libcurl has been
896 compiled to support. That may be useful if you accept the URL
897 from an external source and want to limit the accessibility.
898 CURLOPT_PROTOCOLS
900 Pass a long that holds a bitmask of CURLPROTO_* defines. If
901 used, this bitmask limits what protocols libcurl may use in the
902 transfer. This allows you to have a libcurl built to support a
903 wide range of protocols but still limit specific transfers to
904 only be allowed to use a subset of them. By default libcurl will
905 accept all protocols it supports. See also CURLOPT_REDIR_PROTO‐
906 COLS. (Added in 7.19.4)
907 CURLOPT_REDIR_PROTOCOLS
909 Pass a long that holds a bitmask of CURLPROTO_* defines. If
910 used, this bitmask limits what protocols libcurl may use in a
911 transfer that it follows to in a redirect when CURLOPT_FOLLOWLO‐
912 CATION is enabled. This allows you to limit specific transfers
913 to only be allowed to use a subset of protocols in redirections.
914 By default libcurl will allow all protocols except for FILE and
915 SCP. This is a difference compared to pre-7.19.4 versions which
916 unconditionally would follow to all protocols supported. (Added
917 in 7.19.4)
918 CURLOPT_PROXY
920 Set HTTP proxy to use. The parameter should be a char * to a
921 zero terminated string holding the host name or dotted IP
922 address. To specify port number in this string, append :[port]
923 to the end of the host name. The proxy string may be prefixed
924 with [protocol]:// since any such prefix will be ignored. The
925 proxy's port number may optionally be specified with the sepa‐
926 rate option. If not specified, libcurl will default to using
927 port 1080 for proxies. CURLOPT_PROXYPORT.
928 When you tell the library to use a HTTP proxy, libcurl will
930 transparently convert operations to HTTP even if you specify an
931 FTP URL etc. This may have an impact on what other features of
932 the library you can use, such as CURLOPT_QUOTE and similar FTP
933 specifics that don't work unless you tunnel through the HTTP
934 proxy. Such tunneling is activated with CURLOPT_HTTPPROXYTUNNEL.
935 libcurl respects the environment variables http_proxy,
937 ftp_proxy, all_proxy etc, if any of those are set. The CUR‐
938 LOPT_PROXY option does however override any possibly set envi‐
939 ronment variables.
940 Setting the proxy string to "" (an empty string) will explicitly
942 disable the use of a proxy, even if there is an environment
943 variable set for it.
944 Since 7.14.1, the proxy host string given in environment vari‐
946 ables can be specified the exact same way as the proxy can be
947 set with CURLOPT_PROXY, include protocol prefix (http://) and
948 embedded user + password.
949 Since 7.21.7, the proxy string may be specified with a proto‐
951 col:// prefix to specify alternative proxy protocols. Use
952 socks4://, socks4a://, socks5:// or socks5h:// (the last one to
953 enable socks5 and asking the proxy to do the resolving, also
954 known as CURLPROXY_SOCKS5_HOSTNAME type) to request the specific
955 SOCKS version to be used. No protocol specified, http:// and all
956 others will be treated as HTTP proxies.
957 CURLOPT_PROXYPORT
959 Pass a long with this option to set the proxy port to connect to
960 unless it is specified in the proxy string CURLOPT_PROXY.
961 CURLOPT_PROXYTYPE
963 Pass a long with this option to set type of the proxy. Available
964 options for this are CURLPROXY_HTTP, CURLPROXY_HTTP_1_0 (added
965 in 7.19.4), CURLPROXY_SOCKS4 (added in 7.10), CURLPROXY_SOCKS5,
966 CURLPROXY_SOCKS4A (added in 7.18.0) and CURLPROXY_SOCKS5_HOST‐
967 NAME (added in 7.18.0). The HTTP type is default. (Added in
968 7.10)
969 If you set CURLOPT_PROXYTYPE to CURLPROXY_HTTP_1_0, it will only
971 affect how libcurl speaks to a proxy when CONNECT is used. The
972 HTTP version used for "regular" HTTP requests is instead con‐
973 trolled with CURLOPT_HTTP_VERSION.
974 CURLOPT_NOPROXY
976 Pass a pointer to a zero terminated string. The string consists
977 of a comma separated list of host names that do not require a
978 proxy to get reached, even if one is specified. The only wild‐
979 card available is a single * character, which matches all hosts,
980 and effectively disables the proxy. Each name in this list is
981 matched as either a domain which contains the hostname, or the
982 hostname itself. For example, example.com would match exam‐
983 ple.com, example.com:80, and www.example.com, but not
984 www.notanexample.com. (Added in 7.19.4)
985 CURLOPT_HTTPPROXYTUNNEL
987 Set the parameter to 1 to make the library tunnel all operations
988 through a given HTTP proxy. There is a big difference between
989 using a proxy and to tunnel through it. If you don't know what
990 this means, you probably don't want this tunneling option.
991 CURLOPT_SOCKS5_AUTH
993 Pass a long as parameter, which is set to a bitmask, to tell
994 libcurl which authentication method(s) are allowed for SOCKS5
995 proxy authentication. The only supported flags are
996 CURLAUTH_BASIC, which allows username/password authentication,
997 CURLAUTH_GSSAPI, which allows GSS-API authentication, and
998 CURLAUTH_NONE, which allows no authentication. Set the actual
999 user name and password with the CURLOPT_PROXYUSERPWD(3) option.
1000 Defaults to CURLAUTH_BASIC|CURLAUTH_GSSAPI. (Added in 7.55.0)
1001 CURLOPT_SOCKS5_GSSAPI_SERVICE
1003 Pass a char * as parameter to a string holding the name of the
1004 service. The default service name for a SOCKS5 server is
1005 rcmd/server-fqdn. This option allows you to change it. (Added in
1006 7.19.4)
1007 CURLOPT_SOCKS5_GSSAPI_NEC
1009 Pass a long set to 1 to enable or 0 to disable. As part of the
1010 gssapi negotiation a protection mode is negotiated. The RFC1961
1011 says in section 4.3/4.4 it should be protected, but the NEC ref‐
1012 erence implementation does not. If enabled, this option allows
1013 the unprotected exchange of the protection mode negotiation.
1014 (Added in 7.19.4).
1015 CURLOPT_INTERFACE
1017 Pass a char * as parameter. This sets the interface name to use
1018 as outgoing network interface. The name can be an interface
1019 name, an IP address, or a host name.
1020 Starting with 7.24.0: If the parameter starts with "if!" then it
1022 is treated as only as interface name and no attempt will ever be
1023 named to do treat it as an IP address or to do name resolution
1024 on it. If the parameter starts with "host!" it is treated as
1025 either an IP address or a hostname. Hostnames are resolved syn‐
1026 chronously. Using the if! format is highly recommended when
1027 using the multi interfaces to avoid allowing the code to block.
1028 If "if!" is specified but the parameter does not match an exist‐
1029 ing interface, CURLE_INTERFACE_FAILED is returned.
1030 CURLOPT_LOCALPORT
1032 Pass a long. This sets the local port number of the socket used
1033 for connection. This can be used in combination with CUR‐
1034 LOPT_INTERFACE and you are recommended to use CURLOPT_LOCALPOR‐
1035 TRANGE as well when this is set. Valid port numbers are 1 -
1036 65535. (Added in 7.15.2)
1037 CURLOPT_LOCALPORTRANGE
1039 Pass a long. This is the number of attempts libcurl will make to
1040 find a working local port number. It starts with the given CUR‐
1041 LOPT_LOCALPORT and adds one to the number for each retry. Set‐
1042 ting this to 1 or below will make libcurl do only one try for
1043 the exact port number. Port numbers by nature are scarce
1044 resources that will be busy at times so setting this value to
1045 something too low might cause unnecessary connection setup fail‐
1046 ures. (Added in 7.15.2)
1047 CURLOPT_DNS_CACHE_TIMEOUT
1049 Pass a long, this sets the timeout in seconds. Name resolves
1050 will be kept in memory for this number of seconds. Set to zero
1051 to completely disable caching, or set to -1 to make the cached
1052 entries remain forever. By default, libcurl caches this info for
1053 60 seconds.
1054 The name resolve functions of various libc implementations don't
1056 re-read name server information unless explicitly told so (for
1057 example, by calling res_init(3)). This may cause libcurl to keep
1058 using the older server even if DHCP has updated the server info,
1059 and this may look like a DNS cache issue to the casual libcurl-
1060 app user.
1061 CURLOPT_DNS_USE_GLOBAL_CACHE
1063 Pass a long. If the value is 1, it tells curl to use a global
1064 DNS cache that will survive between easy handle creations and
1065 deletions. This is not thread-safe and this will use a global
1066 variable.
1067 WARNING: this option is considered obsolete. Stop using it.
1069 Switch over to using the share interface instead! See CUR‐
1070 LOPT_SHARE and curl_share_init(3).
1071 CURLOPT_BUFFERSIZE
1073 Pass a long specifying your preferred size (in bytes) for the
1074 receive buffer in libcurl. The main point of this would be that
1075 the write callback gets called more often and with smaller
1076 chunks. Secondly, for some protocols, there's a benefit of hav‐
1077 ing a larger buffer for performance. This is just treated as a
1078 request, not an order. You cannot be guaranteed to actually get
1079 the given size. This buffer size is by default
1080 CURL_MAX_WRITE_SIZE (16kB). The maximum buffer size allowed to
1081 set is CURL_MAX_READ_SIZE (512kB). (Added in 7.10)
1082 CURLOPT_PORT
1084 Pass a long specifying what remote port number to connect to,
1085 instead of the one specified in the URL or the default port for
1086 the used protocol.
1087 CURLOPT_TCP_NODELAY
1089 Pass a long specifying whether the TCP_NODELAY option is to be
1090 set or cleared (1 = set, 0 = clear). The option is cleared by
1091 default. This will have no effect after the connection has been
1092 established.
1093 Setting this option will disable TCP's Nagle algorithm. The pur‐
1095 pose of this algorithm is to try to minimize the number of small
1096 packets on the network (where "small packets" means TCP segments
1097 less than the Maximum Segment Size (MSS) for the network).
1098 Maximizing the amount of data sent per TCP segment is good
1100 because it amortizes the overhead of the send. However, in some
1101 cases (most notably telnet or rlogin) small segments may need to
1102 be sent without delay. This is less efficient than sending
1103 larger amounts of data at a time, and can contribute to conges‐
1104 tion on the network if overdone.
1105 CURLOPT_ADDRESS_SCOPE
1107 Pass a long specifying the scope_id value to use when connecting
1108 to IPv6 link-local or site-local addresses. (Added in 7.19.0)
1109 CURLOPT_TCP_KEEPALIVE
1111 Pass a long. If set to 1, TCP keepalive probes will be sent. The
1112 delay and frequency of these probes can be controlled by the
1113 CURLOPT_TCP_KEEPIDLE and CURLOPT_TCP_KEEPINTVL options, provided
1114 the operating system supports them. Set to 0 (default behavior)
1115 to disable keepalive probes (Added in 7.25.0).
1116 CURLOPT_TCP_KEEPIDLE
1118 Pass a long. Sets the delay, in seconds, that the operating sys‐
1119 tem will wait while the connection is idle before sending
1120 keepalive probes. Not all operating systems support this option.
1121 (Added in 7.25.0)
1122 CURLOPT_TCP_KEEPINTVL
1124 Pass a long. Sets the interval, in seconds, that the operating
1125 system will wait between sending keepalive probes. Not all oper‐
1126 ating systems support this option. (Added in 7.25.0)
1127 CURLOPT_UNIX_SOCKET_PATH
1129 Pass a path to a UNIX domain socket. This enables the use of
1130 UNIX domain sockets as connection end point and sets the path to
1131 path. If path is NULL, then UNIX domain sockets are disabled. An
1132 empty string will result in an error at some point.
1133 When enabled, cURL will connect to the UNIX domain socket
1135 instead of establishing a TCP connection to a host. Since no TCP
1136 connection is established, cURL does not need to resolve the DNS
1137 hostname in the URL.
1138 The maximum path length on Cygwin, Linux and Solaris is 107. On
1140 other platforms might be even less.
1141
1143 CURLOPT_NETRC
1144 This parameter controls the preference of libcurl between using
1145 user names and passwords from your ~/.netrc file, relative to
1146 user names and passwords in the URL supplied with CURLOPT_URL.
1147 libcurl uses a user name (and supplied or prompted password)
1149 supplied with CURLOPT_USERPWD in preference to any of the
1150 options controlled by this parameter.
1151 Pass a long, set to one of the values described below.
1153 CURL_NETRC_OPTIONAL
1155 The use of your ~/.netrc file is optional, and informa‐
1156 tion in the URL is to be preferred. The file will be
1157 scanned for the host and user name (to find the password
1158 only) or for the host only, to find the first user name
1159 and password after that machine, which ever information
1160 is not specified in the URL.
1161 Undefined values of the option will have this effect.
1163 CURL_NETRC_IGNORED
1165 The library will ignore the file and use only the infor‐
1166 mation in the URL.
1167 This is the default.
1169 CURL_NETRC_REQUIRED
1171 This value tells the library that use of the file is
1172 required, to ignore the information in the URL, and to
1173 search the file for the host only.
1174 Only machine name, user name and password are taken into account (init
1175 macros and similar things aren't supported).
1176 libcurl does not verify that the file has the correct properties set
1178 (as the standard Unix ftp client does). It should only be readable by
1179 user.
1180 CURLOPT_NETRC_FILE
1182 Pass a char * as parameter, pointing to a zero terminated string
1183 containing the full path name to the file you want libcurl to
1184 use as .netrc file. If this option is omitted, and CURLOPT_NETRC
1185 is set, libcurl will attempt to find a .netrc file in the cur‐
1186 rent user's home directory. (Added in 7.10.9)
1187 CURLOPT_USERPWD
1189 Pass a char * as parameter, which should be [user name]:[pass‐
1190 word] to use for the connection. Use CURLOPT_HTTPAUTH to decide
1191 the authentication method.
1192 When using NTLM, you can set the domain by prepending it to the
1194 user name and separating the domain and name with a forward (/)
1195 or backward slash (\). Like this: "domain/user:password" or
1196 "domain\user:password". Some HTTP servers (on Windows) support
1197 this style even for Basic authentication.
1198 When using HTTP and CURLOPT_FOLLOWLOCATION, libcurl might per‐
1200 form several requests to possibly different hosts. libcurl will
1201 only send this user and password information to hosts using the
1202 initial host name (unless CURLOPT_UNRESTRICTED_AUTH is set), so
1203 if libcurl follows locations to other hosts it will not send the
1204 user and password to those. This is enforced to prevent acciden‐
1205 tal information leakage.
1206 CURLOPT_PROXYUSERPWD
1208 Pass a char * as parameter, which should be [user name]:[pass‐
1209 word] to use for the connection to the HTTP proxy. Use CUR‐
1210 LOPT_PROXYAUTH to decide the authentication method.
1211 CURLOPT_USERNAME
1213 Pass a char * as parameter, which should be pointing to the zero
1214 terminated user name to use for the transfer.
1215 CURLOPT_USERNAME sets the user name to be used in protocol
1217 authentication. You should not use this option together with the
1218 (older) CURLOPT_USERPWD option.
1219 In order to specify the password to be used in conjunction with
1221 the user name use the CURLOPT_PASSWORD option. (Added in
1222 7.19.1)
1223 CURLOPT_PASSWORD
1225 Pass a char * as parameter, which should be pointing to the zero
1226 terminated password to use for the transfer.
1227 The CURLOPT_PASSWORD option should be used in conjunction with
1229 the CURLOPT_USERNAME option. (Added in 7.19.1)
1230 CURLOPT_PROXYUSERNAME
1232 Pass a char * as parameter, which should be pointing to the zero
1233 terminated user name to use for the transfer while connecting to
1234 Proxy.
1235 The CURLOPT_PROXYUSERNAME option should be used in same way as
1237 the CURLOPT_PROXYUSERPWD is used. In comparison to CUR‐
1238 LOPT_PROXYUSERPWD the CURLOPT_PROXYUSERNAME allows the username
1239 to contain a colon, like in the following example:
1240 "sip:user@example.com". The CURLOPT_PROXYUSERNAME option is an
1241 alternative way to set the user name while connecting to Proxy.
1242 There is no meaning to use it together with the CURLOPT_PROX‐
1243 YUSERPWD option.
1244 In order to specify the password to be used in conjunction with
1246 the user name use the CURLOPT_PROXYPASSWORD option. (Added in
1247 7.19.1)
1248 CURLOPT_PROXYPASSWORD
1250 Pass a char * as parameter, which should be pointing to the zero
1251 terminated password to use for the transfer while connecting to
1252 Proxy.
1253 The CURLOPT_PROXYPASSWORD option should be used in conjunction
1255 with the CURLOPT_PROXYUSERNAME option. (Added in 7.19.1)
1256 CURLOPT_HTTPAUTH
1258 Pass a long as parameter, which is set to a bitmask, to tell
1259 libcurl which authentication method(s) you want it to use. The
1260 available bits are listed below. If more than one bit is set,
1261 libcurl will first query the site to see which authentication
1262 methods it supports and then pick the best one you allow it to
1263 use. For some methods, this will induce an extra network round-
1264 trip. Set the actual name and password with the CURLOPT_USERPWD
1265 option or with the CURLOPT_USERNAME and the CURLOPT_PASSWORD
1266 options. (Added in 7.10.6)
1267 CURLAUTH_BASIC
1269 HTTP Basic authentication. This is the default choice,
1270 and the only method that is in wide-spread use and sup‐
1271 ported virtually everywhere. This sends the user name and
1272 password over the network in plain text, easily captured
1273 by others.
1274 CURLAUTH_DIGEST
1276 HTTP Digest authentication. Digest authentication is
1277 defined in RFC2617 and is a more secure way to do authen‐
1278 tication over public networks than the regular old-fash‐
1279 ioned Basic method.
1280 CURLAUTH_DIGEST_IE
1282 HTTP Digest authentication with an IE flavor. Digest
1283 authentication is defined in RFC2617 and is a more secure
1284 way to do authentication over public networks than the
1285 regular old-fashioned Basic method. The IE flavor is sim‐
1286 ply that libcurl will use a special "quirk" that IE is
1287 known to have used before version 7 and that some servers
1288 require the client to use. (This define was added in
1289 7.19.3)
1290 CURLAUTH_GSSNEGOTIATE
1292 HTTP GSS-Negotiate authentication. The GSS-Negotiate
1293 (also known as plain "Negotiate") method was designed by
1294 Microsoft and is used in their web applications. It is
1295 primarily meant as a support for Kerberos5 authentication
1296 but may also be used along with other authentication
1297 methods. For more information see IETF draft draft-
1298 brezak-spnego-http-04.txt.
1299 You need to build libcurl with a suitable GSS-API library
1301 for this to work.
1302 CURLAUTH_NTLM
1304 HTTP NTLM authentication. A proprietary protocol invented
1305 and used by Microsoft. It uses a challenge-response and
1306 hash concept similar to Digest, to prevent the password
1307 from being eavesdropped.
1308 You need to build libcurl with either OpenSSL, GnuTLS or
1310 NSS support for this option to work, or build libcurl on
1311 Windows.
1312 CURLAUTH_NTLM_WB
1314 NTLM delegating to winbind helper. Authentication is per‐
1315 formed by a separate binary application that is executed
1316 when needed. The name of the application is specified at
1317 compile time but is typically /usr/bin/ntlm_auth (Added
1318 in 7.22.0)
1319 Note that libcurl will fork when necessary to run the
1321 winbind application and kill it when complete, calling
1322 waitpid() to await its exit when done. On POSIX operating
1323 systems, killing the process will cause a SIGCHLD signal
1324 to be raised (regardless of whether CURLOPT_NOSIGNAL is
1325 set), which must be handled intelligently by the applica‐
1326 tion. In particular, the application must not uncondi‐
1327 tionally call wait() in its SIGCHLD signal handler to
1328 avoid being subject to a race condition. This behavior
1329 is subject to change in future versions of libcurl.
1330 CURLAUTH_ANY
1332 This is a convenience macro that sets all bits and thus
1333 makes libcurl pick any it finds suitable. libcurl will
1334 automatically select the one it finds most secure.
1335 CURLAUTH_ANYSAFE
1337 This is a convenience macro that sets all bits except
1338 Basic and thus makes libcurl pick any it finds suitable.
1339 libcurl will automatically select the one it finds most
1340 secure.
1341 CURLAUTH_ONLY
1343 This is a meta symbol. Or this value together with a sin‐
1344 gle specific auth value to force libcurl to probe for un-
1345 restricted auth and if not, only that single auth algo‐
1346 rithm is acceptable. (Added in 7.21.3)
1347 CURLOPT_TLSAUTH_TYPE
1349 Pass a long as parameter, which is set to a bitmask, to tell
1350 libcurl which authentication method(s) you want it to use for
1351 TLS authentication.
1352 CURLOPT_TLSAUTH_SRP
1354 TLS-SRP authentication. Secure Remote Password authenti‐
1355 cation for TLS is defined in RFC5054 and provides mutual
1356 authentication if both sides have a shared secret. To use
1357 TLS-SRP, you must also set the CURLOPT_TLSAUTH_USERNAME
1358 and CURLOPT_TLSAUTH_PASSWORD options.
1359 You need to build libcurl with GnuTLS or OpenSSL with
1361 TLS-SRP support for this to work. (Added in 7.21.4)
1362 CURLOPT_TLSAUTH_USERNAME
1364 Pass a char * as parameter, which should point to the zero ter‐
1365 minated username to use for the TLS authentication method speci‐
1366 fied with the CURLOPT_TLSAUTH_TYPE option. Requires that the
1367 CURLOPT_TLS_PASSWORD option also be set. (Added in 7.21.4)
1368 CURLOPT_TLSAUTH_PASSWORD
1370 Pass a char * as parameter, which should point to the zero ter‐
1371 minated password to use for the TLS authentication method speci‐
1372 fied with the CURLOPT_TLSAUTH_TYPE option. Requires that the
1373 CURLOPT_TLS_USERNAME option also be set. (Added in 7.21.4)
1374 CURLOPT_PROXYAUTH
1376 Pass a long as parameter, which is set to a bitmask, to tell
1377 libcurl which authentication method(s) you want it to use for
1378 your proxy authentication. If more than one bit is set, libcurl
1379 will first query the site to see what authentication methods it
1380 supports and then pick the best one you allow it to use. For
1381 some methods, this will induce an extra network round-trip. Set
1382 the actual name and password with the CURLOPT_PROXYUSERPWD
1383 option. The bitmask can be constructed by or'ing together the
1384 bits listed above for the CURLOPT_HTTPAUTH option. As of this
1385 writing, only Basic, Digest and NTLM work. (Added in 7.10.7)
1386
1388 CURLOPT_AUTOREFERER
1389 Pass a parameter set to 1 to enable this. When enabled, libcurl
1390 will automatically set the Referer: field in requests where it
1391 follows a Location: redirect.
1392 CURLOPT_ACCEPT_ENCODING
1394 Sets the contents of the Accept-Encoding: header sent in a HTTP
1395 request, and enables decoding of a response when a Content-
1396 Encoding: header is received. Three encodings are supported:
1397 identity, which does nothing, deflate which requests the server
1398 to compress its response using the zlib algorithm, and gzip
1399 which requests the gzip algorithm. If a zero-length string is
1400 set, then an Accept-Encoding: header containing all supported
1401 encodings is sent.
1402 This is a request, not an order; the server may or may not do
1404 it. This option must be set (to any non-NULL value) or else any
1405 unsolicited encoding done by the server is ignored. See the spe‐
1406 cial file lib/README.encoding for details.
1407 (This option was called CURLOPT_ENCODING before 7.21.6)
1409 CURLOPT_TRANSFER_ENCODING
1411 Adds a request for compressed Transfer Encoding in the outgoing
1412 HTTP request. If the server supports this and so desires, it can
1413 respond with the HTTP response sent using a compressed Transfer-
1414 Encoding that will be automatically uncompressed by libcurl on
1415 reception.
1416 Transfer-Encoding differs slightly from the Content-Encoding you
1418 ask for with CURLOPT_ACCEPT_ENCODING in that a Transfer-Encoding
1419 is strictly meant to be for the transfer and thus MUST be
1420 decoded before the data arrives in the client. Traditionally,
1421 Transfer-Encoding has been much less used and supported by both
1422 HTTP clients and HTTP servers.
1423 (Added in 7.21.6)
1425 CURLOPT_FOLLOWLOCATION
1427 A parameter set to 1 tells the library to follow any Location:
1428 header that the server sends as part of a HTTP header.
1429 This means that the library will re-send the same request on the
1431 new location and follow new Location: headers all the way until
1432 no more such headers are returned. CURLOPT_MAXREDIRS can be used
1433 to limit the number of redirects libcurl will follow.
1434 Since 7.19.4, libcurl can limit what protocols it will automati‐
1436 cally follow. The accepted protocols are set with CUR‐
1437 LOPT_REDIR_PROTOCOLS and it excludes the FILE protocol by
1438 default.
1439 CURLOPT_UNRESTRICTED_AUTH
1441 A parameter set to 1 tells the library it can continue to send
1442 authentication (user+password) when following locations, even
1443 when hostname changed. This option is meaningful only when set‐
1444 ting CURLOPT_FOLLOWLOCATION.
1445 CURLOPT_MAXREDIRS
1447 Pass a long. The set number will be the redirection limit. If
1448 that many redirections have been followed, the next redirect
1449 will cause an error (CURLE_TOO_MANY_REDIRECTS). This option only
1450 makes sense if the CURLOPT_FOLLOWLOCATION is used at the same
1451 time. Added in 7.15.1: Setting the limit to 0 will make libcurl
1452 refuse any redirect. Set it to -1 for an infinite number of
1453 redirects (which is the default)
1454 CURLOPT_POSTREDIR
1456 Pass a bitmask to control how libcurl acts on redirects after
1457 POSTs that get a 301, 302 or 303 response back. A parameter
1458 with bit 0 set (value CURL_REDIR_POST_301) tells the library to
1459 respect RFC2616/10.3.2 and not convert POST requests into GET
1460 requests when following a 301 redirection. Setting bit 1 (value
1461 CURL_REDIR_POST_302) makes libcurl maintain the request method
1462 after a 302 redirect whilst setting bit 2 (value
1463 CURL_REDIR_POST_303) makes libcurl maintain the request method
1464 after a 303 redirect. The value CURL_REDIR_POST_ALL is a conve‐
1465 nience define that sets all three bits.
1466 The non-RFC behaviour is ubiquitous in web browsers, so the
1468 library does the conversion by default to maintain consistency.
1469 However, a server may require a POST to remain a POST after such
1470 a redirection. This option is meaningful only when setting CUR‐
1471 LOPT_FOLLOWLOCATION. (Added in 7.17.1) (This option was known
1472 as CURLOPT_POST301 up to 7.19.0 as it only supported the 301
1473 then)
1474 CURLOPT_PUT
1476 A parameter set to 1 tells the library to use HTTP PUT to trans‐
1477 fer data. The data should be set with CURLOPT_READDATA and CUR‐
1478 LOPT_INFILESIZE.
1479 This option is deprecated and starting with version 7.12.1 you
1481 should instead use CURLOPT_UPLOAD.
1482 CURLOPT_POST
1484 A parameter set to 1 tells the library to do a regular HTTP
1485 post. This will also make the library use a "Content-Type:
1486 application/x-www-form-urlencoded" header. (This is by far the
1487 most commonly used POST method).
1488 Use one of CURLOPT_POSTFIELDS or CURLOPT_COPYPOSTFIELDS options
1490 to specify what data to post and CURLOPT_POSTFIELDSIZE or CUR‐
1491 LOPT_POSTFIELDSIZE_LARGE to set the data size.
1492 Optionally, you can provide data to POST using the CURLOPT_READ‐
1494 FUNCTION and CURLOPT_READDATA options but then you must make
1495 sure to not set CURLOPT_POSTFIELDS to anything but NULL. When
1496 providing data with a callback, you must transmit it using chun‐
1497 ked transfer-encoding or you must set the size of the data with
1498 the CURLOPT_POSTFIELDSIZE or CURLOPT_POSTFIELDSIZE_LARGE option.
1499 To enable chunked encoding, you simply pass in the appropriate
1500 Transfer-Encoding header, see the post-callback.c example.
1501 You can override the default POST Content-Type: header by set‐
1503 ting your own with CURLOPT_HTTPHEADER.
1504 Using POST with HTTP 1.1 implies the use of a "Expect: 100-con‐
1506 tinue" header. You can disable this header with CURLOPT_HTTP‐
1507 HEADER as usual.
1508 If you use POST to a HTTP 1.1 server, you can send data without
1510 knowing the size before starting the POST if you use chunked
1511 encoding. You enable this by adding a header like "Transfer-
1512 Encoding: chunked" with CURLOPT_HTTPHEADER. With HTTP 1.0 or
1513 without chunked transfer, you must specify the size in the
1514 request.
1515 When setting CURLOPT_POST to 1, it will automatically set CUR‐
1517 LOPT_NOBODY to 0 (since 7.14.1).
1518 If you issue a POST request and then want to make a HEAD or GET
1520 using the same re-used handle, you must explicitly set the new
1521 request type using CURLOPT_NOBODY or CURLOPT_HTTPGET or similar.
1522 CURLOPT_POSTFIELDS
1524 Pass a void * as parameter, which should be the full data to
1525 post in a HTTP POST operation. You must make sure that the data
1526 is formatted the way you want the server to receive it. libcurl
1527 will not convert or encode it for you. Most web servers will
1528 assume this data to be url-encoded.
1529 The pointed data are NOT copied by the library: as a conse‐
1531 quence, they must be preserved by the calling application until
1532 the transfer finishes.
1533 This POST is a normal application/x-www-form-urlencoded kind
1535 (and libcurl will set that Content-Type by default when this
1536 option is used), which is the most commonly used one by HTML
1537 forms. See also the CURLOPT_POST. Using CURLOPT_POSTFIELDS
1538 implies CURLOPT_POST.
1539 If you want to do a zero-byte POST, you need to set CUR‐
1541 LOPT_POSTFIELDSIZE explicitly to zero, as simply setting CUR‐
1542 LOPT_POSTFIELDS to NULL or "" just effectively disables the
1543 sending of the specified string. libcurl will instead assume
1544 that you'll send the POST data using the read callback!
1545 Using POST with HTTP 1.1 implies the use of a "Expect: 100-con‐
1547 tinue" header. You can disable this header with CURLOPT_HTTP‐
1548 HEADER as usual.
1549 To make multipart/formdata posts (aka RFC2388-posts), check out
1551 the CURLOPT_HTTPPOST option.
1552 CURLOPT_POSTFIELDSIZE
1554 If you want to post data to the server without letting libcurl
1555 do a strlen() to measure the data size, this option must be
1556 used. When this option is used you can post fully binary data,
1557 which otherwise is likely to fail. If this size is set to -1,
1558 the library will use strlen() to get the size.
1559 CURLOPT_POSTFIELDSIZE_LARGE
1561 Pass a curl_off_t as parameter. Use this to set the size of the
1562 CURLOPT_POSTFIELDS data to prevent libcurl from doing strlen()
1563 on the data to figure out the size. This is the large file ver‐
1564 sion of the CURLOPT_POSTFIELDSIZE option. (Added in 7.11.1)
1565 CURLOPT_COPYPOSTFIELDS
1567 Pass a char * as parameter, which should be the full data to
1568 post in a HTTP POST operation. It behaves as the CURLOPT_POST‐
1569 FIELDS option, but the original data are copied by the library,
1570 allowing the application to overwrite the original data after
1571 setting this option.
1572 Because data are copied, care must be taken when using this
1574 option in conjunction with CURLOPT_POSTFIELDSIZE or CUR‐
1575 LOPT_POSTFIELDSIZE_LARGE: If the size has not been set prior to
1576 CURLOPT_COPYPOSTFIELDS, the data are assumed to be a NUL-termi‐
1577 nated string; else the stored size informs the library about the
1578 data byte count to copy. In any case, the size must not be
1579 changed after CURLOPT_COPYPOSTFIELDS, unless another CUR‐
1580 LOPT_POSTFIELDS or CURLOPT_COPYPOSTFIELDS option is issued.
1581 (Added in 7.17.1)
1582 CURLOPT_HTTPPOST
1584 Tells libcurl you want a multipart/formdata HTTP POST to be made
1585 and you instruct what data to pass on to the server. Pass a
1586 pointer to a linked list of curl_httppost structs as parameter.
1587 The easiest way to create such a list, is to use curl_formadd(3)
1588 as documented. The data in this list must remain intact until
1589 you close this curl handle again with curl_easy_cleanup(3).
1590 Using POST with HTTP 1.1 implies the use of a "Expect: 100-con‐
1592 tinue" header. You can disable this header with CURLOPT_HTTP‐
1593 HEADER as usual.
1594 When setting CURLOPT_HTTPPOST, it will automatically set CUR‐
1596 LOPT_NOBODY to 0 (since 7.14.1).
1597 CURLOPT_REFERER
1599 Pass a pointer to a zero terminated string as parameter. It will
1600 be used to set the Referer: header in the http request sent to
1601 the remote server. This can be used to fool servers or scripts.
1602 You can also set any custom header with CURLOPT_HTTPHEADER.
1603 CURLOPT_USERAGENT
1605 Pass a pointer to a zero terminated string as parameter. It will
1606 be used to set the User-Agent: header in the http request sent
1607 to the remote server. This can be used to fool servers or
1608 scripts. You can also set any custom header with CURLOPT_HTTP‐
1609 HEADER.
1610 CURLOPT_HTTPHEADER
1612 Pass a pointer to a linked list of HTTP headers to pass to the
1613 server in your HTTP request. The linked list should be a fully
1614 valid list of struct curl_slist structs properly filled in. Use
1615 curl_slist_append(3) to create the list and
1616 curl_slist_free_all(3) to clean up an entire list. If you add a
1617 header that is otherwise generated and used by libcurl inter‐
1618 nally, your added one will be used instead. If you add a header
1619 with no content as in 'Accept:' (no data on the right side of
1620 the colon), the internally used header will get disabled. Thus,
1621 using this option you can add new headers, replace internal
1622 headers and remove internal headers. To add a header with no
1623 content, make the content be two quotes: "". The headers
1624 included in the linked list must not be CRLF-terminated, because
1625 curl adds CRLF after each header item. Failure to comply with
1626 this will result in strange bugs because the server will most
1627 likely ignore part of the headers you specified.
1628 The first line in a request (containing the method, usually a
1630 GET or POST) is not a header and cannot be replaced using this
1631 option. Only the lines following the request-line are headers.
1632 Adding this method line in this list of headers will only cause
1633 your request to send an invalid header.
1634 Pass a NULL to this to reset back to no custom headers.
1636 The most commonly replaced headers have "shortcuts" in the
1638 options CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER.
1639 CURLOPT_HTTP200ALIASES
1641 Pass a pointer to a linked list of aliases to be treated as
1642 valid HTTP 200 responses. Some servers respond with a custom
1643 header response line. For example, IceCast servers respond with
1644 "ICY 200 OK". By including this string in your list of aliases,
1645 the response will be treated as a valid HTTP header line such as
1646 "HTTP/1.0 200 OK". (Added in 7.10.3)
1647 The linked list should be a fully valid list of struct
1649 curl_slist structs, and be properly filled in. Use
1650 curl_slist_append(3) to create the list and
1651 curl_slist_free_all(3) to clean up an entire list.
1652 The alias itself is not parsed for any version strings. Before
1654 libcurl 7.16.3, Libcurl used the value set by option CUR‐
1655 LOPT_HTTP_VERSION, but starting with 7.16.3 the protocol is
1656 assumed to match HTTP 1.0 when an alias matched.
1657 CURLOPT_COOKIE
1659 Pass a pointer to a zero terminated string as parameter. It will
1660 be used to set a cookie in the http request. The format of the
1661 string should be NAME=CONTENTS, where NAME is the cookie name
1662 and CONTENTS is what the cookie should contain.
1663 If you need to set multiple cookies, you need to set them all
1665 using a single option and thus you need to concatenate them all
1666 in one single string. Set multiple cookies in one string like
1667 this: "name1=content1; name2=content2;" etc.
1668 This option sets the cookie header explicitly in the outgoing
1670 request(s). If multiple requests are done due to authentication,
1671 followed redirections or similar, they will all get this cookie
1672 passed on.
1673 Using this option multiple times will only make the latest
1675 string override the previous ones.
1676 CURLOPT_COOKIEFILE
1678 Pass a pointer to a zero terminated string as parameter. It
1679 should contain the name of your file holding cookie data to
1680 read. The cookie data may be in Netscape / Mozilla cookie data
1681 format or just regular HTTP-style headers dumped to a file.
1682 Given an empty or non-existing file or by passing the empty
1684 string (""), this option will enable cookies for this curl han‐
1685 dle, making it understand and parse received cookies and then
1686 use matching cookies in future requests.
1687 If you use this option multiple times, you just add more files
1689 to read. Subsequent files will add more cookies.
1690 CURLOPT_COOKIEJAR
1692 Pass a file name as char *, zero terminated. This will make
1693 libcurl write all internally known cookies to the specified file
1694 when curl_easy_cleanup(3) is called. If no cookies are known, no
1695 file will be created. Specify "-" to instead have the cookies
1696 written to stdout. Using this option also enables cookies for
1697 this session, so if you for example follow a location it will
1698 make matching cookies get sent accordingly.
1699 If the cookie jar file can't be created or written to (when the
1701 curl_easy_cleanup(3) is called), libcurl will not and cannot
1702 report an error for this. Using CURLOPT_VERBOSE or CUR‐
1703 LOPT_DEBUGFUNCTION will get a warning to display, but that is
1704 the only visible feedback you get about this possibly lethal
1705 situation.
1706 CURLOPT_COOKIESESSION
1708 Pass a long set to 1 to mark this as a new cookie "session". It
1709 will force libcurl to ignore all cookies it is about to load
1710 that are "session cookies" from the previous session. By
1711 default, libcurl always stores and loads all cookies, indepen‐
1712 dent if they are session cookies or not. Session cookies are
1713 cookies without expiry date and they are meant to be alive and
1714 existing for this "session" only.
1715 CURLOPT_COOKIELIST
1717 Pass a char * to a cookie string. Cookie can be either in Net‐
1718 scape / Mozilla format or just regular HTTP-style header (Set-
1719 Cookie: ...) format. If cURL cookie engine was not enabled it
1720 will enable its cookie engine. Passing a magic string "ALL"
1721 will erase all cookies known by cURL. (Added in 7.14.1) Passing
1722 the special string "SESS" will only erase all session cookies
1723 known by cURL. (Added in 7.15.4) Passing the special string
1724 "FLUSH" will write all cookies known by cURL to the file speci‐
1725 fied by CURLOPT_COOKIEJAR. (Added in 7.17.1)
1726 CURLOPT_HTTPGET
1728 Pass a long. If the long is 1, this forces the HTTP request to
1729 get back to GET. Usable if a POST, HEAD, PUT, or a custom
1730 request has been used previously using the same curl handle.
1731 When setting CURLOPT_HTTPGET to 1, it will automatically set
1733 CURLOPT_NOBODY to 0 (since 7.14.1).
1734 CURLOPT_HTTP_VERSION
1736 Pass a long, set to one of the values described below. They
1737 force libcurl to use the specific HTTP versions. This is not
1738 sensible to do unless you have a good reason.
1739 CURL_HTTP_VERSION_NONE
1741 We don't care about what version the library uses.
1742 libcurl will use whatever it thinks fit.
1743 CURL_HTTP_VERSION_1_0
1745 Enforce HTTP 1.0 requests.
1746 CURL_HTTP_VERSION_1_1
1748 Enforce HTTP 1.1 requests.
1749 CURLOPT_IGNORE_CONTENT_LENGTH
1751 Ignore the Content-Length header. This is useful for Apache 1.x
1752 (and similar servers) which will report incorrect content length
1753 for files over 2 gigabytes. If this option is used, curl will
1754 not be able to accurately report progress, and will simply stop
1755 the download when the server ends the connection. (added in
1756 7.14.1)
1757 CURLOPT_HTTP_CONTENT_DECODING
1759 Pass a long to tell libcurl how to act on content decoding. If
1760 set to zero, content decoding will be disabled. If set to 1 it
1761 is enabled. Libcurl has no default content decoding but requires
1762 you to use CURLOPT_ENCODING for that. (added in 7.16.2)
1763 CURLOPT_HTTP_TRANSFER_DECODING
1765 Pass a long to tell libcurl how to act on transfer decoding. If
1766 set to zero, transfer decoding will be disabled, if set to 1 it
1767 is enabled (default). libcurl does chunked transfer decoding by
1768 default unless this option is set to zero. (added in 7.16.2)
1769
1771 CURLOPT_MAIL_FROM
1772 Pass a pointer to a zero terminated string as parameter. This
1773 should be used to specify the sender's email address when send‐
1774 ing SMTP mail with libcurl.
1775 An originator email address should be specified with angled
1777 brackets (<>) around it, which if not specified, will be added
1778 by libcurl from version 7.21.4 onwards. Failing to provide such
1779 brackets may cause the server to reject the email.
1780 If this parameter is not specified then an empty address will be
1782 sent to the mail server which may or may not cause the email to
1783 be rejected.
1784 (Added in 7.20.0)
1786 CURLOPT_MAIL_RCPT
1788 Pass a pointer to a linked list of recipients to pass to the
1789 server in your SMTP mail request. The linked list should be a
1790 fully valid list of struct curl_slist structs properly filled
1791 in. Use curl_slist_append(3) to create the list and
1792 curl_slist_free_all(3) to clean up an entire list.
1793 Each recipient should be specified within a pair of angled
1795 brackets (<>), however, should you not use an angled bracket as
1796 the first character libcurl will assume you provided a single
1797 email address and enclose that address within brackets for you.
1798 (Added in 7.20.0)
1800 CURLOPT_MAIL_AUTH
1802 Pass a pointer to a zero terminated string as parameter. This
1803 will be used to specify the authentication address (identity) of
1804 a submitted message that is being relayed to another server.
1805 This optional parameter allows co-operating agents in a trusted
1807 environment to communicate the authentication of individual mes‐
1808 sages and should only be used by the application program, using
1809 libcurl, if the application is itself a mail server acting in
1810 such an environment. If the application is operating as such and
1811 the AUTH address is not known or is invalid, then an empty
1812 string should be used for this parameter.
1813 Unlike CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT, the address
1815 should not be specified within a pair of angled brackets (<>).
1816 However, if an empty string is used then a pair of brackets will
1817 be sent by libcurl as required by RFC2554.
1818 (Added in 7.25.0)
1820
1822 CURLOPT_TFTP_BLKSIZE
1823 Specify block size to use for TFTP data transmission. Valid
1824 range as per RFC2348 is 8-65464 bytes. The default of 512 bytes
1825 will be used if this option is not specified. The specified
1826 block size will only be used pending support by the remote
1827 server. If the server does not return an option acknowledgement
1828 or returns an option acknowledgement with no blksize, the
1829 default of 512 bytes will be used. (added in 7.19.4)
1830
1832 CURLOPT_FTPPORT
1833 Pass a pointer to a zero terminated string as parameter. It will
1834 be used to get the IP address to use for the FTP PORT instruc‐
1835 tion. The PORT instruction tells the remote server to connect to
1836 our specified IP address. The string may be a plain IP address,
1837 a host name, a network interface name (under Unix) or just a '-'
1838 symbol to let the library use your system's default IP address.
1839 Default FTP operations are passive, and thus won't use PORT.
1840 The address can be followed by a ':' to specify a port, option‐
1842 ally followed by a '-' to specify a port range. If the port
1843 specified is 0, the operating system will pick a free port. If
1844 a range is provided and all ports in the range are not avail‐
1845 able, libcurl will report CURLE_FTP_PORT_FAILED for the handle.
1846 Invalid port/range settings are ignored. IPv6 addresses fol‐
1847 lowed by a port or portrange have to be in brackets. IPv6
1848 addresses without port/range specifier can be in brackets.
1849 (added in 7.19.5)
1850 Examples with specified ports:
1852 eth0:0
1854 192.168.1.2:32000-33000
1855 curl.se:32123
1856 [::1]:1234-4567
1857 You disable PORT again and go back to using the passive version
1859 by setting this option to NULL.
1860 CURLOPT_QUOTE
1862 Pass a pointer to a linked list of FTP or SFTP commands to pass
1863 to the server prior to your FTP request. This will be done
1864 before any other commands are issued (even before the CWD com‐
1865 mand for FTP). The linked list should be a fully valid list of
1866 'struct curl_slist' structs properly filled in with text
1867 strings. Use curl_slist_append(3) to append strings (commands)
1868 to the list, and clear the entire list afterwards with
1869 curl_slist_free_all(3). Disable this operation again by setting
1870 a NULL to this option. When speaking to a FTP (or SFTP since
1871 7.24.0) server, prefix the command with an asterisk (*) to make
1872 libcurl continue even if the command fails as by default libcurl
1873 will stop at first failure.
1874 The set of valid FTP commands depends on the server (see RFC959
1876 for a list of mandatory commands).
1877 The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir,
1879 pwd, rename, rm, rmdir, symlink (see curl(1)) (SFTP support
1880 added in 7.16.3)
1881 CURLOPT_POSTQUOTE
1883 Pass a pointer to a linked list of FTP or SFTP commands to pass
1884 to the server after your FTP transfer request. The commands will
1885 only be run if no error occurred. The linked list should be a
1886 fully valid list of struct curl_slist structs properly filled in
1887 as described for CURLOPT_QUOTE. Disable this operation again by
1888 setting a NULL to this option.
1889 CURLOPT_PREQUOTE
1891 Pass a pointer to a linked list of FTP commands to pass to the
1892 server after the transfer type is set. The linked list should be
1893 a fully valid list of struct curl_slist structs properly filled
1894 in as described for CURLOPT_QUOTE. Disable this operation again
1895 by setting a NULL to this option. Before version 7.16.0, if you
1896 also set CURLOPT_NOBODY to 1, this option didn't work.
1897 CURLOPT_DIRLISTONLY
1899 A parameter set to 1 tells the library to just list the names of
1900 files in a directory, instead of doing a full directory listing
1901 that would include file sizes, dates etc. This works for FTP and
1902 SFTP URLs.
1903 This causes an FTP NLST command to be sent on an FTP server.
1905 Beware that some FTP servers list only files in their response
1906 to NLST; they might not include subdirectories and symbolic
1907 links.
1908 Setting this option to 1 also implies a directory listing even
1910 if the URL doesn't end with a slash, which otherwise is neces‐
1911 sary.
1912 Do NOT use this option if you also use CURLOPT_WILDCARDMATCH as
1914 it will effectively break that feature then.
1915 (This option was known as CURLOPT_FTPLISTONLY up to 7.16.4)
1917 CURLOPT_APPEND
1919 A parameter set to 1 tells the library to append to the remote
1920 file instead of overwrite it. This is only useful when uploading
1921 to an FTP site.
1922 (This option was known as CURLOPT_FTPAPPEND up to 7.16.4)
1924 CURLOPT_FTP_USE_EPRT
1926 Pass a long. If the value is 1, it tells curl to use the EPRT
1927 (and LPRT) command when doing active FTP downloads (which is
1928 enabled by CURLOPT_FTPPORT). Using EPRT means that it will first
1929 attempt to use EPRT and then LPRT before using PORT, but if you
1930 pass zero to this option, it will not try using EPRT or LPRT,
1931 only plain PORT. (Added in 7.10.5)
1932 If the server is an IPv6 host, this option will have no effect
1934 as of 7.12.3.
1935 CURLOPT_FTP_USE_EPSV
1937 Pass a long. If the value is 1, it tells curl to use the EPSV
1938 command when doing passive FTP downloads (which it always does
1939 by default). Using EPSV means that it will first attempt to use
1940 EPSV before using PASV, but if you pass zero to this option, it
1941 will not try using EPSV, only plain PASV.
1942 If the server is an IPv6 host, this option will have no effect
1944 as of 7.12.3.
1945 CURLOPT_FTP_USE_PRET
1947 Pass a long. If the value is 1, it tells curl to send a PRET
1948 command before PASV (and EPSV). Certain FTP servers, mainly
1949 drftpd, require this non-standard command for directory listings
1950 as well as up and downloads in PASV mode. Has no effect when
1951 using the active FTP transfers mode. (Added in 7.20.0)
1952 CURLOPT_FTP_CREATE_MISSING_DIRS
1954 Pass a long. If the value is 1, curl will attempt to create any
1955 remote directory that it fails to CWD into. CWD is the command
1956 that changes working directory. (Added in 7.10.7)
1957 This setting also applies to SFTP-connections. curl will attempt
1959 to create the remote directory if it can't obtain a handle to
1960 the target-location. The creation will fail if a file of the
1961 same name as the directory to create already exists or lack of
1962 permissions prevents creation. (Added in 7.16.3)
1963 Starting with 7.19.4, you can also set this value to 2, which
1965 will make libcurl retry the CWD command again if the subsequent
1966 MKD command fails. This is especially useful if you're doing
1967 many simultaneous connections against the same server and they
1968 all have this option enabled, as then CWD may first fail but
1969 then another connection does MKD before this connection and thus
1970 MKD fails but trying CWD works! 7.19.4 also introduced the
1971 CURLFTP_CREATE_DIR and CURLFTP_CREATE_DIR_RETRY enum names for
1972 these arguments.
1973 Before version 7.19.4, libcurl will simply ignore arguments set
1975 to 2 and act as if 1 was selected.
1976 CURLOPT_FTP_RESPONSE_TIMEOUT
1978 Pass a long. Causes curl to set a timeout period (in seconds)
1979 on the amount of time that the server is allowed to take in
1980 order to generate a response message for a command before the
1981 session is considered hung. While curl is waiting for a
1982 response, this value overrides CURLOPT_TIMEOUT. It is recom‐
1983 mended that if used in conjunction with CURLOPT_TIMEOUT, you set
1984 CURLOPT_FTP_RESPONSE_TIMEOUT to a value smaller than CUR‐
1985 LOPT_TIMEOUT. (Added in 7.10.8)
1986 CURLOPT_FTP_ALTERNATIVE_TO_USER
1988 Pass a char * as parameter, pointing to a string which will be
1989 used to authenticate if the usual FTP "USER user" and "PASS
1990 password" negotiation fails. This is currently only known to be
1991 required when connecting to Tumbleweed's Secure Transport FTPS
1992 server using client certificates for authentication. (Added in
1993 7.15.5)
1994 CURLOPT_FTP_SKIP_PASV_IP
1996 Pass a long. If set to 1, it instructs libcurl to not use the IP
1997 address the server suggests in its 227-response to libcurl's
1998 PASV command when libcurl connects the data connection. Instead
1999 libcurl will re-use the same IP address it already uses for the
2000 control connection. But it will use the port number from the
2001 227-response. (Added in 7.14.2)
2002 This option has no effect if PORT, EPRT or EPSV is used instead
2004 of PASV.
2005 CURLOPT_FTPSSLAUTH
2007 Pass a long using one of the values from below, to alter how
2008 libcurl issues "AUTH TLS" or "AUTH SSL" when FTP over SSL is
2009 activated (see CURLOPT_USE_SSL). (Added in 7.12.2)
2010 CURLFTPAUTH_DEFAULT
2012 Allow libcurl to decide.
2013 CURLFTPAUTH_SSL
2015 Try "AUTH SSL" first, and only if that fails try "AUTH
2016 TLS".
2017 CURLFTPAUTH_TLS
2019 Try "AUTH TLS" first, and only if that fails try "AUTH
2020 SSL".
2021 CURLOPT_FTP_SSL_CCC
2023 If enabled, this option makes libcurl use CCC (Clear Command
2024 Channel). It shuts down the SSL/TLS layer after authenticating.
2025 The rest of the control channel communication will be unen‐
2026 crypted. This allows NAT routers to follow the FTP transaction.
2027 Pass a long using one of the values below. (Added in 7.16.1)
2028 CURLFTPSSL_CCC_NONE
2030 Don't attempt to use CCC.
2031 CURLFTPSSL_CCC_PASSIVE
2033 Do not initiate the shutdown, but wait for the server to
2034 do it. Do not send a reply.
2035 CURLFTPSSL_CCC_ACTIVE
2037 Initiate the shutdown and wait for a reply.
2038 CURLOPT_FTP_ACCOUNT
2040 Pass a pointer to a zero terminated string (or NULL to disable).
2041 When an FTP server asks for "account data" after user name and
2042 password has been provided, this data is sent off using the ACCT
2043 command. (Added in 7.13.0)
2044 CURLOPT_FTP_FILEMETHOD
2046 Pass a long that should have one of the following values. This
2047 option controls what method libcurl should use to reach a file
2048 on a FTP(S) server. The argument should be one of the following
2049 alternatives:
2050 CURLFTPMETHOD_MULTICWD
2052 libcurl does a single CWD operation for each path part in
2053 the given URL. For deep hierarchies this means many com‐
2054 mands. This is how RFC1738 says it should be done. This
2055 is the default but the slowest behavior.
2056 CURLFTPMETHOD_NOCWD
2058 libcurl does no CWD at all. libcurl will do SIZE, RETR,
2059 STOR etc and give a full path to the server for all these
2060 commands. This is the fastest behavior.
2061 CURLFTPMETHOD_SINGLECWD
2063 libcurl does one CWD with the full target directory and
2064 then operates on the file "normally" (like in the multi‐
2065 cwd case). This is somewhat more standards compliant than
2066 'nocwd' but without the full penalty of 'multicwd'.
2067 (Added in 7.15.1)
2068
2070 CURLOPT_RTSP_REQUEST
2071 Tell libcurl what kind of RTSP request to make. Pass one of the
2072 following RTSP enum values. Unless noted otherwise, commands
2073 require the Session ID to be initialized. (Added in 7.20.0)
2074 CURL_RTSPREQ_OPTIONS
2076 Used to retrieve the available methods of the server. The
2077 application is responsible for parsing and obeying the
2078 response. (The session ID is not needed for this method.)
2079 (Added in 7.20.0)
2080 CURL_RTSPREQ_DESCRIBE
2082 Used to get the low level description of a stream. The
2083 application should note what formats it understands in
2084 the 'Accept:' header. Unless set manually, libcurl will
2085 automatically fill in 'Accept: application/sdp'. Time-
2086 condition headers will be added to Describe requests if
2087 the CURLOPT_TIMECONDITION option is active. (The session
2088 ID is not needed for this method) (Added in 7.20.0)
2089 CURL_RTSPREQ_ANNOUNCE
2091 When sent by a client, this method changes the descrip‐
2092 tion of the session. For example, if a client is using
2093 the server to record a meeting, the client can use
2094 Announce to inform the server of all the meta-information
2095 about the session. ANNOUNCE acts like a HTTP PUT or POST
2096 just like CURL_RTSPREQ_SET_PARAMETER (Added in 7.20.0)
2097 CURL_RTSPREQ_SETUP
2099 Setup is used to initialize the transport layer for the
2100 session. The application must set the desired Transport
2101 options for a session by using the CURLOPT_RTSP_TRANSPORT
2102 option prior to calling setup. If no session ID is cur‐
2103 rently set with CURLOPT_RTSP_SESSION_ID, libcurl will
2104 extract and use the session ID in the response to this
2105 request. (The session ID is not needed for this method).
2106 (Added in 7.20.0)
2107 CURL_RTSPREQ_PLAY
2109 Send a Play command to the server. Use the CURLOPT_RANGE
2110 option to modify the playback time (e.g. 'npt=10-15').
2111 (Added in 7.20.0)
2112 CURL_RTSPREQ_PAUSE
2114 Send a Pause command to the server. Use the CURLOPT_RANGE
2115 option with a single value to indicate when the stream
2116 should be halted. (e.g. npt='25') (Added in 7.20.0)
2117 CURL_RTSPREQ_TEARDOWN
2119 This command terminates an RTSP session. Simply closing a
2120 connection does not terminate the RTSP session since it
2121 is valid to control an RTSP session over different con‐
2122 nections. (Added in 7.20.0)
2123 CURL_RTSPREQ_GET_PARAMETER
2125 Retrieve a parameter from the server. By default, libcurl
2126 will automatically include a Content-Type: text/parame‐
2127 ters header on all non-empty requests unless a custom one
2128 is set. GET_PARAMETER acts just like a HTTP PUT or POST
2129 (see CURL_RTSPREQ_SET_PARAMETER). Applications wishing
2130 to send a heartbeat message (e.g. in the presence of a
2131 server-specified timeout) should send use an empty
2132 GET_PARAMETER request. (Added in 7.20.0)
2133 CURL_RTSPREQ_SET_PARAMETER
2135 Set a parameter on the server. By default, libcurl will
2136 automatically include a Content-Type: text/parameters
2137 header unless a custom one is set. The interaction with
2138 SET_PARAMTER is much like a HTTP PUT or POST. An applica‐
2139 tion may either use CURLOPT_UPLOAD with CURLOPT_READDATA
2140 like a HTTP PUT, or it may use CURLOPT_POSTFIELDS like a
2141 HTTP POST. No chunked transfers are allowed, so the
2142 application must set the CURLOPT_INFILESIZE in the former
2143 and CURLOPT_POSTFIELDSIZE in the latter. Also, there is
2144 no use of multi-part POSTs within RTSP. (Added in 7.20.0)
2145 CURL_RTSPREQ_RECORD
2147 Used to tell the server to record a session. Use the CUR‐
2148 LOPT_RANGE option to modify the record time. (Added in
2149 7.20.0)
2150 CURL_RTSPREQ_RECEIVE
2152 This is a special request because it does not send any
2153 data to the server. The application may call this func‐
2154 tion in order to receive interleaved RTP data. It will
2155 return after processing one read buffer of data in order
2156 to give the application a chance to run. (Added in
2157 7.20.0)
2158 CURLOPT_RTSP_SESSION_ID
2160 Pass a char * as a parameter to set the value of the current
2161 RTSP Session ID for the handle. Useful for resuming an in-
2162 progress session. Once this value is set to any non-NULL value,
2163 libcurl will return CURLE_RTSP_SESSION_ERROR if ID received from
2164 the server does not match. If unset (or set to NULL), libcurl
2165 will automatically set the ID the first time the server sets it
2166 in a response. (Added in 7.20.0)
2167 CURLOPT_RTSP_STREAM_URI
2169 Set the stream URI to operate on by passing a char * . For exam‐
2170 ple, a single session may be controlling
2171 rtsp://foo/twister/audio and rtsp://foo/twister/video and the
2172 application can switch to the appropriate stream using this
2173 option. If unset, libcurl will default to operating on generic
2174 server options by passing '*' in the place of the RTSP Stream
2175 URI. This option is distinct from CURLOPT_URL. When working with
2176 RTSP, the CURLOPT_STREAM_URI indicates what URL to send to the
2177 server in the request header while the CURLOPT_URL indicates
2178 where to make the connection to. (e.g. the CURLOPT_URL for the
2179 above examples might be set to rtsp://foo/twister (Added in
2180 7.20.0)
2181 CURLOPT_RTSP_TRANSPORT
2183 Pass a char * to tell libcurl what to pass for the Transport:
2184 header for this RTSP session. This is mainly a convenience
2185 method to avoid needing to set a custom Transport: header for
2186 every SETUP request. The application must set a Transport:
2187 header before issuing a SETUP request. (Added in 7.20.0)
2188 CURLOPT_RTSP_HEADER
2190 This option is simply an alias for CURLOPT_HTTP_HEADER. Use this
2191 to replace the standard headers that RTSP and HTTP share. It is
2192 also valid to use the shortcuts such as CURLOPT_USERAGENT.
2193 (Added in 7.20.0)
2194 CURLOPT_RTSP_CLIENT_CSEQ
2196 Manually set the the CSEQ number to issue for the next RTSP
2197 request. Useful if the application is resuming a previously bro‐
2198 ken connection. The CSEQ will increment from this new number
2199 henceforth. (Added in 7.20.0)
2200 CURLOPT_RTSP_SERVER_CSEQ
2202 Manually set the CSEQ number to expect for the next RTSP
2203 Server->Client request. At the moment, this feature (listening
2204 for Server requests) is unimplemented. (Added in 7.20.0)
2205
2207 CURLOPT_TRANSFERTEXT
2208 A parameter set to 1 tells the library to use ASCII mode for FTP
2209 transfers, instead of the default binary transfer. For win32
2210 systems it does not set the stdout to binary mode. This option
2211 can be usable when transferring text data between systems with
2212 different views on certain characters, such as newlines or simi‐
2213 lar.
2214 libcurl does not do a complete ASCII conversion when doing ASCII
2216 transfers over FTP. This is a known limitation/flaw that nobody
2217 has rectified. libcurl simply sets the mode to ASCII and per‐
2218 forms a standard transfer.
2219 CURLOPT_PROXY_TRANSFER_MODE
2221 Pass a long. If the value is set to 1 (one), it tells libcurl to
2222 set the transfer mode (binary or ASCII) for FTP transfers done
2223 via a HTTP proxy, by appending ;type=a or ;type=i to the URL.
2224 Without this setting, or it being set to 0 (zero, the default),
2225 CURLOPT_TRANSFERTEXT has no effect when doing FTP via a proxy.
2226 Beware that not all proxies support this feature. (Added in
2227 7.18.0)
2228 CURLOPT_CRLF
2230 Pass a long. If the value is set to 1 (one), libcurl converts
2231 Unix newlines to CRLF newlines on transfers. Disable this option
2232 again by setting the value to 0 (zero).
2233 CURLOPT_RANGE
2235 Pass a char * as parameter, which should contain the specified
2236 range you want. It should be in the format "X-Y", where X or Y
2237 may be left out. HTTP transfers also support several intervals,
2238 separated with commas as in "X-Y,N-M". Using this kind of multi‐
2239 ple intervals will cause the HTTP server to send the response
2240 document in pieces (using standard MIME separation techniques).
2241 For RTSP, the formatting of a range should follow RFC2326 Sec‐
2242 tion 12.29. For RTSP, byte ranges are not permitted. Instead,
2243 ranges should be given in npt, utc, or smpte formats.
2244 Pass a NULL to this option to disable the use of ranges.
2246 Ranges work on HTTP, FTP, FILE (since 7.18.0), and RTSP (since
2248 7.20.0) transfers only.
2249 CURLOPT_RESUME_FROM
2251 Pass a long as parameter. It contains the offset in number of
2252 bytes that you want the transfer to start from. Set this option
2253 to 0 to make the transfer start from the beginning (effectively
2254 disabling resume). For FTP, set this option to -1 to make the
2255 transfer start from the end of the target file (useful to con‐
2256 tinue an interrupted upload).
2257 When doing uploads with FTP, the resume position is where in the
2259 local/source file libcurl should try to resume the upload from
2260 and it will then append the source file to the remote target
2261 file.
2262 CURLOPT_RESUME_FROM_LARGE
2264 Pass a curl_off_t as parameter. It contains the offset in number
2265 of bytes that you want the transfer to start from. (Added in
2266 7.11.0)
2267 CURLOPT_CUSTOMREQUEST
2269 Pass a pointer to a zero terminated string as parameter. It can
2270 be used to specify the request instead of GET or HEAD when per‐
2271 forming HTTP based requests, instead of LIST and NLST when per‐
2272 forming FTP directory listings and instead of LIST and RETR when
2273 issuing POP3 based commands. This is particularly useful, for
2274 example, for performing a HTTP DELETE request or a POP3 DELE
2275 command.
2276 Please don't perform this at will, on HTTP based requests, by
2278 making sure your server supports the command you are sending
2279 first.
2280 When you change the request method by setting CURLOPT_CUSTOMRE‐
2282 QUEST to something, you don't actually change how libcurl
2283 behaves or acts in regards to the particular request method, it
2284 will only change the actual string sent in the request.
2285 For example:
2287 With the HTTP protocol when you tell libcurl to do a HEAD
2289 request, but then specify a GET though a custom request libcurl
2290 will still act as if it sent a HEAD. To switch to a proper HEAD
2291 use CURLOPT_NOBODY, to switch to a proper POST use CURLOPT_POST
2292 or CURLOPT_POSTFIELDS and to switch to a proper GET use CUR‐
2293 LOPT_HTTPGET.
2294 With the POP3 protocol when you tell libcurl to use a custom
2296 request it will behave like a LIST or RETR command was sent
2297 where it expects data to be returned by the server. As such CUR‐
2298 LOPT_NOBODY should be used when specifying commands such as DELE
2299 and NOOP for example.
2300 Restore to the internal default by setting this to NULL.
2302 Many people have wrongly used this option to replace the entire
2304 request with their own, including multiple headers and POST con‐
2305 tents. While that might work in many cases, it will cause
2306 libcurl to send invalid requests and it could possibly confuse
2307 the remote server badly. Use CURLOPT_POST and CURLOPT_POSTFIELDS
2308 to set POST data. Use CURLOPT_HTTPHEADER to replace or extend
2309 the set of headers sent by libcurl. Use CURLOPT_HTTP_VERSION to
2310 change HTTP version.
2311 (Support for POP3 added in 7.26.0)
2313 CURLOPT_FILETIME
2315 Pass a long. If it is 1, libcurl will attempt to get the modifi‐
2316 cation date of the remote document in this operation. This
2317 requires that the remote server sends the time or replies to a
2318 time querying command. The curl_easy_getinfo(3) function with
2319 the CURLINFO_FILETIME argument can be used after a transfer to
2320 extract the received time (if any).
2321 CURLOPT_NOBODY
2323 A parameter set to 1 tells the library to not include the body-
2324 part in the output. This is only relevant for protocols that
2325 have separate header and body parts. On HTTP(S) servers, this
2326 will make libcurl do a HEAD request.
2327 To change request to GET, you should use CURLOPT_HTTPGET. Change
2329 request to POST with CURLOPT_POST etc.
2330 CURLOPT_INFILESIZE
2332 When uploading a file to a remote site, this option should be
2333 used to tell libcurl what the expected size of the infile is.
2334 This value should be passed as a long. See also CURLOPT_INFILE‐
2335 SIZE_LARGE.
2336 For uploading using SCP, this option or CURLOPT_INFILESIZE_LARGE
2338 is mandatory.
2339 When sending emails using SMTP, this command can be used to
2341 specify the optional SIZE parameter for the MAIL FROM command.
2342 (Added in 7.23.0)
2343 This option does not limit how much data libcurl will actually
2345 send, as that is controlled entirely by what the read callback
2346 returns.
2347 CURLOPT_INFILESIZE_LARGE
2349 When uploading a file to a remote site, this option should be
2350 used to tell libcurl what the expected size of the infile is.
2351 This value should be passed as a curl_off_t. (Added in 7.11.0)
2352 For uploading using SCP, this option or CURLOPT_INFILESIZE is
2354 mandatory.
2355 This option does not limit how much data libcurl will actually
2357 send, as that is controlled entirely by what the read callback
2358 returns.
2359 CURLOPT_UPLOAD
2361 A parameter set to 1 tells the library to prepare for an upload.
2362 The CURLOPT_READDATA and CURLOPT_INFILESIZE or CURLOPT_INFILE‐
2363 SIZE_LARGE options are also interesting for uploads. If the pro‐
2364 tocol is HTTP, uploading means using the PUT request unless you
2365 tell libcurl otherwise.
2366 Using PUT with HTTP 1.1 implies the use of a "Expect: 100-con‐
2368 tinue" header. You can disable this header with CURLOPT_HTTP‐
2369 HEADER as usual.
2370 If you use PUT to a HTTP 1.1 server, you can upload data without
2372 knowing the size before starting the transfer if you use chunked
2373 encoding. You enable this by adding a header like "Transfer-
2374 Encoding: chunked" with CURLOPT_HTTPHEADER. With HTTP 1.0 or
2375 without chunked transfer, you must specify the size.
2376 CURLOPT_MAXFILESIZE
2378 Pass a long as parameter. This allows you to specify the maximum
2379 size (in bytes) of a file to download. If the file requested is
2380 larger than this value, the transfer will not start and
2381 CURLE_FILESIZE_EXCEEDED will be returned.
2382 The file size is not always known prior to download, and for
2384 such files this option has no effect even if the file transfer
2385 ends up being larger than this given limit. This concerns both
2386 FTP and HTTP transfers.
2387 CURLOPT_MAXFILESIZE_LARGE
2389 Pass a curl_off_t as parameter. This allows you to specify the
2390 maximum size (in bytes) of a file to download. If the file
2391 requested is larger than this value, the transfer will not start
2392 and CURLE_FILESIZE_EXCEEDED will be returned. (Added in 7.11.0)
2393 The file size is not always known prior to download, and for
2395 such files this option has no effect even if the file transfer
2396 ends up being larger than this given limit. This concerns both
2397 FTP and HTTP transfers.
2398 CURLOPT_TIMECONDITION
2400 Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE
2401 time value is treated. You can set this parameter to CURL_TIME‐
2402 COND_IFMODSINCE or CURL_TIMECOND_IFUNMODSINCE. This feature
2403 applies to HTTP, FTP, RTSP, and FILE.
2404 The last modification time of a file is not always known and in
2406 such instances this feature will have no effect even if the
2407 given time condition would not have been met. curl_easy_get‐
2408 info(3) with the CURLINFO_CONDITION_UNMET option can be used
2409 after a transfer to learn if a zero-byte successful "transfer"
2410 was due to this condition not matching.
2411 CURLOPT_TIMEVALUE
2413 Pass a long as parameter. This should be the time in seconds
2414 since 1 Jan 1970, and the time will be used in a condition as
2415 specified with CURLOPT_TIMECONDITION.
2416
2418 CURLOPT_TIMEOUT
2419 Pass a long as parameter containing the maximum time in seconds
2420 that you allow the libcurl transfer operation to take. Normally,
2421 name lookups can take a considerable time and limiting opera‐
2422 tions to less than a few minutes risk aborting perfectly normal
2423 operations. This option will cause curl to use the SIGALRM to
2424 enable time-outing system calls.
2425 In unix-like systems, this might cause signals to be used unless
2427 CURLOPT_NOSIGNAL is set.
2428 Default timeout is 0 (zero) which means it never times out.
2430 CURLOPT_TIMEOUT_MS
2432 Like CURLOPT_TIMEOUT but takes number of milliseconds instead.
2433 If libcurl is built to use the standard system name resolver,
2434 that portion of the transfer will still use full-second resolu‐
2435 tion for timeouts with a minimum timeout allowed of one second.
2436 (Added in 7.16.2)
2437 CURLOPT_LOW_SPEED_LIMIT
2439 Pass a long as parameter. It contains the transfer speed in
2440 bytes per second that the transfer should be below during CUR‐
2441 LOPT_LOW_SPEED_TIME seconds for the library to consider it too
2442 slow and abort.
2443 CURLOPT_LOW_SPEED_TIME
2445 Pass a long as parameter. It contains the time in seconds that
2446 the transfer should be below the CURLOPT_LOW_SPEED_LIMIT for the
2447 library to consider it too slow and abort.
2448 CURLOPT_MAX_SEND_SPEED_LARGE
2450 Pass a curl_off_t as parameter. If an upload exceeds this speed
2451 (counted in bytes per second) on cumulative average during the
2452 transfer, the transfer will pause to keep the average rate less
2453 than or equal to the parameter value. Defaults to unlimited
2454 speed. (Added in 7.15.5)
2455 CURLOPT_MAX_RECV_SPEED_LARGE
2457 Pass a curl_off_t as parameter. If a download exceeds this
2458 speed (counted in bytes per second) on cumulative average during
2459 the transfer, the transfer will pause to keep the average rate
2460 less than or equal to the parameter value. Defaults to unlimited
2461 speed. (Added in 7.15.5)
2462 CURLOPT_MAXCONNECTS
2464 Pass a long. The set number will be the persistent connection
2465 cache size. The set amount will be the maximum amount of simul‐
2466 taneously open connections that libcurl may cache in this easy
2467 handle. Default is 5, and there isn't much point in changing
2468 this value unless you are perfectly aware of how this works and
2469 changes libcurl's behaviour. This concerns connections using any
2470 of the protocols that support persistent connections.
2471 When reaching the maximum limit, curl closes the oldest one in
2473 the cache to prevent increasing the number of open connections.
2474 If you already have performed transfers with this curl handle,
2476 setting a smaller MAXCONNECTS than before may cause open connec‐
2477 tions to get closed unnecessarily.
2478 If you add this easy handle to a multi handle, this setting is
2480 not acknowledged, and you must instead use curl_multi_setopt(3)
2481 and the CURLMOPT_MAXCONNECTS option.
2482 CURLOPT_CLOSEPOLICY
2484 (Obsolete) This option does nothing.
2485 CURLOPT_FRESH_CONNECT
2487 Pass a long. Set to 1 to make the next transfer use a new
2488 (fresh) connection by force. If the connection cache is full
2489 before this connection, one of the existing connections will be
2490 closed as according to the selected or default policy. This
2491 option should be used with caution and only if you understand
2492 what it does. Set this to 0 to have libcurl attempt re-using an
2493 existing connection (default behavior).
2494 CURLOPT_FORBID_REUSE
2496 Pass a long. Set to 1 to make the next transfer explicitly close
2497 the connection when done. Normally, libcurl keeps all connec‐
2498 tions alive when done with one transfer in case a succeeding one
2499 follows that can re-use them. This option should be used with
2500 caution and only if you understand what it does. Set to 0 to
2501 have libcurl keep the connection open for possible later re-use
2502 (default behavior).
2503 CURLOPT_CONNECTTIMEOUT
2505 Pass a long. It should contain the maximum time in seconds that
2506 you allow the connection to the server to take. This only lim‐
2507 its the connection phase, once it has connected, this option is
2508 of no more use. Set to zero to switch to the default built-in
2509 connection timeout - 300 seconds. See also the CURLOPT_TIMEOUT
2510 option.
2511 In unix-like systems, this might cause signals to be used unless
2513 CURLOPT_NOSIGNAL is set.
2514 CURLOPT_CONNECTTIMEOUT_MS
2516 Like CURLOPT_CONNECTTIMEOUT but takes the number of milliseconds
2517 instead. If libcurl is built to use the standard system name
2518 resolver, that portion of the connect will still use full-second
2519 resolution for timeouts with a minimum timeout allowed of one
2520 second. (Added in 7.16.2)
2521 CURLOPT_IPRESOLVE
2523 Allows an application to select what kind of IP addresses to use
2524 when resolving host names. This is only interesting when using
2525 host names that resolve addresses using more than one version of
2526 IP. The allowed values are:
2527 CURL_IPRESOLVE_WHATEVER
2529 Default, resolves addresses to all IP versions that your
2530 system allows.
2531 CURL_IPRESOLVE_V4
2533 Resolve to IPv4 addresses.
2534 CURL_IPRESOLVE_V6
2536 Resolve to IPv6 addresses.
2537 CURLOPT_CONNECT_ONLY
2539 Pass a long. If the parameter equals 1, it tells the library to
2540 perform all the required proxy authentication and connection
2541 setup, but no data transfer. This option is implemented for
2542 HTTP, SMTP and POP3.
2543 The option can be used to simply test a connection to a server,
2545 but is more useful when used with the CURLINFO_LASTSOCKET option
2546 to curl_easy_getinfo(3) as the library can set up the connection
2547 and then the application can obtain the most recently used
2548 socket for special data transfers. (Added in 7.15.2)
2549 CURLOPT_USE_SSL
2551 Pass a long using one of the values from below, to make libcurl
2552 use your desired level of SSL for the transfer. (Added in
2553 7.11.0)
2554 This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP
2556 etc.
2557 (This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the
2559 constants were known as CURLFTPSSL_*)
2560 CURLUSESSL_NONE
2562 Don't attempt to use SSL.
2563 CURLUSESSL_TRY
2565 Try using SSL, proceed as normal otherwise.
2566 CURLUSESSL_CONTROL
2568 Require SSL for the control connection or fail with
2569 CURLE_USE_SSL_FAILED.
2570 CURLUSESSL_ALL
2572 Require SSL for all communication or fail with
2573 CURLE_USE_SSL_FAILED.
2574 CURLOPT_RESOLVE
2576 Pass a pointer to a linked list of strings with host name
2577 resolve information to use for requests with this handle. The
2578 linked list should be a fully valid list of struct curl_slist
2579 structs properly filled in. Use curl_slist_append(3) to create
2580 the list and curl_slist_free_all(3) to clean up an entire list.
2581 Each single name resolve string should be written using the for‐
2583 mat HOST:PORT:ADDRESS where HOST is the name libcurl will try to
2584 resolve, PORT is the port number of the service where libcurl
2585 wants to connect to the HOST and ADDRESS is the numerical IP
2586 address. If libcurl is built to support IPv6, ADDRESS can of
2587 course be either IPv4 or IPv6 style addressing.
2588 This option effectively pre-populates the DNS cache with entries
2590 for the host+port pair so redirects and everything that opera‐
2591 tions against the HOST+PORT will instead use your provided
2592 ADDRESS.
2593 You can remove names from the DNS cache again, to stop providing
2595 these fake resolves, by including a string in the linked list
2596 that uses the format "-HOST:PORT". The host name must be pre‐
2597 fixed with a dash, and the host name and port number must
2598 exactly match what was already added previously.
2599 (Added in 7.21.3)
2601 CURLOPT_DNS_SERVERS
2603 Set the list of DNS servers to be used instead of the system
2604 default. The format of the dns servers option is:
2605 host[:port][,host[:port]]...
2607 For example:
2609 192.168.1.100,192.168.1.101,3.4.5.6
2611 This option requires that libcurl was built with a resolver
2613 backend that supports this operation. The c-ares backend is the
2614 only such one.
2615 (Added in 7.24.0)
2617 CURLOPT_ACCEPTTIMEOUT_MS
2619 Pass a long telling libcurl the maximum number of milliseconds
2620 to wait for a server to connect back to libcurl when an active
2621 FTP connection is used. If no timeout is set, the internal
2622 default of 60000 will be used. (Added in 7.24.0)
2623
2625 CURLOPT_SSLCERT
2626 Pass a pointer to a zero terminated string as parameter. The
2627 string should be the file name of your certificate. The default
2628 format is "PEM" and can be changed with CURLOPT_SSLCERTTYPE.
2629 With NSS this can also be the nickname of the certificate you
2631 wish to authenticate with. If you want to use a file from the
2632 current directory, please precede it with "./" prefix, in order
2633 to avoid confusion with a nickname.
2634 CURLOPT_SSLCERTTYPE
2636 Pass a pointer to a zero terminated string as parameter. The
2637 string should be the format of your certificate. Supported for‐
2638 mats are "PEM" and "DER". (Added in 7.9.3)
2639 CURLOPT_SSLKEY
2641 Pass a pointer to a zero terminated string as parameter. The
2642 string should be the file name of your private key. The default
2643 format is "PEM" and can be changed with CURLOPT_SSLKEYTYPE.
2644 CURLOPT_SSLKEYTYPE
2646 Pass a pointer to a zero terminated string as parameter. The
2647 string should be the format of your private key. Supported for‐
2648 mats are "PEM", "DER" and "ENG".
2649 The format "ENG" enables you to load the private key from a
2651 crypto engine. In this case CURLOPT_SSLKEY is used as an identi‐
2652 fier passed to the engine. You have to set the crypto engine
2653 with CURLOPT_SSLENGINE. "DER" format key file currently does
2654 not work because of a bug in OpenSSL.
2655 CURLOPT_KEYPASSWD
2657 Pass a pointer to a zero terminated string as parameter. It will
2658 be used as the password required to use the CURLOPT_SSLKEY or
2659 CURLOPT_SSH_PRIVATE_KEYFILE private key. You never needed a
2660 pass phrase to load a certificate but you need one to load your
2661 private key.
2662 (This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and
2664 CURLOPT_SSLCERTPASSWD up to 7.9.2)
2665 CURLOPT_SSLENGINE
2667 Pass a pointer to a zero terminated string as parameter. It will
2668 be used as the identifier for the crypto engine you want to use
2669 for your private key.
2670 If the crypto device cannot be loaded, CURLE_SSL_ENGINE_NOTFOUND
2672 is returned.
2673 CURLOPT_SSLENGINE_DEFAULT
2675 Sets the actual crypto engine as the default for (asymmetric)
2676 crypto operations.
2677 If the crypto device cannot be set, CURLE_SSL_ENGINE_SETFAILED
2679 is returned.
2680 Even though this option doesn't need any parameter, in some con‐
2682 figurations curl_easy_setopt might be defined as a macro taking
2683 exactly three arguments. Therefore, it's recommended to pass 1
2684 as parameter to this option.
2685 CURLOPT_SSLVERSION
2687 Pass a long as parameter to control what version of SSL/TLS to
2688 attempt to use. (Added in 7.9.2)
2689 The available options are:
2691 CURL_SSLVERSION_DEFAULT
2693 The default action. This will attempt to figure out the
2694 remote SSL protocol version, i.e. either SSLv3 or TLSv1
2695 (but not SSLv2, which became disabled by default with
2696 7.18.1).
2697 CURL_SSLVERSION_TLSv1
2699 Force TLSv1.x
2700 CURL_SSLVERSION_SSLv2
2702 Force SSLv2
2703 CURL_SSLVERSION_SSLv3
2705 Force SSLv3
2706 CURL_SSLVERSION_TLSv1_0
2708 Force TLSv1.0 (Added in 7.34.0)
2709 CURL_SSLVERSION_TLSv1_1
2711 Force TLSv1.1 (Added in 7.34.0)
2712 CURL_SSLVERSION_TLSv1_2
2714 Force TLSv1.2 (Added in 7.34.0)
2715 CURLOPT_SSL_VERIFYPEER
2717 Pass a long as parameter. By default, curl assumes a value of 1.
2718 This option determines whether curl verifies the authenticity of
2720 the peer's certificate. A value of 1 means curl verifies; 0
2721 (zero) means it doesn't.
2722 When negotiating a SSL connection, the server sends a certifi‐
2724 cate indicating its identity. Curl verifies whether the cer‐
2725 tificate is authentic, i.e. that you can trust that the server
2726 is who the certificate says it is. This trust is based on a
2727 chain of digital signatures, rooted in certification authority
2728 (CA) certificates you supply. curl uses a default bundle of CA
2729 certificates (the path for that is determined at build time) and
2730 you can specify alternate certificates with the CURLOPT_CAINFO
2731 option or the CURLOPT_CAPATH option.
2732 When CURLOPT_SSL_VERIFYPEER is nonzero, and the verification
2734 fails to prove that the certificate is authentic, the connection
2735 fails. When the option is zero, the peer certificate verifica‐
2736 tion succeeds regardless.
2737 Authenticating the certificate is not by itself very useful.
2739 You typically want to ensure that the server, as authentically
2740 identified by its certificate, is the server you mean to be
2741 talking to. Use CURLOPT_SSL_VERIFYHOST to control that. The
2742 check that the host name in the certificate is valid for the
2743 host name you're connecting to is done independently of the CUR‐
2744 LOPT_SSL_VERIFYPEER option.
2745 CURLOPT_CAINFO
2747 Pass a char * to a zero terminated string naming a file holding
2748 one or more certificates to verify the peer with. This makes
2749 sense only when used in combination with the CURLOPT_SSL_VERI‐
2750 FYPEER option. If CURLOPT_SSL_VERIFYPEER is zero, CUR‐
2751 LOPT_CAINFO need not even indicate an accessible file.
2752 This option is by default set to the system path where libcurl's
2754 cacert bundle is assumed to be stored, as established at build
2755 time.
2756 If curl is built against the NSS SSL library, the NSS PEM
2758 PKCS#11 module (libnsspem.so) needs to be available for this
2759 option to work properly.
2760 CURLOPT_ISSUERCERT
2762 Pass a char * to a zero terminated string naming a file holding
2763 a CA certificate in PEM format. If the option is set, an addi‐
2764 tional check against the peer certificate is performed to verify
2765 the issuer is indeed the one associated with the certificate
2766 provided by the option. This additional check is useful in
2767 multi-level PKI where one needs to enforce that the peer cer‐
2768 tificate is from a specific branch of the tree.
2769 This option makes sense only when used in combination with the
2771 CURLOPT_SSL_VERIFYPEER option. Otherwise, the result of the
2772 check is not considered as failure.
2773 A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with
2775 the option, which is returned if the setup of the SSL/TLS ses‐
2776 sion has failed due to a mismatch with the issuer of peer cer‐
2777 tificate (CURLOPT_SSL_VERIFYPEER has to be set too for the check
2778 to fail). (Added in 7.19.0)
2779 CURLOPT_CAPATH
2781 Pass a char * to a zero terminated string naming a directory
2782 holding multiple CA certificates to verify the peer with. If
2783 libcurl is built against OpenSSL, the certificate directory must
2784 be prepared using the openssl c_rehash utility. This makes
2785 sense only when used in combination with the CURLOPT_SSL_VERI‐
2786 FYPEER option. If CURLOPT_SSL_VERIFYPEER is zero, CURLOPT_CAP‐
2787 ATH need not even indicate an accessible path. The CURLOPT_CAP‐
2788 ATH function apparently does not work in Windows due to some
2789 limitation in openssl. This option is OpenSSL-specific and does
2790 nothing if libcurl is built to use GnuTLS. NSS-powered libcurl
2791 provides the option only for backward compatibility.
2792 CURLOPT_CRLFILE
2794 Pass a char * to a zero terminated string naming a file with the
2795 concatenation of CRL (in PEM format) to use in the certificate
2796 validation that occurs during the SSL exchange.
2797 When curl is built to use NSS or GnuTLS, there is no way to
2799 influence the use of CRL passed to help in the verification
2800 process. When libcurl is built with OpenSSL support,
2801 X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both
2802 set, requiring CRL check against all the elements of the cer‐
2803 tificate chain if a CRL file is passed.
2804 This option makes sense only when used in combination with the
2806 CURLOPT_SSL_VERIFYPEER option.
2807 A specific error code (CURLE_SSL_CRL_BADFILE) is defined with
2809 the option. It is returned when the SSL exchange fails because
2810 the CRL file cannot be loaded. A failure in certificate verifi‐
2811 cation due to a revocation information found in the CRL does not
2812 trigger this specific error. (Added in 7.19.0)
2813 CURLOPT_SSL_VERIFYHOST
2815 Pass a long as parameter.
2816 This option determines whether libcurl verifies that the server
2818 cert is for the server it is known as.
2819 When negotiating a SSL connection, the server sends a certifi‐
2821 cate indicating its identity.
2822 When CURLOPT_SSL_VERIFYHOST is 2, that certificate must indicate
2824 that the server is the server to which you meant to connect, or
2825 the connection fails.
2826 Curl considers the server the intended one when the Common Name
2828 field or a Subject Alternate Name field in the certificate
2829 matches the host name in the URL to which you told Curl to con‐
2830 nect.
2831 When the value is 1, libcurl will return a failure. It was pre‐
2833 viously (in 7.28.0 and earlier) a debug option of some sorts,
2834 but it is no longer supported due to frequently leading to pro‐
2835 grammer mistakes.
2836 When the value is 0, the connection succeeds regardless of the
2838 names in the certificate.
2839 The default value for this option is 2.
2841 This option controls checking the server's certificate's claimed
2843 identity. The server could be lying. To control lying, see
2844 CURLOPT_SSL_VERIFYPEER. If libcurl is built against NSS and
2845 CURLOPT_SSL_VERIFYPEER is zero, CURLOPT_SSL_VERIFYHOST is
2846 ignored.
2847 CURLOPT_CERTINFO
2850 Pass a long set to 1 to enable libcurl's certificate chain info
2851 gatherer. With this enabled, libcurl (if built with OpenSSL)
2852 will extract lots of information and data about the certificates
2853 in the certificate chain used in the SSL connection. This data
2854 is then possible to extract after a transfer using
2855 curl_easy_getinfo(3) and its option CURLINFO_CERTINFO. (Added in
2856 7.19.1)
2857 CURLOPT_RANDOM_FILE
2859 Pass a char * to a zero terminated file name. The file will be
2860 used to read from to seed the random engine for SSL. The more
2861 random the specified file is, the more secure the SSL connection
2862 will become.
2863 CURLOPT_EGDSOCKET
2865 Pass a char * to the zero terminated path name to the Entropy
2866 Gathering Daemon socket. It will be used to seed the random
2867 engine for SSL.
2868 CURLOPT_SSL_CIPHER_LIST
2870 Pass a char *, pointing to a zero terminated string holding the
2871 list of ciphers to use for the SSL connection. The list must be
2872 syntactically correct, it consists of one or more cipher strings
2873 separated by colons. Commas or spaces are also acceptable sepa‐
2874 rators but colons are normally used, !, - and + can be used as
2875 operators.
2876 For OpenSSL and GnuTLS valid examples of cipher lists include
2878 'RC4-SHA', ´SHA1+DES´, 'TLSv1' and 'DEFAULT'. The default list
2879 is normally set when you compile OpenSSL.
2880 You'll find more details about cipher lists on this URL:
2882 http://www.openssl.org/docs/apps/ciphers.html
2883 For NSS, valid examples of cipher lists include
2885 'rsa_rc4_128_md5', ´rsa_aes_128_sha´, etc. With NSS you don't
2886 add/remove ciphers. If one uses this option then all known
2887 ciphers are disabled and only those passed in are enabled.
2888 You'll find more details about the NSS cipher lists on this URL:
2890 http://git.fedora‐
2891 hosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives
2892 CURLOPT_SSL_SESSIONID_CACHE
2895 Pass a long set to 0 to disable libcurl's use of SSL session-ID
2896 caching. Set this to 1 to enable it. By default all transfers
2897 are done using the cache. While nothing ever should get hurt by
2898 attempting to reuse SSL session-IDs, there seem to be broken SSL
2899 implementations in the wild that may require you to disable this
2900 in order for you to succeed. (Added in 7.16.0)
2901 CURLOPT_SSL_OPTIONS
2903 Pass a long with a bitmask to tell libcurl about specific SSL
2904 behaviors.
2905 CURLSSLOPT_ALLOW_BEAST is the only supported bit and by setting
2907 this the user will tell libcurl to not attempt to use any work‐
2908 arounds for a security flaw in the SSL3 and TLS1.0 protocols.
2909 If this option isn't used or this bit is set to 0, the SSL layer
2910 libcurl uses may use a work-around for this flaw although it
2911 might cause interoperability problems with some (older) SSL
2912 implementations. WARNING: avoiding this work-around loosens the
2913 security, and by setting this option to 1 you ask for exactly
2914 that. (Added in 7.25.0)
2915 CURLOPT_KRBLEVEL
2917 Pass a char * as parameter. Set the kerberos security level for
2918 FTP; this also enables kerberos awareness. This is a string,
2919 'clear', 'safe', 'confidential' or 'private'. If the string is
2920 set but doesn't match one of these, 'private' will be used. Set
2921 the string to NULL to disable kerberos support for FTP.
2922 (This option was known as CURLOPT_KRB4LEVEL up to 7.16.3)
2924 CURLOPT_GSSAPI_DELEGATION
2926 Set the parameter to CURLGSSAPI_DELEGATION_FLAG to allow uncon‐
2927 ditional GSSAPI credential delegation. The delegation is dis‐
2928 abled by default since 7.21.7. Set the parameter to CURLGSS‐
2929 API_DELEGATION_POLICY_FLAG to delegate only if the OK-AS-DELE‐
2930 GATE flag is set in the service ticket in case this feature is
2931 supported by the GSSAPI implementation and the definition of
2932 GSS_C_DELEG_POLICY_FLAG was available at compile-time. (Added
2933 in 7.22.0)
2934
2936 CURLOPT_SSH_AUTH_TYPES
2937 Pass a long set to a bitmask consisting of one or more of
2938 CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD,
2939 CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD and CURLSSH_AUTH_AGENT.
2940 Set CURLSSH_AUTH_ANY to let libcurl pick a suitable one. Cur‐
2941 rently CURLSSH_AUTH_HOST has no effect. (Added in 7.16.1) If
2942 CURLSSH_AUTH_AGENT is used, libcurl attempts to connect to ssh-
2943 agent or pageant and let the agent attempt the authentication.
2944 (Added in 7.28.0)
2945 CURLOPT_SSH_HOST_PUBLIC_KEY_MD5
2947 Pass a char * pointing to a string containing 32 hexadecimal
2948 digits. The string should be the 128 bit MD5 checksum of the
2949 remote host's public key, and libcurl will reject the connection
2950 to the host unless the md5sums match. This option is only for
2951 SCP and SFTP transfers. (Added in 7.17.1)
2952 CURLOPT_SSH_PUBLIC_KEYFILE
2954 Pass a char * pointing to a file name for your public key. If
2955 not used, libcurl defaults to $HOME/.ssh/id_dsa.pub if the HOME
2956 environment variable is set, and just "id_dsa.pub" in the cur‐
2957 rent directory if HOME is not set. (Added in 7.16.1) If NULL
2958 (or an empty string) is passed, libcurl will pass no public key
2959 to libssh2, which then tries to compute it from the private key.
2960 This is known to work with libssh2 1.4.0+ linked against
2961 OpenSSL. (Added in 7.26.0)
2962 CURLOPT_SSH_PRIVATE_KEYFILE
2964 Pass a char * pointing to a file name for your private key. If
2965 not used, libcurl defaults to $HOME/.ssh/id_dsa if the HOME
2966 environment variable is set, and just "id_dsa" in the current
2967 directory if HOME is not set. If the file is password-pro‐
2968 tected, set the password with CURLOPT_KEYPASSWD. (Added in
2969 7.16.1)
2970 CURLOPT_SSH_KNOWNHOSTS
2972 Pass a pointer to a zero terminated string holding the file name
2973 of the known_host file to use. The known_hosts file should use
2974 the OpenSSH file format as supported by libssh2. If this file is
2975 specified, libcurl will only accept connections with hosts that
2976 are known and present in that file, with a matching public key.
2977 Use CURLOPT_SSH_KEYFUNCTION to alter the default behavior on
2978 host and key (mis)matching. (Added in 7.19.6)
2979 CURLOPT_SSH_KEYFUNCTION
2981 Pass a pointer to a curl_sshkeycallback function. It gets called
2982 when the known_host matching has been done, to allow the appli‐
2983 cation to act and decide for libcurl how to proceed. The call‐
2984 back will only be called if CURLOPT_SSH_KNOWNHOSTS is also set.
2985 The curl_sshkeycallback function gets passed the CURL handle,
2987 the key from the known_hosts file, the key from the remote site,
2988 info from libcurl on the matching status and a custom pointer
2989 (set with CURLOPT_SSH_KEYDATA). It MUST return one of the fol‐
2990 lowing return codes to tell libcurl how to act:
2991 CURLKHSTAT_FINE_ADD_TO_FILE
2993 The host+key is accepted and libcurl will append it to
2994 the known_hosts file before continuing with the connec‐
2995 tion. This will also add the host+key combo to the
2996 known_host pool kept in memory if it wasn't already
2997 present there. The adding of data to the file is done by
2998 completely replacing the file with a new copy, so the
2999 permissions of the file must allow this.
3000 CURLKHSTAT_FINE
3002 The host+key is accepted libcurl will continue with the
3003 connection. This will also add the host+key combo to the
3004 known_host pool kept in memory if it wasn't already
3005 present there.
3006 CURLKHSTAT_REJECT
3008 The host+key is rejected. libcurl will deny the connec‐
3009 tion to continue and it will be closed.
3010 CURLKHSTAT_DEFER
3012 The host+key is rejected, but the SSH connection is asked
3013 to be kept alive. This feature could be used when the
3014 app wants to somehow return back and act on the host+key
3015 situation and then retry without needing the overhead of
3016 setting it up from scratch again.
3017 (Added in 7.19.6)
3018 CURLOPT_SSH_KEYDATA
3020 Pass a void * as parameter. This pointer will be passed along
3021 verbatim to the callback set with CURLOPT_SSH_KEYFUNCTION.
3022 (Added in 7.19.6)
3023
3025 CURLOPT_PRIVATE
3026 Pass a void * as parameter, pointing to data that should be
3027 associated with this curl handle. The pointer can subsequently
3028 be retrieved using curl_easy_getinfo(3) with the CURLINFO_PRI‐
3029 VATE option. libcurl itself does nothing with this data. (Added
3030 in 7.10.3)
3031 CURLOPT_SHARE
3033 Pass a share handle as a parameter. The share handle must have
3034 been created by a previous call to curl_share_init(3). Setting
3035 this option, will make this curl handle use the data from the
3036 shared handle instead of keeping the data to itself. This
3037 enables several curl handles to share data. If the curl handles
3038 are used simultaneously in multiple threads, you MUST use the
3039 locking methods in the share handle. See curl_share_setopt(3)
3040 for details.
3041 If you add a share that is set to share cookies, your easy han‐
3043 dle will use that cookie cache and get the cookie engine
3044 enabled. If you unshare an object that was using cookies (or
3045 change to another object that doesn't share cookies), the easy
3046 handle will get its cookie engine disabled.
3047 Data that the share object is not set to share will be dealt
3049 with the usual way, as if no share was used.
3050 CURLOPT_NEW_FILE_PERMS
3052 Pass a long as a parameter, containing the value of the permis‐
3053 sions that will be assigned to newly created files on the remote
3054 server. The default value is 0644, but any valid value can be
3055 used. The only protocols that can use this are sftp://, scp://,
3056 and file://. (Added in 7.16.4)
3057 CURLOPT_NEW_DIRECTORY_PERMS
3059 Pass a long as a parameter, containing the value of the permis‐
3060 sions that will be assigned to newly created directories on the
3061 remote server. The default value is 0755, but any valid value
3062 can be used. The only protocols that can use this are sftp://,
3063 scp://, and file://. (Added in 7.16.4)
3064
3066 CURLOPT_TELNETOPTIONS
3067 Provide a pointer to a curl_slist with variables to pass to the
3068 telnet negotiations. The variables should be in the format
3069 <option=value>. libcurl supports the options 'TTYPE', 'XDISPLOC'
3070 and 'NEW_ENV'. See the TELNET standard for details.
3071
3073 CURLE_OK (zero) means that the option was set properly, non-zero means
3074 an error occurred as <curl/curl.h> defines. See the libcurl-errors(3)
3075 man page for the full list with descriptions.
3076 If you try to set an option that libcurl doesn't know about, perhaps
3078 because the library is too old to support it or the option was removed
3079 in a recent version, this function will return CURLE_FAILED_INIT.
3080
3082 curl_easy_init(3), curl_easy_cleanup(3), curl_easy_reset(3)
3083libcurl 7.20.0 1 Jan 2010 curl_easy_setopt(3)