command

import std::process::command; · source

Command#

type struct Command {
    program:        String;
    args:           Array<String>;
    envs:           Array<EnvEntry>;
    clear_env_flag: boolean;
    cwd:            Option<String>;
    stdin_cfg:      Stdio;
    stdout_cfg:     Stdio;
    stderr_cfg:     Stdio;

    static new(program: Str) -> Command;
    arg(mut &this, value: Str) -> void;
    env(mut &this, key: Str, value: Str) -> void;
    env_clear(mut &this) -> void;
    cwd(mut &this, path: Str) -> void;
    stdin(mut &this, setting: Stdio) -> void;
    stdout(mut &this, setting: Stdio) -> void;
    stderr(mut &this, setting: Stdio) -> void;
    spawn(&this) -> Result<Child, IoError>;
    output(&this) -> Result<Output, IoError>;
    status(&this) -> Result<ExitStatus, IoError>;
    async collect(&this) -> Result<Output, IoError>;
    async run(&this) -> Result<ExitStatus, IoError>;
    static shell(command: string) -> i32;
    static shell(command: string) -> i32;
}

The builder. Configure it, then finish with spawn, output, or status — or their async spellings, collect and run. For one command line through the platform shell, see exec.

import std::process::command;

mut cmd: Command = Command::new(Str::new("git"));
cmd.arg(Str::new("rev-parse"));
cmd.arg(Str::new("HEAD"));
cmd.stdout(Stdio::Piped);

match (cmd.output()) {
    Result::Ok(out)  => { /* out.stdout() is a Slice<u8> */ }
    Result::Err(e)   => { /* IoError */ }
}

Method	Notes
new(program)	The program is resolved against $PATH at spawn time; pass an absolute path to skip the lookup.
arg(value)	Append one argument.
env(key, value)	Set a variable for the child.
env_clear()	Do not inherit the parent's environment — only env() entries reach the child.
cwd(path)	Working directory for the child.
stdin / stdout / stderr(setting)	Wire up the standard streams.

Finishing#

Method	Returns	Notes
spawn()	Result<Child, IoError>	Fork, configure, exec. You must eventually wait.
output()	Result<Output, IoError>	Spawn, wait, and collect stdout and stderr. The "run this and tell me what it printed" case.
status()	Result<ExitStatus, IoError>	Spawn and wait; streams go wherever you configured them.
collect()	async Output	output without blocking the executor: the drains and the exit wait sit on the reactor (Linux) or the blocking pool (Windows).
run()	async ExitStatus	status without blocking the executor. Use collect when anything is Piped, or the child can stall on a full pipe.

Output#

type struct Output {
    status: ExitStatus;
    stdout: Array<u8>;
    stderr: Array<u8>;

    status(&this) -> ExitStatus;
    stdout(&this) -> Slice<u8>;
    stderr(&this) -> Slice<u8>;
}

Output exposes status(), stdout(), and stderr(). Both slices borrow the Output and are valid only until it drops — copy out anything you need to keep.

output and collect drain the captured pipes before waiting, which is what avoids the classic deadlock of a child blocked on a full pipe while the parent is blocked in wait. On Windows a captured child occupies two blocking-pool threads while draining, so a program running N children concurrently should size the pool for 2N there.

Stdio#

type enum Stdio {
    Inherit;
    Null;
    Piped;
    Fd(i32);
}

Variant	Effect
Inherit	Share the parent's fd. The default.
Null	Redirect to / from /dev/null.
Piped	Create a pipe; the parent's end lands in Child::stdin / stdout / stderr.
Fd(i32)	Use a specific fd. Ownership transfers: the spawn dups it into the child and closes it in the parent.

If execvp fails in the child, it exits with 127 — the standard "command not found" status — so the parent sees that rather than a hang.

Trait implementations#

implement trait Drop for struct Command

implement trait Drop for struct Output

implement trait Drop for struct EnvEntry