zig-skills/references/std-os.md

std.os - OS-Specific APIs Reference (Zig 0.16.0)

Thin wrappers around OS-specific APIs. Zig 0.16 moves many blocking/nondeterministic operations behind std.Io; prefer std.Io abstractions for portable code and drop down to std.posix / std.os.windows only for explicitly platform-specific code.

Primary Zig 0.16 release-note source: https://ziglang.org/download/0.16.0/release-notes.html

Table of Contents

• Module Structure
• Platform Submodules
• Linux-Specific APIs
• Windows-Specific APIs
• WASI-Specific APIs
• io_uring (Linux)
• Common Functions
• Common Patterns

Module Structure

std.os.linux      // Linux syscalls and constants
std.os.windows    // Windows NT APIs
std.os.wasi       // WebAssembly System Interface
std.os.plan9      // Plan 9 system calls
std.os.uefi       // UEFI firmware interface
std.os.emscripten // Emscripten runtime

Those six target modules are the complete public surface of std.os in Zig 0.16. For most use cases, prefer std.Io (portable, capability-based I/O) or std.posix (cross-platform POSIX-like APIs). Process startup arguments and environment data are supplied through std.process.Init, not std.os.argv or std.os.environ.

Platform Submodules

When to Use Each Level

// High-level (recommended for most code)
const file = try std.Io.Dir.cwd().openFile(io, "data.txt", .{});
defer file.close(io);

// POSIX-level (cross-platform low-level)
const fd = try std.posix.open("data.txt", .{}, 0);

// OS-specific (platform-specific features)
const result = std.os.linux.syscall3(.read, @intCast(fd), @intFromPtr(buf.ptr), buf.len);

Linux-Specific APIs

Direct Syscalls

const linux = std.os.linux;

// Raw syscall interface
const result = linux.syscall3(.write, fd, @intFromPtr(buf.ptr), buf.len);
if (linux.errno(result) != .SUCCESS) {
    // handle error
}

// Common syscalls with typed wrappers
_ = linux.dup(old_fd);
_ = linux.dup2(old_fd, new_fd);
_ = linux.fork();
_ = linux.execve(path, argv, envp);
_ = linux.chdir(path);
_ = linux.chroot(path);

Memory Mapping

const linux = std.os.linux;

// mmap with typed flags
const result = linux.mmap(
    null,
    length,
    linux.PROT.READ | linux.PROT.WRITE,
    .{ .TYPE = .PRIVATE, .ANONYMOUS = true },
    -1,
    0,
);
const addr: [*]u8 = switch (linux.errno(result)) {
    .SUCCESS => @ptrFromInt(result),
    else => |err| return std.posix.unexpectedErrno(err),
};

// Remap
_ = linux.mremap(old_addr, old_size, new_size, .{ .MAYMOVE = true }, null);

// Unmap
_ = linux.munmap(addr, length);

File Operations

const linux = std.os.linux;

// Open flags (architecture-specific packed struct)
const flags: linux.O = .{
    .ACCMODE = .RDWR,
    .CREAT = true,
    .TRUNC = true,
    .CLOEXEC = true,
};

// fallocate - preallocate file space
_ = linux.fallocate(fd, 0, 0, size);

// utimensat - set file timestamps
_ = linux.utimensat(dirfd, path, &times, 0);

Futex (Fast Userspace Mutex)

const linux = std.os.linux;

// Wait on futex
_ = linux.futex(
    &futex_word,
    .{ .cmd = .WAIT, .private = true },
    expected_value,
    .{ .timeout = &timeout },
    null,
    0,
);

// Wake waiters
_ = linux.futex(
    &futex_word,
    .{ .cmd = .WAKE, .private = true },
    num_to_wake,
    .{ .val2 = 0 },
    null,
    0,
);

Signals

const linux = std.os.linux;

