`uv_udp_t` — UDP handle#

UDP handles encapsulate UDP communication for both clients and servers.

Data types#

type uv_udp_t#: UDP handle type.

type uv_udp_send_t#: UDP send request type.

type uv_udp_flags#

Flags used in uv_udp_bind() and uv_udp_recv_cb..

enum uv_udp_flags {
    /* Disables dual stack mode. */
    UV_UDP_IPV6ONLY = 1,
    /*
    * Indicates message was truncated because read buffer was too small. The
    * remainder was discarded by the OS. Used in uv_udp_recv_cb.
    */
    UV_UDP_PARTIAL = 2,
    /*
    * Indicates if SO_REUSEADDR will be set when binding the handle in
    * uv_udp_bind.
    * This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other
    * Unix platforms, it sets the SO_REUSEADDR flag. What that means is that
    * multiple threads or processes can bind to the same address without error
    * (provided they all set the flag) but only the last one to bind will receive
    * any traffic, in effect "stealing" the port from the previous listener.
    */
    UV_UDP_REUSEADDR = 4,
    /*
     * Indicates that the message was received by recvmmsg, so the buffer provided
     * must not be freed by the recv_cb callback.
     */
    UV_UDP_MMSG_CHUNK = 8,
    /*
     * Indicates that the buffer provided has been fully utilized by recvmmsg and
     * that it should now be freed by the recv_cb callback. When this flag is set
     * in uv_udp_recv_cb, nread will always be 0 and addr will always be NULL.
     */
    UV_UDP_MMSG_FREE = 16,
    /*
     * Indicates if IP_RECVERR/IPV6_RECVERR will be set when binding the handle.
     * This sets IP_RECVERR for IPv4 and IPV6_RECVERR for IPv6 UDP sockets on
     * Linux. This stops the Linux kernel from suppressing some ICMP error messages
     * and enables full ICMP error reporting for faster failover.
     * This flag is no-op on platforms other than Linux.
     */
    UV_UDP_LINUX_RECVERR = 32,
    /*
    * Indicates that recvmmsg should be used, if available.
    */
    UV_UDP_RECVMMSG = 256
};

typedef void (*uv_udp_send_cb)(uv_udp_send_t *req, int status)#: Type definition for callback passed to uv_udp_send(), which is called after the data was sent.

typedef void (*uv_udp_recv_cb)(uv_udp_t *handle, ssize_t nread, const uv_buf_t *buf, const struct sockaddr *addr, unsigned flags)#

Type definition for callback passed to uv_udp_recv_start(), which is called when the endpoint receives data.

handle: UDP handle
nread: Number of bytes that have been received. 0 if there is no more data to read. Note that 0 may also mean that an empty datagram was received (in this case addr is not NULL). < 0 if a transmission error was detected; if using recvmmsg(2) no more chunks will be received and the buffer can be freed safely.
buf: uv_buf_t with the received data.
addr: struct sockaddr* containing the address of the sender. Can be NULL. Valid for the duration of the callback only.
flags: One or more or’ed UV_UDP_* constants.

The callee is responsible for freeing the buffer, libuv does not reuse it. The buffer may be a null buffer (where buf->base == NULL and buf->len == 0) on error.

When using recvmmsg(2), chunks will have the UV_UDP_MMSG_CHUNK flag set, those must not be freed. If no errors occur, there will be a final callback with nread set to 0, addr set to NULL and the buffer pointing at the initially allocated data with the UV_UDP_MMSG_CHUNK flag cleared and the UV_UDP_MMSG_FREE flag set. If a UDP socket error occurs, nread will be < 0. In either scenario, the callee can now safely free the provided buffer.

Changed in version 1.40.0: added the UV_UDP_MMSG_FREE flag.

Note

The receive callback will be called with nread == 0 and addr == NULL when there is nothing to read, and with nread == 0 and addr != NULL when an empty UDP packet is received.

enum uv_membership#

Membership type for a multicast address.

typedef enum {
    UV_LEAVE_GROUP = 0,
    UV_JOIN_GROUP
} uv_membership;

Public members#

size_t uv_udp_t.send_queue_size#: Number of bytes queued for sending. This field strictly shows how much information is currently queued.

size_t uv_udp_t.send_queue_count#: Number of send requests currently in the queue awaiting to be processed.

uv_udp_t *uv_udp_send_t.handle#: UDP handle where this send request is taking place.

API#

