diff options
| -rw-r--r-- | docs/libcurl/curl_multi_socket.3 | 40 |
1 files changed, 26 insertions, 14 deletions
diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 0c5ba7345..9ad8257f1 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -6,26 +6,38 @@ curl_multi_socket \- reads/writes available data .SH SYNOPSIS #include <curl/curl.h> -CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd); +CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd, + int *running_handles); -CURLMcode curl_multi_socket_all(CURLM *multi_handle); +CURLMcode curl_multi_socket_all(CURLM *multi_handle, + int *running_handles); .SH DESCRIPTION -Alternative versions of \fIcurl_multi_perform()\fP that allows the application -to pass in one of the file descriptors/sockets that have been detected to have -\&"action" on them and let libcurl perform. This allows libcurl to not have to -scan through all possible file descriptors to check for action. When the -application has detected action on a socket handled by libcurl, it should call -\fIcurl_multi_perform()\fP with the \fBsockfd\fP argument set to the socket -with the action. - -These functions inform the application about updates in the socket (file -descriptor) status by doing none, one or multiple calls to the callback -function set with the CURLMOPT_SOCKETFUNCTION option to +Alternative versions of \fIcurl_multi_perform(3)\fP that allows the +application to pass in one of the file descriptors/sockets that have been +detected to have \&"action" on them and let libcurl perform. This allows +libcurl to not have to scan through all possible file descriptors to check for +action. When the application has detected action on a socket handled by +libcurl, it should call \fIcurl_multi_socket(3)\fP with the \fBsockfd\fP +argument set to the socket with the action. + +At return, the int \fBrunning_handles\fP points to will contain the number of +still running easy handles within the multi handle. When this number reaches +zero, all transfers are complete/done. Note that when you call +\fIcurl_multi_socket(3)\fP on a specific socket and the counter decreases by +one, it DOES NOT necessarily mean that this exact socket/transfer is the one +that completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy +handle that completed. + +The curl_multi_socket functions inform the application about updates in the +socket (file descriptor) status by doing none, one or multiple calls to the +socket callback function set with the CURLMOPT_SOCKETFUNCTION option to \fIcurl_multi_setopt(3)\fP. They update the status with changes since the previous time this function was called. To force libcurl to (re-)check all its internal sockets and transfers instead -of just a single one, you call \fBcurl_multi_socket_all(3)\fP. +of just a single one, you call \fBcurl_multi_socket_all(3)\fP. This is +typically done as the first function call before the application has any +knowledge about what sockets libcurl uses. Applications should call \fBcurl_multi_timeout(3)\fP to figure out how long to wait for socket actions \- at most \- before doing the timeout action: call |