curl_easy_setopt.3

THIS IS HTTP CURL Example

.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, <[e-mail]>, 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: curl_easy_setopt.3,v 1.211 2008-01-11 14:20:41 bagder Exp $
.\" **************************************************************************
.\"
.TH curl_easy_setopt 3 "5 Jan 2008" "libcurl 7.18.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 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. 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 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).
.IP CURLOPT_NOPROGRESS
A non-zero parameter 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 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)

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
non-zero 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.