|
160
|
1
|
|
|
2 .. _udp:
|
|
|
3
|
|
|
4 :c:type:`uv_udp_t` --- UDP handle
|
|
|
5 =================================
|
|
|
6
|
|
|
7 UDP handles encapsulate UDP communication for both clients and servers.
|
|
|
8
|
|
|
9
|
|
|
10 Data types
|
|
|
11 ----------
|
|
|
12
|
|
|
13 .. c:type:: uv_udp_t
|
|
|
14
|
|
|
15 UDP handle type.
|
|
|
16
|
|
|
17 .. c:type:: uv_udp_send_t
|
|
|
18
|
|
|
19 UDP send request type.
|
|
|
20
|
|
|
21 .. c:enum:: uv_udp_flags
|
|
|
22
|
|
|
23 Flags used in :c:func:`uv_udp_bind` and :c:type:`uv_udp_recv_cb`..
|
|
|
24
|
|
|
25 ::
|
|
|
26
|
|
|
27 enum uv_udp_flags {
|
|
|
28 /* Disables dual stack mode. */
|
|
|
29 UV_UDP_IPV6ONLY = 1,
|
|
|
30 /*
|
|
|
31 * Indicates message was truncated because read buffer was too small. The
|
|
|
32 * remainder was discarded by the OS. Used in uv_udp_recv_cb.
|
|
|
33 */
|
|
|
34 UV_UDP_PARTIAL = 2,
|
|
|
35 /*
|
|
|
36 * Indicates if SO_REUSEADDR will be set when binding the handle.
|
|
|
37 * This sets the SO_REUSEPORT socket flag on the BSDs (except for
|
|
|
38 * DragonFlyBSD), OS X, and other platforms where SO_REUSEPORTs don't
|
|
|
39 * have the capability of load balancing, as the opposite of what
|
|
|
40 * UV_UDP_REUSEPORT would do. On other Unix platforms, it sets the
|
|
|
41 * SO_REUSEADDR flag. What that means is that multiple threads or
|
|
|
42 * processes can bind to the same address without error (provided
|
|
|
43 * they all set the flag) but only the last one to bind will receive
|
|
|
44 * any traffic, in effect "stealing" the port from the previous listener.
|
|
|
45 */
|
|
|
46 UV_UDP_REUSEADDR = 4,
|
|
|
47 /*
|
|
|
48 * Indicates that the message was received by recvmmsg, so the buffer provided
|
|
|
49 * must not be freed by the recv_cb callback.
|
|
|
50 */
|
|
|
51 UV_UDP_MMSG_CHUNK = 8,
|
|
|
52 /*
|
|
|
53 * Indicates that the buffer provided has been fully utilized by recvmmsg and
|
|
|
54 * that it should now be freed by the recv_cb callback. When this flag is set
|
|
|
55 * in uv_udp_recv_cb, nread will always be 0 and addr will always be NULL.
|
|
|
56 */
|
|
|
57 UV_UDP_MMSG_FREE = 16,
|
|
|
58 /*
|
|
|
59 * Indicates if IP_RECVERR/IPV6_RECVERR will be set when binding the handle.
|
|
|
60 * This sets IP_RECVERR for IPv4 and IPV6_RECVERR for IPv6 UDP sockets on
|
|
|
61 * Linux. This stops the Linux kernel from suppressing some ICMP error messages
|
|
|
62 * and enables full ICMP error reporting for faster failover.
|
|
|
63 * This flag is no-op on platforms other than Linux.
|
|
|
64 */
|
|
|
65 UV_UDP_LINUX_RECVERR = 32,
|
|
|
66 /*
|
|
|
67 * Indicates if SO_REUSEPORT will be set when binding the handle.
|
|
|
68 * This sets the SO_REUSEPORT socket option on supported platforms.
|
|
|
69 * Unlike UV_UDP_REUSEADDR, this flag will make multiple threads or
|
|
|
70 * processes that are binding to the same address and port "share"
|
|
|
71 * the port, which means incoming datagrams are distributed across
|
|
|
72 * the receiving sockets among threads or processes.
|
|
|
73 *
|
|
|
74 * This flag is available only on Linux 3.9+, DragonFlyBSD 3.6+,
|
|
|
75 * FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ for now.
|
|
|
76 */
|
|
|
77 UV_UDP_REUSEPORT = 64,
|
|
|
78 /*
|
|
|
79 * Indicates that recvmmsg should be used, if available.
|
|
|
80 */
|
|
|
81 UV_UDP_RECVMMSG = 256
|
|
|
82 };
|
|
|
83
|
|
|
84 .. c:type:: void (*uv_udp_send_cb)(uv_udp_send_t* req, int status)
|
|
|
85
|
|
|
86 Type definition for callback passed to :c:func:`uv_udp_send`, which is
|
|
|
87 called after the data was sent.
|
|
|
88
|
|
|
89 .. c:type:: void (*uv_udp_recv_cb)(uv_udp_t* handle, ssize_t nread, const uv_buf_t* buf, const struct sockaddr* addr, unsigned flags)
|
|
|
90
|
|
|
91 Type definition for callback passed to :c:func:`uv_udp_recv_start`, which
|
|
|
92 is called when the endpoint receives data.
|
|
|
93
|
|
|
94 * `handle`: UDP handle
|
|
|
95 * `nread`: Number of bytes that have been received.
|
|
|
96 0 if there is no more data to read. Note that 0 may also mean that an
|
|
|
97 empty datagram was received (in this case `addr` is not NULL). < 0 if
|
|
|
98 a transmission error was detected; if using :man:`recvmmsg(2)` no more
|
|
|
99 chunks will be received and the buffer can be freed safely.
|
|
|
100 * `buf`: :c:type:`uv_buf_t` with the received data.
|
|
|
101 * `addr`: ``struct sockaddr*`` containing the address of the sender.
|
|
|
102 Can be NULL. Valid for the duration of the callback only.
|
|
|
103 * `flags`: One or more or'ed UV_UDP_* constants.
|
|
|
104
|
|
|
105 The callee is responsible for freeing the buffer, libuv does not reuse it.
|
|
|
106 The buffer may be a null buffer (where `buf->base` == NULL and `buf->len` == 0)
|
|
|
107 on error.
|
|
|
108
|
|
|
109 When using :man:`recvmmsg(2)`, chunks will have the `UV_UDP_MMSG_CHUNK` flag set,
|
|
|
110 those must not be freed. If no errors occur, there will be a final callback with
|
|
|
111 `nread` set to 0, `addr` set to NULL and the buffer pointing at the initially
|
|
|
112 allocated data with the `UV_UDP_MMSG_CHUNK` flag cleared and the `UV_UDP_MMSG_FREE`
|
|
|
113 flag set. If a UDP socket error occurs, `nread` will be < 0. In either scenario,
|
|
|
114 the callee can now safely free the provided buffer.
|
|
|
115
|
|
|
116 .. versionchanged:: 1.40.0 added the `UV_UDP_MMSG_FREE` flag.
|
|
|
117
|
|
|
118 .. note::
|
|
|
119 The receive callback will be called with `nread` == 0 and `addr` == NULL when there is
|
|
|
120 nothing to read, and with `nread` == 0 and `addr` != NULL when an empty UDP packet is
|
|
|
121 received.
|
|
|
122
|
|
|
123 .. c:enum:: uv_membership
|
|
|
124
|
|
|
125 Membership type for a multicast address.
|
|
|
126
|
|
|
127 ::
|
|
|
128
|
|
|
129 typedef enum {
|
|
|
130 UV_LEAVE_GROUP = 0,
|
|
|
131 UV_JOIN_GROUP
|
|
|
132 } uv_membership;
|
|
|
133
|
|
|
134
|
|
|
135 Public members
|
|
|
136 ^^^^^^^^^^^^^^
|
|
|
137
|
|
|
138 .. c:member:: size_t uv_udp_t.send_queue_size
|
|
|
139
|
|
|
140 Number of bytes queued for sending. This field strictly shows how much
|
|
|
141 information is currently queued.
|
|
|
142
|
|
|
143 .. c:member:: size_t uv_udp_t.send_queue_count
|
|
|
144
|
|
|
145 Number of send requests currently in the queue awaiting to be processed.
|
|
|
146
|
|
|
147 .. c:member:: uv_udp_t* uv_udp_send_t.handle
|
|
|
148
|
|
|
149 UDP handle where this send request is taking place.
|
|
|
150
|
|
|
151 .. seealso:: The :c:type:`uv_handle_t` members also apply.
|
|
|
152
|
|
|
153
|
|
|
154 API
|
|
|
155 ---
|
|
|
156
|
|
|
157 .. c:function:: int uv_udp_init(uv_loop_t* loop, uv_udp_t* handle)
|
|
|
158
|
|
|
159 Initialize a new UDP handle. The actual socket is created lazily.
|
|
|
160 Returns 0 on success.
|
|
|
161
|
|
|
162 .. c:function:: int uv_udp_init_ex(uv_loop_t* loop, uv_udp_t* handle, unsigned int flags)
|
|
|
163
|
|
|
164 Initialize the handle with the specified flags. The lower 8 bits of the `flags`
|
|
|
165 parameter are used as the socket domain. A socket will be created for the given domain.
|
|
|
166 If the specified domain is ``AF_UNSPEC`` no socket is created, just like :c:func:`uv_udp_init`.
|
|
|
167
|
|
|
168 The remaining bits can be used to set one of these flags:
|
|
|
169
|
|
|
170 * `UV_UDP_RECVMMSG`: if set, and the platform supports it, :man:`recvmmsg(2)` will
|
|
|
171 be used.
|
|
|
172
|
|
|
173 .. versionadded:: 1.7.0
|
|
|
174 .. versionchanged:: 1.37.0 added the `UV_UDP_RECVMMSG` flag.
|
|
|
175
|
|
|
176 .. c:function:: int uv_udp_open(uv_udp_t* handle, uv_os_sock_t sock)
|
|
|
177
|
|
|
178 Opens an existing file descriptor or Windows SOCKET as a UDP handle.
|
|
|
179
|
|
|
180 Unix only:
|
|
|
181 The only requirement of the `sock` argument is that it follows the datagram
|
|
|
182 contract (works in unconnected mode, supports sendmsg()/recvmsg(), etc).
|
|
|
183 In other words, other datagram-type sockets like raw sockets or netlink
|
|
|
184 sockets can also be passed to this function.
|
|
|
185
|
|
|
186 .. versionchanged:: 1.2.1 the file descriptor is set to non-blocking mode.
|
|
|
187
|
|
|
188 .. note::
|
|
|
189 The passed file descriptor or SOCKET is not checked for its type, but
|
|
|
190 it's required that it represents a valid datagram socket.
|
|
|
191
|
|
|
192 .. c:function:: int uv_udp_bind(uv_udp_t* handle, const struct sockaddr* addr, unsigned int flags)
|
|
|
193
|
|
|
194 Bind the UDP handle to an IP address and port.
|
|
|
195
|
|
|
196 :param handle: UDP handle. Should have been initialized with
|
|
|
197 :c:func:`uv_udp_init`.
|
|
|
198
|
|
|
199 :param addr: `struct sockaddr_in` or `struct sockaddr_in6`
|
|
|
200 with the address and port to bind to.
|
|
|
201
|
|
|
202 :param flags: Indicate how the socket will be bound,
|
|
|
203 ``UV_UDP_IPV6ONLY``, ``UV_UDP_REUSEADDR``, ``UV_UDP_REUSEPORT``,
|
|
|
204 and ``UV_UDP_RECVERR`` are supported.
|
|
|
205
|
|
|
206 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
207
|
|
|
208 .. versionchanged:: 1.49.0 added the ``UV_UDP_REUSEPORT`` flag.
|
|
|
209
|
|
|
210 .. note::
|
|
|
211 ``UV_UDP_REUSEPORT`` flag is available only on Linux 3.9+, DragonFlyBSD 3.6+,
|
|
|
212 FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ at the moment. On other platforms
|
|
|
213 this function will return an UV_ENOTSUP error.
|
|
|
214 For platforms where `SO_REUSEPORT`s have the capability of load balancing,
|
|
|
215 specifying both ``UV_UDP_REUSEADDR`` and ``UV_UDP_REUSEPORT`` in flags is allowed
|
|
|
216 and `SO_REUSEPORT` will always override the behavior of `SO_REUSEADDR`.
|
|
|
217 For platforms where `SO_REUSEPORT`s don't have the capability of load balancing,
|
|
|
218 specifying both ``UV_UDP_REUSEADDR`` and ``UV_UDP_REUSEPORT`` in flags will fail,
|
|
|
219 returning an UV_ENOTSUP error.
|
|
|
220
|
|
|
221 .. c:function:: int uv_udp_connect(uv_udp_t* handle, const struct sockaddr* addr)
|
|
|
222
|
|
|
223 Associate the UDP handle to a remote address and port, so every
|
|
|
224 message sent by this handle is automatically sent to that destination.
|
|
|
225 Calling this function with a `NULL` `addr` disconnects the handle.
|
|
|
226 Trying to call `uv_udp_connect()` on an already connected handle will result
|
|
|
227 in an `UV_EISCONN` error. Trying to disconnect a handle that is not
|
|
|
228 connected will return an `UV_ENOTCONN` error.
|
|
|
229
|
|
|
230 :param handle: UDP handle. Should have been initialized with
|
|
|
231 :c:func:`uv_udp_init`.
|
|
|
232
|
|
|
233 :param addr: `struct sockaddr_in` or `struct sockaddr_in6`
|
|
|
234 with the address and port to associate to.
|
|
|
235
|
|
|
236 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
237
|
|
|
238 .. versionadded:: 1.27.0
|
|
|
239
|
|
|
240 .. c:function:: int uv_udp_getpeername(const uv_udp_t* handle, struct sockaddr* name, int* namelen)
|
|
|
241
|
|
|
242 Get the remote IP and port of the UDP handle on connected UDP handles.
|
|
|
243 On unconnected handles, it returns `UV_ENOTCONN`.
|
|
|
244
|
|
|
245 :param handle: UDP handle. Should have been initialized with
|
|
|
246 :c:func:`uv_udp_init` and bound.
|
|
|
247
|
|
|
248 :param name: Pointer to the structure to be filled with the address data.
|
|
|
249 In order to support IPv4 and IPv6 `struct sockaddr_storage` should be
|
|
|
250 used.
|
|
|
251
|
|
|
252 :param namelen: On input it indicates the data of the `name` field. On
|
|
|
253 output it indicates how much of it was filled.
|
|
|
254
|
|
|
255 :returns: 0 on success, or an error code < 0 on failure
|
|
|
256
|
|
|
257 .. versionadded:: 1.27.0
|
|
|
258
|
|
|
259 .. c:function:: int uv_udp_getsockname(const uv_udp_t* handle, struct sockaddr* name, int* namelen)
|
|
|
260
|
|
|
261 Get the local IP and port of the UDP handle.
|
|
|
262
|
|
|
263 :param handle: UDP handle. Should have been initialized with
|
|
|
264 :c:func:`uv_udp_init` and bound.
|
|
|
265
|
|
|
266 :param name: Pointer to the structure to be filled with the address data.
|
|
|
267 In order to support IPv4 and IPv6 `struct sockaddr_storage` should be
|
|
|
268 used.
|
|
|
269
|
|
|
270 :param namelen: On input it indicates the data of the `name` field. On
|
|
|
271 output it indicates how much of it was filled.
|
|
|
272
|
|
|
273 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
274
|
|
|
275 .. c:function:: int uv_udp_set_membership(uv_udp_t* handle, const char* multicast_addr, const char* interface_addr, uv_membership membership)
|
|
|
276
|
|
|
277 Set membership for a multicast address
|
|
|
278
|
|
|
279 :param handle: UDP handle. Should have been initialized with
|
|
|
280 :c:func:`uv_udp_init`.
|
|
|
281
|
|
|
282 :param multicast_addr: Multicast address to set membership for.
|
|
|
283
|
|
|
284 :param interface_addr: Interface address.
|
|
|
285
|
|
|
286 :param membership: Should be ``UV_JOIN_GROUP`` or ``UV_LEAVE_GROUP``.
|
|
|
287
|
|
|
288 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
289
|
|
|
290 .. c:function:: int uv_udp_set_source_membership(uv_udp_t* handle, const char* multicast_addr, const char* interface_addr, const char* source_addr, uv_membership membership)
|
|
|
291
|
|
|
292 Set membership for a source-specific multicast group.
|
|
|
293
|
|
|
294 :param handle: UDP handle. Should have been initialized with
|
|
|
295 :c:func:`uv_udp_init`.
|
|
|
296
|
|
|
297 :param multicast_addr: Multicast address to set membership for.
|
|
|
298
|
|
|
299 :param interface_addr: Interface address.
|
|
|
300
|
|
|
301 :param source_addr: Source address.
|
|
|
302
|
|
|
303 :param membership: Should be ``UV_JOIN_GROUP`` or ``UV_LEAVE_GROUP``.
|
|
|
304
|
|
|
305 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
306
|
|
|
307 .. versionadded:: 1.32.0
|
|
|
308
|
|
|
309 .. c:function:: int uv_udp_set_multicast_loop(uv_udp_t* handle, int on)
|
|
|
310
|
|
|
311 Set IP multicast loop flag. Makes multicast packets loop back to
|
|
|
312 local sockets.
|
|
|
313
|
|
|
314 :param handle: UDP handle. Should have been initialized with
|
|
|
315 :c:func:`uv_udp_init_ex` as either ``AF_INET`` or ``AF_INET6``, or have
|
|
|
316 been bound to an address explicitly with :c:func:`uv_udp_bind`, or
|
|
|
317 implicitly with :c:func:`uv_udp_send()` or :c:func:`uv_udp_recv_start`.
|
|
|
318
|
|
|
319 :param on: 1 for on, 0 for off.
|
|
|
320
|
|
|
321 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
322
|
|
|
323 .. c:function:: int uv_udp_set_multicast_ttl(uv_udp_t* handle, int ttl)
|
|
|
324
|
|
|
325 Set the multicast ttl.
|
|
|
326
|
|
|
327 :param handle: UDP handle. Should have been initialized with
|
|
|
328 :c:func:`uv_udp_init_ex` as either ``AF_INET`` or ``AF_INET6``, or have
|
|
|
329 been bound to an address explicitly with :c:func:`uv_udp_bind`, or
|
|
|
330 implicitly with :c:func:`uv_udp_send()` or :c:func:`uv_udp_recv_start`.
|
|
|
331
|
|
|
332 :param ttl: 1 through 255.
|
|
|
333
|
|
|
334 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
335
|
|
|
336 .. c:function:: int uv_udp_set_multicast_interface(uv_udp_t* handle, const char* interface_addr)
|
|
|
337
|
|
|
338 Set the multicast interface to send or receive data on.
|
|
|
339
|
|
|
340 :param handle: UDP handle. Should have been initialized with
|
|
|
341 :c:func:`uv_udp_init_ex` as either ``AF_INET`` or ``AF_INET6``, or have
|
|
|
342 been bound to an address explicitly with :c:func:`uv_udp_bind`, or
|
|
|
343 implicitly with :c:func:`uv_udp_send()` or :c:func:`uv_udp_recv_start`.
|
|
|
344
|
|
|
345 :param interface_addr: interface address.
|
|
|
346
|
|
|
347 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
348
|
|
|
349 .. c:function:: int uv_udp_set_broadcast(uv_udp_t* handle, int on)
|
|
|
350
|
|
|
351 Set broadcast on or off.
|
|
|
352
|
|
|
353 :param handle: UDP handle. Should have been initialized with
|
|
|
354 :c:func:`uv_udp_init_ex` as either ``AF_INET`` or ``AF_INET6``, or have
|
|
|
355 been bound to an address explicitly with :c:func:`uv_udp_bind`, or
|
|
|
356 implicitly with :c:func:`uv_udp_send()` or :c:func:`uv_udp_recv_start`.
|
|
|
357
|
|
|
358 :param on: 1 for on, 0 for off.
|
|
|
359
|
|
|
360 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
361
|
|
|
362 .. c:function:: int uv_udp_set_ttl(uv_udp_t* handle, int ttl)
|
|
|
363
|
|
|
364 Set the time to live.
|
|
|
365
|
|
|
366 :param handle: UDP handle. Should have been initialized with
|
|
|
367 :c:func:`uv_udp_init_ex` as either ``AF_INET`` or ``AF_INET6``, or have
|
|
|
368 been bound to an address explicitly with :c:func:`uv_udp_bind`, or
|
|
|
369 implicitly with :c:func:`uv_udp_send()` or :c:func:`uv_udp_recv_start`.
|
|
|
370
|
|
|
371 :param ttl: 1 through 255.
|
|
|
372
|
|
|
373 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
374
|
|
|
375 .. c:function:: int uv_udp_send(uv_udp_send_t* req, uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr, uv_udp_send_cb send_cb)
|
|
|
376
|
|
|
377 Send data over the UDP socket. If the socket has not previously been bound
|
|
|
378 with :c:func:`uv_udp_bind` it will be bound to 0.0.0.0
|
|
|
379 (the "all interfaces" IPv4 address) and a random port number.
|
|
|
380
|
|
|
381 On Windows if the `addr` is initialized to point to an unspecified address
|
|
|
382 (``0.0.0.0`` or ``::``) it will be changed to point to ``localhost``.
|
|
|
383 This is done to match the behavior of Linux systems.
|
|
|
384
|
|
|
385 For connected UDP handles, `addr` must be set to `NULL`, otherwise it will
|
|
|
386 return `UV_EISCONN` error.
|
|
|
387
|
|
|
388 For connectionless UDP handles, `addr` cannot be `NULL`, otherwise it will
|
|
|
389 return `UV_EDESTADDRREQ` error.
|
|
|
390
|
|
|
391 :param req: UDP request handle. Need not be initialized.
|
|
|
392
|
|
|
393 :param handle: UDP handle. Should have been initialized with
|
|
|
394 :c:func:`uv_udp_init`.
|
|
|
395
|
|
|
396 :param bufs: List of buffers to send.
|
|
|
397
|
|
|
398 :param nbufs: Number of buffers in `bufs`.
|
|
|
399
|
|
|
400 :param addr: `struct sockaddr_in` or `struct sockaddr_in6` with the
|
|
|
401 address and port of the remote peer.
|
|
|
402
|
|
|
403 :param send_cb: Callback to invoke when the data has been sent out.
|
|
|
404
|
|
|
405 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
406
|
|
|
407 .. versionchanged:: 1.19.0 added ``0.0.0.0`` and ``::`` to ``localhost``
|
|
|
408 mapping
|
|
|
409
|
|
|
410 .. versionchanged:: 1.27.0 added support for connected sockets
|
|
|
411
|
|
|
412 .. c:function:: int uv_udp_try_send(uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr)
|
|
|
413
|
|
|
414 Same as :c:func:`uv_udp_send`, but won't queue a send request if it can't
|
|
|
415 be completed immediately.
|
|
|
416
|
|
|
417 For connected UDP handles, `addr` must be set to `NULL`, otherwise it will
|
|
|
418 return `UV_EISCONN` error.
|
|
|
419
|
|
|
420 For connectionless UDP handles, `addr` cannot be `NULL`, otherwise it will
|
|
|
421 return `UV_EDESTADDRREQ` error.
|
|
|
422
|
|
|
423 :returns: >= 0: number of bytes sent (it matches the given buffer size).
|
|
|
424 < 0: negative error code (``UV_EAGAIN`` is returned when the message
|
|
|
425 can't be sent immediately).
|
|
|
426
|
|
|
427 .. versionchanged:: 1.27.0 added support for connected sockets
|
|
|
428
|
|
|
429 .. c:function:: int uv_udp_try_send2(uv_udp_t* handle, unsigned int count, uv_buf_t* bufs[/*count*/], unsigned int nbufs[/*count*/], struct sockaddr* addrs[/*count*/], unsigned int flags)
|
|
|
430
|
|
|
431 Like :c:func:`uv_udp_try_send`, but can send multiple datagrams.
|
|
|
432 Lightweight abstraction around :man:`sendmmsg(2)`, with a :man:`sendmsg(2)`
|
|
|
433 fallback loop for platforms that do not support the former. The handle must
|
|
|
434 be fully initialized; call c:func:`uv_udp_bind` first.
|
|
|
435
|
|
|
436 :returns: >= 0: number of datagrams sent. Zero only if `count` was zero.
|
|
|
437 < 0: negative error code. Only if sending the first datagram fails,
|
|
|
438 otherwise returns a positive send count. ``UV_EAGAIN`` when datagrams
|
|
|
439 cannot be sent right now; fall back to :c:func:`uv_udp_send`.
|
|
|
440
|
|
|
441 .. versionadded:: 1.50.0
|
|
|
442
|
|
|
443 .. c:function:: int uv_udp_recv_start(uv_udp_t* handle, uv_alloc_cb alloc_cb, uv_udp_recv_cb recv_cb)
|
|
|
444
|
|
|
445 Prepare for receiving data. If the socket has not previously been bound
|
|
|
446 with :c:func:`uv_udp_bind` it is bound to 0.0.0.0 (the "all interfaces"
|
|
|
447 IPv4 address) and a random port number.
|
|
|
448
|
|
|
449 :param handle: UDP handle. Should have been initialized with
|
|
|
450 :c:func:`uv_udp_init`.
|
|
|
451
|
|
|
452 :param alloc_cb: Callback to invoke when temporary storage is needed.
|
|
|
453
|
|
|
454 :param recv_cb: Callback to invoke with received data.
|
|
|
455
|
|
|
456 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
457
|
|
|
458 .. note::
|
|
|
459 When using :man:`recvmmsg(2)`, the number of messages received at a time is limited
|
|
|
460 by the number of max size dgrams that will fit into the buffer allocated in `alloc_cb`, and
|
|
|
461 `suggested_size` in `alloc_cb` for udp_recv is always set to the size of 1 max size dgram.
|
|
|
462
|
|
|
463 .. versionchanged:: 1.35.0 added support for :man:`recvmmsg(2)` on supported platforms).
|
|
|
464 The use of this feature requires a buffer larger than
|
|
|
465 2 * 64KB to be passed to `alloc_cb`.
|
|
|
466 .. versionchanged:: 1.37.0 :man:`recvmmsg(2)` support is no longer enabled implicitly,
|
|
|
467 it must be explicitly requested by passing the `UV_UDP_RECVMMSG` flag to
|
|
|
468 :c:func:`uv_udp_init_ex`.
|
|
|
469 .. versionchanged:: 1.39.0 :c:func:`uv_udp_using_recvmmsg` can be used in `alloc_cb` to
|
|
|
470 determine if a buffer sized for use with :man:`recvmmsg(2)` should be
|
|
|
471 allocated for the current handle/platform.
|
|
|
472
|
|
|
473 .. c:function:: int uv_udp_using_recvmmsg(uv_udp_t* handle)
|
|
|
474
|
|
|
475 Returns 1 if the UDP handle was created with the `UV_UDP_RECVMMSG` flag
|
|
|
476 and the platform supports :man:`recvmmsg(2)`, 0 otherwise.
|
|
|
477
|
|
|
478 .. versionadded:: 1.39.0
|
|
|
479
|
|
|
480 .. c:function:: int uv_udp_recv_stop(uv_udp_t* handle)
|
|
|
481
|
|
|
482 Stop listening for incoming datagrams.
|
|
|
483
|
|
|
484 :param handle: UDP handle. Should have been initialized with
|
|
|
485 :c:func:`uv_udp_init`.
|
|
|
486
|
|
|
487 :returns: 0 on success, or an error code < 0 on failure.
|
|
|
488
|
|
|
489 .. c:function:: size_t uv_udp_get_send_queue_size(const uv_udp_t* handle)
|
|
|
490
|
|
|
491 Returns `handle->send_queue_size`.
|
|
|
492
|
|
|
493 .. versionadded:: 1.19.0
|
|
|
494
|
|
|
495 .. c:function:: size_t uv_udp_get_send_queue_count(const uv_udp_t* handle)
|
|
|
496
|
|
|
497 Returns `handle->send_queue_count`.
|
|
|
498
|
|
|
499 .. versionadded:: 1.19.0
|
|
|
500
|
|
|
501 .. seealso:: The :c:type:`uv_handle_t` API functions also apply.
|
