readFileAlloc reads a file’s contents into dynamically allocated memory. Call it on a directory handle to resolve a relative path, and supply an I/O context, an allocator, and a size limit. section 3.2.1
Listing 3.1 Our first cat
const std = @import("std");
pub fn main(init: std.process.Init) !void {
const io = init.io;
const arena = init.arena.allocator();
const filepath = "meow.txt"; #1
const cwd = std.Io.Dir.cwd(); #2
const text = try cwd.readFileAlloc(io, filepath, arena, .unlimited); #3
const stdout_file = std.Io.File.stdout();
var stdout_buffer: [1024]u8 = undefined;
var stdout_writer = stdout_file.writer(io, &stdout_buffer); #4
const stdout = &stdout_writer.interface; #5
try stdout.writeAll(text);
try stdout.flush();
}
This minimal cat program reads meow.txt from the current working directory, writes the returned contents to stdout, and flushes the writer. section 3.2.1
The example uses std.Io.Dir.cwd() for the directory handle and init.arena.allocator() for allocation. Its call, try cwd.readFileAlloc(io, filepath, arena, .unlimited), propagates errors; the arena’s memory is freed after main returns. section 3.2.1
The convenience comes with a few trade-offs:
- An unreadable file can make the call fail. A user-facing utility may want to report that failure rather than simply propagate it. section 3.4.1
- The call can also fail if memory runs out. With an arena retained until main ends, reading multiple files keeps their allocated contents for the program’s remaining lifetime. section 3.4.1
- For copying data straight to stdout, allocating enough space for the entire file is unnecessary. Reading and writing incrementally avoids that allocation and its potential out-of-memory failure. section 3.4.4
