summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/luv/docs.md
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/luv/docs.md')
-rw-r--r--3rdparty/luv/docs.md1309
1 files changed, 0 insertions, 1309 deletions
diff --git a/3rdparty/luv/docs.md b/3rdparty/luv/docs.md
deleted file mode 100644
index 187dec24ff1..00000000000
--- a/3rdparty/luv/docs.md
+++ /dev/null
@@ -1,1309 +0,0 @@
-# LibUV in Lua
-
-The [luv][] project provides access to the multi-platform support library
-[libuv][] to lua code. It was primariliy developed for the [luvit][] project as
-the `uv` builtin module, but can be used in other lua environments.
-
-### TCP Echo Server Example
-
-Here is a small example showing a TCP echo server:
-
-```lua
-local uv = require('uv')
-
-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()
-```
-
-### Methods vs Functions
-
-As a quick note, [libuv][] is a C library and as such, there are no such things
-as methods. The [luv][] bindings allow calling the libuv functions as either
-functions or methods. For example, calling `server:bind(host, port)` is
-equivalent to calling `uv.tcp_bind(server, host, port)`. All wrapped uv types
-in lua have method shortcuts where is makes sense. Some are even renamed
-shorter like the `tcp_` prefix that removed in method form. Under the hood it's
-the exact same C function.
-
-## Table Of Contents
-
-The rest of the docs are organized by libuv type. There is some hierarchy as
-most types are considered handles and some are considered streams.
-
- - [`uv_loop_t`][] — Event loop
- - [`uv_handle_t`][] — Base handle
- - [`uv_timer_t`][] — Timer handle
- - [`uv_prepare_t`][] — Prepare handle
- - [`uv_check_t`][] — Check handle
- - [`uv_idle_t`][] — Idle handle
- - [`uv_async_t`][] — Async handle
- - [`uv_poll_t`][] — Poll handle
- - [`uv_signal_t`][] — Signal handle
- - [`uv_process_t`][] — Process handle
- - [`uv_stream_t`][] — Stream handle
- - [`uv_tcp_t`][] — TCP handle
- - [`uv_pipe_t`][] — Pipe handle
- - [`uv_tty_t`][] — TTY handle
- - [`uv_udp_t`][] — UDP handle
- - [`uv_fs_event_t`][] — FS Event handle
- - [`uv_fs_poll_t`][] — FS Poll handle
- - [Filesystem operations][]
- - [DNS utility functions][]
- - [Miscellaneous utilities][]
-
-## `uv_loop_t` — Event loop
-
-[`uv_loop_t`]: #uv_loop_t--event-loop
-
-The event loop is the central part of libuv’s functionality. It takes care of
-polling for i/o and scheduling callbacks to be run based on different sources of
-events.
-
-In [luv][], there is an implicit uv loop for every lua state that loads the
-library. You can use this library in an multithreaded environment as long as
-each thread has it's own lua state with corresponsding own uv loop.
-
-### `uv.loop_close()`
-
-Closes all internal loop resources. This function must only be called once the
-loop has finished its execution or it will raise a UV_EBUSY error.
-
-### `uv.run([mode])`
-
-> optional `mode` defaults to `"default"`
-
-This function runs the event loop. It will act differently depending on the
-specified mode:
-
- - `"default"`: Runs the event loop until there are no more active and
- referenced handles or requests. Always returns `false`.
-
- - `"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).
-
-Luvit will implicitly call `uv.run()` after loading user code, but if you use
-the `luv` bindings directly, you need to call this after registering your
-initial set of event callbacks to start the event loop.
-
-### `uv.loop_alive()`
-
-Returns true if there are active handles or request in the loop.
-
-### `uv.stop()`
-
-Stop the event loop, causing `uv_run()` to end as soon as possible. This
-will happen not sooner than the next loop iteration. If this function was called
-before blocking for i/o, the loop won’t block for i/o on this iteration.
-
-### `uv.backend_fd()`
-
-Get backend file descriptor. Only kqueue, epoll and event ports are supported.
-
-This can be used in conjunction with `uv_run("nowait")` to poll in one thread
-and run the event loop’s callbacks in another.
-
-**Note**: Embedding a kqueue fd in another kqueue pollset doesn’t work on all
-platforms. It’s not an error to add the fd but it never generates events.
-
-### `uv.backend_timeout()`
-
-Get the poll timeout. The return value is in milliseconds, or -1 for no timeout.
-
-### `uv.now()`
-
-Return 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.
-
-### `uv.update_time()`
-
-Update the event loop’s concept of “now”. Libuv caches the current time at the
-start of the event loop tick in order to reduce the number of time-related
-system calls.
-
-You won’t normally need to call this function unless you have callbacks that
-block the event loop for longer periods of time, where “longer” is somewhat
-subjective but probably on the order of a millisecond or more.
-
-### `uv.walk(callback)`
-
-Walk the list of handles: `callback` will be executed with the 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)
-```
-
-## `uv_handle_t` — Base handle
-
-[`uv_handle_t`]: #uv_handle_t--base-handle
-
-`uv_handle_t` is the base type for all libuv handle types.
-
-Structures are aligned so that any libuv handle can be cast to `uv_handle_t`.
-All API functions defined here work with any handle type.
-
-### `uv.is_active(handle)`
-
-> method form `handle:is_active()`
-
-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. handlebasically any
- handle that deals with i/ois 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()`, etc.
-
-Rule of thumb: if a handle of type `uv_foo_t` has a `uv.foo_start()` function,
-then it’s active from the moment that function is called. Likewise,
-`uv.foo_stop()` deactivates the handle again.
-
-### `uv.is_closing(handle)`
-
-> method form `handle:is_closing()`
-
-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.
-
-### `uv.close(handle, callback)`
-
-> method form `handle:close(callback)`
-
-Request handle to be closed. `callback` will be called asynchronously after this
-call. This MUST be called on each handle before memory is released.
-
-Handles that wrap file descriptors are closed immediately but `callback` will
-still be deferred to the next iteration of the event loop. It gives you a chance
-to free up any resources associated with the handle.
-
-In-progress requests, like `uv_connect_t` or `uv_write_t`, are cancelled and
-have their callbacks called asynchronously with `status=UV_ECANCELED`.
-
-### `uv.ref(handle)`
-
-> method form `handle:ref()`
-
-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][].
-
-### `uv.unref(handle)`
-
-> method form `handle:unref()`
-
-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][].
-
-### `uv.has_ref(handle)`
-
-> method form `handle:has_ref()`
-
-Returns `true` if the handle referenced, `false` otherwise.
-
-See [Reference counting][].
-
-### `uv.send_buffer_size(handle, [size]) -> size`
-
-> method form `handle:send_buffer_size(size)`
-
-Gets or sets the size of the send buffer that the operating system uses for the
-socket.
-
-If `size` is omitted, it will return the current send buffer size, otherwise it
-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.
-
-### `uv.recv_buffer_size(handle, [size])`
-
-> method form `handle:recv_buffer_size(size)`
-
-Gets or sets the size of the receive buffer that the operating system uses for
-the socket.
-
-If `size` is omitted, it will return the current receive buffer size, otherwise
-it will use `size` to set the new receive 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.
-
-### `uv.fileno(handle)`
-
-> method form `handle:fileno()`
-
-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 UV_EINVAL.
-
-If a handle doesn’t have an attached file descriptor yet or the handle itself
-has been closed, this function will return UV_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.
-
-## Reference counting
-
-[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.
-
-## `uv_timer_t` — Timer handle
-
-[`uv_timer_t`]: #uv_timer_t--timer-handle
-
-Timer handles are used to schedule callbacks to be called in the future.
-
-### `uv.new_timer() -> timer`
-
-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 ()
- timer:stop()
- timer:close()
- callback()
- end)
- return timer
-end
-
--- And clearInterval
-local function clearInterval(timer)
- timer:stop()
- timer:close()
-end
-```
-
-### `uv.timer_start(timer, timeout, repeat, callback)`
-
-> method form `timer:start(timeout, repeat, callback)`
-
-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.
-
-### `uv.timer_stop(timer)`
-
-> method form `timer:stop()`
-
-Stop the timer, the callback will not be called anymore.
-
-### `uv.timer_again(timer)`
-
-> method form `timer:again()`
-
-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`.
-
-### `uv.timer_set_repeat(timer, repeat)`
-
-> method form `timer:set_repeat(repeat)`
-
-Set the repeat value in milliseconds.
-
-**Note**: If the repeat value is set from a timer callback it does not
-immediately take effect. If the timer was non-repeating before, it will have
-been stopped. If it was repeating, then the old repeat value will have been
-used to schedule the next timeout.
-
-### `uv.timer_get_repeat(timer) -> repeat`
-
-> method form `timer:get_repeat() -> repeat`
-
-Get the timer repeat value.
-
-## `uv_prepare_t` — Prepare handle
-
-[`uv_prepare_t`]: #uv_prepare_t--prepare-handle
-
-Prepare handles will run the given callback once per loop iteration, right before polling for i/o.
-
-```lua
-local prepare = uv.new_prepare()
-prepare:start(function()
- print("Before I/O polling")
-end)
-```
-
-### `uv.new_prepare() -> prepare`
-
-Creates and initializes a new `uv_prepare_t`. Returns the lua userdata wrapping
-it.
-
-### `uv.prepare_start(prepare, callback)`
-
-> method form `prepare:start(callback)`
-
-Start the handle with the given callback.
-
-### `uv.prepare_stop(prepare)`
-
-> method form `prepare:stop()`
-
-Stop the handle, the callback will no longer be called.
-
-## `uv_check_t` — Check handle
-
-[`uv_check_t`]: #uv_check_t--check-handle
-
-Check handles will run the given callback once per loop iteration, right after
-polling for i/o.
-
-```lua
-local check = uv.new_check()
-check:start(function()
- print("After I/O polling")
-end)
-```
-
-### `uv.new_check() -> check`
-
-Creates and initializes a new `uv_check_t`. Returns the lua userdata wrapping
-it.
-
-### `uv.check_start(check, callback)`
-
-> method form `check:start(callback)`
-
-Start the handle with the given callback.
-
-### `uv.check_stop(check)`
-
-> method form `check:stop()`
-
-Stop the handle, the callback will no longer be called.
-
-## `uv_idle_t` — Idle handle
-
-[`uv_idle_t`]: #uv_idle_t--idle-handle
-
-Idle handles will run the given callback once per loop iteration, right before
-the [`uv_prepare_t`][] handles.
-
-**Note**: The notable difference with prepare handles is that when there are
-active idle handles, the loop will perform a zero timeout poll instead of
-blocking for i/o.
-
-**Warning**: Despite the name, idle handles will get their callbacks called on
-every loop iteration, not when the loop is actually “idle”.
-
-```lua
-local idle = uv.new_idle()
-idle:start(function()
- print("Before I/O polling, no blocking")
-end)
-```
-### `uv.new_idle() -> idle`
-
-Creates and initializes a new `uv_idle_t`. Returns the lua userdata wrapping
-it.
-
-### `uv.idle_start(idle, callback)`
-
-> method form `idle:start(callback)`
-
-Start the handle with the given callback.
-
-### `uv.idle_stop(check)`
-
-> method form `idle:stop()`
-
-Stop the handle, the callback will no longer be called.
-
-## `uv_async_t` — Async handle
-
-[`uv_async_t`]: #uv_async_t--async-handle
-
-Async handles allow the user to “wakeup” the event loop and get a callback
-called from another thread.
-
-```lua
-local async
-async = uv.new_async(function()
- print("async operation ran")
- async:close()
-end)
-
-async:send()
-```
-
-### `uv.new_async(callback) -> async`
-
-Creates and initializes a new `uv_async_t`. Returns the lua userdata wrapping
-it. A NULL callback is allowed.
-
-**Note**: Unlike other handle initialization functions, it immediately starts
-the handle.
-
-### `uv.async_send(async)`
-
-> method form `async:send()`
-
-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, the only guarantee is
-that it will be called at least once. Thus, calling this function may not
-wakeup the event loop if it was already called previously within a short period
-of time.
-
-## `uv_poll_t` — Poll handle
-
-[`uv_poll_t`]: #uv_poll_t--poll-handle
-
-Poll handles are used to watch file descriptors for readability and writability,
-similar to the purpose of [poll(2)](http://linux.die.net/man/2/poll).
-
-The purpose of poll handles is to enable integrating external libraries that
-rely on the event loop to signal it about the socket status changes, like c-ares
-or libssh2. Using `uv_poll_t` for any other purpose is not recommended;
-`uv_tcp_t`, `uv_udp_t`, etc. provide an implementation that is faster and more
-scalable than what can be achieved with `uv_poll_t`, especially on Windows.
-
-It is possible that poll handles occasionally signal that a file descriptor is
-readable or writable even when it isn’t. The user should therefore always be
-prepared to handle EAGAIN or equivalent when it attempts to read from or write
-to the fd.
-
-It is not okay to have multiple active poll handles for the same socket, this
-can cause libuv to busyloop or otherwise malfunction.
-
-The user should not close a file descriptor while it is being polled by an
-active poll handle. This can cause the handle to report an error, but it might
-also start polling another socket. However the fd can be safely closed
-immediately after a call to `uv.poll_stop()` or `uv.close()`.
-
-**Note** On windows only sockets can be polled with poll handles. On Unix any
-file descriptor that would be accepted by poll(2) can be used.
-
-
-### `uv.new_poll(fd) -> poll`
-
-Initialize the handle using a file descriptor.
-
-The file descriptor is set to non-blocking mode.
-
-### `uv.new_socket_poll(fd) -> poll`
-
-Initialize the handle using a socket descriptor. On Unix this is identical to
-`uv.poll_init()`. On windows it takes a SOCKET handle.
-
-The socket is set to non-blocking mode.
-
-### `uv.poll_start(poll, events, callback)`
-
-> method form `poll:start()`
-
-Starts polling the file descriptor. `events` is `"r"`, `"w"`, or `"rw"` and
-translates to a bitmask made up of UV_READABLE and UV_WRITABLE. 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.
-
-## `uv.poll_stop(poll)`
-
-> method form `poll:stop()`
-
-Stop polling the file descriptor, the callback will no longer be called.
-
-## `uv_signal_t` — Signal handle
-
-[`uv_signal_t`]: #uv_signal_t--signal-handle
-
-Signal handles implement Unix style signal handling on a per-event loop bases.
-
-Reception of some signals is emulated on Windows:
-* SIGINT is normally delivered when the user presses CTRL+C. However, like on
-Unix, it is not generated when terminal raw mode is enabled.
-* SIGBREAK is delivered when the user pressed CTRL + BREAK.
-* SIGHUP is generated when the user closes the console window. On SIGHUP the
-program is given approximately 10 seconds to perform cleanup. After that
-Windows will unconditionally terminate it.
-* SIGWINCH is raised whenever libuv detects that the console has been resized.
-SIGWINCH is emulated by libuv when the program uses a uv_tty_t handle to write
-to the console. SIGWINCH may not always be delivered in a timely manner; libuv
-will only detect size changes when the cursor is being moved. When a readable
-[`uv_tty_t`][] handle is used in raw mode, resizing the console buffer will
-also trigger a SIGWINCH signal.
-
-Watchers for other signals can be successfully created, but these signals are
-never received. These signals are: SIGILL, SIGABRT, SIGFPE, SIGSEGV, SIGTERM
-and SIGKILL.
-
-Calls to raise() or abort() to programmatically raise a signal are not detected
-by libuv; these will not trigger a signal watcher.
-
-**Note**: On Linux SIGRT0 and SIGRT1 (signals 32 and 33) are used by the NPTL
-pthreads library to manage threads. Installing watchers for those signals will
-lead to unpredictable behavior and is strongly discouraged. Future versions of
-libuv may simply reject them.
-
-```lua
--- Create a new signal handler
-local sigint = uv.new_signal()
--- Define a handler function
-uv.signal_start(sigint, "sigint", function(signal)
-print("got " .. signal .. ", shutting down")
-os.exit(1)
-end)
-```
-
-### `uv.new_signal() -> signal`
-
-Creates and initializes a new `uv_signal_t`. Returns the lua userdata wrapping
-it.
-
-### `uv.signal_start(signal, signum, callback)`
-
-> method form `signal:start(signum, callback)`
-
-Start the handle with the given callback, watching for the given signal.
-
-### `uv.signal_stop(signal)`
-
-> method form `signal:stop()`
-
-Stop the handle, the callback will no longer be called.
-
-## `uv_process_t` — Process handle
-
-[`uv_process_t`]: #uv_process_t--process-handle
-
-Process handles will spawn a new process and allow the user to control it and
-establish communication channels with it using streams.
-
-### `uv.disable_stdio_inheritance()`
-
-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.
-
-### `uv.spawn(file, options, onexit) -> process, pid`
-
-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 stdout = uv.new_pipe(false)
-local stderr = uv.new_pipe(false)
-local stdin = uv.new_pipe(false)
-
-local handle, pid
-
-local function onexit(code, signal)
- p("exit", {code=code,signal=signal})
-end
-
-local function onclose()
- p("close")
-end
-
-local function onread(err, chunk)
- assert(not err, err)
- if (chunk) then
- p("data", {data=chunk})
- else
- p("end")
- end
-end
-
-local function onshutdown()
- uv.close(handle, onclose)
-end
-
-handle, pid = uv.spawn("cat", {
- stdio = {stdin, stdout, stderr}
-}, onexit)
-
-p{
- handle=handle,
- pid=pid
-}
-
-uv.read_start(stdout, onread)
-uv.read_start(stderr, onread)
-uv.write(stdin, "Hello World")
-uv.shutdown(stdin, onshutdown)
-```
-
- - `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 current working directory for the subprocess.
- - `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_h` 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.
-
-When the child process exits, the `onexit` callback will be called with exit
-code and signal.
-
-### `uv.process_kill(process, sigmun)`
-
-> method form `process:kill(sigmun)`
-
-Sends the specified signal to the given process handle.
-
-### `uv.kill(pid, sigmun)`
-
-Sends the specified signal to the given PID.
-
-## `uv_stream_t` — Stream handle
-
-[`uv_stream_t`]: #uv_stream_t--stream-handle
-
-Stream handles provide an abstraction of a duplex communication channel.
-[`uv_stream_t`][] is an abstract type, libuv provides 3 stream implementations in
-the form of [`uv_tcp_t`][], [`uv_pipe_t`][] and [`uv_tty_t`][].
-
-### `uv.shutdown(stream, [callback]) -> req`
-
-> (method form `stream:shutdown([callback]) -> req`)
-
-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.
-
-### `uv.listen(stream, backlog, callback)`
-
-> (method form `stream:listen(backlog, callback)`)
-
-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.
-
-### `uv.accept(stream, client_stream)`
-
-> (method form `stream:accept(client_stream)`)
-
-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)
-```
-
-### `uv.read_start(stream, callback)`
-
-> (method form `stream:read_start(callback)`)
-
-Callback is of the form `(err, data)`.
-
-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)
-```
-
-### `uv.read_stop(stream)`
-
-> (method form `stream:read_stop()`)
-
-Stop reading data from the stream. The read callback will no longer be called.
-
-### `uv.write(stream, data, [callback])`
-
-> (method form `stream:write(data, [callback])`)
-
-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.
-
-### `uv.write2(stream, data, send_handle, callback)`
-
-> (method form `stream:write2(data, send_handle, callback)`)
-
-Extended write function for sending handles over a pipe. The pipe must be
-initialized with ip option to `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.
-
-### `uv.try_write(stream, data)`
-
-> (method form `stream:try_write(data)`)
-
-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).
-
-### `uv.is_readable(stream)`
-
-> (method form `stream:is_readable()`)
-
-Returns `true` if the stream is readable, `false` otherwise.
-
-### `uv.is_writable(stream)`
-
-> (method form `stream:is_writable()`)
-
-Returns `true` if the stream is writable, `false` otherwise.
-
-### `uv.stream_set_blocking(stream, blocking)`
-
-> (method form `stream:set_blocking(blocking)`)
-
-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.
-
-## `uv_tcp_t` — TCP handle
-
-[`uv_tcp_t`]: #uv_tcp_t--tcp-handle
-
-TCP handles are used to represent both TCP streams and servers.
-
-`uv_tcp_t` is a ‘subclass’ of [`uv_stream_t`][](#uv_stream_t--stream-handle).
-
-### `uv.new_tcp() -> tcp`
-
-Creates and initializes a new `uv_tcp_t`. Returns the lua userdata wrapping it.
-
-### `uv.tcp_open(tcp, sock)`
-
-> (method form `tcp:open(sock)`)
-
-Open an existing file descriptor or SOCKET as a TCP handle.
-
-**Note: The user is responsible for setting the file descriptor in non-blocking
-mode.
-
-### `uv.tcp_nodelay(tcp, enable)`
-
-> (method form `tcp:nodelay(enable)`)
-
-Enable / disable Nagle’s algorithm.
-
-### `uv.tcp_keepalive(tcp, enable, [delay])`
-
-> (method form `tcp:keepalive(enable, [delay])`)
-
-Enable / disable TCP keep-alive. `delay` is the initial delay in seconds, ignored
-when enable is `false`.
-
-### `uv.tcp_simultaneous_accepts(tcp, enable)`
-
-> (method form `tcp:simultaneous_accepts(enable)`)
-
-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.
-
-### `uv.tcp_bind(tcp, address, port)`
-
-> (method form `tcp:bind(address, port)`)
-
-Bind the handle to an address and port. `address` should be an IP address and
-not a domain name.
-
-When the port is already taken, you can expect to see an UV_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()`.
-
-### `uv.tcp_getsockname(tcp)`
-
-> (method form `tcp:getsockname()`)
-
-Get the current address to which the handle is bound.
-
-### `uv.tcp_getpeername(tcp)`
-
-> (method form `tcp:getpeername()`)
-
-Get the address of the peer connected to the handle.
-
-### `uv.tcp_connect(tcp, address, port, callback) -> req`
-
-> (method form `tcp:connect(host, port, callback) -> req`)
-
-### `uv.tcp_write_queue_size(tcp) -> size`
-
-> (method form `tcp:write_queue_size() -> size`)
-
-Establish an IPv4 or IPv6 TCP connection.
-
-The callback is made when the connection has been established or when a
-connection error happened.
-
-```lua
-local client = uv.new_tcp()
-client:connect("127.0.0.1", 8080, function (err)
- -- check error and carry on.
-end)
-```
-
-## `uv_pipe_t` — Pipe handle
-
-[`uv_pipe_t`]: #uv_pipe_t--pipe-handle
-
-Pipe handles provide an abstraction over local domain sockets on Unix and named
-pipes on Windows.
-
-```lua
-local pipe = uv.new_pipe(false)
-
-pipe:bind('/tmp/sock.test')
-
-pipe:listen(128, function()
- local client = uv.new_pipe(false)
- pipe:accept(client)
- client:write("hello!\n")
- client:close()
-end)
-```
-
-### `uv.new_pipe(ipc) -> pipe`
-
-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.
-
-### `uv.pipe_open(file) -> pipe`
-
-Open an existing file descriptor or [`uv_handle_t`][] as a pipe.
-
-**Note**: The file descriptor is set to non-blocking mode.
-
-### `uv.pipe_bind(pipe, name)`
-
-> (method form `pipe:bind(name)`)
-
-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.
-
-### `uv.pipe_connect(pipe, name, callback)`
-
-> (method form `pipe:connect(name, callback)`)
-
-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.
-
-### `uv.pipe_getsockname(pipe)`
-
-> (method form `pipe:getsockname()`)
-
-Returns the name of the Unix domain socket or the named pipe.
-
-### `uv.pipe_pending_instances(pipe, count)`
-
-> (method form `pipe:pending_instances(count)`)
-
-Set the number of pending pipe instance handles when the pipe server is waiting for connections.
-
-**Note**: This setting applies to Windows only.
-
-### `uv.pipe_pending_count(pipe)`
-
-> (method form `pipe:pending_count()`)
-
-Returns the pending pipe count for the named pipe.
-
-### `uv.pipe_pending_type(pipe)`
-
-> (method form `pipe:pending_type()`)
-
-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)`][].
-
-## `uv_tty_t` — TTY handle
-
-[`uv_tty_t`]: #uv_tty_t--tty-handle
-
-TTY handles represent a stream for the console.
-
-```lua
--- Simple echo program
-local stdin = uv.new_tty(0, true)
-local stdout = uv.new_tty(1, false)
-
-stdin:read_start(function (err, data)
- assert(not err, err)
- if data then
- stdout:write(data)
- else
- stdin:close()
- stdout:close()
- end
-end)
-```
-
-### uv.new_tty(fd, readable) -> tty
-
-Initialize a new TTY stream with the given file descriptor. Usually the file
-descriptor will be:
-
- - 0 - stdin
- - 1 - stdout
- - 2 - stderr
-
-`readable, specifies if you plan on calling uv_read_start() with this stream.
-`stdin is readable, stdout is not.
-
-On Unix this function will try to open /dev/tty 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.
-
-Note: If opening `/dev/tty` fails, libuv falls back to blocking writes for
-non-readable TTY streams.
-
-### uv.tty_set_mode(mode)
-
-> (method form `tty:set_mode(mode)`)
-
-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)
-
-## uv.tty_reset_mode()
-
-To be called when the program exits. Resets TTY settings to default values for
-the next process to take over.
-
-This function is async signal-safe on Unix platforms but can fail with error
-code UV_EBUSY if you call it when execution is inside uv_tty_set_mode().
-
-## uv.tty_get_winsize() -> w, h
-
-> (method form `tty:get_winsize() -> w, h`)
-
-Gets the current Window size.
-
-## `uv_udp_t` — UDP handle
-
-[`uv_udp_t`]: #uv_udp_t--udp-handle
-
-UDP handles encapsulate UDP communication for both clients and servers.
-
-### uv.new_udp() -> udp
-
-Initialize a new UDP handle. The actual socket is created lazily.
-
-### uv.udp_open(udp, fd)
-
-> (method form `udp:open(fd)`)
-
-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.
-
-### uv.udp_bind(udp, host, port)
-
-> (method form `udp:bind(host, port)`)
-
-Bind the UDP handle to an IP address and port.
-
-### uv.udp_getsockname(udp)
-
-> (method form `udp:getsockname()`)
-
-Get the local IP and port of the UDP handle.
-
-### uv.udp_set_membership(udp, multicast_addr, interface_addr, membership)
-
-> (method form `udp:set_membership(multicast_addr, interface_addr, membership)`)
-
-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"`.
-
-### uv.udp_set_multicast_loop(udp, on)
-
-> (method form `udp:set_multicast_loop(on)`)
-
-Set IP multicast loop flag. Makes multicast packets loop back to local
-sockets.
-
-`on` is a boolean.
-
-### uv.udp_set_multicast_ttl(udp, tty)
-
-> (method form `udp:set_multicast_ttl(tty)`)
-
-Set the multicast ttl.
-
-`ttl` is an integer 1 through 255.
-
-### uv.udp_set_multicast_interface(udp, interface_addr)
-
-> (method form `udp:set_multicast_interface(interface_addr)`)
-
-Set the multicast interface to send or receive data on.
-
-### uv.udp_set_broadcast(udp, on)
-
-Set broadcast on or off.
-
-> (method form `udp:set_broadcast(, on)`)
-
-### uv.udp_set_ttl(udp, ttl)
-
-> (method form `udp:set_ttl(ttl)`)
-
-Set the time to live.
-
-`ttl` is an integer 1 through 255.
-
-### uv.udp_send(udp, data, host, port, callback)
-
-> (method form `udp:send(data, host, port, callback)`)
-
-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.
-
-### uv.udp_try_send(udp, data, host, port)
-
-> (method form `udp:try_send(data, host, port)`)
-
-Same as `uv_udp_send()`, but won’t queue a send request if it can’t be
-completed immediately.
-
-### uv.udp_recv_start(udp, callback)
-
-> (method form `udp:recv_start(callback)`)
-
-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.
-
-### uv.udp_recv_stop(udp)
-
-> (method form `udp:recv_stop()`)
-
-## `uv_fs_event_t` — FS Event handle
-
-[`uv_fs_event_t`]: #uv_fs_event_t--fs-event-handle
-
-**TODO**: port docs from [docs.libuv.org](http://docs.libuv.org/en/v1.x/fs_event.html)
-using [functions](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L174-L177)
-and [methods](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L265-L270)
-from [fs_event.c](https://github.com/luvit/luv/blob/master/src/fs_event.c)
-
-## `uv_fs_poll_t` — FS Poll handle
-
-[`uv_fs_poll_t`]: #uv_fs_poll_t--fs-poll-handle
-
-**TODO**: port docs from [docs.libuv.org](http://docs.libuv.org/en/v1.x/fs_poll.html)
-using [functions](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L180-L183)
-and [methods](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L272-L277)
-from [fs_poll.c](https://github.com/luvit/luv/blob/master/src/fs_poll.c)
-
-## Filesystem operations
-
-[Filesystem operations]:#filesystem-operations
-
-**TODO**: port docs from [docs.libuv.org](http://docs.libuv.org/en/v1.x/fs.html)
-using [functions](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L186-L213)
-from [fs.c](https://github.com/luvit/luv/blob/master/src/fs.c)
-
-## DNS utility functions
-
-[DNS utility functions]: #dns-utility-functions
-
-**TODO**: port docs from [docs.libuv.org](http://docs.libuv.org/en/v1.x/dns.html)
-using [functions](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L216-L217)
-from [dns.c](https://github.com/luvit/luv/blob/master/src/dns.c)
-
-## Miscellaneous utilities
-
-[Miscellaneous utilities]: #miscellaneous-utilities
-
-**TODO**: port docs from [docs.libuv.org](http://docs.libuv.org/en/v1.x/misc.html)
-using [functions](https://github.com/luvit/luv/blob/25278a3871962cab29763692fdc3b270a7e96fe9/src/luv.c#L220-L235)
-from [misc.c](https://github.com/luvit/luv/blob/master/src/misc.c)
-
-[luv]: https://github.com/luvit/luv
-[luvit]: https://github.com/luvit/luvit
-[libuv]: https://github.com/libuv/libuv