Struct tokio_process::Command

pub struct Command { /* fields omitted */ }

This structure mimics the API of std::process::Command found in the standard library, but replaces functions that create a process with an asynchronous variant. The main provided asynchronous functions are spawn, status, and output.

Command uses asynchronous versions of some std types (for example Child).

Methods

impl Command

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

Constructs a new Command for launching the program at path program, with the following default configuration:

• No arguments to the program
• Inherit the current process's environment
• Inherit the current process's working directory
• Inherit stdin/stdout/stderr for spawn or status, but create pipes for output

Builder methods are provided to change these defaults and otherwise configure the process.

If program is not an absolute path, the PATH will be searched in an OS-defined way.

The search path to be used may be controlled by setting the PATH environment variable on the Command, but this has some implementation limitations on Windows (see issue rust-lang/rust#37519).

Examples

Basic usage:

use tokio_process::Command;
let command = Command::new("sh");

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

Adds an argument to pass to the program.

Only one argument can be passed per use. So instead of:

.arg("-C /path/to/repo")

usage would be:

.arg("-C")
.arg("/path/to/repo")

To pass multiple arguments see args.

Examples

Basic usage:

use tokio_process::Command;

let command = Command::new("ls")
        .arg("-l")
        .arg("-a");

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.

To pass a single argument see arg.

Examples

Basic usage:

use tokio_process::Command;

let command = Command::new("ls")
        .args(&["-l", "-a"]);

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

Inserts or updates an environment variable mapping.

Note that environment variable names are case-insensitive (but case-preserving) on Windows, and case-sensitive on all other platforms.

Examples

Basic usage:

use tokio_process::Command;

let command = Command::new("ls")
        .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>, 

Adds or updates multiple environment variable mappings.

Examples

Basic usage:

use std::process::{Stdio};
use std::env;
use std::collections::HashMap;
use tokio_process::Command;

let filtered_env : HashMap<String, String> =
    env::vars().filter(|&(ref k, _)|
        k == "TERM" || k == "TZ" || k == "LANG" || k == "PATH"
    ).collect();

let command = Command::new("printenv")
        .stdin(Stdio::null())
        .stdout(Stdio::inherit())
        .env_clear()
        .envs(&filtered_env);

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

Removes an environment variable mapping.

Examples

Basic usage:

use tokio_process::Command;

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

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

Clears the entire environment map for the child process.

Examples

Basic usage:

use tokio_process::Command;

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

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

Sets the working directory for the child process.

Platform-specific behavior

If the program path is relative (e.g., "./script.sh"), it's ambiguous whether it should be interpreted relative to the parent's working directory or relative to current_dir. The behavior in this case is platform specific and unstable, and it's recommended to use canonicalize to get an absolute program path instead.

Examples

Basic usage:

use tokio_process::Command;

let command = Command::new("ls")
        .current_dir("/bin");

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

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

Defaults to inherit when used with spawn or status, and defaults to piped when used with output.

Examples

Basic usage:

use std::process::{Stdio};
use tokio_process::Command;

let command = Command::new("ls")
        .stdin(Stdio::null());

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

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

Defaults to inherit when used with spawn or status, and defaults to piped when used with output.

Examples

Basic usage:

use std::process::{Stdio};
use tokio_process::Command;;

let command = Command::new("ls")
        .stdout(Stdio::null());

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

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

Defaults to inherit when used with spawn or status, and defaults to piped when used with output.

Examples

Basic usage:

use std::process::{Stdio};
use tokio_process::Command;;

let command = Command::new("ls")
        .stderr(Stdio::null());

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

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

By default, stdin, stdout and stderr are inherited from the parent.

This method will spawn the child process synchronously and return a handle to a future-aware child process. The Child returned implements Future itself to acquire the ExitStatus of the child, and otherwise the Child has methods to acquire handles to the stdin, stdout, and stderr streams.

All I/O this child does will be associated with the current default event loop.

Examples

Basic usage:

#![feature(async_await)]
use tokio_process::Command;

async fn run_ls() -> std::process::ExitStatus {
    Command::new("ls")
        .spawn()
        .expect("ls command failed to start")
        .await
        .expect("ls command failed to run")
}

pub fn spawn_with_handle(&mut self, handle: &Handle) -> Result<Child>

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

By default, stdin, stdout and stderr are inherited from the parent.

This method will spawn the child process synchronously and return a handle to a future-aware child process. The Child returned implements Future itself to acquire the ExitStatus of the child, and otherwise the Child has methods to acquire handles to the stdin, stdout, and stderr streams.

The handle specified to this method must be a handle to a valid event loop, and all I/O this child does will be associated with the specified event loop.

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

Executes a command as a child process, waiting for it to finish and collecting its exit status.

By default, stdin, stdout and stderr are inherited from the parent.

The StatusAsync future returned will resolve to the ExitStatus type in the standard library representing how the process exited. If any input/output handles are set to a pipe then they will be immediately closed after the child is spawned.

All I/O this child does will be associated with the current default event loop.

If the StatusAsync future is dropped before the future resolves, then the child will be killed, if it was spawned.

Errors

This function will return an error immediately if the child process cannot be spawned. Otherwise errors obtained while waiting for the child are returned through the StatusAsync future.

Examples

Basic usage:

#![feature(async_await)]
use tokio_process::Command;

async fn run_ls() -> std::process::ExitStatus {
    Command::new("ls")
        .status()
        .expect("ls command failed to start")
        .await
        .expect("ls command failed to run")
}

pub fn status_with_handle(&mut self, handle: &Handle) -> Result<StatusAsync>

Executes a command as a child process, waiting for it to finish and collecting its exit status.

By default, stdin, stdout and stderr are inherited from the parent.

The StatusAsync future returned will resolve to the ExitStatus type in the standard library representing how the process exited. If any input/output handles are set to a pipe then they will be immediately closed after the child is spawned.

The handle specified must be a handle to a valid event loop, and all I/O this child does will be associated with the specified event loop.

If the StatusAsync future is dropped before the future resolves, then the child will be killed, if it was spawned.

Errors

This function will return an error immediately if the child process cannot be spawned. Otherwise errors obtained while waiting for the child are returned through the StatusAsync future.

Important traits for OutputAsync

impl Future for OutputAsync type Output = Result<Output>;

pub fn output(&mut self) -> OutputAsync

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

Note: this method, unlike the standard library, will unconditionally configure the stdout/stderr handles to be pipes, even if they have been previously configured. If this is not desired then the spawn method should be used in combination with the wait_with_output method on child.

This method will return a future representing the collection of the child process's stdout/stderr. The OutputAsync future will resolve to the Output type in the standard library, containing stdout and stderr as Vec<u8> along with an ExitStatus representing how the process exited.

All I/O this child does will be associated with the current default event loop.

If the OutputAsync future is dropped before the future resolves, then the child will be killed, if it was spawned.

Examples

Basic usage:

#![feature(async_await)]
use tokio_process::Command;

async fn run_ls() {
    let output: std::process::Output = Command::new("ls")
        .output()
        .await
        .expect("ls command failed to run");
    println!("stderr of ls: {:?}", output.stderr);
}

Important traits for OutputAsync

impl Future for OutputAsync type Output = Result<Output>;

pub fn output_with_handle(&mut self, handle: &Handle) -> OutputAsync

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

Note: this method, unlike the standard library, will unconditionally configure the stdout/stderr handles to be pipes, even if they have been previously configured. If this is not desired then the spawn method should be used in combination with the wait_with_output method on child.

This method will return a future representing the collection of the child process's stdout/stderr. The OutputAsync future will resolve to the Output type in the standard library, containing stdout and stderr as Vec<u8> along with an ExitStatus representing how the process exited.

The handle specified must be a handle to a valid event loop, and all I/O this child does will be associated with the specified event loop.

If the OutputAsync future is dropped before the future resolves, then the child will be killed, if it was spawned.

Trait Implementations

impl Debug for Command

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

Formats the value using the given formatter.