The Terminal Is a File

Run a program in a terminal and three file descriptors are already open: 0 (stdin), 1 (stdout), 2 (stderr). Usually all three point at the same kernel object — a tty device. isatty(0) asks whether fd 0 is one:

#include <unistd.h>

if (!isatty(STDIN_FILENO)) {
    // stdin is a pipe or a file — an interactive editor can't run here.
}

The name is a fossil: tty = teletype, the electromechanical printing terminals of the 1960s. The terminal "screen" your editor will draw on is, as far as the kernel is concerned, a serial device you write(2) bytes to and read(2) bytes from. There is no "move the cursor" system call, no "key event" structure. Bytes in, bytes out. Everything a full-screen program does — vim, htop, less — is built on exactly two tricks:

• Output: certain byte sequences, when written to the terminal, are interpreted as commands (move cursor, clear line, change color) instead of text. Lesson 3 is about those.
• Input: keys arrive as bytes, and you reconfigure the tty so they arrive immediately and unmodified. That is this lesson.

Canonical mode: the line discipline is editing before you are

By default a tty is in canonical mode. The kernel's line discipline — a layer between the device and your process — buffers input until the user presses Enter, and implements its own primitive line editor: backspace erases, Ctrl-U kills the line, and only the finished line is delivered to read(). That's why a plain std::getline program feels "line based": the kernel is doing the editing, not the C++ runtime.

The line discipline also echoes every typed character back to the screen, translates carriage returns to newlines, and turns certain bytes into signals: Ctrl-C sends SIGINT, Ctrl-Z sends SIGTSTP, Ctrl-\ sends SIGQUIT. Useful defaults for a shell session; fatal for an editor. If the kernel echoes keystrokes, every j the user types to move down gets printed into your carefully painted screen. If Ctrl-C kills you, you can't bind it. An editor needs the terminal in raw mode: every byte delivered as typed, nothing echoed, nothing translated, no signals.

termios, flag by flag

The tty's configuration lives in a struct termios (POSIX, <termios.h>), read with tcgetattr(fd, &t) and written with tcsetattr(fd, TCSAFLUSH, &t). It has four flag words — input (c_iflag), output (c_oflag), control (c_cflag), local (c_lflag) — plus an array c_cc of control characters and thresholds. "Raw mode" is not a single switch (well, non-portably there is cfmakeraw); it is a specific set of flags to clear, and knowing why each one matters is knowing what the terminal actually does for you:

• ECHO (local): kernel echoes input back to the display. Off — the editor decides what appears on screen.
• ICANON (local): canonical (line-buffered) mode. Off — read() returns bytes as they are typed, not lines.
• ISIG (local): Ctrl-C → SIGINT, Ctrl-Z → SIGTSTP. Off — those bytes (0x03, 0x1A) are delivered to you like any other key, so vi-style bindings can use them.
• IXON (input): software flow control — Ctrl-S freezes output until Ctrl-Q resumes it. A gift to 1970s serial links, a trap today (everyone has "frozen" a terminal with a stray Ctrl-S). Off, so Ctrl-S is just a byte.
• IEXTEN (local): extended input processing — on many systems Ctrl-V means "quote the next character" (and on macOS Ctrl-O is swallowed). Off.
• ICRNL (input): translate carriage return (0x0D, what the Enter key actually sends) into newline (0x0A). Off — you want to see the real byte, and to tell Enter (0x0D) apart from Ctrl-J (0x0A).
• OPOST (output): output post-processing, in practice \n → \r\n translation. Off — from now on, when you want the cursor at the start of the next line you write "\r\n" yourself. (Forget this and your output staircases across the screen.)
• BRKINT, INPCK, ISTRIP (input): break-condition SIGINT, parity checking, and stripping the 8th bit. All relics of real serial hardware; all off, both for tradition and because ISTRIP would mangle UTF-8.
• CS8 (control): a two-bit field, set rather than cleared — 8-bit characters. Almost certainly already set.

Two entries of c_cc control when read() returns in non-canonical mode, and they are worth internalizing because they define your event loop's personality:

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

