path: root/meta/3rd/luv/library/uv.lua

---@meta

--- The luv project provides access to the multi-platform support library
--- libuv in Lua code. It was primarily developed for the 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.
---
---
--- 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
--- ```
---
---
--- 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 one non-function field exists:
--- `uv.constants`, which is a table.
---
---
--- 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.
---
---
--- 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.
---
---
--- 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`
---
---
--- 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]: #error-handling
---
--- In libuv, errors are negative numbered constants; however, these errors and 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.
---
---
--- [reference counting]: #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.
---
---
--- [File system operations]: #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 userdata` and asynchronously execute its callback; if an error is encountered, the first and only argument passed to the callback will be the `err` error string; if the operation completes successfully, the first argument will be `nil` and the remaining arguments will be the results of the FS call.
---
--- Synchronous and asynchronous versions of `readFile` (with naive error handling)
--- are implemented below as an example:
---
--- ```lua
--- local function readFileSync(path)
---   local fd = assert(uv.fs_open(path, "r", 438))
---   local stat = assert(uv.fs_fstat(fd))
---   local data = assert(uv.fs_read(fd, stat.size, 0))
---   assert(uv.fs_close(fd))
---   return data
--- end
---
--- local data = readFileSync("main.lua")
--- print("synchronous read", data)
--- ```
---
--- ```lua
--- local function readFile(path, callback)
---   uv.fs_open(path, "r", 438, function(err, fd)
---     assert(not err, err)
---     uv.fs_fstat(fd, function(err, stat)
---       assert(not err, err)
---       uv.fs_read(fd, stat.size, 0, function(err, data)
---         assert(not err, err)
---         uv.fs_close(fd, function(err)
---           assert(not err, err)
---           return callback(data)
---         end)
---       end)
---     end)
---   end)
--- end
---
--- readFile("main.lua", function(data)
---   print("asynchronous read", data)
--- end)
--- ```
---
---
--- [Thread pool work scheduling]: #thread-pool-work-scheduling
---
--- Libuv provides a threadpool which can be used to run user code and get notified
--- in the loop thread. This threadpool is internally used to run all file system
--- operations, as well as `getaddrinfo` and `getnameinfo` requests.
---
--- ```lua
--- local function work_callback(a, b)
---   return a + b
--- end
---
--- local function after_work_callback(c)
---   print("The result is: " .. c)
--- end
---
--- local work = uv.new_work(work_callback, after_work_callback)
---
--- work:queue(1, 2)
---
--- -- output: "The result is: 3"
--- ```
---
---
--- [DNS utility functions]: #dns-utility-functions
---
---
--- [Threading and synchronization utilities]: #threading-and-synchronization-utilities
---
--- Libuv provides cross-platform implementations for multiple threading an
---  synchronization primitives. The API largely follows the pthreads API.
---
---
--- [Miscellaneous utilities]: #miscellaneous-utilities
---
---
--- [Metrics operations]: #metrics-operations
---
---@class uv
---
---@field errno uv.errno
---
local uv


--- 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.uv_stream_t
---@param  client_stream uv.uv_stream_t
---@return 0|nil         success
---@return uv.error.message|nil    err
---@return uv.error.name|nil    err_name
function uv.accept(stream, client_stream) end


--- 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.uv_async_t
---@param  ...        uv.threadargs
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.async_send(async, ...) 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
function uv.available_parallelism() 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 fd
function uv.backend_fd() end



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


--- Cancel a pending request. Fails if the request is executing or has finished
--- executing. Only cancellation of `uv_fs_t`, `uv_getaddrinfo_t`,
--- `uv_getnameinfo_t` and `uv_work_t` requests is currently supported.
---
---@param  req        uv.uv_req_t
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.cancel(req) end



--- Sets the current working directory with the string `cwd`.
---
---@param  cwd        string
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.chdir(cwd) end


--- Start the handle with the given callback.
---
---@param  check      uv.uv_check_t
---@param  callback   function
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.check_start(check, callback) end


--- Stop the handle, the callback will no longer be called.
---
---@param  check      uv.uv_check_t
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.check_stop(check) end


--- 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.uv_handle_t
---@param callback? function
function uv.close(handle, callback) end



--- Returns information about the CPU(s) on the system as a table of tables for each
--- CPU found.
---
--- **Returns:** `table` or `fail`
--- - `[1, 2, 3, ..., n]` : `table`
---   - `model` : `string`
---   - `speed` : `number`
---   - `times` : `table`
---     - `user` : `number`
---     - `nice` : `number`
---     - `sys` : `number`
---     - `idle` : `number`
---     - `irq` : `number`
---
---@return uv.cpu_info.cpu[]|nil info
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.cpu_info() end



--- Returns the current working directory.
---
---@return string|nil cwd
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.cwd() end



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



--- Returns the executable path.
---
---@return string|nil exepath
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.exepath() end


--- 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.uv_handle_t
---@return integer|nil fileno
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.fileno(handle) 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        integer|string
---@return boolean|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:string, mode:integer|string, callback:uv.fs_access.callback):uv.uv_fs_t
function uv.fs_access(path, mode) end



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



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



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


