uv

Returns the libuv version packed into a single integer. 8 bits are used for each component, with the patch number stored in the 8 least significant bits. For example, this would be 0x010203 in libuv 1.2.3.

Returns the libuv version number as a string. For example, this would be "1.2.3" in libuv 1.2.3. For non-release versions, the version suffix is included.

Closes all internal loop resources. In normal execution, the loop will automatically be closed when it is garbage collected by Lua, so it is not necessary to explicitly call loop_close(). Call this function only after the loop has finished executing and all open handles and requests have been closed, or it will return EBUSY.

This function runs the event loop. It will act differently depending on the specified mode:

• "default": Runs the event loop until there are no more active and

referenced handles or requests. Returns true if uv.stop() was called and there are still active handles or requests. Returns false in all other cases.

• "once": Poll for I/O once. Note that this function blocks if there are no

pending callbacks. Returns false when done (no active handles or requests left), or true if more callbacks are expected (meaning you should run the event loop again sometime in the future).

• "nowait": Poll for I/O once but don't block if there are no pending

callbacks. Returns false if done (no active handles or requests left), or true if more callbacks are expected (meaning you should run the event loop again sometime in the future). Note: Luvit will implicitly call uv.run() after loading user code, but if you use the luv bindings directly, you need to call this after registering your initial set of event callbacks to start the event loop.

Set additional loop options. You should normally call this before the first call to uv_run() unless mentioned otherwise.

Supported options:

• "block_signal": Block a signal when polling for new events. The second argument

to loop_configure() is the signal name (as a lowercase string) or the signal number. This operation is currently only implemented for "sigprof" signals, to suppress unnecessary wakeups when using a sampling profiler. Requesting other signals will fail with EINVAL.

• "metrics_idle_time": Accumulate the amount of idle time the event loop spends

in the event provider. This option is necessary to use metrics_idle_time().

An example of a valid call to this function is:

uv.loop_configure("block_signal", "sigprof")

Note: Be prepared to handle the ENOSYS error; it means the loop option is not supported by the platform.

If the loop is running, returns a string indicating the mode in use. If the loop is not running, nil is returned instead.

Returns true if there are referenced active handles, active requests, or closing handles in the loop; otherwise, false.

Stop the event loop, causing uv.run() to end as soon as possible. This will happen not sooner than the next loop iteration. If this function was called before blocking for I/O, the loop won't block for I/O on this iteration.

Get backend file descriptor. Only kqueue, epoll, and event ports are supported.

This can be used in conjunction with uv.run("nowait") to poll in one thread and run the event loop's callbacks in another Note: Embedding a kqueue fd in another kqueue pollset doesn't work on all platforms. It's not an error to add the fd but it never generates events.

Get the poll timeout. The return value is in milliseconds, or -1 for no timeout.

Returns the current timestamp in milliseconds. The timestamp is cached at the start of the event loop tick, see uv.update_time() for details and rationale.

The timestamp increases monotonically from some arbitrary point in time. Don't make assumptions about the starting point, you will only get disappointed. Note: Use uv.hrtime() if you need sub-millisecond granularity.

Update the event loop's concept of "now". Libuv caches the current time at the start of the event loop tick in order to reduce the number of time-related system calls.

You won't normally need to call this function unless you have callbacks that block the event loop for longer periods of time, where "longer" is somewhat subjective but probably on the order of a millisecond or more.

Walk the list of handles: callback will be executed with each handle. Example

-- Example usage of uv.walk to close all handles that aren't already closing.
uv.walk(function (handle)
  if not handle:is_closing() then
    handle:close()
  end
end)

Cancel a pending request. Fails if the request is executing or has finished executing. Only cancellation of uv_fs_t, uv_getaddrinfo_t, uv_getnameinfo_t and uv_work_t requests is currently supported.

Returns the name of the struct for a given request (e.g. "fs" for uv_fs_t) and the libuv enum integer for the request's type (uv_req_type).

Returns true if the handle is active, false if it's inactive. What "active” means depends on the type of handle:

• A [uv_async_t][] handle is always active and cannot be deactivated, except

by closing it with uv.close().

• A [uv_pipe_t][], [uv_tcp_t][], [uv_udp_t][], etc. handle - basically

any handle that deals with I/O - is active when it is doing something that involves I/O, like reading, writing, connecting, accepting new connections, etc.

• A [uv_check_t][], [uv_idle_t][], [uv_timer_t][], etc. handle is active

when it has been started with a call to uv.check_start(), uv.idle_start(), uv.timer_start() etc. until it has been stopped with a call to its respective stop function.

Returns true if the handle is closing or closed, false otherwise. Note: This function should only be used between the initialization of the handle and the arrival of the close callback.

Request handle to be closed. callback will be called asynchronously after this call. This MUST be called on each handle before memory is released.

Handles that wrap file descriptors are closed immediately but callback will still be deferred to the next iteration of the event loop. It gives you a chance to free up any resources associated with the handle.

