How do I find out what escape sequence my terminal needs to send?

Question

I am using the terminal application on osX to connect to ubuntu (12.04 i think). I have the terminal at it's default setting of xerm-256. In this mode the terminal sends the sequence of \033OQ when F2 is pressed. There is no mapping however for Shift-F2 or Control-F2. There is also no sequences set for Shift-Left, Shift-Right, Control-Left, Control-Right, etc. I need some of these keys to operate features from time to time in various programs. Take for example byobu. Shift-F2 and Control-F2 are used to split the screen vertically and horizontally. In tmux the arrow keys are used with shift and control for resizing panes.

My problem is that I don't know what sequence the terminal should send. How do I find out what these sequences should be? I know that I can press Control-v and then a key to get the code that is being received but this is not what I need. I don't need to see what sequence is being sent. I need to know what sequence I need to send.

For instance my left arrow sends ^[OD. My Control-Left sends ^[[5D]. However my up and down keys have no distinction. My down sends ^[OB and Control-down also sends ^[OB. Same problem with my up key. It is the same with or without shift.

Is there a list somewhere with all of the keys and there codes, specifically with modifiers such as shift, control, alt/option?

How can I find out what the expected sequence is so I can send what is needed?

Answer 1

XTerm

Since you are advertising that you are using an xterm (via your TERM value), you will most likely want to arrange to send the sequences that xterm would send for these keys. The ctlseqs documentation from xterm describes these particular modified key sequences at the bottom of the PC-Style Function Keys section:

… xterm recognizes function key modifiers which are parameters appended before the final character of the control sequence.

    2 Shift
    3 Alt
    4 Shift + Alt
    5 Control
    6 Control + Shift
    ⋮

Examples

F5 sends ^[[15~, so Shift-F5 should send ^[[15;2~ (i.e. add ;2 before the final character)

The arrow keys and the first four function keys are a bit different. They often use SS3-based sequences (starting with ^[O); these will need to be changed to CSI-based equivalents (starting with ^[[) since SS3 sequences can not have parameters. Also, the normal sequences for the keys do not usually have a numeric parameter, so a placeholder(?) 1 parameter is also added:

Up sends ^[[A or ^[OA, so Shift+Up should send ^[[1;2A (i.e. switch to CSI, and add 1;2 before the final character)

F1 sends ^[OP, so Shift+F1 should send ^[[1;2P (i.e. switch to CSI, add 1;2 before the final character)

You might also like to look at the source code of various terminal emulators to see whay they do. For example, the relevant bits of tmux are in its xterm-keys.c file.

Configuration

Since your terminal emulator is not already sending all the sequences you want to support, you will have to configure it to do so. The built-in terminal emulator that comes with OS X, Terminal, has a few keys preconfigured, but you will probably have to add most of them yourself. You can get to the list of keys by invoking the Terminal > Preferences… menu item, selecting the top-level Settings tab, picking the appropriate profile, and switching to its Keyboard tab. From there you can add and remove key definitions. For example, you could define F2 with shift to send string to shell: (sic) and type ESC followed by [1;2Q into the string text box (the ESC will show up as \033, this is okay).

Note: Changing the definition of Option-Right and Option-Left might affect how some programs (e.g. shells and Emacs) work with those keystrokes. The default configuration sends ESC-f and ESC-b, which are Emacs-style keystrokes for backward-word and forward-word that many programs will understand by default. This configuration seems backwards to me; the shell (and other programs) should be configured to recognize proper modified arrow key sequences instead.

You might also want to try a different terminal emulator. iTerm 2 has built-in support for most of these modified keys (maybe not the Control+Fn variants), so there would be less to manually configure.

Also, note that OS X has some system-wide shortcuts defined for some of the Control-Fx combinations (see System Preferences, Keyboard, Keyboard Shortcuts, Keyboard & Text Input). You will have to disable some of these shortcuts to make sure that Terminal or iTerm has a chance to “see” your desired key combinations.