my-website-base/decl/luv.d.lua

---@meta luv
---@diagnostic disable: duplicate-set-field

-- TODO: define @source for all sections and methods

-- TODO: things like uv.tty_set_mode has in the description-
-- "look below for possible values" and then we rely on lls to list the alias
-- we need a way to list those off when generating the docs

---
---The [luv](https://github.com/luvit/luv/) project provides access to the multi-platform support library
---[libuv](http://libuv.org/) 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](http://docs.libuv.org/en/v1.x/).
---
---### TCP Echo Server Example
---
---Here is a small example showing a TCP echo server:
---
---```lua
---local uv = require("luv") -- "luv" when stand-alone, "uv" in luvi apps
---
---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 [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`, numbers of argument limited to 9.
---
---@namespace
---@class uv
---@section Libuv in Lua
local uv = {}

---@alias uv.aliases.buffer string|string[]

---@alias uv.aliases.threadargs userdata|string|number|boolean|nil # numbers of argument limited to 9.

---
---@section Contents
---
---This documentation is mostly a retelling of the [libuv API documentation][]
---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.
---
--- - [Error handling][]
--- - [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
--- - [File system operations][]
--- - [Thread pool work scheduling][]
--- - [DNS utility functions][]
--- - [Threading and synchronization utilities][]
--- - [Miscellaneous utilities][]
--- - [Metrics operations][]
---

-- TODO: above section should probably not be hardcoded

---
---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.
---
---@alias uv.errno {E2BIG: integer, EACCES: integer, EADDRINUSE: integer, EADDRNOTAVAIL: integer, EAFNOSUPPORT: integer, EAGAIN: integer, EAI_ADDRFAMILY: integer, EAI_AGAIN: integer, EAI_BADFLAGS: integer, EAI_BADHINTS: integer, EAI_CANCELED: integer, EAI_FAIL: integer, EAI_FAMILY: integer, EAI_MEMORY: integer, EAI_NODATA: integer, EAI_NONAME: integer, EAI_OVERFLOW: integer, EAI_PROTOCOL: integer, EAI_SERVICE: integer, EAI_SOCKTYPE: integer, EALREADY: integer, EBADF: integer, EBUSY: integer, ECANCELED: integer, ECHARSET: integer, ECONNABORTED: integer, ECONNREFUSED: integer, ECONNRESET: integer, EDESTADDRREQ: integer, EEXIST: integer, EFAULT: integer, EFBIG: integer, EFTYPE: integer, EHOSTDOWN: integer, EHOSTUNREACH: integer, EILSEQ: integer, EINTR: integer, EINVAL: integer, EIO: integer, EISCONN: integer, EISDIR: integer, ELOOP: integer, EMFILE: integer, EMLINK: integer, EMSGSIZE: integer, ENAMETOOLONG: integer, ENETDOWN: integer, ENETUNREACH: integer, ENFILE: integer, ENOBUFS: integer, ENODATA: integer, ENODEV: integer, ENOENT: integer, ENOMEM: integer, ENONET: integer, ENOPROTOOPT: integer, ENOSPC: integer, ENOSYS: integer, ENOTCONN: integer, ENOTDIR: integer, ENOTEMPTY: integer, ENOTSOCK: integer, ENOTSUP: integer, ENOTTY: integer, ENXIO: integer, EOF: integer, EOVERFLOW: integer, EPERM: integer, EPIPE: integer, EPROTO: integer, EPROTONOSUPPORT: integer, EPROTOTYPE: integer, ERANGE: integer, EREMOTEIO: integer, EROFS: integer, ESHUTDOWN: integer, ESOCKTNOSUPPORT: integer, ESPIPE: integer, ESRCH: integer, ETIMEDOUT: integer, ETXTBSY: integer, EXDEV: integer, UNKNOWN: integer}
---@section Error Handling

-- TODO: errno fields should have descriptions!

---
---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)
---
---@type uv.errno
uv.errno = {}

---
---@section Version Checking
---

---
---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.
---
---@return integer
---@nodiscard
function uv.version() end

---
---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.
---
---@return string
---@nodiscard
function uv.version_string() end

---
---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.
---
---@class uv_loop_t: userdata
---@section Event loop
local uv_loop_t = {}

---@alias uv.aliases.run_mode
---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.
---|>'default'
---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).
---|'once'
---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).
---|'nowait'

---@alias uv.aliases.loop_configure_option
---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`.
---|'block_signal'
---Accumulate the amount of idle time the event loop spends in the event provider.
---This option is necessary to use `metrics_idle_time()`.
---|'metrics_idle_time'

---
---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`.
---
---@return 0|nil success, string? err_name, string? err_msg
function uv.loop_close() end

---
---This function runs the event loop. It will act differently depending on the
---specified mode:
---- `"default"`: Runs the event loop until there are no more active and
---referenced handles or requests. Returns `true` if `uv.stop()` was called and
---there are still active handles or requests. Returns `false` in all other
---cases.
---- `"once"`: Poll for I/O once. Note that this function blocks if there are no
---pending callbacks. Returns `false` when done (no active handles or requests
---left), or `true` if more callbacks are expected (meaning you should run the
---event loop again sometime in the future).
---- `"nowait"`: Poll for I/O once but don't block if there are no pending
---callbacks. Returns `false` if done (no active handles or requests left),
---or `true` if more callbacks are expected (meaning you should run the event
---loop again sometime in the future).
---
---**Note**: Luvit will implicitly call `uv.run()` after loading user code, but if
---you use the luv bindings directly, you need to call this after registering
---your initial set of event callbacks to start the event loop.
---
---@param mode uv.aliases.run_mode|nil
---@return boolean|nil, string? err_name, string? err_msg
function uv.run(mode) end

---
---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")
---```
---
---**Note**: Be prepared to handle the `ENOSYS` error; it means the loop option is
---not supported by the platform.
---
---@param option uv.aliases.loop_configure_option
---@param ... any
---@return 0|nil success, string? err_name, string? err_msg
function uv.loop_configure(option, ...) end

---
---If the loop is running, returns a string indicating the mode in use. If the loop
---is not running, `nil` is returned instead.
---
---@return uv.aliases.run_mode|nil
---@nodiscard
function uv.loop_mode() end

---
---Returns `true` if there are referenced active handles, active requests, or
---closing handles in the loop; otherwise, `false`.
---
---@return boolean|nil, string? err_name, string? err_msg
---@nodiscard
function uv.loop_alive() end

---
---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.
---
function uv.stop() end

---
---Get backend file descriptor. Only kqueue, epoll, and event ports are supported.
---This can be used in conjunction with `uv.run("nowait")` to poll in one thread
---and run the event loop's callbacks in another
---
---**Note**: Embedding a kqueue fd in another kqueue pollset doesn't work on all
---platforms. It's not an error to add the fd but it never generates events.
---
---@return integer|nil
---@nodiscard
function uv.backend_fd() end

---
---Get the poll timeout. The return value is in milliseconds, or -1 for no timeout.
---
---@return integer
---@nodiscard
function uv.backend_timeout() end

---
---Returns the current timestamp in milliseconds. The timestamp is cached at the
---start of the event loop tick, see `uv.update_time()` for details and rationale.
---The timestamp increases monotonically from some arbitrary point in time. Don't
---make assumptions about the starting point, you will only get disappointed.
---
---**Note**: Use `uv.hrtime()` if you need sub-millisecond granularity.
---
---@return integer
---@nodiscard
function uv.now() end

---
---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.
---
function uv.update_time() end

---
---Walk the list of handles: `callback` will be executed with each handle.
---
---Example usage of uv.walk to close all handles that aren't already closing.
---```lua
---uv.walk(function (handle)
---  if not handle:is_closing() then
---    handle:close()
---  end
---end)
---```
---
---@param callback fun(handle: uv.aliases.handle_instances)
function uv.walk(callback) end

---
---`uv_req_t` is the base type for all libuv request types.
---
---@class uv_req_t: userdata
---@section Base request
local uv_req_t = {}

---@alias uv.aliases.req_struct_name
---|'unknown'     # 0
---|'req'         # 1
---|'connect'     # 2
---|'write'       # 3
---|'shutdown'    # 4
---|'udp_send'    # 5
---|'fs'          # 6
---|'work'        # 7
---|'getaddrinfo' # 8
---|'getnameinfo' # 9
---|'random'      # 10

---@alias uv.aliases.req_struct_type
---|0   # unknown
---|1   # req
---|2   # connect
---|3   # write
---|4   # shutdown
---|5   # udp_send
---|6   # fs
---|7   # work
---|8   # getaddrinfo
---|9   # getnameinfo
---|10  # random

---
---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.
---
---@param req uv_fs_t|uv_getaddrinfo_t|uv_getnameinfo_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.cancel(req) end
uv_req_t.cancel = uv.cancel

---
---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`).
---
---@param req uv_req_t
---@return uv.aliases.req_struct_name
---@return uv.aliases.req_struct_type
function uv.req_get_type(req) end
uv_req_t.get_type = uv.req_get_type

---
---`uv_handle_t` is the base type for all libuv handle types. All API functions
---defined here work with any handle type.
---
---@class uv_handle_t: userdata
---@section Base handle
local uv_handle_t = {}

---@alias uv.aliases.handle_instances
---|uv_handle_t
---|uv_stream_t
---|uv_tcp_t
---|uv_pipe_t
---|uv_tty_t
---|uv_udp_t
---|uv_fs_event_t
---|uv_fs_poll_t

---@alias uv.aliases.handle_struct_name
---|'unknown'   # 0
---|'"async"'   # 1
---|'check'     # 2
---|'fs_event'  # 3
---|'fs_poll'   # 4
---|'handle'    # 5
---|'idle'      # 6
---|'pipe'      # 7
---|'poll'      # 8
---|'prepare'   # 9
---|'process'   # 10
---|'stream'    # 11
---|'tcp'       # 12
---|'timer'     # 13
---|'tty'       # 14
---|'udp'       # 15
---|'signal'    # 16
---|'file'      # 17

---@alias uv.aliases.handle_struct_type
---|0   # unknown
---|1   # async
---|2   # check
---|3   # fs_event
---|4   # fs_poll
---|5   # handle
---|6   # idle
---|7   # pipe
---|8   # poll
---|9   # prepare
---|10  # process
---|11  # stream
---|12  # tcp
---|13  # timer
---|14  # tty
---|15  # udp
---|16  # signal
---|17  # file

---
---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.
---
---@param handle uv_handle_t # `userdata` for sub-type of `uv_handle_t`
---@return boolean|nil, string? err_name, string? err_msg
---@nodiscard
function uv.is_active(handle) end
uv_handle_t.is_active = uv.is_active

---
---Returns `true` if the handle is closing or closed, `false` otherwise.
---
---**Note**: This function should only be used between the initialization of the
---handle and the arrival of the close callback.
---
---@param handle uv_handle_t # `userdata` for sub-type of `uv_handle_t`
---@return boolean|nil, string? err_name, string? err_msg
---@nodiscard
function uv.is_closing(handle) end
uv_handle_t.is_closing = uv.is_closing

---
---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`.
---
---@param handle uv_handle_t # `userdata` for sub-type of `uv_handle_t`
---@param callback? function
function uv.close(handle, callback) end
uv_handle_t.close = uv.close

---
---Reference the given handle. References are idempotent, that is, if a handle is
---already referenced calling this function again will have no effect.
---
---@param handle uv_handle_t # `userdata` for sub-type of `uv_handle_t`
function uv.ref(handle) end
uv_handle_t.ref = uv.ref

---
---Un-reference the given handle. References are idempotent, that is, if a handle
---is not referenced calling this function again will have no effect.
---
---@param handle uv_handle_t # `userdata` for sub-type of `uv_handle_t`
function uv.unref(handle) end
uv_handle_t.unref = uv.unref

---
---Returns `true` if the handle referenced, `false` if not.
---
---@param handle uv_handle_t # `userdata` for sub-type of `uv_handle_t`
---@return boolean|nil, string? err_name, string? err_msg
---@nodiscard
function uv.has_ref(handle) end
uv_handle_t.has_ref = uv.has_ref

---
---Gets or sets the size of the send buffer that the operating system uses for the socket.
---
---If `size` is omitted (or `0`), this will return the current send buffer size; otherwise, this will use `size` to set the new send buffer size.
---
---This function works for TCP, pipe and UDP handles on Unix and for TCP and UDP
---handles on Windows.
---
---**Note**: Linux will set double the size and return double the size of the
---original set value.
---
---@param handle uv_handle_t # `userdata` for sub-type of `uv_handle_t`
---@return integer|nil, string? err_name, string? err_msg
---@nodiscard
function uv.send_buffer_size(handle) end
---@param size? integer # (default: `0`)
---@return 0|nil, string? err_name, string? err_msg
function uv.send_buffer_size(handle, size) end
uv_handle_t.send_buffer_size = uv.send_buffer_size

---
---Gets or sets the size of the receive buffer that the operating system uses for the socket.
---
---If `size` is omitted (or `0`), this will return the current send buffer size; otherwise, this will use `size` to set the new send buffer size.
---
---This function works for TCP, pipe and UDP handles on Unix and for TCP and UDP
---handles on Windows.
---
---**Note**: Linux will set double the size and return double the size of the
---original set value.
---
---@param handle uv_handle_t `userdata` for sub-type of `uv_handle_t`
---@return integer|nil, string? err_name, string? err_msg
---@nodiscard
function uv.recv_buffer_size(handle) end
---@param size? integer # (default: `0`)
---@return 0|nil, string? err_name, string? err_msg
function uv.recv_buffer_size(handle, size) end
uv_handle_t.recv_buffer_size = uv.recv_buffer_size

---
---Gets the platform dependent file descriptor equivalent.
---
---The following handles are supported: TCP, pipes, TTY, UDP and poll. Passing any
---other handle type will fail with `EINVAL`.
---
---If a handle doesn't have an attached file descriptor yet or the handle itself
---has been closed, this function will return `EBADF`.
---
---**Warning**: Be very careful when using this function. libuv assumes it's in
---control of the file descriptor so any change to it may lead to malfunction.
---
---@param handle uv_handle_t `userdata` for sub-type of `uv_handle_t`
---@return integer|nil, string? err_name, string? err_msg
---@nodiscard
function uv.fileno(handle) end
uv_handle_t.fileno = uv.fileno

---
---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`).
---
---@param handle uv_handle_t # `userdata` for sub-type of `uv_handle_t`
---@return uv.aliases.handle_struct_name
---@return uv.aliases.handle_struct_type
function uv.handle_get_type(handle) end
uv_handle_t.get_type = uv.handle_get_type

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