In-progress requests, like uv_connect_t or uv_write_t, are cancelled and have their callbacks called asynchronously with ECANCELED.

Reference the given handle. References are idempotent, that is, if a handle is already referenced calling this function again will have no effect.

Un-reference the given handle. References are idempotent, that is, if a handle is not referenced calling this function again will have no effect.

Returns true if the handle referenced, false if not.

Gets or sets the size of the send buffer that the operating system uses for the socket.

If size is omitted (or 0), this will return the current send buffer size; otherwise, this will use size to set the new send buffer size.

This function works for TCP, pipe and UDP handles on Unix and for TCP and UDP handles on Windows. Note: Linux will set double the size and return double the size of the original set value.

Gets or sets the size of the receive buffer that the operating system uses for the socket.

If size is omitted (or 0), this will return the current send buffer size; otherwise, this will use size to set the new send buffer size.

This function works for TCP, pipe and UDP handles on Unix and for TCP and UDP handles on Windows. Note: Linux will set double the size and return double the size of the original set value.

Gets the platform dependent file descriptor equivalent.

The following handles are supported: TCP, pipes, TTY, UDP and poll. Passing any other handle type will fail with EINVAL.

If a handle doesn't have an attached file descriptor yet or the handle itself has been closed, this function will return EBADF. Warning: Be very careful when using this function. libuv assumes it's in control of the file descriptor so any change to it may lead to malfunction.

Returns the name of the struct for a given handle (e.g. "pipe" for uv_pipe_t) and the libuv enum integer for the handle's type (uv_handle_type).

Creates and initializes a new uv_timer_t. Returns the Lua userdata wrapping it. Example

-- Creating a simple setTimeout wrapper
local function setTimeout(timeout, callback)
  local timer = uv.new_timer()
  timer:start(timeout, 0, function ()
    timer:stop()
    timer:close()
    callback()
  end)
  return timer
end

-- Creating a simple setInterval wrapper
local function setInterval(interval, callback)
  local timer = uv.new_timer()
  timer:start(interval, interval, function ()
    callback()
  end)
  return timer
end

-- And clearInterval
local function clearInterval(timer)
  timer:stop()
  timer:close()
end

Start the timer. timeout and repeat are in milliseconds.

If timeout is zero, the callback fires on the next event loop iteration. If repeat is non-zero, the callback fires first after timeout milliseconds and then repeatedly after repeat milliseconds.

Stop the timer, the callback will not be called anymore.

Stop the timer, and if it is repeating restart it using the repeat value as the timeout. If the timer has never been started before it raises EINVAL.

Set the repeat interval value in milliseconds. The timer will be scheduled to run on the given interval, regardless of the callback execution duration, and will follow normal timer semantics in the case of a time-slice overrun.

For example, if a 50 ms repeating timer first runs for 17 ms, it will be scheduled to run again 33 ms later. If other tasks consume more than the 33 ms following the first timer callback, then the callback will run as soon as possible.

Get the timer repeat value.

Get the timer due value or 0 if it has expired. The time is relative to uv.now().

Creates and initializes a new uv_prepare_t. Returns the Lua userdata wrapping it.

Start the handle with the given callback.

Stop the handle, the callback will no longer be called.

Creates and initializes a new uv_check_t. Returns the Lua userdata wrapping it.

Start the handle with the given callback.

Stop the handle, the callback will no longer be called.

Creates and initializes a new uv_idle_t. Returns the Lua userdata wrapping it.

Start the handle with the given callback.

Stop the handle, the callback will no longer be called.

Creates and initializes a new uv_async_t. Returns the Lua userdata wrapping it. Note: Unlike other handle initialization functions, this immediately starts the handle.

Wakeup the event loop and call the async handle's callback. Note: It's safe to call this function from any thread. The callback will be called on the loop thread. Warning: libuv will coalesce calls to uv.async_send(async), that is, not every call to it will yield an execution of the callback. For example: if uv.async_send() is called 5 times in a row before the callback is called, the callback will only be called once. If uv.async_send() is called again after the callback was called, it will be called again.

Initialize the handle using a file descriptor.

The file descriptor is set to non-blocking mode.

Initialize the handle using a socket descriptor. On Unix this is identical to uv.new_poll(). On windows it takes a SOCKET handle.

The socket is set to non-blocking mode.

Starts polling the file descriptor. events are: "r", "w", "rw", "d", "rd", "wd", "rwd", "p", "rp", "wp", "rwp", "dp", "rdp", "wdp", or "rwdp" where r is READABLE, w is WRITABLE, d is DISCONNECT, and p is PRIORITIZED. As soon as an event is detected the callback will be called with status set to 0, and the detected events set on the events field.

The user should not close the socket while the handle is active. If the user does that anyway, the callback may be called reporting an error status, but this is not guaranteed. Note: Calling uv.poll_start() on a handle that is already active is fine. Doing so will update the events mask that is being watched for.

