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 7a8edde4c8ccdedd1556895eec3ed265a4f615bf

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: DCS CTerm:Font:p1:<b64> ST
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: DCS [ p1 [ ; p2 ] ] q ST
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: DCS $ q pt ST
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: DCS p1 [ ; p2 [ ; p3 ] ! z ST
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: OSC 4;(pX;pY)... ST
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.

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 ST
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 ST
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 ST
Loads a PPM to a buffer. Ps0 is the filename

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

Sequence: APS SyncTERM:P;Copy Ps... ST
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... ST
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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!

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.

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

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

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

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

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.

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

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

Sequence: CSI Ps... m
Defaults: Ps1 = 0
Sets or clears one or more text attributes. Unlimited parameters are supported and are applied in received order. The following are supported:

All others are ignored.

Blink indicates the blink bit.
Bold indicates the bold bit.
FG indicates the foreground colour.
BG indicates the background colour.
TF indicates that the Tru Colour foreground is changed.
TB indicates that the Tru Colour background is changed.

NOTE: For 90-97, there is no effect unless bright foreground colours are enabled.

NOTE: For 100-107, there is no effect unless bright background colours are enabled.

NOTE: For 38 and 48, two additional formats are supported, a palette selection and a direct colour selection.

For palette selection, an additional two parameters are required after that value. They are considered part of the 38/48, not separate values. The first additional parameter must be a 5. The second additional parameter specified the palette index to use. To set the foreground to orange, and the background to a fairly dark grey, you would send: CSI 38 ; 5 ; 214 ; 48 ; 5 ; 238 m

The default palette is the XTerm 256-colour palette.

For direct colour selection, an additional four parameters are required after that value. They are considered part of the 38/48, not separate values. The first additional parameter must be a 2. The second, third, and fourth specify the R/G/B values respectively. CTerm handles this with an internal temporary palette, so scrollback may not have the correct colours. The internal palette is large enough for all cells in a 132×60 screen to have unique foreground and background colours though, so the current screen should always be as expected.

Sequence: CSI Ps n
Defaults: Ps = 0
A request for a status report. CTerm handles the following three requests:

Sequence: CSI = Ps n
Defaults: Ps = 1
When Ps is 1, CTerm will respond with a Font State Report of the form CSI = 1 ;pF ;pR ;pS0 ;pS1 ;pS2 ;pS3 n where pF is the first available loadable-font slot number and pR is the result of the previous “Font Selection” request:

pS0 - pS3 contain the font slots numbers of previously successful “Font Selection” requests into the 4 available alternate-font style/attribute values:

When Ps is 2, CTerm will respond with a Mode Report of the form CSI = 2[;pN [;pN] [...]] n Where pN represent zero or more mode values set previously (e.g. via 'CSI ? pN h). Mode values cleared (disabled via CSI ? pN l) will not be included in the set of values returned in the Mode Report. If no modes are currently set, an empty parameter will be included as the first and only pN.

When Ps is 3, CTerm will respond with a Mode Report of the form CSI = 3 ; pH ; pW n Where pH is the height of a character cell in pixels, and pW is the width of a character cell in pixels.

When Ps is 4, CTerm will respond with a Mode Report of the form CSI = 4 ; pF n Where pF is 1 if LCF mode is enabled, and 0 if it is disabled.

When Ps is 5, CTerm will respond with a Mode Report of the form CSI = 5 ; pF n Where pF is 1 if LCF mode is forced, and 0 if it is not.

Sequence: CSI ? Ps [ ; Pn ] n
Defaults: Ps = 1, Pn = 1

When Ps is 62 (DECMSR) and there is no Pn, CTerm will respond with a Mode Report of the form CSI 32767 * { This indicates that 524,272 bytes are available for macro storage. This is not actually true, SyncTERM will use all available memory for macro storage, but some software checks this value, and some parsers don't allow more than INT16_MAX parameter values.

When Ps is 63 (DECCKSR) Pn defaults to 1, and CTerm will respond with a checksum of the defined macros in the form DCS Pn ! xxxx ST Where xxxx is the hex checksum.

Sequence: CSI Pn1 ; Pn2 r
Defaults: Pn1 = 1, Pn2 = last line on screen
Selects top and bottom margins, defining the scrolling region. Pn1 is the line number of the first line in the scrolling region. Pn2 is the line number of the bottom line.

Sequence: CSI Ps1 ; Ps2 * r
Defaults: Ps1 = 0, Ps2 = 0
Set the output emulation speed (Select Communication Speed). If Ps1 or Ps2 are omitted, causes output speed emulation to stop. Ps1 may be empty. Sequence is ignored if Ps1 is not empty, 0, or 1. The value of Ps2 sets the output speed emulation as follows:

Sequence: CSI ? Ps... s
Defaults: None
Saves the current mode states as specified by CSI ? l and CSI ? h. If Ps1 is omitted, saves all such states. If one or more values of Ps is included, saves only the specified states (arguments to CSI ? l and CSI ? h).

Sequence: CSI Pn1 ; Pn2 s
Defaults: Pn1 = 1, Pn2 = last column on screen
(Only when DEC Left Right Margin Mode - 69 - is enabled)
If either Pn1 or Pn2 is zero, the current setting is retained. Selects left and right margins, defining the scrolling region. Pn1 is the column number of the first column in the scrolling region. Pn2 is the column number of the right column.

Sequence: CSI s
Defaults: None
(Only when DEC Left Right Margin Mode - 69 - is disabled)
Saves the current cursor position for later restoring with CSI u although this is non-standard, it's so widely used in the BBS world that any terminal program MUST implement it.

Sequence: CSI Ps ; Pn1 ; Pn2 ; Pn3 t
Defaults: None
Select a 24-bit colour. If Ps is 0, sets the background colour. If Ps is 1, sets the foreground colour. Pn1, Pn2, Pn3 contains the RGB value to set. CTerm handles this with an internal temporary palette, so scrollback may not have the correct colours. The internal palette is large enough for all cells in a 132×60 screen to have unique foreground and background colours though, so the current screen should always be as expected.

Sequence: CSI ? Ps... u
Defaults: None
Restores the mode states as saved via CSI ? s. If Ps is omitted, restores all such states. If one or more values of Ps is included, restores all the specified states (arguments to CSI ? l/h)

Sequence: CSI u
Defaults: None
Move the cursor to the last position saved by CSI s. If no position has been saved, the cursor is not moved.

Sequence: CSI 2 $ w
Defaults: None
Requests a list of tab stops. The list is in the form: DCS 2 $ u Pt ST. The string Pt is a list of tab stops separated by /.

Sequence: CSI Pn1 ; Ps ; Pn2 ; Pn3 ; Pn4 ; Pn5 * y
Defaults: None
Returns a checksum for the specified rectangular area. Pn1 is an ID that is returned in the response. Ps MUST be 1. Pn2 specifies the top row of the rectangle. Pn3 specifies the left column of the rectangle. Pn4 specifies the bottom row of the rectangle. Pn5 specifies the right column of the rectangle. The return value is in the format of DCS Pn1 ! ~ xxxx ST where xxxx is the hex value of the checksum.

Sequence: CSI Pn1 ; Ps ; Pn2 ; Pn3 ; Pn4 ; Pn5 * y
Defaults: None
Invokes a macro. Pn specifies the macro number. If Pn is not 0..63, no action is taken.

Sequence: CSI = Ps1 ; Ps2 {
Defaults: Ps1 = 255, PS2 = 0
This is a poorly defined command that violates the basic design laid out in ECMA-48. This will be removed in the next major version of CTerm, and should not be used.

Indicates that a font block is following. Ps1 indicates the font slot to place the loaded font into. This must be higher than the last default defined font (See CSI sp D for list of predefined fonts) Ps2 indicates font size according to the following table:

The DCS font string should be used instead as of CTerm 1.213

This is the place where the BBS world completely fell on it's face in ANSI usage. A programmer with either TeleMate or QModem (the first two programs to support “ANSI” music as far as I can tell) decided they needed a method of playing music on a BBS connection. They decided to add an “unused” ANSI code and go their merry way. Since their product didn't implement CSI M (Delete line) they assumed it was unused and blissfully broke the spec. They defined “ANSI” music as: CSI M <music string> 0x0e

They used a subset of IBM BASICs PLAY statement functionality for ANSI music strings which often start with “MF” or “MB”, so the M after the CSI was often considered as part of the music string. You would see things such as: CSI MFABCD 0x0e and the F would not be played as a note. This just added further confusion to the mess.

Later on, BananaCom realized the conflict between delete line and music, so they added *another* broken code CSI N (Properly, erase in field... not implemented in many BBS clients) which was to provide an “unbroken” method of playing music strings. They also used CSI Y to disambiguate delete line, CSI Y is supposed to be a vertical tab (also not implemented in very many clients). BananaCom also introduced many more non-standard and standard-breaking control sequences which are not supported by CTerm.

CTerm has further introduced a standard compliant ANSI music introducer CSI |

By default, CTerm allows both CSI N and CSI | to introduce a music string. Allowed introducers are set by CSI = p1 M as defined above.

The details of ANSI music then are as follows:
The following characters are allowed in music strings:
“aAbBcCdDeEfFgGlLmMnNoOpPsStT0123456789.-+#<> ” If any character not in this list is present, the music string is ignored as is the introducing code.

If the introducing code is CSI M the first char is examined, and if it is a one of “BbFfLlSs” or if it is “N” or “n” and is not followed by a decimal digit, then the music string is treated as though an M is located in front of the first character.

The music string is then parsed with the following sequences supported:

The lowest playable character is C in octave zero. The frequencies for the six C notes for the seven octaves in rising order are:
65.406, 130.810, 261.620, 523.250, 1046.500, 2093.000, 4186.000

Purists will note that the lower three octaves are not exactly one half of the next higher octave in frequency. This is due to lost resolution of low frequencies. The notes *sound* correct to me. If anyone can give me an excellent reason to change them (and more correct integer values for all notes) I am willing to do that assuming the notes still sound “right”.

PLEASE NOTE!!! If you are playing some ANSI Music then ask the user if they heard it, ALWAYS follow it with an 0x0f as 0x0e is the shift lock character which *will* cause people with anything but an ANSI-BBS terminal (ie: *nix users using the bundled telnet app) to have their screen messed up. 0x0f “undoes” the 0x0e.

While CTerm does not handle keyboard I/O, and therefore does not send any key sequences, it's only used by one piece of software (SyncTERM), which does send a set of sequences when keys are pressed. These are listed below for reference.

• ANSI References
• ECMA-48 Standard
• XTerm Control Sequences
• VT100.net
• Banana ANSI