std::process
std/src/process.mo
pub def exec_cmd (cmd : String) (args : List String) : IO I64Run cmd args with all three standard streams INHERITED -- what a
shell does without a redirect -- and return the exit status, or -1 when
the child died on a signal (Proc.wait's convention).
Built on proc_spawn (inherit flag) + proc_wait instead of its own
native: fork/exec/wait was implemented twice, once in C and once in the
interpreter, for what is now two calls. A spawn that never happened is
Proc.spawn's Result.err; this returns a plain status, so a failure
to spawn is reported as -1, which is also what a signal death answers.
pub def Process.quiet_terminal (path : String) : IO I64Keep the terminal for the screen: this process's own stderr and every
later exec_cmd child's stdout and stderr are appended to path, and a
child reads /dev/null instead of the keyboard. "" restores both. For a
full-screen program, whose screen a GC warning or a helper command's
message would otherwise overwrite. 0, or -errno when path cannot be
opened.
pub def process_id : I64pub type Child {
child
}pub def Proc.spawn (cmd : String) (args : List String) : IO (Result StreamError Child)Fork+exec cmd args with all three standard streams piped.
Result.err when the child could not be spawned -- a missing
command is not_found, like every other absent thing.
pub def Proc.write (c : Child) (s : String) : IO (Result StreamError I64)Write s to the child's stdin and flush. Result.err when the
child is gone (a dead peer's EPIPE arrives as broken_pipe -- that
is the signal to stop talking to it), Result.ok with the byte
count otherwise.
pub def Proc.read_line (c : Child) : IO (Result StreamError (Option String))One line of the child's stdout WITHOUT its trailing newline (any
\r stays -- toolkit's framing trims it, keeping one definition of
"line" per concern). Option.none is end of stream; a final line
truncated by EOF is DISCARDED rather than half-delivered, because
a JSON-RPC frame without its newline is a truncated message, not a
message. A line whose content exceeds Proc.max_line (one
mebibyte) is invalid_input -- a peer that withholds its newline
must fail the read rather than grow it without limit. Treat such a
peer as broken.
pub def Proc.read_stderr_line (c : Child) : IO (Result StreamError (Option String))Proc.read_line's contract, over the child's stderr -- the log
stream a server writes while its protocol stream stays clean.
pub def Proc.wait (c : Child) : IO I64Close the pipes, reap the child, and return its exit status -- or
-1 if it died on a signal, exec_cmd's own convention. The handle
dies with the child: nothing may use it after wait.
pub def Proc.kill (c : Child) : IO UnitSIGKILL the child, then reap it and free its slot -- one call is the
whole teardown, so no caller needs a wait after kill. Killing
an already-exited child is not an error (a disposer must be
idempotent); a wait AFTER kill returns -1 because the slot is
already freed, not because the kill failed to reap.
pub def Proc.kill_group (pgid : I64) (sig : I64) : IO BoolSignal a process group (a detached job started with set -m, whose
group id is its leader's pid). True when the signal was delivered.
Signal 0 delivers nothing and only probes that the group is alive.
pub def Proc.sigterm : I64pub def Proc.sigkill : I64pub def Proc.shell_quote (s : String) : StringQuote s so that a POSIX shell reads it as one literal word.
Single quotes, because they are the only POSIX quoting that is FULLY
literal: no parameter expansion, no command substitution, no backslash
escapes, no globbing. So a quoted argument cannot be reinterpreted by
the shell whatever it contains -- which is what makes it safe to pass a
path, a git URL or a ref through sh -c at all.
This is the control, not a convention. Every interpolated component of
a sh -c script must go through it, and
test_capture_does_not_expand_a_dollar_sign (in
std/src/process_tests.mo) is what fails if one stops doing so: it
asserts that $HOME reaches echo as four literal characters.
pub def Proc.capture (cmd : String) (args : List String) : IO (Pair I64 String)Run cmd args and return its exit status together with everything it
wrote, stdout and stderr MERGED.
Merged on purpose. The callers are toolchain probes and failing
external tools, and which stream carries the interesting text is not
something they should have to know: clang -dumpmachine prints the
triple on stdout, llc --version splits its target list across both
depending on version, and a failed mlir-opt pass pipeline puts its
ENTIRE signal on stderr (see plans/bootstrapping/mlir-codegen.md, which
records that as a hard blocker). One string, one exit code.