From a718cb05ff4405dd5a3e09b718413b5066fc5e09 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Dec 2005 15:11:11 +0000 Subject: The inital early embryos to describe the curl_multi_socket() API. Committed now to enable them to get added as web pages easier, they are not ready for anything "real" just yet. --- docs/libcurl/curl_multi_socket.3 | 82 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/libcurl/curl_multi_socket.3 (limited to 'docs/libcurl/curl_multi_socket.3') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 new file mode 100644 index 000000000..8c42a8db1 --- /dev/null +++ b/docs/libcurl/curl_multi_socket.3 @@ -0,0 +1,82 @@ +.\" $Id$ +.\" +.TH curl_multi_socket 3 "21 Dec 2005" "libcurl 7.16.0" "libcurl Manual" +.SH NAME +curl_multi_socket - reads/writes available data +.SH SYNOPSIS +#include + +CURLMcode curl_multi_socket(CURLM * multi_handle, + curl_socket_t sockfd, + CURL *easy, + curl_socket_callback callback, + void *userp); + +CURLMcode curl_multi_socket_all(CURLM *multi_handle, + curl_socket_callback callback, + void *userp); +.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. The +application is recommended to pass in the \fBeasy\fP argument (or set it to +CURL_EASY_NONE) to make libcurl figure out the internal structure even faster +and easier. If the easy argument is set to something else than +CURL_EASY_NONE, the \fBsockfd\fP argument will be ignored by libcurl. + +These functions inform the application about updates in the socket (file +descriptor) status by doing none, one or multiple calls to the +curl_socket_callback given in the \fBcallback\fP argument. They update the +status with changes since the previous time this function was used. If +\fBcallback\fP is NULL, no callback will be called. A status change may also +be a new timeout only, having the same IN/OUT status as before. + +If a previous wait for socket action(s) timed out, you should call this +function with the socket argument set to CURL_SOCKET_TIMEOUT. If you want to +force libcurl to (re-)check all its internal sockets, and call the callback +with status for all sockets no matter what the previous state is, you call +curl_multi_socket_all() instead. + +curl_multi_perform() is the equivalent of calling +curl_multi_socket_all(handle, NULL, NULL); + +Regarding the timeout argument in the callback: it is the timeout (in +milliseconds) for waiting on action on this socket (and the given time period +starts when the callback is called) until you should call curl_multi_socket() +with the timeout stuff mentioned above. If "actions" happens on the socket +before the timeout happens, remember that the timout timer keeps ticking until +told otherwise. + +The "what" argument has one of five values: +.RS +.IP "CURL_POLL_NONE (0)" +register, not interested in readiness (yet) +.IP "CURL_POLL_IN (1)" +register, interested in read readiness +.IP "CURL_POLL_OUT (2)" +register, interested in write readiness +.IP "CURL_POLL_INOUT (3)" +register, interested in both read and write readiness +.IP "CURL_POLL_REMOVE (4)" +deregister +.RE +.SH "RETURN VALUE" +CURLMcode type, general libcurl multi interface error code. + +If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you +should call \fIcurl_multi_perform\fP again, before you select() on more +actions. You don't have to do it immediately, but the return code means that +libcurl may have more data available to return or that there may be more data +to send off before it is "satisfied". + +NOTE that this only returns errors etc regarding the whole multi stack. There +might still have occurred problems on individual transfers even when this +function returns OK. +.SH "TYPICAL USAGE" +Call curl_multi_socket_all() first. Setup a "collection" of sockets to +supervise, then when action happens call curl_multi_socket() for the easy +handle that got the action. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " +.BR curl_multi_fdset "(3), " curl_multi_info_read "(3)" -- cgit v1.2.3