The actions controlled by these escape sequences are often called capabilities. Some escape sequences are shared among many terminals, and many of those sequences are specified in the ANSI X3.64-1979 standard. Nearly all color-capable terminals use the same sequences to choose colors to display. However, many terminals have wildly different escape sequences. For instance, on a Wyse 30 terminal, pressing F1 sends the sequence ^A@ , whereas pressing F1 on your Linux console sends the sequence ^[[[A. Similarly, to move the cursor up on a Wyse 30, you send it a ^K character; to move the cursor up on the Linux console, send the ^[[A sequence. To write a program that can work on either terminal, you clearly need a way to abstract these differences, which would allow you to program with the capabilities rather than the raw character sequences.

The most common programming library that provides this abstraction is called curses,^[1] documented in Programming with curses [Strang, 1991A]. It has two important conceptual levels. The first level provides functions that (generally speaking) send one escape sequence to accomplish one action, such as move the cursor up, move it down, scroll the screen, and so on. The second level provides a concept of “windows": independent screen areas that can be manipulated separately, with curses quietly figuring out the shortest character sequences to send to effect the changes you request.

The curses library determines which sequences to send to the terminal by consulting a database that, for each terminal, maps capability names to the strings that need to be sent.

Linux, like all modern Unix systems, provides two databases that describe terminals in terms of the capabilities they possess and which escape sequences map to which capabilities. The older database is called termcap (short for terminal capabilities) and is kept in one large ASCII flat file called /etc/termcap. This file has become unwieldy; it has grown to approximately half a megabyte. The newer database is called terminfo (short for terminal information) and is kept in many binary files, one per terminal, normally in subdirectories of the /usr/lib/terminfo directory.

Within each database, the capability information for each terminal is indexed by one or more unique names. Both databases use the same name for the same terminal. For instance, the Linux console is called linux in both termcap and terminfo. You tell programs which terminal entry to use by setting the TERM environment variable. When writing programs that use termcap and terminfo, you rarely need to look at the TERM environment variable; usually, the low-level libraries for accessing the termcap or terminfo databases automatically take care of that.

However, if you wish to do Linux-specific optimizations, especially if you want to use some of Linux’s unusual capabilities that are not described in the capability databases, you can check the TERM environment variable with code like this:

if (!strcmp("linux", getenv("TERM"))) {
    /* should be a Linux console */
} else {
    /* handle as a normal serial terminal */
}

Also, if you wish to write programs in programming languages without easy access to curses or some other terminal abstraction library, you may find it convenient to use this documentation.

Of course, that your terminal type is linux does not guarantee that your program is running on a local terminal. If the terminal type is linux, you know you have access to the escape sequences documented in this chapter, but you do not know if you have access to the vcs devices (documented later in this chapter) or ioctl() s. POSIX specifies a ttyname() function that you can use to find the name of the device file for the controlling terminal. On a Linux system, the virtual consoles are named /dev/ttyn for n between 1 and 63 (/dev/tty0 is always the current console).

Complete documentation for the termcap and terminfo systems is available in termcap & terminfo [Strang, 1991B]. Eric Raymond currently maintains the termcap and terminfo databases, which he makes available via the Web at http://www.ccil.org/~esr/terminfo/ The source code to ncurses (new curses, the implementation of curses used on Linux) includes an introduction to curses programming in the misc/ncurses-intro.html file.

When you write a character to any terminal, several steps of translation may happen. The value written to the terminal is the character number, or character code. That character code is not enough to determine what to display on the screen, however. The shape depends on what font is being used. The character code 97 may be printed as an a in a font designed for rendering Latin-based languages, but might be rendered as an in a font designed for rendering Greek or mathematics. The shape that is displayed is called a glyph. The translation from character codes to glyphs is called a map.

The Linux console,^[2] like most terminals, is modal: Its response to data depends on what mode it is in. By default, it prints on the screen the characters you send to it unless it receives an escape or control character. A control character simply causes some control action to be taken, but the next character is read normally; there is no change in processing mode. An escape character signals the beginning of an escape sequence and changes the processing mode to escape mode.

For example, consider the following C string:

"this is a line
a 33[1mbold33[0m word
"

The console processes the string in the following sequence:

So, assuming that the cursor was at the beginning of a line to start with, the output from the entire string will look something like this:

this is a line
a bold word

#define CTRLCHAR(ch) ((ch)&0x1F)

if (c == CTRLCHAR('C')) {
    /* control-C was pressed */
}

cat > /tmp/somefile

There are some cases in which being able to write characters to the screen is simply insufficient, partially because it is impossible to determine the current state of the screen. Although standard Unix practice is to ignore the state of the screen—to set it up as you need it, make changes to it as you have changes to make, and to redraw it completely any time the user requests it (usually by pressing ^L)—you may have other applications in mind.

In particular, screen capture and restore programs and functions need access to the current contents of the screen. Linux provides this through two interfaces. One provides only the text contents of the screen, and one contains attributes (color and so forth), as well.

The simple text device is called vcs, which presumably stands for virtual console screen.^[3] The /dev/vcs0 device when read produces the contents of the current virtual console as it is being viewed at the time it is read. If the screen is currently scrolled back (the Control-PageUp and Control-PageDown keys are set up to control console scrolling by default), /dev/vcs0 contains the scrolled-back contents that are being viewed. The rest of the vcs devices, /dev/vcs n, each represent the current state of the virtual console n, normally accessed through /dev/ttyn.

When you read /dev/vcs*, you are given no indication of new lines or of console size other than an EOF at the end of the screen. If you read 2,000 bytes and then receive an EOF, there is no indication whether the screen is 80 columns and 25 lines or 40 columns and 50 lines. No newline characters are produced to mark the ends of lines, and every empty character cell, whether or not it was ever written to, is denoted by a space character. There are several popular screen configurations, and there is no guarantee that each of them has a unique number of lines and columns. The vcs device provides an easy way for a savvy sysadmin or developer to see what is on any virtual console, but it is not very useful from a programmer’s standpoint, at least alone.

One useful way to use vcs is from within X. XFree86, by default, starts the X server on the first free virtual console, not on the console that the program was started from. If you start XFree86 from virtual console 1, you do not need to change back to virtual console 1 to see the detection messages that XFree86 left on the screen; bring up a terminal window the same size as the console (normally 80 columns by 25 lines), become superuser (in order to gain access to the vcs device), and run cat /dev/vcs1. The contents of the first virtual console will fill your terminal window.

In order to write reliable programs, however, you need some basic knowledge about the state of the screen that a vcs device does not provide

The vcsa device (which presumably stands for virtual console screen with attributes) provides all this. The first four bytes of /dev/vcsan (for the same n as vcs devices) contain a header that gives the current cursor position and screen configuration. The first byte contains the number of rows, the second the number of columns, the third the cursor’s current column, and the fourth the cursor’s current row. The rest of the file contains alternating bytes that represent the text and text attribute bytes of the console in question.

So, if you need to know only the size of the console and its textual contents, you can read the first two bytes of the appropriate vcsa device and from then on use only the vcs device. If you want to set the current cursor position, write to the third and fourth bytes of the vcsa device (the first two bytes are read-only, so the first two characters are placeholders; we prefer to use spaces or some other similar character to make this more obvious). As an example, to move the cursor on the fourth virtual console to the eighth row and the twentieth column (counting from zero):

echo -n -e '..2307' > /dev/vcsa4

The -n keeps echo from adding a newline character to the end, and the -e makes it interpret escape codes, so that nnn is interpreted as octal character nnn.

The attributes and character contents are represented as alternating bytes, the first containing the character and the second containing the attributes to apply to the character. The attribute byte is normally defined like the attribute byte used on VGA hardware. Other kinds of hardware, including the TGA cards used on many Linux/Alpha machines and the SPARC console driver, emulate the VGA attribute handling. On video hardware without color support but with underline support, it can be read slightly differently; it is designed in such a way that you can pretend that it is all VGA hardware, and all other hardware will behave somewhat reasonably.

For each attribute byte, the bits are interpreted as documented in Table 21.12. That is the VGA representation; some color hardware replaces blink by a bright background. The monochrome representation uses bit 0 of the foreground color to indicate underline.