CTerm

CTerm is the ANSI parsing code maintained as part of ciolib (and used by SyncTERM). This page is basically a pretty version of the cterm.txt file in git, as of 72305c4cfe7afe31064422694beac53a9fe8e5f3

The text file is still the normative reference, but this may serve as a friendlier source.

The cursor is moved to the first character of the next line as soon as a character is written to the last column of the current line, not on the next character. A tab will wrap to the next line only if the current cursor position is the last character on the line. This behavior is often surprising to people who are used to VT emulators which implement the LCF as documented in STD-070, who expect the cursor to “stick” in the last column until the next character is received.

There are two settable flags that will impact the default behaviour.

CSI ? 7 l will disable wrapping at the end of line completely, and any characters written to the last column will not move the cursor at all, overwriting the existing charater. Default behaviour can be restored with CSI ? 7 h.

If the CSI = 4 h sequence is received, CTerm will enable LCF mode as documented in STD-070, and CSI = 4 l will restore default behaviour. CSI = 5 h will set LCF mode and disable CSI = 4 l, as well as cause LCF to remain enabled across an ESC c (RIS).

Specifically, the LCF will be set when displaying a printable character advances the cursor to the right margin, and cleared by any of the following being received: CSI ? 6 h, CSI ? 6 l, CSI ? 7 l, CSI @, CSI A, CSI B, CSI a, CSI j, CSI H, CSI f, CSI I, CSI Y, CSI J, CSI K, CSI P, CSI X, CSI r, ESC E, ESC M, CR, LF, BS, TAB, Any normal printable character when the cursor is at the right margin (of the screen or scrollable area).

Control codes are in the following format: ESC {'0' (ZERO) to '~'} Legal combinations which are not handled are silently dropped.

Sequence: CTerm:Font:p1:<b64>
Indicates the string is a loadable font. (CTerm 1.213)

