.. _udp:

:c:type:`uv_udp_t` --- UDP handle

=================================

UDP handles encapsulate UDP communication for both clients and servers.

Data types

----------

.. c:type:: uv_udp_t

    UDP handle type.

.. c:type:: uv_udp_send_t

    UDP send request type.

.. c:type:: uv_udp_flags

    Flags used in :c:func:`uv_udp_bind` and :c:type:`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 recvmmsg should be used, if available.

            */

            UV_UDP_RECVMMSG = 256

        };

.. c:type:: void (*uv_udp_send_cb)(uv_udp_send_t* req, int status)

    Type definition for callback passed to :c:func:`uv_udp_send`, which is

    called after the data was sent.

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

    Type definition for callback passed to :c:func:`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`: :c:type:`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 :man:`recvmmsg(2)`, chunks will have the `UV_UDP_MMSG_CHUNK` flag set,

    those must not be freed. 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. This is a good chance for the callee to

    free the provided buffer.

    .. 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.

.. c:type:: uv_membership

    Membership type for a multicast address.

    ::

        typedef enum {

            UV_LEAVE_GROUP = 0,

            UV_JOIN_GROUP

        } uv_membership;

Public members

^^^^^^^^^^^^^^

.. c:member:: size_t uv_udp_t.send_queue_size

    Number of bytes queued for sending. This field strictly shows how much

    information is currently queued.

.. c:member:: size_t uv_udp_t.send_queue_count

    Number of send requests currently in the queue awaiting to be processed.

.. c:member:: uv_udp_t* uv_udp_send_t.handle

    UDP handle where this send request is taking place.

.. seealso:: The :c:type:`uv_handle_t` members also apply.

API

---

.. c:function:: 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.

.. c:function:: 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 :c:func:`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, :man:`recvmmsg(2)` will

      be used.

    .. versionadded:: 1.7.0

    .. versionchanged:: 1.37.0 added the `UV_UDP_RECVMMSG` flag.

.. c:function:: 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.

    .. versionchanged:: 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.

.. c:function:: 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.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param addr: `struct sockaddr_in` or `struct sockaddr_in6`

        with the address and port to bind to.

    :param 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.

.. c:function:: 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.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param 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.

    .. versionadded:: 1.27.0

.. c:function:: 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`.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init` and bound.

    :param 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.

    :param 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

    .. versionadded:: 1.27.0

.. c:function:: int uv_udp_getsockname(const uv_udp_t* handle, struct sockaddr* name, int* namelen)

    Get the local IP and port of the UDP handle.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init` and bound.

    :param 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.

    :param 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.

.. c:function:: 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

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param multicast_addr: Multicast address to set membership for.

    :param interface_addr: Interface address.

    :param membership: Should be ``UV_JOIN_GROUP`` or ``UV_LEAVE_GROUP``.

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

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

    Set membership for a source-specific multicast group.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param multicast_addr: Multicast address to set membership for.

    :param interface_addr: Interface address.

    :param source_addr: Source address.

    :param membership: Should be ``UV_JOIN_GROUP`` or ``UV_LEAVE_GROUP``.

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

    .. versionadded:: 1.32.0

.. c:function:: 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.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param on: 1 for on, 0 for off.

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

.. c:function:: int uv_udp_set_multicast_ttl(uv_udp_t* handle, int ttl)

    Set the multicast ttl.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param ttl: 1 through 255.

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

.. c:function:: int uv_udp_set_multicast_interface(uv_udp_t* handle, const char* interface_addr)

    Set the multicast interface to send or receive data on.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param interface_addr: interface address.

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

.. c:function:: int uv_udp_set_broadcast(uv_udp_t* handle, int on)

    Set broadcast on or off.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param on: 1 for on, 0 for off.

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

.. c:function:: int uv_udp_set_ttl(uv_udp_t* handle, int ttl)

    Set the time to live.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param ttl: 1 through 255.

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

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

    Send data over the UDP socket. If the socket has not previously been bound

    with :c:func:`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.

    :param req: UDP request handle. Need not be initialized.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param bufs: List of buffers to send.

    :param nbufs: Number of buffers in `bufs`.

    :param addr: `struct sockaddr_in` or `struct sockaddr_in6` with the

        address and port of the remote peer.

    :param send_cb: Callback to invoke when the data has been sent out.

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

    .. versionchanged:: 1.19.0 added ``0.0.0.0`` and ``::`` to ``localhost``

        mapping

    .. versionchanged:: 1.27.0 added support for connected sockets

.. c:function:: int uv_udp_try_send(uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr)

    Same as :c:func:`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).

    .. versionchanged:: 1.27.0 added support for connected sockets

.. c:function:: 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 :c:func:`uv_udp_bind` it is bound to 0.0.0.0 (the "all interfaces"

    IPv4 address) and a random port number.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

    :param alloc_cb: Callback to invoke when temporary storage is needed.

    :param recv_cb: Callback to invoke with received data.

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

    .. versionchanged:: 1.35.0 added support for :man:`recvmmsg(2)` on supported platforms).

                        The use of this feature requires a buffer larger than

                        2 * 64KB to be passed to `alloc_cb`.

    .. versionchanged:: 1.37.0 :man:`recvmmsg(2)` support is no longer enabled implicitly,

                        it must be explicitly requested by passing the `UV_UDP_RECVMMSG` flag to

                        :c:func:`uv_udp_init_ex`.

.. c:function:: int uv_udp_recv_stop(uv_udp_t* handle)

    Stop listening for incoming datagrams.

    :param handle: UDP handle. Should have been initialized with

        :c:func:`uv_udp_init`.

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

.. c:function:: size_t uv_udp_get_send_queue_size(const uv_udp_t* handle)

    Returns `handle->send_queue_size`.

    .. versionadded:: 1.19.0

.. c:function:: size_t uv_udp_get_send_queue_count(const uv_udp_t* handle)

    Returns `handle->send_queue_count`.

    .. versionadded:: 1.19.0

.. seealso:: The :c:type:`uv_handle_t` API functions also apply.