vercel-labs--zerolang/docs/articles/modules/proc.md

When To Use std.proc

In Zerolang, use std.proc for hosted process helpers behind explicit process capability boundaries. The surface is host-only and supports both status-style helpers and owned child handles for incremental I/O.

Runnable today:

API	Return	Notes
std.proc.spawn(command)	ProcStatus	Runs an argv-style command with inherited stdio through the explicit proc capability surface and returns its status.
std.proc.spawnInherit(command)	ProcStatus	Runs an argv-style command while inheriting stdin, stdout, and stderr from the parent process.
std.proc.spawnInheritArgs(program, args, cwd, env)	ProcStatus	Runs a program path plus newline-separated argv entries while inheriting stdio, using a working directory and newline-separated KEY=value environment bindings.
std.proc.exitCode(status)	i32	Reads the process status code.
std.proc.succeeded(status)	Bool	Reports whether the status exit code is 0.
std.proc.failed(status)	Bool	Reports whether the status exit code is nonzero.
std.proc.runOk(command)	Bool	Spawns a hosted command and reports whether the resulting status succeeded.
std.proc.runCode(command)	i32	Spawns a hosted command and returns its exit code.
std.proc.capture(command, buffer)	Maybe<usize>	Runs an argv-style command and captures stdout into caller storage. Returns null on parse failure, spawn failure, nonzero exit, unsupported target, or output truncation.
std.proc.captureArgs(program, args, buffer)	Maybe<usize>	Runs a program path plus newline-separated argv entries and captures stdout into caller storage.
std.proc.captureFiles(command, stdoutPath, stderrPath)	ProcStatus	Runs an argv-style command and writes stdout and stderr to hosted paths. Returns 127 when the command cannot be parsed, spawned, waited on, or the output files cannot be opened.
std.proc.captureFilesArgs(program, args, stdoutPath, stderrPath)	ProcStatus	Runs a program path plus newline-separated argv entries and redirects stdout and stderr to hosted paths.
std.proc.spawnChild(command)	ProcChild	Starts a hosted child process with piped stdin, stdout, and stderr. Returns an invalid handle when the process cannot be created.
std.proc.spawnChildIn(command, cwd)	ProcChild	Starts a hosted child process in a working directory with piped stdin, stdout, and stderr. Returns an invalid handle when the cwd is invalid or the process cannot be created.
std.proc.spawnChildInEnv(command, cwd, env)	ProcChild	Starts a hosted child process in a working directory with piped stdin/stdout/stderr and explicit newline-separated KEY=value environment bindings.
std.proc.spawnChildArgs(program, args, cwd, env)	ProcChild	Starts a hosted child process from a program path plus newline-separated argv entries, working directory, and newline-separated KEY=value environment bindings.
std.proc.childValid(child)	Bool	Reports whether the handle currently names an open child slot.
std.proc.running(child)	Bool	Polls the child process without blocking.
std.proc.wait(child)	ProcStatus	Waits for process exit and returns its status.
std.proc.kill(child)	Bool	Sends the child a termination signal on supported hosts.
std.proc.interrupt(child)	Bool	Sends the child an interrupt signal on supported hosts.
std.proc.close(child)	Bool	Closes the handle and any remaining pipes.
std.proc.closeStdin(child)	Bool	Closes the child stdin pipe while keeping stdout, stderr, and status available.
std.proc.pid(child)	i32	Returns the hosted process id for a child handle, or 0 when unavailable.
std.proc.pidRunning(pid)	Bool	Reports whether a hosted process id appears to be running.
std.proc.killPid(pid)	Bool	Sends a termination signal to a hosted process id on supported hosts.
std.proc.interruptPid(pid)	Bool	Sends an interrupt signal to a hosted process id on supported hosts.
std.proc.killGroupPid(pid)	Bool	Sends a termination signal to the hosted process group whose id is pid on supported hosts.
std.proc.interruptGroupPid(pid)	Bool	Sends an interrupt signal to the hosted process group whose id is pid on supported hosts.
std.proc.readStdout(child, buffer)	Maybe<usize>	Nonblocking read from the child's stdout pipe into caller storage. Returns null when no bytes are currently available or the stream is closed.
std.proc.readStderr(child, buffer)	Maybe<usize>	Nonblocking read from the child's stderr pipe into caller storage. Returns null when no bytes are currently available or the stream is closed.
std.proc.writeStdin(child, bytes)	Maybe<usize>	Nonblocking write to the child's stdin pipe. Returns null when the stream is not writable.

