Filesystem

Zig 0.16 moved the filesystem API onto std.Io. This is the change most likely to make older filesystem examples fail to compile.

const std = @import("std");

pub fn main(init: std.process.Init) !void {
    const io = init.io;
    const gpa = std.heap.page_allocator;

    // `std.fs.cwd()` is now `std.Io.Dir.cwd()`, and every operation that
    // touches the disk takes the io instance explicitly.
    var dir = std.Io.Dir.cwd();

    // Create, write, close.
    const file = try dir.createFile(io, "example.txt", .{});
    defer file.close(io);

    var buf: [128]u8 = undefined;
    var writer = file.writerStreaming(io, &buf);
    try writer.interface.writeAll("written by zig\n");
    try writer.interface.flush();

    // Read the whole thing back.
    const contents = try dir.readFileAlloc(io, "example.txt", gpa, .limited(1 << 20));
    defer gpa.free(contents);
    std.debug.assert(std.mem.eql(u8, contents, "written by zig\n"));

    // Walk a directory.
    var iterable = try dir.openDir(io, ".", .{ .iterate = true });
    defer iterable.close(io);
    var it = iterable.iterate();
    while (try it.next(io)) |entry| {
        _ = entry.name;
    }

    try dir.deleteFile(io, "example.txt");
}

// Marked `//! norun`: the browser WASI sandbox has no preopened directories,
// so this compiles (proving the API is current) but is not executed.

What moved

Was	Now
`std.fs.cwd()`	`std.Io.Dir.cwd()`
`std.fs.File`	`std.Io.File`
`dir.openFile(path, .{})`	`dir.openFile(io, path, .{})`
`file.close()`	`file.close(io)`

The pattern is uniform: anything that can block takes the io instance as its first argument. You get that instance from main:

pub fn main(init: std.process.Init) !void {
    const io = init.io;

Why

It is the same argument as Allocator. A function’s signature now tells you whether it performs I/O, and the caller decides how that I/O is executed (threaded, evented, or something else) instead of the standard library choosing on your behalf.

Reading a whole file

const contents = try dir.readFileAlloc(io, path, gpa, .limited(1 << 20));
defer gpa.free(contents);

The limit is mandatory, not optional. There is no API that reads an unbounded amount of untrusted input into memory by accident.

Why this page does not run

Every other snippet on this site executes in your browser. This one cannot: WASI programs can only touch directories the host explicitly preopens, and the playground grants none. CI still compiles it, so if the filesystem API changes again this page turns the build red. It just cannot be executed here.