Zig System Calls for Bun

Оптимизируйте файловый ввод-вывод и системные вызовы Zig с помощью bun.sys. Изучайте кроссплатформенные паттерны, обработку ошибок с Maybe(T) и специфические для Bun системные реализации.

Инструменты разработчика ★ 85,980 GitHub (85,980 ★)

The Zig System Calls skill provides specialized guidance for developers working within the Bun ecosystem to perform low-level file operations and syscalls. It emphasizes the use of the `bun.sys` library over Zig's standard `std.fs` or `std.posix` modules to ensure superior cross-platform compatibility, especially for Windows environments. By leveraging the `Maybe(T)` union type, the skill helps developers implement robust error handling that includes syscall tags, file descriptors, and automatic retry logic for interrupted calls (EINTR), resulting in more stable and performant systems code.

Key Features

01Advanced error handling with detailed syscall metadata

02Automatic EINTR retry logic for system-level operations

03Directory iteration and optimized Linux statx support

04Cross-platform normalization for Windows and POSIX systems

0585,980 GitHub stars

06Implementation patterns for the bun.sys.File wrapper

Use Cases

01Developing Bun core components or Zig-based Bun plugins

02Refactoring standard Zig code to use Bun's robust syscall interface

03Building high-performance file system utilities in Zig

name	description
zig-system-calls	Guides using bun.sys for system calls and file I/O in Zig. Use when implementing file operations instead of std.fs or std.posix.

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

📌 Что это

Навык zig-system-calls (Zig System Calls for Bun) — это руководство по системным вызовам и файловому вводу-выводу в Zig внутри рантайма Bun. Вместо стандартного std.fs или std.posix предлагается использовать bun.sys, который предоставляет кроссплатформенные обёртки с детальной информацией об ошибках, автоматической обработкой EINTR и поддержкой Windows через libuv. Подходит для разработчиков, пишущих нативные модули для Bun на Zig.

⚙️ Как работает

🧱 Основная абстракция — `bun.sys.File`

Для большинства операций с файлами предпочтительна обёртка bun.sys.File. Она даёт:

открытие (File.open) с флагами bun.O.*;
чтение и запись (read, writeAll);
получение информации (stat, getEndPos);
совместимость со стандартными интерфейсами: .reader() и .writer();
автоматическое закрытие через defer file.close().

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

🎯 Тип `Maybe(T)` — контроль каждой ошибки

Функции bun.sys возвращают помеченное объединение Maybe(T). Три типовых паттерна обработки:

switch на .result / .err — максимальная информация об ошибке;
.unwrap() — преобразует в обычную Zig-ошибку, удобно с try;
.unwrapOr(default) — значение по умолчанию при ошибке.

const sys = bun.sys;

// Pattern: switch на результат/ошибку
switch (sys.read(fd, buffer)) {
    .result => |bytes_read| { /* используем bytes_read */ },
    .err => |err| {
        // err.errno, err.syscall, err.fd, err.path
        if (err.getErrno() == .AGAIN) { /* EAGAIN */ }
    },
}

Структура ошибки bun.sys.Error содержит: номер errno, тег системного вызова (syscall), опционально fd и path. Это намного информативнее, чем generic std.posix.Error.

📂 Низкоуровневые операции (когда `bun.sys.File` не хватает)

Если нужен прямой контроль над файловым дескриптором, используйте сырые системные вызовы:

Открытие: sys.open(path, bun.O.RDONLY, 0) → возвращает FD;
Чтение и запись: sys.read, sys.readAll, sys.pread, sys.pwrite;
Векторный I/O: sys.readv, sys.writev;
Информация: sys.stat, sys.lstat, sys.fstat, sys.fstatat, sys.statx (Linux);
Операции с путями: sys.unlink, sys.rename, sys.readlink, sys.link, sys.symlink, sys.mkdir, sys.rmdir;
Права: sys.chmod, sys.fchmod, sys.chown, sys.fchown;
Прочее: sys.ftruncate, sys.lseek, sys.dup, sys.fcntl, sys.pipe, sys.mmap, sys.access, sys.futimens, sys.utimens.

Закрытие дескриптора — через метод .close() на bun.FD. По умолчанию он делает assert (подходит для defer). Если нужно обработать ошибку, используйте closeAllowingBadFileDescriptor(null).

