zig-system-calls

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

```zig

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

```zig

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(),

};

}

```

| 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 |

bun.sys functions return Maybe(T) - a tagged union:

```zig

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);

```

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

Opening Files

```zig

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

```zig

// 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

```zig

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

```zig

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

```zig

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:

```zig

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

// Or if you need error info:

if (fd.closeAllowingBadFileDescriptor(null)) |err| {

// handle error

}

```

```zig

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:

```zig

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 },

}

}

```

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:

```zig

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.

```zig

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)

```

```zig

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

```

• 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