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.
+or the stream set with \fICURLOPT_STDERR\fP. The default value for this
+parameter is 0.
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
.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).
+preceding the data (like HTTP). The default value for this parameter is 0.
.IP CURLOPT_NOPROGRESS
Pass a long. If set to 1, it tells the library to shut off the progress meter
completely. It will also prevent the \fICURLOPT_PROGRESSFUNCTION\fP from
-getting called.
+getting called. The default value for this parameter is 1.
Future versions of libcurl are likely to not have any built-in progress meter
at all.
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.
+The default value for this parameter is 0.
(Added in 7.10)
If this option is set and libcurl has been built with the standard name
.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.
+input. If you don't use a callback, you must pass a 'FILE *' (cast
+to 'void *') as libcurl will pass this to fwrite() when writing data.
+By default, the value of this parameter is unspecified.
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.
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 *.
+read function, this data must be a valid readable FILE * (cast to 'void *').
If you're using libcurl as a win32 DLL, you MUST use a
\fICURLOPT_READFUNCTION\fP if you set this option.
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).
+method. By default, this parameter is set to NULL. (Option added in 7.12.3).
-Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking!
+Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking! If
+\fICURLOPT_SEEKFUNCTION\fP is set, this parameter will be ignored when 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)
+argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP.
+By default, the value of this parameter is unspecified. (Option added in
+7.12.3)
.IP CURLOPT_SEEKFUNCTION
Pass a pointer to a function that matches the following prototype: \fBint
function(void *instream, curl_off_t offset, int origin);\fP This function gets
free to work around the problem if possible. The latter can sometimes be done
by instead reading from the input or similar.
+By default, this parameter is unset.
+
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)
you don't specify a seek callback, NULL is passed. (Option added in 7.18.0)
.IP CURLOPT_SOCKOPTFUNCTION
Pass a pointer to a function that matches the following prototype: \fBint
-function(void *clientp, curl_socket_t curlfd, curlsocktype purpose);\fP. This
+function(void *clientp, curl_socket_t curlfd, curlsocktype purpose);\fP. By
+default, this parameter is unset. If set, 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:
.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.
+The default value of this parameter is unspecified.
(Option added in 7.16.0)
.IP CURLOPT_OPENSOCKETFUNCTION
Pass a pointer to a function that matches the following prototype:
.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.
+The default value of this parameter is unspecified.
(Option added in 7.17.1.)
.IP CURLOPT_CLOSESOCKETFUNCTION
Pass a pointer to a function that matches the following prototype: \fBint
.IP CURLOPT_CLOSESOCKETDATA
Pass a pointer that will be untouched by libcurl and passed as the first
argument in the closesocket callback set with
-\fICURLOPT_CLOSESOCKETFUNCTION\fP. (Option added in 7.21.7)
+\fICURLOPT_CLOSESOCKETFUNCTION\fP.
+The default value of this parameter is unspecified.
+(Option added in 7.21.7)
.IP CURLOPT_PROGRESSFUNCTION
Pass a pointer to a function that matches the following prototype: \fBint
function(void *clientp, double dltotal, double dlnow, double ultotal, double
.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.
+The default value of this parameter is unspecified.
.IP CURLOPT_HEADERFUNCTION
Pass a pointer to a function that matches the following prototype:
\fBsize_t function( void *ptr, size_t size, size_t nmemb, void
more callback details.
.IP CURLMOPT_SOCKETDATA
Pass a pointer to whatever you want passed to the \fBcurl_socket_callback\fP's
-forth argument, the userp pointer. This is not used by libcurl but only
+fourth argument, the userp pointer. This is not used by libcurl but only
passed-thru as-is. Set the callback pointer with
\fICURLMOPT_SOCKETFUNCTION\fP.
.IP CURLMOPT_PIPELINING
7.16.0)
.IP CURLMOPT_TIMERFUNCTION
Pass a pointer to a function matching the \fBcurl_multi_timer_callback\fP
-prototype. This function will then be called when the timeout value
+prototype: int curl_multi_timer_callback(CURLM *multi /* multi handle */,
+long timeout_ms /* timeout in milliseconds */, void *userp /* TIMERDATA */).
+This function will then be called when the timeout value
changes. The timeout value is at what latest time the application should call
one of the \&"performing" functions of the multi interface
(\fIcurl_multi_socket_action(3)\fP and \fIcurl_multi_perform(3)\fP) - to allow
libcurl to keep timeouts and retries etc to work. A timeout value of -1 means
that there is no timeout at all, and 0 means that the timeout is already
reached. Libcurl attempts to limit calling this only when the fixed future
-timeout time actually changes. See also \fICURLMOPT_TIMERDATA\fP. This
+timeout time actually changes. See also \fICURLMOPT_TIMERDATA\fP. The callback
+should return 0 on success, and -1 on error. This
callback can be used instead of, or in addition to,
\fIcurl_multi_timeout(3)\fP. (Added in 7.16.0)
.IP CURLMOPT_TIMERDATA
\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of
events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or
CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and
-libcurl will test the descriptor internally.
+libcurl will test the descriptor internally. It is also permissible to pass
+CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the
+whole process or when a timeout occurs.
At return, the integer \fBrunning_handles\fP points to will contain the number
of running easy handles within the multi handle. When this number reaches
curl_socket_t s, /* socket */
int action, /* see values below */
void *userp, /* private callback pointer */
- void *socketp); /* private socket pointer */
+ void *socketp); /* private socket pointer,
+ \fBNULL\fI if not
+ previously assigned with
+ \fIcurl_multi_assign(3)\fP */
.fi
The callback MUST return 0.
them for activity. This can be done through your application code, or by way
of an external library such as libevent or glib.
-6. Call curl_multi_socket_action(...CURL_SOCKET_TIMEOUT...) to kickstart
-everything. To get one or more callbacks called.
+6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...)
+to kickstart everything. To get one or more callbacks called.
7. Wait for activity on any of libcurl's sockets, use the timeout value your
-callback has been told
+callback has been told.
8, When activity is detected, call curl_multi_socket_action() for the
socket(s) that got action. If no activity is detected and the timeout expires,
-call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP
+call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP.
.SH AVAILABILITY
This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0.
.SH "SEE ALSO"