2004-01-07 02:20:08 -05:00
|
|
|
.\" **************************************************************************
|
|
|
|
.\" * _ _ ____ _
|
|
|
|
.\" * Project ___| | | | _ \| |
|
|
|
|
.\" * / __| | | | |_) | |
|
|
|
|
.\" * | (__| |_| | _ <| |___
|
|
|
|
.\" * \___|\___/|_| \_\_____|
|
|
|
|
.\" *
|
2006-01-09 08:17:14 -05:00
|
|
|
.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, <daniel@haxx.se>, et al.
|
2004-01-07 02:20:08 -05:00
|
|
|
.\" *
|
|
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
|
|
.\" * you should have received as part of this distribution. The terms
|
|
|
|
.\" * are also available at http://curl.haxx.se/docs/copyright.html.
|
|
|
|
.\" *
|
|
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
|
|
.\" *
|
|
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
|
|
.\" * KIND, either express or implied.
|
|
|
|
.\" *
|
|
|
|
.\" * $Id$
|
|
|
|
.\" **************************************************************************
|
2002-03-04 05:09:48 -05:00
|
|
|
.\"
|
2006-11-02 17:10:18 -05:00
|
|
|
.TH curl_easy_setopt 3 "2 Nov 2006" "libcurl 7.16.1" "libcurl Manual"
|
2002-03-04 05:09:48 -05:00
|
|
|
.SH NAME
|
2006-01-08 17:55:13 -05:00
|
|
|
curl_easy_setopt \- set options for a curl easy handle
|
2002-03-04 05:09:48 -05:00
|
|
|
.SH SYNOPSIS
|
|
|
|
#include <curl/curl.h>
|
|
|
|
|
|
|
|
CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
|
|
|
|
.SH DESCRIPTION
|
2002-09-18 11:26:42 -04:00
|
|
|
curl_easy_setopt() is used to tell libcurl how to behave. By using the
|
|
|
|
appropriate options to \fIcurl_easy_setopt\fP, you can change libcurl's
|
|
|
|
behavior. All options are set with the \fIoption\fP followed by a
|
2004-08-16 06:49:57 -04:00
|
|
|
\fIparameter\fP. That parameter can be a \fBlong\fP, a \fBfunction pointer\fP,
|
|
|
|
an \fBobject pointer\fP or a \fBcurl_off_t\fP, depending on what the specific
|
|
|
|
option expects. Read this manual carefully as bad input values may cause
|
|
|
|
libcurl to behave badly! You can only set one option in each function call. A
|
|
|
|
typical application uses many curl_easy_setopt() calls in the setup phase.
|
2002-03-04 05:09:48 -05:00
|
|
|
|
2004-01-15 05:38:08 -05:00
|
|
|
Options set with this function call are valid for all forthcoming transfers
|
|
|
|
performed using this \fIhandle\fP. The options are not in any way reset
|
|
|
|
between transfers, so if you want subsequent transfers with different options,
|
2004-08-17 08:37:35 -04:00
|
|
|
you must change them between the transfers. You can optionally reset all
|
|
|
|
options back to internal default with \fIcurl_easy_reset(3)\fP.
|
2004-01-15 05:38:08 -05:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
Strings passed to libcurl as 'char *' arguments, will not be copied by the
|
|
|
|
library. Instead you should keep them available until libcurl no longer needs
|
|
|
|
them. Failing to do so will cause very odd behavior or even crashes. libcurl
|
|
|
|
will need them until you call \fIcurl_easy_cleanup(3)\fP or you set the same
|
|
|
|
option again to use a different pointer.
|
2002-03-04 05:09:48 -05:00
|
|
|
|
|
|
|
The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or
|
|
|
|
\fIcurl_easy_duphandle(3)\fP call.
|
2002-09-18 11:26:42 -04:00
|
|
|
.SH BEHAVIOR OPTIONS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_VERBOSE
|
2002-09-18 11:26:42 -04:00
|
|
|
Set the parameter to non-zero to get the library to display a lot of verbose
|
|
|
|
information about its operations. Very useful for libcurl and/or protocol
|
2004-01-21 02:46:17 -05:00
|
|
|
debugging and understanding. The verbose information will be sent to stderr,
|
2004-01-22 05:17:09 -05:00
|
|
|
or the stream set with \fICURLOPT_STDERR\fP.
|
2002-03-04 05:09:48 -05:00
|
|
|
|
2002-09-18 11:26:42 -04:00
|
|
|
You hardly ever want this set in production use, you will almost always want
|
|
|
|
this when you debug/report problems. Another neat option for debugging is the
|
|
|
|
\fICURLOPT_DEBUGFUNCTION\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_HEADER
|
2002-09-18 11:26:42 -04:00
|
|
|
A non-zero parameter tells the library to include the header in the body
|
|
|
|
output. This is only relevant for protocols that actually have headers
|
|
|
|
preceding the data (like HTTP).
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_NOPROGRESS
|
2003-11-04 07:07:19 -05:00
|
|
|
A non-zero parameter tells the library to shut off the built-in progress meter
|
2002-09-18 11:26:42 -04:00
|
|
|
completely.
|
2002-05-06 09:43:35 -04:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
Future versions of libcurl is likely to not have any built-in progress meter
|
|
|
|
at all.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_NOSIGNAL
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long. If it is non-zero, libcurl will not use any functions that
|
|
|
|
install signal handlers or any functions that cause signals to be sent to the
|
|
|
|
process. This option is mainly here to allow multi-threaded unix applications
|
|
|
|
to still set/use all timeout options etc, without risking getting signals.
|
|
|
|
(Added in 7.10)
|
2003-11-07 04:15:28 -05:00
|
|
|
|
|
|
|
Consider building libcurl with ares support to enable asynchronous DNS
|
|
|
|
lookups. It enables nice timeouts for name resolves without signals.
|
2002-09-18 11:26:42 -04:00
|
|
|
.PP
|
|
|
|
.SH CALLBACK OPTIONS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_WRITEFUNCTION
|
2002-03-04 05:09:48 -05:00
|
|
|
Function pointer that should match the following prototype: \fBsize_t
|
|
|
|
function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This
|
2004-03-24 16:40:45 -05:00
|
|
|
function gets called by libcurl as soon as there is data received that needs
|
2002-03-18 03:53:21 -05:00
|
|
|
to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP
|
2002-12-16 12:33:21 -05:00
|
|
|
multiplied with \fInmemb\fP, it will not be zero terminated. Return the number
|
|
|
|
of bytes actually taken care of. If that amount differs from the amount passed
|
|
|
|
to your function, it'll signal an error to the library and it will abort the
|
|
|
|
transfer and return \fICURLE_WRITE_ERROR\fP.
|
2002-03-04 05:09:48 -05:00
|
|
|
|
2004-08-23 10:41:54 -04:00
|
|
|
This function may be called with zero bytes data if the transfered file is
|
|
|
|
empty.
|
|
|
|
|
2005-09-21 02:12:41 -04:00
|
|
|
Set this option to NULL to get the internal default function. The internal
|
|
|
|
default function will write the data to the FILE * given with
|
|
|
|
\fICURLOPT_WRITEDATA\fP.
|
|
|
|
|
2003-11-07 04:15:28 -05:00
|
|
|
Set the \fIstream\fP argument with the \fICURLOPT_WRITEDATA\fP option.
|
2002-03-04 05:09:48 -05:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
The callback function will be passed as much data as possible in all invokes,
|
|
|
|
but you cannot possibly make any assumptions. It may be one byte, it may be
|
2002-05-03 10:50:29 -04:00
|
|
|
thousands. The maximum amount of data that can be passed to the write callback
|
|
|
|
is defined in the curl.h header file: CURL_MAX_WRITE_SIZE.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_WRITEDATA
|
2005-09-21 02:59:01 -04:00
|
|
|
Data pointer to pass to the file write function. If you use the
|
|
|
|
\fICURLOPT_WRITEFUNCTION\fP option, this is the pointer you'll get as
|
|
|
|
input. If you don't use a callback, you must pass a 'FILE *' as libcurl will
|
|
|
|
pass this to fwrite() when writing data.
|
2002-03-04 05:09:48 -05:00
|
|
|
|
2005-09-21 02:12:41 -04:00
|
|
|
The internal \fICURLOPT_WRITEFUNCTION\fP will write the data to the FILE *
|
|
|
|
given with this option, or to stdout if this option hasn't been set.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
If you're using libcurl as a win32 DLL, you \fBMUST\fP use the
|
2002-09-18 11:26:42 -04:00
|
|
|
\fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience
|
|
|
|
crashes.
|
2002-05-06 09:43:35 -04:00
|
|
|
|
2003-11-07 04:15:28 -05:00
|
|
|
This option is also known with the older name \fICURLOPT_FILE\fP, the name
|
|
|
|
\fICURLOPT_WRITEDATA\fP was introduced in 7.9.7.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_READFUNCTION
|
2002-03-04 05:09:48 -05:00
|
|
|
Function pointer that should match the following prototype: \fBsize_t
|
|
|
|
function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This
|
|
|
|
function gets called by libcurl as soon as it needs to read data in order to
|
|
|
|
send it to the peer. The data area pointed at by the pointer \fIptr\fP may be
|
|
|
|
filled with at most \fIsize\fP multiplied with \fInmemb\fP number of
|
|
|
|
bytes. Your function must return the actual number of bytes that you stored in
|
|
|
|
that memory area. Returning 0 will signal end-of-file to the library and cause
|
|
|
|
it to stop the current transfer.
|
2004-06-21 10:09:23 -04:00
|
|
|
|
|
|
|
If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
|
|
|
|
server expected it, like when you've told you will upload N bytes and you
|
|
|
|
upload less than N bytes), you may experience that the server "hangs" waiting
|
|
|
|
for the rest of the data that won't come.
|
|
|
|
|
2005-09-22 06:15:10 -04:00
|
|
|
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
|
|
|
|
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
|
|
|
|
code from the transfer (Added in 7.12.1)
|
|
|
|
|
|
|
|
If you set the callback pointer to NULL, or doesn't set it at all, the default
|
|
|
|
internal read function will be used. It is simply doing an fread() on the FILE
|
|
|
|
* stream set with \fICURLOPT_READDATA\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_READDATA
|
2005-09-21 02:59:01 -04:00
|
|
|
Data pointer to pass to the file read function. If you use the
|
|
|
|
\fICURLOPT_READFUNCTION\fP option, this is the pointer you'll get as input. If
|
2005-09-22 06:15:10 -04:00
|
|
|
you don't specify a read callback but instead rely on the default internal
|
|
|
|
read function, this data must be a valid readable FILE *.
|
2002-09-18 11:26:42 -04:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
If you're using libcurl as a win32 DLL, you MUST use a
|
2002-09-18 11:26:42 -04:00
|
|
|
\fICURLOPT_READFUNCTION\fP if you set this option.
|
|
|
|
|
2003-11-07 04:15:28 -05:00
|
|
|
This option is also known with the older name \fICURLOPT_INFILE\fP, the name
|
|
|
|
\fICURLOPT_READDATA\fP was introduced in 7.9.7.
|
2004-11-24 11:11:35 -05:00
|
|
|
.IP CURLOPT_IOCTLFUNCTION
|
|
|
|
Function pointer that should match the \fIcurl_ioctl_callback\fP prototype
|
|
|
|
found in \fI<curl/curl.h>\fP. 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
|
2006-08-29 10:39:33 -04:00
|
|
|
HTTP PUT or POST with a multi-pass authentication method. (Option added in
|
2004-11-24 11:11:35 -05:00
|
|
|
7.12.3)
|
|
|
|
.IP CURLOPT_IOCTLDATA
|
|
|
|
Pass a pointer that will be untouched by libcurl and passed as the 3rd
|
|
|
|
argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP. (Option
|
|
|
|
added in 7.12.3)
|
2006-08-29 10:39:33 -04:00
|
|
|
.IP CURLOPT_SOCKOPTFUNCTION
|
|
|
|
Function pointer that should match the \fIcurl_sockopt_callback\fP prototype
|
|
|
|
found in \fI<curl/curl.h>\fP. This function gets called by libcurl after the
|
|
|
|
socket() call but before the connect() call. The callback's \fIpurpose\fP
|
|
|
|
argument identifies the exact purpose for this particular socket, and
|
|
|
|
currently only one value is supported: \fICURLSOCKTYPE_IPCXN\fP 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
|
|
|
|
\fICURLE_COULDNT_CONNECT\fP. (Option added in 7.15.6.)
|
|
|
|
.IP CURLOPT_SOCKOPTDATA
|
|
|
|
Pass a pointer that will be untouched by libcurl and passed as the first
|
|
|
|
argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP.
|
|
|
|
(Option added in 7.15.6.)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_PROGRESSFUNCTION
|
2002-09-18 11:26:42 -04:00
|
|
|
Function pointer that should match the \fIcurl_progress_callback\fP prototype
|
|
|
|
found in \fI<curl/curl.h>\fP. This function gets called by libcurl instead of
|
2006-08-02 05:33:32 -04:00
|
|
|
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
|
|
|
|
\fICURLE_ABORTED_BY_CALLBACK\fP.
|
2006-01-03 10:53:29 -05:00
|
|
|
|
|
|
|
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 \fBCURLOPT_PROGRESSFUNCTION\fP
|
|
|
|
callback is not recommended when using the multi interface.
|
2002-09-18 11:26:42 -04:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
\fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this function actually
|
|
|
|
get called.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_PROGRESSDATA
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a pointer that will be untouched by libcurl and passed as the first
|
|
|
|
argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_HEADERFUNCTION
|
2002-09-18 11:26:42 -04:00
|
|
|
Function pointer that should match the following prototype: \fIsize_t
|
|
|
|
function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This
|
2005-07-13 05:46:37 -04:00
|
|
|
function gets called by libcurl as soon as it has received header data. The
|
|
|
|
header callback will be called once for each header and only complete header
|
|
|
|
lines are passed on to the callback. Parsing headers should be easy enough
|
2002-09-18 11:26:42 -04:00
|
|
|
using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP
|
2005-07-13 05:46:37 -04:00
|
|
|
multiplied with \fInmemb\fP. Do not assume that the header line is zero
|
|
|
|
terminated! The pointer named \fIstream\fP is the one you set with the
|
|
|
|
\fICURLOPT_WRITEHEADER\fP option. The callback function must return the number
|
|
|
|
of bytes actually taken care of, or return -1 to signal error to the library
|
2002-09-18 11:26:42 -04:00
|
|
|
(it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return
|
2003-08-15 02:35:41 -04:00
|
|
|
code).
|
2005-07-13 05:37:22 -04:00
|
|
|
|
|
|
|
Since 7.14.1: When a server sends a chunked encoded transfer, it may contain a
|
|
|
|
trailer. That trailer is identical to a HTTP header and if such a trailer is
|
|
|
|
received it is passed to the application using this callback as well. There
|
|
|
|
are several ways to detect it being a trailer and not an ordinary header: 1)
|
|
|
|
it comes after the response-body. 2) it comes after the final header line (CR
|
|
|
|
LF) 3) a Trailer: header among the response-headers mention what header to
|
|
|
|
expect in the trailer.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_WRITEHEADER
|
2005-07-13 05:46:37 -04:00
|
|
|
(This option is also known as \fBCURLOPT_HEADERDATA\fP) Pass a pointer to be
|
|
|
|
used to write the header part of the received data to. If you don't use your
|
|
|
|
own callback to take care of the writing, this must be a valid FILE *. See
|
|
|
|
also the \fICURLOPT_HEADERFUNCTION\fP option above on how to set a custom
|
|
|
|
get-all-headers callback.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_DEBUGFUNCTION
|
2002-09-18 11:26:42 -04:00
|
|
|
Function pointer that should match the following prototype: \fIint
|
|
|
|
curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP
|
2003-11-07 04:15:28 -05:00
|
|
|
\fICURLOPT_DEBUGFUNCTION\fP replaces the standard debug function used when
|
|
|
|
\fICURLOPT_VERBOSE \fP is in effect. This callback receives debug information,
|
2004-03-24 16:40:45 -05:00
|
|
|
as specified with the \fBcurl_infotype\fP argument. This function must return
|
2003-11-07 04:15:28 -05:00
|
|
|
0. The data pointed to by the char * passed to this function WILL NOT be zero
|
2003-09-12 14:35:38 -04:00
|
|
|
terminated, but will be exactly of the size as told by the size_t argument.
|
2002-12-03 05:37:20 -05:00
|
|
|
|
2003-09-12 14:35:38 -04:00
|
|
|
Available curl_infotype values:
|
|
|
|
.RS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLINFO_TEXT
|
2003-09-12 14:35:38 -04:00
|
|
|
The data is informational text.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLINFO_HEADER_IN
|
2003-09-12 14:35:38 -04:00
|
|
|
The data is header (or header-like) data received from the peer.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLINFO_HEADER_OUT
|
2003-09-12 14:35:38 -04:00
|
|
|
The data is header (or header-like) data sent to the peer.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLINFO_DATA_IN
|
2003-09-12 14:35:38 -04:00
|
|
|
The data is protocol data received from the peer.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLINFO_DATA_OUT
|
2003-09-12 14:35:38 -04:00
|
|
|
The data is protocol data sent to the peer.
|
|
|
|
.RE
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_DEBUGDATA
|
2003-11-07 04:15:28 -05:00
|
|
|
Pass a pointer to whatever you want passed in to your
|
|
|
|
\fICURLOPT_DEBUGFUNCTION\fP in the last void * argument. This pointer is not
|
|
|
|
used by libcurl, it is only passed to the callback.
|
2004-01-15 05:38:08 -05:00
|
|
|
.IP CURLOPT_SSL_CTX_FUNCTION
|
|
|
|
Function pointer that should match the following prototype: \fBCURLcode
|
|
|
|
sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called
|
|
|
|
by libcurl just before the initialization of an SSL connection after having
|
|
|
|
processed all other SSL related options to give a last chance to an
|
2004-03-24 16:40:45 -05:00
|
|
|
application to modify the behaviour of openssl's ssl initialization. The
|
2004-01-15 05:38:08 -05:00
|
|
|
\fIsslctx\fP parameter is actually a pointer to an openssl \fISSL_CTX\fP. If
|
|
|
|
an error is returned no attempt to establish a connection is made and the
|
|
|
|
perform operation will return the error code from this callback function. Set
|
|
|
|
the \fIparm\fP argument with the \fICURLOPT_SSL_CTX_DATA\fP option. This
|
|
|
|
option was introduced in 7.11.0.
|
|
|
|
|
2005-09-01 09:41:29 -04:00
|
|
|
This function will get called on all new connections made to a server, during
|
|
|
|
the SSL negotiation. The SSL_CTX pointer will be a new one every time.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
To use this properly, a non-trivial amount of knowledge of the openssl
|
|
|
|
libraries is necessary. Using this function allows for example to use openssl
|
|
|
|
callbacks to add additional validation code for certificates, and even to
|
|
|
|
change the actual URI of an HTTPS request (example used in the lib509 test
|
2004-01-15 05:38:08 -05:00
|
|
|
case). See also the example section for a replacement of the key, certificate
|
|
|
|
and trust file settings.
|
|
|
|
.IP CURLOPT_SSL_CTX_DATA
|
|
|
|
Data pointer to pass to the ssl context callback set by the option
|
|
|
|
\fICURLOPT_SSL_CTX_FUNCTION\fP, this is the pointer you'll get as third
|
|
|
|
parameter, otherwise \fBNULL\fP. (Added in 7.11.0)
|
2006-04-19 05:08:15 -04:00
|
|
|
.IP CURLOPT_CONV_TO_NETWORK_FUNCTION
|
|
|
|
.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION
|
|
|
|
.IP CURLOPT_CONV_FROM_UTF8_FUNCTION
|
|
|
|
Function pointers that should match the following prototype: CURLcode
|
|
|
|
function(char *ptr, size_t length);
|
|
|
|
|
|
|
|
These three options apply to non-ASCII platforms only. They are available
|
|
|
|
only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. When
|
|
|
|
this is the case, \fIcurl_version_info(3)\fP will return the CURL_VERSION_CONV
|
|
|
|
feature bit set.
|
|
|
|
|
|
|
|
The data to be converted is in a buffer pointed to by the ptr parameter. The
|
|
|
|
amount of data to convert is indicated by the length parameter. The converted
|
|
|
|
data overlays the input data in the buffer pointed to by the ptr parameter.
|
|
|
|
CURLE_OK should be returned upon successful conversion. A CURLcode return
|
|
|
|
value defined by curl.h, such as CURLE_CONV_FAILED, should be returned if an
|
|
|
|
error was encountered.
|
|
|
|
|
|
|
|
\fBCURLOPT_CONV_TO_NETWORK_FUNCTION\fP and
|
|
|
|
\fBCURLOPT_CONV_FROM_NETWORK_FUNCTION\fP convert between the host encoding and
|
|
|
|
the network encoding. They are used when commands or ASCII data are
|
|
|
|
sent/received over the network.
|
|
|
|
|
|
|
|
\fBCURLOPT_CONV_FROM_UTF8_FUNCTION\fP is called to convert from UTF8 into the
|
|
|
|
host encoding. It is required only for SSL processing.
|
|
|
|
|
|
|
|
If you set a callback pointer to NULL, or don't set it at all, the built-in
|
|
|
|
libcurl iconv functions will be used. If HAVE_ICONV was not defined when
|
|
|
|
libcurl was built, and no callback has been established, conversion will
|
|
|
|
return the CURLE_CONV_REQD error code.
|
|
|
|
|
|
|
|
If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined.
|
|
|
|
For example:
|
|
|
|
|
|
|
|
\&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
|
|
|
|
|
|
|
|
The iconv code in libcurl will default the network and UTF8 codeset names as
|
|
|
|
follows:
|
|
|
|
|
|
|
|
\&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
|
|
|
|
|
|
|
|
\&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
|
|
|
|
|
|
|
|
You will need to override these definitions if they are different on your
|
|
|
|
system.
|
2002-09-18 11:26:42 -04:00
|
|
|
.SH ERROR OPTIONS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_ERRORBUFFER
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a char * to a buffer that the libcurl may store human readable error
|
2005-09-21 02:59:01 -04:00
|
|
|
messages in. This may be more helpful than just the return code from
|
|
|
|
\fIcurl_easy_perform\fP. The buffer must be at least CURL_ERROR_SIZE big.
|
2002-09-18 11:26:42 -04:00
|
|
|
|
|
|
|
Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better
|
|
|
|
debug/trace why errors happen.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
If the library does not return an error, the buffer may not have been
|
|
|
|
touched. Do not rely on the contents in those cases.
|
|
|
|
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_STDERR
|
2003-11-07 04:15:28 -05:00
|
|
|
Pass a FILE * as parameter. Tell libcurl to use this stream instead of stderr
|
|
|
|
when showing the progress meter and displaying \fICURLOPT_VERBOSE\fP data.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FAILONERROR
|
2002-09-18 11:26:42 -04:00
|
|
|
A non-zero parameter tells the library to fail silently if the HTTP code
|
2005-12-10 17:12:44 -05:00
|
|
|
returned is equal to or larger than 400. The default action would be to return
|
2002-09-18 11:26:42 -04:00
|
|
|
the page normally, ignoring that code.
|
2006-10-25 16:40:14 -04:00
|
|
|
|
|
|
|
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).
|
|
|
|
|
|
|
|
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.
|
2002-09-18 11:26:42 -04:00
|
|
|
.SH NETWORK OPTIONS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_URL
|
2002-03-04 05:09:48 -05:00
|
|
|
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.
|
|
|
|
|
2004-02-27 09:07:22 -05:00
|
|
|
If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will
|
|
|
|
attempt to guess which protocol to use based on the given host name. If the
|
|
|
|
given protocol of the set URL is not supported, libcurl will return on error
|
|
|
|
(\fICURLE_UNSUPPORTED_PROTOCOL\fP) when you call \fIcurl_easy_perform(3)\fP or
|
|
|
|
\fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed info
|
|
|
|
on which protocols that are supported.
|
|
|
|
|
2006-04-09 18:40:49 -04:00
|
|
|
The string given to CURLOPT_URL must be url-encoded and following the RFC 2396
|
|
|
|
(http://curl.haxx.se/rfc/rfc2396.txt).
|
|
|
|
|
|
|
|
\fICURLOPT_URL\fP is the only option that \fBmust\fP be set before
|
2002-03-04 05:09:48 -05:00
|
|
|
\fIcurl_easy_perform(3)\fP is called.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_PROXY
|
2002-03-04 05:09:48 -05:00
|
|
|
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
|
|
|
|
\fICURLOPT_PROXYPORT\fP.
|
|
|
|
|
2005-08-25 03:06:50 -04:00
|
|
|
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
|
|
|
|
\fICURLOPT_QUOTE\fP and similar FTP specifics that don't work unless you
|
|
|
|
tunnel through the HTTP proxy. Such tunneling is activated with
|
2002-03-04 05:09:48 -05:00
|
|
|
\fICURLOPT_HTTPPROXYTUNNEL\fP.
|
|
|
|
|
2005-08-25 03:06:50 -04:00
|
|
|
libcurl respects the environment variables \fBhttp_proxy\fP, \fBftp_proxy\fP,
|
|
|
|
\fBall_proxy\fP etc, if any of those is set. The \fICURLOPT_PROXY\fP option
|
|
|
|
does however override any possibly set environment variables.
|
2005-06-23 19:07:07 -04:00
|
|
|
|
2006-08-23 17:49:44 -04:00
|
|
|
Starting with 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
|
|
|
|
\fICURLOPT_PROXY\fP, include protocol prefix (http://) and embedded user +
|
|
|
|
password.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_PROXYPORT
|
2002-03-04 05:09:48 -05:00
|
|
|
Pass a long with this option to set the proxy port to connect to unless it is
|
|
|
|
specified in the proxy string \fICURLOPT_PROXY\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_PROXYTYPE
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long with this option to set type of the proxy. Available options for
|
2006-02-21 02:46:41 -05:00
|
|
|
this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2)
|
|
|
|
\fICURLPROXY_SOCKS5\fP. The HTTP type is default. (Added in 7.10)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_HTTPPROXYTUNNEL
|
2002-03-04 05:09:48 -05:00
|
|
|
Set the parameter to non-zero to get the library to tunnel all operations
|
2005-09-21 02:59:01 -04:00
|
|
|
through a given HTTP proxy. There is a big difference between using a proxy
|
|
|
|
and to tunnel through it. If you don't know what this means, you probably
|
|
|
|
don't want this tunneling option.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_INTERFACE
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a char * as parameter. This set the interface name to use as outgoing
|
|
|
|
network interface. The name can be an interface name, an IP address or a host
|
2003-08-15 02:35:41 -04:00
|
|
|
name.
|
2006-01-30 03:24:07 -05:00
|
|
|
.IP CURLOPT_LOCALPORT
|
|
|
|
Pass a long. This sets the local port number of the socket used for
|
|
|
|
connection. This can be used in combination with \fICURLOPT_INTERFACE\fP and
|
|
|
|
you are recommended to use \fICURLOPT_LOCALPORTRANGE\fP as well when this is
|
|
|
|
set. Note that port numbers are only valid 1 - 65535. (Added in 7.15.2)
|
|
|
|
.IP CURLOPT_LOCALPORTRANGE
|
|
|
|
Pass a long. This is the number of attempts libcurl should do to find a
|
|
|
|
working local port number. It starts with the given \fICURLOPT_LOCALPORT\fP
|
|
|
|
and adds one to the number for each retry. Setting this value to 1 or below
|
|
|
|
will make libcurl do only one try for exact port number. Note that port
|
|
|
|
numbers by nature is a scarce resource that will be busy at times so setting
|
|
|
|
this value to something too low might cause unnecessary connection setup
|
|
|
|
failures. (Added in 7.15.2)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_DNS_CACHE_TIMEOUT
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long, this sets the timeout in seconds. Name resolves will be kept in
|
|
|
|
memory for this number of seconds. Set to zero (0) to completely disable
|
|
|
|
caching, or set to -1 to make the cached entries remain forever. By default,
|
2004-02-19 05:21:54 -05:00
|
|
|
libcurl caches this info for 60 seconds.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_DNS_USE_GLOBAL_CACHE
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long. If the value is non-zero, it tells curl to use a global DNS cache
|
|
|
|
that will survive between easy handle creations and deletions. This is not
|
2004-03-24 16:40:45 -05:00
|
|
|
thread-safe and this will use a global variable.
|
2004-03-01 10:50:15 -05:00
|
|
|
|
|
|
|
\fBWARNING:\fP this option is considered obsolete. Stop using it. Switch over
|
|
|
|
to using the share interface instead! See \fICURLOPT_SHARE\fP and
|
|
|
|
\fIcurl_share_init(3)\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_BUFFERSIZE
|
2005-09-12 16:36:17 -04:00
|
|
|
Pass a long specifying your preferred size (in bytes) for the receive buffer
|
|
|
|
in libcurl. The main point of this would be that the write callback gets
|
|
|
|
called more often and with smaller chunks. This is just treated as a request,
|
|
|
|
not an order. You cannot be guaranteed to actually get the given size. (Added
|
|
|
|
in 7.10)
|
|
|
|
|
|
|
|
This size is by default set as big as possible (CURL_MAX_WRITE_SIZE), so it
|
|
|
|
only makse sense to use this option if you want it smaller.
|
2004-02-27 04:02:06 -05:00
|
|
|
.IP CURLOPT_PORT
|
|
|
|
Pass a long specifying what remote port number to connect to, instead of the
|
|
|
|
one specified in the URL or the default port for the used protocol.
|
2004-03-25 08:37:18 -05:00
|
|
|
.IP CURLOPT_TCP_NODELAY
|
|
|
|
Pass a long specifying whether the TCP_NODELAY option should be set or
|
|
|
|
cleared (1 = set, 0 = clear). The option is cleared by default. This
|
|
|
|
will have no effect after the connection has been established.
|
|
|
|
|
|
|
|
Setting this option will disable TCP's Nagle algorithm. The purpose of
|
|
|
|
this algorithm is to try to minimize the number of small packets on
|
|
|
|
the network (where "small packets" means TCP segments less than the
|
|
|
|
Maximum Segment Size (MSS) for the network).
|
|
|
|
|
|
|
|
Maximizing the amount of data sent per TCP segment is good because it
|
|
|
|
amortizes the overhead of the send. However, in some cases (most
|
|
|
|
notably telnet or rlogin) small segments may need to be sent
|
|
|
|
without delay. This is less efficient than sending larger amounts of
|
|
|
|
data at a time, and can contribute to congestion on the network if
|
2004-05-17 03:12:32 -04:00
|
|
|
overdone.
|
2003-06-10 08:22:19 -04:00
|
|
|
.SH NAMES and PASSWORDS OPTIONS (Authentication)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_NETRC
|
2002-05-21 18:20:16 -04:00
|
|
|
This parameter controls the preference of libcurl between using user names and
|
|
|
|
passwords from your \fI~/.netrc\fP file, relative to user names and passwords
|
|
|
|
in the URL supplied with \fICURLOPT_URL\fP.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
libcurl uses a user name (and supplied or prompted password) supplied with
|
|
|
|
\fICURLOPT_USERPWD\fP in preference to any of the options controlled by this
|
|
|
|
parameter.
|
2002-05-21 18:20:16 -04:00
|
|
|
|
|
|
|
Pass a long, set to one of the values described below.
|
|
|
|
.RS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURL_NETRC_OPTIONAL
|
2002-05-21 18:20:16 -04:00
|
|
|
The use of your \fI~/.netrc\fP file is optional,
|
|
|
|
and information in the URL is to be preferred. The file will be scanned
|
|
|
|
with the host and user name (to find the password only) or with the host only,
|
|
|
|
to find the first user name and password after that \fImachine\fP,
|
|
|
|
which ever information is not specified in the URL.
|
|
|
|
|
|
|
|
Undefined values of the option will have this effect.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURL_NETRC_IGNORED
|
2002-05-21 18:20:16 -04:00
|
|
|
The library will ignore the file and use only the information in the URL.
|
|
|
|
|
|
|
|
This is the default.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURL_NETRC_REQUIRED
|
2002-05-21 18:20:16 -04:00
|
|
|
This value tells the library that use of the file is required,
|
|
|
|
to ignore the information in the URL,
|
|
|
|
and to search the file with the host only.
|
|
|
|
.RE
|
2004-05-17 03:12:32 -04:00
|
|
|
Only machine name, user name and password are taken into account
|
2002-05-21 18:20:16 -04:00
|
|
|
(init macros and similar things aren't supported).
|
2002-03-04 05:09:48 -05:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
libcurl does not verify that the file has the correct properties set (as the
|
|
|
|
standard Unix ftp client does). It should only be readable by user.
|
2003-11-11 09:30:43 -05:00
|
|
|
.IP CURLOPT_NETRC_FILE
|
|
|
|
Pass a char * as parameter, pointing to a zero terminated string containing
|
|
|
|
the full path name to the file you want libcurl to use as .netrc file. If this
|
2004-02-27 10:34:06 -05:00
|
|
|
option is omitted, and \fICURLOPT_NETRC\fP is set, libcurl will attempt to
|
|
|
|
find the a .netrc file in the current user's home directory. (Added in 7.10.9)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_USERPWD
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a char * as parameter, which should be [user name]:[password] to use for
|
2003-11-07 04:15:28 -05:00
|
|
|
the connection. Use \fICURLOPT_HTTPAUTH\fP to decide authentication method.
|
2003-03-30 23:04:40 -05:00
|
|
|
|
2005-11-11 03:52:29 -05:00
|
|
|
When using NTLM, you can set domain by prepending it to the user name and
|
|
|
|
separating the domain and name with a forward (/) or backward slash (\\). Like
|
|
|
|
this: "domain/user:password" or "domain\\user:password". Some HTTP servers (on
|
|
|
|
Windows) support this style even for Basic authentication.
|
|
|
|
|
2004-01-05 09:46:56 -05:00
|
|
|
When using HTTP and \fICURLOPT_FOLLOWLOCATION\fP, libcurl might perform
|
|
|
|
several requests to possibly different hosts. libcurl will only send this user
|
|
|
|
and password information to hosts using the initial host name (unless
|
2003-11-07 04:15:28 -05:00
|
|
|
\fICURLOPT_UNRESTRICTED_AUTH\fP is set), so if libcurl follows locations to
|
|
|
|
other hosts it will not send the user and password to those. This is enforced
|
|
|
|
to prevent accidental information leakage.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_PROXYUSERPWD
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a char * as parameter, which should be [user name]:[password] to use for
|
2003-11-07 04:15:28 -05:00
|
|
|
the connection to the HTTP proxy. Use \fICURLOPT_PROXYAUTH\fP to decide
|
|
|
|
authentication method.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_HTTPAUTH
|
2003-06-26 07:40:44 -04:00
|
|
|
Pass a long as parameter, which is set to a bitmask, to tell libcurl what
|
|
|
|
authentication method(s) you want it to use. The available bits are listed
|
|
|
|
below. If more than one bit is set, libcurl will first query the site to see
|
|
|
|
what authentication methods it supports and then pick the best one you allow
|
2005-09-21 02:59:01 -04:00
|
|
|
it to use. For some methods, this will induce an extra network round-trip. Set
|
|
|
|
the actual name and password with the \fICURLOPT_USERPWD\fP option. (Added in
|
|
|
|
7.10.6)
|
2003-06-10 08:58:40 -04:00
|
|
|
.RS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLAUTH_BASIC
|
2003-06-26 07:40:44 -04:00
|
|
|
HTTP Basic authentication. This is the default choice, and the only method
|
|
|
|
that is in wide-spread use and supported virtually everywhere. This is sending
|
|
|
|
the user name and password over the network in plain text, easily captured by
|
|
|
|
others.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLAUTH_DIGEST
|
2003-06-26 07:40:44 -04:00
|
|
|
HTTP Digest authentication. Digest authentication is defined in RFC2617 and
|
|
|
|
is a more secure way to do authentication over public networks than the
|
|
|
|
regular old-fashioned Basic method.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLAUTH_GSSNEGOTIATE
|
2003-11-07 04:15:28 -05:00
|
|
|
HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain
|
2005-05-12 17:56:26 -04:00
|
|
|
\&"Negotiate") method was designed by Microsoft and is used in their web
|
2004-03-24 16:40:45 -05:00
|
|
|
applications. It is primarily meant as a support for Kerberos5 authentication
|
2003-11-07 04:15:28 -05:00
|
|
|
but may be also used along with another authentication methods. For more
|
|
|
|
information see IETF draft draft-brezak-spnego-http-04.txt.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
You need to build libcurl with a suitable GSS-API library for this to work.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLAUTH_NTLM
|
2003-06-26 07:40:44 -04:00
|
|
|
HTTP NTLM authentication. A proprietary protocol invented and used by
|
2004-01-05 09:56:46 -05:00
|
|
|
Microsoft. It uses a challenge-response and hash concept similar to Digest, to
|
2004-03-24 16:40:45 -05:00
|
|
|
prevent the password from being eavesdropped.
|
2003-11-07 04:15:28 -05:00
|
|
|
|
2005-10-13 02:20:43 -04:00
|
|
|
You need to build libcurl with OpenSSL support for this option to work, or
|
|
|
|
build libcurl on Windows.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLAUTH_ANY
|
2003-06-26 07:40:44 -04:00
|
|
|
This is a convenience macro that sets all bits and thus makes libcurl pick any
|
2004-03-24 16:40:45 -05:00
|
|
|
it finds suitable. libcurl will automatically select the one it finds most
|
2003-06-26 07:40:44 -04:00
|
|
|
secure.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLAUTH_ANYSAFE
|
2003-06-26 07:40:44 -04:00
|
|
|
This is a convenience macro that sets all bits except Basic and thus makes
|
2004-03-24 16:40:45 -05:00
|
|
|
libcurl pick any it finds suitable. libcurl will automatically select the one it
|
2003-06-26 07:40:44 -04:00
|
|
|
finds most secure.
|
2003-06-10 08:58:40 -04:00
|
|
|
.RE
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_PROXYAUTH
|
2003-08-11 07:54:14 -04:00
|
|
|
Pass a long as parameter, which is set to a bitmask, to tell libcurl what
|
|
|
|
authentication method(s) you want it to use for your proxy authentication. If
|
|
|
|
more than one bit is set, libcurl will first query the site to see what
|
|
|
|
authentication methods it supports and then pick the best one you allow it to
|
2005-09-21 02:59:01 -04:00
|
|
|
use. For some methods, this will induce an extra network round-trip. Set the
|
|
|
|
actual name and password with the \fICURLOPT_PROXYUSERPWD\fP option. The
|
|
|
|
bitmask can be constructed by or'ing together the bits listed above for the
|
|
|
|
\fICURLOPT_HTTPAUTH\fP option. As of this writing, only Basic, Digest and NTLM
|
|
|
|
work. (Added in 7.10.7)
|
2002-09-18 11:26:42 -04:00
|
|
|
.SH HTTP OPTIONS
|
2004-02-27 04:02:06 -05:00
|
|
|
.IP CURLOPT_AUTOREFERER
|
|
|
|
Pass a non-zero parameter to enable this. When enabled, libcurl will
|
2004-03-24 16:40:45 -05:00
|
|
|
automatically set the Referer: field in requests where it follows a Location:
|
2004-02-27 04:02:06 -05:00
|
|
|
redirect.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_ENCODING
|
2003-05-12 08:47:35 -04:00
|
|
|
Sets the contents of the Accept-Encoding: header sent in an HTTP
|
|
|
|
request, and enables decoding of a response when a Content-Encoding:
|
|
|
|
header is received. Three encodings are supported: \fIidentity\fP,
|
|
|
|
which does nothing, \fIdeflate\fP which requests the server to
|
|
|
|
compress its response using the zlib algorithm, and \fIgzip\fP which
|
|
|
|
requests the gzip algorithm. If a zero-length string is set, then an
|
|
|
|
Accept-Encoding: header containing all supported encodings is sent.
|
|
|
|
|
|
|
|
This is a request, not an order; the server may or may not do it. This
|
|
|
|
option must be set (to any non-NULL value) or else any unsolicited
|
|
|
|
encoding done by the server is ignored. See the special file
|
|
|
|
lib/README.encoding for details.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FOLLOWLOCATION
|
2002-03-04 05:09:48 -05:00
|
|
|
A non-zero parameter tells the library to follow any Location: header that the
|
2004-03-24 16:40:45 -05:00
|
|
|
server sends as part of an HTTP header.
|
2002-03-04 05:09:48 -05:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
This means that the library will re-send the same request on the new location
|
|
|
|
and follow new Location: headers all the way until no more such headers are
|
|
|
|
returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number of redirects
|
|
|
|
libcurl will follow.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_UNRESTRICTED_AUTH
|
2003-03-30 23:41:05 -05:00
|
|
|
A non-zero parameter tells the library it can continue to send authentication
|
2005-09-21 02:59:01 -04:00
|
|
|
(user+password) when following locations, even when hostname changed. This
|
|
|
|
option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_MAXREDIRS
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long. The set number will be the redirection limit. If that many
|
|
|
|
redirections have been followed, the next redirect will cause an error
|
|
|
|
(\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the
|
2005-10-27 18:05:38 -04:00
|
|
|
\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. Added in 7.15.1:
|
|
|
|
Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for
|
|
|
|
an infinite number of redirects (which is the default)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_PUT
|
2002-03-04 05:09:48 -05:00
|
|
|
A non-zero parameter tells the library to use HTTP PUT to transfer data. The
|
2003-11-07 04:15:28 -05:00
|
|
|
data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP.
|
2004-06-02 10:06:49 -04:00
|
|
|
|
|
|
|
This option is deprecated and starting with version 7.12.1 you should instead
|
|
|
|
use \fICURLOPT_UPLOAD\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_POST
|
2004-08-10 09:22:08 -04:00
|
|
|
A non-zero parameter tells the library to do a regular HTTP post. This will
|
|
|
|
also make the library use the a "Content-Type:
|
|
|
|
application/x-www-form-urlencoded" header. (This is by far the most commonly
|
|
|
|
used POST method).
|
|
|
|
|
|
|
|
Use the \fICURLOPT_POSTFIELDS\fP option to specify what data to post and
|
2004-11-11 18:11:32 -05:00
|
|
|
\fICURLOPT_POSTFIELDSIZE\fP to set the data size.
|
|
|
|
|
|
|
|
Optionally, you can provide data to POST using the \fICURLOPT_READFUNCTION\fP
|
|
|
|
and \fICURLOPT_READDATA\fP options but then you must make sure to not set
|
|
|
|
\fICURLOPT_POSTFIELDS\fP to anything but NULL. When providing data with a
|
|
|
|
callback, you must transmit it using chunked transfer-encoding or you must set
|
2004-11-12 01:42:30 -05:00
|
|
|
the size of the data with the \fICURLOPT_POSTFIELDSIZE\fP option.
|
2004-08-10 09:22:08 -04:00
|
|
|
|
|
|
|
You can override the default POST Content-Type: header by setting your own
|
|
|
|
with \fICURLOPT_HTTPHEADER\fP.
|
|
|
|
|
2004-08-23 10:04:38 -04:00
|
|
|
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
|
|
|
|
You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual.
|
|
|
|
|
|
|
|
If you use POST to a HTTP 1.1 server, you can send data without knowing the
|
|
|
|
size before starting the POST if you use chunked encoding. You enable this by
|
|
|
|
adding a header like "Transfer-Encoding: chunked" with
|
|
|
|
\fICURLOPT_HTTPHEADER\fP. With HTTP 1.0 or without chunked transfer, you must
|
|
|
|
specify the size in the request.
|
|
|
|
|
2005-07-27 18:29:50 -04:00
|
|
|
When setting \fICURLOPT_POST\fP to a non-zero value, it will automatically set
|
2005-08-01 07:56:03 -04:00
|
|
|
\fICURLOPT_NOBODY\fP to 0 (since 7.14.1).
|
2005-07-27 18:29:50 -04:00
|
|
|
|
|
|
|
If you issue a POST request and then want to make a HEAD or GET using the same
|
|
|
|
re-used handle, you must explictly set the new request type using
|
2004-08-10 09:22:08 -04:00
|
|
|
\fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_POSTFIELDS
|
2004-03-24 16:40:45 -05:00
|
|
|
Pass a char * as parameter, which should be the full data to post in an HTTP
|
2004-08-10 09:22:08 -04:00
|
|
|
POST operation. You must make sure that the data is formatted the way you want
|
|
|
|
the server to receive it. libcurl will not convert or encode it for you. Most
|
|
|
|
web servers will assume this data to be url-encoded. Take note.
|
2003-02-28 02:53:31 -05:00
|
|
|
|
|
|
|
This POST is a normal application/x-www-form-urlencoded kind (and libcurl will
|
|
|
|
set that Content-Type by default when this option is used), which is the most
|
2003-11-07 04:15:28 -05:00
|
|
|
commonly used one by HTML forms. See also the \fICURLOPT_POST\fP. Using
|
|
|
|
\fICURLOPT_POSTFIELDS\fP implies \fICURLOPT_POST\fP.
|
2002-03-04 05:09:48 -05:00
|
|
|
|
2004-08-23 10:04:38 -04:00
|
|
|
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
|
|
|
|
You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
To make multipart/formdata posts (aka rfc1867-posts), check out the
|
|
|
|
\fICURLOPT_HTTPPOST\fP option.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_POSTFIELDSIZE
|
2002-03-04 05:09:48 -05:00
|
|
|
If you want to post data to the server without letting libcurl do a strlen()
|
|
|
|
to measure the data size, this option must be used. When this option is used
|
|
|
|
you can post fully binary data, which otherwise is likely to fail. If this
|
2004-11-11 18:11:32 -05:00
|
|
|
size is set to -1, the library will use strlen() to get the size.
|
2004-03-12 03:55:47 -05:00
|
|
|
.IP CURLOPT_POSTFIELDSIZE_LARGE
|
|
|
|
Pass a curl_off_t as parameter. Use this to set the size of the
|
|
|
|
\fICURLOPT_POSTFIELDS\fP data to prevent libcurl from doing strlen() on the
|
|
|
|
data to figure out the size. This is the large file version of the
|
2004-03-12 04:14:45 -05:00
|
|
|
\fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_HTTPPOST
|
2002-09-18 11:26:42 -04:00
|
|
|
Tells libcurl you want a multipart/formdata HTTP POST to be made and you
|
|
|
|
instruct what data to pass on to the server. Pass a pointer to a linked list
|
2005-01-21 03:56:04 -05:00
|
|
|
of curl_httppost structs as parameter. . The easiest way to create such a
|
|
|
|
list, is to use \fIcurl_formadd(3)\fP as documented. The data in this list
|
|
|
|
must remain intact until you close this curl handle again with
|
|
|
|
\fIcurl_easy_cleanup(3)\fP.
|
2004-08-23 10:04:38 -04:00
|
|
|
|
|
|
|
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
|
|
|
|
You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual.
|
2005-07-27 18:29:50 -04:00
|
|
|
|
|
|
|
When setting \fICURLOPT_HTTPPOST\fP, it will automatically set
|
2005-08-01 07:56:03 -04:00
|
|
|
\fICURLOPT_NOBODY\fP to 0 (since 7.14.1).
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_REFERER
|
2002-03-04 05:09:48 -05:00
|
|
|
Pass a pointer to a zero terminated string as parameter. It will be used to
|
|
|
|
set the Referer: header in the http request sent to the remote server. This
|
|
|
|
can be used to fool servers or scripts. You can also set any custom header
|
|
|
|
with \fICURLOPT_HTTPHEADER\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_USERAGENT
|
2002-03-04 05:09:48 -05:00
|
|
|
Pass a pointer to a zero terminated string as parameter. It will be used to
|
|
|
|
set the User-Agent: header in the http request sent to the remote server. This
|
|
|
|
can be used to fool servers or scripts. You can also set any custom header
|
|
|
|
with \fICURLOPT_HTTPHEADER\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_HTTPHEADER
|
2002-03-04 05:09:48 -05:00
|
|
|
Pass a pointer to a linked list of HTTP headers to pass to the server in your
|
|
|
|
HTTP request. The linked list should be a fully valid list of \fBstruct
|
|
|
|
curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to
|
|
|
|
create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire
|
|
|
|
list. If you add a header that is otherwise generated and used by libcurl
|
|
|
|
internally, your added one will be used instead. If you add a header with no
|
|
|
|
contents as in 'Accept:' (no data on the right side of the colon), the
|
|
|
|
internally used header will get disabled. Thus, using this option you can add
|
2006-01-27 10:01:10 -05:00
|
|
|
new headers, replace internal headers and remove internal headers. To add a
|
|
|
|
header with no contents, make the contents be two quotes: \&"". The headers
|
|
|
|
included in the linked list must not be CRLF-terminated, because curl adds
|
|
|
|
CRLF after each header item. Failure to comply with this will result in
|
|
|
|
strange bugs because the server will most likely ignore part of the headers
|
|
|
|
you specified.
|
|
|
|
|
|
|
|
The first line in a request (containing the method, usually a GET or POST) is
|
|
|
|
not a header and cannot be replaced using this option. Only the lines
|
|
|
|
following the request-line are headers. Adding this method line in this list
|
|
|
|
of headers will only cause your request to send an invalid header.
|
2003-06-10 09:06:38 -04:00
|
|
|
|
2004-06-22 13:22:30 -04:00
|
|
|
Pass a NULL to this to reset back to no custom headers.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
The most commonly replaced headers have "shortcuts" in the options
|
2003-11-07 04:15:28 -05:00
|
|
|
\fICURLOPT_COOKIE\fP, \fICURLOPT_USERAGENT\fP and \fICURLOPT_REFERER\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_HTTP200ALIASES
|
2003-01-09 10:04:55 -05:00
|
|
|
Pass a pointer to a linked list of aliases to be treated as valid HTTP 200
|
|
|
|
responses. Some servers respond with a custom header response line. For
|
|
|
|
example, IceCast servers respond with "ICY 200 OK". By including this string
|
|
|
|
in your list of aliases, the response will be treated as a valid HTTP header
|
|
|
|
line such as "HTTP/1.0 200 OK". (Added in 7.10.3)
|
|
|
|
|
|
|
|
The linked list should be a fully valid list of struct curl_slist structs, and
|
|
|
|
be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and
|
|
|
|
\fIcurl_slist_free_all(3)\fP to clean up an entire list.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
The alias itself is not parsed for any version strings. So if your alias is
|
|
|
|
\&"MYHTTP/9.9", Libcurl will not treat the server as responding with HTTP
|
|
|
|
version 9.9. Instead Libcurl will use the value set by option
|
2003-01-09 10:04:55 -05:00
|
|
|
\fICURLOPT_HTTP_VERSION\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_COOKIE
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a pointer to a zero terminated string as parameter. It will be used to
|
|
|
|
set a cookie in the http request. The format of the string should be
|
|
|
|
NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie
|
|
|
|
should contain.
|
|
|
|
|
2004-03-24 16:40:45 -05:00
|
|
|
If you need to set multiple cookies, you need to set them all using a single
|
|
|
|
option and thus you need to concatenate them all in one single string. Set
|
|
|
|
multiple cookies in one string like this: "name1=content1; name2=content2;"
|
|
|
|
etc.
|
2002-09-18 11:26:42 -04:00
|
|
|
|
|
|
|
Using this option multiple times will only make the latest string override the
|
|
|
|
previously ones.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_COOKIEFILE
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a pointer to a zero terminated string as parameter. It should contain the
|
|
|
|
name of your file holding cookie data to read. The cookie data may be in
|
|
|
|
Netscape / Mozilla cookie data format or just regular HTTP-style headers
|
|
|
|
dumped to a file.
|
2002-03-04 05:09:48 -05:00
|
|
|
|
2005-03-03 19:26:50 -05:00
|
|
|
Given an empty or non-existing file or by passing the empty string (""), this
|
|
|
|
option will enable cookies for this curl handle, making it understand and
|
|
|
|
parse received cookies and then use matching cookies in future request.
|
2005-08-19 17:38:44 -04:00
|
|
|
|
|
|
|
If you use this option multiple times, you just add more files to read.
|
|
|
|
Subsequent files will add more cookies.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_COOKIEJAR
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a file name as char *, zero terminated. This will make libcurl write all
|
|
|
|
internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP
|
|
|
|
is called. If no cookies are known, no file will be created. Specify "-" to
|
|
|
|
instead have the cookies written to stdout. Using this option also enables
|
|
|
|
cookies for this session, so if you for example follow a location it will make
|
2003-08-15 02:35:41 -04:00
|
|
|
matching cookies get sent accordingly.
|
2003-04-11 04:19:06 -04:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
If the cookie jar file can't be created or written to (when the
|
2004-02-27 10:34:06 -05:00
|
|
|
\fIcurl_easy_cleanup(3)\fP is called), libcurl will not and cannot report an
|
|
|
|
error for this. Using \fICURLOPT_VERBOSE\fP or \fICURLOPT_DEBUGFUNCTION\fP
|
|
|
|
will get a warning to display, but that is the only visible feedback you get
|
|
|
|
about this possibly lethal situation.
|
2004-02-27 04:02:06 -05:00
|
|
|
.IP CURLOPT_COOKIESESSION
|
|
|
|
Pass a long set to non-zero to mark this as a new cookie "session". It will
|
|
|
|
force libcurl to ignore all cookies it is about to load that are "session
|
|
|
|
cookies" from the previous session. By default, libcurl always stores and
|
|
|
|
loads all cookies, independent if they are session cookies are not. Session
|
|
|
|
cookies are cookies without expiry date and they are meant to be alive and
|
|
|
|
existing for this "session" only.
|
2005-07-27 18:17:14 -04:00
|
|
|
.IP CURLOPT_COOKIELIST
|
|
|
|
Pass a char * to a cookie string. Cookie can be either in Netscape / Mozilla
|
2005-07-30 04:27:51 -04:00
|
|
|
format or just regular HTTP-style header (Set-Cookie: ...) format. If cURL
|
|
|
|
cookie engine was not enabled it will enable its cookie engine. Passing a
|
2005-08-25 03:06:50 -04:00
|
|
|
magic string \&"ALL" will erase all cookies known by cURL. (Added in 7.14.1)
|
2006-05-24 18:46:38 -04:00
|
|
|
Passing the special string \&"SESS" will only erase all session cookies known
|
|
|
|
by cURL. (Added in 7.15.4)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_HTTPGET
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long. If the long is non-zero, this forces the HTTP request to get back
|
2004-09-01 05:25:19 -04:00
|
|
|
to GET. usable if a POST, HEAD, PUT or a custom request have been used
|
2003-08-15 02:35:41 -04:00
|
|
|
previously using the same curl handle.
|
2005-07-27 18:29:50 -04:00
|
|
|
|
|
|
|
When setting \fICURLOPT_HTTPGET\fP to a non-zero value, it will automatically
|
2005-08-01 07:56:03 -04:00
|
|
|
set \fICURLOPT_NOBODY\fP to 0 (since 7.14.1).
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_HTTP_VERSION
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long, set to one of the values described below. They force libcurl to
|
|
|
|
use the specific HTTP versions. This is not sensible to do unless you have a
|
|
|
|
good reason.
|
|
|
|
.RS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURL_HTTP_VERSION_NONE
|
2002-09-18 11:26:42 -04:00
|
|
|
We don't care about what version the library uses. libcurl will use whatever
|
|
|
|
it thinks fit.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURL_HTTP_VERSION_1_0
|
2002-09-18 11:26:42 -04:00
|
|
|
Enforce HTTP 1.0 requests.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURL_HTTP_VERSION_1_1
|
2002-09-18 11:26:42 -04:00
|
|
|
Enforce HTTP 1.1 requests.
|
2005-08-24 06:57:28 -04:00
|
|
|
.IP CURLOPT_IGNORE_CONTENT_LENGTH
|
2005-08-25 03:06:50 -04:00
|
|
|
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)
|
2002-09-18 11:26:42 -04:00
|
|
|
.RE
|
|
|
|
.SH FTP OPTIONS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FTPPORT
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a pointer to a zero terminated string as parameter. It will be used to
|
|
|
|
get the IP address to use for the ftp PORT instruction. The PORT instruction
|
|
|
|
tells the remote server to connect to our specified IP address. The string may
|
|
|
|
be a plain IP address, a host name, an network interface name (under Unix) or
|
|
|
|
just a '-' letter to let the library use your systems default IP
|
|
|
|
address. Default FTP operations are passive, and thus won't use PORT.
|
2003-02-17 18:23:11 -05:00
|
|
|
|
|
|
|
You disable PORT again and go back to using the passive version by setting
|
|
|
|
this option to NULL.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_QUOTE
|
2002-03-04 05:09:48 -05:00
|
|
|
Pass a pointer to a linked list of FTP commands to pass to the server prior to
|
2002-09-18 11:26:42 -04:00
|
|
|
your ftp request. This will be done before any other FTP commands are issued
|
|
|
|
(even before the CWD command). The linked list should be a fully valid list of
|
|
|
|
'struct curl_slist' structs properly filled in. Use \fIcurl_slist_append(3)\fP
|
|
|
|
to append strings (commands) to the list, and clear the entire list afterwards
|
2002-03-04 05:09:48 -05:00
|
|
|
with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a
|
|
|
|
NULL to this option.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_POSTQUOTE
|
2002-03-04 05:09:48 -05:00
|
|
|
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
|
|
|
|
\fICURLOPT_QUOTE\fP. Disable this operation again by setting a NULL to this
|
|
|
|
option.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_PREQUOTE
|
2002-09-18 11:26:42 -04:00
|
|
|
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
|
|
|
|
\fICURLOPT_QUOTE\fP. Disable this operation again by setting a NULL to this
|
2006-08-08 18:56:46 -04:00
|
|
|
option. Before version 7.15.6, if you also set \fICURLOPT_NOBODY\fP non-zero,
|
|
|
|
this option didn't work.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FTPLISTONLY
|
2002-09-18 11:26:42 -04:00
|
|
|
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.
|
2002-08-07 04:23:40 -04:00
|
|
|
|
2002-09-18 11:26:42 -04:00
|
|
|
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.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FTPAPPEND
|
2002-09-18 11:26:42 -04:00
|
|
|
A non-zero parameter tells the library to append to the remote file instead of
|
2004-03-24 16:40:45 -05:00
|
|
|
overwrite it. This is only useful when uploading to an ftp site.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FTP_USE_EPRT
|
2003-05-14 05:03:51 -04:00
|
|
|
Pass a long. If the value is non-zero, it tells curl to use the EPRT (and
|
|
|
|
LPRT) command when doing active FTP downloads (which is enabled by
|
2003-11-07 04:15:28 -05:00
|
|
|
\fICURLOPT_FTPPORT\fP). Using EPRT means that it will first attempt to use
|
|
|
|
EPRT and then LPRT before using PORT, but if you pass FALSE (zero) to this
|
|
|
|
option, it will not try using EPRT or LPRT, only plain PORT. (Added in 7.10.5)
|
2004-11-29 16:25:07 -05:00
|
|
|
|
|
|
|
If the server is an IPv6 host, this option will have no effect as of 7.12.3.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FTP_USE_EPSV
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long. If the value is non-zero, it tells curl to use the EPSV command
|
|
|
|
when doing passive FTP downloads (which it always does by default). Using EPSV
|
|
|
|
means that it will first attempt to use EPSV before using PASV, but if you
|
|
|
|
pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV.
|
2004-11-29 16:25:07 -05:00
|
|
|
|
|
|
|
If the server is an IPv6 host, this option will have no effect as of 7.12.3.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FTP_CREATE_MISSING_DIRS
|
2003-08-08 07:04:35 -04:00
|
|
|
Pass a long. If the value is non-zero, curl will attempt to create any remote
|
|
|
|
directory that it fails to CWD into. CWD is the command that changes working
|
|
|
|
directory. (Added in 7.10.7)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FTP_RESPONSE_TIMEOUT
|
2003-09-05 07:02:11 -04:00
|
|
|
Pass a long. Causes curl to set a timeout period (in seconds) on the amount
|
|
|
|
of time that the server is allowed to take in order to generate a response
|
2005-09-21 02:59:01 -04:00
|
|
|
message for a command before the session is considered hung. While curl is
|
|
|
|
waiting for a response, this value overrides \fICURLOPT_TIMEOUT\fP. It is
|
|
|
|
recommended that if used in conjunction with \fICURLOPT_TIMEOUT\fP, you set
|
2003-11-07 04:15:28 -05:00
|
|
|
\fICURLOPT_FTP_RESPONSE_TIMEOUT\fP to a value smaller than
|
|
|
|
\fICURLOPT_TIMEOUT\fP. (Added in 7.10.8)
|
2006-07-25 18:45:21 -04:00
|
|
|
.IP CURLOPT_FTP_ALTERNATIVE_TO_USER
|
|
|
|
Pass a char * as parameter, pointing to a string which will be used to
|
|
|
|
authenticate if the usual FTP "USER user" and "PASS password" negotiation
|
|
|
|
fails. This is currently only known to be required when connecting to
|
|
|
|
Tumbleweed's Secure Transport FTPS server using client certificates for
|
|
|
|
authentication. (Added in 7.15.5)
|
2005-09-04 01:16:06 -04:00
|
|
|
.IP CURLOPT_FTP_SKIP_PASV_IP
|
|
|
|
Pass a long. If set to a non-zero value, it instructs libcurl to not use the
|
|
|
|
IP address the server suggests in its 227-response to libcurl's PASV command
|
|
|
|
when libcurl connects the data connection. Instead libcurl will re-use the
|
|
|
|
same IP address it already uses for the control connection. But it will use
|
2005-09-04 01:23:08 -04:00
|
|
|
the port number from the 227-response. (Added in 7.14.2)
|
2005-09-04 01:16:06 -04:00
|
|
|
|
|
|
|
This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
|
2004-02-27 04:02:06 -05:00
|
|
|
.IP CURLOPT_FTP_SSL
|
|
|
|
Pass a long using one of the values from below, to make libcurl use your
|
|
|
|
desired level of SSL for the ftp transfer. (Added in 7.11.0)
|
|
|
|
.RS
|
|
|
|
.IP CURLFTPSSL_NONE
|
|
|
|
Don't attempt to use SSL.
|
|
|
|
.IP CURLFTPSSL_TRY
|
|
|
|
Try using SSL, proceed as normal otherwise.
|
|
|
|
.IP CURLFTPSSL_CONTROL
|
|
|
|
Require SSL for the control connection or fail with \fICURLE_FTP_SSL_FAILED\fP.
|
|
|
|
.IP CURLFTPSSL_ALL
|
|
|
|
Require SSL for all communication or fail with \fICURLE_FTP_SSL_FAILED\fP.
|
|
|
|
.RE
|
2004-09-16 17:45:16 -04:00
|
|
|
.IP CURLOPT_FTPSSLAUTH
|
|
|
|
Pass a long using one of the values from below, to alter how libcurl issues
|
|
|
|
\&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated (see
|
2004-12-03 06:25:06 -05:00
|
|
|
\fICURLOPT_FTP_SSL\fP). (Added in 7.12.2)
|
2004-09-16 17:45:16 -04:00
|
|
|
.RS
|
|
|
|
.IP CURLFTPAUTH_DEFAULT
|
|
|
|
Allow libcurl to decide
|
|
|
|
.IP CURLFTPAUTH_SSL
|
|
|
|
Try "AUTH SSL" first, and only if that fails try "AUTH TLS"
|
|
|
|
.IP CURLFTPAUTH_TLS
|
|
|
|
Try "AUTH TLS" first, and only if that fails try "AUTH SSL"
|
|
|
|
.RE
|
2005-01-25 17:13:12 -05:00
|
|
|
.IP CURLOPT_FTP_ACCOUNT
|
|
|
|
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)
|
2006-03-13 19:05:15 -05:00
|
|
|
.IP CURLOPT_FTP_FILEMETHOD
|
|
|
|
Pass a long that should have one of the following values. This option controls
|
|
|
|
what method libcurl should use to reach a file on a FTP(S) server. The
|
|
|
|
argument should be one of the following alternatives:
|
|
|
|
.RS
|
|
|
|
.IP CURLFTPMETHOD_MULTICWD
|
|
|
|
libcurl does a single CWD operation for each path part in the given URL. For
|
|
|
|
deep hierarchies this means very many commands. This is how RFC1738 says it
|
|
|
|
should be done. This is the default but the slowest behavior.
|
|
|
|
.IP CURLFTPMETHOD_NOCWD
|
|
|
|
libcurl does no CWD at all. libcurl will do SIZE, RETR, STOR etc and give a
|
|
|
|
full path to the server for all these commands. This is the fastest behavior.
|
|
|
|
.IP CURLFTPMETHOD_SINGLECWD
|
|
|
|
libcurl does one CWD with the full target directory and then operates on the
|
|
|
|
file \&"normally" (like in the multicwd case). This is somewhat more standards
|
|
|
|
compliant than 'nocwd' but without the full penalty of 'multicwd'.
|
|
|
|
.RE
|
2002-09-18 11:26:42 -04:00
|
|
|
.SH PROTOCOL OPTIONS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_TRANSFERTEXT
|
2002-09-18 11:26:42 -04:00
|
|
|
A non-zero parameter tells the library to use ASCII mode for ftp transfers,
|
2005-06-26 06:08:08 -04:00
|
|
|
instead of the default binary transfer. For win32 systems it does not set the
|
|
|
|
stdout to binary mode. This option can be usable when transferring text data
|
|
|
|
between systems with different views on certain characters, such as newlines
|
|
|
|
or similar.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
libcurl does not do a complete ASCII conversion when doing ASCII transfers
|
|
|
|
over FTP. This is a known limitation/flaw that nobody has rectified. libcurl
|
|
|
|
simply sets the mode to ascii and performs a standard transfer.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_CRLF
|
2002-09-18 11:26:42 -04:00
|
|
|
Convert Unix newlines to CRLF newlines on transfers.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_RANGE
|
2002-09-18 11:26:42 -04:00
|
|
|
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
|
|
|
|
\fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP
|
|
|
|
server to send the response document in pieces (using standard MIME separation
|
2004-06-09 04:05:23 -04:00
|
|
|
techniques). Pass a NULL to this option to disable the use of ranges.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_RESUME_FROM
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long as parameter. It contains the offset in number of bytes that you
|
2004-06-09 04:05:23 -04:00
|
|
|
want the transfer to start from. Set this option to 0 to make the transfer
|
2006-09-26 06:38:24 -04:00
|
|
|
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).
|
2004-01-05 17:29:29 -05:00
|
|
|
.IP CURLOPT_RESUME_FROM_LARGE
|
2004-08-16 06:49:57 -04:00
|
|
|
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)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_CUSTOMREQUEST
|
2002-03-04 05:09:48 -05:00
|
|
|
Pass a pointer to a zero terminated string as parameter. It will be user
|
2004-03-24 16:40:45 -05:00
|
|
|
instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST
|
2003-06-26 07:40:44 -04:00
|
|
|
when doing an ftp directory listing. This is useful for doing DELETE or other
|
|
|
|
more or less obscure HTTP requests. Don't do this at will, make sure your
|
|
|
|
server supports the command first.
|
2003-06-10 09:06:38 -04:00
|
|
|
|
2004-06-27 17:19:54 -04:00
|
|
|
Restore to the internal default by setting this to NULL.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
Many people have wrongly used this option to replace the entire request with
|
|
|
|
their own, including multiple headers and POST contents. While that might work
|
|
|
|
in many cases, it will cause libcurl to send invalid requests and it could
|
|
|
|
possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and
|
|
|
|
\fICURLOPT_POSTFIELDS\fP to set POST data. Use \fICURLOPT_HTTPHEADER\fP to
|
2003-06-10 09:06:38 -04:00
|
|
|
replace or extend the set of headers sent by libcurl. Use
|
|
|
|
\fICURLOPT_HTTP_VERSION\fP to change HTTP version.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FILETIME
|
2002-03-04 05:09:48 -05:00
|
|
|
Pass a long. If it is a non-zero value, libcurl will attempt to get the
|
|
|
|
modification date of the remote document in this operation. This requires that
|
|
|
|
the remote server sends the time or replies to a time querying command. The
|
|
|
|
\fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME\fP argument
|
2003-08-15 02:35:41 -04:00
|
|
|
can be used after a transfer to extract the received time (if any).
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_NOBODY
|
2002-09-18 11:26:42 -04:00
|
|
|
A non-zero parameter tells the library to not include the body-part in the
|
|
|
|
output. This is only relevant for protocols that have separate header and body
|
2003-10-04 10:01:41 -04:00
|
|
|
parts. On HTTP(S) servers, this will make libcurl do a HEAD request.
|
2004-09-01 08:05:59 -04:00
|
|
|
|
2005-08-01 07:56:03 -04:00
|
|
|
To change request to GET, you should use \fICURLOPT_HTTPGET\fP. Change request
|
|
|
|
to POST with \fICURLOPT_POST\fP etc.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_INFILESIZE
|
2002-09-18 11:26:42 -04:00
|
|
|
When uploading a file to a remote site, this option should be used to tell
|
2004-01-05 17:29:29 -05:00
|
|
|
libcurl what the expected size of the infile is. This value should be passed
|
|
|
|
as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP.
|
|
|
|
.IP CURLOPT_INFILESIZE_LARGE
|
|
|
|
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
|
2004-01-23 07:52:04 -05:00
|
|
|
as a curl_off_t. (Added in 7.11.0)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_UPLOAD
|
2002-09-18 11:26:42 -04:00
|
|
|
A non-zero parameter tells the library to prepare for an upload. The
|
2006-08-09 16:54:17 -04:00
|
|
|
\fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP or
|
|
|
|
\fICURLOPT_INFILESIZE_LARGE\fP options are also interesting for uploads. If
|
|
|
|
the protocol is HTTP, uploading means using the PUT request unless you tell
|
2004-08-23 10:04:38 -04:00
|
|
|
libcurl otherwise.
|
|
|
|
|
|
|
|
Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
|
|
|
|
You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual.
|
|
|
|
|
|
|
|
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
|
|
|
|
\fICURLOPT_HTTPHEADER\fP. With HTTP 1.0 or without chunked transfer, you must
|
|
|
|
specify the size.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_MAXFILESIZE
|
2003-10-17 09:11:00 -04:00
|
|
|
Pass a long as parameter. This allows you to specify the maximum size (in
|
|
|
|
bytes) of a file to download. If the file requested is larger than this value,
|
2004-01-05 17:29:29 -05:00
|
|
|
the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
The file size is not always known prior to download, and for such files this
|
|
|
|
option has no effect even if the file transfer ends up being larger than this
|
|
|
|
given limit. This concerns both FTP and HTTP transfers.
|
2004-01-05 17:29:29 -05:00
|
|
|
.IP CURLOPT_MAXFILESIZE_LARGE
|
2004-01-23 07:52:04 -05:00
|
|
|
Pass a curl_off_t as parameter. This allows you to specify the maximum size
|
|
|
|
(in bytes) of a file to download. If the file requested is larger than this
|
|
|
|
value, the transfer will not start and \fICURLE_FILESIZE_EXCEEDED\fP will be
|
|
|
|
returned. (Added in 7.11.0)
|
2003-10-17 09:11:00 -04:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
The file size is not always known prior to download, and for such files this
|
|
|
|
option has no effect even if the file transfer ends up being larger than this
|
|
|
|
given limit. This concerns both FTP and HTTP transfers.
|
2004-02-09 08:51:52 -05:00
|
|
|
.IP CURLOPT_TIMECONDITION
|
|
|
|
Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE\fP time
|
|
|
|
value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP
|
|
|
|
or \fICURL_TIMECOND_IFUNMODSINCE\fP. This feature applies to HTTP and FTP.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
The last modification time of a file is not always known and in such instances
|
|
|
|
this feature will have no effect even if the given time condition would have
|
|
|
|
not been met.
|
2004-02-09 08:51:52 -05:00
|
|
|
.IP CURLOPT_TIMEVALUE
|
|
|
|
Pass a long as parameter. This should be the time in seconds since 1 jan 1970,
|
2004-05-17 03:12:32 -04:00
|
|
|
and the time will be used in a condition as specified with
|
2004-02-09 08:51:52 -05:00
|
|
|
\fICURLOPT_TIMECONDITION\fP.
|
2002-09-18 11:26:42 -04:00
|
|
|
.SH CONNECTION OPTIONS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_TIMEOUT
|
2002-09-18 11:26:42 -04:00
|
|
|
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.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
In unix-like systems, this might cause signals to be used unless
|
|
|
|
\fICURLOPT_NOSIGNAL\fP is set.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_LOW_SPEED_LIMIT
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long as parameter. It contains the transfer speed in bytes per second
|
2003-11-07 04:15:28 -05:00
|
|
|
that the transfer should be below during \fICURLOPT_LOW_SPEED_TIME\fP seconds
|
|
|
|
for the library to consider it too slow and abort.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_LOW_SPEED_TIME
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a long as parameter. It contains the time in seconds that the transfer
|
2003-11-07 04:15:28 -05:00
|
|
|
should be below the \fICURLOPT_LOW_SPEED_LIMIT\fP for the library to consider
|
|
|
|
it too slow and abort.
|
2006-06-22 17:36:53 -04:00
|
|
|
.IP CURLOPT_MAX_SEND_SPEED_LARGE
|
2006-09-08 08:46:41 -04:00
|
|
|
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. Defaults to unlimited
|
|
|
|
speed. (Added in 7.15.5)
|
2006-06-22 17:36:53 -04:00
|
|
|
.IP CURLOPT_MAX_RECV_SPEED_LARGE
|
2006-09-08 08:46:41 -04:00
|
|
|
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. Defaults to unlimited speed. (Added
|
|
|
|
in 7.15.5)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_MAXCONNECTS
|
2002-09-13 08:37:14 -04:00
|
|
|
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.
|
|
|
|
|
|
|
|
When reaching the maximum limit, curl uses the \fICURLOPT_CLOSEPOLICY\fP to
|
|
|
|
figure out which of the existing connections to close to prevent the number of
|
|
|
|
open connections to increase.
|
2002-03-04 05:09:48 -05:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
If you already have performed transfers with this curl handle, setting a
|
|
|
|
smaller MAXCONNECTS than before may cause open connections to get closed
|
|
|
|
unnecessarily.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_CLOSEPOLICY
|
2002-03-04 05:09:48 -05:00
|
|
|
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 \fICURLCLOSEPOLICY_LEAST_RECENTLY_USED\fP to make libcurl close
|
|
|
|
the connection that was least recently used, that connection is also least
|
|
|
|
likely to be capable of re-use. Use \fICURLCLOSEPOLICY_OLDEST\fP 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
|
2003-08-15 02:35:41 -04:00
|
|
|
yet.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FRESH_CONNECT
|
2002-03-04 05:09:48 -05:00
|
|
|
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
|
2003-08-15 02:35:41 -04:00
|
|
|
existing connection (default behavior).
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_FORBID_REUSE
|
2002-03-04 05:09:48 -05:00
|
|
|
Pass a long. Set to non-zero to make the next transfer explicitly close the
|
|
|
|
connection when done. Normally, libcurl keep all connections alive when done
|
|
|
|
with one transfer in case there comes a succeeding one that can re-use them.
|
|
|
|
This option should be used with caution and only if you understand what it
|
|
|
|
does. Set to 0 to have libcurl keep the connection open for possibly later
|
2003-08-15 02:35:41 -04:00
|
|
|
re-use (default behavior).
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_CONNECTTIMEOUT
|
2002-03-04 05:09:48 -05:00
|
|
|
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 \fICURLOPT_TIMEOUT\fP option.
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
In unix-like systems, this might cause signals to be used unless
|
|
|
|
\fICURLOPT_NOSIGNAL\fP is set.
|
2003-12-22 05:53:55 -05:00
|
|
|
.IP CURLOPT_IPRESOLVE
|
|
|
|
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:
|
|
|
|
.RS
|
|
|
|
.IP CURL_IPRESOLVE_WHATEVER
|
|
|
|
Default, resolves addresses to all IP versions that your system allows.
|
|
|
|
.IP CURL_IPRESOLVE_V4
|
|
|
|
Resolve to ipv4 addresses.
|
|
|
|
.IP CURL_IPRESOLVE_V6
|
|
|
|
Resolve to ipv6 addresses.
|
|
|
|
.RE
|
2006-06-20 03:03:29 -04:00
|
|
|
.IP CURLOPT_CONNECT_ONLY
|
2006-02-11 17:35:16 -05:00
|
|
|
Pass a long. A non-zero parameter tells the library to perform any required
|
|
|
|
proxy authentication and connection setup, but no data transfer.
|
|
|
|
|
|
|
|
This option is useful with the \fICURLINFO_LASTSOCKET\fP option to
|
|
|
|
\fIcurl_easy_getinfo(3)\fP. The library can set up the connection and then the
|
|
|
|
application can obtain the most recently used socket for special data
|
|
|
|
transfers. (Added in 7.15.2)
|
2002-09-18 11:26:42 -04:00
|
|
|
.SH SSL and SECURITY OPTIONS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_SSLCERT
|
2002-09-18 11:26:42 -04:00
|
|
|
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 \fICURLOPT_SSLCERTTYPE\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_SSLCERTTYPE
|
2002-09-18 11:26:42 -04:00
|
|
|
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)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_SSLCERTPASSWD
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a pointer to a zero terminated string as parameter. It will be used as
|
2003-11-07 08:26:45 -05:00
|
|
|
the password required to use the \fICURLOPT_SSLCERT\fP certificate.
|
2002-09-18 11:26:42 -04:00
|
|
|
|
2003-11-07 08:26:45 -05:00
|
|
|
This option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and should only be used
|
|
|
|
for backward compatibility. You never needed a pass phrase to load a
|
|
|
|
certificate but you need one to load your private key.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_SSLKEY
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a pointer to a zero terminated string as parameter. The string should be
|
|
|
|
the file name of your private key. The default format is "PEM" and can be
|
2003-08-15 02:35:41 -04:00
|
|
|
changed with \fICURLOPT_SSLKEYTYPE\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_SSLKEYTYPE
|
2002-09-18 11:26:42 -04:00
|
|
|
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".
|
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
The format "ENG" enables you to load the private key from a crypto engine. In
|
|
|
|
this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to the
|
|
|
|
engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE\fP.
|
2004-05-17 03:12:32 -04:00
|
|
|
\&"DER" format key file currently does not work because of a bug in OpenSSL.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_SSLKEYPASSWD
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a pointer to a zero terminated string as parameter. It will be used as
|
2003-11-07 08:26:45 -05:00
|
|
|
the password required to use the \fICURLOPT_SSLKEY\fP private key.
|
2004-02-27 04:02:06 -05:00
|
|
|
.IP CURLOPT_SSLENGINE
|
2002-09-18 11:26:42 -04:00
|
|
|
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
|
2003-08-15 02:35:41 -04:00
|
|
|
key.
|
2002-09-18 11:26:42 -04:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
If the crypto device cannot be loaded, \fICURLE_SSL_ENGINE_NOTFOUND\fP is
|
|
|
|
returned.
|
2004-02-27 04:02:06 -05:00
|
|
|
.IP CURLOPT_SSLENGINE_DEFAULT
|
2004-03-24 16:40:45 -05:00
|
|
|
Sets the actual crypto engine as the default for (asymmetric) crypto
|
2003-08-15 02:35:41 -04:00
|
|
|
operations.
|
2002-09-18 11:26:42 -04:00
|
|
|
|
2005-09-21 02:59:01 -04:00
|
|
|
If the crypto device cannot be set, \fICURLE_SSL_ENGINE_SETFAILED\fP is
|
|
|
|
returned.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_SSLVERSION
|
2005-05-12 17:49:42 -04:00
|
|
|
Pass a long as parameter to control what version of SSL/TLS to attempt to use.
|
|
|
|
The available options are:
|
|
|
|
.RS
|
|
|
|
.IP CURL_SSLVERSION_DEFAULT
|
|
|
|
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.
|
|
|
|
.IP CURL_SSLVERSION_TLSv1
|
|
|
|
Force TLSv1
|
|
|
|
.IP CURL_SSLVERSION_SSLv2
|
|
|
|
Force SSLv2
|
|
|
|
.IP CURL_SSLVERSION_SSLv3
|
|
|
|
Force SSLv3
|
|
|
|
.RE
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_SSL_VERIFYPEER
|
2005-05-02 03:28:40 -04:00
|
|
|
Pass a long as parameter.
|
|
|
|
|
|
|
|
This option determines whether curl verifies the authenticity of the
|
|
|
|
peer's certificate. A nonzero value means curl verifies; zero means it
|
|
|
|
doesn't. The default is nonzero, but before 7.10, it was zero.
|
|
|
|
|
|
|
|
When negotiating an SSL connection, the server sends a certificate
|
|
|
|
indicating its identity. Curl verifies whether the certificate is
|
|
|
|
authentic, i.e. that you can trust that the server is who the
|
|
|
|
certificate says it is. This trust is based on a chain of digital
|
|
|
|
signatures, rooted in certification authority (CA) certificates you
|
|
|
|
supply. As of 7.10, curl installs a default bundle of CA certificates
|
|
|
|
and you can specify alternate certificates with the
|
|
|
|
\fICURLOPT_CAINFO\fP option or the \fICURLOPT_CAPATH\fP option.
|
|
|
|
|
|
|
|
When \fICURLOPT_SSL_VERIFYPEER\fP is nonzero, and the verification
|
|
|
|
fails to prove that the certificate is authentic, the connection
|
|
|
|
fails. When the option is zero, the connection succeeds regardless.
|
|
|
|
|
|
|
|
Authenticating the certificate is not by itself very useful. You
|
|
|
|
typically want to ensure that the server, as authentically identified
|
|
|
|
by its certificate, is the server you mean to be talking to. Use
|
|
|
|
\fICURLOPT_SSL_VERIFYHOST\fP to control that.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_CAINFO
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a char * to a zero terminated string naming a file holding one or more
|
2005-05-02 03:28:40 -04:00
|
|
|
certificates to verify the peer with. This makes sense only when used in
|
|
|
|
combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If
|
|
|
|
\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_CAINFO\fP need not
|
|
|
|
even indicate an accessible file.
|
2006-03-02 17:09:30 -05:00
|
|
|
|
|
|
|
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.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_CAPATH
|
2005-05-02 03:28:40 -04:00
|
|
|
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
|
|
|
|
\fICURLOPT_SSL_VERIFYPEER\fP option. If \fICURLOPT_SSL_VERIFYPEER\fP
|
|
|
|
is zero, \fICURLOPT_CAPATH\fP need not even indicate an accessible
|
|
|
|
path. The \fICURLOPT_CAPATH\fP function apparently does not work in
|
|
|
|
Windows due to some limitation in openssl. (Added in 7.9.8)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_RANDOM_FILE
|
2002-09-18 11:26:42 -04:00
|
|
|
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.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_EGDSOCKET
|
2002-09-18 11:26:42 -04:00
|
|
|
Pass a char * to the zero terminated path name to the Entropy Gathering Daemon
|
|
|
|
socket. It will be used to seed the random engine for SSL.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_SSL_VERIFYHOST
|
2005-05-02 03:28:40 -04:00
|
|
|
Pass a long as parameter.
|
|
|
|
|
2005-10-13 17:49:28 -04:00
|
|
|
This option determines whether libcurl verifies that the server cert is for
|
|
|
|
the server it is known as.
|
2005-05-02 03:28:40 -04:00
|
|
|
|
2005-10-13 17:49:28 -04:00
|
|
|
When negotiating an SSL connection, the server sends a certificate indicating
|
|
|
|
its identity.
|
2005-05-02 03:28:40 -04:00
|
|
|
|
2005-10-13 17:49:28 -04:00
|
|
|
When \fICURLOPT_SSL_VERIFYHOST\fP is 2, that certificate must indicate that
|
|
|
|
the server is the server to which you meant to connect, or the connection
|
|
|
|
fails.
|
2005-05-02 03:28:40 -04:00
|
|
|
|
2005-10-13 17:49:28 -04:00
|
|
|
Curl considers the server the intended one when the Common Name field or a
|
|
|
|
Subject Alternate Name field in the certificate matches the host name in the
|
|
|
|
URL to which you told Curl to connect.
|
2005-05-02 03:28:40 -04:00
|
|
|
|
2005-10-13 17:49:28 -04:00
|
|
|
When the value is 1, the certificate must contain a Common Name field, but it
|
|
|
|
doesn't matter what name it says. (This is not ordinarily a useful setting).
|
2005-05-02 03:28:40 -04:00
|
|
|
|
2005-10-13 17:49:28 -04:00
|
|
|
When the value is 0, the connection succeeds regardless of the names in the
|
|
|
|
certificate.
|
2005-05-02 03:28:40 -04:00
|
|
|
|
|
|
|
The default, since 7.10, is 2.
|
|
|
|
|
|
|
|
The checking this option controls is of the identity that the server
|
|
|
|
\fIclaims\fP. The server could be lying. To control lying, see
|
|
|
|
\fICURLOPT_SSL_VERIFYPEER\fP.
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_SSL_CIPHER_LIST
|
2002-03-04 05:09:48 -05:00
|
|
|
Pass a char *, pointing to a zero terminated string holding the list of
|
2004-03-24 16:40:45 -05:00
|
|
|
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
|
2002-03-04 05:09:48 -05:00
|
|
|
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.
|
|
|
|
|
|
|
|
You'll find more details about cipher lists on this URL:
|
|
|
|
\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP
|
2006-09-11 13:18:18 -04:00
|
|
|
.IP CURLOPT_SSL_SESSIONID_CACHE
|
|
|
|
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)
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_KRB4LEVEL
|
2002-09-18 11:26:42 -04:00
|
|
|
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
|
2003-08-15 02:35:41 -04:00
|
|
|
support only works for FTP.
|
2006-11-02 17:10:18 -05:00
|
|
|
.SH SSH OPTIONS
|
|
|
|
.IP CURLOPT_SSH_AUTH_TYPES
|
|
|
|
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.
|
|
|
|
.IP CURLOPT_SSH_PUBLIC_KEYFILE
|
|
|
|
Pass a char * pointing to a file name for your public key. If not used,
|
|
|
|
libcurl defaults to using \fB~/.ssh/id_dsa.pub\fP.
|
|
|
|
.IP CURLOPT_SSH_PRIVATE_KEYFILE
|
|
|
|
Pass a char * pointing to a file name for your private key. If not used,
|
|
|
|
libcurl defaults to using \fB~/.ssh/id_dsa\fP.
|
2002-11-20 14:11:22 -05:00
|
|
|
.SH OTHER OPTIONS
|
2003-11-04 07:55:53 -05:00
|
|
|
.IP CURLOPT_PRIVATE
|
2002-12-01 06:23:06 -05:00
|
|
|
Pass a char * as parameter, pointing to data that should be associated with
|
2003-12-04 08:01:30 -05:00
|
|
|
this curl handle. The pointer can subsequently be retrieved using
|
2004-02-27 10:34:06 -05:00
|
|
|
\fIcurl_easy_getinfo(3)\fP with the CURLINFO_PRIVATE option. libcurl itself
|
|
|
|
does nothing with this data. (Added in 7.10.3)
|
2004-02-25 07:20:41 -05:00
|
|
|
.IP CURLOPT_SHARE
|
|
|
|
Pass a share handle as a parameter. The share handle must have been created by
|
2004-02-25 07:32:33 -05:00
|
|
|
a previous call to \fIcurl_share_init(3)\fP. Setting this option, will make
|
|
|
|
this curl handle use the data from the shared handle instead of keeping the
|
|
|
|
data to itself. This enables several curl handles to share data. If the curl
|
|
|
|
handles are used simultaneously, you \fBMUST\fP use the locking methods in the
|
|
|
|
share handle. See \fIcurl_share_setopt(3)\fP for details.
|
2004-02-27 04:02:06 -05:00
|
|
|
.SH TELNET OPTIONS
|
|
|
|
.IP CURLOPT_TELNETOPTIONS
|
|
|
|
Provide a pointer to a curl_slist with variables to pass to the telnet
|
|
|
|
negotiations. The variables should be in the format <option=value>. libcurl
|
|
|
|
supports the options 'TTYPE', 'XDISPLOC' and 'NEW_ENV'. See the TELNET
|
|
|
|
standard for details.
|
2002-03-04 05:09:48 -05:00
|
|
|
.SH RETURN VALUE
|
|
|
|
CURLE_OK (zero) means that the option was set properly, non-zero means an
|
2004-02-27 10:34:06 -05:00
|
|
|
error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors(3)\fP
|
2002-04-12 07:39:27 -04:00
|
|
|
man page for the full list with descriptions.
|
2004-06-03 07:19:35 -04:00
|
|
|
|
|
|
|
If you try to set an option that libcurl doesn't know about, perhaps because
|
|
|
|
the library is too old to support it or the option was removed in a recent
|
|
|
|
version, this function will return \fICURLE_FAILED_INIT\fP.
|
2002-03-04 05:09:48 -05:00
|
|
|
.SH "SEE ALSO"
|
2004-08-17 08:37:35 -04:00
|
|
|
.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3), "
|