termios Cheat Sheet

Everything about the line discipline on one page.

struct termios {
    tcflag_t c_iflag;      /* input modes   */
    tcflag_t c_oflag;      /* output modes  */
    tcflag_t c_cflag;      /* control modes — mostly vestigial on a PTY */
    tcflag_t c_lflag;      /* "local" modes — the interesting ones */
    cc_t     c_cc[NCCS];   /* control characters */
};

One termios per PTY pair, reachable from either fd. Setting it on the master changes what the child experiences — almost always a bug.

c_lflag — Local Modes

TOSTOP off by default is why background jobs can scribble over your prompt. stty tostop changes it.

c_iflag — Input Modes

c_oflag — Output Modes

Clearing OPOST is what makes raw-mode output stair-step. Print \r\n yourself.

c_cc[] — Control Characters

VMIN/VTIME share storage with VEOF/VEOL on many systems, which is why they only have meaning when ICANON is off.

The four VMIN/VTIME combinations

VMIN=1, VTIME=0 is what you want. cfmakeraw() does not set them; forgetting causes a 100%-CPU spin returning 0 bytes.

What cfmakeraw() Does

t.c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP | INLCR | IGNCR | ICRNL | IXON);
t.c_oflag &= ~OPOST;
t.c_lflag &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN);
t.c_cflag &= ~(CSIZE | PARENB);
t.c_cflag |= CS8;
/* It does NOT set VMIN/VTIME. You must: */
t.c_cc[VMIN]  = 1;
t.c_cc[VTIME] = 0;

Note: "Raw mode" is a set of changes, not a flag. Many programs want something in between — bash's readline clears ICANON and ECHO but leaves ISIG on, so ^C still interrupts.

Applying Changes

tcgetattr(fd, &t);
tcsetattr(fd, TCSANOW,   &t);   /* immediately */
tcsetattr(fd, TCSADRAIN, &t);   /* after pending output drains */
tcsetattr(fd, TCSAFLUSH, &t);   /* drain output, DISCARD pending input, then apply */

Use TCSAFLUSH when entering raw mode, or input typed before the switch is reinterpreted under the new rules and you get a phantom byte.

tcsetattr returns success if it changed any requested setting, not all of them. To be certain, tcgetattr afterwards and compare.

The stty Equivalents

When a raw-mode program dies without restoring: type stty sane blind and press Enter — or Ctrl+J if Enter does not work, because ICRNL is off. You will need this.

Canonical vs. Raw at a Glance

The Rust Guard

#![allow(unused)]
fn main() {
/// Restores on Drop — including during a panic unwind.
pub struct RawMode { fd: i32, original: libc::termios }

impl RawMode {
    pub fn enable(fd: i32) -> io::Result<Self> {
        // MaybeUninit, not mem::zeroed(): a zeroed termios is not a valid one,
        // and constructing an invalid value is UB even if you overwrite it.
        let mut original = MaybeUninit::<libc::termios>::uninit();
        if unsafe { libc::tcgetattr(fd, original.as_mut_ptr()) } != 0 {
            return Err(io::Error::last_os_error());
        }
        let original = unsafe { original.assume_init() };
        let mut raw = original;
        unsafe { libc::cfmakeraw(&mut raw) };
        raw.c_cc[libc::VMIN] = 1;    // cfmakeraw does NOT set these
        raw.c_cc[libc::VTIME] = 0;
        if unsafe { libc::tcsetattr(fd, libc::TCSAFLUSH, &raw) } != 0 {
            return Err(io::Error::last_os_error());
        }
        Ok(RawMode { fd, original })
    }
}

impl Drop for RawMode {
    fn drop(&mut self) {
        // Drop must not panic; there is nothing useful to do on failure.
        unsafe { libc::tcsetattr(self.fd, libc::TCSAFLUSH, &self.original) };
    }
}
}

Every exit path

Common Mistakes

See also: termios & the Line Discipline · Glossary