System Calls & File I/O in Zig

Use bun.sys instead of std.fs or std.posix for cross-platform syscalls with proper error handling.

bun.sys.File (Preferred)

For most file operations, use the bun.sys.File wrapper:

const File = bun.sys.File;

const file = switch (File.open(path, bun.O.RDWR, 0o644)) { .result => |f| f, .err => |err| return .{ .err = err }, }; defer file.close();

// Read/write _ = try file.read(buffer).unwrap(); _ = try file.writeAll(data).unwrap();

// Get file info const stat = try file.stat().unwrap(); const size = try file.getEndPos().unwrap();

// std.io compatible const reader = file.reader(); const writer = file.writer();

Complete Example

const File = bun.sys.File;

pub fn writeFile(path: [:0]const u8, data: []const u8) File.WriteError!void { const file = switch (File.open(path, bun.O.WRONLY | bun.O.CREAT | bun.O.TRUNC, 0o664)) { .result => |f| f, .err => |err| return err.toError(), }; defer file.close();

_ = switch (file.writeAll(data)) {
    .result => {},
    .err => |err| return err.toError(),
};

}

Why bun.sys?

Aspect bun.sys std.fs/std.posix

Return Type Maybe(T) with detailed Error Generic error union

Windows Full support with libuv fallback Limited/POSIX-only

Error Info errno, syscall tag, path, fd errno only

EINTR Automatic retry Manual handling

Error Handling with Maybe(T)

bun.sys functions return Maybe(T)

• a tagged union:

const sys = bun.sys;

// Pattern 1: Switch on result/error switch (sys.read(fd, buffer)) { .result => |bytes_read| { // use bytes_read }, .err => |err| { // err.errno, err.syscall, err.fd, err.path if (err.getErrno() == .AGAIN) { // handle EAGAIN } }, }

// Pattern 2: Unwrap with try (converts to Zig error) const bytes = try sys.read(fd, buffer).unwrap();

// Pattern 3: Unwrap with default const value = sys.stat(path).unwrapOr(default_stat);

Low-Level File Operations

Only use these when bun.sys.File doesn't meet your needs.

Opening Files

const sys = bun.sys;

// Use bun.O flags (cross-platform normalized) const fd = switch (sys.open(path, bun.O.RDONLY, 0)) { .result => |fd| fd, .err => |err| return .{ .err = err }, }; defer fd.close();

// Common flags bun.O.RDONLY, bun.O.WRONLY, bun.O.RDWR bun.O.CREAT, bun.O.TRUNC, bun.O.APPEND bun.O.NONBLOCK, bun.O.DIRECTORY

Reading & Writing

// Single read (may return less than buffer size) switch (sys.read(fd, buffer)) { .result => |n| { /* n bytes read / }, .err => |err| { / handle error */ }, }

// Read until EOF or buffer full const total = try sys.readAll(fd, buffer).unwrap();

// Position-based read/write sys.pread(fd, buffer, offset) sys.pwrite(fd, data, offset)

// Vector I/O sys.readv(fd, iovecs) sys.writev(fd, iovecs)

File Info

sys.stat(path) // Follow symlinks sys.lstat(path) // Don't follow symlinks sys.fstat(fd) // From file descriptor sys.fstatat(fd, path)

// Linux-only: faster selective stat sys.statx(path, &.{ .size, .mtime })

Path Operations

sys.unlink(path) sys.unlinkat(dir_fd, path) sys.rename(from, to) sys.renameat(from_dir, from, to_dir, to) sys.readlink(path, buf) sys.readlinkat(fd, path, buf) sys.link(T, src, dest) sys.linkat(src_fd, src, dest_fd, dest) sys.symlink(target, dest) sys.symlinkat(target, dirfd, dest) sys.mkdir(path, mode) sys.mkdirat(dir_fd, path, mode) sys.rmdir(path)

Permissions

sys.chmod(path, mode) sys.fchmod(fd, mode) sys.fchmodat(fd, path, mode, flags) sys.chown(path, uid, gid) sys.fchown(fd, uid, gid)

Closing File Descriptors

Close is on bun.FD :

fd.close(); // Asserts on error (use in defer)

// Or if you need error info: if (fd.closeAllowingBadFileDescriptor(null)) |err| { // handle error }

Directory Operations

var buf: bun.PathBuffer = undefined; const cwd = try sys.getcwd(&buf).unwrap(); const cwdZ = try sys.getcwdZ(&buf).unwrap(); // Zero-terminated sys.chdir(path, destination)

Directory Iteration

Use bun.DirIterator instead of std.fs.Dir.Iterator :

var iter = bun.iterateDir(dir_fd); while (true) { switch (iter.next()) { .result => |entry| { if (entry) |e| { const name = e.name.slice(); const kind = e.kind; // .file, .directory, .sym_link, etc. } else { break; // End of directory } }, .err => |err| return .{ .err = err }, } }

Socket Operations

Important: bun.sys has limited socket support. For network I/O:

• Non-blocking sockets: Use uws.Socket (libuwebsockets) exclusively

• Pipes/blocking I/O: Use PipeReader.zig and PipeWriter.zig

Available in bun.sys:

sys.setsockopt(fd, level, optname, value) sys.socketpair(domain, socktype, protocol, nonblocking_status)

Do NOT use bun.sys for socket read/write - use uws.Socket instead.

Other Operations

sys.ftruncate(fd, size) sys.lseek(fd, offset, whence) sys.dup(fd) sys.dupWithFlags(fd, flags) sys.fcntl(fd, cmd, arg) sys.pipe() sys.mmap(...) sys.munmap(memory) sys.access(path, mode) sys.futimens(fd, atime, mtime) sys.utimens(path, atime, mtime)

Error Type

const err: bun.sys.Error = ...; err.errno // Raw errno value err.getErrno() // As std.posix.E enum err.syscall // Which syscall failed (Tag enum) err.fd // Optional: file descriptor err.path // Optional: path string

Key Points

• Prefer bun.sys.File wrapper for most file operations

• Use low-level bun.sys functions only when needed

• Use bun.O.* flags instead of std.os.O.*

• Handle Maybe(T) with switch or .unwrap()

• Use defer fd.close() for cleanup

• EINTR is handled automatically in most functions

• For sockets, use uws.Socket not bun.sys