mirror of
https://github.com/moparisthebest/curl
synced 2024-10-31 15:45:12 -04:00
410 lines
17 KiB
Groff
410 lines
17 KiB
Groff
.\" You can view this file with:
|
|
.\" nroff -man [file]
|
|
.\" Written by daniel@haxx.se
|
|
.\"
|
|
.TH curl_easy_setopt 3 "28 November 2000" "Curl 7.5" "libcurl Manual"
|
|
.SH NAME
|
|
curl_easy_setopt - Set curl easy-session options
|
|
.SH SYNOPSIS
|
|
.B #include <curl/easy.h>
|
|
.sp
|
|
.BI "CURLcode curl_easy_setopt(CURL *" handle ", CURLoption "option ", ...);
|
|
.ad
|
|
.SH DESCRIPTION
|
|
curl_easy_setopt() is called to tell libcurl how to behave in a number of
|
|
ways. Most operations in libcurl have default actions, and by using the
|
|
appropriate options you can make them behave differently (as documented). All
|
|
options are set with the
|
|
.I option
|
|
followed by a parameter. That parameter can be a long, a function pointer or
|
|
an object pointer, all depending on what the option in question 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 calls in the setup phase.
|
|
|
|
The
|
|
.I "handle"
|
|
is the return code from the
|
|
.I "curl_easy_init"
|
|
call.
|
|
.SH OPTIONS
|
|
These options are in a bit of random order, but you'll figure it out!
|
|
.TP 0.8i
|
|
.B CURLOPT_FILE
|
|
Data pointer to pass instead of FILE * to the file write function. Note that
|
|
if you specify the
|
|
.I CURLOPT_WRITEFUNCTION
|
|
, this is the pointer you'll get as input.
|
|
.TP
|
|
.B CURLOPT_WRITEFUNCTION
|
|
Function pointer that should use match the following prototype:
|
|
.BI "size_t function( void *ptr, size_t size, size_t nmemb, FILE *stream);"
|
|
This function gets called by libcurl as soon as there is received data that
|
|
needs to be written down. The size of the data pointed to by
|
|
.I ptr
|
|
is
|
|
.I size
|
|
multiplied with
|
|
.I nmemb.
|
|
Return the number of bytes actually written or return -1 to signal error to the library (it will cause it to abort the transfer).
|
|
.TP
|
|
.B CURLOPT_INFILE
|
|
Data pointer to pass instead of FILE * to the file read function. Note that if
|
|
you specify the
|
|
.I CURLOPT_READFUNCTION
|
|
, this is the pointer you'll get as input.
|
|
.TP
|
|
.B CURLOPT_READFUNCTION
|
|
Function pointer that should use match the following prototype:
|
|
.BI "size_t function( void *ptr, size_t size, size_t nmemb, FILE *stream);"
|
|
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
|
|
.I ptr
|
|
may be filled with at most
|
|
.I size
|
|
multiplied with
|
|
.I nmemb
|
|
number of bytes. Your function must return the actual number of bytes that you
|
|
stored in that memory area. Returning -1 will signal an error to the library
|
|
and cause it to abort the current transfer immediately.
|
|
.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. NOTE: this option is currently required!
|
|
.TP
|
|
.B CURLOPT_PROXY
|
|
If you need libcurl to use a http proxy to access the outside world, set the
|
|
proxy string with this option. The parameter should be a char * to a zero
|
|
terminated string. 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.
|
|
.TP
|
|
.B CURLOPT_PROXYPORT
|
|
Set this long with this option to set the proxy port to use unless it is
|
|
specified in the proxy string CURLOPT_PROXY.
|
|
.TP
|
|
.B CURLOPT_HTTPPROXYTUNNEL
|
|
Set the parameter to non-zero to get the library to tunnel all non-HTTP
|
|
operations through the given HTTP proxy. Do note that there is a big
|
|
difference to use a proxy and to tunnel through it. If you don't know what
|
|
this means, you probably don't want this tunnel 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.
|
|
.TP
|
|
.B CURLOPT_HEADER
|
|
A non-zero parameter tells the library to include the header in the
|
|
output. This is only relevant for protocols that actually has a header
|
|
preceeding the data (like HTTP).
|
|
.TP
|
|
.B CURLOPT_NOPROGRESS
|
|
A non-zero parameter tells the library to shut of the built-in progress meter
|
|
completely. (NOTE: future versions of the lib 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 a separate header and
|
|
body part.
|
|
.TP
|
|
.B CURLOPT_FAILONERROR
|
|
A non-zero parameter tells the library to fail silently if the HTTP code
|
|
returned is equal 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.
|
|
.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 listin 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
|
|
.I ~/.netrc
|
|
file to find user name and password for the remote site you are about to
|
|
access. Do note that curl does not verify that the file has the correct
|
|
properties set (as the standard unix ftp client does), and that only machine
|
|
name, user name and password is taken into account (init macros and similar
|
|
things aren't supported).
|
|
.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. NOTE that this means that the library
|
|
will resend the same request on the new location and follow new Location:
|
|
headers all the way until no more such headers are returned.
|
|
.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 useable when transfering text data between
|
|
system 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 a file. The file to put
|
|
must be set with CURLOPT_INFILE and CURLOPT_INFILESIZE.
|
|
.TP
|
|
.B CURLOPT_MUTE
|
|
A non-zero parameter tells the library to be completely quiet.
|
|
.TP
|
|
.B CURLOPT_USERPWD
|
|
Pass a char * as parameter, which should be [username]:[password] to use for
|
|
the connection. If the password is left out, you will be prompted for it.
|
|
.TP
|
|
.B CURLOPT_PROXYUSERPWD
|
|
Pass a char * as parameter, which should be [username]:[password] to use for
|
|
the connection to the HTTP proxy. If the password is left out, you will be
|
|
prompted for it.
|
|
.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. The HTTP
|
|
transfers also support several intervals, separated with commas as in
|
|
.I "X-Y,N-M".
|
|
.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.
|
|
.TP
|
|
.B CURLOPT_TIMEOUT
|
|
Pass a long as parameter containing the maximum time in seconds that you allow
|
|
the libcurl transfer operation to take. Do note that normally, name lookups
|
|
maky take a considerable time and that limiting the operation to less than a
|
|
few minutes risk aborting perfectly normal operations.
|
|
.TP
|
|
.B CURLOPT_POSTFIELDS
|
|
Pass a char * as parameter, which should be the full data to post in a HTTP
|
|
post operation. See also the CURLOPT_POST.
|
|
.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. Also, 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 data
|
|
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.
|
|
.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.
|
|
.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.
|
|
.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 'struct
|
|
curl_slist' structs properly filled in. Use
|
|
.I curl_slist_append(3)
|
|
to create the list and
|
|
.I curl_slist_free_all(3)
|
|
to clean up an entire list.
|
|
.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
|
|
.I curl_formparse(3)
|
|
as documented.
|
|
.TP
|
|
.B CURLOPT_SSLCERT
|
|
Pass a pointer to a zero terminated string as parameter. The string should be
|
|
the file name of your certficicate in PEM format.
|
|
.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.
|
|
.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
|
|
.I curl_slist_append(3)
|
|
to append strings (commands) to the list, and clear the entire list afterwards
|
|
with
|
|
.I curl_slist_free_all(3)
|
|
.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
|
|
.I "CURLOPT_QUOTE"
|
|
.TP
|
|
.B CURLOPT_WRITEHEADER
|
|
Pass a FILE * to be used to write the header part of the received data to.
|
|
.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
|
|
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 will 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 aa 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 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_WRITEINFO
|
|
(NOT PRESENT IN 7.4 or later!)
|
|
Pass a pointer to a zero terminated string as parameter. It will be used to
|
|
report information after a successful request. This string may contain
|
|
variables that will be substituted by their contents when output. Described
|
|
elsewhere.
|
|
.TP
|
|
.B CURLOPT_PROGRESSFUNCTION
|
|
Function pointer that should match the
|
|
.BI curl_progress_callback
|
|
prototype found in
|
|
.I <curl/curl.h>
|
|
This function gets called by libcurl instead of its internal
|
|
equivalent. 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
|
|
CURLE_ABORTED_BY_CALLBACK.
|
|
.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
|
|
.I CURLOPT_PROGRESSFUNCTION
|
|
.
|
|
.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 curl_passwd_callback function that will then be called
|
|
instead of the internal one if libcurl requests a password. The function must
|
|
match this prototype:
|
|
.BI "int my_getpass(void *client, char *prompt, char* buffer, int buflen );"
|
|
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.
|
|
.I client
|
|
is a generic pointer, see CURLOPT_PASSWDDATA.
|
|
.I prompt
|
|
is a zero-terminated string that is text that prefixes the input request.
|
|
.I buffer
|
|
is a pointer to data where the entered password should be stored and
|
|
.I buflen
|
|
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 CURLOPT_PASSWDFUNCTION 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
|
|
curl_easy_getinfo() function with the CURLINFO_FILETIME 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. This
|
|
option only makes sense if the CURLOPT_FOLLOWLOCATION is used at the same
|
|
time. (Added in 7.5)
|
|
.PP
|
|
.SH RETURN VALUE
|
|
0 means the option was set properly, non-zero means an error as
|
|
.I <curl/curl.h>
|
|
defines
|
|
.SH "SEE ALSO"
|
|
.BR curl_easy_init "(3), " curl_easy_cleanup "(3), "
|
|
.SH BUGS
|
|
Surely there are some, you tell me!
|