zig-system-calls

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

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

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

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