Struct Command 

pub struct Command { /* private fields */ }

A builder for spawning processes.

Examples

use async_process::Command;

let output = Command::new("sh").arg("-c").arg("echo hello").output().await?;

Implementations

impl Command

pub fn new<S: AsRef<OsStr>>(program: S) -> Command

Constructs a new Command for launching program.

The initial configuration (the working directory and environment variables) is inherited from the current process.

Examples

use async_process::Command;

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

Examples found in repository

examples/timeout.rs (line 11)

fn main() -> io::Result<()> {
    async_io::block_on(async {
        // Spawn a a command of your choice.
        let mut child = Command::new("sleep")
            .arg("3")
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()?;

        // Run a future to drain the stdout of the child.
        // We can't use output() here because it would be cancelled along with the child when the timeout
        // expires.
        let mut stdout = String::new();
        let drain_stdout = {
            let buffer = &mut stdout;
            let mut stdout = child.stdout.take().unwrap();

            async move {
                stdout.read_to_string(buffer).await?;

                // Wait for the child to exit or the timeout.
                future::pending().await
            }
        };

        // Run a future to drain the stderr of the child.
        let mut stderr = String::new();
        let drain_stderr = {
            let buffer = &mut stderr;
            let mut stderr = child.stderr.take().unwrap();

            async move {
                stderr.read_to_string(buffer).await?;

                // Wait for the child to exit or the timeout.
                future::pending().await
            }
        };

        // Run a future that waits for the child to exit.
        let wait = async move {
            child.status().await?;

            // Child exited.
            io::Result::Ok(false)
        };

        // Run a future that times out after 1 second.
        let timeout_s = 1;
        let timeout = async move {
            Timer::after(std::time::Duration::from_secs(timeout_s)).await;

            // Timed out.
            Ok(true)
        };

        // Run the futures concurrently.
        // Note: For larger scale programs than this you should probably spawn each individual future on
        // a separate task in an executor.
        let timed_out = drain_stdout.or(drain_stderr).or(wait).or(timeout).await?;

        if timed_out {
            println!("The child timed out.");
        } else {
            println!("The child exited.");
        }

        println!("Stdout:\n{stdout}");
        println!("Stderr:\n{stderr}");

        Ok(())
    })
}

pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Command

Adds a single argument to pass to the program.

Examples

use async_process::Command;

let mut cmd = Command::new("echo");
cmd.arg("hello");
cmd.arg("world");

Examples found in repository

examples/timeout.rs (line 12)

fn main() -> io::Result<()> {
    async_io::block_on(async {
        // Spawn a a command of your choice.
        let mut child = Command::new("sleep")
            .arg("3")
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()?;

        // Run a future to drain the stdout of the child.
        // We can't use output() here because it would be cancelled along with the child when the timeout
        // expires.
        let mut stdout = String::new();
        let drain_stdout = {
            let buffer = &mut stdout;
            let mut stdout = child.stdout.take().unwrap();

            async move {
                stdout.read_to_string(buffer).await?;

                // Wait for the child to exit or the timeout.
                future::pending().await
            }
        };

        // Run a future to drain the stderr of the child.
        let mut stderr = String::new();
        let drain_stderr = {
            let buffer = &mut stderr;
            let mut stderr = child.stderr.take().unwrap();

            async move {
                stderr.read_to_string(buffer).await?;

                // Wait for the child to exit or the timeout.
                future::pending().await
            }
        };

        // Run a future that waits for the child to exit.
        let wait = async move {
            child.status().await?;

            // Child exited.
            io::Result::Ok(false)
        };

        // Run a future that times out after 1 second.
        let timeout_s = 1;
        let timeout = async move {
            Timer::after(std::time::Duration::from_secs(timeout_s)).await;

            // Timed out.
            Ok(true)
        };

        // Run the futures concurrently.
        // Note: For larger scale programs than this you should probably spawn each individual future on
        // a separate task in an executor.
        let timed_out = drain_stdout.or(drain_stderr).or(wait).or(timeout).await?;

        if timed_out {
            println!("The child timed out.");
        } else {
            println!("The child exited.");
        }

        println!("Stdout:\n{stdout}");
        println!("Stderr:\n{stderr}");

        Ok(())
    })
}

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

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

Adds multiple arguments to pass to the program.

Examples

use async_process::Command;

let mut cmd = Command::new("echo");
cmd.args(&["hello", "world"]);

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

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

Configures an environment variable for the new process.

Note that environment variable names are case-sensitive.

Examples

use async_process::Command;

let mut cmd = Command::new("ls");
cmd.env("PATH", "/bin");

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

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

Configures multiple environment variables for the new process.

Note that environment variable names are case-sensitive.

Examples

use async_process::Command;

let mut cmd = Command::new("ls");
cmd.envs(vec![("PATH", "/bin"), ("TERM", "xterm-256color")]);

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

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

Examples

use std::ffi::OsStr;
use async_process::Command;

