rm-lisa 0.3.2

//! A wrapper around termios APIs.
//!
//! This has been forked from the `termios` crate, mostly to support some of
//! the newer PRs that have been pending for awhile. The license for the code
//! is available at:
//! <https://github.com/dcuddeback/termios-rs/blob/c0a99bf904ab41a152a43dd9cdd2c44eb0857b47/LICENSE>
//!
//! The following PRs have been merged in:
//!
//! - <https://github.com/dcuddeback/termios-rs/pull/40>
//! - <https://github.com/dcuddeback/termios-rs/pull/31>
//! - <https://github.com/dcuddeback/termios-rs/pull/37>
//! - <https://github.com/dcuddeback/termios-rs/pull/30>
//! - <https://github.com/dcuddeback/termios-rs/pull/28>
//! - <https://github.com/dcuddeback/termios-rs/pull/26>
//!
//! Also the following changes have been made:
//!
//! - Support for `tcgetwinsize`.
//! - Formatting, and linting fixes to make this look like the codebase.
//!
//! -------
//!
//! The termios API operates on file descriptors that are associated with terminal devices, e.g.,
//! `/dev/tty*`. When used with other file descriptors, termios functions return an error. All
//! functions that are part of the POSIX standard are included in the `termios` crate. Where file
//! descriptors are expected, the type `std::os::unix::io::RawFd` is used, and integer error codes
//! are translated to `std::io::Result`.
//!
//! A major feature of the termios API is configuring a terminal device's parameters. The POSIX
//! standard defines a `termios` structure that contains the parameters and several functions for
//! manipulating the parameters. The `termios` crate defines a safe constructor that returns a
//! [`Termios`](struct.Termios.html) struct populated with the parameters of an open terminal
//! device:
//!
//! ```no_run
//! use rm_lisa::termios::*;
//! # let fd = 1;
//! let mut termios = Termios::from_fd(fd).unwrap();
//! ```
//!
//! The [`Termios`](struct.Termios.html) struct provides access to the fields defined in the POSIX
//! standard (`c_iflag`, `c_oflag`, `c_cflag`, `c_lflag`, and `c_cc`):
//!
//! ```no_run
//! # use rm_lisa::termios::*;
//! # let fd = 1;
//! # let mut termios = Termios::from_fd(fd).unwrap();
//! termios.c_cflag |= CREAD | CLOCAL;
//! termios.c_lflag &= !(ICANON | ECHO | ECHOE | ECHOK | ECHONL | ISIG | IEXTEN);
//! termios.c_oflag &= !OPOST;
//! termios.c_iflag &= !(INLCR | IGNCR | ICRNL | IGNBRK);
//!
//! termios.c_cc[VMIN] = 0;
//! termios.c_cc[VTIME] = 0;
//! ```
//!
//! The [`Termios`](struct.Termios.html) struct can also be manipulated using any of the standard
//! termios API functions:
//!
//! ```no_run
//! # use rm_lisa::termios::*;
//! # let fd = 1;
//! # let mut termios = Termios::from_fd(fd).unwrap();
//! cfgetispeed(&termios);
//! cfgetospeed(&termios);
//! cfsetispeed(&mut termios, B9600).unwrap();
//! cfsetospeed(&mut termios, B9600).unwrap();
//! tcsetattr(fd, TCSANOW, &termios).unwrap();
//! ```
//!
//! ## Portability
//!
//! The `termios` crate is organized in a way to help write portable code, while also allowing
//! access to OS-specific functionality when necessary.
//!
//! The crate root contains types, constants, and function definitions that are common across Unix
//! operating systems. Most of the definitions in the crate root are from the POSIX standard;
//! however, support for the standard may differ across operating systems. A couple functions in
//! the crate root are not part of the POSIX standard, but are included in the crate root because
//! they are widely available across Unix operating systems.
//!
//! To write portable code, import the `termios` crate and use only the definitions from the crate
//! root.
//!
//! ### OS-Specific Extensions
//!
//! Each operating system may define extensions to the POSIX API. To make it clear when code
//! depends on OS-specific definitions, any non-standard definitions are exported in the
//! `termios::os` module. Programs that depend on OS-specific functionality must explicity opt-in.
//! When writing portable code that depends on OS-specific definitions, it will often be necessary
//! to use `#[cfg(...)]` attributes to support alternative implementations. The following is an
//! example of a portable function that sets the maximum speed on a `Termios` struct.
//!
//! ```no_run
//! use rm_lisa::termios::{Termios,cfsetspeed};
//! use std::io::Result as IOResult;
//!
//! #[cfg(any(target_os = "macos", target_os = "ios"))]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::darwin::B230400)
//! }
//!
//! #[cfg(target_os = "freebsd")]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::freebsd::B921600)
//! }
//!
//! #[cfg(target_os = "openbsd")]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::openbsd::B921600)
//! }
//!
//! #[cfg(target_os = "netbsd")]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::netbsd::B921600)
//! }
//!
//! #[cfg(target_os = "dragonfly")]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::dragonfly::B230400)
//! }
//!
//! #[cfg(target_os = "solaris")]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::solaris::B921600)
//! }
//!
//! #[cfg(target_os = "illumos")]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::illumos::B921600)
//! }
//!
//! #[cfg(target_os = "aix")]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::aix::B38400)
//! }
//!
//! #[cfg(target_os = "haiku")]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::haiku::B230400)
//! }
//!
//! #[cfg(target_os = "linux")]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::linux::B38400)
//! }
//!
//! #[cfg(target_os = "android")]
//! fn set_fastest_speed(termios: &mut Termios) -> IOResult<()> {
//!     cfsetspeed(termios, rm_lisa::termios::os::android::B4000000)
//! }
//!
//! # let fd = 1;
//! let mut termios = Termios::from_fd(fd).unwrap();
//! set_fastest_speed(&mut termios).unwrap();
//! ```

