← Index

x/sys/proc

Proc: run argv as a child process – wait for status, or capture stdout.

First consumer of Sys pipe; capture is the door callers previously lacked (curl wrote to files, cc printed to the terminal).

Class Proc

Argv-based child processes: run and wait, or run and capture stdout.

Status convention: 0-255 = the child’s exit code; 125 = the child died before exec (an error between fork and exec – the child never escapes); 127 = exec never happened (command absent); 128+N = killed by signal N. Callers branch on = 127 for command-absent (the %pin-download! contract).

(Proc run! argv)

Fork/exec argv; wait; return how the child ended.

Parameters:

• argv : LIST — Command and arguments, e.g. (list “curl” “-fsSL” url)

Returns: INT — Exit status; 127 = exec failed; 128+N = signal death

Examples:

(Proc run! (list "/bin/sh" "-c" "exit 3")) => 3

(Proc %child-prep opts)

Parameters:

• opts : ALIST — Options: (cwd . PATH) and/or (env . ((NAME . VALUE) …))

(Proc run-with! opts argv)

run! with a child-side working directory and/or environment overrides (#364). Env pairs are set on top of the inherited environment; cwd applies after them.

Parameters:

• opts : ALIST — Options: (cwd . PATH) working directory, (env . ((NAME . VALUE) …)) environment overrides – both optional
• argv : LIST — Command and arguments

Returns: INT — Exit status; 126 = the cwd was unusable; 127 = exec failed; 128+N = signal death

Examples:

(Proc run-with! (list (pair 'cwd "/tmp")) (list "/bin/sh" "-c" "test $(pwd) = /tmp || test $(pwd) = /private/tmp")) => 0

(Proc capture-with opts argv)

capture with a child-side working directory and/or environment overrides (#364).

Parameters:

• opts : ALIST — Options as in run-with!
• argv : LIST — Command and arguments

Returns: PAIR — (status . stdout-string); status as in run-with!

Examples:

(rest (Proc capture-with (list (pair 'env (list (pair "X364" "y")))) (list "/bin/sh" "-c" "printf %s $X364"))) => "y"

(Proc capture argv)

Fork/exec argv with stdout piped back; wait; return status and output.

Parameters:

• argv : LIST — Command and arguments

Returns: PAIR — (status . stdout-string); status as in run!

Examples:

(Proc capture (list "/bin/sh" "-c" "printf hi")) => (0 . "hi")