Struct async_process::Command

source ·
pub struct Command { /* private fields */ }
Expand description

A builder for spawning processes.

Examples

use async_process::Command;

let output = if cfg!(target_os = "windows") {
    Command::new("cmd").args(&["/C", "echo hello"]).output().await?
} else {
    Command::new("sh").arg("-c").arg("echo hello").output().await?
};

Implementations§

source§

impl Command

source

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");
source

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");
source

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"]);
source

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-insensitive (but case-preserving) on Windows, and case-sensitive on all other platforms.

Examples
use async_process::Command;

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

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-insensitive (but case-preserving) on Windows, and case-sensitive on all other platforms.

Examples
use async_process::Command;

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

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");
source

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();
source

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("/");
source

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());
source

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());
source

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());
source

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);
source

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);
source

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()?;
source

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?;
source

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§

source§

impl CommandExt for Command

source§

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.
source§

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.
source§

unsafe fn pre_exec<F>(&mut self, f: F) -> &mut Command
where F: FnMut() -> Result<()> + Send + Sync + 'static,

Schedules a closure to be run just before the exec function is invoked. Read more
source§

fn exec(&mut self) -> Error

Performs all the required setup by this Command, followed by calling the execvp syscall. Read more
source§

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

Set executable argument Read more
source§

impl Debug for Command

source§

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

Formats the value using the given formatter. Read more
source§

impl From<Command> for Command

source§

fn from(inner: Command) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more