pub mod ffi;
pub mod os;

use crate::termios::{
	ffi::{
		cfgetispeed as raw_cfgetispeed, cfgetospeed as raw_cfgetospeed, cfmakeraw as raw_cfmakeraw,
		cfsetispeed as raw_cfsetispeed, cfsetospeed as raw_cfsetospeed,
		cfsetspeed as raw_cfsetspeed, tcdrain as raw_tcdrain, tcflow as raw_tcflow,
		tcflush as raw_tcflush, tcgetattr as raw_tcgetattr, tcgetsid as raw_tcgetsid,
		tcgetwinsize as raw_tcgetwinsize, tcsendbreak as raw_tcsendbreak,
		tcsetattr as raw_tcsetattr,
	},
	os::target::{termios as raw_os_termios, winsize as raw_os_winsize},
};
use libc::{c_int, pid_t};
use std::{
	io::{Error as IOError, Result as IOResult},
	mem::MaybeUninit,
	ops::{Deref, DerefMut},
	os::unix::io::RawFd,
};
use valuable::Valuable;

pub use crate::termios::os::target::{
	B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800, B2400, B4800, B9600, B19200,
	B38400, BRKINT, CLOCAL, CREAD, CS5, CS6, CS7, CS8, CSIZE, CSTOPB, ECHO, ECHOE, ECHOK, ECHONL,
	HUPCL, ICANON, ICRNL, IEXTEN, IGNBRK, IGNCR, IGNPAR, INLCR, INPCK, ISIG, ISTRIP, IXANY, IXOFF,
	IXON, NOFLSH, OCRNL, ONLCR, ONLRET, ONOCR, OPOST, PARENB, PARMRK, PARODD, TCIFLUSH, TCIOFF,
	TCIOFLUSH, TCION, TCOFLUSH, TCOOFF, TCOON, TCSADRAIN, TCSAFLUSH, TCSANOW, TOSTOP, VEOF, VEOL,
	VERASE, VINTR, VKILL, VMIN, VQUIT, VSTART, VSTOP, VSUSP, VTIME, cc_t, speed_t, tcflag_t,
};