Stop polling the file descriptor, the callback will no longer be called.

Creates and initializes a new uv_signal_t. Returns the Lua userdata wrapping it.

Start the handle with the given callback, watching for the given signal.

See [Constants][] for supported signame input and output values.

Same functionality as uv.signal_start() but the signal handler is reset the moment the signal is received.

See [Constants][] for supported signame input and output values.

Stop the handle, the callback will no longer be called.

Disables inheritance for file descriptors / handles that this process inherited from its parent. The effect is that child processes spawned by this process don't accidentally inherit these handles.

It is recommended to call this function as early in your program as possible, before the inherited file descriptors can be closed or duplicated. Note: This function works on a best-effort basis: there is no guarantee that libuv can discover all file descriptors that were inherited. In general it does a better job on Windows than it does on Unix.

Initializes the process handle and starts the process. If the process is successfully spawned, this function will return the handle and pid of the child process.

Possible reasons for failing to spawn would include (but not be limited to) the file to execute not existing, not having permissions to use the setuid or setgid specified, or not having enough memory to allocate for the new process.

local stdin = uv.new_pipe()
local stdout = uv.new_pipe()
local stderr = uv.new_pipe()

print("stdin", stdin)
print("stdout", stdout)
print("stderr", stderr)

local handle, pid = uv.spawn("cat", {
  stdio = {stdin, stdout, stderr}
}, function(code, signal) -- on exit
  print("exit code", code)
  print("exit signal", signal)
end)

print("process opened", handle, pid)

uv.read_start(stdout, function(err, data)
  assert(not err, err)
  if data then
    print("stdout chunk", stdout, data)
  else
    print("stdout end", stdout)
  end
end)

uv.read_start(stderr, function(err, data)
  assert(not err, err)
  if data then
    print("stderr chunk", stderr, data)
  else
    print("stderr end", stderr)
  end
end)

uv.write(stdin, "Hello World")

uv.shutdown(stdin, function()
  print("stdin shutdown", stdin)
  uv.close(handle, function()
    print("process closed", handle, pid)
  end)
end)

When the child process exits, on_exit is called with an exit code and signal.

Sends the specified signal to the given process handle. Check the documentation on uv_signal_t for signal support, specially on Windows.

See [Constants][] for supported signame input values.

Sends the specified signal to the given PID. Check the documentation on uv_signal_t for signal support, specially on Windows.

See [Constants][] for supported signame input values.

Returns the handle's pid.

Shutdown the outgoing (write) side of a duplex stream. It waits for pending write requests to complete. The callback is called after shutdown is complete.

Start listening for incoming connections. backlog indicates the number of connections the kernel might queue, same as listen(2). When a new incoming connection is received the callback is called.

This call is used in conjunction with uv.listen() to accept incoming connections. Call this function after receiving a callback to accept the connection.

When the connection callback is called it is guaranteed that this function will complete successfully the first time. If you attempt to use it more than once, it may fail. It is suggested to only call this function once per connection call. Example

server:listen(128, function (err)
  local client = uv.new_tcp()
  server:accept(client)
end)

Read data from an incoming stream. The callback will be made several times until there is no more data to read or uv.read_stop() is called. When we've reached EOF, data will be nil. Example

stream:read_start(function (err, chunk)
  if err then
    -- handle read error
  elseif chunk then
    -- handle data
  else
    -- handle disconnect
  end
end)

Stop reading data from the stream. The read callback will no longer be called.

This function is idempotent and may be safely called on a stopped stream.

Write data to stream.

data can either be a Lua string or a table of strings. If a table is passed in, the C backend will use writev to send all strings in a single system call.

The optional callback is for knowing when the write is complete.

Extended write function for sending handles over a pipe. The pipe must be initialized with ipc option true. Note: send_handle must be a TCP socket or pipe, which is a server or a connection (listening or connected state). Bound sockets or pipes will be assumed to be servers.

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

Will return number of bytes written (can be less than the supplied buffer size).

Like uv.write2(), but with the properties of uv.try_write(). Not supported on Windows, where it returns UV_EAGAIN.

Will return number of bytes written (can be less than the supplied buffer size).

Returns true if the stream is readable, false otherwise.

Returns true if the stream is writable, false otherwise.

Enable or disable blocking mode for a stream.

When blocking mode is enabled all writes complete synchronously. The interface remains unchanged otherwise, e.g. completion or failure of the operation will still be reported through a callback which is made asynchronously. Warning: Relying too much on this API is not recommended. It is likely to change significantly in the future. Currently this only works on Windows and only for uv_pipe_t handles. Also libuv currently makes no ordering guarantee when the blocking mode is changed after write requests have already been submitted. Therefore it is recommended to set the blocking mode immediately after opening or creating the stream.

Returns the stream's write queue size.

