1
.\" You can view this file with:
3
.\" $Id: curl_easy_setopt.3,v 1.1 2002/03/04 10:09:49 bagder Exp $
5
.TH curl_easy_setopt 3 "10 Dec 2001" "libcurl 7.9.2" "libcurl Manual"
7
curl_easy_setopt - Set curl easy-session options
11
CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
14
curl_easy_setopt() is used to tell libcurl how to behave. Most operations in
15
libcurl have default actions, and by using the appropriate options to
16
\fIcurl_easy_setopt\fP, you can change them. All options are set with the
17
\fIoption\fP followed by a \fIparameter\fP. That parameter can be a long, a
18
function pointer or an object pointer, all depending on what the specific
19
option expects. Read this manual carefully as bad input values may cause
20
libcurl to behave badly! You can only set one option in each function call. A
21
typical application uses many curl_easy_setopt() calls in the setup phase.
23
\fBNOTE:\fP strings passed to libcurl as 'char *' arguments, will not be
24
copied by the library. Instead you should keep them available until libcurl no
25
longer needs them. Failing to do so will cause very odd behavior or even
28
\fBNOTE2:\fP options set with this function call are valid for the forthcoming
29
data transfers that are performed when you invoke \fIcurl_easy_perform\fP.
30
The options are not in any way reset between transfers, so if you want
31
subsequent transfers with different options, you must change them between the
34
The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or
35
\fIcurl_easy_duphandle(3)\fP call.
37
The options are listed in a sort of random order, but you'll figure it out!
40
Data pointer to pass to the file write function. Note that if you specify the
41
\fICURLOPT_WRITEFUNCTION\fP, this is the pointer you'll get as input. If you
42
don't use a callback, you must pass a 'FILE *' as libcurl will pass this to
43
fwrite() when writing data.
45
\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use the
46
\fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience
49
.B CURLOPT_WRITEFUNCTION
50
Function pointer that should match the following prototype: \fBsize_t
51
function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This
52
function gets called by libcurl as soon as there is data available to pass
53
available that needs to be saved. The size of the data pointed to by \fIptr\fP
54
is \fIsize\fP multiplied with \fInmemb\fP. Return the number of bytes
55
actually taken care of. If that amount differs from the amount passed to your
56
function, it'll signal an error to the library and it will abort the transfer
57
and return \fICURLE_WRITE_ERROR\fP.
59
Set the \fIstream\fP argument with the \fBCURLOPT_FILE\fP option.
61
\fBNOTE:\fP you will be passed as much data as possible in all invokes, but
62
you cannot possibly make any assumptions. It may be one byte, it may be
66
Data pointer to pass to the file read function. Note that if you specify the
67
\fICURLOPT_READFUNCTION\fP, this is the pointer you'll get as input. If you
68
don't specify a read callback, this must be a valid FILE *.
70
\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use a
71
\fICURLOPT_READFUNCTION\fP if you set this option.
73
.B CURLOPT_READFUNCTION
74
Function pointer that should match the following prototype: \fBsize_t
75
function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This
76
function gets called by libcurl as soon as it needs to read data in order to
77
send it to the peer. The data area pointed at by the pointer \fIptr\fP may be
78
filled with at most \fIsize\fP multiplied with \fInmemb\fP number of
79
bytes. Your function must return the actual number of bytes that you stored in
80
that memory area. Returning 0 will signal end-of-file to the library and cause
81
it to stop the current transfer.
84
When uploading a file to a remote site, this option should be used to tell
85
libcurl what the expected size of the infile is.
88
The actual URL to deal with. The parameter should be a char * to a zero
89
terminated string. The string must remain present until curl no longer needs
90
it, as it doesn't copy the string.
92
\fBNOTE:\fP this option is (the only one) required to be set before
93
\fIcurl_easy_perform(3)\fP is called.
96
Set HTTP proxy to use. The parameter should be a char * to a zero terminated
97
string holding the host name or dotted IP address. To specify port number in
98
this string, append :[port] to the end of the host name. The proxy string may
99
be prefixed with [protocol]:// since any such prefix will be ignored. The
100
proxy's port number may optionally be specified with the separate option
101
\fICURLOPT_PROXYPORT\fP.
103
\fBNOTE:\fP when you tell the library to use a HTTP proxy, libcurl will
104
transparently convert operations to HTTP even if you specify a FTP URL
105
etc. This may have an impact on what other features of the library you can
106
use, such as CURLOPT_QUOTE and similar FTP specifics that don't work unless
107
you tunnel through the HTTP proxy. Such tunneling is activated with
108
\fICURLOPT_HTTPPROXYTUNNEL\fP.
110
\fBNOTE2:\fP libcurl respects the environment variables \fBhttp_proxy\fP,
111
\fBftp_proxy\fP, \fBall_proxy\fP etc, if any of those is set.
114
Pass a long with this option to set the proxy port to connect to unless it is
115
specified in the proxy string \fICURLOPT_PROXY\fP.
117
.B CURLOPT_HTTPPROXYTUNNEL
118
Set the parameter to non-zero to get the library to tunnel all operations
119
through a given HTTP proxy. Note that there is a big difference between using
120
a proxy and to tunnel through it. If you don't know what this means, you
121
probably don't want this tunneling option. (Added in libcurl 7.3)
124
Set the parameter to non-zero to get the library to display a lot of verbose
125
information about its operations. Very useful for libcurl and/or protocol
126
debugging and understanding.
128
You hardly ever want this set in production use, you will almost always want
129
this when you debug/report problems.
132
A non-zero parameter tells the library to include the header in the body
133
output. This is only relevant for protocols that actually have headers
134
preceding the data (like HTTP).
136
.B CURLOPT_NOPROGRESS
137
A non-zero parameter tells the library to shut of the built-in progress meter
140
\fBNOTE:\fP future versions of libcurl is likely to not have any built-in
141
progress meter at all.
144
A non-zero parameter tells the library to not include the body-part in the
145
output. This is only relevant for protocols that have separate header and body
148
.B CURLOPT_FAILONERROR
149
A non-zero parameter tells the library to fail silently if the HTTP code
150
returned is equal to or larger than 300. The default action would be to return
151
the page normally, ignoring that code.
154
A non-zero parameter tells the library to prepare for an upload. The
155
CURLOPT_INFILE and CURLOPT_INFILESIZE are also interesting for uploads.
158
A non-zero parameter tells the library to do a regular HTTP post. This is a
159
normal application/x-www-form-urlencoded kind, which is the most commonly used
160
one by HTML forms. See the CURLOPT_POSTFIELDS option for how to specify the
161
data to post and CURLOPT_POSTFIELDSIZE in how to set the data size. Starting
162
with libcurl 7.8, this option is obsolete. Using the CURLOPT_POSTFIELDS option
163
will imply this option.
165
.B CURLOPT_FTPLISTONLY
166
A non-zero parameter tells the library to just list the names of an ftp
167
directory, instead of doing a full directory listing that would include file
171
A non-zero parameter tells the library to append to the remote file instead of
172
overwrite it. This is only useful when uploading to a ftp site.
175
A non-zero parameter tells the library to scan your \fI~/.netrc\fP file to
176
find user name and password for the remote site you are about to access. Only
177
machine name, user name and password is taken into account (init macros and
178
similar things aren't supported).
180
\fBNote:\fP libcurl does not verify that the file has the correct properties
181
set (as the standard Unix ftp client does). It should only be readable by
184
.B CURLOPT_FOLLOWLOCATION
185
A non-zero parameter tells the library to follow any Location: header that the
186
server sends as part of a HTTP header.
188
\fBNOTE:\fP this means that the library will re-send the same request on the
189
new location and follow new Location: headers all the way until no more such
190
headers are returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number
191
of redirects libcurl will follow.
193
.B CURLOPT_TRANSFERTEXT
194
A non-zero parameter tells the library to use ASCII mode for ftp transfers,
195
instead of the default binary transfer. For LDAP transfers it gets the data in
196
plain text instead of HTML and for win32 systems it does not set the stdout to
197
binary mode. This option can be usable when transferring text data between
198
systems with different views on certain characters, such as newlines or
202
A non-zero parameter tells the library to use HTTP PUT to transfer data. The
203
data should be set with CURLOPT_INFILE and CURLOPT_INFILESIZE.
206
Pass a char * as parameter, which should be [user name]:[password] to use for
207
the connection. If the password is left out, you will be prompted for it.
208
\fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function.
210
.B CURLOPT_PROXYUSERPWD
211
Pass a char * as parameter, which should be [user name]:[password] to use for
212
the connection to the HTTP proxy. If the password is left out, you will be
213
prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own
217
Pass a char * as parameter, which should contain the specified range you
218
want. It should be in the format "X-Y", where X or Y may be left out. HTTP
219
transfers also support several intervals, separated with commas as in
220
\fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP
221
server to send the response document in pieces (using standard MIME separation
224
.B CURLOPT_ERRORBUFFER
225
Pass a char * to a buffer that the libcurl may store human readable error
226
messages in. This may be more helpful than just the return code from the
227
library. The buffer must be at least CURL_ERROR_SIZE big.
229
\fBNote:\fP if the library does not return an error, the buffer may not have
230
been touched. Do not rely on the contents in those cases.
233
Pass a long as parameter containing the maximum time in seconds that you allow
234
the libcurl transfer operation to take. Normally, name lookups can take a
235
considerable time and limiting operations to less than a few minutes risk
236
aborting perfectly normal operations. This option will cause curl to use the
237
SIGALRM to enable time-outing system calls.
239
\fBNOTE:\fP this does not work in Unix multi-threaded programs, as it uses
242
.B CURLOPT_POSTFIELDS
243
Pass a char * as parameter, which should be the full data to post in a HTTP
244
post operation. This is a normal application/x-www-form-urlencoded kind, which
245
is the most commonly used one by HTML forms. See also the CURLOPT_POST. Since
246
7.8, using CURLOPT_POSTFIELDS implies CURLOPT_POST.
248
\fBNote:\fP to make multipart/formdata posts (aka rfc1867-posts), check out
249
the \fICURLOPT_HTTPPOST\fP option.
251
.B CURLOPT_POSTFIELDSIZE
252
If you want to post data to the server without letting libcurl do a strlen()
253
to measure the data size, this option must be used. When this option is used
254
you can post fully binary data, which otherwise is likely to fail. If this
255
size is set to zero, the library will use strlen() to get the size. (Added in
259
Pass a pointer to a zero terminated string as parameter. It will be used to
260
set the Referer: header in the http request sent to the remote server. This
261
can be used to fool servers or scripts. You can also set any custom header
262
with \fICURLOPT_HTTPHEADER\fP.
265
Pass a pointer to a zero terminated string as parameter. It will be used to
266
set the User-Agent: header in the http request sent to the remote server. This
267
can be used to fool servers or scripts. You can also set any custom header
268
with \fICURLOPT_HTTPHEADER\fP.
271
Pass a pointer to a zero terminated string as parameter. It will be used to
272
get the IP address to use for the ftp PORT instruction. The PORT instruction
273
tells the remote server to connect to our specified IP address. The string may
274
be a plain IP address, a host name, an network interface name (under Unix) or
275
just a '-' letter to let the library use your systems default IP
276
address. Default FTP operations are passive, and thus won't use PORT.
278
.B CURLOPT_LOW_SPEED_LIMIT
279
Pass a long as parameter. It contains the transfer speed in bytes per second
280
that the transfer should be below during CURLOPT_LOW_SPEED_TIME seconds for
281
the library to consider it too slow and abort.
283
.B CURLOPT_LOW_SPEED_TIME
284
Pass a long as parameter. It contains the time in seconds that the transfer
285
should be below the CURLOPT_LOW_SPEED_LIMIT for the library to consider it too
288
.B CURLOPT_RESUME_FROM
289
Pass a long as parameter. It contains the offset in number of bytes that you
290
want the transfer to start from.
293
Pass a pointer to a zero terminated string as parameter. It will be used to
294
set a cookie in the http request. The format of the string should be
295
[NAME]=[CONTENTS]; Where NAME is the cookie name.
297
.B CURLOPT_HTTPHEADER
298
Pass a pointer to a linked list of HTTP headers to pass to the server in your
299
HTTP request. The linked list should be a fully valid list of \fBstruct
300
curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to
301
create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire
302
list. If you add a header that is otherwise generated and used by libcurl
303
internally, your added one will be used instead. If you add a header with no
304
contents as in 'Accept:' (no data on the right side of the colon), the
305
internally used header will get disabled. Thus, using this option you can add
306
new headers, replace internal headers and remove internal headers.
308
\fBNOTE:\fPThe most commonly replaced headers have "shortcuts" in the options
309
CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER.
312
Tells libcurl you want a multipart/formdata HTTP POST to be made and you
313
instruct what data to pass on to the server. Pass a pointer to a linked list
314
of HTTP post structs as parameter. The linked list should be a fully valid
315
list of 'struct HttpPost' structs properly filled in. The best and most
316
elegant way to do this, is to use \fIcurl_formadd(3)\fP as documented. The
317
data in this list must remained intact until you close this curl handle again
318
with \fIcurl_easy_cleanup(3)\fP.
321
Pass a pointer to a zero terminated string as parameter. The string should be
322
the file name of your certificate. The default format is "PEM" and can be
323
changed with \fICURLOPT_SSLCERTTYPE\fP.
325
.B CURLOPT_SSLCERTTYPE
326
Pass a pointer to a zero terminated string as parameter. The string should be
327
the format of your certificate. Supported formats are "PEM" and "DER". (Added
330
.B CURLOPT_SSLCERTPASSWD
331
Pass a pointer to a zero terminated string as parameter. It will be used as
332
the password required to use the CURLOPT_SSLCERT certificate. If the password
333
is not supplied, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can
334
be used to set your own prompt function.
336
\fBNOTE:\fPThis option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and only
337
cept for backward compatibility. You never needed a pass phrase to load
338
a certificate but you need one to load your private key.
341
Pass a pointer to a zero terminated string as parameter. The string should be
342
the file name of your private key. The default format is "PEM" and can be
343
changed with \fICURLOPT_SSLKEYTYPE\fP. (Added in 7.9.3)
345
.B CURLOPT_SSLKEYTYPE
346
Pass a pointer to a zero terminated string as parameter. The string should be
347
the format of your private key. Supported formats are "PEM", "DER" and "ENG".
350
\fBNOTE:\fPThe format "ENG" enables you to load the private key from a crypto
351
engine. in this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to
352
the engine. You have to set the crypto engine with \fICURLOPT_SSL_ENGINE\fP.
354
.B CURLOPT_SSLKEYASSWD
355
Pass a pointer to a zero terminated string as parameter. It will be used as
356
the password required to use the \fICURLOPT_SSLKEY\fP private key. If the
357
password is not supplied, you will be prompted for
358
it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function.
361
.B CURLOPT_SSL_ENGINE
362
Pass a pointer to a zero terminated string as parameter. It will be used as
363
the identifier for the crypto engine you want to use for your private
364
key. (Added in 7.9.3)
366
\fBNOTE:\fPIf the crypto device cannot be loaded,
367
\fICURLE_SSL_ENGINE_NOTFOUND\fP is returned.
369
.B CURLOPT_SSL_ENGINEDEFAULT
370
Sets the actual crypto engine as the default for (asymetric) crypto
371
operations. (Added in 7.9.3)
373
\fBNOTE:\fPIf the crypto device cannot be set,
374
\fICURLE_SSL_ENGINE_SETFAILED\fP is returned.
377
Convert Unix newlines to CRLF newlines on FTP uploads.
380
Pass a pointer to a linked list of FTP commands to pass to the server prior to
381
your ftp request. The linked list should be a fully valid list of 'struct
382
curl_slist' structs properly filled in. Use \fIcurl_slist_append(3)\fP to
383
append strings (commands) to the list, and clear the entire list afterwards
384
with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a
388
Pass a pointer to a linked list of FTP commands to pass to the server after
389
your ftp transfer request. The linked list should be a fully valid list of
390
struct curl_slist structs properly filled in as described for
391
\fICURLOPT_QUOTE\fP. Disable this operation again by setting a NULL to this
394
.B CURLOPT_WRITEHEADER
395
Pass a pointer to be used to write the header part of the received data to. If
396
you don't use your own callback to take care of the writing, this must be a
397
valid FILE *. See also the \fICURLOPT_HEADERFUNCTION\fP option below on how to set a
398
custom get-all-headers callback.
400
.B CURLOPT_HEADERFUNCTION
401
Function pointer that should match the following prototype: \fIsize_t
402
function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This
403
function gets called by libcurl as soon as there is received header data that
404
needs to be written down. The headers are guaranteed to be written one-by-one
405
and only complete lines are written. Parsing headers should be easy enough
406
using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP
407
multiplied with \fInmemb\fP. The pointer named \fIstream\fP will be the one
408
you passed to libcurl with the \fICURLOPT_WRITEHEADER\fP option. Return the
409
number of bytes actually written or return -1 to signal error to the library
410
(it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return
411
code). (Added in libcurl 7.7.2)
413
.B CURLOPT_COOKIEFILE
414
Pass a pointer to a zero terminated string as parameter. It should contain the
415
name of your file holding cookie data. The cookie data may be in Netscape /
416
Mozilla cookie data format or just regular HTTP-style headers dumped to a
419
.B CURLOPT_SSLVERSION
420
Pass a long as parameter. Set what version of SSL to attempt to use, 2 or
421
3. By default, the SSL library will try to solve this by itself although some
422
servers make this difficult why you at times may have to use this option.
424
.B CURLOPT_TIMECONDITION
425
Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE time value is
426
treated. You can set this parameter to TIMECOND_IFMODSINCE or
427
TIMECOND_IFUNMODSINCE. This is a HTTP-only feature. (TBD)
430
Pass a long as parameter. This should be the time in seconds since 1 jan 1970,
431
and the time will be used as specified in CURLOPT_TIMECONDITION or if that
432
isn't used, it will be TIMECOND_IFMODSINCE by default.
434
.B CURLOPT_CUSTOMREQUEST
435
Pass a pointer to a zero terminated string as parameter. It will be user
436
instead of GET or HEAD when doing the HTTP request. This is useful for doing
437
DELETE or other more or less obscure HTTP requests. Don't do this at will,
438
make sure your server supports the command first.
441
Pass a FILE * as parameter. This is the stream to use instead of stderr
442
internally when reporting errors.
445
Pass a char * as parameter. This set the interface name to use as outgoing
446
network interface. The name can be an interface name, an IP address or a host
447
name. (Added in libcurl 7.3)
450
Pass a char * as parameter. Set the krb4 security level, this also enables
451
krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or
452
\&'private'. If the string is set but doesn't match one of these, 'private'
453
will be used. Set the string to NULL to disable kerberos4. The kerberos
454
support only works for FTP. (Added in libcurl 7.3)
456
.B CURLOPT_PROGRESSFUNCTION
457
Function pointer that should match the \fIcurl_progress_callback\fP prototype
458
found in \fI<curl/curl.h>\fP. This function gets called by libcurl instead of
459
its internal equivalent with a frequent interval during data transfer.
460
Unknown/unused argument values will be set to zero (like if you only download
461
data, the upload size will remain 0). Returning a non-zero value from this
462
callback will cause libcurl to abort the transfer and return
463
\fICURLE_ABORTED_BY_CALLBACK\fP.
465
.B CURLOPT_PROGRESSDATA
466
Pass a pointer that will be untouched by libcurl and passed as the first
467
argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP.
469
.B CURLOPT_SSL_VERIFYPEER
470
Pass a long that is set to a non-zero value to make curl verify the peer's
471
certificate. The certificate to verify against must be specified with the
472
CURLOPT_CAINFO option. (Added in 7.4.2)
475
Pass a char * to a zero terminated file naming holding the certificate to
476
verify the peer with. This only makes sense when used in combination with the
477
CURLOPT_SSL_VERIFYPEER option. (Added in 7.4.2)
479
.B CURLOPT_PASSWDFUNCTION
480
Pass a pointer to a \fIcurl_passwd_callback\fP function that will be called
481
instead of the internal one if libcurl requests a password. The function must
482
match this prototype: \fBint my_getpass(void *client, char *prompt, char*
483
buffer, int buflen );\fP. If set to NULL, it equals to making the function
484
always fail. If the function returns a non-zero value, it will abort the
485
operation and an error (CURLE_BAD_PASSWORD_ENTERED) will be returned.
486
\fIclient\fP is a generic pointer, see \fICURLOPT_PASSWDDATA\fP. \fIprompt\fP
487
is a zero-terminated string that is text that prefixes the input request.
488
\fIbuffer\fP is a pointer to data where the entered password should be stored
489
and \fIbuflen\fP is the maximum number of bytes that may be written in the
490
buffer. (Added in 7.4.2)
492
.B CURLOPT_PASSWDDATA
493
Pass a void * to whatever data you want. The passed pointer will be the first
494
argument sent to the specifed \fICURLOPT_PASSWDFUNCTION\fP function. (Added in
498
Pass a long. If it is a non-zero value, libcurl will attempt to get the
499
modification date of the remote document in this operation. This requires that
500
the remote server sends the time or replies to a time querying command. The
501
\fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME\fP argument
502
can be used after a transfer to extract the received time (if any). (Added in
506
Pass a long. The set number will be the redirection limit. If that many
507
redirections have been followed, the next redirect will cause an error
508
(\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the
509
\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. (Added in 7.5)
511
.B CURLOPT_MAXCONNECTS
512
Pass a long. The set number will be the persistant connection cache size. The
513
set amount will be the maximum amount of simultaneous connections that libcurl
514
may cache between file transfers. Default is 5, and there isn't much point in
515
changing this value unless you are perfectly aware of how this work and
516
changes libcurl's behaviour.
518
\fBNOTE:\fP if you already have performed transfers with this curl handle,
519
setting a smaller MAXCONNECTS than before may cause open connections to get
520
closed unnecessarily. (Added in 7.7)
522
.B CURLOPT_CLOSEPOLICY
523
Pass a long. This option sets what policy libcurl should use when the
524
connection cache is filled and one of the open connections has to be closed to
525
make room for a new connection. This must be one of the CURLCLOSEPOLICY_*
526
defines. Use \fICURLCLOSEPOLICY_LEAST_RECENTLY_USED\fP to make libcurl close
527
the connection that was least recently used, that connection is also least
528
likely to be capable of re-use. Use \fICURLCLOSEPOLICY_OLDEST\fP to make
529
libcurl close the oldest connection, the one that was created first among the
530
ones in the connection cache. The other close policies are not support
533
.B CURLOPT_FRESH_CONNECT
534
Pass a long. Set to non-zero to make the next transfer use a new (fresh)
535
connection by force. If the connection cache is full before this connection,
536
one of the existing connections will be closed as according to the selected or
537
default policy. This option should be used with caution and only if you
538
understand what it does. Set this to 0 to have libcurl attempt re-using an
539
existing connection (default behavior). (Added in 7.7)
541
.B CURLOPT_FORBID_REUSE
542
Pass a long. Set to non-zero to make the next transfer explicitly close the
543
connection when done. Normally, libcurl keep all connections alive when done
544
with one transfer in case there comes a succeeding one that can re-use them.
545
This option should be used with caution and only if you understand what it
546
does. Set to 0 to have libcurl keep the connection open for possibly later
547
re-use (default behavior). (Added in 7.7)
549
.B CURLOPT_RANDOM_FILE
550
Pass a char * to a zero terminated file name. The file will be used to read
551
from to seed the random engine for SSL. The more random the specified file is,
552
the more secure will the SSL connection become.
555
Pass a char * to the zero terminated path name to the Entropy Gathering Daemon
556
socket. It will be used to seed the random engine for SSL.
558
.B CURLOPT_CONNECTTIMEOUT
559
Pass a long. It should contain the maximum time in seconds that you allow the
560
connection to the server to take. This only limits the connection phase, once
561
it has connected, this option is of no more use. Set to zero to disable
562
connection timeout (it will then only timeout on the system's internal
563
timeouts). See also the \fICURLOPT_TIMEOUT\fP option.
565
\fBNOTE:\fP this does not work in unix multi-threaded programs, as it uses
569
Pass a long. If the long is non-zero, this forces the HTTP request to get back
570
to GET. Only really usable if POST, PUT or a custom request have been used
571
previously using the same curl handle. (Added in 7.8.1)
573
.B CURLOPT_SSL_VERIFYHOST
574
Pass a long. Set if we should verify the Common name from the peer certificate
575
in the SSL handshake, set 1 to check existence, 2 to ensure that it matches
576
the provided hostname. (Added in 7.8.1)
579
Pass a file name as char *, zero terminated. This will make libcurl dump all
580
internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP
581
is called. If no cookies are known, no file will be created. Specify "-" to
582
instead have the cookies written to stdout.
584
.B CURLOPT_SSL_CIPHER_LIST
585
Pass a char *, pointing to a zero terminated string holding the list of
586
ciphers to use for the SSL connection. The list must be syntactly correct, it
587
consists of one or more cipher strings separated by colons. Commas or spaces
588
are also acceptable separators but colons are normally used, \!, \- and \+ can
589
be used as operators. Valid examples of cipher lists include 'RC4-SHA',
590
\'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you
593
You'll find more details about cipher lists on this URL:
594
\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP
596
.B CURLOPT_HTTP_VERSION
597
Pass a long, set to one of the values described below. They force libcurl to
598
use the specific HTTP versions. This is not sensible to do unless you have a
602
.B CURL_HTTP_VERSION_NONE
603
We don't care about what version the library uses. libcurl will use whatever
606
.B CURL_HTTP_VERSION_1_0
607
Enforce HTTP 1.0 requests.
609
.B CURL_HTTP_VERSION_1_1
610
Enforce HTTP 1.1 requests.
613
.B CURLOPT_FTP_USE_EPSV
614
Pass a long. If the value is non-zero, it tells curl to use the EPSV command
615
when doing passive FTP downloads (which is always does by default). Using EPSV
616
means that it will first attempt to use EPSV before using PASV, but if you
617
pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV.
620
CURLE_OK (zero) means that the option was set properly, non-zero means an
621
error occurred as \fI<curl/curl.h>\fP defines.
623
.BR curl_easy_init "(3), " curl_easy_cleanup "(3), "
625
If you find any bugs, or just have questions, subscribe to one of the mailing
626
lists and post. We won't bite.
added
removed
docs/libcurl/curl_easy_setopt.3