/// Unix terminal I/O control structure.
///
/// The `Termios` structure is a thin wrapper for the OS-specific `termios` struct. The only safe
/// way to obtain a `Termios` structure is to fill one from a file descriptor with
/// [`Termios::from_fd()`](#method.from_fd), after which it can be treated just like the POSIX
/// `termios` struct. It provides access to the standard fields of the `termios` struct (`c_iflag`,
/// `c_oflag`, `c_cflag`, `c_lflag`, and `c_cc`) through the `Deref` and `DerefMut` traits.
///
/// ## Example
///
/// The following is an example of how one might setup a file descriptor for a serial port:
///
/// ```no_run
/// use std::{io::Result as IOResult, os::unix::io::RawFd};
///
/// fn setup_serial(fd: RawFd) -> IOResult<()> {
///   use rm_lisa::termios::*;
///
///   let mut termios = Termios::from_fd(fd)?;
///
///   termios.c_cflag |= CREAD | CLOCAL;
///   termios.c_lflag &= !(ICANON | ECHO | ECHOE | ECHOK | ECHONL | ISIG | IEXTEN);
///   termios.c_oflag &= !OPOST;
///   termios.c_iflag &= !(INLCR | IGNCR | ICRNL | IGNBRK);
///
///   termios.c_cc[VMIN] = 0;
///   termios.c_cc[VTIME] = 0;
///
///   cfsetspeed(&mut termios, B9600)?;
///   tcsetattr(fd, TCSANOW, &mut termios)?;
///
///   Ok(())
/// }
/// ```
#[derive(Debug, Copy, Clone, Eq, PartialEq, Valuable)]
pub struct Termios {
	inner: raw_os_termios,
}

impl Termios {
	/// Get an empty termios that can't be used.
	#[must_use]
	pub fn empty() -> Self {
		Self {
			inner: raw_os_termios::default(),
		}
	}

	/// Creates a `Termios` structure based on the current settings of a file descriptor.
	///
	/// `fd` must be an open file descriptor for a terminal device.
	///
	/// ## Errors
	///
	/// See your platforms underlying errors for `tcgetattr` given a file
	/// descriptor.
	pub fn from_fd(fd: RawFd) -> IOResult<Self> {
		let mut termios = MaybeUninit::uninit();

		match io_result(unsafe { raw_tcgetattr(fd, termios.as_mut_ptr()) }) {
			Ok(()) => Ok(Termios {
				inner: unsafe { termios.assume_init() },
			}),
			Err(err) => Err(err),
		}
	}

	fn inner(&self) -> &raw_os_termios {
		&self.inner
	}

	fn inner_mut(&mut self) -> &mut raw_os_termios {
		&mut self.inner
	}
}

impl Deref for Termios {
	type Target = raw_os_termios;

	fn deref(&self) -> &raw_os_termios {
		self.inner()
	}
}

impl DerefMut for Termios {
	fn deref_mut(&mut self) -> &mut raw_os_termios {
		self.inner_mut()
	}
}

/// Gets the input baud rate stored in a `Termios` structure.
///
/// ## Errors
///
/// See your platforms underlying errors for `cfgetispeed`.
///
/// ## Examples
///
/// ```
/// # use rm_lisa::termios::{Termios,B9600,cfsetispeed,cfgetispeed};
/// # use std::mem::MaybeUninit;
/// # let mut termios = unsafe { MaybeUninit::uninit().assume_init() };
/// cfsetispeed(&mut termios, B9600).unwrap();
/// assert_eq!(cfgetispeed(&termios), B9600);
/// ```
#[must_use]
pub fn cfgetispeed(termios: &Termios) -> speed_t {
	unsafe { raw_cfgetispeed(termios.inner()) }
}