// Signal handling
var act: linux.Sigaction = .{
    .handler = .{ .handler = signal_handler },
    .mask = linux.empty_sigset,
    .flags = .{},
};
const result = linux.sigaction(.INT, &act, null);
if (linux.errno(result) != .SUCCESS) {
    // translate or handle the raw errno
}

// Kill process
_ = linux.kill(pid, linux.SIG.TERM);

Epoll

const linux = std.os.linux;

// Create epoll instance
const epfd = linux.epoll_create1(.{ .CLOEXEC = true });

// Add file descriptor
var event: linux.epoll_event = .{
    .events = linux.EPOLL.IN | linux.EPOLL.ET,
    .data = .{ .fd = client_fd },
};
_ = linux.epoll_ctl(epfd, .ADD, client_fd, &event);

// Wait for events
var events: [64]linux.epoll_event = undefined;
const result = linux.epoll_wait(epfd, &events, @intCast(events.len), -1);
const n: usize = switch (linux.errno(result)) {
    .SUCCESS => result,
    else => |err| return std.posix.unexpectedErrno(err),
};
for (events[0..n]) |ev| {
    // handle event
}

getauxval

const linux = std.os.linux;

// Get auxiliary vector values (set by kernel at process start)
const page_size = linux.getauxval(std.elf.AT_PAGESZ);
const entry_point = linux.getauxval(std.elf.AT_ENTRY);
const platform = linux.getauxval(std.elf.AT_PLATFORM);

Windows-Specific APIs

File Operations

// Prefer the portable std.Io layer even in Windows-only programs.
const file = try std.Io.Dir.cwd().openFile(io, "data.txt", .{});
defer file.close(io);

For Win32 or NT features that std.Io does not expose, use declarations actually exported by std.os.windows and its kernel32/ntdll submodules. There is no public std.os.windows.OpenFile helper in Zig 0.16.

Process Information

const windows = std.os.windows;

// Current process/thread
const process = windows.GetCurrentProcess();
const pid = windows.GetCurrentProcessId();
const thread = windows.GetCurrentThread();
const tid = windows.GetCurrentThreadId();

// Last error
const err = windows.GetLastError();

Pipes

Use the std.Io pipe/process APIs for portable pipes. If raw Windows handles are required, call a declaration that is actually exported from the relevant Windows submodule and translate its Win32 error explicitly; Zig 0.16 does not expose a fallible std.os.windows.CreatePipe wrapper with the signature shown in older examples.

Submodules

windows.kernel32   // kernel32.dll functions
windows.ntdll      // ntdll.dll functions (NT native API)
windows.ws2_32     // Winsock 2 networking
windows.crypt32    // Cryptographic functions
windows.nls        // National Language Support

WASI-Specific APIs

File Descriptors

const wasi = std.os.wasi;

// Read/write
var nread: usize = undefined;
switch (wasi.fd_read(fd, &iovs, iovs.len, &nread)) {
    .SUCCESS => {},
    .BADF => return error.BadFileDescriptor,
    else => |e| return unexpectedErrno(e),
}

// Seek
var new_offset: wasi.filesize_t = undefined;
_ = wasi.fd_seek(fd, offset, .SET, &new_offset);

// Sync
_ = wasi.fd_sync(fd);
_ = wasi.fd_datasync(fd);

Path Operations

const wasi = std.os.wasi;

// Create directory
_ = wasi.path_create_directory(dirfd, path.ptr, path.len);

// Open file
var result_fd: wasi.fd_t = undefined;
_ = wasi.path_open(
    dirfd,
    .{ .SYMLINK_FOLLOW = true },
    path.ptr,
    path.len,
    .{ .CREAT = true },
    rights_base,
    rights_inheriting,
    .{},
    &result_fd,
);

// Symlinks
_ = wasi.path_symlink(old_path.ptr, old_path.len, dirfd, new_path.ptr, new_path.len);
_ = wasi.path_readlink(dirfd, path.ptr, path.len, buf.ptr, buf.len, &bufused);

Clock

const wasi = std.os.wasi;