--- Closes a directory stream returned by a successful `uv.fs_opendir()` call.
---
---@param  dir         uv.luv_dir_t
---@return boolean|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(dir:uv.luv_dir_t, callback:uv.fs_closedir.callback):uv.uv_fs_t
function uv.fs_closedir(dir) 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`.
---
--- **Returns (sync version):** `boolean` or `fail`
---
--- **Returns (async version):** `uv_fs_t userdata`
---
---@param  path        string
---@param  new_path    string
---@param  flags?      uv.fs_copyfile.flags
---@return boolean|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:string, new_path:string, flags?:uv.fs_copyfile.flags, callback:uv.fs_copyfile.callback):uv.uv_fs_t
---@overload fun(path:string, new_path:string, callback:uv.fs_copyfile.callback):uv.uv_fs_t
function uv.fs_copyfile(path, new_path, flags) end


--- Get the path being monitored by the handle.
---
---@param  fs_event   uv.uv_fs_event_t
---@return string|nil path
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.fs_event_getpath(fs_event) end


--- Start the handle with the given callback, which will watch the specified path
--- for changes.
---
---@param  fs_event   uv.uv_fs_event_t
---@param  path       string
---@param  flags      uv.fs_event_start.flags
---@param  callback   uv.fs_event_start.callback
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.fs_event_start(fs_event, path, flags, callback) end


--- Stop the handle, the callback will no longer be called.
---
---@param  fs_event   uv.uv_fs_event_t
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.fs_event_stop(fs_event) end



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



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



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



--- Equivalent to `fstat(2)`.
---
--- **Returns (sync version):** `table` or `fail` (see `uv.fs_stat`)
---
--- **Returns (async version):** `uv_fs_t userdata`
---
---@param  fd                    integer
---@return uv.fs_stat.result|nil stat
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(fd:integer, callback:uv.fs_fstat.callback):uv.uv_fs_t
function uv.fs_fstat(fd) end



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



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



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



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



--- Equivalent to `link(2)`.
---
--- **Returns (sync version):** `boolean` or `fail`
---
--- **Returns (async version):** `uv_fs_t userdata`
---
---@param  path        string
---@param  new_path    string
---@return boolean|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:string, new_path:string, callback:uv.fs_link.callback):uv.uv_fs_t
function uv.fs_link(path, new_path) end



--- Equivalent to `lstat(2)`.
---
--- **Returns (sync version):** `table` or `fail` (see `uv.fs_stat`)
---
--- **Returns (async version):** `uv_fs_t userdata`
---
---@param  path                  integer
---@return uv.fs_stat.result|nil stat
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:integer, callback:uv.fs_lstat.callback):uv.uv_fs_t
function uv.fs_lstat(path) end



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



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



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



--- Equivalent to `mkstemp(3)`. Returns a temporary file handle and filename.
---
---@param  template    string
---@return integer|nil fd
---@return string      path_or_errmsg
---@return uv.error.name|nil err_name
---
---@overload fun(template:string, callback:uv.fs_mkstemp.callback):uv.uv_fs_t
function uv.fs_mkstemp(template) end



--- Equivalent to `open(2)`. Access `flags` may be an integer or one of: `"r"`,
--- `"rs"`, `"sr"`, `"r+"`, `"rs+"`, `"sr+"`, `"w"`, `"wx"`, `"xw"`, `"w+"`,
--- `"wx+"`, `"xw+"`, `"a"`, `"ax"`, `"xa"`, `"a+"`, `"ax+"`, or "`xa+`".
---
--- **Returns (sync version):** `integer` or `fail`
---
--- **Returns (async version):** `uv_fs_t userdata`
---
--- **Note:** On Windows, libuv uses `CreateFileW` and thus the file is always
--- opened in binary mode. Because of this, the `O_BINARY` and `O_TEXT` flags are
--- not supported.
---
---@param  path        string
---@param  flags       uv.fs_open.flags
---@param  mode        integer
---@return integer|nil fd
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:string, flags:uv.fs_open.flags, mode:integer, callback:uv.fs_open.callback):uv.uv_fs_t
function uv.fs_open(path, flags, mode) 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()`.
---
--- **Returns (sync version):** `luv_dir_t userdata` or `fail`
---
--- **Returns (async version):** `uv_fs_t userdata`
---
---@param  path             string
---@return uv.luv_dir_t|nil dir
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path: string, callback: uv.fs_opendir.callback, entries?: integer):uv.uv_fs_t
function uv.fs_opendir(path) end


--- Get the path being monitored by the handle.
---
---@param  fs_poll    uv.uv_fs_poll_t
---@return string|nil path
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.fs_poll_getpath(fs_poll) end


--- 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.uv_fs_poll_t
---@param  path       string
---@param  interval   integer
---@param  callback   uv.fs_poll_start.callback
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.fs_poll_start(fs_poll, path, interval, callback) end


--- Stop the handle, the callback will no longer be called.
---
---@param fs_poll uv.uv_fs_poll_t
---@return 0|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.fs_poll_stop(fs_poll) 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
---@return string|nil data
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(fd:integer, size:integer, offset?:integer, callback:uv.fs_read.callback):uv.uv_fs_t
function uv.fs_read(fd, size, offset) 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                       uv.luv_dir_t
---@return uv.fs_readdir.entry[]|nil entries
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(dir:uv.luv_dir_t, callback:uv.fs_readdir.callback):uv.uv_fs_t
function uv.fs_readdir(dir) end



--- Equivalent to `readlink(2)`.
---
---@param  path       string
---@return string|nil path
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:string, callback:uv.fs_readlink.callback):uv.uv_fs_t
function uv.fs_readlink(path) end



--- Equivalent to `realpath(3)`.
---
---@param  path       string
---@return string|nil realpath
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:string, callback:uv.fs_realpath.callback):uv.uv_fs_t
function uv.fs_realpath(path) end



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



--- Equivalent to `rmdir(2)`.
---
---@param  path        string
---@return boolean|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:string, callback:uv.fs_rmdir.callback):uv.uv_fs_t
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?      uv.fs_scandir.callback
---@return uv.uv_fs_t|nil fs
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.fs_scandir(path, callback) 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.uv_fs_t
---@return string|nil name
---@return string     type_or_errmsg
---@return uv.error.name|nil err_name
function uv.fs_scandir_next(fs) 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
---@return integer|nil bytes
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(out_fd:integer, in_fd:integer, in_offset:integer, size:integer, callback:uv.fs_sendfile.callback):uv.uv_fs_t
function uv.fs_sendfile(out_fd, in_fd, in_offset, size) end



