/rust-system-calls

name: rust-system-calls
description: Guides using bun_sys for system calls and file I/O in Rust. Use when implementing file operations, opening fds, or any syscall path instead of std::fs or libc.

System Calls & File I/O in Rust

Use `bun_sys` instead of `std::fs` or raw `libc` for cross-platform syscalls with proper error handling.

bun_sys::File (Preferred)

For most file operations, use the `bun_sys::File` wrapper. It owns the fd and closes on `Drop`.

use bun_sys::{File, Fd, O};

let file = File::openat(Fd::cwd(), b"path/to/file", O::RDONLY, 0)?;
let mut buf = vec![0u8; 4096];
let n = file.read_all(&mut buf)?;     // loops until EOF or full
// `file` closes on Drop.

Complete Example

use bun_sys::{File, Fd, O};

pub fn write_file(path: &[u8], data: &[u8]) -> Result<(), bun_sys::Error> {
    let file = File::openat(Fd::cwd(), path, O::WRONLY | O::CREAT | O::TRUNC, 0o664)?;
    file.write_all(data)?;
    Ok(())
}

Why bun_sys?

| Aspect | bun_sys | std::fs / libc | | ----------- | ---------------------------------- | ---------------------- | | Return Type | `Maybe<T>` with rich `Error` | `io::Error` (lossy) | | Windows | Full support with libuv fallback | Incomplete/POSIX-ish | | Error Info | errno, syscall tag, path, fd | errno only | | EINTR | Automatic retry | Manual handling | | Paths | `&[u8]` (WTF-8 safe) | `&Path` (UTF-8 lossy) |

Error Handling with Maybe<T>

`bun_sys` functions return `Maybe<T> = Result<T, bun_sys::Error>`. Propagate with `?`; convert to a JS exception via `bun_sys_jsc::ErrorJsc::to_js`:

use bun_sys_jsc::ErrorJsc;
use bun_sys::{File, Fd, O};

let file = match File::openat(Fd::cwd(), path, O::RDONLY, 0) {
    Ok(f) => f,
    Err(err) => return Ok(err.to_js(global)?),
};

`bun_sys::Error` carries `errno`, `syscall: Tag`, and `path: Box<[u8]>`. To branch on errno:

match bun_sys::unlink(path) {
    Ok(()) => {}
    Err(e) if e.errno() == bun_c::ENOENT => {} // already gone
    Err(e) => return Err(e),
}

Key Types and Functions

• `Fd` (`bun_core::Fd`) — cross-platform file descriptor. `Fd::cwd()`, `Fd::stdin()/stdout()/stderr()`, `fd.close()`.
• `File::open(path: &ZStr, flags, mode)` / `File::openat(dir: Fd, path: &[u8], flags, mode)` / `File::make_open(...)` (creates parent dirs) / `File::create(dir, path, truncate)`
• `file.read(buf)` / `read_all(buf)` / `read_to_end()` / `read_to_end_small()` / `write(buf)` / `write_all(buf)`
• `bun_sys::open`, `read`, `write`, `pread`, `pwrite`, `stat`, `fstat`, `lstat`, `mkdir`, `unlink`, `rename`, `symlink`, `chmod` — free fns over `Fd`
• Open flags: `bun_sys::O::RDONLY`, `O::WRONLY | O::CREAT | O::TRUNC`, etc.

Path Buffers

Use `bun_paths` for joining/normalization and the path-buffer pool to avoid 64 KB stack allocations on Windows:

use bun_paths::{path_buffer_pool, resolve_path::{self, platform}};

let mut buf = path_buffer_pool::get();
let joined = resolve_path::join_string_buf::<platform::Auto>(&mut *buf, &[dir, name]);
let file = File::openat(Fd::cwd(), joined, O::RDONLY, 0)?;

Common Mistakes

• **Don't `.unwrap()`** a `bun_sys` result that user input or the OS can cause to fail at runtime — return the error.
• **Don't use `std::fs::File`** — it loses the syscall tag and path needed for Node-compatible error objects.
• **Don't allocate `PathBuffer` on the stack** in hot paths — use `path_buffer_pool::get()`.
• **Don't forget `Drop`** alone closes a `File` — never `file.fd().close()` while the `File` is still live (double close).

See `src/CLAUDE.md` for the full `bun_core`/`bun_sys` reference.