var timestamp: wasi.timestamp_t = undefined;
switch (wasi.clock_time_get(.MONOTONIC, 1, &timestamp)) {
    .SUCCESS => {},
    else => |e| return error.ClockGetFailed,
}

Environment and Arguments

const wasi = std.os.wasi;

// Arguments
var argc: usize = undefined;
var argv_buf_size: usize = undefined;
_ = wasi.args_sizes_get(&argc, &argv_buf_size);

// Environment
var environ_count: usize = undefined;
var environ_buf_size: usize = undefined;
_ = wasi.environ_sizes_get(&environ_count, &environ_buf_size);

Random

const wasi = std.os.wasi;

var buf: [32]u8 = undefined;
switch (wasi.random_get(&buf, buf.len)) {
    .SUCCESS => {},
    else => return error.RandomFailed,
}

io_uring (Linux)

High-performance async I/O for Linux 5.4+.

Basic Setup

const IoUring = std.os.linux.IoUring;

// Initialize with 256 entries
var ring = try IoUring.init(256, 0);
defer ring.deinit();

// With custom parameters
var params = std.mem.zeroInit(std.os.linux.io_uring_params, .{
    .flags = std.os.linux.IORING_SETUP_SQPOLL,  // kernel-side submission
    .sq_thread_idle = 2000,  // ms before SQ thread sleeps
});
var ring = try IoUring.init_params(256, &params);

Submitting Operations

// Get submission queue entry
const sqe = try ring.get_sqe();

// Prepare read operation
sqe.prep_read(fd, buffer, offset);
sqe.user_data = my_context;  // identify this request in completion

// Or write
sqe.prep_write(fd, data, offset);

// Submit to kernel
const submitted = try ring.submit();

Waiting for Completions

// Submit and wait for at least 1 completion
_ = try ring.submit_and_wait(1);

// Process completions
var cqes: [32]std.os.linux.io_uring_cqe = undefined;
const ready = try ring.copy_cqes(&cqes, 1);
for (cqes[0..ready]) |cqe| {
    const user_data = cqe.user_data;
    const result = cqe.res;  // bytes transferred or -errno

    if (result < 0) {
        const err: std.os.linux.E = @enumFromInt(@as(u16, @intCast(-result)));
        // handle error
    }
}

copy_cqes copies and consumes completions as a batch. copy_cqe is the corresponding wait-for-one convenience method. Do not additionally call cqe_seen or cq_advance after either copying API.

Common Operations

// File I/O
sqe.prep_read(fd, buf, offset);
sqe.prep_write(fd, data, offset);
sqe.prep_readv(fd, iovecs, offset);
sqe.prep_writev(fd, iovecs, offset);

// Fixed buffers (pre-registered, zero-copy)
sqe.prep_read_fixed(fd, registered_iovec, offset, buf_index);
sqe.prep_write_fixed(fd, registered_iovec, offset, buf_index);

// Network
sqe.prep_accept(listen_fd, &client_addr, &addr_len, 0);
sqe.prep_connect(fd, &addr, addr_len);
sqe.prep_recv(fd, buf, 0);
sqe.prep_send(fd, data, 0);

// Timeouts
sqe.prep_timeout(&timespec, 0, 0);
sqe.prep_link_timeout(&timespec, 0);  // timeout linked op

// File operations
sqe.prep_openat(dirfd, path, flags, mode);
sqe.prep_close(fd);
sqe.prep_statx(dirfd, path, flags, mask, &statx);

// Misc
sqe.prep_nop();  // no-op (for benchmarking)
sqe.prep_cancel(user_data, 0);  // cancel pending request

Linked Operations

// Chain operations: second runs only if first succeeds
const sqe1 = try ring.get_sqe();
sqe1.prep_write(fd, header, 0);
sqe1.flags |= std.os.linux.IOSQE_IO_LINK;

const sqe2 = try ring.get_sqe();
sqe2.prep_write(fd, body, header.len);

_ = try ring.submit();

Buffer Registration