---
---Timer handles are used to schedule callbacks to be called in the future.
---
---@class uv_timer_t: uv_handle_t
---@section Timer handle
local uv_timer_t = {}

---
---Creates and initializes a new `uv_timer_t`. Returns the Lua userdata wrapping it.
---
---Some examples:
---```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
---```
---
---@return uv_timer_t
---@nodiscard
function uv.new_timer() end

---
---Start the timer. `timeout` and `repeat_n` are in milliseconds.
---
---If `timeout` is zero, the callback fires on the next event loop iteration. If
---`repeat_n` is non-zero, the callback fires first after `timeout` milliseconds and
---then repeatedly after `repeat_n` milliseconds.
---
---@param timer uv_timer_t
---@param timeout integer
---@param repeat_n integer
---@param callback fun()
---@return 0|nil success, string? err_name, string? err_msg
function uv.timer_start(timer, timeout, repeat_n, callback) end
uv_timer_t.start = uv.timer_start

---
---Stop the timer, the callback will not be called anymore.
---
---@param timer uv_timer_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.timer_stop(timer) end
uv_timer_t.stop = uv.timer_stop

---
---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`.
---
---@param timer uv_timer_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.timer_again(timer) end
uv_timer_t.again = uv.timer_again

---
---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.
---
---@param timer uv_timer_t
---@param repeat_n integer
function uv.timer_set_repeat(timer, repeat_n) end
uv_timer_t.set_repeat = uv.timer_set_repeat

---
---Get the timer repeat value.
---
---@param timer uv_timer_t
---@return integer
---@nodiscard
function uv.timer_get_repeat(timer) end
uv_timer_t.get_repeat = uv.timer_get_repeat

---
---Get the timer due value or 0 if it has expired. The time is relative to `uv.now()`.
---
---**Note**: New in libuv version 1.40.0.
---
---@param timer uv_timer_t
---@return integer
---@nodiscard
function uv.timer_get_due_in(timer) end
uv_timer_t.get_due_in = uv.timer_get_due_in

---
---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)
---```
---
---@class uv_prepare_t: uv_handle_t
---@section Prepare handle
local uv_prepare_t = {}

---
---Creates and initializes a new `uv_prepare_t`.
---Returns the Lua userdata wrapping it.
---
---@return uv_prepare_t
---@nodiscard
function uv.new_prepare() end

-- TODO: make sure that the above method can indeed return nil + error.
-- confirmed to never return error see libuv/unix/loop-watcher

---
---Start the handle with the given callback.
---
---@param prepare uv_prepare_t
---@param callback fun()
---@return 0|nil success, string? err_name, string? err_msg
function uv.prepare_start(prepare, callback) end
uv_prepare_t.start = uv.prepare_start

---
---Stop the handle, the callback will no longer be called.
---
---@param prepare uv_prepare_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.prepare_stop(prepare) end
uv_prepare_t.stop = uv.prepare_stop

---
---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)
---```
---
---@class uv_check_t: uv_handle_t
---@section Check handle
local uv_check_t = {}

---
---Creates and initializes a new `uv_check_t`. Returns the Lua userdata wrapping it.
---
---@return uv_check_t
---@nodiscard
function uv.new_check() end

-- TODO: make sure that the above method can indeed return nil + error.
-- confirmed to never error see libuv/unix/loop-watcher

---
---Start the handle with the given callback.
---
---@param check uv_check_t
---@param callback fun()
---@return 0|nil success, string? err_name, string? err_msg
function uv.check_start(check, callback) end
uv_check_t.start = uv.check_start

---
---Stop the handle, the callback will no longer be called.
---
---@param check uv_check_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.check_stop(check) end
uv_check_t.stop = uv.check_stop

---
---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)
---```
---
---@class uv_idle_t: uv_handle_t
---@section Idle handle
local uv_idle_t = {}

---
---Creates and initializes a new `uv_idle_t`. Returns the Lua userdata wrapping it.
---
---@return uv_idle_t
---@nodiscard
function uv.new_idle() end

-- TODO: make sure that the above method can indeed return nil + error.
-- confirmed to never error see libuv/unix/loop-watcher

---
---Start the handle with the given callback.
---
---@param idle uv_idle_t
---@param callback fun()
---@return 0|nil success, string? err_name, string? err_msg
function uv.idle_start(idle, callback) end
uv_idle_t.start = uv.idle_start

---
---Stop the handle, the callback will no longer be called.
---
---@param idle uv_idle_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.idle_stop(idle) end
uv_idle_t.stop = uv.idle_stop

---
---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()
---```
---
---@class uv_async_t: uv_handle_t
---@section Async handle
local uv_async_t = {}

---
---Creates and initializes a new `uv_async_t`. Returns the Lua userdata wrapping
---it. A `nil` callback is allowed.
---
---**Note**: Unlike other handle initialization functions, this immediately starts
---the handle.
---
---@param callback fun(...: uv.aliases.threadargs)|nil
---@return uv_async_t|nil handle, string? err_name, string? err_msg
---@nodiscard
function uv.new_async(callback) end

-- TODO: make sure that the above method can indeed return nil + error.
-- seems like this can technically fail when loop.async_io_watcher.fd is -1
-- but not sure if that is ever practically true for luv
-- TODO: Luv code suggests that a callback is required, the docs seem to be wrong.

---
---Wakeup the event loop and call the async handle's callback.
---
---**Note**: It's safe to call this function from any thread. The callback will be
---called on the loop thread.
---
---**Warning**: libuv will coalesce calls to `uv.async_send(async)`, that is, not
---every call to it will yield an execution of the callback. For example: if
---`uv.async_send()` is called 5 times in a row before the callback is called, the
---callback will only be called once. If `uv.async_send()` is called again after
---the callback was called, it will be called again.
---
---@param async uv_async_t
---@param ... uv.aliases.threadargs
---@return 0|nil success, string? err_name, string? err_msg
function uv.async_send(async, ...) end
uv_async_t.send = uv.async_send

---
---Poll handles are used to watch file descriptors for readability and writability,
---similar to the purpose of [poll(2)](http://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.
---
---@class uv_poll_t: uv_handle_t
---@section Poll handle
local uv_poll_t = {}

---@alias uv.aliases.poll_events
---|'"r"'
---|'"w"'
---|>'"rw"'
---|'"d"'
---|'"rd"'
---|'"wd"'
---|'"rwd"'
---|'"p"'
---|'"rp"'
---|'"wp"'
---|'"rwp"'
---|'"dp"'
---|'"rdp"'
---|'"wdp"'
---|'"rwdp"'

---
---Initialize the handle using a file descriptor.
---The file descriptor is set to non-blocking mode.
---
---@param fd integer # the file descriptor
---@return uv_poll_t|nil, string? err_name, string? err_msg
---@nodiscard
function uv.new_poll(fd) end

---
---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.
---
---@param fd integer # the file descriptor
---@return uv_poll_t|nil, string? err_name, string? err_msg
---@nodiscard
function uv.new_socket_poll(fd) end

---
---Starts polling the file descriptor.
---See alias below for accepted `events`, where `r` is `READABLE`, `w` is `WRITABLE`, `d` is
---`DISCONNECT`, and `p` is `PRIORITIZED`.
---As soon as an event is detected
---the callback will be called with status set to 0, and the detected events set on
---the events field.
---
---The user should not close the socket while the handle is active. If the user
---does that anyway, the callback may be called reporting an error status, but this
---is not guaranteed.
---
---**Note** Calling `uv.poll_start()` on a handle that is already active is fine.
---Doing so will update the events mask that is being watched for.
---
---@param poll uv_poll_t
---@param events uv.aliases.poll_events|nil # (default: `"rw"`)
---@param callback fun(err?: string, events?: uv.aliases.poll_events)
---@return 0|nil success, string? err_name, string? err_msg
function uv.poll_start(poll, events, callback) end
uv_poll_t.start = uv.poll_start

---
---Stop polling the file descriptor, the callback will no longer be called.
---
---@param poll uv_poll_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.poll_stop(poll) end
uv_poll_t.stop = uv.poll_stop

---
---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)
---```
---
---@class uv_signal_t: uv_handle_t
---@section Signal handle
local uv_signal_t = {}

---@alias uv.aliases.signals
---| "sigabrt"    # Abort signal from abort(3)
---| "sigalrm"    # Timer signal from alarm(2)
---| "sigbus"     # Bus error (bad memory access)
---| "sigchld"    # Child stopped or terminated
---| "sigcont"    # Continue if stopped
---| "sigfpe"     # Floating-point exception
---| "sighup"     # Hangup detected on controlling terminal or death of controlling process
---| "sigill"     # Illegal Instruction
---| "sigint"     # Interrupt from keyboard
---| "sigio"      # I/O now possible (4.2BSD)
---| "sigiot"     # IOT trap. A synonym for sigabrt
---| "sigkill"    # Kill signal
---| "sigpipe"    # Broken pipe: write to pipe with no readers; see pipe(7)
---| "sigpoll"    # Pollable event (Sys V); synonym for sigIO
---| "sigprof"    # Profiling timer expired
---| "sigpwr"     # Power failure (System V)
---| "sigquit"    # Quit from keyboard
---| "sigsegv"    # Invalid memory reference
---| "sigstkflt"  # Stack fault on coprocessor
---| "sigstop"    # Stop process
---| "sigtstp"    # Stop typed at terminal
---| "sigsys"     # Bad system call (SVr4); see also seccomp(2)
---| "sigterm"    # Termination signal
---| "sigtrap"    # Trace/breakpoint trap
---| "sigttin"    # Terminal input for background process
---| "sigttou"    # Terminal output for background process
---| "sigurg"     # Urgent condition on socket (4.2BSD)
---| "sigusr1"    # User-defined signal 1
---| "sigusr2"    # User-defined signal 2
---| "sigvtalrm"  # Virtual alarm clock (4.2BSD)
---| "sigxcpu"    # CPU time limit exceeded (4.2BSD); see setrlimit(2)
---| "sigxfsz"    # File size limit exceeded (4.2BSD);see setrlimit(2)
---| "sigwinch"   # Window resize signal (4.3BSD, Sun)
---| "sigbreak"   # CTRL + BREAK has been pressed
---| "siglost"    # File lock lost

---
---Creates and initializes a new `uv_signal_t`.
---Returns the Lua userdata wrapping it.
---
---@return uv_signal_t|nil, string? err_name, string? err_msg
---@nodiscard
function uv.new_signal() end

-- TODO: make sure that the above method can indeed return nil + error.
-- see uv_signal_init and uv__make_pipe, it will only fail if pipe2 fails
-- I belive it is very unlikely it would ever error for this call, but it is theortically possible

---
---Start the handle with the given callback, watching for the given signal.
---
---@param signal uv_signal_t
---@param signum integer|uv.aliases.signals
---@param callback? fun(signum: uv.aliases.signals)
---@return 0|nil success, string? err_name, string? err_msg
function uv.signal_start(signal, signum, callback) end
uv_signal_t.start = uv.signal_start

---
---Same functionality as `uv.signal_start()` but the signal handler is reset the moment the signal is received.
---
---@param signal uv_signal_t
---@param signum integer|uv.aliases.signals
---@param callback? fun(signum: uv.aliases.signals)
---@return 0|nil success, string? err_name, string? err_msg
function uv.signal_start_oneshot(signal, signum, callback) end
uv_signal_t.start_oneshot = uv.signal_start_oneshot

---
---Stop the handle, the callback will no longer be called.
---
---@param signal uv_signal_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.signal_stop(signal) end
uv_signal_t.stop = uv.signal_stop

---
---Process handles will spawn a new process and allow the user to control it and
---establish communication channels with it using streams.
---
---@class uv_process_t: uv_handle_t
---@section Process handle
local uv_process_t = {}

