TERM 7 miscellany nosh
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. The `COLORTERM`, `XTERM_VERSION`, and `VTE_VERSION` environment variables are non-standard additions to `TERM`.

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.

### 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/ITU T.416 Indexed colour or ISO 8613-6/ITU T.416 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/ITU T.416 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, to properly ECMA-48 conformant mouse reports. 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`, `teken-16color`, or `teken-256color`, the latter being a termcap extension provided by the nosh toolset, because console-terminal-emulator 1 provides ISO 8613-6/ITU T.416 colour SGR capability (unlike the FreeBSD KVT)

Linux kernel virtual terminal

  `linux` or `linux-256color`, the latter being a termcap extension provided by the nosh toolset, because console-terminal-emulator 1 provides ISO 8613-6/ITU T.416 colour SGR capability (unlike the Linux KVT)

tmux

  `tmux` or `tmux-256color`

GNU Screen

  `screen` or `screen-256color`

PuTTY

  `putty` `putty` or `putty-256color`

Unicode rxvt

  `rxvt-unicode` or `rxvt-unicode-256color`

Terminal.app

  `nsterm` or `nsterm-256color`

iTerm.app

  `iterm`

Microsoft Terminal

  `ms-terminal`

### 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 back end (called "master side" in older documentation) 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-terminal 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-terminal 1 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, on old AT&T Unix systems (and their clones) and BSDs

  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.

  What it says about AT&T Unix System 5 Unices is wrong.

## Author

Documentation by

Jonathan de Boyne Pollard