aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl
diff options
context:
space:
mode:
Diffstat (limited to 'docs/libcurl')
-rw-r--r--docs/libcurl/curl_easy_setopt.337
-rw-r--r--docs/libcurl/curl_multi_cleanup.33
-rw-r--r--docs/libcurl/curl_multi_setopt.39
-rw-r--r--docs/libcurl/curl_multi_socket_action.317
-rw-r--r--docs/libcurl/curl_multi_timeout.32
-rw-r--r--docs/libcurl/curl_version.33
6 files changed, 47 insertions, 24 deletions
diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index 2d6fa4e5d..aa22a002a 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -58,7 +58,8 @@ The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or
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
@@ -66,11 +67,11 @@ 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.
@@ -79,6 +80,7 @@ Pass a long. If it is 1, 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.
+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
@@ -180,8 +182,9 @@ means 100K.
.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.
@@ -226,7 +229,7 @@ userdata set with \fICURLOPT_READDATA\fP.
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.
@@ -240,13 +243,15 @@ 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).
+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
@@ -262,6 +267,8 @@ success, 1 (CURL_SEEKFUNC_FAIL) to cause the upload operation to fail or 2
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)
@@ -271,7 +278,8 @@ Data pointer to pass to the file seek function. If you use the
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:
@@ -293,6 +301,7 @@ in fact already connected and then libcurl will not attempt to connect it.
.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:
@@ -317,6 +326,7 @@ blacklisting. The default behavior is:
.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
@@ -328,7 +338,9 @@ success and 1 if there was an error. (Option added in 7.21.7)
.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
@@ -349,6 +361,7 @@ get called.
.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
diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3
index e83c9f01b..50bc8adbd 100644
--- a/docs/libcurl/curl_multi_cleanup.3
+++ b/docs/libcurl/curl_multi_cleanup.3
@@ -41,6 +41,7 @@ handle is no longer connected to the multi handle
3 - \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are
removed
.SH RETURN VALUE
-CURLMcode type, general libcurl multi interface error code.
+CURLMcode type, general libcurl multi interface error code. On success,
+CURLM_OK is returned.
.SH "SEE ALSO"
.BR curl_multi_init "(3)," curl_easy_cleanup "(3)," curl_easy_init "(3)"
diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3
index baaaaeac0..9e456a093 100644
--- a/docs/libcurl/curl_multi_setopt.3
+++ b/docs/libcurl/curl_multi_setopt.3
@@ -49,7 +49,7 @@ argument with \fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for
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
@@ -61,14 +61,17 @@ on the same connection rather than being executed in parallel. (Added in
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
diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3
index ac3b176c7..59a9d942a 100644
--- a/docs/libcurl/curl_multi_socket_action.3
+++ b/docs/libcurl/curl_multi_socket_action.3
@@ -38,7 +38,9 @@ can be passed as an events bitmask \fBev_bitmask\fP by first setting
\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
@@ -71,7 +73,10 @@ The socket \fBcallback\fP function uses a prototype like this
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.
@@ -132,15 +137,15 @@ timeout value to use when waiting for socket activities.
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"
diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3
index 5ad8008ea..e18b935cc 100644
--- a/docs/libcurl/curl_multi_timeout.3
+++ b/docs/libcurl/curl_multi_timeout.3
@@ -42,7 +42,7 @@ of milliseconds at this very moment. If 0, it means you should proceed
immediately without waiting for anything. If it returns -1, there's no timeout
at all set.
-An application that uses the multi_socket API SHOULD not use this function, but
+An application that uses the multi_socket API SHOULD NOT use this function, but
SHOULD instead use \fIcurl_multi_setopt(3)\fP and its
\fPCURLMOPT_TIMERFUNCTION\fP option for proper and desired behavior.
diff --git a/docs/libcurl/curl_version.3 b/docs/libcurl/curl_version.3
index 003329800..f66e38d14 100644
--- a/docs/libcurl/curl_version.3
+++ b/docs/libcurl/curl_version.3
@@ -31,6 +31,7 @@ curl_version - returns the libcurl version string
Returns a human readable string with the version number of libcurl and some of
its important components (like OpenSSL version).
.SH RETURN VALUE
-A pointer to a zero terminated string.
+A pointer to a zero terminated string. The string resides in a statically
+allocated buffer and must not be freed by the caller.
.SH "SEE ALSO"
.BR curl_version_info "(3)"