Creates and initializes a new uv_tcp_t. Returns the Lua userdata wrapping it.

If set, flags must be a valid address family. See [Constants][] for supported address family input values.

Open an existing file descriptor or SOCKET as a TCP handle. Note: The passed file descriptor or SOCKET is not checked for its type, but it's required that it represents a valid stream socket.

Enable / disable Nagle's algorithm.

Enable / disable TCP keep-alive. delay is the initial delay in seconds, intvl is the time in seconds between individual keep-alive probes, and cnt is the number of probes to send before assuming the connection is dead. ignored when enable is false. Note: intvl and cnt are only supported with Libuv >= 1.52.0.

Enable / disable simultaneous asynchronous accept requests that are queued by the operating system when listening for new TCP connections.

This setting is used to tune a TCP server for the desired performance. Having simultaneous accepts can significantly improve the rate of accepting connections (which is why it is enabled by default) but may lead to uneven load distribution in multi-process setups.

Bind the handle to an host and port. host should be an IP address and not a domain name. Any flags are set with a table with field ipv6only equal to true or false.

When the port is already taken, you can expect to see an EADDRINUSE error from either uv.tcp_bind(), uv.listen() or uv.tcp_connect(). That is, a successful call to this function does not guarantee that the call to uv.listen() or uv.tcp_connect() will succeed as well.

Use a port of 0 to let the OS assign an ephemeral port. You can look it up later using uv.tcp_getsockname().

Get the address of the peer connected to the handle.

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

Get the current address to which the handle is bound.

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

Establish an IPv4 or IPv6 TCP connection. Example

local client = uv.new_tcp()
client:connect("127.0.0.1", 8080, function (err)
  -- check error and carry on.
end)

Resets a TCP connection by sending a RST packet. This is accomplished by setting the SO_LINGER socket option with a linger interval of zero and then calling uv.close(). Due to some platform inconsistencies, mixing of uv.shutdown() and uv.tcp_close_reset() calls is not allowed.

Create a pair of connected sockets with the specified properties. The resulting handles can be passed to uv.tcp_open, used with uv.spawn, or for any other purpose.

See [Constants][] for supported socktype input values.

When protocol is set to 0 or nil, it will be automatically chosen based on the socket's domain and type. When protocol is specified as a string, it will be looked up using the getprotobyname(3) function (examples: "ip", "icmp", "tcp", "udp", etc).

Flags:

• nonblock: Opens the specified socket handle for OVERLAPPED or FIONBIO/O_NONBLOCK I/O usage. This is recommended for handles that will be used by libuv, and not usually recommended otherwise.

Equivalent to socketpair(2) with a domain of AF_UNIX. Example

-- Simple read/write with tcp
local fds = uv.socketpair(nil, nil, {nonblock=true}, {nonblock=true})

local sock1 = uv.new_tcp()
sock1:open(fds[1])

local sock2 = uv.new_tcp()
sock2:open(fds[2])

sock1:write("hello")
sock2:read_start(function(err, chunk)
  assert(not err, err)
  print(chunk)
end)

Creates and initializes a new uv_pipe_t. Returns the Lua userdata wrapping it. The ipc argument is a boolean to indicate if this pipe will be used for handle passing between processes.

Open an existing file descriptor or [uv_handle_t][] as a pipe. Note: The file descriptor is set to non-blocking mode.

Bind the pipe to a file path (Unix) or a name (Windows). Note: Paths on Unix get truncated to sizeof(sockaddrun.sunpath) bytes, typically between 92 and 108 bytes.

Connect to the Unix domain socket or the named pipe. Note: Paths on Unix get truncated to sizeof(sockaddrun.sunpath) bytes, typically between 92 and 108 bytes.

Get the name of the Unix domain socket or the named pipe.

Get the name of the Unix domain socket or the named pipe to which the handle is connected.

Set the number of pending pipe instance handles when the pipe server is waiting for connections. Note: This setting applies to Windows only.

Returns the pending pipe count for the named pipe.

Used to receive handles over IPC pipes.

First - call uv.pipe_pending_count(), if it's > 0 then initialize a handle of the given type, returned by uv.pipe_pending_type() and call uv.accept(pipe, handle).

Alters pipe permissions, allowing it to be accessed from processes run by different users. Makes the pipe writable or readable by all users. flags are: "r", "w", "rw", or "wr" where r is READABLE and w is WRITABLE. This function is blocking.

Create a pair of connected pipe handles. Data may be written to the write fd and read from the read fd. The resulting handles can be passed to pipe_open, used with spawn, or for any other purpose.

Flags:

• nonblock: Opens the specified socket handle for OVERLAPPED or FIONBIO/O_NONBLOCK I/O usage. This is recommended for handles that will be used by libuv, and not usually recommended otherwise.

Equivalent to pipe(2) with the O_CLOEXEC flag set. Example

-- Simple read/write with pipe_open
local fds = uv.pipe({nonblock=true}, {nonblock=true})

