Mercurial

comparison third_party/libuv/docs/src/udp.rst @ 160:948de3f54cea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added libuv
author June Park <parkjune1995@gmail.com>
date Wed, 14 Jan 2026 19:39:52 -0800
parents
children
comparison
equal deleted inserted replaced
159:05cf9467a1c3 160:948de3f54cea
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.