Process

import stdlib::process::*;

let cmd: *Command = Command::new("git");
cmd.arg("rev-parse").arg("HEAD").capture_out();
let r: !ProcessResult = cmd.run();
if r.ok {
    println!("HEAD =", r.val.stdout.trim());
}
cmd.free();

pub struct ProcessResult {
    pub exit_code: i32,   // 0 = success
    pub stdout: string,   // empty if not captured
    pub stderr: string,   // empty if not captured
    pub signaled: bool,   // true if child died from a signal (POSIX)
    pub signal: i32,      // signal number; 0 if !signaled
}

pub struct Command {
    pub program: string,
    pub args: *Vector<string>,
    pub env_kv: *Vector<string>,   // entries are "KEY=VAL" strings
    pub cwd_path: string,
    pub stdin_payload: string,
    pub flags: i32,                // bit 0 capture stdout, bit 1 capture stderr,
                                   // bit 2 env_clear, bit 3 pipe stdin,
                                   // bit 4 pipe stdout, bit 5 pipe stderr
}

pub struct Child {
    pub pid: i32,
    pub stdin:  *ChildStdin,    // null unless pipe_stdin()
    pub stdout: *ChildStdout,   // null unless pipe_stdout()
    pub stderr: *ChildStderr,   // null unless pipe_stderr()
}

pub struct ChildStdin  { pub handle: i64 }
pub struct ChildStdout { pub handle: i64 }
pub struct ChildStderr { pub handle: i64 }

let cmd: *Command = Command::new("echo");
defer cmd.free();
cmd.arg("hi").run();

let extras: *Vector<string> = Vector::new();
extras.push_all!("--verbose", "input.txt");

let cmd: *Command = Command::new("tool");
cmd.arg("build")
   .args(extras)
   .env_clear()
   .env("PATH", "/usr/bin:/bin")   // only PATH reaches the child now
   .cwd("/tmp/repo")
   .stdin_str("data\n")
   .capture();

let r: !ProcessResult = cmd.run();
if r.ok { println!("exit:", r.val.exit_code); }
cmd.free();
extras.free();

let cmd: *Command = Command::new("wc");
cmd.arg("-l").stdin_str("a\nb\nc\n").capture_out().capture_err();
let r: !ProcessResult = cmd.run();
if r.ok {
    if r.val.exit_code == 0 {
        println!("lines:", r.val.stdout.trim());   // "3"
    } else {
        println!("failed:", r.val.stderr);
    }
}
cmd.free();

let cmd: *Command = Command::new("gcc");
cmd.arg("missing.c").capture_err();
let r: !ProcessResult = cmd.run();
if r.ok {
    if r.val.exit_code != 0 {
        println!("compile failed:", r.val.stderr.trim());
    } else {
        println!("ok");
    }
} else {
    println!("could not launch gcc:", r.err);
}
cmd.free();

pub fn run(self: *Command) -> !ProcessResult

let r: !ProcessResult = Command::new("echo").arg("hi").capture_out().run();
if r.ok {
    println!("exit:", r.val.exit_code);
    println!("out:",  r.val.stdout.trim());   // "hi"
}

fn capture_uname() -> !string {
    let cmd: *Command = Command::new("uname");
    defer cmd.free();
    let r: ProcessResult = cmd.arg("-s").capture_out().run()?;
    if r.exit_code != 0 { return err("uname failed"); }
    return ok(r.stdout.trim());
}

pub fn spawn(self: *Command) -> !Child

let r: !Child = Command::new("sleep").arg("60").spawn();
if r.ok {
    let ch: *Child = &r.val;
    println!("pid:", ch.pid);
    let k: ! = ch.kill(9);          // SIGKILL on POSIX, TerminateProcess on Windows
    if !k.ok { println!(k.err); }
    let res: !ProcessResult = ch.wait();
    if res.ok {
        if res.val.signaled {
            println!("killed by signal", res.val.signal);
        } else {
            println!("exited", res.val.exit_code);
        }
    }
}

let r: !Child = Command::new("true").spawn();
if r.ok {
    let res: !ProcessResult = r.val.wait();
    if res.ok { println!("exited", res.val.exit_code); }
}

let cmd: *Command = Command::new("cat");
cmd.pipe_stdin().pipe_stdout();
let r: !Child = cmd.spawn();
if r.ok {
    let ch: *Child = &r.val;
    if ch.stdin != null {
        let w: !i32 = ch.stdin.write("hello\n");
        if w.ok { println!("wrote", w.val); }
        let c: ! = ch.stdin.close();        // EOF
        if !c.ok { println!(c.err); }
    }
    if ch.stdout != null {
        let all: !string = ch.stdout.read_all();
        if all.ok { print!(all.val); }
        let oc: ! = ch.stdout.close();
        if !oc.ok { println!(oc.err); }
    }
    let done: !ProcessResult = ch.wait();
    if done.ok { println!("exit", done.val.exit_code); }
}
cmd.free();

let r: !Child = Command::new("ls").arg("-la").pipe_stdout().spawn();
if r.ok {
    let ch: *Child = &r.val;
    if ch.stdout != null {
        while true {
            let chunk: !string = ch.stdout.read(4096);
            if !chunk.ok { println!(chunk.err); break; }
            if chunk.val.len() == 0 { break; }   // EOF
            print!(chunk.val);
        }
        let c: ! = ch.stdout.close();
        if !c.ok { println!(c.err); }
    }
    let done: !ProcessResult = ch.wait();
    if done.ok { println!("exit", done.val.exit_code); }
}

if process_exists(1234) {
    let r: ! = process_kill(1234, 15);   // SIGTERM
    if !r.ok { println!(r.err); }
} else {
    println!("pid 1234 not running");
}

  let cmd: *Command = Command::new("sh");
  cmd.arg("-c").arg("ls -la | wc -l").capture_out();
  let r: !ProcessResult = cmd.run();
  if r.ok && r.val.exit_code == 0 {
      println!("entries:", r.val.stdout.trim());
  }
  cmd.free();
  ```

- **Streaming + `run()` don't mix.** `run()` ignores `pipe_*`; `spawn()` ignores
  `capture_*` and `stdin_str`. Pick one model per command.
- **Signals are POSIX-shaped.** `signaled` / `signal` are only meaningful on
  POSIX; on Windows `kill` always force-terminates regardless of `sig`.
- **Exit code `127`** from a `run()` that returned `ok` usually means the program
  was not found or `chdir` to the `cwd` failed in the child (`execvp` / `chdir`
  failure inside the forked child calls `_exit(127)`).
- **Free the builder.** `Command::new` allocates with `malloc`; always `free()`
  it (use `defer cmd.free();` right after construction) to release the struct and
  its internal vectors.

## See also

- [`stdlib::os`](09-os.md) — lower-level OS primitives (`os_shell` and friends).
- [`stdlib::env`](10-env.md) — read/inspect the parent's environment variables.
- [`fs-io`](08-fs-io.md) — `eprintln` and stream helpers for logging captured
  output.