1 2.. _udp: 3 4:c:type:`uv_udp_t` --- UDP handle 5================================= 6 7UDP handles encapsulate UDP communication for both clients and servers. 8 9 10Data 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 135Public 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 154API 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. 502
