aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/libcurl/curl_multi_socket.342
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)"