Skip to content
This repository has been archived by the owner on Sep 1, 2023. It is now read-only.

Latest commit

 

History

History
1116 lines (946 loc) · 63.2 KB

ControlSequences.md

File metadata and controls

1116 lines (946 loc) · 63.2 KB
Raw

[TOC]

hterm Control Sequences

Like every terminal out there, hterm supports a number of standard (and perhaps not so standard) control/escape sequences. This doc outlines hterm's position on everything -- things that are supported, things that will never be supported, etc...

It's not meant to be a comprehensive guide to a terminal. For that, please see the References section.

Parsing of these sequences are contained entirely in hterm_vt.js, and the character maps are defined in hterm_vt_character_map.js.

For TBD entries, it means we haven't put in the work to implement the feature yet, but we generally wouldn't be adverse to adding it. Or we haven't quite figured out how best to do so. Or we just haven't thought about it at all to say no :).

Similarly for entries marked as passed thru -- we might do something with them in the future, but currently we just print it.

However, for entries marked "won't support", it means we don't consider them relevant and will probably never be implemented.

If you come across missing features or have other requests, feel free to file a bug at https://goo.gl/vb94JY.

General Guidelines

We aim to be compliant with:

  • ECMA-35 (Character Code Structure and Extension Techniques): covers some fundamentals related to character sets, the notions of C0, C1, G0, etc... (but not their contents), and how escape sequences work (but not what they mean). This is equivalent to ISO/IEC 2022.
  • ECMA-43 (8-bit Coded Character Set Structure and Rules): Builds on top of ECMA-35 by defining the character sets (e.g. 0x40 == @). This is equivalent to ISO/IEC 4873.
  • ECMA-48 (Control Functions for Coded Character Sets): Builds on top of ECMA-35 by defining many of the common escape sequences. Supersedes the ANSI codes, and is equivalent to ISO/IEC 6429.
  • ISO/IEC 8613-6 (Character content architectures): Builds on top of ECMA-35 by defining fonts and graphic renditions (e.g. SGR). This is equivalent to ITU T.416.

Going beyond those basics, we use these sites for guidance:

  • XTerm: Canonical terminal emulator in the X world.
  • VT100.net: Spec sheets for VT100 and similar terminals.

