Terminal Settings with termios

Everything the line discipline does — echo, buffering, signals, translation — is configurable, per terminal device, through one struct and two functions declared in termios.h:

#include <termios.h>

struct termios t;
tcgetattr(fd, &t);              /* read the device's current settings  */
t.c_lflag &= ~ECHO;             /* flip some bits                      */
tcsetattr(fd, TCSAFLUSH, &t);   /* write them back                     */

This is the API. stty is a thin wrapper over it; so is everything vim or ssh does to a terminal. Note that both calls take an fd: the settings belong to the device, not to your process. Change them and they stay changed for everyone using that device until something changes them back — which is why "restore on exit" is a hard requirement, not a courtesy.

The struct, field by field

struct termios {
    tcflag_t c_iflag;    /* input processing:  what happens to arriving bytes */
    tcflag_t c_oflag;    /* output processing: what happens to departing bytes */
    tcflag_t c_cflag;    /* hardware-ish: baud, character size, parity */
    tcflag_t c_lflag;    /* "local": the line discipline's personality */
    cc_t     c_cc[NCCS]; /* control characters: which byte means what */
};

Each tcflag_t is a bitmask; you flip flags with the usual idioms:

t.c_lflag &= ~(ECHO | ICANON);   /* clear (disable) */
t.c_cflag |= CS8;                /* set (enable)    */

c_lflag — the big personality switches

Flag	When set (the default)	Raw mode
ICANON	line buffering + kernel line editing (Backspace, ^U)	clear
ECHO	kernel echoes input back to the display	clear
ISIG	^C→SIGINT, ^Z→SIGTSTP, ^\→SIGQUIT	clear
IEXTEN	extended input processing (^V literal-next, ^O)	clear

ICANON and ECHO are the headliners. Clearing ISIG means Ctrl+C becomes just a byte (0x03) delivered to you — your program decides what "interrupt" means. Clearing IEXTEN closes the odd loopholes.

c_iflag — input translation

Flag	When set	Raw mode
IXON	^S/^Q pause and resume output (software flow control)	clear
ICRNL	translate incoming \r (Enter) into \n	clear
BRKINT	serial "break" sends SIGINT	clear
INPCK	parity checking (serial-line era)	clear
ISTRIP	strip input bytes to 7 bits	clear

With ICRNL cleared you'll see Enter as it truly arrives: \r, byte 0x0D. Your key decoder (a few lessons from now) must know that. BRKINT, INPCK, ISTRIP are fossils of real serial hardware — clearing them is tradition and costs nothing.

c_oflag — output translation

Flag	When set	Raw mode
OPOST	enable all output processing	clear
ONLCR	(under OPOST) translate outgoing \n to \r\n	—

Clearing OPOST turns off all output massaging — most visibly ONLCR. From then on \n moves the cursor down one row without returning to column 0, staircasing your text like

first line
          second line
                     third line

That's not a bug; it's two motions you're now responsible for distinguishing. Full-screen programs don't mind — they position the cursor explicitly anyway.

c_cflag and c_cc

c_cflag matters to us only for CS8: 8-bit characters, please (yet another serial fossil — 7-bit terminals were real). In c_cc, the control-character array, two "characters" aren't characters at all but read-timing knobs — and they're important enough to get their own section.

VMIN and VTIME: how much, how long

With ICANON cleared, when does read() return? Two bytes in c_cc decide:

• VMIN — the minimum number of bytes before read may return.
• VTIME — a timeout in tenths of a second.

The four quadrants:

VMIN	VTIME	read() behavior
0	0	never blocks: returns whatever is there, possibly 0
>0	0	blocks until VMIN bytes exist (classic blocking read)
0	>0	returns on first byte OR after VTIME expires with 0
>0	>0	inter-byte timer: first byte starts the clock

VMIN=1, VTIME=0 is the sane default for interactive programs: block until there's something, deliver it immediately. VMIN=0, VTIME=1 (return within 0.1 s no matter what) is the poor-man's event loop — kilo (antirez's ~1000-line C text editor, the tutorial in this course's extended reading, and a name that will keep coming up) uses it. We'll use VMIN=1 and get our timeouts a better way, with poll(), in the next lesson.

Applying settings: the third argument

tcsetattr(fd, when, &t) — the when matters:

• TCSANOW — apply immediately, even mid-output.
• TCSADRAIN — wait for pending output to finish first. Use when changing output flags so queued text isn't garbled.
• TCSAFLUSH — drain output and discard pending unread input. The right choice when entering/leaving raw mode: keystrokes typed before the switch die instead of leaking into the new regime.

One more trap, straight from the man page: tcsetattr returns success if any requested change succeeded. Paranoid code calls tcgetattr afterwards and compares. (Our tests do exactly that to your code.)

Raw mode, assembled

Putting the whole lesson in one function — this is cfmakeraw(3) reimplemented by hand, and it's the next challenge:

raw.c_iflag &= ~(BRKINT | ICRNL | INPCK | ISTRIP | IXON);
raw.c_oflag &= ~OPOST;
raw.c_cflag |= CS8;
raw.c_lflag &= ~(ECHO | ICANON | IEXTEN | ISIG);
raw.c_cc[VMIN]  = 1;
raw.c_cc[VTIME] = 0;

And the discipline that goes with it, which every serious tool follows: save the original struct before touching anything, restore it on every exit path — normal exit, error, fatal signal. A program that dies in raw mode leaves the shell deaf and mute (reset fixes it, but users shouldn't need to know that incantation).