1curl_multi_socket(3) libcurl Manual curl_multi_socket(3)
2
6 curl_multi_socket - reads/writes available data
7
9 #include <curl/curl.h>
10 CURLMcode curl_multi_socket_action(CURLM * multi_handle,
12 curl_socket_t sockfd, int ev_bitmask,
13 int *running_handles);
14 CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd,
16 int *running_handles);
17 CURLMcode curl_multi_socket_all(CURLM *multi_handle,
19 int *running_handles);
20
22 Alternative versions of curl_multi_perform(3) that allows the applica‐
23 tion to pass in the file descriptor/socket that has been detected to
24 have "action" on it and let libcurl perform. This allows libcurl to not
25 have to scan through all possible file descriptors to check for action.
26 When the application has detected action on a socket handled by
27 libcurl, it should call curl_multi_socket_action(3) with the sockfd
28 argument set to the socket with the action. When the events on a socket
29 are known, they can be passed as an events bitmask ev_bitmask by first
30 setting ev_bitmask to 0, and then adding using bitwise OR (|) any com‐
31 bination of events to be choosen from CURL_CSELECT_IN, CURL_CSELECT_OUT
32 or CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0
33 instead, and libcurl will test the descriptor internally.
34 At return, the int running_handles points to will contain the number of
36 still running easy handles within the multi handle. When this number
37 reaches zero, all transfers are complete/done. Note that when you call
38 curl_multi_socket_action(3) on a specific socket and the counter
39 decreases by one, it DOES NOT necessarily mean that this exact
40 socket/transfer is the one that completed. Use curl_multi_info_read(3)
41 to figure out which easy handle that completed.
42 The curl_multi_socket functions inform the application about updates in
44 the socket (file descriptor) status by doing none, one or multiple
45 calls to the socket callback function set with the CURLMOPT_SOCKETFUNC‐
46 TION option to curl_multi_setopt(3). They update the status with
47 changes since the previous time this function was called.
48 To force libcurl to (re-)check all its internal sockets and transfers
50 instead of just a single one, you call curl_multi_socket_all(3). This
51 is typically done as the first function call before the application has
52 any knowledge about what sockets libcurl uses.
53 Applications should call curl_multi_timeout(3) to figure out how long
55 to wait for socket actions - at most - before doing the timeout action:
56 call the curl_multi_socket(3) function with the sockfd argument set to
57 CURL_SOCKET_TIMEOUT.
58 Usage of curl_multi_socket(3) is depricated, whereas the function is
60 equivalent to curl_multi_socket_action(3), when ev_bitmask is set to 0.
61
64 The socket callback function uses a prototype like this
65 int curl_socket_callback(CURL *easy, /* easy handle */
67 curl_socket_t s, /* socket */
68 int action, /* see values below */
69 void *userp, /* private callback pointer */
70 void *socketp); /* private socket pointer */
71 The callback MUST return 0.
73 The easy argument is a pointer to the easy handle that deals with this
75 particular socket. Note that a single handle may work with several
76 sockets simultaneously.
77 The s argument is the actual socket value as you use it within your
79 system.
80 The action argument to the callback has one of five values:
82 CURL_POLL_NONE (0)
84 register, not interested in readiness (yet)
85 CURL_POLL_IN (1)
87 register, interested in read readiness
88 CURL_POLL_OUT (2)
90 register, interested in write readiness
91 CURL_POLL_INOUT (3)
93 register, interested in both read and write readiness
94 CURL_POLL_REMOVE (4)
96 deregister
97 The socketp argument is a private pointer you have previously set with
99 curl_multi_assign(3) to be associated with the s socket. If no pointer
100 has been set, socketp will be NULL. This argument is of course a ser‐
101 vice to applications that want to keep certain data or structs that are
102 strictly associated to the given socket.
103 The userp argument is a private pointer you have previously set with
105 curl_multi_setopt(3) and the CURLMOPT_SOCKETDATA option.
106
108 CURLMcode type, general libcurl multi interface error code.
109 If you receive CURLM_CALL_MULTI_PERFORM, this basically means that you
111 should call curl_multi_perform again, before you wait for more actions
112 on libcurl's sockets. You don't have to do it immediately, but the
113 return code means that libcurl may have more data available to return
114 or that there may be more data to send off before it is "satisfied".
115 NOTE that this only returns errors etc regarding the whole multi stack.
117 There might still have occurred problems on individual transfers even
118 when this function returns OK.
119
121 1. Create a multi handle
122 2. Set the socket callback with CURLMOPT_SOCKETFUNCTION
124 3. Add easy handles
126 4. Call curl_multi_socket_all() first once
128 5. Setup a "collection" of sockets to supervise when your socket call‐
130 back is called.
131 6. Use curl_multi_timeout() to figure out how long to wait for action
133 7. Wait for action on any of libcurl's sockets
135 8, When action happens, call curl_multi_socket_action() for the
137 socket(s) that got action.
138 9. Go back to step 6.
140
142 This function was added in libcurl 7.15.4, although deemed stablesince
143 7.16.0.
144 curl_multi_socket(3) is deprecated, use curl_multi_socket_action(3)
146 instead!
147
149 curl_multi_cleanup(3), curl_multi_init(3), curl_multi_fdset(3),
150 curl_multi_info_read(3)
151libcurl 7.16.0 9 Jul 2006 curl_multi_socket(3)