The Linux console, 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\na \033[1mbold\033[0m word\n"

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  

Control Characters

The console reads control characters immediately, acts on them, and then continues to read characters in normal mode.

In termcap and terminfo files and documentation, control characters are represented by ^c. To find the numeric value of a control character, some systems provide a CTRL() macro in <termios.h>, but it is not standard on all systems. Instead, we provide our own version, CTRLCHAR():

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

It is used like this:

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

The control characters understood by the Linux console are described in Table 1. The ^? character is actually '?'+0100, not '?'-0100, so it is not really a control-question-mark, but ^? is the standard name for it anyway. Its value is 0177 (octal), 127 (decimal), 7F (hexadecimal). You will not be able to use the CTRL macro just described to test for it. Instead, use the numeric value 127.

Note that the effect of some of these codes depends on the tty settings. Although the console itself is precisely documented here, the tty settings may alter what characters are sent. For instance, sending a ^J (LF) usually causes the tty layer also to send a ^M (CR), and ^? (DEL) can be set to send ^H (BS) instead.

The ALT-^[ character is not an ASCII character at all. It is an ESC character with the eighth bit set—ASCII specifies only 7-bit characters. You can use it as a shortcut for entering the CSI sequence, but we recommend that you avoid it because it requires an 8-bit-clean communications link, which might keep your program from running remotely on another Linux system connected, perhaps, by a serial link that transmits only seven bits out of every byte.

For more information on the ASCII characters, see the ascii(7) online manual page. Similarly, the iso_8859_1(7) manual page covers the 8-bit ISO Latin 1 character set (more properly, ISO 8859 Latin Alphabet number 1); this newer standard is becoming the de facto replacement for ASCII, which is now officially called ISO 646-IRV.

Escape Sequences

There are several distinct types of escape sequences. The simplest type of escape sequence consists of the escape character (^[) followed by a single command character. (Although the escape character is represented in C strings as \033, it is represented as ^[ in termcap and terminfo files and documentation.) Five of those single command characters preface more complex escape sequences called command sequences, and the rest cause the console to take simple actions and immediately leave escape mode. The simple escape sequences are documented in Table 2

Storing and restoring the cursor position (^[7 and ^[8) are not done on a stack; if you do two stores in a row, the second stored position overwrites the first stored position. Conversely, after storing the cursor position once, you can restore it as many times as you wish. Each time, the cursor will revert to the same location. When you restore the cursor position, you also restore character rendition attributes, current character set, and character set definitions.

Cursor position is given in terms of a character cell address, an x,y pair of numbers that names one position on the screen. Character cell addresses on most terminals, including the Linux console, do not follow standard computer-science practice of counting from zero. The upper-left character on the screen is the origin and is addressed as character cell 1,1.

Note that control characters may be included in the middle of an escape sequence. For example, ^[^G8 first beeps and then restores the cursor position and attributes. The sequence ^[^X8 simply prints an 8.

Testing Sequences

To test most sequences, you merely need to log into a virtual console and run cat. Type the sequences you wish to test, and watch the results. For ^[, press the Escape key.

Terminal responses to commands such as the ^[Z terminal identification command or the CSIn command documented later show up as escape sequences that disappear in terminal handling. In cases in which you wish to see such a response, you can simply run

cat > /tmp/somefile  

Then type the commands, followed by a return and a ^D. Use less, vi, Emacs, or some other program that can handle arbitrary characters to read /tmp/somefile, where you will find the responses directly following the sequences you typed.

Complex Escape Sequences

Five two-character escape sequences are really prefixes to longer, more-complex escape sequences, as shown in Table 3. We describe each of these sequences, in turn.

CSI sequences have three or four parts.

The parameters are usually referred to as par1 through par16. If you do not set a parameter explicitly, its value is automatically set to 0 or 1, depending on what makes the most sense. The CSI command characters are documented in Table 4.

Several sequences take arguments describing colors; they all use the same mapping from numbers to colors, documented in Table 5. Sequences that describe background colors accept only color numbers between 0 and 7; sequences that describe foreground colors accept numbers between 8 and 15 that describe bold or bright colors.

These colors are actually offsets into a table—the color names in the table describe the default colors stored at those offsets. However, you can change those colors with a palette-setting sequence; the ^[]P sequence sets an individual palette entry, and the ^[]R sequence resets the palette to the system default palette. Palette entries are defined by seven hexadecimal digits that follow ^[]P, as documented in Table 6. So for each palette entry, you can provide a 24-bit color definition with eight bits for each color.

The character rendition sequences denoted by the CSI m command may have up to 16 parameters, documented in Table 7, in any order. They are applied to the terminal in the order in which they are given, so if 0 to set the default rendition is followed by 1 to set bold, the result is a bold—but not blinking, reverse video, or underlined—character, regardless of the previous rendition settings.

Related somewhat to the character rendition sequences are the mode sequences. There are two types of modes: ANSI modes and DEC private modes. The CSI h sequence sets ANSI modes, documented in Table 8, and the CSI l sequence clears them. More than one parameter can be included in a sequence. The CSI ?h sequence sets DEC private modes, documented in Table 9, and the CSI ?l sequence clears them. Again, more than one parameter can be included.

The setterm sequences are a set of CSI sequences with the command character ]. They are documented in Table 10.

There is more to conversing with the console than telling it what to display; you also must recognize key sequences and know which keys they are attached to—and although some of them are specified in the terminfo database, others are not. To make life even more interesting, the keyboard is modal. In application mode, the cursor keys produce different codes. As shown in Table 9, they are prefixed with ^[O instead of ^[[. This is to support legacy applications that assume that they are talking to DEC terminals.

The key sequences are documented in Table 11. Note that the function-key numbering has gaps and that it is designed so that people without F11 and F12 keys are not handicapped.