LIBUV(1)

💖 libuv(1) — libuv API documentation 💖

okay so bestie, you're looking at the libuv manual page, aka libuv(1), aka the libuv API documentation. It's giving foundational async energy, and we're gonna get through it together. 🫶

---

🌈 NAME 🌈

libuv — libuv documentation. That's the name, that's the vibe, iconic. 👑

✨ OVERVIEW ✨

libuv is a multi-platform support library with a focus on asynchronous I/O. It was primarily developed for use by Node.js (https://nodejs.org), but it's also used by Luvit (https://luvit.io), Julia (https://julialang.org), uvloop (https://github.com/MagicStack/uvloop), and others (https://github.com/libuv/libuv/blob/v1.x/LINKS.md). no cap, the ecosystem said "we stan." 💅

Note: In case you find errors in this documentation you can help by sending pull requests (https://github.com/libuv/libuv)! bestie behavior fr fr. 💖

🦋 FEATURES 🦋

• Full-featured event loop backed by epoll, kqueue, IOCP, event ports. 🔥
• Asynchronous TCP and UDP sockets.
• Asynchronous DNS resolution.
• Asynchronous file and file system operations.
• File system events.
• ANSI escape code controlled TTY.
• IPC with socket sharing, using Unix domain sockets or named pipes (Windows).
• Child processes.
• Thread pool.
• Signal handling.
• High resolution clock.
• Threading and synchronization primitives.

🌸 DOCUMENTATION 🌸

🎀 Design overview 🎀

libuv is a cross-platform support library which was originally written for Node.js (https://nodejs.org). It's designed around the event-driven asynchronous I/O model. 💫

The library provides much more than a simple abstraction over different I/O polling mechanisms: 'handles' and 'streams' provide a high level abstraction for sockets and other entities; cross-platform file I/O and threading functionality is also provided, amongst other things. it's giving range, honestly.

Here is a diagram illustrating the different parts that compose libuv and what subsystem they relate to:

          LIBUV

          +----------------------------------------------+ +---+ +---+ +---+
          |                                              | |   | |   | |   |
          | Network I/O                                  | | F | | D | | U |
          |                                              | | i | | N | | s |
          |                                              | | l | | S | | e |
          |                                              | | e | |   | | r |
          |                                              | |   | | O | |   |
          |                                              | | I | | p | | C |
          | +------+ +------+ +------+ +------+ +------+ | | / | | s | | o |
          | | TCP  | | UDP  | | TTY  | | Pipe | | ...  | | | O | |   | | d |
          | +------+ +------+ +------+ +------+ +------+ | |   | |   | | e |
          |                                              | |   | |   | |   |
          +----------------------------------------------+ +---+ +---+ +---+

          +----------------------------------+  +--------+ +---------------+
          |           uv__io_t               |  |        | |               |
          +----------------------------------+  |        | |               |
                                                |  IOCP  | |  Thread Pool  |
          +-------+ +--------+ +-------------+  |        | |               |
          | epoll | | kqueue | | event ports |  |        | |               |
          +-------+ +--------+ +-------------+  +--------+ +---------------+

💜 Handles and requests 💜

libuv provides users with 2 abstractions to work with, in combination with the event loop: handles and requests. yes bestie, only two, and they're both main characters. 🎀

Handles represent long-lived objects capable of performing certain operations while active. Some examples:

• A prepare handle gets its callback called once every loop iteration when active.
• A TCP server handle that gets its connection callback called every time there is a new connection.

Requests represent (typically) short-lived operations. These operations can be performed over a handle: write requests are used to write data on a handle; or standalone: getaddrinfo requests don't need a handle they run directly on the loop.

Guidelines for dealing with handles and requests:

1. If uv_foo_init() succeeds in initializing the handle, you must call uv_close(). If the handle's init function errors, you don't need to do anything.
2. Only handles are closed, not requests. For example, uv_tcp_t is a handle, uv_write_t is a request.
3. The handle's memory can only be reclaimed or reused from inside the uv_close_cb or afterwards, not before.
4. Most handles have init + start/stop functions; some handles don't. Example: uv_tcp_t vs. uv_process_t; uv_spawn() combines handle initialization and process start into one.
5. Requests are closed automatically when they complete, or when they are cancelled with uv_cancel().
6. No additional cleanup is needed except for uv_fs_t and uv_getaddrinfo_t requests. For uv_fs_t, call uv_fs_req_cleanup() once you are done with it; for uv_getaddrinfo_t, that's uv_freeaddrinfo().
7. The request's memory can only be reclaimed or reused from that point onward.

🔥 The I/O loop 🔥

The I/O (or event) loop is the central part of libuv. It establishes the content for all I/O operations, and it's meant to be tied to a single thread. One can run multiple event loops as long as each runs in a different thread. The libuv event loop (or any other API involving the loop or handles, for that matter) is not thread-safe except where stated otherwise. ⚠️

The event loop follows the rather usual single threaded asynchronous I/O approach: all (network) I/O is performed on non-blocking sockets which are polled using the best mechanism available on the given platform: epoll on Linux, kqueue on OSX and other BSDs, event ports on SunOS and IOCP on Windows. As part of a loop iteration the loop will block waiting for I/O activity on sockets which have been added to the poller and callbacks will be fired indicating socket conditions (readable, writable hangup) so handles can read, write or perform the desired I/O operation.

In order to better understand how the event loop operates, the following diagram illustrates all stages of a loop iteration:

                     +------------------------+
                     | Initialze loop time    |
                     +------------------------+
                     | Run due timers         |
                     +------------------------+
                                 |
                                 v
                                 __
             _____              /  \
            /     \            /    \
           /       \  No      / Loop \
           | end    |<-------| alive? |<----------+
           \       /          \      /            |
            \     /            \    /             |
             -----              \__/              |
                                 |                |
                                 | Yes            |
                                 v                |
                     +------------------------+   |
                     | Call pending callbacks |   |
                     +------------------------+   |
                     | Run idle handles       |   |
                     +------------------------+   |
                     | Run prepare handles    |   |
                     +------------------------+   |
                     | Poll for I/O           |   |
                     +------------------------+   |
                     | Run check handles      |   |
                     +------------------------+   |
                     | Call close callbacks   |   |
                     +------------------------+   |
                     | Update loop time       |   |
                     +------------------------+   |
                     | Run due timers         |---+
                     +------------------------+

1. The loop concept of 'now' is initially set.
2. Due timers are run if the loop was run with UV_RUN_DEFAULT. All active timers scheduled for a time before the loop's concept of now get their callbacks called.
3. If the loop is alive an iteration is started, otherwise the loop will exit immediately. So, when is a loop considered to be alive? If a loop has active and ref'd handles, active requests or closing handles it's considered to be alive.
4. Pending callbacks are called. All I/O callbacks are called right after polling for I/O, for the most part. There are cases, however, in which calling such a callback is deferred for the next loop iteration. If the previous iteration deferred any I/O callback it will be run at this point.
5. Idle handle callbacks are called. Despite the unfortunate name, idle handles are run on every loop iteration, if they are active.
6. Prepare handle callbacks are called. Prepare handles get their callbacks called right before the loop will block for I/O.
7. Poll timeout is calculated. Before blocking for I/O the loop calculates for how long it should block. These are the rules when calculating the timeout:
   • If the loop was run with the UV_RUN_NOWAIT flag, the timeout is 0.
   • If the loop is going to be stopped (uv_stop() was called), the timeout is 0.
   • If there are no active handles or requests, the timeout is 0.
   • If there are any idle handles active, the timeout is 0.
   • If there are any handles pending to be closed, the timeout is 0.
   • If none of the above cases matches, the timeout of the closest timer is taken, or if there are no active timers, infinity.
8. The loop blocks for I/O. At this point the loop will block for I/O for the duration calculated in the previous step. All I/O related handles that were monitoring a given file descriptor for a read or write operation get their callbacks called at this point.
9. Check handle callbacks are called. Check handles get their callbacks called right after the loop has blocked for I/O. Check handles are essentially the counterpart of prepare handles.
10. Close callbacks are called. If a handle was closed by calling uv_close() it will get the close callback called.
11. The loop concept of 'now' is updated.
12. Due timers are run. Note that 'now' is not updated again until the next loop iteration. So if a timer became due while other timers were being processed, it won't be run until the following event loop iteration.
13. Iteration ends. If the loop was run with UV_RUN_NOWAIT or UV_RUN_ONCE modes the iteration ends and uv_run() will return. If the loop was run with UV_RUN_DEFAULT it will continue from the start if it's still alive, otherwise it will also end.

Important: libuv uses a thread pool to make asynchronous file I/O operations possible, but network I/O is always performed in a single thread, each loop's thread. this part matters, bestie, don't skip it. 🫶

Note: the polling mechanism is different, but libuv keeps the execution model consistent across Unix systems and Windows. Same vibe, different plumbing 💅

🌸 File I/O

Okay so here's the thing — network I/O has all these cute platform-specific primitives libuv can lean on, but file I/O? Nope. There are none. So the current approach is to run blocking file I/O operations in a thread pool. Iconic workaround, honestly.

For a thorough explanation of the whole cross-platform file I/O landscape, check out this post <https://blog.libtorrent.org/2012/10/asynchronous-disk-io/>.

libuv currently uses a global thread pool on which all loops can queue work. And 3 types of operations are currently run on this pool:

• File system operations
• DNS functions (getaddrinfo and getnameinfo)
• User specified code via uv_queue_work()

Warning bestie: see the Thread pool work scheduling section for more details, but keep in mind the thread pool size is quite limited. 🫶

🦋 API documentation

💜 Error handling

In libuv, errors are negative numbered constants. Rule of thumb: whenever there's a status parameter, or an API function returns an integer, a negative number implies an error. That's the whole tell, iykyk.

When a function which takes a callback returns an error, the callback will never be called. Not once. Not ever. 😭

Note: implementation detail — on Unix, error codes are the negated errno (or -errno), while on Windows they're defined by libuv to arbitrary negative numbers.

✨ Error constants

• UV_E2BIG — argument list too long
• UV_EACCES — permission denied
• UV_EADDRINUSE — address already in use
• UV_EADDRNOTAVAIL — address not available
• UV_EAFNOSUPPORT — address family not supported
• UV_EAGAIN — resource temporarily unavailable
• UV_EAI_ADDRFAMILY — address family not supported
• UV_EAI_AGAIN — temporary failure
• UV_EAI_BADFLAGS — bad ai_flags value
• UV_EAI_BADHINTS — invalid value for hints
• UV_EAI_CANCELED — request canceled
• UV_EAI_FAIL — permanent failure
• UV_EAI_FAMILY — ai_family not supported
• UV_EAI_MEMORY — out of memory
• UV_EAI_NODATA — no address
• UV_EAI_NONAME — unknown node or service
• UV_EAI_OVERFLOW — argument buffer overflow
• UV_EAI_PROTOCOL — resolved protocol is unknown
• UV_EAI_SERVICE — service not available for socket type
• UV_EAI_SOCKTYPE — socket type not supported
• UV_EALREADY — connection already in progress
• UV_EBADF — bad file descriptor
• UV_EBUSY — resource busy or locked
• UV_ECANCELED — operation canceled
• UV_ECHARSET — invalid Unicode character
• UV_ECONNABORTED — software caused connection abort
• UV_ECONNREFUSED — connection refused
• UV_ECONNRESET — connection reset by peer
• UV_EDESTADDRREQ — destination address required
• UV_EEXIST — file already exists
• UV_EFAULT — bad address in system call argument
• UV_EFBIG — file too large
• UV_EHOSTUNREACH — host is unreachable
• UV_EINTR — interrupted system call
• UV_EINVAL — invalid argument
• UV_EIO — i/o error
• UV_EISCONN — socket is already connected
• UV_EISDIR — illegal operation on a directory
• UV_ELOOP — too many symbolic links encountered
• UV_EMFILE — too many open files
• UV_EMSGSIZE — message too long
• UV_ENAMETOOLONG — name too long
• UV_ENETDOWN — network is down
• UV_ENETUNREACH — network is unreachable
• UV_ENFILE — file table overflow
• UV_ENOBUFS — no buffer space available
• UV_ENODEV — no such device
• UV_ENOENT — no such file or directory
• UV_ENOMEM — not enough memory
• UV_ENONET — machine is not on the network
• UV_ENOPROTOOPT — protocol not available
• UV_ENOSPC — no space left on device
• UV_ENOSYS — function not implemented
• UV_ENOTCONN — socket is not connected
• UV_ENOTDIR — not a directory
• UV_ENOTEMPTY — directory not empty
• UV_ENOTSOCK — socket operation on non-socket
• UV_ENOTSUP — operation not supported on socket
• UV_EOVERFLOW — value too large for defined data type
• UV_EPERM — operation not permitted
• UV_EPIPE — broken pipe
• UV_EPROTO — protocol error
• UV_EPROTONOSUPPORT — protocol not supported
• UV_EPROTOTYPE — protocol wrong type for socket
• UV_ERANGE — result too large
• UV_EROFS — read-only file system
• UV_ESHUTDOWN — cannot send after transport endpoint shutdown
• UV_ESPIPE — invalid seek
• UV_ESRCH — no such process
• UV_ETIMEDOUT — connection timed out
• UV_ETXTBSY — text file is busy
• UV_EXDEV — cross-device link not permitted
• UV_UNKNOWN — unknown error
• UV_EOF — end of file
• UV_ENXIO — no such device or address
• UV_EMLINK — too many links
• UV_ENOTTY — inappropriate ioctl for device
• UV_EFTYPE — inappropriate file type or format
• UV_EILSEQ — illegal byte sequence
• UV_ESOCKTNOSUPPORT — socket type not supported
• UV_EUNATCH — protocol driver not attached

🎀 API

• UV_ERRNO_MAP(iter_macro) — Macro that expands to a series of invocations of iter_macro for each of the error constants above. iter_macro is invoked with two arguments: the name of the error constant without the UV_ prefix, and the error message string literal.
• const char *uv_strerror(int err) — Returns the error message for the given error code. Leaks a few bytes of memory when you call it with an unknown error code. 🙈 (yes, really, that's canon)
• char *uv_strerror_r(int err, char *buf, size_t buflen) — Returns the error message for the given error code. The zero-terminated message is stored in the user-supplied buffer buf of at most buflen bytes.

Added in version 1.22.0.

• const char *uv_err_name(int err) — Returns the error name for the given error code. Leaks a few bytes of memory when you call it with an unknown error code.
• char *uv_err_name_r(int err, char *buf, size_t buflen) — Returns the error name for the given error code. The zero-terminated name is stored in the user-supplied buffer buf of at most buflen bytes.

Added in version 1.22.0.

• int uv_translate_sys_error(int sys_errno) — Returns the libuv error code 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()).

If sys_errno is already a libuv error, it is simply returned. No notes. 💅

Changed in version 1.10.0: function declared public.

---

👑 Version-checking macros and functions

Starting with version 1.0.0, libuv follows the semantic versioning <https://semver.org> scheme. Which means new APIs can absolutely pop up throughout the lifetime of a major release — so this section has all the macros and functions that let you write or compile code conditionally, so you can work with multiple libuv versions at once. Bestie behaviour, fr fr.

🌈 Macros

• UV_VERSION_MAJOR — libuv version's major number.
• UV_VERSION_MINOR — libuv version's minor number.
• UV_VERSION_PATCH — libuv version's patch number.
• UV_VERSION_IS_RELEASE — Set to 1 to indicate a release version of libuv, 0 for a development snapshot.
• UV_VERSION_SUFFIX — libuv version suffix. Certain development releases such as Release Candidates might have a suffix such as "rc".
• UV_VERSION_HEX — 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. E.g. for libuv 1.2.3 this would be 0x010203.

Added in version 1.7.0.

⭐ Functions

• unsigned int uv_version(void) — Returns UV_VERSION_HEX.
• const char *uv_version_string(void) — Returns the libuv version number as a string. For non-release versions the version suffix is included.

---

🦋 uv_loop_t — Event loop

The event loop is the central part of libuv's functionality — the main character, honestly. It takes care of polling for i/o and scheduling callbacks to be run based on different sources of events.

🎀 Data types

• type uv_loop_t — Loop data type.
• enum uv_loop_option — Additional loop options. See uv_loop_configure().

typedef enum {
    UV_LOOP_BLOCK_SIGNAL = 0,
    UV_METRICS_IDLE_TIME,
    UV_LOOP_USE_IO_URING_SQPOLL
} uv_loop_option;

• enum uv_run_mode — Mode used to run the loop with uv_run().

typedef enum {
    UV_RUN_DEFAULT = 0,
    UV_RUN_ONCE,
    UV_RUN_NOWAIT
} uv_run_mode;

• typedef void (*uv_walk_cb)(uv_handle_t *handle, void *arg) — Type definition for callback passed to uv_walk().

💜 Public members

• void *uv_loop_t.data — Space for user-defined arbitrary data. libuv does not use and does not touch this field. It's yours, bestie, go off. 🫶

✨ API

• int uv_loop_init(uv_loop_t *loop) — Initializes the given uv_loop_t structure.
• int uv_loop_configure(uv_loop_t *loop, uv_loop_option option, ...) — Added in version 1.0.2.

Set additional loop options. You should normally call this before the first call to uv_run() unless mentioned otherwise.

Returns 0 on success or a UV_E* error code on failure. Be prepared to handle UV_ENOSYS — that means the loop option is not supported by the platform. No cap, you gotta check for it.

Supported options:

• UV_LOOP_BLOCK_SIGNAL: Block a signal when polling for new events. The second argument to uv_loop_configure() is 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 UV_EINVAL. 💀

• UV_METRICS_IDLE_TIME: Accumulate the amount of idle time the event loop spends in the event provider.

This option is necessary to use uv_metrics_idle_time().

• UV_LOOP_USE_IO_URING_SQPOLL — turns on the SQPOLL io_uring instance so asynchronous file system operations get handled 💅

Changed in version 1.39.0: added the UV_METRICS_IDLE_TIME option.

Changed in version 1.49.0: added the UV_LOOP_USE_IO_URING_SQPOLL option.

---

🌈 int uv_loop_close(uv_loop_t *loop)

Okay so this one frees literally all the internal loop resources ✨ But — and this is the important part bestie — only call it when the loop has finished executing and all open handles and requests have been closed. Otherwise it just returns UV_EBUSY and gives you nothing 😭

Once it comes back successfully, you're free to free the memory you allocated for the loop. Cleanup queen behavior, we love to see it 🎀

🦋 uv_loop_t *uv_default_loop(void)

Gives you back the initialized default loop 💖 It can return NULL if allocation fails, so like… check it, bestie.

This is literally just the convenient way to have one global loop across your whole app. The default loop is in no way different from ones you make with uv_loop_init(). So obviously it can — and should — be closed with uv_loop_close() so its resources get freed. No special treatment, no main character exception ✨

⚠️ Warning: this function is not thread safe. Do not be passing it around between threads, ngl.

🔥 int uv_run(uv_loop_t *loop, uv_run_mode mode)

This runs the event loop, and it behaves differently depending on which mode you hand it 👑

• UV_RUN_DEFAULT — runs the event loop until there are no more active and referenced handles or requests left. Returns non-zero if uv_stop() was called and there are still active handles or requests. Returns zero in all other cases.
• UV_RUN_ONCE — polls for i/o once. Heads up: this one blocks if there are no pending callbacks 🙈 Returns zero when it's done (no active handles or requests left), or non-zero if more callbacks are expected — meaning you should run the event loop again sometime in the future.
• UV_RUN_NOWAIT — polls for i/o once but does not block when there are no pending callbacks. Returns zero if it's done (no active handles or requests left), or non-zero if more callbacks are expected — same deal, run the loop again sometime later.

💀 Big one: uv_run() is not reentrant. It must not be called from a callback. Periodt.

⭐ int uv_loop_alive(const uv_loop_t *loop)

Returns non-zero if there are referenced active handles, active requests, or closing handles chilling in the loop ✨ Basically a vibe check for "is anything still happening in here".

🎀 void uv_stop(uv_loop_t *loop)

Stops the event loop, making uv_run() end as soon as possible. But not sooner than the next loop iteration, bestie — it's not instant magic 😌

Oh and if you called this before it started blocking for i/o, the loop won't block for i/o on this iteration. Slay.

🌸 size_t uv_loop_size(void)

Returns the size of the uv_loop_t structure 🫶 Made for the FFI binding writers who don't wanna know the structure layout. Respect the hustle.

💜 int uv_backend_fd(const uv_loop_t *loop)

Gets the backend file descriptor. Only kqueue, epoll and event ports are supported, so like… know your platform 💅

You can pair this with uv_run(loop, UV_RUN_NOWAIT) to poll in one thread and run the event loop's callbacks in another — go look at test/test-embed.c for an example, it's giving tutorial energy ✨

📝 Note: embedding a kqueue fd in another kqueue pollset doesn't work on all platforms. It's not an error to add the fd, it just never generates events 💀

🍓 int uv_backend_timeout(const uv_loop_t *loop)

Gets the poll timeout ⏰ Return value is in milliseconds, or -1 when there's no timeout at all.

🧚 uint64_t uv_now(const uv_loop_t *loop)

Returns the current timestamp in milliseconds ✨ It's cached at the start of the event loop tick — check uv_update_time() for the details and the reasoning behind that.

The timestamp increases monotonically from some arbitrary point in time. So please don't go making assumptions about the starting point, you will only get disappointed 😭🙈

📝 Note: use uv_hrtime() if you need sub-millisecond granularity. She's the precision one.

🌈 void uv_update_time(uv_loop_t *loop)

Updates the event loop's whole concept of "now" 🫶 Libuv caches the current time at the start of the event loop tick purely to cut down on time-related system calls. Efficient icon behavior.

You won't normally need to call this unless you've got callbacks that block the event loop for longer periods of time — and "longer" is kinda subjective, but probably on the order of a millisecond or more. Iykyk ⏳

👑 void uv_walk(uv_loop_t *loop, uv_walk_cb walk_cb, void *arg)

Walks the list of handles: walk_cb gets executed with the given arg. That's it, that's the whole thing 💅

🦋 int uv_loop_fork(uv_loop_t *loop)

Added in version 1.12.0.

Reinitializes any kernel state that's necessary in the child process after a fork(2) system call 🌱

Watchers that were already started will keep on being started in the child process. No rest for the watchers.

Okay so this part is required: you have to explicitly call this function on every event loop created in the parent process that you plan to keep using in the child — including the default loop, even if you don't continue using it in the parent. And it must be called before calling uv_run() or any other API function that uses the loop in the child.

💀 If you skip it: undefined behaviour, bestie. Possibly duplicate events delivered to both parent and child, or the child process just aborting. Not cute.

When it's possible, it's preferred to create a brand new loop in the child process instead of reusing one created in the parent. New loops created in the child after the fork should not use this function — they're fresh, they're fine 🎀

This function is not implemented on Windows, where it returns UV_ENOSYS.

⚠️ Caution: this function is experimental. It may contain bugs, and it's subject to change or removal. API and ABI stability is not guaranteed 😭

📝 Note: on Mac OS X, if directory FS event handles were in use in the parent process for any event loop, the child process will no longer be able to use the most efficient FSEvent implementation. Instead, uses of directory FS event handles in the child fall back to the same implementation used for files and on other kqueue-based systems 🙈

⚠️ Caution: on AIX and SunOS, FS event handles that were already started in the parent process at the time of forking will not deliver events in the child process — they must be closed and restarted. On all other platforms they'll keep working normally without any further intervention ✨

⚠️ Caution: any previous value you got from uv_backend_fd() is now invalid. Call it again to determine the correct backend file descriptor, no cap 💅

🎀 void *uv_loop_get_data(const uv_loop_t *loop)

Returns loop->data.

Added in version 1.19.0.

🎀 void uv_loop_set_data(uv_loop_t *loop, void *data)

Sets loop->data to data.

Added in version 1.19.0.

---

💜 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, and all the API functions defined here work with any handle type. Universal icon behavior ✨

🦋 Important: libuv handles are not movable. Pointers to handle structures passed to functions must remain valid for the duration of the requested operation. So take care when you're using stack allocated handles — do not let them go out of scope on you 😭

🌸 Data types 🌸

• type uv_handle_t — the base libuv handle type.
• enum uv_handle_type — the kind of the libuv handle 👑

typedef enum {
  UV_UNKNOWN_HANDLE = 0,
  UV_ASYNC,
  UV_CHECK,
  UV_FS_EVENT,
  UV_FS_POLL,
  UV_HANDLE,
  UV_IDLE,
  UV_NAMED_PIPE,
  UV_POLL,
  UV_PREPARE,
  UV_PROCESS,
  UV_STREAM,
  UV_TCP,
  UV_TIMER,
  UV_TTY,
  UV_UDP,
  UV_SIGNAL,
  UV_FILE,
  UV_HANDLE_TYPE_MAX
} uv_handle_type;

• type uv_any_handle — union of all handle types.
• typedef void (*uv_alloc_cb)(uv_handle_t *handle, size_t suggested_size, uv_buf_t *buf) — type definition for the callback you pass to uv_read_start() and uv_udp_recv_start(). You, the user, must allocate memory and fill the supplied uv_buf_t structure 💅 If NULL is assigned as the buffer's base or 0 as its length, a UV_ENOBUFS error gets triggered in the uv_udp_recv_cb or the uv_read_cb callback 😭

Each buffer is used only once, and you're responsible for freeing it in the uv_udp_recv_cb or the uv_read_cb callback. No leaks, bestie 🫶

A suggested size is provided (65536 at the moment in most cases), but it's literally just an indication — not related in any way to the pending data to be read. You're free to allocate however much memory you decide.

For example, apps with custom allocation schemes — freelists, allocation pools, slab based allocators — might decide to use a different size that matches the memory chunks they already have. Smart, honestly ✨

Example:

static void my_alloc_cb(uv_handle_t* handle, size_t suggested_size, uv_buf_t* buf) {
  buf->base = malloc(suggested_size);
  buf->len = suggested_size;
}

• typedef void (*uv_close_cb)(uv_handle_t *handle) — type definition for the callback passed to uv_close().

🦋 Public members 🦋

• uv_loop_t *uv_handle_t.loop — pointer to the uv_loop_t the handle is running on. Readonly 🔒
• uv_handle_type uv_handle_t.type — the uv_handle_type, indicating the type of the underlying handle. Readonly 🔒
• void *uv_handle_t.data — space for user-defined arbitrary data. libuv does not use this field. It's all yours, go wild 🎀

API ✨

• UV_HANDLE_TYPE_MAP(iter_macro) — a macro that expands into a whole lil series of invocations of iter_macro, one per handle type 🫶. Each time it's called, iter_macro gets two arguments: the name of the uv_handle_type element without the UV_ prefix, and the name of the matching structure type without the uv_ prefix and _t suffix. iykyk 🌸
• int uv_is_active(const uv_handle_t *handle) — returns non-zero if the handle is active, zero if it's inactive. And what "active" even means? bestie it depends on the handle type 💅:
  • 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's 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, and this one's iconic: 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 👑

• int uv_is_closing(const uv_handle_t *handle) — returns non-zero if the handle is closing or closed, zero otherwise.

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

• void uv_close(uv_handle_t *handle, uv_close_cb close_cb) — requests the handle to be closed. close_cb gets called asynchronously after this call. This MUST be called on each handle before memory is released 😭. Moreover — and this is the part people fumble — the memory can only be released in close_cb or after it has returned.

Handles that wrap file descriptors are closed immediately, but close_cb will still be deferred to the next iteration of the event loop. That's literally giving 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.

close_cb can be NULL in cases where no cleanup or deallocation is necessary 💜.

• void uv_ref(uv_handle_t *handle) — references 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 ✨
• void uv_unref(uv_handle_t *handle) — unreferences 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 ✨
• int uv_has_ref(const uv_handle_t *handle) — returns non-zero if the handle is referenced, zero otherwise. See Reference counting ✨
• size_t uv_handle_size(uv_handle_type type) — returns the size of the given handle type. Useful for FFI binding writers who don't want to know the structure layout 🧚

---

Miscellaneous API functions 🌈

The following API functions take a uv_handle_t argument, but they work just for some handle types. slay, but selectively 💅

• int uv_send_buffer_size(uv_handle_t *handle, int *value) — gets or sets the size of the send buffer that the operating system uses for the socket.

If *value == 0, then it will set *value to the current send buffer size. If *value > 0 then it will use *value to set the new send buffer size.

On success, zero is returned. On error, a negative result is returned.

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. yes, double. no, that's not a typo, that's just Linux being Linux 💀

• int uv_recv_buffer_size(uv_handle_t *handle, int *value) — gets or sets the size of the receive buffer that the operating system uses for the socket.

If *value == 0, then it will set *value to the current receive buffer size. If *value > 0 then it will use *value to set the new receive buffer size.

On success, zero is returned. On error, a negative result is returned.

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. same deal, bestie 🍓

• int uv_fileno(const uv_handle_t *handle, uv_os_fd_t *fd) — 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. like, do not touch, the vibes are load-bearing 😭

• uv_loop_t *uv_handle_get_loop(const uv_handle_t *handle) — returns handle->loop.

Added in version 1.19.0.

• void *uv_handle_get_data(const uv_handle_t *handle) — returns handle->data.

Added in version 1.19.0.

• void uv_handle_set_data(uv_handle_t *handle, void *data) — sets handle->data to data.

Added in version 1.19.0.

• uv_handle_type uv_handle_get_type(const uv_handle_t *handle) — returns handle->type.

Added in version 1.19.0.

• const char *uv_handle_type_name(uv_handle_type type) — returns the name for the equivalent struct for a given handle type, e.g. "pipe" (as in uv_pipe_t) for UV_NAMED_PIPE. 🦋

If no such handle type exists, this returns NULL.

Added in version 1.19.0.

---

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(). main character energy: you decide when the loop leaves the party 👑

A handle can be referenced or unreferenced, and the refcounting scheme doesn't use a counter, so both operations are idempotent. no cap, there's no number going up and down 🎀

All handles are referenced when active by default. See uv_is_active() for a more detailed explanation on what being active involves.

---

uv_req_t — Base request 🌟

uv_req_t is the base type for all libuv request types.

Structures are aligned so that any libuv request can be cast to uv_req_t. All API functions defined here work with any request type. it's giving "universal base class" and honestly? iconic 💅

Data types ✨

• type uv_req_t — the base libuv request structure.
• type uv_any_req — union of all request types.
• enum uv_req_type — the kind of the libuv request. 🎀

typedef enum {
    UV_UNKNOWN_REQ = 0,
    UV_REQ,
    UV_CONNECT,
    UV_WRITE,
    UV_SHUTDOWN,
    UV_UDP_SEND,
    UV_FS,
    UV_WORK,
    UV_GETADDRINFO,
    UV_GETNAMEINFO,
    UV_REQ_TYPE_MAX,
} uv_req_type;

Public members 🫶

• void *uv_req_t.data — space for user-defined arbitrary data. libuv does not use this field. it's yours, bestie, decorate it however you want 🌸
• uv_req_type uv_req_t.type — the uv_req_type, indicating the type of the request. Readonly. hands off 🔒

API 💖

• UV_REQ_TYPE_MAP(iter_macro) — macro that expands to a series of invocations of iter_macro for each of the request types. iter_macro is invoked with two arguments: the name of the uv_req_type element without the UV_ prefix, and the name of the corresponding structure type without the uv_ prefix and _t suffix. ✨
• int uv_cancel(uv_req_t *req) — cancel a pending request. Fails if the request is executing or has finished executing. Write requests are an exception though 👀: cancellation of a write that is already in progress will attempt to interrupt it (the callback may report a partial write), and cancellation of an already-completed write is a successful no-op.

Returns 0 on success, or an error code < 0 on failure.

Only cancellation of uv_write_t, uv_fs_t, uv_getaddrinfo_t, uv_getnameinfo_t, uv_random_t and uv_work_t requests is currently supported.

Cancelled requests have their callbacks invoked some time in the future. It's not safe to free the memory associated with the request until the callback is called. like, do not free yet, the callback hasn't shown up 😭

Here's how cancellation is reported to the callback:

• A uv_fs_t request has its req->result field set to UV_ECANCELED.
• A uv_work_t, uv_getaddrinfo_t, uv_getnameinfo_t or uv_random_t request has its callback invoked with status == UV_ECANCELED.
• A uv_write_t request has its callback invoked with status == UV_ECANCELED. Use uv_write_nwritten() from the callback to determine how many bytes were written before cancellation. Fully cancelled writes (where no bytes were written) may have their callbacks called out of order with respect to other writes on the same stream. Note that cancelled writes may still succeed or fail with other errors if the kernel finished processing the write before the cancellation took effect. the kernel said "too late bestie" 💀

• size_t uv_req_size(uv_req_type type) — returns the size of the given request type. Useful for FFI binding writers who don't want to know the structure layout 🧚
• void *uv_req_get_data(const uv_req_t *req) — returns req->data.

Added in version 1.19.0.

• void uv_req_set_data(uv_req_t *req, void *data) — sets req->data to data.

Added in version 1.19.0. ✨

---

🎀 uv_req_get_type

uv_req_type uv_req_get_type(const uv_req_t *req)

Bestie this one is so simple it's basically a vibe check — it just hands you back req->type. That's it. That's the whole function. 💅

Added in version 1.19.0.

🎀 uv_req_type_name

const char *uv_req_type_name(uv_req_type type)

Gives you the name for the equivalent struct for a given request type. Like, for UV_CONNECT you get "connect" (as in uv_connect_t — see what they did there? 🦋).

And if no such request type exists? It returns NULL. No cap, no drama, just NULL. 🙈

Added in version 1.19.0.

---

🕐 uv_timer_t — the Timer handle

Okay so timer handles are literally the "call me later" of libuv — they schedule callbacks to be called in the future. ⏰✨

Timers come in two flavors: single-shot or repeating. Repeating timers do not adjust for overhead but are rearmed relative to the event loop's idea of "now".

Libuv updates its idea of "now" right before executing timer callbacks, and right after waking up from waiting for I/O. See also uv_update_time().

Example that eats: a repeating timer with a 50 ms interval whose callback takes 17 ms to complete, runs again 33 ms later. If other tasks take longer than 33 ms, the timer callback runs as soon as possible. 👑

🧁 Data types

• type uv_timer_t — Timer handle type.
• typedef void (*uv_timer_cb)(uv_timer_t *handle) — Type definition for callback passed to uv_timer_start().

🧁 Public members

N/A 🫥

See also: the uv_handle_t members also apply.

🧁 API

• int uv_timer_init(uv_loop_t *loop, uv_timer_t *handle) — Initialize the handle. Baby's first step. 🌱
• int uv_timer_start(uv_timer_t *handle, uv_timer_cb cb, uint64_t timeout, uint64_t repeat) — 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.

Note: Does not update the event loop's concept of "now". See uv_update_time() for more information. Also — if the timer is already active, it is simply updated. No restart drama, it just updates. 💅

• int uv_timer_stop(uv_timer_t *handle) — Stop the timer, the callback will not be called anymore. Ghosted. 👻
• int uv_timer_again(uv_timer_t *handle) — 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 returns UV_EINVAL. 😭
• void uv_timer_set_repeat(uv_timer_t *handle, uint64_t repeat) — 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.

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. Timing is everything, bestie. ⏳

• uint64_t uv_timer_get_repeat(const uv_timer_t *handle) — Get the timer repeat value.
• uint64_t uv_timer_get_due_in(const uv_timer_t *handle) — Get the timer due value or 0 if it has expired. The time is relative to uv_now(). 🌸

Added in version 1.40.0.

See also: the uv_handle_t API functions also apply.

---

🌅 uv_prepare_t — the Prepare handle

Prepare handles will run the given callback once per loop iteration, right before polling for i/o. Think of it as the "get ready, we're about to go look for work" moment. 🧚

🧁 Data types

• type uv_prepare_t — Prepare handle type.
• typedef void (*uv_prepare_cb)(uv_prepare_t *handle) — Type definition for callback passed to uv_prepare_start().

🧁 Public members

N/A 🫥

See also: the uv_handle_t members also apply.

🧁 API

• int uv_prepare_init(uv_loop_t *loop, uv_prepare_t *prepare) — Initialize the handle. This function always succeeds.

Returns: 0 ✅

• int uv_prepare_start(uv_prepare_t *prepare, uv_prepare_cb cb) — Start the handle with the given callback. This function always succeeds, except when cb is NULL.

Returns: 0 on success, or UV_EINVAL when cb == NULL.

• int uv_prepare_stop(uv_prepare_t *prepare) — Stop the handle, the callback will no longer be called. This function always succeeds.

Returns: 0 ✅

See also: the uv_handle_t API functions also apply.

---

✅ uv_check_t — the Check handle

Check handles will run the given callback once per loop iteration, right after polling for i/o. Prepare's sibling, basically — same energy, opposite side of the poll. 💖

🧁 Data types

• type uv_check_t — Check handle type.
• typedef void (*uv_check_cb)(uv_check_t *handle) — Type definition for callback passed to uv_check_start().

🧁 Public members

N/A 🫥

See also: the uv_handle_t members also apply.

🧁 API

• int uv_check_init(uv_loop_t *loop, uv_check_t *check) — Initialize the handle. This function always succeeds.

Returns: 0 ✅

• int uv_check_start(uv_check_t *check, uv_check_cb cb) — Start the handle with the given callback. This function always succeeds, except when cb is NULL.

Returns: 0 on success, or UV_EINVAL when cb == NULL.

• int uv_check_stop(uv_check_t *check) — Stop the handle, the callback will no longer be called. This function always succeeds.

Returns: 0 ✅

See also: the uv_handle_t API functions also apply.

---

💤 uv_idle_t — the Idle handle

Idle handles will run the given callback once per loop iteration, right before the uv_prepare_t handles. Early bird energy. 🐦

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". The name is lying to you, bestie. It's giving misleading branding. 💀

🧁 Data types

• type uv_idle_t — Idle handle type.
• typedef void (*uv_idle_cb)(uv_idle_t *handle) — Type definition for callback passed to uv_idle_start().

🧁 Public members

N/A 🫥

See also: the uv_handle_t members also apply.

🧁 API

• int uv_idle_init(uv_loop_t *loop, uv_idle_t *idle) — Initialize the handle. This function always succeeds.

Returns: 0 ✅

• int uv_idle_start(uv_idle_t *idle, uv_idle_cb cb) — Start the handle with the given callback. This function always succeeds, except when cb is NULL.

Returns: 0 on success, or UV_EINVAL when cb == NULL.

• int uv_idle_stop(uv_idle_t *idle) — Stop the handle, the callback will no longer be called. This function always succeeds.

Returns: 0 ✅

See also: the uv_handle_t API functions also apply.

---

📣 uv_async_t — the Async handle

Async handles allow the user to "wakeup" the event loop and get a callback called from another thread. Cross-thread communication, but make it cute. 🦋

Note: uv_async_send() and the uv_async_cb invocation are sequentially consistent (seq_cst) operations for a given async handle: all memory accesses (reads and writes) made before uv_async_send() are visible to that callback.

Warning: libuv will coalesce calls to uv_async_send() — 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. However, since it is sequentially consistent, the values read or written in that callback will always be the same (or newer) as those read or written by the other thread. 🔥

Changed in version 1.53.0: uv_async_send() and uv_async_cb are sequentially consistent. Prior to this version, any case where libuv might coalesce calls probably requires a full seq_cst fence before it for correctness.

🧁 Data types

• type uv_async_t — Async handle type.
• typedef void (*uv_async_cb)(uv_async_t *handle) — Type definition for callback passed to uv_async_init().

🧁 Public members

N/A 🫥

See also: the uv_handle_t members also apply.

🧁 API

• int uv_async_init(uv_loop_t *loop, uv_async_t *async, uv_async_cb async_cb) — Initialize the handle. A NULL callback is allowed.

Returns: 0 on success, or an error code < 0 on failure.

Note: Unlike other handle initialization functions, it immediately starts the handle. No waiting around, it's already on main character energy the second it exists. ⭐

• int uv_async_send(uv_async_t *async) — Wake up the event loop and call the async handle's callback.

Returns: 0 on success, or an error code < 0 on failure.

Note: It's safe to call this function from any thread. The callback will be called on the loop thread.

Note: uv_async_send() is async-signal-safe. It's safe to call this function from a signal handler. 🫶

Note: This is a full memory fence with respect to other calls and callbacks using this same async handle, and so it will order all operations around this call and the corresponding callback on the sending thread and receiving thread. Memory-ordering queen. 👑

See also: the uv_handle_t API functions also apply.

---

👀 uv_poll_t — the Poll handle

Poll handles are used to watch file descriptors for readability, writability and disconnection — similar to the purpose of poll(2). Basically libuv's little spy on your file descriptors. 🕵️‍♀️

The whole point of poll handles, bestie, is so you can plug in external libraries that rely on the event loop to tell them when a socket's status changes — think c-ares or libssh2. That's the gig. Using uv_poll_t for literally anything else? Not recommended, ngl. uv_tcp_t, uv_udp_t, etc. give you an implementation that's faster and more scalable than anything you can pull off with uv_poll_t, especially on Windows. 💅

Okay and here's a lil reality check: poll handles might occasionally signal that a file descriptor is readable or writable even when it so isn't. So the user should always be prepared to handle EAGAIN or equivalent when it tries to read from or write to the fd. Don't get caught lacking. 😭

It is not okay to have multiple active poll handles for the same socket — that can cause libuv to busyloop or otherwise malfunction. One handle, one socket, periodt.

Also, the user should not close a file descriptor while it is being polled by an active poll handle. Like, this can cause the handle to report an error, but it might also start polling another socket (chaos, no cap). The fd can however 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.

Note: On AIX, watching for disconnection is not supported. 🙈

---

Data types

• type uv_poll_t — Poll handle type. That's the whole vibe.
• typedef void (*uv_poll_cb)(uv_poll_t *handle, int status, int events) — Type definition for the callback passed to uv_poll_start().
• enum uv_poll_event — Poll event types:

enum uv_poll_event {
    UV_READABLE = 1,
    UV_WRITABLE = 2,
    UV_DISCONNECT = 4,
    UV_PRIORITIZED = 8
};

Public members

N/A. Nothing here, bestie — but see also: the uv_handle_t members also apply. 🫶

API

• int uv_poll_init(uv_loop_t *loop, uv_poll_t *handle, int fd) — Initialize the handle using a file descriptor.

Changed in version 1.2.2: the file descriptor is set to non-blocking mode.

• int uv_poll_init_socket(uv_loop_t *loop, uv_poll_t *handle, uv_os_sock_t socket) — Initialize the handle using a socket descriptor. On Unix this is identical to uv_poll_init(). On Windows it takes a SOCKET handle.

Changed in version 1.2.2: the socket is set to non-blocking mode.

• int uv_poll_start(uv_poll_t *handle, int events, uv_poll_cb cb) — Starts polling the file descriptor. events is a bitmask made up of UV_READABLE, UV_WRITABLE, UV_PRIORITIZED and UV_DISCONNECT. 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 UV_PRIORITIZED event is used to watch for sysfs interrupts or TCP out-of-band messages. 👑

The UV_DISCONNECT event is optional in the sense that it may not be reported and the user is free to ignore it, but it can help optimize the shutdown path because an extra read or write call might be avoided.

If an error happens while polling, status will be < 0 and corresponds with one of the UV_E* error codes (see Error handling). 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. If status == UV_EBADF polling is discontinued for the file handle and no further events will be reported. The user should then call uv_close() on the handle. 💀

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.

Note: Though UV_DISCONNECT can be set, it is unsupported on AIX and as such will not be set on the events field in the callback.

Note: If one of the events UV_READABLE or UV_WRITABLE are set, the callback will be called again, as long as the given fd/socket remains readable or writable accordingly. Particularly in each of the following scenarios: - The callback has been called because the socket became readable/writable and the callback did not conduct a read/write on this socket at all. - The callback committed a read on the socket, and has not read all the available data (when UV_READABLE is set). - The callback committed a write on the socket, but it remained writable afterwards (when UV_WRITABLE is set). - The socket has already became readable/writable before calling uv_poll_start() on a poll handle associated with this socket, and since then the state of the socket did not changed. In all of the above listed scenarios, the socket remains readable or writable and hence the callback will be called again (depending on the events set in the bitmask). This behaviour is known as level triggering. ⭐

Changed in version 1.9.0: Added the UV_DISCONNECT event. Changed in version 1.14.0: Added the UV_PRIORITIZED event.

• int uv_poll_stop(uv_poll_t *poll) — Stop polling the file descriptor, the callback will no longer be called.

Note: Calling uv_poll_stop() is effective immediately: any pending callback is also canceled, even if the socket state change notification was already pending. 🧚

See also: the uv_handle_t API functions also apply.

---

🌸 uv_signal_t --- Signal handle 🌸

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

Windows notes

Reception of some signals is emulated:

• 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. When a libuv app is running under a console emulator, or when a 32-bit libuv app is running on 64-bit system, SIGWINCH will be emulated. In such cases SIGWINCH signals may not always be delivered in a timely manner. For a writable uv_tty_t handle libuv will only detect size changes when the cursor is moved. When a readable uv_tty_t handle is used, resizing of the console buffer will be detected only if the handle is in raw mode and is being read.
• 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.

Changed in version 1.15.0: SIGWINCH support on Windows was improved. Changed in version 1.31.0: 32-bit libuv SIGWINCH support on 64-bit Windows was rolled back to old implementation.

Unix notes

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

Data types

• type uv_signal_t — Signal handle type.
• typedef void (*uv_signal_cb)(uv_signal_t *handle, int signum) — Type definition for the callback passed to uv_signal_start().

Public members

• int uv_signal_t.signum — Signal being monitored by this handle. Readonly.

See also: the uv_handle_t members also apply. 🫶

API

• int uv_signal_init(uv_loop_t *loop, uv_signal_t *signal) — Initialize the handle.
• int uv_signal_start(uv_signal_t *signal, uv_signal_cb cb, int signum) — Start the handle with the given callback, watching for the given signal.
• int uv_signal_start_oneshot(uv_signal_t *signal, uv_signal_cb cb, int signum) — Same functionality as uv_signal_start() but the signal handler is reset the moment the signal is received.

Added in version 1.12.0.

• int uv_signal_stop(uv_signal_t *signal) — Stop the handle, the callback will no longer be called.

See also: the uv_handle_t API functions also apply.

---

🦋 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. Main character energy fr fr.

Data types

• type uv_process_t — Process handle type.
• type uv_process_options_t — Options for spawning the process (passed to uv_spawn()).

typedef struct uv_process_options_s {
    uv_exit_cb exit_cb;
    const char* file;
    char** args;
    char** env;
    const char* cwd;
    unsigned int flags;
    int stdio_count;
    uv_stdio_container_t* stdio;
    uv_uid_t uid;
    uv_gid_t gid;
} uv_process_options_t;

• typedef void (*uv_exit_cb)(uv_process_t*, int64_t exit_status, int term_signal) — Type definition for the callback passed in uv_process_options_t which will indicate the exit status and the signal that caused the process to terminate, if any.
• enum uv_process_flags — Flags to be set on the flags field of uv_process_options_t. ✨

🎀 enum uv_process_flags — the little switchboard for uv_spawn()

okay so before we talk about spawning anything, here's the whole flag menu, copied exactly, no cap:

enum uv_process_flags {
    /*
    * Set the child process' user id.
    */
    UV_PROCESS_SETUID = (1 << 0),
    /*
    * Set the child process' group id.
    */
    UV_PROCESS_SETGID = (1 << 1),
    /*
    * 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.
    */
    UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2),
    /*
    * 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.
    */
    UV_PROCESS_DETACHED = (1 << 3),
    /*
    * Hide the subprocess window that would normally be created. This option is
    * only meaningful on Windows systems. On Unix it is silently ignored.
    */
    UV_PROCESS_WINDOWS_HIDE = (1 << 4),
    /*
    * Hide the subprocess console window that would normally be created. This
    * option is only meaningful on Windows systems. On Unix it is silently
    * ignored.
    */
    UV_PROCESS_WINDOWS_HIDE_CONSOLE = (1 << 5),
    /*
    * Hide the subprocess GUI window that would normally be created. This
    * option is only meaningful on Windows systems. On Unix it is silently
    * ignored.
    */
    UV_PROCESS_WINDOWS_HIDE_GUI = (1 << 6),
    /*
     * On Windows, if the path to the program to execute, specified in
     * uv_process_options_t's file field, has a directory component,
     * search for the exact file name before trying variants with
     * extensions like '.exe' or '.cmd'.
     */
    UV_PROCESS_WINDOWS_FILE_PATH_EXACT_NAME = (1 << 7)
};

and here's what each one is giving, one by one 🫶

• UV_PROCESS_SETUID — sets the child process' user id.
• UV_PROCESS_SETGID — sets the child process' group id.
• UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS — do not wrap any arguments in quotes, and don't do any other escaping, when the argument list gets converted into a command line string. this one is only meaningful on Windows; on Unix it's silently ignored.
• UV_PROCESS_DETACHED — spawns the child in a detached state, which makes it a process group leader, and effectively lets the child keep running after the parent exits. ⚠️ but heads up: 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.
• UV_PROCESS_WINDOWS_HIDE — hides the subprocess window that would normally be created. Windows-only; on Unix, silently ignored.
• UV_PROCESS_WINDOWS_HIDE_CONSOLE — hides the subprocess console window that would normally be created. Windows-only; on Unix, silently ignored.
• UV_PROCESS_WINDOWS_HIDE_GUI — hides the subprocess GUI window that would normally be created. Windows-only; on Unix, silently ignored.
• UV_PROCESS_WINDOWS_FILE_PATH_EXACT_NAME — on Windows, if the path to the program to execute (that's the file field of uv_process_options_t) has a directory component, it searches for the exact file name before trying variants with extensions like '.exe' or '.cmd'. 🎯

---

🦋 uv_stdio_container_t

literally just: the container for each stdio handle or fd that gets passed to a child process.

typedef struct uv_stdio_container_s {
    uv_stdio_flags flags;
    union {
        uv_stream_t* stream;
        int fd;
    } data;
} uv_stdio_container_t;

🌈 enum uv_stdio_flags

these ones specify how a stdio should be transmitted to the child process. iconique behaviour:

typedef enum {
    /*
     * The following four options are mutually-exclusive, and define
     * the operation to perform for the corresponding file descriptor
     * in the child process:
     */

    /*
     * No file descriptor will be provided (or redirected to
     * `/dev/null` if it is fd 0, 1 or 2).
     */
    UV_IGNORE = 0x00,

    /*
     * Open a new pipe into `data.stream`, per the flags below. The
     * `data.stream` field must point to a uv_pipe_t object that has
     * been initialized with `uv_pipe_init(loop, data.stream, ipc);`,
     * but not yet opened or connected.
    /*
    UV_CREATE_PIPE = 0x01,

    /*
     * The child process will be given a duplicate of the parent's
     * file descriptor given by `data.fd`.
     */
    UV_INHERIT_FD = 0x02,

    /*
     * The child process will be given a duplicate of the parent's
     * file descriptor being used by the stream handle given by
     * `data.stream`.
     */
    UV_INHERIT_STREAM = 0x04,

    /*
     * When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE
     * determine the direction of flow, from the child process' perspective. Both
     * flags may be specified to create a duplex data stream.
     */
    UV_READABLE_PIPE = 0x10,
    UV_WRITABLE_PIPE = 0x20,

    /*
     * When UV_CREATE_PIPE is specified, specifying UV_NONBLOCK_PIPE opens the
     * handle in non-blocking mode in the child. This may cause loss of data,
     * if the child is not designed to handle to encounter this mode,
     * but can also be significantly more efficient.
     */
    UV_NONBLOCK_PIPE = 0x40
} uv_stdio_flags;

ngl bestie, that comment block above UV_CREATE_PIPE closes with /* instead of */ — that's literally how it's written on the page and i'm not touching it 🙈 who am i to edit the sacred text

and the rundown, flag by flag 💅

• the first four are mutually exclusive, and they define the operation to perform for the corresponding file descriptor in the child process:
• UV_IGNORE = 0x00 — no file descriptor will be provided (or it gets redirected to /dev/null if it's fd 0, 1 or 2).
• UV_CREATE_PIPE = 0x01 — opens a new pipe into data.stream, per the flags below. the data.stream field must point to a uv_pipe_t object that's been initialized with uv_pipe_init(loop, data.stream, ipc); but not yet opened or connected ✨
• UV_INHERIT_FD = 0x02 — the child process gets a duplicate of the parent's file descriptor given by data.fd.
• UV_INHERIT_STREAM = 0x04 — the child process gets a duplicate of the parent's file descriptor being used by the stream handle given by data.stream.
• UV_READABLE_PIPE = 0x10, UV_WRITABLE_PIPE = 0x20 — when UV_CREATE_PIPE is specified, these determine the direction of flow, from the child process' perspective. both flags can be specified together to create a duplex data stream 🌀
• UV_NONBLOCK_PIPE = 0x40 — when UV_CREATE_PIPE is specified, this opens the handle in non-blocking mode in the child. ⚠️ this may cause loss of data if the child isn't designed to handle encountering this mode — but it can also be significantly more efficient. risk vs reward, your call 💀

---

👑 Public members

• int uv_process_t.pid — the PID of the spawned process. it's set after calling uv_spawn() and it retains that value even after the process exits. important vibe check: the value is only unique while the process is alive — after exit, another process may be reassigned the same PID.
• Note: the uv_handle_t members also apply.
• uv_exit_cb uv_process_options_t.exit_cb — callback called after the process exits. 🫶
• const char *uv_process_options_t.file — path pointing to the program to be executed.
• char **uv_process_options_t.args — command line arguments. args[0] should be the path to the program. on Windows this uses CreateProcess, which concatenates the arguments into a string — that can cause some strange errors 😭. see the UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS flag on uv_process_flags.
• char **uv_process_options_t.env — environment for the new process. if NULL, the parent's environment is used.
• const char *uv_process_options_t.cwd — current working directory for the subprocess.
• unsigned int uv_process_options_t.flags — various flags that control how uv_spawn() behaves. see uv_process_flags.
• int uv_process_options_t.stdio_count
• uv_stdio_container_t *uv_process_options_t.stdio — the stdio field points to an array of uv_stdio_container_t structs that describe the file descriptors that will be made available to the child process. the convention is that stdio[0] points to stdin, fd 1 is used for stdout, and fd 2 is stderr.
• Note: on Windows, file descriptors greater than 2 are available to the child process only if the child process uses the MSVCRT runtime.
• uv_uid_t uv_process_options_t.uid
• uv_gid_t uv_process_options_t.gid — libuv can change the child process' user/group id. this happens only when the appropriate bits are set in the flags fields.
• Note: this is not supported on Windows — uv_spawn() will fail and set the error to UV_ENOTSUP. 💀
• uv_stdio_flags uv_stdio_container_t.flags — flags specifying how the stdio container should be passed to the child.
• union [anonymous] uv_stdio_container_t.data — union containing either the stream or fd to be passed on to the child process.

---

✨ API ✨

🧚 void uv_disable_stdio_inheritance(void)

disables inheritance for file descriptors / handles that this process inherited from its parent. the effect? child processes spawned by this process don't accidentally inherit these handles. not me preventing generational trauma 💅

it's 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's 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.

🌸 int uv_spawn(...)

int uv_spawn(uv_loop_t *loop, uv_process_t *handle, const uv_process_options_t *options)

initializes the process handle and starts the process. if the process is successfully spawned, this function returns 0. otherwise, the negative error code corresponding to the reason it couldn't spawn is returned. and here's the part everyone forgets: either way — success or failure — you must eventually call uv_close() to close the handle again before freeing the memory of the handle. unlike the other init functions in libuv. 👀 like, yes, even the fail case, bestie.

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.

Warning: on unix, if the process has not yet exited when you call uv_close, you will create a zombie that libuv cannot reap. you are responsible for calling waitpid later. this is not relevant on Windows. 🧟‍♀️

Changed in version 1.24.0: added UV_PROCESS_WINDOWS_HIDE_CONSOLE and UV_PROCESS_WINDOWS_HIDE_GUI flags.

Changed in version 1.48.0: added the UV_PROCESS_WINDOWS_FILE_PATH_EXACT_NAME flag.

🔥 int uv_process_kill(uv_process_t *handle, int signum)

sends the specified signal to the given process handle. check the documentation on uv_signal_t — Signal handle for signal support, specially on Windows.

if the specified process is already dead, this will not kill a different process which happened to reuse the same pid. by contrast, uv_kill may kill an arbitrary other process if you use a cached value of uv_process_get_pid(). 😭 that's the whole difference and it matters.

⭐ int uv_kill(int pid, int signum)

sends the specified signal to the given PID. check the documentation on uv_signal_t — Signal handle for signal support, specially on Windows.

🎀 uv_pid_t uv_process_get_pid(const uv_process_t *handle)

returns handle->pid. that's it, that's the function, she's simple and she slays 🫶

Added in version 1.19.0.

---

okay and we're still going — this is genuinely the middle of the process vibes, so keep scrolling bestie, there's more where that came from 💖

✨ See also: the uv_handle_t API functions also apply to all of this, bestie. Same family, same rules. 🫶

🌊 uv_stream_t — Stream handle

Okay so picture a duplex communication channel — both directions, sending and receiving, no cap. That's what stream handles abstract. uv_stream_t is an abstract type, which is fancy-speak for "not the whole story yet" — libuv actually ships three real implementations of it: uv_tcp_t, uv_pipe_t, and uv_tty_t. Three flavors, one vibe. 💅

🧬 Data types

• type uv_stream_t — the stream handle type itself. The blueprint. 🎀
• type uv_connect_t — the connect request type.
• type uv_shutdown_t — the shutdown request type.
• type uv_write_t — the write request type. And listen, careful attention must be paid when you reuse objects of this type. When a stream is in non-blocking mode, write requests sent with uv_write get queued up, and reusing objects at that point is undefined behaviour — like, genuinely do-not-pass-go territory 😭. It is safe to reuse the uv_write_t object only after the callback passed to uv_write is fired. That's the finish line. Not before. Periodt.
• typedef void (*uv_read_cb)(uv_stream_t *stream, ssize_t nread, const uv_buf_t *buf) — called when data was read on a stream. Here's the deal on nread: it's > 0 if there's data available, or < 0 on error. When we've hit EOF, nread gets set to UV_EOF. And when nread < 0, the buf parameter might not point to a valid buffer at all — in that case buf.len and buf.base are both set to 0. ⭐

Note: nread might be 0, and that does not indicate an error or EOF, okay? It's equivalent to EAGAIN or EWOULDBLOCK under read(2). Don't panic. 🙈

The callee is responsible for stopping/closing the stream when an error happens, by calling uv_read_stop() or uv_close(). Trying to read from the stream again after that is undefined. And the callee is also responsible for freeing the buffer — libuv does not reuse it. That buffer may be a null buffer (where buf->base == NULL and buf->len == 0) on error. 😭

• typedef void (*uv_write_cb)(uv_write_t *req, int status) — called after data was written on a stream. status will be 0 in case of success, < 0 otherwise. Slay. ✨
• typedef void (*uv_connect_cb)(uv_connect_t *req, int status) — called after a connection started by uv_connect() is done. status is 0 on success, < 0 otherwise.
• typedef void (*uv_shutdown_cb)(uv_shutdown_t *req, int status) — called after a shutdown request has been completed. Same status deal: 0 good, < 0 not good.
• typedef void (*uv_connection_cb)(uv_stream_t *server, int status) — called when a stream server has received an incoming connection. You (the user) can accept that connection by calling uv_accept(). status is 0 on success, < 0 otherwise. 🦋

👀 Public members

• size_t uv_stream_t.write_queue_size — contains the amount of queued bytes waiting to be sent. Readonly, so don't even think about writing to it. 👑
• uv_stream_t *uv_connect_t.handle — pointer to the stream where this connection request is running.
• uv_stream_t *uv_shutdown_t.handle — pointer to the stream where this shutdown request is running.
• uv_stream_t *uv_write_t.handle — pointer to the stream where this write request is running.
• uv_stream_t *uv_write_t.send_handle — pointer to the stream being sent using this write request.

✨ See also: the uv_handle_t members also apply. The whole handle squad shares its stuff, iykyk.

🛠 API

• int uv_shutdown(uv_shutdown_t *req, uv_stream_t *handle, uv_shutdown_cb cb) — shuts down the outgoing (write) side of a duplex stream. It waits for pending write requests to complete first, because we're polite. The handle should refer to an initialized stream, and req should be an uninitialized shutdown request struct. cb is called after shutdown is complete. 🎀
• int uv_listen(uv_stream_t *stream, int backlog, uv_connection_cb cb) — 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 uv_connection_cb callback gets called. 🔥
• int uv_accept(uv_stream_t *server, uv_stream_t *client) — this call is used in conjunction with uv_listen() to accept incoming connections. Call it after receiving a uv_connection_cb to accept the connection. Before calling this function the client handle must be initialized. A < 0 return value indicates an error.

When the uv_connection_cb 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. So the suggestion is: only call this function once per uv_connection_cb call. One and done. 💅

Note: server and client must be handles running on the same loop. No mixing loops, bestie, that's chaos. 🌈

• int uv_read_start(uv_stream_t *stream, uv_alloc_cb alloc_cb, uv_read_cb read_cb) — read data from an incoming stream. The uv_read_cb callback will be made several times until there's no more data to read or uv_read_stop() is called. 🌸

Changed in version 1.38.0: uv_read_start() now consistently returns UV_EALREADY when called twice, and UV_EINVAL when the stream is closing. With older libuv versions, it returns UV_EALREADY on Windows but not UNIX, and UV_EINVAL on UNIX but not Windows. (Iconic cross-platform chaos, we fixed it. 🫶)

• int uv_read_stop(uv_stream_t*) — stop reading data from the stream. The uv_read_cb callback will no longer be called.

This function is idempotent and may be safely called on a stopped stream. It will always succeed — hence, checking its return value is unnecessary. A non-zero return indicates that finishing releasing resources may be pending on the next input event on that TTY on Windows, and does not indicate failure. Don't read into it. 💀

• int uv_write(uv_write_t *req, uv_stream_t *handle, const uv_buf_t bufs[], unsigned int nbufs, uv_write_cb cb) — write data to a stream. Buffers are written in order, which is the whole point. Behold, an example:

void cb(uv_write_t* req, int status) {
    /* Logic which handles the write result */
}

uv_buf_t a[] = {
    { .base = "1", .len = 1 },
    { .base = "2", .len = 1 }
};

uv_buf_t b[] = {
    { .base = "3", .len = 1 },
    { .base = "4", .len = 1 }
};

uv_write_t req1;
uv_write_t req2;

/* writes "1234" */
uv_write(&req1, stream, a, 2, cb);
uv_write(&req2, stream, b, 2, cb);

Note: the memory pointed to by the buffers must remain valid until the callback gets called. This also holds for uv_write2(). Do not free it early, I'm begging. 😭

• int uv_write2(uv_write_t *req, uv_stream_t *handle, const uv_buf_t bufs[], unsigned int nbufs, uv_stream_t *send_handle, uv_write_cb cb) — the extended write function for sending handles over a pipe. The pipe must be initialized with ipc == 1. 🦋

Note: send_handle must be a TCP, pipe and UDP handle on Unix, or a TCP handle on Windows, which is a server or a connection (listening or connected state). Bound sockets or pipes will be assumed to be servers. 👍

• int uv_try_write(uv_stream_t *handle, const uv_buf_t bufs[], unsigned int nbufs) — same as uv_write(), but won't queue a write request if it can't be completed immediately. It'll return either:
  • > 0: the number of bytes written (can be less than the supplied buffer size — yeah, really).
  • < 0: a negative error code (UV_EAGAIN is returned if no data can be sent immediately).
• int uv_try_write2(uv_stream_t *handle, const uv_buf_t bufs[], unsigned int nbufs, uv_stream_t *send_handle) — same as uv_try_write() and an extended write function for sending handles over a pipe like uv_write2. Trying to send a handle is not supported on Windows, where it returns UV_EAGAIN. 🙈

Added in version 1.42.0.

• size_t uv_write_nwritten(const uv_write_t *req) — returns the number of bytes written by a write request. Only valid when called from within the write callback (uv_write_cb). 📏

This is primarily useful when a write has been cancelled via uv_cancel() and the callback receives UV_ECANCELED status, so you can determine how many bytes were actually written before cancellation. Note that cancelled writes may still succeed or fail with other errors if the kernel finished processing the write before the cancellation took effect. The kernel does what it wants, honestly. 💀

Added in version 1.53.0.

• int uv_is_readable(const uv_stream_t *handle) — returns 1 if the stream is readable, 0 otherwise. ⭐
• int uv_is_writable(const uv_stream_t *handle) — returns 1 if the stream is writable, 0 otherwise. ⭐
• int uv_stream_set_blocking(uv_stream_t *handle, int 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 only works on Windows for uv_pipe_t handles. On UNIX platforms, all uv_stream_t handles are supported. Also, libuv currently makes no ordering guarantee when the blocking mode is changed after write requests have already been submitted. So it's recommended to set the blocking mode immediately after opening or creating the stream. Before you get messy with it. 💅

Changed in version 1.4.0: UNIX implementation added.

size_t uv_stream_get_write_queue_size(const uv_stream_t *stream)

Okay bestie this one is so simple it's basically a flexion 💅 — it just hands you back stream->write_queue_size. That's it. That's the whole function.

Added in version 1.19.0.

See also: The uv_handle_t API functions also apply. 🫶

---

🦋 uv_tcp_t --- TCP handle 🦋

So uv_tcp_t handles are the whole vibe for representing, like, both TCP streams and servers. One type, two moods, no cap.

And yes, uv_tcp_t is a 'subclass' of uv_stream_t — it inherits the whole stream situation, so everything stream-y applies here too. 🧚

✨ Data types ✨

type uv_tcp_t

The TCP handle type. That's the one. 👑

enum uv_tcp_flags

These are the flags you'd use in uv_tcp_bind(). Copy them exactly, bestie:

enum uv_tcp_flags {
    /* Used with uv_tcp_bind, when an IPv6 address is used. */
    UV_TCP_IPV6ONLY = 1,

    /* Enable SO_REUSEPORT socket option when binding the handle.
     * This allows completely duplicate bindings by multiple processes
     * or threads if they all set SO_REUSEPORT before binding the port.
     * Incoming connections are distributed across the participating
     * listener sockets.
     *
     * This flag is available only on Linux 3.9+, DragonFlyBSD 3.6+,
     * FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ for now.
     */
    UV_TCP_REUSEPORT = 2,
};

🌸 Public members 🌸

N/A. Literally none. Nothing to see here, move along. 🙈

See also: The uv_stream_t members also apply.

💖 API 💖

int uv_tcp_init(uv_loop_t *loop, uv_tcp_t *handle)

Initializes the handle. Heads up though — no socket is created as of yet. It's giving "set up but not set up," iykyk.

int uv_tcp_init_ex(uv_loop_t *loop, uv_tcp_t *handle, unsigned int flags)

Same deal but with flags so you can be specific. Right now only the lower 8 bits of the flags parameter get used, and they're used as the socket domain. A socket will be created for that domain. But if the domain you specified is AF_UNSPEC, then no socket is created — exactly like uv_tcp_init().

Added in version 1.7.0.

int uv_tcp_open(uv_tcp_t *handle, uv_os_sock_t sock)

Opens an existing file descriptor or SOCKET and treats it as a TCP handle. Very "bring your own socket" energy. 💅

Changed in version 1.2.1: the file descriptor is set to non-blocking mode.

Note: the file descriptor or SOCKET you pass in is not checked for its type — but it's still required that it represents a valid stream socket. So like, the library trusts you. Don't make it regret that. 😭

int uv_tcp_nodelay(uv_tcp_t *handle, int enable)

Turns on TCP_NODELAY, which disables Nagle's algorithm. Nagle is over, we don't stan. ✨

int uv_tcp_keepalive(uv_tcp_t *handle, int enable, unsigned int delay)

Enables / disables TCP keep-alive. delay is the initial delay, in seconds — and it gets ignored when enable is zero.

Once delay has been reached, there's still a whole saga: 10 successive probes, each spaced 1 second from the previous one, will still happen. If the connection is still lost at the end of that whole procedure, then the handle gets destroyed with a UV_ETIMEDOUT error passed to the corresponding callback. Rip bozo. 💀

If delay is less than 1, then UV_EINVAL is returned.

Changed in version 1.49.0: If delay is less than 1 then UV_EINVAL is returned.

int uv_tcp_keepalive_ex(uv_tcp_t *handle, int on, unsigned int idle, unsigned int intvl, unsigned int cnt)

The deluxe version — enable / disable TCP keep-alive with all the socket options: TCP_KEEPIDLE, TCP_KEEPINTVL and TCP_KEEPCNT. So idle is the value for TCP_KEEPIDLE, intvl is the value for TCP_KEEPINTVL, cnt is the value for TCP_KEEPCNT. All of them ignored when on is zero.

With TCP keep-alive enabled, idle is the time (in seconds) the connection needs to remain idle before TCP starts sending keep-alive probes. intvl is the time (in seconds) between individual keep-alive probes. Then TCP will drop the connection after sending cnt probes without getting any replies from the peer, and then the handle is destroyed with a UV_ETIMEDOUT error passed to the corresponding callback. It really said "no reply? blocked." 🚫

If one of idle, intvl, or cnt is less than 1, UV_EINVAL is returned.

Changed in version 1.52.0: added support of setting TCP_KEEPINTVL and TCP_KEEPCNT socket options.

Note: make sure the socket options are actually supported by the underlying operating system. Currently supported platforms: - AIX - DragonFlyBSD - FreeBSD - illumos - Linux - macOS - NetBSD - Solaris - Windows

int uv_tcp_simultaneous_accepts(uv_tcp_t *handle, int enable)

Enable / disable simultaneous asynchronous accept requests that the OS queues up when it's listening for new TCP connections.

This is a tuning knob for getting the TCP server performance you want. Having simultaneous accepts can significantly improve the rate of accepting connections (which is why it is enabled by default 👀) but it may lead to uneven load distribution in multi-process setups. So it's a tradeoff, fr fr.

int uv_tcp_bind(uv_tcp_t *handle, const struct sockaddr *addr, unsigned int flags)

Binds the handle to an address and port. Iconic.

When the port is already taken, you can expect to see a UV_EADDRINUSE error from uv_listen() or uv_tcp_connect() — unless you specify UV_TCP_REUSEPORT in flags for all the binding sockets. And like, a successful call to this function does not guarantee that the call to uv_listen() or uv_tcp_connect() will succeed as well. No promises, bestie.

Parameters

• handle -- TCP handle. It should have been initialized with uv_tcp_init().
• addr -- Address to bind to. It should point to an initialized struct sockaddr_in or struct sockaddr_in6.
• flags -- Flags that control the behavior of binding the socket. UV_TCP_IPV6ONLY can be contained in flags to disable dual-stack support and only use IPv6. UV_TCP_REUSEPORT can be contained in flags to enable the socket option SO_REUSEPORT with the capability of load balancing that distribute incoming connections across all listening sockets in multiple processes or threads.

Returns 0 on success, or an error code < 0 on failure.

Changed in version 1.49.0: added the UV_TCP_REUSEPORT flag.

Note: the UV_TCP_REUSEPORT flag is available only on Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ at the moment. On other platforms this function will return an UV_ENOTSUP error. 💀

int uv_tcp_getsockname(const uv_tcp_t *handle, struct sockaddr *name, int *namelen)

Gets you the current address the handle is bound to. name must point to a valid and big enough chunk of memory — struct sockaddr_storage is the recommended pick so you're covered for both IPv4 and IPv6 support. 🎀

int uv_tcp_getpeername(const uv_tcp_t *handle, struct sockaddr *name, int *namelen)

Same vibe, but for the address of the peer connected to the handle. Again, name must point to a valid and big enough chunk of memory, and struct sockaddr_storage is recommended for IPv4 and IPv6 support.

int uv_tcp_connect(uv_connect_t *req, uv_tcp_t *handle, const struct sockaddr *addr, uv_connect_cb cb)

Establishes an IPv4 or IPv6 TCP connection. Give it an initialized TCP handle and an uninitialized uv_connect_t. The addr should point to an initialized struct sockaddr_in or struct sockaddr_in6.

On Windows, if the addr is initialized to point to an unspecified address (0.0.0.0 or ::) it will be changed to point to localhost. That's on purpose, to match the behavior of Linux systems. 🌈

The callback fires when the connection has been established, or when a connection error happened. Either way you're getting a callback, babe.

Changed in version 1.19.0: added 0.0.0.0 and :: to localhost mapping

See also: The uv_stream_t API functions also apply. 🫶

int uv_tcp_close_reset(uv_tcp_t *handle, uv_close_cb close_cb)

Resets a TCP connection by sending a RST packet. It pulls this off by setting the SO_LINGER socket option with a linger interval of zero and then calling uv_close(). Cold. 🧊

Because of some platform inconsistencies, mixing uv_shutdown() and uv_tcp_close_reset() calls is not allowed. Like, genuinely not allowed. Don't do it.

Added in version 1.32.0.

int uv_socketpair(int type, int protocol, uv_os_sock_t socket_vector[2], int flags0, int flags1)

Creates a pair of connected sockets with the properties you specify. The resulting handles can be passed to uv_tcp_open, used with uv_spawn, or honestly used for any other purpose you want. Versatile icon. ✨

Valid values for flags0 and flags1 are:

• UV_NONBLOCK_PIPE: 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.

Added in version 1.41.0.

---

🎀 uv_pipe_t --- Pipe handle 🎀

Pipe handles are like... the abstraction layer over streaming files on Unix (that includes local domain sockets, pipes, and FIFOs) and named pipes on Windows. Very "one handle, many situations" of them. 💅

And yup, uv_pipe_t is a 'subclass' of uv_stream_t. Same family energy. 🧚

🌸 Data types 🌸

type uv_pipe_t

The pipe handle type. Boom, that's the type.

⭐ Public members ⭐

int uv_pipe_t.ipc

Whether this pipe is suitable for handle passing between processes. Only a connected pipe that will be passing the handles should have this flag set — not the listening pipe that uv_accept is called on. That distinction matters, bestie, don't mix it up. 🙈

See also: The uv_stream_t members also apply. 🫶

💜 API 💜

int uv_pipe_init(uv_loop_t *loop, uv_pipe_t *handle, int ipc)

Initializes a pipe handle. The ipc argument is a boolean that says whether this pipe will be used for handle passing between processes (which may change the bytes on the wire 👀). And again, for emphasis: only a connected pipe that will be passing the handles should have this flag set, not the listening pipe that uv_accept is called on. 🫶

int uv_pipe_open(uv_pipe_t *handle, uv_file file)

Open an already-existing file descriptor or HANDLE and treat it as a pipe 🎀

Changed in version 1.2.1: the file descriptor gets set to non-blocking mode, okay?

⚠️ Heads up bestie: the file descriptor or HANDLE you pass in is not type-checked. Like, nobody's vibe-checking it for you — it's just required that it actually represents a valid pipe. So maybe don't lie to it. 😭

---

int uv_pipe_bind(uv_pipe_t *handle, const char *name)

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

Does NOT support Linux abstract namespace sockets — unlike uv_pipe_bind2(), which does. So if that's your thing, go use the other one, iykyk.

Lowkey it's just an alias for uv_pipe_bind2(handle, name, strlen(name), 0).

🌸 Note: on Unix, paths get truncated to sizeof(sockaddr_un.sun_path) bytes — typically somewhere between 92 and 108 bytes. So keep your names cute but short, bestie.

---

int uv_pipe_bind2(uv_pipe_t *handle, const char *name, size_t namelen, unsigned int flags)

Same deal: bind the pipe to a file path (Unix) or a name (Windows) 💖

flags must be zero or UV_PIPE_NO_TRUNCATE. If you hand it unsupported flags it returns UV_EINVAL without performing the bind operation at all — like it just refuses, no bind, nothing happened, we move on.

This one does support Linux abstract namespace sockets. 👑

And listen: namelen must include the leading nul byte but not the trailing nul byte. Yes, that's real. Read it twice. 🫶

Added in version 1.46.0.

🌸 Note: on Unix, paths get truncated to sizeof(sockaddr_un.sun_path) bytes (usually 92–108) unless you specified the UV_PIPE_NO_TRUNCATE flag — in which case you get an UV_EINVAL error instead. Pick your fighter.

---

void uv_pipe_connect(uv_connect_t *req, uv_pipe_t *handle, const char *name, uv_connect_cb cb)

Connect to the Unix domain socket or the Windows named pipe 🌈

Does not support Linux abstract namespace sockets — unlike uv_pipe_connect2().

It's an alias for uv_pipe_connect2(req, handle, name, strlen(name), 0, cb) — same energy, shorter name.

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

---

int uv_pipe_connect2(uv_connect_t *req, uv_pipe_t *handle, const char *name, size_t namelen, unsigned int flags, uv_connect_cb cb)

Connect to the Unix domain socket or the Windows named pipe, but make it fancy ✨

flags must be zero or UV_PIPE_NO_TRUNCATE. Unsupported flags → UV_EINVAL, and it bails without performing the connect operation. No connection, no drama.

Supports Linux abstract namespace sockets 💅 And again: namelen must include the leading nul byte, but not the trailing nul byte.

Added in version 1.46.0.

🌸 Note: on Unix, paths get truncated to sizeof(sockaddr_un.sun_path) bytes (typically 92–108) unless UV_PIPE_NO_TRUNCATE is specified, in which case you get UV_EINVAL. Yes, same note as before. It's important, okay??

---

int uv_pipe_getsockname(const uv_pipe_t *handle, char *buffer, size_t *size)

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

You must provide a preallocated buffer, bestie — it's not gonna make one for you. The size parameter holds the length of the buffer going in, and gets set to the number of bytes written to the buffer on output. If your buffer isn't big enough you'll get UV_ENOBUFS back, and len will contain the required size — so now you know exactly how much room you needed. 🙈

On FreeBSD, UNIX domain socket paths cannot exceed the size of sockaddr_un.sun_path, even though the platform defines a SOCK_MAXADDRLEN that's larger. Like, it defines it, but it doesn't mean it. 💀

Changed in version 1.3.0: the returned length no longer includes the terminating null byte, and the buffer is not null terminated. Adjust your expectations accordingly.

---

int uv_pipe_getpeername(const uv_pipe_t *handle, char *buffer, size_t *size)

Get the name of the Unix domain socket or the named pipe to which the handle is connected — the other side of the situationship 🫶

Same rules: preallocated buffer, required. size holds the buffer length on the way in, and gets set to the number of bytes written on the way out. Not big enough? UV_ENOBUFS, and len tells you the required size.

Added in version 1.3.0.

---

void uv_pipe_pending_instances(uv_pipe_t *handle, int count)

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

🎀 Note: this setting applies to Windows only. Unix girlies, this one's not for you.

---

int uv_pipe_pending_count(uv_pipe_t *handle)

uv_handle_type uv_pipe_pending_type(uv_pipe_t *handle)

These two are how you receive handles over IPC pipes 💖

The ritual goes like this:

1. First — call uv_pipe_pending_count().
2. If it's > 0, then initialize a handle of the given type, returned by uv_pipe_pending_type().
3. And call uv_accept(pipe, handle).

That's it. That's the whole ceremony. ✨

🦋 See also: the uv_stream_t API functions also apply.

---

int uv_pipe_chmod(uv_pipe_t *handle, int flags)

Alters pipe permissions so it can be accessed from processes run by different users. Basically makes the pipe writable or readable by all users. Very generous of you. 🌸

Mode can be UV_WRITABLE, UV_READABLE, or UV_WRITABLE | UV_READABLE.

⚠️ This function is blocking. Like, actually blocking. Just so you know.

Added in version 1.16.0.

---

int uv_pipe(uv_file fds[2], int read_flags, int write_flags)

Create a pair of connected pipe handles 🎀 Data may be written to fds[1] and read from fds[0]. The resulting handles can be passed to uv_pipe_open, used with uv_spawn, or honestly used for any other purpose you can dream up.

Valid values for the flags are:

• UV_NONBLOCK_PIPE — 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. So, like, context-dependent, bestie.

Equivalent to pipe(2) with the O_CLOEXEC flag set. 💅

Added in version 1.41.0.

---

🎀 uv_tty_t --- TTY handle 🎀

TTY handles represent a stream for the console 🖥️✨

uv_tty_t is a 'subclass' of uv_stream_t. Family tree stuff.

---

Data types

type uv_tty_t

TTY handle type. That's the whole description. It's a handle. For TTYs. Iconic brevity. 👑

enum uv_tty_mode_t

Added in version 1.2.0.

TTY mode type:

typedef enum {
    /* Initial/normal terminal mode */
    UV_TTY_MODE_NORMAL,
    /*
    * Raw input mode (On Windows, ENABLE_WINDOW_INPUT is also enabled).
    * May become equivalent to UV_TTY_MODE_RAW_VT in future libuv versions.
    */
    UV_TTY_MODE_RAW,
    /* Binary-safe I/O mode for IPC (Unix-only) */
    UV_TTY_MODE_IO,
    /* Raw input mode. On Windows ENABLE_VIRTUAL_TERMINAL_INPUT is also set. */
    UV_TTY_MODE_RAW_VT
} uv_tty_mode_t;

enum uv_tty_vtermstate_t

Console virtual terminal mode type:

typedef enum {
    /*
     * The console supports handling of virtual terminal sequences
     * (Windows10 new console, ConEmu)
     */
    UV_TTY_SUPPORTED,
    /* The console cannot process virtual terminal sequences.  (Legacy
     * console)
     */
    UV_TTY_UNSUPPORTED
} uv_tty_vtermstate_t

---

Public members

N/A — nothing to see here, move along 🦋

🌸 See also: the uv_stream_t members also apply.

---

API

int uv_tty_init(uv_loop_t *loop, uv_tty_t *handle, uv_file fd, int unused)

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. Considerate queen behavior. 👑

⚠️ This function is not thread safe on systems that don't support ioctl TIOCGPTN or TIOCPTYGNAME — for instance OpenBSD and Solaris. Know your platform, bestie.

🎀 Note: if reopening the TTY fails, libuv falls back to blocking writes. Not ideal, but it's what we've got.

Changed in version 1.23.1: the readable parameter is now unused and ignored. The correct value will now be auto-detected from the kernel. She's autonomous now. 💅

Changed in version 1.9.0: the path of the TTY is determined by ttyname_r(3). In earlier versions libuv opened /dev/tty instead.

Changed in version 1.5.0: trying to initialize a TTY stream with a file descriptor that refers to a file returns UV_EINVAL on UNIX. Rude, but fair.

int uv_tty_set_mode(uv_tty_t *handle, uv_tty_mode_t mode)

Changed in version 1.2.0: the mode is specified as a uv_tty_mode_t value.

Set the TTY using the specified terminal mode 🌈

int uv_tty_reset_mode(void)

To be called when the program exits. Resets TTY settings to default values for the next process to take over — like cleaning up after yourself at a sleepover 🫶

✨ This function is async signal-safe on Unix platforms, but it can fail with error code UV_EBUSY if you call it while execution is inside uv_tty_set_mode(). So maybe don't do that. 😭

int uv_tty_get_winsize(uv_tty_t *handle, int *width, int *height)

Gets the current Window size. On success it returns 0. Simple. Clean. We love a zero return. 💖

🌸 See also: the uv_stream_t API functions also apply.

void uv_tty_set_vterm_state(uv_tty_vtermstate_t state)

Controls whether console virtual terminal sequences are processed by libuv or by the console. Useful in particular for enabling ConEmu support of ANSI X3.64 and Xterm 256 colors 🎨 Otherwise Windows10 consoles are usually detected automatically — she figures it out herself.

🎀 This function is only meaningful on Windows systems. On Unix it is silently ignored. Like, it hears you, it's just not engaging.

Added in version 1.33.0.

int uv_tty_get_vterm_state(uv_tty_vtermstate_t *state)

Get the current state of whether console virtual terminal sequences are handled by libuv or by the console 👑

⚠️ This function is not implemented on Unix, where it returns UV_ENOTSUP. Sorry Unix girlies, this one's Windows-only.

Added in version 1.33.0.

---

🔥 uv_udp_t --- UDP handle 🔥

UDP handles encapsulate UDP communication for both clients and servers. Both sides of the coin, we love a versatile icon ✨

🦋 Data types 🦋

okay so here are the actual type girlies for UDP, no cap:

• type uv_udp_t — UDP handle type. that's the main character handle 💅
• type uv_udp_send_t — UDP send request type. the lil request object for sends ✨

---

enum uv_udp_flags — flags used in uv_udp_bind() and uv_udp_recv_cb. yes bestie, these are the vibe switches 🎀

enum uv_udp_flags {
    /* Disables dual stack mode. */
    UV_UDP_IPV6ONLY = 1,
    /*
     * Indicates message was truncated because read buffer was too small. The
     * remainder was discarded by the OS. Used in uv_udp_recv_cb.
     */
    UV_UDP_PARTIAL = 2,
    /*
     * Indicates if SO_REUSEADDR will be set when binding the handle.
     * This sets the SO_REUSEPORT socket flag on the BSDs (except for
     * DragonFlyBSD), OS X, and other platforms where SO_REUSEPORTs don't
     * have the capability of load balancing, as the opposite of what
     * UV_UDP_REUSEPORT would do. On other Unix platforms, it sets the
     * SO_REUSEADDR flag. What that means is that multiple threads or
     * processes can bind to the same address without error (provided
     * they all set the flag) but only the last one to bind will receive
     * any traffic, in effect "stealing" the port from the previous listener.
     */
    UV_UDP_REUSEADDR = 4,
    /*
     * Indicates that the message was received by recvmmsg, so the buffer provided
     * must not be freed by the recv_cb callback.
     */
    UV_UDP_MMSG_CHUNK = 8,
    /*
     * Indicates that the buffer provided has been fully utilized by recvmmsg and
     * that it should now be freed by the recv_cb callback. When this flag is set
     * in uv_udp_recv_cb, nread will always be 0 and addr will always be NULL.
     */
    UV_UDP_MMSG_FREE = 16,
    /*
     * Indicates if IP_RECVERR/IPV6_RECVERR will be set when binding the handle.
     * This sets IP_RECVERR for IPv4 and IPV6_RECVERR for IPv6 UDP sockets on
     * Linux. This stops the Linux kernel from suppressing some ICMP error messages
     * and enables full ICMP error reporting for faster failover.
     * This flag is no-op on platforms other than Linux.
     */
    UV_UDP_LINUX_RECVERR = 32,
    /*
     * Indicates if SO_REUSEPORT will be set when binding the handle.
     * This sets the SO_REUSEPORT socket option on supported platforms.
     * Unlike UV_UDP_REUSEADDR, this flag will make multiple threads or
     * processes that are binding to the same address and port "share"
     * the port, which means incoming datagrams are distributed across
     * the receiving sockets among threads or processes.
     *
     * This flag is available only on Linux 3.9+, DragonFlyBSD 3.6+,
     * FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ for now.
     */
    UV_UDP_REUSEPORT = 64,
    /*
     * Indicates that recvmmsg should be used, if available. The uv_alloc_cb
     * for this handle should create buffers that are multiples of 64 KiB.
     */
    UV_UDP_RECVMMSG = 256
};

---

typedef void (*uv_udp_send_cb)(uv_udp_send_t *req, int status) — callback type for uv_udp_send(), called after the data was sent. it's giving “send complete, bestie” 💌

typedef void (*uv_udp_recv_cb)(uv_udp_t *handle, ssize_t nread, const uv_buf_t *buf, const struct sockaddr *addr, unsigned flags) — callback type passed to uv_udp_recv_start(), called when the endpoint receives data. this is the “omg package arrived” callback 🎁

the args are:

• handle — UDP handle.
• nread — number of bytes that have been received. 0 if there is no more data to read. note that 0 may also mean that an empty datagram was received (in this case addr is not NULL). < 0 if a transmission error was detected; if using recvmmsg(2) no more chunks will be received and the buffer can be freed safely.
• buf — uv_buf_t with the received data.
• addr — struct sockaddr* containing the address of the sender. can be NULL. valid for the duration of the callback only.
• flags — one or more or'ed UV_UDP_* constants.

the callee is responsible for freeing the buffer, libuv does not reuse it. the buffer may be a null buffer (where buf->base == NULL and buf->len == 0) on error.

when using recvmmsg(2), chunks will have the UV_UDP_MMSG_CHUNK flag set, those must not be freed. if no errors occur, there will be a final callback with nread set to 0, addr set to NULL and the buffer pointing at the initially allocated data with the UV_UDP_MMSG_CHUNK flag cleared and the UV_UDP_MMSG_FREE flag set. if a UDP socket error occurs, nread will be < 0. in either scenario, the callee can now safely free the provided buffer.

changed in version 1.40.0: added the UV_UDP_MMSG_FREE flag.

Note: the receive callback will be called with nread == 0 and addr == NULL when there is nothing to read, and with nread == 0 and addr != NULL when an empty UDP packet is received. lowkey important bestie 🫶

---

enum uv_membership — membership type for a multicast address. literally the join/leave situation 🌈

typedef enum {
    UV_LEAVE_GROUP = 0,
    UV_JOIN_GROUP
} uv_membership;

---

🎀 Public members 🎀

• size_t uv_udp_t.send_queue_size — number of bytes queued for sending. this field strictly shows how much information is currently queued. it's giving “how full is the send queue rn” 📦
• size_t uv_udp_t.send_queue_count — number of send requests currently in the queue awaiting to be processed. yes, the count count 💅
• uv_udp_t *uv_udp_send_t.handle — UDP handle where this send request is taking place.

See also: the uv_handle_t members also apply. so don't forget those bestie ✨

---

🚀 API 🚀

• int uv_udp_init(uv_loop_t *loop, uv_udp_t *handle) — initialize a new UDP handle. the actual socket is created lazily. returns 0 on success. lazy socket creation is so real 😌
• int uv_udp_init_ex(uv_loop_t *loop, uv_udp_t *handle, unsigned int flags) — initialize the handle with the specified flags. the lower 8 bits of the flags parameter are used as the socket domain. a socket will be created for the given domain. if the specified domain is AF_UNSPEC no socket is created, just like uv_udp_init().

the remaining bits can be used to set one of these flags:

• UV_UDP_RECVMMSG: if set, and the platform supports it, recvmmsg(2) will be used. the uv_alloc_cb for this handle should create buffers that are multiples of 64 KiB.

added in version 1.7.0.

changed in version 1.37.0: added the UV_UDP_RECVMMSG flag.

• int uv_udp_open_ex(uv_udp_t *handle, uv_os_sock_t sock, unsigned int flags) — opens an existing file descriptor or Windows SOCKET as a UDP handle.

params, bestie:

• handle — UDP handle. should have been initialized with uv_udp_init().
• sock — an existing socket to associate with the handle.
• flags — flags that control socket behavior, UV_UDP_REUSEADDR, and UV_UDP_REUSEPORT are supported.

returns 0 on success, or an error code < 0 on failure.

added in version 1.52.0.

• int uv_udp_open(uv_udp_t *handle, uv_os_sock_t sock) — 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.

changed in version 1.2.1: 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.

internally sets the SO_REUSEADDR socket option unconditionally. this means the reuse flag is always enabled, regardless of user intent. for more control use uv_udp_open_ex(). periodt 💅

• int uv_udp_bind(uv_udp_t *handle, const struct sockaddr *addr, unsigned int flags) — bind the UDP handle to an IP address and port.

params:

• handle — UDP handle. should have been initialized with uv_udp_init().
• addr — struct sockaddr_in or struct sockaddr_in6 with the address and port to bind to.
• flags — indicate how the socket will be bound, UV_UDP_IPV6ONLY, UV_UDP_REUSEADDR, UV_UDP_REUSEPORT, and UV_UDP_RECVERR are supported.

returns 0 on success, or an error code < 0 on failure.

changed in version 1.49.0: added the UV_UDP_REUSEPORT flag.

Note: UV_UDP_REUSEPORT flag is available only on Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4, and AIX 7.2.5+ at the moment. on other platforms this function will return an UV_ENOTSUP error. for platforms where SO_REUSEPORT has the capability of load balancing, specifying both UV_UDP_REUSEADDR and UV_UDP_REUSEPORT in flags is allowed and SO_REUSEPORT will always override the behavior of SO_REUSEADDR. for platforms where SO_REUSEPORT doesn't have the capability of load balancing, specifying both UV_UDP_REUSEADDR and UV_UDP_REUSEPORT in flags will fail, returning an UV_ENOTSUP error. no cap, that's the whole tea ☕

💅 uv_udp_connect()

int uv_udp_connect(uv_udp_t *handle, const struct sockaddr *addr)

okay so this one is literally the "set it and forget it" of UDP 🌸 — you associate the handle with a remote address and port, and after that every message this handle sends automatically goes to that destination. No more typing the address every time, bestie. Iconic.

Calling it with a NULL addr disconnects the handle. And here's the vibe check you gotta pass: trying to call uv_udp_connect() on an already-connected handle gives you an UV_EISCONN error 😭 and trying to disconnect a handle that isn't connected gives you UV_ENOTCONN. So it's very much a "know your status" situation.

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init().
• addr — a struct sockaddr_in or struct sockaddr_in6 holding the address and port to associate to.

Returns 0 on success, or an error code < 0 on failure.

Added in version 1.27.0. ✨

---

🎀 uv_udp_getpeername()

int uv_udp_getpeername(const uv_udp_t *handle, struct sockaddr *name, int *namelen)

Gets the remote IP and port of the UDP handle — but only on connected UDP handles, bestie. On unconnected ones it just hands you an UV_ENOTCONN and refuses to engage 💀 (respect, honestly).

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init() and bound.
• name — pointer to the structure that gets filled with the address data. In order to support IPv4 and IPv6, struct sockaddr_storage should be used.
• namelen — on input it indicates the data of the name field. On output it indicates how much of it was filled.

Returns 0 on success, or an error code < 0 on failure.

Added in version 1.27.0. 🦋

---

🌸 uv_udp_getsockname()

int uv_udp_getsockname(const uv_udp_t *handle, struct sockaddr *name, int *namelen)

Same energy as above but make it local — this gives you the local IP and port of the UDP handle. Very "who am I, really" of it 🫶.

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init() and bound.
• name — pointer to the structure to be filled with the address data. In order to support IPv4 and IPv6, struct sockaddr_storage should be used.
• namelen — on input it indicates the data of the name field. On output it indicates how much of it was filled.

Returns 0 on success, or an error code < 0 on failure.

---

👑 uv_udp_set_membership()

int uv_udp_set_membership(uv_udp_t *handle, const char *multicast_addr, const char *interface_addr, uv_membership membership)

Set membership for a multicast address. It's giving "club membership but for packets" 🎀.

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init().
• multicast_addr — the multicast address to set membership for.
• interface_addr — interface address.
• membership — should be UV_JOIN_GROUP or UV_LEAVE_GROUP.

Returns 0 on success, or an error code < 0 on failure.

---

💜 uv_udp_set_source_membership()

int uv_udp_set_source_membership(uv_udp_t *handle, const char *multicast_addr, const char *interface_addr, const char *source_addr, uv_membership membership)

Set membership for a source-specific multicast group. Same as the one above but with extra ✨ specificity ✨ — now you're picky about the source too, and honestly? Same.

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init().
• multicast_addr — the multicast address to set membership for.
• interface_addr — interface address.
• source_addr — source address.
• membership — should be UV_JOIN_GROUP or UV_LEAVE_GROUP.

Returns 0 on success, or an error code < 0 on failure.

Added in version 1.32.0. ⭐

---

🔁 uv_udp_set_multicast_loop()

int uv_udp_set_multicast_loop(uv_udp_t *handle, int on)

Sets the IP multicast loop flag — which makes multicast packets loop back to local sockets. It's the "hear your own echo" button 🌀.

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init_ex() as either AF_INET or AF_INET6, or have been bound to an address explicitly with uv_udp_bind(), or implicitly with uv_udp_send() or uv_udp_recv_start().
• on — 1 for on, 0 for off.

Returns 0 on success, or an error code < 0 on failure.

---

📡 uv_udp_set_multicast_ttl()

int uv_udp_set_multicast_ttl(uv_udp_t *handle, int ttl)

Sets the multicast ttl. Short and sweet, no notes 💅.

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init_ex() as either AF_INET or AF_INET6, or have been bound to an address explicitly with uv_udp_bind(), or implicitly with uv_udp_send() or uv_udp_recv_start().
• ttl — 1 through 255.

Returns 0 on success, or an error code < 0 on failure.

---

🧚 uv_udp_set_multicast_interface()

int uv_udp_set_multicast_interface(uv_udp_t *handle, const char *interface_addr)

Sets the multicast interface to send or receive data on — like picking which door the packets leave through 🚪✨.

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init_ex() as either AF_INET or AF_INET6, or have been bound to an address explicitly with uv_udp_bind(), or implicitly with uv_udp_send() or uv_udp_recv_start().
• interface_addr — interface address.

Returns 0 on success, or an error code < 0 on failure.

---

📢 uv_udp_set_broadcast()

int uv_udp_set_broadcast(uv_udp_t *handle, int on)

Set broadcast on or off. Scream to the whole subnet or don't, your call 🗣️💖.

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init_ex() as either AF_INET or AF_INET6, or have been bound to an address explicitly with uv_udp_bind(), or implicitly with uv_udp_send() or uv_udp_recv_start().
• on — 1 for on, 0 for off.

Returns 0 on success, or an error code < 0 on failure.

---

⏳ uv_udp_set_ttl()

int uv_udp_set_ttl(uv_udp_t *handle, int ttl)

Sets the time to live. Lowkey the packet's little lifespan countdown ⏱️.

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init_ex() as either AF_INET or AF_INET6, or have been bound to an address explicitly with uv_udp_bind(), or implicitly with uv_udp_send() or uv_udp_recv_start().
• ttl — 1 through 255.

Returns 0 on success, or an error code < 0 on failure.

---

🚀 uv_udp_send()

int uv_udp_send(uv_udp_send_t *req, uv_udp_t *handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr *addr, uv_udp_send_cb send_cb)

Sends data over the UDP socket, bestie! 🎉 And if the socket hasn't previously been bound with uv_udp_bind(), it'll get bound to 0.0.0.0 (the "all interfaces" IPv4 address) and a random port number. Surprise binding, but make it functional.

On Windows, if addr is initialized to point to an unspecified address (0.0.0.0 or ::) it will be changed to point to localhost. That's done to match the behavior of Linux systems — consistency slay 💅.

Now pay attention because these two are the ones people mess up:

For connected UDP handles, addr must be set to NULL, otherwise it will return UV_EISCONN error. For connectionless UDP handles, addr cannot be NULL, otherwise it will return UV_EDESTADDRREQ error.

Parameters

• req — UDP request handle. Need not be initialized.
• handle — the UDP handle. Should have been initialized with uv_udp_init().
• bufs — list of buffers to send.
• nbufs — number of buffers in bufs.
• addr — struct sockaddr_in or struct sockaddr_in6 with the address and port of the remote peer.
• send_cb — callback to invoke when the data has been sent out.

Returns 0 on success, or an error code < 0 on failure.

Changed in version 1.19.0: added 0.0.0.0 and :: to localhost mapping

Changed in version 1.27.0: added support for connected sockets 🌈

---

⚡ uv_udp_try_send()

int uv_udp_try_send(uv_udp_t *handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr *addr)

Same as uv_udp_send(), but it won't queue a send request if it can't be completed immediately. No waiting around, no "I'll get to it later" energy — it's now or never 🔥.

Same rules as before, and yes they still matter:

For connected UDP handles, addr must be set to NULL, otherwise it will return UV_EISCONN error. For connectionless UDP handles, addr cannot be NULL, otherwise it will return UV_EDESTADDRREQ error.

Returns

• >= 0: number of bytes sent (it matches the given buffer size).
• < 0: negative error code (UV_EAGAIN is returned when the message can't be sent immediately).

Changed in version 1.27.0: added support for connected sockets ✨

---

🌟 uv_udp_try_send2()

int uv_udp_try_send2(uv_udp_t *handle, unsigned int count, uv_buf_t *bufs[/*count*/], unsigned int nbufs[/*count*/], struct sockaddr *addrs[/*count*/], unsigned int flags)

Like uv_udp_try_send(), but it can send multiple datagrams at once. Main character energy, honestly 👑. It's a lightweight abstraction around sendmmsg(2), with a sendmsg(2) fallback loop for platforms that do not support the former. The handle must be fully initialized — call uv_udp_bind first! (Not optional, bestie, that's a whole pre-requisite.)

Returns

• >= 0: number of datagrams sent. Zero only if count was zero.
• < 0: negative error code. Only if sending the first datagram fails, otherwise returns a positive send count. UV_EAGAIN when datagrams cannot be sent right now; fall back to uv_udp_send().

Added in version 1.50.0. 🎀

---

💌 uv_udp_recv_start()

int uv_udp_recv_start(uv_udp_t *handle, uv_alloc_cb alloc_cb, uv_udp_recv_cb recv_cb)

Prepare for receiving data — the "inbox open for business" moment 📥✨. 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.

Parameters

• handle — the UDP handle. Should have been initialized with uv_udp_init().
• alloc_cb — callback to invoke when temporary storage is needed.
• recv_cb — callback to invoke with received data.

Returns — 0 on success, or an error code < 0 on failure. ✨

Note, bestie: when you're out here using recvmmsg(2) (https://man7.org/linux/man-pages/man2/recvmmsg.2.html), the number of messages you receive at a time is limited by how many max-size dgrams fit into the buffer you allocated in alloc_cb. And listen — suggested_size in alloc_cb for udp_recv is always set to the size of exactly 1 max-size dgram. Always always. 💅

Changed in version 1.35.0: added support for recvmmsg(2) (https://man7.org/linux/man-pages/man2/recvmmsg.2.html) on supported platforms. The uv_alloc_cb for this handle should create buffers that are multiples of 64 KiB. 👑

Changed in version 1.37.0: recvmmsg(2) (https://man7.org/linux/man-pages/man2/recvmmsg.2.html) support is no longer enabled implicitly — you have to explicitly request it by passing the UV_UDP_RECVMMSG flag to uv_udp_init_ex(). No more surprise freebies. 💀

Changed in version 1.39.0: uv_udp_using_recvmmsg() can be used in alloc_cb to determine if a buffer sized for use with recvmmsg(2) (https://man7.org/linux/man-pages/man2/recvmmsg.2.html) should be allocated for the current handle/platform. iykyk 🧚

---

int uv_udp_using_recvmmsg(uv_udp_t *handle)

Returns 1 if the UDP handle was created with the UV_UDP_RECVMMSG flag and the platform supports recvmmsg(2) (https://man7.org/linux/man-pages/man2/recvmmsg.2.html), and 0 otherwise. That's it, that's the whole vibe check. 🦋

Added in version 1.39.0.

---

int uv_udp_recv_stop(uv_udp_t *handle)

Stop listening for incoming datagrams. Like putting your phone on do-not-disturb, but for packets. 🙈

Parameters

• handle — UDP handle. Should have been initialized with uv_udp_init().

Returns — 0 on success, or an error code < 0 on failure.

---

size_t uv_udp_get_send_queue_size(const uv_udp_t *handle)

Returns handle->send_queue_size. Literally just hands you that field. 🎀

Added in version 1.19.0.

---

size_t uv_udp_get_send_queue_count(const uv_udp_t *handle)

Returns handle->send_queue_count. Same energy, different field. ✨

Added in version 1.19.0.

See also

The uv_handle_t API functions also apply. 🫶

---

🦋 uv_fs_event_t --- FS Event handle

FS Event handles let you monitor a given path for changes — like, say, the file got renamed, or there was some generic change in it. This handle uses the best backend for the job on each platform. Iconic behaviour honestly. 👑

Note: on AIX, the non-default IBM bos.ahafs package has to be installed. The AIX Event Infrastructure file system (ahafs) has some limitations, and they are real: - ahafs tracks monitoring per process and is not thread safe. A separate process must be spawned for each monitor for the same event. - Events for file modification (writing to a file) are not received if only the containing folder is watched. See documentation (https://www.ibm.com/docs/en/aix/7.2?topic=management-aix-event-infrastructure-aix-aix-clusters-ahafs) for more details.

Also: the z/OS file system events monitoring infrastructure does not notify of file creation/deletion within a directory that is being monitored. See the IBM Knowledge centre (https://www.ibm.com/docs/en/zos/2.2.0?topic=SSLTBW_2.2.0/com.ibm.zos.v2r1.bpxb100/ioc.html) for more details. 😭

Data types

type uv_fs_event_t — FS Event handle type. Simple as that. 🍓

typedef void (*uv_fs_event_cb)(uv_fs_event_t *handle, const char *filename, int events, int status)

The callback you pass to uv_fs_event_start(), which will be called repeatedly after the handle is started. It just keeps showing up. main character energy. 💖

If the handle was started with a directory, the filename parameter will be a relative path to a file contained in the directory, or NULL if the file name cannot be determined.

The events parameter is an ORed mask of uv_fs_event elements.

Note: for FreeBSD, path could sometimes be NULL due to a kernel bug. Not your fault, bestie. 💀

enum uv_fs_event — event types that uv_fs_event_t handles monitor.

enum uv_fs_event {
    UV_RENAME = 1,
    UV_CHANGE = 2
};

enum uv_fs_event_flags — flags you can pass to uv_fs_event_start() to control its behavior.

enum uv_fs_event_flags {
    /*
    * By default, if the fs event watcher is given a directory name, we will
    * watch for all events in that directory. This flags overrides this behavior
    * and makes fs_event report only changes to the directory entry itself. This
    * flag does not affect individual files watched.
    * This flag is currently not implemented yet on any backend.
    */
    UV_FS_EVENT_WATCH_ENTRY = 1,
    /*
    * By default uv_fs_event will try to use a kernel interface such as inotify
    * or kqueue to detect events. This may not work on remote file systems such
    * as NFS mounts. This flag makes fs_event fall back to calling stat() on a
    * regular interval.
    * This flag is currently not implemented yet on any backend.
    */
    UV_FS_EVENT_STAT = 2,
    /*
    * By default, event watcher, when watching directory, is not registering
    * (is ignoring) changes in its subdirectories.
    * This flag will override this behaviour on platforms that support it.
    */
    UV_FS_EVENT_RECURSIVE = 4
};

Public members

N/A — there are none. Shocking, I know. 🎀

See also

The uv_handle_t members also apply.

API

int uv_fs_event_init(uv_loop_t *loop, uv_fs_event_t *handle)

Initialize the handle. That's the whole task. slay. ✨

---

int uv_fs_event_start(uv_fs_event_t *handle, uv_fs_event_cb cb, const char *path, unsigned int flags)

Start the handle with the given callback, which will watch the specified path for changes. flags can be an ORed mask of uv_fs_event_flags. Obsessed with how simple that is. 💜

Note: currently the only supported flag is UV_FS_EVENT_RECURSIVE, and only on OSX and Windows. Yeah. Only those two. 😭

Note: on macOS, events collected by the OS immediately before calling uv_fs_event_start might be reported to the uv_fs_event_cb callback. Sneaky little time-travellers. 🙈

---

int uv_fs_event_stop(uv_fs_event_t *handle)

Stop the handle — the callback will no longer be called. Bye bestie, you're unsubscribed. 💅

---

int uv_fs_event_getpath(uv_fs_event_t *handle, char *buffer, size_t *size)

Get the path being monitored by the handle. The buffer must be preallocated by you, the user. Returns 0 on success or an error code < 0 in case of failure. On success, buffer will contain the path and size its length. If the buffer is not big enough, UV_ENOBUFS will be returned and size will be set to the required size, including the null terminator. 🌸

Changed in version 1.3.0: the returned length no longer includes the terminating null byte, and the buffer is not null terminated. glow-up but also lowkey chaotic.

Changed in version 1.9.0: the returned length includes the terminating null byte on UV_ENOBUFS, and the buffer is null terminated on success. fixed fr fr. 🫶

See also

The uv_handle_t API functions also apply.

---

🌈 uv_fs_poll_t --- FS Poll handle

FS Poll handles let you monitor a given path for changes. Unlike uv_fs_event_t, fs poll handles use stat to detect when a file has changed — so they can work on file systems where fs event handles can't. Different technique, same goal. iconique. 👑

Data types

type uv_fs_poll_t — FS Poll handle type. 💖

typedef void (*uv_fs_poll_cb)(uv_fs_poll_t *handle, int status, const uv_stat_t *prev, const uv_stat_t *curr)

The callback passed to uv_fs_poll_start(), which will be called repeatedly after the handle is started, whenever any change happens to the monitored path. 🦋

The callback is invoked with status < 0 if path does not exist or is inaccessible. The watcher is not stopped, but your callback is not called again until something changes (e.g. when the file is created or the error reason changes). So like... it's waiting, not ghosting. 💀

When status == 0, the callback receives pointers to the old and new uv_stat_t structs. They are valid for the duration of the callback only — do not go saving those pointers for later, bestie, that's a one-night-only performance. 😭

Public members

N/A — nothing here. 🎀

See also

The uv_handle_t members also apply.

API

int uv_fs_poll_init(uv_loop_t *loop, uv_fs_poll_t *handle)

Initialize the handle. ✨

---

int uv_fs_poll_start(uv_fs_poll_t *handle, uv_fs_poll_cb poll_cb, const char *path, unsigned int interval)

Check the file at path for changes every interval milliseconds. Yes, milliseconds. Yes, it really does that. 👑

Note: for maximum portability, use multi-second intervals. Sub-second intervals will not detect all changes on many file systems. That's not a vibe, that's just how it is. 💅

---

int uv_fs_poll_stop(uv_fs_poll_t *handle)

Stop the handle — the callback will no longer be called. periodt. 💜

---

int uv_fs_poll_getpath(uv_fs_poll_t *handle, char *buffer, size_t *size)

Get the path being monitored by the handle. The buffer must be preallocated by the user. Returns 0 on success or an error code < 0 in case of failure. On success, buffer will contain the path and size its length. If the buffer is not big enough, UV_ENOBUFS will be returned and size will be set to the required size. 🌸

Changed in version 1.3.0: the returned length no longer includes the terminating null byte, and the buffer is not null terminated.

Changed in version 1.9.0: the returned length includes the terminating null byte on UV_ENOBUFS, and the buffer is null terminated on success. 🫶

See also

The uv_handle_t API functions also apply.

---

🌈 File system operations

libuv provides a wide variety of cross-platform sync and async file system operations, and honestly? She ate. 🔥

All functions defined in this document take a callback, which is allowed to be NULL. If the callback is NULL, the request is completed synchronously; otherwise it will be performed asynchronously. Choose your own adventure. ⭐

All file operations are run on the threadpool. See Thread pool work scheduling (#threadpool) for the info on the threadpool size — because yes, there's a size, and yes, it matters. 🎀

Starting with libuv v1.45.0, some file operations on Linux get handed off to io_uring whenever it's possible. Bestie, literally the only observable difference is a (sometimes huge) glow-up in throughput — nothing else changes, no cap. Libuv falls back to its trusty threadpool when the kernel features it needs are unavailable or just not it. Then starting with libuv v1.49.0 this whole thing got reverted, so Libuv on Linux is back to using the threadpool by default. Wanna turn io_uring on anyway? Then you gotta configure that uv_loop_t <#c.uv_loop_t> instance with the UV_LOOP_USE_IO_URING_SQPOLL option. 💅

Note: On Windows, uv_fs_* functions use utf-8 encoding. 🫶

---

🦋 Data types 🦋

• type uv_fs_t — the file system request type. Your main character struct, fr.
• type uv_timespec_t — a Y2K38-unsafe data type for storing times with nanosecond resolution. It's getting replaced with uv_timespec64_t <#c.uv_timespec64_t> in libuv v2.0, so like… enjoy it while it lasts 💀

typedef struct {
    long tv_sec;
    long tv_nsec;
} uv_timespec_t;

• type uv_stat_t — the portable equivalent of struct stat. Slay, cross-platform queen ✨

typedef struct {
    uint64_t st_dev;
    uint64_t st_mode;
    uint64_t st_nlink;
    uint64_t st_uid;
    uint64_t st_gid;
    uint64_t st_rdev;
    uint64_t st_ino;
    uint64_t st_size;
    uint64_t st_blksize;
    uint64_t st_blocks;
    uint64_t st_flags;
    uint64_t st_gen;
    uv_timespec_t st_atim;
    uv_timespec_t st_mtim;
    uv_timespec_t st_ctim;
    uv_timespec_t st_birthtim;
} uv_stat_t;

• enum uv_fs_type — the file system request type. Yeah, same description as above, it's giving "the same but an enum". Here's the whole lineup, every single one, no skipping 🙈

typedef enum {
    UV_FS_UNKNOWN = -1,
    UV_FS_CUSTOM,
    UV_FS_OPEN,
    UV_FS_CLOSE,
    UV_FS_READ,
    UV_FS_WRITE,
    UV_FS_SENDFILE,
    UV_FS_STAT,
    UV_FS_LSTAT,
    UV_FS_FSTAT,
    UV_FS_FTRUNCATE,
    UV_FS_UTIME,
    UV_FS_FUTIME,
    UV_FS_ACCESS,
    UV_FS_CHMOD,
    UV_FS_FCHMOD,
    UV_FS_FSYNC,
    UV_FS_FDATASYNC,
    UV_FS_UNLINK,
    UV_FS_RMDIR,
    UV_FS_MKDIR,
    UV_FS_MKDTEMP,
    UV_FS_RENAME,
    UV_FS_SCANDIR,
    UV_FS_LINK,
    UV_FS_SYMLINK,
    UV_FS_READLINK,
    UV_FS_CHOWN,
    UV_FS_FCHOWN,
    UV_FS_REALPATH,
    UV_FS_COPYFILE,
    UV_FS_LCHOWN,
    UV_FS_OPENDIR,
    UV_FS_READDIR,
    UV_FS_CLOSEDIR,
    UV_FS_MKSTEMP,
    UV_FS_LUTIME
} uv_fs_type;

• type uv_statfs_t — a reduced, cross-platform equivalent of struct statfs. It gets used in uv_fs_statfs(). 🍓

typedef struct uv_statfs_s {
    uint64_t f_type;
    uint64_t f_bsize;
    uint64_t f_blocks;
    uint64_t f_bfree;
    uint64_t f_bavail;
    uint64_t f_files;
    uint64_t f_ffree;
    uint64_t f_frsize;
    uint64_t f_spare[3];
} uv_statfs_t;

• enum uv_dirent_type_t — the type of dirent. Lowkey self-explanatory, highkey useful 💜

typedef enum {
    UV_DIRENT_UNKNOWN,
    UV_DIRENT_FILE,
    UV_DIRENT_DIR,
    UV_DIRENT_LINK,
    UV_DIRENT_FIFO,
    UV_DIRENT_SOCKET,
    UV_DIRENT_CHAR,
    UV_DIRENT_BLOCK
} uv_dirent_type_t;

• type uv_dirent_t — the cross-platform (reduced) equivalent of struct dirent. Used in uv_fs_scandir_next(). Isn't she neat 🎀

typedef struct uv_dirent_s {
    const char* name;
    uv_dirent_type_t type;
} uv_dirent_t;

• type uv_dir_t — the data type for streaming directory iteration. Used by uv_fs_opendir(), uv_fs_readdir(), and uv_fs_closedir(). Okay so quick breakdown: dirents represents a user provided array of uv_dirent_ts used to hold results, and nentries is the user provided maximum array size of dirents. You bring the storage, bestie — libuv just fills it 💖

typedef struct uv_dir_s {
    uv_dirent_t* dirents;
    size_t nentries;
} uv_dir_t;

• typedef void (*uv_fs_cb)(uv_fs_t *req) — the callback that gets called when a request is completed asynchronously. Your little "it's done!!" notification 🦋

---

🌸 Public members 🌸

• uv_loop_t *uv_fs_t.loop — the loop that started this request and where completion will be reported. Readonly, so don't even try it 🙈
• uv_fs_type uv_fs_t.fs_type — the FS request type.
• const char *uv_fs_t.path — the path affecting the request.
• ssize_t uv_fs_t.result — the result of the request. < 0 means error, success otherwise. On requests like uv_fs_read() or uv_fs_write() it tells you the amount of data that was read or written, respectively. Basically the receipts 🔥
• uv_stat_t uv_fs_t.statbuf — stores the result of uv_fs_stat() and other stat requests.
• void *uv_fs_t.ptr — stores the result of uv_fs_readlink() and uv_fs_realpath(), and serves as an alias to statbuf. Multi-purpose icon 👑

See also: the uv_req_t <#c.uv_req_t> members also apply. Don't forget them, iykyk.

---

⭐ API ⭐

void uv_fs_req_cleanup(uv_fs_t *req)

Cleanup request. You must call this after a request is finished so libuv can deallocate any memory it might have allocated. Not optional, bestie — it's the "please clear the table" of libuv 🧹✨

int uv_fs_close(uv_loop_t *loop, uv_fs_t *req, uv_file file, uv_fs_cb cb)

Equivalent to close(2) (yes, that one, over on the Linux man-pages at man7.org).

int uv_fs_open(uv_loop_t *loop, uv_fs_t *req, const char *path, int flags, int mode, uv_fs_cb cb)

Equivalent to open(2).

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. Not me finding out the hard way 😭

int uv_fs_read(uv_loop_t *loop, uv_fs_t *req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb)

Equivalent to preadv(2). If the offset argument is -1, then the current file offset is used and updated. Little detail, big consequences 💅

Warning: On Windows, under non-MSVC environments (e.g. when GCC or Clang is used to build libuv), files opened using UV_FS_O_FILEMAP may cause a fatal crash if the memory mapped read operation fails. Fr fr, be careful 💀

int uv_fs_unlink(uv_loop_t *loop, uv_fs_t *req, const char *path, uv_fs_cb cb)

Equivalent to unlink(2).

int uv_fs_write(uv_loop_t *loop, uv_fs_t *req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb)

Equivalent to pwritev(2). If the offset argument is -1, then the current file offset is used and updated. Same deal as read 🫶

Warning: On Windows, under non-MSVC environments (e.g. when GCC or Clang is used to build libuv), files opened using UV_FS_O_FILEMAP may cause a fatal crash if the memory mapped write operation fails. Same warning, write edition — it's giving déjà vu 🙈

int uv_fs_mkdir(uv_loop_t *loop, uv_fs_t *req, const char *path, int mode, uv_fs_cb cb)

Equivalent to mkdir(2).

Note: mode is currently not implemented on Windows. Windows said "no thanks" 💀

int uv_fs_mkdtemp(uv_loop_t *loop, uv_fs_t *req, const char *tpl, uv_fs_cb cb)

Equivalent to mkdtemp(3). The result can be found as a null terminated string at req->path. Cute, it tells you where it put the directory 🎀

int uv_fs_mkstemp(uv_loop_t *loop, uv_fs_t *req, const char *tpl, uv_fs_cb cb)

Equivalent to mkstemp(3). The created file path can be found as a null terminated string at req->path, and the file descriptor can be found as an integer at req->result. Two-for-one, we love to see it 👑

Added in version 1.34.0.

int uv_fs_rmdir(uv_loop_t *loop, uv_fs_t *req, const char *path, uv_fs_cb cb)

Equivalent to rmdir(2).

int uv_fs_opendir(uv_loop_t *loop, uv_fs_t *req, const char *path, uv_fs_cb cb)

Opens path as a directory stream. On success, a uv_dir_t is allocated and returned via req->ptr. Okay, crucial thing: this memory is NOT freed by uv_fs_req_cleanup(), even though req->ptr gets set to NULL. You have to free that allocated memory yourself by calling uv_fs_closedir(). On failure, no memory is allocated. Don't leak, bestie, it's not the vibe 😭💧

The contents of the directory can be iterated over by passing the resulting uv_dir_t to uv_fs_readdir().

Added in version 1.28.0.

int uv_fs_closedir(uv_loop_t *loop, uv_fs_t *req, uv_dir_t *dir, uv_fs_cb cb)

Closes the directory stream represented by dir and frees the memory allocated by uv_fs_opendir(). The circle is complete, the memory is released, we love a clean exit 🌈

Added in version 1.28.0.

int uv_fs_readdir(uv_loop_t *loop, uv_fs_t *req, uv_dir_t *dir, uv_fs_cb cb)

Iterates over the directory stream dir returned by a successful uv_fs_opendir() call. Before you invoke uv_fs_readdir(), the caller must set dir->dirents and dir->nentries, representing the array of uv_dirent_t elements used to hold the read directory entries and its size. You set up the lil bucket, libuv pours the entries in 🍓

On success, the result is an integer >= 0 representing the number of entries read from the stream. Zero means you're at the end, so don't panic 🔥

Added in version 1.28.0.

Warning: uv_fs_readdir() is not thread safe. Like, do not share it across threads, bestie, I'm serious 😭

Note: This function does not return the "." and ".." entries. So don't go looking for them, they're not invited to this party 💅

Note: On success this function allocates memory that must be freed using uv_fs_req_cleanup(). And uv_fs_req_cleanup() must be called before closing the directory with uv_fs_closedir(). Order matters, okay? 🫶

---

int uv_fs_scandir(uv_loop_t *loop, uv_fs_t *req, const char *path, int flags, uv_fs_cb cb)

int uv_fs_scandir_next(uv_fs_t *req, uv_dirent_t *ent)

Okay so uv_fs_scandir_next() is basically the same energy as scandir(3) — here's the man page if you wanna peek: https://man7.org/linux/man-pages/man3/scandir.3.html — but the API is slightly different, because of course it is ✨

Once the callback for the request gets called, you can use uv_fs_scandir_next() to get ent populated with the next directory entry's data. When there are no more entries, UV_EOF will be returned. That's the "we're done here" signal 🎀

Note: Unlike scandir(3), this function does not return the "." and ".." entries. Again. They are not coming. Accept it 🙈

Note: On Linux, getting the type of an entry is only supported by some file systems — at the time of this writing: btrfs, ext2, ext3 and ext4. Check the getdents(2) man page for the full tea: https://man7.org/linux/man-pages/man2/getdents.2.html 🍓

---

int uv_fs_stat(uv_loop_t *loop, uv_fs_t *req, const char *path, uv_fs_cb cb)

int uv_fs_fstat(uv_loop_t *loop, uv_fs_t *req, uv_file file, uv_fs_cb cb)

int uv_fs_lstat(uv_loop_t *loop, uv_fs_t *req, const char *path, uv_fs_cb cb)

These three are equivalent to stat(2), fstat(2) and lstat(2) respectively. Respectively is doing a lot of work there, but slay 💅

Man pages for the curious: https://man7.org/linux/man-pages/man2/stat.2.html https://man7.org/linux/man-pages/man2/fstat.2.html https://man7.org/linux/man-pages/man2/lstat.2.html

---

int uv_fs_statfs(uv_loop_t *loop, uv_fs_t *req, const char *path, uv_fs_cb cb)

Equivalent to statfs(2) — yep, here's the link: https://man7.org/linux/man-pages/man2/statfs.2.html ✨

On success, a uv_statfs_t is allocated and returned via req->ptr. This memory is freed by uv_fs_req_cleanup(). So yeah, cleanup is your bestie, don't ghost it 🫶

Note: Any fields in the resulting uv_statfs_t that are not supported by the underlying operating system are set to zero. No cap, they just zero out 🧚

Added in version 1.31.0. 👑

---

int uv_fs_rename(uv_loop_t *loop, uv_fs_t *req, const char *path, const char *new_path, uv_fs_cb cb)

Equivalent to rename(2). Link for the lore: https://man7.org/linux/man-pages/man2/rename.2.html 🦋

---

int uv_fs_fsync(uv_loop_t *loop, uv_fs_t *req, uv_file file, uv_fs_cb cb)

Equivalent to fsync(2). Here's the man page: https://man7.org/linux/man-pages/man2/fsync.2.html 🌸

Note: For AIX, uv_fs_fsync returns UV_EBADF on file descriptors referencing non regular files. AIX said "not today" 💀

---

int uv_fs_fdatasync(uv_loop_t *loop, uv_fs_t *req, uv_file file, uv_fs_cb cb)

Equivalent to fdatasync(2). Link: https://man7.org/linux/man-pages/man2/fdatasync.2.html ⭐

---

int uv_fs_ftruncate(uv_loop_t *loop, uv_fs_t *req, uv_file file, int64_t offset, uv_fs_cb cb)

Equivalent to ftruncate(2). Link: https://man7.org/linux/man-pages/man2/ftruncate.2.html 🎀

---

int uv_fs_copyfile(uv_loop_t *loop, uv_fs_t *req, const char *path, const char *new_path, int flags, uv_fs_cb cb)

Copies a file from path to new_path. The supported flags are giving very much "choose your fighter" and they're described below 👇

• UV_FS_COPYFILE_EXCL — If present, uv_fs_copyfile() will fail with UV_EEXIST if the destination path already exists. The default behavior is to overwrite the destination if it exists. So if you want it to be exclusive, say it with your chest 💅
• UV_FS_COPYFILE_FICLONE — If present, uv_fs_copyfile() will attempt to create a copy-on-write reflink. If the underlying platform does not support copy-on-write, or an error occurs while attempting to use copy-on-write, a fallback copy mechanism based on uv_fs_sendfile() is used. Lowkey resilient 🦋
• UV_FS_COPYFILE_FICLONE_FORCE — If present, uv_fs_copyfile() will attempt to create a copy-on-write reflink. If the underlying platform does not support copy-on-write, or an error occurs while attempting to use copy-on-write, then an error is returned. No fallback, no backup plan, just vibes and consequences 😭

Warning: If the destination path is created, but an error occurs while copying the data, then the destination path is removed. There is a brief window of time between closing and removing the file where another process could access the file. So yeah, tiny race window, keep that in mind, bestie 🫶

Added in version 1.14.0.

Changed in version 1.20.0: UV_FS_COPYFILE_FICLONE and UV_FS_COPYFILE_FICLONE_FORCE are supported.

Changed in version 1.33.0: If an error occurs while using UV_FS_COPYFILE_FICLONE_FORCE, that error is returned. Previously, all errors were mapped to UV_ENOTSUP. Glow-up behavior ✨

---

int uv_fs_sendfile(uv_loop_t *loop, uv_fs_t *req, uv_file out_fd, uv_file in_fd, int64_t in_offset, size_t length, uv_fs_cb cb)

Limited equivalent to sendfile(2). Link: https://man7.org/linux/man-pages/man2/sendfile.2.html 🌈

---

int uv_fs_access(uv_loop_t *loop, uv_fs_t *req, const char *path, int mode, uv_fs_cb cb)

Equivalent to access(2) on Unix. Windows uses GetFileAttributesW(). Platform differences, classic 🙈

Link: https://man7.org/linux/man-pages/man2/access.2.html 🍓

---

int uv_fs_chmod(uv_loop_t *loop, uv_fs_t *req, const char *path, int mode, uv_fs_cb cb)

int uv_fs_fchmod(uv_loop_t *loop, uv_fs_t *req, uv_file file, int mode, uv_fs_cb cb)

Equivalent to chmod(2) and fchmod(2) respectively. Respectively again, iconic 💅

Links: https://man7.org/linux/man-pages/man2/chmod.2.html https://man7.org/linux/man-pages/man2/fchmod.2.html

---

int uv_fs_utime(uv_loop_t *loop, uv_fs_t *req, const char *path, double atime, double mtime, uv_fs_cb cb)

int uv_fs_futime(uv_loop_t *loop, uv_fs_t *req, uv_file file, double atime, double mtime, uv_fs_cb cb)

int uv_fs_lutime(uv_loop_t *loop, uv_fs_t *req, const char *path, double atime, double mtime, uv_fs_cb cb)

Equivalent to utime(2), futimes(3) and lutimes(3) respectively. Timestamp besties 🎀

Links: https://man7.org/linux/man-pages/man2/utime.2.html https://man7.org/linux/man-pages/man3/futimes.3.html https://man7.org/linux/man-pages/man3/lutimes.3.html

Passing UV_FS_UTIME_NOW as the atime or mtime sets the timestamp to the current time. "Now" means now, periodt ⏰

Passing UV_FS_UTIME_OMIT as the atime or mtime leaves the timestamp untouched. Leave it alone, it's fine 💅

Note: z/OS: uv_fs_lutime() is not implemented for z/OS. It can still be called but will return UV_ENOSYS. So it exists, but it's not doing the thing 😭

Note: AIX: uv_fs_futime() and uv_fs_lutime() functions only work for AIX 7.1 and newer. They can still be called on older versions but will return UV_ENOSYS. AIX said "version check, babe" 💀

Changed in version 1.10.0: sub-second precission is supported on Windows. Yes, "precission" — that's the spelling in the original, don't come for me 🙈

---

int uv_fs_link(uv_loop_t *loop, uv_fs_t *req, const char *path, const char *new_path, uv_fs_cb cb)

Equivalent to link(2). Link: https://man7.org/linux/man-pages/man2/link.2.html 🔥

---

int uv_fs_symlink(uv_loop_t *loop, uv_fs_t *req, const char *path, const char *new_path, int flags, uv_fs_cb cb)

Equivalent to symlink(2). Link: https://man7.org/linux/man-pages/man2/symlink.2.html 🦋

Note: On Windows the flags parameter can be specified to control how the symlink will be created:

• UV_FS_SYMLINK_DIR — indicates that path points to a directory. Directory energy 👑
• UV_FS_SYMLINK_JUNCTION — request that the symlink is created using junction points. Junction points, fancy 💅

---

int uv_fs_readlink(uv_loop_t *loop, uv_fs_t *req, const char *path, uv_fs_cb cb)

Equivalent to readlink(2). Link: https://man7.org/linux/man-pages/man2/readlink.2.html ✨

The resulting string is stored in req->ptr. So that's where the magic lives 🎀

---

int uv_fs_realpath(uv_loop_t *loop, uv_fs_t *req, const char *path, uv_fs_cb cb)

Equivalent to realpath(3) on Unix. Windows uses GetFinalPathNameByHandleW — link if you're nosy: https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfinalpathnamebyhandlew 🌸

The resulting string is stored in req->ptr. Same spot as readlink, cute 🌈

Warning: This function has certain platform-specific caveats that were discovered when used in Node. Not me being dramatic, this is literally in the notes 😭

• macOS and other BSDs: this function will fail with UV_ELOOP if more than 32 symlinks are found while resolving the given path. This limit is hardcoded and cannot be sidestepped. Thirty-two. That's the number. No negotiating 💀
• Windows: while this function works in the common case, there are a number of corner cases where it doesn't:
  • Paths in ramdisk volumes created by tools which sidestep the Volume Manager (such as ImDisk) cannot be resolved.
  • Inconsistent casing when using drive letters.
  • Resolved path bypasses subst'd drives.

While this function can still be used, it's not recommended if scenarios such as the above need to be supported. So like, use it, but know the limits, bestie 🫶

The background story and some more details on these issues can be checked here: https://github.com/nodejs/node/issues/7726 🍓

Added in version 1.8.0.

---

int uv_fs_chown(uv_loop_t *loop, uv_fs_t *req, const char *path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb)

int uv_fs_fchown(uv_loop_t *loop, uv_fs_t *req, uv_file file, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb)

Ownership change besties, uid and gid and all that 👑

• int uv_fs_lchown(uv_loop_t *loop, uv_fs_t *req, const char *path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb) — bestie this is the ownership-change squad 💅 it's equivalent to chown(2), fchown(2) and lchown(2) respectively.

Note: these functions are not implemented on Windows 🚫🪟

Changed in version 1.21.0: uv_fs_lchown got implemented. slay.

• uv_fs_type uv_fs_get_type(const uv_fs_t *req) — hands you back req->fs_type. that's it, that's the whole vibe ✨

Added in version 1.19.0.

• ssize_t uv_fs_get_result(const uv_fs_t *req) — returns req->result. short king of a getter 🫶

Added in version 1.19.0.

• int uv_fs_get_system_error(const uv_fs_t *req) — gives you the platform-specific error code: that's the GetLastError() value on Windows, and -(req->result) everywhere else 🪟🆚🐧

Added in version 1.19.0. (no wait — Added in version 1.38.0, my bad 💀)

• void *uv_fs_get_ptr(const uv_fs_t *req) — returns req->ptr. pointer reveal 🔍

Added in version 1.19.0.

• const char *uv_fs_get_path(const uv_fs_t *req) — returns req->path. the path is giving main character energy 🌈

Added in version 1.19.0.

• uv_stat_t *uv_fs_get_statbuf(uv_fs_t *req) — returns &req->statbuf. literally just the address, no cap ✨

Added in version 1.19.0.

See also: the uv_req_t API functions also apply 🫶

---

🛠️ Helper functions 🛠️

• uv_os_fd_t uv_get_osfhandle(int fd) — you hand it a file descriptor from the C runtime, and it gives you back the OS-dependent handle. On UNIX it returns the fd intact, untouched, iconic. On Windows it calls _get_osfhandle (https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/get-osfhandle?view=vs-2019).

ngl this is the important part: the return value is still owned by the C runtime, so any attempts to close it or to use it after closing the fd may lead to malfunction 😭 don't do it bestie.

Added in version 1.12.0.

• int uv_open_osfhandle(uv_os_fd_t os_fd) — the reverse situation 🔁 give it an OS-dependent handle and it gives you the file descriptor in the C runtime. On UNIX it returns the os_fd intact. On Windows it calls _open_osfhandle (https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/open-osfhandle?view=vs-2019).

and fr fr, this one consumes the argument, so any attempts to close it or to use it after closing the return value may lead to malfunction 🙈

Added in version 1.23.0.

---

🚪 File open constants 🚪

• UV_FS_O_APPEND — file opens in append mode. before every single write, the file offset gets moved to the end of the file. periodt. 📎
• UV_FS_O_CREAT — the file gets created if it doesn't already exist. baby's first file 🐣
• UV_FS_O_DIRECT — file I/O goes directly to and from user-space buffers, which must be aligned. buffer size and address should be a multiple of the physical sector size of the block device. we love an alignment queen 📐

Note: UV_FS_O_DIRECT is supported on Linux, and on Windows via FILE_FLAG_NO_BUFFERING (https://learn.microsoft.com/en-us/windows/win32/fileio/file-buffering). UV_FS_O_DIRECT is not supported on macOS 🍎💔

• UV_FS_O_DIRECTORY — if the path isn't a directory, fail the open. no imposters allowed 🚫

Note: UV_FS_O_DIRECTORY is not supported on Windows.

• UV_FS_O_DSYNC — file opens for synchronous I/O. write operations complete once all data and a minimum of metadata are flushed to disk. lowkey thorough 💾

Note: UV_FS_O_DSYNC is supported on Windows via FILE_FLAG_WRITE_THROUGH (https://learn.microsoft.com/en-us/windows/win32/fileio/file-buffering).

• UV_FS_O_EXCL — if the O_CREAT flag is set and the file already exists, fail the open. exclusive much? 💅

Note: in general, the behavior of O_EXCL is undefined if it's used without O_CREAT 😬 there is one exception though: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. if the block device is in use by the system (e.g., mounted), the open will fail with the error EBUSY.

• UV_FS_O_EXLOCK — atomically obtain an exclusive lock. lock it down 🔒

Note: UV_FS_O_EXLOCK is only supported on macOS and Windows.

Changed in version 1.17.0: support is added for Windows.

• UV_FS_O_FILEMAP — use a memory file mapping to access the file. when you use this flag, the file cannot be open multiple times concurrently 🚨

Note: UV_FS_O_FILEMAP is only supported on Windows.

• UV_FS_O_NOATIME — don't update the file access time when the file is read. time is fake anyway ⏰✨

Note: UV_FS_O_NOATIME is not supported on Windows.

• UV_FS_O_NOCTTY — if the path identifies a terminal device, opening that path will not cause the terminal to become the controlling terminal for the process (if the process doesn't already have one). no stealing the spotlight 👑

Note: UV_FS_O_NOCTTY is not supported on Windows.

• UV_FS_O_NOFOLLOW — if the path is a symbolic link, fail the open. we don't follow, we lead 🦋

Note: UV_FS_O_NOFOLLOW is not supported on Windows.

• UV_FS_O_NONBLOCK — open the file in nonblocking mode if possible. no waiting around 💨

Note: UV_FS_O_NONBLOCK is not supported on Windows.

• UV_FS_O_RANDOM — access is intended to be random. the system can use this as a hint to optimize file caching. chaos but make it efficient 🎲

Note: UV_FS_O_RANDOM is only supported on Windows via FILE_FLAG_RANDOM_ACCESS (https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew).

• UV_FS_O_RDONLY — open the file for read-only access. look, don't touch 👀
• UV_FS_O_RDWR — open the file for read-write access. touch and look, both 💖
• UV_FS_O_SEQUENTIAL — access is intended to be sequential from beginning to end. the system can use this as a hint to optimize file caching. start to finish, no detours 🚂

Note: UV_FS_O_SEQUENTIAL is only supported on Windows via FILE_FLAG_SEQUENTIAL_SCAN (https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew).

• UV_FS_O_SHORT_LIVED — the file is temporary and should not be flushed to disk if possible. here for a short time, not a long time 🧚

Note: UV_FS_O_SHORT_LIVED is only supported on Windows via FILE_ATTRIBUTE_TEMPORARY (https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew).

• UV_FS_O_SYMLINK — open the symbolic link itself rather than the resource it points to. the link is the moment 🔗
• UV_FS_O_SYNC — file opens for synchronous I/O. write operations complete once all data and all metadata are flushed to disk. the full send 💾🔥

Note: UV_FS_O_SYNC is supported on Windows via FILE_FLAG_WRITE_THROUGH (https://learn.microsoft.com/en-us/windows/win32/fileio/file-buffering).

• UV_FS_O_TEMPORARY — the file is temporary and should not be flushed to disk if possible. (yes, this is basically twins with UV_FS_O_SHORT_LIVED, don't come for me 😭)

Note: UV_FS_O_TEMPORARY is only supported on Windows via FILE_ATTRIBUTE_TEMPORARY (https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew).

• UV_FS_O_TRUNC — if the file exists and is a regular file, and the file is opened successfully for write access, its length shall be truncated to zero. bye bye content ✂️
• UV_FS_O_WRONLY — open the file for write-only access. speak, don't listen 🗣️

---

🧵 Thread pool work scheduling 🧵

okay so libuv gives you a threadpool 🫶 you can use it to run your own code and get notified back on the loop thread. this pool is used internally for all the file system operations, plus getaddrinfo and getnameinfo requests. it's doing a lot, basically.

its default size is 4, but you can change it at startup time by setting the UV_THREADPOOL_SIZE environment variable to any value (the absolute maximum is 1024). ✨

Changed in version 1.30.0: the maximum UV_THREADPOOL_SIZE allowed was increased from 128 to 1024. glow up 📈

Changed in version 1.45.0: threads now have an 8 MB stack instead of the (sometimes too low) platform default. room to breathe 🌬️

Changed in version 1.50.0: threads now have a default name of libuv-worker. they have names now, we stan 🎀

the threadpool is global and shared across all event loops. when a particular function makes use of the threadpool (e.g. when using uv_queue_work()), libuv preallocates and initializes the maximum number of threads allowed by UV_THREADPOOL_SIZE. more threads usually means more throughput but a higher memory footprint. thread stacks grow lazily on most platforms though, so no cap on the dramatics 💅

Note: even though a global thread pool shared across all event loops is used, the functions are not thread safe. fr fr, don't try it 😭

---

📦 Data types 📦

• type uv_work_t — work request type. that's the whole description bestie, it's a type 🫶
• typedef void (*uv_work_cb)(uv_work_t *req) — the callback you pass to uv_queue_work(), which will be run on the thread pool. the pool girlies are on it 🏊
• typedef void (*uv_after_work_cb)(uv_work_t *req, int status) — the callback you pass to uv_queue_work() which gets called on the loop thread after the work on the threadpool has been completed. if the work was cancelled using uv_cancel(), status will be UV_ECANCELED 🚫

---

👀 Public members 👀

• uv_loop_t *uv_work_t.loop — the loop that started this request and where completion will be reported. Readonly. no touching 🔒

See also: the uv_req_t members also apply 🫶

---

🔌 API 🔌

• int uv_queue_work(uv_loop_t *loop, uv_work_t *req, uv_work_cb work_cb, uv_after_work_cb after_work_cb) — initializes a work request which will run the given work_cb in a thread from the threadpool. once work_cb is completed, after_work_cb will be called on the loop thread. cute lil assembly line 🏭✨

this request can be cancelled with uv_cancel(). iconic escape hatch 💅

See also: the uv_req_t API functions also apply.

---

🌐 DNS utility functions 🌐

libuv provides asynchronous variants of getaddrinfo and getnameinfo. async queen behavior, no blocking on my watch ⭐

🏷️ Data types 🏷️

• type uv_getaddrinfo_t — getaddrinfo request type.
• typedef void (*uv_getaddrinfo_cb)(uv_getaddrinfo_t *req, int status, struct addrinfo *res) — callback which will be called with the getaddrinfo request result once complete. in case it was cancelled, status will have a value of UV_ECANCELED 🚫🦋
• type uv_getnameinfo_t — getnameinfo request type.
• typedef void (*uv_getnameinfo_cb)(uv_getnameinfo_t *req, int status, const char *hostname, const char *service) — this is the callback that gets summoned the moment your getnameinfo request is done, bestie. It hands you req, status, hostname and service. Oh and if the whole thing got cancelled? Then status comes back as UV_ECANCELED 💀 so don't panic, that's just what canceled looks like.

---

🧸 Public members

• uv_loop_t *uv_getaddrinfo_t.loop — the loop that kicked off this getaddrinfo request and where the completion gets reported back to you. Readonly, so hands off 🫶
• struct addrinfo *uv_getaddrinfo_t.addrinfo — pointer to a struct addrinfo holding the actual result. You must free this yourself with uv_freeaddrinfo(), no cap. Also: Changed in version 1.3.0: the field is declared as public ✨
• uv_loop_t *uv_getnameinfo_t.loop — the loop that started this getnameinfo request and where the completion gets reported. Readonly again, same energy 💅
• char[NI_MAXHOST] uv_getnameinfo_t.host — a char array holding the resulting host. It's null terminated, iconic behavior. Changed in version 1.3.0: the field is declared as public 🌸
• char[NI_MAXSERV] uv_getnameinfo_t.service — char array holding the resulting service, also null terminated, also public since Changed in version 1.3.0 🎀

See also: the uv_req_t members apply here too, bestie 👑

---

🛠️ API

• int uv_getaddrinfo(uv_loop_t *loop, uv_getaddrinfo_t *req, uv_getaddrinfo_cb getaddrinfo_cb, const char *node, const char *service, const struct addrinfo *hints) — asynchronous getaddrinfo(3), the async glow-up of the classic.

So like, either node or service can be NULL, but not both — that's the one rule, don't break it 🙈

hints is a pointer to a struct addrinfo with extra address type constraints, or NULL. Go consult man -s 3 getaddrinfo for the full lore.

Returns 0 on success or an error code < 0 on failure. If it worked, the callback gets called sometime in the future with the lookup result, which is literally either:

• status == 0, and the res argument points to a valid struct addrinfo, or
• status < 0, and the res argument is NULL. Check the UV_EAI_* constants for what went down.

Call uv_freeaddrinfo() to free the addrinfo structure — it's giving "you break it, you bought it" 💖

Changed in version 1.3.0: the callback parameter is now allowed to be NULL, and in that case the request will run synchronously. Yes bestie, sync mode, main character energy 🔥

• void uv_freeaddrinfo(struct addrinfo *ai) — frees the struct addrinfo. Passing NULL is allowed and is a total no-op, so honestly very forgiving of you 🌈
• int uv_getnameinfo(uv_loop_t *loop, uv_getnameinfo_t *req, uv_getnameinfo_cb getnameinfo_cb, const struct sockaddr *addr, int flags) — asynchronous getnameinfo(3), the name-lookup cousin.

Returns 0 on success or an error code < 0 on failure. If it succeeded, the callback gets called sometime in the future with the lookup result. Consult man -s 3 getnameinfo for the details, iykyk.

Changed in version 1.3.0: the callback parameter is now allowed to be NULL, and in that case the request will run synchronously ✨

See also: the uv_req_t API functions apply here too 🫶

---

📚 Shared library handling

libuv hooks you up with cross-platform utilities for loading shared libraries and pulling symbols out of them, using this API right here. Very "borrowing code from your friend's project" of it 💅

🗂️ Data types

• type uv_lib_t — the shared library data type. That's it, that's the whole thing.

🧸 Public members

• N/A — none. Nothing. Empty. The void. 🕳️

🛠️ API

• int uv_dlopen(const char *filename, uv_lib_t *lib) — opens a shared library. filename is in utf-8. Returns 0 on success and -1 on error. Then call uv_dlerror() to get the actual error message, because -1 alone is not the vibe 😭
• void uv_dlclose(uv_lib_t *lib) — closes the shared library. Closing time, you don't gotta go home but you can't stay here 🎀
• int uv_dlsym(uv_lib_t *lib, const char *name, void **ptr) — retrieves a data pointer from a dynamic library. Fun fact: it is legal for a symbol to map to NULL — yes, NULL can be a real answer, don't @ me. Returns 0 on success and -1 if the symbol was not found 🌸
• const char *uv_dlerror(const uv_lib_t *lib) — returns the last uv_dlopen() or uv_dlsym() error message. Your receipts, basically 🧾

---

🧵 Threading and synchronization utilities

libuv gives you cross-platform implementations for a whole squad of threading and synchronization primitives. The API largely follows the pthreads API, so if you know that one you're already slaying 💜

🗂️ Data types

• type uv_thread_t — thread data type.
• typedef void (*uv_thread_cb)(void *arg) — the callback invoked to initialize thread execution. arg is the same value you passed to uv_thread_create(), so it comes right back to you 🦋
• type uv_key_t — thread-local key data type.
• type uv_once_t — once-only initializer data type.
• type uv_mutex_t — mutex data type.
• type uv_rwlock_t — read-write lock data type.
• type uv_sem_t — semaphore data type.
• type uv_cond_t — condition data type.
• type uv_barrier_t — barrier data type.

🛠️ API

🧵 Threads

• type uv_thread_options_t — options for spawning a new thread, passed to uv_thread_create_ex(). Here's the whole struct, keep it exact bestie:

typedef struct uv_thread_options_s {
  enum {
    UV_THREAD_NO_FLAGS = 0x00,
    UV_THREAD_HAS_STACK_SIZE = 0x01
  } flags;
  size_t stack_size;
} uv_thread_options_t;

Heads up: more fields may be added to this struct at any time, so its exact layout and size should not be relied upon. It's giving "living document" 🫠

Added in version 1.26.0.

• int uv_thread_create(uv_thread_t *tid, uv_thread_cb entry, void *arg) — Changed in version 1.4.1: returns a UV_E* error code on failure. So now you actually get told what went wrong, we love growth 🌱
• int uv_thread_detach(uv_thread_t *tid) — detaches a thread. Detached threads automatically release their resources upon termination, eliminating the need for the application to call uv_thread_join. Set it free, it'll clean up after itself 🦋 Added in version 1.26.0... wait, no — Added in version 1.50.0. ✨
• int uv_thread_create_ex(uv_thread_t *tid, const uv_thread_options_t *params, uv_thread_cb entry, void *arg) — like uv_thread_create(), but with bonus options for creating a new thread 👑

If UV_THREAD_HAS_STACK_SIZE is set, then stack_size specifies a stack size for the new thread. A 0 means "use the default value", i.e. it behaves exactly as if the flag was not set. Any other value gets rounded up to the nearest page boundary — math is math 📐

Added in version 1.26.0.

• int uv_thread_setaffinity(uv_thread_t *tid, char *cpumask, char *oldmask, size_t mask_size) — sets the specified thread's affinity to cpumask, which is specified in bytes. Optionally it also returns the previous affinity setting in oldmask — a little before-and-after pic 📸

On Unix, it uses pthread_getaffinity_np(3) to get the affinity setting and maps the cpu_set_t to bytes in oldmask. Then it maps the bytes in cpumask to a cpu_set_t and uses pthread_setaffinity_np(3). On Windows, it maps the bytes in cpumask to a bitmask and uses SetThreadAffinityMask(), which returns the previous affinity setting.

mask_size specifies the number of entries (bytes) in cpumask / oldmask, and must be greater-than-or-equal-to uv_cpumask_size() 💅

Note: thread affinity setting is not atomic on Windows. Unsupported on macOS. So like, plan accordingly bestie 😭

Added in version 1.45.0.

• int uv_thread_getaffinity(uv_thread_t *tid, char *cpumask, size_t mask_size) — gets the specified thread's affinity setting. On Unix, this maps the cpu_set_t returned by pthread_getaffinity_np(3) to bytes in cpumask.

mask_size specifies the number of entries (bytes) in cpumask, and must be greater-than-or-equal-to uv_cpumask_size() 🌸

Note: thread affinity getting is not atomic on Windows. Unsupported on macOS. Again. Same energy 💀

Added in version 1.45.0.

• int uv_thread_getcpu(void) — gets the CPU number on which the calling thread is running. Where am I? On which core? The mystery is solved 🔍

Note: currently only implemented on Windows, Linux and FreeBSD. Everywhere else it's just vibes 🫠

Added in version 1.45.0.

• uv_thread_t uv_thread_self(void) — gives you the current thread. Your own little self 🪞
• int uv_thread_join(uv_thread_t *tid) — waits for that thread to finish up. The "I'm not leaving without you" of functions 🫶
• int uv_thread_equal(const uv_thread_t *t1, const uv_thread_t *t2) — checks whether t1 and t2 are the same thread. Twin check 💕
• int uv_thread_setname(const char *name) — sets the name of the current thread. Every platform has its own limit on how many characters a thread name can be: Linux, IBM i (16), macOS (64), Windows (32767), and NetBSD (32), etc. uv_thread_setname() will truncate it in case name is larger than the platform's limit — sorry, your essay is getting cut ✂️

Not supported on Windows Server 2016, returns UV_ENOSYS. Rude, but okay.

Added in version 1.50.0.

• int uv_thread_getname(uv_thread_t *tid, char *name, size_t *size) — gets the name of the thread specified by tid. The thread name is copied, with the trailing NUL, into the buffer pointed to by name. The size parameter specifies the size of the buffer pointed to by name. The buffer should be large enough to hold the name of the thread plus the trailing NUL, or it will be truncated to fit with the trailing NUL. So like, size your buffer properly or lose letters 😬

It's undefined behavior to call this after the thread has terminated. Do not do that. Seriously, don't. ⚠️

Not supported on Windows Server 2016, returns UV_ENOSYS.

Added in version 1.50.0.

• int uv_thread_setpriority(uv_thread_t tid, int priority) — if the function succeeds, the return value is 0. If the function fails, the return value is less than zero. Sets the scheduling priority of the thread specified by tid. Some platforms require elevated privilege to set specific priorities — so like, you might need admin energy for this one 👑

The priority can be set to the following constants: UV_THREAD_PRIORITY_HIGHEST, UV_THREAD_PRIORITY_ABOVE_NORMAL, UV_THREAD_PRIORITY_NORMAL, UV_THREAD_PRIORITY_BELOW_NORMAL, UV_THREAD_PRIORITY_LOWEST.

It's undefined behavior to call this after the thread has terminated. Same warning, same drama 🫠

Added in version 1.48.0.

• int uv_thread_getpriority(uv_thread_t tid, int *priority) — returns 0 if it worked, and something less than zero if it flopped 😭. It grabs the scheduling priority of the thread you point at with tid, and the value that lands in the output param priority is platform dependent. On Linux, when the scheduling policy is SCHED_OTHER (the default), priority comes back as 0.

⚠️ Calling this after the thread has already terminated is undefined behavior. Do not do that, bestie. That's a vibe check you will fail 💀.

Added in version 1.48.0 ✨.

🧵 Thread-local storage

📌 Note: the total thread-local storage size may be limited. Like, it may literally not be possible to create a whole bunch of TLS keys. Budget accordingly 🎀.

• int uv_key_create(uv_key_t *key) — makes you a shiny new TLS key ✨
• void uv_key_delete(uv_key_t *key) — yeets the key into the void
• void *uv_key_get(uv_key_t *key) — reads the value hanging off that key
• void uv_key_set(uv_key_t *key, void *value) — sets the value on that key

🎯 Once-only initialization

Runs a function once and only once. Like, periodt 💅. When concurrent calls to uv_once() all show up with the same guard, every caller gets blocked except one — and it's unspecified which one gets the honor, so no favorites 👑. The guard should be initialized statically with the UV_ONCE_INIT macro.

• void uv_once(uv_once_t *guard, void (*callback)(void)) — the one-shot wonder

🔒 Mutex locks

All of these return 0 on success or an error code < 0 — unless the return type is void, of course, because then there's literally nothing to return 🙈.

• int uv_mutex_init(uv_mutex_t *handle) — spins up your mutex
• int uv_mutex_init_recursive(uv_mutex_t *handle) — same but recursive, so the same thread can lock it again, no drama
• void uv_mutex_destroy(uv_mutex_t *handle) — destroys it, free the memory, move on
• void uv_mutex_lock(uv_mutex_t *handle) — locks it (may block, that's the whole point)
• int uv_mutex_trylock(uv_mutex_t *handle) — tries to lock and does not block if it can't, so you get an answer immediately
• void uv_mutex_unlock(uv_mutex_t *handle) — unlocks it, release the vibes

📖 Read-write locks

Same deal: functions return 0 on success or an error code < 0 (unless the return type is void, obviously 💁).

• int uv_rwlock_init(uv_rwlock_t *rwlock) — initialize the rwlock
• void uv_rwlock_destroy(uv_rwlock_t *rwlock) — destroy it
• void uv_rwlock_rdlock(uv_rwlock_t *rwlock) — grab a read lock
• int uv_rwlock_tryrdlock(uv_rwlock_t *rwlock) — try for a read lock without committing
• void uv_rwlock_rdunlock(uv_rwlock_t *rwlock) — drop the read lock
• void uv_rwlock_wrlock(uv_rwlock_t *rwlock) — grab a write lock
• int uv_rwlock_trywrlock(uv_rwlock_t *rwlock) — try for a write lock, no blocking
• void uv_rwlock_wrunlock(uv_rwlock_t *rwlock) — drop the write lock

🚦 Semaphores

Again, friends: return 0 on success or an error code < 0 (unless it's void, you know the drill 😌).

• int uv_sem_init(uv_sem_t *sem, unsigned int value) — init the semaphore with an initial value
• void uv_sem_destroy(uv_sem_t *sem) — destroy it
• void uv_sem_post(uv_sem_t *sem) — post to it, bump it up
• void uv_sem_wait(uv_sem_t *sem) — wait on it
• int uv_sem_trywait(uv_sem_t *sem) — try to wait, but don't block if you can't

🌸 Conditions

Yeah yeah — 0 on success, error code < 0 on failure, unless the return type is void, as ever 💖.

📌 Note: 1. Callers should be prepared to deal with spurious wakeups on uv_cond_wait() and uv_cond_timedwait(). Like, it can just wake up for no reason. Handle it. Don't be weird about it 🙈. 2. The timeout parameter for uv_cond_timedwait() is relative to the time at which the function is called. Not absolute. Relative. ✨ 3. On z/OS, the timeout parameter for uv_cond_timedwait() gets converted into an absolute system time at which the wait expires 🕰️. If the current system clock time passes that calculated absolute time before the condition is signaled, you get an ETIMEDOUT error. Once the wait begins, the wait time is not affected by changes to the system clock. Iconic platform-specific behavior ngl.

• int uv_cond_init(uv_cond_t *cond) — init the condition
• void uv_cond_destroy(uv_cond_t *cond) — destroy it
• void uv_cond_signal(uv_cond_t *cond) — signal one waiter
• void uv_cond_broadcast(uv_cond_t *cond) — broadcast to literally everyone
• void uv_cond_wait(uv_cond_t *cond, uv_mutex_t *mutex) — wait on the condition with the given mutex
• int uv_cond_timedwait(uv_cond_t *cond, uv_mutex_t *mutex, uint64_t timeout) — wait, but with a timeout so you don't wait forever

🧱 Barriers

You already know: 0 on success, error code < 0 otherwise, unless the type is void 🌈.

📌 Note: uv_barrier_wait() returns a value > 0 to an arbitrarily chosen "serializer" thread to facilitate cleanup, i.e. c if (uv_barrier_wait(&barrier) > 0) uv_barrier_destroy(&barrier); One thread gets picked to do the cleanup chores. Main character energy 👑.

• int uv_barrier_init(uv_barrier_t *barrier, unsigned int count) — init the barrier with a count of threads
• void uv_barrier_destroy(uv_barrier_t *barrier) — destroy the barrier
• int uv_barrier_wait(uv_barrier_t *barrier) — wait at the barrier

🧰 Miscellaneous utilities

This is the catch-all section — the miscellaneous functions that don't really belong in any other section. The island of misfit toys 🧚.

🔮 Data types

uv_buf_t

Buffer data type. The blueprint of a buffer 💜.

• char *uv_buf_t.base — pointer to the base of the buffer
• size_t uv_buf_t.len — total bytes in the buffer

📌 Note: on Windows this field is ULONG.

typedef void *(*uv_malloc_func)(size_t size)

Replacement function for malloc(3). See uv_replace_allocator() 🫶.

typedef void *(*uv_realloc_func)(void *ptr, size_t size)

Replacement function for realloc(3). See uv_replace_allocator().

typedef void *(*uv_calloc_func)(size_t count, size_t size)

Replacement function for calloc(3). See uv_replace_allocator().

typedef void (*uv_free_func)(void *ptr)

Replacement function for free(3). See uv_replace_allocator().

typedef void (*uv_random_cb)(uv_random_t *req, int status, void *buf, size_t buflen)

The callback you pass to uv_random(). status is non-zero in case of error 😭. The buf pointer is the same pointer that was passed to uv_random() — no sneaky swaps, fr fr.

uv_file

Cross platform representation of a file handle 🗂️.

uv_os_sock_t

Cross platform representation of a socket handle 🔌.

uv_os_fd_t

Abstract representation of a file descriptor. On Unix systems this is a typedef of int and on Windows a HANDLE.

uv_pid_t

Cross platform representation of a pid_t 🌟.

Added in version 1.16.0.

uv_timeval_t

Y2K38-unsafe data type for storing times with microsecond resolution ⏳. Will be replaced with uv_timeval64_t in libuv v2.0.

typedef struct {
    long tv_sec;
    long tv_usec;
} uv_timeval_t;

uv_timeval64_t

Y2K38-safe data type for storing times with microsecond resolution 🛡️.

typedef struct {
    int64_t tv_sec;
    int32_t tv_usec;
} uv_timeval64_t;

uv_timespec64_t

Y2K38-safe data type for storing times with nanosecond resolution ✨.

typedef struct {
    int64_t tv_sec;
    int32_t tv_nsec;
} uv_timespec64_t;

enum uv_clock_id

Clock source for uv_clock_gettime() 🕰️.

typedef enum {
  UV_CLOCK_MONOTONIC,
  UV_CLOCK_REALTIME
} uv_clock_id;

uv_rusage_t

Data type for resource usage results 📊.

typedef struct {
    uv_timeval_t ru_utime; /* user CPU time used */
    uv_timeval_t ru_stime; /* system CPU time used */
    uint64_t ru_maxrss; /* maximum resident set size */
    uint64_t ru_ixrss; /* integral shared memory size (X) */
    uint64_t ru_idrss; /* integral unshared data size (X) */
    uint64_t ru_isrss; /* integral unshared stack size (X) */
    uint64_t ru_minflt; /* page reclaims (soft page faults) (X) */
    uint64_t ru_majflt; /* page faults (hard page faults) */
    uint64_t ru_nswap; /* swaps (X) */
    uint64_t ru_inblock; /* block input operations */
    uint64_t ru_oublock; /* block output operations */
    uint64_t ru_msgsnd; /* IPC messages sent (X) */
    uint64_t ru_msgrcv; /* IPC messages received (X) */
    uint64_t ru_nsignals; /* signals received (X) */
    uint64_t ru_nvcsw; /* voluntary context switches (X) */
    uint64_t ru_nivcsw; /* involuntary context switches (X) */
} uv_rusage_t;

Members marked with (X) are unsupported on Windows 🙅. See getrusage(2) for supported fields on UNIX-like platforms.

The maximum resident set size is reported in kilobytes — the unit most platforms use natively, so slay, no conversion needed 💅.

uv_cpu_info_t

Data type for CPU information 🔥.

typedef struct uv_cpu_info_s {
    char* model;
    int speed;
    struct uv_cpu_times_s {
        uint64_t user; /* milliseconds */
        uint64_t nice; /* milliseconds */
        uint64_t sys; /* milliseconds */
        uint64_t idle; /* milliseconds */
        uint64_t irq; /* milliseconds */
    } cpu_times;
} uv_cpu_info_t;

uv_interface_address_t

Data type for interface addresses 🌐.

typedef struct uv_interface_address_s {
    char* name;
    char phys_addr[6];
    int is_internal;
    union {
        struct sockaddr_in address4;
        struct sockaddr_in6 address6;
    } address;
    union {
        struct sockaddr_in netmask4;
        struct sockaddr_in6 netmask6;
    } netmask;
} uv_interface_address_t;

uv_passwd_t

Data type for password file information 🔑.

typedef struct uv_passwd_s {
    char* username;
    long uid;
    long gid;
    char* shell;
    char* homedir;
} uv_passwd_t;

uv_group_t

Data type for group file information 👯.

typedef struct uv_group_s {
  char* groupname;
  unsigned long gid;
  char** members;
} uv_group_t;

uv_utsname_t

Data type for operating system name and version information 🖥️.

typedef struct uv_utsname_s {
    char sysname[256];
    char release[256];
    char version[256];
    char machine[256];
} uv_utsname_t;

uv_env_item_t

Data type for environment variable storage 🌱.

                 typedef struct uv_env_item_s {
                     char* name;
                     char* value;
                 } uv_env_item_t;

…aaand uv_random_t, which is literally just a random data request type. that's it. that's the whole vibe. 🎲

---

✨ API ✨

okay bestie, here comes the fun part — this is the actual toolbox. every function gets its exact signature, so no guessing 💅

---

uv_handle_type uv_guess_handle(uv_file file)

Detects what kind of stream you should be using with a given file descriptor. normally you'd call this at init time to figure out what the stdio streams actually are — like, is this thing a TTY or a pipe, iykyk? 🔍

For isatty(3)-equivalent functionality, use this function and then test for UV_TTY.

---

int uv_replace_allocator(uv_malloc_func malloc_func, uv_realloc_func realloc_func, uv_calloc_func calloc_func, uv_free_func free_func)

Added in version 1.6.0.

This one lets you override the standard library's malloc(3), calloc(3), realloc(3) and free(3) memory allocation functions. absolute control, no cap. 👑

You must call this before any other libuv function is called — or, alternately, after all resources have been freed so libuv isn't referencing any allocated memory chunk. timing is everything, fr.

On success it returns 0. if any of the function pointers is NULL, it returns UV_EINVAL.

⚠️ Warning: there's no protection against changing the allocator multiple times. if the user changes it, they're responsible for making sure the allocator is changed while no memory was allocated with the previous allocator — or that the two allocators are compatible. so like… be careful.

⚠️ Warning: the allocator must be thread-safe. non-negotiable.

---

void uv_library_shutdown(void);

Added in version 1.38.0.

Releases any global state that libuv is holding onto. libuv normally does this automatically when it's unloaded, but you can tell it to do the cleanup manually if you want to be extra. 🧹

⚠️ Warning: only call uv_library_shutdown() once.

⚠️ Warning: don't call uv_library_shutdown() when there are still event loops or I/O requests active.

⚠️ Warning: don't call libuv functions after calling uv_library_shutdown(). like, at all. that's the end of the era.

---

uv_buf_t uv_buf_init(char *base, unsigned int len)

Constructor for uv_buf_t. 🍼

Because platforms are messy, the user can't rely on the ordering of the base and len members of the uv_buf_t struct. the user is responsible for freeing base after the uv_buf_t is done with. returns the struct passed by value.

⚠️ Warning: it's discouraged to set len to a large value, because that may result in spurious failures. specifically: Windows may fail on writes larger than about 511 MB, and various Unicies may fail on I/O larger than about 2 GB (0x7ffff000 bytes). instead it's generally better to split the data into multiple uv_write calls — attach the write_cb to the last one. 🧩

---

char **uv_setup_args(int argc, char **argv)

Stores the program arguments. this is required for getting/setting the process title, or the executable path. libuv may take ownership of the memory that argv points to. ⚠️ call this function exactly once, at program start-up. no seconds, no thirds.

Example:

                 argv = uv_setup_args(argc, argv);  /* May return a copy of argv. */

---

int uv_get_process_title(char *buffer, size_t size)

Gets the title of the current process. on Unix and AIX systems you must call uv_setup_args before calling this. if uv_setup_args hasn't been called on systems that require it, then UV_ENOBUFS is returned. if buffer is NULL or size is zero, UV_EINVAL is returned. if size can't accommodate the process title plus the terminating nul character, the function returns UV_ENOBUFS. 📛

📝 Note: on BSD systems, uv_setup_args is needed for getting the initial process title. the process title returned will be an empty string until either uv_setup_args or uv_set_process_title is called.

Changed in version 1.18.1: now thread-safe on all supported platforms.

Changed in version 1.39.0: now returns an error if uv_setup_args is needed but hasn't been called.

---

int uv_set_process_title(const char *title)

Sets the current process title. on Unix and AIX systems you must call uv_setup_args before calling this. if uv_setup_args hasn't been called on systems that require it, then UV_ENOBUFS is returned. on platforms with a fixed size buffer for the process title, the contents of title will be copied into the buffer and truncated if it's larger than the available space. other platforms will return UV_ENOMEM if they can't allocate enough space to duplicate the contents of title. ✍️

Changed in version 1.18.1: now thread-safe on all supported platforms.

Changed in version 1.39.0: now returns an error if uv_setup_args is needed but hasn't been called.

---

int uv_resident_set_memory(size_t *rss)

Gets the resident set size (RSS) for the current process. memory check, bestie. 🧠

---

int uv_uptime(double *uptime)

Gets the current system uptime. depending on the system, you get full or fractional seconds back. ⏰

---

int uv_getrusage(uv_rusage_t *rusage)

Gets the resource usage measures for the current process. 📊

📝 Note: on Windows not all fields are set — the unsupported fields are filled with zeroes. see uv_rusage_t for more details.

---

int uv_getrusage_thread(uv_rusage_t *rusage)

Gets the resource usage measures for the calling thread. 🧵

Added in version 1.50.0.

📝 Note: not supported on all platforms. may return UV_ENOTSUP. on macOS and Windows not all fields are set — the unsupported fields are filled with zeroes. see uv_rusage_t for more details.

---

uv_pid_t uv_os_getpid(void)

Returns the current process ID. 🪪

Added in version 1.18.0.

---

uv_pid_t uv_os_getppid(void)

Returns the parent process ID. hi mom 👋

Added in version 1.16.0.

---

unsigned int uv_available_parallelism(void)

Returns an estimate of the default amount of parallelism a program should use. always returns a non-zero value. 💪

On Linux, it inspects the calling thread's CPU affinity mask to determine whether it's been pinned to specific CPUs.

On Windows, the available parallelism may be underreported on systems with more than 64 logical CPUs.

On other platforms, it reports the number of CPUs that the operating system considers to be online.

Added in version 1.44.0.

---

int uv_cpu_info(uv_cpu_info_t **cpu_infos, int *count)

Gets information about the CPUs on the system. the cpu_infos array will have count elements and needs to be freed with uv_free_cpu_info(). 🖥️✨

Use uv_available_parallelism() if you actually need to know how many CPUs are available for threads or child processes.

---

void uv_free_cpu_info(uv_cpu_info_t *cpu_infos, int count)

Frees the cpu_infos array previously allocated with uv_cpu_info(). bye bye memory 🫶

---

int uv_cpumask_size(void)

Returns the maximum size of the mask used for process/thread affinities — or UV_ENOTSUP if affinities aren't supported on the current platform. 🎭

Added in version 1.45.0.

---

int uv_interface_addresses(uv_interface_address_t **addresses, int *count)

Gets address information about the network interfaces on the system. an array of count elements is allocated and returned in addresses. the user must free it by calling uv_free_interface_addresses(). 🌐

---

void uv_free_interface_addresses(uv_interface_address_t *addresses, int count)

Frees an array of uv_interface_address_t which was returned by uv_interface_addresses(). 🗑️

---

void uv_loadavg(double avg[3])

Gets the load average. see: https://en.wikipedia.org/wiki/Load_(computing) 📈

📝 Note: returns [0,0,0] on Windows (i.e., it's not implemented). we don't talk about that.

---

int uv_ip4_addr(const char *ip, int port, struct sockaddr_in *addr)

Converts a string containing an IPv4 address into a binary structure. 🔢

---

int uv_ip6_addr(const char *ip, int port, struct sockaddr_in6 *addr)

Converts a string containing an IPv6 address into a binary structure. 🔢

---

int uv_ip4_name(const struct sockaddr_in *src, char *dst, size_t size)

Converts a binary structure containing an IPv4 address into a string. 🔤

---

int uv_ip6_name(const struct sockaddr_in6 *src, char *dst, size_t size)

Converts a binary structure containing an IPv6 address into a string. 🔤

---

int uv_ip_name(const struct sockaddr *src, char *dst, size_t size)

Converts a binary structure containing an IPv4 address or an IPv6 address into a string. either one, she's flexible like that. 🌈

---

int uv_inet_ntop(int af, const void *src, char *dst, size_t size)

int uv_inet_pton(int af, const char *src, void *dst)

Cross-platform, IPv6-capable implementation of inet_ntop(3) and inet_pton(3). on success they return 0. in case of error, the target dst pointer is left unmodified. 🛰️

---

UV_IF_NAMESIZE

Maximum IPv6 interface identifier name length. defined as IFNAMSIZ on Unix and IF_NAMESIZE on Linux and Windows. 📏

Added in version 1.16.0.

int uv_if_indextoname(unsigned int ifindex, char *buffer, size_t *size)

Okay so this one is basically if_indextoname(3) but make it IPv6-coded ✨. You call it, and *size on the way in tells it how long your buffer is (that's where the result goes).

On success you get a big fat 0 back, buffer is holding the interface name, and *size becomes the string length of the buffer — and note that it does not count the NUL terminator byte in *size. Like, it's excluded, bestie, don't @ me. On error you get a negative value back. And if buffer is too smol to hold the result, you get UV_ENOBUFS and *size tells you the necessary size in bytes, and this time it does include the NUL terminator byte in *size. Growth mindset 💅.

On Unix the returned interface name can be used directly as an interface identifier in scoped IPv6 addresses, like fe80::abc:def1:2345%en0. Iconic.

On Windows tho? Nope — the returned interface cannot be used as an interface identifier, because Windows uses numerical interface identifiers, like fe80::abc:def1:2345%5. Different vibes entirely.

So if you want an interface identifier in a cross-platform compatible way, use uv_if_indextoiid(). That's the move 🫶.

Example:

char ifname[UV_IF_NAMESIZE];
size_t size = sizeof(ifname);
uv_if_indextoname(sin6->sin6_scope_id, ifname, &size);

Added in version 1.16.0. 🎀

---

int uv_if_indextoiid(unsigned int ifindex, char *buffer, size_t *size)

This one grabs you a network interface identifier that's suitable for use in an IPv6 scoped address. On Windows it just returns the numeric ifindex as a string. On literally every other platform it calls uv_if_indextoname() for you. So thoughtful of it 💖.

The result gets written to buffer, with *size indicating the length of buffer. If buffer isn't big enough to hold the result, then UV_ENOBUFS is returned, and *size represents the size — including the NUL byte — required to hold the result.

See uv_if_indextoname for further details. Go read it, iykyk.

Added in version 1.16.0. 🦋

---

int uv_exepath(char *buffer, size_t *size)

Gets the executable path. Lowkey crucial detail: you must call uv_setup_args before calling this function. Like, that's a prerequisite, not a suggestion.

Be careful in setuid executables 😭. On some platforms the executable path is an arbitrary string that is controlled by the user. On other platforms environment variables are consulted that may be under control of the user. So yeah — trust issues, fr fr.

---

int uv_cwd(char *buffer, size_t *size)

Gets the current working directory and stores it in buffer. If the current working directory is too large to fit in buffer, this function returns UV_ENOBUFS and sets size to the required length, including the null terminator. No silent truncation, she's honest 💅.

Changed in version 1.1.0: on Unix the path no longer ends in a slash. Clean girl aesthetic.

Changed in version 1.9.0: the returned length includes the terminating null byte on UV_ENOBUFS, and the buffer is null terminated on success. Both glow-ups at once, we love to see it ✨.

---

int uv_chdir(const char *dir)

Changes the current working directory. That's it, that's the whole thing. Short and slay 🧚.

---

int uv_os_homedir(char *buffer, size_t *size)

Gets the current user's home directory 🏠. On Windows, uv_os_homedir() first checks the USERPROFILE environment variable using GetEnvironmentVariableW(). If USERPROFILE isn't set, GetUserProfileDirectoryW() is called. On all other operating systems, uv_os_homedir() first checks the HOME environment variable using getenv(3). If HOME isn't set, getpwuid_r(3) is called.

The user's home directory is stored in buffer. When uv_os_homedir() is called, size indicates the maximum size of buffer. On success size is set to the string length of buffer. On UV_ENOBUFS failure size is set to the required length for buffer, including the null byte.

Warning: uv_os_homedir() is not thread safe 💀. Don't be brave.

Added in version 1.6.0. 🌸

---

int uv_os_tmpdir(char *buffer, size_t *size)

Gets the temp directory 🌡️. On Windows, uv_os_tmpdir() uses GetTempPathW(). On all other operating systems, uv_os_tmpdir() uses the first environment variable found in this ordered list: TMPDIR, TMP, TEMP, and TEMPDIR. Order matters, bestie, it's a priority queue of vibes. If none of these are found, the path /tmp is used, or, on Android, /data/local/tmp is used.

The temp directory is stored in buffer. When uv_os_tmpdir() is called, size indicates the maximum size of buffer. On success size is set to the string length of buffer (which does not include the terminating null). On UV_ENOBUFS failure size is set to the required length for buffer, including the null byte.

Warning: uv_os_tmpdir() is not thread safe 💀. Same energy as above, same rule.

Added in version 1.9.0. ⭐

---

int uv_os_get_passwd(uv_passwd_t *pwd)

Gets a subset of the password file entry for the current effective uid — not the real uid, okay, effective, keep up ✨. The populated data includes the username, euid, gid, shell, and home directory. On non-Windows systems, all data comes from getpwuid_r(3). On Windows, uid and gid are set to -1 and have no meaning, and shell is NULL.

After successfully calling this function, the memory allocated to pwd needs to be freed with uv_os_free_passwd(). Clean up after yourself, main character energy includes taking out the trash 🗑️💖.

Added in version 1.9.0. 🎀

---

int uv_os_get_passwd2(uv_passwd_t *pwd, uv_uid_t uid)

Same deal as above but for the uid you provide, instead of the current effective one. The populated data includes the username, euid, gid, shell, and home directory. On non-Windows systems, all data comes from getpwuid_r(3). On Windows, uid and gid are set to -1 and have no meaning, and shell is NULL.

After successfully calling this function, the memory allocated to pwd needs to be freed with uv_os_free_passwd(). Yes, again. Free your memory, babes 🫶.

Added in version 1.45.0. 🦋

---

int uv_os_get_group(uv_group_t *group, uv_uid_t gid)

Gets a subset of the group file entry for the provided uid. The populated data includes the group name, gid, and members. On non-Windows systems, all data comes from getgrgid_r(3). On Windows, uid and gid are set to -1 and have no meaning.

After successfully calling this function, the memory allocated to group needs to be freed with uv_os_free_group(). You know the drill 💅.

Added in version 1.45.0. 🌈

---

void uv_os_free_group(uv_passwd_t *pwd)

Frees the memory previously allocated with uv_os_get_group(). That's the whole assignment. Do it. 🙈

Added in version 1.45.0. 🍓

---

void uv_os_free_passwd(uv_passwd_t *pwd)

Frees the pwd memory previously allocated with uv_os_get_passwd(). Yes, the param is literally called pwd, we're keeping it exactly as written, no notes ✨.

Added in version 1.9.0. 🧚

---

uint64_t uv_get_free_memory(void)

Gets the amount of free memory available in the system, as reported by the kernel (in bytes). Returns 0 when unknown. When she doesn't know, she says she doesn't know — healthy communication 😌.

---

uint64_t uv_get_total_memory(void)

Gets the total amount of physical memory in the system (in bytes). Returns 0 when unknown. Same energy, no cap 🔥.

---

uint64_t uv_get_constrained_memory(void)

Gets the total amount of memory available to the process (in bytes) based on limits imposed by the OS. If there's no such constraint, or the constraint is unknown, 0 is returned. But if there is a constraining mechanism and yet no constraint is set, UINT64_MAX is returned. Sneaky little distinction, right? 💀

Note that it is not unusual for this value to be less than or greater than uv_get_total_memory(). Yeah. Greater. Don't ask, it's just built different.

Note: This function currently only returns a non-zero value on Linux, based on cgroups if it is present, and on z/OS based on RLIMIT_MEMLIMIT. Soz, everywhere else ✌️.

Added in version 1.29.0. 👑

---

uint64_t uv_get_available_memory(void)

Gets the amount of free memory that is still available to the process (in bytes). This differs from uv_get_free_memory() in that it takes into account any limits imposed by the OS. If there's no such constraint, or the constraint is unknown, the amount returned will be identical to uv_get_free_memory(). Twins when there are no limits 🫶✨.

Note: This function currently only returns a value that is different from what uv_get_free_memory() reports on Linux, based on cgroups if it is present. Linux stays having the most lore, honestly.

Added in version 1.45.0. 💜

---

uint64_t uv_hrtime(void)

Returns the current high-resolution timestamp. This is expressed in nanoseconds ⏱️. It's relative to an arbitrary time in the past — like, she's not telling you when the clock started, that's personal. It is not related to the time of day and therefore not subject to clock drift. The primary use is for measuring performance between intervals. Benchmark bestie behaviour, periodt.

Note: Not every platform can support nanosecond resolution; however, this value will always be in nanoseconds. The unit is consistent even when the precision can't be 💅.

---

int uv_clock_gettime(uv_clock_id clock_id, uv_timespec64_t *ts)

Obtains the current system time from a high-resolution real-time or monotonic clock source. Two clocks, two vibes, choose wisely 🔮.

The real-time clock counts from the UNIX epoch (1970-01-01) and is subject to time adjustments; it can jump back in time. 😭 Betrayal.

The monotonic clock counts from an arbitrary point in the past and never jumps back in time. Loyal. Reliable. The one you want.

Added in version 1.45.0. 🌸

---

void uv_print_all_handles(uv_loop_t *loop, FILE *stream)

Prints all handles associated with the given loop to the given stream. Full tea, spilled 🫖.

Example:

uv_print_all_handles(uv_default_loop(), stderr);
/*
[--I] signal   0x1a25ea8
[-AI] async    0x1a25cf0
[R--] idle     0x1a7a8c8
*/

The format is [flags] handle-type handle-address. And for the flags:

• R is printed for a handle that is referenced
• A is printed for a handle that is active
• I is printed for a handle that is internal

Warning: This function is meant for ad hoc debugging, there is no API/ABI stability guarantees 😬. Cute for a quick look, not for building your whole app on top of, bestie.

Added in version 1.8.0. 🎀

---

void uv_print_active_handles(uv_loop_t *loop, FILE *stream)

This is the same as uv_print_all_handles() except only active handles are printed. Filtered. Curated. Minimalist 😌✨.

Warning: This function is meant for ad hoc debugging, there is no API/ABI stability guarantees. Same warning, same seriousness, don't come crying to me 🔥.

Added in version 1.8.0. 🦋

int uv_os_environ(uv_env_item_t **envitems, int *count)

okay so this one grabs, like, every single environment variable on the system and hands them all to you in envitems, with the count dropped into count. but bestie listen — it allocates memory for you, and you have to free it yourself with uv_os_free_environ(). don't just walk away from it, that's not the vibe 💅

⚠️ Warning: this function is not thread safe. no cap, don't be calling it from five threads at once thinking it'll slay.

Added in version 1.31.0.

---

void uv_os_free_environ(uv_env_item_t *envitems, int count);

the designated cleanup crew 🧹 — frees the memory that uv_os_environ() allocated. pass it the same envitems and count and you're gucci.

Added in version 1.31.0.

---

int uv_os_getenv(const char *name, char *buffer, size_t *size)

grabs the env variable called name, copies its value into buffer, and sets size to the string length of that value. the way that you have to do the math yourself first tho 😭 — when you call it, size must already be set to the amount of storage available in buffer, including the null terminator.

if the variable is bigger than your buffer, you get UV_ENOBUFS back and size gets set to the amount of storage you'd actually need. so like, it tells you how much room to give it. iconic of it tbh. and if there's no matching environment variable at all? you get UV_ENOENT. ✨

⚠️ Warning: not thread safe. fr fr.

Added in version 1.12.0.

---

int uv_os_setenv(const char *name, const char *value)

creates the environment variable name with value — or updates it if it already exists. either way it's getting set, no questions asked 🫶

⚠️ Warning: not thread safe.

Added in version 1.12.0.

---

int uv_os_unsetenv(const char *name)

deletes the environment variable called name. and here's the cute part — if that variable doesn't even exist, this still returns successfully. it's not gonna be dramatic about it. it's at peace 💜

⚠️ Warning: not thread safe.

Added in version 1.12.0.

---

int uv_os_gethostname(char *buffer, size_t *size)

gives you the hostname as a null-terminated string in buffer, and sets size to the string length of the hostname. same deal as before: size must be set to the storage available in buffer, including the null terminator. too small? UV_ENOBUFS, and size tells you how much you actually need.

Added in version 1.12.0.

Changed in version 1.26.0: UV_MAXHOSTNAMESIZE is available now and it represents the maximum buffer size you need to store a hostname plus that terminating nul character. so you don't gotta guess anymore 🎀

---

int uv_os_getpriority(uv_pid_t pid, int *priority)

fetches the scheduling priority of the process identified by pid. the priority you get back lands between -20 (high priority) and 19 (low priority). think of it like niceness but the numbers are doing their own thing 💀

📝 Note: on Windows, the returned priority will equal one of the UV_PRIORITY constants.

Added in version 1.23.0.

---

int uv_os_setpriority(uv_pid_t pid, int priority)

sets the scheduling priority of the process specified by pid. priority goes between -20 (high priority) and 19 (low priority). and for convenience they hand you these constants so you don't have to memorize the numbers:

• UV_PRIORITY_LOW
• UV_PRIORITY_BELOW_NORMAL
• UV_PRIORITY_NORMAL
• UV_PRIORITY_ABOVE_NORMAL
• UV_PRIORITY_HIGH
• UV_PRIORITY_HIGHEST

📝 Note: on Windows this function utilizes SetPriorityClass(). the priority argument gets mapped to a Windows priority class. and when you retrieve the process priority afterward, the result will equal one of the UV_PRIORITY constants — not necessarily the exact value of priority you passed in. so don't come for it when the number looks different 😌

📝 Note: on Windows, setting PRIORITY_HIGHEST will only work for an elevated user. for everyone else it gets silently reduced to PRIORITY_HIGH. sneaky little downgrade.

📝 Note: on IBM i PASE, the highest process priority is -10. the constants shake out like this: UV_PRIORITY_HIGHEST is -10, UV_PRIORITY_HIGH is -7, UV_PRIORITY_ABOVE_NORMAL is -4, UV_PRIORITY_NORMAL is 0, UV_PRIORITY_BELOW_NORMAL is 15 and UV_PRIORITY_LOW is 39.

📝 Note: on IBM i PASE you're not allowed to change your priority unless you have the *JOBCTL special authority — and yes, that includes lowering it. like, even being nice needs permission. rude.

Added in version 1.23.0.

---

int uv_os_uname(uv_utsname_t *buffer)

pulls system information into buffer. the populated data includes the operating system name, release, version, and machine. on non-Windows systems, uv_os_uname() is a thin wrapper around uname(2). returns zero on success and a non-zero error value otherwise. ✨

Added in version 1.25.0.

---

int uv_gettimeofday(uv_timeval64_t *tv)

the cross-platform implementation of gettimeofday(2). heads up though — the timezone argument to gettimeofday() is not supported, because it's considered obsolete. it's giving legacy code that everyone agreed to stop talking about 🙈

Added in version 1.28.0.

---

int uv_random(uv_loop_t *loop, uv_random_t *req, void *buf, size_t buflen, unsigned int flags, uv_random_cb cb)

fills buf with exactly buflen cryptographically strong random bytes acquired from the system CSPRNG. and flags — that's reserved for future extension and must currently be 0. no funny business 🔥

short reads are not possible. when less than buflen random bytes are available, you get a non-zero error value returned or passed to the callback. that's it, that's the deal.

okay and here's where it gets real: 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. so like... it could just vibe there forever. 👑

Sources of entropy (where the randomness comes from, per platform):

• Windows: RtlGenRandom
• Linux, Android: getrandom(2) if available, or urandom(4) after reading from /dev/random once, or the KERN_RANDOM sysctl(2)
• FreeBSD: getrandom(2), or /dev/urandom after reading from /dev/random once
• NetBSD: KERN_ARND sysctl(7)
• macOS, OpenBSD: getentropy(2) if available, or /dev/urandom after reading from /dev/random once
• AIX: /dev/random
• IBM i: /dev/urandom
• Other UNIX: /dev/urandom after reading from /dev/random once

Returns

0 on success, or an error code < 0 on failure. the contents of buf is undefined after an error — so don't go reading it and acting surprised 💀

📝 Note: when using the synchronous version, both loop and req parameters are not used and can be set to NULL.

Added in version 1.33.0.

---

void uv_sleep(unsigned int msec)

puts the calling thread to sleep for msec milliseconds. that's it. that's the whole function. go take a nap bestie 😴💜

Added in version 1.34.0.

---

✨ String manipulation functions ✨

these string utilities are needed internally for dealing with Windows, and they're exported so clients can work uniformly with this data when the libuv API isn't complete. they're the little helpers that got promoted 🎀

---

size_t uv_utf16_length_as_wtf8(const uint16_t *utf16, ssize_t utf16_len)

gets the length of a UTF-16 (or UCS-2) utf16 value after converting it to WTF-8. if utf16 is NUL terminated, utf16_len can be set to -1; otherwise it must be specified. that -1 is the "trust me, it's terminated" signal 🦋

Added in version 1.47.0.

---

int uv_utf16_to_wtf8(const uint16_t *utf16, ssize_t utf16_len, char **wtf8_ptr, size_t *wtf8_len_ptr)

converts UTF-16 (or UCS-2) data in utf16 to WTF-8 data in *wtf8_ptr. the utf16_len count (in characters) gives the length of utf16. if utf16 is NUL terminated, utf16_len can be set to -1; otherwise it must be specified. and okay, there are like four whole modes here, pay attention bestie:

• if wtf8_ptr is NULL, no result will be computed, but the length (equal to uv_utf16_length_as_wtf8) will be stored in wtf8_len_ptr.
• if *wtf8_ptr is NULL, space for the conversion will be allocated and returned in wtf8_ptr, and the length will be returned in wtf8_len_ptr.
• otherwise, the length of *wtf8_ptr must be passed in wtf8_len_ptr. wtf8_ptr must contain an extra space for an extra NUL after the result.
• if the result is truncated, UV_ENOBUFS will be returned and wtf8_len_ptr will be the length of the required wtf8_ptr to contain the whole result.

Added in version 1.47.0.

---

ssize_t uv_wtf8_length_as_utf16(const char *wtf8)

gets the length in characters of a NUL-terminated WTF-8 wtf8 value after converting it to UTF-16 (or UCS-2) — and yes, that includes the NUL terminator. it counts the terminator. it's thorough like that 💅

Added in version 1.47.0.

---

void uv_wtf8_to_utf16(const char *utf8, uint16_t *utf16, size_t utf16_len)

converts NUL-terminated WTF-8 data in wtf8 (the signature calls the param utf8, we're not gonna fight about it, iykyk 🙈) to UTF-16 (or UCS-2) data in utf16. the utf16_len count (in characters) must include space for the NUL terminator. don't forget the terminator or it's gonna be a whole thing.

Added in version 1.47.0.

---

🌈 Metrics operations 🌈

libuv provides a metrics API to track various internal operations of the event loop. it's basically the event loop's screen time report ⭐

💖 Data types 💖

type uv_metrics_t

the struct that contains event loop metrics. pro tip: it's recommended to retrieve these metrics in a uv_prepare_cb so you can make sure there are no inconsistencies with the metrics counters. like checking your stats at a moment when nothing's mid-update 🫶

typedef struct {
    uint64_t loop_count;
    uint64_t events;
    uint64_t events_waiting;
    /* private */
    uint64_t* reserved[13];
} uv_metrics_t;

🌸 Public members 🌸

• uint64_t uv_metrics_t.loop_count — number of event loop iterations. every lap counts 💫
• uint64_t uv_metrics_t.events — number of events that have been processed by the event handler.
• uint64_t uv_metrics_t.events_waiting — number of events that were waiting to be processed when the event provider was called. the little queue of "we'll get to you" 👑

🦋 API 🦋

uint64_t uv_metrics_idle_time(uv_loop_t *loop)

retrieves the amount of time the event loop has been idle in the kernel's event provider (e.g. epoll_wait). and good news — this call is thread safe. no warnings here, she's well behaved ✨💜

...The return value is literally the accumulated time spent idle in the kernel's event provider, starting from when that 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 you call uv_loop_configure with UV_METRICS_IDLE_TIME. Configure first, metrics later, bestie. 🫶

Added in version 1.39.0. ✨

• int uv_metrics_info(uv_loop_t *loop, uv_metrics_t *metrics) — copies the current set of event loop metrics over to the metrics pointer. That's it, that's the whole job. 🎀

Added in version 1.45.0.

---

🌸 USER GUIDE 🌸

Warning: the contents of this guide have been recently incorporated into the libuv documentation and it hasn't gone through thorough review yet. If you spot a mistake please file an issue, or better yet, open a pull request! 💖

🌱 Introduction

This 'book' is a small set of tutorials about using libuv (https://github.com/libuv/libuv) as a high performance evented I/O library which offers the same API on Windows and Unix.

It's meant to cover the main areas of libuv, but it is not a comprehensive reference discussing every function and data structure. For full details, the official libuv documentation (https://docs.libuv.org/en/v1.x/) may be consulted. 📚

This book is still a work in progress, so sections may be incomplete, but I hope you'll enjoy it as it grows. 🌱

🫶 Who this book is for

If you're reading this book, you are either:

1. a systems programmer, creating low-level programs such as daemons or network services and clients. You've found that the event loop approach is well suited for your application and decided to use libuv.
2. a node.js module writer, who wants to wrap platform APIs written in C or C++ with a set of (a)synchronous APIs that are exposed to JavaScript. You'll use libuv purely in the context of node.js. For this you'll require some other resources as the book does not cover parts specific to v8/node.js.

This book assumes that you're comfortable with the C programming language. 👑

📖 Background

The node.js (https://nodejs.org) project began in 2009 as a JavaScript environment decoupled from the browser. Using Google's V8 (https://v8.dev) and Marc Lehmann's libev (http://software.schmorp.de/pkg/libev.html), node.js combined a model of I/O — evented — with a language that was well suited to the style of programming; due to the way it had been shaped by browsers. As node.js grew in popularity, it was important to make it work on Windows, but libev ran only on Unix. The Windows equivalent of kernel event notification mechanisms like kqueue or (e)poll is IOCP. libuv was an abstraction around libev or IOCP depending on the platform, providing users an API based on libev. In the node-v0.9.0 version of libuv libev was removed (https://github.com/joyent/libuv/issues/485). 😭

Since then libuv has continued to mature and become a high quality standalone library for system programming. Users outside of node.js include Mozilla's Rust (https://rust-lang.org/) programming language, and a variety (https://github.com/libuv/libuv/blob/v1.x/LINKS.md) of language bindings. 🦋

This book and the code is based on libuv version v1.42.0 (https://github.com/libuv/libuv/releases/tag/v1.42.0).

💻 Code

All the example code and the source of the book is included as part of the libuv (https://github.com/libuv/libuv) project on GitHub. Clone or Download libuv (https://github.com/libuv/libuv), then build it:

sh autogen.sh
./configure
make

There is no need to make install. To build the examples run make in the docs/code/ directory. 🛠️

✨ Basics of libuv

libuv enforces an asynchronous, event-driven style of programming. Its core job is to provide an event loop and callback based notifications of I/O and other activities. libuv offers core utilities like timers, non-blocking networking support, asynchronous file system access, child processes and more. 💅

🔁 Event loops

In event-driven programming, an application expresses interest in certain events and responds to them when they occur. The responsibility of gathering events from the operating system or monitoring other sources of events is handled by libuv, and the user can register callbacks to be invoked when an event occurs. The event-loop usually keeps running forever. In pseudocode:

while there are still events to process:
    e = get the next event
    if there is a callback associated with e:
        call the callback

Some examples of events are:

• File is ready for writing
• A socket has data ready to be read
• A timer has timed out

This event loop is encapsulated by uv_run() — the end-all function when using libuv. 👑

The most common activity of systems programs is to deal with input and output, rather than a lot of number-crunching. The problem with using conventional input/output functions (read, fprintf, etc.) is that they are blocking. The actual write to a hard disk or reading from a network takes a disproportionately long time compared to the speed of the processor. The functions don't return until the task is done, so that your program is doing nothing. For programs which require high performance this is a major roadblock as other activities and other I/O operations are kept waiting. 💀

One of the standard solutions is to use threads. Each blocking I/O operation is started in a separate thread (or in a thread pool). When the blocking function gets invoked in the thread, the operating system can schedule another thread to run, which actually needs the CPU.

The approach followed by libuv uses another style, which is the asynchronous, non-blocking style. Most modern operating systems provide event notification subsystems. For example, a normal read call on a socket would block until the sender actually sent something. Instead, the application can request the operating system to watch the socket and put an event notification in the queue. The application can inspect the events at its convenience (perhaps doing some number crunching before to use the processor to the maximum) and grab the data. It is asynchronous because the application expressed interest at one point, then used the data at another point (in time and space). It is non-blocking because the application process was free to do other tasks. This fits in well with libuv's event-loop approach, since the operating system events can be treated as just another libuv event. The non-blocking ensures that other events can continue to be handled as fast as they come in [1]. 🔥

Note: how the I/O is run in the background is not of our concern, but due to the way our computer hardware works, with the thread as the basic unit of the processor, libuv and OSes will usually run background/worker threads and/or polling to perform tasks in a non-blocking manner.

Bert Belder, one of the libuv core developers, has a small video explaining the architecture of libuv and its background. If you have no prior experience with libuv, it is a quick, useful watch. 👀

libuv's event loop is explained in more detail in the documentation (https://docs.libuv.org/en/v1.x/design.html#the-i-o-loop).

👋 Hello World

With the basics out of the way, let's write our first libuv program. It does nothing, except start a loop which will exit immediately. 😌

helloworld/main.c

#include <stdio.h>
#include <stdlib.h>
#include <uv.h>

int main() {
    uv_loop_t *loop = malloc(sizeof(uv_loop_t));
    uv_loop_init(loop);

    printf("Now quitting.\n");
    uv_run(loop, UV_RUN_DEFAULT);

    uv_loop_close(loop);
    free(loop);
    return 0;
}

This program quits immediately because it has no events to process. A libuv event loop has to be told to watch out for events using the various API functions.

Starting with libuv v1.0, users should allocate the memory for the loops before initializing it with uv_loop_init(uv_loop_t *). This allows you to plug in custom memory management. Remember to de-initialize the loop using uv_loop_close(uv_loop_t *) and then delete the storage. The examples never close loops since the program quits after the loop ends and the system will reclaim memory. Production grade projects, especially long running systems programs, should take care to release correctly. 🫶

🌈 Default loop

A default loop is provided by libuv and can be accessed using uv_default_loop(). You should use this loop if you only want a single loop. ✨

default-loop/main.c

#include <stdio.h>
#include <uv.h>

int main() {
    uv_loop_t *loop = uv_default_loop();

    printf("Default loop.\n");
    uv_run(loop, UV_RUN_DEFAULT);

    uv_loop_close(loop);
    return 0;
}

Note: node.js uses the default loop as its main loop. If you are writing bindings you should be aware of this. 👑

💀 Error handling

Initialization functions or synchronous functions which may fail return a negative number on error. Async functions that may fail will pass a status parameter to their callbacks. The error messages are defined as UV_E* constants (https://docs.libuv.org/en/v1.x/errors.html#error-constants).

You can use the uv_strerror(int) and uv_err_name(int) functions to get a const char * describing the error or the error name respectively. 🎀

I/O read callbacks (such as for files and sockets) are passed a parameter nread. If nread is less than 0, there was an error (UV_EOF is the end of file error, which you may want to handle differently). 🙈

🎀 Handles and Requests

libuv works by the user expressing interest in particular events. This is usually done by creating a handle to an I/O device, timer or process. Handles are opaque structs named as uv_TYPE_t where type signifies what the handle is used for.

libuv watchers:

/* Handle types. */
typedef struct uv_loop_s uv_loop_t;
typedef struct uv_handle_s uv_handle_t;
typedef struct uv_dir_s uv_dir_t;
typedef struct uv_stream_s uv_stream_t;
typedef struct uv_tcp_s uv_tcp_t;
typedef struct uv_udp_s uv_udp_t;
typedef struct uv_pipe_s uv_pipe_t;
typedef struct uv_tty_s uv_tty_t;
typedef struct uv_poll_s uv_poll_t;
typedef struct uv_timer_s uv_timer_t;
typedef struct uv_prepare_s uv_prepare_t;
typedef struct uv_check_s uv_check_t;
typedef struct uv_idle_s uv_idle_t;
typedef struct uv_async_s uv_async_t;
typedef struct uv_process_s uv_process_t;
typedef struct uv_fs_event_s uv_fs_event_t;
typedef struct uv_fs_poll_s uv_fs_poll_t;
typedef struct uv_signal_s uv_signal_t;

          /* Request types. */
          typedef struct uv_req_s uv_req_t;
          typedef struct uv_getaddrinfo_s uv_getaddrinfo_t;
          typedef struct uv_getnameinfo_s uv_getnameinfo_t;
          typedef struct uv_shutdown_s uv_shutdown_t;
          typedef struct uv_write_s uv_write_t;
          typedef struct uv_connect_s uv_connect_t;
          typedef struct uv_udp_send_s uv_udp_send_t;
          typedef struct uv_fs_s uv_fs_t;
          typedef struct uv_work_s uv_work_t;
          typedef struct uv_random_s uv_random_t;

          /* None of the above. */
          typedef struct uv_env_item_s uv_env_item_t;
          typedef struct uv_cpu_info_s uv_cpu_info_t;
          typedef struct uv_interface_address_s uv_interface_address_t;
          typedef struct uv_dirent_s uv_dirent_t;
          typedef struct uv_passwd_s uv_passwd_t;
          typedef struct uv_utsname_s uv_utsname_t;
          typedef struct uv_statfs_s uv_statfs_t;

Okay so handles are the long-lived girlies 💅 — they represent objects that stick around. And any async operation you do on one of those handles gets identified with a request. A request is short-lived (usually it only lives across a single callback) and it basically says "here's one I/O operation happening on a handle." ✨ Requests exist to preserve context between when you start something and when its callback fires. Example time: a UDP socket is a uv_udp_t, but each individual write to that socket uses a uv_udp_send_t struct that gets passed to the callback once the write is done. iykyk 💖

Handles get set up by their matching init function, and it goes like this:

          uv_TYPE_init(uv_loop_t *, uv_TYPE_t *)

Callbacks are the functions libuv calls whenever an event the watcher cares about has happened 👑. Your app-specific logic lowkey lives in the callback. Like, an IO watcher's callback gets the data read from a file, a timer callback fires on timeout, and so on. Main character energy fr fr 🌟

💤 Idling

Here's an example of using an idle handle — the callback gets called once on every single turn of the event loop. A use case for idle handles is discussed in Utilities <>. Let's use an idle watcher to peek at the watcher life cycle and see how uv_run() will now block because a watcher is present 🦋. The idle watcher gets stopped when the count is reached, and then uv_run() exits since no event watchers are active. Slay.

idle-basic/main.c

          #include <stdio.h>
          #include <uv.h>

          int64_t counter = 0;

          void wait_for_a_while(uv_idle_t* handle) {
              counter++;

              if (counter >= 10e6)
                  uv_idle_stop(handle);
          }

          int main() {
              uv_idle_t idler;

              uv_idle_init(uv_default_loop(), &idler);
              uv_idle_start(&idler, wait_for_a_while);

              printf("Idling...\n");
              uv_run(uv_default_loop(), UV_RUN_DEFAULT);

              uv_loop_close(uv_default_loop());
              return 0;
          }

🎀 Storing context

In callback-based programming style you're gonna constantly want to pass some 'context' — application-specific info, bestie — between the call site and the callback. Good news: all handles and requests have a void* data member that you can set to your context and then cast back inside the callback 💖. This is a super common pattern all over the C library ecosystem, no cap. And bonus: uv_loop_t has a similar data member too. 👑

---

[1] Depending on the capacity of the hardware of course. 😭

🗂️ Filesystem

Simple filesystem read/write is achieved using the uv_fs_* functions and the uv_fs_t struct. Easy.

Note: the libuv filesystem operations are different from socket operations <>. Socket operations use the non-blocking operations provided by the operating system. Filesystem operations use blocking functions internally, but invoke these functions in a thread pool (https://docs.libuv.org/en/v1.x/threadpool.html#thread-pool-work-scheduling) and notify watchers registered with the event loop when application interaction is required. 🧚

All filesystem functions have two forms — synchronous and asynchronous ✨.

The synchronous forms automatically get called (and block) if the callback is null. The return value of functions is a libuv error code <#libuv-error-handling>. This is usually only useful for synchronous calls. The asynchronous form is called when a callback is passed, and the return value is 0. 💅

📖 Reading/Writing files

A file descriptor is obtained using:

          int uv_fs_open(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, int mode, uv_fs_cb cb)

flags and mode are standard Unix flags (https://man7.org/linux/man-pages/man2/open.2.html). libuv takes care of converting to the appropriate Windows flags 🪄.

File descriptors are closed using:

          int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb)

Filesystem operation callbacks have the signature:

          void callback(uv_fs_t* req);

Let's see a simple implementation of cat. We start with registering a callback for when the file is opened:

uvcat/main.c - opening a file

              // The request passed to the callback is the same as the one the call setup
              // function was passed.
              assert(req == &open_req);
              if (req->result >= 0) {
                  iov = uv_buf_init(buffer, sizeof(buffer));
                  uv_fs_read(uv_default_loop(), &read_req, req->result,
                             &iov, 1, -1, on_read);
              }
              else {
                  fprintf(stderr, "error opening file: %s\n", uv_strerror((int)req->result));
              }
          }

The result field of a uv_fs_t is the file descriptor in the case of the uv_fs_open callback. If the file is successfully opened, we start reading it 📖✨

uvcat/main.c - read callback

              if (req->result < 0) {
                  fprintf(stderr, "Read error: %s\n", uv_strerror(req->result));
              }
              else if (req->result == 0) {
                  uv_fs_t close_req;
                  // synchronous
                  uv_fs_close(uv_default_loop(), &close_req, open_req.result, NULL);
              }
              else if (req->result > 0) {
                  iov.len = req->result;
                  uv_fs_write(uv_default_loop(), &write_req, 1, &iov, 1, -1, on_write);
              }
          }

In the case of a read call, you should pass an initialized buffer which will be filled with data before the read callback is triggered. The uv_fs_* operations map almost directly to certain POSIX functions, so EOF is indicated in this case by result being 0. In the case of streams or pipes, the UV_EOF constant would have been passed as a status instead 🌸.

Here you see a common pattern when writing asynchronous programs: the uv_fs_close() call is performed synchronously. Usually tasks which are one-off, or are done as part of the startup or shutdown stage, are performed synchronously, since we're interested in fast I/O when the program is going about its primary task and dealing with multiple I/O sources. For solo tasks the performance difference usually is negligible and may lead to simpler code 💅✨.

Filesystem writing is similarly simple using uv_fs_write(). Your callback will be triggered after the write is complete. In our case the callback simply drives the next read. Thus read and write proceed in lockstep via callbacks 🫶.

uvcat/main.c - write callback

              if (req->result < 0) {
                  fprintf(stderr, "Write error: %s\n", uv_strerror((int)req->result));
              }
              else {
                  uv_fs_read(uv_default_loop(), &read_req, open_req.result, &iov, 1, -1, on_read);
              }
          }

Warning: due to the way filesystems and disk drives are configured for performance, a write that 'succeeds' may not be committed to disk yet. 😭 bestie do not assume it's safely on disk, fr fr.

We set the dominos rolling in main():

uvcat/main.c

              uv_fs_open(uv_default_loop(), &open_req, argv[1], O_RDONLY, 0, on_open);
              uv_run(uv_default_loop(), UV_RUN_DEFAULT);

              uv_fs_req_cleanup(&open_req);
              uv_fs_req_cleanup(&read_req);
              uv_fs_req_cleanup(&write_req);
              return 0;
          }

Warning: the uv_fs_req_cleanup() function must always be called on filesystem requests to free internal memory allocations in libuv. Like, every single time. No skipping, no "it's probably fine" 🙈💀

🧰 Filesystem operations

All the standard filesystem operations like unlink, rmdir, stat are supported asynchronously and have intuitive argument order 👑. They follow the same patterns as the read/write/open calls, returning the result in the uv_fs_t.result field. The full list:

Filesystem operations

          int uv_fs_close(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb);
          int uv_fs_open(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, int mode, uv_fs_cb cb);
          int uv_fs_read(uv_loop_t* loop, uv_fs_t* req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb);
          int uv_fs_unlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
          int uv_fs_write(uv_loop_t* loop, uv_fs_t* req, uv_file file, const uv_buf_t bufs[], unsigned int nbufs, int64_t offset, uv_fs_cb cb);
          int uv_fs_copyfile(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb);
          int uv_fs_mkdir(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb);
          int uv_fs_mkdtemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb);
          int uv_fs_mkstemp(uv_loop_t* loop, uv_fs_t* req, const char* tpl, uv_fs_cb cb);
          int uv_fs_rmdir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
          int uv_fs_scandir(uv_loop_t* loop, uv_fs_t* req, const char* path, int flags, uv_fs_cb cb);
          int uv_fs_scandir_next(uv_fs_t* req, uv_dirent_t* ent);
          int uv_fs_opendir(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
          int uv_fs_readdir(uv_loop_t* loop, uv_fs_t* req, uv_dir_t* dir, uv_fs_cb cb);
          int uv_fs_closedir(uv_loop_t* loop, uv_fs_t* req, uv_dir_t* dir, uv_fs_cb cb);
          int uv_fs_stat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
          int uv_fs_fstat(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb);
          int uv_fs_rename(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb);
          int uv_fs_fsync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb);
          int uv_fs_fdatasync(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_fs_cb cb);
          int uv_fs_ftruncate(uv_loop_t* loop, uv_fs_t* req, uv_file file, int64_t offset, uv_fs_cb cb);
          int uv_fs_sendfile(uv_loop_t* loop, uv_fs_t* req, uv_file out_fd, uv_file in_fd, int64_t in_offset, size_t length, uv_fs_cb cb);
          int uv_fs_access(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb);
          int uv_fs_chmod(uv_loop_t* loop, uv_fs_t* req, const char* path, int mode, uv_fs_cb cb);
          int uv_fs_utime(uv_loop_t* loop, uv_fs_t* req, const char* path, double atime, double mtime, uv_fs_cb cb);
          int uv_fs_futime(uv_loop_t* loop, uv_fs_t* req, uv_file file, double atime, double mtime, uv_fs_cb cb);
          int uv_fs_lutime(uv_loop_t* loop, uv_fs_t* req, const char* path, double atime, double mtime, uv_fs_cb cb);
          int uv_fs_lstat(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
          int uv_fs_link(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, uv_fs_cb cb);
          int uv_fs_symlink(uv_loop_t* loop, uv_fs_t* req, const char* path, const char* new_path, int flags, uv_fs_cb cb);
          int uv_fs_readlink(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
          int uv_fs_realpath(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);
          int uv_fs_fchmod(uv_loop_t* loop, uv_fs_t* req, uv_file file, int mode, uv_fs_cb cb);
          int uv_fs_chown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb);
          int uv_fs_fchown(uv_loop_t* loop, uv_fs_t* req, uv_file file, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb);
          int uv_fs_lchown(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_uid_t uid, uv_gid_t gid, uv_fs_cb cb);
          int uv_fs_statfs(uv_loop_t* loop, uv_fs_t* req, const char* path, uv_fs_cb cb);

---

🦋 Buffers and Streams 🦋

ok so the basic I/O handle in libuv is the stream (uv_stream_t). like, TCP sockets, TTYs, and pipes for file I/O and IPC are all treated as stream subclasses. one handle type to rule them all, honestly iconic. 👑

Streams get initialized using custom functions for each subclass, and then you operate on them using:

          int uv_read_start(uv_stream_t*, uv_alloc_cb alloc_cb, uv_read_cb read_cb);
          int uv_read_stop(uv_stream_t*);
          int uv_write(uv_write_t* req, uv_stream_t* handle,
                       const uv_buf_t bufs[], unsigned int nbufs, uv_write_cb cb);

The stream-based functions are way simpler to use than the filesystem ones, and libuv will automatically keep reading from a stream once uv_read_start() is called — like once and done, bestie — until you call uv_read_stop(). 🫶

The discrete unit of data is the buffer — uv_buf_t. It's literally just a collection of a pointer to bytes (uv_buf_t.base) and the length (uv_buf_t.len). The uv_buf_t itself is lightweight and gets passed around by value. What actually needs managing is the real bytes, which have to be allocated and freed by the application. that's you. that's the assignment. 💅

Error: THIS PROGRAM DOES NOT ALWAYS WORK, NEED SOMETHING BETTER

To demonstrate streams we're gonna need uv_pipe_t. This lets you stream local files [2]. Here's a simple little tee utility using libuv. Doing all operations asynchronously shows the power of evented I/O — the two writes won't block each other, but we have to be careful to copy over the buffer data to ensure we don't free a buffer until it has been written. ✨

The program is to be executed as:

          ./uvtee <output_file>

We start off opening pipes on the files we require. libuv pipes to a file are opened as bidirectional by default. cute, right? 🎀

uvtee/main.c — read on pipes

              loop = uv_default_loop();

              uv_pipe_init(loop, &stdin_pipe, 0);
              uv_pipe_open(&stdin_pipe, 0);

              uv_pipe_init(loop, &stdout_pipe, 0);
              uv_pipe_open(&stdout_pipe, 1);

              uv_fs_t file_req;
              int fd = uv_fs_open(loop, &file_req, argv[1], O_CREAT | O_RDWR, 0644, NULL);
              uv_pipe_init(loop, &file_pipe, 0);
              uv_pipe_open(&file_pipe, fd);

              uv_read_start((uv_stream_t*)&stdin_pipe, alloc_buffer, read_stdin);

              uv_run(loop, UV_RUN_DEFAULT);
              return 0;
          }

The third argument of uv_pipe_init() should be set to 1 for IPC using named pipes. That's covered in Processes <>. The uv_pipe_open() call associates the pipe with the file descriptor — in this case 0 (standard input). 💖

We start monitoring stdin. The alloc_buffer callback is invoked as new buffers are required to hold incoming data. read_stdin will be called with these buffers.

uvtee/main.c — reading buffers

              *buf = uv_buf_init((char*) malloc(suggested_size), suggested_size);
          }

          void free_write_req(uv_write_t *req) {
              if (nread < 0){
                  if (nread == UV_EOF){
                      // end of file
                      uv_close((uv_handle_t *)&stdin_pipe, NULL);
                      uv_close((uv_handle_t *)&stdout_pipe, NULL);
                      uv_close((uv_handle_t *)&file_pipe, NULL);
                  }
              } else if (nread > 0) {
                  write_data((uv_stream_t *)&stdout_pipe, nread, *buf, on_stdout_write);
                  write_data((uv_stream_t *)&file_pipe, nread, *buf, on_file_write);
              }

              // OK to free buffer as write_data copies it.
              if (buf->base)
                  free(buf->base);
          }

The standard malloc is sufficient here, but ngl you can use any memory allocation scheme. For example, node.js uses its own slab allocator which associates buffers with V8 objects. fancy.

The read callback's nread parameter is less than 0 on any error. This error might be EOF, in which case we close all the streams, using the generic close function uv_close() which deals with the handle based on its internal type. Otherwise nread is a non-negative number and we can attempt to write that many bytes to the output streams. And finally — remember that buffer allocation and deallocation is application responsibility, so we free the data. 🧚

The allocation callback may return a buffer with length zero if it fails to allocate memory. In that case, the read callback is invoked with error UV_ENOBUFS. But heads up — libuv will continue to attempt to read the stream though, so you must explicitly call uv_close() if you want to stop when allocation fails. like, it's not gonna stop for you. 💀

The read callback may be called with nread = 0, indicating that at this point there is nothing to be read. Most applications will just ignore this. mood, honestly.

uvtee/main.c — Write to pipe

              uv_write_t req;
              uv_buf_t buf;
          } write_req_t;

          uv_loop_t *loop;
              write_req_t *wr = (write_req_t*) req;
              free(wr->buf.base);
              free(wr);
          }

          void on_stdout_write(uv_write_t *req, int status) {
              free_write_req(req);
          }

          void on_file_write(uv_write_t *req, int status) {
              free_write_req(req);
          }

          void write_data(uv_stream_t *dest, size_t size, uv_buf_t buf, uv_write_cb cb) {
              write_req_t *req = (write_req_t*) malloc(sizeof(write_req_t));
              req->buf = uv_buf_init((char*) malloc(size), size);
              memcpy(req->buf.base, buf.base, size);
              uv_write((uv_write_t*) req, (uv_stream_t*)dest, &req->buf, 1, cb);
          }

write_data() makes a copy of the buffer obtained from read. This buffer does not get passed through to the write callback triggered on write completion. To get around this we wrap a write request and a buffer in write_req_t and unwrap it in the callbacks. We make a copy so we can free the two buffers from the two calls to write_data independently of each other. While acceptable for a demo program like this, you'll probably want smarter memory management — like reference counted buffers or a pool of buffers — in any major application. ✨

Warning: If your program is meant to be used with other programs it may knowingly or unknowingly be writing to a pipe. This makes it susceptible to aborting on receiving a SIGPIPE — see the whole thing at <http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#The_special_problem_of_SIGPIPE>. It is a good idea to insert: c signal(SIGPIPE, SIG_IGN) in the initialization stages of your application. protect ur peace, bestie. 🫶

---

🌸 File change events 🌸

All modern operating systems provide APIs to put watches on individual files or directories and be informed when the files are modified. libuv wraps common file change notification libraries [1]. Ngl this is one of the more inconsistent parts of libuv — file change notification systems are themselves extremely varied across platforms, so getting everything working everywhere is difficult. it's giving chaos. 😭

To demonstrate, I'm going to build a simple utility which runs a command whenever any of the watched files change:

          ./onchange <command> <file1> [file2] ...

Note: Currently this example only works on OSX and Windows. Refer to the notes of the uv_fs_event_start function — <https://docs.libuv.org/en/v1.x/fs_event.html#c.uv_fs_event_start>.

The file change notification is started using uv_fs_event_init():

onchange/main.c — The setup

          int main(int argc, char **argv) {
              if (argc <= 2) {
                  fprintf(stderr, "Usage: %s <command> <file1> [file2 ...]\n", argv[0]);
                  return 1;
              }

              loop = uv_default_loop();
              command = argv[1];

              while (argc-- > 2) {
                  fprintf(stderr, "Adding watch on %s\n", argv[argc]);
                  uv_fs_event_t *fs_event_req = malloc(sizeof(uv_fs_event_t));
                  uv_fs_event_init(loop, fs_event_req);
                  // The recursive flag watches subdirectories too.
                  uv_fs_event_start(fs_event_req, run_command, argv[argc], UV_FS_EVENT_RECURSIVE);
              }

              return uv_run(loop, UV_RUN_DEFAULT);
          }

So yeah — that third argument is the actual file or directory you're monitoring 💅 and the last one, flags, can be any of these lil beauties:

/*
 * Flags to be passed to uv_fs_event_start().
 */
enum uv_fs_event_flags {
    UV_FS_EVENT_WATCH_ENTRY = 1,
    UV_FS_EVENT_STAT = 2,
    UV_FS_EVENT_RECURSIVE = 4
};

Real talk: UV_FS_EVENT_WATCH_ENTRY and UV_FS_EVENT_STAT don't do anything (yet 🙈). UV_FS_EVENT_RECURSIVE will start watching subdirectories too on supported platforms. That's the one that actually eats. ✨

---

Your callback gets handed these four things, in order:

1. uv_fs_event_t *handle — the handle, obviously. Its path field is the file the watch was set on. 👑
2. const char *filename — if you're monitoring a directory, this is the file that changed. Only non-null on Linux and Windows, and ngl it may be null even on those platforms 😭
3. int events — one of UV_RENAME or UV_CHANGE, or a bitwise OR of both.
4. int status — if status < 0, there's a libuv error (#libuv-error-handling). 💀

In our example we literally just print the arguments and run the command using system().

onchange/main.c — file change notification callback

void run_command(uv_fs_event_t *handle, const char *filename, int events, int status) {
    char path[1024];
    size_t size = 1023;
    // Does not handle error if path is longer than 1023.
    uv_fs_event_getpath(handle, path, &size);
    path[size] = '\0';

    fprintf(stderr, "Change detected in %s: ", path);
    if (events & UV_RENAME)
        fprintf(stderr, "renamed");
    if (events & UV_CHANGE)
        fprintf(stderr, "changed");

    fprintf(stderr, " %s\n", filename ? filename : "");
    system(command);
}

---

Footnotes, bestie, don't skip 'em 🫶

• [1] inotify on Linux, FSEvents on Darwin, kqueue on BSDs, ReadDirectoryChangesW on Windows, event ports on Solaris, unsupported on Cygwin
• [2] see Parent-child IPC (#pipes)

---

🌐 Networking 🌐

Okay so networking in libuv? Not much different from directly using the BSD socket interface — some things are easier, all are non-blocking, but the concepts stay the exact same, no cap. On top of that, libuv offers utility functions to abstract the annoying, repetitive and low-level tasks, like setting up sockets using the BSD socket structures, DNS lookup, and tweaking various socket parameters. It's giving glow-up for your socket code 🌈

The uv_tcp_t and uv_udp_t structures are what you use for network I/O. 💖

Note: the code samples in this chapter exist to show certain libuv APIs. They are not examples of good quality code. They leak memory and don't always close connections properly. 😭 Do not copy-paste these into prod, I'm begging.

🧵 TCP 🧵

TCP is a connection oriented, stream protocol and is therefore based on the libuv streams infrastructure. Periodt.

🖥️ Server 🖥️

Server sockets proceed like this, step by step:

1. uv_tcp_init the TCP handle.
2. uv_tcp_bind it.
3. Call uv_listen on the handle to have a callback invoked whenever a new connection is established by a client.
4. Use uv_accept to accept the connection.
5. Use stream operations (#buffers-and-streams) to communicate with the client.

Here is a simple echo server 💅

tcp-echo-server/main.c — The listen socket

              uv_close((uv_handle_t*) client, on_close);
          }
      }

      int main() {
          loop = uv_default_loop();

          uv_tcp_t server;
          uv_tcp_init(loop, &server);

          uv_ip4_addr("0.0.0.0", DEFAULT_PORT, &addr);

          uv_tcp_bind(&server, (const struct sockaddr*)&addr, 0);
          int r = uv_listen((uv_stream_t*) &server, DEFAULT_BACKLOG, on_new_connection);
          if (r) {
              fprintf(stderr, "Listen error %s\n", uv_strerror(r));
              return 1;
          }
          return uv_run(loop, UV_RUN_DEFAULT);
      }

You can see the utility function uv_ip4_addr being used to convert from a human readable IP address + port pair into the sockaddr_in structure that the BSD socket APIs require. And the reverse? That's uv_ip4_name. 🔁

Note: there are uv_ip6_* analogues for the ip4 functions. 🦋

Most of the setup functions are synchronous since they are CPU-bound. uv_listen is where we return to libuv's callback style. The second arguments is the backlog queue — the maximum length of queued connections. 📚

When a connection is initiated by clients, the callback is required to set up a handle for the client socket and associate the handle using uv_accept. In this case we also establish interest in reading from this stream. 👀

tcp-echo-server/main.c — Accepting the client

              free(buf->base);
          }

          void on_new_connection(uv_stream_t *server, int status) {
              if (status < 0) {
                  fprintf(stderr, "New connection error %s\n", uv_strerror(status));
                  // error!
                  return;
              }

              uv_tcp_t *client = (uv_tcp_t*) malloc(sizeof(uv_tcp_t));
              uv_tcp_init(loop, client);
              if (uv_accept(server, (uv_stream_t*) client) == 0) {
                  uv_read_start((uv_stream_t*) client, alloc_buffer, echo_read);
              }

The remaining set of functions is very similar to the streams example and can be found in the code. Just remember to call uv_close when the socket isn't required. Bestie you can even do this inside the uv_listen callback if you're not interested in accepting the connection — no hard feelings 💅

📞 Client 📞

Where you do bind/listen/accept on the server, on the client side it's simply a matter of calling uv_tcp_connect. Same uv_connect_cb style callback as uv_listen is used by uv_tcp_connect. Try: ✨

uv_tcp_t* socket = (uv_tcp_t*)malloc(sizeof(uv_tcp_t));
uv_tcp_init(loop, socket);

uv_connect_t* connect = (uv_connect_t*)malloc(sizeof(uv_connect_t));

struct sockaddr_in dest;
uv_ip4_addr("127.0.0.1", 80, &dest);

uv_tcp_connect(connect, socket, (const struct sockaddr*)&dest, on_connect);

where on_connect will be called after the connection is established. The callback receives the uv_connect_t struct, which has a member .handle pointing to the socket. 🎀

📡 UDP 📡

The User Datagram Protocol (https://en.wikipedia.org/wiki/User_Datagram_Protocol) offers connectionless, unreliable network communication. Hence libuv doesn't offer a stream. Instead libuv provides non-blocking UDP support via the uv_udp_t handle (for receiving) and uv_udp_send_t request (for sending) and related functions. That said, the actual API for reading/writing is very similar to normal stream reads. 👑

To look at how UDP can be used, the example shows the first stage of obtaining an IP address from a DHCP (https://datatracker.ietf.org/doc/html/rfc2131) server — DHCP Discover. 🕵️‍♀️

Note: you will have to run udp-dhcp as root since it uses well known port numbers below 1024. 🔥

udp-dhcp/main.c — Setup and send UDP packets

uv_loop_t *loop;
uv_udp_t send_socket;
uv_udp_t recv_socket;

int main() {
    loop = uv_default_loop();

    uv_udp_init(loop, &recv_socket);
    struct sockaddr_in recv_addr;
    uv_ip4_addr("0.0.0.0", 68, &recv_addr);
    uv_udp_bind(&recv_socket, (const struct sockaddr *)&recv_addr, UV_UDP_REUSEADDR);
    uv_udp_recv_start(&recv_socket, alloc_buffer, on_read);

    uv_udp_init(loop, &send_socket);
    struct sockaddr_in broadcast_addr;
    uv_ip4_addr("0.0.0.0", 0, &broadcast_addr);
    uv_udp_bind(&send_socket, (const struct sockaddr *)&broadcast_addr, 0);
    uv_udp_set_broadcast(&send_socket, 1);

    uv_udp_send_t send_req;
    uv_buf_t discover_msg = make_discover_msg();

    struct sockaddr_in send_addr;
    uv_ip4_addr("255.255.255.255", 67, &send_addr);
    uv_udp_send(&send_req, &send_socket, &discover_msg, 1, (const struct sockaddr *)&send_addr, on_send);

    return uv_run(loop, UV_RUN_DEFAULT);
}

Note: the IP address 0.0.0.0 is used to bind to all interfaces. The IP address 255.255.255.255 is a broadcast address meaning that packets will be sent to all interfaces on the subnet. Port 0 means that the OS randomly assigns a port. 🎲

First we setup the receiving socket to bind on all interfaces on port 68 (DHCP client) and start a read on it. This will read back responses from any DHCP server that replies. We use the UV_UDP_REUSEADDR flag to play nice with any other system DHCP clients that are running on this computer on the same port. 🤝 Then we setup a similar send socket and use uv_udp_send to send a broadcast message on port 67 (DHCP server).

It is necessary to set the broadcast flag, otherwise you will get an EACCES error [1]. 😤 The exact message being sent is not relevant to this book and you can study the code if you are interested. As usual, the read and write callbacks will receive a status code of < 0 if something went wrong.

Since UDP sockets are not connected to a particular peer, the read callback receives an extra parameter about the sender of the packet. 📬

nread may be zero if there is no more data to be read. If addr is NULL, it indicates there is nothing to read (the callback shouldn't do anything), if not NULL, it indicates that an empty datagram was received from the host at addr. The flags parameter may be UV_UDP_PARTIAL if the buffer provided by your allocator was not large enough to hold the data. In this case the OS will discard the data that could not fit (That's UDP for you!). 💀

udp-dhcp/main.c — Reading packets

void on_read(uv_udp_t *req, ssize_t nread, const uv_buf_t *buf, const struct sockaddr *addr, unsigned flags) {
    if (nread < 0) {
        fprintf(stderr, "Read error %s\n", uv_err_name(nread));
        uv_close((uv_handle_t*) req, NULL);
        free(buf->base);
        return;
    }

    char sender[17] = { 0 };
    uv_ip4_name((const struct sockaddr_in*) addr, sender, 16);
    fprintf(stderr, "Recv from %s\n", sender);

    // ... DHCP specific code
    unsigned int *as_integer = (unsigned int*)buf->base;
    unsigned int ipbin = ntohl(as_integer[4]);
    unsigned char ip[4] = {0};
    int i;
    for (i = 0; i < 4; i++)
        ip[i] = (ipbin >> i*8) & 0xff;
    fprintf(stderr, "Offered IP %d.%d.%d.%d\n", ip[3], ip[2], ip[1], ip[0]);

    free(buf->base);
    uv_udp_recv_stop(req);
}

�蝴蝶 UDP Options 🦋

Okay bestie, UDP has some little knobs and honestly they’re giving “small but powerful.” Let’s go through them.

⏳ Time-to-live ⏳

The TTL of packets sent on the socket can be changed using uv_udp_set_ttl.

🪩 IPv6 stack only 🪩

IPv6 sockets can be used for both IPv4 and IPv6 communication. If you want to restrict the socket to IPv6 only, pass the UV_UDP_IPV6ONLY flag to uv_udp_bind.

🌈 Multicast 🌈

A socket can (un)subscribe to a multicast group using:

where membership is UV_JOIN_GROUP or UV_LEAVE_GROUP.

The concepts of multicasting are nicely explained in this guide <https://tldp.org/HOWTO/Multicast-HOWTO-2.html>.

Local loopback of multicast packets is enabled by default [2], use uv_udp_set_multicast_loop to switch it off.

The packet time-to-live for multicast packets can be changed using uv_udp_set_multicast_ttl.

🔍 Querying DNS 🔍

libuv provides asynchronous DNS resolution. For this it provides its own getaddrinfo replacement [3]. In the callback you can perform normal socket operations on the retrieved addresses. Let’s connect to Libera.chat to see an example of DNS resolution.

dns/main.c

int main() {
    loop = uv_default_loop();

    struct addrinfo hints;
    hints.ai_family = PF_INET;
    hints.ai_socktype = SOCK_STREAM;
    hints.ai_protocol = IPPROTO_TCP;
    hints.ai_flags = 0;

    uv_getaddrinfo_t resolver;
    fprintf(stderr, "irc.libera.chat is... ");
    int r = uv_getaddrinfo(loop, &resolver, on_resolved, "irc.libera.chat", "6667", &hints);

    if (r) {
        fprintf(stderr, "getaddrinfo call error %s\n", uv_err_name(r));
        return 1;
    }
    return uv_run(loop, UV_RUN_DEFAULT);
}

If uv_getaddrinfo returns non-zero, something went wrong in the setup and your callback won’t be invoked at all. All arguments can be freed immediately after uv_getaddrinfo returns. The hostname, servname and hints structures are documented in the getaddrinfo man page <https://man7.org/linux/man-pages/man3/getaddrinfo.3.html>. The callback can be NULL in which case the function will run synchronously.

In the resolver callback, you can pick any IP from the linked list of struct addrinfo(s). This also demonstrates uv_tcp_connect. It is necessary to call uv_freeaddrinfo in the callback.

dns/main.c

void on_resolved(uv_getaddrinfo_t *resolver, int status, struct addrinfo *res) {
    if (status < 0) {
        fprintf(stderr, "getaddrinfo callback error %s\n", uv_err_name(status));
        return;
    }

    char addr[17] = {'\0'};
    uv_ip4_name((struct sockaddr_in*) res->ai_addr, addr, 16);
    fprintf(stderr, "%s\n", addr);

    uv_connect_t *connect_req = (uv_connect_t*) malloc(sizeof(uv_connect_t));
    uv_tcp_t *socket = (uv_tcp_t*) malloc(sizeof(uv_tcp_t));
    uv_tcp_init(loop, socket);

    uv_tcp_connect(connect_req, socket, (const struct sockaddr*) res->ai_addr, on_connect);

    uv_freeaddrinfo(res);
}

libuv also provides the inverse uv_getnameinfo <https://docs.libuv.org/en/v1.x/dns.html#c.uv_getnameinfo>.

🌐 Network interfaces 🌐

Information about the system’s network interfaces can be obtained through libuv using uv_interface_addresses. This simple program just prints out all the interface details so you get an idea of the fields that are available. This is useful to allow your service to bind to IP addresses when it starts.

interfaces/main.c

#include <stdio.h>
#include <uv.h>

int main() {
    char buf[512];
    uv_interface_address_t *info;
    int count, i;

    uv_interface_addresses(&info, &count);
    i = count;

    printf("Number of interfaces: %d\n", count);
    while (i--) {
        uv_interface_address_t interface_a = info[i];

        printf("Name: %s\n", interface_a.name);
        printf("Internal? %s\n", interface_a.is_internal ? "Yes" : "No");

        if (interface_a.address.address4.sin_family == AF_INET) {
            uv_ip4_name(&interface_a.address.address4, buf, sizeof(buf));
            printf("IPv4 address: %s\n", buf);
        }
        else if (interface_a.address.address4.sin_family == AF_INET6) {
            uv_ip6_name(&interface_a.address.address6, buf, sizeof(buf));
            printf("IPv6 address: %s\n", buf);
        }

        printf("\n");
    }

    uv_free_interface_addresses(info, count);
    return 0;
}

is_internal is true for loopback interfaces. Note that if a physical interface has multiple IPv4/IPv6 addresses, the name will be reported multiple times, with each address being reported once.

---

• [1] <https://beej.us/guide/bgnet/html/#broadcast-packetshello-world>
• [2] <https://tldp.org/HOWTO/Multicast-HOWTO-6.html#ss6.1>
• [3] libuv use the system getaddrinfo in the libuv threadpool. libuv v0.8.0 and earlier also included c-ares <https://c-ares.org/> as an alternative, but this has been removed in v0.9.0.

🧵 Threads 🧵

Wait a minute? Why are we on threads? Aren’t event loops supposed to be the way to do web-scale programming? Well... no. Threads are still the medium in which processors do their jobs. Threads are therefore mighty useful sometimes, even though you might have to wade through various synchronization primitives.

Threads are used internally to fake the asynchronous nature of all of the system calls. libuv also uses threads to allow you, the application, to perform a task asynchronously that is actually blocking, by spawning a thread and collecting the result when it is done.

Today there are two predominant thread libraries: the Windows threads implementation and POSIX’s pthreads(7) <https://man7.org/linux/man-pages/man7/pthreads.7.html>. libuv’s thread API is analogous to the pthreads API and often has similar semantics.

A notable aspect of libuv’s thread facilities is that it is a self contained section within libuv. Whereas other features intimately depend on the event loop and callback principles, threads are complete agnostic, they block as required, signal errors directly via return values, and, as shown in the first example, don’t even require a running event loop.

libuv’s thread API is also very limited since the semantics and syntax of threads are different on all platforms, with different levels of completeness.

This chapter makes the following assumption: There is only one event loop, running in one thread (the main thread). No other thread interacts with the event loop (except using uv_async_send).

🧵 Core thread operations 🧵

There isn’t much here, you just start a thread using uv_thread_create() and wait for it to close using uv_thread_join().

thread-create/main.c

int tracklen = 10;
uv_thread_t hare_id;
uv_thread_t tortoise_id;
uv_thread_create(&hare_id, hare, &tracklen);
uv_thread_create(&tortoise_id, tortoise, &tracklen);

uv_thread_join(&hare_id);
uv_thread_join(&tortoise_id);
return 0;
}

Tip: uv_thread_t is just an alias for pthread_t on Unix, but this is an implementation detail, avoid depending on it to always be true.

The second parameter is the function which will serve as the entry point for the thread, the last parameter is a void * argument which can be used to pass custom parameters to the thread. The function hare will now run in a separate thread, scheduled pre-emptively by the operating system:

thread-create/main.c

int tracklen = *((int *) arg);
while (tracklen) {
    tracklen--;
    uv_sleep(1000);
    fprintf(stderr, "Hare ran another step\n");
}
fprintf(stderr, "Hare done running!\n");
}

Unlike pthread_join() which allows the target thread to pass back a value to the calling thread using a second parameter, uv_thread_join() does not. To send values use Inter-thread communication.

🧷 Synchronization Primitives 🧷

This section is purposely spartan. This book is not about threads, so I only catalogue any surprises in the libuv APIs here. For the rest you can look at the pthreads(7) <https://man7.org/linux/man-pages/man7/pthreads.7.html> man pages.

🔒 Mutexes 🔒

The mutex functions are a direct map to the pthread equivalents.

libuv mutex functions

int uv_mutex_init(uv_mutex_t* handle);
int uv_mutex_init_recursive(uv_mutex_t* handle);
void uv_mutex_destroy(uv_mutex_t* handle);
void uv_mutex_lock(uv_mutex_t* handle);
int uv_mutex_trylock(uv_mutex_t* handle);
void uv_mutex_unlock(uv_mutex_t* handle);

The uv_mutex_init(), uv_mutex_init_recursive() and uv_mutex_trylock() functions will return 0 on success, and an error code otherwise.

If libuv has been compiled with debugging enabled, uv_mutex_destroy(), uv_mutex_lock() and uv_mutex_unlock() will abort() on error. Similarly uv_mutex_trylock() will abort if the error is anything other than EAGAIN or EBUSY.

Recursive mutexes are supported, but you should not rely on them. Also, they should not be used with uv_cond_t variables.

The default BSD mutex implementation will raise an error if a thread which has locked a mutex attempts to lock it again. For example, a construct like:

uv_mutex_init(a_mutex);
uv_mutex_lock(a_mutex);
uv_thread_create(thread_id, entry, (void *)a_mutex);
uv_mutex_lock(a_mutex);
// more things here

can be used to wait until another thread initializes some stuff and then unlocks a_mutex but will lead to your program crashing if in debug mode, or return an error in the second call to uv_mutex_lock().

Note: Mutexes on Windows are always recursive.

🔓 Locks 🔓

Read-write locks are a more granular access mechanism. Two readers can access shared memory at the same time. A writer may not acquire the lock when it is held by a reader. A reader or writer may not acquire a lock when a writer is holding it. Read-write locks are frequently used in databases. Here is a toy example.

locks/main.c - simple rwlocks

#include <stdio.h>
#include <uv.h>

uv_barrier_t blocker;
uv_rwlock_t numlock;
int shared_num;

void reader(void *n)
{
    int num = *(int *)n;
    int i;
    for (i = 0; i < 20; i++) {
        uv_rwlock_rdlock(&numlock);
        printf("Reader %d: acquired lock\n", num);
        printf("Reader %d: shared num = %d\n", num, shared_num);
        uv_rwlock_rdunlock(&numlock);
        printf("Reader %d: released lock\n", num);
    }
    uv_barrier_wait(&blocker);
}

          void writer(void *n)
          {
              int num = *(int *)n;
              int i;
              for (i = 0; i < 20; i++) {
                  uv_rwlock_wrlock(&numlock);
                  printf("Writer %d: acquired lock\n", num);
                  shared_num++;
                  printf("Writer %d: incremented shared num = %d\n", num, shared_num);
                  uv_rwlock_wrunlock(&numlock);
                  printf("Writer %d: released lock\n", num);
              }
              uv_barrier_wait(&blocker);
          }

          int main()
          {
              uv_barrier_init(&blocker, 4);

              shared_num = 0;
              uv_rwlock_init(&numlock);

              uv_thread_t threads[3];

              int thread_nums[] = {1, 2, 1};
              uv_thread_create(&threads[0], reader, &thread_nums[0]);
              uv_thread_create(&threads[1], reader, &thread_nums[1]);

              uv_thread_create(&threads[2], writer, &thread_nums[2]);

              uv_barrier_wait(&blocker);
              uv_barrier_destroy(&blocker);

              uv_rwlock_destroy(&numlock);
              return 0;
          }

Run this and literally just watch — the readers will sometimes overlap 💅 like, yes bestie, that's the whole point. And when you've got multiple writers? Schedulers usually give them higher priority, so if you add two writers you'll see both writers tend to finish first before the readers get a chance again. Obsessed with the drama of it honestly.

We also use barriers in the example above so the main thread can wait for all readers and writers to indicate they have ended 🫶 (yes, the uv_barrier_wait(&blocker) in main — that's the "are we all done" check-in, iconic behaviour).

---

🎀 Others 🎀

libuv also supports semaphores, condition variables and barriers — with APIs very similar to their pthread counterparts. Here's where to read up if you want the lore:

• semaphores — https://en.wikipedia.org/wiki/Semaphore_(programming)
• condition variables — https://en.wikipedia.org/wiki/Monitor_(synchronization)#Condition_variables_2
• barriers — https://en.wikipedia.org/wiki/Barrier_(computer_science)

In addition, libuv provides a convenience function uv_once(). Multiple threads can attempt to call uv_once() with a given guard and a function pointer — only the first one will win, and the function gets called once and only once. No cap, one singular time:

/* Initialize guard */
static uv_once_t once_only = UV_ONCE_INIT;

int i = 0;

void increment() {
    i++;
}

void thread1() {
    /* ... work */
    uv_once(once_only, increment);
}

void thread2() {
    /* ... work */
    uv_once(once_only, increment);
}

int main() {
    /* ... spawn threads */
}

After all threads are done, i == 1. That's it. That's the whole flex ✨

libuv v0.11.11 onwards also added a uv_key_t struct and api for thread-local storage — https://docs.libuv.org/en/v1.x/threading.html#thread-local-storage 🎀

---

🌸 libuv work queue 🌸

uv_queue_work() is a convenience function that lets an application run a task in a separate thread, and have a callback triggered when the task is done. Sounds simple, right? What makes uv_queue_work() so tempting is that it allows potentially any third-party libraries to be used with the event-loop paradigm. Because bestie — when you use event loops, it is imperative to make sure that no function which runs periodically in the loop thread blocks when performing I/O or is a serious CPU hog. Why? Because that means the loop slows down and events are not being handled at full capacity 😭

However, a lot of existing code out there features blocking functions (for example a routine which performs I/O under the hood) to be used with threads if you want responsiveness — the classic 'one thread per client' server model — and getting them to play with an event loop library generally involves rolling your own system of running the task in a separate thread. libuv just provides a convenient abstraction for this. King behaviour, honestly 👑

Here's a simple example inspired by node.js is cancer — http://widgetsandshit.com/teddziuba/2011/10/node-js-is-cancer.html. We're going to calculate fibonacci numbers, sleeping a bit along the way, but run it in a separate thread so that the blocking and CPU bound task does not prevent the event loop from performing other activities.

queue-work/main.c — lazy fibonacci:

void fib(uv_work_t *req) {
    int n = *(int *) req->data;
    if (random() % 2)
        sleep(1);
    else
        sleep(3);
    long fib = fib_(n);
    fprintf(stderr, "%dth fibonacci is %lu\n", n, fib);
}

void after_fib(uv_work_t *req, int status) {
    fprintf(stderr, "Done calculating %dth fibonacci\n", *(int *) req->data);
}

The actual task function is simple — nothing to show that it's going to be run in a separate thread. The uv_work_t structure is the clue 🔍 You can pass arbitrary data through it using the void* data field and use it to communicate to and from the thread. But be sure you are using proper locks if you're changing things while both threads may be running. Do not skip that part, I'm begging 🙈

The trigger is uv_queue_work:

queue-work/main.c:

int main() {
    loop = uv_default_loop();

    int data[FIB_UNTIL];
    uv_work_t req[FIB_UNTIL];
    int i;
    for (i = 0; i < FIB_UNTIL; i++) {
        data[i] = i;
        req[i].data = (void *) &data[i];
        uv_queue_work(loop, &req[i], fib, after_fib);
    }

    return uv_run(loop, UV_RUN_DEFAULT);
}

The thread function will be launched in a separate thread, passed the uv_work_t structure, and once the function returns, the after function will be called on the thread the event loop is running in. It'll be passed the same structure. Symmetry, we love to see it 💖

For writing wrappers to blocking libraries, a common pattern #baton is to use a baton to exchange data.

Since libuv version 0.9.4 an additional function, uv_cancel(), is available. This allows you to cancel tasks on the libuv work queue. Only tasks that are yet to be started can be cancelled. If a task has already started executing, or it has finished executing, uv_cancel() will fail. Read that again, bestie — it's not a magic undo button 🔥

uv_cancel() is useful to cleanup pending tasks if the user requests termination. For example, a music player may queue up multiple directories to be scanned for audio files. If the user terminates the program, it should quit quickly and not wait until all pending requests are run. Nobody's got time for that.

Let's modify the fibonacci example to demonstrate uv_cancel(). We first set up a signal handler for termination.

queue-cancel/main.c:

int main() {
    loop = uv_default_loop();

    int data[FIB_UNTIL];
    int i;
    for (i = 0; i < FIB_UNTIL; i++) {
        data[i] = i;
        fib_reqs[i].data = (void *) &data[i];
        uv_queue_work(loop, &fib_reqs[i], fib, after_fib);
    }

    uv_signal_t sig;
    uv_signal_init(loop, &sig);
    uv_signal_start(&sig, signal_handler, SIGINT);

    return uv_run(loop, UV_RUN_DEFAULT);
}

When the user triggers the signal by pressing Ctrl+C we send uv_cancel() to all the workers. uv_cancel() will return 0 for those tasks that are pending execution and could be cancelled ✨

queue-cancel/main.c:

void signal_handler(uv_signal_t *req, int signum)
{
    printf("Signal received!\n");
    int i;
    for (i = 0; i < FIB_UNTIL; i++) {
        uv_cancel((uv_req_t*) &fib_reqs[i]);
    }
    uv_signal_stop(req);
}

For tasks that do get cancelled successfully, the after function is called with status set to UV_ECANCELED. Sad but correct 😭

queue-cancel/main.c:

void after_fib(uv_work_t *req, int status) {
    if (status == UV_ECANCELED)
        fprintf(stderr, "Calculation of %d cancelled.\n", *(int *) req->data);
}

uv_cancel() can also be used with uv_fs_t and uv_getaddrinfo_t requests. For the filesystem family of functions, uv_fs_t.errorno will be set to UV_ECANCELED.

Tip: a well designed program would have a way to terminate long running workers that have already started executing. Such a worker could periodically check for a variable that only the main process sets to signal termination. Big brain move tbh 🧠✨

---

🦋 Inter-thread communication 🦋

Sometimes you want various threads to actually send each other messages while they're running. For example you might be running some long duration task in a separate thread (perhaps using uv_queue_work) but want to notify progress to the main thread. This is a simple example of having a download manager informing the user of the status of running downloads 💅

progress/main.c — the original listing is split up across the page, so here it is exactly as it appears:

uv_loop_t *loop;
}

void print_progress(uv_async_t *handle) {
    double pct = atomic_load_explicit(&percentage, memory_order_acquire);
    fprintf(stderr, "Downloaded %.2f%%\n", pct);
}

int main() {
    loop = uv_default_loop();

    uv_work_t req;
    int size = 10240;
    req.data = (void*) &size;

    uv_async_init(loop, &async, print_progress);
    uv_queue_work(loop, &req, fake_download, after);
    return uv_run(loop, UV_RUN_DEFAULT);
}

The async thread communication works on loops, so although any thread can be the message sender, only threads with libuv loops can be receivers (or rather the loop is the receiver). libuv will invoke the callback (print_progress) with the async watcher whenever it receives a message 🎀

Warning: it is important to realize that since the message send is async, the callback may be invoked immediately after uv_async_send is called in another thread, or it may be invoked after some time. libuv may also combine multiple calls to uv_async_send and invoke your callback only once. The only guarantee that libuv makes is: the callback function is called at least once after the call to uv_async_send. If you have no pending calls to uv_async_send, the callback won't be called. If you make two or more calls, and libuv hasn't had a chance to run the callback yet, it may invoke your callback only once for the multiple invocations of uv_async_send. Your callback will never be called twice for just one event. Periodt 💀

progress/main.c:

_Atomic double percentage;

void fake_download(uv_work_t *req) {
    int size = *((int*) req->data);
    int downloaded = 0;
    double pct;
    while (downloaded < size) {
        pct = downloaded * 100.0 / size;
        atomic_store_explicit(&percentage, pct, memory_order_release);
        uv_async_send(&async);

        sleep(1);
        downloaded += (200+random())%1000; // can only download max 1000bytes/sec,
                                           // but at least a 200;

In the download function, we modify the progress indicator and queue the message for delivery with uv_async_send. Remember: uv_async_send is also non-blocking and will return immediately 🔥

progress/main.c:

void after(uv_work_t *req, int status) {
    fprintf(stderr, "Download complete\n");
    uv_close((uv_handle_t*) &async, NULL);

okay so that callback is literally the standard libuv pattern — it’s doing the thing where it extracts the data from the watcher. And bestie, please remember to clean up the watcher at the end, it’s important 💅

progress/main.c

// Ensure final 100% progress update is sent
pct = 100.0;
atomic_store_explicit(&percentage, pct, memory_order_release);
uv_async_send(&async);

After this example — which lowkey showed the abuse of the data field — bnoordhuis (GitHub: https://github.com/bnoordhuis) pointed out that using the data field is not thread safe, and uv_async_send() is actually only meant to wake up the event loop. Use a mutex or rwlock to make sure accesses are performed in the right order.

Note: mutexes and rwlocks DO NOT work inside a signal handler, whereas uv_async_send does.

One use case where uv_async_send is required is when interoperating with libraries that require thread affinity for their functionality. For example in node.js, a v8 engine instance, contexts and its objects are bound to the thread that the v8 instance was started in. Interacting with v8 data structures from another thread can lead to undefined results. Now consider some node.js module which binds a third party library. It may go something like this:

1. In node, the third party library is set up with a JavaScript callback to be invoked for more information:

var lib = require('lib');
lib.on_progress(function() {
    console.log("Progress");
});

lib.do();

// do other stuff

2. lib.do is supposed to be non-blocking but the third party lib is blocking, so the binding uses uv_queue_work.
3. The actual work being done in a separate thread wants to invoke the progress callback, but cannot directly call into v8 to interact with JavaScript. So it uses uv_async_send.
4. The async callback, invoked in the main loop thread, which is the v8 thread, then interacts with v8 to invoke the JavaScript callback.

---

🌈 Processes 🌈

libuv offers considerable child process management, abstracting the platform differences and allowing communication with the child process using streams or named pipes.

A common idiom in Unix is for every process to do one thing and do it well. In such a case, a process often uses multiple child processes to achieve tasks (similar to using pipes in shells). A multi-process model with messages may also be easier to reason about compared to one with threads and shared memory.

A common refrain against event-based programs is that they cannot take advantage of multiple cores in modern computers. In a multi-threaded program the kernel can perform scheduling and assign different threads to different cores, improving performance. But an event loop has only one thread. The workaround can be to launch multiple processes instead, with each process running an event loop, and each process getting assigned to a separate CPU core ✨

🍼 Spawning child processes 🍼

The simplest case is when you simply want to launch a process and know when it exits. This is achieved using uv_spawn.

spawn/main.c

uv_loop_t *loop;
uv_process_t child_req;
uv_process_options_t options;
int main() {
    loop = uv_default_loop();

    char* args[3];
    args[0] = "mkdir";
    args[1] = "test-dir";
    args[2] = NULL;

    options.exit_cb = on_exit;
    options.file = "mkdir";
    options.args = args;

    int r;
    if ((r = uv_spawn(loop, &child_req, &options))) {
        fprintf(stderr, "%s\n", uv_strerror(r));
        return 1;
    } else {
        fprintf(stderr, "Launched process with ID %d\n", child_req.pid);
    }

    return uv_run(loop, UV_RUN_DEFAULT);
}

Note: options is implicitly initialized with zeros since it is a global variable. If you change options to a local variable, remember to initialize it to null out all unused fields: c uv_process_options_t options = {0};

The uv_process_t struct only acts as the handle, all options are set via uv_process_options_t. To simply launch a process, you need to set only the file and args fields. file is the program to execute. Since uv_spawn uses execvp(3) internally, there is no need to supply the full path. Finally as per underlying conventions, the arguments array has to be one larger than the number of arguments, with the last element being NULL.

After the call to uv_spawn, uv_process_t.pid will contain the process ID of the child process.

The exit callback will be invoked with the exit status and the type of signal which caused the exit.

Note that it is important not to call uv_close before the exit callback.

spawn/main.c

void on_exit(uv_process_t *req, int64_t exit_status, int term_signal) {
    fprintf(stderr, "Process exited with status %" PRId64 ", signal %d\n", exit_status, term_signal);
    uv_close((uv_handle_t*) req, NULL);

It is required to close the process watcher after the process exits.

🔧 Changing process parameters 🔧

Before the child process is launched you can control the execution environment using fields in uv_process_options_t.

📁 Change execution directory 📁

Set uv_process_options_t.cwd to the corresponding directory.

🌱 Set environment variables 🌱

uv_process_options_t.env is a null-terminated array of strings, each of the form VAR=VALUE used to set up the environment variables for the process. Set this to NULL to inherit the environment from the parent (this) process.

🚩 Option flags 🚩

Setting uv_process_options_t.flags to a bitwise OR of the following flags, modifies the child process behaviour:

• UV_PROCESS_SETUID — sets the child’s execution user ID to uv_process_options_t.uid.
• UV_PROCESS_SETGID — sets the child’s execution group ID to uv_process_options_t.gid.

Changing the UID/GID is only supported on Unix, uv_spawn will fail on Windows with UV_ENOTSUP.

• UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS — No quoting or escaping of uv_process_options_t.args is done on Windows. Ignored on Unix.
• UV_PROCESS_DETACHED — Starts the child process in a new session, which will keep running after the parent process exits. See example below.

🧨 Detaching processes 🧨

Passing the flag UV_PROCESS_DETACHED can be used to launch daemons, or child processes which are independent of the parent so that the parent exiting does not affect it.

detach/main.c

int main() {
    loop = uv_default_loop();

    char* args[3];
    args[0] = "sleep";
    args[1] = "100";
    args[2] = NULL;

    options.exit_cb = NULL;
    options.file = "sleep";
    options.args = args;
    options.flags = UV_PROCESS_DETACHED;

    int r;
    if ((r = uv_spawn(loop, &child_req, &options))) {
        fprintf(stderr, "%s\n", uv_strerror(r));
        return 1;
    }
    fprintf(stderr, "Launched sleep with PID %d\n", child_req.pid);
    uv_unref((uv_handle_t*) &child_req);

    return uv_run(loop, UV_RUN_DEFAULT);

Just remember that the handle is still monitoring the child, so your program won’t exit. Use uv_unref() if you want to be more fire-and-forget 🔥

📡 Sending signals to processes 📡

libuv wraps the standard kill(2) system call on Unix and implements one with similar semantics on Windows, with one caveat: all of SIGTERM, SIGINT and SIGKILL, lead to termination of the process. The signature of uv_kill is:

uv_err_t uv_kill(int pid, int signum);

For processes started using libuv, you may use uv_process_kill instead, which accepts the uv_process_t watcher as the first argument, rather than the pid. In this case, remember to call uv_close on the watcher after the exit callback has been called.

🚨 Signals 🚨

libuv provides wrappers around Unix signals with some Windows support (https://docs.libuv.org/en/v1.x/signal.html#signal) as well.

Use uv_signal_init() to initialize a handle and associate it with a loop. To listen for particular signals on that handler, use uv_signal_start() with the handler function. Each handler can only be associated with one signal number, with subsequent calls to uv_signal_start() overwriting earlier associations. Use uv_signal_stop() to stop watching. Here is a small example demonstrating the various possibilities:

signal/main.c

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <uv.h>

uv_loop_t* create_loop()
{
    uv_loop_t *loop = malloc(sizeof(uv_loop_t));
    if (loop) {
      uv_loop_init(loop);
    }
    return loop;
}

void signal_handler(uv_signal_t *handle, int signum)
{
    printf("Signal received: %d\n", signum);
    uv_signal_stop(handle);
}

// two signal handlers in one loop
void thread1_worker(void *userp)
{
    uv_loop_t *loop1 = create_loop();

    uv_signal_t sig1a, sig1b;
    uv_signal_init(loop1, &sig1a);
    uv_signal_start(&sig1a, signal_handler, SIGUSR1);

    uv_signal_init(loop1, &sig1b);
    uv_signal_start(&sig1b, signal_handler, SIGUSR1);

    uv_run(loop1, UV_RUN_DEFAULT);
}

// two signal handlers, each in its own loop
void thread2_worker(void *userp)
{
    uv_loop_t *loop2 = create_loop();
    uv_loop_t *loop3 = create_loop();

    uv_signal_t sig2;
    uv_signal_init(loop2, &sig2);
    uv_signal_start(&sig2, signal_handler, SIGUSR1);

    uv_signal_t sig3;
    uv_signal_init(loop3, &sig3);
    uv_signal_start(&sig3, signal_handler, SIGUSR1);

    while (uv_run(loop2, UV_RUN_NOWAIT) || uv_run(loop3, UV_RUN_NOWAIT)) {
    }
}

int main()
{
    printf("PID %d\n", getpid());

    uv_thread_t thread1, thread2;

    uv_thread_create(&thread1, thread1_worker, 0);
    uv_thread_create(&thread2, thread2_worker, 0);

    uv_thread_join(&thread1);
    uv_thread_join(&thread2);
    return 0;
}

Note: uv_run(loop, UV_RUN_NOWAIT) is similar to uv_run(loop, UV_RUN_ONCE) in that it will process only one event. UV_RUN_ONCE blocks if there are no pending events, while UV_RUN_NOWAIT will return immediately. We use NOWAIT so that one of the loops isn’t starved because the other one has no pending activity.

...so you send SIGUSR1 to the process, and bestie, your handler gets invoked 4 times — one for each uv_signal_t. The handler here just stops each handle so the program exits. This whole dispatch-to-all-handlers thing is lowkey gorgeous and super useful. Picture a server running multiple event loops that needs to make sure all data is safely saved before termination — every loop just adds a watcher for SIGINT and you're done. Iconic. 💅

🧸 Child Process I/O

okay so a normal, newly spawned process has its own set of file descriptors, with 0, 1 and 2 being stdin, stdout and stderr respectively. But sometimes you want to share file descriptors with the child. Like, say your app launches a sub-command and you want any errors to go in the log file, but you want to ignore stdout. For that you'd want the child's stderr to be the same as the parent's stderr. And yes — libuv supports inheriting file descriptors, slay ✨

In this sample we invoke the test program, which is:

proc-streams/test.c

#include <stdio.h>

int main()
{
    fprintf(stderr, "This is stderr\n");
    printf("This is stdout\n");
    return 0;
}

The actual program proc-streams runs this while sharing only stderr. The file descriptors of the child process get set using the stdio field in uv_process_options_t. First set the stdio_count field to the number of file descriptors being set. uv_process_options_t.stdio is an array of uv_stdio_container_t, which is:

typedef struct uv_stdio_container_s {
    uv_stdio_flags flags;

    union {
        uv_stream_t* stream;
        int fd;
    } data;
} uv_stdio_container_t;

where flags can have several values. Use UV_IGNORE if it isn't going to be used. And heads up — if the first three stdio fields are marked as UV_IGNORE they'll redirect to /dev/null. 🫶

Since we want to pass on an existing descriptor, we'll use UV_INHERIT_FD. Then we set the fd to stderr.

proc-streams/main.c

int main() {
    loop = uv_default_loop();

    /* ... */

    options.stdio_count = 3;
    uv_stdio_container_t child_stdio[3];
    child_stdio[0].flags = UV_IGNORE;
    child_stdio[1].flags = UV_IGNORE;
    child_stdio[2].flags = UV_INHERIT_FD;
    child_stdio[2].data.fd = 2;
    options.stdio = child_stdio;

    options.exit_cb = on_exit;
    options.file = args[0];
    options.args = args;

    int r;
    if ((r = uv_spawn(loop, &child_req, &options))) {
        fprintf(stderr, "%s\n", uv_strerror(r));
        return 1;
    }

    return uv_run(loop, UV_RUN_DEFAULT);
}

If you run proc-stream you'll see that only the line "This is stderr" gets displayed. Try marking stdout as being inherited and see what the output does 👀

---

It is dead simple to apply this redirection to streams. By setting flags to UV_INHERIT_STREAM and setting data.stream to the stream in the parent process, the child process can treat that stream as standard I/O. This is literally how you'd implement something like CGI. 🦋

A sample CGI script/executable is:

cgi/tick.c

#include <stdio.h>
#include <unistd.h>

int main() {
    int i;
    for (i = 0; i < 10; i++) {
        printf("tick\n");
        fflush(stdout);
        sleep(1);
    }
    printf("BOOM!\n");
    return 0;
}

The CGI server combines the concepts from this chapter and Networking so that every client gets sent ten ticks, after which that connection is closed. 🎀

cgi/main.c

void on_new_connection(uv_stream_t *server, int status) {
    if (status == -1) {
        // error!
        return;
    }

    uv_tcp_t *client = (uv_tcp_t*) malloc(sizeof(uv_tcp_t));
    uv_tcp_init(loop, client);
    if (uv_accept(server, (uv_stream_t*) client) == 0) {
        invoke_cgi_script(client);
    }
    else {
        uv_close((uv_handle_t*) client, NULL);
    }

Here we simply accept the TCP connection and pass on the socket (stream) to invoke_cgi_script.

cgi/main.c

    args[1] = NULL;

    /* ... finding the executable path and setting up arguments ... */

    options.stdio_count = 3;
    uv_stdio_container_t child_stdio[3];
    child_stdio[0].flags = UV_IGNORE;
    child_stdio[1].flags = UV_INHERIT_STREAM;
    child_stdio[1].data.stream = (uv_stream_t*) client;
    child_stdio[2].flags = UV_IGNORE;
    options.stdio = child_stdio;

    options.exit_cb = cleanup_handles;
    options.file = args[0];
    options.args = args;

    // Set this so we can close the socket after the child process exits.
    child_req.data = (void*) client;
    int r;
    if ((r = uv_spawn(loop, &child_req, &options))) {
        fprintf(stderr, "%s\n", uv_strerror(r));

The stdout of the CGI script is set to the socket so that whatever our tick script prints gets sent straight to the client. By using processes we can offload the read/write buffering to the operating system, so in terms of convenience this is great 🌈 — just be warned that creating processes is a costly task. 😭

🔗 Parent-child IPC

A parent and child can have one or two way communication over a pipe created by setting uv_stdio_container_t.flags to a bit-wise combination of UV_CREATE_PIPE and UV_READABLE_PIPE or UV_WRITABLE_PIPE. The read/write flag is from the perspective of the child process. In this case, the uv_stream_t* stream field must be set to point to an initialized, unopened uv_pipe_t instance. 💜

🌊 New stdio Pipes

The uv_pipe_t structure represents more than just pipe(7) (or |), because it supports any streaming file-like objects. On Windows, the only object of that description is the Named Pipe. On Unix, this could be any of a Unix Domain Socket, or something derived from mkfifo(1), or it could actually be a pipe(7). When uv_spawn initializes a uv_pipe_t due to the UV_CREATE_PIPE flag, it opts for creating a socketpair(2). 😌

This is intended for the purpose of allowing multiple libuv processes to communicate with IPC. Which is discussed below. 👇

💌 Arbitrary process IPC

Since domain sockets [1] can have a well known name and a location in the file-system, they can be used for IPC between unrelated processes. The D-BUS system used by open source desktop environments uses domain sockets for event notification — various applications can then react when a contact comes online or new hardware is detected. The MySQL server also runs a domain socket on which clients can interact with it. ✨

When using domain sockets, a client-server pattern is usually followed with the creator/owner of the socket acting as the server. After the initial setup, messaging is no different from TCP, so we'll re-use the echo server example. 🐚

pipe-echo-server/main.c

void remove_sock(int sig) {
    uv_fs_t req;
    uv_fs_unlink(loop, &req, PIPENAME, NULL);
    exit(0);
}

int main() {
    loop = uv_default_loop();

    uv_pipe_t server;
    uv_pipe_init(loop, &server, 0);

    signal(SIGINT, remove_sock);

    int r;
    if ((r = uv_pipe_bind(&server, PIPENAME))) {
        fprintf(stderr, "Bind error %s\n", uv_err_name(r));
        return 1;
    }
    if ((r = uv_listen((uv_stream_t*) &server, 128, on_new_connection))) {
        fprintf(stderr, "Listen error %s\n", uv_err_name(r));
        return 2;
    }
    return uv_run(loop, UV_RUN_DEFAULT);
}

We name the socket echo.sock which means it will be created in the local directory. This socket now behaves no different from TCP sockets as far as the stream API is concerned. You can test this server using socat:

$ socat - /path/to/socket

A client which wants to connect to a domain socket will use:

void uv_pipe_connect(uv_connect_t *req, uv_pipe_t *handle, const char *name, uv_connect_cb cb);

where name will be echo.sock or similar. On Unix systems, name must point to a valid file (e.g. /tmp/echo.sock). On Windows, name follows a \\?\pipe\echo.sock format. 🪟

🎁 Sending file descriptors over pipes

The cool thing about domain sockets is that file descriptors can be exchanged between processes by sending them over a domain socket. This allows processes to hand off their I/O to other processes — applications include load-balancing servers, worker processes and other ways to make optimum use of CPU. libuv only supports sending TCP sockets or other pipes over pipes for now. ngl that's still pretty iconic. 👑

To demonstrate, we will look at an echo server implementation that hands off clients to worker processes in a round-robin fashion. This program is a bit involved, and while only snippets are included in the book, it is recommended to read the full code to really understand it. fr fr, go read it 📖

The worker process is quite simple, since the file-descriptor is handed over to it by the master.

multi-echo-server/worker.c

uv_loop_t *loop;
uv_pipe_t queue;
int main() {
    loop = uv_default_loop();

    uv_pipe_init(loop, &queue, 1 /* ipc */);
    uv_pipe_open(&queue, 0);
    uv_read_start((uv_stream_t*)&queue, alloc_buffer, on_new_connection);
    return uv_run(loop, UV_RUN_DEFAULT);
}

queue is the pipe connected to the master process on the other end, along which new file descriptors get sent. It is important to set the ipc argument of uv_pipe_init to 1 to indicate this pipe will be used for inter-process communication! Since the master will write the file handle to the standard input of the worker, we connect the pipe to stdin using uv_pipe_open. 💅

multi-echo-server/worker.c

void on_new_connection(uv_stream_t *q, ssize_t nread, const uv_buf_t *buf) {
    if (nread < 0) {
        if (nread != UV_EOF)
            fprintf(stderr, "Read error %s\n", uv_err_name(nread));
        uv_close((uv_handle_t*) q, NULL);
        return;
    }

    uv_pipe_t *pipe = (uv_pipe_t*) q;
    if (!uv_pipe_pending_count(pipe)) {
        fprintf(stderr, "No pending count\n");
        return;
    }

    uv_handle_type pending = uv_pipe_pending_type(pipe);
    assert(pending == UV_TCP);

...and the snippet cuts off right there 🫠 — hang tight, bestie, there's more coming 💖

uv_tcp_t *client = (uv_tcp_t*) malloc(sizeof(uv_tcp_t));
uv_tcp_init(loop, client);
if (uv_accept(q, (uv_stream_t*) client) == 0) {
    uv_os_fd_t fd;
    uv_fileno((const uv_handle_t*) client, &fd);
    fprintf(stderr, "Worker %d: Accepted fd %d\n", getpid(), fd);
    uv_read_start((uv_stream_t*) client, alloc_buffer, echo_read);
}
else {
    uv_close((uv_handle_t*) client, NULL);
}
}

Okay so first things first: we hit up uv_pipe_pending_count() to make sure there's actually a handle sitting there ready to be read out, bestie. Because if there isn't, you're just grabbing at air 💀. And if your program is the kind that could deal with different types of handles, uv_pipe_pending_type() tells you which type you're working with. iykyk.

Now, the accept in there might look weird — like, why are we accepting?? — but it genuinely makes sense, no cap. What accept traditionally does is get a file descriptor (the client) from another file descriptor (the listening socket). Which is exactly what we're doing here. We fetch the file descriptor (client) from the queue. From that point on the worker is just doing standard echo server stuff. Iconic. 💅

Turning now to the master — let's peek at how the workers get launched so we can do load balancing. main character energy only.

multi-echo-server/main.c

struct child_worker {
    uv_process_t req;
    uv_process_options_t options;
    uv_pipe_t pipe;
} *workers;

The child_worker structure wraps the process, and the pipe between the master and the individual process. Cute little bundle, honestly 🎀

multi-echo-server/main.c

void setup_workers() {
    round_robin_counter = 0;

    // ...

    // launch same number of workers as number of CPUs
    uv_cpu_info_t *info;
    int cpu_count;
    uv_cpu_info(&info, &cpu_count);
    uv_free_cpu_info(info, cpu_count);

    child_worker_count = cpu_count;

    workers = calloc(cpu_count, sizeof(struct child_worker));
    while (cpu_count--) {
        struct child_worker *worker = &workers[cpu_count];
        uv_pipe_init(loop, &worker->pipe, 1);

        uv_stdio_container_t child_stdio[3];
        child_stdio[0].flags = UV_CREATE_PIPE | UV_READABLE_PIPE;
        child_stdio[0].data.stream = (uv_stream_t*) &worker->pipe;
        child_stdio[1].flags = UV_IGNORE;
        child_stdio[2].flags = UV_INHERIT_FD;
        child_stdio[2].data.fd = 2;

        worker->options.stdio = child_stdio;
        worker->options.stdio_count = 3;

        worker->options.exit_cb = close_process_handle;
        worker->options.file = args[0];
        worker->options.args = args;

        uv_spawn(loop, &worker->req, &worker->options);
        fprintf(stderr, "Started worker %d\n", worker->req.pid);
    }
}

So in setting up the workers we use the nifty little libuv function uv_cpu_info to grab the number of CPUs, so we can launch an equal number of workers. Balance those loads, slay 🌸

And again — it is genuinely important to initialize the pipe that's acting as our IPC channel with that third argument as 1. Do not skip it, fr. Then we indicate that the child process' stdin is going to be a readable pipe (readable from the point of view of the child, just to be clear). Everything is straightforward till here. The workers are launched and they're just sitting there waiting for file descriptors to be written to their standard input 🦋

Then it's in on_new_connection (the TCP infrastructure is initialized in main()) that we accept the client socket and pass it along to the next worker in the round-robin. Chef's kiss scheduling.

multi-echo-server/main.c

void on_new_connection(uv_stream_t *server, int status) {
    if (status == -1) {
        // error!
        return;
    }

    uv_tcp_t *client = (uv_tcp_t*) malloc(sizeof(uv_tcp_t));
    uv_tcp_init(loop, client);
    if (uv_accept(server, (uv_stream_t*) client) == 0) {
        uv_write_t *write_req = (uv_write_t*) malloc(sizeof(uv_write_t));
        dummy_buf = uv_buf_init("a", 1);
        struct child_worker *worker = &workers[round_robin_counter];
        uv_write2(write_req, (uv_stream_t*) &worker->pipe, &dummy_buf, 1, (uv_stream_t*) client, NULL);
        round_robin_counter = (round_robin_counter + 1) % child_worker_count;
    }
    else {
        uv_close((uv_handle_t*) client, NULL);
    }
}

The uv_write2 call handles all the abstraction for us — it is literally just a matter of passing in the handle (client) as the right argument. And with that, our multi-process echo server is operational 🔥

Thanks to Kyle for pointing out <https://github.com/nikhilm/uvbook/issues/56> that uv_write2() requires a non-empty buffer even when sending handles. So like... yeah, that's a real thing, note it down 🙈

----

[1] In this section domain sockets stands in for named pipes on Windows as well.

✨ Advanced event loops ✨

libuv gives you a considerable amount of user control over event loops, and you can absolutely achieve interesting results by juggling multiple loops at once — like, full juggling routine, no notes 🤹‍♀️

You can also embed libuv's event loop into another event loop based library. Picture a Qt based UI, with Qt's event loop driving a libuv backend that's out there doing intensive system level tasks. Two loops, one vibe. 💜

🛑 Stopping an event loop

uv_stop() can be used to stop an event loop. But listen — the earliest the loop will stop running is on the next iteration, possibly later. Which means events that are ready to be processed in this iteration of the loop will still get processed. So uv_stop() can't be used as a kill switch. Not me learning that the hard way 😭

When uv_stop() is called, the loop won't block for i/o on this iteration. The semantics of these things can be a bit difficult to understand, so let's look at uv_run() where all the control flow occurs. Grab a snack, bestie 🍓

src/unix/core.c - uv_run

uv_signal_t* sh;

/* Note: while the handle is in the UV_HANDLE_CLOSING state now, it's still
 * possible for it to be active in the sense that uv__is_active() returns
 * true.
 *
 * A good example is when the user calls uv_shutdown(), immediately followed
 * by uv_close(). The handle is considered active at this point because the
 * completion of the shutdown req is still pending.
 */
assert(handle->flags & UV_HANDLE_CLOSING);
assert(!(handle->flags & UV_HANDLE_CLOSED));
handle->flags |= UV_HANDLE_CLOSED;

switch (handle->type) {
  case UV_PREPARE:
  case UV_CHECK:
  case UV_IDLE:
  case UV_ASYNC:
  case UV_TIMER:
  case UV_PROCESS:

stop_flag is set by uv_stop(). Now — all libuv callbacks are invoked within the event loop, which is exactly why invoking uv_stop() in them will still lead to this iteration of the loop occurring. First libuv updates timers, then runs pending timer, idle and prepare callbacks, and invokes any pending I/O callbacks. If you were to call uv_stop() in any of them, stop_flag would be set. That causes uv_backend_timeout() to return 0, which is why the loop does not block on I/O. If, on the other hand, you called uv_stop() in one of the check handlers, I/O has already finished and is not affected. Timing is everything, literally 💅

uv_stop() is useful to shut down a loop when a result has been computed or there's an error, without having to ensure that all handlers are stopped one by one. So convenient, honestly.

Here's a simple example that stops the loop and demonstrates how the current iteration of the loop still takes place 👑

uvstop/main.c

#include <stdio.h>
#include <uv.h>

int64_t counter = 0;

void idle_cb(uv_idle_t *handle) {
    printf("Idle callback\n");
    counter++;

    if (counter >= 5) {
        uv_stop(uv_default_loop());
        printf("uv_stop() called\n");
    }
}

void prep_cb(uv_prepare_t *handle) {
    printf("Prep callback\n");
}

int main() {
    uv_idle_t idler;
    uv_prepare_t prep;

    uv_idle_init(uv_default_loop(), &idler);
    uv_idle_start(&idler, idle_cb);

    uv_prepare_init(uv_default_loop(), &prep);
    uv_prepare_start(&prep, prep_cb);

    uv_run(uv_default_loop(), UV_RUN_DEFAULT);

    return 0;
}

🌈 Utilities 🌈

This chapter catalogues tools and techniques which are useful for common tasks. The libev man page <http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#COMMON_OR_USEFUL_IDIOMS_OR_BOTH> already covers some patterns which can be adopted to libuv through simple API changes. It also covers parts of the libuv API that don't require entire chapters dedicated to them. Efficient! We love a two-for-one 🫶

⏰ Timers

Timers invoke the callback after a certain time has elapsed since the timer was started. And libuv timers can also be set to invoke at regular intervals instead of just once. Recurring queen behaviour 👑

Simple use is to init a watcher and start it with a timeout, and optional repeat. Timers can be stopped at any time.

uv_timer_t timer_req;

uv_timer_init(loop, &timer_req);
uv_timer_start(&timer_req, callback, 5000, 2000);

That will start a repeating timer, which first starts 5 seconds (the timeout) after the execution of uv_timer_start, then repeats every 2 seconds (the repeat). Math is mathing ✨

Use:

uv_timer_stop(&timer_req);

to stop the timer. And this one can be used safely from within the callback as well, so no stress 💖

The repeat interval can be modified at any time with:

uv_timer_set_repeat(uv_timer_t *timer, int64_t repeat);

which will take effect when possible. And if this function is called from a timer callback, it means:

• If the timer was non-repeating, the timer has already been stopped. Use uv_timer_start again.
• If the timer is repeating, the next timeout has already been scheduled, so the old repeat interval will be used once more before the timer switches to the new interval.

The utility function:

int uv_timer_again(uv_timer_t *)

applies only to repeating timers and is equivalent to stopping the timer and then starting it with both initial timeout and repeat set to the old repeat value. If the timer hasn't been started it fails (error code UV_EINVAL) and returns -1. Sad times, but at least it tells you 😭

An actual timer example is in the reference count section. Coming up next, bestie —

🔁 Event loop reference count

The event loop only runs as long as there are active handles. That's the whole system, no cap. This works by having every handle increase the reference count of the event loop when it is started and decreasing the reference count when stopped. It's giving very tidy little ledger 📒

It's also possible to manually change the reference count of handles using:

void uv_ref(uv_handle_t*);
void uv_unref(uv_handle_t*);

These functions can be used to allow a loop to exit even when a watcher is active, or to use custom objects to keep the loop alive. So like — you get to decide who's keeping this party going 🎀

Okay so the latter can be used with interval timers — like, say you’ve got a garbage collector that runs every X seconds, or your network service sends a heartbeat to everyone periodically, but you do not want to have to stop those along all the clean exit paths or error scenarios. Or maybe you want the program to exit when all your other watchers are done. In that case, just unref the timer immediately after creation so that if it’s the only watcher running, uv_run will still exit. Slay.

This is also used in node.js where some libuv methods are being bubbled up to the JS API. A uv_handle_t (the superclass of all watchers) is created per JS object and can be ref/unrefed. Iconic.

ref-timer/main.c

uv_loop_t *loop;
uv_timer_t gc_req;
uv_timer_t fake_job_req;

int main() {
    loop = uv_default_loop();

    uv_timer_init(loop, &gc_req);
    uv_unref((uv_handle_t*) &gc_req);

    uv_timer_start(&gc_req, gc, 0, 2000);

    // could actually be a TCP download or something
    uv_timer_init(loop, &fake_job_req);
    uv_timer_start(&fake_job_req, fake_job, 9000, 0);
    return uv_run(loop, UV_RUN_DEFAULT);
}

We initialize the garbage collector timer, then immediately unref it. Observe how after 9 seconds, when the fake job is done, the program automatically exits, even though the garbage collector is still running. The vibe check passed 💅

🌸 Idler pattern 🌸

The callbacks of idle handles are invoked once per event loop. The idle callback can be used to perform some very low priority activity. For example, you could dispatch a summary of the daily application performance to the developers for analysis during periods of idleness, or use the application’s CPU time to perform SETI calculations :) An idle watcher is also useful in a GUI application. Say you are using an event loop for a file download. If the TCP socket is still being established and no other events are present, your event loop will pause (block), which means your progress bar will freeze and the user will face an unresponsive application. In such a case, queue up an idle watcher to keep the UI operational. Main character energy for the event loop, honestly.

idle-compute/main.c

uv_loop_t *loop;
uv_fs_t stdin_watcher;
uv_idle_t idler;
char buffer[1024];

int main() {
    loop = uv_default_loop();

    uv_idle_init(loop, &idler);

    uv_buf_t buf = uv_buf_init(buffer, 1024);
    uv_fs_read(loop, &stdin_watcher, 0, &buf, 1, -1, on_type);
    uv_idle_start(&idler, crunch_away);
    return uv_run(loop, UV_RUN_DEFAULT);
}

Here we initialize the idle watcher and queue it up along with the actual events we are interested in. crunch_away will now be called repeatedly until the user types something and presses Return. Then it will be interrupted for a brief amount as the loop deals with the input data, after which it will keep calling the idle callback again. It’s giving “multitasking but make it cute.” 🦋

idle-compute/main.c

void crunch_away(uv_idle_t* handle) {
    // Compute extra-terrestrial life
    // fold proteins
    // computer another digit of PI
    // or similar
    fprintf(stderr, "Computing PI...\n");
    // just to avoid overwhelming your terminal emulator
    uv_idle_stop(handle);
}

🫶 Passing data to worker thread 🫶

When using uv_queue_work you’ll usually need to pass complex data through to the worker thread. The solution is to use a struct and set uv_work_t.data to point to it. A slight variation is to have the uv_work_t itself as the first member of this struct (called a baton [1]). This allows cleaning up the work request and all the data in one free call. No cap, that’s efficient.

struct ftp_baton {
    uv_work_t req;
    char *host;
    int port;
    char *username;
    char *password;
}

ftp_baton *baton = (ftp_baton*) malloc(sizeof(ftp_baton));
baton->req.data = (void*) baton;
baton->host = strdup("my.webhost.com");
baton->port = 21;
// ...

uv_queue_work(loop, &baton->req, ftp_session, ftp_cleanup);

Here we create the baton and queue the task.

Now the task function can extract the data it needs:

void ftp_session(uv_work_t *req) {
    ftp_baton *baton = (ftp_baton*) req->data;

    fprintf(stderr, "Connecting to %s\n", baton->host);
}

void ftp_cleanup(uv_work_t *req) {
    ftp_baton *baton = (ftp_baton*) req->data;

    free(baton->host);
    // ...
    free(baton);
}

We then free the baton, which also frees the watcher. One little cleanup moment, zero chaos. 🎀

🔥 External I/O with polling 🔥

Usually third-party libraries will handle their own I/O, and keep track of their sockets and other files internally. In this case it isn’t possible to use the standard stream I/O operations, but the library can still be integrated into the libuv event loop. All that is required is that the library allow you to access the underlying file descriptors and provide functions that process tasks in small increments as decided by your application. Some libraries though will not allow such access, providing only a standard blocking function which will perform the entire I/O transaction and only then return. It is unwise to use these in the event loop thread — use the Thread pool work scheduling #threadpool instead. Of course, this will also mean losing granular control on the library. Sad but true, bestie.

The uv_poll section of libuv simply watches file descriptors using the operating system notification mechanism. In some sense, all the I/O operations that libuv implements itself are also backed by uv_poll-like code. Whenever the OS notices a change of state in file descriptors being polled, libuv will invoke the associated callback.

Here we will walk through a simple download manager that will use libcurl (https://curl.se/libcurl/) to download files. Rather than give all control to libcurl, we’ll instead be using the libuv event loop, and use the non-blocking, async multi (https://curl.se/libcurl/c/libcurl-multi.html) interface to progress with the download whenever libuv notifies of I/O readiness. It’s giving teamwork, honestly.

uvwget/main.c — The setup

#include <assert.h>
#include <stdio.h>
#include <stdlib.h>
#include <uv.h>
#include <curl/curl.h>

uv_loop_t *loop;
CURLM *curl_handle;
uv_timer_t timeout;
int main(int argc, char **argv) {
    loop = uv_default_loop();

    if (argc <= 1)
        return 0;

    if (curl_global_init(CURL_GLOBAL_ALL)) {
        fprintf(stderr, "Could not init cURL\n");
        return 1;
    }

    uv_timer_init(loop, &timeout);

    curl_handle = curl_multi_init();
    curl_multi_setopt(curl_handle, CURLMOPT_SOCKETFUNCTION, handle_socket);
    curl_multi_setopt(curl_handle, CURLMOPT_TIMERFUNCTION, start_timeout);

    while (argc-- > 1) {
        add_download(argv[argc], argc);
    }

    uv_run(loop, UV_RUN_DEFAULT);
    curl_multi_cleanup(curl_handle);
    return 0;
}

The way each library is integrated with libuv will vary. In the case of libcurl, we can register two callbacks. The socket callback handle_socket is invoked whenever the state of a socket changes and we have to start polling it. start_timeout is called by libcurl to notify us of the next timeout interval, after which we should drive libcurl forward regardless of I/O status. This is so that libcurl can handle errors or do whatever else is required to get the download moving.

Our downloader is to be invoked as:

$ ./uvwget [url1] [url2] ...

So we add each argument as a URL

uvwget/main.c — Adding urls

void add_download(const char *url, int num) {
    char filename[50];
    sprintf(filename, "%d.download", num);
    FILE *file;

    file = fopen(filename, "w");
    if (file == NULL) {
        fprintf(stderr, "Error opening %s\n", filename);
        return;
    }

    CURL *handle = curl_easy_init();
    curl_easy_setopt(handle, CURLOPT_WRITEDATA, file);
    curl_easy_setopt(handle, CURLOPT_URL, url);
    curl_multi_add_handle(curl_handle, handle);
    fprintf(stderr, "Added download %s -> %s\n", url, filename);
}

We let libcurl directly write the data to a file, but much more is possible if you so desire.

start_timeout will be called immediately the first time by libcurl, so things are set in motion. This simply starts a libuv timer #timers which drives curl_multi_socket_action with CURL_SOCKET_TIMEOUT whenever it times out. curl_multi_socket_action is what drives libcurl, and what we call whenever sockets change state. But before we go into that, we need to poll on sockets whenever handle_socket is called. Bestie, this is the glue.

uvwget/main.c — Setting up polling

void start_timeout(CURLM *multi, long timeout_ms, void *userp) {
    if (timeout_ms <= 0)
        timeout_ms = 1; /* 0 means directly call socket_action, but we'll do it in a bit */
    uv_timer_start(&timeout, on_timeout, timeout_ms, 0);
}

int handle_socket(CURL *easy, curl_socket_t s, int action, void *userp, void *socketp) {
    curl_context_t *curl_context;
    if (action == CURL_POLL_IN || action == CURL_POLL_OUT) {
        if (socketp) {
            curl_context = (curl_context_t*) socketp;
        }
        else {
            curl_context = create_curl_context(s);
            curl_multi_assign(curl_handle, s, (void *) curl_context);
        }
    }

    switch (action) {
        case CURL_POLL_IN:
            uv_poll_start(&curl_context->poll_handle, UV_READABLE, curl_perform);
            break;
        case CURL_POLL_OUT:
            uv_poll_start(&curl_context->poll_handle, UV_WRITABLE, curl_perform);
            break;
        case CURL_POLL_REMOVE:
            if (socketp) {
                uv_poll_stop(&((curl_context_t*)socketp)->poll_handle);
                destroy_curl_context((curl_context_t*) socketp);
                curl_multi_assign(curl_handle, s, NULL);
            }
            break;
        default:
            abort();
    }

    return 0;
}

We are interested in the socket fd s, and the action. For every socket we create a uv_poll_t handle if it doesn’t exist, and associate it with the socket using curl_multi_assign. This way socketp points to it whenever the callback is invoked.

In the case that the download is done or fails, libcurl requests removal of the poll. So we stop and free the poll handle. Clean exit, no crumbs. ✨

Depending on what events libcurl wishes to watch for, we start polling with UV_READABLE or UV_WRITABLE. That’s the vibe. Now libuv will invoke the poll callback whenever the socket is ready for reading or writing. Calling uv_poll_start multiple times on the same handle is totally acceptable — it will just update the events mask with the new value. curl_perform is the crux of this program.

uvwget/main.c — Driving libcurl.

          void curl_perform(uv_poll_t *req, int status, int events) {
              uv_timer_stop(&timeout);
              int running_handles;
              int flags = 0;
              if (status < 0)                      flags = CURL_CSELECT_ERR;
              if (!status && events & UV_READABLE) flags |= CURL_CSELECT_IN;
              if (!status && events & UV_WRITABLE) flags |= CURL_CSELECT_OUT;

              curl_context_t *context;

              context = (curl_context_t*)req;

              curl_multi_socket_action(curl_handle, context->sockfd, flags, &running_handles);
              check_multi_info();
          }

The first thing we do is stop the timer, because there’s been some progress in the interval. Then depending on what event triggered the callback, we set the correct flags. Then we call curl_multi_socket_action with the socket that progressed and the flags informing about what events happened. At this point libcurl does all of its internal tasks in small increments, and will attempt to return as fast as possible — which is exactly what an evented program wants in its main thread. libcurl keeps queueing messages into its own queue about transfer progress. In our case we are only interested in transfers that are completed. So we extract these messages, and clean up handles whose transfers are done.

uvwget/main.c — Reading transfer status.

          void check_multi_info(void) {
              char *done_url;
              CURLMsg *message;
              int pending;

              while ((message = curl_multi_info_read(curl_handle, &pending))) {
                  switch (message->msg) {
                  case CURLMSG_DONE:
                      curl_easy_getinfo(message->easy_handle, CURLINFO_EFFECTIVE_URL,
                                      &done_url);
                      printf("%s DONE\n", done_url);

                      curl_multi_remove_handle(curl_handle, message->easy_handle);
                      curl_easy_cleanup(message->easy_handle);
                      break;

                  default:
                      fprintf(stderr, "CURLMSG default\n");
                      abort();
                  }
              }
          }

Check & Prepare watchers 💭

TODO 💀

---

Loading libraries 📚

libuv provides a cross platform API to dynamically load shared libraries — the wiki link is https://en.wikipedia.org/wiki/Shared_library. This can be used to implement your own plugin/extension/module system and is used by node.js to implement require() support for bindings. The usage is quite simple as long as your library exports the right symbols. Be careful with sanity and security checks when loading third party code, otherwise your program will behave unpredictably. This example implements a very simple plugin system which does nothing except print the name of the plugin.

Let us first look at the interface provided to plugin authors.

plugin/plugin.h

          #ifndef UVBOOK_PLUGIN_SYSTEM
          #define UVBOOK_PLUGIN_SYSTEM

          // Plugin authors should use this to register their plugins with mfp.
          void mfp_register(const char *name);

          #endif

You can similarly add more functions that plugin authors can use to do useful things in your application [2]. A sample plugin using this API is:

plugin/hello.c

          #include "plugin.h"

          void initialize() {
              mfp_register("Hello World!");
          }

Our interface defines that all plugins should have an initialize function which will be called by the application. This plugin is compiled as a shared library and can be loaded by running our application:

$ ./plugin libhello.dylib
Loading libhello.dylib
Registered plugin "Hello World!"

Note: The shared library filename will be different depending on platforms. On Linux it is libhello.so.

This is done by using uv_dlopen to first load the shared library libhello.dylib. Then we get access to the initialize function using uv_dlsym and invoke it.

plugin/main.c

          #include "plugin.h"

          typedef void (*init_plugin_function)();

          void mfp_register(const char *name) {
              fprintf(stderr, "Registered plugin \"%s\"\n", name);
          }

          int main(int argc, char **argv) {
              if (argc == 1) {
                  fprintf(stderr, "Usage: %s [plugin1] [plugin2] ...\n", argv[0]);
                  return 0;
              }

              uv_lib_t lib;
              while (--argc) {
                  fprintf(stderr, "Loading %s\n", argv[argc]);
                  if (uv_dlopen(argv[argc], &lib)) {
                      fprintf(stderr, "Error: %s\n", uv_dlerror(&lib));
                      continue;
                  }

                  init_plugin_function init_plugin;
                  if (uv_dlsym(&lib, "initialize", (void **) &init_plugin)) {
                      fprintf(stderr, "dlsym error: %s\n", uv_dlerror(&lib));
                      continue;
                  }

                  init_plugin();
              }
              return 0;
          }

uv_dlopen expects a path to the shared library and sets the opaque uv_lib_t pointer. It returns 0 on success, -1 on error. Use uv_dlerror to get the error message.

uv_dlsym stores a pointer to the symbol in the second argument in the third argument. init_plugin_function is a function pointer to the sort of function we are looking for in the application's plugins.

---

TTY 🖥️

Text terminals have supported basic formatting for a long time, with a pretty standardised https://en.wikipedia.org/wiki/ANSI_escape_sequences command set. This formatting is often used by programs to improve the readability of terminal output. For example grep --colour. libuv provides the uv_tty_t abstraction (a stream) and related functions to implement the ANSI escape codes across all platforms. By this I mean that libuv converts ANSI codes to the Windows equivalent, and provides functions to get terminal information.

The first thing to do is to initialize a uv_tty_t with the file descriptor it reads/writes from. This is achieved with:

int uv_tty_init(uv_loop_t*, uv_tty_t*, uv_file fd, int unused)

The unused parameter is now auto-detected and ignored. It previously needed to be set to use uv_read_start() on the stream.

It is then best to use uv_tty_set_mode to set the mode to normal which enables most TTY formatting, flow-control and other settings. Other https://docs.libuv.org/en/v1.x/tty.html#c.uv_tty_mode_t modes are also available.

Remember to call uv_tty_reset_mode when your program exits to restore the state of the terminal. Just good manners. Another set of good manners is to be aware of redirection. If the user redirects the output of your command to a file, control sequences should not be written as they impede readability and grep. To check if the file descriptor is indeed a TTY, call uv_guess_handle with the file descriptor and compare the return value with UV_TTY.

Here is a simple example which prints white text on a red background:

tty/main.c

          #include <stdio.h>
          #include <string.h>
          #include <unistd.h>
          #include <uv.h>

          uv_loop_t *loop;
          uv_tty_t tty;

          int main() {
              uv_write_t req;
              uv_buf_t buf;
              uv_write_t req1;
              uv_buf_t buf1;

              loop = uv_default_loop();
              uv_tty_init(loop, &tty, STDOUT_FILENO, 0);
              uv_tty_set_mode(&tty, UV_TTY_MODE_NORMAL);

              if (uv_guess_handle(1) == UV_TTY) {
                  buf1.base = "\033[41;37m";
                  buf1.len = strlen(buf1.base);
                  uv_write(&req1, (uv_stream_t*) &tty, &buf1, 1, NULL);
              }

              buf.base = "Hello TTY\n";
              buf.len = strlen(buf.base);
              uv_write(&req, (uv_stream_t*) &tty, &buf, 1, NULL);

              uv_tty_reset_mode();
              return uv_run(loop, UV_RUN_DEFAULT);
          }

The final TTY helper is uv_tty_get_winsize() which is used to get the width and height of the terminal and returns 0 on success. Here is a small program which does some animation using the function and character position escape codes.

tty-gravity/main.c

          #include <stdio.h>
          #include <string.h>
          #include <unistd.h>
          #include <uv.h>

          uv_loop_t *loop;
          uv_tty_t tty;
          uv_timer_t tick;
          uv_write_t write_req;
          int width, height;
          int pos = 0;
          char *message = "  Hello TTY  ";

          void update(uv_timer_t *req) {
              char data[500];

              uv_buf_t buf;
              buf.base = data;
              buf.len = sprintf(data, "\033[2J\033[H\033[%dB\033[%luC\033[42;37m%s",
                                      pos,
                                      (unsigned long) (width-strlen(message))/2,
                                      message);
              uv_write(&write_req, (uv_stream_t*) &tty, &buf, 1, NULL);

              pos++;
              if (pos > height) {
                  uv_tty_reset_mode();
                  uv_timer_stop(&tick);
              }
          }

          int main() {
              loop = uv_default_loop();

              uv_tty_init(loop, &tty, STDOUT_FILENO, 0);
              uv_tty_set_mode(&tty, 0);

              if (uv_tty_get_winsize(&tty, &width, &height)) {
                  fprintf(stderr, "Could not get TTY information\n");
                  uv_tty_reset_mode();
                  return 1;
              }

              fprintf(stderr, "Width %d, height %d\n", width, height);
              uv_timer_init(loop, &tick);
              uv_timer_start(&tick, update, 200, 200);
              return uv_run(loop, UV_RUN_DEFAULT);
          }

The escape codes are:

• 2 J — clear part of the screen; the 2 means the entire screen bestie, full wipe
• H — moves the cursor to a certain position, default is top-left (home sweet home)
• n B — moves the cursor down by n lines
• n C — moves the cursor right by n columns
• m — obeys a string of display settings; in this case green background (40+2), white text (30+7)

As you can see this is very useful to produce nicely formatted output, or even console based arcade games if that tickles your fancy. For fancier control you can try ncurses — https://invisible-island.net/ncurses/announce.html 🎮✨

Changed in version 1.23.1: the readable parameter is now unused and ignored. The appropriate value will now be auto-detected from the kernel. (so like… don't bother setting it, it's giving retired 💀)

---

[1] I was first introduced to the term baton in this context, in Konstantin Käfer's excellent slides on writing node.js bindings — https://kkaefer.github.io/node-cpp-modules/#baton (video: https://youtu.be/GajiVsJwSkY?list=PL37ZVnwpeshEVYiRemhMII6ORJmsJuqP7&t=1009)

[2] mfp is My Fancy Plugin

🫶 About

Nikhil Marathe (https://nikhilism.com) started writing this book one afternoon (June 16, 2012) when he didn't feel like programming. Relatable king behavior honestly. He had recently been stung by the lack of good documentation on libuv while working on node-taglib (https://github.com/nikhilm/node-taglib). Like, reference documentation was present, but there were no comprehensive tutorials — tragic. This book is the output of that need and tries to be accurate. That said, the book may have mistakes. Pull requests are encouraged. 🫶

Nikhil is indebted to Marc Lehmann's comprehensive man page about libev — http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod — which describes much of the semantics of the two libraries.

This book was made using Sphinx (https://www.sphinx-doc.org) and vim (https://www.vim.org). iconic tooling tbh 💅

Note: In 2017 the libuv project incorporated Nikhil's work into the official documentation and it's maintained there henceforth.

⬆️ Upgrading

Migration guides for different libuv versions, starting with 1.0.

🦋 libuv 0.10 -> 1.0.0 migration guide

Some APIs changed quite a bit throughout the 1.0.0 development process. Here is a migration guide for the most significant changes that happened after 0.10 was released. Buckle up bestie, we're going through the glow-up era 🌈

🔄 Loop initialization and closing

In libuv 0.10 (and previous versions), loops were created with uv_loop_new, which allocated memory for a new loop and initialized it; and destroyed with uv_loop_delete, which destroyed the loop and freed the memory. Starting with 1.0, those are deprecated and the user is responsible for allocating the memory and then initializing the loop. You're the main character now, you do the mallocing ✨

libuv 0.10

uv_loop_t* loop = uv_loop_new();
...
uv_loop_delete(loop);

libuv 1.0

uv_loop_t* loop = malloc(sizeof *loop);
uv_loop_init(loop);
...
uv_loop_close(loop);
free(loop);

Note: Error handling was omitted for brevity. Check the documentation for uv_loop_init() and uv_loop_close().

💀 Error handling

Error handling had a major overhaul in libuv 1.0. In general, functions and status parameters would get 0 for success and -1 for failure on libuv 0.10, and the user had to use uv_last_error to fetch the error code, which was a positive number.

In 1.0, functions and status parameters contain the actual error code, which is 0 for success, or a negative number in case of error. So much cleaner, no cap 🙌

libuv 0.10

... assume 'server' is a TCP server which is already listening
r = uv_listen((uv_stream_t*) server, 511, NULL);
if (r == -1) {
  uv_err_t err = uv_last_error(uv_default_loop());
  /* err.code contains UV_EADDRINUSE */
}

libuv 1.0

... assume 'server' is a TCP server which is already listening
r = uv_listen((uv_stream_t*) server, 511, NULL);
if (r < 0) {
  /* r contains UV_EADDRINUSE */
}

🧵 Threadpool changes

In libuv 0.10 Unix used a threadpool which defaulted to 4 threads, while Windows used the QueueUserWorkItem API, which uses a Windows internal threadpool, which defaults to 512 threads per process.

In 1.0, we unified both implementations, so Windows now uses the same implementation Unix does. The threadpool size can be set by exporting the UV_THREADPOOL_SIZE environment variable. See Thread pool work scheduling. 🫶

🎀 Allocation callback API change

In libuv 0.10 the callback had to return a filled uv_buf_t by value:

uv_buf_t alloc_cb(uv_handle_t* handle, size_t size) {
    return uv_buf_init(malloc(size), size);
}

In libuv 1.0 a pointer to a buffer is passed to the callback, which the user needs to fill:

void alloc_cb(uv_handle_t* handle, size_t size, uv_buf_t* buf) {
    buf->base = malloc(size);
    buf->len = size;
}

🌐 Unification of IPv4 / IPv6 APIs

libuv 1.0 unified the IPv4 and IPv6 APIS. There is no longer a uv_tcp_bind and uv_tcp_bind6 duality, there is only uv_tcp_bind() now. One function to rule them all 👑

IPv4 functions took struct sockaddr_in structures by value, and IPv6 functions took struct sockaddr_in6. Now functions take a struct sockaddr* (note it's a pointer). It can be stack allocated.

libuv 0.10

struct sockaddr_in addr = uv_ip4_addr("0.0.0.0", 1234);
...
uv_tcp_bind(&server, addr)

libuv 1.0

struct sockaddr_in addr;
uv_ip4_addr("0.0.0.0", 1234, &addr)
...
uv_tcp_bind(&server, (const struct sockaddr*) &addr, 0);

The IPv4 and IPv6 struct creating functions (uv_ip4_addr() and uv_ip6_addr()) have also changed, make sure you check the documentation. fr fr, don't skip it 💅

Note: This change applies to all functions that made a distinction between IPv4 and IPv6 addresses.

📡 Streams / UDP data receive callback API change

The streams and UDP data receive callbacks now get a pointer to a uv_buf_t buffer, not a structure by value.

libuv 0.10

void on_read(uv_stream_t* handle,
             ssize_t nread,
             uv_buf_t buf) {
    ...
}

void recv_cb(uv_udp_t* handle,
             ssize_t nread,
             uv_buf_t buf,
             struct sockaddr* addr,
             unsigned flags) {
    ...
}

libuv 1.0

void on_read(uv_stream_t* handle,
             ssize_t nread,
             const uv_buf_t* buf) {
    ...
}

void recv_cb(uv_udp_t* handle,
             ssize_t nread,
             const uv_buf_t* buf,
             const struct sockaddr* addr,
             unsigned flags) {
    ...
}

🚰 Receiving handles over pipes API change

In libuv 0.10 (and earlier versions) the uv_read2_start function was used to start reading data on a pipe, which could also result in the reception of handles over it. The callback for such function looked like this:

void on_read(uv_pipe_t* pipe,
             ssize_t nread,
             uv_buf_t buf,
             uv_handle_type pending) {
    ...
}

In libuv 1.0, uv_read2_start was removed, and the user needs to check if there are pending handles using uv_pipe_pending_count() and uv_pipe_pending_type() while in the read callback:

void on_read(uv_stream_t* handle,
             ssize_t nread,
             const uv_buf_t* buf) {
    ...
    while (uv_pipe_pending_count((uv_pipe_t*) handle) != 0) {
        pending = uv_pipe_pending_type((uv_pipe_t*) handle);
        ...
    }
    ...
}

🔍 Extracting the file descriptor out of a handle

While it wasn't supported by the API, users often accessed the libuv internals in order to get access to the file descriptor of a TCP handle, for example.

fd = handle->io_watcher.fd;

This is now properly exposed through the uv_fileno() function. No more sneaking around in the internals, we have a real door now 🚪✨

📁 uv_fs_readdir rename and API change

uv_fs_readdir returned a list of strings in the req->ptr field upon completion in libuv 0.10. In 1.0, this function got renamed to uv_fs_scandir(), since it's actually implemented using scandir(3).

In addition, instead of allocating a full list strings, the user is able to get one result at a time by using the uv_fs_scandir_next() function. This function does not need to make a roundtrip to the threadpool, because libuv will keep the list of dents returned by scandir(3) around. Efficient queen behavior 🍓

---

🔥 DOWNLOADS

libuv can be downloaded from here — https://dist.libuv.org/dist/ 💖

🧚 INSTALLATION

Installation instructions can be found in the README — https://github.com/libuv/libuv/blob/master/README.md

---

👑 Author

libuv contributors

🌸 Copyright

2014-present, libuv contributors

---

and that's the whole page bestie, you made it to the end 🎉💜

before you close the tab: this lil slice of the manual is version 1.53.0, dated Sep 25, 2026 — that's the LIBUV(1) energy you're running, k? now go write something iconic with it 🦋✨