diff options
Diffstat (limited to 'docs/libcurl')
| -rw-r--r-- | docs/libcurl/curl_multi_socket.3 | 42 |
1 files changed, 30 insertions, 12 deletions
diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 9ad8257f1..3cfd20b40 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -4,29 +4,40 @@ .SH NAME curl_multi_socket \- reads/writes available data .SH SYNOPSIS +.nf #include <curl/curl.h> +CURLMcode curl_multi_socket_action(CURLM * multi_handle, + curl_socket_t sockfd, int ev_bitmask, + int *running_handles); + CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd, int *running_handles); CURLMcode curl_multi_socket_all(CURLM *multi_handle, int *running_handles); +.fi .SH DESCRIPTION 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. +application to pass in the file descriptor/socket that has been detected to +have \&"action" on it 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_action(3)\fP with the \fBsockfd\fP argument set to the +socket with the action. When the events on a socket are known, they 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 +choosen 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. 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. +\fIcurl_multi_socket_action(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 @@ -44,6 +55,10 @@ wait for socket actions \- at most \- before doing the timeout action: call the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. +Usage of \fIcurl_multi_socket(3)\fP is depricated, whereas the function is +equivalent to \fIcurl_multi_socket_action(3)\fP, when \fBev_bitmask\fP is set +to 0. + .SH "CALLBACK DETAILS" The socket \fBcallback\fP function uses a prototype like this @@ -115,12 +130,15 @@ callback is called. 7. Wait for action on any of libcurl's sockets -8, When action happens, call curl_multi_socket() for the socket(s) that got +8, When action happens, call curl_multi_socket_action() for the socket(s) that got action. 9. Go back to step 6. .SH AVAILABILITY -This function was added in libcurl 7.15.4, although not deemed stable yet. +This function was added in libcurl 7.15.4, although deemed stablesince 7.16.0. + +\fIcurl_multi_socket(3)\fP is deprecated, use +\fIcurl_multi_socket_action(3)\fP instead! .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " .BR curl_multi_fdset "(3), " curl_multi_info_read "(3)" |