---@alias uv.aliases.spawn_options {args?: string[], stdio?: table<integer, integer|uv_stream_t|nil>, env?: table<string, any>, cwd?: string, uid?: integer, gid?: integer, verbatim?: boolean, detached?: boolean, hide?: boolean}

-- TODO: add descriptions to above fields

---
---Disables inheritance for file descriptors / handles that this process inherited
---from its parent. The effect is that child processes spawned by this process
---don't accidentally inherit these handles.
---It is recommended to call this function as early in your program as possible,
---before the inherited file descriptors can be closed or duplicated.
---
---**Note:** This function works on a best-effort basis: there is no guarantee that
---libuv can discover all file descriptors that were inherited. In general it does
---a better job on Windows than it does on Unix.
---
function uv.disable_stdio_inheritance() end

---
---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)
---```
---
---The `options` table accepts the following fields:
---
--- - `options.args` - Command line arguments as a list of strings. The first
---  string should *not* be the path to the program, since that is already
---  provided via `path`. 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.
---
---@param path string
---@param options uv.aliases.spawn_options
---@param on_exit fun(code: integer, signal: integer)?
---@return uv_process_t|nil, integer|string, string?
function uv.spawn(path, options, on_exit) end

---
---Sends the specified signal to the given process handle.
---
---@param process uv_process_t
---@param signum? integer|uv.aliases.signals # (default: `"sigterm"`)
---@return 0|nil success, string? err_name, string? err_msg
function uv.process_kill(process, signum) end
uv_process_t.kill = uv.process_kill

---
---Sends the specified signal to the given PID.
---
---@param pid integer
---@param signum? integer|uv.aliases.signals # (default: `"sigterm"`)
---@return 0|nil success, string? err_name, string? err_msg
function uv.kill(pid, signum) end

---
---Returns the handle's pid.
---
---@param process uv_process_t
---@return integer
---@nodiscard
function uv.process_get_pid(process) end
uv_process_t.get_pid = uv.process_get_pid

---
---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`.
---
---@class uv_stream_t: uv_handle_t
---@section Stream handle
local uv_stream_t = {}

---@class uv_shutdown_t: uv_req_t

---@class uv_write_t: uv_req_t

---
---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.
---
---@param stream uv_stream_t
---@param callback fun(err?: string)|nil
---@return uv_shutdown_t|nil stream, string? err_name, string? err_msg
function uv.shutdown(stream, callback) end
uv_stream_t.shutdown = uv.shutdown

---
---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.
---
---@param stream uv_stream_t
---@param backlog integer
---@param callback fun(err?: string)
---@return 0|nil success, string? err_name, string? err_msg
function uv.listen(stream, backlog, callback) end
uv_stream_t.listen = uv.listen

---
---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.
---
---```lua
---server:listen(128, function (err)
---  local client = uv.new_tcp()
---  server:accept(client)
---end)
---```
---
---@param stream uv_stream_t
---@param client_stream uv_stream_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.accept(stream, client_stream) end
uv_stream_t.accept = uv.accept

---
---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`.
---
---```lua
---stream:read_start(function (err, chunk)
---  if err then
---    -- handle read error
---  elseif chunk then
---    -- handle data
---  else
---    -- handle disconnect
---  end
---end)
---```
---
---@param stream uv_stream_t
---@param callback fun(err?: string, data?: string)
---@return 0|nil success, string? err_name, string? err_msg
function uv.read_start(stream, callback) end
uv_stream_t.read_start = uv.read_start

---
---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.
---
---@param stream uv_stream_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.read_stop(stream) end
uv_stream_t.read_stop = uv.read_stop

---
---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.
---
---@param stream uv_stream_t
---@param data uv.aliases.buffer
---@param callback fun(err?: string)|nil
---@return uv_write_t|nil stream, string? err_name, string? err_msg
function uv.write(stream, data, callback) end
uv_stream_t.write = uv.write

---
---Extended write function for sending handles over a pipe. The pipe must be
---initialized with `ipc` option `true`.
---
---**Note:** `send_handle` must be a TCP socket or pipe, which is a server or a
---connection (listening or connected state). Bound sockets or pipes will be
---assumed to be servers.
---
---@param stream uv_stream_t
---@param data uv.aliases.buffer
---@param send_handle uv_tcp_t|uv_pipe_t
---@param callback fun()|nil
---@return uv_write_t|nil stream, string? err_name, string? err_msg
function uv.write2(stream, data, send_handle, callback) end
uv_stream_t.write2 = uv.write2

---
---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).
---
---@param stream uv_stream_t
---@param data uv.aliases.buffer
---@return integer|nil, string? err_name, string? err_msg
function uv.try_write(stream, data) end
uv_stream_t.try_write = uv.try_write

---
---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).
---
---@param stream uv_stream_t
---@param data uv.aliases.buffer
---@param send_handle uv_tcp_t|uv_pipe_t
---@return integer|nil, string? err_name, string? err_msg
function uv.try_write2(stream, data, send_handle) end
uv_stream_t.try_write2 = uv.try_write2

---
---Returns `true` if the stream is readable, `false` otherwise.
---
---@param stream uv_stream_t
---@return boolean
---@nodiscard
function uv.is_readable(stream) end
uv_stream_t.is_readable = uv.is_readable

---
---Returns `true` if the stream is writable, `false` otherwise.
---
---@param stream uv_stream_t
---@return boolean
---@nodiscard
function uv.is_writable(stream) end
uv_stream_t.is_writable = uv.is_writable

---
---Enable or disable blocking mode for a stream.
---When blocking mode is enabled all writes complete synchronously. The interface
---remains unchanged otherwise, e.g. completion or failure of the operation will
---still be reported through a callback which is made asynchronously.
---
---**Warning**: Relying too much on this API is not recommended. It is likely to
---change significantly in the future. Currently this only works on Windows and
---only for `uv_pipe_t` handles. Also libuv currently makes no ordering guarantee
---when the blocking mode is changed after write requests have already been
---submitted. Therefore it is recommended to set the blocking mode immediately
---after opening or creating the stream.
---
---@param stream uv_stream_t
---@param blocking boolean
---@return 0|nil success, string? err_name, string? err_msg
function uv.stream_set_blocking(stream, blocking) end
uv_stream_t.set_blocking = uv.stream_set_blocking

---
---Returns the stream's write queue size.
---
---@return integer
---@nodiscard
function uv.stream_get_write_queue_size() end
uv_stream_t.get_write_queue_size = uv.stream_get_write_queue_size

---
---TCP handles are used to represent both TCP streams and servers.
---
---@class uv_tcp_t: uv_stream_t
---@section TCP handle
local uv_tcp_t = {}

---@class uv_connect_t: uv_req_t

---@alias uv.aliases.network_family
---|'"unix"'
---|'"inet"'
---|'"inet6"'
---|'"ipx"'
---|'"netlink"'
---|'"x25"'
---|'"ax25"'
---|'"atmpvc"'
---|'"appletalk"'
---|'"packet"'

---@alias uv.aliases.network_protocols
---|'"ip"'              # internet protocol, pseudo protocol number
---|'"hopopt"'          # hop-by-hop options for ipv6
---|'"icmp"'            # internet control message protocol
---|'"igmp"'            # internet group management protocol
---|'"ggp"'             # gateway-gateway protocol
---|'"ipv4"'            # IPv4 encapsulation
---|'"st"'              # ST datagram mode
---|'"tcp"'             # transmission control protocol
---|'"cbt"'             # CBT, Tony Ballardie <A.Ballardie@cs.ucl.ac.uk>
---|'"egp"'             # exterior gateway protocol
---|'"igp"'             # any private interior gateway (Cisco: for IGRP)
---|'"bbn-rcc"'         # BBN RCC Monitoring
---|'"nvp"'             # Network Voice Protocol
---|'"pup"'             # PARC universal packet protocol
---|'"argus"'           # ARGUS (deprecated)
---|'"emcon"'           # EMCON
---|'"xnet"'            # Cross Net Debugger
---|'"chaos"'           # Chaos
---|'"udp"'             # user datagram protocol
---|'"mux"'             # Multiplexing protocol
---|'"dcn"'             # DCN Measurement Subsystems
---|'"hmp"'             # host monitoring protocol
---|'"prm"'             # packet radio measurement protocol
---|'"xns-idp"'         # Xerox NS IDP
---|'"trunk-1"'         # Trunk-1
---|'"trunk-2"'         # Trunk-2
---|'"leaf-1"'          # Leaf-1
---|'"leaf-2"'          # Leaf-2
---|'"rdp"'             # "reliable datagram" protocol
---|'"irtp"'            # Internet Reliable Transaction Protocol
---|'"iso-tp4"'         # ISO Transport Protocol Class 4
---|'"netblt"'          # Bulk Data Transfer Protocol
---|'"mfe-nsp"'         # MFE Network Services Protocol
---|'"merit-inp"'       # MERIT Internodal Protocol
---|'"dccp"'            # Datagram Congestion Control Protocol
---|'"3pc"'             # Third Party Connect Protocol
---|'"idpr"'            # Inter-Domain Policy Routing Protocol
---|'"xtp"'             # Xpress Tranfer Protocol
---|'"ddp"'             # Datagram Delivery Protocol
---|'"idpr-cmtp"'       # IDPR Control Message Transport Proto
---|'"tp++"'            # TP++ Transport Protocol
---|'"il"'              # IL Transport Protocol
---|'"ipv6"'            # IPv6 encapsulation
---|'"sdrp"'            # Source Demand Routing Protocol
---|'"ipv6-route"'      # Routing Header for IPv6
---|'"ipv6-frag"'       # Fragment Header for IPv6
---|'"idrp"'            # Inter-Domain Routing Protocol
---|'"rsvp"'            # Resource ReSerVation Protocol
---|'"gre"'             # Generic Routing Encapsulation
---|'"dsr"'             # Dynamic Source Routing Protocol
---|'"bna"'             # BNA
---|'"esp"'             # Encap Security Payload
---|'"ipv6-crypt"'      # Encryption Header for IPv6 (not in official list)
---|'"ah"'              # Authentication Header
---|'"ipv6-auth"'       # Authentication Header for IPv6 (not in official list)
---|'"i-nlsp"'          # Integrated Net Layer Security TUBA
---|'"swipe"'           # IP with Encryption
---|'"narp"'            # NBMA Address Resolution Protocol
---|'"mobile"'          # IP Mobility
---|'"tlsp"'            # Transport Layer Security Protocol
---|'"skip"'            # SKIP
---|'"ipv6-icmp"'       # ICMP for IPv6
---|'"ipv6-nonxt"'      # No Next Header for IPv6
---|'"ipv6-opts"'       # Destination Options for IPv6
---|'"#"'               # any host internal protocol
---|'"cftp"'            # CFTP
---|'"#"'               # any local network
---|'"sat-expak"'       # SATNET and Backroom EXPAK
---|'"kryptolan"'       # Kryptolan
---|'"rvd"'             # MIT Remote Virtual Disk Protocol
---|'"ippc"'            # Internet Pluribus Packet Core
---|'"#"'               # any distributed file system
---|'"sat-mon"'         # SATNET Monitoring
---|'"visa"'            # VISA Protocol
---|'"ipcv"'            # Internet Packet Core Utility
---|'"cpnx"'            # Computer Protocol Network Executive
---|'"cphb"'            # Computer Protocol Heart Beat
---|'"wsn"'             # Wang Span Network
---|'"pvp"'             # Packet Video Protocol
---|'"br-sat-mon"'      # Backroom SATNET Monitoring
---|'"sun-nd"'          # SUN ND PROTOCOL-Temporary
---|'"wb-mon"'          # WIDEBAND Monitoring
---|'"wb-expak"'        # WIDEBAND EXPAK
---|'"iso-ip"'          # ISO Internet Protocol
---|'"vmtp"'            # Versatile Message Transport
---|'"secure-vmtp"'     # SECURE-VMTP
---|'"vines"'           # VINES
---|'"ttp"'             # TTP
---|'"nsfnet-igp"'      # NSFNET-IGP
---|'"dgp"'             # Dissimilar Gateway Protocol
---|'"tcf"'             # TCF
---|'"eigrp"'           # Enhanced Interior Routing Protocol (Cisco)
---|'"ospf"'            # Open Shortest Path First IGP
---|'"sprite-rpc"'      # Sprite RPC Protocol
---|'"larp"'            # Locus Address Resolution Protocol
---|'"mtp"'             # Multicast Transport Protocol
---|'"ax.25"'           # AX.25 Frames
---|'"ipip"'            # Yet Another IP encapsulation
---|'"micp"'            # Mobile Internetworking Control Pro.
---|'"scc-sp"'          # Semaphore Communications Sec. Pro.
---|'"etherip"'         # Ethernet-within-IP Encapsulation
---|'"encap"'           # Yet Another IP encapsulation
---|'"#"'               # any private encryption scheme
---|'"gmtp"'            # GMTP
---|'"ifmp"'            # Ipsilon Flow Management Protocol
---|'"pnni"'            # PNNI over IP
---|'"pim"'             # Protocol Independent Multicast
---|'"aris"'            # ARIS
---|'"scps"'            # SCPS
---|'"qnx"'             # QNX
---|'"a/n"'             # Active Networks
---|'"ipcomp"'          # IP Payload Compression Protocol
---|'"snp"'             # Sitara Networks Protocol
---|'"compaq-peer"'     # Compaq Peer Protocol
---|'"ipx-in-ip"'       # IPX in IP
---|'"vrrp"'            # Virtual Router Redundancy Protocol
---|'"pgm"'             # PGM Reliable Transport Protocol
---|'"#"'               # any 0-hop protocol
---|'"l2tp"'            # Layer Two Tunneling Protocol
---|'"ddx"'             # D-II Data Exchange
---|'"iatp"'            # Interactive Agent Transfer Protocol
---|'"stp"'             # Schedule Transfer
---|'"srp"'             # SpectraLink Radio Protocol
---|'"uti"'             # UTI
---|'"smp"'             # Simple Message Protocol
---|'"sm"'              # SM (deprecated)
---|'"ptp"'             # Performance Transparency Protocol
---|'"isis"'            # ISIS over IPv4
---|'"crtp"'            # Combat Radio Transport Protocol
---|'"crudp"'           # Combat Radio User Datagram
---|'"sps"'             # Secure Packet Shield
---|'"pipe"'            # Private IP Encapsulation within IP
---|'"sctp"'            # Stream Control Transmission Protocol
---|'"fc"'              # Fibre Channel
---|'"mobility-header"' # Mobility Header
---|'"manet"'           # MANET Protocols
---|'"hip"'             # Host Identity Protocol
---|'"shim6"'           # Shim6 Protocol
---|'"wesp"'            # Wrapped Encapsulating Security Payload
---|'"rohc"'            # Robust Header Compression

---@alias uv.aliases.tcp_socket_type
---|>'"stream"'
---|'"dgram"'
---|'"raw"'
---|'"rdm"'
---|'"seqpacket"'

---@alias uv.aliases.tcp_bind_flags {ipv6only?: boolean}

---@alias uv.aliases.getpeername_rtn {ip: string, family: uv.aliases.network_family, port: integer}

---@alias uv.aliases.getsockname_rtn uv.aliases.getpeername_rtn

---@alias uv.aliases.socketpair_flags {nonblock: boolean}

---
---Creates and initializes a new `uv_tcp_t`.
---Returns the Lua userdata wrapping it.
---
---@param flags uv.aliases.network_family|integer
---@return uv_tcp_t|nil, string? err_name, string? err_msg
---@nodiscard
function uv.new_tcp(flags) end
---@return uv_tcp_t
---@nodiscard
function uv.new_tcp() end

---
---Open an existing file descriptor or SOCKET as a TCP handle.
---
---**Note:** The passed file descriptor or SOCKET is not checked for its type, but it's required that it represents a valid stream socket.
---
---@param tcp uv_tcp_t
---@param sock integer
---@return 0|nil success, string? err_name, string? err_msg
function uv.tcp_open(tcp, sock) end
uv_tcp_t.open = uv.tcp_open

---
---Enable / disable Nagle's algorithm.
---
---@param tcp uv_tcp_t
---@param enable boolean
---@return 0|nil success, string? err_name, string? err_msg
function uv.tcp_nodelay(tcp, enable) end
uv_tcp_t.nodelay = uv.tcp_nodelay

---
---Enable / disable TCP keep-alive. `delay` is the initial delay in seconds,
---ignored when enable is `false`.
---
---@param tcp uv_tcp_t
---@param enable boolean
---@param delay integer|nil
---@return 0|nil success, string? err_name, string? err_msg
function uv.tcp_keepalive(tcp, enable, delay) end
uv_tcp_t.keepalive = uv.tcp_keepalive

---
---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.
---
---@param tcp uv_tcp_t
---@param enable boolean
---@return 0|nil success, string? err_name, string? err_msg
function uv.tcp_simultaneous_accepts(tcp, enable) end
uv_tcp_t.simultaneous_accepts = uv.tcp_simultaneous_accepts

---
---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()`.
---
---@param tcp uv_tcp_t
---@param host string
---@param port integer
---@param flags uv.aliases.tcp_bind_flags|nil
---@return 0|nil success, string? err_name, string? err_msg
function uv.tcp_bind(tcp, host, port, flags) end
uv_tcp_t.bind = uv.tcp_bind

