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

When To Use std.pty

In Zerolang, use std.pty for hosted child processes that need terminal semantics instead of plain pipes. PTY children are useful for interactive CLIs, REPLs, shells, editors, pagers, and tools that change behavior when stdout is a terminal.

Runnable today:

API	Return	Notes
std.pty.spawn(command)	ProcChild	Starts an argv-style command attached to a pseudoterminal.
std.pty.spawnIn(command, cwd)	ProcChild	Starts a PTY child in a hosted working directory.
std.pty.spawnInEnv(command, cwd, env)	ProcChild	Starts a PTY child with a working directory and newline-separated KEY=value environment bindings.
std.pty.spawnArgs(program, args, cwd, env)	ProcChild	Starts a program path plus newline-separated argv entries attached to a pseudoterminal.
std.pty.valid(child)	Bool	Reports whether the handle currently names an open child slot.
std.pty.childValid(child)	Bool	Alias for std.pty.valid.
std.pty.running(child)	Bool	Polls the PTY child without blocking.
std.pty.wait(child)	ProcStatus	Waits for process exit and returns its status.
std.pty.kill(child)	Bool	Sends the child a termination signal on supported hosts.
std.pty.interrupt(child)	Bool	Sends the child an interrupt signal on supported hosts.
std.pty.close(child)	Bool	Closes the handle and remaining terminal resources.
std.pty.pid(child)	i32	Returns the hosted process id for the child, or 0 when unavailable.
std.pty.read(child, buffer)	Maybe<usize>	Nonblocking read from the PTY master into caller storage.
std.pty.write(child, bytes)	Maybe<usize>	Nonblocking write to the PTY master.
std.pty.resize(child, columns, rows)	Bool	Sets the child terminal size on supported hosts.

Metadata labels:

• effects: proc
• allocation behavior: child handles may keep runtime-owned PTY output buffers while wait drains terminal output
• target support: hosted targets with the proc capability
• error behavior: spawn helpers return an invalid ProcChild handle on failure; read and write return null when no bytes can be transferred
• 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

pub fn main(world: World) -> Void raises {
    let child: ProcChild = std.pty.spawnArgs("printf", "hello pty\n", ".", "")
    let resized: Bool = std.pty.resize(child, 80_usize, 24_usize)

    var storage: [64]u8 = [0_u8; 64]
    var saw_output: Bool = false
    var attempts: usize = 0
    while attempts < 20_usize && !saw_output {
        let read: Maybe<usize> = std.pty.read(child, storage)
        if read.has {
            let bytes: Span<u8> = std.io.written(storage, read.value)
            saw_output = std.str.contains(bytes, "hello pty")
        }
        if !saw_output {
            let slept: Bool = std.time.sleep(std.time.ms(10))
        }
        attempts = attempts + 1_usize
    }

    let status: ProcStatus = std.pty.wait(child)
    if resized && saw_output && std.proc.succeeded(status) {
        check world.out.write("pty ok\n")
    }
    let closed: Bool = std.pty.close(child)
}

Design Notes

std.pty returns the same ProcChild handle shape used by std.proc, but the underlying child is connected to a pseudoterminal master. PTY output is a single terminal byte stream: stderr is merged by the terminal, and std.pty.read reads from that stream. Targets without process support, including Windows hosts until their process runtime is implemented, reject PTY helpers before code generation. For short-lived programs, drain the PTY with std.pty.read before wait; some hosts report the terminal as closed once the child exits.

Use std.proc.spawnChild* for programs where separate stdout and stderr pipes matter. Use std.pty.spawn* for programs where terminal behavior matters.