local read_pipe = uv.new_pipe()
read_pipe:open(fds.read)

local write_pipe = uv.new_pipe()
write_pipe:open(fds.write)

write_pipe:write("hello")
read_pipe:read_start(function(err, chunk)
  assert(not err, err)
  print(chunk)
end)

Bind the pipe to a file path (Unix) or a name (Windows).

Flags:

• If type(flags) is number, it must be 0 or uv.constants.PIPE_NO_TRUNCATE.
• If type(flags) is table, it must be {} or { no_truncate = true|false }.
• If type(flags) is nil, it use default value 0.
• Returns EINVAL for unsupported flags without performing the bind operation.

Supports Linux abstract namespace sockets. namelen must include the leading '0' byte but not the trailing nul byte. Note:

1. Paths on Unix get truncated to sizeof(sockaddrun.sunpath) bytes,

typically between 92 and 108 bytes.

2. New in version 1.46.0.

Connect to the Unix domain socket or the named pipe.

Flags:

• If type(flags) is number, it must be 0 or uv.constants.PIPE_NO_TRUNCATE.
• If type(flags) is table, it must be {} or { no_truncate = true|false }.
• If type(flags) is nil, it use default value 0.
• Returns EINVAL for unsupported flags without performing the bind operation.

Supports Linux abstract namespace sockets. namelen must include the leading nul byte but not the trailing nul byte. Note:

1. Paths on Unix get truncated to sizeof(sockaddrun.sunpath) bytes,

typically between 92 and 108 bytes.

2. New in version 1.46.0.

Initialize a new TTY stream with the given file descriptor. Usually the file descriptor will be:

• 0 - stdin
• 1 - stdout
• 2 - stderr

On Unix this function will determine the path of the fd of the terminal using ttyname_r(3), open it, and use it if the passed file descriptor refers to a TTY. This lets libuv put the tty in non-blocking mode without affecting other processes that share the tty.

This function is not thread safe on systems that don’t support ioctl TIOCGPTN or TIOCPTYGNAME, for instance OpenBSD and Solaris. Note: If reopening the TTY fails, libuv falls back to blocking writes.

Set the TTY using the specified terminal mode.

See [Constants][] for supported TTY mode input values.

To be called when the program exits. Resets TTY settings to default values for the next process to take over.

This function is async signal-safe on Unix platforms but can fail with error code EBUSY if you call it when execution is inside uv.tty_set_mode().

Gets the current Window width and height.

Controls whether console virtual terminal sequences are processed by libuv or console. Useful in particular for enabling ConEmu support of ANSI X3.64 and Xterm 256 colors. Otherwise Windows10 consoles are usually detected automatically. State should be one of: "supported" or "unsupported".

This function is only meaningful on Windows systems. On Unix it is silently ignored.

Get the current state of whether console virtual terminal sequences are handled by libuv or the console. The return value is "supported" or "unsupported".

This function is not implemented on Unix, where it returns ENOTSUP.

Creates and initializes a new uv_udp_t. Returns the Lua userdata wrapping it. The actual socket is created lazily.

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

When specified, mmsgs determines the number of messages able to be received at one time via recvmmsg(2) (the allocated buffer will be sized to be able to fit the specified number of max size dgrams). Only has an effect on platforms that support recvmmsg(2).

Note: For backwards compatibility reasons, flags can also be a string or integer. When it is a string, it will be treated like the family key above. When it is an integer, it will be used directly as the flags parameter when calling uv_udp_init_ex.

Returns the handle's send queue size.

Returns the handle's send queue count.

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.

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.

Get the local IP and port of the UDP handle.

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

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

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

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

Set the multicast ttl.

ttl is an integer 1 through 255.

Set the multicast interface to send or receive data on.

Set broadcast on or off.

Set the time to live.

ttl is an integer 1 through 255.

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.

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

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" },
})

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.

Stop listening for incoming datagrams.

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.

Creates and initializes a new uv_fs_event_t. Returns the Lua userdata wrapping it.

Start the handle with the given callback, which will watch the specified path for changes.

Stop the handle, the callback will no longer be called.

Get the path being monitored by the handle.

Creates and initializes a new uv_fs_poll_t. Returns the Lua userdata wrapping it.

Check the file at path for changes every interval milliseconds.

Note: For maximum portability, use multi-second intervals. Sub-second intervals will not detect all changes on many file systems.

Stop the handle, the callback will no longer be called.

Get the path being monitored by the handle.

Equivalent to close(2).

Equivalent to open(2). Access flags may be an integer or one of: "r", "rs", "sr", "r+", "rs+", "sr+", "w", "wx", "xw", "w+", "wx+", "xw+", "a", "ax", "xa", "a+", "ax+", or "xa+". Note: On Windows, libuv uses CreateFileW and thus the file is always opened in binary mode. Because of this, the O_BINARY and O_TEXT flags are not supported.

