| 1 |
.\" ************************************************************************** |
| 2 |
.\" * _ _ ____ _ |
| 3 |
.\" * Project ___| | | | _ \| | |
| 4 |
.\" * / __| | | | |_) | | |
| 5 |
.\" * | (__| |_| | _ <| |___ |
| 6 |
.\" * \___|\___/|_| \_\_____| |
| 7 |
.\" * |
| 8 |
.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <[email protected]>, et al. |
| 9 |
.\" * |
| 10 |
.\" * This software is licensed as described in the file COPYING, which |
| 11 |
.\" * you should have received as part of this distribution. The terms |
| 12 |
.\" * are also available at https://curl.haxx.se/docs/copyright.html. |
| 13 |
.\" * |
| 14 |
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| 15 |
.\" * copies of the Software, and permit persons to whom the Software is |
| 16 |
.\" * furnished to do so, under the terms of the COPYING file. |
| 17 |
.\" * |
| 18 |
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| 19 |
.\" * KIND, either express or implied. |
| 20 |
.\" * |
| 21 |
.\" ************************************************************************** |
| 22 |
.TH curl_multi_socket 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" |
| 23 |
.SH NAME |
| 24 |
curl_multi_socket \- reads/writes available data |
| 25 |
.SH SYNOPSIS |
| 26 |
.nf |
| 27 |
#include <curl/curl.h> |
| 28 |
CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd, |
| 29 |
int *running_handles); |
| 30 |
|
| 31 |
CURLMcode curl_multi_socket_all(CURLM *multi_handle, |
| 32 |
int *running_handles); |
| 33 |
.fi |
| 34 |
.SH DESCRIPTION |
| 35 |
These functions are deprecated. Do not use! See |
| 36 |
\fIcurl_multi_socket_action(3)\fP instead! |
| 37 |
|
| 38 |
At return, the integer \fBrunning_handles\fP points to will contain the number |
| 39 |
of still running easy handles within the multi handle. When this number |
| 40 |
reaches zero, all transfers are complete/done. Note that when you call |
| 41 |
\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter |
| 42 |
decreases by one, it DOES NOT necessarily mean that this exact socket/transfer |
| 43 |
is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out |
| 44 |
which easy handle that completed. |
| 45 |
|
| 46 |
The \fIcurl_multi_socket_action(3)\fP functions inform the application about |
| 47 |
updates in the socket (file descriptor) status by doing none, one, or multiple |
| 48 |
calls to the socket callback function set with the |
| 49 |
\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They |
| 50 |
update the status with changes since the previous time the callback was |
| 51 |
called. |
| 52 |
|
| 53 |
Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option |
| 54 |
with \fIcurl_multi_setopt(3)\fP. Your application will then get called with |
| 55 |
information on how long to wait for socket actions at most before doing the |
| 56 |
timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the |
| 57 |
\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the |
| 58 |
\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but |
| 59 |
for an event-based system using the callback is far better than relying on |
| 60 |
polling the timeout value. |
| 61 |
|
| 62 |
Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is |
| 63 |
equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to |
| 64 |
0. |
| 65 |
|
| 66 |
Force libcurl to (re-)check all its internal sockets and transfers instead of |
| 67 |
just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there |
| 68 |
should not be any reason to use this function! |
| 69 |
.SH "CALLBACK DETAILS" |
| 70 |
|
| 71 |
The socket \fBcallback\fP function uses a prototype like this |
| 72 |
.nf |
| 73 |
|
| 74 |
int curl_socket_callback(CURL *easy, /* easy handle */ |
| 75 |
curl_socket_t s, /* socket */ |
| 76 |
int action, /* see values below */ |
| 77 |
void *userp, /* private callback pointer */ |
| 78 |
void *socketp); /* private socket pointer */ |
| 79 |
|
| 80 |
.fi |
| 81 |
The callback MUST return 0. |
| 82 |
|
| 83 |
The \fIeasy\fP argument is a pointer to the easy handle that deals with this |
| 84 |
particular socket. Note that a single handle may work with several sockets |
| 85 |
simultaneously. |
| 86 |
|
| 87 |
The \fIs\fP argument is the actual socket value as you use it within your |
| 88 |
system. |
| 89 |
|
| 90 |
The \fIaction\fP argument to the callback has one of five values: |
| 91 |
.RS |
| 92 |
.IP "CURL_POLL_NONE (0)" |
| 93 |
register, not interested in readiness (yet) |
| 94 |
.IP "CURL_POLL_IN (1)" |
| 95 |
register, interested in read readiness |
| 96 |
.IP "CURL_POLL_OUT (2)" |
| 97 |
register, interested in write readiness |
| 98 |
.IP "CURL_POLL_INOUT (3)" |
| 99 |
register, interested in both read and write readiness |
| 100 |
.IP "CURL_POLL_REMOVE (4)" |
| 101 |
unregister |
| 102 |
.RE |
| 103 |
|
| 104 |
The \fIsocketp\fP argument is a private pointer you have previously set with |
| 105 |
\fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no |
| 106 |
pointer has been set, socketp will be NULL. This argument is of course a |
| 107 |
service to applications that want to keep certain data or structs that are |
| 108 |
strictly associated to the given socket. |
| 109 |
|
| 110 |
The \fIuserp\fP argument is a private pointer you have previously set with |
| 111 |
\fIcurl_multi_setopt(3)\fP and the \fICURLMOPT_SOCKETDATA(3)\fP option. |
| 112 |
.SH "RETURN VALUE" |
| 113 |
CURLMcode type, general libcurl multi interface error code. |
| 114 |
|
| 115 |
Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means |
| 116 |
that you should call \fIcurl_multi_socket(3)\fP again, before you wait for |
| 117 |
more actions on libcurl's sockets. You don't have to do it immediately, but |
| 118 |
the return code means that libcurl may have more data available to return or |
| 119 |
that there may be more data to send off before it is "satisfied". |
| 120 |
|
| 121 |
In modern libcurls, \fICURLM_CALL_MULTI_PERFORM\fP or |
| 122 |
\fICURLM_CALL_MULTI_SOCKET\fP should not be returned and no application needs |
| 123 |
to care about them. |
| 124 |
|
| 125 |
NOTE that the return code is for the whole multi stack. Problems still might have |
| 126 |
occurred on individual transfers even when one of these functions |
| 127 |
return OK. |
| 128 |
.SH "TYPICAL USAGE" |
| 129 |
1. Create a multi handle |
| 130 |
|
| 131 |
2. Set the socket callback with \fICURLMOPT_SOCKETFUNCTION(3)\fP |
| 132 |
|
| 133 |
3. Set the timeout callback with \fICURLMOPT_TIMERFUNCTION(3)\fP, to get to |
| 134 |
know what timeout value to use when waiting for socket activities. |
| 135 |
|
| 136 |
4. Add easy handles with curl_multi_add_handle() |
| 137 |
|
| 138 |
5. Provide some means to manage the sockets libcurl is using, so you can check |
| 139 |
them for activity. This can be done through your application code, or by way |
| 140 |
of an external library such as libevent or glib. |
| 141 |
|
| 142 |
6. Wait for activity on any of libcurl's sockets, use the timeout value your |
| 143 |
callback has been told |
| 144 |
|
| 145 |
7, When activity is detected, call curl_multi_socket_action() for the |
| 146 |
socket(s) that got action. If no activity is detected and the timeout expires, |
| 147 |
call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP |
| 148 |
|
| 149 |
8. Go back to step 6. |
| 150 |
.SH AVAILABILITY |
| 151 |
This function was added in libcurl 7.15.4, and is deemed stable since |
| 152 |
7.16.0. |
| 153 |
|
| 154 |
\fIcurl_multi_socket(3)\fP is deprecated, use |
| 155 |
\fIcurl_multi_socket_action(3)\fP instead! |
| 156 |
.SH "SEE ALSO" |
| 157 |
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " |
| 158 |
.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), " |
| 159 |
.BR "the hiperfifo.c example" |