~ubuntu-branches/ubuntu/lucid/curl/lucid-201101212007

If you're using libcurl as a win32 DLL, you MUST use a <a class="emphasis" href="#CURLOPTREADFUNCTION">CURLOPT_READFUNCTION</a> if you set this option.

This option is also known with the older name CURLOPT_INFILE, the name <a class="emphasis" href="#CURLOPTREADDATA">CURLOPT_READDATA</a> was introduced in 7.9.7.

<a name="CURLOPTIOCTLFUNCTION"></a>CURLOPT_IOCTLFUNCTION

Function pointer that should match the curl_ioctl_callback prototype found in <curl/curl.h>. This function gets called by libcurl when something special I/O-related needs to be done that the library can't do by itself. For now, rewinding the read data stream is the only action it can request. The rewinding of the read data stream may be necessary when doing a HTTP PUT or POST with a multi-pass authentication method. (Opion added in 7.12.3)

<a name="CURLOPTIOCTLDATA"></a>CURLOPT_IOCTLDATA

Pass a pointer that will be untouched by libcurl and passed as the 3rd argument in the ioctl callback set with <a class="emphasis" href="#CURLOPTIOCTLFUNCTION">CURLOPT_IOCTLFUNCTION</a>. (Option added in 7.12.3)

<a name="CURLOPTSOCKOPTFUNCTION"></a>CURLOPT_SOCKOPTFUNCTION

Function pointer that should match the curl_sockopt_callback prototype found in <curl/curl.h>. This function gets called by libcurl after the socket() call but before the connect() call. The callback's purpose argument identifies the exact purpose for this particular socket, and currently only one value is supported: CURLSOCKTYPE_IPCXN for the primary connection (meaning the control connection in the FTP case). Future versions of libcurl may support more purposes. It passes the newly created socket descriptor so additional setsockopt() calls can be done at the user's discretion. A non-zero return code from the callback function will signal an unrecoverable error to the library and it will close the socket and return CURLE_COULDNT_CONNECT. (Option added in 7.15.6.)

<a name="CURLOPTSOCKOPTDATA"></a>CURLOPT_SOCKOPTDATA

Pass a pointer that will be untouched by libcurl and passed as the first argument in the sockopt callback set with <a class="emphasis" href="#CURLOPTSOCKOPTFUNCTION">CURLOPT_SOCKOPTFUNCTION</a>. (Option added in 7.15.6.)

<a name="CURLOPTPROGRESSFUNCTION"></a>CURLOPT_PROGRESSFUNCTION

Function pointer that should match the curl_progress_callback prototype found in <curl/curl.h>. This function gets called by libcurl instead of its internal equivalent with a frequent interval during operation (roughly once per second) no matter if data is being transfered or not. Unknown/unused argument values passed to the callback will be set to zero (like if you only download data, the upload size will remain 0). Returning a non-zero value from this callback will cause libcurl to abort the transfer and return CURLE_ABORTED_BY_CALLBACK.

If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl function that performs transfers. Usage of the <a class="bold" href="#CURLOPTPROGRESSFUNCTION">CURLOPT_PROGRESSFUNCTION</a> callback is not recommended when using the multi interface.

148

152

<a name="CURLOPTSTDERR"></a>CURLOPT_STDERR

149

153

Pass a FILE * as parameter. Tell libcurl to use this stream instead of stderr when showing the progress meter and displaying <a class="emphasis" href="#CURLOPTVERBOSE">CURLOPT_VERBOSE</a> data.

150

154

<a name="CURLOPTFAILONERROR"></a>CURLOPT_FAILONERROR

151

A non-zero parameter tells the library to fail silently if the HTTP code returned is equal to or larger than 400. The default action would be to return the page normally, ignoring that code. <a name="NETWORK"></a><h2 class="nroffsh">NETWORK OPTIONS</h2>

155

156

This method is not fail-safe and there are occasions where non-succesful response codes will slip through, especially when authentication is involved (response codes 401 and 407).

157

You might get some amounts of headers transferred before this situation is detected, like for when a "100-continue" is received as a response to a POST/PUT and a 401 or 407 is received immediately afterwards. <a name="NETWORK"></a><h2 class="nroffsh">NETWORK OPTIONS</h2>

