Escape Sequences & Terminal Capabilities

The sequences fall into layers with very different levels of authority, and a portable program has to know which layer it is standing on.

The official documents do not provide a test that tells a program "this terminal supports hyperlinks" or "this terminal supports the Kitty keyboard protocol"; the practical techniques (environment variables, queries and terminfo extension entries) are described below and each has failure modes that are stated where they apply.

ECMA-48 divides the 8-bit code table into the C0 set (0x00 to 0x1F, among them BEL 0x07, BS 0x08, HT 0x09, LF 0x0A, CR 0x0D and ESC 0x1B), the graphic characters, and the C1 set (0x80 to 0x9F). A C1 function has a 7-bit form, an ESC followed by a byte in 0x40 to 0x5F, and that two-byte form is what programs emit.

In a UTF-8 terminal a lone 0x9B byte is not a character, and U+009B is encoded as two bytes, so the C1 controls are not reliably usable; always send the 7-bit forms. A control sequence has the shape ESC [, then optional parameter bytes (0x30 to 0x3F: digits, ;, and the private-parameter markers ?, >, <, =), then optional intermediate bytes (0x20 to 0x2F), then one final byte (0x40 to 0x7E) that selects the function. Omitted parameters take a default, usually 0 or 1, which depends on the function. A string sequence (OSC, DCS, APC) runs until ST; most terminals also accept BEL (0x07) as the end of an OSC string, which is how title sequences were traditionally written.

Two properties follow from this design and recur in every section below.

SGR, Select Graphic Rendition, is CSI Ps ; Ps ... m. Several parameters can share one sequence, and they are applied left to right. CSI m with no parameter is the same as CSI 0 m, reset.

ITU T.416 and ECMA-48 define the extended colours with colons (38:2::r:g:b); real programs overwhelmingly send the semicolon form shown above, and some emulators accept only that form. Extensions such as curly and coloured underlines (4:3, 58;2;r;g;b) exist in several emulators, but they are not part of ECMA-48 and a terminal that does not know them may render a plain underline or misparse the colon.

Coordinates are 1-based, row first. Most movement parameters default to 1.

Two warnings come with this table. A cursor that is hidden must be shown again on every exit path, including a panic, a signal and an error; a program that dies with the cursor hidden leaves the user’s shell without one. And the position CSI s and CSI u (save and restore) pair collides with DECSLRM in terminals that implement left and right margins and with the Kitty keyboard protocol, whose reports also end in u, so prefer ESC 7 and ESC 8.

Writing at the last column is a classic trap. A terminal that has written a character in the last column sets a pending wrap flag instead of moving to the next line; the next printable character then wraps. A program that computes positions assuming the cursor is already on the next line misplaces its output by one row. Emulators agree on this behaviour (it is the xenl capability in terminfo), but not on what a following cursor-movement sequence does to the pending flag, which is why full-screen programs address cells with CUP instead of relying on wrapping.

A full-screen program should not scribble over the user’s scrollback. DEC private modes 47, 1047 and 1049 switch to an alternate screen buffer that has no scrollback, and switch back on exit. Use 1049: it saves the cursor, switches buffers and clears the alternate screen on entry, and restores the cursor on exit, which is also what the terminfo smcup / rmcup capabilities do for xterm-256color.

The full-screen entry and exit order that the Bookshelf catalogue browser uses is: enter raw mode, enter the alternate screen, hide the cursor, enable bracketed paste, enable mouse and focus reporting, draw. On exit, undo everything in reverse order. Programs that are interrupted (SIGINT, SIGTERM, SIGHUP, a panic, SIGTSTP on suspend) must run the same restore code; the C and Python examples below show an atexit and try / finally shape. The signal and exit mechanics are covered on POSIX Processes, Signals & I/O.

Pitfalls: output that a program prints while on the alternate screen vanishes when the screen is left, so error messages and the final result must be printed after leaving it. Terminals reached through tmux or screen honour the same mode, and some emulators offer a setting that turns the alternate screen off, so scrolling the mouse wheel inside a full-screen program may scroll the primary buffer unless mouse reporting is enabled.

Several private modes ask the terminal to send more information on the program’s input. They are set with CSI ? Pm h and reset with CSI ? Pm l, and each one changes the bytes that arrive on standard input, so a program that enables one must be ready to parse its reports.

Redrawing a large screen as many small writes can show tearing, with half of the old frame and half of the new. Mode 2026, defined by the community document contour-terminal/vt-extensions, brackets one frame: the terminal buffers everything between the two sequences and presents it at once.

Terminals that do not know the mode ignore the sequences, so sending them unconditionally is common; checking the DECRQM reply (see the query section) avoids relying on that. A frame should stay short: terminals impose a timeout and flush the buffer if the end sequence never arrives, but the length of that timeout is an implementation choice that the specification does not fix. Because the pair costs a few bytes per frame it is sensible for full-screen redraws, not for every shelf list line. This is a community convention; it is not in ECMA-48 or in the XTerm document.

Source: contour-terminal/vt-extensions — synchronized output.

An OSC sequence is ESC ] Ps ; Pt ST, where Ps is a command number and Pt its payload. Use ST (ESC \); BEL works in most emulators but ST is the standard terminator.

