DECRQCRA / DECCKSR — Request Checksum of Rectangular Area (`CSI Pi;Pg;Pt;Pl;Pb;Pr*y`)

Byte forms

Every common string-literal form so you can paste-and-search either direction.

Description

**DECRQCRA** (*Request Checksum of Rectangular Area*, `\x1b[<Pi>;<Pg>;<Pt>;<Pl>;<Pb>;<Pr>*y`) makes the terminal compute a 16-bit checksum over the characters + attributes of every cell inside the bounding rectangle, then return it as a four-digit uppercase hex value inside a DCS **DECCKSR** frame: `\x1bP<Pi>!~<HHHH>\x1b\\`. This is the **xterm vttest** conformance pin — every screen-painting feature (DECCRA, DECFRA, DECERA, ED, EL, scroll, line-wrap, SGR-pen carry, alt-screen swap) gets validated by 'paint, then DECRQCRA, then assert the checksum equals the recorded golden value'. Konsole's `tests/vt-tests`, mlterm's regression suite, and PowerShell ConPTY's TerminalEcho test all lean on it. **Parameters** - `Pi` — request ID (0–65535). Echoed back verbatim in the reply's `!~<Pi>` slot so a host pipelining multiple checksum requests can demux replies. - `Pg` — page number (1-based; `0` or omitted treated as `1`). Almost always `1` since modern emulators don't expose multi-page memory. - `Pt;Pl;Pb;Pr` — bounding rectangle (top, left, bottom, right; 1-based, inclusive). All four required; omission → entire page. **Checksum algorithm** — xterm 's reference implementation: start at `0`, for each cell in reading order subtract `cell_char_code + sgr_attr_bits` (treating attributes as a tagged bitfield: bold = 0x80, underline = 0x40, blink = 0x20, reverse = 0x10, etc.). The result modulo 0x10000 is the reported value. **Both the algorithm AND the SGR-bit mapping vary between emulators** — never compare checksums across two different terminal implementations; only golden-value vs same-emulator-version comparisons are valid. **Reply** — `\x1bP<Pi>!~<HHHH>\x1b\\`. The `!~` intermediate-final pair distinguishes DECCKSR from other DCS replies (DECRQSS's `$r`, DECRPTAB's `$u`, DECRPSS's `!u`). `<HHHH>` is exactly 4 uppercase hex digits, zero-padded. Example for an all-blank rectangle on a fresh xterm: `\x1bP0!~0000\x1b\\`. Example after `printf '\x1b[31mABC\x1b[0m'` at top-left and probing the first cell: `\x1bP0!~01A1\x1b\\` (xterm 392; the value drifts across versions, hence the golden-per-version pin). **Edge cases** - Coordinates out of page → silently clipped (no error reply). - Empty rectangle (`Pt > Pb` or `Pl > Pr`) → reply with checksum `0000`. - Some emulators (older Konsole, certain xterm builds) negate the checksum before reporting (one-complement) — match against your golden, not against an abstract formula. - Reply uses `\x1b\\` (ST as ESC + backslash) by default; xterm in 8-bit C1 mode (`decscl-compat-level`) uses single-byte `\x9c`. **Coverage** — **xterm** = full (reference). **mlterm** + **Konsole** + **WezTerm** = full. **Ghostty** = partial (emits a reply but checksum value diverges from xterm's by ≥ 1 bit per attribute change — treat as 'replies present, algorithm different'). **Kitty** + **iTerm2** = partial (some builds reply, some swallow). **Alacritty** / **Linux console** / **Windows Terminal** / **cmd / ConPTY** / **macOS Terminal** / **gnome-terminal** = no-op (no reply at all — be sure to time out probes at ~100 ms).

Spec citation: DEC VT510 RM (DECRQCRA / DECCKSR) / xterm-ctlseqs (CSI Pi;Pg;Pt;Pl;Pb;Pr * y)

Parameters

Examples

# Probe top-left cell on the main screen, parse the DCS reply.\nprintf '\\033[7;1;1;1;1;1*y'\nIFS= read -rs -d '\\\\' -t 0.1 reply </dev/tty 2>/dev/null\necho \"DECCKSR: ${reply}\"   # expect: \\x1bP7!~XXXX\\x1b

import sys, re\n# Parse a DECCKSR reply, extract Pi + hex checksum.\nreply = '\\x1bP42!~01A1\\x1b\\\\'\nm = re.search(r'\\x1bP(\\d+)!~([0-9A-F]{4})\\x1b\\\\', reply)\nif m:\n    pi, chk = int(m.group(1)), int(m.group(2), 16)\n    print(f'request {pi} checksum 0x{chk:04X}')

// Pipeline three checksum probes with distinct Pi.\nfor i, rect := range [][4]int{{1,1,1,1},{1,1,1,80},{1,1,24,80}} {\n    pi := i + 1\n    fmt.Printf(\"\\x1b[%d;1;%d;%d;%d;%d*y\", pi, rect[0], rect[1], rect[2], rect[3])\n}\n// Demux replies by !~<Pi> matching to issued Pi.

// vttest-style: paint, checksum, assert against golden.\nasync function checksum(rect) {\n  process.stdout.write(`\\x1b[1;1;${rect.t};${rect.l};${rect.b};${rect.r}*y`);\n  for await (const buf of process.stdin) {\n    const m = /\\x1bP1!~([0-9A-F]{4})\\x1b\\\\/.exec(buf.toString('binary'));\n    if (m) return parseInt(m[1], 16);\n  }\n}

/* Skeleton: emit probe, read until ST, parse Pi + 4 hex digits. */\nprintf(\"\\x1b[1;1;1;1;1;1*y\"); fflush(stdout);\n/* read until 0x1b 0x5c with 100ms select timeout, then sscanf(\"\\x1bP%d!~%4x\\x1b\\\\\", ...). */

Terminal support

xterm

yes

Linux console (fbcon)

no

macOS Terminal.app

no

iTerm2

partial

Windows Terminal

no

cmd.exe / ConPTY

no

kitty

partial

alacritty

no

WezTerm

yes

Ghostty

partial

GNOME Terminal

no

Konsole

yes

tmux

no

GNU screen

no

Related sequences

• DECCRA / DECFRA / DECERA / DECSERA — Copy / Fill / Erase / Selective-erase rectangular area
• DECSACE — Select Attribute Change Extent (`CSI Ps * x`)
• DECRQSS — Request Selection or Setting (DCS $ q ... ST)
• DECTABSR — Tab Stop Report (`CSI 2 $ w`)