let mut cmd = Command::new("echo");
cmd.arg("first").arg("second");
let args: Vec<&OsStr> = cmd.get_args().collect();
assert_eq!(args, &["first", "second"]);

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

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

Examples

use std::ffi::OsStr;
use async_process::Command;

let mut cmd = Command::new("ls");
cmd.env("TERM", "dumb").env_remove("TZ");
let envs: Vec<(&OsStr, Option<&OsStr>)> = cmd.get_envs().collect();
assert_eq!(envs, &[
    (OsStr::new("TERM"), Some(OsStr::new("dumb"))),
    (OsStr::new("TZ"), None)
]);

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

Gets the working directory for the child process.

This returns None if the working directory will not be changed.

Examples

use std::path::Path;
use async_process::Command;

let mut cmd = Command::new("ls");
assert_eq!(cmd.get_current_dir(), None);
cmd.current_dir("/bin");
assert_eq!(cmd.get_current_dir(), Some(Path::new("/bin")));

pub fn get_program(&self) -> &OsStr

Gets the path to the program that was given to Command::new.

Examples

use async_process::Command;

let cmd = Command::new("echo");
assert_eq!(cmd.get_program(), "echo");

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

Removes an environment variable mapping.

Examples

use async_process::Command;

let mut cmd = Command::new("ls");
cmd.env_remove("PATH");

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

Removes all environment variable mappings.

Examples

use async_process::Command;

let mut cmd = Command::new("ls");
cmd.env_clear();

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

Configures the working directory for the new process.

Examples

use async_process::Command;

let mut cmd = Command::new("ls");
cmd.current_dir("/");

pub fn stdin<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command

Configures the standard input (stdin) for the new process.

Examples

use async_process::{Command, Stdio};

let mut cmd = Command::new("cat");
cmd.stdin(Stdio::null());

pub fn stdout<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command

Configures the standard output (stdout) for the new process.

Examples

use async_process::{Command, Stdio};

let mut cmd = Command::new("ls");
cmd.stdout(Stdio::piped());

Examples found in repository

examples/timeout.rs (line 13)

fn main() -> io::Result<()> {
    async_io::block_on(async {
        // Spawn a a command of your choice.
        let mut child = Command::new("sleep")
            .arg("3")
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()?;

        // Run a future to drain the stdout of the child.
        // We can't use output() here because it would be cancelled along with the child when the timeout
        // expires.
        let mut stdout = String::new();
        let drain_stdout = {
            let buffer = &mut stdout;
            let mut stdout = child.stdout.take().unwrap();

            async move {
                stdout.read_to_string(buffer).await?;

                // Wait for the child to exit or the timeout.
                future::pending().await
            }
        };

        // Run a future to drain the stderr of the child.
        let mut stderr = String::new();
        let drain_stderr = {
            let buffer = &mut stderr;
            let mut stderr = child.stderr.take().unwrap();

            async move {
                stderr.read_to_string(buffer).await?;

                // Wait for the child to exit or the timeout.
                future::pending().await
            }
        };

        // Run a future that waits for the child to exit.
        let wait = async move {
            child.status().await?;

            // Child exited.
            io::Result::Ok(false)
        };

        // Run a future that times out after 1 second.
        let timeout_s = 1;
        let timeout = async move {
            Timer::after(std::time::Duration::from_secs(timeout_s)).await;

            // Timed out.
            Ok(true)
        };

        // Run the futures concurrently.
        // Note: For larger scale programs than this you should probably spawn each individual future on
        // a separate task in an executor.
        let timed_out = drain_stdout.or(drain_stderr).or(wait).or(timeout).await?;

        if timed_out {
            println!("The child timed out.");
        } else {
            println!("The child exited.");
        }

        println!("Stdout:\n{stdout}");
        println!("Stderr:\n{stderr}");

        Ok(())
    })
}

pub fn stderr<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command

Configures the standard error (stderr) for the new process.

Examples

use async_process::{Command, Stdio};

let mut cmd = Command::new("ls");
cmd.stderr(Stdio::piped());

Examples found in repository

examples/timeout.rs (line 14)