Metadata labels:

• effects: proc
• allocation behavior: child handles may keep runtime-owned pipe buffers while wait drains stdout, stderr, or PTY output
• target support: hosted targets with the proc capability
• error behavior: spawn, spawnInherit, captureFiles, and wait return ProcStatus; exitCode is infallible; capture and child I/O helpers return null when they cannot produce a complete result
• ownership notes: ProcChild values name runtime-owned process slots; call wait when process status matters and close when the handle is no longer needed
• example: examples/std-platform.graph

Example

pub fn main(world: World) -> Void raises {
    let status: ProcStatus = std.proc.spawn("zero-noop")
    var storage: [64]u8 = [0_u8; 64]
    let captured: Maybe<usize> = std.proc.capture("printf proc-capture", storage)
    let files: ProcStatus = std.proc.captureFiles("sh -c 'printf proc-out; printf proc-err >&2'", ".zero/proc.out", ".zero/proc.err")
    if std.proc.succeeded(status) && std.proc.succeeded(files) && std.proc.runOk("sh -c true") && std.proc.runCode("sh -c true") == 0 && captured.has {
        check world.out.write("proc ok\n")
    }
}

Incremental child I/O uses caller-owned buffers:

pub fn main(world: World) -> Void raises {
    let child: ProcChild = std.proc.spawnChild("zero-noop")
    var stdoutStorage: [64]u8 = [0_u8; 64]
    let out: Maybe<usize> = std.proc.readStdout(child, stdoutStorage)
    if out.has {
        check world.out.write("child stdout available\n")
    }
    let pid: i32 = std.proc.pid(child)
    let status: ProcStatus = std.proc.wait(child)
    let closed: Bool = std.proc.close(child)
    if pid > 0 && std.proc.succeeded(status) && closed {
        check world.out.write("child ok\n")
    }
}

Design Notes

std.proc requires a hosted target that advertises the proc capability. Targets without process support, including Windows hosts until their process runtime is implemented, must reject process helpers before code generation.

They should not compile a placeholder process implementation.

capture and captureFiles do not invoke a shell. They split simple argv-style command text and support quoted arguments. capture captures stdout only into caller storage. captureFiles redirects stdout and stderr to separate hosted paths.

spawnInherit uses the same argv-style parser and leaves stdin, stdout, and stderr connected to the parent process. spawnInheritArgs uses an explicit program plus newline-separated argv entries, working directory, and environment block. Use inherited stdio for editor, pager, and terminal program launches where captured pipes would be the wrong interface.

Child handles use the same command parser when created from command text. The *Args helpers avoid command-text parsing: program is argv[0], and each non-empty line in args becomes one following argv entry with spaces preserved. captureArgs captures stdout into caller storage, captureFilesArgs redirects stdout and stderr to hosted paths, and spawnChildArgs returns nonblocking pipes so event loops can poll process state and terminal input without owning threads. wait drains child output into the handle before reaping so post-wait readStdout and readStderr calls can still consume buffered data.

Hosted child helpers start children in their own process group where the target platform supports it. Use killGroupPid or interruptGroupPid when a stored pid should stop a command tree instead of only the direct parent process.

spawnChildInEnv, spawnInheritArgs, and spawnChildArgs accept a newline-separated env block such as "TOKEN=...\nMODE=batch". Empty lines are ignored. Invalid entries or oversized env blocks make the helper fail: status helpers return an error status and child helpers return an invalid handle.