curl_easy_setopt.3

harvest是一个下载html网页得机器人

.\" nroff -man [file]
.\" $Id: curl_easy_setopt.3,v 1.55 2003/10/17 13:11:01 bagder Exp $
.\"
.TH curl_easy_setopt 3 "16 Oct 2003" "libcurl 7.10.8" "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);
.ad
.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 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. libcurl will need them until you call curl_easy_cleanup() or you set
the same option again to use a different pointer.

\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 BEHAVIOR OPTIONS
.TP 0.4i
.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. Another neat option for debugging is the
\fICURLOPT_DEBUGFUNCTION\fP.
.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_NOSIGNAL
Pass a long. If it is non-zero, libcurl will not use any functions that
install signal handlers or any functions that cause signals to be sent to the
process. This option is mainly here to allow multi-threaded unix applications
to still set/use all timeout options etc, without risking getting signals.
(Added in 7.10)
.PP
.SH CALLBACK OPTIONS
.TP 0.4i
.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 reveiced 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.

Set the \fIstream\fP argument with the \fBCURLOPT_WRITEDATA\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. 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.
.TP
.B CURLOPT_WRITEDATA
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.

This option is also known with the older name \fBCURLOPT_FILE\fP, the name
CURLOPT_WRITEDATA was introduced in 7.9.7.
.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_READDATA
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.

This option is also known with the older name \fBCURLOPT_INFILE\fP, the name
CURLOPT_READDATA was introduced in 7.9.7.
.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.

Also note that \fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this
function actually get called.
.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_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).
.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 above on how to
set a custom get-all-headers callback.
.TP
.B CURLOPT_DEBUGFUNCTION
Function pointer that should match the following prototype: \fIint
curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP
CURLOPT_DEBUGFUNCTION replaces the standard debug function used when
CURLOPT_VERBOSE is in effect. This callback receives debug information, as
specified with the \fIcurl_infotype\fP argument. This funtion 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
.TP 5
.B CURLINFO_TEXT
The data is informational text.
.TP
.B CURLINFO_HEADER_IN
The data is header (or header-like) data received from the peer.
.TP
.B CURLINFO_HEADER_OUT
The data is header (or header-like) data sent to the peer.
.TP
.B CURLINFO_DATA_IN
The data is protocol data received from the peer.
.TP
.B CURLINFO_DATA_OUT
The data is protocol data sent to the peer.
.RE
.TP
.B CURLOPT_DEBUGDATA
Pass a pointer to whatever you want passed in to your CURLOPT_DEBUGFUNCTION in
the last void * argument. This pointer is not used by libcurl, it is only
passed to the callback.
.PP
.SH ERROR OPTIONS
.TP 0.4i
.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.

Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better
debug/trace why errors happen.

\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_STDERR
Pass a FILE * as parameter. This is the stream to use instead of stderr
internally when reporting errors.
.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.
.PP
.SH NETWORK OPTIONS
.TP 0.4i
.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_PROXYTYPE
Pass a long with this option to set type of the proxy. Available options for
this are CURLPROXY_HTTP and CURLPROXY_SOCKS5, with the HTTP one being
default. (Added in 7.10)
.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.
.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.
.TP
.B 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 (0) to completely disable
caching, or set to -1 to make the cached entries remain forever. By default,
libcurl caches info for 60 seconds.
.TP
.B CURLOPT_DNS_USE_GLOBAL_CACHE
Pass a long. If the value is non-zero, it tells curl to use a global DNS cache
that will survive between easy handle creations and deletions. This is not
thread-safe and this will use a global varible.
.TP
.B CURLOPT_BUFFERSIZE
Pass a long specifying your prefered size 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)
.PP
.SH NAMES and PASSWORDS OPTIONS (Authentication)
.TP 0.4i
.B 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.

\fBNote:\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
.TP 5
.B 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.
.TP     
.B CURL_NETRC_IGNORED
The library will ignore the file and use only the information in the URL.

This is the default.
.TP
.B 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
.TP
Only machine name, user name and password are 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