---
---Get the address of the peer connected to the handle.
---
---@param tcp uv_tcp_t
---@return uv.aliases.getpeername_rtn|nil, string? err_name, string? err_msg
---@nodiscard
function uv.tcp_getpeername(tcp) end
uv_tcp_t.getpeername = uv.tcp_getpeername

---
---Get the current address to which the handle is bound.
---
---@param tcp uv_tcp_t
---@return uv.aliases.getsockname_rtn|nil, string? err_name, string? err_msg
---@nodiscard
function uv.tcp_getsockname(tcp) end
uv_tcp_t.getsockname = uv.tcp_getsockname

---
---Establish an IPv4 or IPv6 TCP connection.
---
---```lua
---local client = uv.new_tcp()
---client:connect("127.0.0.1", 8080, function (err)
---  -- check error and carry on.
---end)
---```
---
---@param tcp uv_tcp_t
---@param host string
---@param port integer
---@param callback fun(err?: string)
---@return uv_connect_t|nil stream, string? err_name, string? err_msg
function uv.tcp_connect(tcp, host, port, callback) end
uv_tcp_t.connect = uv.tcp_connect

---
---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.
---
---@param tcp uv_tcp_t
---@param callback fun()|nil
---@return 0|nil success, string? err_name, string? err_msg
function uv.tcp_close_reset(tcp, callback) end
uv_tcp_t.close_reset = uv.tcp_close_reset

---
---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`.
---
---```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)
---```
---
---@param socktype uv.aliases.tcp_socket_type|integer|nil # (default: `"stream"`)
---@param protocol uv.aliases.network_protocols|integer|nil # (default: `0`)
---@param flags1 uv.aliases.socketpair_flags|nil # (nonblock default: `false`)
---@param flags2 uv.aliases.socketpair_flags|nil # (nonblock default: `false`)
---@return {[1]: integer, [2]: integer}|nil, string? err_name, string? err_msg # [1, 2] file descriptor
function uv.socketpair(socktype, protocol, flags1, flags2) end

---
---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)
---```
---
---@class uv_pipe_t: uv_stream_t
---@section Pipe handle
local uv_pipe_t = {}

---@alias uv.aliases.pipe_chmod_flags
---|'"r"'
---|'"w"'
---|'"rw"'
---|'"wr"'

---@alias uv.aliases.pipe_flags {nonblock: boolean} # (nonblock default: `false`)

---@alias uv.aliases.pipe_rtn {read: integer, write: integer}

---@alias uv.aliases.pipe_2_flags {no_truncate: boolean}

---
---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.
---
---@param ipc boolean|nil
---@return uv_pipe_t
---@nodiscard
function uv.new_pipe(ipc) end

-- TODO: make sure the above method can indeed return nil + error message.
-- confirmed to never return error.

---
---Open an existing file descriptor or `uv_handle_t` as a pipe.
---
---**Note**: The file descriptor is set to non-blocking mode.
---
---@param pipe uv_pipe_t
---@param fd integer
---@return 0|nil success, string? err_name, string? err_msg
function uv.pipe_open(pipe, fd) end
uv_pipe_t.open = uv.pipe_open

---
---Bind the pipe to a file path (Unix) or a name (Windows).
---
---**Note**: Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) bytes,
---typically between 92 and 108 bytes.
---
---@param pipe uv_pipe_t
---@param name string
---@return 0|nil success, string? err_name, string? err_msg
function uv.pipe_bind(pipe, name) end
uv_pipe_t.bind = uv.pipe_bind

---
---Connect to the Unix domain socket or the named pipe.
---
---**Note**: Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) bytes,
---typically between 92 and 108 bytes.
---
---@param pipe uv_pipe_t
---@param name string
---@param callback fun(err?: string)|nil
---@return uv_connect_t|nil stream, string? err_name, string? err_msg
function uv.pipe_connect(pipe, name, callback) end
uv_pipe_t.connect = uv.pipe_connect

---
---Get the name of the Unix domain socket or the named pipe.
---
---@param pipe uv_pipe_t
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.pipe_getsockname(pipe) end
uv_pipe_t.getsockname = uv.pipe_getsockname

---
---Get the name of the Unix domain socket or the named pipe to which the handle is
---connected.
---
---@param pipe uv_pipe_t
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.pipe_getpeername(pipe) end
uv_pipe_t.getpeername = uv.pipe_getpeername

---
---Set the number of pending pipe instance handles when the pipe server is waiting
---for connections.
---
---**Note**: This setting applies to Windows only.
---
---@param pipe uv_pipe_t
---@param count integer
function uv.pipe_pending_instances(pipe, count) end
uv_pipe_t.pending_instances = uv.pipe_pending_instances

---
---Returns the pending pipe count for the named pipe.
---
---@param pipe uv_pipe_t
---@return integer
---@nodiscard
function uv.pipe_pending_count(pipe) end
uv_pipe_t.pending_count = uv.pipe_pending_count

---
---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)`.
---
---@param pipe uv_pipe_t
---@return string
---@nodiscard
function uv.pipe_pending_type(pipe) end
uv_pipe_t.pending_type = uv.pipe_pending_type

---
---Alters pipe permissions, allowing it to be accessed from processes run by different users.
---Makes the pipe writable or readable by all users.
---See below for accepted flags, where `r` is `READABLE` and `w` is `WRITABLE`.
---This function is blocking.
---
---@param pipe uv_pipe_t
---@param flags uv.aliases.pipe_chmod_flags
---@return 0|nil success, string? err_name, string? err_msg
function uv.pipe_chmod(pipe, flags) end
uv_pipe_t.chmod = uv.pipe_chmod

---
---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.
---
---```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)
---```
---
---@param read_flags uv.aliases.pipe_flags|nil  # (nonblock default: `false`)
---@param write_flags uv.aliases.pipe_flags|nil # (nonblock default: `false`)
---@return uv.aliases.pipe_rtn|nil, string? err_name, string? err_msg
---@nodiscard
function uv.pipe(read_flags, write_flags) end

---
---Bind the pipe to a file path (Unix) or a name (Windows).
---
---`Flags`:
---
--- - If `type(flags)` is `number`, it must be `0` or `uv.constants.PIPE_NO_TRUNCATE`.
--- - If `type(flags)` is `table`, it must be `{}` or `{ no_trunate = true|false }`.
--- - If `type(flags)` is `nil`, it use default value `0`.
--- - Returns `EINVAL` for unsupported flags without performing the bind operation.
---
---Supports Linux abstract namespace sockets. namelen must include the leading '\0' byte but not the trailing nul byte.
---
---**Note**:
---1. Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) bytes,
---typically between 92 and 108 bytes.
---2. New in version 1.46.0.
---
---@param pipe uv_pipe_t
---@param name string
---@param flags integer|uv.aliases.pipe_2_flags|nil # (default: 0)
---@return 0|nil success, string? err_name, string? err_msg
function uv.pipe_bind2(pipe, name, flags) end
uv_pipe_t.bind2 = uv.pipe_bind2

---
---Connect to the Unix domain socket or the named pipe.
---
---`Flags`:
---
--- - If `type(flags)` is `number`, it must be `0` or `uv.constants.PIPE_NO_TRUNCATE`.
--- - If `type(flags)` is `table`, it must be `{}` or `{ no_trunate = true|false }`.
--- - If `type(flags)` is `nil`, it use default value `0`.
--- - Returns `EINVAL` for unsupported flags without performing the bind operation.
---
---Supports Linux abstract namespace sockets. namelen must include the leading nul byte but not the trailing nul byte.
---
---**Note**:
---1. Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) bytes,
---typically between 92 and 108 bytes.
---2. New in version 1.46.0.
---
---@param pipe uv_pipe_t
---@param name string
---@param flags integer|uv.aliases.pipe_2_flags|nil # (default: 0)
---@param callback fun(err?: string)|nil
---@return uv_connect_t|nil stream, string? err_name, string? err_msg
function uv.pipe_connect2(pipe, name, flags, callback) end
uv_pipe_t.connect2 = uv.pipe_connect2

---
---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)
---```
---
---@class uv_tty_t: uv_stream_t
---@section TTY handle
local uv_tty_t = {}

---@alias uv.aliases.tty_fd
---|0 # stdin
---|1 # stdout
---|2 # stderr

---@alias uv.aliases.tty_mode
---|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)

---@alias uv.aliases.tty_vsterm_state
---|'supported'
---|'unsupported'

---
---Initialize a new TTY stream with the given file descriptor.
---See below for possible file descriptors.
---
---On Unix this function will determine the path of the fd of the terminal using
---ttyname_r(3), open it, and use it if the passed file descriptor refers to a TTY.
---
---This lets libuv put the tty in non-blocking mode without affecting other
---processes that share the tty.
---
---This function is not thread safe on systems that don’t support ioctl TIOCGPTN or TIOCPTYGNAME, for instance OpenBSD and Solaris.
---
---**Note:** If reopening the TTY fails, libuv falls back to blocking writes.
---
---@param fd uv.aliases.tty_fd|integer
---@param readable boolean
---@return uv_tty_t|nil, string? err_name, string? err_msg
---@nodiscard
function uv.new_tty(fd, readable) end

