rust-system-calls

Source excerpt starting at line 1.

1---2name: rust-system-calls3description: 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.4---5 6# System Calls & File I/O in Rust7 8Use `bun_sys` instead of `std::fs` or raw `libc` for cross-platform syscalls with proper error handling.9 10## bun_sys::File (Preferred)11 12For most file operations, use the `bun_sys::File` wrapper. It owns the fd and closes on `Drop`.13 14```rust15use bun_sys::{File, Fd, O};16 17let file = File::openat(Fd::cwd(), b"path/to/file", O::RDONLY, 0)?;18let mut buf = vec![0u8; 4096];19let n = file.read_all(&mut buf)?;     // loops until EOF or full20// `file` closes on Drop.21```22 23### Complete Example24 25```rust26use bun_sys::{File, Fd, O};27 28pub fn write_file(path: &[u8], data: &[u8]) -> Result<(), bun_sys::Error> {29    let file = File::openat(Fd::cwd(), path, O::WRONLY | O::CREAT | O::TRUNC, 0o664)?;30    file.write_all(data)?;31    Ok(())32}33```34 35## Why bun_sys?36 37| Aspect      | bun_sys                            | std::fs / libc         |38| ----------- | ---------------------------------- | ---------------------- |39| Return Type | `Maybe<T>` with rich `Error`       | `io::Error` (lossy)    |40| Windows     | Full support with libuv fallback   | Incomplete/POSIX-ish   |41| Error Info  | errno, syscall tag, path, fd       | errno only             |42| EINTR       | Automatic retry                    | Manual handling        |43| Paths       | `&[u8]` (WTF-8 safe)               | `&Path` (UTF-8 lossy)  |44 45## Error Handling with Maybe<T>46 47`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`:48 49```rust50use bun_sys_jsc::ErrorJsc;51use bun_sys::{File, Fd, O};52 53let file = match File::openat(Fd::cwd(), path, O::RDONLY, 0) {54    Ok(f) => f,55    Err(err) => return Ok(err.to_js(global)?),56};57```58 59`bun_sys::Error` carries `errno`, `syscall: Tag`, and `path: Box<[u8]>`. To branch on errno:60 61```rust62match bun_sys::unlink(path) {63    Ok(()) => {}64    Err(e) if e.errno() == bun_c::ENOENT => {} // already gone65    Err(e) => return Err(e),66}67```68 69## Key Types and Functions70 71- `Fd` (`bun_core::Fd`) — cross-platform file descriptor. `Fd::cwd()`, `Fd::stdin()/stdout()/stderr()`, `fd.close()`.72- `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)`73- `file.read(buf)` / `read_all(buf)` / `read_to_end()` / `read_to_end_small()` / `write(buf)` / `write_all(buf)`74- `bun_sys::open`, `read`, `write`, `pread`, `pwrite`, `stat`, `fstat`, `lstat`, `mkdir`, `unlink`, `rename`, `symlink`, `chmod` — free fns over `Fd`75- Open flags: `bun_sys::O::RDONLY`, `O::WRONLY | O::CREAT | O::TRUNC`, etc.76 77## Path Buffers78 79Use `bun_paths` for joining/normalization and the path-buffer pool to avoid 64 KB stack allocations on Windows:80 81```rust82use bun_paths::{path_buffer_pool, resolve_path::{self, platform}};83 84let mut buf = path_buffer_pool::get();85let joined = resolve_path::join_string_buf::<platform::Auto>(&mut *buf, &[dir, name]);86let file = File::openat(Fd::cwd(), joined, O::RDONLY, 0)?;87```88 89## Common Mistakes90 91- **Don't `.unwrap()`** a `bun_sys` result that user input or the OS can cause to fail at runtime — return the error.92- **Don't use `std::fs::File`** — it loses the syscall tag and path needed for Node-compatible error objects.93- **Don't allocate `PathBuffer` on the stack** in hot paths — use `path_buffer_pool::get()`.94- **Don't forget `Drop`** alone closes a `File` — never `file.fd().close()` while the `File` is still live (double close).95 96See `src/CLAUDE.md` for the full `bun_core`/`bun_sys` reference.97