fn main() -> io::Result<()> {
    async_io::block_on(async {
        // Spawn a a command of your choice.
        let mut child = Command::new("sleep")
            .arg("3")
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()?;

        // Run a future to drain the stdout of the child.
        // We can't use output() here because it would be cancelled along with the child when the timeout
        // expires.
        let mut stdout = String::new();
        let drain_stdout = {
            let buffer = &mut stdout;
            let mut stdout = child.stdout.take().unwrap();

            async move {
                stdout.read_to_string(buffer).await?;

                // Wait for the child to exit or the timeout.
                future::pending().await
            }
        };

        // Run a future to drain the stderr of the child.
        let mut stderr = String::new();
        let drain_stderr = {
            let buffer = &mut stderr;
            let mut stderr = child.stderr.take().unwrap();

            async move {
                stderr.read_to_string(buffer).await?;

                // Wait for the child to exit or the timeout.
                future::pending().await
            }
        };

        // Run a future that waits for the child to exit.
        let wait = async move {
            child.status().await?;

            // Child exited.
            io::Result::Ok(false)
        };

        // Run a future that times out after 1 second.
        let timeout_s = 1;
        let timeout = async move {
            Timer::after(std::time::Duration::from_secs(timeout_s)).await;

            // Timed out.
            Ok(true)
        };

        // Run the futures concurrently.
        // Note: For larger scale programs than this you should probably spawn each individual future on
        // a separate task in an executor.
        let timed_out = drain_stdout.or(drain_stderr).or(wait).or(timeout).await?;

        if timed_out {
            println!("The child timed out.");
        } else {
            println!("The child exited.");
        }

        println!("Stdout:\n{stdout}");
        println!("Stderr:\n{stderr}");

        Ok(())
    })
}

pub fn reap_on_drop(&mut self, reap_on_drop: bool) -> &mut Command

Configures whether to reap the zombie process when Child is dropped.

When the process finishes, it becomes a “zombie” and some resources associated with it remain until Child::try_status(), Child::status(), or Child::output() collects its exit code.

If its exit code is never collected, the resources may leak forever. This crate has a background thread named “async-process” that collects such “zombie” processes and then “reaps” them, thus preventing the resource leaks.

The default value of this option is true.

Examples

use async_process::{Command, Stdio};

let mut cmd = Command::new("cat");
cmd.reap_on_drop(false);

pub fn kill_on_drop(&mut self, kill_on_drop: bool) -> &mut Command

Configures whether to kill the process when Child is dropped.

The default value of this option is false.

Examples

use async_process::{Command, Stdio};

let mut cmd = Command::new("cat");
cmd.kill_on_drop(true);

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

Executes the command and returns the Child handle to it.

If not configured, stdin, stdout and stderr will be set to Stdio::inherit().

Examples

use async_process::Command;

let child = Command::new("ls").spawn()?;

Examples found in repository

examples/timeout.rs (line 15)

fn main() -> io::Result<()> {
    async_io::block_on(async {
        // Spawn a a command of your choice.
        let mut child = Command::new("sleep")
            .arg("3")
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()?;

        // Run a future to drain the stdout of the child.
        // We can't use output() here because it would be cancelled along with the child when the timeout
        // expires.
        let mut stdout = String::new();
        let drain_stdout = {
            let buffer = &mut stdout;
            let mut stdout = child.stdout.take().unwrap();

            async move {
                stdout.read_to_string(buffer).await?;

                // Wait for the child to exit or the timeout.
                future::pending().await
            }
        };

        // Run a future to drain the stderr of the child.
        let mut stderr = String::new();
        let drain_stderr = {
            let buffer = &mut stderr;
            let mut stderr = child.stderr.take().unwrap();

            async move {
                stderr.read_to_string(buffer).await?;

                // Wait for the child to exit or the timeout.
                future::pending().await
            }
        };

        // Run a future that waits for the child to exit.
        let wait = async move {
            child.status().await?;

            // Child exited.
            io::Result::Ok(false)
        };

        // Run a future that times out after 1 second.
        let timeout_s = 1;
        let timeout = async move {
            Timer::after(std::time::Duration::from_secs(timeout_s)).await;

            // Timed out.
            Ok(true)
        };

        // Run the futures concurrently.
        // Note: For larger scale programs than this you should probably spawn each individual future on
        // a separate task in an executor.
        let timed_out = drain_stdout.or(drain_stderr).or(wait).or(timeout).await?;

        if timed_out {
            println!("The child timed out.");
        } else {
            println!("The child exited.");
        }

        println!("Stdout:\n{stdout}");
        println!("Stderr:\n{stderr}");

        Ok(())
    })
}

pub fn status(&mut self) -> impl Future<Output = Result<ExitStatus>>

Executes the command, waits for it to exit, and returns the exit status.

If not configured, stdin, stdout and stderr will be set to Stdio::inherit().

Examples

use async_process::Command;

let status = Command::new("cp")
    .arg("a.txt")
    .arg("b.txt")
    .status()
    .await?;

pub fn output(&mut self) -> impl Future<Output = Result<Output>>

Executes the command and collects its output.

If not configured, stdin will be set to Stdio::null(), and stdout and stderr will be set to Stdio::piped().

Examples

use async_process::Command;

let output = Command::new("cat")
    .arg("a.txt")
    .output()
    .await?;

Trait Implementations

impl CommandExt for Command

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

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.

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

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

fn exec(&mut self) -> Error

Performs all the required setup by this Command, followed by calling the execvp syscall.

fn arg0<S>(&mut self, arg: S) -> &mut Command

where S: AsRef<OsStr>,

Set executable argument

impl Debug for Command

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

Formats the value using the given formatter.

impl From<Command> for Command

fn from(inner: Command) -> Self

Converts to this type from the input type.