---
---Set the TTY using the specified terminal mode.
---
---Parameter `mode` is a C enum with the values below.
---
---@param tty uv_tty_t
---@param mode uv.aliases.tty_mode
---@return 0|nil success, string? err_name, string? err_msg
function uv.tty_set_mode(tty, mode) end
uv_tty_t.set_mode = uv.tty_set_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()`.
---
---@return 0|nil success, string? err_name, string? err_msg
function uv.tty_reset_mode() end

---
---Gets the current Window width and height.
---
---@param tty uv_tty_t
---@return integer|nil width, integer|string height_or_errname, string? err_msg
---@nodiscard
function uv.tty_get_winsize(tty) end
uv_tty_t.get_winsize = uv.tty_get_winsize

---
---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.
---
---@param state uv.aliases.tty_vsterm_state
function uv.tty_set_vterm_state(state) end

---
---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`.
---
---@return uv.aliases.tty_vsterm_state|nil, string? err_name, string? err_msg
---@nodiscard
function uv.tty_get_vterm_state() end

---
---UDP handles encapsulate UDP communication for both clients and servers.
---
---@class uv_udp_t: uv_handle_t
---@section UDP handle
local uv_udp_t = {}

---@class uv_udp_send_t: userdata

---@alias uv.aliases.new_udp_flags {family: uv.aliases.network_family, mmsgs: integer}

---@alias uv.aliases.udp_bind_flags {ipv6only: boolean, reuseaddr: boolean}

---@alias uv.aliases.udp_getsockname_rtn uv.aliases.getsockname_rtn

---@alias uv.aliases.udp_getpeername_rtn uv.aliases.getpeername_rtn

---@alias uv.aliases.udp_membership '"join"'|'"leave"'

---@alias uv.aliases.udp_recv_start_callback_flags {partial: boolean|nil, mmsg_chunk: boolean|nil}

---
---Creates and initializes a new `uv_udp_t`. Returns the Lua userdata wrapping
---it. The actual socket is created lazily.
---
---See below for accepted `family` values.
---
---When specified, `mmsgs` determines the number of messages able to be received
---at one time via `recvmmsg(2)` (the allocated buffer will be sized to be able
---to fit the specified number of max size dgrams). Only has an effect on
---platforms that support `recvmmsg(2)`.
---
---**Note:** For backwards compatibility reasons, `flags` can also be a string or
---integer. When it is a string, it will be treated like the `family` key above.
---When it is an integer, it will be used directly as the `flags` parameter when
---calling `uv_udp_init_ex`.
---
---@param flags uv.aliases.new_udp_flags|uv.aliases.network_family|integer # (mmsgs default: `1`)
---@return uv_udp_t|nil, string? err_name, string? err_msg
---@nodiscard
function uv.new_udp(flags) end
---@return uv_udp_t
---@nodiscard
function uv.new_udp() end

---
---Returns the handle's send queue size.
---
---@return integer
---@nodiscard
function uv.udp_get_send_queue_size() end
uv_udp_t.get_send_queue_size = uv.udp_get_send_queue_size

---
---Returns the handle's send queue count.
---
---@return integer
---@nodiscard
function uv.udp_get_send_queue_count() end
uv_udp_t.get_send_queue_count = uv.udp_get_send_queue_count

---
---Opens an existing file descriptor or Windows SOCKET as a UDP handle.
---
---Unix only: The only requirement of the sock argument is that it follows the
---datagram contract (works in unconnected mode, supports sendmsg()/recvmsg(),
---etc). In other words, other datagram-type sockets like raw sockets or netlink
---sockets can also be passed to this function.
---
---The file descriptor is set to non-blocking mode.
---
---**Note:** The passed file descriptor or SOCKET is not checked for its type, but
---it's required that it represents a valid datagram socket.
---
---@param udp uv_udp_t
---@param fd integer
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_open(udp, fd) end
uv_udp_t.open = uv.udp_open

---
---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`.
---
---@param udp uv_udp_t
---@param host string
---@param port integer
---@param flags uv.aliases.udp_bind_flags|nil
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_bind(udp, host, port, flags) end
uv_udp_t.bind = uv.udp_bind

---
---Get the local IP and port of the UDP handle.
---
---@param udp uv_udp_t
---@return uv.aliases.udp_getsockname_rtn|nil, string? err_name, string? err_msg
---@nodiscard
function uv.udp_getsockname(udp) end
uv_udp_t.getsockname = uv.udp_getsockname

---
---Get the remote IP and port of the UDP handle on connected UDP handles.
---
---@param udp uv_udp_t
---@return uv.aliases.udp_getpeername_rtn|nil, string? err_name, string? err_msg
---@nodiscard
function uv.udp_getpeername(udp) end
uv_udp_t.getpeername = uv.udp_getpeername

---
---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"`.
---
---@param udp uv_udp_t
---@param multicast_addr string
---@param interface_addr string|nil
---@param membership uv.aliases.udp_membership
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_set_membership(udp, multicast_addr, interface_addr, membership) end
uv_udp_t.set_membership = uv.udp_set_membership

---
---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"`.
---
---@param udp uv_udp_t
---@param multicast_addr string
---@param interface_addr string|nil
---@param source_addr string
---@param membership uv.aliases.udp_membership
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_set_source_membership(udp, multicast_addr, interface_addr, source_addr, membership) end
uv_udp_t.set_source_membership = uv.udp_set_source_membership

---
---Set IP multicast loop flag. Makes multicast packets loop back to local
---sockets.
---
---@param udp uv_udp_t
---@param on boolean
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_set_multicast_loop(udp, on) end
uv_udp_t.set_multicast_loop = uv.udp_set_multicast_loop

---
---Set the multicast ttl.
---`ttl` is an integer 1 through 255.
---
---@param udp uv_udp_t
---@param ttl integer
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_set_multicast_ttl(udp, ttl) end
uv_udp_t.set_multicast_ttl = uv.udp_set_multicast_ttl

---
---Set the multicast interface to send or receive data on.
---
---@param udp uv_udp_t
---@param interface_addr string
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_set_multicast_interface(udp, interface_addr) end
uv_udp_t.set_multicast_interface = uv.udp_set_multicast_interface

---
---Set broadcast on or off.
---
---@param udp uv_udp_t
---@param on boolean
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_set_broadcast(udp, on) end
uv_udp_t.set_broadcast = uv.udp_set_broadcast

---
---Set the time to live.
---`ttl` is an integer 1 through 255.
---
---@param udp uv_udp_t
---@param ttl integer
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_set_ttl(udp, ttl) end
uv_udp_t.set_ttl = uv.udp_set_ttl

---
---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.
---
---@param udp uv_udp_t
---@param data uv.aliases.buffer
---@param host string
---@param port integer
---@param callback fun(err?: string)
---@return uv_udp_send_t|nil stream, string? err_name, string? err_msg
function uv.udp_send(udp, data, host, port, callback) end
uv_udp_t.send = uv.udp_send

---
---Same as `uv.udp_send()`, but won't queue a send request if it can't be
---completed immediately.
---
---@param udp uv_udp_t
---@param data uv.aliases.buffer
---@param host string
---@param port integer
---@return integer|nil, string? err_name, string? err_msg
function uv.udp_try_send(udp, data, host, port) end
uv_udp_t.try_send = uv.udp_try_send

---
---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.
---
---@param udp uv_udp_t
---@param callback fun(err?: string, data?: string, add?: uv.aliases.udp_getpeername_rtn, flags: uv.aliases.udp_recv_start_callback_flags)
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_recv_start(udp, callback) end
uv_udp_t.recv_start = uv.udp_recv_start

---
---Stop listening for incoming datagrams.
---
---@param udp uv_udp_t
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_recv_stop(udp) end
uv_udp_t.recv_stop = uv.udp_recv_stop

---
---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.
---
---@param udp uv_udp_t
---@param host string
---@param port integer
---@return 0|nil success, string? err_name, string? err_msg
function uv.udp_connect(udp, host, port) end
uv_udp_t.connect = uv.udp_connect

---
---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.
---
---@class uv_fs_event_t: uv_handle_t
---@section FS Event handle
local uv_fs_event_t = {}

---@alias uv.aliases.fs_event_start_flags {watch_entry?: boolean, stat?: boolean, recursive?: boolean}

---@alias uv.aliases.fs_event_start_callback_events {change?: boolean, rename?: boolean}

---
---Creates and initializes a new `uv_fs_event_t`.
---Returns the Lua userdata wrapping it.
---
---@return uv_fs_event_t|nil, string? err_name, string? err_msg
---@nodiscard
function uv.new_fs_event() end

-- TODO: make sure that the above method can indeed return nil + error.
-- can fail in case the feature is not supported, see unix/no-fsevents.c

---
---Start the handle with the given callback, which will watch the specified path
---for changes.
---
---@param fs_event uv_fs_event_t
---@param path string
---@param flags uv.aliases.fs_event_start_flags # (all flags have default of `false`)
---@param callback fun(err?: string, filename: string, events: uv.aliases.fs_event_start_callback_events)
---@return 0|nil success, string? err_name, string? err_msg
function uv.fs_event_start(fs_event, path, flags, callback) end
uv_fs_event_t.start = uv.fs_event_start

---
---Stop the handle, the callback will no longer be called.
---
---@return 0|nil success, string? err_name, string? err_msg
function uv.fs_event_stop() end
uv_fs_event_t.stop = uv.fs_event_stop

---
---Get the path being monitored by the handle.
---
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.fs_event_getpath() end
uv_fs_event_t.getpath = uv.fs_event_getpath

---
---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.
---
---@class uv_fs_poll_t: uv_handle_t
---@section FS Poll handle
local uv_fs_poll_t = {}

---
---Creates and initializes a new `uv_fs_poll_t`.
---Returns the Lua userdata wrapping it.
---
---@return uv_fs_poll_t
---@nodiscard
function uv.new_fs_poll() end

-- TODO: make sure that the above method can indeed return nil + error.
-- confirmed to never return error see libuv/fs-poll#uv_fs_poll_init

---
---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.
---
---@param fs_poll uv_fs_poll_t
---@param path string
---@param interval integer
---@param callback fun(err?: string, prev: uv.aliases.fs_stat_table, curr: uv.aliases.fs_stat_table)
---@return 0|nil success, string? err_name, string? err_msg
function uv.fs_poll_start(fs_poll, path, interval, callback) end
uv_fs_poll_t.start = uv.fs_poll_start

---
---Stop the handle, the callback will no longer be called.
---
---@return 0|nil success, string? err_name, string? err_msg
function uv.fs_poll_stop() end
uv_fs_poll_t.stop = uv.fs_poll_stop

---
---Get the path being monitored by the handle.
---
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.fs_poll_getpath() end
uv_fs_poll_t.getpath = uv.fs_poll_getpath

---
---@section File system operations
---
---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` 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)
---```
---

---@class uv_fs_t: uv_req_t

---@class luv_dir_t: userdata
local luv_dir_t = {}

---@alias uv.aliases.fs_access_flags
---Open file for reading.
---
---Fails if the file does not exist.
---
---Mode: O_RDONLY.
---|'"r"'
---Open file for reading in synchronous mode.
---Instructs the operating system to bypass the local file system cache.
---
---This is primarily useful for opening files on NFS mounts as it allows you to
---skip the potentially stale local cache. It has a very real impact on I/O
---performance so don't use this flag unless you need it.
---
---Note that this doesn't turn this call into a synchronous blocking call.
---
---Mode: O_RDONLY + O_SYNC.
---|'"rs"'
---Same as `'rs'`.
---|'"sr"'
---Open file for reading and writing.
---
---Fails if the file does not exist.
---
---Mode: O_RDWR.
---|'"r+"'
---Open file for reading and writing, telling the OS to open it synchronously.
---
---See notes for `'rs'` about using this with caution.
---
---Mode: O_RDWR + O_SYNC.
---|'"rs+"'
---Same as `'rs+'`.
---|'"sr+"'
---Open file for writing.
---
---The file is created (if it does not exist) or truncated (if it exists).
---
---Mode: O_TRUNC + O_CREAT + O_WRONLY.
---|'"w"'
---Open file for writing.
---
---Fails if the file exists.
---
---Mode: O_TRUNC + O_CREAT + O_WRONLY + O_EXCL.
---|'"wx"'
---Same as `'wx'`.
---|'"xw"'
---Open file for reading and writing.
---
---The file is created (if it does not exist) or truncated (if it exists).
---
---Mode: O_TRUNC + O_CREAT + O_RDWR.
---|'"w+"'
---Open file for reading and writing.
---
---Fails if file exists.
---
---Mode: O_TRUNC + O_CREAT + O_RDWR + O_EXCL.
---|'"wx+"'
---Same as `'wx+'`.
---|'"xw+"'
---Open file for appending.
---
---The file is created if it does not exist.
---
---Mode: O_APPEND + O_CREAT + O_WRONLY.
---|'"a"'
---Open file for appending.
---
---Fails if the file exists.
---
---Mode: O_APPEND + O_CREAT + O_WRONLY + O_EXCL.
---|'"ax"'
---Same as `'ax'`.
---|'"xa"'
---Open file for reading and appending.
---
---The file is created if it does not exist.
---
---Mode: O_APPEND + O_CREAT + O_RDWR.
---|'"a+"'
---Like `'a+'` but fails if `path` exists.
---
---Mode: O_APPEND + O_CREAT + O_RDWR + O_EXCL
---|'"ax+"'
---Same as `'ax+'`.
---|'"xa+"'

