Bertrand SIMONNET | e6cd738 | 2015-07-01 15:39:44 -0700 | [diff] [blame] | 1 | .\" ************************************************************************** |
| 2 | .\" * _ _ ____ _ |
| 3 | .\" * Project ___| | | | _ \| | |
| 4 | .\" * / __| | | | |_) | | |
| 5 | .\" * | (__| |_| | _ <| |___ |
| 6 | .\" * \___|\___/|_| \_\_____| |
| 7 | .\" * |
Alex Deymo | 8f1a214 | 2016-06-28 14:49:26 -0700 | [diff] [blame] | 8 | .\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. |
Bertrand SIMONNET | e6cd738 | 2015-07-01 15:39:44 -0700 | [diff] [blame] | 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 |
Alex Deymo | 8f1a214 | 2016-06-28 14:49:26 -0700 | [diff] [blame] | 12 | .\" * are also available at https://curl.haxx.se/docs/copyright.html. |
Bertrand SIMONNET | e6cd738 | 2015-07-01 15:39:44 -0700 | [diff] [blame] | 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 | .\" ************************************************************************** |
Elliott Hughes | cac3980 | 2018-04-27 16:19:43 -0700 | [diff] [blame] | 22 | .TH curl_multi_socket 3 "December 15, 2016" "libcurl 7.59.0" "libcurl Manual" |
Elliott Hughes | 82be86d | 2017-09-20 17:00:17 -0700 | [diff] [blame] | 23 | |
Lucas Eckels | 9bd90e6 | 2012-08-06 15:07:02 -0700 | [diff] [blame] | 24 | .SH NAME |
| 25 | curl_multi_socket \- reads/writes available data |
| 26 | .SH SYNOPSIS |
| 27 | .nf |
| 28 | #include <curl/curl.h> |
| 29 | CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd, |
| 30 | int *running_handles); |
| 31 | |
| 32 | CURLMcode curl_multi_socket_all(CURLM *multi_handle, |
| 33 | int *running_handles); |
| 34 | .fi |
| 35 | .SH DESCRIPTION |
| 36 | These functions are deprecated. Do not use! See |
| 37 | \fIcurl_multi_socket_action(3)\fP instead! |
| 38 | |
| 39 | At return, the integer \fBrunning_handles\fP points to will contain the number |
| 40 | of still running easy handles within the multi handle. When this number |
| 41 | reaches zero, all transfers are complete/done. Note that when you call |
| 42 | \fIcurl_multi_socket_action(3)\fP on a specific socket and the counter |
| 43 | decreases by one, it DOES NOT necessarily mean that this exact socket/transfer |
| 44 | is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out |
| 45 | which easy handle that completed. |
| 46 | |
Alex Deymo | 8f1a214 | 2016-06-28 14:49:26 -0700 | [diff] [blame] | 47 | The \fIcurl_multi_socket_action(3)\fP functions inform the application about |
Lucas Eckels | 9bd90e6 | 2012-08-06 15:07:02 -0700 | [diff] [blame] | 48 | updates in the socket (file descriptor) status by doing none, one, or multiple |
| 49 | calls to the socket callback function set with the CURLMOPT_SOCKETFUNCTION |
| 50 | option to \fIcurl_multi_setopt(3)\fP. They update the status with changes |
| 51 | since the previous time the callback was called. |
| 52 | |
| 53 | Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION\fP option with |
| 54 | \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 |
Alex Deymo | 8f1a214 | 2016-06-28 14:49:26 -0700 | [diff] [blame] | 56 | timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the |
Lucas Eckels | 9bd90e6 | 2012-08-06 15:07:02 -0700 | [diff] [blame] | 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 |
Alex Deymo | 8f1a214 | 2016-06-28 14:49:26 -0700 | [diff] [blame] | 67 | just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there |
Lucas Eckels | 9bd90e6 | 2012-08-06 15:07:02 -0700 | [diff] [blame] | 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 CURLMOPT_SOCKETDATA 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 |
Elliott Hughes | 82be86d | 2017-09-20 17:00:17 -0700 | [diff] [blame] | 122 | \fICURLM_CALL_MULTI_SOCKET\fP should not be returned and no application needs |
Lucas Eckels | 9bd90e6 | 2012-08-06 15:07:02 -0700 | [diff] [blame] | 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 CURLMOPT_SOCKETFUNCTION |
| 132 | |
| 133 | 3. Set the timeout callback with CURLMOPT_TIMERFUNCTION, to get to know what |
| 134 | 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" |