10. Key bindings

10.1 How do I bind keys (including function keys) to commands?
10.2 Why does Emacs say "Key sequence XXX uses invalid prefix characters"?
10.3 Why doesn't this [terminal or window-system setup] code work in my `.emacs' file, but it works just fine after Emacs starts up?
10.4 How do I use function keys under X?
10.5 How do I tell what characters or symbols my function or arrow keys emit?
10.6 How do I set the X key "translations" for Emacs?
10.7 How do I handle C-s and C-q being used for flow control?
10.8 How do I bind C-s and C-q (or any key) if these keys are filtered out?
10.9 Why does the Backspace key invoke help?
10.10 Why doesn't Emacs look at the `stty' settings for Backspace vs. Delete?
10.11 How do I swap two keys?
10.12 How do I produce C-XXX with my keyboard?
10.13 What if I don't have a Meta key?
10.14 What if I don't have an Escape key?
10.15 Can I make my Compose Character key behave like a Meta key?
10.16 How do I bind a combination of modifier key and function key?
10.17 Why doesn't my Meta key work in an xterm window?
10.18 Why doesn't my ExtendChar key work as a Meta key under HP-UX 8.0 and 9.x?

10.1 How do I bind keys (including function keys) to commands?

Keys can be bound to commands either interactively or in your `.emacs' file. To interactively bind keys for all modes, type M-x global-set-key RET key cmd RET.

To bind a key just in the current major mode, type M-x local-set-key RET key cmd RET.

See Info file `emacs', node `Key Bindings', for further details.

To make the process of binding keys interactively eaiser, use the following "trick": First bind the key interactively, then immediately type C-x ESC ESC C-a C-k C-g. Now, the command needed to bind the key is in the kill ring, and can be yanked into your `.emacs' file. If the key binding is global, no changes to the command are required. For example,

(global-set-key (quote [f1]) (quote help-for-help))

can be placed directly into the `.emacs' file. If the key binding is local, the command is used in conjunction with the "add-hook" command. For example, in tex-mode, a local binding might be

(add-hook 'tex-mode-hook (lambda () (local-set-key (quote [f1]) (quote help-for-help))))

• Control characters in key sequences, in the form yanked from the kill ring are given in their graphic form--i.e., CTRL is shown as `^', TAB as a set of spaces (usually 8), etc. You may want to convert these into their vector or string forms.

• If a prefix key of the character sequence to be bound is already bound as a complete key, then you must unbind it before the new binding. For example, if ESC { is previously bound:

  (global-unset-key [?\e ?{]) ;; or (local-unset-key [?\e ?{])

• Aside from commands and "lambda lists," a vector or string also can be bound to a key and thus treated as a macro. For example:

  (global-set-key [f10] [?\C-x?\e?\e?\C-a?\C-k?\C-g]) ;; or (global-set-key [f10] "\C-x\e\e\C-a\C-k\C-g")

10.2 Why does Emacs say "Key sequence XXX uses invalid prefix characters"?

Usually, one of two things has happened. In one case, the control character in the key sequence has been misspecified (e.g. `C-f' used instead of `\C-f' within a Lisp expression). In the other case, a prefix key in the keystroke sequence you were trying to bind was already bound as a complete key. Historically, the `ESC [' prefix was usually the problem, in which case you should evaluate either of these forms before attempting to bind the key sequence:

(global-unset-key [?\e ?[]) ;; or (global-unset-key "\e[")

10.3 Why doesn't this [terminal or window-system setup] code work in my `.emacs' file, but it works just fine after Emacs starts up?

During startup, Emacs initializes itself according to a given code/file order. If some of the code executed in your `.emacs' file needs to be postponed until the initial terminal or window-system setup code has been executed but is not, then you will experience this problem (this code/file execution order is not enforced after startup).

To postpone the execution of Emacs Lisp code until after terminal or window-system setup, treat the code as a lambda list and set the value of either the term-setup-hook or window-setup-hook variable to this lambda function. For example,

(add-hook 'term-setup-hook (lambda () (when (string-match "\\`vt220" (or (getenv "TERM") "")) ;; Make vt220's "Do" key behave like M-x: (global-set-key [do] 'execute-extended-command))))

For information on what Emacs does every time it is started, see the `lisp/startup.el' file.

10.4 How do I use function keys under X?

With Emacs 19, functions keys under X are bound like any other key. See section 10.1 How do I bind keys (including function keys) to commands?, for details.

10.5 How do I tell what characters or symbols my function or arrow keys emit?

Type C-h c then the function or arrow keys. The command will return either a function key symbol or character sequence (see the Emacs on-line documentation for an explanation). This works for other keys as well.

10.6 How do I set the X key "translations" for Emacs?

Emacs is not written using the Xt library by default, so there are no "translations" to be set. (We aren't sure how to set such translations if you do build Emacs with Xt; please let us know if you've done this!)

The only way to affect the behavior of keys within Emacs is through xmodmap (outside Emacs) or define-key (inside Emacs). The define-key command should be used in conjunction with the function-key-map map. For instance,

(define-key function-key-map [M-TAB] [?\M-\t])

defines the M-TAB key sequence.

10.7 How do I handle C-s and C-q being used for flow control?

C-s and C-q are used in the XON/XOFF flow control protocol. This messes things up when you're using Emacs over a serial line, because Emacs binds these keys to commands by default. Because Emacs won't honor them as flow control characters, too many of these characters are not passed on and overwhelm output buffers. Sometimes, intermediate software using XON/XOFF flow control will prevent Emacs from ever seeing C-s and C-q.

Possible solutions:

• Disable the use of C-s and C-q for flow control.

  You need to determine the cause of the flow control.

  • your terminal

    Your terminal may use XON/XOFF flow control to have time to display all the characters it receives. For example, VT series terminals do this. It may be possible to turn this off from a setup menu. For example, on a VT220 you may select "No XOFF" in the setup menu. This is also true for some terminal emulation programs on PCs.

    When you turn off flow control at the terminal, you will also need to turn it off at the other end, which might be at the computer you are logged in to or at some terminal server in between.

    If you turn off flow control, characters may be lost; using a printer connected to the terminal may fail. You may be able to get around this problem by modifying the `termcap' entry for your terminal to include extra NUL padding characters.

  • a modem

    If you are using a dialup connection, the modems may be using XON/XOFF flow control. It's not clear how to get around this.

  • a router or terminal server

    Some network box between the terminal and your computer may be using XON/XOFF flow control. It may be possible to make it use some other kind of flow control. You will probably have to ask your local network experts for help with this.

  • tty and/or pty devices

    If your connection to Emacs goes through multiple tty and/or pty devices, they may be using XON/XOFF flow control even when it is not necessary.

    Eirik Fuller writes:

    Some versions of rlogin (and possibly telnet) do not pass flow control characters to the remote system to which they connect. On such systems, Emacs on the remote system cannot disable flow control on the local system. Sometimes `rlogin -8' will avoid this problem.

    One way to cure this is to disable flow control on the local host (the one running rlogin, not the one running rlogind) using the stty command, before starting the rlogin process. On many systems, `stty start u stop u' will do this.

    Some versions of `tcsh' will prevent even this from working. One way around this is to start another shell before starting rlogin, and issue the `stty' command to disable flow control from that shell.

    Use `stty -ixon' instead of `stty start u stop u' on some systems.

