subprocess/
lib.rs

1//! Execution of and interaction with external processes and pipelines.
2//!
3//! The main entry points to the crate are the [`Exec`] and [`Pipeline`] builders.
4//! They provide a builder-pattern API with convenient methods for streaming and capturing
5//! of output, as well as combining commands into pipelines.
6//!
7//! Compared to `std::process`, the crate provides these additional features:
8//!
9//! * Connecting multiple commands into OS-level [pipelines](Pipeline).
10//!
11//! * The *capture* and *communicate* [family of methods](Job::capture) for
12//!   deadlock-free capturing of subprocess output/error, while simultaneously feeding
13//!   data to its standard input.  Capturing supports optional timeout and read size
14//!   limit.
15//!
16//! * Flexible [redirection options](Redirection), such as connecting standard streams to
17//!   arbitrary [open files](Redirection::File), or [merging](Redirection::Merge) output
18//!   streams like shell's `2>&1` and `1>&2` operators.
19//!
20//! * Non-blocking and timeout methods to wait on the process: [`poll`](Process::poll),
21//!   [`wait`](Process::wait), and [`wait_timeout`](Process::wait_timeout).
22//!
23//! # Examples
24//!
25//! Execute a command and capture its output:
26//!
27//! ```
28//! # use subprocess::*;
29//! # fn dummy() -> std::io::Result<()> {
30//! let out = Exec::cmd("echo").arg("hello").capture()?.stdout_str();
31//! assert!(out.contains("hello"));
32//! # Ok(())
33//! # }
34//! ```
35//!
36//! Use the [`Exec`] builder to execute a pipeline of commands and capture the output:
37//!
38//! ```no_run
39//! # use subprocess::*;
40//! # fn dummy() -> std::io::Result<()> {
41//! let dir_checksum = {
42//!     Exec::shell("find . -type f") | Exec::cmd("sort") | Exec::cmd("sha1sum")
43//! }.capture()?.stdout_str();
44//! # Ok(())
45//! # }
46//! ```
47
48#![warn(missing_debug_implementations, missing_docs)]
49#![allow(clippy::type_complexity)]
50
51mod communicate;
52mod exec;
53mod job;
54mod pipeline;
55mod process;
56mod spawn;
57
58#[cfg(unix)]
59mod posix;
60
61#[cfg(windows)]
62mod win32;
63
64#[cfg(test)]
65mod tests;
66
67pub use communicate::Communicator;
68pub use exec::Redirection;
69#[cfg(unix)]
70pub use exec::unix::ExecExt;
71#[cfg(unix)]
72pub use exec::unix::JobExt;
73#[cfg(unix)]
74pub use exec::unix::PipelineExt;
75#[cfg(windows)]
76pub use exec::windows::ExecExt;
77pub use exec::{Capture, Exec, FromSink, FromSource, InputData};
78pub use job::Job;
79pub use pipeline::Pipeline;
80pub use process::ExitStatus;
81pub use process::Process;
82
83/// Subprocess extensions for Unix platforms.
84#[cfg(unix)]
85pub mod unix {
86    pub use super::exec::unix::JobExt;
87    pub use super::exec::unix::PipelineExt;
88    pub use super::process::ProcessExt;
89}
90
91/// Subprocess extensions for Windows platforms.
92#[cfg(windows)]
93pub mod windows {
94    pub use super::exec::windows::*;
95}
subprocess/lib.rs

subprocess/
lib.rs