Kitty defined two extensions that other emulators (among them Ghostty, WezTerm, iTerm2 and foot, at different levels of completeness) have adopted. Both are community specifications, so detect them by querying and degrade quietly.

A terminal answers some control sequences by writing a reply on its output, which arrives on the program’s input as if the user had typed it. That is how a program discovers what it is talking to without trusting TERM.

A robust probe follows three rules. First, put the terminal in raw mode (no echo, no line buffering), or the reply is echoed and shows on the screen. Second, use a timeout, because a pipe, a dumb terminal or a slow link never answers. Third, send DA1 last as a sentinel: every terminal that understands queries at all answers DA1, so when the DA1 reply arrives, any query sent before it that has not been answered is known to be unsupported. Only probe when both standard input and output are a terminal; a program run from a script, an agent or a pipeline must never block waiting for a reply.

This probe compiles under Python 3.9 and exits with the message above when it is not attached to a terminal. The replies from a live terminal were not exercised while this page was written, so the sequential three-query shape (rather than the sentinel pattern described above) is deliberately simple. A production version sends all queries followed by DA1 and parses the replies as they arrive.

Source: XTerm Control Sequences — Functions using CSI and DCS and the Python termios module.

Replies are a security boundary as well as a feature: because they arrive on standard input, text that makes a terminal emit a reply can inject keystrokes into whatever reads the terminal next. This is the reason several terminals refuse to answer title or clipboard queries, and one more reason to filter untrusted output.

TERM names the terminal’s type, and the terminfo database maps that name to a list of capabilities: booleans (am, xenl), numbers (colors, cols) and strings with parameters (cup, setaf, smcup). The older termcap format is superseded; ncurses implements both lookups from the terminfo files. A program that uses ncurses, notcurses, tput or termwiz reads terminfo; many other libraries do not read it at all and emit xterm-style sequences directly, so TERM only decides colour depth for them.

