diff options
Diffstat (limited to 'docs/libcurl/curl_easy_setopt.3')
| -rw-r--r-- | docs/libcurl/curl_easy_setopt.3 | 627 |
1 files changed, 627 insertions, 0 deletions
diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 new file mode 100644 index 000000000..4067cec5e --- /dev/null +++ b/docs/libcurl/curl_easy_setopt.3 @@ -0,0 +1,627 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_easy_setopt 3 "10 Dec 2001" "libcurl 7.9.2" "libcurl Manual" +.SH NAME +curl_easy_setopt - Set curl easy-session options +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter); +.ad +.SH DESCRIPTION +curl_easy_setopt() is used to tell libcurl how to behave. Most operations in +libcurl have default actions, and by using the appropriate options to +\fIcurl_easy_setopt\fP, you can change them. All options are set with the +\fIoption\fP followed by a \fIparameter\fP. That parameter can be a long, a +function pointer or an object pointer, all 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. + +\fBNOTE:\fP 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. + +\fBNOTE2:\fP options set with this function call are valid for the forthcoming +data transfers that are performed when you invoke \fIcurl_easy_perform\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. + +The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or +\fIcurl_easy_duphandle(3)\fP call. +.SH OPTIONS +The options are listed in a sort of random order, but you'll figure it out! +.TP 0.8i +.B CURLOPT_FILE +Data pointer to pass to the file write function. Note that if you specify the +\fICURLOPT_WRITEFUNCTION\fP, 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. + +\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use the +\fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience +crashes. +.TP +.B 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 available to pass +available that needs to be saved. The size of the data pointed to by \fIptr\fP +is \fIsize\fP multiplied with \fInmemb\fP. 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. + +Set the \fIstream\fP argument with the \fBCURLOPT_FILE\fP option. + +\fBNOTE:\fP you 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. +.TP +.B CURLOPT_INFILE +Data pointer to pass to the file read function. Note that if you specify the +\fICURLOPT_READFUNCTION\fP, this is the pointer you'll get as input. If you +don't specify a read callback, this must be a valid FILE *. + +\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use a +\fICURLOPT_READFUNCTION\fP if you set this option. +.TP +.B 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. +.TP +.B 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. +.TP +.B CURLOPT_URL +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. + +\fBNOTE:\fP this option is (the only one) required to be set before +\fIcurl_easy_perform(3)\fP is called. +.TP +.B 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. + +\fBNOTE:\fP when you tell the library to use a HTTP proxy, libcurl will +transparently convert operations to HTTP even if you specify a FTP URL +etc. This may have an impact on what other features of the library you can +use, such as CURLOPT_QUOTE and similar FTP specifics that don't work unless +you tunnel through the HTTP proxy. Such tunneling is activated with +\fICURLOPT_HTTPPROXYTUNNEL\fP. + +\fBNOTE2:\fP libcurl respects the environment variables \fBhttp_proxy\fP, +\fBftp_proxy\fP, \fBall_proxy\fP etc, if any of those is set. +.TP +.B 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. +.TP +.B CURLOPT_HTTPPROXYTUNNEL +Set the parameter to non-zero to get the library to tunnel all operations +through a given HTTP proxy. Note that 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. (Added in libcurl 7.3) +.TP +.B CURLOPT_VERBOSE +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 +debugging and understanding. + +You hardly ever want this set in production use, you will almost always want +this when you debug/report problems. +.TP +.B CURLOPT_HEADER +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). +.TP +.B CURLOPT_NOPROGRESS +A non-zero parameter tells the library to shut of the built-in progress meter +completely. + +\fBNOTE:\fP future versions of libcurl is likely to not have any built-in +progress meter at all. +.TP +.B CURLOPT_NOBODY +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 +parts. +.TP +.B CURLOPT_FAILONERROR +A non-zero parameter tells the library to fail silently if the HTTP code +returned is equal to or larger than 300. The default action would be to return +the page normally, ignoring that code. +.TP +.B CURLOPT_UPLOAD +A non-zero parameter tells the library to prepare for an upload. The +CURLOPT_INFILE and CURLOPT_INFILESIZE are also interesting for uploads. +.TP +.B CURLOPT_POST +A non-zero parameter tells the library to do a regular HTTP post. This is a +normal application/x-www-form-urlencoded kind, which is the most commonly used +one by HTML forms. See the CURLOPT_POSTFIELDS option for how to specify the +data to post and CURLOPT_POSTFIELDSIZE in how to set the data size. Starting +with libcurl 7.8, this option is obsolete. Using the CURLOPT_POSTFIELDS option +will imply this option. +.TP +.B CURLOPT_FTPLISTONLY +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. +.TP +.B CURLOPT_FTPAPPEND +A non-zero parameter tells the library to append to the remote file instead of +overwrite it. This is only useful when uploading to a ftp site. +.TP +.B CURLOPT_NETRC +A non-zero parameter tells the library to scan your \fI~/.netrc\fP file to +find user name and password for the remote site you are about to access. Only +machine name, user name and password is taken into account (init macros and +similar things aren't supported). + +\fBNote:\fP 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. +.TP +.B CURLOPT_FOLLOWLOCATION +A non-zero parameter tells the library to follow any Location: header that the +server sends as part of a HTTP header. + +\fBNOTE:\fP 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. +.TP +.B CURLOPT_TRANSFERTEXT +A non-zero parameter tells the library to use ASCII mode for ftp transfers, +instead of the default binary transfer. For LDAP transfers it gets the data in +plain text instead of HTML and 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. +.TP +.B CURLOPT_PUT +A non-zero parameter tells the library to use HTTP PUT to transfer data. The +data should be set with CURLOPT_INFILE and CURLOPT_INFILESIZE. +.TP +.B CURLOPT_USERPWD +Pass a char * as parameter, which should be [user name]:[password] to use for +the connection. If the password is left out, you will be prompted for it. +\fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +.TP +.B CURLOPT_PROXYUSERPWD +Pass a char * as parameter, which should be [user name]:[password] to use for +the connection to the HTTP proxy. If the password is left out, you will be +prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own +prompt function. +.TP +.B 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). +.TP +.B 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 the +library. The buffer must be at least CURL_ERROR_SIZE big. + +\fBNote:\fP if the library does not return an error, the buffer may not have +been touched. Do not rely on the contents in those cases. +.TP +.B 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. + +\fBNOTE:\fP this does not work in Unix multi-threaded programs, as it uses +signals. +.TP +.B CURLOPT_POSTFIELDS +Pass a char * as parameter, which should be the full data to post in a HTTP +post operation. This is a normal application/x-www-form-urlencoded kind, which +is the most commonly used one by HTML forms. See also the CURLOPT_POST. Since +7.8, using CURLOPT_POSTFIELDS implies CURLOPT_POST. + +\fBNote:\fP to make multipart/formdata posts (aka rfc1867-posts), check out +the \fICURLOPT_HTTPPOST\fP option. +.TP +.B 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 zero, the library will use strlen() to get the size. (Added in +libcurl 7.2) +.TP +.B 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. +.TP +.B 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. +.TP +.B 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. +.TP +.B 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 CURLOPT_LOW_SPEED_TIME seconds for +the library to consider it too slow and abort. +.TP +.B CURLOPT_LOW_SPEED_TIME +Pass a long as parameter. It contains the time in seconds that the transfer +should be below the CURLOPT_LOW_SPEED_LIMIT for the library to consider it too +slow and abort. +.TP +.B CURLOPT_RESUME_FROM +Pass a long as parameter. It contains the offset in number of bytes that you +want the transfer to start from. +.TP +.B 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. +.TP +.B 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. + +\fBNOTE:\fPThe most commonly replaced headers have "shortcuts" in the options +CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER. +.TP +.B 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 HTTP post structs as parameter. The linked list should be a fully valid +list of 'struct HttpPost' structs properly filled in. The best and most +elegant way to do this, is to use \fIcurl_formadd(3)\fP as documented. The +data in this list must remained intact until you close this curl handle again +with \fIcurl_easy_cleanup(3)\fP. +.TP +.B 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. +.TP +.B 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) +.TP +.B CURLOPT_SSLCERTPASSWD +Pass a pointer to a zero terminated string as parameter. It will be used as +the password required to use the CURLOPT_SSLCERT certificate. If the password +is not supplied, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can +be used to set your own prompt function. + +\fBNOTE:\fPThis option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and only +cept for backward compatibility. You never needed a pass phrase to load +a certificate but you need one to load your private key. +.TP +.B 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. (Added in 7.9.3) +.TP +.B 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". +(Added in 7.9.3) + +\fBNOTE:\fPThe 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_SSL_ENGINE\fP. +.TP +.B CURLOPT_SSLKEYASSWD +Pass a pointer to a zero terminated string as parameter. It will be used as +the password required to use the \fICURLOPT_SSLKEY\fP private key. If the +password is not supplied, you will be prompted for +it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +(Added in 7.9.3) +.TP +.B CURLOPT_SSL_ENGINE +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. (Added in 7.9.3) + +\fBNOTE:\fPIf the crypto device cannot be loaded, +\fICURLE_SSL_ENGINE_NOTFOUND\fP is returned. +.TP +.B CURLOPT_SSL_ENGINEDEFAULT +Sets the actual crypto engine as the default for (asymetric) crypto +operations. (Added in 7.9.3) + +\fBNOTE:\fPIf the crypto device cannot be set, +\fICURLE_SSL_ENGINE_SETFAILED\fP is returned. +.TP +.B CURLOPT_CRLF +Convert Unix newlines to CRLF newlines on FTP uploads. +.TP +.B CURLOPT_QUOTE +Pass a pointer to a linked list of FTP commands to pass to the server prior to +your ftp request. 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 +with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a +NULL to this option. +.TP +.B CURLOPT_POSTQUOTE +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. +.TP +.B CURLOPT_WRITEHEADER +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 below on how to set a +custom get-all-headers callback. +.TP +.B 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 there is received header data that +needs to be written down. The headers are guaranteed to be written one-by-one +and only complete lines are written. 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. The pointer named \fIstream\fP will be the one +you passed to libcurl with the \fICURLOPT_WRITEHEADER\fP option. Return the +number of bytes actually written 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). (Added in libcurl 7.7.2) +.TP +.B CURLOPT_COOKIEFILE +Pass a pointer to a zero terminated string as parameter. It should contain the +name of your file holding cookie data. The cookie data may be in Netscape / +Mozilla cookie data format or just regular HTTP-style headers dumped to a +file. +.TP +.B CURLOPT_SSLVERSION +Pass a long as parameter. Set what version of SSL to attempt to use, 2 or +3. By default, the SSL library will try to solve this by itself although some +servers make this difficult why you at times may have to use this option. +.TP +.B CURLOPT_TIMECONDITION +Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE time value is +treated. You can set this parameter to TIMECOND_IFMODSINCE or +TIMECOND_IFUNMODSINCE. This is a HTTP-only feature. (TBD) +.TP +.B CURLOPT_TIMEVALUE +Pass a long as parameter. This should be the time in seconds since 1 jan 1970, +and the time will be used as specified in CURLOPT_TIMECONDITION or if that +isn't used, it will be TIMECOND_IFMODSINCE by default. +.TP +.B CURLOPT_CUSTOMREQUEST +Pass a pointer to a zero terminated string as parameter. It will be user +instead of GET or HEAD when doing the HTTP request. 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. +.TP +.B CURLOPT_STDERR +Pass a FILE * as parameter. This is the stream to use instead of stderr +internally when reporting errors. +.TP +.B 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. (Added in libcurl 7.3) +.TP +.B CURLOPT_KRB4LEVEL +Pass a char * as parameter. Set the krb4 security level, this also enables +krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or +\&'private'. If the string is set but doesn't match one of these, 'private' +will be used. Set the string to NULL to disable kerberos4. The kerberos +support only works for FTP. (Added in libcurl 7.3) +.TP +.B 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 data transfer. +Unknown/unused argument values 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. +.TP +.B 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. +.TP +.B CURLOPT_SSL_VERIFYPEER +Pass a long that is set to a non-zero value to make curl verify the peer's +certificate. The certificate to verify against must be specified with the +CURLOPT_CAINFO option. (Added in 7.4.2) +.TP +.B CURLOPT_CAINFO +Pass a char * to a zero terminated file naming holding the certificate to +verify the peer with. This only makes sense when used in combination with the +CURLOPT_SSL_VERIFYPEER option. (Added in 7.4.2) +.TP +.B CURLOPT_PASSWDFUNCTION +Pass a pointer to a \fIcurl_passwd_callback\fP function that will be called +instead of the internal one if libcurl requests a password. The function must +match this prototype: \fBint my_getpass(void *client, char *prompt, char* +buffer, int buflen );\fP. If set to NULL, it equals to making the function +always fail. If the function returns a non-zero value, it will abort the +operation and an error (CURLE_BAD_PASSWORD_ENTERED) will be returned. +\fIclient\fP is a generic pointer, see \fICURLOPT_PASSWDDATA\fP. \fIprompt\fP +is a zero-terminated string that is text that prefixes the input request. +\fIbuffer\fP is a pointer to data where the entered password should be stored +and \fIbuflen\fP is the maximum number of bytes that may be written in the +buffer. (Added in 7.4.2) +.TP +.B CURLOPT_PASSWDDATA +Pass a void * to whatever data you want. The passed pointer will be the first +argument sent to the specifed \fICURLOPT_PASSWDFUNCTION\fP function. (Added in +7.4.2) +.TP +.B CURLOPT_FILETIME +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 +can be used after a transfer to extract the received time (if any). (Added in +7.5) +.TP +.B 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.5) +.TP +.B CURLOPT_MAXCONNECTS +Pass a long. The set number will be the persistant connection cache size. The +set amount will be the maximum amount of simultaneous connections that libcurl +may cache between file transfers. 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. + +\fBNOTE:\fP if you already have performed transfers with this curl handle, +setting a smaller MAXCONNECTS than before may cause open connections to get +closed unnecessarily. (Added in 7.7) +.TP +.B CURLOPT_CLOSEPOLICY +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 +yet. (Added in 7.7) +.TP +.B CURLOPT_FRESH_CONNECT +Pass a long. Set to non-zero to make the next transfer use a new (fresh) +connection by force. If the connection cache is full before this connection, +one of the existing connections will be closed as according to the selected or +default policy. This option should be used with caution and only if you +understand what it does. Set this to 0 to have libcurl attempt re-using an +existing connection (default behavior). (Added in 7.7) +.TP +.B CURLOPT_FORBID_REUSE +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 +re-use (default behavior). (Added in 7.7) +.TP +.B 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 will the SSL connection become. +.TP +.B 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. +.TP +.B 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. + +\fBNOTE:\fP this does not work in unix multi-threaded programs, as it uses +signals. +.TP +.B CURLOPT_HTTPGET +Pass a long. If the long is non-zero, this forces the HTTP request to get back +to GET. Only really usable if POST, PUT or a custom request have been used +previously using the same curl handle. (Added in 7.8.1) +.TP +.B CURLOPT_SSL_VERIFYHOST +Pass a long. Set if we should verify the Common name from the peer certificate +in the SSL handshake, set 1 to check existence, 2 to ensure that it matches +the provided hostname. (Added in 7.8.1) +.TP +.B CURLOPT_COOKIEJAR +Pass a file name as char *, zero terminated. This will make libcurl dump 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. +.TP +.B 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 syntactly correct, it +consists of one or more cipher strings separated by colons. Commas or spaces +are also acceptable separators but colons are normally used, \!, \- and \+ can +be used as operators. Valid examples of cipher lists include 'RC4-SHA', +\'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you +compile OpenSSL. + +You'll find more details about cipher lists on this URL: +\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP +.TP +.B 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 +.TP 5 +.B CURL_HTTP_VERSION_NONE +We don't care about what version the library uses. libcurl will use whatever +it thinks fit. +.TP +.B CURL_HTTP_VERSION_1_0 +Enforce HTTP 1.0 requests. +.TP +.B CURL_HTTP_VERSION_1_1 +Enforce HTTP 1.1 requests. +.RE +.TP +.B CURLOPT_FTP_USE_EPSV +Pass a long. If the value is non-zero, it tells curl to use the EPSV command +when doing passive FTP downloads (which is 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. +.PP +.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. +.SH "SEE ALSO" +.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " +.SH BUGS +If you find any bugs, or just have questions, subscribe to one of the mailing +lists and post. We won't bite. + |