UDP handle type.

UDP send request type.

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.
         * This sets the SO_REUSEPORT socket flag on the BSDs (except for
         * DragonFlyBSD), OS X, and other platforms where SO_REUSEPORTs don't
         * have the capability of load balancing, as the opposite of what
         * UV_UDP_REUSEPORT would do. 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 if SO_REUSEPORT will be set when binding the handle.
         * This sets the SO_REUSEPORT socket option on supported platforms.
         * Unlike UV_UDP_REUSEADDR, this flag will make multiple threads or
         * processes that are binding to the same address and port "share"
         * the port, which means incoming datagrams are distributed across
         * the receiving sockets among threads or processes.
         *
         * This flag is available only on Linux 3.9+, DragonFlyBSD 3.6+,
         * FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ for now.
         */
        UV_UDP_REUSEPORT = 64,
        /*
         * Indicates that recvmmsg should be used, if available.
         */
        UV_UDP_RECVMMSG = 256
    };

Type definition for callback passed to :c:func:`uv_udp_send`, which is
called after the data was sent.

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; if using :man:`recvmmsg(2)` no more
  chunks will be received and the buffer can be freed safely.
* `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. 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.

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

Membership type for a multicast address.

::

    typedef enum {
        UV_LEAVE_GROUP = 0,
        UV_JOIN_GROUP
    } uv_membership;

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

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

UDP handle where this send request is taking place.

Initialize a new UDP handle. The actual socket is created lazily.
Returns 0 on success.

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.

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.

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``, ``UV_UDP_REUSEADDR``, ``UV_UDP_REUSEPORT``,
    and ``UV_UDP_RECVERR`` are supported.

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

.. versionchanged:: 1.49.0 added the ``UV_UDP_REUSEPORT`` flag.

.. note::
    ``UV_UDP_REUSEPORT`` flag is available only on Linux 3.9+, DragonFlyBSD 3.6+,
    FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ at the moment. On other platforms
    this function will return an UV_ENOTSUP error.
    For platforms where `SO_REUSEPORT`s have the capability of load balancing,
    specifying both ``UV_UDP_REUSEADDR`` and ``UV_UDP_REUSEPORT`` in flags is allowed
    and `SO_REUSEPORT` will always override the behavior of `SO_REUSEADDR`.
    For platforms where `SO_REUSEPORT`s don't have the capability of load balancing,
    specifying both ``UV_UDP_REUSEADDR`` and ``UV_UDP_REUSEPORT`` in flags will fail,
    returning an UV_ENOTSUP error.

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

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

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.

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.

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

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_ex` as either ``AF_INET`` or ``AF_INET6``, or have
    been bound to an address explicitly with :c:func:`uv_udp_bind`, or
    implicitly with :c:func:`uv_udp_send()` or :c:func:`uv_udp_recv_start`.

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

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

Set the multicast ttl.

:param handle: UDP handle. Should have been initialized with
    :c:func:`uv_udp_init_ex` as either ``AF_INET`` or ``AF_INET6``, or have
    been bound to an address explicitly with :c:func:`uv_udp_bind`, or
    implicitly with :c:func:`uv_udp_send()` or :c:func:`uv_udp_recv_start`.

:param ttl: 1 through 255.

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

Set the multicast interface to send or receive data on.

:param handle: UDP handle. Should have been initialized with
    :c:func:`uv_udp_init_ex` as either ``AF_INET`` or ``AF_INET6``, or have
    been bound to an address explicitly with :c:func:`uv_udp_bind`, or
    implicitly with :c:func:`uv_udp_send()` or :c:func:`uv_udp_recv_start`.

:param interface_addr: interface address.

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

Set broadcast on or off.

:param handle: UDP handle. Should have been initialized with
    :c:func:`uv_udp_init_ex` as either ``AF_INET`` or ``AF_INET6``, or have
    been bound to an address explicitly with :c:func:`uv_udp_bind`, or
    implicitly with :c:func:`uv_udp_send()` or :c:func:`uv_udp_recv_start`.

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

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

Set the time to live.

:param handle: UDP handle. Should have been initialized with
    :c:func:`uv_udp_init_ex` as either ``AF_INET`` or ``AF_INET6``, or have
    been bound to an address explicitly with :c:func:`uv_udp_bind`, or
    implicitly with :c:func:`uv_udp_send()` or :c:func:`uv_udp_recv_start`.

:param ttl: 1 through 255.

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

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

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

Like :c:func:`uv_udp_try_send`, but can send multiple datagrams.
Lightweight abstraction around :man:`sendmmsg(2)`, with a :man:`sendmsg(2)`
fallback loop for platforms that do not support the former. The handle must
be fully initialized; call c:func:`uv_udp_bind` first.

:returns: >= 0: number of datagrams sent. Zero only if `count` was zero.
    < 0: negative error code. Only if sending the first datagram fails,
    otherwise returns a positive send count. ``UV_EAGAIN`` when datagrams
    cannot be sent right now; fall back to :c:func:`uv_udp_send`.

.. versionadded:: 1.50.0

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.

.. note::
    When using :man:`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.

.. 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`.
.. versionchanged:: 1.39.0 :c:func:`uv_udp_using_recvmmsg` can be used in `alloc_cb` to
                    determine if a buffer sized for use with :man:`recvmmsg(2)` should be
                    allocated for the current handle/platform.

Returns 1 if the UDP handle was created with the `UV_UDP_RECVMMSG` flag
and the platform supports :man:`recvmmsg(2)`, 0 otherwise.

.. versionadded:: 1.39.0

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.

Returns `handle->send_queue_size`.

.. versionadded:: 1.19.0

Returns `handle->send_queue_count`.

.. versionadded:: 1.19.0