--- Equivalent to `stat(2)`.
---
--- **Returns (sync version):** `table` or `fail`
--- - `dev` : `integer`
--- - `mode` : `integer`
--- - `nlink` : `integer`
--- - `uid` : `integer`
--- - `gid` : `integer`
--- - `rdev` : `integer`
--- - `ino` : `integer`
--- - `size` : `integer`
--- - `blksize` : `integer`
--- - `blocks` : `integer`
--- - `flags` : `integer`
--- - `gen` : `integer`
--- - `atime` : `table`
---   - `sec` : `integer`
---   - `nsec` : `integer`
--- - `mtime` : `table`
---   - `sec` : `integer`
---   - `nsec` : `integer`
--- - `ctime` : `table`
---   - `sec` : `integer`
---   - `nsec` : `integer`
--- - `birthtime` : `table`
---   - `sec` : `integer`
---   - `nsec` : `integer`
--- - `type` : `string`
---
--- **Returns (async version):** `uv_fs_t userdata`
---
---@param path string
---@return uv.fs_stat.result|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:string, callback:uv.fs_stat.callback):uv.uv_fs_t
function uv.fs_stat(path) end


--- Equivalent to `statfs(2)`.
---
--- **Returns** `table` or `nil`
--- - `type` : `integer`
--- - `bsize` : `integer`
--- - `blocks` : `integer`
--- - `bfree` : `integer`
--- - `bavail` : `integer`
--- - `files` : `integer`
--- - `ffree` : `integer`
---
---@param path string
---@return uv.fs_statfs.result|nil stat
---
---@overload fun(path: string, callback: uv.fs_statfs.callback)
function uv.fs_statfs(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.fs_symlink.flags|integer
---@return boolean|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:string, new_path:string, flags?:uv.fs_symlink.flags|integer, callback:uv.fs_symlink.callback):uv.uv_fs_t
---@overload fun(path:string, new_path:string, callback:uv.fs_symlink.callback):uv.uv_fs_t
function uv.fs_symlink(path, new_path, flags) end



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



--- Equivalent to `utime(2)`.
---
---@param  path        string
---@param  atime       number
---@param  mtime       number
---@return boolean|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(path:string, atime:number, mtime:number, callback:uv.fs_utime.callback):uv.uv_fs_t
function uv.fs_utime(path, atime, mtime) 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.buffer
---@param  offset?     integer
---@return integer|nil bytes
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(fd:integer, data:uv.buffer, offset?:integer, callback:uv.fs_write.callback):uv.uv_fs_t
function uv.fs_write(fd, data, offset) 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 number
function uv.get_constrained_memory() end



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



--- Returns the title of the current process.
---
---@return string|nil title
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.get_process_title() end



--- Returns the current total system memory in bytes.
---
--- **Returns:** `number`
---
---@return number
function uv.get_total_memory() end



--- Equivalent to `getaddrinfo(3)`. Either `node` or `service` may be `nil` but not
--- both.
---
--- Valid hint strings for the keys that take a string:
--- - `family`: `"unix"`, `"inet"`, `"inet6"`, `"ipx"`,
--- `"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or `"packet"`
--- - `socktype`: `"stream"`, `"dgram"`, `"raw"`,
--- `"rdm"`, or `"seqpacket"`
--- - `protocol`: will be looked up using the `getprotobyname(3)` function (examples: `"ip"`, `"icmp"`, `"tcp"`, `"udp"`, etc)
---
--- **Returns (sync version):** `table` or `fail`
--- - `[1, 2, 3, ..., n]` : `table`
---   - `addr` : `string`
---   - `family` : `string`
---   - `port` : `integer` or `nil`
---   - `socktype` : `string`
---   - `protocol` : `string`
---   - `canonname` : `string` or `nil`
---
--- **Returns (async version):** `uv_getaddrinfo_t userdata` or `fail`
---
---@param  host                        string
---@param  service                     string
---@param  hints?                      uv.getaddrinfo.hints
---@return uv.getaddrinfo.result[]|nil info
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(host:string, service:string, hints?:uv.getaddrinfo.hints, callback:uv.getaddrinfo.callback):uv.uv_getaddrinfo_t userdata|nil, string?, string?
function uv.getaddrinfo(host, service, hints) end



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



--- Equivalent to `getnameinfo(3)`.
---
--- When specified, `family` must be one of `"unix"`, `"inet"`, `"inet6"`, `"ipx"`,
--- `"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or `"packet"`.
---
--- **Returns (sync version):** `string, string` or `fail`
---
--- **Returns (async version):** `uv_getnameinfo_t userdata` or `fail`
---
---@param  address    uv.getnameinfo.address
---@return string|nil host
---@return string     service_or_errmsg
---@return uv.error.name|nil err_name
---
---@overload fun(address:uv.getnameinfo.address, callback:uv.getnameinfo.callback):uv.uv_getnameinfo_t|nil, string|nil, string|nil
function uv.getnameinfo(address) end



--- **Deprecated:** Please use `uv.os_getpid()` instead.
---
function uv.getpid() end



--- Returns the resource usage.
---
--- **Returns:** `table` or `fail`
--- - `utime` : `table` (user CPU time used)
---   - `sec` : `integer`
---   - `usec` : `integer`
--- - `stime` : `table` (system CPU time used)
---   - `sec` : `integer`
---   - `usec` : `integer`
--- - `maxrss` : `integer` (maximum resident set size)
--- - `ixrss` : `integer` (integral shared memory size)
--- - `idrss` : `integer` (integral unshared data size)
--- - `isrss` : `integer` (integral unshared stack size)
--- - `minflt` : `integer` (page reclaims (soft page faults))
--- - `majflt` : `integer` (page faults (hard page faults))
--- - `nswap` : `integer` (swaps)
--- - `inblock` : `integer` (block input operations)
--- - `oublock` : `integer` (block output operations)
--- - `msgsnd` : `integer` (IPC messages sent)
--- - `msgrcv` : `integer` (IPC messages received)
--- - `nsignals` : `integer` (signals received)
--- - `nvcsw` : `integer` (voluntary context switches)
--- - `nivcsw` : `integer` (involuntary context switches)
---
---@return uv.getrusage.result|nil usage
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.getrusage() end



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



