mirror of
https://codeberg.org/kiss-community/repo
synced 2024-08-19 12:46:58 +00:00
104 lines
4.5 KiB
Groff
104 lines
4.5 KiB
Groff
.\" generated by cd2nroff 0.1 from curl_multi_socket_action.md
|
|
.TH curl_multi_socket_action 3 "2024-06-01" libcurl
|
|
.SH NAME
|
|
curl_multi_socket_action \- reads/writes available data given an action
|
|
.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);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
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 chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or
|
|
CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and
|
|
libcurl tests the descriptor internally. It is also permissible to pass
|
|
CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the
|
|
whole process or when a timeout occurs.
|
|
|
|
At return, \fBrunning_handles\fP points to the number of running easy handles
|
|
within the multi handle. When this number reaches zero, all transfers are
|
|
complete/done. When you call \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 \fIcurl_multi_socket_action(3)\fP function informs 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
|
|
\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They
|
|
update the status with changes since the previous time the callback was
|
|
called.
|
|
|
|
Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option
|
|
with \fIcurl_multi_setopt(3)\fP. Your application then gets called with
|
|
information on how long to wait for socket actions at most before doing the
|
|
timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
|
|
\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the
|
|
\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but
|
|
for an event\-based system using the callback is far better than relying on
|
|
polling the timeout value.
|
|
|
|
When this function returns error, the state of all transfers are uncertain and
|
|
they cannot be continued. \fIcurl_multi_socket_action(3)\fP should not be
|
|
called again on the same multi handle after an error has been returned, unless
|
|
first removing all the handles and adding new ones.
|
|
.SH TYPICAL USAGE
|
|
1. Create a multi handle
|
|
|
|
2. Set the socket callback with \fICURLMOPT_SOCKETFUNCTION(3)\fP
|
|
|
|
3. Set the timeout callback with \fICURLMOPT_TIMERFUNCTION(3)\fP, to get to
|
|
know what timeout value to use when waiting for socket activities.
|
|
|
|
4. Add easy handles with curl_multi_add_handle()
|
|
|
|
5. Provide some means to manage the sockets libcurl is using, so you can check
|
|
them for activity. This can be done through your application code, or by way
|
|
of an external library such as libevent or glib.
|
|
|
|
6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...)
|
|
to kickstart everything. To get one or more callbacks called.
|
|
|
|
7. Wait for activity on any of libcurl\(aqs sockets, use the timeout value your
|
|
callback has been told.
|
|
|
|
8, When activity is detected, call curl_multi_socket_action() for the
|
|
socket(s) that got action. If no activity is detected and the timeout expires,
|
|
call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP.
|
|
.SH PROTOCOLS
|
|
All
|
|
.SH EXAMPLE
|
|
.nf
|
|
int main(void)
|
|
{
|
|
/* the event-library gets told when there activity on the socket 'fd',
|
|
which we translate to a call to curl_multi_socket_action() */
|
|
int running;
|
|
CURLM *multi; /* the stack we work with */
|
|
int fd; /* the descriptor that had action */
|
|
int bitmask; /* what activity that happened */
|
|
CURLMcode mc = curl_multi_socket_action(multi, fd, bitmask, &running);
|
|
if(mc)
|
|
printf("error: %s\\n", curl_multi_strerror(mc));
|
|
}
|
|
.fi
|
|
.SH AVAILABILITY
|
|
This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0.
|
|
.SH RETURN VALUE
|
|
CURLMcode type, general libcurl multi interface error code. See
|
|
\fIlibcurl\-errors(3)\fP
|
|
.SH SEE ALSO
|
|
.BR curl_multi_cleanup (3),
|
|
.BR curl_multi_fdset (3),
|
|
.BR curl_multi_info_read (3),
|
|
.BR curl_multi_init (3),
|
|
.BR the hiperfifo.c example
|