1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
# Reference: terminal windows
> Neutral description of the terminal windows Turbo Rust opens, the keys they answer to, and the escape sequences the emulator implements.
## Opening
| Route | Condition |
| --- | --- |
| `F8` | Always |
| **Window ▸ New terminal** | Always |
Neither requires a file to be open.
## The shell
| Property | Value |
| --- | --- |
| Program | `$SHELL`, or `/bin/sh` when it is unset or empty; on Windows `%COMSPEC%`, or `cmd.exe` |
| Working directory | The directory of the file in the front window; the editor's working directory when no file is open |
| `TERM` | `xterm-256color`, always — replacing any inherited value |
| Environment | The editor's own, with `TERM` replaced |
| Controlling terminal | Yes: on Linux and macOS the shell runs in its own session with the pseudo-terminal as its controlling terminal; on Windows it is attached to a pseudo-console. Either way job control and `Ctrl-C` work |
| Initial size | The window's, updated whenever the window is resized |
## Platform support
| Platform | Behaviour |
| --- | --- |
| Linux | Supported (`/dev/ptmx`) |
| macOS | Supported (`/dev/ptmx`) |
| Windows | Supported (pseudo-console, ConPTY): Windows 10 version 1809 or later. Built and vetted; **not yet run by the authors** on a Windows machine |
| Others | `F8` opens a message saying terminal windows are not supported yet; nothing else changes |
## Keys
### After the program has gone
A window whose command has finished keeps its output, but stops behaving like a terminal: only `Shift-PgUp` and `Shift-PgDn` are still taken, and every other key reaches the editor — which is what lets `Ctrl-W` close it.
### Sent to the shell
Every key not listed under "kept by the editor" below, encoded as a terminal expects it.
| Key | Bytes sent |
| --- | --- |
| printable character | its UTF-8 encoding |
| `Alt-<key>` | `ESC` followed by that key's own bytes |
| `Ctrl-A` … `Ctrl-Z` | `0x01` … `0x1a` |
| `Enter` | `\r` |
| `Tab` | `\t` |
| `Shift-Tab` | `ESC [ Z` |
| `Backspace` | `0x7f` |
| `Escape` | `0x1b` |
| `↑` `↓` `→` `←` | `ESC [ A B C D`, or `ESC O A B C D` in application cursor mode |
| `Home` `End` | `ESC [ H`, `ESC [ F`, or the `ESC O` forms in application cursor mode |
| `Insert` `Delete` | `ESC [ 2~`, `ESC [ 3~` |
| `PgUp` `PgDn` | `ESC [ 5~`, `ESC [ 6~` |
| `F1` … `F4` | `ESC O P Q R S` |
| `F5` … `F12` | `ESC [ 15~ 17~ 18~ 19~ 20~ 21~ 23~ 24~` |
A key with no terminal meaning sends nothing.
### Kept by the editor
| Key | Action |
| --- | --- |
| `F1` … `F12` | Their usual editor action |
| `Alt-X` | Exit |
| `Alt-0` … `Alt-9` | List windows / bring window 1…9 forward |
Function keys therefore never reach a program inside a terminal window.
### Handled by the terminal window itself
| Key | Action |
| --- | --- |
| `Shift-PgUp` | Back one screenful through the history |
| `Shift-PgDn` | Forward one screenful |
Any key sent to the shell also returns the view to the live screen.
## Mouse
| Action | Effect |
| --- | --- |
| Wheel up / down | Scroll three lines through the history |
| Click | Brings the window forward; not forwarded to the program |
Mouse reporting is not implemented, so a program is never told about clicks.
## History
| Property | Value |
| --- | --- |
| Lines kept | 2000 |
| What is kept | Lines scrolled off the top of the primary screen only |
| Alternate screen | Not kept — a full-screen program leaves no history behind |
## Emulation
`TERM` is `xterm-256color`. What is implemented of it:
### Control characters
| Byte | Effect |
| --- | --- |
| `0x07` BEL | Noted; the editor does not sound it |
| `0x08` BS | Cursor left one column |
| `0x09` HT | To the next tab stop, every 8 columns |
| `0x0a` `0x0b` `0x0c` | Line feed |
| `0x0d` CR | To column 1 |
### Escape sequences
| Sequence | Name | Effect |
| --- | --- | --- |
| `ESC D` | IND | Line feed |
| `ESC E` | NEL | Carriage return and line feed |
| `ESC M` | RI | Reverse line feed, keeping the column |
| `ESC 7` | DECSC | Save cursor and style |
| `ESC 8` | DECRC | Restore cursor and style |
| `ESC c` | RIS | Full reset |
### CSI sequences
| Sequence | Name | Effect |
| --- | --- | --- |
| `CSI n A B C D` | CUU CUD CUF CUB | Move n cells up, down, right, left |
| `CSI n E F` | CNL CPL | n lines down / up, to column 1 |
| `CSI n G` | CHA | To column n |
| `CSI r ; c H`, `CSI r ; c f` | CUP HVP | To row r, column c |
| `CSI n d` | VPA | To row n |
| `CSI n J` | ED | Erase display: 0 to end, 1 to start, 2 or 3 all |
| `CSI n K` | EL | Erase line: 0 to end, 1 to start, 2 all |
| `CSI n L` | IL | Insert n blank lines at the cursor |
| `CSI n M` | DL | Delete n lines at the cursor |
| `CSI n @` | ICH | Insert n blank cells |
| `CSI n P` | DCH | Delete n cells |
| `CSI n X` | ECH | Erase n cells in place |
| `CSI n S` | SU | Scroll the region up n lines |
| `CSI n T` | SD | Scroll the region down n lines |
| `CSI t ; b r` | DECSTBM | Set the scroll region to rows t…b |
| `CSI s`, `CSI u` | SCP RCP | Save / restore the cursor |
| `CSI … m` | SGR | Colours and attributes, below |
`IL` and `DL` do nothing when the cursor is outside the scroll region.
### Private modes
Set with `CSI ? n h`, cleared with `CSI ? n l`.
| n | Name | Effect |
| --- | --- | --- |
| 1 | DECCKM | Application cursor keys: arrows send `ESC O x` |
| 7 | DECAWM | Auto-wrap at the right margin |
| 25 | DECTCEM | Show the cursor |
| 47, 1047 | | Alternate screen |
| 1048 | | Save / restore the cursor |
| 1049 | | Save the cursor, then the alternate screen |
Any other mode is parsed and ignored.
### SGR
| Code | Effect |
| --- | --- |
| 0 | Reset |
| 1, 22 | Bold on / off |
| 2, 22 | Dim on / off |
| 3, 23 | Italic on / off |
| 4, 24 | Underline on / off |
| 5, 6, 25 | Blink on / off |
| 7, 27 | Reverse on / off |
| 9, 29 | Strike-through on / off |
| 30–37, 40–47 | The eight normal colours, foreground / background |
| 90–97, 100–107 | The eight bright colours, foreground / background |
| 38;5;n, 48;5;n | Palette colour n of 256 |
| 38;2;r;g;b, 48;2;r;g;b | 24-bit colour |
| 39, 49 | Back to the theme's colour |
The sixteen named colours are tcell's, which means the palette the user's own terminal is configured with, not fixed hex values. An extended colour that runs out of parameters partway leaves the style unchanged. Any other code is ignored.
### OSC
| Sequence | Effect |
| --- | --- |
| `OSC 0 ; text BEL`, `OSC 2 ; text BEL` | Set the window title |
| `OSC … ST` | The `ESC \` terminator is accepted in place of BEL |
The title is capped at 4096 bytes. Other OSC commands are parsed and ignored.
### Consumed and ignored
Parsed correctly, so they never appear as stray characters, but with no effect:
| Sequence | Name |
| --- | --- |
| `ESC P …`, `ESC X …`, `ESC ^ …`, `ESC _ …` | DCS, SOS, PM, APC — read to their string terminator |
| `ESC (`, `ESC )`, `ESC *`, `ESC +`, `ESC %`, `ESC #`, `ESC <space>` | Character-set and line-size selectors — the emulator works in UTF-8 regardless |
| `CSI ? n h`, `CSI ? n l` for any other n | Private modes not listed above |
| Any other CSI final byte, SGR code, or OSC command | |
### Not implemented
Mouse reporting, bracketed paste, shift-in / shift-out, double-width lines, sixel and other graphics protocols, and the DEC status and device-attribute reports. A program that asks for one of these gets no reply, so a program that waits for one waits forever.
## Colours
| Theme key | What it colours |
| --- | --- |
| `terminal.text` | Every cell whose colour the program did not choose |
| `terminal.cursor` | The cell under the cursor, when the window has the focus |
See [Theme file format](themes.md).
## Errors
| Message | Cause |
| --- | --- |
| Terminal windows are not supported on this platform yet | The build has no pseudo-terminal support: any platform other than Linux, macOS and Windows |
| `openpt: …`, `grantpt: …`, `ptsname: …` | The operating system refused to open a pseudo-terminal |
| `fork/exec …: no such file or directory` | `$SHELL` names a program that does not exist |
## See also
- [How to run shell commands without leaving the editor](../how-to/use-a-terminal.md)
- [Terminal windows](../explanation/terminal-windows.md)
- [Keyboard](keyboard.md)
|