subprocess/
lib.rs

1//! Execution of and interaction with external processes and pipelines.
2//!
3//! The entry points to the crate are the [`Popen`] struct and the [`Exec`]
4//! builder.  `Popen` is the interface to a running child process, inspired by
5//! Python's [`subprocess.Popen`].  `Exec` provides a builder-pattern API with
6//! convenient methods for streaming and capturing of output, as well as
7//! combining `Popen` instances into pipelines.
8//!
9//! Compared to `std::process`, the module follows the following
10//! additional features:
11//!
12//! * The *communicate* [family of methods] for deadlock-free capturing of
13//!   subprocess output/error, while simultaneously feeding data to its
14//!   standard input.  Capturing supports optional timeout and read size
15//!   limit.
16//!
17//! * Connecting multiple commands into OS-level [pipelines].
18//!
19//! * Flexible [redirection options], such as connecting standard
20//!   streams to arbitary [open files], or [merging] output streams
21//!   like shell's `2>&1` and `1>&2` operators.
22//!
23//! * Non-blocking and timeout methods to wait on the process:
24//!   [`poll`], [`wait`], and [`wait_timeout`].
25//!
26//! # Examples
27//!
28//! Communicate with a process and optionally terminate it:
29//!
30//! ```
31//! # use subprocess::*;
32//! # fn dummy() -> Result<()> {
33//! let mut p = Popen::create(&["ps", "x"], PopenConfig {
34//!     stdout: Redirection::Pipe, ..Default::default()
35//! })?;
36//!
37//! // Obtain the output from the standard streams.
38//! let (out, err) = p.communicate(None)?;
39//!
40//! if let Some(exit_status) = p.poll() {
41//!     // the process has finished
42//! } else {
43//!     // it is still running, terminate it
44//!     p.terminate()?;
45//! }
46//! # Ok(())
47//! # }
48//! ```
49//!
50//! Use the [`Exec`] builder to execute a pipeline of commands and
51//! capture the output:
52//!
53//! ```no_run
54//! # use subprocess::*;
55//! # fn dummy() -> Result<()> {
56//! let dir_checksum = {
57//!     Exec::shell("find . -type f") | Exec::cmd("sort") | Exec::cmd("sha1sum")
58//! }.capture()?.stdout_str();
59//! # Ok(())
60//! # }
61//! ```
62//!
63//! [`Popen`]: struct.Popen.html
64//! [`Exec`]: struct.Exec.html
65//! [family of methods]: struct.Popen.html#method.communicate_start
66//! [redirection options]: enum.Redirection.html
67//! [open files]: enum.Redirection.html#variant.File
68//! [merging]: enum.Redirection.html#variant.Merge
69//! [`poll`]: struct.Popen.html#method.poll
70//! [`wait`]: struct.Popen.html#method.wait
71//! [`wait_timeout`]: struct.Popen.html#method.wait_timeout
72//! [`subprocess.Popen`]: https://docs.python.org/3/library/subprocess.html#subprocess.Popen
73//! [pipelines]: struct.Pipeline.html
74
75#![warn(missing_debug_implementations, rust_2018_idioms, missing_docs)]
76#![allow(clippy::type_complexity, clippy::single_match)]
77
78mod builder;
79mod communicate;
80mod popen;
81
82#[cfg(unix)]
83mod posix;
84
85#[cfg(windows)]
86mod win32;
87
88mod os_common;
89
90pub use self::builder::{CaptureData, Exec, NullFile, Pipeline};
91pub use self::communicate::{CommunicateError, Communicator};
92pub use self::os_common::ExitStatus;
93pub use self::popen::{make_pipe, Popen, PopenConfig, PopenError, Redirection, Result};
94
95/// Subprocess extensions for Unix platforms.
96pub mod unix {
97    pub use super::popen::os_ext::*;
98}
99
100#[cfg(test)]
101mod tests {
102    mod builder;
103    mod common;
104    #[cfg(unix)]
105    mod posix;
106    #[cfg(windows)]
107    mod win32;
108}
subprocess/lib.rs

subprocess/
lib.rs