--- Returns the user ID of the process.
---
--- **Note:** This is not a libuv function and is not supported on Windows.
---
---@return integer
function uv.getuid() 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 string
function uv.guess_handle(fd) end


--- 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.uv_handle_t
---@return string  type
---@return integer enum
function uv.handle_get_type(handle) end


--- Returns `true` if the handle referenced, `false` if not.
---
--- See [Reference counting][].
---
---@param  handle      uv.uv_handle_t
---@return boolean|nil has_ref
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.has_ref(handle) 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.
---
--- **Returns:** `number`
---
---@return number
function uv.hrtime() end


--- Start the handle with the given callback.
---
---@param  idle       uv.uv_idle_t
---@param  callback   function
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.idle_start(idle, callback) end


--- Stop the handle, the callback will no longer be called.
---
---@param  idle       uv.uv_idle_t
---@param  check      any
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.idle_stop(idle, check) 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 id
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.if_indextoiid(ifindex) end



--- IPv6-capable implementation of `if_indextoname(3)`.
---
---@param  ifindex    integer
---@return string|nil name
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.if_indextoname(ifindex) 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 table<string, uv.interface_addresses.addr>
function uv.interface_addresses() end


--- 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.uv_handle_t
---@return boolean|nil active
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.is_active(handle) end


--- 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.uv_handle_t
---@return boolean|nil closing
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.is_closing(handle) end


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


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


--- Sends the specified signal to the given PID. Check the documentation on
--- `uv_signal_t` for signal support, specially on Windows.
---
---@param  pid        integer
---@param  signum     integer|string
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.kill(pid, signum) end


--- Start listening for incoming connections. `backlog` indicates the number of
--- connections the kernel might queue, same as `listen(2)`. When a new incoming
--- connection is received the callback is called.
---
--- **Returns:** `0` or `fail`
---
---@param  stream     uv.uv_stream_t
---@param  backlog    integer
---@param  callback   uv.listen.callback
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.listen(stream, backlog, callback) end


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



--- Returns `true` if there are referenced active handles, active requests, or
--- closing handles in the loop; otherwise, `false`.
---
---@return boolean|nil alive
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.loop_alive() end



--- 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
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.loop_close() 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     "block_signal"
---@param  value      "sigprof"
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(option: "metrics_idle_time"):(success:0|nil, err:uv.error.message|nil, err_name:uv.error.name|nil)
function uv.loop_configure(option, value) 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 string|nil
function uv.loop_mode() end


--- Retrieve the amount of time the event loop has been idle in the kernel’s event
--- provider (e.g. `epoll_wait`). The call is thread safe.
---
--- The return value is the accumulated time spent idle in the kernel’s event
--- provider starting from when the [`uv_loop_t`][] was configured to collect the idle time.
---
--- **Note:** The event loop will not begin accumulating the event provider’s idle
--- time until calling `loop_configure` with `"metrics_idle_time"`.
---
--- **Returns:** `number`
---
--- ---
---
--- [luv]: https://github.com/luvit/luv
--- [luvit]: https://github.com/luvit/luvit
--- [libuv]: https://github.com/libuv/libuv
--- [libuv documentation page]: http://docs.libuv.org/
--- [libuv API documentation]: http://docs.libuv.org/en/v1.x/api.html
---
---@return number
function uv.metrics_idle_time() end


--- 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?         uv.new_async.callback
---@return uv.uv_async_t|nil async
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_async(callback) end


--- Creates and initializes a new `uv_check_t`. Returns the Lua userdata wrapping
--- it.
---
---@return uv.uv_check_t|nil check
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_check() end


--- Creates and initializes a new `uv_fs_event_t`. Returns the Lua userdata wrapping
--- it.
---
---@return uv.uv_fs_event_t|nil fs_event
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_fs_event() end


--- Creates and initializes a new `uv_fs_poll_t`. Returns the Lua userdata wrapping
--- it.
---
---@return uv.uv_fs_poll_t|nil fs_poll
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_fs_poll() end


--- Creates and initializes a new `uv_idle_t`. Returns the Lua userdata wrapping
--- it.
---
---@return uv.uv_idle_t|nil idle
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_idle() end


--- Creates and initializes a new `uv_pipe_t`. Returns the Lua userdata wrapping
--- it. The `ipc` argument is a boolean to indicate if this pipe will be used for
--- handle passing between processes.
---
---@param  ipc?             boolean|false
---@return uv.uv_pipe_t|nil pipe
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_pipe(ipc) end


--- Initialize the handle using a file descriptor.
---
--- The file descriptor is set to non-blocking mode.
---
---@param  fd               integer
---@return uv.uv_poll_t|nil poll
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_poll(fd) end


--- Creates and initializes a new `uv_prepare_t`. Returns the Lua userdata wrapping
--- it.
---
---@return uv.uv_prepare_t|nil prepare
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_prepare() end


--- Creates and initializes a new `uv_signal_t`. Returns the Lua userdata wrapping
--- it.
---
---@return uv.uv_signal_t|nil signal
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_signal() 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
---@return uv.uv_poll_t|nil poll
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_socket_poll(fd) end


