Process and Environment

Overview

After building observability with timers, logging, and progress bars in the previous chapter, we now step into the mechanics of how Zig programs interact with their immediate operating-system context. That means enumerating command-line arguments, examining and shaping environment variables, managing working directories, and spawning child processes—all via std.process on Zig 0.15.2. process.zig

Mastering these APIs lets tools feel at home on every machine: flags parse predictably, configuration flows in cleanly, and subprocesses cooperate instead of hanging or leaking handles. In Part VI we will broaden that scope across build targets, so the patterns here form the portable baseline to build upon. 41

Learning Goals

• Navigate std.process iterators to inspect program arguments without leaking allocations.
• Capture, clone, and modify environment maps safely using Zig’s sentinel-aware strings. 3
• Query and update the current working directory with deterministic error handling.
• Launch child processes, harvest their output, and interpret exit conditions in a portable fashion. Child.zig
• Build small utilities that respect user overrides while maintaining predictable defaults. 5

Process Basics: Arguments, Environment, and CWD

Zig keeps process state explicit: argument iteration, environment snapshots, and working-directory lookups all surface as functions returning slices or dedicated structs rather than hidden globals. That mirrors the data-first mindset from Part I while adding just enough OS abstraction to stay portable. 1

const std = @import("std");

pub fn main() !void {
    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
    defer arena.deinit();
    const allocator = arena.allocator();

    const argv = try std.process.argsAlloc(allocator);
    defer std.process.argsFree(allocator, argv);

    const argc = argv.len;
    const program_name = if (argc > 0)
        std.fs.path.basename(std.mem.sliceTo(argv[0], 0))
    else
        "<unknown>";

    std.debug.print("argv[0].basename = {s}\n", .{program_name});
    std.debug.print("argc = {d}\n", .{argc});
    if (argc > 1) {
        std.debug.print("user args present\n", .{});
    } else {
        std.debug.print("user args absent\n", .{});
    }
}

$ zig run args_overview.zig

argv[0].basename = args_overview
argc = 1
user args absent

const std = @import("std");

pub fn main() !void {
    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
    defer arena.deinit();
    const allocator = arena.allocator();

    var env = std.process.EnvMap.init(allocator);
    defer env.deinit();

    try env.put("APP_MODE", "demo");
    try env.put("HOST", "localhost");
    try env.put("THREADS", "4");

    std.debug.print("pairs = {d}\n", .{env.count()});

    try env.put("APP_MODE", "override");
    std.debug.print("APP_MODE = {s}\n", .{env.get("APP_MODE").?});

    env.remove("THREADS");
    const threads = env.get("THREADS");
    std.debug.print("THREADS present? {s}\n", .{if (threads == null) "no" else "yes"});
}

$ zig run env_map_playground.zig

pairs = 3
APP_MODE = override
THREADS present? no

Managing Child Processes

Process orchestration centers on std.process.Child, which wraps OS-specific hazards (handle inheritance, Unicode command lines, signal races) in a consistent interface. 22 You decide how each stream behaves (inherit, ignore, pipe, or close), then wait for a Term that spells out whether the child exited, signaled, or stopped.

const std = @import("std");

pub fn main() !void {
    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
    defer arena.deinit();
    const allocator = arena.allocator();

    var child = std.process.Child.init(&.{ "zig", "version" }, allocator);
    child.stdin_behavior = .Ignore;
    child.stdout_behavior = .Pipe;
    child.stderr_behavior = .Pipe;

    try child.spawn();
    defer if (child.term == null) {
        _ = child.kill() catch {};
    };

    var stdout_buffer = try std.ArrayList(u8).initCapacity(allocator, 0);
    defer stdout_buffer.deinit(allocator);

    var stderr_buffer = try std.ArrayList(u8).initCapacity(allocator, 0);
    defer stderr_buffer.deinit(allocator);

    try std.process.Child.collectOutput(child, allocator, &stdout_buffer, &stderr_buffer, 16 * 1024);

    const term = try child.wait();

    const stdout_trimmed = std.mem.trimRight(u8, stdout_buffer.items, "\r\n");

    switch (term) {
        .Exited => |code| {
            if (code != 0) return error.UnexpectedExit;
        },
        else => return error.UnexpectedExit,
    }

    std.debug.print("zig version -> {s}\n", .{stdout_trimmed});
    std.debug.print("stderr bytes -> {d}\n", .{stderr_buffer.items.len});
}

$ zig run child_process_capture.zig

zig version -> 0.15.2
stderr bytes -> 0

Notes & Caveats

• argsWithAllocator borrows buffers. Stash any data you need beyond the iteration before calling deinit.
• Environment keys are case-insensitive on Windows. Avoid storing duplicates that differ only by case. 36
• Child.spawn can still fail after fork/CreateProcess. Always call waitForSpawn implicitly via wait() before touching pipes. 13

Exercises

• Write a wrapper that prints a table of (index, argument, length) using only the iterator interface. No heap copies permitted.
• Extend the EnvMap example to merge overlay variables from a .env file while rejecting duplicates of security-critical keys (e.g., PATH). 28
• Build a miniature task runner that spawns three commands in sequence, piping stdout into a progress logger from Chapter 47.

Caveats, alternatives, edge cases

• WASI without libc disables dynamic argument/environment access. Gate code with builtin.os.tag checks when targeting the browser or serverless runtimes.
• On Windows, batch files require cmd.exe quoting rules. Rely on argvToScriptCommandLineWindows rather than crafting strings manually. 41
• High-output children can exhaust pipes. Use collectOutput with a sensible max_output_bytes, or stream to disk to avoid StdoutStreamTooLong.