diff options
Diffstat (limited to 'Utilities/cmcurl-7.19.0/docs/libcurl/curl_easy_setopt.3')
| -rw-r--r-- | Utilities/cmcurl-7.19.0/docs/libcurl/curl_easy_setopt.3 | 1637 |
1 files changed, 0 insertions, 1637 deletions
diff --git a/Utilities/cmcurl-7.19.0/docs/libcurl/curl_easy_setopt.3 b/Utilities/cmcurl-7.19.0/docs/libcurl/curl_easy_setopt.3 deleted file mode 100644 index 6059e38..0000000 --- a/Utilities/cmcurl-7.19.0/docs/libcurl/curl_easy_setopt.3 +++ /dev/null @@ -1,1637 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, <daniel@haxx.se>, et al. -.\" * -.\" * 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$ -.\" ************************************************************************** -.\" -.TH curl_easy_setopt 3 "30 Jul 2008" "libcurl 7.19.0" "libcurl Manual" -.SH NAME -curl_easy_setopt \- set options for a curl easy handle -.SH SYNOPSIS -#include <curl/curl.h> - -CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter); -.SH DESCRIPTION -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 -\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. - -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, -you must change them between the transfers. You can optionally reset all -options back to internal default with \fIcurl_easy_reset(3)\fP. - -Strings passed to libcurl as 'char *' arguments, are copied by the library; -thus the string storage associated to the pointer argument may be overwritten -after curl_easy_setopt() returns. Exceptions to this rule are described in -the option details below. - -NOTE: before 7.17.0 strings were not copied. Instead the user was forced keep -them available until libcurl no longer needed them. - -The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or -\fIcurl_easy_duphandle(3)\fP call. -.SH BEHAVIOR OPTIONS -.IP CURLOPT_VERBOSE -Set the parameter to 1 to get the library to display a lot of verbose -information about its operations. Very useful for libcurl and/or protocol -debugging and understanding. The verbose information will be sent to stderr, -or the stream set with \fICURLOPT_STDERR\fP. - -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. -.IP CURLOPT_HEADER -A parameter set to 1 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). -.IP CURLOPT_NOPROGRESS -A parameter set to 1 tells the library to shut off the built-in progress meter -completely. - -Future versions of libcurl is likely to not have any built-in progress meter -at all. -.IP CURLOPT_NOSIGNAL -Pass a long. If it is 1, 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) - -Consider building libcurl with ares support to enable asynchronous DNS -lookups. It enables nice timeouts for name resolves without signals. -.PP -.SH CALLBACK OPTIONS -.IP CURLOPT_WRITEFUNCTION -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 there is data received that needs -to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP -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. - -From 7.18.0, the function can return CURL_WRITEFUNC_PAUSE which then will -cause writing to this connection to become paused. See -\fIcurl_easy_pause(3)\fP for further details. - -This function may be called with zero bytes data if the transfered file is -empty. - -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. - -Set the \fIstream\fP argument with the \fICURLOPT_WRITEDATA\fP option. - -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 -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. -.IP CURLOPT_WRITEDATA -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. - -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. - -If you're using libcurl as a win32 DLL, you \fBMUST\fP use the -\fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience -crashes. - -This option is also known with the older name \fICURLOPT_FILE\fP, the name -\fICURLOPT_WRITEDATA\fP was introduced in 7.9.7. -.IP CURLOPT_READFUNCTION -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. - -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. - -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) - -From 7.18.0, the function can return CURL_READFUNC_PAUSE which then will cause -reading from this connection to become paused. See \fIcurl_easy_pause(3)\fP -for further details. - -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. -.IP CURLOPT_READDATA -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 -you don't specify a read callback but instead rely on the default internal -read function, this data must be a valid readable FILE *. - -If you're using libcurl as a win32 DLL, you MUST use a -\fICURLOPT_READFUNCTION\fP if you set this option. - -This option is also known with the older name \fICURLOPT_INFILE\fP, the name -\fICURLOPT_READDATA\fP was introduced in 7.9.7. -.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 -HTTP PUT or POST with a multi-pass authentication method. (Option added in -7.12.3). - -Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking! -.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) -.IP CURLOPT_SEEKFUNCTION -Function pointer that should match the following prototype: \fIint -function(void *instream, curl_off_t offset, int origin);\fP This function gets -called by libcurl to seek to a certain position in the input stream and can be -used to fast forward a file in a resumed upload (instead of reading all -uploaded bytes with the normal read function/callback). It is also called to -rewind a stream when doing a HTTP PUT or POST with a multi-pass authentication -method. The function shall work like "fseek" or "lseek" and accepted SEEK_SET, -SEEK_CUR and SEEK_END as argument for origin, although (in 7.18.0) libcurl -only passes SEEK_SET. The callback must return 0 on success as returning -something else will cause the upload operation to fail. - -If you forward the input arguments directly to "fseek" or "lseek", note that -the data type for \fIoffset\fP is not the same as defined for curl_off_t on -many systems! (Option added in 7.18.0) -.IP CURLOPT_SEEKDATA -Data pointer to pass to the file read function. If you use the -\fICURLOPT_SEEKFUNCTION\fP option, this is the pointer you'll get as input. If -you don't specify a seek callback, NULL is passed. (Option added in 7.18.0) -.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.) -.IP CURLOPT_OPENSOCKETFUNCTION -Function pointer that should match the \fIcurl_opensocket_callback\fP -prototype found in \fI<curl/curl.h>\fP. This function gets called by libcurl -instead of the \fIsocket(2)\fP 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 resolved peer address as a -\fIaddress\fP argument so the callback can modify the address or refuse to -connect at all. The callback function should return the socket or -\fICURL_SOCKET_BAD\fP in case no connection should be established or any error -detected. Any additional \fIsetsockopt(2)\fP calls can be done on the socket -at the user's discretion. \fICURL_SOCKET_BAD\fP return value from the -callback function will signal an unrecoverable error to the library and it -will return \fICURLE_COULDNT_CONNECT\fP. This return code can be used for IP -address blacklisting. The default behavior is: -.Bd -literal -offset indent - return socket(addr->family, addr->socktype, addr->protocol); -.Ed -(Option added in 7.17.1.) -.IP CURLOPT_OPENSOCKETDATA -Pass a pointer that will be untouched by libcurl and passed as the first -argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION\fP. -(Option added in 7.17.1.) -.IP CURLOPT_PROGRESSFUNCTION -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 -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. - -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. - -\fICURLOPT_NOPROGRESS\fP must be set to 0 to make this function actually -get called. -.IP CURLOPT_PROGRESSDATA -Pass a pointer that will be untouched by libcurl and passed as the first -argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. -.IP CURLOPT_HEADERFUNCTION -Function pointer that should match the following prototype: \fIsize_t -function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This -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 -using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP -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 -(it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return -code). - -If this option is not set, or if it is set to NULL, but -\fICURLOPT_HEADERDATA\fP (\fICURLOPT_WRITEHEADER\fP) is set to anything but -NULL, the function used to accept response data will be used instead. That is, -it will be the function specified with \fICURLOPT_WRITEFUNCTION\fP, or if it -is not specified or NULL - the default, stream-writing function. - -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. -.IP CURLOPT_WRITEHEADER -(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. -.IP CURLOPT_DEBUGFUNCTION -Function pointer that should match the following prototype: \fIint -curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP -\fICURLOPT_DEBUGFUNCTION\fP replaces the standard debug function used when -\fICURLOPT_VERBOSE \fP is in effect. This callback receives debug information, -as specified with the \fBcurl_infotype\fP argument. This function must return -0. The data pointed to by the char * passed to this function WILL NOT be zero -terminated, but will be exactly of the size as told by the size_t argument. - -Available curl_infotype values: -.RS -.IP CURLINFO_TEXT -The data is informational text. -.IP CURLINFO_HEADER_IN -The data is header (or header-like) data received from the peer. -.IP CURLINFO_HEADER_OUT -The data is header (or header-like) data sent to the peer. -.IP CURLINFO_DATA_IN -The data is protocol data received from the peer. -.IP CURLINFO_DATA_OUT -The data is protocol data sent to the peer. -.RE -.IP CURLOPT_DEBUGDATA -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. -.IP CURLOPT_SSL_CTX_FUNCTION -This option does only function for libcurl powered by OpenSSL. If libcurl was -built against another SSL library, this functionality is absent. - -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 -application to modify the behaviour of openssl's ssl initialization. The -\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. - -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. - -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 -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) -.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. -.SH ERROR OPTIONS -.IP CURLOPT_ERRORBUFFER -Pass a char * to a buffer that the libcurl may store human readable error -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. -Although this argument is a 'char *', it does not describe an input string. -Therefore the (probably undefined) contents of the buffer is NOT copied -by the library. You should keep the associated storage available until -libcurl no longer needs it. Failing to do so will cause very odd behavior -or even crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP -or you set the same option again to use a different pointer. - -Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better -debug/trace why errors happen. - -If the library does not return an error, the buffer may not have been -touched. Do not rely on the contents in those cases. - -.IP CURLOPT_STDERR -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. -.IP CURLOPT_FAILONERROR -A parameter set to 1 tells the library to fail silently if the HTTP code -returned is equal to or larger than 400. The default action would be to return -the page normally, ignoring that code. - -This method is not fail-safe and there are occasions where non-successful -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. -.SH NETWORK OPTIONS -.IP CURLOPT_URL -The actual URL to deal with. The parameter should be a char * to a zero -terminated string. - -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. - -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 -\fIcurl_easy_perform(3)\fP is called. -.IP CURLOPT_PROXY -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. - -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 -\fICURLOPT_HTTPPROXYTUNNEL\fP. - -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. - -Setting the proxy string to "" (an empty string) will explicitly disable the -use of a proxy, even if there is an environment variable set for it. - -Since 7.14.1, the proxy host string given in environment variables can be -specified the exact same way as the proxy can be set with \fICURLOPT_PROXY\fP, -include protocol prefix (http://) and embedded user + password. -.IP CURLOPT_PROXYPORT -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. -.IP CURLOPT_PROXYTYPE -Pass a long with this option to set type of the proxy. Available options for -this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2), -\fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and -\fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.18.0). The HTTP type is -default. (Added in 7.10) -.IP CURLOPT_HTTPPROXYTUNNEL -Set the parameter to 1 to make the library tunnel all operations 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. -.IP CURLOPT_SOCKS5_RESOLVE_LOCAL -Set the parameter to 1 to make the library to resolve the host name locally -instead of passing it to the proxy to resolve, when using a SOCKS5 proxy. - -Note that libcurl before 7.18.0 always resolved the host name locally even -when SOCKS5 was used. (Added in 7.18.0) -.IP CURLOPT_INTERFACE -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 -name. -.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 to 1 or below will -make libcurl do only one try for the exact port number. Note that port numbers -by nature are scarce resources 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) -.IP CURLOPT_DNS_CACHE_TIMEOUT -Pass a long, this sets the timeout in seconds. Name resolves will be kept in -memory for this number of seconds. Set to zero to completely disable -caching, or set to -1 to make the cached entries remain forever. By default, -libcurl caches this info for 60 seconds. - -NOTE: the name resolve functions of various libc implementations don't re-read -name server information unless explicitly told so (by for example calling -\fIres_init(3)\fP. This may cause libcurl to keep using the older server even -if DHCP has updated the server info, and this may look like a DNS cache issue -to the casual libcurl-app user. -.IP CURLOPT_DNS_USE_GLOBAL_CACHE -Pass a long. If the value is 1, it tells curl to use a global DNS cache -that will survive between easy handle creations and deletions. This is not -thread-safe and this will use a global variable. - -\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. -.IP CURLOPT_BUFFERSIZE -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 makes sense to use this option if you want it smaller. -.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. -.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 -overdone. -.IP CURLOPT_ADDRESS_SCOPE -Pass a long specifying the scope_id value to use when connecting to IPv6 -link-local or site-local addresses. -.SH NAMES and PASSWORDS OPTIONS (Authentication) -.IP CURLOPT_NETRC -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. - -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. - -Pass a long, set to one of the values described below. -.RS -.IP CURL_NETRC_OPTIONAL -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. -.IP CURL_NETRC_IGNORED -The library will ignore the file and use only the information in the URL. - -This is the default. -.IP CURL_NETRC_REQUIRED -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 -Only machine name, user name and password are taken into account -(init macros and similar things aren't supported). - -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. -.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 -option is omitted, and \fICURLOPT_NETRC\fP is set, libcurl will attempt to -find a .netrc file in the current user's home directory. (Added in 7.10.9) -.IP CURLOPT_USERPWD -Pass a char * as parameter, which should be [user name]:[password] to use for -the connection. Use \fICURLOPT_HTTPAUTH\fP to decide authentication method. - -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. - -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 -\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. -.IP CURLOPT_PROXYUSERPWD -Pass a char * as parameter, which should be [user name]:[password] to use for -the connection to the HTTP proxy. Use \fICURLOPT_PROXYAUTH\fP to decide -authentication method. -.IP CURLOPT_HTTPAUTH -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 -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) -.RS -.IP CURLAUTH_BASIC -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. -.IP CURLAUTH_DIGEST -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. -.IP CURLAUTH_GSSNEGOTIATE -HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain -\&"Negotiate") method was designed by Microsoft and is used in their web -applications. It is primarily meant as a support for Kerberos5 authentication -but may be also used along with another authentication methods. For more -information see IETF draft draft-brezak-spnego-http-04.txt. - -You need to build libcurl with a suitable GSS-API library for this to work. -.IP CURLAUTH_NTLM -HTTP NTLM authentication. A proprietary protocol invented and used by -Microsoft. It uses a challenge-response and hash concept similar to Digest, to -prevent the password from being eavesdropped. - -You need to build libcurl with OpenSSL support for this option to work, or -build libcurl on Windows. -.IP CURLAUTH_ANY -This is a convenience macro that sets all bits and thus makes libcurl pick any -it finds suitable. libcurl will automatically select the one it finds most -secure. -.IP CURLAUTH_ANYSAFE -This is a convenience macro that sets all bits except Basic and thus makes -libcurl pick any it finds suitable. libcurl will automatically select the one it -finds most secure. -.RE -.IP CURLOPT_PROXYAUTH -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 -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) -.SH HTTP OPTIONS -.IP CURLOPT_AUTOREFERER -Pass a parameter set to 1 to enable this. When enabled, libcurl will -automatically set the Referer: field in requests where it follows a Location: -redirect. -.IP CURLOPT_ENCODING -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. -.IP CURLOPT_FOLLOWLOCATION -A parameter set to 1 tells the library to follow any Location: header that the -server sends as part of an HTTP header. - -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. -.IP CURLOPT_UNRESTRICTED_AUTH -A parameter set to 1 tells the library it can continue to send authentication -(user+password) when following locations, even when hostname changed. This -option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP. -.IP CURLOPT_MAXREDIRS -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 -\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) -.IP CURLOPT_POST301 -A parameter set to 1 tells the library to respect RFC 2616/10.3.2 and not -convert POST requests into GET requests when following a 301 redirection. The -non-RFC behaviour is ubiquitous in web browsers, so the library does the -conversion by default to maintain consistency. However, a server may requires -a POST to remain a POST after such a redirection. This option is meaningful -only when setting \fICURLOPT_FOLLOWLOCATION\fP. (Added in 7.17.1) -.IP CURLOPT_PUT -A parameter set to 1 tells the library to use HTTP PUT to transfer data. The -data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP. - -This option is deprecated and starting with version 7.12.1 you should instead -use \fICURLOPT_UPLOAD\fP. -.IP CURLOPT_POST -A parameter set to 1 tells the library to do a regular HTTP post. This will -also make the library use a "Content-Type: -application/x-www-form-urlencoded" header. (This is by far the most commonly -used POST method). - -Use one of \fICURLOPT_POSTFIELDS\fP or \fICURLOPT_COPYPOSTFIELDS\fP options to -specify what data to post and \fICURLOPT_POSTFIELDSIZE\fP or -\fICURLOPT_POSTFIELDSIZE_LARGE\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 -the size of the data with the \fICURLOPT_POSTFIELDSIZE\fP or -\fICURLOPT_POSTFIELDSIZE_LARGE\fP option. To enable chunked encoding, you -simply pass in the appropriate Transfer-Encoding header, see the -post-callback.c example. - -You can override the default POST Content-Type: header by setting your own -with \fICURLOPT_HTTPHEADER\fP. - -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. - -When setting \fICURLOPT_POST\fP to 1, it will automatically set -\fICURLOPT_NOBODY\fP to 0 (since 7.14.1). - -If you issue a POST request and then want to make a HEAD or GET using the same -re-used handle, you must explicitly set the new request type using -\fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar. -.IP CURLOPT_POSTFIELDS -Pass a void * as parameter, which should be the full data to post in an HTTP -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. - -The pointed data are NOT copied by the library: as a consequence, they must -be preserved by the calling application until the transfer finishes. - -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 -commonly used one by HTML forms. See also the \fICURLOPT_POST\fP. Using -\fICURLOPT_POSTFIELDS\fP implies \fICURLOPT_POST\fP. - -If you want to do a zero-byte POST, you need to set -\fICURLOPT_POSTFIELDSIZE\fP explicitly to zero, as simply setting -\fICURLOPT_POSTFIELDS\fP to NULL or "" just effectively disables the sending -of the specified string. libcurl will instead assume that you'll send the POST -data using the read callback! - -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. - -To make multipart/formdata posts (aka rfc1867-posts), check out the -\fICURLOPT_HTTPPOST\fP option. -.IP CURLOPT_POSTFIELDSIZE -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 -size is set to -1, the library will use strlen() to get the size. -.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 -\fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1) -.IP CURLOPT_COPYPOSTFIELDS -Pass a char * as parameter, which should be the full data to post in an HTTP -POST operation. It behaves as the \fICURLOPT_POSTFIELDS\fP option, but the -original data are copied by the library, allowing the application to overwrite -the original data after setting this option. - -Because data are copied, care must be taken when using this option in -conjunction with \fICURLOPT_POSTFIELDSIZE\fP or -\fICURLOPT_POSTFIELDSIZE_LARGE\fP: If the size has not been set prior to -\fICURLOPT_COPYPOSTFIELDS\fP, the data are assumed to be a NUL-terminated -string; else the stored size informs the library about the data byte count to -copy. In any case, the size must not be changed after -\fICURLOPT_COPYPOSTFIELDS\fP, unless another \fICURLOPT_POSTFIELDS\fP or -\fICURLOPT_COPYPOSTFIELDS\fP option is issued. -(Added in 7.17.1) - -.IP CURLOPT_HTTPPOST -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 -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. - -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. - -When setting \fICURLOPT_HTTPPOST\fP, it will automatically set -\fICURLOPT_NOBODY\fP to 0 (since 7.14.1). -.IP CURLOPT_REFERER -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. -.IP CURLOPT_USERAGENT -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. -.IP CURLOPT_HTTPHEADER -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 -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. - -Pass a NULL to this to reset back to no custom headers. - -The most commonly replaced headers have "shortcuts" in the options -\fICURLOPT_COOKIE\fP, \fICURLOPT_USERAGENT\fP and \fICURLOPT_REFERER\fP. -.IP CURLOPT_HTTP200ALIASES -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. - -The alias itself is not parsed for any version strings. Before libcurl 7.16.3, -Libcurl used the value set by option \fICURLOPT_HTTP_VERSION\fP, but starting -with 7.16.3 the protocol is assumed to match HTTP 1.0 when an alias matched. -.IP CURLOPT_COOKIE -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. - -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. - -Note that this option sets the cookie header explictly in the outgoing -request(s). If multiple requests are done due to authentication, followed -redirections or similar, they will all get this cookie passed on. - -Using this option multiple times will only make the latest string override the -previous ones. -.IP CURLOPT_COOKIEFILE -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. - -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. - -If you use this option multiple times, you just add more files to read. -Subsequent files will add more cookies. -.IP CURLOPT_COOKIEJAR -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 -matching cookies get sent accordingly. - -If the cookie jar file can't be created or written to (when the -\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. -.IP CURLOPT_COOKIESESSION -Pass a long set to 1 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. -.IP CURLOPT_COOKIELIST -Pass a char * to a cookie string. Cookie can be either in Netscape / Mozilla -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 -magic string \&"ALL" will erase all cookies known by cURL. (Added in 7.14.1) -Passing the special string \&"SESS" will only erase all session cookies known -by cURL. (Added in 7.15.4) Passing the special string \&"FLUSH" will write -all cookies known by cURL to the file specified by \fICURLOPT_COOKIEJAR\fP. -(Added in 7.17.1) -.IP CURLOPT_HTTPGET -Pass a long. If the long is 1, this forces the HTTP request to get back -to GET. usable if a POST, HEAD, PUT or a custom request have been used -previously using the same curl handle. - -When setting \fICURLOPT_HTTPGET\fP to 1, it will automatically set -\fICURLOPT_NOBODY\fP to 0 (since 7.14.1). -.IP CURLOPT_HTTP_VERSION -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 -.IP CURL_HTTP_VERSION_NONE -We don't care about what version the library uses. libcurl will use whatever -it thinks fit. -.IP CURL_HTTP_VERSION_1_0 -Enforce HTTP 1.0 requests. -.IP CURL_HTTP_VERSION_1_1 -Enforce HTTP 1.1 requests. -.RE -.IP CURLOPT_IGNORE_CONTENT_LENGTH -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) -.IP CURLOPT_HTTP_CONTENT_DECODING -Pass a long to tell libcurl how to act on content decoding. If set to zero, -content decoding will be disabled. If set to 1 it is enabled. Note however -that libcurl has no default content decoding but requires you to use -\fICURLOPT_ENCODING\fP for that. (added in 7.16.2) -.IP CURLOPT_HTTP_TRANSFER_DECODING -Pass a long to tell libcurl how to act on transfer decoding. If set to zero, -transfer decoding will be disabled, if set to 1 it is enabled -(default). libcurl does chunked transfer decoding by default unless this -option is set to zero. (added in 7.16.2) -.SH FTP OPTIONS -.IP CURLOPT_FTPPORT -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. - -You disable PORT again and go back to using the passive version by setting -this option to NULL. -.IP CURLOPT_QUOTE -Pass a pointer to a linked list of FTP or SFTP commands to pass to -the server prior to your ftp request. This will be done before any -other commands are issued (even before the CWD command for FTP). The -linked list should be a fully valid list of 'struct curl_slist' structs -properly filled in with text strings. Use \fIcurl_slist_append(3)\fP -to append strings (commands) to the list, and clear the entire list -afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation -again by setting a NULL to this option. -The set of valid FTP commands depends on the server (see RFC959 for a -list of mandatory commands). -The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, -rename, rm, rmdir, symlink (see -.BR curl (1)) -(SFTP support added in 7.16.3) -.IP CURLOPT_POSTQUOTE -Pass a pointer to a linked list of FTP or SFTP 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. -.IP CURLOPT_PREQUOTE -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 -option. Before version 7.15.6, if you also set \fICURLOPT_NOBODY\fP to 1, this -option didn't work. -.IP CURLOPT_DIRLISTONLY -A parameter set to 1 tells the library to just list the names of files in a -directory, instead of doing a full directory listing that would include file -sizes, dates etc. This works for FTP and SFTP URLs. - -This causes an FTP NLST command to be sent on an FTP server. Beware -that some FTP servers list only files in their response to NLST; they -might not include subdirectories and symbolic links. - -(This option was known as CURLOPT_FTPLISTONLY up to 7.16.4) -.IP CURLOPT_APPEND -A parameter set to 1 tells the library to append to the remote file instead of -overwrite it. This is only useful when uploading to an ftp site. - -(This option was known as CURLOPT_FTPAPPEND up to 7.16.4) -.IP CURLOPT_FTP_USE_EPRT -Pass a long. If the value is 1, it tells curl to use the EPRT (and -LPRT) command when doing active FTP downloads (which is enabled by -\fICURLOPT_FTPPORT\fP). Using EPRT means that it will first attempt to use -EPRT and then LPRT before using PORT, but if you pass zero to this -option, it will not try using EPRT or LPRT, only plain PORT. (Added in 7.10.5) - -If the server is an IPv6 host, this option will have no effect as of 7.12.3. -.IP CURLOPT_FTP_USE_EPSV -Pass a long. If the value is 1, 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 zero to this option, it will not try using EPSV, only plain PASV. - -If the server is an IPv6 host, this option will have no effect as of 7.12.3. -.IP CURLOPT_FTP_CREATE_MISSING_DIRS -Pass a long. If the value is 1, 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) - -This setting also applies to SFTP-connections. curl will attempt to create -the remote directory if it can't obtain a handle to the target-location. The -creation will fail if a file of the same name as the directory to create -already exists or lack of permissions prevents creation. (Added in 7.16.3) -.IP CURLOPT_FTP_RESPONSE_TIMEOUT -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 -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 -\fICURLOPT_FTP_RESPONSE_TIMEOUT\fP to a value smaller than -\fICURLOPT_TIMEOUT\fP. (Added in 7.10.8) -.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) -.IP CURLOPT_FTP_SKIP_PASV_IP -Pass a long. If set to 1, 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 the port number -from the 227-response. (Added in 7.14.2) - -This option has no effect if PORT, EPRT or EPSV is used instead of PASV. -.IP CURLOPT_USE_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) - -(This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants -were known as CURLFTPSSL_*) -.RS -.IP CURLUSESSL_NONE -Don't attempt to use SSL. -.IP CURLUSESSL_TRY -Try using SSL, proceed as normal otherwise. -.IP CURLUSESSL_CONTROL -Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP. -.IP CURLUSESSL_ALL -Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. -.RE -.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 -\fICURLOPT_FTP_SSL\fP). (Added in 7.12.2) -.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 -.IP CURLOPT_FTP_SSL_CCC -If enabled, this option makes libcurl use CCC (Clear Command Channel). It -shuts down the SSL/TLS layer after authenticating. The rest of the -control channel communication will be unencrypted. This allows NAT routers -to follow the FTP transaction. Pass a long using one of the values below. -(Added in 7.16.1) -.RS -.IP CURLFTPSSL_CCC_NONE -Don't attempt to use CCC. -.IP CURLFTPSSL_CCC_PASSIVE -Do not initiate the shutdown, but wait for the server to do it. Do not send -a reply. -.IP CURLFTPSSL_CCC_ACTIVE -Initiate the shutdown and wait for a reply. -.RE -.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) -.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 -.SH PROTOCOL OPTIONS -.IP CURLOPT_TRANSFERTEXT -A parameter set to 1 tells the library to use ASCII mode for ftp transfers, -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. - -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. -.IP CURLOPT_PROXY_TRANSFER_MODE -Pass a long. If the value is set to 1 (one), it tells libcurl to set the -transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by -appending ;type=a or ;type=i to the URL. Without this setting, or it being set -to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when doing -FTP via a proxy. Beware that not all proxies support this feature. (Added in -7.18.0) -.IP CURLOPT_CRLF -Convert Unix newlines to CRLF newlines on transfers. -.IP CURLOPT_RANGE -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 -techniques). Pass a NULL to this option to disable the use of ranges. - -Ranges work on HTTP, FTP and FILE (since 7.18.0) transfers only. -.IP CURLOPT_RESUME_FROM -Pass a long as parameter. It contains the offset in number of bytes that you -want the transfer to start from. Set this option to 0 to make the transfer -start from the beginning (effectively disabling resume). For FTP, set this -option to -1 to make the transfer start from the end of the target file -(useful to continue an interrupted upload). -.IP CURLOPT_RESUME_FROM_LARGE -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) -.IP CURLOPT_CUSTOMREQUEST -Pass a pointer to a zero terminated string as parameter. It will be used -instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST -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. - -Note that libcurl will still act and assume the keyword it would use if you -didn't set your custom one is the one in use and it will act according to -that. Thus, changing this to a HEAD when libcurl otherwise would do a GET -might cause libcurl to act funny, and similar. To switch to a proper HEAD, use -\fICURLOPT_NOBODY\fP, to switch to a proper POST, use \fICURLOPT_POST\fP or -\fICURLOPT_POSTFIELDS\fP and so on. - -Restore to the internal default by setting this to NULL. - -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 -replace or extend the set of headers sent by libcurl. Use -\fICURLOPT_HTTP_VERSION\fP to change HTTP version. -.IP CURLOPT_FILETIME -Pass a long. If it is 1, 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 -can be used after a transfer to extract the received time (if any). -.IP CURLOPT_NOBODY -A parameter set to 1 tells the library to not include the body-part in the -output. This is only relevant for protocols that have separate header and body -parts. On HTTP(S) servers, this will make libcurl do a HEAD request. - -To change request to GET, you should use \fICURLOPT_HTTPGET\fP. Change request -to POST with \fICURLOPT_POST\fP etc. -.IP CURLOPT_INFILESIZE -When uploading a file to a remote site, this option should be used to tell -libcurl what the expected size of the infile is. This value should be passed -as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP. - -For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE\fP is -mandatory. - -Note that this option does not limit how much data libcurl will actually send, -as that is controlled entirely by what the read callback returns. -.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 -as a curl_off_t. (Added in 7.11.0) - -For uploading using SCP, this option or \fICURLOPT_INFILESIZE\fP is mandatory. - -Note that this option does not limit how much data libcurl will actually send, -as that is controlled entirely by what the read callback returns. -.IP CURLOPT_UPLOAD -A parameter set to 1 tells the library to prepare for an upload. The -\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 -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. -.IP CURLOPT_MAXFILESIZE -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, -the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. - -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. -.IP CURLOPT_MAXFILESIZE_LARGE -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) - -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. -.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. - -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. -.IP CURLOPT_TIMEVALUE -Pass a long as parameter. This should be the time in seconds since 1 jan 1970, -and the time will be used in a condition as specified with -\fICURLOPT_TIMECONDITION\fP. -.SH CONNECTION OPTIONS -.IP CURLOPT_TIMEOUT -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. - -In unix-like systems, this might cause signals to be used unless -\fICURLOPT_NOSIGNAL\fP is set. -.IP CURLOPT_TIMEOUT_MS -Like \fICURLOPT_TIMEOUT\fP but takes number of milliseconds instead. If -libcurl is built to use the standard system name resolver, that part will -still use full-second resolution for timeouts. (Added in 7.16.2) -.IP CURLOPT_LOW_SPEED_LIMIT -Pass a long as parameter. It contains the transfer speed in bytes per second -that the transfer should be below during \fICURLOPT_LOW_SPEED_TIME\fP seconds -for the library to consider it too slow and abort. -.IP CURLOPT_LOW_SPEED_TIME -Pass a long as parameter. It contains the time in seconds that the transfer -should be below the \fICURLOPT_LOW_SPEED_LIMIT\fP for the library to consider -it too slow and abort. -.IP CURLOPT_MAX_SEND_SPEED_LARGE -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) -.IP CURLOPT_MAX_RECV_SPEED_LARGE -Pass a curl_off_t as parameter. If a download exceeds this speed on -cumulative average during the transfer, the transfer will pause to keep the -average rate less than or equal to the parameter value. Defaults to unlimited -speed. (Added in 7.15.5) -.IP CURLOPT_MAXCONNECTS -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 in this easy handle. 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 closes the oldest one in the cache to -prevent the number of open connections to increase. - -If you already have performed transfers with this curl handle, setting a -smaller MAXCONNECTS than before may cause open connections to get closed -unnecessarily. - -Note that if you add this easy handle to a multi handle, this setting is not -being acknowledged, but you must instead use \fIcurl_multi_setopt(3)\fP and -the \fICURLMOPT_MAXCONNECTS\fP option. -.IP CURLOPT_CLOSEPOLICY -(Obsolete) This option does nothing. -.IP CURLOPT_FRESH_CONNECT -Pass a long. Set to 1 to make the next transfer use a new (fresh) connection -by force. If the connection cache is full before this connection, one of the -existing connections will be closed as according to the selected or default -policy. This option should be used with caution and only if you understand -what it does. Set this to 0 to have libcurl attempt re-using an existing -connection (default behavior). -.IP CURLOPT_FORBID_REUSE -Pass a long. Set to 1 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 -re-use (default behavior). -.IP CURLOPT_CONNECTTIMEOUT -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. - -In unix-like systems, this might cause signals to be used unless -\fICURLOPT_NOSIGNAL\fP is set. -.IP CURLOPT_CONNECTTIMEOUT_MS -Like \fICURLOPT_CONNECTTIMEOUT\fP but takes number of milliseconds instead. If -libcurl is built to use the standard system name resolver, that part will -still use full-second resolution for timeouts. (Added in 7.16.2) -.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 -.IP CURLOPT_CONNECT_ONLY -Pass a long. If the parameter equals 1, it tells the library to perform all -the 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) -.SH SSL and SECURITY OPTIONS -.IP CURLOPT_SSLCERT -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. - -With NSS this is the nickname of the certificate you wish to authenticate -with. -.IP CURLOPT_SSLCERTTYPE -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) -.IP CURLOPT_SSLKEY -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 -changed with \fICURLOPT_SSLKEYTYPE\fP. -.IP CURLOPT_SSLKEYTYPE -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". - -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. -\&"DER" format key file currently does not work because of a bug in OpenSSL. -.IP CURLOPT_KEYPASSWD -Pass a pointer to a zero terminated string as parameter. It will be used as -the password required to use the \fICURLOPT_SSLKEY\fP or -\fICURLOPT_SSH_PRIVATE_KEYFILE\fP private key. -You never needed a pass phrase to load a certificate but you need one to -load your private key. - -(This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and -CURLOPT_SSLCERTPASSWD up to 7.9.2) -.IP CURLOPT_SSLENGINE -Pass a pointer to a zero terminated string as parameter. It will be used as -the identifier for the crypto engine you want to use for your private -key. - -If the crypto device cannot be loaded, \fICURLE_SSL_ENGINE_NOTFOUND\fP is -returned. -.IP CURLOPT_SSLENGINE_DEFAULT -Sets the actual crypto engine as the default for (asymmetric) crypto -operations. - -If the crypto device cannot be set, \fICURLE_SSL_ENGINE_SETFAILED\fP is -returned. - -Note that even though this option doesn't need any parameter, in some -configurations \fIcurl_easy_setopt\fP might be defined as a macro taking -exactly three arguments. Therefore, it's recommended to pass 1 as parameter to -this option. -.IP CURLOPT_SSLVERSION -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. This will attempt to figure out the remote SSL protocol -version, i.e. either SSLv3 or TLSv1 (but not SSLv2, which became disabled -by default with 7.18.1). -.IP CURL_SSLVERSION_TLSv1 -Force TLSv1 -.IP CURL_SSLVERSION_SSLv2 -Force SSLv2 -.IP CURL_SSLVERSION_SSLv3 -Force SSLv3 -.RE -.IP CURLOPT_SSL_VERIFYPEER -Pass a long as parameter. - -This option determines whether curl verifies the authenticity of the peer's -certificate. A value of 1 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. -.IP CURLOPT_CAINFO -Pass a char * to a zero terminated string naming a file holding one or more -certificates to verify the peer with. This makes sense only when used in -combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If -\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_CAINFO\fP need not -even indicate an accessible file. - -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. - -When built against NSS this is the directory that the NSS certificate -database resides in. -.IP CURLOPT_ISSUERCERT -Pass a char * to a zero terminated string naming a file holding a CA -certificate in PEM format. If the option is set, an additional check against -the peer certificate is performed to verify the issuer is indeed the one -associated with the certificate provided by the option. This additional check -is useful in multi-level PKI where one need to enforce the peer certificate is -from a specific branch of the tree. - -This option makes sense only when used in combination with the -\fICURLOPT_SSL_VERIFYPEER\fP option. Otherwise, the result of the check is not -considered as failure. - -A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, -which is returned if the setup of the SSL/TLS session has failed due to a -mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER\fP has -to be set too for the check to fail). (Added in 7.19.0) -.IP CURLOPT_CAPATH -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. This option is -OpenSSL-specific and does nothing if libcurl is built to use GnuTLS. -.IP CURLOPT_CRLFILE -Pass a char * to a zero terminated string naming a file with the concatenation -of CRL (in PEM format) to use in the certificate validation that occurs during -the SSL exchange. - -When curl is built to use NSS or GnuTLS, there is no way to influence the use -of CRL passed to help in the verification process. When libcurl is built with -OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both -set, requiring CRL check against all the elements of the certificate chain if -a CRL file is passed. - -This option makes sense only when used in combination with the -\fICURLOPT_SSL_VERIFYPEER\fP option. - -A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It -is returned when the SSL exchange fails because the CRL file cannot be loaded. -Note that a failure in certificate verification due to a revocation information -found in the CRL does not trigger this specific error. (Added in 7.19.0) -.IP CURLOPT_RANDOM_FILE -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. -.IP CURLOPT_EGDSOCKET -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. -.IP CURLOPT_SSL_VERIFYHOST -Pass a long as parameter. - -This option determines whether libcurl verifies that the server cert is for -the server it is known as. - -When negotiating an SSL connection, the server sends a certificate indicating -its identity. - -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. - -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. - -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). - -When the value is 0, the connection succeeds regardless of the names in the -certificate. - -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. -.IP CURLOPT_SSL_CIPHER_LIST -Pass a char *, pointing to a zero terminated string holding the list of -ciphers to use for the SSL connection. The list must be syntactically correct, -it consists of one or more cipher strings separated by colons. Commas or spaces -are also acceptable separators but colons are normally used, \!, \- and \+ can -be used as operators. - -For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', -\'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you -compile OpenSSL. - -You'll find more details about cipher lists on this URL: -\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP - -For NSS valid examples of cipher lists include 'rsa_rc4_128_md5', -\'rsa_aes_128_sha\', etc. With NSS you don't add/remove ciphers. If one uses -this option then all known ciphers are disabled and only those passed in -are enabled. - -You'll find more details about the NSS cipher lists on this URL: -\fIhttp://directory.fedora.redhat.com/docs/mod_nss.html#Directives\fP - -.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) -.IP CURLOPT_KRBLEVEL -Pass a char * as parameter. Set the kerberos security level for FTP; this -also enables kerberos 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 kerberos -support for FTP. - -(This option was known as CURLOPT_KRB4LEVEL up to 7.16.3) -.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. -(Added in 7.16.1) -.IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 -Pass a char * pointing to a string containing 32 hexadecimal digits. The -string should be the 128 bit MD5 checksum of the remote host's public key, and -libcurl will reject the connection to the host unless the md5sums match. This -option is only for SCP and SFTP transfers. (Added in 7.17.1) -.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. -(Added in 7.16.1) -.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. -If the file is password-protected, set the password with \fICURLOPT_KEYPASSWD\fP. -(Added in 7.16.1) -.SH OTHER OPTIONS -.IP CURLOPT_PRIVATE -Pass a void * as parameter, pointing to data that should be associated with -this curl handle. The pointer can subsequently be retrieved using -\fIcurl_easy_getinfo(3)\fP with the CURLINFO_PRIVATE option. libcurl itself -does nothing with this data. (Added in 7.10.3) -.IP CURLOPT_SHARE -Pass a share handle as a parameter. The share handle must have been created by -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. - -If you add a share that is set to share cookies, your easy handle will use -that cookie cache and get the cookie engine enabled. If you unshare an object -that were using cookies (or change to another object that doesn't share -cookies), the easy handle will get its cookie engine disabled. - -Data that the share object is not set to share will be dealt with the usual -way, as if no share was used. -.IP CURLOPT_NEW_FILE_PERMS -Pass a long as a parameter, containing the value of the permissions that will -be assigned to newly created files on the remote server. The default value is -\fI0644\fP, but any valid value can be used. The only protocols that can use -this are \fIsftp://\fP, \fIscp://\fP and \fIfile://\fP. (Added in 7.16.4) -.IP CURLOPT_NEW_DIRECTORY_PERMS -Pass a long as a parameter, containing the value of the permissions that will -be assigned to newly created directories on the remote server. The default -value is \fI0755\fP, but any valid value can be used. The only protocols that -can use this are \fIsftp://\fP, \fIscp://\fP and \fIfile://\fP. -(Added in 7.16.4) -.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. -.SH RETURN VALUE -CURLE_OK (zero) means that the option was set properly, non-zero means an -error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors(3)\fP -man page for the full list with descriptions. - -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. -.SH "SEE ALSO" -.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3)" |