mirror of https://github.com/moparisthebest/curl
83 lines
3.6 KiB
Groff
83 lines
3.6 KiB
Groff
.\" $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 <curl/curl.h>
|
|
|
|
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)"
|