152

158

153

159

<a name="CURLOPTURL"></a>CURLOPT_URL

154

160

The actual URL to deal with. The parameter should be a char * to a zero terminated string. The string must remain present until curl no longer needs it, as it doesn't copy the string.

159

165

Set HTTP proxy to use. The parameter should be a char * to a zero terminated string holding the host name or dotted IP address. To specify port number in this string, append :[port] to the end of the host name. The proxy string may be prefixed with [protocol]:// since any such prefix will be ignored. The proxy's port number may optionally be specified with the separate option <a class="emphasis" href="#CURLOPTPROXYPORT">CURLOPT_PROXYPORT</a>.

160

166

When you tell the library to use an HTTP proxy, libcurl will transparently convert operations to HTTP even if you specify an FTP URL etc. This may have an impact on what other features of the library you can use, such as <a class="emphasis" href="#CURLOPTQUOTE">CURLOPT_QUOTE</a> and similar FTP specifics that don't work unless you tunnel through the HTTP proxy. Such tunneling is activated with <a class="emphasis" href="#CURLOPTHTTPPROXYTUNNEL">CURLOPT_HTTPPROXYTUNNEL</a>.

161

167

libcurl respects the environment variables http_proxy, ftp_proxy, all_proxy etc, if any of those is set. The <a class="emphasis" href="#CURLOPTPROXY">CURLOPT_PROXY</a> option does however override any possibly set environment variables.

162

