1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
//! 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: //! //! ``` //! # use subprocess::*; //! # fn dummy() -> Result<()> { //! 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()?; //! } //! # Ok(()) //! # } //! ``` //! //! Use the [`Exec`] builder to execute a pipeline of commands and //! capture the output: //! //! ```no_run //! # use subprocess::*; //! # fn dummy() -> Result<()> { //! let dir_checksum = { //! Exec::shell("find . -type f") | Exec::cmd("sort") | Exec::cmd("sha1sum") //! }.capture()?.stdout_str(); //! # Ok(()) //! # } //! ``` //! //! [`Popen`]: struct.Popen.html //! [`Exec`]: struct.Exec.html //! [family of methods]: struct.Popen.html#method.communicate_start //! [redirection options]: enum.Redirection.html //! [open files]: enum.Redirection.html#variant.File //! [merging]: enum.Redirection.html#variant.Merge //! [`poll`]: struct.Popen.html#method.poll //! [`wait`]: struct.Popen.html#method.wait //! [`wait_timeout`]: struct.Popen.html#method.wait_timeout //! [`subprocess.Popen`]: https://docs.python.org/3/library/subprocess.html#subprocess.Popen //! [pipelines]: struct.Pipeline.html #![warn(missing_docs)] #![allow(clippy::type_complexity, clippy::single_match)] mod builder; mod communicate; mod popen; #[cfg(unix)] mod posix; #[cfg(windows)] mod win32; mod os_common; pub use self::builder::{CaptureData, Exec, NullFile, Pipeline}; pub use self::communicate::{CommunicateError, Communicator}; pub use self::os_common::ExitStatus; pub use self::popen::{make_pipe, Popen, PopenConfig, PopenError, Redirection, Result}; /// Subprocess extensions for Unix platforms. pub mod unix { pub use super::popen::os_ext::*; } #[cfg(test)] mod tests { mod builder; mod common; #[cfg(unix)] mod posix; #[cfg(windows)] mod win32; }