C0 Control Codes {#C0}

These are the basic characters in the 0x00 - 0x1F range.

While DEL (0x7F) isn't actually part of C0, we list it here for convenience.

Seq Dec Hex Name C Description Action
^@ 00 00 NUL \0 Null Ignored
^A 01 01 SOH Start of Heading Passed thru
^B 02 02 STX Start of Text Passed thru
^C 03 03 ETX End of Text Passed thru
^D 04 04 EOT End of Transmission Passed thru
^E 05 05 ENQ Enquiry Ignored
^F 06 06 ACK Acknowledge Passed thru
^G 07 07 BEL \a Bell Supported
^H 08 08 BS \b Backspace Supported
^I 09 09 HT \t Character Tabulation (Horizontal Tabulation) Supported
^J 10 0A LF \n Line Feed Supported
^K 11 0B VT \v Line Tabulation (Vertical Tabulation) Converted to LF (\n)
^L 12 0C FF \f Form Feed Converted to LF (\n)
^M 13 0D CR \r Carriage Return Supported
^N 14 0E SO/LS1 Shift Out / Locking Shift One Point GL to G1
^O 15 0F SI/LS0 Shift In / Locking Shift Zero Point GL to G0
^P 16 10 DLE Data Link Escape Passed thru
^Q 17 11 DC1 Device Control One (XON) Ignored (TBD)
^R 18 12 DC2 Device Control Two Passed thru
^S 19 13 DC3 Device Control Three (XOFF) Ignored (TBD)
^T 20 14 DC4 Device Control Four Passed thru
^U 21 15 NAK Negative Acknowledge Passed thru
^V 22 16 SYN Synchronous Idle Passed thru
^W 23 17 ETB End of Transmission Block Passed thru
^X 24 18 CAN Cancel Supported (1)
^Y 25 19 EM End of medium Passed thru
^Z 26 1A SUB Substitute Converted to CAN
^[ 27 1B ESC \e Escape Supported (2)
^\ 28 1C FS/IS4 File Separator / Information Separator Four Passed thru
^] 29 1D GS/IS3 Group Separator / Information Separator Three Passed thru
^^ 30 1E RS/IS2 Record Separator / Information Separator Two Passed thru
^_ 31 1F US/IS1 Unit Separator / Information Separator One Passed thru
^? 127 7F DEL Delete Supported

{#C0-footer}

  1. Used to cancel escape sequences, and to change GL back to G0.
  2. ESC is a multiplexed command; see section below for more details.

C1 Control Codes {#C1}

These are some extended characters in the 0x80 - 0x9F range.

Since these don't play well with UTF-8 encoding, they're typically accessed via an escape sequence. e.g. ESC+@ (0x1b 0x40) instead of 0x80.

ESC Dec Hex Name Description Action
@ 128 80 PAD Padding Character Ignored (TBD)
A 129 81 HOP High Octet Preset Ignored (TBD)
B 130 82 BPH Break Permitted Here Ignored (TBD)
C 131 83 NBH No Break Here Ignored (TBD)
D 132 84 IND Index Like newline, but keep column position
E 133 85 NEL Next Line Like newline, but doesn't add a line
F 134 86 SSA Start of Selected Area Won't support
G 135 87 ESA End of Selected Area Ignored (TBD)
H 136 88 HTS Character Tabulation Set Sets horizontal tab stop at the column
I 137 89 HTJ Character Tabulation With Justification Ignored (TBD)
J 138 8A VTS Line Tabulation Set Ignored (TBD)
K 139 8B PLD Partial Line Forward Ignored (TBD)
L 140 8C PLU Partial Line Backward Ignored (TBD)
M 141 8D RI Reverse Line Feed Move up one line keeping column position
N 142 8E SS2 Single-Shift Two Ignored
O 143 8F SS3 Single-Shift Three Ignored
P 144 90 DCS Device Control String Ignored (TBD) (1)
Q 145 91 PU1 Private Use One Ignored (TBD)
R 146 92 PU2 Private Use Two Ignored (TBD)
S 147 93 STS Set Transmit State Ignored (TBD)
T 148 94 CCH Cancel character Ignored (TBD)
U 149 95 MW Message Waiting Ignored (TBD)
V 150 96 SPA Start of Guarded Area Won't support
W 151 97 EPA End of Guarded Area Won't support
X 152 98 SOS Start of String Won't support
Y 153 99 SGCI Single Graphic Character Introducer Ignored (TBD)
Z 154 9A SCI Single Character Introducer Sends [?1;2c
[ 155 9B CSI Control Sequence Introducer Supported (2)
\ 156 9C ST String Terminator Used to terminate escape sequences
] 157 9D OSC Operating System Command Supported (3)
^ 158 9E PM Privacy Message Won't support
_ 159 9F APC Application Program Command Won't support

{#C1-footer}

  1. DCS is a multiplexed command; see section below for more details.
  2. CSI is a multiplexed command; see section below for more details.
  3. OSC is a multiplexed command; see section below for more details.

G0/G1/G2/G3 Graphic Codesets for GL/GR (SCS) {#SCS}

***note Support for character maps may be disabled at runtime via DOCS.

With the rise of UTF-8 encoding, graphic codesets have fallen out of favor. Although we still support a limited number for legacy systems.

Basically, instead of seeing things like "w" or "#", you'll see "┬" or "£". These were used to get basic graphics (like border lines), or to support other 7-bit character sets (like German characters ß and ü).

The terminal has 4 graphic codeset slots (named G0, G1, G2, and G3), and 2 pointers (GL and GR) to those slots. The active display then uses those pointers to determine what is shown. Both the slots and pointers can be updated at any time.

The GR pointer, while tracked, does not actually get processed. When running in a UTF8 environment, it's easy to corrupt codeunits in a codepoint leading to bad output.

We don't currently differentiate between 94-character sets and 96-character sets. Although all of the maps we support are within the 94-char range.

As for the character sets that you can actually load, we support some hard character sets, but not all of them. We do not support soft character sets.

Here's the list of national replacement character sets (NRCS) we support:

ID Description
0 Graphics
4 Dutch
5 Finnish
6 Norwegian/Danish
7 Swedish
= Swiss
A British
B United States (ASCII)
C Finnish (same as "5" above)
E Norwegian/Danish (same as "6" above)
H Swedish (same as "7" above)
K German
Q French Canadian
R French
Y Italian
Z Spanish

Designate Other Coding System (DOCS) {#DOCS}

ECMA-35 supports changing the encoding system of terminal. Since hterm is natively UTF-8, we use this to control support for character maps (see SCS for more details).

This escape sequence has a one or two byte form. If the first byte is /, then it is a one way transition. i.e. Any further attempts to change the encoding will simply be ignored. This is useful for putting the terminal into UTF-8 mode permanently and not worrying about binary data switching character maps to graphics mode.

To invoke these, use ESC+%+DOCS. e.g. ESC+%/G (0x1b 0x25 0x2f 0x47).

Any sequence not documented below is simply ignored. The only two byte sequence supported currently is where the first byte is /.

DOCS Description Character Maps (SCS)
@ Switch to ECMA-35 encoding (default) Supported
G Switch to UTF-8 encoding Supported
/G Permanently switch to UTF-8 encoding Level 1 Treated as /I
/H Permanently switch to UTF-8 encoding Level 2 Treated as /I
/I Permanently switch to UTF-8 encoding Level 3 Supported

Escape Sequences {#ESC}

These are other escape sequences we support. This is similar to the C1 Control Codes space, but there is only a two byte sequence. e.g. ESC+# (0x1b 0x23).

Some of these may have subcommands, so it might end up being a three byte sequence where the 3rd byte is further interpreted. We refer to that as arg1 in the Action column below.

ESC Name Description Action
␠ SP Ignored (TBD)
! Ignored (TBD)
" Ignored (TBD)
# DEC Semi-supported
$ Ignored (TBD)
% DOCS Designate Other Coding System Supported
& Ignored (TBD)
' Ignored (TBD)
( SCS Set G0 character set (VT100) Set G0 to NRCS arg1
) SCS Set G1 character set (VT220) Set G1 to NRCS arg1
* SCS Set G2 character set (VT220) Set G2 to NRCS arg1
+ SCS Set G3 character set (VT220) Set G3 to NRCS arg1
, Ignored (TBD)
- SCS Set G1 character set (VT300) Set G1 to NRCS arg1
. SCS Set G2 character set (VT300) Set G2 to NRCS arg1
/ SCS Set G3 character set (VT300) Set G3 to NRCS arg1
0 Ignored (TBD)
1 Ignored (TBD)
2 Ignored (TBD)
3 Ignored (TBD)
4 Ignored (TBD)
5 Ignored (TBD)
6 DECBI Back Index Ignored (TBD)
7 DECSC Save Cursor Supported
8 DECRC Restore Cursor Supported
9 DECFI Forward Index Ignored (TBD)
: Ignored (TBD)
; Ignored (TBD)
< Ignored (TBD)
= DECKPAM Keypad Application Mode Supported
> DECKPNM Keypad Numeric Mode Supported
? Ignored (TBD)
@ See C1 Control Codes
A See C1 Control Codes
B See C1 Control Codes
C See C1 Control Codes
D See C1 Control Codes
E See C1 Control Codes
F See C1 Control Codes
G See C1 Control Codes
H See C1 Control Codes
I See C1 Control Codes
J See C1 Control Codes
K See C1 Control Codes
L See C1 Control Codes
M See C1 Control Codes
N See C1 Control Codes
O See C1 Control Codes
P See C1 Control Codes
Q See C1 Control Codes
R See C1 Control Codes
S See C1 Control Codes
T See C1 Control Codes
U See C1 Control Codes
V See C1 Control Codes
W See C1 Control Codes
X See C1 Control Codes
Y See C1 Control Codes
Z See C1 Control Codes
[ See C1 Control Codes
\ See C1 Control Codes
] See C1 Control Codes
^ See C1 Control Codes
_ See C1 Control Codes
` DMI Disable Manual Input Ignored (TBD)
a INT Interrupt Ignored (TBD)
b EMI Enable Manual Input Ignored (TBD)
c RIS Reset to Initial State Resets terminal state
d CMD Coding Method Delimiter Ignored (TBD)
e Ignored (TBD)
f Ignored (TBD)
g Ignored (TBD)
h Ignored (TBD)
i Ignored (TBD)
j Ignored (TBD)
k Ignored (TBD)
l Memory lock/unlock Won't support
m Memory lock/unlock Won't support
n LS2 Locking Shift Two Point GL to G2
o LS3 Locking Shift Three Point GL to G3
p Ignored (TBD)
q Ignored (TBD)
r Ignored (TBD)
s Ignored (TBD)
t Ignored (TBD)
u Ignored (TBD)
v Ignored (TBD)
w Ignored (TBD)
x Ignored (TBD)
y Ignored (TBD)
z Ignored (TBD)
{ Ignored (TBD)
| LS3R Locking Shift Three Right Ignored (Point GR to G3)
} LS2R Locking Shift Two Right Ignored (Point GR to G2)
~ LS1R Locking Shift One Right Ignored (Point GR to G1)

ESC+# (DEC) {#DEC}

A few random escape sequences. They are initiated with ESC+#.

Num Name Description Action
3 DECDHL Double-Width, Double-Height Line (Top Half) Ignored
4 DECDHL Double-Width, Double-Height Line (Bottom Half) Ignored
5 DECSWL Single-Width, Single-Height Line Ignored
6 DECDWL Double-Width, Single-Height Line Ignored
8 DECALN Screen Alignment Pattern Fill terminal with E's

Device Control String (DCS) {#DCS}

Device Control String is not currently supported which means none of its subcommands work either (like ReGIS or Sixel).

Operating System Command (OSC) {#OSC}

This is a grab bag of various escape sequences. They are initiated with ESC+]. Arguments to the sequences are typically delimited by ;, and terminated with BEL. e.g. ESC+] 0 ; title BEL (0x1b 0x5d 0x30 0x3b ... 0x07).

For example:

OSC Description Status Format
0 Set window title & icon name Only window title ESC ] 0 ; [title] \a
1 Change icon name Ignored ESC ] 1 ; [icon] \a
2 Set window title Converted to 0 ESC ] 2 ; [title] \a
3 Set X property Ignored
4 Set/read color palette Supported ESC ] 4 ; index1;rgb1;...;indexN;rgbN \a
5 Change special color number Ignored
6 Enable special color number Ignored
6 Set current file path Ignored
7 Set current directory Ignored ESC ] 7 ; directory \a
8 Set hyperlink Supported ESC ] 8 ; id=foo ; uri \a text ESC ] 8 ;; \a
9 iTerm2 Growl notifications Supported ESC ] 9 ; [message] \a
10 Set foreground color Supported ESC ] 10 ; [X11 color spec] \a
11 Set background color Supported ESC ] 11 ; [X11 color spec] \a
12 Set text cursor color Supported ESC ] 12 ; [X11 color spec] \a
13 Set mouse foreground color Ignored ESC ] 13 ; [X11 color spec] \a
14 Set mouse background color Ignored ESC ] 14 ; [X11 color spec] \a
15 Set Tektronix foreground color Ignored ESC ] 15 ; [X11 color spec] \a
16 Set Tektronix background color Ignored ESC ] 16 ; [X11 color spec] \a
17 Set highlight background color Ignored ESC ] 17 ; [X11 color spec] \a
18 Set Tektronix cursor color Ignored ESC ] 18 ; [X11 color spec] \a
19 Set highlight foreground color Ignored ESC ] 19 ; [X11 color spec] \a
46 Set logfile path Ignored ESC ] 46 ; path \a
50 Change font number/name Ignored ESC ] 50 ; [number
50 Set the cursor shape Supported ESC ] 50 ; CursorShape=[0|1|2] \a
51 Reserved for Emacs Ignored
52 Clipboard operations Only "c" supported ESC ] 52 ; c ; [base64 data] \a
104 Reset color number Supported ESC ] 104 ; index1;...;indexN \a
105 Reset special color number Ignored
106 Enable special color number Ignored
110 Reset foreground color Supported ESC ] 110 ; \a
111 Reset background color Supported ESC ] 111 ; \a
112 Reset text cursor color Supported ESC ] 112 ; \a
113 Reset mouse foreground color Ignored ESC ] 113 ; \a
114 Reset mouse background color Ignored ESC ] 114 ; \a
115 Reset Tektronix foreground color Ignored ESC ] 115 ; \a
116 Reset Tektronix background color Ignored ESC ] 116 ; \a
117 Reset highlight background color Ignored ESC ] 117 ; \a
118 Reset Tektronix cursor color Ignored ESC ] 118 ; \a
119 Reset highlight foreground color Ignored ESC ] 119 ; \a
777 rxvt-unicode (urxvt) modules Only "notify" supported ESC ] 777 ; notify ; [title] ; [body] \a
1337 iTerm2 sequences Only "File" supported ESC ] 1337 ; File = [args] : [base64 data] \a

OSC+1337: iTerm2 sequences {#OSC-1337}

The iTerm2 terminal for macOS provides a lot of proprietary options via the OSC 1337 command. Many of them duplicate other standard sequences, so most of them aren't supported.

We support media display and file transfers. This is specified via the File= keyword. None of the options below are required as a reasonable default will be selected automatically.

***note There is a helper script you can use to handle the protocol for you.

***note Warning: You should avoid transferring larger files as Chrome performance will suffer. If it's under 2 MB, it probably will be fine, but YMMV.

The overall form looks like ESC+] 1337 ; File=name=[base64];inline=1 : [base64 data] BEL.

  • name: The base64 encoded name of the file or other human readable text.
  • size: How many bytes in the base64 data (for transfer progress).
  • width: The display width specification (see below). Defaults to auto.
  • height: The display height specification (see below). Defaults to auto.
  • preserveAspectRatio: If 0, scale/stretch the display to fit the space. If 1 (the default), fill the display as much as possible without stretching.
  • inline: If 0 (the default), download the file instead of displaying it. If 1, display the file in the terminal.
  • align: Set the display alignment with left (the default), right, or center.
  • type: Set the MIME type of the content. Auto-detected otherwise.

For the base64 encoded fields, make sure to omit whitespace (e.g. newlines) if using a tool like base64.

For the width & height fields, a number of forms are accepted. Note that the terminal will probably restrict the maximum size automatically to the active terminal dimensions. e.g. If the terminal is 1000 pixels wide, specifying a width greater than that will automatically be limited to 1000 pixels.

  • N: How many cells (e.g. rows or columns) to fill.
  • Npx: How many pixels to fill.
  • N%: A percentage of the overall terminal screen.
  • auto: Use the file's dimension.

For inline display, currently only images in formats Chrome itself understands are supported.

Control Sequence Introducer (CSI) {#CSI}

These are various color and cursor related escape sequences. Also referred to as ANSI escape sequences. They are initiated with ESC+[. Arguments to the sequences are typically delimited by ; and precede the command. e.g. ESC+[ arg1 ; arg2 ; argN m.

The final command is a single character in the range 0x40 (@) through 0x7F (~). That's a limited space, so the command can be further refined with characters immediately following the ESC+[ bytes. Those may be in the range 0x20 (␠) through 0x3F (?), excluding the range 0x30 (0) through 0x39 (9) and 0x3A (:) and 0x3B (;). e.g. The CSI command ?$p command below takes the form ESC+[ ? $ arg1 ; arg2 ; argN p.

CSI Name Description Action
@ ICH Insert Blank Characters Add space
A CUU Cursor Up Move cursor up arg1 rows
B CUD Cursor Down Move cursor down arg1 rows
C CUF Cursor Forward Move cursor forward arg1 columns
D CUB Cursor Backward Move cursor back arg1 columns
E CNL Cursor Next Line Move cursor down arg1 rows and to first column
F CPL Cursor Preceding Line Move cursor up arg1 rows and to first column
G CHA Cursor Horizontal Absolute Move cursor to arg1 column
H CUP Cursor Position Move cursor to arg1 row and arg2 column
I CHT Cursor Forward Tabulation Move cursor forward arg1 tabs
J ED Erase in Display !arg1 or arg1 == 0: Clear cursor to end of display
arg1 == 1: Clear start of display to cursor
arg1 == 2: Clear display
arg1 == 3: Clear scrollback
?J DECSED Selective Erase in Display Same as ED above
K EL Erase in Line !arg1 or arg1 == 0: Clear cursor to end of line
arg1 == 1: Clear start of line to cursor
arg1 == 2: Clear line
?K DECSEL Selective Erase in Line Same as EL above
L IL Insert Lines Insert arg1 lines
M DL Delete Lines Delete arg1 lines
N EF Erase in Field Ignored (TBD)
O EA Erase in Area Ignored (TBD)
P DCH Delete Characters Delete arg1 characters before cursor
Q SEE Select Editing Extent Ignored (TBD)
R CPR Active Position Report Ignored (TBD)
S SU Scroll Up Scroll up arg1 lines
T SD Scroll Down Scroll down arg1 lines
>T Won't support
U NP Next Page Ignored (TBD)
V PP Previous Page Ignored (TBD)
W CTC Cursor Tabulation Control Ignored (TBD)
X ECH Erase Characters Delete arg1 characters after cursor
Y CVT Cursor Line Tabulation Ignored (TBD)
Z CBT Cursor Backward Tabulation Move cursor back arg1 tabs
[ SRS Start Reversed String Ignored (TBD)
\ PTX Parallel Texts Ignored (TBD); See Ruby character
] SDS Start Directed String Ignored (TBD)
^ SIMD Select Implicit Movement Direction Ignored (TBD)
_ Ignored (TBD)
` HPA Character Position Absolute Same as CHA above
a HPR Character Position Relative Move cursor forward arg1 columns
b REP Repeat Ignored (TBD)
c DA/DA1 Send Primary Device Attributes Currently reports "VT100 with Advanced Video Option"
>c DA2 Send Secondary Device Attributes Currently reports "VT100"
d VPA Line Position Absolute Move cursor to arg1 row
e VPR Line Position Forward Ignored (TBD)
f HVP Horizontal and Vertical Position Same as CUP above
g TBC Tab Clear !arg1 or arg1 == 0: Clear tab stop at cursor
arg1 == 3: Clear all tab stops
h SM Set Mode Supported (1)
?h DECSET DEC Set Mode Supported (2)
i MC Media Copy Won't support
?i DECMC DEC Media Copy Won't support
j HPB Character Position Backward Ignored (TBD)
k VPB Line Position Backward Ignored (TBD)
l RM Reset Mode Supported (1)
?l DECRST DEC Mode Reset Supported (2)
m SGR Select Graphic Rendition Supported (3)
>m xterm specific keyboard modes Won't support
n DSR Device Status Reports Supported
?n DECDSR DEC Device Status Reports Supported
>n xterm specific modifiers Won't support
o DAQ Define Area Qualification Ignored (TBD)
p Ignored (TBD)
>p xterm specific cursor display control Ignored (TBD)
!p DECSTR Soft Terminal Reset Supported
$p DECRQM Request Mode - Host To Terminal Ignored (TBD)
?$p DECRQM Request Mode - Host To Terminal Ignored (TBD)
"p DECSCL Select Conformance Level Ignored (TBD)
q DECLL Load LEDs Ignored (TBD)
␠q DECSCUSR Set Cursor Style Supported
"q DECSCA Select Character Protection Attribute Won't support
r DECSTBM Set Top and Bottom Margins Supported
?r Restore DEC Private Mode Values Won't support
$r DECCARA Change Attributes in Rectangular Area Won't support
s Save cursor (ANSI.SYS) Supported
?s Save DEC Private Mode Values Won't support
t Window manipulation Won't support
$t DECRARA Reverse Attributes in Rectangular Area Won't support
>t Set one or more features of the title modes Won't support
␠t DECSWBV Set Warning Bell Volume Won't support
u Restore cursor (ANSI.SYS) Supported
␠u DECSMBV Set Margin Bell Volume Won't support
v Ignored (TBD)
$v DECCRA Copy Rectangular Area Won't support
w Ignored (TBD)
'w DECEFR Enable Filter Rectangle Won't support
x DECREQTPARM Request Terminal Parameters Ignored (TBD)
*x DECSACE Select Attribute Change Extent Won't support
$x DECFRA Fill Rectangular Area Won't support
y Ignored (TBD)
z vt_tiledata Tile data Semi-Supported
'z DECELR Enable Locator Reporting Ignored (TBD)
$z DECERA Erase Rectangular Area Won't support
{ Ignored (TBD)
'{ DECSLE Select Locator Events Ignored (TBD)
| Ignored (TBD)
'| DECRQLP Request Locator Position Ignored (TBD)
} Ignored (TBD)
'} DECIC Insert Column Won't support
~ Ignored (TBD)
'~ DECDC Delete Column Won't support

{#CSI-footer}

  1. SM/RM are multiplexed commands; see section below for more details.
  2. DECSET/DECRST are multiplexed commands; see section below for more details.
  3. SGR is a multiplexed command; see section below for more details.

Modes (SM) / (RM) {#SM}

Ignoring the use of the generic word "mode", the Set Mode and Reset Mode commands are used to control different operating modes. Historically these made sense with a wide range of hardware devices that used different binary protocols, but nowadays we can ignore most as dead code. That is why hterm doesn't support most of these.

For SM, the specified mode is enabled. For RM, it's disabled (reset).

Mode Name Description Action
1 GATM Guarded Area Transfer Mode Won't support
2 KAM Keyboard Action Mode Won't support
3 CRM Control Representation Mode Ignored
4 IRM Insertion Replacement Mode Supported
5 SRTM Status Report Transfer Mode Ignored
6 ERM ERasure mode Ignored
7 VEM Line Editing Mode Ignored
8 BDSM Bi-Directional Support Mode Ignored
9 DCSM Device Component Select Mode Ignored
10 HEM Character Editing Mode Ignored
11 PUM Positioning Unit Mode Ignored
12 SRM Send/Receive Mode Won't support
13 FEAM Format Effector Action Mode Ignored
14 FETM Format Effector Transfer Mode Ignored
15 MATM Multiple Area Transfer Mode Ignored
16 TTM Transfer Termination Mode Ignored
17 SATM Selected Area Transfer Mode Ignored
18 TSM Tabulation Stop Mode Ignored
19 Reserved Ignored
20 LNM Automatic Newline Supported
21 GRCM Graphic Rendition Combination Mode Ignored
22 ZDM Zero Default Mode Ignored

Private Modes (DECSET) / (DECRST) {#DECSET}

Similar to the SM & RM commands, these are extensions that DEC added to their VT's. Then other people started adding their own. There are many, and we support some of them.

Mode Name Source Description Status
1 DECCKM DEC Application Cursor Keys Supported
2 DECANM DEC Designate USASCII for character sets G0-G3, and set VT100 mode Ignored (TBD)
3 DECCOLM DEC 132 Column Mode Supported
4 DECSCLM DEC Smooth (Slow) Scroll Won't support
5 DECSCNM DEC Reverse Video Supported
6 DECOM DEC Origin Mode Supported
7 DECAWM DEC Wraparound Mode Supported
8 DECARM DEC Auto-repeat Keys Won't support
9 X10 MOUSE X Send Mouse X & Y on button press Supported
10 rxvt Show toolbar Won't support
12 att610 Start blinking cursor Supported
18 DECPFF DEC Print form feed Ignored (TBD)
19 DECPEX DEC Set print extent to full screen Won't support
25 DECTCEM DEC Show Cursor Supported
30 rxvt Show scrollbar Supported
35 rxvt Enable font-shifting functions Won't support
38 DECTEK DEC Enter Tektronix Mode Won't support
40 Allow 80 - 132 (DECCOLM) Mode Supported
41 curses more(1) fix Ignored (TBD)
42 DECNRCM DEC Enable Nation Replacement Character sets Ignored (TBD)
44 Turn On Margin Bell Ignored (TBD)
45 Reverse-wraparound Mode Supported
46 Start Logging Ignored (TBD)
47 Use Alternate Screen Buffer Supported
66 DECNKM DEC Application keypad Ignored (TBD)
67 DECBKM DEC Backarrow key sends backspace Supported
1000 MOUSE_REPORT_CLICK X Send Mouse X & Y on button press and release Supported
1001 Use Hilite Mouse Tracking Ignored (TBD)
1002 MOUSE_REPORT_DRAG Use Cell Motion Mouse Tracking Supported
1003 Use All Motion Mouse Tracking Ignored (TBD)
1004 Send FocusIn/FocusOut events Supported
1005 Enable Extended Mouse Mode (UTF-8) Supported
1006 Enable Extended Mouse Mode (SGR) Supported
1007 xterm Enable Alternate Scroll Mode Supported
1010 rxvt Scroll to bottom on tty output Supported
1011 rxvt Scroll to bottom on key press Supported
1015 rxvt Enable Extended Mouse Mode (urxvt) Won't support
1034 Interpret "meta" key, sets eighth bit Won't support
1035 Enable special modifiers for Alt and NumLock keys Won't support
1036 Send ESC when Meta modifies a key Supported
1037 Send DEL from the editing-keypad Delete key Ignored (TBD)
1039 Send ESC when Alt modifies a key Supported
1040 Keep selection even if not highlighted Won't support
1041 Use the CLIPBOARD selection Won't support
1042 Enable Urgency window manager hint when Ctrl+G is received Ignored (TBD)
1043 Enable raising of the window when Ctrl+G is received Ignored (TBD)
1047 Use Alternate Screen Buffer Supported
1048 Save cursor as in DECSC Supported
1049 Combine 1047 and 1048 modes and clear Supported
1050 Set terminfo/termcap function-key mode Ignored (TBD)
1051 Set Sun function-key mode Won't support
1052 Set HP function-key mode Won't support
1053 Set SCO function-key mode Won't support
1060 Set legacy keyboard emulation (X11R6) Won't support
1061 Set VT220 keyboard emulation Ignored (TBD)
2004 Set bracketed paste mode Supported

Mouse Reporting / Tracking

These are the sequences that the terminal generates based on mouse events the user themselves create. The terminal sends them to the remote so the application can handle mouse inputs. These could be things as simple as clicking different mouse buttons in different terminal rows/cols, or more complicated things like click & drag, or wheel scrolling.

There are a few different mouse reporting modes in the wild. Here we document all the modes that hterm currently supports. It's unlikely we'll support more modes unless they offer significant functionality over the existing modes.

Some of the modes seem to overlap, but they can largely be broken down into two different aspects: what is reported (presses/drags/etc...) and how is the message encoded. The terminal first calculates the values to report (via the reporting mode), then the values are encoded before being sent to the remote.

By default, no mouse reporting is enabled, so all mouse events are handled by the native implementation (e.g. for copying content or clicking links). If mouse reporting is enabled, it by default uses the X10 encoding.

If you want to enable mouse reporting, you should always use the SGR encoding. For reporting modes, most people want to start with the xterm extensions (so they get mouse press & release events, wheel scrolls, and keyboard modifiers).

Reporting Modes

Only mouse buttons 1 (primary aka left), 2 (secondary aka right), 3 (middle), 4 (wheel up), and 5 (wheel down) can be reported. All other buttons are ignored.

X10

This is the simplest and oldest mode: only mouse button presses are reported; no releases, and no motion/drags. It is enabled via DECSET 9.

The mouse button is the button number minus 1.

X11 / xterm

Reporting is extended to support mouse button releases and keyboard modifiers. It is enabled via DECSET 1000.

The mouse button status is in the bottom two bits. Only SGR supports reporting which mouse button was released (see the SGR encoding section below for more details).

  • 0: Mouse button 1 is pressed.
  • 1: Mouse button 2 is pressed.
  • 2: Mouse button 3 is pressed.
  • 3: The mouse button was released.

The keyboard modifiers are encoded in bits 2, 3, and 4. They indicate which keyboard keys were held down. There is no way to detect keyboard presses/releases directly.

  • bit 2: The shift key.
  • bit 3: The meta key.
  • bit 4: The control key.
Cell / Button Event Tracking

Reporting is extended to support motion events while buttons are held down. It is enabled via DECSET 1002.

Motion Event Tracking

Reporting is extended to support motion events regardless of button state. It is enabled via DECSET 1003.

This is not currently supported as most programs do not use it or care. It can end up transmitting a lot of data when the mouse is constantly moved.

Encoding Modes

If you're unsure which encoding to select, then use SGR.

X10

***note In >=hterm-1.85, we limit to 95 rows and columns due to encoding limitations.

There is a limit of 223 rows and columns due to the protocol encoding: they made sure that each byte of data was printable, so 32 was added (which is the first printable ASCII character). There is also an 8-bit encoding limit, so 255 is the largest value.

This is the default encoding if no other selection has been made. You should really use SGR instead though.

The encoding takes the form of CSI M Cb Cx Cy where:

  • Each value has 32 added to it.
  • Cb is the button & keyboard modifiers.
  • Cx is the column (between 0 and 223).
  • Cy is the row (between 0 and 223).
UTF-8 (Extended)

This is like the X10 form, but since we can assume UTF-8 encoding, the row and column limit is increased to 2047. The values still had 32 added to them. Hence it is often referred to as "UTF-8" or "extended" encoding modes.

It is enabled via DECSET 1005.

The encoding takes the form of CSI M Cb Cx Cy where:

  • Each field is encoded in UTF-8.
  • Each value has 32 added to it.
  • Cb is the button & keyboard modifiers.
  • Cx is the column (between 0 and 2047).
  • Cy is the row (between 0 and 2047).
SGR

This is the preferred encoding format as there are no row or column limits.

This can easily be confused with the Select Graphic Rendition (SGR) naming, but that's no coincidence: they use similar encoding formats with semi-colon delimited numbers.

Since the value is always printable (by virtue of being a number), there is no need to add 32 to each value.

It is enabled via DECSET 1006.

The encoding takes the form of CSI < Cb ; Cx ; Cy M when a button is pressed, and CSI < Cb ; Cx ; Cy m when a button is released, where:

  • Each field is encoded as an ASCII integer.
  • Cb is the button & keyboard modifiers.
  • Cx is the column.
  • Cy is the row.
urxvt

The only other notable encoding at this time is urxvt's, but since its encoding is ambiguous with other CSI sequences, we won't support it. The SGR encoding supports everything that urxvt tried to do too.

It is enabled via DECSET 1015.

Wheel Mice

Since the mouse reporting can only handle 3 buttons normally, wheel up (button 4) is encoded as mouse button 1 with 64 added to it. Wheel down (button 5) is mouse button 2 with 64 added to it.

No release events are generated.

Wheel mice events are always enabled when mouse reporting is active.

Alternate Scroll Mode

Instead of generating mouse events, the mouse wheel can be configured to emit up/down/left/right arrow key presses instead. This is useful when working with applications that don't understand mouse reporting, but do handle arrow keys fine.

This mode is only active when the alternate screen is enabled. Otherwise, the mouse wheel is used to control local buffer scrolling.

It is enabled via DECSET 1007.

Select Graphic Rendition (SGR) {#SGR}

These are various color and cursor related escape sequences. Also referred to as ANSI escape sequences. They are initiated with ESC+[ and finish with the m command. Accepts an arbitrary number of args delimited by ; and in any order.

SGR Character Attribute Action
Enable Attributes
0 Normal (default) Supported
1 Bold (increased intensity) Supported
2 Faint (decreased intensity) Supported
3 Italic Supported
4 Underlined Supported (2)
5 Blink (slowly) Supported
6 Rapid blink Ignored (TBD)
7 Inverse (negative image) Supported
8 Invisible Supported
9 Crossed out Supported
10 Primary font Ignored
11 First alternative font Ignored
12 Second alternative font Ignored
13 Third alternative font Ignored
14 Fourth alternative font Ignored
15 Fifth alternative font Ignored
16 Sixth alternative font Ignored
17 Seventh alternative font Ignored
18 Eighth alternative font Ignored
19 Ninth alternative font Ignored
20 Reserved Ignored (TBD)
21 Double underlined Supported
Disable Attributes
22 Normal (decorations) Supported
23 Not italic Supported
24 Not underlined Supported
25 Steady (not blink) Supported
26 Variable spacing Ignored (TBD)
27 Positive image (not inverse) Supported
28 Visible (not invisible) Supported
29 Not crossed out Supported
Foreground Color
30 Set foreground color to Black Supported
31 Set foreground color to Red Supported
32 Set foreground color to Green Supported
33 Set foreground color to Yellow Supported
34 Set foreground color to Blue Supported
35 Set foreground color to Magenta Supported
36 Set foreground color to Cyan Supported
37 Set foreground color to White Supported
38 Set foreground color to extended color Supported (1)
39 Set foreground color to default (original) Supported
Background Color
40 Set background color to Black Supported
41 Set background color to Red Supported
42 Set background color to Green Supported
43 Set background color to Yellow Supported
44 Set background color to Blue Supported
45 Set background color to Magenta Supported
46 Set background color to Cyan Supported
47 Set background color to White Supported
48 Set background color to extended color Supported (1)
49 Set background color to default (original) Supported
Misc
50 Not variable spacing Ignored (TBD)
51 Framed Ignored (TBD)
52 Encircled Ignored (TBD)
53 Overlined Ignored (TBD)
54 Not framed and not encircled Ignored (TBD)
55 Not overlined Ignored (TBD)
56 Reserved Ignored (TBD)
57 Reserved Ignored (TBD)
58 Set underline color to extended color Supported (1)
59 Set underline color to default (original) Supported
60 Ideogram underline or right side line Ignored (TBD)
61 Ideogram double underline or double right side line Ignored (TBD)
62 Ideogram overline or left side line Ignored (TBD)
63 Ideogram double overline or double left side line Ignored (TBD)
64 Ideogram stress marking Ignored (TBD)
65 Cancel SGR 60 through 64 Ignored (TBD)
Bright Foreground Color
90 Set foreground color to bright Black Supported
91 Set foreground color to bright Red Supported
92 Set foreground color to bright Green Supported
93 Set foreground color to bright Yellow Supported
94 Set foreground color to bright Blue Supported
95 Set foreground color to bright Magenta Supported
96 Set foreground color to bright Cyan Supported
97 Set foreground color to bright White Supported
Bright Background Color
100 Set background color to bright Black Supported
101 Set background color to bright Red Supported
102 Set background color to bright Green Supported
103 Set background color to bright Yellow Supported
104 Set background color to bright Blue Supported
105 Set background color to bright Magenta Supported
106 Set background color to bright Cyan Supported
107 Set background color to bright White Supported

Note that most terminals consider "bold" to be "bold and bright". In some documents the bold state is even referred to as bright. We interpret bold as bold-bright here too, but only when the "bold" setting comes before the color selection.

Underlining {#SGR-underline}

In addition to the standard underline sequences, we support some non-standard sequences to enable more styles and coloring. We'll cover the non-standard sequences here only.

  • 4:0: Turn off underlining (same as SGR+24).
  • 4:1: Underline with a single solid line (same as the normal 4).
  • 4:2: Underline with double lines (same as SGR+21).
  • 4:3: Underline with a single wavy/curvy line.
  • 4:4: Underline with a single dotted line.
  • 4:5: Underline with a single dashed line.

In addition to the style, you can change the color by using SGR+58 (which uses the same syntax as SGR+38/SGR+48, and clear the color by using SGR+59 (which uses the same syntax as SGR+39/SGR+49).

SGR+38/SGR+48: Extended Colors {#SGR-extended-color}

These color sequences support both the ISO/IEC 8613-6 form (i.e. colon delimited) and, because of wide legacy usage, some xterm specific forms (i.e. semi-colon delimited). It's likely that other emulators do not support the ISO/IEC 8613-6 forms fully.

There are multiple extended color choices available.

  • 0: Implementation defined. We ignore it.
  • 1: Transparent color.
  • 2: RGB color (a.k.a. true color or 24-bit color).
  • 3: CMY color. We don't support it yet.
  • 4: CMYK color. We don't support it yet.
  • 5: Select color by palette index (a.k.a. 8-bit or 88-color or 256-color).

Implementation & Transparent Colors

For 0 and 1, we require the ISO/IEC 8613-6 form.

  • 38 : 0 -- Do nothing to the foreground!
  • 48 : 0 -- Do nothing to the background!
  • 38 : 1 -- Make the foreground transparent.
  • 48 : 1 -- Make the background transparent.

RGB/True/24-bit Colors

For RGB colors, the ISO/IEC 8613-6 forms apply. The 2nd argument is left blank as it is the color space identifier which we ignore. We also ignore the trailing tolerance and color space arguments.

  • 38 : 2 : : R : G : B -- Set foreground color to rgb(R, G, B).
  • 48 : 2 : : R : G : B -- Set background color to rgb(R, G, B).

We also support the legacy xterm forms for compatibility.

  • 38 ; 2 ; R ; G ; B -- Only RGB is specified, and uses semi-colons.
  • 48 ; 2 ; R ; G ; B -- Same as above.
  • 38 : 2 : R : G : B -- Only RGB is specified using colons.
  • 48 : 2 : R : G : B -- Same as above.

We do not support the mixed xterm form as no one else seems to either, or has actively decided to drop support for it.

  • 38 ; 2 : R : G : B -- Mixes semi-colon & colon arguments.
  • 48 ; 2 : R : G : B -- Same as above.

CMY/CMYK Colors

***note CMY is not yet supported.

For CMY and CMYK colors, we require the ISO/IEC 8613-6 form. The 2nd argument is left blank as it is the color space identifier which we ignore. We also ignore the trailing tolerance and color space arguments.

  • 38 : 3 : : C : M : Y -- Set foreground color to CMY color.
  • 48 : 3 : : C : M : Y -- Set background color to CMY color.
  • 38 : 4 : : C : M : Y : K -- Set foreground color to CMYK color.
  • 48 : 4 : : C : M : Y : K -- Set background color to CMYK color.

Palette/8-bit/88/256 Colors

For palette based colors (8-bit/88-colors/256-colors), the ISO/IEC 8613-6 forms apply.

  • 38 : 5 : P -- Set foreground color using a palette index.
  • 48 : 5 : P -- Set background color using a palette index.

We also support the legacy xterm forms for compatibility.

  • 38 ; 5 ; P -- Uses semi-colons instead of colons.
  • 48 ; 5 ; P -- Same as above.

We do not support the mixed xterm form as no one else seems to either, or has actively decided to drop support for it.

  • 38 ; 5 : P -- Mixes semi-colon & colon arguments.
  • 48 ; 5 : P -- Same as above.

References