--- Creates and initializes a new `uv_tcp_t`. Returns the Lua userdata wrapping it.
--- Flags may be a family string: `"unix"`, `"inet"`, `"inet6"`, `"ipx"`,
--- `"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or `"packet"`.
---
---@param  flags?          uv.socket.family
---@return uv.uv_tcp_t|nil tcp
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_tcp(flags) end



--- 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 Lua function dumped to a string. Additional arguments `...`
--- are passed to the `entry` function and an optional `options` table may be
--- provided. Currently accepted `option` fields are `stack_size`.
---
---@param  options?            uv.new_thread.options
---@param  entry               function
---@param  ...                 uv.threadargs
---@return uv.luv_thread_t|nil thread
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_thread(options, entry, ...) end



--- Creates and initializes a new `uv_timer_t`. Returns the Lua userdata wrapping
--- it.
---
--- ```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.uv_timer_t|nil timer
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_timer() end



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



--- Creates and initializes a new `uv_udp_t`. Returns the Lua userdata wrapping
--- it. The actual socket is created lazily.
---
--- When specified, `family` must be one of `"unix"`, `"inet"`, `"inet6"`,
--- `"ipx"`, `"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, or
--- `"packet"`.
---
--- When specified, `mmsgs` determines the number of messages able to be received
--- at one time via `recvmmsg(2)` (the allocated buffer will be sized to be able
--- to fit the specified number of max size dgrams). Only has an effect on
--- platforms that support `recvmmsg(2)`.
---
--- **Note:** For backwards compatibility reasons, `flags` can also be a string or
--- integer. When it is a string, it will be treated like the `family` key above.
--- When it is an integer, it will be used directly as the `flags` parameter when
--- calling `uv_udp_init_ex`.
---
--- **Returns:** `uv_udp_t userdata` or `fail`
---
---@param  flags?          uv.new_udp.flags|uv.new_udp.flags.family|integer
---@return uv.uv_udp_t|nil udp
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.new_udp(flags) end



--- Creates and initializes a new `luv_work_ctx_t` (not `uv_work_t`). Returns the
--- Lua userdata wrapping it.
---
--- **Parameters:**
--- - `work_callback`: `function`
---   - `...`: `threadargs` passed to/from `uv.queue_work(work_ctx, ...)`
--- - `after_work_callback`: `function`
---   - `...`: `threadargs` returned from `work_callback`
---
---@param work_callback uv.new_work.work_callback
---@param after_work_callback uv.new_work.after_work_callback
---@return uv.luv_work_ctx_t
function uv.new_work(work_callback, after_work_callback) 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
function uv.now() end



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



--- Returns password file information.
---
---@return uv.os_get_passwd.info
function uv.os_get_passwd() 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 value
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.os_getenv(name, size) end



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



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



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



--- Returns the scheduling priority of the process specified by `pid`.
---
---@param  pid        integer
---@return number|nil priority
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.os_getpriority(pid) end



--- **Warning:** This function is not thread safe.
---
---@return string|nil homedir
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.os_homedir() 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
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.os_setenv(name, value) 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
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.os_setpriority(pid, priority) end


--- **Warning:** This function is not thread safe.
---
---@return string|nil tmpdir
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.os_tmpdir() end



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



--- **Warning:** This function is not thread safe.
---
---@return boolean|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.os_unsetenv() end



--- Create a pair of connected pipe handles. Data may be written to the `write` fd and read from the `read` fd. The resulting handles can be passed to `pipe_open`, used with `spawn`, or for any other purpose.
---
--- Flags:
---  - `nonblock`: Opens the specified socket handle for `OVERLAPPED` or `FIONBIO`/`O_NONBLOCK` I/O usage. This is recommended for handles that will be used by libuv, and not usually recommended otherwise.
---
--- Equivalent to `pipe(2)` with the `O_CLOEXEC` flag set.
---
--- **Returns:** `table` or `fail`
--- - `read` : `integer` (file descriptor)
--- - `write` : `integer` (file descriptor)
---
--- ```lua
--- -- Simple read/write with pipe_open
--- local fds = uv.pipe({nonblock=true}, {nonblock=true})
---
--- local read_pipe = uv.new_pipe()
--- read_pipe:open(fds.read)
---
--- local write_pipe = uv.new_pipe()
--- write_pipe:open(fds.write)
---
--- write_pipe:write("hello")
--- read_pipe:read_start(function(err, chunk)
---   assert(not err, err)
---   print(chunk)
--- end)
--- ```
---
---@param  read_flags      uv.pipe.read_flags
---@param  write_flags     uv.pipe.write_flags
---@return uv.pipe.fds|nil fds
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.pipe(read_flags, write_flags) end


--- 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.uv_pipe_t
---@param  name       string
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.pipe_bind(pipe, name) end


--- Alters pipe permissions, allowing it to be accessed from processes run by different users.
--- Makes the pipe writable or readable by all users. `flags` are: `"r"`, `"w"`, `"rw"`, or `"wr"`
--- where `r` is `READABLE` and `w` is `WRITABLE`. This function is blocking.
---
---@param  pipe       uv.uv_pipe_t
---@param  flags      uv.pipe_chmod.flags
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.pipe_chmod(pipe, flags) end


--- 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.uv_pipe_t
---@param  name                string
---@param  callback?           uv.pipe_connect.callback
---@return uv.uv_connect_t|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.pipe_connect(pipe, name, callback) end


--- Get the name of the Unix domain socket or the named pipe to which the handle is
--- connected.
---
---@param  pipe       uv.uv_pipe_t
---@return string|nil peername
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.pipe_getpeername(pipe) end


--- Get the name of the Unix domain socket or the named pipe.
---
---@param  pipe       uv.uv_pipe_t
---@return string|nil sockname
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.pipe_getsockname(pipe) end


--- 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.uv_pipe_t
---@param  fd         integer
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.pipe_open(pipe, fd) end


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


--- 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.uv_pipe_t
---@param count integer
function uv.pipe_pending_instances(pipe, count) end


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


--- Starts polling the file descriptor.
---
--- `events` are: `"r"`, `"w"`, `"rw"`, `"d"`,
--- `"rd"`, `"wd"`, `"rwd"`, `"p"`, `"rp"`, `"wp"`, `"rwp"`, `"dp"`, `"rdp"`,
--- `"wdp"`, or `"rwdp"` where `r` is `READABLE`, `w` is `WRITABLE`, `d` is
--- `DISCONNECT`, and `p` is `PRIORITIZED`. As soon as an event is detected
--- the callback will be called with status set to 0, and the detected events set on
--- the events field.
---
--- The user should not close the socket while the handle is active. If the user
--- does that anyway, the callback may be called reporting an error status, but this
--- is not guaranteed.
---
--- **Note** Calling `uv.poll_start()` on a handle that is already active is fine.
--- Doing so will update the events mask that is being watched for.
---
---@param  poll       uv.uv_poll_t
---@param  events     uv.poll.eventspec
---@param  callback   uv.poll_start.callback
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.poll_start(poll, events, callback) end


--- Stop polling the file descriptor, the callback will no longer be called.
---
---@param  poll       uv.uv_poll_t
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.poll_stop(poll) end


--- Start the handle with the given callback.
---
---@param  prepare    uv.uv_prepare_t
---@param  callback   function
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.prepare_start(prepare, callback) end


--- Stop the handle, the callback will no longer be called.
---
---@param  prepare    uv.uv_prepare_t
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.prepare_stop(prepare) 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


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


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


--- Sends the specified signal to the given process handle. Check the documentation
--- on `uv_signal_t` for signal support, specially on Windows.
---
---@param  process    uv.uv_process_t
---@param  signum     integer|string
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.process_kill(process, signum) end


--- 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    uv.luv_work_ctx_t
---@param  ...         uv.threadargs
---@return boolean|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.queue_work(work_ctx, ...) 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.
---
--- **Returns (sync version):** `string` or `fail`
---
--- **Returns (async version):** `0` or `fail`
---
---@param  len        integer
---@param  flags?     nil|0|{}
---@return string|nil bytes
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
---
---@overload fun(len:integer, flags?:nil, callback:uv.random.callback):0|nil, string?, string?
function uv.random(len, flags) end


--- Read data from an incoming stream. The callback will be made several times until
--- there is no more data to read or `uv.read_stop()` is called. When we've reached
--- EOF, `data` will be `nil`.
---
--- ```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.uv_stream_t
---@param  callback   uv.read_start.callback
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.read_start(stream, callback) end


