# 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