5
5
.\" * | (__| |_| | _ <| |___
6
6
.\" * \___|\___/|_| \_\_____|
8
.\" * Copyright (C) 1998 - 2005, Daniel Stenberg, <daniel@haxx.se>, et al.
8
.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, <daniel@haxx.se>, et al.
10
10
.\" * This software is licensed as described in the file COPYING, which
11
11
.\" * you should have received as part of this distribution. The terms
18
18
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19
19
.\" * KIND, either express or implied.
21
.\" * $Id: curl_easy_setopt.3,v 1.136 2005/11/17 14:29:54 bagder Exp $
21
.\" * $Id: curl_easy_setopt.3,v 1.149 2006-05-24 22:46:39 bagder Exp $
22
22
.\" **************************************************************************
24
.TH curl_easy_setopt 3 "27 Oct 2005" "libcurl 7.14.2" "libcurl Manual"
24
.TH curl_easy_setopt 3 "19 Apr 2006" "libcurl 7.15.4" "libcurl Manual"
26
curl_easy_setopt - set options for a curl easy handle
26
curl_easy_setopt \- set options for a curl easy handle
28
28
#include <curl/curl.h>
169
169
.IP CURLOPT_PROGRESSFUNCTION
170
170
Function pointer that should match the \fIcurl_progress_callback\fP prototype
171
171
found in \fI<curl/curl.h>\fP. This function gets called by libcurl instead of
172
its internal equivalent with a frequent interval during data transfer.
173
Unknown/unused argument values will be set to zero (like if you only download
174
data, the upload size will remain 0). Returning a non-zero value from this
175
callback will cause libcurl to abort the transfer and return
176
\fICURLE_ABORTED_BY_CALLBACK\fP.
172
its internal equivalent with a frequent interval during data transfer (roughly
173
once per second). Unknown/unused argument values pass to the callback will be
174
set to zero (like if you only download data, the upload size will remain
175
0). Returning a non-zero value from this callback will cause libcurl to abort
176
the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
178
If you transfer data with the multi interface, this function will not be
179
called during periods of idleness unless you call the appropriate libcurl
180
function that performs transfers. Usage of the \fBCURLOPT_PROGRESSFUNCTION\fP
181
callback is not recommended when using the multi interface.
178
183
\fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this function actually
258
263
Data pointer to pass to the ssl context callback set by the option
259
264
\fICURLOPT_SSL_CTX_FUNCTION\fP, this is the pointer you'll get as third
260
265
parameter, otherwise \fBNULL\fP. (Added in 7.11.0)
266
.IP CURLOPT_CONV_TO_NETWORK_FUNCTION
267
.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION
268
.IP CURLOPT_CONV_FROM_UTF8_FUNCTION
269
Function pointers that should match the following prototype: CURLcode
270
function(char *ptr, size_t length);
272
These three options apply to non-ASCII platforms only. They are available
273
only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. When
274
this is the case, \fIcurl_version_info(3)\fP will return the CURL_VERSION_CONV
277
The data to be converted is in a buffer pointed to by the ptr parameter. The
278
amount of data to convert is indicated by the length parameter. The converted
279
data overlays the input data in the buffer pointed to by the ptr parameter.
280
CURLE_OK should be returned upon successful conversion. A CURLcode return
281
value defined by curl.h, such as CURLE_CONV_FAILED, should be returned if an
282
error was encountered.
284
\fBCURLOPT_CONV_TO_NETWORK_FUNCTION\fP and
285
\fBCURLOPT_CONV_FROM_NETWORK_FUNCTION\fP convert between the host encoding and
286
the network encoding. They are used when commands or ASCII data are
287
sent/received over the network.
289
\fBCURLOPT_CONV_FROM_UTF8_FUNCTION\fP is called to convert from UTF8 into the
290
host encoding. It is required only for SSL processing.
292
If you set a callback pointer to NULL, or don't set it at all, the built-in
293
libcurl iconv functions will be used. If HAVE_ICONV was not defined when
294
libcurl was built, and no callback has been established, conversion will
295
return the CURLE_CONV_REQD error code.
297
If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined.
300
\&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
302
The iconv code in libcurl will default the network and UTF8 codeset names as
305
\&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
307
\&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
309
You will need to override these definitions if they are different on your
261
311
.SH ERROR OPTIONS
262
312
.IP CURLOPT_ERRORBUFFER
263
313
Pass a char * to a buffer that the libcurl may store human readable error
275
325
when showing the progress meter and displaying \fICURLOPT_VERBOSE\fP data.
276
326
.IP CURLOPT_FAILONERROR
277
327
A non-zero parameter tells the library to fail silently if the HTTP code
278
returned is equal to or larger than 300. The default action would be to return
328
returned is equal to or larger than 400. The default action would be to return
279
329
the page normally, ignoring that code.
280
330
.SH NETWORK OPTIONS
290
340
\fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed info
291
341
on which protocols that are supported.
293
\fICURLOPT_URL\fP is the only option that must be set before
343
The string given to CURLOPT_URL must be url-encoded and following the RFC 2396
344
(http://curl.haxx.se/rfc/rfc2396.txt).
346
\fICURLOPT_URL\fP is the only option that \fBmust\fP be set before
294
347
\fIcurl_easy_perform(3)\fP is called.
295
348
.IP CURLOPT_PROXY
296
349
Set HTTP proxy to use. The parameter should be a char * to a zero terminated
319
372
specified in the proxy string \fICURLOPT_PROXY\fP.
320
373
.IP CURLOPT_PROXYTYPE
321
374
Pass a long with this option to set type of the proxy. Available options for
322
this are \fICURLPROXY_HTTP\fP and \fICURLPROXY_SOCKS5\fP, with the HTTP one
323
being default. (Added in 7.10)
375
this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2)
376
\fICURLPROXY_SOCKS5\fP. The HTTP type is default. (Added in 7.10)
324
377
.IP CURLOPT_HTTPPROXYTUNNEL
325
378
Set the parameter to non-zero to get the library to tunnel all operations
326
379
through a given HTTP proxy. There is a big difference between using a proxy
330
383
Pass a char * as parameter. This set the interface name to use as outgoing
331
384
network interface. The name can be an interface name, an IP address or a host
386
.IP CURLOPT_LOCALPORT
387
Pass a long. This sets the local port number of the socket used for
388
connection. This can be used in combination with \fICURLOPT_INTERFACE\fP and
389
you are recommended to use \fICURLOPT_LOCALPORTRANGE\fP as well when this is
390
set. Note that port numbers are only valid 1 - 65535. (Added in 7.15.2)
391
.IP CURLOPT_LOCALPORTRANGE
392
Pass a long. This is the number of attempts libcurl should do to find a
393
working local port number. It starts with the given \fICURLOPT_LOCALPORT\fP
394
and adds one to the number for each retry. Setting this value to 1 or below
395
will make libcurl do only one try for exact port number. Note that port
396
numbers by nature is a scarce resource that will be busy at times so setting
397
this value to something too low might cause unnecessary connection setup
398
failures. (Added in 7.15.2)
333
399
.IP CURLOPT_DNS_CACHE_TIMEOUT
334
400
Pass a long, this sets the timeout in seconds. Name resolves will be kept in
335
401
memory for this number of seconds. Set to zero (0) to completely disable
615
681
internally, your added one will be used instead. If you add a header with no
616
682
contents as in 'Accept:' (no data on the right side of the colon), the
617
683
internally used header will get disabled. Thus, using this option you can add
618
new headers, replace internal headers and remove internal headers. The
619
headers included in the linked list must not be CRLF-terminated, because
620
curl adds CRLF after each header item. Failure to comply with this will
621
result in strange bugs because the server will most likely ignore part
622
of the headers you specified.
684
new headers, replace internal headers and remove internal headers. To add a
685
header with no contents, make the contents be two quotes: \&"". The headers
686
included in the linked list must not be CRLF-terminated, because curl adds
687
CRLF after each header item. Failure to comply with this will result in
688
strange bugs because the server will most likely ignore part of the headers
624
The first line in a request (usually containing a GET or POST) is not a header
625
and cannot be replaced using this option. Only the lines following the
626
request-line are headers.
691
The first line in a request (containing the method, usually a GET or POST) is
692
not a header and cannot be replaced using this option. Only the lines
693
following the request-line are headers. Adding this method line in this list
694
of headers will only cause your request to send an invalid header.
628
696
Pass a NULL to this to reset back to no custom headers.
694
762
format or just regular HTTP-style header (Set-Cookie: ...) format. If cURL
695
763
cookie engine was not enabled it will enable its cookie engine. Passing a
696
764
magic string \&"ALL" will erase all cookies known by cURL. (Added in 7.14.1)
765
Passing the special string \&"SESS" will only erase all session cookies known
766
by cURL. (Added in 7.15.4)
697
767
.IP CURLOPT_HTTPGET
698
768
Pass a long. If the long is non-zero, this forces the HTTP request to get back
699
769
to GET. usable if a POST, HEAD, PUT or a custom request have been used
838
908
Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP
839
909
server asks for "account data" after user name and password has been provided,
840
910
this data is sent off using the ACCT command. (Added in 7.13.0)
911
.IP CURLOPT_FTP_FILEMETHOD
912
Pass a long that should have one of the following values. This option controls
913
what method libcurl should use to reach a file on a FTP(S) server. The
914
argument should be one of the following alternatives:
916
.IP CURLFTPMETHOD_MULTICWD
917
libcurl does a single CWD operation for each path part in the given URL. For
918
deep hierarchies this means very many commands. This is how RFC1738 says it
919
should be done. This is the default but the slowest behavior.
920
.IP CURLFTPMETHOD_NOCWD
921
libcurl does no CWD at all. libcurl will do SIZE, RETR, STOR etc and give a
922
full path to the server for all these commands. This is the fastest behavior.
923
.IP CURLFTPMETHOD_SINGLECWD
924
libcurl does one CWD with the full target directory and then operates on the
925
file \&"normally" (like in the multicwd case). This is somewhat more standards
926
compliant than 'nocwd' but without the full penalty of 'multicwd'.
841
928
.SH PROTOCOL OPTIONS
842
929
.IP CURLOPT_TRANSFERTEXT
843
930
A non-zero parameter tells the library to use ASCII mode for ftp transfers,
1024
1111
.IP CURL_IPRESOLVE_V6
1025
1112
Resolve to ipv6 addresses.
1114
.SH CURLOPT_CONNECT_ONLY
1115
Pass a long. A non-zero parameter tells the library to perform any required
1116
proxy authentication and connection setup, but no data transfer.
1118
This option is useful with the \fICURLINFO_LASTSOCKET\fP option to
1119
\fIcurl_easy_getinfo(3)\fP. The library can set up the connection and then the
1120
application can obtain the most recently used socket for special data
1121
transfers. (Added in 7.15.2)
1027
1122
.SH SSL and SECURITY OPTIONS
1028
1123
.IP CURLOPT_SSLCERT
1029
1124
Pass a pointer to a zero terminated string as parameter. The string should be
1114
1209
combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If
1115
1210
\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_CAINFO\fP need not
1116
1211
even indicate an accessible file.
1213
Note that option is by default set to the system path where libcurl's cacert
1214
bundle is assumed to be stored, as established at build time.
1117
1215
.IP CURLOPT_CAPATH
1118
1216
Pass a char * to a zero terminated string naming a directory holding
1119
1217
multiple CA certificates to verify the peer with. The certificate
added
removed
docs/libcurl/curl_easy_setopt.3