--- Stop reading data from the stream. The read callback will no longer be called.
---
--- This function is idempotent and may be safely called on a stopped stream.
---
---@param  stream     uv.uv_stream_t
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.read_stop(stream) end


--- 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.uv_handle_t
---@param  size?       integer  # default is `0`
---@return integer|nil size_or_ok
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.recv_buffer_size(handle, size) end


--- Reference the given handle. References are idempotent, that is, if a handle is
--- already referenced calling this function again will have no effect.
---
--- See [Reference counting][].
---
---@param handle uv.uv_handle_t
function uv.ref(handle) end


--- 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.uv_req_t
---@return uv.req_type.name type
---@return uv.req_type.enum enum
function uv.req_get_type(req) end


--- Returns the resident set size (RSS) for the current process.
---
---@return integer|nil rss
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.resident_set_memory() 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.run.mode
---@return boolean
function uv.run(mode) end


--- Gets or sets the size of the send buffer that the operating system uses for the
--- socket.
---
--- If `size` is omitted (or `0`), this will return the current send buffer size; otherwise, this will use `size` to set the new send buffer size.
---
--- This function works for TCP, pipe and UDP handles on Unix and for TCP and UDP
--- handles on Windows.
---
--- **Returns:**
--- - `integer` or `fail` (if `size` is `nil` or `0`)
--- - `0` or `fail` (if `size` is not `nil` and not `0`)
---
--- **Note**: Linux will set double the size and return double the size of the
--- original set value.
---
---@param  handle               uv.uv_handle_t
---@param  size?                integer|0
---@return integer|nil          success
---@return uv.error.message|nil err
---@return uv.error.name|nil    err_name
---
---@overload fun(handle: uv.uv_handle_t):(size:integer|nil, err:uv.error.message|nil, err_name:uv.error.name|nil)
---@overload fun(handle: uv.uv_handle_t, size:0):(size:integer|nil, err:uv.error.message|nil, err_name:uv.error.name|nil)
function uv.send_buffer_size(handle, size) end


--- Sets the title of the current process with the string `title`.
---
---@param  title      string
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.set_process_title(title) 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


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


--- 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.uv_stream_t
---@param  callback?            uv.shutdown.callback
---@return uv.uv_shutdown_t|nil shutdown
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.shutdown(stream, callback) end


--- Start the handle with the given callback, watching for the given signal.
---
---@param  signal     uv.uv_signal_t
---@param  signum     integer|string
---@param  callback   uv.signal_start.callback
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.signal_start(signal, signum, callback) end


--- Same functionality as `uv.signal_start()` but the signal handler is reset the moment the signal is received.
---
---@param  signal     uv.uv_signal_t
---@param  signum     integer|string
---@param  callback   uv.signal_start_oneshot.callback
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.signal_start_oneshot(signal, signum, callback) end


--- Stop the handle, the callback will no longer be called.
---@param  signal     uv.uv_signal_t
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.signal_stop(signal) end


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