Starting with 7.14.1, the proxy host string can be specified the exact same way as the proxy environment variables, include protocol prefix (http://) and embedded user + password.

168

Setting the proxy string to "" (an empty string) will explicitly disable the use of a proxy, even if there is an environment variable set for it.

169

Since 7.14.1, the proxy host string given in environment variables can be specified the exact same way as the proxy can be set with <a class="emphasis" href="#CURLOPTPROXY">CURLOPT_PROXY</a>, include protocol prefix (http://) and embedded user + password.

163

170

<a name="CURLOPTPROXYPORT"></a>CURLOPT_PROXYPORT

164

171

Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string <a class="emphasis" href="#CURLOPTPROXY">CURLOPT_PROXY</a>.

165

172

<a name="CURLOPTPROXYTYPE"></a>CURLOPT_PROXYTYPE

310

317

Enforce HTTP 1.1 requests.

311

318

<a name="CURLOPTIGNORECONTENTLENGTH"></a>CURLOPT_IGNORE_CONTENT_LENGTH

312

319

Ignore the Content-Length header. This is useful for Apache 1.x (and similar servers) which will report incorrect content length for files over 2 gigabytes. If this option is used, curl will not be able to accurately report progress, and will simply stop the download when the server ends the connection. (added in 7.14.1)

320

<a name="CURLOPTHTTPCONTENTDECODING"></a>CURLOPT_HTTP_CONTENT_DECODING

321

Pass a long to tell libcurl how to act on content decoding. If set to zero, content decoding will be disabled. If set to 1 it is enabled. Note however that libcurl has no default content decoding but requires you to use <a class="emphasis" href="#CURLOPTENCODING">CURLOPT_ENCODING</a> for that. (added in 7.16.2)

322

<a name="CURLOPTHTTPTRANSFERDECODING"></a>CURLOPT_HTTP_TRANSFER_DECODING

323

Pass a long to tell libcurl how to act on transfer decoding. If set to zero, transfer decoding will be disabled, if set to 1 it is enabled (default). libcurl does chunked transfer decoding by default unless this option is set to zero. (added in 7.16.2)

313

324

<a name="FTP"></a><h2 class="nroffsh">FTP OPTIONS</h2>

314

325

315

326

<a name="CURLOPTFTPPORT"></a>CURLOPT_FTPPORT

320

331

<a name="CURLOPTPOSTQUOTE"></a>CURLOPT_POSTQUOTE

321

332

Pass a pointer to a linked list of FTP commands to pass to the server after your ftp transfer request. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for <a class="emphasis" href="#CURLOPTQUOTE">CURLOPT_QUOTE</a>. Disable this operation again by setting a NULL to this option.

322

333

<a name="CURLOPTPREQUOTE"></a>CURLOPT_PREQUOTE

323

Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for <a class="emphasis" href="#CURLOPTQUOTE">CURLOPT_QUOTE</a>. Disable this operation again by setting a NULL to this option.

334

324

335

<a name="CURLOPTFTPLISTONLY"></a>CURLOPT_FTPLISTONLY

325

336

A non-zero parameter tells the library to just list the names of an ftp directory, instead of doing a full directory listing that would include file sizes, dates etc.

326

337

This causes an FTP NLST command to be sent. Beware that some FTP servers list only files in their response to NLST; they might not include subdirectories and symbolic links.

363

374

<a name="CURLFTPAUTHTLS"></a>CURLFTPAUTH_TLS

364

375

Try "AUTH TLS" first, and only if that fails try "AUTH SSL"

365

376

366

<a name="CURLOPTSOURCEURL"></a>CURLOPT_SOURCE_URL

367

When set, it enables a FTP third party transfer, using the set URL as source, while <a class="emphasis" href="#CURLOPTURL">CURLOPT_URL</a> is the target.

368

<a name="CURLOPTSOURCEUSERPWD"></a>CURLOPT_SOURCE_USERPWD

369

Set "username:password" to use for the source connection when doing FTP third party transfers.

370

<a name="CURLOPTSOURCEQUOTE"></a>CURLOPT_SOURCE_QUOTE

371

Exactly like <a class="emphasis" href="#CURLOPTQUOTE">CURLOPT_QUOTE</a>, but for the source host.

372

<a name="CURLOPTSOURCEPREQUOTE"></a>CURLOPT_SOURCE_PREQUOTE

373

Exactly like <a class="emphasis" href="#CURLOPTPREQUOTE">CURLOPT_PREQUOTE</a>, but for the source host.

374

<a name="CURLOPTSOURCEPOSTQUOTE"></a>CURLOPT_SOURCE_POSTQUOTE

375

Exactly like <a class="emphasis" href="#CURLOPTPOSTQUOTE">CURLOPT_POSTQUOTE</a>, but for the source host.

377

<a name="CURLOPTFTPSSLCCC"></a>CURLOPT_FTP_SSL_CCC

378

If enabled, this option makes libcurl use CCC (Clear Command Channel). It shuts down the SSL/TLS layer after authenticating. The rest of the control channel communication will be unencrypted. This allows NAT routers to follow the FTP transaction. Pass a long using one of the values below. (Added in 7.16.1)

379

380

<a name="CURLFTPSSLCCCNONE"></a>CURLFTPSSL_CCC_NONE

381

Don't attempt to use CCC.

382

<a name="CURLFTPSSLCCCPASSIVE"></a>CURLFTPSSL_CCC_PASSIVE

383

Do not initiate the shutdown, but wait for the server to do it. Do not send a reply.

384

<a name="CURLFTPSSLCCCACTIVE"></a>CURLFTPSSL_CCC_ACTIVE

385

Initiate the shutdown and wait for a reply.

386

376

387

<a name="CURLOPTFTPACCOUNT"></a>CURLOPT_FTP_ACCOUNT

377

388

Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP server asks for "account data" after user name and password has been provided, this data is sent off using the ACCT command. (Added in 7.13.0)

378

389

<a name="CURLOPTFTPFILEMETHOD"></a>CURLOPT_FTP_FILEMETHOD

394

405

<a name="CURLOPTRANGE"></a>CURLOPT_RANGE

395

406

Pass a char * as parameter, which should contain the specified range you want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in "X-Y,N-M". Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation techniques). Pass a NULL to this option to disable the use of ranges.

396

407

<a name="CURLOPTRESUMEFROM"></a>CURLOPT_RESUME_FROM

397

408

Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. Set this option to 0 to make the transfer start from the beginning (effectively disabling resume). For FTP, set this option to -1 to make the transfer start from the end of the target file (useful to continue an interrupted upload).

398

409

<a name="CURLOPTRESUMEFROMLARGE"></a>CURLOPT_RESUME_FROM_LARGE

399

410

Pass a curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0)

400

411

<a name="CURLOPTCUSTOMREQUEST"></a>CURLOPT_CUSTOMREQUEST

