Crate subprocess

Execution of and interaction with external processes and pipelines.

The entry points to the crate are the Popen struct and the Exec builder. Popen is the interface to a running child process, inspired by Python’s subprocess.Popen. Exec provides a builder-pattern API with convenient methods for streaming and capturing of output, as well as combining Popen instances into pipelines.

Compared to std::process, the module follows the following additional features:

• The communicate family of methods for deadlock-free capturing of subprocess output/error, while simultaneously feeding data to its standard input. Capturing supports optional timeout and read size limit.

• Connecting multiple commands into OS-level pipelines.

• Flexible redirection options, such as connecting standard streams to arbitary open files, or merging output streams like shell’s 2>&1 and 1>&2 operators.

• Non-blocking and timeout methods to wait on the process: poll, wait, and wait_timeout.

Examples

Communicate with a process and optionally terminate it:

let mut p = Popen::create(&["ps", "x"], PopenConfig {
    stdout: Redirection::Pipe, ..Default::default()
})?;

// Obtain the output from the standard streams.
let (out, err) = p.communicate(None)?;

if let Some(exit_status) = p.poll() {
    // the process has finished
} else {
    // it is still running, terminate it
    p.terminate()?;
}

Use the Exec builder to execute a pipeline of commands and capture the output:

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

Modules

unix

Subprocess extensions for Unix platforms.

Structs

CaptureData

Data captured by Exec::capture and Pipeline::capture.

CommunicateError

Error during communication.

Communicator

Unattended data exchange with the subprocess.

Exec

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

NullFile

Marker value for stdin, stdout, and stderr methods of Exec and Pipeline.

Pipeline

A builder for multiple Popen instances connected via pipes.

Popen

Interface to a running subprocess.

PopenConfig

Options for Popen::create.

Enums

ExitStatus

Exit status of a process.

PopenError

Error in Popen calls.

Redirection

Instruction what to do with a stream in the child process.

Functions

make_pipe

Create a pipe.

Type Definitions

Result

Result returned by calls in the subprocess crate in places where ::std::io::Result does not suffice.