diff options
| -rw-r--r-- | docs/libcurl/curl_easy_setopt.3 | 37 | ||||
| -rw-r--r-- | docs/libcurl/curl_multi_cleanup.3 | 3 | ||||
| -rw-r--r-- | docs/libcurl/curl_multi_setopt.3 | 9 | ||||
| -rw-r--r-- | docs/libcurl/curl_multi_socket_action.3 | 17 | ||||
| -rw-r--r-- | docs/libcurl/curl_multi_timeout.3 | 2 | ||||
| -rw-r--r-- | docs/libcurl/curl_version.3 | 3 |
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)" |