std.process

pid, args, env vars, child processes and pipes

ProcessError

pub ProcessError :: errors {
    spawn_failed,
    wait_failed,
    exit_code_failed,
    command_too_long,
    name_too_long,
    read_failed,
}

• spawn_failed: the child couldn’t be launched
• wait_failed: waiting on the child failed
• exit_code_failed: the child’s exit code couldn’t be read
• command_too_long: command line doesn’t fit in the internal buffer
• name_too_long: env name/value too long for the buffer
• read_failed: reading what the child wrote failed

current_pid

pub current_pid :: fn() -> u32

command_line

pub command_line :: fn(out: []u8) -> []const u8

copied into out, truncated if it doesn’t fit

args

pub args :: fn(a: *Arena) -> [][]const u8

program first, in a; windows splits like the C runtime, linux as the kernel passed

split_command_line

pub split_command_line :: fn(line: []const u8, a: *Arena) -> [][]const u8

windows command line split like the C runtime, in a; the program part has no escapes

get_env

pub get_env :: fn(name: []const u8, out: []u8) -> ?[]const u8

value copied into out; null if unset or it doesn’t fit

set_env

pub set_env :: fn(name: []const u8, value: []const u8) -> bool

later children see it too; linux: a process-wide overlay that get_env and spawn use

unset_env

pub unset_env :: fn(name: []const u8) -> bool

EnvVar

pub EnvVar :: struct {
    name: []const u8,
    value: []const u8,
}

env_vars

pub env_vars :: fn(a: *Arena) -> []EnvVar

all vars in a, set_env/unset_env applied; linux: first 8 KB of the startup env

exe_path

pub exe_path :: fn(a: *Arena) -> ?[]const u8

in a; null when the OS won’t say

Child

pub Child :: struct {
    token: i64,
    stdin: i64,
    stdout: i64,
    stderr: i64,
}

call release when done

• stdin: our end of its stdin pipe, or -1 (spawn_piped)
• stdout: our end of the pipe from its stdout, or -1
• stderr: our end of the pipe from its stderr, or -1

spawn

pub spawn :: fn(command: []const u8) -> Child ! ProcessError

whole command line; inherits our std handles; linux runs it via /bin/sh -c

wait

pub wait :: fn(self: *Child) -> u32 ! ProcessError

blocks; returns the exit code

try_wait

pub try_wait :: fn(self: *Child) -> ?u32 ! ProcessError

non-blocking; null while still running

kill

pub kill :: fn(self: *Child) -> bool

force-terminate

release

pub release :: fn(self: *Child)

frees the OS handle and pipes; safe to call twice

Pipes

pub Pipes :: struct {
    stdin: bool,
    stdout: bool,
    stderr: bool,
}

streams to pipe; the rest stay this process’s

spawn_piped

pub spawn_piped :: fn(command: []const u8, pipes: Pipes) -> Child ! ProcessError

like spawn, with pipes; read while it runs, a full pipe blocks the child piping both stdout and stderr: drain one on another thread or it can deadlock

stdin_file

pub stdin_file :: fn(self: *Child) -> fs::File

writable File; closed if stdin wasn’t piped

stdout_file

pub stdout_file :: fn(self: *Child) -> fs::File

readable File, 0 at EOF; closed if stdout wasn’t piped

stderr_file

pub stderr_file :: fn(self: *Child) -> fs::File

as stdout_file

close_stdin

pub close_stdin :: fn(self: *Child)

child sees EOF on stdin

Output

pub Output :: struct {
    code: u32,
    stdout: []u8,
}

output

pub output :: fn(a: *Arena, command: []const u8) -> Output ! ProcessError

runs to completion, stdout kept in a; stdin and stderr stay ours