---@alias uv.aliases.fs_stat_types
---|'"file"'
---|'"directory"'
---|'"link"'
---|'"fifo"'
---|'"socket"'
---|'"char"'
---|'"block"'

---@alias uv.aliases.fs_stat_table {gen: integer, flags: integer, atime: {nsec: integer, sec: integer}, ctime: {nsec: integer, sec: integer}, birthtime: {nsec: integer, sec: integer}, uid: integer, gid: integer, mtime: {nsec: integer, sec: integer}, size: integer, type?: uv.aliases.fs_stat_types, nlink: integer, dev: integer, mode: integer, rdev: integer, ino: integer, blksize: integer, blocks: integer}

---@alias uv.aliases.fs_types
---|'"file"'
---|'"directory"'
---|'"link"'
---|'"fifo"'
---|'"socket"'
---|'"char"'
---|'"block"'
---|'"unknown"'

---@alias uv.aliases.fs_access_mode
---Tests for readbility.
---|'R'
---Tests for writiblity.
---|'W'
---Tests for executibility.
---|'X'
---Tests for readbility and writiblity.
---|'RW'
---Tests for readbility and executibility.
---|'RX'
---Tests for writiblity and executibility.
---|'WX'
---Tests for writiblity and readbility and executibility.
---|'WRX'
---A bitwise OR mask.
---|integer

---@alias uv.aliases.fs_readdir_entries {type: uv.aliases.fs_types, name: string}

---@alias uv.aliases.fs_symlink_flags {dir: boolean, junction: boolean}

---@alias uv.aliases.fs_copyfile_flags {excl: boolean, ficlone: boolean, ficlone_force: boolean}

---@alias uv.aliases.fs_statfs_stats_type
---Always 0 on Windows, sun, MVS, OpenBSD, NetBSD, HAIKU, QNK.
---|0
---ADFS_SUPER_MAGIC = 0xadf5
---|44533
---AFFS_SUPER_MAGIC = 0xadff
---|44543
---AFS_SUPER_MAGIC = 0x5346414f
---|1397113167
---ANON_INODE_FS_MAGIC = 0x09041934 | Anonymous inode FS (for pseudofiles that have no name; e.g., epoll, signalfd, bpf)
---|151263540
---AUTOFS_SUPER_MAGIC = 0x0187
---|391
---BDEVFS_MAGIC = 0x62646576
---|1650746742
---BEFS_SUPER_MAGIC = 0x42465331
---|1111905073
---BFS_MAGIC = 0x1badface
---|464386766
---BINFMTFS_MAGIC = 0x42494e4d
---|1112100429
---BPF_FS_MAGIC = 0xcafe4a11
---|3405662737
---BTRFS_SUPER_MAGIC = 0x9123683e
---|2435016766
---BTRFS_TEST_MAGIC = 0x73727279
---|1936880249
---CGROUP_SUPER_MAGIC = 0x27e0eb | Cgroup pseudo FS
---|2613483
---CGROUP2_SUPER_MAGIC = 0x63677270 | Cgroup v2 pseudo FS
---|1667723888
---CIFS_MAGIC_NUMBER = 0xff534d42
---|4283649346
---CODA_SUPER_MAGIC = 0x73757245
---|1937076805
---COH_SUPER_MAGIC = 0x012ff7b7
---|19920823
---CRAMFS_MAGIC = 0x28cd3d45
---|684539205
---DEBUGFS_MAGIC = 0x64626720
---|1684170528
---DEVFS_SUPER_MAGIC = 0x1373 | Linux 2.6.17 and earlier
---|4979
---DEVPTS_SUPER_MAGIC =	0x1cd1
---|7377
---ECRYPTFS_SUPER_MAGIC	=	0xf15f
---|61791
---EFIVARFS_MAGIC	=	0xde5e81e4
---|3730735588
---EFS_SUPER_MAGIC =	0x00414a53
---|4278867
---EXT_SUPER_MAGIC = 0x137d | Linux 2.0 and earlier
---|4989
---EXT2_OLD_SUPER_MAGIC = 0xef51
---|61265
---EXT2_SUPER_MAGIC = 0xef53
---|61267
---EXT3_SUPER_MAGIC = 0xef53
---|61267
---EXT4_SUPER_MAGIC = 0xef53
---|61267
---F2FS_SUPER_MAGIC = 0xf2f52010
---|4076150800
---FUSE_SUPER_MAGIC = 0x65735546
---|1702057286
---FUTEXFS_SUPER_MAGIC = 0xbad1dea | Unused
---|195894762
---HFS_SUPER_MAGIC = 0x4244
---|16964
---HOSTFS_SUPER_MAGIC = 0x00c0ffee
---|12648430
---HPFS_SUPER_MAGIC = 0xf995e849
---|4187351113
---HUGETLBFS_MAGIC = 0x958458f6
---|2508478710
---ISOFS_SUPER_MAGIC = 0x9660
---|38496
---JFFS2_SUPER_MAGIC = 0x72b6
---|29366
---JFS_SUPER_MAGIC = 0x3153464a
---|827541066
---MINIX_SUPER_MAGIC = 0x137f | original minix FS
---|4991
---MINIX_SUPER_MAGIC2 = 0x138f | 30 char minix FS
---|5007
---MINIX2_SUPER_MAGIC = 0x2468 | minix V2 FS
---|9320
---MINIX2_SUPER_MAGIC2 = 0x2478 | minix V2 FS, 30 char names
---|9336
---MINIX3_SUPER_MAGIC = 0x4d5a | minix V3 FS, 60 char names
---|19802
---MQUEUE_MAGIC = 0x19800202 | POSIX message queue FS
---|427819522
---MSDOS_SUPER_MAGIC = 0x4d44
---|19780
---MTD_INODE_FS_MAGIC = 0x11307854
---|288389204
---NCP_SUPER_MAGIC = 0x564c
---|22092
---NFS_SUPER_MAGIC = 0x6969
---|26985
---NILFS_SUPER_MAGIC = 0x3434
---|13364
---NSFS_MAGIC = 0x6e736673
---|1853056627
---NTFS_SB_MAGIC = 0x5346544e
---|1397118030
---OCFS2_SUPER_MAGIC = 0x7461636f
---|1952539503
---OPENPROM_SUPER_MAGIC = 0x9fa1
---|40865
---OVERLAYFS_SUPER_MAGIC = 0x794c7630
---|2035054128
---PIPEFS_MAGIC = 0x50495045
---|1346981957
---PROC_SUPER_MAGIC = 0x9fa0 | /proc FS
---|40864
---PSTOREFS_MAGIC = 0x6165676c
---|1634035564
---QNX4_SUPER_MAGIC = 0x002f
---|47
---QNX6_SUPER_MAGIC = 0x68191122
---|1746473250
---RAMFS_MAGIC = 0x858458f6
---|2240043254
---REISERFS_SUPER_MAGIC = 0x52654973
---|1382369651
---ROMFS_MAGIC = 0x7275
---|29301
---SECURITYFS_MAGIC = 0x73636673
---|1935894131
---SELINUX_MAGIC = 0xf97cff8c
---|4185718668
---SMACK_MAGIC = 0x43415d53
---|1128357203
---SMB_SUPER_MAGIC = 0x517b
---|20859
---SMB2_MAGIC_NUMBER = 0xfe534d42
---|4266872130
---SOCKFS_MAGIC = 0x534f434b
---|1397703499
---SQUASHFS_MAGIC = 0x73717368
---|1936814952
---SYSFS_MAGIC = 0x62656572
---|1650812274
---SYSV2_SUPER_MAGIC = 0x012ff7b6
---|19920822
---SYSV4_SUPER_MAGIC = 0x012ff7b5
---|19920821
---TMPFS_MAGIC = 0x01021994
---|16914836
---TRACEFS_MAGIC = 0x74726163
---|1953653091
---UDF_SUPER_MAGIC = 0x15013346
---|352400198
---UFS_MAGIC = 0x00011954
---|72020
---USBDEVICE_SUPER_MAGIC = 0x9fa2
---|40866
---V9FS_MAGIC = 0x01021997
---|16914839
---VXFS_SUPER_MAGIC = 0xa501fcf5
---|2768370933
---XENFS_SUPER_MAGIC = 0xabba1974
---|2881100148
---XENIX_SUPER_MAGIC = 0x012ff7b4
---|19920820
---XFS_SUPER_MAGIC = 0x58465342
---|1481003842
---_XIAFS_SUPER_MAGIC = 0x012fd16d | Linux 2.0 and earlier
---|19911021

---@alias uv.aliases.fs_statfs_stats {type: uv.aliases.fs_statfs_stats_type, bzise: integer, blocks: integer, bfree: integer, bavail: integer, files: integer, ffree: integer}

---
---Equivalent to `close(2)`.
---
---@param fd integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_close(fd, callback) end
---@param fd integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_close(fd) end

---
---Equivalent to `open(2)`.
---See below for available access `flags`.
---
---**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.
---
---@param path string
---@param flags uv.aliases.fs_access_flags|integer
---@param mode integer
---@param callback fun(err: nil|string, fd: integer|nil)
---@return uv_fs_t
function uv.fs_open(path, flags, mode, callback) end
---@param path string
---@param flags uv.aliases.fs_access_flags|integer
---@param mode integer
---@return integer|nil fd, string? err_name, string? err_msg
---@nodiscard
function uv.fs_open(path, flags, mode) end

---
---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.
---
---@param fd integer
---@param size integer
---@param offset integer|nil
---@param callback fun(err: nil|string, data: string|nil)
---@return uv_fs_t
function uv.fs_read(fd, size, offset, callback) end
---@param fd integer
---@param size integer
---@param callback fun(err: nil|string, data: string|nil)
---@return uv_fs_t
function uv.fs_read(fd, size, callback) end
---@param fd integer
---@param size integer
---@param offset integer|nil
---@return string|nil data, string? err_name, string? err_msg
---@nodiscard
function uv.fs_read(fd, size, offset) end

---
---Equivalent to `unlink(2)`.
---
---@param path string
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_unlink(path, callback) end
---@param path string
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_unlink(path) end

---
---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.
---
---@param fd integer
---@param data uv.aliases.buffer
---@param offset integer|nil
---@param callback fun(err: nil|string, bytes: integer|nil)
---@return uv_fs_t
function uv.fs_write(fd, data, offset, callback) end
---@param fd integer
---@param data uv.aliases.buffer
---@param callback fun(err: nil|string, bytes: integer|nil)
---@return uv_fs_t
function uv.fs_write(fd, data, callback) end
---@param fd integer
---@param data uv.aliases.buffer
---@param offset integer|nil
---@return integer|nil bytes, string? err_name, string? err_msg
function uv.fs_write(fd, data, offset) end

---
---Equivalent to `mkdir(2)`.
---
---@param path string
---@param mode integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_mkdir(path, mode, callback) end
---@param path string
---@param mode integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_mkdir(path, mode) end

---
---Equivalent to `mkdtemp(3)`.
---
---@param template string
---@param callback fun(err: nil|string, path: string|nil)
---@return uv_fs_t
function uv.fs_mkdtemp(template, callback) end
---@param template string
---@return string|nil path, string? err_name, string? err_msg
---@nodiscard
function uv.fs_mkdtemp(template) end

---
---Equivalent to `mkstemp(3)`. Returns a temporary file handle and filename.
---
---@param template string
---@param callback fun(err: nil|string, fd: integer|nil, path: string|nil)
---@return uv_fs_t
function uv.fs_mkstemp(template, callback) end
---@param template string
---@return integer|nil fd, string path_or_errname, string? err_msg
---@nodiscard
function uv.fs_mkstemp(template) end

---
---Equivalent to `rmdir(2)`.
---
---@param path string
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_rmdir(path, callback) end
---@param path string
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_rmdir(path) end

---
---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.
---
---@param path string
---@param callback fun(err: nil|string, success: uv_fs_t|nil)
---@return uv_fs_t|nil, string? err_name, string? err_msg
function uv.fs_scandir(path, callback) end
---@param path string
---@return uv_fs_t|nil success, string? err_name, string? err_msg
---@nodiscard
function uv.fs_scandir(path) end

---
---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.
---
---@param fs uv_fs_t
---@return string|nil, string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.fs_scandir_next(fs) end

---
---Equivalent to `stat(2)`.
---
---@param path string
---@param callback fun(err: nil|string, stat: uv.aliases.fs_stat_table|nil)
---@return uv_fs_t
function uv.fs_stat(path, callback) end
---@param path string
---@return uv.aliases.fs_stat_table|nil stat, string? err_name, string? err_msg
---@nodiscard
function uv.fs_stat(path) end

