4
<!-- Manpage converted by man2html 3.0.1 -->
8
curl_easy_setopt - Set curl easy-session options
12
<H2>SYNOPSIS</H2><PRE>
13
#include <curl/curl.h>
15
CURLcode curl_easy_setopt(CURL *handle, CURLoption option,
20
<H2>DESCRIPTION</H2><PRE>
21
curl_easy_setopt() is used to tell libcurl how to behave.
22
Most operations in libcurl have default actions, and by
23
using the appropriate options to <I>curl</I><B>_</B><I>easy</I><B>_</B><I>setopt</I>, you can
24
change them. All options are set with the <I>option</I> followed
25
by a <I>parameter</I>. That parameter can be a long, a function
26
pointer or an object pointer, all depending on what the spe�
27
cific option expects. Read this manual carefully as bad
28
input values may cause libcurl to behave badly! You can
29
only set one option in each function call. A typical appli�
30
cation uses many curl_easy_setopt() calls in the setup
33
<B>NOTE:</B> strings passed to libcurl as 'char *' arguments, will
34
not be copied by the library. Instead you should keep them
35
available until libcurl no longer needs them. Failing to do
36
so will cause very odd behavior or even crashes.
38
<B>NOTE2:</B> options set with this function call are valid for the
39
forthcoming data transfers that are performed when you
40
invoke <I>curl</I><B>_</B><I>easy</I><B>_</B><I>perform</I>. The options are not in any way
41
reset between transfers, so if you want subsequent transfers
42
with different options, you must change them between the
45
The <I>handle</I> is the return code from a <I>curl</I><B>_</B><I>easy</I><B>_</B><I>init(3)</I> or
46
<I>curl</I><B>_</B><I>easy</I><B>_</B><I>duphandle(3)</I> call.
51
The options are listed in a sort of random order, but you'll
55
Data pointer to pass to the file write function.
56
Note that if you specify the <I>CURLOPT</I><B>_</B><I>WRITEFUNCTION</I>,
57
this is the pointer you'll get as input. If you
58
don't use a callback, you must pass a 'FILE *' as
59
libcurl will pass this to fwrite() when writing
62
<B>NOTE:</B> If you're using libcurl as a win32 DLL, you
63
MUST use the <I>CURLOPT</I><B>_</B><I>WRITEFUNCTION</I> if you set this
64
option or you will experience crashes.
66
<B>CURLOPT_WRITEFUNCTION</B>
67
Function pointer that should match the following
68
prototype: <B>size_t</B> <B>function(</B> <B>void</B> <B>*ptr,</B> <B>size_t</B> <B>size,</B>
69
<B>size_t</B> <B>nmemb,</B> <B>void</B> <B>*stream);</B> This function gets
70
called by libcurl as soon as there is data available
71
to pass available that needs to be saved. The size
72
of the data pointed to by <I>ptr</I> is <I>size</I> multiplied
73
with <I>nmemb</I>. Return the number of bytes actually
74
taken care of. If that amount differs from the
75
amount passed to your function, it'll signal an
76
error to the library and it will abort the transfer
77
and return <I>CURLE</I><B>_</B><I>WRITE</I><B>_</B><I>ERROR</I>.
79
Set the <I>stream</I> argument with the <B>CURLOPT_FILE</B>
82
<B>NOTE:</B> you will be passed as much data as possible in
83
all invokes, but you cannot possibly make any
84
assumptions. It may be one byte, it may be thou�
88
Data pointer to pass to the file read function. Note
89
that if you specify the <I>CURLOPT</I><B>_</B><I>READFUNCTION</I>, this
90
is the pointer you'll get as input. If you don't
91
specify a read callback, this must be a valid FILE
94
<B>NOTE:</B> If you're using libcurl as a win32 DLL, you
95
MUST use a <I>CURLOPT</I><B>_</B><I>READFUNCTION</I> if you set this
98
<B>CURLOPT_READFUNCTION</B>
99
Function pointer that should match the following
100
prototype: <B>size_t</B> <B>function(</B> <B>void</B> <B>*ptr,</B> <B>size_t</B> <B>size,</B>
101
<B>size_t</B> <B>nmemb,</B> <B>void</B> <B>*stream);</B> This function gets
102
called by libcurl as soon as it needs to read data
103
in order to send it to the peer. The data area
104
pointed at by the pointer <I>ptr</I> may be filled with at
105
most <I>size</I> multiplied with <I>nmemb</I> number of bytes.
106
Your function must return the actual number of bytes
107
that you stored in that memory area. Returning 0
108
will signal end-of-file to the library and cause it
109
to stop the current transfer.
111
<B>CURLOPT_INFILESIZE</B>
112
When uploading a file to a remote site, this option
113
should be used to tell libcurl what the expected
114
size of the infile is.
117
The actual URL to deal with. The parameter should be
118
a char * to a zero terminated string. The string
119
must remain present until curl no longer needs it,
120
as it doesn't copy the string.
122
<B>NOTE:</B> this option is (the only one) required to be
123
set before <I>curl</I><B>_</B><I>easy</I><B>_</B><I>perform(3)</I> is called.
126
Set HTTP proxy to use. The parameter should be a
127
char * to a zero terminated string holding the host
128
name or dotted IP address. To specify port number in
129
this string, append :[port] to the end of the host
130
name. The proxy string may be prefixed with [proto�
131
col]:// since any such prefix will be ignored. The
132
proxy's port number may optionally be specified with
133
the separate option <I>CURLOPT</I><B>_</B><I>PROXYPORT</I>.
135
<B>NOTE:</B> when you tell the library to use a HTTP proxy,
136
libcurl will transparently convert operations to
137
HTTP even if you specify a FTP URL etc. This may
138
have an impact on what other features of the library
139
you can use, such as CURLOPT_QUOTE and similar FTP
140
specifics that don't work unless you tunnel through
141
the HTTP proxy. Such tunneling is activated with
142
<I>CURLOPT</I><B>_</B><I>HTTPPROXYTUNNEL</I>.
144
<B>NOTE2:</B> libcurl respects the environment variables
145
<B>http_proxy</B>, <B>ftp_proxy</B>, <B>all_proxy</B> etc, if any of
148
<B>CURLOPT_PROXYPORT</B>
149
Pass a long with this option to set the proxy port
150
to connect to unless it is specified in the proxy
151
string <I>CURLOPT</I><B>_</B><I>PROXY</I>.
153
<B>CURLOPT_HTTPPROXYTUNNEL</B>
154
Set the parameter to non-zero to get the library to
155
tunnel all operations through a given HTTP proxy.
156
Note that there is a big difference between using a
157
proxy and to tunnel through it. If you don't know
158
what this means, you probably don't want this tun�
159
neling option. (Added in libcurl 7.3)
161
<B>CURLOPT_VERBOSE</B>
162
Set the parameter to non-zero to get the library to
163
display a lot of verbose information about its oper�
164
ations. Very useful for libcurl and/or protocol
165
debugging and understanding.
167
You hardly ever want this set in production use, you
168
will almost always want this when you debug/report
171
<B>CURLOPT_HEADER</B>
172
A non-zero parameter tells the library to include
173
the header in the body output. This is only relevant
174
for protocols that actually have headers preceding
175
the data (like HTTP).
177
<B>CURLOPT_NOPROGRESS</B>
178
A non-zero parameter tells the library to shut of
179
the built-in progress meter completely.
181
<B>NOTE:</B> future versions of libcurl is likely to not
182
have any built-in progress meter at all.
184
<B>CURLOPT_NOBODY</B>
185
A non-zero parameter tells the library to not
186
include the body-part in the output. This is only
187
relevant for protocols that have separate header and
190
<B>CURLOPT_FAILONERROR</B>
191
A non-zero parameter tells the library to fail
192
silently if the HTTP code returned is equal to or
193
larger than 300. The default action would be to
194
return the page normally, ignoring that code.
196
<B>CURLOPT_UPLOAD</B>
197
A non-zero parameter tells the library to prepare
198
for an upload. The CURLOPT_INFILE and CUR�
199
LOPT_INFILESIZE are also interesting for uploads.
202
A non-zero parameter tells the library to do a regu�
203
lar HTTP post. This is a normal application/x-www-
204
form-urlencoded kind, which is the most commonly
205
used one by HTML forms. See the CURLOPT_POSTFIELDS
206
option for how to specify the data to post and CUR�
207
LOPT_POSTFIELDSIZE in how to set the data size.
208
Starting with libcurl 7.8, this option is obsolete.
209
Using the CURLOPT_POSTFIELDS option will imply this
212
<B>CURLOPT_FTPLISTONLY</B>
213
A non-zero parameter tells the library to just list
214
the names of an ftp directory, instead of doing a
215
full directory listing that would include file
218
<B>CURLOPT_FTPAPPEND</B>
219
A non-zero parameter tells the library to append to
220
the remote file instead of overwrite it. This is
221
only useful when uploading to a ftp site.
224
A non-zero parameter tells the library to scan your
225
<I>~/.netrc</I> file to find user name and password for the
226
remote site you are about to access. Only machine
227
name, user name and password is taken into account
228
(init macros and similar things aren't supported).
230
<B>Note:</B> libcurl does not verify that the file has the
231
correct properties set (as the standard Unix ftp
232
client does). It should only be readable by user.
234
<B>CURLOPT_FOLLOWLOCATION</B>
235
A non-zero parameter tells the library to follow any
236
Location: header that the server sends as part of a
239
<B>NOTE:</B> this means that the library will re-send the
240
same request on the new location and follow new
241
Location: headers all the way until no more such
242
headers are returned. <I>CURLOPT</I><B>_</B><I>MAXREDIRS</I> can be used
243
to limit the number of redirects libcurl will fol�
246
<B>CURLOPT_TRANSFERTEXT</B>
247
A non-zero parameter tells the library to use ASCII
248
mode for ftp transfers, instead of the default
249
binary transfer. For LDAP transfers it gets the data
250
in plain text instead of HTML and for win32 systems
251
it does not set the stdout to binary mode. This
252
option can be usable when transferring text data
253
between systems with different views on certain
254
characters, such as newlines or similar.
257
A non-zero parameter tells the library to use HTTP
258
PUT to transfer data. The data should be set with
259
CURLOPT_INFILE and CURLOPT_INFILESIZE.
261
<B>CURLOPT_USERPWD</B>
262
Pass a char * as parameter, which should be [user
263
name]:[password] to use for the connection. If the
264
password is left out, you will be prompted for it.
265
<I>CURLOPT</I><B>_</B><I>PASSWDFUNCTION</I> can be used to set your own
268
<B>CURLOPT_PROXYUSERPWD</B>
269
Pass a char * as parameter, which should be [user
270
name]:[password] to use for the connection to the
271
HTTP proxy. If the password is left out, you will be
272
prompted for it. <I>CURLOPT</I><B>_</B><I>PASSWDFUNCTION</I> can be used
273
to set your own prompt function.
276
Pass a char * as parameter, which should contain the
277
specified range you want. It should be in the format
278
"X-Y", where X or Y may be left out. HTTP transfers
279
also support several intervals, separated with com�
280
mas as in <I>"X-Y,N-M"</I>. Using this kind of multiple
281
intervals will cause the HTTP server to send the
282
response document in pieces (using standard MIME
283
separation techniques).
285
<B>CURLOPT_ERRORBUFFER</B>
286
Pass a char * to a buffer that the libcurl may store
287
human readable error messages in. This may be more
288
helpful than just the return code from the library.
289
The buffer must be at least CURL_ERROR_SIZE big.
291
<B>Note:</B> if the library does not return an error, the
292
buffer may not have been touched. Do not rely on the
293
contents in those cases.
295
<B>CURLOPT_TIMEOUT</B>
296
Pass a long as parameter containing the maximum time
297
in seconds that you allow the libcurl transfer oper�
298
ation to take. Normally, name lookups can take a
299
considerable time and limiting operations to less
300
than a few minutes risk aborting perfectly normal
301
operations. This option will cause curl to use the
302
SIGALRM to enable time-outing system calls.
304
<B>NOTE:</B> this does not work in Unix multi-threaded pro�
305
grams, as it uses signals.
307
<B>CURLOPT_POSTFIELDS</B>
308
Pass a char * as parameter, which should be the full
309
data to post in a HTTP post operation. This is a
310
normal application/x-www-form-urlencoded kind, which
311
is the most commonly used one by HTML forms. See
312
also the CURLOPT_POST. Since 7.8, using CUR�
313
LOPT_POSTFIELDS implies CURLOPT_POST.
315
<B>Note:</B> to make multipart/formdata posts (aka
316
rfc1867-posts), check out the <I>CURLOPT</I><B>_</B><I>HTTPPOST</I>
319
<B>CURLOPT_POSTFIELDSIZE</B>
320
If you want to post data to the server without let�
321
ting libcurl do a strlen() to measure the data size,
322
this option must be used. When this option is used
323
you can post fully binary data, which otherwise is
324
likely to fail. If this size is set to zero, the
325
library will use strlen() to get the size. (Added in
328
<B>CURLOPT_REFERER</B>
329
Pass a pointer to a zero terminated string as param�
330
eter. It will be used to set the Referer: header in
331
the http request sent to the remote server. This can
332
be used to fool servers or scripts. You can also set
333
any custom header with <I>CURLOPT</I><B>_</B><I>HTTPHEADER</I>.
335
<B>CURLOPT_USERAGENT</B>
336
Pass a pointer to a zero terminated string as param�
337
eter. It will be used to set the User-Agent: header
338
in the http request sent to the remote server. This
339
can be used to fool servers or scripts. You can also
340
set any custom header with <I>CURLOPT</I><B>_</B><I>HTTPHEADER</I>.
342
<B>CURLOPT_FTPPORT</B>
343
Pass a pointer to a zero terminated string as param�
344
eter. It will be used to get the IP address to use
345
for the ftp PORT instruction. The PORT instruction
346
tells the remote server to connect to our specified
347
IP address. The string may be a plain IP address, a
348
host name, an network interface name (under Unix) or
349
just a '-' letter to let the library use your sys�
350
tems default IP address. Default FTP operations are
351
passive, and thus won't use PORT.
353
<B>CURLOPT_LOW_SPEED_LIMIT</B>
354
Pass a long as parameter. It contains the transfer
355
speed in bytes per second that the transfer should
356
be below during CURLOPT_LOW_SPEED_TIME seconds for
357
the library to consider it too slow and abort.
359
<B>CURLOPT_LOW_SPEED_TIME</B>
360
Pass a long as parameter. It contains the time in
361
seconds that the transfer should be below the CUR�
362
LOPT_LOW_SPEED_LIMIT for the library to consider it
365
<B>CURLOPT_RESUME_FROM</B>
366
Pass a long as parameter. It contains the offset in
367
number of bytes that you want the transfer to start
370
<B>CURLOPT_COOKIE</B>
371
Pass a pointer to a zero terminated string as param�
372
eter. It will be used to set a cookie in the http
373
request. The format of the string should be
374
[NAME]=[CONTENTS]; Where NAME is the cookie name.
376
<B>CURLOPT_HTTPHEADER</B>
377
Pass a pointer to a linked list of HTTP headers to
378
pass to the server in your HTTP request. The linked
379
list should be a fully valid list of <B>struct</B>
380
<B>curl_slist</B> structs properly filled in. Use
381
<I>curl</I><B>_</B><I>slist</I><B>_</B><I>append(3)</I> to create the list and
382
<I>curl</I><B>_</B><I>slist</I><B>_</B><I>free</I><B>_</B><I>all(3)</I> to clean up an entire list.
383
If you add a header that is otherwise generated and
384
used by libcurl internally, your added one will be
385
used instead. If you add a header with no contents
386
as in 'Accept:' (no data on the right side of the
387
colon), the internally used header will get dis�
388
abled. Thus, using this option you can add new head�
389
ers, replace internal headers and remove internal
392
<B>NOTE:</B>The most commonly replaced headers have "short�
393
cuts" in the options CURLOPT_COOKIE, CURLOPT_USERA�
394
GENT and CURLOPT_REFERER.
396
<B>CURLOPT_HTTPPOST</B>
397
Tells libcurl you want a multipart/formdata HTTP
398
POST to be made and you instruct what data to pass
399
on to the server. Pass a pointer to a linked list
400
of HTTP post structs as parameter. The linked list
401
should be a fully valid list of 'struct HttpPost'
402
structs properly filled in. The best and most ele�
403
gant way to do this, is to use <I>curl</I><B>_</B><I>formadd(3)</I> as
404
documented. The data in this list must remained
405
intact until you close this curl handle again with
406
<I>curl</I><B>_</B><I>easy</I><B>_</B><I>cleanup(3)</I>.
408
<B>CURLOPT_SSLCERT</B>
409
Pass a pointer to a zero terminated string as param�
410
eter. The string should be the file name of your
411
certificate. The default format is "PEM" and can be
412
changed with <I>CURLOPT</I><B>_</B><I>SSLCERTTYPE</I>.
414
<B>CURLOPT_SSLCERTTYPE</B>
415
Pass a pointer to a zero terminated string as param�
416
eter. The string should be the format of your cer�
417
tificate. Supported formats are "PEM" and "DER".
420
<B>CURLOPT_SSLCERTPASSWD</B>
421
Pass a pointer to a zero terminated string as param�
422
eter. It will be used as the password required to
423
use the CURLOPT_SSLCERT certificate. If the password
424
is not supplied, you will be prompted for it. <I>CUR�</I>
425
<I>LOPT</I><B>_</B><I>PASSWDFUNCTION</I> can be used to set your own
428
<B>NOTE:</B>This option is replaced by <I>CURLOPT</I><B>_</B><I>SSLKEYPASSWD</I>
429
and only cept for backward compatibility. You never
430
needed a pass phrase to load a certificate but you
431
need one to load your private key.
433
<B>CURLOPT_SSLKEY</B>
434
Pass a pointer to a zero terminated string as param�
435
eter. The string should be the file name of your
436
private key. The default format is "PEM" and can be
437
changed with <I>CURLOPT</I><B>_</B><I>SSLKEYTYPE</I>. (Added in 7.9.3)
439
<B>CURLOPT_SSLKEYTYPE</B>
440
Pass a pointer to a zero terminated string as param�
441
eter. The string should be the format of your pri�
442
vate key. Supported formats are "PEM", "DER" and
443
"ENG". (Added in 7.9.3)
445
<B>NOTE:</B>The format "ENG" enables you to load the pri�
446
vate key from a crypto engine. in this case <I>CUR�</I>
447
<I>LOPT</I><B>_</B><I>SSLKEY</I> is used as an identifier passed to the
448
engine. You have to set the crypto engine with <I>CUR�</I>
449
<I>LOPT</I><B>_</B><I>SSL</I><B>_</B><I>ENGINE</I>.
451
<B>CURLOPT_SSLKEYASSWD</B>
452
Pass a pointer to a zero terminated string as param�
453
eter. It will be used as the password required to
454
use the <I>CURLOPT</I><B>_</B><I>SSLKEY</I> private key. If the password
455
is not supplied, you will be prompted for it. <I>CUR�</I>
456
<I>LOPT</I><B>_</B><I>PASSWDFUNCTION</I> can be used to set your own
457
prompt function. (Added in 7.9.3)
459
<B>CURLOPT_SSL_ENGINE</B>
460
Pass a pointer to a zero terminated string as param�
461
eter. It will be used as the identifier for the
462
crypto engine you want to use for your private key.
465
<B>NOTE:</B>If the crypto device cannot be loaded,
466
<I>CURLE</I><B>_</B><I>SSL</I><B>_</B><I>ENGINE</I><B>_</B><I>NOTFOUND</I> is returned.
468
<B>CURLOPT_SSL_ENGINEDEFAULT</B>
469
Sets the actual crypto engine as the default for
470
(asymetric) crypto operations. (Added in 7.9.3)
472
<B>NOTE:</B>If the crypto device cannot be set,
473
<I>CURLE</I><B>_</B><I>SSL</I><B>_</B><I>ENGINE</I><B>_</B><I>SETFAILED</I> is returned.
476
Convert Unix newlines to CRLF newlines on FTP
480
Pass a pointer to a linked list of FTP commands to
481
pass to the server prior to your ftp request. The
482
linked list should be a fully valid list of 'struct
483
curl_slist' structs properly filled in. Use
484
<I>curl</I><B>_</B><I>slist</I><B>_</B><I>append(3)</I> to append strings (commands) to
485
the list, and clear the entire list afterwards with
486
<I>curl</I><B>_</B><I>slist</I><B>_</B><I>free</I><B>_</B><I>all(3)</I>. Disable this operation again
487
by setting a NULL to this option.
489
<B>CURLOPT_POSTQUOTE</B>
490
Pass a pointer to a linked list of FTP commands to
491
pass to the server after your ftp transfer request.
492
The linked list should be a fully valid list of
493
struct curl_slist structs properly filled in as
494
described for <I>CURLOPT</I><B>_</B><I>QUOTE</I>. Disable this operation
495
again by setting a NULL to this option.
497
<B>CURLOPT_WRITEHEADER</B>
498
Pass a pointer to be used to write the header part
499
of the received data to. If you don't use your own
500
callback to take care of the writing, this must be a
501
valid FILE *. See also the <I>CURLOPT</I><B>_</B><I>HEADERFUNCTION</I>
502
option below on how to set a custom get-all-headers
505
<B>CURLOPT_HEADERFUNCTION</B>
506
Function pointer that should match the following
507
prototype: <I>size</I><B>_</B><I>t</I> <I>function(</I> <I>void</I> <I>*ptr,</I> <I>size</I><B>_</B><I>t</I> <I>size,</I>
508
<I>size</I><B>_</B><I>t</I> <I>nmemb,</I> <I>void</I> <I>*stream);</I>. This function gets
509
called by libcurl as soon as there is received
510
header data that needs to be written down. The head�
511
ers are guaranteed to be written one-by-one and only
512
complete lines are written. Parsing headers should
513
be easy enough using this. The size of the data
514
pointed to by <I>ptr</I> is <I>size</I> multiplied with <I>nmemb</I>.
515
The pointer named <I>stream</I> will be the one you passed
516
to libcurl with the <I>CURLOPT</I><B>_</B><I>WRITEHEADER</I> option.
517
Return the number of bytes actually written or
518
return -1 to signal error to the library (it will
519
cause it to abort the transfer with a
520
<I>CURLE</I><B>_</B><I>WRITE</I><B>_</B><I>ERROR</I> return code). (Added in libcurl
523
<B>CURLOPT_COOKIEFILE</B>
524
Pass a pointer to a zero terminated string as param�
525
eter. It should contain the name of your file hold�
526
ing cookie data. The cookie data may be in Netscape
527
/ Mozilla cookie data format or just regular HTTP-
528
style headers dumped to a file.
530
<B>CURLOPT_SSLVERSION</B>
531
Pass a long as parameter. Set what version of SSL to
532
attempt to use, 2 or 3. By default, the SSL library
533
will try to solve this by itself although some
534
servers make this difficult why you at times may
535
have to use this option.
537
<B>CURLOPT_TIMECONDITION</B>
538
Pass a long as parameter. This defines how the CUR�
539
LOPT_TIMEVALUE time value is treated. You can set
540
this parameter to TIMECOND_IFMODSINCE or TIME�
541
COND_IFUNMODSINCE. This is a HTTP-only feature.
544
<B>CURLOPT_TIMEVALUE</B>
545
Pass a long as parameter. This should be the time in
546
seconds since 1 jan 1970, and the time will be used
547
as specified in CURLOPT_TIMECONDITION or if that
548
isn't used, it will be TIMECOND_IFMODSINCE by
551
<B>CURLOPT_CUSTOMREQUEST</B>
552
Pass a pointer to a zero terminated string as param�
553
eter. It will be user instead of GET or HEAD when
554
doing the HTTP request. This is useful for doing
555
DELETE or other more or less obscure HTTP requests.
556
Don't do this at will, make sure your server sup�
557
ports the command first.
559
<B>CURLOPT_STDERR</B>
560
Pass a FILE * as parameter. This is the stream to
561
use instead of stderr internally when reporting
564
<B>CURLOPT_INTERFACE</B>
565
Pass a char * as parameter. This set the interface
566
name to use as outgoing network interface. The name
567
can be an interface name, an IP address or a host
568
name. (Added in libcurl 7.3)
570
<B>CURLOPT_KRB4LEVEL</B>
571
Pass a char * as parameter. Set the krb4 security
572
level, this also enables krb4 awareness. This is a
573
string, 'clear', 'safe', 'confidential' or 'pri�
574
vate'. If the string is set but doesn't match one
575
of these, 'private' will be used. Set the string to
576
NULL to disable kerberos4. The kerberos support only
577
works for FTP. (Added in libcurl 7.3)
579
<B>CURLOPT_PROGRESSFUNCTION</B>
580
Function pointer that should match the
581
<I>curl</I><B>_</B><I>progress</I><B>_</B><I>callback</I> prototype found in
582
<I><curl/curl.h></I>. This function gets called by libcurl
583
instead of its internal equivalent with a frequent
584
interval during data transfer. Unknown/unused argu�
585
ment values will be set to zero (like if you only
586
download data, the upload size will remain 0).
587
Returning a non-zero value from this callback will
588
cause libcurl to abort the transfer and return
589
<I>CURLE</I><B>_</B><I>ABORTED</I><B>_</B><I>BY</I><B>_</B><I>CALLBACK</I>.
591
<B>CURLOPT_PROGRESSDATA</B>
592
Pass a pointer that will be untouched by libcurl and
593
passed as the first argument in the progress call�
594
back set with <I>CURLOPT</I><B>_</B><I>PROGRESSFUNCTION</I>.
596
<B>CURLOPT_SSL_VERIFYPEER</B>
597
Pass a long that is set to a non-zero value to make
598
curl verify the peer's certificate. The certificate
599
to verify against must be specified with the CUR�
600
LOPT_CAINFO option. (Added in 7.4.2)
602
<B>CURLOPT_CAINFO</B>
603
Pass a char * to a zero terminated file naming hold�
604
ing the certificate to verify the peer with. This
605
only makes sense when used in combination with the
606
CURLOPT_SSL_VERIFYPEER option. (Added in 7.4.2)
608
<B>CURLOPT_PASSWDFUNCTION</B>
609
Pass a pointer to a <I>curl</I><B>_</B><I>passwd</I><B>_</B><I>callback</I> function
610
that will be called instead of the internal one if
611
libcurl requests a password. The function must match
612
this prototype: <B>int</B> <B>my_getpass(void</B> <B>*client,</B> <B>char</B>
613
<B>*prompt,</B> <B>char*</B> <B>buffer,</B> <B>int</B> <B>buflen</B> <B>);</B>. If set to
614
NULL, it equals to making the function always fail.
615
If the function returns a non-zero value, it will
616
abort the operation and an error (CURLE_BAD_PASS�
617
WORD_ENTERED) will be returned. <I>client</I> is a generic
618
pointer, see <I>CURLOPT</I><B>_</B><I>PASSWDDATA</I>. <I>prompt</I> is a zero-
619
terminated string that is text that prefixes the
620
input request. <I>buffer</I> is a pointer to data where
621
the entered password should be stored and <I>buflen</I> is
622
the maximum number of bytes that may be written in
623
the buffer. (Added in 7.4.2)
625
<B>CURLOPT_PASSWDDATA</B>
626
Pass a void * to whatever data you want. The passed
627
pointer will be the first argument sent to the
628
specifed <I>CURLOPT</I><B>_</B><I>PASSWDFUNCTION</I> function. (Added in
631
<B>CURLOPT_FILETIME</B>
632
Pass a long. If it is a non-zero value, libcurl will
633
attempt to get the modification date of the remote
634
document in this operation. This requires that the
635
remote server sends the time or replies to a time
636
querying command. The <I>curl</I><B>_</B><I>easy</I><B>_</B><I>getinfo(3)</I> function
637
with the <I>CURLINFO</I><B>_</B><I>FILETIME</I> argument can be used
638
after a transfer to extract the received time (if
641
<B>CURLOPT_MAXREDIRS</B>
642
Pass a long. The set number will be the redirection
643
limit. If that many redirections have been followed,
644
the next redirect will cause an error
645
(<I>CURLE</I><B>_</B><I>TOO</I><B>_</B><I>MANY</I><B>_</B><I>REDIRECTS</I>). This option only makes
646
sense if the <I>CURLOPT</I><B>_</B><I>FOLLOWLOCATION</I> is used at the
647
same time. (Added in 7.5)
649
<B>CURLOPT_MAXCONNECTS</B>
650
Pass a long. The set number will be the persistant
651
connection cache size. The set amount will be the
652
maximum amount of simultaneous connections that
653
libcurl may cache between file transfers. Default is
654
5, and there isn't much point in changing this value
655
unless you are perfectly aware of how this work and
656
changes libcurl's behaviour.
658
<B>NOTE:</B> if you already have performed transfers with
659
this curl handle, setting a smaller MAXCONNECTS than
660
before may cause open connections to get closed
661
unnecessarily. (Added in 7.7)
663
<B>CURLOPT_CLOSEPOLICY</B>
664
Pass a long. This option sets what policy libcurl
665
should use when the connection cache is filled and
666
one of the open connections has to be closed to make
667
room for a new connection. This must be one of the
668
CURLCLOSEPOLICY_* defines. Use <I>CURLCLOSEPOL�</I>
669
<I>ICY</I><B>_</B><I>LEAST</I><B>_</B><I>RECENTLY</I><B>_</B><I>USED</I> to make libcurl close the
670
connection that was least recently used, that con�
671
nection is also least likely to be capable of re-
672
use. Use <I>CURLCLOSEPOLICY</I><B>_</B><I>OLDEST</I> to make libcurl
673
close the oldest connection, the one that was cre�
674
ated first among the ones in the connection cache.
675
The other close policies are not support yet. (Added
678
<B>CURLOPT_FRESH_CONNECT</B>
679
Pass a long. Set to non-zero to make the next trans�
680
fer use a new (fresh) connection by force. If the
681
connection cache is full before this connection, one
682
of the existing connections will be closed as
683
according to the selected or default policy. This
684
option should be used with caution and only if you
685
understand what it does. Set this to 0 to have
686
libcurl attempt re-using an existing connection
687
(default behavior). (Added in 7.7)
689
<B>CURLOPT_FORBID_REUSE</B>
690
Pass a long. Set to non-zero to make the next trans�
691
fer explicitly close the connection when done. Nor�
692
mally, libcurl keep all connections alive when done
693
with one transfer in case there comes a succeeding
694
one that can re-use them. This option should be
695
used with caution and only if you understand what it
696
does. Set to 0 to have libcurl keep the connection
697
open for possibly later re-use (default behavior).
700
<B>CURLOPT_RANDOM_FILE</B>
701
Pass a char * to a zero terminated file name. The
702
file will be used to read from to seed the random
703
engine for SSL. The more random the specified file
704
is, the more secure will the SSL connection become.
706
<B>CURLOPT_EGDSOCKET</B>
707
Pass a char * to the zero terminated path name to
708
the Entropy Gathering Daemon socket. It will be used
709
to seed the random engine for SSL.
711
<B>CURLOPT_CONNECTTIMEOUT</B>
712
Pass a long. It should contain the maximum time in
713
seconds that you allow the connection to the server
714
to take. This only limits the connection phase,
715
once it has connected, this option is of no more
716
use. Set to zero to disable connection timeout (it
717
will then only timeout on the system's internal
718
timeouts). See also the <I>CURLOPT</I><B>_</B><I>TIMEOUT</I> option.
720
<B>NOTE:</B> this does not work in unix multi-threaded pro�
721
grams, as it uses signals.
723
<B>CURLOPT_HTTPGET</B>
724
Pass a long. If the long is non-zero, this forces
725
the HTTP request to get back to GET. Only really
726
usable if POST, PUT or a custom request have been
727
used previously using the same curl handle. (Added
730
<B>CURLOPT_SSL_VERIFYHOST</B>
731
Pass a long. Set if we should verify the Common name
732
from the peer certificate in the SSL handshake, set
733
1 to check existence, 2 to ensure that it matches
734
the provided hostname. (Added in 7.8.1)
736
<B>CURLOPT_COOKIEJAR</B>
737
Pass a file name as char *, zero terminated. This
738
will make libcurl dump all internally known cookies
739
to the specified file when <I>curl</I><B>_</B><I>easy</I><B>_</B><I>cleanup(3)</I> is
740
called. If no cookies are known, no file will be
741
created. Specify "-" to instead have the cookies
744
<B>CURLOPT_SSL_CIPHER_LIST</B>
745
Pass a char *, pointing to a zero terminated string
746
holding the list of ciphers to use for the SSL con�
747
nection. The list must be syntactly correct, it con�
748
sists of one or more cipher strings separated by
749
colons. Commas or spaces are also acceptable separa�
750
tors but colons are normally used, , - and + can be
751
used as operators. Valid examples of cipher lists
752
include 'RC4-SHA', �SHA1+DES�, 'TLSv1' and
753
'DEFAULT'. The default list is normally set when you
756
You'll find more details about cipher lists on this
757
URL: <I>http://www.openssl.org/docs/apps/ciphers.html</I>
759
<B>CURLOPT_HTTP_VERSION</B>
760
Pass a long, set to one of the values described
761
below. They force libcurl to use the specific HTTP
762
versions. This is not sensible to do unless you have
765
<B>CURL_HTTP_VERSION_NONE</B>
766
We don't care about what version the library
767
uses. libcurl will use whatever it thinks fit.
769
<B>CURL_HTTP_VERSION_1_0</B>
770
Enforce HTTP 1.0 requests.
772
<B>CURL_HTTP_VERSION_1_1</B>
773
Enforce HTTP 1.1 requests.
775
<B>CURLOPT_FTP_USE_EPSV</B>
776
Pass a long. If the value is non-zero, it tells curl
777
to use the EPSV command when doing passive FTP down�
778
loads (which is always does by default). Using EPSV
779
means that it will first attempt to use EPSV before
780
using PASV, but if you pass FALSE (zero) to this
781
option, it will not try using EPSV, only plain PASV.
785
<H2>RETURN VALUE</H2><PRE>
786
CURLE_OK (zero) means that the option was set properly, non-
787
zero means an error occurred as <I><curl/curl.h></I> defines.
791
<H2>SEE ALSO</H2><PRE>
792
<B>curl_easy_init(3)</B>, <B>curl_easy_cleanup(3)</B>,
797
If you find any bugs, or just have questions, subscribe to
798
one of the mailing lists and post. We won't bite.
806
Man(1) output converted with
807
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
added
removed
docs/libcurl/curl_easy_setopt.html
