neovim/runtime/doc/luvref.txt

*luvref.txt*               Nvim


                    LUV REFERENCE MANUAL

								      *luvref*
This file documents the Lua bindings for the LibUV library which is used for
Nvim's event-loop and is accessible from Lua via |vim.loop| (e.g., |uv.version()|
is exposed as `vim.loop.version()`).

For information about this manual, see |luv-credits|.

For further examples, see https://github.com/luvit/luv/tree/master/examples.

==============================================================================
INTRODUCTION                                                  *luv* *luv-intro* *uv*

The luv (https://github.com/luvit/luv) project provides access to the
multi-platform support library libuv (https://github.com/libuv/libuv) in Lua
code. It was primarily developed for the luvit
(https://github.com/luvit/luvit) project as the built-in `uv` module, but can
be used in other Lua environments.

More information about the core libuv library can be found at the original
libuv documentation page (https://docs.libuv.org/).

TCP Echo Server Example ~

Here is a small example showing a TCP echo server:

    >lua
    local uv = vim.loop

    local server = uv.new_tcp()
    server:bind("127.0.0.1", 1337)
    server:listen(128, function (err)
      assert(not err, err)
      local client = uv.new_tcp()
      server:accept(client)
      client:read_start(function (err, chunk)
        assert(not err, err)
        if chunk then
          client:write(chunk)
        else
          client:shutdown()
          client:close()
        end
      end)
    end)
    print("TCP server listening at 127.0.0.1 port 1337")
    uv.run() -- an explicit run call is necessary outside of luvit
<

Module Layout ~

The luv library contains a single Lua module referred to hereafter as `uv` for
simplicity. This module consists mostly of functions with names corresponding
to their original libuv versions. For example, the libuv function
`uv_tcp_bind` has a luv version at |uv.tcp_bind()|. Currently, only two
non-function fields exists: `uv.constants` and `uv.errno`, which are tables.

Functions vs Methods ~

In addition to having simple functions, luv provides an optional method-style
API. For example, `uv.tcp_bind(server, host, port)` can alternatively be
called as `server:bind(host, port)` . Note that the first argument `server`
becomes the object and `tcp_` is removed from the function name. Method forms
are documented below where they exist.

Synchronous vs Asynchronous Functions ~

Functions that accept a callback are asynchronous. These functions may
immediately return results to the caller to indicate their initial status, but
their final execution is deferred until at least the next libuv loop
iteration. After completion, their callbacks are executed with any results
passed to it.

Functions that do not accept a callback are synchronous. These functions
immediately return their results to the caller.

Some (generally FS and DNS) functions can behave either synchronously or
asynchronously. If a callback is provided to these functions, they behave
asynchronously; if no callback is provided, they behave synchronously.

Pseudo-Types ~

Some unique types are defined. These are not actual types in Lua, but they are
used here to facilitate documenting consistent behavior:
- `fail`: an assertable `nil, string, string` tuple (see |luv-error-handling|)
- `callable`: a `function`; or a `table` or `userdata` with a `__call`
  metamethod
- `buffer`: a `string` or a sequential `table` of `string`s
- `threadargs`: variable arguments (`...`) of type `nil`, `boolean`, `number`,
  `string`, or `userdata`; number of arguments limited to 9.

==============================================================================
CONTENTS                                                          *luv-contents*

This documentation is mostly a retelling of the libuv API documentation
(https://docs.libuv.org/en/v1.x/api.html) within the context of luv's Lua API.
Low-level implementation details and unexposed C functions and types are not
documented here except for when they are relevant to behavior seen in the Lua
module.

- |luv-error-handling| — Error handling
- |luv-version-checking| — Version checking
- |uv_loop_t| — Event loop
- |uv_req_t| — Base request
- |uv_handle_t| — Base handle
  - |uv_timer_t| — Timer handle
  - |uv_prepare_t| — Prepare handle
  - |uv_check_t| — Check handle
  - |uv_idle_t| — Idle handle
  - |uv_async_t| — Async handle
  - |uv_poll_t| — Poll handle
  - |uv_signal_t| — Signal handle
  - |uv_process_t| — Process handle
  - |uv_stream_t| — Stream handle
    - |uv_tcp_t| — TCP handle
    - |uv_pipe_t| — Pipe handle
    - |uv_tty_t| — TTY handle
  - |uv_udp_t| — UDP handle
  - |uv_fs_event_t| — FS Event handle
  - |uv_fs_poll_t| — FS Poll handle
- |luv-file-system-operations| — File system operations
- |luv-thread-pool-work-scheduling| — Thread pool work scheduling
- |luv-dns-utility-functions| — DNS utility functions
- |luv-threading-and-synchronization-utilities| — Threading and
  synchronization utilities
- |luv-miscellaneous-utilities| — Miscellaneous utilities
- |luv-metrics-operations| — Metrics operations

==============================================================================
ERROR HANDLING                                              *luv-error-handling*

In libuv, errors are negative numbered constants; however, while those errors
are exposed through `uv.errno`, the functions used to handle them are not
exposed to luv users. Instead, if an internal error is encountered, the luv
function will return to the caller an assertable `nil, err, name` tuple.

- `nil` idiomatically indicates failure
- `err` is a string with the format `{name}: {message}`
  - `{name}` is the error name provided internally by `uv_err_name`
  - `{message}` is a human-readable message provided internally by
    `uv_strerror`
- `name` is the same string used to construct `err`

This tuple is referred to below as the `fail` pseudo-type.

When a function is called successfully, it will return either a value that is
relevant to the operation of the function, or the integer `0` to indicate
success, or sometimes nothing at all. These cases are documented below.

`uv.errno`                                                              *uv.errno*

A table value which exposes error constants as a map, where the key is the
error name (without the `UV_` prefix) and its value is a negative number.
See Libuv's "Error constants" page for further details.
(https://docs.libuv.org/en/v1.x/errors.html#error-constants)

- `E2BIG`: argument list too long.
- `EACCES`: permission denied.
- `EADDRINUSE`: address already in use.
- `EADDRNOTAVAIL`: address not available.
- `EAFNOSUPPORT`: address family not supported.
- `EAGAIN`: resource temporarily unavailable.
- `EAI_ADDRFAMILY`: address family not supported.
- `EAI_AGAIN`: temporary failure.
- `EAI_BADFLAGS`: bad ai_flags value.
- `EAI_BADHINTS`: invalid value for hints.
- `EAI_CANCELED`: request canceled.
- `EAI_FAIL`: permanent failure.
- `EAI_FAMILY`: ai_family not supported.
- `EAI_MEMORY`: out of memory.
- `EAI_NODATA`: no address.
- `EAI_NONAME`: unknown node or service.
- `EAI_OVERFLOW`: argument buffer overflow.
- `EAI_PROTOCOL`: resolved protocol is unknown.
- `EAI_SERVICE`: service not available for socket type.
- `EAI_SOCKTYPE`: socket type not supported.
- `EALREADY`: connection already in progress.
- `EBADF`: bad file descriptor.
- `EBUSY`: resource busy or locked.
- `ECANCELED`: operation canceled.
- `ECHARSET`: invalid Unicode character.
- `ECONNABORTED`: software caused connection abort.
- `ECONNREFUSED`: connection refused.
- `ECONNRESET`: connection reset by peer.
- `EDESTADDRREQ`: destination address required.
- `EEXIST`: file already exists.
- `EFAULT`: bad address in system call argument.
- `EFBIG`: file too large.
- `EHOSTUNREACH`: host is unreachable.
- `EINTR`: interrupted system call.
- `EINVAL`: invalid argument.
- `EIO`: i/o error.
- `EISCONN`: socket is already connected.
- `EISDIR`: illegal operation on a directory.
- `ELOOP`: too many symbolic links encountered.
- `EMFILE`: too many open files.
- `EMSGSIZE`: message too long.
- `ENAMETOOLONG`: name too long.
- `ENETDOWN`: network is down.
- `ENETUNREACH`: network is unreachable.
- `ENFILE`: file table overflow.
- `ENOBUFS`: no buffer space available.
- `ENODEV`: no such device.
- `ENOENT`: no such file or directory.
- `ENOMEM`: not enough memory.
- `ENONET`: machine is not on the network.
- `ENOPROTOOPT`: protocol not available.
- `ENOSPC`: no space left on device.
- `ENOSYS`: function not implemented.
- `ENOTCONN`: socket is not connected.
- `ENOTDIR`: not a directory.
- `ENOTEMPTY`: directory not empty.
- `ENOTSOCK`: socket operation on non-socket.
- `ENOTSUP`: operation not supported on socket.
- `EOVERFLOW`: value too large for defined data type.
- `EPERM`: operation not permitted.
- `EPIPE`: broken pipe.
- `EPROTO`: protocol error.
- `EPROTONOSUPPORT`: protocol not supported.
- `EPROTOTYPE`: protocol wrong type for socket.
- `ERANGE`: result too large.
- `EROFS`: read-only file system.
- `ESHUTDOWN`: cannot send after transport endpoint shutdown.
- `ESPIPE`: invalid seek.
- `ESRCH`: no such process.
- `ETIMEDOUT`: connection timed out.
- `ETXTBSY`: text file is busy.
- `EXDEV`: cross-device link not permitted.
- `UNKNOWN`: unknown error.
- `EOF`: end of file.
- `ENXIO`: no such device or address.
- `EMLINK`: too many links.
- `ENOTTY`: inappropriate ioctl for device.
- `EFTYPE`: inappropriate file type or format.
- `EILSEQ`: illegal byte sequence.
- `ESOCKTNOSUPPORT`: socket type not supported.

==============================================================================
VERSION CHECKING                                          *luv-version-checking*

uv.version()                                                      *uv.version()*

                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: `integer`

uv.version_string()                                        *uv.version_string()*

                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.

                Returns: `string`

==============================================================================
`uv_loop_t` — Event loop                                *luv-event-loop* *uv_loop_t*

The event loop is the central part of libuv's functionality. It takes care of
polling for I/O and scheduling callbacks to be run based on different sources
of events.

In luv, there is an implicit uv loop for every Lua state that loads the
library. You can use this library in an multi-threaded environment as long as
each thread has it's own Lua state with its corresponding own uv loop. This
loop is not directly exposed to users in the Lua module.

uv.loop_close()                                                *uv.loop_close()*

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

                Returns: `0` or `fail`

uv.run([{mode}])                                                      *uv.run()*

                Parameters:
                - `mode`: `string` or `nil` (default: `"default"`)

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

                Returns: `boolean` or `fail`

                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.

uv.loop_configure({option}, {...})                         *uv.loop_configure()*

                Parameters:
                - `option`: `string`
                - `...`: depends on `option`, see below

                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:

                    >lua
                    uv.loop_configure("block_signal", "sigprof")
<

                Returns: `0` or `fail`

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

uv.loop_mode()                                                  *uv.loop_mode()*

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

                Returns: `string` or `nil`

uv.loop_alive()                                                *uv.loop_alive()*

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

                Returns: `boolean` or `fail`

uv.stop()                                                            *uv.stop()*

                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.

                Returns: Nothing.

uv.backend_fd()                                                *uv.backend_fd()*

                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

                Returns: `integer` or `nil`

                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.

uv.backend_timeout()                                      *uv.backend_timeout()*

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

                Returns: `integer`

uv.now()                                                              *uv.now()*

                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.

                Returns: `integer`

                Note: Use |uv.hrtime()| if you need sub-millisecond
                granularity.

uv.update_time()                                              *uv.update_time()*

                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.

                Returns: Nothing.

uv.walk({callback})                                                  *uv.walk()*

                Parameters:
                - `callback`: `callable`
                  - `handle`: `userdata` for sub-type of |uv_handle_t|

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

                Returns: Nothing.

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

==============================================================================
`uv_req_t` — Base request                              *luv-base-request* *uv_req_t*

`uv_req_t` is the base type for all libuv request types.

uv.cancel({req})                                                   *uv.cancel()*

                > method form `req:cancel()`

                Parameters:
                - `req`: `userdata` for sub-type of |uv_req_t|

                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: `0` or `fail`

uv.req_get_type({req})                                       *uv.req_get_type()*

                > method form `req:get_type()`

                Parameters:
                - `req`: `userdata` for sub-type of |uv_req_t|

                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: `string, integer`

==============================================================================
`uv_handle_t` — Base handle                          *luv-base-handle* *uv_handle_t*

`uv_handle_t` is the base type for all libuv handle types. All API functions
defined here work with any handle type.

uv.is_active({handle})                                          *uv.is_active()*

                > method form `handle:is_active()`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|

                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: `boolean` or `fail`

uv.is_closing({handle})                                        *uv.is_closing()*

                > method form `handle:is_closing()`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|

                Returns `true` if the handle is closing or closed, `false`
                otherwise.

                Returns: `boolean` or `fail`

                Note: This function should only be used between the
                initialization of the handle and the arrival of the close
                callback.

uv.close({handle} [, {callback}])                                   *uv.close()*

                > method form `handle:close([callback])`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|
                - `callback`: `callable` or `nil`

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

                Returns: Nothing.

uv.ref({handle})                                                      *uv.ref()*

                > method form `handle:ref()`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|

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

                Returns: Nothing.

                See |luv-reference-counting|.

uv.unref({handle})                                                  *uv.unref()*

                > method form `handle:unref()`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|

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

See |luv-reference-counting|.

uv.has_ref({handle})                                              *uv.has_ref()*

                > method form `handle:has_ref()`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|

                Returns `true` if the handle referenced, `false` if not.

                Returns: `boolean` or `fail`

                See |luv-reference-counting|.

uv.send_buffer_size({handle} [, {size}])                 *uv.send_buffer_size()*

                > method form `handle:send_buffer_size([size])`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|
                - `size`: `integer` or `nil` (default: `0`)

                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.

                Returns:
                - `integer` or `fail` (if `size` is `nil` or `0`)
                - `0` or `fail` (if `size` is not `nil` and not `0`)

                Note: Linux will set double the size and return double the
                size of the original set value.

uv.recv_buffer_size({handle} [, {size}])                 *uv.recv_buffer_size()*

                > method form `handle:recv_buffer_size([size])`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|
                - `size`: `integer` or `nil` (default: `0`)

                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.

                Returns:
                - `integer` or `fail` (if `size` is `nil` or `0`)
                - `0` or `fail` (if `size` is not `nil` and not `0`)

                Note: Linux will set double the size and return double the
                size of the original set value.

uv.fileno({handle})                                                *uv.fileno()*

                > method form `handle:fileno()`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|

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

                Returns: `integer` or `fail`

                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.

uv.handle_get_type({handle})                              *uv.handle_get_type()*

                > method form `handle:get_type()`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|

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

                Returns: `string, integer`

==============================================================================
REFERENCE COUNTING                                      *luv-reference-counting*

The libuv event loop (if run in the default mode) will run until there are no
active and referenced handles left. The user can force the loop to exit early
by unreferencing handles which are active, for example by calling |uv.unref()|
after calling |uv.timer_start()|.

A handle can be referenced or unreferenced, the refcounting scheme doesn't use
a counter, so both operations are idempotent.

All handles are referenced when active by default, see |uv.is_active()| for a
more detailed explanation on what being active involves.

==============================================================================
`uv_timer_t` — Timer handle                          *luv-timer-handle* *uv_timer_t*

> |uv_handle_t| functions also apply.

Timer handles are used to schedule callbacks to be called in the future.

uv.new_timer()                                                  *uv.new_timer()*

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

                Returns: `uv_timer_t userdata` or `fail`

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

uv.timer_start({timer}, {timeout}, {repeat}, {callback})      *uv.timer_start()*

                > method form `timer:start(timeout, repeat, callback)`

                Parameters:
                - `timer`: `uv_timer_t userdata`
                - `timeout`: `integer`
                - `repeat`: `integer`
                - `callback`: `callable`

                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.

                Returns: `0` or `fail`

uv.timer_stop({timer})                                         *uv.timer_stop()*

                > method form `timer:stop()`

                Parameters:
                - `timer`: `uv_timer_t userdata`

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

                Returns: `0` or `fail`

uv.timer_again({timer})                                       *uv.timer_again()*

                > method form `timer:again()`

                Parameters:
                - `timer`: `uv_timer_t userdata`

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

                Returns: `0` or `fail`

uv.timer_set_repeat({timer}, {repeat})                   *uv.timer_set_repeat()*

                > method form `timer:set_repeat(repeat)`

                Parameters:
                - `timer`: `uv_timer_t userdata`
                - `repeat`: `integer`

                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.

                Returns: Nothing.

uv.timer_get_repeat({timer})                             *uv.timer_get_repeat()*

                > method form `timer:get_repeat()`

                Parameters:
                - `timer`: `uv_timer_t userdata`

                Get the timer repeat value.

                Returns: `integer`

uv.timer_get_due_in({timer})                             *uv.timer_get_due_in()*

                > method form `timer:get_due_in()`

                Parameters:
                - `timer`: `uv_timer_t userdata`

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

                Returns: `integer`

                Note: New in libuv version 1.40.0.

==============================================================================
`uv_prepare_t` — Prepare handle                  *luv-prepare-handle* *uv_prepare_t*

> |uv_handle_t| functions also apply.

Prepare handles will run the given callback once per loop iteration, right
before polling for I/O.

    >lua
    local prepare = uv.new_prepare()
    prepare:start(function()
      print("Before I/O polling")
    end)
<

uv.new_prepare()                                              *uv.new_prepare()*

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

                Returns: `uv_prepare_t userdata` or `fail`

uv.prepare_start({prepare}, {callback})                     *uv.prepare_start()*

                > method form `prepare:start(callback)`

                Parameters:
                - `prepare`: `uv_prepare_t userdata`
                - `callback`: `callable`

                Start the handle with the given callback.

                Returns: `0` or `fail`

uv.prepare_stop({prepare})                                   *uv.prepare_stop()*

                > method form `prepare:stop()`

                Parameters:
                - `prepare`: `uv_prepare_t userdata`

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

                Returns: `0` or `fail`

==============================================================================
`uv_check_t` — Check handle                          *luv-check-handle* *uv_check_t*

> |uv_handle_t| functions also apply.

Check handles will run the given callback once per loop iteration, right after
polling for I/O.

    >lua
    local check = uv.new_check()
    check:start(function()
      print("After I/O polling")
    end)
<

uv.new_check()                                                  *uv.new_check()*

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

                Returns: `uv_check_t userdata` or `fail`

uv.check_start({check}, {callback})                           *uv.check_start()*

                > method form `check:start(callback)`

                Parameters:
                - `check`: `uv_check_t userdata`
                - `callback`: `callable`

                Start the handle with the given callback.

                Returns: `0` or `fail`

uv.check_stop({check})                                         *uv.check_stop()*

                > method form `check:stop()`

                Parameters:
                - `check`: `uv_check_t userdata`

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

                Returns: `0` or `fail`

==============================================================================
`uv_idle_t` — Idle handle                              *luv-idle-handle* *uv_idle_t*

> |uv_handle_t| functions also apply.

Idle handles will run the given callback once per loop iteration, right before
the |uv_prepare_t| handles.

Note: The notable difference with prepare handles is that when there are
active idle handles, the loop will perform a zero timeout poll instead of
blocking for I/O.

WARNING: Despite the name, idle handles will get their callbacks called on
every loop iteration, not when the loop is actually "idle".

    >lua
    local idle = uv.new_idle()
    idle:start(function()
      print("Before I/O polling, no blocking")
    end)
<

uv.new_idle()                                                    *uv.new_idle()*

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

                Returns: `uv_idle_t userdata` or `fail`

uv.idle_start({idle}, {callback})                              *uv.idle_start()*

                > method form `idle:start(callback)`

                Parameters:
                - `idle`: `uv_idle_t userdata`
                - `callback`: `callable`

                Start the handle with the given callback.

                Returns: `0` or `fail`

uv.idle_stop({check})                                           *uv.idle_stop()*

                > method form `idle:stop()`

                Parameters:
                - `idle`: `uv_idle_t userdata`

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

                Returns: `0` or `fail`

==============================================================================
`uv_async_t` — Async handle                          *luv-async-handle* *uv_async_t*

> |uv_handle_t| functions also apply.

Async handles allow the user to "wakeup" the event loop and get a callback
called from another thread.

    >lua
    local async
    async = uv.new_async(function()
      print("async operation ran")
      async:close()
    end)

    async:send()
<

uv.new_async([{callback}])                                      *uv.new_async()*

                Parameters:
                - `callback`: `callable` or `nil`
                  - `...`: `threadargs` passed to/from
                    `uv.async_send(async, ...)`

                Creates and initializes a new |uv_async_t|. Returns the Lua
                userdata wrapping it. A `nil` callback is allowed.

                Returns: `uv_async_t userdata` or `fail`

                Note: Unlike other handle initialization functions, this
                immediately starts the handle.

uv.async_send({async}, {...})                                  *uv.async_send()*

                > method form `async:send(...)`

                Parameters:
                - `async`: `uv_async_t userdata`
                - `...`: `threadargs`

                Wakeup the event loop and call the async handle's callback.

                Returns: `0` or `fail`

                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.

==============================================================================
`uv_poll_t` — Poll handle                              *luv-poll-handle* *uv_poll_t*

> |uv_handle_t| functions also apply.

Poll handles are used to watch file descriptors for readability and
writability, similar to the purpose of poll(2)
(https://linux.die.net/man/2/poll).

The purpose of poll handles is to enable integrating external libraries that
rely on the event loop to signal it about the socket status changes, like
c-ares or libssh2. Using `uv_poll_t` for any other purpose is not recommended;
|uv_tcp_t|, |uv_udp_t|, etc. provide an implementation that is faster and more
scalable than what can be achieved with `uv_poll_t`, especially on Windows.

It is possible that poll handles occasionally signal that a file descriptor is
readable or writable even when it isn't. The user should therefore always be
prepared to handle EAGAIN or equivalent when it attempts to read from or write
to the fd.

It is not okay to have multiple active poll handles for the same socket, this
can cause libuv to busyloop or otherwise malfunction.

The user should not close a file descriptor while it is being polled by an
active poll handle. This can cause the handle to report an error, but it might
also start polling another socket. However the fd can be safely closed
immediately after a call to |uv.poll_stop()| or |uv.close()|.

Note: On windows only sockets can be polled with poll handles. On Unix any
file descriptor that would be accepted by poll(2) can be used.

uv.new_poll({fd})                                                *uv.new_poll()*

                Parameters:
                - `fd`: `integer`

                Initialize the handle using a file descriptor.

                The file descriptor is set to non-blocking mode.

                Returns: `uv_poll_t userdata` or `fail`

uv.new_socket_poll({fd})                                  *uv.new_socket_poll()*

                Parameters:
                - `fd`: `integer`

                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.

                Returns: `uv_poll_t userdata` or `fail`

uv.poll_start({poll}, {events}, {callback})                    *uv.poll_start()*

                > method form `poll:start(events, callback)`

                Parameters:
                - `poll`: `uv_poll_t userdata`
                - `events`: `string` or `nil` (default: `"rw"`)
                - `callback`: `callable`
                  - `err`: `nil` or `string`
                  - `events`: `string` or `nil`

                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.

                Returns: `0` or `fail`

                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.

uv.poll_stop({poll})                                            *uv.poll_stop()*

                > method form `poll:stop()`

                Parameters:
                - `poll`: `uv_poll_t userdata`

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

                Returns: `0` or `fail`

==============================================================================
`uv_signal_t` — Signal handle                      *luv-signal-handle* *uv_signal_t*

> |uv_handle_t| functions also apply.

Signal handles implement Unix style signal handling on a per-event loop bases.

Windows Notes:

Reception of some signals is emulated on Windows:
  - SIGINT is normally delivered when the user presses CTRL+C. However, like
    on Unix, it is not generated when terminal raw mode is enabled.
  - SIGBREAK is delivered when the user pressed CTRL + BREAK.
  - SIGHUP is generated when the user closes the console window. On SIGHUP the
    program is given approximately 10 seconds to perform cleanup. After that
    Windows will unconditionally terminate it.
  - SIGWINCH is raised whenever libuv detects that the console has been
    resized. SIGWINCH is emulated by libuv when the program uses a uv_tty_t
    handle to write to the console. SIGWINCH may not always be delivered in a
    timely manner; libuv will only detect size changes when the cursor is
    being moved. When a readable |uv_tty_t| handle is used in raw mode,
    resizing the console buffer will also trigger a SIGWINCH signal.
  - Watchers for other signals can be successfully created, but these signals
    are never received. These signals are: SIGILL, SIGABRT, SIGFPE, SIGSEGV,
    SIGTERM and SIGKILL.
  - Calls to raise() or abort() to programmatically raise a signal are not
    detected by libuv; these will not trigger a signal watcher.

Unix Notes:

  - SIGKILL and SIGSTOP are impossible to catch.
  - Handling SIGBUS, SIGFPE, SIGILL or SIGSEGV via libuv results into
    undefined behavior.
  - SIGABRT will not be caught by libuv if generated by abort(), e.g. through
    assert().
  - On Linux SIGRT0 and SIGRT1 (signals 32 and 33) are used by the NPTL
    pthreads library to manage threads. Installing watchers for those signals
    will lead to unpredictable behavior and is strongly discouraged. Future
    versions of libuv may simply reject them.

    >lua
    -- Create a new signal handler
    local signal = uv.new_signal()
    -- Define a handler function
    uv.signal_start(signal, "sigint", function(signal)
      print("got " .. signal .. ", shutting down")
      os.exit(1)
    end)
<

uv.new_signal()                                                *uv.new_signal()*

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

                Returns: `uv_signal_t userdata` or `fail`

uv.signal_start({signal}, {signum}, {callback})              *uv.signal_start()*

                > method form `signal:start(signum, callback)`

                Parameters:
                - `signal`: `uv_signal_t userdata`
                - `signum`: `integer` or `string`
                - `callback`: `callable`
                  - `signum`: `string`

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

                Returns: `0` or `fail`
                                                     *uv.signal_start_oneshot()*
uv.signal_start_oneshot({signal}, {signum}, {callback})

                > method form `signal:start_oneshot(signum, callback)`

                Parameters:
                - `signal`: `uv_signal_t userdata`
                - `signum`: `integer` or `string`
                - `callback`: `callable`
                  - `signum`: `string`

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

                Returns: `0` or `fail`

uv.signal_stop({signal})                                      *uv.signal_stop()*

                > method form `signal:stop()`

                Parameters:
                - `signal`: `uv_signal_t userdata`

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

                Returns: `0` or `fail`

==============================================================================
`uv_process_t` — Process handle                  *luv-process-handle* *uv_process_t*

> |uv_handle_t| functions also apply.

Process handles will spawn a new process and allow the user to control it and
establish communication channels with it using streams.

uv.disable_stdio_inheritance()                  *uv.disable_stdio_inheritance()*

                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.

                Returns: Nothing.

                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.

uv.spawn({path}, {options}, {on_exit})                              *uv.spawn()*

                Parameters:
                - `path`: `string`
                - `options`: `table` (see below)
                - `on_exit`: `callable`
                  - `code`: `integer`
                  - `signal`: `integer`

                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.

                    >lua
                    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)
<
                                                              *uv.spawn-options*
                The `options` table accepts the following fields:

                  - `options.args` - Command line arguments as a list of
                    string. The first string should be the path to the
                    program. On Windows, this uses CreateProcess which
                    concatenates the arguments into a string. This can cause
                    some strange errors. (See `options.verbatim` below for
                    Windows.)
                  - `options.stdio` - Set the file descriptors that will be
                    made available to the child process. The convention is
                    that the first entries are stdin, stdout, and stderr.
                    (Note: On Windows, file descriptors after the third are
                    available to the child process only if the child processes
                    uses the MSVCRT runtime.)
                  - `options.env` - Set environment variables for the new
                    process.
                  - `options.cwd` - Set the current working directory for the
                    sub-process.
                  - `options.uid` - Set the child process' user id.
                  - `options.gid` - Set the child process' group id.
                  - `options.verbatim` - If true, do not wrap any arguments in
                    quotes, or perform any other escaping, when converting the
                    argument list into a command line string. This option is
                    only meaningful on Windows systems. On Unix it is silently
                    ignored.
                  - `options.detached` - If true, spawn the child process in a
                    detached state - this will make it a process group leader,
                    and will effectively enable the child to keep running
                    after the parent exits. Note that the child process will
                    still keep the parent's event loop alive unless the parent
                    process calls |uv.unref()| on the child's process handle.
                  - `options.hide` - If true, hide the subprocess console
                    window that would normally be created. This option is only
                    meaningful on Windows systems. On Unix it is silently
                    ignored.

                The `options.stdio` entries can take many shapes.

                  - If they are numbers, then the child process inherits that
                    same zero-indexed fd from the parent process.
                  - If |uv_stream_t| handles are passed in, those are used as
                    a read-write pipe or inherited stream depending if the
                    stream has a valid fd.
                  - Including `nil` placeholders means to ignore that fd in
                    the child process.

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

                Returns: `uv_process_t userdata`, `integer`

uv.process_kill({process}, {signum})                         *uv.process_kill()*

                > method form `process:kill(signum)`

                Parameters:
                - `process`: `uv_process_t userdata`
                - `signum`: `integer` or `string`

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

                Returns: `0` or `fail`

uv.kill({pid}, {signum})                                             *uv.kill()*

                Parameters:
                - `pid`: `integer`
                - `signum`: `integer` or `string`

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

                Returns: `0` or `fail`

uv.process_get_pid({process})                             *uv.process_get_pid()*

                > method form `process:get_pid()`

                Parameters:
                - `process`: `uv_process_t userdata`

                Returns the handle's pid.

                Returns: `integer`

==============================================================================
`uv_stream_t` — Stream handle                      *luv-stream-handle* *uv_stream_t*

> |uv_handle_t| functions also apply.

Stream handles provide an abstraction of a duplex communication channel.
`uv_stream_t` is an abstract type, libuv provides 3 stream implementations
in the form of |uv_tcp_t|, |uv_pipe_t| and |uv_tty_t|.

uv.shutdown({stream} [, {callback}])                             *uv.shutdown()*

                > method form `stream:shutdown([callback])`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|
                - `callback`: `callable` or `nil`
                  - `err`: `nil` or `string`

                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.

                Returns: `uv_shutdown_t userdata` or `fail`

uv.listen({stream}, {backlog}, {callback})                         *uv.listen()*

                > method form `stream:listen(backlog, callback)`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|
                - `backlog`: `integer`
                - `callback`: `callable`
                  - `err`: `nil` or `string`

                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.

                Returns: `0` or `fail`

uv.accept({stream}, {client_stream})                               *uv.accept()*

                > method form `stream:accept(client_stream)`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|
                - `client_stream`: `userdata` for sub-type of |uv_stream_t|

                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.

                Returns: `0` or `fail`

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

uv.read_start({stream}, {callback})                            *uv.read_start()*

                > method form `stream:read_start(callback)`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|
                - `callback`: `callable`
                  - `err`: `nil` or `string`
                  - `data`: `string` or `nil`

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

                Returns: `0` or `fail`

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

uv.read_stop({stream})                                          *uv.read_stop()*

                > method form `stream:read_stop()`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|

                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.

                Returns: `0` or `fail`

uv.write({stream}, {data} [, {callback}])                           *uv.write()*

                > method form `stream:write(data, [callback])`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|
                - `data`: `buffer`
                - `callback`: `callable` or `nil`
                  - `err`: `nil` or `string`

                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.

                Returns: `uv_write_t userdata` or `fail`

uv.write2({stream}, {data}, {send_handle} [, {callback}])          *uv.write2()*

                > method form `stream:write2(data, send_handle, [callback])`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|
                - `data`: `buffer`
                - `send_handle`: `userdata` for sub-type of |uv_stream_t|
                - `callback`: `callable` or `nil`
                  - `err`: `nil` or `string`

                Extended write function for sending handles over a pipe. The
                pipe must be initialized with `ipc` option `true`.

                Returns: `uv_write_t userdata` or `fail`

                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.

uv.try_write({stream}, {data})                                  *uv.try_write()*

                > method form `stream:try_write(data)`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|
                - `data`: `buffer`

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

                Returns: `integer` or `fail`

uv.try_write2({stream}, {data}, {send_handle})                 *uv.try_write2()*

                > method form `stream:try_write2(data, send_handle)`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|
                - `data`: `buffer`
                - `send_handle`: `userdata` for sub-type of |uv_stream_t|

                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: `integer` or `fail`

uv.is_readable({stream})                                      *uv.is_readable()*

                > method form `stream:is_readable()`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|

                Returns `true` if the stream is readable, `false` otherwise.

                Returns: `boolean`

uv.is_writable({stream})                                      *uv.is_writable()*

                > method form `stream:is_writable()`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|

                Returns `true` if the stream is writable, `false` otherwise.

                Returns: `boolean`

uv.stream_set_blocking({stream}, {blocking})          *uv.stream_set_blocking()*

                > method form `stream:set_blocking(blocking)`

                Parameters:
                - `stream`: `userdata` for sub-type of |uv_stream_t|
                - `blocking`: `boolean`

                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.

                Returns: `0` or `fail`

                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.

uv.stream_get_write_queue_size()              *uv.stream_get_write_queue_size()*

                > method form `stream:get_write_queue_size()`

                Returns the stream's write queue size.

                Returns: `integer`

==============================================================================
`uv_tcp_t` — TCP handle                                  *luv-tcp-handle* *uv_tcp_t*

> |uv_handle_t| and |uv_stream_t| functions also apply.

TCP handles are used to represent both TCP streams and servers.

uv.new_tcp([{flags}])                                             *uv.new_tcp()*

                Parameters:
                - `flags`: `string` or `nil`

                Creates and initializes a new |uv_tcp_t|. Returns the Lua
                userdata wrapping it. Flags may be a family string: `"unix"`,
                `"inet"`, `"inet6"`, `"ipx"`, `"netlink"`, `"x25"`, `"ax25"`,
                `"atmpvc"`, `"appletalk"`, or `"packet"`.

                Returns: `uv_tcp_t userdata` or `fail`

uv.tcp_open({tcp}, {sock})                                       *uv.tcp_open()*

                > method form `tcp:open(sock)`

                Parameters:
                - `tcp`: `uv_tcp_t userdata`
                - `sock`: `integer`

                Open an existing file descriptor or SOCKET as a TCP handle.

                Returns: `0` or `fail`

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

uv.tcp_nodelay({tcp}, {enable})                               *uv.tcp_nodelay()*

                > method form `tcp:nodelay(enable)`

                Parameters:
                - `tcp`: `uv_tcp_t userdata`
                - `enable`: `boolean`

                Enable / disable Nagle's algorithm.

                Returns: `0` or `fail`

uv.tcp_keepalive({tcp}, {enable} [, {delay}])               *uv.tcp_keepalive()*

                > method form `tcp:keepalive(enable, [delay])`

                Parameters:
                - `tcp`: `uv_tcp_t userdata`
                - `enable`: `boolean`
                - `delay`: `integer` or `nil`

                Enable / disable TCP keep-alive. `delay` is the initial delay
                in seconds, ignored when enable is `false`.

                Returns: `0` or `fail`

uv.tcp_simultaneous_accepts({tcp}, {enable})     *uv.tcp_simultaneous_accepts()*

                > method form `tcp:simultaneous_accepts(enable)`

                Parameters:
                - `tcp`: `uv_tcp_t userdata`
                - `enable`: `boolean`

                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.

                Returns: `0` or `fail`

uv.tcp_bind({tcp}, {host}, {port} [, {flags}])                   *uv.tcp_bind()*

                > method form `tcp:bind(host, port, [flags])`

                Parameters:
                - `tcp`: `uv_tcp_t userdata`
                - `host`: `string`
                - `port`: `integer`
                - `flags`: `table` or `nil`
                  - `ipv6only`: `boolean`

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

                Returns: `0` or `fail`

uv.tcp_getpeername({tcp})                                 *uv.tcp_getpeername()*

                > method form `tcp:getpeername()`

                Parameters:
                - `tcp`: `uv_tcp_t userdata`

                Get the address of the peer connected to the handle.

                Returns: `table` or `fail`
                - `ip` : `string`
                - `family` : `string`
                - `port` : `integer`

uv.tcp_getsockname({tcp})                                 *uv.tcp_getsockname()*

                > method form `tcp:getsockname()`

                Parameters:
                - `tcp`: `uv_tcp_t userdata`

                Get the current address to which the handle is bound.

                Returns: `table` or `fail`
                - `ip` : `string`
                - `family` : `string`
                - `port` : `integer`

uv.tcp_connect({tcp}, {host}, {port}, {callback})             *uv.tcp_connect()*

                > method form `tcp:connect(host, port, callback)`

                Parameters:
                - `tcp`: `uv_tcp_t userdata`
                - `host`: `string`
                - `port`: `integer`
                - `callback`: `callable`
                   - `err`: `nil` or `string`

                Establish an IPv4 or IPv6 TCP connection.

                Returns: `uv_connect_t userdata` or `fail`

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

uv.tcp_write_queue_size({tcp})                       *uv.tcp_write_queue_size()*

                > method form `tcp:write_queue_size()`

                DEPRECATED: Please use |uv.stream_get_write_queue_size()|
                instead.

uv.tcp_close_reset([{callback}])                          *uv.tcp_close_reset()*

                > method form `tcp:close_reset([callback])`

                Parameters:
                - `tcp`: `uv_tcp_t userdata`
                - `callback`: `callable` or `nil`

                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.

                Returns: `0` or `fail`
                                                               *uv.socketpair()*
uv.socketpair([{socktype}, [{protocol}, [{flags1}, [{flags2}]]]])

                Parameters:
                - `socktype`: `string`, `integer` or `nil` (default: `stream`)
                - `protocol`: `string`, `integer` or `nil` (default: 0)
                - `flags1`: `table` or `nil`
                  - `nonblock`: `boolean` (default: `false`)
                - `flags2`: `table` or `nil`
                  - `nonblock`: `boolean` (default: `false`)

                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.

                When specified as a string, `socktype` must be one of
                `"stream"`, `"dgram"`, `"raw"`, `"rdm"`, or `"seqpacket"`.

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

                Returns: `table` or `fail`
                - `[1, 2]` : `integer` (file descriptor)

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

==============================================================================
`uv_pipe_t` — Pipe handle                              *luv-pipe-handle* *uv_pipe_t*

> |uv_handle_t| and |uv_stream_t| functions also apply.

Pipe handles provide an abstraction over local domain sockets on Unix and
named pipes on Windows.

    >lua
    local pipe = uv.new_pipe(false)

    pipe:bind('/tmp/sock.test')

    pipe:listen(128, function()
      local client = uv.new_pipe(false)
      pipe:accept(client)
      client:write("hello!\n")
      client:close()
    end)
<

uv.new_pipe([{ipc}])                                             *uv.new_pipe()*

                Parameters:
                - `ipc`: `boolean` or `nil` (default: `false`)

                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.

                Returns: `uv_pipe_t userdata` or `fail`

uv.pipe_open({pipe}, {fd})                                      *uv.pipe_open()*

                > method form `pipe:open(fd)`

                Parameters:
                - `pipe`: `uv_pipe_t userdata`
                - `fd`: `integer`

                Open an existing file descriptor or |uv_handle_t| as a
                pipe.

                Returns: `0` or `fail`

                Note: The file descriptor is set to non-blocking mode.

uv.pipe_bind({pipe}, {name})                                    *uv.pipe_bind()*

                > method form `pipe:bind(name)`

                Parameters:
                - `pipe`: `uv_pipe_t userdata`
                - `name`: `string`

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

                Returns: `0` or `fail`

                Note: Paths on Unix get truncated to
                sizeof(sockaddr_un.sun_path) bytes, typically between 92 and
                108 bytes.

uv.pipe_connect({pipe}, {name} [, {callback}])               *uv.pipe_connect()*

                > method form `pipe:connect(name, [callback])`

                Parameters:
                - `pipe`: `uv_pipe_t userdata`
                - `name`: `string`
                - `callback`: `callable` or `nil`
                  - `err`: `nil` or `string`

                Connect to the Unix domain socket or the named pipe.

                Returns: `uv_connect_t userdata` or `fail`

                Note: Paths on Unix get truncated to
                sizeof(sockaddr_un.sun_path) bytes, typically between 92 and
                108 bytes.

uv.pipe_getsockname({pipe})                              *uv.pipe_getsockname()*

                > method form `pipe:getsockname()`

                Parameters:
                - `pipe`: `uv_pipe_t userdata`

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

                Returns: `string` or `fail`

uv.pipe_getpeername({pipe})                              *uv.pipe_getpeername()*

                > method form `pipe:getpeername()`

                Parameters:
                - `pipe`: `uv_pipe_t userdata`

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

                Returns: `string` or `fail`

uv.pipe_pending_instances({pipe}, {count})         *uv.pipe_pending_instances()*

                > method form `pipe:pending_instances(count)`

                Parameters:
                - `pipe`: `uv_pipe_t userdata`
                - `count`: `integer`

                Set the number of pending pipe instance handles when the pipe
                server is waiting for connections.

                Returns: Nothing.

                Note: This setting applies to Windows only.

uv.pipe_pending_count({pipe})                          *uv.pipe_pending_count()*

                > method form `pipe:pending_count()`

                Parameters:
                - `pipe`: `uv_pipe_t userdata`

                Returns the pending pipe count for the named pipe.

                Returns: `integer`

uv.pipe_pending_type({pipe})                            *uv.pipe_pending_type()*

                > method form `pipe:pending_type()`

                Parameters:
                - `pipe`: `uv_pipe_t userdata`

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

                Returns: `string`

uv.pipe_chmod({pipe}, {flags})                                 *uv.pipe_chmod()*

                > method form `pipe:chmod(flags)`

                Parameters:
                - `pipe`: `uv_pipe_t userdata`
                - `flags`: `string`

                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.

                Returns: `0` or `fail`

uv.pipe({read_flags}, {write_flags})                                 *uv.pipe()*

                Parameters:
                - `read_flags`: `table` or `nil`
                  - `nonblock`: `boolean` (default: `false`)
                - `write_flags`: `table` or `nil`
                  - `nonblock`: `boolean` (default: `false`)

                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.

                Returns: `table` or `fail`
                - `read` : `integer` (file descriptor)
                - `write` : `integer` (file descriptor)

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

==============================================================================
`uv_tty_t` — TTY handle                                  *luv-tty-handle* *uv_tty_t*

> |uv_handle_t| and |uv_stream_t| functions also apply.

TTY handles represent a stream for the console.

    >lua
    -- Simple echo program
    local stdin = uv.new_tty(0, true)
    local stdout = uv.new_tty(1, false)

    stdin:read_start(function (err, data)
      assert(not err, err)
      if data then
        stdout:write(data)
      else
        stdin:close()
        stdout:close()
      end
    end)
<

uv.new_tty({fd}, {readable})                                      *uv.new_tty()*

                Parameters:
                - `fd`: `integer`
                - `readable`: `boolean`

                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.

                Returns: `uv_tty_t userdata` or `fail`

                Note: If reopening the TTY fails, libuv falls back to blocking
                writes.

uv.tty_set_mode({tty}, {mode})                               *uv.tty_set_mode()*

                > method form `tty:set_mode(mode)`

                Parameters:
                - `tty`: `uv_tty_t userdata`
                - `mode`: `integer`

                Set the TTY using the specified terminal mode.

                Parameter `mode` is a C enum with the following values:

                  - 0 - UV_TTY_MODE_NORMAL: Initial/normal terminal mode
                  - 1 - UV_TTY_MODE_RAW: Raw input mode (On Windows,
                    ENABLE_WINDOW_INPUT is also enabled)
                  - 2 - UV_TTY_MODE_IO: Binary-safe I/O mode for IPC
                    (Unix-only)

                Returns: `0` or `fail`

uv.tty_reset_mode()                                        *uv.tty_reset_mode()*

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

                Returns: `0` or `fail`

uv.tty_get_winsize({tty})                                 *uv.tty_get_winsize()*

                > method form `tty:get_winsize()`

                Parameters:
                - `tty`: `uv_tty_t userdata`

                Gets the current Window width and height.

                Returns: `integer, integer` or `fail`

uv.tty_set_vterm_state({state})                       *uv.tty_set_vterm_state()*

                Parameters:
                - `state`: `string`

                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.

                Returns: none

uv.tty_get_vterm_state()                              *uv.tty_get_vterm_state()*

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

                Returns: `string` or `fail`

==============================================================================
`uv_udp_t` — UDP handle                                  *luv-udp-handle* *uv_udp_t*

> |uv_handle_t| functions also apply.

UDP handles encapsulate UDP communication for both clients and servers.

uv.new_udp([{flags}])                                             *uv.new_udp()*

                Parameters:
                - `flags`: `table` or `nil`
                  - `family`: `string` or `nil`
                  - `mmsgs`: `integer` or `nil` (default: `1`)

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

                When specified, `family` must be one of `"unix"`, `"inet"`,
                `"inet6"`, `"ipx"`, `"netlink"`, `"x25"`, `"ax25"`,
                `"atmpvc"`, `"appletalk"`, or `"packet"`.

                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: `uv_udp_t userdata` or `fail`

uv.udp_get_send_queue_size()                      *uv.udp_get_send_queue_size()*

                > method form `udp:get_send_queue_size()`

                Returns the handle's send queue size.

                Returns: `integer`

uv.udp_get_send_queue_count()                    *uv.udp_get_send_queue_count()*

                > method form `udp:get_send_queue_count()`

                Returns the handle's send queue count.

                Returns: `integer`

uv.udp_open({udp}, {fd})                                         *uv.udp_open()*

                > method form `udp:open(fd)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `fd`: `integer`

                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.

                Returns: `0` or `fail`

uv.udp_bind({udp}, {host}, {port} [, {flags}])                   *uv.udp_bind()*

                > method form `udp:bind(host, port, [flags])`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `host`: `string`
                - `port`: `number`
                - `flags`: `table` or `nil`
                  - `ipv6only`: `boolean`
                  - `reuseaddr`: `boolean`

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

                Returns: `0` or `fail`

uv.udp_getsockname({udp})                                 *uv.udp_getsockname()*

                > method form `udp:getsockname()`

                Parameters:
                - `udp`: `uv_udp_t userdata`

                Get the local IP and port of the UDP handle.

                Returns: `table` or `fail`
                - `ip` : `string`
                - `family` : `string`
                - `port` : `integer`

uv.udp_getpeername({udp})                                 *uv.udp_getpeername()*

                > method form `udp:getpeername()`

                Parameters:
                - `udp`: `uv_udp_t userdata`

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

                Returns: `table` or `fail`
                - `ip` : `string`
                - `family` : `string`
                - `port` : `integer`

                                                       *uv.udp_set_membership()*
uv.udp_set_membership({udp}, {multicast_addr}, {interface_addr}, {membership})

                > method form
                > `udp:set_membership(multicast_addr, interface_addr, membership)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `multicast_addr`: `string`
                - `interface_addr`: `string` or `nil`
                - `membership`: `string`

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

                Returns: `0` or `fail`

                                                *uv.udp_set_source_membership()*
uv.udp_set_source_membership({udp}, {multicast_addr}, {interface_addr}, {source_addr}, {membership})

                > method form
                > `udp:set_source_membership(multicast_addr, interface_addr, source_addr, membership)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `multicast_addr`: `string`
                - `interface_addr`: `string` or `nil`
                - `source_addr`: `string`
                - `membership`: `string`

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

                Returns: `0` or `fail`

uv.udp_set_multicast_loop({udp}, {on})             *uv.udp_set_multicast_loop()*

                > method form `udp:set_multicast_loop(on)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `on`: `boolean`

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

                Returns: `0` or `fail`

uv.udp_set_multicast_ttl({udp}, {ttl})              *uv.udp_set_multicast_ttl()*

                > method form `udp:set_multicast_ttl(ttl)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `ttl`: `integer`

                Set the multicast ttl.

                `ttl` is an integer 1 through 255.

                Returns: `0` or `fail`

                                              *uv.udp_set_multicast_interface()*
uv.udp_set_multicast_interface({udp}, {interface_addr})

                > method form `udp:set_multicast_interface(interface_addr)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `interface_addr`: `string`

                Set the multicast interface to send or receive data on.

                Returns: `0` or `fail`

uv.udp_set_broadcast({udp}, {on})                       *uv.udp_set_broadcast()*

                > method form `udp:set_broadcast(on)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `on`: `boolean`

                Set broadcast on or off.

                Returns: `0` or `fail`

uv.udp_set_ttl({udp}, {ttl})                                  *uv.udp_set_ttl()*

                > method form `udp:set_ttl(ttl)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `ttl`: `integer`

                Set the time to live.

                `ttl` is an integer 1 through 255.

                Returns: `0` or `fail`

uv.udp_send({udp}, {data}, {host}, {port}, {callback})           *uv.udp_send()*

                > method form `udp:send(data, host, port, callback)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `data`: `buffer`
                - `host`: `string`
                - `port`: `integer`
                - `callback`: `callable`
                  - `err`: `nil` or `string`

                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.

                Returns: `uv_udp_send_t userdata` or `fail`

uv.udp_try_send({udp}, {data}, {host}, {port})               *uv.udp_try_send()*

                > method form `udp:try_send(data, host, port)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `data`: `buffer`
                - `host`: `string`
                - `port`: `integer`

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

                Returns: `integer` or `fail`

uv.udp_recv_start({udp}, {callback})                       *uv.udp_recv_start()*

                > method form `udp:recv_start(callback)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `callback`: `callable`
                  - `err`: `nil` or `string`
                  - `data`: `string` or `nil`
                  - `addr`: `table` or `nil`
                    - `ip`: `string`
                    - `port`: `integer`
                    - `family`: `string`
                  - `flags`: `table`
                    - `partial`: `boolean` or `nil`
                    - `mmsg_chunk`: `boolean` or `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.

                Returns: `0` or `fail`

uv.udp_recv_stop({udp})                                     *uv.udp_recv_stop()*

                > method form `udp:recv_stop()`

                Parameters:
                - `udp`: `uv_udp_t userdata`

                Stop listening for incoming datagrams.

                Returns: `0` or `fail`

uv.udp_connect({udp}, {host}, {port})                         *uv.udp_connect()*

                > method form `udp:connect(host, port)`

                Parameters:
                - `udp`: `uv_udp_t userdata`
                - `host`: `string`
                - `port`: `integer`

                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.

                Returns: `0` or `fail`

==============================================================================
`uv_fs_event_t` — FS Event handle              *luv-fs-event-handle* *uv_fs_event_t*

> |uv_handle_t| functions also apply.

FS Event handles allow the user to monitor a given path for changes, for
example, if the file was renamed or there was a generic change in it. This
handle uses the best backend for the job on each platform.

uv.new_fs_event()                                            *uv.new_fs_event()*

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

                Returns: `uv_fs_event_t userdata` or `fail`

uv.fs_event_start({fs_event}, {path}, {flags}, {callback}) *uv.fs_event_start()*

                > method form `fs_event:start(path, flags, callback)`

                Parameters:
                - `fs_event`: `uv_fs_event_t userdata`
                - `path`: `string`
                - `flags`: `table`
                  - `watch_entry`: `boolean` or `nil` (default: `false`)
                  - `stat`: `boolean` or `nil` (default: `false`)
                  - `recursive`: `boolean` or `nil` (default: `false`)
                - `callback`: `callable`
                  - `err`: `nil` or `string`
                  - `filename`: `string`
                  - `events`: `table`
                    - `change`: `boolean` or `nil`
                    - `rename`: `boolean` or `nil`

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

                Returns: `0` or `fail`

uv.fs_event_stop()                                          *uv.fs_event_stop()*

                > method form `fs_event:stop()`

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

                Returns: `0` or `fail`

uv.fs_event_getpath()                                    *uv.fs_event_getpath()*

                > method form `fs_event:getpath()`

                Get the path being monitored by the handle.

                Returns: `string` or `fail`

==============================================================================
`uv_fs_poll_t` — FS Poll handle                  *luv-fs-poll-handle* *uv_fs_poll_t*

> |uv_handle_t| functions also apply.

FS Poll handles allow the user to monitor a given path for changes. Unlike
|uv_fs_event_t|, fs poll handles use `stat` to detect when a file has changed
so they can work on file systems where fs event handles can't.

uv.new_fs_poll()                                              *uv.new_fs_poll()*

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

                Returns: `uv_fs_poll_t userdata` or `fail`

uv.fs_poll_start({fs_poll}, {path}, {interval}, {callback}) *uv.fs_poll_start()*

                > method form `fs_poll:start(path, interval, callback)`

                Parameters:
                - `fs_poll`: `uv_fs_poll_t userdata`
                - `path`: `string`
                - `interval`: `integer`
                - `callback`: `callable`
                  - `err`: `nil` or `string`
                  - `prev`: `table` or `nil` (see `uv.fs_stat`)
                  - `curr`: `table` or `nil` (see `uv.fs_stat`)

                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.

                Returns: `0` or `fail`

uv.fs_poll_stop()                                            *uv.fs_poll_stop()*

                > method form `fs_poll:stop()`

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

                Returns: `0` or `fail`

uv.fs_poll_getpath()                                      *uv.fs_poll_getpath()*

                > method form `fs_poll:getpath()`

                Get the path being monitored by the handle.

                Returns: `string` or `fail`

==============================================================================
FILE SYSTEM OPERATIONS                      *luv-file-system-operations* *uv_fs_t*

Most file system functions can operate synchronously or asynchronously. When a
synchronous version is called (by omitting a callback), the function will
immediately return the results of the FS call. When an asynchronous version is
called (by providing a callback), the function will immediately return a
`uv_fs_t userdata` and asynchronously execute its callback; if an error is
encountered, the first and only argument passed to the callback will be the
`err` error string; if the operation completes successfully, the first
argument will be `nil` and the remaining arguments will be the results of the
FS call.

Synchronous and asynchronous versions of `readFile` (with naive error
handling) are implemented below as an example:

    >lua
    local function readFileSync(path)
      local fd = assert(uv.fs_open(path, "r", 438))
      local stat = assert(uv.fs_fstat(fd))
      local data = assert(uv.fs_read(fd, stat.size, 0))
      assert(uv.fs_close(fd))
      return data
    end

    local data = readFileSync("main.lua")
    print("synchronous read", data)
<

    >lua
    local function readFile(path, callback)
      uv.fs_open(path, "r", 438, function(err, fd)
        assert(not err, err)
        uv.fs_fstat(fd, function(err, stat)
          assert(not err, err)
          uv.fs_read(fd, stat.size, 0, function(err, data)
            assert(not err, err)
            uv.fs_close(fd, function(err)
              assert(not err, err)
              return callback(data)
            end)
          end)
        end)
      end)
    end

    readFile("main.lua", function(data)
      print("asynchronous read", data)
    end)
<

uv.fs_close({fd} [, {callback}])                                 *uv.fs_close()*

                Parameters:
                - `fd`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `close(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_open({path}, {flags}, {mode} [, {callback}])                *uv.fs_open()*

                Parameters:
                - `path`: `string`
                - `flags`: `string` or `integer`
                - `mode`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `fd`: `integer` or `nil`

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

                Returns (sync version): `integer` or `fail`

                Returns (async version): `uv_fs_t userdata`

                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.

uv.fs_read({fd}, {size} [, {offset} [, {callback}]])              *uv.fs_read()*

                Parameters:
                - `fd`: `integer`
                - `size`: `integer`
                - `offset`: `integer` or `nil`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `data`: `string` or `nil`

                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.

                Returns (sync version): `string` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_unlink({path} [, {callback}])                             *uv.fs_unlink()*

                Parameters:
                - `path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `unlink(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_write({fd}, {data} [, {offset} [, {callback}]])            *uv.fs_write()*

                Parameters:
                - `fd`: `integer`
                - `data`: `buffer`
                - `offset`: `integer` or `nil`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `bytes`: `integer` or `nil`

                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.

                Returns (sync version): `integer` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_mkdir({path}, {mode} [, {callback}])                       *uv.fs_mkdir()*

                Parameters:
                - `path`: `string`
                - `mode`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `mkdir(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_mkdtemp({template} [, {callback}])                       *uv.fs_mkdtemp()*

                Parameters:
                - `template`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `path`: `string` or `nil`

                Equivalent to `mkdtemp(3)`.

                Returns (sync version): `string` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_mkstemp({template} [, {callback}])                       *uv.fs_mkstemp()*

                Parameters:
                - `template`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `fd`: `integer` or `nil`
                  - `path`: `string` or `nil`

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

                Returns (sync version): `integer, string` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_rmdir({path} [, {callback}])                               *uv.fs_rmdir()*

                Parameters:
                - `path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `rmdir(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_scandir({path} [, {callback}])                           *uv.fs_scandir()*

                Parameters:
                - `path`: `string`
                - `callback`: `callable`
                  - `err`: `nil` or `string`
                  - `success`: `uv_fs_t userdata` or `nil`

                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.

                Returns: `uv_fs_t userdata` or `fail`

uv.fs_scandir_next({fs})                                  *uv.fs_scandir_next()*

                Parameters:
                - `fs`: `uv_fs_t userdata`

                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.

                Returns: `string, string` or `nil` or `fail`

uv.fs_stat({path} [, {callback}])                                 *uv.fs_stat()*

                Parameters:
                - `path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `stat`: `table` or `nil` (see below)

                Equivalent to `stat(2)`.

                Returns (sync version): `table` or `fail`
                - `dev` : `integer`
                - `mode` : `integer`
                - `nlink` : `integer`
                - `uid` : `integer`
                - `gid` : `integer`
                - `rdev` : `integer`
                - `ino` : `integer`
                - `size` : `integer`
                - `blksize` : `integer`
                - `blocks` : `integer`
                - `flags` : `integer`
                - `gen` : `integer`
                - `atime` : `table`
                  - `sec` : `integer`
                  - `nsec` : `integer`
                - `mtime` : `table`
                  - `sec` : `integer`
                  - `nsec` : `integer`
                - `ctime` : `table`
                  - `sec` : `integer`
                  - `nsec` : `integer`
                - `birthtime` : `table`
                  - `sec` : `integer`
                  - `nsec` : `integer`
                - `type` : `string`

                Returns (async version): `uv_fs_t userdata`

uv.fs_fstat({fd} [, {callback}])                                 *uv.fs_fstat()*

                Parameters:
                - `fd`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `stat`: `table` or `nil` (see `uv.fs_stat`)

                Equivalent to `fstat(2)`.

                Returns (sync version): `table` or `fail` (see `uv.fs_stat`)

                Returns (async version): `uv_fs_t userdata`

uv.fs_lstat({path} [, {callback}])                               *uv.fs_lstat()*

                Parameters:
                - `fd`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `stat`: `table` or `nil` (see `uv.fs_stat`)

                Equivalent to `lstat(2)`.

                Returns (sync version): `table` or `fail` (see |uv.fs_stat()|)

                Returns (async version): `uv_fs_t userdata`

uv.fs_rename({path}, {new_path} [, {callback}])                 *uv.fs_rename()*

                Parameters:
                - `path`: `string`
                - `new_path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `rename(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_fsync({fd} [, {callback}])                                 *uv.fs_fsync()*

                Parameters:
                - `fd`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `fsync(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_fdatasync({fd} [, {callback}])                         *uv.fs_fdatasync()*

                Parameters:
                - `fd`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `fdatasync(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_ftruncate({fd}, {offset} [, {callback}])               *uv.fs_ftruncate()*

                Parameters:
                - `fd`: `integer`
                - `offset`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `ftruncate(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

                                                              *uv.fs_sendfile()*
uv.fs_sendfile({out_fd}, {in_fd}, {in_offset}, {size} [, {callback}])

                Parameters:
                - `out_fd`: `integer`
                - `in_fd`: `integer`
                - `in_offset`: `integer`
                - `size`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `bytes`: `integer` or `nil`

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

                Returns (sync version): `integer` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_access({path}, {mode} [, {callback}])                     *uv.fs_access()*

                Parameters:
                - `path`: `string`
                - `mode`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `permission`: `boolean` or `nil`

                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.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_chmod({path}, {mode} [, {callback}])                       *uv.fs_chmod()*

                Parameters:
                - `path`: `string`
                - `mode`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `chmod(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_fchmod({fd}, {mode} [, {callback}])                       *uv.fs_fchmod()*

                Parameters:
                - `fd`: `integer`
                - `mode`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `fchmod(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_utime({path}, {atime}, {mtime} [, {callback}])             *uv.fs_utime()*

                Parameters:
                - `path`: `string`
                - `atime`: `number`
                - `mtime`: `number`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `utime(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_futime({fd}, {atime}, {mtime} [, {callback}])             *uv.fs_futime()*

                Parameters:
                - `fd`: `integer`
                - `atime`: `number`
                - `mtime`: `number`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `futime(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_lutime({path}, {atime}, {mtime} [, {callback}])           *uv.fs_lutime()*

                Parameters:
                - `path`: `string`
                - `atime`: `number`
                - `mtime`: `number`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `lutime(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_link({path}, {new_path} [, {callback}])                     *uv.fs_link()*

                Parameters:
                - `path`: `string`
                - `new_path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `link(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_symlink({path}, {new_path} [, {flags} [, {callback}]])   *uv.fs_symlink()*

                Parameters:
                - `path`: `string`
                - `new_path`: `string`
                - `flags`: `table`, `integer`, or `nil`
                  - `dir`: `boolean`
                  - `junction`: `boolean`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

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

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_readlink({path} [, {callback}])                         *uv.fs_readlink()*

                Parameters:
                - `path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `path`: `string` or `nil`

                Equivalent to `readlink(2)`.

                Returns (sync version): `string` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_realpath({path} [, {callback}])                         *uv.fs_realpath()*

                Parameters:
                - `path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `path`: `string` or `nil`

                Equivalent to `realpath(3)`.

                Returns (sync version): `string` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_chown({path}, {uid}, {gid} [, {callback}])                 *uv.fs_chown()*

                Parameters:
                - `path`: `string`
                - `uid`: `integer`
                - `gid`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `chown(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_fchown({fd}, {uid}, {gid} [, {callback}])                 *uv.fs_fchown()*

                Parameters:
                - `fd`: `integer`
                - `uid`: `integer`
                - `gid`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `fchown(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_lchown({fd}, {uid}, {gid} [, {callback}])                 *uv.fs_lchown()*

                Parameters:
                - `fd`: `integer`
                - `uid`: `integer`
                - `gid`: `integer`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

                Equivalent to `lchown(2)`.

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_copyfile({path}, {new_path} [, {flags} [, {callback}]]) *uv.fs_copyfile()*

                Parameters:
                - `path`: `string`
                - `new_path`: `string`
                - `flags`: `table`, `integer`, or `nil`
                  - `excl`: `boolean`
                  - `ficlone`: `boolean`
                  - `ficlone_force`: `boolean`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

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

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_opendir({path} [, {callback} [, {entries}]])             *uv.fs_opendir()*

                Parameters:
                - `path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `dir`: `luv_dir_t userdata` or `nil`
                - `entries`: `integer` or `nil`

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

                Returns (sync version): `luv_dir_t userdata` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_readdir({dir} [, {callback}])                            *uv.fs_readdir()*

                > method form `dir:readdir([callback])`

                Parameters:
                - `dir`: `luv_dir_t userdata`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `entries`: `table` or `nil` (see below)

                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.

                Returns (sync version): `table` or `fail`
                - `[1, 2, 3, ..., n]` : `table`
                  - `name` : `string`
                  - `type` : `string`

                Returns (async version): `uv_fs_t userdata`

uv.fs_closedir({dir} [, {callback}])                          *uv.fs_closedir()*

                > method form `dir:closedir([callback])`

                Parameters:
                - `dir`: `luv_dir_t userdata`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `success`: `boolean` or `nil`

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

                Returns (sync version): `boolean` or `fail`

                Returns (async version): `uv_fs_t userdata`

uv.fs_statfs({path} [, {callback}])                             *uv.fs_statfs()*

                Parameters:
                - `path`: `string`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `table` or `nil` (see below)

                Equivalent to `statfs(2)`.

                Returns `table` or `nil`
                - `type` : `integer`
                - `bsize` : `integer`
                - `blocks` : `integer`
                - `bfree` : `integer`
                - `bavail` : `integer`
                - `files` : `integer`
                - `ffree` : `integer`

==============================================================================
THREAD POOL WORK SCHEDULING                    *luv-thread-pool-work-scheduling*

Libuv provides a threadpool which can be used to run user code and get
notified in the loop thread. This threadpool is internally used to run all
file system operations, as well as `getaddrinfo` and `getnameinfo` requests.

    >lua
    local function work_callback(a, b)
      return a + b
    end

    local function after_work_callback(c)
      print("The result is: " .. c)
    end

    local work = uv.new_work(work_callback, after_work_callback)

    work:queue(1, 2)

    -- output: "The result is: 3"
<

uv.new_work({work_callback}, {after_work_callback})              *uv.new_work()*

                Parameters:
                - `work_callback`: `function` or `string`
                  - `...`: `threadargs` passed to/from
                    `uv.queue_work(work_ctx, ...)`
                - `after_work_callback`: `function`
                  - `...`: `threadargs` returned from `work_callback`

                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.

                Returns: `luv_work_ctx_t userdata`

uv.queue_work({work_ctx}, {...})                               *uv.queue_work()*

                > method form `work_ctx:queue(...)`

                Parameters:
                - `work_ctx`: `luv_work_ctx_t userdata`
                - `...`: `threadargs`

                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.

                Returns: `boolean` or `fail`

==============================================================================
DNS UTILITY FUNCTIONS                                *luv-dns-utility-functions*

uv.getaddrinfo({host}, {service} [, {hints} [, {callback}]])  *uv.getaddrinfo()*

                Parameters:
                - `host`: `string` or `nil`
                - `service`: `string` or `nil`
                - `hints`: `table` or `nil`
                  - `family`: `string` or `integer` or `nil`
                  - `socktype`: `string` or `integer` or `nil`
                  - `protocol`: `string` or `integer` or `nil`
                  - `addrconfig`: `boolean` or `nil`
                  - `v4mapped`: `boolean` or `nil`
                  - `all`: `boolean` or `nil`
                  - `numerichost`: `boolean` or `nil`
                  - `passive`: `boolean` or `nil`
                  - `numericserv`: `boolean` or `nil`
                  - `canonname`: `boolean` or `nil`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `addresses`: `table` or `nil` (see below)

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

                Valid hint strings for the keys that take a string:
                - `family`: `"unix"`, `"inet"`, `"inet6"`, `"ipx"`,
                  `"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`,
                  or `"packet"`
                - `socktype`: `"stream"`, `"dgram"`, `"raw"`, `"rdm"`, or
                  `"seqpacket"`
                - `protocol`: will be looked up using the `getprotobyname(3)`
                  function (examples: `"ip"`, `"icmp"`, `"tcp"`, `"udp"`, etc)

                Returns (sync version): `table` or `fail`
                - `[1, 2, 3, ..., n]` : `table`
                  - `addr` : `string`
                  - `family` : `string`
                  - `port` : `integer` or `nil`
                  - `socktype` : `string`
                  - `protocol` : `string`
                  - `canonname` : `string` or `nil`

                Returns (async version): `uv_getaddrinfo_t userdata` or `fail`

uv.getnameinfo({address} [, {callback}])                      *uv.getnameinfo()*

                Parameters:
                - `address`: `table`
                  - `ip`: `string` or `nil`
                  - `port`: `integer` or `nil`
                  - `family`: `string` or `integer` or `nil`
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `host`: `string` or `nil`
                  - `service`: `string` or `nil`

                Equivalent to `getnameinfo(3)`.

                When specified, `family` must be one of `"unix"`, `"inet"`,
                `"inet6"`, `"ipx"`, `"netlink"`, `"x25"`, `"ax25"`,
                `"atmpvc"`, `"appletalk"`, or `"packet"`.

                Returns (sync version): `string, string` or `fail`

                Returns (async version): `uv_getnameinfo_t userdata` or `fail`

==============================================================================
THREADING AND SYNCHRONIZATION UTILITIES *luv-threading-and-synchronization-utilities*

Libuv provides cross-platform implementations for multiple threading an
synchronization primitives. The API largely follows the pthreads API.

uv.new_thread([{options}, ] {entry}, {...})                    *uv.new_thread()*

                Parameters:
                - `options`: `table` or `nil`
                  - `stack_size`: `integer` or `nil`
                - `entry`: `function` or `string`
                - `...`: `threadargs` passed to `entry`

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

                Returns: `luv_thread_t userdata` or `fail`

                Note: unsafe, please make sure that the thread's end of life
                is before Lua state is closed.

uv.thread_equal({thread}, {other_thread})                    *uv.thread_equal()*

                > method form `thread:equal(other_thread)`

                Parameters:
                - `thread`: `luv_thread_t userdata`
                - `other_thread`: `luv_thread_t userdata`

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

                Returns: `boolean`

uv.thread_self()                                              *uv.thread_self()*

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

                Returns: `luv_thread_t`

uv.thread_join({thread})                                      *uv.thread_join()*

                > method form `thread:join()`

                Parameters:
                - `thread`: `luv_thread_t userdata`

                Waits for the `thread` to finish executing its entry function.

                Returns: `boolean` or `fail`

uv.sleep({msec})                                                    *uv.sleep()*

                Parameters:
                - `msec`: `integer`

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

                Returns: Nothing.

==============================================================================
MISCELLANEOUS UTILITIES                            *luv-miscellaneous-utilities*

uv.exepath()                                                      *uv.exepath()*

                Returns the executable path.

                Returns: `string` or `fail`

uv.cwd()                                                              *uv.cwd()*

                Returns the current working directory.

                Returns: `string` or `fail`

uv.chdir({cwd})                                                     *uv.chdir()*

                Parameters:
                - `cwd`: `string`

                Sets the current working directory with the string `cwd`.

                Returns: `0` or `fail`

uv.get_process_title()                                  *uv.get_process_title()*

                Returns the title of the current process.

                Returns: `string` or `fail`

uv.set_process_title({title})                           *uv.set_process_title()*

                Parameters:
                - `title`: `string`

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

                Returns: `0` or `fail`

uv.get_total_memory()                                    *uv.get_total_memory()*

                Returns the current total system memory in bytes.

                Returns: `number`

uv.get_free_memory()                                      *uv.get_free_memory()*

                Returns the current free system memory in bytes.

                Returns: `number`

uv.get_constrained_memory()                        *uv.get_constrained_memory()*

                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.

                Returns: `number`

uv.resident_set_memory()                              *uv.resident_set_memory()*

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

                Returns: `integer` or `fail`

uv.getrusage()                                                  *uv.getrusage()*

                Returns the resource usage.

                Returns: `table` or `fail`
                - `utime` : `table` (user CPU time used)
                  - `sec` : `integer`
                  - `usec` : `integer`
                - `stime` : `table` (system CPU time used)
                  - `sec` : `integer`
                  - `usec` : `integer`
                - `maxrss` : `integer` (maximum resident set size)
                - `ixrss` : `integer` (integral shared memory size)
                - `idrss` : `integer` (integral unshared data size)
                - `isrss` : `integer` (integral unshared stack size)
                - `minflt` : `integer` (page reclaims (soft page faults))
                - `majflt` : `integer` (page faults (hard page faults))
                - `nswap` : `integer` (swaps)
                - `inblock` : `integer` (block input operations)
                - `oublock` : `integer` (block output operations)
                - `msgsnd` : `integer` (IPC messages sent)
                - `msgrcv` : `integer` (IPC messages received)
                - `nsignals` : `integer` (signals received)
                - `nvcsw` : `integer` (voluntary context switches)
                - `nivcsw` : `integer` (involuntary context switches)

uv.available_parallelism()                          *uv.available_parallelism()*

                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: `integer`

uv.cpu_info()                                                    *uv.cpu_info()*

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

                Returns: `table` or `fail`
                - `[1, 2, 3, ..., n]` : `table`
                  - `model` : `string`
                  - `speed` : `number`
                  - `times` : `table`
                    - `user` : `number`
                    - `nice` : `number`
                    - `sys` : `number`
                    - `idle` : `number`
                    - `irq` : `number`

uv.getpid()                                                        *uv.getpid()*

                DEPRECATED: Please use |uv.os_getpid()| instead.

uv.getuid()                                                        *uv.getuid()*

                Returns the user ID of the process.

                Returns: `integer`

                Note: This is not a libuv function and is not supported on
                Windows.

uv.getgid()                                                        *uv.getgid()*

                Returns the group ID of the process.

                Returns: `integer`

                Note: This is not a libuv function and is not supported on
                Windows.

uv.setuid({id})                                                    *uv.setuid()*

                Parameters:
                - `id`: `integer`

                Sets the user ID of the process with the integer `id`.

                Returns: Nothing.

                Note: This is not a libuv function and is not supported on
                Windows.

uv.setgid({id})                                                    *uv.setgid()*

                Parameters:
                - `id`: `integer`

                Sets the group ID of the process with the integer `id`.

                Returns: Nothing.

                Note: This is not a libuv function and is not supported on
                Windows.

uv.hrtime()                                                        *uv.hrtime()*

                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.

                Returns: `number`

uv.uptime()                                                        *uv.uptime()*

                Returns the current system uptime in seconds.

                Returns: `number` or `fail`

uv.print_all_handles()                                  *uv.print_all_handles()*

                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.

                Returns: Nothing.

                Note: This is not available on Windows.

                WARNING: This function is meant for ad hoc debugging, there
                are no API/ABI stability guarantees.

uv.print_active_handles()                            *uv.print_active_handles()*

                The same as |uv.print_all_handles()| except only active
                handles are printed.

                Returns: Nothing.

                Note: This is not available on Windows.

                WARNING: This function is meant for ad hoc debugging, there
                are no API/ABI stability guarantees.

uv.guess_handle({fd})                                        *uv.guess_handle()*

                Parameters:
                - `fd`: `integer`

                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.

                Returns: `string`

uv.gettimeofday()                                            *uv.gettimeofday()*

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

                Returns: `integer, integer` or `fail`

uv.interface_addresses()                              *uv.interface_addresses()*

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

                Returns: `table`
                - `[name(s)]` : `table`
                  - `ip` : `string`
                  - `family` : `string`
                  - `netmask` : `string`
                  - `internal` : `boolean`
                  - `mac` : `string`

uv.if_indextoname({ifindex})                               *uv.if_indextoname()*

                Parameters:
                - `ifindex`: `integer`

                IPv6-capable implementation of `if_indextoname(3)`.

                Returns: `string` or `fail`

uv.if_indextoiid({ifindex})                                 *uv.if_indextoiid()*

                Parameters:
                - `ifindex`: `integer`

                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: `string` or `fail`

uv.loadavg()                                                      *uv.loadavg()*

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

                Returns: `number, number, number`

uv.os_uname()                                                    *uv.os_uname()*

                Returns system information.

                Returns: `table`
                - `sysname` : `string`
                - `release` : `string`
                - `version` : `string`
                - `machine` : `string`

uv.os_gethostname()                                        *uv.os_gethostname()*

                Returns the hostname.

                Returns: `string`

uv.os_getenv({name} [, {size}])                                 *uv.os_getenv()*

                Parameters:
                - `name`: `string`
                - `size`: `integer` (default = `LUAL_BUFFERSIZE`)

                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.

                Returns: `string` or `fail`

                WARNING: This function is not thread safe.

uv.os_setenv({name}, {value})                                   *uv.os_setenv()*

                Parameters:
                - `name`: `string`
                - `value`: `string`

                Sets the environmental variable specified by `name` with the
                string `value`.

                Returns: `boolean` or `fail`

                WARNING: This function is not thread safe.

uv.os_unsetenv()                                              *uv.os_unsetenv()*

                Returns: `boolean` or `fail`

                WARNING: This function is not thread safe.

uv.os_environ()                                                *uv.os_environ()*

                Returns all environmental variables as a dynamic table of
                names associated with their corresponding values.

                Returns: `table`

                WARNING: This function is not thread safe.

uv.os_homedir()                                                *uv.os_homedir()*

                Returns: `string` or `fail`

                WARNING: This function is not thread safe.

uv.os_tmpdir()                                                  *uv.os_tmpdir()*

                Returns: `string` or `fail`

                WARNING: This function is not thread safe.

uv.os_get_passwd()                                          *uv.os_get_passwd()*

                Returns password file information.

                Returns: `table`
                - `username` : `string`
                - `uid` : `integer`
                - `gid` : `integer`
                - `shell` : `string`
                - `homedir` : `string`

uv.os_getpid()                                                  *uv.os_getpid()*

                Returns the current process ID.

                Returns: `number`

uv.os_getppid()                                                *uv.os_getppid()*

                Returns the parent process ID.

                Returns: `number`

uv.os_getpriority({pid})                                   *uv.os_getpriority()*

                Parameters:
                - `pid`: `integer`

                Returns the scheduling priority of the process specified by
                `pid`.

                Returns: `number` or `fail`

uv.os_setpriority({pid}, {priority})                       *uv.os_setpriority()*

                Parameters:
                - `pid`: `integer`
                - `priority`: `integer`

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

                Returns: `boolean` or `fail`

uv.random({len}, {flags} [, {callback}])                           *uv.random()*

                Parameters:
                - `len`: `integer`
                - `flags`: `nil` (see below)
                - `callback`: `callable` (async version) or `nil` (sync
                  version)
                  - `err`: `nil` or `string`
                  - `bytes`: `string` or `nil`

                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 (sync version): `string` or `fail`

                Returns (async version): `0` or `fail`

uv.translate_sys_error({errcode})                     *uv.translate_sys_error()*

                Parameters:
                - `errcode`: `integer`

                Returns the libuv error message and error name (both in string
                form, see `err` and `name` in |luv-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()).

                Returns: `string, string` or `nil`

==============================================================================
METRICS OPERATIONS                                      *luv-metrics-operations*

uv.metrics_idle_time()                                  *uv.metrics_idle_time()*

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

                Returns: `number`

==============================================================================
CREDITS                                                            *luv-credits*

This document is a reformatted version of the LUV documentation, up-to-date
with commit e8e7b7e (3 Feb 2023) of the luv repository
https://github.com/luvit/luv/commit/e8e7b7e13225348a8806118a3ea9e021383a9536.

Based on https://github.com/nanotee/luv-vimdocs with kind permission.


vim:tw=78:ts=8:ft=help:norl: