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#![cfg_attr(docsrs, feature(doc_cfg))]
51#![cfg_attr(docsrs, doc(auto_cfg(hide(docsrs))))]
52
53mod communicate;
54mod exec;
55mod job;
56mod pipeline;
57mod process;
58mod spawn;
59
60#[cfg(unix)]
61mod posix;
62
63#[cfg(windows)]
64mod win32;
65
66#[cfg(test)]
67mod tests;
68
69pub use communicate::Communicator;
70pub use exec::Redirection;
71#[cfg(unix)]
72pub use exec::unix::ExecExt;
73#[cfg(unix)]
74pub use exec::unix::JobExt;
75#[cfg(unix)]
76pub use exec::unix::PipelineExt;
77#[cfg(windows)]
78pub use exec::windows::ExecExt;
79pub use exec::{Capture, Exec, FromSink, FromSource, InputData};
80pub use job::Job;
81pub use pipeline::Pipeline;
82pub use process::ExitStatus;
83pub use process::Process;
84
85/// Subprocess extensions for Unix platforms.
86#[cfg(unix)]
87pub mod unix {
88    pub use super::exec::unix::JobExt;
89    pub use super::exec::unix::PipelineExt;
90    pub use super::process::ProcessExt;
91}
92
93/// Subprocess extensions for Windows platforms.
94#[cfg(any(windows, docsrs))]
95pub mod windows {
96    pub use super::exec::windows::*;
97}
subprocess/lib.rs

subprocess/
lib.rs
