Struct Child 

pub struct Child {
    pub stdin: Option<ChildStdin>,
    pub stdout: Option<ChildStdout>,
    pub stderr: Option<ChildStderr>,
    /* private fields */
}

A spawned child process.

The process can be in running or exited state. Use status() or output() to wait for it to exit.

If the Child is dropped, the process keeps running in the background.

Examples

Spawn a process and wait for it to complete:

use async_process::Command;

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

Fields

stdin: Option<ChildStdin>

The handle for writing to the child’s standard input (stdin), if it has been captured.

stdout: Option<ChildStdout>

The handle for reading from the child’s standard output (stdout), if it has been captured.

stderr: Option<ChildStderr>

The handle for reading from the child’s standard error (stderr), if it has been captured.

Implementations

impl Child

pub fn id(&self) -> u32

Returns the OS-assigned process identifier associated with this child.

Examples

use async_process::Command;

let mut child = Command::new("ls").spawn()?;
println!("id: {}", child.id());

pub fn kill(&mut self) -> Result<()>

Forces the child process to exit.

If the child has already exited, an InvalidInput error is returned.

This is equivalent to sending a SIGKILL on Unix platforms.

Examples

use async_process::Command;

let mut child = Command::new("yes").spawn()?;
child.kill()?;
println!("exit status: {}", child.status().await?);

pub fn try_status(&mut self) -> Result<Option<ExitStatus>>

Returns the exit status if the process has exited.

Unlike status(), this method will not drop the stdin handle.

Examples

use async_process::Command;

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

match child.try_status()? {
    None => println!("still running"),
    Some(status) => println!("exited with: {}", status),
}

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

Drops the stdin handle and waits for the process to exit.

Closing the stdin of the process helps avoid deadlocks. It ensures that the process does not block waiting for input from the parent process while the parent waits for the child to exit.

Examples

use async_process::{Command, Stdio};

let mut child = Command::new("cp")
    .arg("a.txt")
    .arg("b.txt")
    .spawn()?;

println!("exit status: {}", child.status().await?);

Examples found in repository

examples/timeout.rs (line 49)

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 output(self) -> impl Future<Output = Result<Output>>

Drops the stdin handle and collects the output of the process.

Closing the stdin of the process helps avoid deadlocks. It ensures that the process does not block waiting for input from the parent process while the parent waits for the child to exit.

In order to capture the output of the process, Command::stdout() and Command::stderr() must be configured with Stdio::piped().

Examples

use async_process::{Command, Stdio};

let child = Command::new("ls")
    .stdout(Stdio::piped())
    .stderr(Stdio::piped())
    .spawn()?;

let out = child.output().await?;

Trait Implementations

impl Debug for Child

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

Formats the value using the given formatter.