int uv_udp_init(uv_loop_t *loop, uv_udp_t *handle)#: Initialize a new UDP handle. The actual socket is created lazily. Returns 0 on success.

int uv_udp_init_ex(uv_loop_t *loop, uv_udp_t *handle, unsigned int flags)#

Initialize the handle with the specified flags. The lower 8 bits of the flags parameter are used as the socket domain. A socket will be created for the given domain. If the specified domain is AF_UNSPEC no socket is created, just like uv_udp_init().

The remaining bits can be used to set one of these flags:

UV_UDP_RECVMMSG: if set, and the platform supports it, recvmmsg(2) will be used.

New in version 1.7.0.

Changed in version 1.37.0: added the UV_UDP_RECVMMSG flag.

int uv_udp_open(uv_udp_t *handle, uv_os_sock_t sock)#

Opens an existing file descriptor or Windows SOCKET as a UDP handle.

Unix only: The only requirement of the sock argument is that it follows the datagram contract (works in unconnected mode, supports sendmsg()/recvmsg(), etc). In other words, other datagram-type sockets like raw sockets or netlink sockets can also be passed to this function.

Changed in version 1.2.1: the file descriptor is set to non-blocking mode.

Note

The passed file descriptor or SOCKET is not checked for its type, but it’s required that it represents a valid datagram socket.

int uv_udp_bind(uv_udp_t *handle, const struct sockaddr *addr, unsigned int flags)#

Bind the UDP handle to an IP address and port.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().
addr – struct sockaddr_in or struct sockaddr_in6 with the address and port to bind to.
flags – Indicate how the socket will be bound, UV_UDP_IPV6ONLY, UV_UDP_REUSEADDR, and UV_UDP_RECVERR are supported.

Returns:

0 on success, or an error code < 0 on failure.

int uv_udp_connect(uv_udp_t *handle, const struct sockaddr *addr)#

Associate the UDP handle to a remote address and port, so every message sent by this handle is automatically sent to that destination. Calling this function with a NULL addr disconnects the handle. Trying to call uv_udp_connect() on an already connected handle will result in an UV_EISCONN error. Trying to disconnect a handle that is not connected will return an UV_ENOTCONN error.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().
addr – struct sockaddr_in or struct sockaddr_in6 with the address and port to associate to.

Returns:

0 on success, or an error code < 0 on failure.

New in version 1.27.0.

int uv_udp_getpeername(const uv_udp_t *handle, struct sockaddr *name, int *namelen)#

Get the remote IP and port of the UDP handle on connected UDP handles. On unconnected handles, it returns UV_ENOTCONN.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init() and bound.
name – Pointer to the structure to be filled with the address data. In order to support IPv4 and IPv6 struct sockaddr_storage should be used.
namelen – On input it indicates the data of the name field. On output it indicates how much of it was filled.

Returns:

0 on success, or an error code < 0 on failure

New in version 1.27.0.

int uv_udp_getsockname(const uv_udp_t *handle, struct sockaddr *name, int *namelen)#

Get the local IP and port of the UDP handle.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init() and bound.
name – Pointer to the structure to be filled with the address data. In order to support IPv4 and IPv6 struct sockaddr_storage should be used.
namelen – On input it indicates the data of the name field. On output it indicates how much of it was filled.

Returns:

0 on success, or an error code < 0 on failure.

int uv_udp_set_membership(uv_udp_t *handle, const char *multicast_addr, const char *interface_addr, uv_membership membership)#

Set membership for a multicast address

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().
multicast_addr – Multicast address to set membership for.
interface_addr – Interface address.
membership – Should be UV_JOIN_GROUP or UV_LEAVE_GROUP.

Returns:

0 on success, or an error code < 0 on failure.

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)#

Set membership for a source-specific multicast group.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().
multicast_addr – Multicast address to set membership for.
interface_addr – Interface address.
source_addr – Source address.
membership – Should be UV_JOIN_GROUP or UV_LEAVE_GROUP.

Returns:

0 on success, or an error code < 0 on failure.

New in version 1.32.0.

int uv_udp_set_multicast_loop(uv_udp_t *handle, int on)#

Set IP multicast loop flag. Makes multicast packets loop back to local sockets.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().
on – 1 for on, 0 for off.

Returns:

0 on success, or an error code < 0 on failure.

int uv_udp_set_multicast_ttl(uv_udp_t *handle, int ttl)#

Set the multicast ttl.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().
ttl – 1 through 255.

Returns:

0 on success, or an error code < 0 on failure.