--- Create a pair of connected sockets with the specified properties. The resulting handles can be passed to `uv.tcp_open`, used with `uv.spawn`, or for any other purpose.
---
--- When specified as a string, `socktype` must be one of `"stream"`, `"dgram"`, `"raw"`,
--- `"rdm"`, or `"seqpacket"`.
---
--- When `protocol` is set to 0 or nil, it will be automatically chosen based on the socket's domain and type. When `protocol` is specified as a string, it will be looked up using the `getprotobyname(3)` function (examples: `"ip"`, `"icmp"`, `"tcp"`, `"udp"`, etc).
---
--- Flags:
---  - `nonblock`: Opens the specified socket handle for `OVERLAPPED` or `FIONBIO`/`O_NONBLOCK` I/O usage. This is recommended for handles that will be used by libuv, and not usually recommended otherwise.
---
--- Equivalent to `socketpair(2)` with a domain of `AF_UNIX`.
---
--- **Returns:** `table` or `fail`
--- - `[1, 2]` : `integer` (file descriptor)
---
--- ```lua
--- -- Simple read/write with tcp
--- local fds = uv.socketpair(nil, nil, {nonblock=true}, {nonblock=true})
---
--- local sock1 = uv.new_tcp()
--- sock1:open(fds[1])
---
--- local sock2 = uv.new_tcp()
--- sock2:open(fds[2])
---
--- sock1:write("hello")
--- sock2:read_start(function(err, chunk)
---   assert(not err, err)
---   print(chunk)
--- end)
--- ```
---
---@param  socktype?  uv.socketpair.socktype
---@param  protocol?  uv.socketpair.protocol
---@param  flags1?    uv.socketpair.flags
---@param  flags2?    uv.socketpair.flags
---@return uv.socketpair.fds|nil fds
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.socketpair(socktype, protocol, flags1, flags2) 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 string. The first
---   string should be the path to the program. On Windows, this uses CreateProcess
---   which concatenates the arguments into a string. This can cause some strange
---   errors. (See `options.verbatim` below for Windows.)
---   - `options.stdio` - Set the file descriptors that will be made available to
---   the child process. The convention is that the first entries are stdin, stdout,
---   and stderr. (**Note**: On Windows, file descriptors after the third are
---   available to the child process only if the child processes uses the MSVCRT
---   runtime.)
---   - `options.env` - Set environment variables for the new process.
---   - `options.cwd` - Set the current working directory for the sub-process.
---   - `options.uid` - Set the child process' user id.
---   - `options.gid` - Set the child process' group id.
---   - `options.verbatim` - If true, do not wrap any arguments in quotes, or
---   perform any other escaping, when converting the argument list into a command
---   line string. This option is only meaningful on Windows systems. On Unix it is
---   silently ignored.
---   - `options.detached` - If true, spawn the child process in a detached state -
---   this will make it a process group leader, and will effectively enable the
---   child to keep running after the parent exits. Note that the child process
---   will still keep the parent's event loop alive unless the parent process calls
---   `uv.unref()` on the child's process handle.
---   - `options.hide` - If true, hide the subprocess console window that would
---   normally be created. This option is only meaningful on Windows systems. On
---   Unix it is silently ignored.
---
--- The `options.stdio` entries can take many shapes.
---
---   - If they are numbers, then the child process inherits that same zero-indexed
---   fd from the parent process.
---   - If `uv_stream_t` handles are passed in, those are used as a read-write pipe
---   or inherited stream depending if the stream has a valid fd.
---   - Including `nil` placeholders means to ignore that fd in the child process.
---
--- When the child process exits, `on_exit` is called with an exit code and signal.
---
---@param  path            string
---@param  options         uv.spawn.options
---@param  on_exit         uv.spawn.on_exit
---@return uv.uv_process_t proc
---@return integer         pid
function uv.spawn(path, options, on_exit) 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


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


--- 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.uv_stream_t
---@param  blocking   boolean
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.stream_set_blocking(stream, blocking) end


--- 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.uv_tcp_t
---@param  host       string
---@param  port       integer
---@param  flags?     uv.tcp_bind.flags
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tcp_bind(tcp, host, port, flags) end


--- Resets a TCP connection by sending a RST packet. This is accomplished by setting
--- the SO_LINGER socket option with a linger interval of zero and then calling
--- `uv.close()`. Due to some platform inconsistencies, mixing of `uv.shutdown()`
--- and `uv.tcp_close_reset()` calls is not allowed.
---
---@param  tcp        uv.uv_tcp_t
---@param  callback?  function
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tcp_close_reset(tcp, callback) end


--- 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.uv_tcp_t
---@param  host                string
---@param  port                integer
---@param  callback            uv.tcp_connect.callback
---@return uv.uv_connect_t|nil conn
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tcp_connect(tcp, host, port, callback) end


--- Get the address of the peer connected to the handle.
---
---@param  tcp               uv.uv_tcp_t
---@return uv.socketinfo|nil sockname
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tcp_getpeername(tcp) end


--- Get the current address to which the handle is bound.
---
---@param  tcp               uv.uv_tcp_t
---@return uv.socketinfo|nil sockname
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tcp_getsockname(tcp) end


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


--- Enable / disable Nagle's algorithm.
---
---@param  tcp        uv.uv_tcp_t
---@param  enable     boolean
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tcp_nodelay(tcp, enable) 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.uv_tcp_t
---@param  sock       integer
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tcp_open(tcp, sock) end


--- 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.uv_tcp_t
---@param  enable     boolean
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tcp_simultaneous_accepts(tcp, enable) end


--- **Deprecated:** Please use `uv.stream_get_write_queue_size()` instead.
---
---@param tcp uv.uv_tcp_t
function uv.tcp_write_queue_size(tcp) end


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


--- Waits for the `thread` to finish executing its entry function.
---
---@param  thread      uv.luv_thread_t
---@return boolean|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.thread_join(thread) end


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


--- 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.uv_timer_t
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.timer_again(timer) end


--- 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.uv_timer_t
---@return integer
function uv.timer_get_due_in(timer) end


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


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