408

419

To change request to GET, you should use <a class="emphasis" href="#CURLOPTHTTPGET">CURLOPT_HTTPGET</a>. Change request to POST with <a class="emphasis" href="#CURLOPTPOST">CURLOPT_POST</a> etc.

409

420

<a name="CURLOPTINFILESIZE"></a>CURLOPT_INFILESIZE

410

421

When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed as a long. See also <a class="emphasis" href="#CURLOPTINFILESIZELARGE">CURLOPT_INFILESIZE_LARGE</a>.

422

Note that this option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns.

411

423

<a name="CURLOPTINFILESIZELARGE"></a>CURLOPT_INFILESIZE_LARGE

412

424

When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed as a curl_off_t. (Added in 7.11.0)

425

Note that this option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns.

413

426

<a name="CURLOPTUPLOAD"></a>CURLOPT_UPLOAD

414

A non-zero parameter tells the library to prepare for an upload. The <a class="emphasis" href="#CURLOPTREADDATA">CURLOPT_READDATA</a> and CURLOPT_INFILESIZEE or <a class="emphasis" href="#CURLOPTINFILESIZELARGE">CURLOPT_INFILESIZE_LARGE</a> are also interesting for uploads. If the protocol is HTTP, uploading means using the PUT request unless you tell libcurl otherwise.

427

A non-zero parameter tells the library to prepare for an upload. The <a class="emphasis" href="#CURLOPTREADDATA">CURLOPT_READDATA</a> and <a class="emphasis" href="#CURLOPTINFILESIZE">CURLOPT_INFILESIZE</a> or <a class="emphasis" href="#CURLOPTINFILESIZELARGE">CURLOPT_INFILESIZE_LARGE</a> options are also interesting for uploads. If the protocol is HTTP, uploading means using the PUT request unless you tell libcurl otherwise.

415

428

Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with <a class="emphasis" href="#CURLOPTHTTPHEADER">CURLOPT_HTTPHEADER</a> as usual.

416

429

If you use PUT to a HTTP 1.1 server, you can upload data without knowing the size before starting the transfer if you use chunked encoding. You enable this by adding a header like "Transfer-Encoding: chunked" with <a class="emphasis" href="#CURLOPTHTTPHEADER">CURLOPT_HTTPHEADER</a>. With HTTP 1.0 or without chunked transfer, you must specify the size.

417

430

<a name="CURLOPTMAXFILESIZE"></a>CURLOPT_MAXFILESIZE

429

442

<a name="CURLOPTTIMEOUT"></a>CURLOPT_TIMEOUT

430

443

Pass a long as parameter containing the maximum time in seconds that you allow the libcurl transfer operation to take. Normally, name lookups can take a considerable time and limiting operations to less than a few minutes risk aborting perfectly normal operations. This option will cause curl to use the SIGALRM to enable time-outing system calls.

431

444

In unix-like systems, this might cause signals to be used unless <a class="emphasis" href="#CURLOPTNOSIGNAL">CURLOPT_NOSIGNAL</a> is set.

445

<a name="CURLOPTTIMEOUTMS"></a>CURLOPT_TIMEOUT_MS

446

Like <a class="emphasis" href="#CURLOPTTIMEOUT">CURLOPT_TIMEOUT</a> but takes number of milliseconds instead. If libcurl is built to use the standard system name resolver, that part will still use full-second resolution for timeouts. (Added in 7.16.2)

432

447

<a name="CURLOPTLOWSPEEDLIMIT"></a>CURLOPT_LOW_SPEED_LIMIT

433

448

Pass a long as parameter. It contains the transfer speed in bytes per second that the transfer should be below during <a class="emphasis" href="#CURLOPTLOWSPEEDTIME">CURLOPT_LOW_SPEED_TIME</a> seconds for the library to consider it too slow and abort.

434

449

<a name="CURLOPTLOWSPEEDTIME"></a>CURLOPT_LOW_SPEED_TIME

435

450

Pass a long as parameter. It contains the time in seconds that the transfer should be below the <a class="emphasis" href="#CURLOPTLOWSPEEDLIMIT">CURLOPT_LOW_SPEED_LIMIT</a> for the library to consider it too slow and abort.

