Your X Environment (Unix Power Tools, 3rd Edition)

6.1. Defining Keys and Button Presses with xmodmap

If you have a Linux system, you may want to use loadkeys instead of xmodmap. loadkeys is designed to set the keymap used by the system as a whole, particularly the console, so use your own judgment. Whatever is done in xmodmap will affect X but not the system console.

An important piece to the X Window System puzzle is filled by the xmodmap client. When the user performs any action -- such as typing a key or moving the mouse -- the server sends a packet of information to the client called an event. These events are then translated into actions by the client. You can use the xmodmap utility to effectively change the event that is reported to the client.

Keysym mappings are mappings of keyboard events at the server level, before the event is sent to the client. Keysyms are the symbols used for each key on the keyboard.

The X server maintains a keymap table, which contains a listing of keys on the keyboard and how they should be interpreted. A client gets the keymap table from the server upon client startup. In most cases, the keymap table is used to interpret keys literally -- when you press the letter "a," a key code is sent to the client that corresponds to the letter "a" in the keymap table.

You can use the xmodmap client to reassign key codes within the keymap table. xmodmap can therefore be used to redefine how the key is interpreted by the client. You probably wouldn't want to translate the alphanumeric keys on the keyboard, but you may want to translate others. For example, you might want to change the BACKSPACE key to DELETE:

% xmodmap -e "keysym BackSpace = Delete"

Another example is if you mistakenly hit the CAPS LOCK key a bit too often, you can disable it completely. Some people might disable CAPS LOCK the low-tech way (by just removing the key from the keyboard!), but you can also render it harmless with the command:

% xmodmap -e "keysym Caps_Lock = "

effectively disabling the CAPS LOCK key entirely. Note that the symbol is now gone and can't be redefined without using the hardware key code.

If you are a DVORAK typist, you can use xmodmap to translate every key on the keyboard and so your QWERTY keyboard behaves like a DVORAK keyboard.

If it ever seems that keystrokes are not working correctly, you can check current keysym settings by running xmodmap with the -pk argument. Use the xev client to determine exactly which key code a key generates on your display. There is also a public domain client called xkeycaps that can be used to display the keysyms for selected keyboards.

You can use xmodmap to add or remove keysyms, or even to redefine the key code associated with that keysym. You can also use it to redefine the mouse buttons, using the pointer keyword. For example, to have the second and third mouse button switch places, you can enter:

% xmodmap -e "pointer = 1 3 2"

If you have a large number of keys to remap, you can put the commands in a file that is read when your X session starts. For example, create a file called .Xmodmap:

! my .Xmodmap file
remove Lock = Caps_Lock
remove Control = Control_L
keysym Control_L = Caps_Lock
keysym Caps_Lock = Control_L
add Lock = Caps_Lock
add Control = Control_L
  ...

These commands effectively reverse your CTRL and CAPS LOCK keys. (CTRL and CAPS LOCK are "switched" on PC and Macintosh keyboards, which can be exceedingly frustrating.) This file can then be read automatically in a X startup script:

  ...
xset b 10 100 10
xrdb $HOME/.Xdefaults
xmodmap $HOME/.Xmodmap
fvwm &
  ...

Alternately, you might want to assign different functions to little-used keys, such as making the tiny "enter" key on Powerbook keyboards into another command key. Remember, too, that some keys may have different names than what you're used to. Sun keyboards, for example, often come with a "meta" key; Macintosh keyboards have an "option" key where PC users expect to find "alt" (though they act the same); and so forth.

On Linux systems, the loadkeys command is often used to make system-level changes to key mappings; it's common to see a variety of keytables already defined and a system default chosen from among them. The system default is often found in /etc/sysconfig/keytable (Red Hat 6 and earlier) or /etc/sysconfig/keyboard (Red Hat 7) or otherwise defined in a directory such as /usr/share/keymaps or /usr/lib/kbd/keymaps. On Debian, the keytable is simply set in /etc/console-tools/default.kmap.gz.

If you have a physical keyboard on which you've switched certain keys, you may want to modify the system-level key mappings as well, so that they are always loaded properly for those times when you need the console to work without any special user-level configuration. For example, on my Red Hat systems, I always modify my keymap (in 6.* and earlier, found in /usr/lib/kbd/keymaps/i386/qwerty/us.kmap.gz, and in 7.*, found in /lib/kbd/keymaps/i386/qwerty/us.kmap.gz) to reflect the fact that the keyboard I carry with me to the co-lo has swapped CAPS LOCK and CTRL keys. Just gunzip the file, edit, and then gzip it back up again. Alternately, you can create a new file from an existing one, make your edits, and specify the new file in your /etc/sysconfig/keytable or /etc/syscongig/keyboard file, as appropriate.

The keymaps directory tree is broken down by the platform (Amiga, Atari, i386, Mac, Sun) and then by the layout type of the keyboard (DVORAK, QWERTY, and various other layouts) and finally by the language or character set. So, there is a U.S. keymap, a U.K. keymap, a Hebrew keymap, and dozens of various others, for all of the systems on which Linux is supported. The files are in a relatively straightforward format:

keycode  54 = Shift
keycode  56 = Alt
keycode  57 = space
        control keycode  57 = nul
keycode  58 = Control
keycode  86 = less             greater          bar
keycode  97 = Control

First comes the keycode keyword, followed by the numeric value of the keysym generated when the key is pressed, and then a keyword (or several) describing the character to be generated when a given keysym is received. Modifiers may precede the keycode keyword, binding the combination of modifier key and keysym to another character value.

NOTE: One danger of using xmodmap is that anything set with xmodmap might remain in effect after you have logged out. This isn't a problem if you use the same X server every day, but be aware that if you use a coworker's X terminal in his absence, he may come back complaining that you broke his CAPS LOCK key. This might happen if you use xdm, since the server is not restarted after every X session. On some X terminals, you can fix this problem by toggling "Retain X Settings" on the X terminal setup menu.

--LM, EP, and SJC

Chapter 6. Your X Environment

Contents:

6.1. Defining Keys and Button Presses with xmodmap