uv_udp_t — UDP handle

UDP handles encapsulate UDP communication for both clients and servers.

Data types

uv_udp_t

UDP handle type.

uv_udp_send_t

UDP send request 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
};
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.

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.
  • 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. Right now only UV_UDP_PARTIAL is used.

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.

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.

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.

See also

The uv_handle_t members also apply.

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. At the moment 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().

New in version 1.7.0.

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().
  • addrstruct 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 and UV_UDP_REUSEADDR 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().
  • addrstruct 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.
  • addrstruct 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.

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.

See also

The uv_handle_t API functions also apply.