/// Gets the output baud rate stored in a `Termios` structure.
///
/// ## Errors
///
/// See your platforms underlying errors for `cfgetospeed`.
///
/// ## Examples
///
/// ```
/// # use rm_lisa::termios::{Termios,B9600,cfsetospeed,cfgetospeed};
/// # use std::mem::MaybeUninit;
/// # let mut termios = unsafe { MaybeUninit::uninit().assume_init() };
/// cfsetospeed(&mut termios, B9600).unwrap();
/// assert_eq!(cfgetospeed(&termios), B9600);
/// ```
#[must_use]
pub fn cfgetospeed(termios: &Termios) -> speed_t {
	unsafe { raw_cfgetospeed(termios.inner()) }
}

/// Sets the input baud rate.
///
/// This function only sets the necessary values on the given `Termios` structure. The settings are
/// applied by a subsequent call to [`tcsetattr()`](fn.tcsetattr.html).
///
/// # Parameters
///
/// * `termios` should be a mutable reference to a `Termios` structure.
/// * `speed` should be one of the baud rate constants:
///   - `B0`
///   - `B50`
///   - `B75`
///   - `B110`
///   - `B134`
///   - `B150`
///   - `B200`
///   - `B300`
///   - `B600`
///   - `B1200`
///   - `B1800`
///   - `B2400`
///   - `B4800`
///   - `B9600`
///   - `B19200`
///   - `B38400`
///   - any OS-specific baud rate defined in [`termios::os`](os/index.html).
///
/// A value of `B0` for `speed` sets the input baud rate to be the same as the output baud rate.
///
/// ## Errors
///
/// See your platforms underlying errors for `cfsetispeed`.
///
/// ## Examples
///
/// ```
/// # use rm_lisa::termios::{Termios,B9600,cfsetispeed,cfgetispeed};
/// # use std::mem::MaybeUninit;
/// # let mut termios = unsafe { MaybeUninit::uninit().assume_init() };
/// cfsetispeed(&mut termios, B9600).unwrap();
/// assert_eq!(cfgetispeed(&termios), B9600);
/// ```
pub fn cfsetispeed(termios: &mut Termios, speed: speed_t) -> IOResult<()> {
	io_result(unsafe { raw_cfsetispeed(termios.inner_mut(), speed) })
}

/// Sets the output baud rate.
///
/// This function only sets the necessary values on the given `Termios` structure. The settings are
/// applied on a successful call to [`tcsetattr()`](fn.tcsetattr.html).
///
/// # Parameters
///
/// * `termios` should be a mutable reference to a `Termios` structure.
/// * `speed` should be one of the baud rate constants:
///   - `B0` (hang up)
///   - `B50`
///   - `B75`
///   - `B110`
///   - `B134`
///   - `B150`
///   - `B200`
///   - `B300`
///   - `B600`
///   - `B1200`
///   - `B1800`
///   - `B2400`
///   - `B4800`
///   - `B9600`
///   - `B19200`
///   - `B38400`
///   - any OS-specific baud rate defined in [`termios::os`](os/index.html).
///
/// A value of `B0` for `speed` deasserts the modem control lines when applied with
/// [`tcsetattr()`](fn.tcsetattr.html).  This normally has the effect of disconnecting the line.
///
/// ## Errors
///
/// See your platforms underlying errors for `cfsetospeed`.
///
/// ## Examples
///
/// ```
/// # use rm_lisa::termios::{Termios,B9600,cfsetospeed,cfgetospeed};
/// # use std::mem::MaybeUninit;
/// # let mut termios = unsafe { MaybeUninit::uninit().assume_init() };
/// cfsetospeed(&mut termios, B9600).unwrap();
/// assert_eq!(cfgetospeed(&termios), B9600);
/// ```
pub fn cfsetospeed(termios: &mut Termios, speed: speed_t) -> IOResult<()> {
	io_result(unsafe { raw_cfsetospeed(termios.inner_mut(), speed) })
}