int uv_udp_set_multicast_interface(uv_udp_t *handle, const char *interface_addr)#

Set the multicast interface to send or receive data on.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().
interface_addr – interface address.

Returns:

0 on success, or an error code < 0 on failure.

int uv_udp_set_broadcast(uv_udp_t *handle, int on)#

Set broadcast on or off.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().
on – 1 for on, 0 for off.

Returns:

0 on success, or an error code < 0 on failure.

int uv_udp_set_ttl(uv_udp_t *handle, int ttl)#

Set the time to live.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().
ttl – 1 through 255.

Returns:

0 on success, or an error code < 0 on failure.

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)#

Send data over the UDP socket. If the socket has not previously been bound with uv_udp_bind() it will be bound to 0.0.0.0 (the “all interfaces” IPv4 address) and a random port number.

On Windows if the addr is initialized to point to an unspecified address (0.0.0.0 or ::) it will be changed to point to localhost. This is done to match the behavior of Linux systems.

For connected UDP handles, addr must be set to NULL, otherwise it will return UV_EISCONN error.

For connectionless UDP handles, addr cannot be NULL, otherwise it will return UV_EDESTADDRREQ error.

Parameters:

req – UDP request handle. Need not be initialized.
handle – UDP handle. Should have been initialized with uv_udp_init().
bufs – List of buffers to send.
nbufs – Number of buffers in bufs.
addr – struct sockaddr_in or struct sockaddr_in6 with the address and port of the remote peer.
send_cb – Callback to invoke when the data has been sent out.

Returns:

0 on success, or an error code < 0 on failure.

Changed in version 1.19.0: added 0.0.0.0 and :: to localhost mapping

Changed in version 1.27.0: added support for connected sockets

int uv_udp_try_send(uv_udp_t *handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr *addr)#

Same as uv_udp_send(), but won’t queue a send request if it can’t be completed immediately.

For connected UDP handles, addr must be set to NULL, otherwise it will return UV_EISCONN error.

For connectionless UDP handles, addr cannot be NULL, otherwise it will return UV_EDESTADDRREQ error.

Returns:: >= 0: number of bytes sent (it matches the given buffer size). < 0: negative error code (UV_EAGAIN is returned when the message can’t be sent immediately).

Changed in version 1.27.0: added support for connected sockets

int uv_udp_recv_start(uv_udp_t *handle, uv_alloc_cb alloc_cb, uv_udp_recv_cb recv_cb)#

Prepare for receiving data. If the socket has not previously been bound with uv_udp_bind() it is bound to 0.0.0.0 (the “all interfaces” IPv4 address) and a random port number.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().
alloc_cb – Callback to invoke when temporary storage is needed.
recv_cb – Callback to invoke with received data.

Returns:

0 on success, or an error code < 0 on failure.

Note

When using recvmmsg(2), the number of messages received at a time is limited by the number of max size dgrams that will fit into the buffer allocated in alloc_cb, and suggested_size in alloc_cb for udp_recv is always set to the size of 1 max size dgram.

Changed in version 1.35.0: added support for recvmmsg(2) on supported platforms). The use of this feature requires a buffer larger than 2 * 64KB to be passed to alloc_cb.

Changed in version 1.37.0: recvmmsg(2) support is no longer enabled implicitly, it must be explicitly requested by passing the UV_UDP_RECVMMSG flag to uv_udp_init_ex().

Changed in version 1.39.0: uv_udp_using_recvmmsg() can be used in alloc_cb to determine if a buffer sized for use with recvmmsg(2) should be allocated for the current handle/platform.

int uv_udp_using_recvmmsg(uv_udp_t *handle)#: Returns 1 if the UDP handle was created with the UV_UDP_RECVMMSG flag and the platform supports recvmmsg(2), 0 otherwise.

New in version 1.39.0.

int uv_udp_recv_stop(uv_udp_t *handle)#

Stop listening for incoming datagrams.

Parameters:

handle – UDP handle. Should have been initialized with uv_udp_init().

Returns:

0 on success, or an error code < 0 on failure.

size_t uv_udp_get_send_queue_size(const uv_udp_t *handle)#: Returns handle->send_queue_size.

New in version 1.19.0.

size_t uv_udp_get_send_queue_count(const uv_udp_t *handle)#: Returns handle->send_queue_count.

New in version 1.19.0.

uv_udp_t — UDP handle#

Data types#

Public members#

API#

`uv_udp_t` — UDP handle#