nvim_runtime_lua

uv.uv_udp_t

supers: uv.uv_handle_t

uv_udp_t - UDP handle

[uv_handle_t][] functions also apply.

UDP handles encapsulate UDP communication for both clients and servers.

Methods19 

function uv_udp_t.get_send_queue_size() -> integer

Returns the handle's send queue size.

function uv_udp_t.get_send_queue_count() -> integer

Returns the handle's send queue count.

function uv_udp_t.open(fd: integer, flags: integer | { reuseaddr: boolean?, reuseport: boolean? } | nil) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

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.

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. Note: flags is only supported with Libuv >= 1.52.0.

function uv_udp_t.bind(host: string, port: number, flags: uv.udp_bind.flags | nil) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

Bind the UDP handle to an IP address and port. Any flags are set with a table with fields reuseaddr, ipv6only, linux_recverr, reuseport equal to true or false.

  • reuseaddr: 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 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.

  • ipv6only: Disables dual stack mode.
  • linux_recverr: Indicates if IPRECVERR/IPV6RECVERR will be set when binding the handle.

    • This sets IPRECVERR for IPv4 and IPV6RECVERR 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.

  • reuseport: Indicates if SO_REUSEPORT will be set when binding the handle.

    • This sets the SO_REUSEPORT socket option on supported platforms. Unlike 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. Note: The flag linux_recverr is only supported with Libuv >= 1.42.0. The flag reuseport is only supported with Libuv >= 1.49.0.

function uv_udp_t.getsockname() -> (address uv.socketinfo | nil, err nil | string, err_name uv.error_name | nil)

Get the local IP and port of the UDP handle.

function uv_udp_t.getpeername() -> (address uv.socketinfo | nil, err nil | string, err_name uv.error_name | nil)

Get the remote IP and port of the UDP handle on connected UDP handles.

function uv_udp_t.set_membership(multicast_addr: string, interface_addr: nil | string, membership: string) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

Set membership for a multicast address. multicast_addr is multicast address to set membership for. interface_addr is interface address. membership can be the string "leave" or "join".

function uv_udp_t.set_source_membership(multicast_addr: string, interface_addr: nil | string, source_addr: string, membership: string) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

Set membership for a source-specific multicast group. multicast_addr is multicast address to set membership for. interface_addr is interface address. source_addr is source address. membership can be the string "leave" or "join".

function uv_udp_t.set_multicast_loop(on: boolean) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

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

function uv_udp_t.set_multicast_ttl(ttl: integer) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

Set the multicast ttl.

ttl is an integer 1 through 255.

function uv_udp_t.set_multicast_interface(interface_addr: string) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

Set the multicast interface to send or receive data on.

function uv_udp_t.set_broadcast(on: boolean) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

Set broadcast on or off.

function uv_udp_t.set_ttl(ttl: integer) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

Set the time to live.

ttl is an integer 1 through 255.

function uv_udp_t.send(data: uv.buffer, host: string, port: integer, callback: fun(err: nil | string) -> nil) -> (send uv.uv_udp_send_t | nil, err nil | string, err_name uv.error_name | nil)

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.

function uv_udp_t.try_send(data: uv.buffer, host: string, port: integer) -> (bytes_sent nil | integer, err nil | string, err_name uv.error_name | nil)

Same as uv.udp_send(), but won't queue a send request if it can't be completed immediately.

function uv_udp_t.try_send2(messages: {integer, { addr: { ip: string, port: integer }, data: uv.buffer }}, flags: 0 | {  } | nil, port: integer) -> (messages_sent nil | integer, err nil | string, err_name uv.error_name | nil)

Like uv.udp_try_send(), but can send multiple datagrams. Lightweight abstraction around sendmmsg(2), with a sendmsg(2) fallback loop for platforms that do not support the former. The udp handle must be fully initialized, either from a uv.udp_bind call, another call that will bind automatically (udp_send, udp_try_send, etc), or from uv.udp_connect.

messages should be an array-like table, where addr must be specified if the udp has not been connected via udp_connect. Otherwise, addr must be nil.

flags is reserved for future extension and must currently be nil or 0 or {}.

Returns the number of messages sent successfully. An error will only be returned if the first datagram failed to be sent. Example

-- If client:connect(...) was not called
local addr = { ip = "127.0.0.1", port = 1234 }
client:try_send2({
  { data = "Message 1", addr = addr },
  { data = "Message 2", addr = addr },
})

-- If client:connect(...) was called
client:try_send2({
  { data = "Message 1" },
  { data = "Message 2" },
})

function uv_udp_t.recv_start(callback: uv.udp_recv_start.callback) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

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.

See [Constants][] for supported address family output values.

function uv_udp_t.recv_stop() -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

Stop listening for incoming datagrams.

function uv_udp_t.connect(host: string, port: integer) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)

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 EISCONN error. Trying to disconnect a handle that is not connected will return an ENOTCONN error.