/// Sets input and output baud rates.
///
/// This function only sets the necessary values on the given `Termios` structure. The settings are
/// applied on a successful call to [`tcsetattr()`](fn.tcsetattr.html).
///
/// # Parameters
///
/// * `termios` should be a mutable reference to a `Termios` structure.
/// * `speed` should be one of the baud rate constants:
///   - `B0`
///   - `B50`
///   - `B75`
///   - `B110`
///   - `B134`
///   - `B150`
///   - `B200`
///   - `B300`
///   - `B600`
///   - `B1200`
///   - `B1800`
///   - `B2400`
///   - `B4800`
///   - `B9600`
///   - `B19200`
///   - `B38400`
///   - any OS-specific baud rate defined in [`termios::os`](os/index.html).
///
/// ## Errors
///
/// See your platforms underlying errors for `cfsetspeed`.
///
/// ## Examples
///
/// ```
/// # use rm_lisa::termios::{Termios,B9600,cfsetspeed,cfgetispeed,cfgetospeed};
/// # use std::mem::MaybeUninit;
/// # let mut termios = unsafe { MaybeUninit::uninit().assume_init() };
/// cfsetspeed(&mut termios, B9600).unwrap();
/// assert_eq!(cfgetispeed(&termios), B9600);
/// assert_eq!(cfgetospeed(&termios), B9600);
/// ```
///
/// # Portability
///
/// This function is not part of the IEEE Std 1003.1 ("POSIX.1") specification, but it is available
/// on Linux, BSD, and OS X.
pub fn cfsetspeed(termios: &mut Termios, speed: speed_t) -> IOResult<()> {
	io_result(unsafe { raw_cfsetspeed(termios.inner_mut(), speed) })
}

/// Sets flags to disable all input and output processing.
///
/// This function only sets the necessary values on the given `Termios` structure. The settings are
/// applied on a successful call to [`tcsetattr()`](fn.tcsetattr.html).
///
/// # Portability
///
/// This function is not part of the IEEE Std 1003.1 ("POSIX.1") specification, but it is available
/// on Linux, BSD, and OS X.
///
/// ## Errors
///
/// See your platforms underlying errors for `cfmakeraw`.
pub fn cfmakeraw(termios: &mut Termios) {
	unsafe { raw_cfmakeraw(termios.inner_mut()) };
}

/// Blocks until all output written to the file descriptor is transmitted.
///
/// # Parameters
///
/// * `fd` should be an open file descriptor associated with a terminal.
///
/// ## Errors
///
/// See your platforms underlying errors for `tcdrain`.
pub fn tcdrain(fd: RawFd) -> IOResult<()> {
	io_result(unsafe { raw_tcdrain(fd) })
}

/// Suspends or restarts transmission or reception of data.
///
/// # Parameters
///
/// * `fd` should be an open file descriptor associated with a terminal.
/// * `action` should be one of the following constants:
///   - `TCOOFF` suspends output.
///   - `TCOON` restarts output.
///   - `TCIOFF` transmits a STOP character, intended to cause the remote device to stop
///     transmitting.
///   - `TCION` transmits a START character, intended to cause the remote device to resume
///     transmitting.
///
/// ## Errors
///
/// See your platforms underlying errors for `tcflow`.
pub fn tcflow(fd: RawFd, action: c_int) -> IOResult<()> {
	io_result(unsafe { raw_tcflow(fd, action) })
}

/// Discards data waiting in the terminal device's buffers.
///
/// `tcflush()` discards data that has been written to the device by an application but has not yet
/// been transmitted by the hardware or data that has been received by the hardware but has not yet
/// been read by an application.
///
/// # Parameters
///
/// * `fd` should be an open file descriptor associated with a terminal.
/// * `queue_selector` should be one of:
///   - `TCIFLUSH` to discard data received but not read.
///   - `TCOFLUSH` to discard data written but not transmitted.
///   - `TCIOFLUSH` to discard both data received but not read and data written but not
///     transmitted.
///
/// ## Errors
///
/// See your platforms underlying errors for `tcflush`.
pub fn tcflush(fd: RawFd, queue_selector: c_int) -> IOResult<()> {
	io_result(unsafe { raw_tcflush(fd, queue_selector) })
}

