Struct Command

pub struct Command(/* private fields */);

A process builder, providing fine-grained control over how a new process should be spawned.

A default configuration can be generated using Command::new(program), where program gives a path to the program to be executed. Additional builder methods allow the configuration to be changed (for example, by adding arguments) prior to spawning:

use compio_process::Command;

let output = if cfg!(windows) {
    Command::new("cmd")
        .args(["/C", "echo hello"])
        .output()
        .await
        .expect("failed to execute process")
} else {
    Command::new("sh")
        .args(["-c", "echo hello"])
        .output()
        .await
        .expect("failed to execute process")
};

let hello = output.stdout;

Command can be reused to spawn multiple processes. The builder methods change the command without needing to immediately spawn the process.

use compio_process::Command;

let mut echo_hello = Command::new("sh");
echo_hello.arg("-c").arg("echo hello");
let hello_1 = echo_hello
    .output()
    .await
    .expect("failed to execute process");
let hello_2 = echo_hello
    .output()
    .await
    .expect("failed to execute process");

Similarly, you can call builder methods after spawning a process and then spawn a new process with the modified settings.

use compio_process::Command;

let mut list_dir = Command::new("ls");

// Execute `ls` in the current directory of the program.
list_dir.status().await.expect("process failed to execute");

println!();

// Change `ls` to execute in the root directory.
list_dir.current_dir("/");

// And then execute `ls` again but in the root directory.
list_dir.status().await.expect("process failed to execute");

See std::process::Command for detailed documents.

Implementations

impl Command

pub fn new(program: impl AsRef<OsStr>) -> Self

Create Command.

pub fn arg(&mut self, arg: impl AsRef<OsStr>) -> &mut Self

Adds an argument to pass to the program.

pub fn args<I, S>(&mut self, args: I) -> &mut Self

where I: IntoIterator<Item = S>, S: AsRef<OsStr>,

Adds multiple arguments to pass to the program.

pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Self

where K: AsRef<OsStr>, V: AsRef<OsStr>,

Inserts or updates an explicit environment variable mapping.

pub fn envs<I, K, V>(&mut self, vars: I) -> &mut Self

where I: IntoIterator<Item = (K, V)>, K: AsRef<OsStr>, V: AsRef<OsStr>,

Inserts or updates multiple explicit environment variable mappings.

pub fn env_remove(&mut self, key: impl AsRef<OsStr>) -> &mut Self

Removes an explicitly set environment variable and prevents inheriting it from a parent process.

pub fn env_clear(&mut self) -> &mut Self

Clears all explicitly set environment variables and prevents inheriting any parent process environment variables.

pub fn current_dir(&mut self, dir: impl AsRef<Path>) -> &mut Self

Sets the working directory for the child process.

pub fn stdin<S: TryInto<Stdio>>( &mut self, cfg: S, ) -> Result<&mut Self, S::Error>

Configuration for the child process’s standard input (stdin) handle.

pub fn stdout<S: TryInto<Stdio>>( &mut self, cfg: S, ) -> Result<&mut Self, S::Error>

Configuration for the child process’s standard output (stdout) handle.

pub fn stderr<S: TryInto<Stdio>>( &mut self, cfg: S, ) -> Result<&mut Self, S::Error>

Configuration for the child process’s standard error (stderr) handle.

pub fn get_program(&self) -> &OsStr

Returns the path to the program.

pub fn get_args(&self) -> CommandArgs<'_>

Returns an iterator of the arguments that will be passed to the program.

pub fn get_envs(&self) -> CommandEnvs<'_>

Returns an iterator of the environment variables explicitly set for the child process.

pub fn get_current_dir(&self) -> Option<&Path>

Returns the working directory for the child process.

pub fn spawn(&mut self) -> Result<Child>

Executes the command as a child process, returning a handle to it.

pub async fn status(&mut self) -> Result<ExitStatus>

Executes a command as a child process, waiting for it to finish and collecting its status. The output of child stdout and child stderr will be ignored.

pub async fn output(&mut self) -> Result<Output>

Executes the command as a child process, waiting for it to finish and collecting all of its output.

impl Command

pub fn uid(&mut self, id: u32) -> &mut Self

Available on Unix only.

Sets the child process’s user ID. This translates to a setuid`` call in the child process. Failure in the setuid` call will cause the spawn to fail.

pub fn gid(&mut self, id: u32) -> &mut Self

Available on Unix only.

Similar to uid, but sets the group ID of the child process. This has the same semantics as the uid field.

pub unsafe fn pre_exec( &mut self, f: impl FnMut() -> Result<()> + Send + Sync + 'static, ) -> &mut Self

Available on Unix only.

Schedules a closure to be run just before the exec function is invoked.

Safety

See CommandExt::pre_exec.

pub fn exec(&mut self) -> Error

Available on Unix only.

exec the command without fork.

pub fn arg0(&mut self, arg: impl AsRef<OsStr>) -> &mut Self

Available on Unix only.

Set the first process argument, argv[0], to something other than the default executable path.

pub fn process_group(&mut self, pgroup: i32) -> &mut Self

Available on Unix only.

Sets the process group ID (PGID) of the child process.

Trait Implementations

impl Debug for Command

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.