📁 Работа с директориями

Текущая директория: sys.getcwd (с \.0 — sys.getcwdZ);
Смена директории: sys.chdir;
Итерация: bun.iterateDir(dir_fd) возвращает итератор, работающий через Maybe(T). Запись содержит .name.slice() и .kind (.file, .directory, .sym_link).

🔌 Сокеты и сетевой I/O

Важно: bun.sys имеет ограниченную поддержку сокетов. Для неблокирующих сокетов используйте uws.Socket (libuwebsockets). Для pipe — PipeReader.zig / PipeWriter.zig. В bun.sys доступны только setsockopt и socketpair.

Не используйте bun.sys для read/write с сокетами — только через uws.Socket.

🚀 Когда использовать

Когда разрабатываете нативный Zig-модуль для Bun (например, плагин Bun с FFI) и нужен кросс-платформенный файловый I/O.
Когда важна детальная диагностика ошибок (errno + имя системного вызова).
Когда хочется автоматического повторения при EINTR и избавления от ручной обработки этого случая.
Когда требуется поддержка Windows (libuv fallback на не-POSIX платформах).
Когда нужно быстро читать/писать файлы с минимальным накладным расходом, используя Zig, но с «батарейками» от Bun.

📌 Важно знать

Флаги: всегда используйте bun.O.* вместо std.os.O.* — они нормализованы между ОС.
EINTR: в большинстве функций bun.sys обрабатывается автоматически.
Сеть: не пытайтесь делать сокетный I/O через bun.sys — используйте выделенные абстракции.
Производительность: bun.sys.File даёт лёгкую обёртку с читаемым API, низкоуровневые функции — максимальный контроль.
Документация: весь код предполагается в контексте сборки под Bun (Bun runtime), не как standalone Zig-программа.

Установите одной командой.

npx skillfish add oven-sh/bun zig-system-calls

Источник: https://mcpmarket.com/tools/skills/zig-system-calls-for-bun

Zig System Calls for Bun

Key Features

Use Cases

System Calls & File I/O in Zig

bun.sys.File (Preferred)

Complete Example

Why bun.sys?

Error Handling with Maybe(T)

Low-Level File Operations

Opening Files

Reading & Writing

File Info

Path Operations

Permissions

Closing File Descriptors

Directory Operations

Directory Iteration

Socket Operations

Other Operations

Error Type

Key Points

📌 Что это

⚙️ Как работает

🧱 Основная абстракция — `bun.sys.File`

🎯 Тип `Maybe(T)` — контроль каждой ошибки

📂 Низкоуровневые операции (когда `bun.sys.File` не хватает)

📁 Работа с директориями

🔌 Сокеты и сетевой I/O

🚀 Когда использовать

📌 Важно знать

Можно ли использовать bun.sys для операций с сетевыми сокетами?

Совместим ли bun.sys.File со стандартным вводом-выводом Zig?

Почему стоит использовать bun.sys вместо std.fs от Zig?

Что такое тип возвращаемого значения Maybe(T) в bun.sys?

Комментарии

Key Features

Use Cases

System Calls & File I/O in Zig

bun.sys.File (Preferred)

Complete Example

Why bun.sys?

Error Handling with Maybe(T)

Low-Level File Operations

Opening Files

Reading & Writing

File Info

Path Operations

Permissions

Closing File Descriptors

Directory Operations

Directory Iteration

Socket Operations

Other Operations

Error Type

Key Points

📌 Что это

⚙️ Как работает

🧱 Основная абстракция — bun.sys.File

🎯 Тип Maybe(T) — контроль каждой ошибки

📂 Низкоуровневые операции (когда bun.sys.File не хватает)

📁 Работа с директориями

🔌 Сокеты и сетевой I/O

🚀 Когда использовать

📌 Важно знать

Можно ли использовать bun.sys для операций с сетевыми сокетами?

Совместим ли bun.sys.File со стандартным вводом-выводом Zig?

Почему стоит использовать bun.sys вместо std.fs от Zig?

Что такое тип возвращаемого значения Maybe(T) в bun.sys?

Комментарии

🧱 Основная абстракция — `bun.sys.File`

🎯 Тип `Maybe(T)` — контроль каждой ошибки

📂 Низкоуровневые операции (когда `bun.sys.File` не хватает)