Name

console-control-sequence, setterm — emit control sequences to a user-space virtual (or other) terminal

Synopsis

console-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] [--bce boolean] [--linewrap boolean] [--inversescreen boolean] [--insert boolean] [--square boolean] [--132-columns boolean] [--regtabs interval] [--settabs tabstops] [--clrtabs tabstops] [--notabs] [--rows count] [--columns count] [--dec-locator-reports { off | press | release | all }] [--xterm-mouse-reports { off | click | drag | all }] [--cursor-shape { default | block | underline | star | box | bar | underover | mirrorl }] [--underline-type { single | double | curly | dotted | dashed | ldashed | lldashed | ldotted | lldotted | lcurly }] [--reset] [--soft-reset] [--showtabs]

setterm [--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] [--bce boolean] [--linewrap boolean] [--inversescreen boolean] [--insert boolean] [--132-columns boolean] [--regtabs interval] [--settabs tabstops] [--clrtabs tabstops] [--notabs] [--rows count] [--columns count] [--dec-locator-reports { off | press | release | all }] [--xterm-mouse-reports { off | click | drag | all }] [--cursor-shape { default | block | underline | star | box | bar | underover | mirrorl }] [--underline-type { single | double | curly | dotted | dashed | ldashed | lldashed | ldotted | lldotted | lcurly }] [--reset] [--soft-reset] [--showtabs]

Description

console-control-sequence emits control sequences to its standard output that instruct a compatible terminal emulator to perform various actions. console-terminal-emulator(1) is one such compatible terminal emulator.

Although its behaviour is controlled by the TERM(7) environment variable, it does not use terminfo(3) or termcap(3). It instead uses TerminalCapabilities(3). 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.

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.

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

(DEC Private Mode 1369) Set square (not oblong) mode 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 (TerminalCapabilities(3) 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 { all | rest | scrollback }

(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:

--rows count

Set the number of rows to count.

This uses the DECSNLS control sequence if the terminal type is known to support it (TerminalCapabilities(3) 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 (TerminalCapabilities(3) 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.

Note that 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/TrueOS kernel virtual terminal subsystems do not support any of these control sequences. console-terminal-emulator(1) 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 (TerminalCapabilities(3) 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/TrueOS kernel virtual terminal subsystems do not support either of these control sequences. console-terminal-emulator(1) supports both.

--dec-locator-reports { off | press | release | all }

(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 (TerminalCapabilities(3) has use_DEC_Locator set to false).

--xterm-mouse-reports { off | click | drag | all }

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 (TerminalCapabilities(3) 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 { default | block | underline | star | box | bar | underover | mirrorl }

(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 { single | double | curly | dotted | dashed | ldashed | lldashed | ldotted | lldotted | lcurly }

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-emulator(1) supports this sub-parameter.

--reset

(RIS) Reset the terminal to its initial state, including the serial communications, and run self-tests.

Caution

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 (TerminalCapabilities(3) 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. 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), or failing that 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.

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-emulator(1) 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.)

  • xterm(1) 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 attributes

boolean 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 . Indexed colours can be specified by their index numbers, such as 188 . Note that hexadecimal and octal numbers are permitted, so care must be taken with leading zeroes. Direct RGB colours can be specified by # followed by the RGB value in hexadecimal, such as #00B0E815 .

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-emulator(1) 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.

Standards

Compatibility

There is a setterm(1) 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 ioctl(2) calls, and hardwires control sequences that are peculiar to the Linux built-in terminal emulator (not looking several of them up in the terminfo(3) 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.

Author

Jonathan de Boyne Pollard