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

yes

GNU screen

yes

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`)