[−][src]Struct tokio::process::Command
process
only.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
).
Implementations
impl Command
[src]
pub fn new<S: AsRef<OsStr>>(program: S) -> Command
[src]
process
only.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
orstatus
, but create pipes foroutput
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
[src]
process
only.Adds an argument to pass to the program.
Only one argument can be passed per use. So instead of:
tokio::process::Command::new("sh") .arg("-C /path/to/repo");
usage would be:
tokio::process::Command::new("sh") .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>,
[src]
I: IntoIterator<Item = S>,
S: AsRef<OsStr>,
process
only.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>,
[src]
K: AsRef<OsStr>,
V: AsRef<OsStr>,
process
only.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>,
[src]
I: IntoIterator<Item = (K, V)>,
K: AsRef<OsStr>,
V: AsRef<OsStr>,
process
only.Adds or updates multiple environment variable mappings.
Examples
Basic usage:
use tokio::process::Command; use std::process::{Stdio}; use std::env; use std::collections::HashMap; 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
[src]
process
only.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
[src]
process
only.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
[src]
process
only.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
[src]
process
only.Sets 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
[src]
process
only.Sets 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 tokio::process::Command;; use std::process::Stdio; let command = Command::new("ls") .stdout(Stdio::null());
pub fn stderr<T: Into<Stdio>>(&mut self, cfg: T) -> &mut Command
[src]
process
only.Sets 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 tokio::process::Command;; use std::process::{Stdio}; let command = Command::new("ls") .stderr(Stdio::null());
pub fn kill_on_drop(&mut self, kill_on_drop: bool) -> &mut Command
[src]
process
only.Controls whether a kill
operation should be invoked on a spawned child
process when its corresponding Child
handle is dropped.
By default, this value is assumed to be false
, meaning the next spawned
process will not be killed on drop, similar to the behavior of the standard
library.
Caveats
On Unix platforms processes must be "reaped" by their parent process after they have exited in order to release all OS resources. A child process which has exited, but has not yet been reaped by its parent is considered a "zombie" process. Such processes continue to count against limits imposed by the system, and having too many zombie processes present can prevent additional processes from being spawned.
Although issuing a kill
signal to the child process is a synchronous
operation, the resulting zombie process cannot be .await
ed inside of the
destructor to avoid blocking other tasks. The tokio runtime will, on a
best-effort basis, attempt to reap and clean up such processes in the
background, but makes no additional guarantees are made with regards
how quickly or how often this procedure will take place.
If stronger guarantees are required, it is recommended to avoid dropping
a Child
handle where possible, and instead utilize child.wait().await
or child.kill().await
where possible.
pub fn creation_flags(&mut self, flags: u32) -> &mut Command
[src]
process
only.Sets the process creation flags to be passed to CreateProcess
.
These will always be ORed with CREATE_UNICODE_ENVIRONMENT
.
pub fn spawn(&mut self) -> Result<Child>
[src]
process
only.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:
use tokio::process::Command; async fn run_ls() -> std::process::ExitStatus { Command::new("ls") .spawn() .expect("ls command failed to start") .wait() .await .expect("ls command failed to run") }
Caveats
Dropping/Cancellation
Similar to the behavior to the standard library, and unlike the futures
paradigm of dropping-implies-cancellation, a spawned process will, by
default, continue to execute even after the Child
handle has been dropped.
The Command::kill_on_drop
method can be used to modify this behavior
and kill the child process if the Child
wrapper is dropped before it
has exited.
Unix Processes
On Unix platforms processes must be "reaped" by their parent process after they have exited in order to release all OS resources. A child process which has exited, but has not yet been reaped by its parent is considered a "zombie" process. Such processes continue to count against limits imposed by the system, and having too many zombie processes present can prevent additional processes from being spawned.
The tokio runtime will, on a best-effort basis, attempt to reap and clean up any process which it has spawned. No additional guarantees are made with regards how quickly or how often this procedure will take place.
It is recommended to avoid dropping a Child
process handle before it has been
fully await
ed if stricter cleanup guarantees are required.
Errors
On Unix platforms this method will fail with std::io::ErrorKind::WouldBlock
if the system process limit is reached (which includes other applications
running on the system).
pub fn status(&mut self) -> impl Future<Output = Result<ExitStatus>>
[src]
process
only.Executes the 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. 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.
The destructor of the future returned by this function will kill
the child if kill_on_drop
is set to true.
Errors
This future will return an error if the child process cannot be spawned or if there is an error while awaiting its status.
On Unix platforms this method will fail with std::io::ErrorKind::WouldBlock
if the system process limit is reached (which includes other applications
running on the system).
Examples
Basic usage:
use tokio::process::Command; async fn run_ls() -> std::process::ExitStatus { Command::new("ls") .status() .await .expect("ls command failed to run") }
pub fn output(&mut self) -> impl Future<Output = Result<Output>>
[src]
process
only.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 thewait_with_output
method on child.
This method will return a future representing the collection of the
child process's stdout/stderr. It 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.
The destructor of the future returned by this function will kill
the child if kill_on_drop
is set to true.
Errors
This future will return an error if the child process cannot be spawned or if there is an error while awaiting its status.
On Unix platforms this method will fail with std::io::ErrorKind::WouldBlock
if the system process limit is reached (which includes other applications
running on the system).
Examples
Basic usage:
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); }
Trait Implementations
impl Debug for Command
[src]
impl From<Command> for Command
[src]
fn from(std: StdCommand) -> Command
[src]
Auto Trait Implementations
impl RefUnwindSafe for Command
impl Send for Command
impl Sync for Command
impl Unpin for Command
impl UnwindSafe for Command
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut Tⓘ
[src]
impl<T> From<T> for T
[src]
impl<T> Instrument for T
[src]
fn instrument(self, span: Span) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>
impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
[src]
Notable traits for Instrumented<T>
impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
fn in_current_span(self) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>
impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
[src]
Notable traits for Instrumented<T>
impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,