VMIN=1, VTIME=0 makes read() block until at least one byte arrives — a pure event-driven loop. VMIN=0, VTIME=1 makes read() return after at most 100 ms even with no input — a polling loop that gives you a natural place to handle "no key pressed" work (like noticing the window was resized, or timing out a lone ESC — a plot point in the next lesson). We'll use VMIN=0, VTIME=1.

In real code, entering raw mode looks like this — and note that we modify a copy of the original settings rather than building a termios from zero, because the struct has fields we don't understand and must not clobber:

#include <termios.h>
#include <unistd.h>

termios orig;                       // saved so we can restore at exit
void enter_raw() {
    tcgetattr(STDIN_FILENO, &orig);
    termios raw = orig;             // copy, then surgically edit
    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] = 0;
    raw.c_cc[VTIME] = 1;
    tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
}

TCSAFLUSH applies the change after pending output drains and discards unread input — so a half-typed line from before raw mode doesn't leak into the editor as phantom keystrokes.

Leaving the terminal the way you found it

Exit your editor without restoring the original termios and the user's shell inherits raw mode: nothing echoes, Enter doesn't work, and they're typing reset blind. Restoration must happen on every exit path — normal quit, early return, exception. C++ has a dedicated idiom for "must happen on every exit path": RAII (Resource Acquisition Is Initialization). Acquire in a constructor, release in the destructor, and let scope exit — however it happens — do the bookkeeping:

class RawMode {
public:
    RawMode() {
        tcgetattr(STDIN_FILENO, &orig_);
        termios raw = orig_;
        make_raw(raw);                       // this lesson's challenge
        tcsetattr(STDIN_FILENO, TCSAFLUSH, &raw);
    }
    ~RawMode() { tcsetattr(STDIN_FILENO, TCSAFLUSH, &orig_); }

    RawMode(const RawMode&) = delete;             // copying makes no sense:
    RawMode& operator=(const RawMode&) = delete;  // who restores, and when?

private:
    termios orig_;
};

int main() {
    RawMode raw;          // terminal is raw from here on
    run_editor();         // may return early, may throw
}                         // ...restored here, no matter what

A raw-mode guard is the canonical RAII example for a reason: the resource isn't memory, it's terminal state, and leaking it hurts a human immediately. Two design points worth dwelling on:

• Copying is deleted. If two RawMode objects existed, the second's constructor would save an orig_ that is already raw — restoring it would "restore" rawness. Deleting the copy operations makes the broken program not compile. This is the rule of five in action: since we wrote a destructor with side effects, we must decide what copy/move mean, and here the right answer is "they don't".
• The flip side is the rule of zero: classes that don't own a resource should define none of the five special members and let the compiler-generated ones work. Most classes you write in this course — positions, ranges, buffers built on std::string — follow the rule of zero. Only resource guards need the full ceremony.

The exit paths RAII cannot catch

Destructors run on returns and exceptions — but not on std::abort, not on _exit, and not when a signal kills the process. Two signals need explicit handling in a real editor, and both are pure terminal lore worth knowing:

• SIGTSTP / SIGCONT (Ctrl-Z suspend, fg resume): with ISIG off you won't get Ctrl-Z from the keyboard, but kill -TSTP can still arrive. The polite dance: on SIGTSTP, restore the original termios, then re-raise SIGTSTP with default disposition so the shell actually suspends you; on SIGCONT, re-enter raw mode and repaint the whole screen (the shell owned the display while you slept).
• Crash safety: register the restore with atexit, and keep signal handler paths async-signal-safe — tcsetattr and write are on the safe list; std::cout and malloc are not.

The grader has no tty (and that's a feature)

Everything above is glue you'll assemble in your own editor binary and verify by running it in a real terminal. The grader, though, runs your code headless — no tty at all — which enforces a discipline this whole course is built on: separate the OS glue from the logic, and make the logic pure. The first challenge tests your raw-mode flag surgery against a stand-in Termios struct with the same field names and (Linux) flag values as the real one — swap Termios for termios and the identical function body drops into your editor. The second distills the RAII guard into a reusable, tty-free scope guard.