/// Populates a `Termios` structure with parameters associated with a terminal.
///
/// Upon successful completion, the `Termios` structure referred to by the `termios` parameter will
/// contain the parameters associated with the terminal device referred to by `fd`.
///
/// # Parameters
///
/// * `fd` should be an open file descriptor associated with a terminal.
/// * `termios` should be a mutable reference to the `Termios` structure that will hold the
///   terminal device's parameters.
///
/// ## Errors
///
/// See your platforms underlying errors for `tcgetattr`.
pub fn tcgetattr(fd: RawFd, termios: &mut Termios) -> IOResult<()> {
	io_result(unsafe { raw_tcgetattr(fd, termios.inner_mut()) })
}

/// Sets a terminal device's parameters.
///
/// `tcsetattr()` returns successfully if it was able to perform any of the requested actions, even
/// if other requested actions could not be performed. It will set all attributes that the
/// implementation supports and leave others unchanged. The `Termios` structure will not be updated
/// to reflect the changes that were applied.
///
/// In order to determine which parameters were applied to the terminal device, an application
/// should use [`tcgetattr()`](fn.tcgetattr.html) to obtain the latest state of the terminal
/// device. In particular, when attempting to change baud rates, [`tcgetattr()`](fn.tcgetattr.html)
/// can be used to determine which baud rates were actually selected.
///
/// If none of the requested actions could be performed, then `tcsetattr()` returns an error.
///
/// # Parameters
///
/// * `fd` should be an open file descriptor associated with a terminal.
/// * `action` should be one of the constants:
///   - `TCSANOW` applies the change immediately.
///   - `TCSADRAIN` applies the change after all output previously written to `fd` is transmitted.
///     This mode should be used when changing parameters that affect output.
///   - `TCSAFLUSH` applies the change after all output previously written to `fd` is transmitted.
///     All data received but not read is discarded before applying the change.
/// * `termios` should be a mutable reference to a `Termios` structure containing the parameters to
///   apply to the terminal device.
///
/// ## Errors
///
/// See your platforms underlying errors for `tcsetattr`.
pub fn tcsetattr(fd: RawFd, action: c_int, termios: &Termios) -> IOResult<()> {
	io_result(unsafe { raw_tcsetattr(fd, action, termios.inner()) })
}

/// Returns the process group ID of the controlling terminal's session.
///
/// # Parameters
///
/// * `fd` should be an open file descriptor associated with a controlling terminal.
///
/// ## Errors
///
/// See your platforms underlying errors for `tcgetsid`.
#[must_use]
pub fn tcgetsid(fd: RawFd) -> pid_t {
	unsafe { raw_tcgetsid(fd) }
}

/// Transmits data to generate a break condition.
///
/// If the terminal device is using asynchronous data transmission, `tcsendbreak()` transmits a
/// continuous stream of zero bits for a specific duration.
///
/// # Parameters
///
/// * `fd` should be an open file descriptor associated with a terminal.
/// * `duration` controls the duration of the transmitted zero bits. A value of 0 causes a
///   transmission between 0.25 and 0.5 seconds. A value other than 0 causes a transmission for an
///   implementation-defined period of time.
///
/// ## Errors
///
/// See your platforms underlying errors for `tcsendbreak`.
pub fn tcsendbreak(fd: RawFd, duration: c_int) -> IOResult<()> {
	io_result(unsafe { raw_tcsendbreak(fd, duration) })
}

/// Get the terminal window size.
///
/// This will get the window size for a particular file descriptor.
///
/// ## Errors
///
/// See your platforms underlying errors for `tcgetwinsize`.
pub fn tcgetwinsize(fd: RawFd) -> IOResult<raw_os_winsize> {
	let mut winsize: MaybeUninit<raw_os_winsize> = MaybeUninit::uninit();
	io_result(unsafe { raw_tcgetwinsize(fd, winsize.as_mut_ptr()) })?;
	Ok(unsafe { winsize.assume_init() })
}

#[inline]
fn io_result(result: c_int) -> IOResult<()> {
	match result {
		0 => Ok(()),
		_ => Err(IOError::last_os_error()),
	}
}