// Register buffers for zero-copy I/O
var buffers: [16][4096]u8 = undefined;
var iovecs: [16]std.posix.iovec = undefined;
for (&iovecs, &buffers) |*iov, *buf| {
    iov.* = .{ .base = buf, .len = buf.len };
}

try ring.register_buffers(&iovecs);
defer ring.unregister_buffers() catch {};

// Use registered buffer
const sqe = try ring.get_sqe();
sqe.prep_read_fixed(fd, &iovecs[0], 0, 0);  // buf_index = 0

File Descriptor Registration

// Register FDs for faster access
var fds = [_]std.posix.fd_t{ fd1, fd2, fd3 };
try ring.register_files(&fds);
defer ring.unregister_files() catch {};

// Use with IOSQE_FIXED_FILE flag
const sqe = try ring.get_sqe();
sqe.prep_read(0, buf, 0);  // fd index, not actual fd
sqe.flags |= std.os.linux.IOSQE_FIXED_FILE;

Common Functions

Zig 0.16 deliberately has no cross-platform function layer at the std.os root. Older references may mention root functions such as std.os.getFdPath, std.os.accessW, std.os.fstatat_wasi, or std.os.fstat_wasi; those are not public Zig 0.16 APIs.

Choose the API by intent:

• Use std.Io.Dir and std.Io.File for portable path, access, and metadata operations.
• Use std.posix for POSIX-like file-descriptor operations.
• Use std.os.windows, std.os.wasi, or another exported target module when the behavior is intentionally ABI-specific.
• Preserve the path separately when an application needs to associate a portable path with an open file; a descriptor does not portably retain a recoverable canonical pathname.

Common Patterns

Platform-Specific Code

const builtin = @import("builtin");

fn platformSpecific() !void {
    switch (builtin.os.tag) {
        .linux => {
            const linux = std.os.linux;
            // Linux-specific code
        },
        .windows => {
            const windows = std.os.windows;
            // Windows-specific code
        },
        .wasi => {
            const wasi = std.os.wasi;
            // WASI-specific code
        },
        else => @compileError("Unsupported OS"),
    }
}

io_uring Event Loop

fn eventLoop(ring: *std.os.linux.IoUring) !void {
    while (running) {
        // Submit pending and wait for completions
        _ = try ring.submit_and_wait(1);

        // Copying also advances the completion queue.
        var cqes: [64]std.os.linux.io_uring_cqe = undefined;
        const count = try ring.copy_cqes(&cqes, 1);
        for (cqes[0..count]) |cqe| {
            const ctx = @as(*Context, @ptrFromInt(cqe.user_data));
            try ctx.handle_completion(cqe.res);
        }
    }
}

Handling Syscall Errors

const linux = std.os.linux;

fn readSyscall(fd: i32, buf: []u8) !usize {
    const result = linux.syscall3(.read, @intCast(fd), @intFromPtr(buf.ptr), buf.len);

    switch (linux.errno(result)) {
        .SUCCESS => return result,
        .INTR => return error.Interrupted,
        .AGAIN => return error.WouldBlock,
        .BADF => return error.BadFileDescriptor,
        .FAULT => return error.BadAddress,
        .INVAL => return error.InvalidArgument,
        .IO => return error.InputOutput,
        .ISDIR => return error.IsDir,
        else => |e| return std.posix.unexpectedErrno(e),
    }
}

Windows Error Handling

const windows = std.os.windows;

fn translateLastError() !void {
    // Call this immediately after a Win32 API reports failure; another Win32
    // call may overwrite the thread's last-error value.
    switch (windows.GetLastError()) {
        .FILE_NOT_FOUND => return error.FileNotFound,
        .ACCESS_DENIED => return error.AccessDenied,
        else => |e| return windows.unexpectedError(e),
    }
}

Retaining a Portable File Path

If later logic needs both a file and its pathname, store an owned copy of the pathname when opening the file. Trying to reconstruct a canonical path from a descriptor is target-specific and can be ambiguous after rename, unlink, mount, or namespace changes.