--- Start the timer. `timeout` and `repeat` are in milliseconds.
---
--- If `timeout` is zero, the callback fires on the next event loop iteration. If
--- `repeat` is non-zero, the callback fires first after `timeout` milliseconds and
--- then repeatedly after `repeat` milliseconds.
---
---@param  timer      uv.uv_timer_t
---@param  timeout    integer
---@param  repeat_    integer
---@param  callback   function
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.timer_start(timer, timeout, repeat_, callback) end


--- Stop the timer, the callback will not be called anymore.
---
---@param  timer      uv.uv_timer_t
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.timer_stop(timer) end


--- Returns the libuv error message and error name (both in string form, see [`err` and `name` in Error Handling](#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 uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.translate_sys_error(errcode) end


--- 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.uv_stream_t
---@param  data        uv.buffer
---@return integer|nil bytes
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.try_write(stream, data) end


--- Like `uv.write2()`, but with the properties of `uv.try_write()`. Not supported on Windows, where it returns `UV_EAGAIN`.
---
--- Will return number of bytes written (can be less than the supplied buffer size).
---
--- **Returns:** `integer` or `fail`
---
---@param  stream      uv.uv_stream_t
---@param  data        uv.buffer
---@param  send_handle uv.uv_stream_t
---@return integer|nil bytes
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.try_write2(stream, data, send_handle) 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 "supported"|"unsupported"|nil state
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tty_get_vterm_state() end


--- Gets the current Window width and height.
---
--- **Returns:** `integer, integer` or `fail`
---
---@param  tty            uv.uv_tty_t
---@return integer|nil    width
---@return integer|string height_or_errmsg
---@return uv.error.name|nil err_name
function uv.tty_get_winsize(tty) end


--- 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
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tty_reset_mode() end


--- Set the TTY using the specified terminal mode.
---
--- Parameter `mode` is a C enum with the following values:
---
---   - 0 - UV_TTY_MODE_NORMAL: Initial/normal terminal mode
---   - 1 - UV_TTY_MODE_RAW: Raw input mode (On Windows, ENABLE_WINDOW_INPUT is
---   also enabled)
---   - 2 - UV_TTY_MODE_IO: Binary-safe I/O mode for IPC (Unix-only)
---
---@param  tty        uv.uv_tty_t
---@param  mode       uv.tty.mode
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.tty_set_mode(tty, mode) end


--- 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 "supported"|"unsupported"
function uv.tty_set_vterm_state(state) end


--- 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.uv_udp_t
---@param  host       string
---@param  port       integer
---@param  flags?     uv.udp_bind.flags
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_bind(udp, host, port, flags) end


--- 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.uv_udp_t
---@param host string
---@param port integer
---@return 0|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_connect(udp, host, port) end


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


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


--- Get the remote IP and port of the UDP handle on connected UDP handles.
---
---@param  udp                 uv.uv_udp_t
---@return uv.udp.sockname|nil peername
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_getpeername(udp) end


--- Get the local IP and port of the UDP handle.
---
---@param  udp                 uv.uv_udp_t
---@return uv.udp.sockname|nil sockname
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_getsockname(udp) end


--- 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.uv_udp_t
---@param  fd         integer
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_open(udp, fd) end


--- 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.uv_udp_t
---@param  callback   uv.udp_recv_start.callback
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_recv_start(udp, callback) end


--- Stop listening for incoming datagrams.
---
---@param  udp        uv.uv_udp_t
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_recv_stop(udp) end


--- 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.uv_udp_t
---@param  data                 uv.buffer
---@param  host                 string
---@param  port                 integer
---@param  callback             uv.udp_send.callback
---@return uv.uv_udp_send_t|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_send(udp, data, host, port, callback) end


--- Set broadcast on or off.
---
---@param  udp        uv.uv_udp_t
---@param  on         boolean
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_set_broadcast(udp, on) end


--- 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.uv_udp_t
---@param  multicast_addr string
---@param  interface_addr string
---@param  membership     "leave"|"join"
---@return 0|nil          success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_set_membership(udp, multicast_addr, interface_addr, membership) end


--- Set the multicast interface to send or receive data on.
---
---@param  udp            uv.uv_udp_t
---@param  interface_addr string
---@return 0|nil          success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_set_multicast_interface(udp, interface_addr) end


--- Set IP multicast loop flag. Makes multicast packets loop back to local
--- sockets.
---
---@param  udp        uv.uv_udp_t
---@param  on         boolean
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_set_multicast_loop(udp, on) end


--- Set the multicast ttl.
---
--- `ttl` is an integer 1 through 255.
---
---@param  udp        uv.uv_udp_t
---@param  ttl        integer
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_set_multicast_ttl(udp, ttl) end


--- 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.uv_udp_t
---@param  multicast_addr string
---@param  interface_addr string|nil
---@param  source_addr    string
---@param  membership     "leave"|"join"
---@return 0|nil          success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_set_source_membership(udp, multicast_addr, interface_addr, source_addr, membership) end


--- Set the time to live.
---
--- `ttl` is an integer 1 through 255.
---
---@param  udp        uv.uv_udp_t
---@param  ttl        integer
---@return 0|nil      success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.udp_set_ttl(udp, ttl) end


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


--- Un-reference the given handle. References are idempotent, that is, if a handle
--- is not referenced calling this function again will have no effect.
---
--- See [Reference counting][].
---
---@param handle uv.uv_handle_t
function uv.unref(handle) 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


--- Returns the current system uptime in seconds.
---
---@return number|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.uptime() end


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


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


--- 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.uv_stream_t
---@param  data              uv.buffer
---@param  callback?         uv.write.callback
---@return uv.uv_write_t|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.write(stream, data, callback) end

--- 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.uv_stream_t
---@param  data              uv.buffer
---@param  send_handle       uv.uv_stream_t
---@param  callback?         uv.write2.callback
---@return uv.uv_write_t|nil success
---@return uv.error.message|nil err
---@return uv.error.name|nil err_name
function uv.write2(stream, data, send_handle, callback) end