---
---Equivalent to `fstat(2)`.
---
---@param fd integer
---@param callback fun(err: nil|string, stat: uv.aliases.fs_stat_table|nil)
---@return uv_fs_t
function uv.fs_fstat(fd, callback) end
---@param fd integer
---@return uv.aliases.fs_stat_table|nil stat, string? err_name, string? err_msg
---@nodiscard
function uv.fs_fstat(fd) end

---
---Equivalent to `lstat(2)`.
---
---@param path string
---@param callback fun(err: nil|string, stat: uv.aliases.fs_stat_table|nil)
---@return uv_fs_t
function uv.fs_lstat(path, callback) end
---@param path string
---@return uv.aliases.fs_stat_table|nil stat, string? err_name, string? err_msg
---@nodiscard
function uv.fs_lstat(path) end

---
---Equivalent to `rename(2)`.
---
---@param path string
---@param new_path string
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_rename(path, new_path, callback) end
---@param path string
---@param new_path string
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_rename(path, new_path) end

---
---Equivalent to `fsync(2)`.
---
---@param fd integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_fsync(fd, callback) end
---@param fd integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_fsync(fd) end

---
---Equivalent to `fdatasync(2)`.
---
---@param fd integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_fdatasync(fd, callback) end
---@param fd integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_fdatasync(fd) end

---
---Equivalent to `ftruncate(2)`.
---
---@param fd integer
---@param offset integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_ftruncate(fd, offset, callback) end
---@param fd integer
---@param offset integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_ftruncate(fd, offset) end

---
---Limited equivalent to `sendfile(2)`. Returns the number of bytes written.
---
---@param out_fd integer
---@param in_fd integer
---@param in_offset integer
---@param size integer
---@param callback fun(err: nil|string, bytes: integer|nil)
---@return uv_fs_t
function uv.fs_sendfile(out_fd, in_fd, in_offset, size, callback) end
---@param out_fd integer
---@param in_fd integer
---@param in_offset integer
---@param size integer
---@return integer|nil bytes, string? err_name, string? err_msg
function uv.fs_sendfile(out_fd, in_fd, in_offset, size) end

---
---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.
---
---@param path string
---@param mode uv.aliases.fs_access_mode|integer
---@param callback fun(err: nil|string, permission: boolean|nil)
---@return uv_fs_t
function uv.fs_access(path, mode, callback) end
---@param path string
---@param mode uv.aliases.fs_access_mode|integer
---@return boolean|nil permission, string? err_name, string? err_msg
---@nodiscard
function uv.fs_access(path, mode) end

---
---Equivalent to `chmod(2)`.
---
---@param path string
---@param mode integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_chmod(path, mode, callback) end
---@param path string
---@param mode integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_chmod(path, mode) end

---
---Equivalent to `fchmod(2)`.
---
---@param fd integer
---@param mode integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_fchmod(fd, mode, callback) end
---@param fd integer
---@param mode integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_fchmod(fd, mode) end

---
---Equivalent to `utime(2)`.
---
---@param path string
---@param atime number
---@param mtime number
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_utime(path, atime, mtime, callback) end
---@param path string
---@param atime number
---@param mtime number
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_utime(path, atime, mtime) end

---
---Equivalent to `futime(2)`.
---
---@param fd integer
---@param atime number
---@param mtime number
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_futime(fd, atime, mtime, callback) end
---@param fd integer
---@param atime number
---@param mtime number
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_futime(fd, atime, mtime) end

---
---Equivalent to `lutime(2)`.
---
---@param path string
---@param atime number
---@param mtime number
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_lutime(path, atime, mtime, callback) end
---@param path string
---@param atime number
---@param mtime number
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_lutime(path, atime, mtime) end

---
---Equivalent to `link(2)`.
---
---@param path string
---@param new_path string
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_link(path, new_path, callback) end
---@param path string
---@param new_path string
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_link(path, new_path) end

---
---Equivalent to `symlink(2)`.
---If the `flags` parameter is omitted, then the 3rd parameter will be treated as the `callback`.
---
---@param path string
---@param new_path string
---@param flags uv.aliases.fs_symlink_flags|integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_symlink(path, new_path, flags, callback) end
---@param path string
---@param new_path string
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_symlink(path, new_path, callback) end
---@param path string
---@param new_path string
---@param flags? uv.aliases.fs_symlink_flags|integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_symlink(path, new_path, flags) end

---
---Equivalent to `readlink(2)`.
---
---@param path string
---@param callback fun(err: nil|string, path: string|nil)
---@return uv_fs_t
function uv.fs_readlink(path, callback) end
---@param path string
---@return string|nil path, string? err_name, string? err_msg
---@nodiscard
function uv.fs_readlink(path) end

---
---Equivalent to `realpath(3)`.
---
---@param path string
---@param callback fun(err: nil|string, path: string|nil)
---@return uv_fs_t
function uv.fs_realpath(path, callback) end
---@param path string
---@return string|nil path, string? err_name, string? err_msg
---@nodiscard
function uv.fs_realpath(path) end

---
---Equivalent to `chown(2)`.
---
---@param path string
---@param uid integer
---@param gid integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_chown(path, uid, gid, callback) end
---@param path string
---@param uid integer
---@param gid integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_chown(path, uid, gid) end

---
---Equivalent to `fchown(2)`.
---
---@param fd integer
---@param uid integer
---@param gid integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_fchown(fd, uid, gid, callback) end
---@param fd integer
---@param uid integer
---@param gid integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_fchown(fd, uid, gid) end

---
---Equivalent to `lchown(2)`.
---
---@param fd integer
---@param uid integer
---@param gid integer
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_lchown(fd, uid, gid, callback) end
---@param fd integer
---@param uid integer
---@param gid integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_lchown(fd, uid, gid) end

---
---Copies a file from `path` to `new_path`.
---If the `flags` parameter is omitted, then the 3rd parameter will be treated as the `callback`.
---
---@param path string
---@param new_path string
---@param flags uv.aliases.fs_copyfile_flags
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_copyfile(path, new_path, flags, callback) end
---@param path string
---@param new_path string
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_copyfile(path, new_path, callback) end
---@param path string
---@param new_path string
---@param flags? uv.aliases.fs_copyfile_flags
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_copyfile(path, new_path, flags) end

---
---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()`.
---
---@param path string
---@param entries integer|nil
---@param callback fun(err: nil|string, dir: luv_dir_t|nil)
---@return uv_fs_t
function uv.fs_opendir(path, entries, callback) end
---@param path string
---@param entries integer|nil
---@return luv_dir_t|nil dir, string? err_name, string? err_msg
---@nodiscard
function uv.fs_opendir(path, entries) end

---
---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.
---
---@param dir luv_dir_t
---@param callback fun(err: nil|string, entries: uv.aliases.fs_readdir_entries|nil)
---@return uv_fs_t
function uv.fs_readdir(dir, callback) end
---@param dir luv_dir_t
---@return uv.aliases.fs_readdir_entries|nil entries, string? err_name, string? err_msg
---@nodiscard
function uv.fs_readdir(dir) end
luv_dir_t.readdir = uv.fs_readdir

---
---Closes a directory stream returned by a successful `uv.fs_opendir()` call.
---
---@param dir luv_dir_t
---@param callback fun(err: nil|string, success: boolean|nil)
---@return uv_fs_t
function uv.fs_closedir(dir, callback) end
---@param dir luv_dir_t
---@return boolean|nil success, string? err_name, string? err_msg
function uv.fs_closedir(dir) end
luv_dir_t.closedir = uv.fs_closedir

---
---Equivalent to `statfs(2)`.
---
---@param path string
---@param callback fun(err: nil|string, stats: uv.aliases.fs_statfs_stats|nil)
---@return uv_fs_t
function uv.fs_statfs(path, callback) end
---@param path string
---@return uv.aliases.fs_statfs_stats|nil stats, string? err_name, string? err_msg
---@nodiscard
function uv.fs_statfs(path) end

---
---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"
---```
---
---@class luv_work_ctx_t: userdata
---@section Thread pool work scheduling
local luv_work_ctx_t = {}

---
---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.
---
---@generic T: uv.aliases.threadargs
---@param work_callback fun(...: T)|string # passed to/from `uv.queue_work(work_ctx, ...)`
---@param after_work_callback fun(...: uv.aliases.threadargs) # returned from `work_callback`
---@return luv_work_ctx_t
---@nodiscard
function uv.new_work(work_callback, after_work_callback) end

-- TODO: make sure that the above method can indeed return nil + error.
-- confirmed to never return error see luv/work.c#luv_new_work

---
---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.
---
---@param work_ctx luv_work_ctx_t
---@param ... uv.aliases.threadargs
---@return boolean|nil success, string? err_name, string? err_msg
function uv.queue_work(work_ctx, ...) end
luv_work_ctx_t.queue = uv.queue_work

---
---@section DNS utility functions
---

---@class uv_getaddrinfo_t: uv_req_t

---@alias uv.aliases.getaddrinfo_hint {family: uv.aliases.network_family|integer|nil, socktype: uv.aliases.tcp_socket_type|nil, protocol: uv.aliases.network_protocols|nil, addrconfig: boolean|nil, v4mapped: boolean|nil, all: boolean|nil, numberichost: boolean|nil, passive: boolean|nil, numericserv: boolean|nil, canonname: boolean|nil}

---@alias uv.aliases.getaddrinfo_rtn {addr: string, family: uv.aliases.network_family, port: integer|nil, socktype: uv.aliases.tcp_socket_type, protocol: uv.aliases.network_protocols, canonname: string|nil}[]

---@class uv_getnameinfo_t: uv_req_t

---@alias uv_getnameinfo_address {ip: string|nil, port: integer|nil, family: uv.aliases.network_family|integer|nil}

---
---Equivalent to `getaddrinfo(3)`.
---Either `host` or `service` may be `nil` but not both.
---
---@param host string|nil
---@param service string|nil
---@param hints uv.aliases.getaddrinfo_hint?
---@param callback fun(err?: string, addresses?: uv.aliases.getaddrinfo_rtn)
---@return uv_getaddrinfo_t
function uv.getaddrinfo(host, service, hints, callback) end
---@param host string|nil
---@param service string|nil
---@param hints uv.aliases.getaddrinfo_hint?
---@return uv.aliases.getaddrinfo_rtn|nil addresses, string? err_name, string? err_msg
function uv.getaddrinfo(host, service, hints) end

---
---Equivalent to `getnameinfo(3)`.
---
---@param address uv_getnameinfo_address
---@param callback fun(err?: string, host?: string, service?: string)
---@return uv_getnameinfo_t
function uv.getnameinfo(address, callback) end
---@param address uv_getnameinfo_address
---@return string|nil host, string service_or_errname, string? err_msg
function uv.getnameinfo(address) end

---
---Libuv provides cross-platform implementations for multiple threading an
--- synchronization primitives. The API largely follows the pthreads API.
---
---@class luv_thread_t: userdata
---@section Threading and synchronization utilities
local luv_thread_t = {}

---@alias uv.aliases.thread_affinity {[integer]: boolean}

---
---Creates and initializes a `luv_thread_t` (not `uv_thread_t`). Returns the Lua
---userdata wrapping it and asynchronously executes `entry`, which can be
---either a Lua function or a string containing Lua code or bytecode dumped from a function. Additional arguments `...`
---are passed to the `entry` function and an optional `options` table may be
---provided. Currently accepted `option` fields are `stack_size`.
---
---**Note** unsafe, please make sure the thread end of life before Lua state close.
---
---@generic T: uv.aliases.threadargs
---@param options? {stack_size?: integer}
---@param entry fun(...: T)|string
---@vararg T # varargs passed to `entry`
---@return luv_thread_t?, string? err_name, string? err_msg
function uv.new_thread(options, entry, ...) end
---@generic T: uv.aliases.threadargs
---@param entry fun(...: T)|string
---@vararg T # varargs passed to `entry`
---@return luv_thread_t?, string? err_name, string? err_msg
function uv.new_thread(entry, ...) end

-- TODO: make sure that the above method can indeed return nil + error.
-- new_thread may fail if pthread fails.

---
---Returns a boolean indicating whether two threads are the same. This function is
---equivalent to the `__eq` metamethod.
---
---@param thread luv_thread_t
---@param other_thread luv_thread_t
---@return boolean
function uv.thread_equal(thread, other_thread) end
luv_thread_t.equal = uv.thread_equal

---
---Sets the specified thread's affinity setting.
---
---`affinity` must be a table where each of the keys are a CPU number and the
---values are booleans that represent whether the `thread` should be eligible to
---run on that CPU. If the length of the `affinity` table is not greater than or
---equal to `uv.cpumask_size()`, any CPU numbers missing from the table will have
---their affinity set to `false`. If setting the affinity of more than
---`uv.cpumask_size()` CPUs is desired, `affinity` must be an array-like table
---with no gaps, since `#affinity` will be used as the `cpumask_size` if it is
---greater than `uv.cpumask_size()`.
---
---If `get_old_affinity` is `true`, the previous affinity settings for the `thread`
---will be returned. Otherwise, `true` is returned after a successful call.
---
---**Note:** Thread affinity setting is not atomic on Windows. Unsupported on macOS.
---
---@param thread luv_thread_t
---@param affinity uv.aliases.thread_affinity
---@param get_old_affinity? boolean
---@return boolean|uv.aliases.thread_affinity|nil, string? err_name, string? err_msg
function uv.thread_setaffinity(thread, affinity, get_old_affinity) end
luv_thread_t.setaffinity = uv.thread_setaffinity