• Make Emacs speak the XON/XOFF flow control protocol.

  You can make Emacs treat C-s and C-q as flow control characters by evaluating the form

  (enable-flow-control)

  to unconditionally enable flow control or

  (enable-flow-control-on "vt100" "h19")

  (using your terminal names instead of `vt100' or `h19') to enable selectively. These commands will automatically swap C-s and C-q to C-\ and C-^. Variables can be used to change the default swap keys (flow-control-c-s-replacement and flow-control-c-q-replacement).

  If you are fixing this for yourself, simply put the form in your `.emacs' file. If you are fixing this for your entire site, the best place to put it is in the `site-lisp/site-start.el' file. (Here `site-lisp' is actually a subdirectory of your Emacs installation directory, typically `/usr/local/share/emacs'.) Putting this form in `site-lisp/default.el' has the problem that if the user's `.emacs' file has an error, this will prevent `default.el' from being loaded and Emacs may be unusable for the user, even for correcting their `.emacs' file (unless they're smart enough to move it to another name).

  enable-flow-control can be invoked interactively as well: M-x enable-flow-control RET.

For further discussion of this issue, read the file `etc/PROBLEMS' (in the Emacs source directory when you unpack the Emacs distribution).

10.8 How do I bind C-s and C-q (or any key) if these keys are filtered out?

To bind C-s and C-q, use either enable-flow-control or enable-flow-control-on. See section 10.7 How do I handle C-s and C-q being used for flow control?, for usage and implementation details.

To bind other keys, use keyboard-translate. See section 10.11 How do I swap two keys?, for usage details. To do this for an entire site, you should swap the keys in `site-lisp/site-start.el'. See section 10.7 How do I handle C-s and C-q being used for flow control?, for an explanation of why `site-lisp/default.el' should not be used.

• If you do this for an entire site, the users will be confused by the disparity between what the documentation says and how Emacs actually behaves.

10.9 Why does the Backspace key invoke help?

The Backspace key (on most keyboards) generates ASCII code 8. C-h sends the same code. In Emacs by default C-h invokes help-command. This is intended to be easy to remember since the first letter of `help' is `h'. The easiest solution to this problem is to use C-h (and Backspace) for help and DEL (the Delete key) for deleting the previous character.

For many people this solution may be problematic:

• They normally use Backspace outside of Emacs for deleting the previous character. This can be solved by making DEL the command for deleting the previous character outside of Emacs. On many Unix systems, this command will remap DEL:

  stty erase `^?'

• The user may prefer the Backspace key for deleting the previous character because it is more conveniently located on their keyboard or because they don't even have a separate Delete key. In this case, the Backspace key should be made to behave like Delete. There are several methods.
  • Some terminals (e.g., VT3## terminals) and terminal emulators (e.g., TeraTerm) allow the character generated by the Backspace key to be changed from a setup menu.

  • You may be able to get a keyboard that is completely programmable, or a terminal emulator that supports remapping of any key to any other key.

  • With Emacs 21.1 and later, you can control the effect of the Backspace and Delete keys, on both dumb terminals and a windowed displays, by customizing the option normal-erase-is-backspace-mode, or by invoking M-x normal-erase-is-backspace. See the documentation of these symbols (see section 3.4 Where can I get documentation on Emacs Lisp?) for more info.

  • It is possible to swap the Backspace and DEL keys inside Emacs:

    (keyboard-translate ?\C-h ?\C-?)

    This is the recommended method of forcing Backspace to act as DEL, because it works even in modes which bind DEL to something other than delete-backward-char.

    Similarly, you could remap DEL to act as C-d, which by default deletes forward:

    (keyboard-translate ?\C-? ?\C-d)

    See section 10.11 How do I swap two keys?, for further details about keyboard-translate.

  • Another approach is to switch key bindings and put help on C-x h instead:

    (global-set-key "\C-h" 'delete-backward-char) ;;; overrides mark-whole-buffer (global-set-key "\C-xh" 'help-command)

    This method is not recommended, though: it only solves the problem for those modes which bind DEL to delete-backward-char. Modes which bind DEL to something else, such as view-mode, will not work as you expect when you press the Backspace key. For this reason, we recommend the the keyboard-translate method, shown above.

    Other popular key bindings for help are M-? and C-x ?.

  Don't try to bind DEL to help-command, because there are many modes that have local bindings of DEL that will interfere.

When Emacs 21 or later runs on a windowed display, it binds the Delete key to a command which deletes the character at point, to make Emacs more consistent with keyboard operation on these systems.

For more information about troubleshooting this problem, see section `If DEL Fails to Delete' in The GNU Emacs Manual.

10.10 Why doesn't Emacs look at the `stty' settings for Backspace vs. Delete?

Good question!

10.11 How do I swap two keys?

In Emacs 19, you can swap two keys (or key sequences) by using the keyboard-translate function. For example, to turn C-h into DEL and DEL to C-h, use

(keyboard-translate ?\C-h ?\C-?) ; translate `C-h' to DEL (keyboard-translate ?\C-? ?\C-h) ; translate DEL to `C-h'.

The first key sequence of the pair after the function identifies what is produced by the keyboard; the second, what is matched for in the keymaps.

Keyboard translations are not the same as key bindings in keymaps. Emacs contains numerous keymaps that apply in different situations, but there is only one set of keyboard translations, and it applies to every character that Emacs reads from the terminal. Keyboard translations take place at the lowest level of input processing; the keys that are looked up in keymaps contain the characters that result from keyboard translation.

See Info file `emacs', node `Keyboard Translations'.

10.12 How do I produce C-XXX with my keyboard?

On terminals (but not under X), some common "aliases" are:

C-2 or C-SPC

C-@

C-6

C-^

C-7 or C-S--

C-_

C-4

C-\

C-5

C-]

C-/

C-?

Often other aliases exist; use the C-h c command and try CTRL with all of the digits on your keyboard to see what gets generated. You can also try the C-h w command if you know the name of the command.

10.13 What if I don't have a Meta key?

On many keyboards, the Alt key acts as Meta, so try it.

Instead of typing M-a, you can type ESC a. In fact, Emacs converts M-a internally into ESC a anyway (depending on the value of meta-prefix-char). Note that you press Meta and a together, but with ESC, you press ESC, release it, and then press a.

10.14 What if I don't have an Escape key?

Type C-[ instead. This should send ASCII code 27 just like an Escape key would. C-3 may also work on some terminal (but not under X). For many terminals (notably DEC terminals) F11 generates ESC. If not, the following form can be used to bind it:

;;; F11 is the documented ESC replacement on DEC terminals. (define-key function-key-map [f11] [?\e])

10.15 Can I make my Compose Character key behave like a Meta key?

On a dumb terminal such as a VT220, no. It is rumored that certain VT220 clones could have their Compose key configured this way. If you're using X, you might be able to do this with the xmodmap command.

10.16 How do I bind a combination of modifier key and function key?

With Emacs 19 and later, you can represent modified function keys in vector format by adding prefixes to the function key symbol. For example (from the on-line documentation):

(global-set-key [?\C-x right] 'forward-page)

where `?\C-x' is the Lisp character constant for the character C-x.

You can use the modifier keys Control, Meta, Hyper, Super, Alt, and Shift with function keys. To represent these modifiers, prepend the strings `C-', `M-', `H-', `s-', `A-', and `S-' to the symbol name. Here is how to make H-M-RIGHT move forward a word:

(global-set-key [H-M-right] 'forward-word)

• Not all modifiers are permitted in all situations. Hyper, Super, and Alt are not available on Unix character terminals. Non-ASCII keys and mouse events (e.g. C-= and Mouse-1) also fall under this category.

See section 10.1 How do I bind keys (including function keys) to commands?, for general key binding instructions.

10.17 Why doesn't my Meta key work in an xterm window?

See Info file `emacs', node `Single-Byte Character Support'.

If the advice in the Emacs manual fails, try all of these methods before asking for further help:

• You may have big problems using mwm as your window manager. (Does anyone know a good generic solution to allow the use of the Meta key in Emacs with `mwm'?)

• For X11: Make sure it really is a Meta key. Use xev to find out what keysym your Meta key generates. It should be either Meta_L or Meta_R. If it isn't, use `xmodmap' to fix the situation. If Meta does generate Meta_L or Meta_R, but M-x produces a non-ASCII character, put this in your `~/.Xdefaults' file:

  XTerm*eightBitInput: false XTerm*eightBitOutput: true

• Make sure the pty the xterm is using is passing 8 bit characters. `stty -a' (or `stty everything') should show `cs8' somewhere. If it shows `cs7' instead, use `stty cs8 -istrip' (or `stty pass8') to fix it.

• If there is an rlogin connection between xterm and Emacs, the `-8' argument may need to be given to rlogin to make it pass all 8 bits of every character.

• If Emacs is running on Ultrix, it is reported that evaluating (set-input-mode t nil) helps.

• If all else fails, you can make xterm generate ESC W when you type M-W, which is the same conversion Emacs would make if it got the M-W anyway. In X11R4, the following resource specification will do this:

  XTerm.VT100.EightBitInput: false

  (This changes the behavior of the insert-eight-bit action.)

  With older xterms, you can specify this behavior with a translation:

  XTerm.VT100.Translations: #override \ Meta<KeyPress>: string(0x1b) insert()

  You might have to replace `Meta' with `Alt'.

10.18 Why doesn't my ExtendChar key work as a Meta key under HP-UX 8.0 and 9.x?

This is a result of an internationalization extension in X11R4 and the fact that HP is now using this extension. Emacs assumes that the XLookupString function returns the same result regardless of the Meta key state which is no longer necessarily true. Until Emacs is fixed, the temporary kludge is to run this command after each time the X server is started but preferably before any xterm clients are:

xmodmap -e 'remove mod1 = Mode_switch'

This will disable the use of the extra keysyms systemwide, which may be undesirable if you actually intend to use them.