Crate termios [−] [src]

The termios crate provides Rust bindings for the POSIX termios API that is implemented on Unix operating systems. The termios API is defined in the IEEE Std 1003.1 ("POSIX.1") specification.

Getting Started

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 populated with the parameters of an open terminal device:

use termios::*;
let mut termios = Termios::from_fd(fd).unwrap();

The Termios struct provides access to the fields defined in the POSIX standard (c_iflag, c_oflag, c_cflag, c_lflag, and c_cc):

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 can also be manipulated using any of the standard termios API functions:

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.

use std::io;
use termios::{Termios,cfsetspeed};

#[cfg(target_os = "linux")]
fn set_fastest_speed(termios: &mut Termios) -> io::Result<()> {
    cfsetspeed(termios, termios::os::linux::B4000000)
}

#[cfg(target_os = "macos")]
fn set_fastest_speed(termios: &mut Termios) -> io::Result<()> {
    cfsetspeed(termios, termios::os::macos::B230400)
}

#[cfg(target_os = "freebsd")]
fn set_fastest_speed(termios: &mut Termios) -> io::Result<()> {
    cfsetspeed(termios, termios::os::freebsd::B921600)
}

#[cfg(target_os = "openbsd")]
fn set_fastest_speed(termios: &mut Termios) -> io::Result<()> {
    cfsetspeed(termios, termios::os::openbsd::B921600)
}

let mut termios = Termios::from_fd(fd).unwrap();
set_fastest_speed(&mut termios).unwrap();

Reexports

pub use os::target::{cc_t, speed_t, tcflag_t};

pub use os::target::{VEOF, VEOL, VERASE, VINTR, VKILL, VMIN, VQUIT, VSTART, VSTOP, VSUSP, VTIME};

pub use os::target::{BRKINT, ICRNL, IGNBRK, IGNCR, IGNPAR, INLCR, INPCK, ISTRIP, IXANY, IXOFF, IXON, PARMRK};

pub use os::target::{OPOST, ONLCR, OCRNL, TAB3, ONOCR, ONLRET};

pub use os::target::{B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800, B2400, B4800, B9600, B19200, B38400};

pub use os::target::{CSIZE, CS5, CS6, CS7, CS8, CSTOPB, CREAD, PARENB, PARODD, HUPCL, CLOCAL};

pub use os::target::{ECHO, ECHOE, ECHOK, ECHONL, ICANON, IEXTEN, ISIG, NOFLSH, TOSTOP};

pub use os::target::{TCSANOW, TCSADRAIN, TCSAFLUSH};

pub use os::target::{TCIFLUSH, TCIOFLUSH, TCOFLUSH, TCIOFF, TCION, TCOOFF, TCOON};

Modules

ffi	Unsafe FFI bindings.
os	OS-specific definitions.

Structs

Termios

Unix terminal I/O control structure.

Functions

cfgetispeed	Gets the input baud rate stored in a `Termios` structure.
cfgetospeed	Gets the output baud rate stored in a `Termios` structure.
cfmakeraw	Sets flags to disable all input and output processing.
cfsetispeed	Sets the input baud rate.
cfsetospeed	Sets the output baud rate.
cfsetspeed	Sets input and output baud rates.
tcdrain	Blocks until all output written to the file descriptor is transmitted.
tcflow	Suspends or restarts transmission or reception of data.
tcflush	Discards data waiting in the terminal device's buffers.
tcgetattr	Populates a `Termios` structure with parameters associated with a terminal.
tcgetsid	Returns the process group ID of the controlling terminal's session.
tcsendbreak	Transmits data to generate a break condition.
tcsetattr	Sets a terminal device's parameters.