p1 is a font slot number, which must be higher than the last default defined font (See CSI sp D for list of predefined fonts). <b64> is the base64 encoded font data. Font size is deduced from the size of the data. This replaces the now deprecated CSI = Ps1 ; Ps2 {

Sequence: [ p1 [ ; p2 ] ] q
Defaults: p1 = 0 p2 = 0
Indicates the string is a sixel sequence.

p1 selects the vertical height of a single pixel. This may be overridden by the raster attributes command, and is deprecated.

Supported values

p2 indicates if unset sixels should be set to the current background colour. If p2 is 1, positions specified as 0 remain at their current colour.

Any additional parameters are ignored.

The rest of the string is made up of sixel data characters and sixel control functions. Sixel data characters are in the rage of '?' (0x3f) to '~' (0x7e). Each sixel data character represents six vertical pixels. The data is extracted by subtracting 0x3f from the ASCII value of the character. The least significant bit is the topmost pixel.

Sequence: $ q pt
pt is the intermediate and/or final characters of a control function to query the status of. The terminal will send a response in the format DCS p1 $ r pt ST

p1 is 1 if the terminal supports querying the control function and 0 if it does not.

pt is the characters in the control function except the CSI characters.

Currently supported values of p1:

Sequence: p1 [ ; p2 [ ; p3 ] ! z
Defaults: p2 = 0 p3 = 0
Sets a macro to be replayed using CSI Pn * z

p1 is the macro number to set, and make be between 0 and 63 inclusive.

If p2 is zero, the macro numbered p1 will be deleted. If p2 is one, all macros are deleted.

If p3 is zero, the macro is defined using ASCII characters (0x20 - 0x7e and 0xa0 - 0xff only) if p3 is one, the macro is defined using hex pairs.

When the macro is defined using hex pairs, a repeat sequence may be included in the format of ! Pn ; D..D ;. Pn specifies the number of repeats (default of one instance) D..D is the sequence of pairs to send Pn times. The terminating ; may be left out if the sequence to be repeated ends at the end of the string.

Sequence: 4;(pX;pY)...
Specifies one or more palette redefinitions. pX is the palette index, and pY is the colour definition Color format: rgb:R/G/B Where R, G, and B are a sequence of one to four hex digits representing the value of the red, green, and blue channels respectively. xterm

SyncTERM implements the following APS commands:

Sequence: APS SyncTERM:C;S Ps1 Ps2 ST
Where Ps1 is a filename and Ps2 is the base64 encoded contents of the file. The named file is stored in the cache directory for the current connection.

Sequence: APS SyncTERM:C;L Ps ST
List files in cache. SyncTERM responds with an APS string with lines separated by newlines. The first line is always “SyncTERM:C;L\n” and for each matching file, a line in the form <Filename> TAB <MD5 sum> LF is sent (ie: “coolfont.fnt\t595f44fec1e92a71d3e9e77456ba80d1\n”)

And additional argument can be specified as a glob(3) pattern (defaults to “*”) in APS SyncTERM:C;L;Ps ST.

Sequence: APS SyncTERM:C;SetFont Pn Ps
Where Pn is a font slot number (max 255) and Ps is a filename in the cache. This sets font slot Pn to use the specified font file.

Sequence: APS SyncTERM:C;DrawPPM Ps... Ps2
Draws a PPM from the cache directory on the screen. Ps2 is the filename and is required. Arguments for Ps are optional. The following options can be included (separated by semi-colons):

The PPM file may be raw (preferred) or text. SyncTERM does not support more than 255 values per colour channel and assumes it is correctly using the BT.709 gamma transfer.

Sequence: APS SyncTERM:C;LoadPPM Ps... Ps0
Loads a PPM to a buffer. Ps0 is the filename

Sequence: APS SyncTERM:C;LoadPBM Ps... Ps0
Loads a PBM to a buffer. Ps0 is the filename

Sequence: APS SyncTERM:P;Copy Ps...
Copies a portion of the screen into an internal buffer for use with the Paste function. Defaults to copying the entire screen.

Sequence: APS SyncTERM:P,Paste Ps...
Pastes from the copied buffer. Supports the same options as the Cache DrawPPM command except for the filename, and adds the B= option.

Control sequences are in the following format: CSI {'0' (ZERO) to '?'}{SPACE to '/'}{'@' to '~'} There may be multiple characters from the {'0' (ZERO) to '?'} and {SPACE to '/'} before the terminating {'@' to '~'} character.

Legal combinations not handled are silently dropped. Illegal combinations are displayed.

Parameters are expressed by the {'0' (ZERO) to '?'} character set. Sequences which use parameters use decimal parameters separated by a ';'. The use of a ':' from the set is reserved. If the parameter string begins with '<', '=', '>', or '?' then this is a non-standard extension to the ANSI spec.

If a default is defined, the parameter is optional

Sequence: CSI Pn @
Defaults: Pn = 1
Moves text from the current position to the right edge Pn characters to the right, with rightmost characters going off-screen and the resulting hole being filled with the current attribute. ECMA-48

Sequence: CSI Pn SP @
Defaults: Pn = 1
Shifts the contents of the screen left Pn columns(s) with leftmost columns going off-screen and the resulting hole being filled with the current attribute. ECMA-48

Sequence: CSI Pn A
Defaults: Pn = 1
Moves the cursor position up Pn lines from the current position. Attempting to move past the screen boundaries stops the cursor at the screen boundary. ECMA-48

Sequence: CSI Pn SP A
Defaults: Pn = 1
Shifts the contents of the screen right Pn columns(s) with rightmost columns going off-screen and the resulting hole being filled with the current attribute. ECMA-48

Sequence: CSI Pn B
Defaults: Pn = 1
Moves the cursor position down Pn lines from the current position. Attempting to move past the screen boundaries stops the cursor at the screen boundary. ECMA-48

Sequence: CSI Pn C
Defaults: Pn = 1
Moves the cursor position right Pn columns from the current position. Attempting to move past the screen boundaries stops the cursor at the screen boundary. ECMA-48

Sequence: CSI Pn D
Defaults: Pn = 1
Moves the cursor position left Pn columns from the current position. Attempting to move past the screen boundaries stops the cursor at the screen boundary. ECMA-48

Sequence: CSI Ps1 ; Ps2 SP D
Defaults: Ps1 = 0, Ps2 = 0
Sets font Ps1 to be the one indicated by Ps2. Currently four fonts are supported. Ps2 must be between 0 and 255. Not all output types support font selection. Only X11 and SDL currently do.

Supported Ps1 values:

Currently included fonts are:

Not all fonts are supported in all modes. If a font is not supported in the current mode, no action is taken, but there should be a non-zero 'Font Selection result' value in the Font State Report. ECMA-48

Sequence: CSI Pn E
Defaults: Pn = 1
Moves the cursor to the first column of the line Pn down from the current position. Attempting to move past the screen boundaries stops the cursor at the screen boundary. ECMA-48

Sequence: CSI Pn F
Defaults: Pn = 1
Moves the cursor to the first column of the row Pn up from the current position. Attempting to move past the screen boundaries stops the cursor at the screen boundary. ECMA-48

Sequence: CSI Pn G
Defaults: Pn = 1
Movies the cursor to column Pn of the current row. ECMA-48

Sequence: CSI Pn1 ; Pn2 H
Defaults: Pn = 1, Pn2 = 1
Moves the cursor to the Pn2th column of the Pn1th line. ECMA-48

Sequence: CSI Pn I
Defaults: Pn = 1
Move the cursor to the Pn-th next tab stop. Basically the same as sending TAB Pn times. ECMA-48

Sequence: CSI Ps J
Defaults: Ps = 0
Erases from the current screen according to the value of Ps

Erased characters are set to the current attribute. ECMA-48

Sequence: CSI Ps K
Defaults: Ps = 0
Erases from the current line according to the value pf Ps

Erased characters are set to the current attribute.

Sequence: CSI Pn L
Defaults: Pn = 1
Inserts Pn lines at the current line position. The current line and those after it are scrolled down and the new empty lines are filled with the current attribute. If the cursor is not currently inside the scrolling margins, has no effect. ECMA-48

Sequence: CSI Pn M
Defaults: Pn = 1
Deletes the current line and the Pn - 1 lines after it scrolling the first non-deleted line up to the current line and filling the newly empty lines at the end of the screen with the current attribute. If the cursor is not currently inside the scrolling margins, has no effect. If “ANSI” Music is fully enabled (CSI = 2 M), performs “ANSI” music instead. See “ANSI” MUSIC section for more details. ECMA-48, BANSI

Sequence: CSI = Ps M
Defaults: Ps = 0
Sets the current state of ANSI music parsing.

Sequence: CSI N
If “ANSI” Music is set to BananaCom (CSI = 1 M) or fully enabled (CSI = 2 M) performs “ANSI” music. See “ANSI” MUSIC section for more details. BANSI

Sequence: CSI Ps P
Defaults: Pn = 1
Deletes the character at the current position by shifting all characters from the current column + p1 left to the current column. Opened blanks at the end of the line are filled with the current attribute. If the cursor is not currently inside the scrolling margins, has no effect. ECMA-48

Sequence: CSI Ps S
Defaults: Pn = 1
Scrolls the screen up Pn lines. New lines emptied at the bottom are filled with the current attribute. ECMA-48

Sequence: CSI ? Ps1 ; Ps2 S
Defaults: None
If Ps1 is 2, and Ps2 is 1, replies with the graphics screen information in the following format: CSI ? 2 ; 0 ; Px ; Py S Where Px is the width of the screen in pixels and Py is the height. XTERM

Sequence: CSI Pn T
Defaults: Pn = 1
Scrolls all text on the screen down Pn lines. New lines emptied at the top are filled with the current attribute. ECMA-48

Sequence: CSI Pn X
Defaults: Pn = 1
Erase p1 characters starting at the current character. Will not erase past the end of line. Erased characters are set to the current attribute. This can erase across scroll margins. ECMA-48

Sequence: CSI Pn Y
Defaults: Pn = 1
Move the cursor to the Pn-th next tab stop. Basically the same as sending TAB Pn times. ECMA-48

Sequence: CSI Pn Z
Defaults: Pn = 1
Move the cursor to the p1th preceding tab stop. Will not go past the start of the line. ECMA-48

Sequence: CSI Pn `
Defaults: Pn = 1
Move the cursor to the specified position on the current row. Will not go past the end of the line. ECMA-48

Sequence: CSI Pn a
Defaults: Pn = 1
Moves the cursor position forward Pn columns from the current position. Attempting to move past the screen boundaries stops the cursor at the screen boundary. ECMA-48

Sequence: CSI Pn b
Defaults: Pn = 1
Repeats the previous graphic character Pn times. Will not repeat escape sequences. ECMA-48

Sequence: CSI Ps c
Defaults: Ps = 0
If Ps is 0, CTerm will reply with the sequence: CSI = 67;84;101;114;109;pN c. 67;84;101;114;109 is the ASCII values of the “CTerm” string. pN is the revision ID of CTerm with dots converted to semi-colons (e.g. “1;156”). Use the revision to detect if a specific feature is available. If you are adding features to a forked version of cterm, please do so by adding an extra parameter to the end, not by incrementing any existing one! ECMA-48

Sequence: CSI < Ps c
Defaults: Ps = 0
If Pn is 0, CTerm will reply with the sequence: CSI < 0 ; Ps... c

Possible values for Ps:

Sequence: CSI Pn d
Defaults: Ps = 1
Moves to row specified by Pn. ECMA-48

Sequence: CSI Pn SP d
Defaults: None
Removes a tab stop at postion Pn. ECMA-48

Sequence: CSI Pn e
Defaults: Pn = 1
Moves forward Pn rows. ECMA-48

Sequence: CSI Pn1 ; Pn2 f
Defaults: Pn1 = 1, Pn2 = 1
Moves the cursor to the Pn2th column of the Pn1th line. ECMA-48

Sequence: CSI Ps g
Defaults: Ps = 0
Deletes tab stops according to the values of Ps:

ECMA-48

Sequence: CSI = Ps... h
Defaults: None
Sets the mode specified by Ps

Sequence: CSI ? Ps... h
Defaults: None
Sets one or more mode. The following modes are supported:

Sequence: CSI Pn j
Defaults: Pn = 1
Moves the cursor position left Pn columns from the current position. Attempting to move past the screen boundaries stops the cursor at the screen boundary. ECMA-48

Sequence: CSI Pn k
Defaults: Pn = 1
Moves the cursor position up Pn lines from the current position. Attempting to move past the screen boundaries stops the cursor at the screen boundary.

Sequence: CSI = Ps... l
Defaults: None
Resets the mode specified by Ps

• ANSI References