436

451

<a name="CURLOPTMAXSENDSPEEDLARGE"></a>CURLOPT_MAX_SEND_SPEED_LARGE

437

Pass a curl_off_t as parameter. If an upload exceeds this speed on cumulative average during the transfer, the transfer will pause to keep the average rate less than or equal to the parameter value. (default: 0, unlimited)

452

438

453

<a name="CURLOPTMAXRECVSPEEDLARGE"></a>CURLOPT_MAX_RECV_SPEED_LARGE

439

454

Pass a curl_off_t as parameter. If a download exceeds this speed on cumulative average during the transfer, the transfer will pause to keep the average rate less than or equal to the parameter value. Defaults to unlimited speed. (Added in 7.15.5)

440

455

<a name="CURLOPTMAXCONNECTS"></a>CURLOPT_MAXCONNECTS

441

456

Pass a long. The set number will be the persistent connection cache size. The set amount will be the maximum amount of simultaneously open connections that libcurl may cache. Default is 5, and there isn't much point in changing this value unless you are perfectly aware of how this work and changes libcurl's behaviour. This concerns connection using any of the protocols that support persistent connections.

442

When reaching the maximum limit, curl uses the <a class="emphasis" href="#CURLOPTCLOSEPOLICY">CURLOPT_CLOSEPOLICY</a> to figure out which of the existing connections to close to prevent the number of open connections to increase.

457

When reaching the maximum limit, curl closes the oldest one in the cache to prevent the number of open connections to increase.

443

458

If you already have performed transfers with this curl handle, setting a smaller MAXCONNECTS than before may cause open connections to get closed unnecessarily.

444

459

<a name="CURLOPTCLOSEPOLICY"></a>CURLOPT_CLOSEPOLICY

445

Pass a long. This option sets what policy libcurl should use when the connection cache is filled and one of the open connections has to be closed to make room for a new connection. This must be one of the CURLCLOSEPOLICY_* defines. Use CURLCLOSEPOLICY_LEAST_RECENTLY_USED to make libcurl close the connection that was least recently used, that connection is also least likely to be capable of re-use. Use CURLCLOSEPOLICY_OLDEST to make libcurl close the oldest connection, the one that was created first among the ones in the connection cache. The other close policies are not support yet.

460

(Obsolete) This option does nothing.

446

461

<a name="CURLOPTFRESHCONNECT"></a>CURLOPT_FRESH_CONNECT

447

462

Pass a long. Set to non-zero to make the next transfer use a new (fresh) connection by force. If the connection cache is full before this connection, one of the existing connections will be closed as according to the selected or default policy. This option should be used with caution and only if you understand what it does. Set this to 0 to have libcurl attempt re-using an existing connection (default behavior).

448

463

<a name="CURLOPTFORBIDREUSE"></a>CURLOPT_FORBID_REUSE

450

465

<a name="CURLOPTCONNECTTIMEOUT"></a>CURLOPT_CONNECTTIMEOUT

451

466

