Struct subprocess::Exec
[−]
[src]
pub struct Exec { /* fields omitted */ }
A builder for Popen
instances, providing control and
convenience methods.
Exec
provides a builder API for Popen::create
, and
includes convenience methods for capturing the output, and for
connecting subprocesses into pipelines.
Examples
Execute an external command and wait for it to complete:
let exit_status = Exec::cmd("umount").arg(dirname).join()?;
Execute the command using the OS shell, like C's system
:
Exec::shell("shutdown -h now").join()?;
Start a subprocess and obtain its output as a Read
trait object,
like C's popen
:
let stream = Exec::cmd("ls").stream_stdout()?; // call stream.read_to_string, construct io::BufReader(stream), etc.
Capture the output of a command:
let out = Exec::cmd("ls") .stdout(Redirection::Pipe) .capture()? .stdout_str();
Redirect errors to standard output, and capture both in a single stream:
let out_and_err = Exec::cmd("ls") .stdout(Redirection::Pipe) .stderr(Redirection::Merge) .capture()? .stdout_str();
Provide input to the command and read its output:
let out = Exec::cmd("sort") .stdin("b\nc\na\n") .stdout(Redirection::Pipe) .capture()? .stdout_str(); assert!(out == "a\nb\nc\n");
Methods
impl Exec
[src]
fn cmd<S: AsRef<OsStr>>(command: S) -> Exec
Constructs a new Exec
, configured to run command
.
The command will be run directly in the OS, without an
intervening shell. To run it through a shell, use
Exec::shell
instead.
By default, the command will be run without arguments, and none of the standard streams will be modified.
fn shell<S: AsRef<OsStr>>(cmdstr: S) -> Exec
Constructs a new Exec
, configured to run cmdstr
with
the system shell.
subprocess
never spawns shells without an explicit
request. This command requests the shell to be used; on
Unix-like systems, this is equivalent to
Exec::cmd("sh").arg("-c").arg(cmdstr)
. On Windows, it
runs Exec::cmd("cmd.exe").arg("/c")
.
shell
is useful for porting code that uses the C
system
function, which also spawns a shell.
When invoking this function, be careful not to interpolate
arguments into the string run by the shell, such as
Exec::shell(format!("sort {}", filename))
. Such code is
prone to errors and, if filename
comes from an untrusted
source, to shell injection attacks. Instead, use
Exec::cmd("sort").arg(filename)
.
fn arg<S: AsRef<OsStr>>(self, arg: S) -> Exec
Appends arg
to argument list.
fn args<S: AsRef<OsStr>>(self, args: &[S]) -> Exec
Extends the argument list with args
.
fn detached(self) -> Exec
Specifies that the process is initially detached.
A detached process means that we will not wait for the process to finish when the object that owns it goes out of scope.
fn env_clear(self) -> Exec
Clear the environment of the subprocess.
When this is invoked, the subprocess will not inherit the environment of this process.
fn env<K, V>(self, key: K, value: V) -> Exec where K: AsRef<OsStr>, V: AsRef<OsStr>
Specifies the value of an environment variable in the child process.
Other environment variables are inherited by default. If
this is undesirable, call env_clear
first.
fn env_remove<K>(self, key: K) -> Exec where K: AsRef<OsStr>
Removes an environment variable from the child process.
Other environment variables are inherited by default.
fn stdin<T: IntoInputRedirection>(self, stdin: T) -> Exec
Specifies how to set up the standard input of the child process.
Argument can be:
- a
Redirection
; - a
File
, which is a shorthand forRedirection::File(file)
; - a
Vec<u8>
or&str
, which will set up aRedirection::Pipe
for stdin, making sure thatcapture
feeds that data into the standard input of the subprocess; NullFile
, which will redirect the standard input to read from/dev/null
.
fn stdout<T: IntoOutputRedirection>(self, stdout: T) -> Exec
Specifies how to set up the standard output of the child process.
Argument can be:
- a
Redirection
; - a
File
, which is a shorthand forRedirection::File(file)
; NullFile
, which will redirect the standard output to go to/dev/null
.
fn stderr<T: IntoOutputRedirection>(self, stderr: T) -> Exec
Specifies how to set up the standard error of the child process.
Argument can be:
- a
Redirection
; - a
File
, which is a shorthand forRedirection::File(file)
; NullFile
, which will redirect the standard error to go to/dev/null
.
fn popen(self) -> PopenResult<Popen>
Starts the process, returning a Popen
for the running process.
fn join(self) -> PopenResult<ExitStatus>
Starts the process, waits for it to finish, and returns the exit status.
This method will wait for as long as necessary for the
process to finish. If a timeout is needed, use
popen()?.wait_timeout(...)
instead.
fn stream_stdout(self) -> PopenResult<Box<Read>>
Starts the process and returns a Read
trait object that
reads from the standard output of the child process.
This will automatically set up
stdout(Redirection::Pipe)
, so it is not necessary to do
that beforehand.
When the trait object is dropped, it will wait for the
process to finish. If this is undesirable, use
detached()
.
fn stream_stderr(self) -> PopenResult<Box<Read>>
Starts the process and returns a Read
trait object that
reads from the standard error of the child process.
This will automatically set up
stderr(Redirection::Pipe)
, so it is not necessary to do
that beforehand.
When the trait object is dropped, it will wait for the
process to finish. If this is undesirable, use
detached()
.
fn stream_stdin(self) -> PopenResult<Box<Write>>
Starts the process and returns a Write
trait object that
writes to the standard input of the child process.
This will automatically set up stdin(Redirection::Pipe)
,
so it is not necessary to do that beforehand.
When the trait object is dropped, it will wait for the
process to finish. If this is undesirable, use
detached()
.
fn capture(self) -> PopenResult<Capture>
Starts the process, collects its output, and waits for it to finish.
The return value provides the standard output and standard error as bytes or optionally strings, as well as the exit status.
Unlike Popen::communicate
, this method actually waits
for the process to finish, rather than simply waiting for
its standard streams to close. If this is undesirable,
use detached()
.
Trait Implementations
impl Debug for Exec
[src]
impl Clone for Exec
[src]
fn clone(&self) -> Exec
Returns a copy of the value.
This method is guaranteed not to fail as long as none of
the Redirection
values contain a Redirection::File
variant. If a redirection to File
is present, cloning
that field will use File::try_clone
method, which
duplicates a file descriptor and can (but is not likely
to) fail. In that scenario, Exec::clone
panics.
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more