Equivalent to preadv(2). Returns any data. An empty string indicates EOF.

If offset is nil or omitted, it will default to -1, which indicates 'use and update the current file offset.'

Note: When offset is >= 0, the current file offset will not be updated by the read.

Equivalent to unlink(2).

Equivalent to pwritev(2). Returns the number of bytes written.

If offset is nil or omitted, it will default to -1, which indicates 'use and update the current file offset.'

Note: When offset is >= 0, the current file offset will not be updated by the write.

Equivalent to mkdir(2).

Equivalent to mkdtemp(3).

Equivalent to mkstemp(3). Returns a temporary file handle and filename.

Equivalent to rmdir(2).

Equivalent to scandir(3), with a slightly different API. Returns a handle that the user can pass to uv.fs_scandir_next().

Note: This function can be used synchronously or asynchronously. The request userdata is always synchronously returned regardless of whether a callback is provided and the same userdata is passed to the callback if it is provided.

Called on a uv_fs_t returned by uv.fs_scandir() to get the next directory entry data as a name, type pair. When there are no more entries, nil is returned.

Note: This function only has a synchronous version. See uv.fs_opendir and its related functions for an asynchronous version.

Equivalent to stat(2).

Equivalent to fstat(2).

Equivalent to lstat(2).

Equivalent to rename(2).

Equivalent to fsync(2).

Equivalent to fdatasync(2).

Equivalent to ftruncate(2).

Limited equivalent to sendfile(2). Returns the number of bytes written.

Equivalent to access(2) on Unix. Windows uses GetFileAttributesW(). Access mode can be an integer or a string containing "R" or "W" or "X". Returns true or false indicating access permission.

Equivalent to chmod(2).

Equivalent to fchmod(2).

Equivalent to utime(2).

See [Constants][] for supported FS Modification Time constants.

Passing "now" or uv.constants.FS_UTIME_NOW as the atime or mtime sets the timestamp to the current time.

Passing nil, "omit", or uv.constants.FS_UTIME_OMIT as the atime or mtime leaves the timestamp untouched.

Equivalent to futimes(3).

See [Constants][] for supported FS Modification Time constants.

Passing "now" or uv.constants.FS_UTIME_NOW as the atime or mtime sets the timestamp to the current time.

Passing nil, "omit", or uv.constants.FS_UTIME_OMIT as the atime or mtime leaves the timestamp untouched.

Equivalent to lutimes(3).

See [Constants][] for supported FS Modification Time constants.

Passing "now" or uv.constants.FS_UTIME_NOW as the atime or mtime sets the timestamp to the current time.

Passing nil, "omit", or uv.constants.FS_UTIME_OMIT as the atime or mtime leaves the timestamp untouched.

Equivalent to link(2).

Equivalent to symlink(2). If the flags parameter is omitted, then the 3rd parameter will be treated as the callback.

Equivalent to readlink(2).

Equivalent to realpath(3).

Equivalent to chown(2).

Equivalent to fchown(2).

Equivalent to lchown(2).

Copies a file from path to new_path. If the flags parameter is omitted, then the 3rd parameter will be treated as the callback.

Opens path as a directory stream. Returns a handle that the user can pass to uv.fs_readdir(). The entries parameter defines the maximum number of entries that should be returned by each call to uv.fs_readdir().

Iterates over the directory stream luv_dir_t returned by a successful uv.fs_opendir() call. A table of data tables is returned where the number of entries n is equal to or less than the entries parameter used in the associated uv.fs_opendir() call.

Closes a directory stream returned by a successful uv.fs_opendir() call.

Equivalent to statfs(2).

Creates and initializes a new luv_work_ctx_t (not uv_work_t). work_callback is a Lua function or a string containing Lua code or bytecode dumped from a function. Returns the Lua userdata wrapping it.

Queues a work request which will run work_callback in a new Lua state in a thread from the threadpool with any additional arguments from .... Values returned from work_callback are passed to after_work_callback, which is called in the main loop thread.

Equivalent to getaddrinfo(3). Either node or service may be nil but not both.

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

See [Constants][] for supported socktype input and output values.

When protocol is set to 0 or nil, it will be automatically chosen based on the socket's domain and type. When protocol is specified as a string, it will be looked up using the getprotobyname(3) function. Examples: "ip", "icmp", "tcp", "udp", etc.

Equivalent to getnameinfo(3).

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

Creates and initializes a luv_thread_t (not uv_thread_t). Returns the Lua userdata wrapping it and asynchronously executes entry, which can be either a Lua function or a string containing Lua code or bytecode dumped from a function. Additional arguments ... are passed to the entry function and an optional options table may be provided. Currently accepted option fields are stack_size. Note: unsafe, please make sure the thread end of life before Lua state close.

Returns a boolean indicating whether two threads are the same. This function is equivalent to the __eq metamethod.

Sets the specified thread's affinity setting.

