console-control-sequence1administrator commandsnoshconsole-control-sequencesettermemit control sequences to a user-space virtual (or other) terminalconsole-control-sequence--7bit--8bit--permit-fake-truecolour--foreground colour--background colour--bold boolean--faint boolean--italic boolean--underline boolean--overline boolean--encircle boolean--frame boolean--blink boolean--reverse boolean--invisible boolean--strikethrough boolean--cursor boolean--appcursorkeys boolean--appcalckeys boolean--altbuffer boolean--backspace-is-bs boolean--escape-is-fs boolean--delete-is-del boolean--bce boolean--linewrap boolean--inversescreen boolean--insert boolean--square boolean--sco-function-keys boolean--dec-function-keys boolean--teken-function-keys boolean--132-columns boolean--regtabs interval--settabs tabstops--clrtabs tabstops--notabs--rows count--columns count--dec-locator-reports offpressreleaseall--xterm-mouse-reports offclickdragall--cursor-shape defaultblockunderlinestarboxbarunderovermirrorl--underline-type singledoublecurlydotteddashedldashedlldashedldottedlldottedlcurly--reset--soft-reset--showtabssetterm--7bit--8bit--permit-fake-truecolour--foreground colour--background colour--bold boolean--faint boolean--italic boolean--underline boolean--overline boolean--encircle boolean--frame boolean--blink boolean--reverse boolean--invisible boolean--strikethrough boolean--cursor boolean--appcursorkeys boolean--appcalckeys boolean--altbuffer boolean--backspace-is-bs boolean--escape-is-fs boolean--delete-is-del boolean--bce boolean--linewrap boolean--inversescreen boolean--insert boolean--square boolean--sco-function-keys boolean--dec-function-keys boolean--teken-function-keys boolean--132-columns boolean--regtabs interval--settabs tabstops--clrtabs tabstops--notabs--rows count--columns count--dec-locator-reports offpressreleaseall--xterm-mouse-reports offclickdragall--cursor-shape defaultblockunderlinestarboxbarunderovermirrorl--underline-type singledoublecurlydotteddashedldashedlldashedldottedlldottedlcurly--reset--soft-reset--showtabsDescriptionconsole-control-sequence emits control sequences to its standard output that instruct a compatible terminal emulator to perform various actions.
console-terminal-emulator1 is one such compatible terminal emulator.
Although its behaviour is controlled by the TERM7 environment variable, it does not use terminfo3 or termcap3.
It instead uses TerminalCapabilities3.
The terminal type determines a few terminal capabilities (such as whether the terminal can actually handle DEC private mode control sequences at all, and its degree of ISO 8613-6/ITU T.416 support), but most processing adheres to the ECMA-48 and ISO 8613-6/ITU T.416 de jure standard control sequences and the DEC VT, DTTerm, and AIXTerm de facto standard ones.
Control sequences
It emits simple terminal control sequences (ECMA-48 and DEC VT names in parentheses), as follows:
--foreground colour
(SGR 30–37,38,39,90–97)
Set the foreground colour to colour.
--background colour
(SGR 40–47,48,49,100–107)
Set the background colour to colour.
--bold boolean
(SGR 1 and SGR 22)
Set boldface on/off according to boolean.
--faint boolean
(SGR 2 and SGR 22)
Set faint on/off according to boolean.
--italic boolean
(SGR 3 and SGR 23)
Set italic on/off according to boolean.
--underline boolean
(SGR 4 and SGR 24)
Set underline on/off according to boolean.
--frame boolean
(SGR 51 and SGR 53)
Set framed characters on/off according to boolean.
--encircle boolean
(SGR 2 and SGR 53)
Set encircled characters on/off according to boolean.
--overline boolean
(SGR 53 and SGR 55)
Set overline on/off according to boolean.
--blink boolean
(SGR 5 and SGR 25)
Set blink on/off according to boolean.
--reverse boolean
(SGR 7 and SGR 27)
Set reverse on/off according to boolean.
--invisible boolean
(SGR 8 and SGR 28)
Set invisible on/off according to boolean.
--strikethrough boolean
(SGR 9 and SGR 29)
Set strikethrough on/off according to boolean.
--cursor boolean
(DECTCEM)
Cursor visibility on/off according to boolean.
--appcursorkeys boolean
(DECCKM)
Set cursor keypad sending application mode sequences on/off according to boolean.
--appcalckeys boolean
(DECNKM, DECKPAM, DECKPNM)
Set calculator keypad sending application mode sequences on/off according to boolean.
--altbuffer boolean
Switch to/from the XTerm alternate screen buffer according to boolean.
--backspace-is-bs boolean
(DECBKM)
Set the ⌫ Backspace key sending BS (instead of DEL) on/off according to boolean.
--escape-is-fs boolean
(DECSM, DECRM)
Set the ⎋ Escape key(s) sending FS (instead of ESC) on/off according to boolean.
--delete-is-del boolean
(DECSM, DECRM)
Set the ⌦ Delete key(s) sending DEL (instead of DECFNK 3) on/off according to boolean.
--bce boolean
(DECECM)
Set erase with background colour (instead of with screen/default colour) on/off according to boolean.
--linewrap boolean
(DECAWM)
Set automatic right margin wrap on/off according to boolean.
--inversescreen boolean
(DECSCNM)
Set whole screen reverse video on/off according to boolean.
--insert boolean
(IRM)
Set insert (not overstrike) on/off according to boolean.
--square boolean
(SCO Private Mode 1)
Set square (not oblong) mode on/off according to boolean.
--dec-function-keys boolean
(SCO Private Mode 2)
Set the use of DEC function key sequences on/off according to boolean.
--sco-function-keys boolean
(SCO Private Mode 3)
Set the use of SCO function key sequences on/off according to boolean.
--teken-function-keys boolean
(SCO Private Mode 4)
Set the use of Teken function key sequences on/off according to boolean.
--132-columns boolean
(DECCOLM)
Set 132-column mode on/off according to boolean.
--regtabs interval
(CTC, TBC, HTS, and DECST8C)
Clear all existing tabs and register new ones at intervals of interval columns.
The cursor will be moved to the beginning of the line.
DECST8C is used if interval is 8 and the terminal type is known to support it (TerminalCapabilities3 has use_DECST8C set to true).
--settabs tabstops
(CTC, CHA, HPA, and HTS)
Register new tabstops at the positions given in the tabstops comma-separated list of column numbers.
--clrtabs tabstops
(CTC, CHA, HPA, and TBC)
Clear existing tabstops at the positions given in the tabstops comma-separated list of column numbers.
--notabs
(CTC and TBC)
Clear all existing tabs.
--clear allrestscrollback
(ED and CUP)
Erase the whole display (and home the cursor) with ED 2, from the current position to the end of the display with ED 0, or the scrollback buffer with ED 3.
The colour used is determined by whether the terminal is in background colour erase mode.
The type all is a misnomer for compatibility with the tool discussed in the later section on compatibility.
The ED 3 control sequence is an extension to ECMA-48 that is understood by some terminal emulators.
Fortunately, those that do not understand it simply ignore the control sequence, and console-control-sequence can just emit it unconditionally.
Compatible terminal emulators are:
console-terminal-emulator1
This has always implemented the ED 3 extension, but does nothing because it has no off-screen buffers (what is "on screen" being a function of realizers, which are separate from the terminal emulator).
xterm1This extension was added on 1999-06-12 by Stephen P. Wall.
PuTTY
This extension was added in 2006 by Jacob Nevins.
the Linux kernel built-in terminal emulator
This extension was added in 2011 by Petr Písař, albeit erroneously, differing from the long-standing XTerm and PuTTY semantics of clearing only the scrollback buffer.
--rows count
Set the number of rows to count.
This uses the DECSNLS control sequence if the terminal type is known to support it (TerminalCapabilities3 has use_DECSNLS set to true), and the DECSLPP control sequence otherwise.
In the latter case, it rounds count up to 25 if the terminal type is known to implement the DTTerm extensions (TerminalCapabilities3 has has_DTTerm_DECSLPP_extensions set to true).
It then resets the top and bottom margins to the screen borders using the DECSTBM control sequence.
Some shells issue an ED 0 control sequence as part of their prompt, which has the (perhaps unexpected) effect of clearing the screen if a shell prompt is issued immediately after the terminal has been resized.
DECSTBM is supported by the DEC VT100 and later.
DECSLPP is supported by the DEC VT340 and later.
DECSNLS is supported by the DEC VT420 and later.
The Linux and FreeBSD kernel virtual terminal subsystems do not support any of these control sequences.
console-terminal-emulator1 supports all three.
DEC VTs allow any value in a DECSLPP control sequence, and round the number up to the nearest value supported by the terminal display hardware.
However, several purportedly DEC VT compatible terminal emulators ascribe wholly different actions to attempts to set fewer than 25 lines, a re-use of DECSLPP pioneered by DTTerm that prevents its use for setting smaller screen heights.
DECSNLS is unencumbered by the inconsistencies of DECSLPP in those terminal emulators, but conversely is not supported by several other purportedly DEC VT compatible terminal emulators.
If the --columns command line option is used as well and the terminal is known to support the DTTerm extensions, setting the rows and columns is done in one operation with DECSLPP 8.
--columns count
Set the number of columns to count.
This uses the DECSCPP control sequence if the terminal type is known to support it (TerminalCapabilities3 has use_DECSCPP set to true), and does nothing otherwise because there is no other control sequence for only setting the number of columns.
It then resets the left and right margins to the screen borders using the DECSLRM control sequence.
If the --rows command line option is used as well and the terminal is known to support the DTTerm extensions, setting the rows and columns is done in one operation with DECSLPP 8.
DECSCPP is supported by the DEC VT340 and later.
DECSLRM is supported by the DEC VT420 and later.
The Linux and FreeBSD kernel virtual terminal subsystems do not support either of these control sequences.
console-terminal-emulator1 supports both.
--dec-locator-reports offpressreleaseall
(DECELR and DECSLE)
Disable DEC Locator reports, enable for button press reports, enable for button release reports, and enable for all reports, respectively.
This does nothing if the terminal type is not known to support these control sequences (TerminalCapabilities3 has use_DEC_Locator set to false).
--xterm-mouse-reports offclickdragall
Disable XTerm mouse reports, enable for button press reports, enable for button press and motion while pressed reports, and enable for all reports, respectively.
Only the modern ECMA-48-conformant style of mouse report (often misnamed "SGR" style, although it is not a SGR control sequence, and invented by Thomas Dickey in 2012) is requested, which most terminal emulators support nowadays.
The older styles of mouse reports from X10 xterm and Unicode rxvt are malformed CSI sequences which an ECMA-48-conformant decoder has to fail to handle (because they put additional characters after the final character).
This thus does nothing if the terminal type is not known to support the ECMA-48-conformant style (TerminalCapabilities3 has has_XTerm1006Mouse set to false) because emitting the XTerm private mode settings anyway would turn on non-ECMA-48-conformant mouse reports on some terminals.
--cursor-shape defaultblockunderlinestarboxbarunderovermirrorl
(DESCUSR and LINXSCUSR)
Specify the shape of the cursor.
Some terminals and terminal emulators do not have distinct shapes for star, box, bar, underover, or mirrorl.
--underline-type singledoublecurlydotteddashedldashedlldashedldottedlldottedlcurly
Specify the type of underlining for SGR 4 (i.e. --underline on).
This sets an SGR sub-parameter which only a few terminal emulator programs yet recognize or even correctly process.
Even of those, few yet implement all types of underline.
console-terminal-emulator1 supports this sub-parameter.
--reset
(RIS)
Reset the terminal to its initial state, including the serial communications, and run self-tests.
Do not use this.
Use --soft-reset for preference.
DEC internal documentation stated that conforming software will not use the RIS control and it is not intended for use by conforming software in the early 1980s.
As the DEC VT420 programmers' reference manual notes, RIS is usually overkill.
On a real terminal, it resets the serial communications line from the terminal end and will as a result look like a terminal hangup to the host.
--soft-reset does not affect the serial communications.
Moreover, the RIS control sequence invokes what is known as "implied XOFF".
To use it correctly, an application must put the line discipline into XOFF-received mode, so that it does not lose output by sending it while the terminal is resetting.
This is not actually possible with terminal I/O on Linux or the BSDs, and it is not possible to use RIS completely correctly.
--soft-reset does not invoke "implied XOFF".
This is not a match for POSIX terminal I/O, and its use has been proscribed for decades.
--soft-reset
(DECSTR)
Soft reset the terminal, if the terminal type is known to support it (TerminalCapabilities3 has use_DECSTR set to true); and do nothing otherwise because there is no other control sequence for soft reset.
--showtabs
Output a ruler line followed by a line showing where each tabstop is (generated by emitting TAB characters to move to each tabstop).
If the lines do not appear properly, this is usually a symptom of the terminal emulator not correctly processing C1 control characters such as the NEL used at the end of the lines.
Use of line disciplines
Terminal output width is determined from the value of the COLUMNS environment variable if it is set, per the Single Unix Specification which requires that it take precedence.
Failing that, it is determined from the line discipline if standard output is a terminal device, or assumed to be 160 characters otherwise.
Other than assuming a fixed output width, this command makes no attempt to behave differently if its output is not to a terminal, since one might want to use it to generate the control sequences to send to a file, a pipe, or a non-terminal device.
For real terminals, it is necessary to tell the line discipline about size changes with a separate invocation of the stty1 command.
Virtual terminals connect the line discipline to the emulator, through back channels that do not exist with real terminals, and the control sequences to change the emulator's idea of the display size will also change the line discipline's idea automatically.
Character sets
If the --7bit command-line option is used, the various C1 control characters (CSI, HTS, NEL, and so forth) are sent using the ECMA-48 7-bit encoding scheme.
If it is not used but the --8bit command-line option is used, the C1 control characters are sent as a raw 8-bit character.
By default, in the absence of either option, the C1 control characters are sent encoded as UTF-8, in the expectation that the terminal is Unicode aware and decodes all output from UTF-8.
console-terminal-emulator1 properly decodes C1 characters from UTF-8 and processes them; so it does not require either option.
(Indeed, since UTF-8 is mandatory, using the --8bit command-line option is inappropriate.)
xterm1 requires the --7bit option be used as it does not ever treat UTF-8-encoded C1 characters as control characters, irrespective of the setting of its UTF-8 encoding options.
This will work however xterm is configured.
One can use the --8bit option instead if xterm is configured to be in plain 8-bit (+u8) mode.
PuTTY requires the --7bit option be used as it does not treat C1 characters as control characters, and only recognizes the 7-bit extension of ECMA-48 section 5 as C1 controls.
Colours and attributesboolean can be on, off, true, false, yes, or no.
The default colour is named default.
The 16 standard colours can be specified by RGBCMYK names such as bright red, white, and yellow.
Colour 7 is white or bright grey.
Colour 8 is grey or bright black.
Direct RGB colours can be specified by # followed by the RGB value in hexadecimal, such as #00B0E815.
Indexed colours can be specified by their index numbers, such as 188.
Hexadecimal and octal numbers are permitted in index number, so care must be taken with leading zeroes.
If the terminal type is known to not support ISO 8613-6/ITU T.416 Direct colour at all or is known to fake support by mapping 24-bit RGB colours to entries in their 8-bit colour palettes, console-control-sequence maps the RGB value to the nearest indexed colour value and uses ISO 8613-6/ITU T.416 Indexed colour.
It assumes a conventional palette with a 24 value greyscale and a 6×6×6 colour cube (the same as implemented in console-terminal-emulator1 for Indexed colour).
Setting the first 16 ISO 8613-6/ITU T.416 Indexed colours is done with the newer control sequences, not with the 16 ECMA-48 and AIXTerm standard colour ones.
The --permit-fake-truecolour command-line option permits the use of ISO 8613-6/ITU T.416 Direct colour control sequences even on terminals which are known to fake it.
Standardsde jureControl Functions for Coded Character SetsECMA-48 5th edition. 1991. ECMA International.
Information technology — Open Document Architecture (ODA) and interchange format: Document structuresT.412 International Telecommunication Union.
Information technology — Open Document Architecture (ODA) and interchange format: Character content architecturesT.416 International Telecommunication Union.
Information technology — Open Document Architecture (ODA) and Interchange Format: Character content architecturesISO/IEC 8613-6:1994 International Organization for Standardization.
de factoVT520/VT525 Video Terminal Programmer InformationEK-VT520-RM July 1994. Digital.
VT420 Programmer Reference ManualEK-VT420-RM-002 February 1992. Digital.
Compatibility
There is a setterm1 command in the util-linux toolset.
There is a wide range of overlap between the two tools.
Some of the differences are:
That tool employs operating system and device specific ioctl2 calls, and hardwires control sequences that are peculiar to the Linux built-in terminal emulator (not looking several of them up in the terminfo3 database, despite what its manual page claims).
This command does not, and so can be used remotely and with terminal emulators other than the Linux built-in one.
None of the things peculiar to the Linux built-in terminal emulator, such as setting blanking modes or power modes and accessing the internal character+attribute arrays through special device files, are supported.
Conversely, console-control-sequence supports standard terminal control sequences that the Linux-specific tool does not, such as strikethrough and calculator keypad application mode.
To simplify the command-line option parsing, displaying the tabstops and ruler is the remit of a distinct --showtabs option that never takes option arguments.
Similarly, clearing all tabs is the remit of a distinct --notabs option.
This command supports the additional 8 (de facto) standard colours (that originated with AIXTerm), and uses ISO 8613-6/ITU T.416 Indexed and ISO 8613-6/ITU T.416 Direct colour control sequences.
No such concept as "underline colour" or "boldface colour" is recognized.
This is a hangover from an odd quirk in the way that the Linux built-in terminal emulator handled CGA/EGA/VGA hardware in text mode (which it usually employs in graphics mode nowadays, the so-called "framebuffer console").
Underlining and boldface are attributes (displayed on many terminal emulators by actually underlining and boldfacing the glyphs), not colours.
AuthorJonathande Boyne Pollard