-- TODO: the above probably needs to use overloads for the different returns.
-- TODO: the overload with the table return needs a @nodiscard.

---
---Gets the specified thread's affinity setting.
---
---If `mask_size` is provided, it must be greater than or equal to
---`uv.cpumask_size()`. If the `mask_size` parameter is omitted, then the return
---of `uv.cpumask_size()` will be used. Returns an array-like table where each of
---the keys correspond to a CPU number and the values are booleans that represent
---whether the `thread` is eligible to run on that CPU.
---
---**Note:** Thread affinity getting is not atomic on Windows. Unsupported on macOS.
---
---@param thread luv_thread_t
---@param mask_size? integer
---@return table?, string? err_name, string? err_msg
---@nodiscard
function uv.thread_getaffinity(thread, mask_size) end
luv_thread_t.getaffinity = uv.thread_getaffinity

---
---Gets the CPU number on which the calling thread is running.
---
---**Note:** The first CPU will be returned as the number 1, not 0. This allows for
---the number to correspond with the table keys used in `uv.thread_getaffinity` and
---`uv.thread_setaffinity`.
---
---@return integer?, string? err_name, string? err_msg
---@nodiscard
function uv.thread_getcpu() end
luv_thread_t.getcpu = uv.thread_getcpu

---
---Returns the handle for the thread in which this is called.
---
---@return luv_thread_t
---@nodiscard
function uv.thread_self() end

---
---Waits for the `thread` to finish executing its entry function.
---
---@param thread luv_thread_t
---@return boolean?, string? err_name, string? err_msg
function uv.thread_join(thread) end
luv_thread_t.join = uv.thread_join

---
---Pauses the thread in which this is called for a number of milliseconds.
---
---@param msec integer
function uv.sleep(msec) end

---
---@section Miscellaneous utilities
---@source misc.c
---

---@alias uv.aliases.os_passwd {username: string, uid: integer, gid: integer, shell: string, homedir: string}

---@alias uv.aliases.os_uname {sysname: string, release: string, version: string, machine: string}

---@alias uv.aliases.rusage {utime: {sec: integer, usec: integer}, stime: {sec: integer, usec: integer}, maxrss: integer, ixrss: integer, idrss: integer, isrss: integer, minflt: integer, majflt: integer, nswap: integer, inblock: integer, oublock: integer, msgsnd: integer, msgrcv: integer, nsignals: integer, nvcsw: integer, nivcsw: integer}

---@alias uv.aliases.cpu_info {[integer]: {modal: string, speed: number, times: {user: number, nice: number, sys: number, idle: number, irq: number}}}

---@alias uv.aliases.interface_addresses {[string]: {ip: string, family: uv.aliases.network_family, netmask: string, internal: boolean, mac: string}}

---@alias uv.aliases.clock_gettime_rtn {sec: integer, nsec: integer}

---
---Returns the executable path.
---
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.exepath() end

---
---Returns the current working directory.
---
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.cwd() end

---
---Sets the current working directory with the string `cwd`.
---
---@param cwd string
---@return 0|nil success, string? err_name, string? err_msg
function uv.chdir(cwd) end

---
---Returns the title of the current process.
---
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.get_process_title() end

---
---Sets the title of the current process with the string `title`.
---
---@param title string
---@return 0|nil success, string? err_name, string? err_msg
function uv.set_process_title(title) end

---
---Returns the current total system memory in bytes.
---
---@return integer
---@nodiscard
function uv.get_total_memory() end

---
---Returns the current free system memory in bytes.
---
---@return integer
---@nodiscard
function uv.get_free_memory() end

---
---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.
---
---@return integer
---@nodiscard
function uv.get_constrained_memory() end

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

---
---Returns the resident set size (RSS) for the current process.
---
---@return integer|nil, string? err_name, string? err_msg
---@nodiscard
function uv.resident_set_memory() end

---
---Returns the resource usage.
---
---@return uv.aliases.rusage|nil, string? err_name, string? err_msg
---@nodiscard
function uv.getrusage() end

---
---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.
---
---@return integer
---@nodiscard
function uv.available_parallelism() end

---
---Returns information about the CPU(s) on the system as a table of tables for each
---CPU found.
---
---@return uv.aliases.cpu_info|nil, string? err_name, string? err_msg
---@nodiscard
function uv.cpu_info() end

---
---Returns the maximum size of the mask used for process/thread affinities, or
---`ENOTSUP` if affinities are not supported on the current platform.
---
---@return integer|nil, string? err_name, string? err_msg
---@nodiscard
function uv.cpumask_size() end

---
---**Deprecated:** Please use `uv.os_getpid()` instead.
---
---@return integer
---@nodiscard
---@deprecated
function uv.getpid() end

---
---Returns the user ID of the process.
---
---**Note:** This is not a libuv function and is not supported on Windows.
---
---@return integer
---@nodiscard
function uv.getuid() end

---
---Returns the group ID of the process.
---
---**Note:** This is not a libuv function and is not supported on Windows.
---
---@return integer
---@nodiscard
function uv.getgid() end

---
---Sets the user ID of the process with the integer `id`.
---
---**Note:** This is not a libuv function and is not supported on Windows.
---
---@param id integer
function uv.setuid(id) end

---
---Sets the group ID of the process with the integer `id`.
---
---**Note:** This is not a libuv function and is not supported on Windows.
---
---@param id integer
function uv.setgid(id) end

---
---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.
---
---@return integer
---@nodiscard
function uv.hrtime() end

---
---Obtain the current system time from a high-resolution real-time or monotonic
---clock source. `clock_id` can be the string `"monotonic"` or `"realtime"`.
---
---The real-time clock counts from the UNIX epoch (1970-01-01) and is subject
---to time adjustments; it can jump back in time.
---
---The monotonic clock counts from an arbitrary point in the past and never
---jumps back in time.
---
---@param clock_id string
---@return uv.aliases.clock_gettime_rtn?, string? err_name, string? err_msg
---@nodiscard
function uv.clock_gettime(clock_id) end

---
---Returns the current system uptime in seconds.
---
---@return number|nil, string? err_name, string? err_msg
---@nodiscard
function uv.uptime() end

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

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

---
---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.
---
---@param fd integer
---@return uv.aliases.handle_struct_name|nil
---@nodiscard
function uv.guess_handle(fd) end

---
---Cross-platform implementation of `gettimeofday(2)`. Returns the seconds and
---microseconds of a unix time as a pair.
---
---@return integer|nil, integer|string, string?
---@nodiscard
function uv.gettimeofday() end

---
---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`.
---
---@return uv.aliases.interface_addresses
---@nodiscard
function uv.interface_addresses() end

---
---IPv6-capable implementation of `if_indextoname(3)`.
---
---@param ifindex integer
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.if_indextoname(ifindex) end

---
---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.
---
---@param ifindex integer
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.if_indextoiid(ifindex) end

---
---Returns the load average as a triad. Not supported on Windows.
---
---@return number, number, number
---@nodiscard
function uv.loadavg() end

---
---Returns system information.
---
---@return uv.aliases.os_uname
---@nodiscard
function uv.os_uname() end

---
---Returns the hostname.
---
---@return string
---@nodiscard
function uv.os_gethostname() end

---
---Returns the environment variable specified by `name` as string. The internal
---buffer size can be set by defining `size`. If omitted, `LUAL_BUFFERSIZE` is
---used. If the environment variable exceeds the storage available in the internal
---buffer, `ENOBUFS` is returned. If no matching environment variable exists,
---`ENOENT` is returned.
---
---**Warning:** This function is not thread safe.
---
---@param name string
---@param size integer # (default = `LUAL_BUFFERSIZE`)
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.os_getenv(name, size) end

---
---Sets the environmental variable specified by `name` with the string `value`.
---
---**Warning:** This function is not thread safe.
---
---@param name string
---@param value string
---@return boolean|nil success, string? err_name, string? err_msg
function uv.os_setenv(name, value) end

---
---Unsets the environmental variable specified by `name`.
---
---**Warning:** This function is not thread safe.
---
---@param name string
---@return boolean|nil success, string? err_name, string? err_msg
function uv.os_unsetenv(name) end

---
---Returns all environmental variables as a dynamic table of names associated with
---their corresponding values.
---
---**Warning:** This function is not thread safe.
---
---@return {[string]: string}
---@nodiscard
function uv.os_environ() end

---
---**Warning:** This function is not thread safe.
---
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.os_homedir() end

---
---**Warning:** This function is not thread safe.
---
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.os_tmpdir() end

---
---Returns password file information.
---
---@return uv.aliases.os_passwd
---@nodiscard
function uv.os_get_passwd() end

---
---Returns the current process ID.
---
---@return integer
---@nodiscard
function uv.os_getpid() end

---
---Returns the parent process ID.
---
---@return integer
---@nodiscard
function uv.os_getppid() end

---
---Returns the scheduling priority of the process specified by `pid`.
---
---@param pid integer
---@return integer|nil, string? err_name, string? err_msg
---@nodiscard
function uv.os_getpriority(pid) end

---
---Sets the scheduling priority of the process specified by `pid`. The `priority`
---range is between -20 (high priority) and 19 (low priority).
---
---@param pid integer
---@param priority integer
---@return boolean|nil success, string? err_name, string? err_msg
function uv.os_setpriority(pid, priority) end

---
---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.
---
---@param len integer
---@param flags nil|0|{}
---@param callback fun(err?: string, bytes?: string)
---@return 0|nil success, string? err_name, string? err_msg
function uv.random(len, flags, callback) end
---@param len integer
---@param flags nil|0|{}
---@return string|nil, string? err_name, string? err_msg
---@nodiscard
function uv.random(len, flags) end

---
---Returns the libuv error message and error name (both in string form, see `err` and `name` in Error Handling) equivalent to the given platform dependent error code: POSIX error codes on Unix (the ones stored in errno), and Win32 error codes on Windows (those returned by GetLastError() or WSAGetLastError()).
---
---@param errcode integer
---@return string|nil, string|nil
---@source util.c
---@nodiscard
function uv.translate_sys_error(errcode) end

---
---@section Metrics operations
---@source metrics.c
---

---@alias uv.aliases.metric_info_rtn {loop_count: integer, events: integer, events_waiting: integer}

---
---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"`.
---
---@return integer
---@nodiscard
function uv.metrics_idle_time() end

---
---Get the metrics table from current set of event loop metrics. It is recommended
---to retrieve these metrics in a `prepare` callback (see `uv.new_prepare`,
---`uv.prepare_start`) in order to make sure there are no inconsistencies with the
---metrics counters.
---
---@return uv.aliases.metric_info_rtn
---@nodiscard
function uv.metrics_info() end

-- [[ constants ]]

-- TODO: make this its own section
-- TODO: how should this be reflected onto docs? field descriptions?

---@alias uv.constants {O_RDONLY: integer, O_WRONLY: integer, O_RDWR: integer, O_APPEND: integer, O_CREAT: integer, O_DSYNC: integer, O_EXCL: integer, O_NOCTTY: integer, O_NONBLOCK: integer, O_RSYNC: integer, O_SYNC: integer, O_TRUNC: integer, SOCK_STREAM: integer, SOCK_DGRAM: integer, SOCK_SEQPACKET: integer, SOCK_RAW: integer, SOCK_RDM: integer, AF_UNIX: integer, AF_INET: integer, AF_INET6: integer, AF_IPX: integer, AF_NETLINK: integer, AF_X25: integer, AF_AX25: integer, AF_ATMPVC: integer, AF_APPLETALK: integer, AF_PACKET: integer, AI_ADDRCONFIG: integer, AI_V4MAPPED: integer, AI_ALL: integer, AI_NUMERICHOST: integer, AI_PASSIVE: integer, AI_NUMERICSERV: integer, SIGHUP: integer, SIGINT: integer, SIGQUIT: integer, SIGILL: integer, SIGTRAP: integer, SIGABRT: integer, SIGIOT: integer, SIGBUS: integer, SIGFPE: integer, SIGKILL: integer, SIGUSR1: integer, SIGSEGV: integer, SIGUSR2: integer, SIGPIPE: integer, SIGALRM: integer, SIGTERM: integer, SIGCHLD: integer, SIGSTKFLT: integer, SIGCONT: integer, SIGSTOP: integer, SIGTSTP: integer, SIGTTIN: integer, SIGWINCH: integer, SIGIO: integer, SIGPOLL: integer, SIGXFSZ: integer, SIGVTALRM: integer, SIGPROF: integer, UDP_RECVMMSG: integer, UDP_MMSG_CHUNK: integer, UDP_REUSEADDR: integer, UDP_PARTIAL: integer, UDP_IPV6ONLY: integer, TCP_IPV6ONLY: integer, UDP_MMSG_FREE: integer, SIGSYS: integer, SIGPWR: integer, SIGTTOU: integer, SIGURG: integer, SIGXCPU: integer}

---@type uv.constants
uv.constants = {}

return uv