affinity must be a table where each of the keys are a CPU number and the values are booleans that represent whether the thread should be eligible to run on that CPU. If the length of the affinity table is not greater than or equal to uv.cpumask_size(), any CPU numbers missing from the table will have their affinity set to false. If setting the affinity of more than uv.cpumask_size() CPUs is desired, affinity must be an array-like table with no gaps, since #affinity will be used as the cpumask_size if it is greater than uv.cpumask_size().

If get_old_affinity is true, the previous affinity settings for the thread will be returned. Otherwise, true is returned after a successful call.

Note: Thread affinity setting is not atomic on Windows. Unsupported on macOS.

Gets the specified thread's affinity setting.

If mask_size is provided, it must be greater than or equal to uv.cpumask_size(). If the mask_size parameter is omitted, then the return of uv.cpumask_size() will be used. Returns an array-like table where each of the keys correspond to a CPU number and the values are booleans that represent whether the thread is eligible to run on that CPU.

Note: Thread affinity getting is not atomic on Windows. Unsupported on macOS.

Gets the CPU number on which the calling thread is running.

Note: The first CPU will be returned as the number 1, not 0. This allows for the number to correspond with the table keys used in uv.thread_getaffinity and uv.thread_setaffinity.

Sets the specified thread's scheduling priority setting. It requires elevated privilege to set specific priorities on some platforms.

The priority can be set to the following constants.

• uv.constants.THREADPRIORITYHIGHEST
• uv.constants.THREADPRIORITYABOVE_NORMAL
• uv.constants.THREADPRIORITYNORMAL
• uv.constants.THREADPRIORITYBELOW_NORMAL
• uv.constants.THREADPRIORITYLOWEST

Gets the thread's priority setting.

Retrieves the scheduling priority of the specified thread. The returned priority value is platform dependent.

For Linux, when schedule policy is SCHED_OTHER (default), priority is 0.

Returns the handle for the thread in which this is called.

Waits for the thread to finish executing its entry function.

Detaches a thread. Detached threads automatically release their resources upon termination, eliminating the need for the application to call uv.thread_join.

Sets the name of the current thread. Different platforms define different limits on the max number of characters a thread name can be: Linux, IBM i (16), macOS (64), Windows (32767), and NetBSD (32), etc. The name will be truncated if name is larger than the limit of the platform.

Gets the name of the thread specified by thread.

Pauses the thread in which this is called for a number of milliseconds.

Creates a new semaphore with the specified initial value. A semaphore is safe to share across threads. It represents an unsigned integer value that can incremented and decremented atomically but any attempt to make it negative will "wait" until the value can be decremented by another thread incrementing it.

The initial value must be a non-negative integer. Note: A semaphore must be shared between threads, any uv.sem_wait() on a single thread that blocks will deadlock.

Increments (unlocks) a semaphore, if the semaphore's value consequently becomes greater than zero then another thread blocked in a sem_wait call will be woken and proceed to decrement the semaphore.

Decrements (locks) a semaphore, if the semaphore's value is greater than zero then the value is decremented and the call returns immediately. If the semaphore's value is zero then the call blocks until the semaphore's value rises above zero or the call is interrupted by a signal.

The same as uv.sem_wait() but returns immediately if the semaphore is not available.

If the semaphore's value was decremented then true is returned, otherwise the semaphore has a value of zero and false is returned.

Returns the executable path.

Returns the current working directory.

Sets the current working directory with the string cwd.

Returns the title of the current process.

Sets the title of the current process with the string title.

Returns the current total system memory in bytes.

Returns the current free system memory in bytes.

Gets the amount of memory available to the process in bytes based on limits imposed by the OS. If there is no such constraint, or the constraint is unknown, 0 is returned. Note that it is not unusual for this value to be less than or greater than the total system memory.

Gets the amount of free memory that is still available to the process (in bytes). This differs from uv.get_free_memory() in that it takes into account any limits imposed by the OS. If there is no such constraint, or the constraint is unknown, the amount returned will be identical to uv.get_free_memory().

Returns the resident set size (RSS) for the current process.

Returns the resource usage.

Gets the resource usage measures for the calling thread.

Note Not supported on all platforms. May return ENOTSUP. On macOS and Windows not all fields are set (the unsupported fields are filled with zeroes).

Returns an estimate of the default amount of parallelism a program should use. Always returns a non-zero value.

On Linux, inspects the calling thread’s CPU affinity mask to determine if it has been pinned to specific CPUs.

On Windows, the available parallelism may be underreported on systems with more than 64 logical CPUs.

On other platforms, reports the number of CPUs that the operating system considers to be online.

Returns information about the CPU(s) on the system as a table of tables for each CPU found.

Returns the maximum size of the mask used for process/thread affinities, or ENOTSUP if affinities are not supported on the current platform.

Returns the user ID of the process. Note: This is not a libuv function and is not supported on Windows.