The session was captured on macOS with ncurses 6.0 tools; the capability strings are the same on current ncurses releases for these entries, though the system database is older than the 6.6 sources documented at the source link. Note that cup 5 10 is zero-based on the command line and the terminal sequence is 1-based (6;11), and that sgr0 also selects the US-ASCII character set (ESC ( B), a reset that a plain CSI 0 m does not perform.

Common values of TERM: xterm-256color (the safe default, claimed by nearly every emulator), tmux-256color or screen-256color inside a multiplexer, linux for the Linux virtual console, xterm-kitty and xterm-ghostty for those emulators, and dumb for output that must stay plain.

Pitfalls:

Source: terminfo(5) and the ncurses terminfo database.

A terminal is a grid of cells. The program must know how many cells a string takes, or it cannot align a table, truncate a title or place the cursor after a wide character. A code point occupies zero, one or two cells:

The POSIX wcwidth and wcswidth functions return the column count for a wide character or string, subject to the current locale (setlocale(LC_ALL, "") is required in C first). They deal in code points, not user-perceived characters: an accented letter written as a base letter plus a combining mark, or an emoji family joined with zero-width joiners, is several code points that form one grapheme cluster.

Compiled with Apple clang and run with LC_ALL=en_US.UTF-8 on macOS, it prints:

The first line is ASCII, the second two Chinese characters (two cells each), the third and fourth the same letter written with a combining accent and as a single code point, the fifth a books emoji, the sixth a family emoji (three emoji joined with zero-width joiners, 5 code points) and the last the ambiguous plus-minus sign. The sixth line shows the central disagreement: wcswidth sums the three emoji to 6 cells, while an emulator that renders the sequence as one family glyph uses 2. Some terminals implement a community "grapheme clustering" mode (DEC private mode 2027, documented in the same vt-extensions repository as synchronized output), and a DECRQM query (CSI ? 2027 $ p) reveals whether the terminal knows it. Python’s unicodedata.east_asian_width() returns the UAX #11 class (W for the Chinese character and the emoji, A for the plus-minus sign, Na for ASCII), and unicodedata.combining() flags combining marks, but neither produces cell widths on its own.

Source: Unicode UAX #11: East Asian Width and POSIX wcwidth.

Pitfalls for the Bookshelf tool: truncate and pad titles by cells using a width-aware library for the language in use (for example unicode-width for Rust, go-runewidth or uniseg for Go, wcwidth for Python), never by bytes or len; avoid putting emoji in table cells that must stay aligned, because the emulator’s width for the same sequence varies between versions; and never assume the width of a character the font lacks, since the terminal may draw a fallback glyph over several cells.

Windows 10 and later support the sequences above, with a smaller set than xterm, through the console virtual-terminal (VT) processing. Microsoft’s guidance is to use VT sequences for all new development instead of the classic console API, and to keep the classic calls (SetConsoleMode, SetConsoleCP, SetConsoleOutputCP, SetConsoleCtrlHandler, ReadConsoleInput for window resize) where there is no sequence equivalent. VT processing is a mode flag: a program has to switch it on for the output handle, and should switch it back on exit.

This example uses windows.h, so it was not compiled on the macOS host used to write this page; check it on a Windows toolchain. GetConsoleMode failing is the Win32 way of asking "is this a console?", the counterpart of isatty; it fails when the handle is a pipe or a file. SetConsoleOutputCP(CP_UTF8) makes the console accept UTF-8 text; a program can instead embed the activeCodePage UTF-8 manifest setting (Windows 10 version 1903 and later).

Source: Console Virtual Terminal Sequences and SetConsoleMode.

Differences to plan for:

Libraries hide this: crossterm, Bubble Tea, Textual, Terminal.Gui and others enable the flags on startup. A program written directly against sequences, such as the shelf examples above, has to do it itself.

The sequences are an input language of the terminal, so any program that writes text it did not produce itself (a book title or note read from a shared catalogue, a git commit message, a filename, an error from a remote server, the output of a subprocess, a log line) can control the user’s terminal by embedding ESC bytes. What an attacker can do with a hostile string:

Printing a byte stream raw is the problem, and the fix is the same everywhere: sanitise at the output boundary. Drop C0 controls except tab and the line terminator, drop DEL (0x7F) and the C1 range (when decoding UTF-8, U+0080 to U+009F), and consider dropping the bidirectional override characters. Replace a stripped byte with a visible placeholder if it must be noticed. Stripping only ESC leaves single-byte C1 forms and BEL-terminated strings untouched, and stripping only the [ after ESC leaves a half-written string that the terminal keeps waiting on, swallowing the output that follows.

The Bookshelf renderer used on this page does that in the C helper below and prints a hostile title as plain text:

This program was compiled with Apple clang (clang -Wall -Wextra) without warnings. Run into a pipe it prints plain text with the hostile title shown as Hostile[2JTitle, with the ESC and BEL bytes dropped, so the leftover [2J is harmless text. Run inside a pseudo-terminal with COLORTERM=truecolor it emitted exactly this byte stream (shown with the carriage returns the pseudo-terminal adds):

Spaces and line breaks above are added for readability. An unrelated limitation: the exit code path here is a normal return; a real full-screen program also restores the terminal from signal handlers and atexit, as noted in the alternate screen section. Rendering inside a live terminal emulator was not checked while this page was written.

Source: XTerm Control Sequences and POSIX mbrtowc.

Related defences apply when the consumer is a program rather than a person. The AI section covers output caps, sanitisation of tool output and the argv discipline on Security for CLIs, Output caps and sanitisation; this page adds the terminal-specific detail. Tools that show someone else’s text, such as less, usually escape control characters unless asked not to (less -R lets colour sequences through); cat -v and ls -b show them safely.