Name

TERM, COLORTERM, XTERM_VERSION, VTE_VERSION — terminal type environment variables

Description

The TERM environment variable tells programs what type of terminal they are talking to on the terminal device attached to their standard inputs, outputs, and errors. (Note that this makes no distinction amongst the standard files, which must all be terminal devices of the same type if they are terminal devices; and makes no provision for other types of terminal open as devices on other file descriptors.) The COLORTERM, XTERM_VERSION, and VTE_VERSION environment variables are non-standard additions to TERM.

Meaning

Some applications take the value of the TERM environment variable as a key used to look up records in the terminfo(5) or termcap(5) databases. These records describe the "capabilities" of a terminal of the named type. Unfortunately, these databases have some long-standing problems:

  • The model of a "cursor addressing mode" that is switched on and off and a keypad that has "local" and "xmit" modes does not match the nowadays widespread architectures of DEC VTs and of the GUI terminal emulators that emulate them, where rather terminals have "alternate screen buffers", calculator and cursor keypads that have "application" and "normal" modes (neither of which are "local"), and the display is always cursor-addressible.

  • The keyboard input model involves matching fixed strings, which does not work well with DEC VT and compatible terminals where the control sequences for various keys can vary according to the current modifier states.

  • termcap/terminfo do not include capabilities for informing applications that the terminals support ISO 8613-6 Indexed colour or ISO 8613-6 Direct colour (i.e. setting colour from a pallette of usually 256 entries, or setting colour by directly specifying RGB values) and have no direct matches for the ECMA-48 invisible or strikethrough character attributes.

  • termcap/terminfo have capabilities that are largely meaningless on modern terminals and terminal emulators, such as the ability to switch between "near letter quality" and "draft" modes, which applied to (only some) dot-matrix printers and paper terminals.

Some applications use the ncurses(3) library that is built upon termcap/terminfo, and which adds some further problems of its own. For example:

  • The ncurses colour model has the notion of "colour pairs" which existed in some terminals that are rare to nonexistent nowadays, and there is a limited repertoire of such pairs. The colour model of the DEC VTs and compatibles does not comprise colour pairs, but rather has separately settable foreground and background colours that can include every possible pairing.

Because of these, some applications take to employing their own systems that have different models (that are more like the prevalent ECMA-48 and DEC VT model) or just outright ignoring the value of the TERM environment variable and hard-coding terminal escape sequences and control sequences. Hard-coding, however, undermines conventions such as the one that specifying the terminal type "dumb" causes applications to generate no escape sequences or control sequences, and limit themselves to just the C0 control characters. TerminalCapabilities(3) describes how some tools in the nosh toolset, which do not use ncurses/termcap/terminfo, react to these environment variables.

The XTERM_VERSION and VTE_VERSION environment variable values are the value of the XTerm version or the version of the VTE library that the terminal emulator is employing, respectively. The COLORTERM environment variable convention arose in part because of the problems that termcap/terminfo have fully and correctly describing colour capabilities. If it has the value truecolor or the value 24bit, then the terminal type supports ISO 8613-6 Direct colour SGR control sequences. Other values are not really reliable, as its semantics for those cases have never been fully and formally specified.

Remote applications

The TERM environment variable is replicated to the remote system via an SSH login because it is part of the protocol to transfer the terminal type. (The same is true for other protocols, such as TELNET.) For reliable operation of applications on that system using the local terminal for their I/O, by way of the SSH connection, the COLORTERM, XTERM_VERSION, and VTE_VERSION environment variables should be replicated as well.

Utilities in the nosh toolset, and NeoVIM, also make use of the KONSOLE_PROFILE_NAME, TERM_PROGRAM, and ROXTERM_ID environment variables to attempt to heuristically work around several common misconfigurations. It is convenient to replicate them, too, therefore.

Mis-configuration

It is an error to specify xterm or xterm-256color as the value of the TERM environment variable when the terminal emulator is not actually XTerm. The XTerm terminal emulator provides a wide range of functionality, from sixel graphics through Tektronix mode and DTTerm extensions to the DECSLPP control sequence. No other terminal emulator is precisely functionally equivalent to XTerm. Even considering the small subset of terminal functionality that termcap/terminfo records encode, the xterm/xterm-256color records encode capabilities that are not correct matches to the behaviours and capabilities of other terminal emulators.

Terminal emulator documentation claiming XTerm compatibility is invariably wrong. Authors claiming that they have implemented XTerm compatibility far too often turn out not to even have fully and correctly implemented the feature subset covered by the terminfo/termcap records for XTerm.

The termcap/terminfo databases actually have proper, fully-fledged, records that are specifically created for the terminal emulators that are commonly mis-labelled "xterm":

anything based upon libvte (e.g. GNOME/MATE/XFCE Terminal, EvilVTE, LilyTerm, et al.)