Returns the group ID of the process. Note: This is not a libuv function and is not supported on Windows.

Sets the user ID of the process with the integer id. Note: This is not a libuv function and is not supported on Windows.

Sets the group ID of the process with the integer id. Note: This is not a libuv function and is not supported on Windows.

Returns a current high-resolution time in nanoseconds as a number. This is relative to an arbitrary time in the past. It is not related to the time of day and therefore not subject to clock drift. The primary use is for measuring time between intervals.

Obtain the current system time from a high-resolution real-time or monotonic clock source. clock_id can be the string "monotonic" or "realtime".

The real-time clock counts from the UNIX epoch (1970-01-01) and is subject to time adjustments; it can jump back in time.

The monotonic clock counts from an arbitrary point in the past and never jumps back in time.

Returns the current system uptime in seconds.

Prints all handles associated with the main loop to stderr. The format is [flags] handle-type handle-address. Flags are R for referenced, A for active and I for internal. Note: This is not available on Windows. Warning: This function is meant for ad hoc debugging, there are no API/ABI stability guarantees.

The same as uv.print_all_handles() except only active handles are printed. Note: This is not available on Windows. Warning: This function is meant for ad hoc debugging, there are no API/ABI stability guarantees.

Used to detect what type of stream should be used with a given file descriptor fd. Usually this will be used during initialization to guess the type of the stdio streams.

Cross-platform implementation of gettimeofday(2). Returns the seconds and microseconds of a unix time as a pair.

Returns address information about the network interfaces on the system in a table. Each table key is the name of the interface while each associated value is an array of address information where fields are ip, family, netmask, internal, and mac.

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

IPv6-capable implementation of if_indextoname(3).

Retrieves a network interface identifier suitable for use in an IPv6 scoped address. On Windows, returns the numeric ifindex as a string. On all other platforms, uv.if_indextoname() is used.

Returns the load average as a triad. Not supported on Windows.

Returns system information.

Returns the hostname.

Returns the environment variable specified by name as string. The internal buffer size can be set by defining size. If omitted, LUAL_BUFFERSIZE is used. If the environment variable exceeds the storage available in the internal buffer, ENOBUFS is returned. If no matching environment variable exists, ENOENT is returned. Warning: This function is not thread-safe.

Sets the environmental variable specified by name with the string value. Warning: This function is not thread-safe.

Unsets the environmental variable specified by name. Warning: This function is not thread-safe.

Returns all environmental variables as a dynamic table of names associated with their corresponding values. Warning: This function is not thread-safe.

Returns the home directory. Warning: This function is not thread-safe.

Returns a temporary directory. Warning: This function is not thread-safe.

Gets a subset of the password file entry for the current effective uid (not the real uid). On Windows, uid, gid, and shell are set to nil.

Returns the current process ID.

Returns the parent process ID.

Returns the scheduling priority of the process specified by pid.

Sets the scheduling priority of the process specified by pid. The priority range is between -20 (high priority) and 19 (low priority).

Fills a string of length len with cryptographically strong random bytes acquired from the system CSPRNG. flags is reserved for future extension and must currently be nil or 0 or {}.

Short reads are not possible. When less than len random bytes are available, a non-zero error value is returned or passed to the callback. If the callback is omitted, this function is completed synchronously.

The synchronous version may block indefinitely when not enough entropy is available. The asynchronous version may not ever finish when the system is low on entropy.

Returns the libuv error message and error name (both in string form, see `err` and `name` in Error Handling) equivalent to the given platform dependent error code: POSIX error codes on Unix (the ones stored in errno), and Win32 error codes on Windows (those returned by GetLastError() or WSAGetLastError()).

Retrieve the amount of time the event loop has been idle in the kernel’s event provider (e.g. epoll_wait). The call is thread safe.

The return value is the accumulated time spent idle in the kernel’s event provider starting from when the [uv_loop_t][] was configured to collect the idle time.

Note: The event loop will not begin accumulating the event provider’s idle time until calling loop_configure with "metrics_idle_time".

Get the metrics table from current set of event loop metrics. It is recommended to retrieve these metrics in a prepare callback (see uv.new_prepare, uv.prepare_start) in order to make sure there are no inconsistencies with the metrics counters.

Get the length (in bytes) of a UTF-16 (or UCS-2) string utf16 value after converting it to WTF-8.

Convert UTF-16 (or UCS-2) string utf16 to WTF-8 string. The endianness of the UTF-16 (or UCS-2) string is assumed to be the same as the native endianness of the platform.

Get the length (in UTF-16 code units) of a WTF-8 wtf8 value after converting it to UTF-16 (or UCS-2). Note: The number of bytes needed for a UTF-16 (or UCS-2) string is <number of code units> * 2.

Convert WTF-8 string in wtf8 to UTF-16 (or UCS-2) string. The endianness of the UTF-16 (or UCS-2) string will be the same as the native endianness of the platform.