Struct subprocess::Pipeline

pub struct Pipeline { /* fields omitted */ }

A builder for multiple Popen instances connected via pipes.

A pipeline is a sequence of two or more Exec commands connected via pipes. Just like in a Unix shell pipeline, each command receives standard input from the previous command, and passes standard output to the next command. Optionally, the standard input of the first command can be provided from the outside, and the output of the last command can be captured.

In most cases you do not need to create Pipeline instances directly; instead, combine Exec instances using the | operator which produces Pipeline.

Examples

Execite a pipeline and return the exit status of the last command:

let exit_status =
  (Exec::shell("ls *.bak") | Exec::cmd("xargs").arg("rm")).join()?;

Capture the pipeline's output:

let dir_checksum = {
    Exec::cmd("find . -type f") | Exec::cmd("sort") | Exec::cmd("sha1sum")
}.capture()?.output_str();

Methods

impl Pipeline

fn new(cmd1: Exec, cmd2: Exec) -> Pipeline

Creates a new pipeline by combining two commands.

Equivalent to cmd1 | cmd2.

fn stdin<T: IntoInputRedirection>(self, stdin: T) -> Pipeline

Specifies how to set up the standard input of the first command in the pipeline.

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) -> Pipeline

Specifies how to set up the standard output of the last command in the pipeline.

Argument can be:

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

fn popen(self) -> PopenResult<Vec<Popen>>

Starts all commands in the pipeline, and returns a Vec<Popen> whose members correspond to running commands.

If some command fails to start, the remaining commands will not be started, and the appropriate error will be returned. The commands that have already started will be waited to finish (but will probably exit immediately due to missing output), except for the ones for which detached() was called. This is equivalent to what the shell does.

fn join(self) -> PopenResult<ExitStatus>

Starts the pipeline, waits for it to finish, and returns the exit status of the last command.

fn stream_stdout(self) -> PopenResult<Box<Read>>

Starts the pipeline and returns a Read trait object that reads from the standard output of the last command.

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 pipeline to finish. If this is undesirable, use detached().

fn stream_stdin(self) -> PopenResult<Box<Write>>

Starts the pipeline and returns a Write trait object that writes to the standard input of the first command.

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<CaptureOutput>

Starts the pipeline, collects its output, and waits for all commands to finish.

The return value provides the standard output of the last command error as bytes or optionally strings, as well as the exit status of the last command.

Unlike Popen::communicate, this method actually waits for the processes to finish, rather than simply waiting for the output to close. If this is undesirable, use detached().

Trait Implementations

impl Debug for Pipeline

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

Formats the value using the given formatter.

impl Clone for Pipeline

fn clone(&self) -> Pipeline

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)

Performs copy-assignment from source.

impl BitOr<Exec> for Pipeline

type Output = Pipeline

The resulting type after applying the | operator

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

Append a command to the pipeline and return a new pipeline.

impl BitOr for Pipeline

type Output = Pipeline

The resulting type after applying the | operator

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

Append a pipeline to the pipeline and return a new pipeline.