Xterm control sequences, a quick and incomplete introduction

XTerm control sequences are those sequences of characters that when typed into a terminal, can have all sort of cool side-effects. Try this one:

$ echo -e '\e[33;45mHello!'

If you're not too enthused about yellow and magenta (shame!) type in:

$ echo -e '\e[0m'

Many other neat things can be done with those control sequences, so I'm going to document here how to understand the documentation, so I don't have to figure it out from scratch again in the future. This could be summarised as, "read the introduction to the documentation before jumping in the middle" but I might not remember that either given enough time :o)

It all started with a Pippy bug I was trying to figure out, summarised for the interesting bits here:

# xterm magic! see http://rtfm.etla.org/xterm/ctlseq.html
import os, tty, termios
fd = os.open('/dev/tty', os.O_RDWR|os.O_APPEND)
tty.setraw(fd, termios.TCSANOW) # set to raw mode.
os.write(fd, '\x1B[18t') # write the 'query screen size' command
# (Removed: Code to parse response)

"\x1B[18t" is the bit that matters. I'm going to use the documentation linked in the code as a reference here, though there are other versions, some more recent, floating around the Internet.

Before skipping ahead and skimming around the document, there's a couple of crucially important pieces of information that must be read.

First one is:

Ps     A single (usually optional) numeric parameter, composed of one of more digits. Pm     A multiple numeric parameter composed of any number of single numeric parameters, separated by ; character(s). Individual values for the parameters are listed with Ps.

Second bit is (even) weirder and hidden amidst other commands:

ESC [      CSI       0x9b       Control Sequence Introducer

The CSI abbreviation is used all over the paper and without that, well, it's much more difficult to understand.

Now looking again at \x1B[18t. \x1B means hexadecimal character 1B which in ASCII is "ESCAPE."

From what we just read we know that any command needs to be escaped by starting with ESC[ (represented by \e[ in our shell examples.) That's the "CSI" and it tells the terminal that what follows is to be interpreted as a control sequence.

Moving on, the stuff of interest to us here is under the header "Functions using CSI, ordered by the final character(s)". For the Pippy example, it's 't' and thus this one:

CSI Ps ; Ps ; Ps t      Window manipulation (from dtterm, as well as extensions). Valid values for the first (and any additional parameters) are: <snip values>

Looking at the long list of possible values, we find: "CSI 18 t" returns the size of the xterm window in pixels as: "CSI 4 ; height ; width t". End of mystery! Other "suffix t" commands can be played with to change the size of your terminal, $ echo -e '\e[;80;24t' to set things right again.

There's a shell script on that same site if you want to play around more, as well as the patch that was submitted to gnome-terminal to implement more control sequences in all its glorious hyerogliphic majesty (commented though :)).