pty_process/
lib.rs

1//! This crate is a wrapper around [`tokio::process::Command`] or
2//! [`std::process::Command`] which provides the ability to allocate a pty
3//! and spawn new processes attached to that pty, with the pty as their
4//! controlling terminal. This allows for manipulation of interactive
5//! programs.
6//!
7//! The basic functionality looks like this:
8//!
9//! ```no_run
10//! # #[cfg(feature = "async")]
11//! # #[tokio::main]
12//! # async fn foo() -> pty_process::Result<()> {
13//! let (mut pty, pts) = pty_process::open()?;
14//! pty.resize(pty_process::Size::new(24, 80))?;
15//! let mut cmd = pty_process::Command::new("nethack");
16//! let child = cmd.spawn(pts)?;
17//! # Ok(())
18//! # }
19//! # fn main() -> pty_process::Result<()> {
20//! let (mut pty, pts) = pty_process::blocking::open()?;
21//! pty.resize(pty_process::Size::new(24, 80))?;
22//! let mut cmd = pty_process::blocking::Command::new("nethack");
23//! let child = cmd.spawn(pts)?;
24//! # Ok(())
25//! # }
26//! ```
27//!
28//! The returned `child` is a normal instance of [`tokio::process::Child`] (or
29//! [`std::process::Child`] for the [`blocking`] variant), with its
30//! `stdin`/`stdout`/`stderr` file descriptors pointing at the given pty. The
31//! `pty` instance implements [`tokio::io::AsyncRead`] and
32//! [`tokio::io::AsyncWrite`] (or [`std::io::Read`] and [`std::io::Write`] for
33//! the [`blocking`] variant), and can be used to communicate with the child
34//! process. The child process will also be made a session leader of a new
35//! session, and the controlling terminal of that session will be set to the
36//! given pty.
37//!
38//! # Features
39//!
40//! By default, only the [`blocking`] APIs are available. To include the
41//! asynchronous APIs, you must enable the `async` feature.
42
43#![warn(clippy::cargo)]
44#![warn(clippy::pedantic)]
45#![warn(clippy::nursery)]
46#![warn(clippy::as_conversions)]
47#![warn(clippy::get_unwrap)]
48#![allow(clippy::cognitive_complexity)]
49#![allow(clippy::missing_const_for_fn)]
50#![allow(clippy::similar_names)]
51#![allow(clippy::struct_excessive_bools)]
52#![allow(clippy::too_many_arguments)]
53#![allow(clippy::too_many_lines)]
54#![allow(clippy::type_complexity)]
55
56mod error;
57pub use error::{Error, Result};
58mod types;
59pub use types::Size;
60
61mod sys;
62
63pub mod blocking;
64
65#[cfg(feature = "async")]
66mod command;
67#[cfg(feature = "async")]
68pub use command::Command;
69#[cfg(feature = "async")]
70mod pty;
71#[cfg(feature = "async")]
72pub use pty::{
73    open, OwnedReadPty, OwnedWritePty, Pts, Pty, ReadPty, WritePty,
74};
pty_process/lib.rs

pty_process/
lib.rs
