Struct subprocess::Exec

pub struct Exec { /* fields omitted */ }

A builder for Popen instances, providing control and convenience methods.

Exec provides a Rustic API for building up the arguments to Popen::create, but also convenience methods and classes for capturing the output, and for connecting Popen instances 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

fn cmd<S: AsRef<OsStr>>(command: S) -> Exec

Constructs a new Exec, configured to run command.

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.

On Unix-like systems, this is equivalent to Exec::cmd("sh").arg("-c").arg(cmdstr). On Windows, cmd.exe /c is used instead.

fn arg<S: AsRef<OsStr>>(self, arg: S) -> Exec

Append arg to argument list.

fn args<S: AsRef<OsStr>>(self, args: &[S]) -> Exec

Extend the argument list with args.

fn detached(self) -> Exec

Specify 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 stdin<T: IntoInputRedirection>(self, stdin: T) -> Exec

Specify how to set up the standard input of the child process.

Argument can be:

• a Redirection;
• a File, which is a shorthand for Redirection::File(file);
• a Vec<u8> or &str, which will set up a Redirection::Pipe for stdin, making sure that capture 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

Specify how to set up the standard output of the child process.

Argument can be:

• a Redirection;
• a File, which is a shorthand for Redirection::File(file);
• NullFile, which will redirect the standard output to go to /dev/null.

fn stderr<T: IntoOutputRedirection>(self, stderr: T) -> Exec

Specify how to set up the standard error of the child process.

Argument can be:

• a Redirection;
• a File, which is a shorthand for Redirection::File(file);
• NullFile, which will redirect the standard error to go to /dev/null.

fn popen(self) -> PopenResult<Popen>

Start the process, and return the Popen for the running process.

fn join(self) -> PopenResult<ExitStatus>

Start the process, wait for it to finish, and return 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>>

Start the process and return 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>>

Start the process and return 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>>

Start the process and return 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>

Start the process, collect its output, and wait 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

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

Formats the value using the given formatter.

impl Clone for Exec

fn clone(&self) -> Exec

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl BitOr for Exec

type Output = Pipeline

The resulting type after applying the | operator

fn bitor(self, rhs: Exec) -> Pipeline

Combine self and rhs into an OS-level pipeline.