Pass a long. It should contain the maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once it has connected, this option is of no more use. Set to zero to disable connection timeout (it will then only timeout on the system's internal timeouts). See also the <a class="emphasis" href="#CURLOPTTIMEOUT">CURLOPT_TIMEOUT</a> option.

452

467

In unix-like systems, this might cause signals to be used unless <a class="emphasis" href="#CURLOPTNOSIGNAL">CURLOPT_NOSIGNAL</a> is set.

468

<a name="CURLOPTCONNECTTIMEOUTMS"></a>CURLOPT_CONNECTTIMEOUT_MS

469

Like <a class="emphasis" href="#CURLOPTCONNECTTIMEOUT">CURLOPT_CONNECTTIMEOUT</a> but takes number of milliseconds instead. If libcurl is built to use the standard system name resolver, that part will still use full-second resolution for timeouts. (Added in 7.16.2)

453

470

<a name="CURLOPTIPRESOLVE"></a>CURLOPT_IPRESOLVE

454

471

Allows an application to select what kind of IP addresses to use when resolving host names. This is only interesting when using host names that resolve addresses using more than one version of IP. The allowed values are:

455

472

466

483

467

484

<a name="CURLOPTSSLCERT"></a>CURLOPT_SSLCERT

468

485

Pass a pointer to a zero terminated string as parameter. The string should be the file name of your certificate. The default format is "PEM" and can be changed with <a class="emphasis" href="#CURLOPTSSLCERTTYPE">CURLOPT_SSLCERTTYPE</a>.

486

With NSS this is the nickname of the certificate you wish to authenticate with.

469

487

<a name="CURLOPTSSLCERTTYPE"></a>CURLOPT_SSLCERTTYPE

470

488

Pass a pointer to a zero terminated string as parameter. The string should be the format of your certificate. Supported formats are "PEM" and "DER". (Added in 7.9.3)

471

489

<a name="CURLOPTSSLCERTPASSWD"></a>CURLOPT_SSLCERTPASSWD

477

495

Pass a pointer to a zero terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER" and "ENG".

478

496

The format "ENG" enables you to load the private key from a crypto engine. In this case <a class="emphasis" href="#CURLOPTSSLKEY">CURLOPT_SSLKEY</a> is used as an identifier passed to the engine. You have to set the crypto engine with <a class="emphasis" href="#CURLOPTSSLENGINE">CURLOPT_SSLENGINE</a>. "DER" format key file currently does not work because of a bug in OpenSSL.

479

497

<a name="CURLOPTSSLKEYPASSWD"></a>CURLOPT_SSLKEYPASSWD

480

498

Pass a pointer to a zero terminated string as parameter. It will be used as the password required to use the <a class="emphasis" href="#CURLOPTSSLKEY">CURLOPT_SSLKEY</a> or <a class="emphasis" href="#CURLOPTSSHPRIVATEKEYFILE">CURLOPT_SSH_PRIVATE_KEYFILE</a> private key.

481

499

<a name="CURLOPTSSLENGINE"></a>CURLOPT_SSLENGINE

482

500

Pass a pointer to a zero terminated string as parameter. It will be used as the identifier for the crypto engine you want to use for your private key.

483

501

If the crypto device cannot be loaded, CURLE_SSL_ENGINE_NOTFOUND is returned.

488

506

Pass a long as parameter to control what version of SSL/TLS to attempt to use. The available options are:

489

507

490

508

<a name="CURLSSLVERSIONDEFAULT"></a>CURL_SSLVERSION_DEFAULT

491

The default action. When libcurl built with OpenSSL, this will attempt to figure out the remote SSL protocol version. Unfortunately there are a lot of ancient and broken servers in use which cannot handle this technique and will fail to connect. When libcurl is built with GnuTLS, this will mean SSLv3.

509

The default action. When libcurl built with OpenSSL or NSS, this will attempt to figure out the remote SSL protocol version. Unfortunately there are a lot of ancient and broken servers in use which cannot handle this technique and will fail to connect. When libcurl is built with GnuTLS, this will mean SSLv3.

492

510

<a name="CURLSSLVERSIONTLSv1"></a>CURL_SSLVERSION_TLSv1

493

511

Force TLSv1

494

512

<a name="CURLSSLVERSIONSSLv2"></a>CURL_SSLVERSION_SSLv2

505

523

<a name="CURLOPTCAINFO"></a>CURLOPT_CAINFO

506

524

Pass a char * to a zero terminated string naming a file holding one or more certificates to verify the peer with. This makes sense only when used in combination with the <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> option. If <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> is zero, <a class="emphasis" href="#CURLOPTCAINFO">CURLOPT_CAINFO</a> need not even indicate an accessible file.

507

525

Note that option is by default set to the system path where libcurl's cacert bundle is assumed to be stored, as established at build time.

526

When built against NSS this is the directory that the NSS certificate database resides in.

508

527

<a name="CURLOPTCAPATH"></a>CURLOPT_CAPATH

509

Pass a char * to a zero terminated string naming a directory holding multiple CA certificates to verify the peer with. The certificate directory must be prepared using the openssl c_rehash utility. This makes sense only when used in combination with the <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> option. If <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a> is zero, <a class="emphasis" href="#CURLOPTCAPATH">CURLOPT_CAPATH</a> need not even indicate an accessible path. The <a class="emphasis" href="#CURLOPTCAPATH">CURLOPT_CAPATH</a> function apparently does not work in Windows due to some limitation in openssl. (Added in 7.9.8)

528

510

529

<a name="CURLOPTRANDOMFILE"></a>CURLOPT_RANDOM_FILE

511

530

Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, the more secure the SSL connection will become.

512

531

<a name="CURLOPTEGDSOCKET"></a>CURLOPT_EGDSOCKET

522

541

The default, since 7.10, is 2.

523

542

The checking this option controls is of the identity that the server claims. The server could be lying. To control lying, see <a class="emphasis" href="#CURLOPTSSLVERIFYPEER">CURLOPT_SSL_VERIFYPEER</a>.

524

543

<a name="CURLOPTSSLCIPHERLIST"></a>CURLOPT_SSL_CIPHER_LIST

525

Pass a char *, pointing to a zero terminated string holding the list of ciphers to use for the SSL connection. The list must be syntactically correct, it consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used, !, - and + can be used as operators. Valid examples of cipher lists include 'RC4-SHA', ´SHA1+DES´, 'TLSv1' and 'DEFAULT'. The default list is normally set when you compile OpenSSL.

544

545

For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', ´SHA1+DES´, 'TLSv1' and 'DEFAULT'. The default list is normally set when you compile OpenSSL.

526

546

You'll find more details about cipher lists on this URL: <a href="http://www.openssl.org/docs/apps/ciphers.html">http://www.openssl.org/docs/apps/ciphers.html</a>

547

For NSS valid examples of cipher lists include 'rsa_rc4_128_md5', ´rsa_aes_128_sha´, etc. With NSS you don't add/remove ciphers. If one uses this option then all known ciphers are disabled and only those passed in are enabled.

548

You'll find more details about the NSS cipher lists on this URL: <a href="http://directory.fedora.redhat.com/docs/mod_nss.html">http://directory.fedora.redhat.com/docs/mod_nss.html</a>#Directives

549

550

<a name="CURLOPTSSLSESSIONIDCACHE"></a>CURLOPT_SSL_SESSIONID_CACHE

551

Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set this to 1 to enable it. By default all transfers are done using the cache. Note that while nothing ever should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL implementations in the wild that may require you to disable this in order for you to succeed. (Added in 7.16.0)

527

552

<a name="CURLOPTKRB4LEVEL"></a>CURLOPT_KRB4LEVEL

528

Pass a char * as parameter. Set the krb4 security level, this also enables krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or 'private'. If the string is set but doesn't match one of these, 'private' will be used. Set the string to NULL to disable kerberos4. The kerberos support only works for FTP. <a name="OTHER"></a><h2 class="nroffsh">OTHER OPTIONS</h2>

553

554

555

<a name="CURLOPTSSHAUTHTYPES"></a>CURLOPT_SSH_AUTH_TYPES

556

Pass a long set to a bitmask consisting of one or more of CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY to let libcurl pick one.

557

<a name="CURLOPTSSHPUBLICKEYFILE"></a>CURLOPT_SSH_PUBLIC_KEYFILE

558

Pass a char * pointing to a file name for your public key. If not used, libcurl defaults to using ~/.ssh/id_dsa.pub.

559

<a name="CURLOPTSSHPRIVATEKEYFILE"></a>CURLOPT_SSH_PRIVATE_KEYFILE

560

Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to using ~/.ssh/id_dsa. If the file is password-protected, set the password with <a class="emphasis" href="#CURLOPTSSLKEYPASSWD">CURLOPT_SSLKEYPASSWD</a>. <a name="OTHER"></a><h2 class="nroffsh">OTHER OPTIONS</h2>

529

561

530

562

<a name="CURLOPTPRIVATE"></a>CURLOPT_PRIVATE

531

563

Pass a char * as parameter, pointing to data that should be associated with this curl handle. The pointer can subsequently be retrieved using <a class="emphasis" href="./curl_easy_getinfo.html">curl_easy_getinfo(3)</a> with the CURLINFO_PRIVATE option. libcurl itself does nothing with this data. (Added in 7.10.3)

Older »