vte or vte-256color (or their respective aliases gnome and gnome-256color)

FreeBSD kernel virtual terminal

teken or (a termcap extension provided by the nosh toolset, because console-terminal-emulator(1) provides ISO 8613-6 colour SGR capability) teken-256color

Linux kernel virtual terminal

linux or linux-256color

tmux

tmux or tmux-256color

GNU Screen

screen or screen-256color

PuTTY

putty or putty-256color

Unicode rxvt

rxvt-unicode or rxvt-unicode-256color

Terminal.app

nsterm or nsterm-256color

iTerm.app

iterm

Configuration

These environment variables are inherited just like any other, and any program can alter what their values are for itself or for the child processes that it spawns. Because TUI login sessions initially have terminal devices as their standard inputs, outputs, and errors, the first process in a TUI login session sets up these environment variables for that terminal. Non-login terminal sessions, as sometimes run by terminal emulators, also have terminal devices as standard I/O, and again these environment variables are set up in the first process of the session.

How these environment variables are configured to match a given terminal or terminal emulator varies greatly:

terminal emulators such as xterm(1), gnome-terminal(1), and tmux(1)

In this kind of terminal emulator, it is the terminal emulator program that spawns the initial child process that runs in the terminal session. Thus the terminal emulator program itself generally sets the value of these environment variables. In some terminal emulator programs, what it is set to is configurable by a settings dialogue in the GUI. Others hardwire it, sometimes unfortunately hardwiring the wrong thing.

Programs like GNU Screen, mosh-server(1) , and tmux(1) are in fact terminal emulators, with their own distinct types reflected in these environment variables. They emulate their particular type of terminal on the master side of the pseudo-terminal, and a client program renders the state of that terminal onto a third-party terminal. The terminal type seen by the child processes in the terminal sessions in these environment variables is not that seen by the rendering process for its terminal.

Various terminal emulators will also set the COLORTERM, XTERM_VERSION, and VTE_VERSION environment variables, in addition to setting TERM.

TUI login on AT&T Unix System 5 Release 4 and its derivatives

In AT&T Unix System 5 Release 4 and its derivatives that use the Service Access Facility (including OpenSolaris and OpenIndiana) these environment variables are set up for terminal sessions by ttymon(8), using configuration information administered using the ttyadm(8) utility.

By default, only the TERM environnment variable is set.

nosh TUI login

Like AT&T Unix System 5 Release 4, nosh TUI login on kernel virtual terminals no longer uses getty at all.

The nosh pre-supplied TUI login service bundles for kernel virtual terminal and user-space virtual terminal login services employ vc-get-tty(1). This sets the TERM environment variable to a value that matches the type of the kernel virtual terminal, since user space virtual terminals aim to be an enhanced version of that same terminal type.

vc-get-tty always sets the TERM environment variable, and for user-space virtual terminals additionally sets the COLORTERM environment variable. In this way, programs can distinguish a basic kernel virtual terminal from a user-space virtual terminal, and make use of the several enhancements that the latter has (such as extended DECSCUSR) that the former has not.

getty-based TUI login services

getty(1) (and its various clones) sets the TERM environment variable. How it sets it varies, because there are multiple different getty programs and multiple different systems that (still) employ it:

  • BSD getty sets the TERM environment variable from its command-line argument, which does not specify it directly but specifies an entry in the gettytab(5) database. The gettytab record pointed to in turn specifies the TERM environment variable's value. The command line is in turn specified by the system administrator by a record in the ttys(5) database, /etc/ttys.

  • With van Smoorenburg init, getty sets the TERM environment variable from its command-line argument (defaulting to linux, vt100, or hurd according to the specific getty program employed). The command line is in turn specified by the system administrator by a record in the /etc/inittab file.

  • With systemd, getty likewise sets the TERM environment variable from its command-line argument. The defaults are never used, because the systemd services that invoke getty, on kernel virtual terminals and on real terminals, always supply getty with a terminal type to set. They supply it from the TERM environment variable of the systemd process itself, which initializes its own TERM environment variable to either linux or vt220 according to what it find the /dev/console device actually pointing to (a kernel virtual terminal or a real terminal, respectively; see linux-console(4)).

  • Only the nosh pre-supplied TUI login service bundles for real serial terminal login services employ getty. They do not explicitly specify a terminal type when invoking it, and it thus depends entirely from the specific getty program in use what the TERM is set to and how that is determined.

Only the TERM environnment variable is set.

Standards conformance

The TERM environment variable is defined by the Single Unix Specification (per "Environment Variables"). It leaves its actual format and values unspecified.

See also

term(7)

ncurses/terminfo explanation of the values taken by the TERM environment variable and how ncurses/terminfo interprets them. (Note that what it says about AT&T Unix System 5 Unices is wrong.)

Author

Documentation by Jonathan de Boyne Pollard