Keyboard in X - I - xmodmap

Remapping Keys

An X key map acts as an interpreter between your hardware (the keyboard) and the software (the applications running on X). It is compiled every time you start X. Three options in the 'Keyboard Section' of '/etc/X11/xorg.conf' determine how it looks like:

Option "XkbRules" "rule"
Option "XkbModel" "model"
Option "XkbLayout" "layout"

The available rules, models and layouts are stored in the respective subdirectories of '/usr/X11R6/lib/X11/xkb'. 'Rules' define key behavior on different hardware platforms (roughly speaking), 'Models' refer to the keyboard model, and 'Layouts' usually define the language mapping of the keyboard. Good news is that this is only of theoretical interest grin.

To see what your current X key map looks like, run

xmodmap -pke | more

A typical 'xmodmap' line looks like this:

keycode 10 = 1 exclam onesuperior exclamdown

This is the mapping for the '1' key on a German keyboard. The first value denotes the 'keycode', a shorthand reference and a very practical thing when it comes to remapping it. The names on the right tell you which 'events' are currently mapped to this key.
The first 'event' is what happens when you simply press the key. The other values tell you (and X) what happens when you use a modifier key in combination with this key: 'SHIFT+1' results in an exclamation mark, the second modifier key (usually that's 'Alt Gr') and '1' result in ¹ and a third modifier key in combination with '1' would provide the ¡, the Spanish exclamation mark.

Notice that 'SHIFT' is regarded as a 'natural' modifier, so when you run

xmodmap -pm

to show the list of modifier keys, the second modifier key is listed as 'mod1'.

To change a key-mapping from the command line, all you need to do is:

xmodmap -e 'keycode keycode=mapping'

Let's say you're a 'vim' freak. 'vim' is an editor and uses the ESC key a lot. Regrettably this key is somewhat inconveniently located. How about switching the position of the CapsLock key with the ESC key?

xmodmap -pke | egrep -i '(caps|esc)'

provides us with the necessary keycodes and the exact value names:

keycode 9 = Escape
keycode 66 = Caps_Lock

Now switch:

xmodmap -e 'keycode 9=Caps_Lock' && xmodmap -e 'keycode 66=Escape'

You should now be able to get the ESC event by pressing the now-former CapsLock key.

These changes however will be lost at the end of your X session. If you want them to be permanent, create a file in your home directory called '.Xmodmap' and put them in there like this:

keycode 9 = Caps_Lock
keycode 66 = Escape

Now all that's left to do is create a script and let it run automatically every time you start X.

Now you might ask: 'Isn't there a more comfortable way to do this? Maybe some graphical tool?' Indeed, there is, and it's called XKeyCaps (RH RPM).
It's old, it's ugly, but it does its job. Note that XKeyCaps does not auto-detect your keyboard settings, you'll have to specify them in the first pop-up window dialog. Furthermore it doesn't change your current key map, all it does is writing the changes you made to an '.Xmodmap-host' file ('Write Output').

section index

Mapping New Keys

The method introduced above only works for keys which have been mapped by X already. But what if X doesn't even seem to recognize the keys, like those 'Multimedia keys' on some newer keyboards?

Enter 'xev', the 'X Event Handler'. 'xev' is part of the X11R6-contrib package which you will likely have to install first. Start 'xev' from a command line window. You will immediately note lots of output in the window every time you press a key or move the mouse in the 'xev' window. The 'xev' output looks a bit cryptic:

~KeyPress event, serial 27, synthetic NO, window 0x2c00001,
root 0x2d, subw 0x0, time 1556344064, (8,-8), root:(12,702),
state 0x10, keycode 36 (keysym 0xff0d, Return), same_screen YES,
XLookupString gives 1 characters:  "

You can discard most of it, however. For you, only this part is interesting:

keycode 36 (keysym 0xff0d, Return)

This tells you all you need to know: the keycode, the keysym and if and how that key is mapped. If you get no output, you can forget using that key in Linux.
As you can see, I pressed the 'Return' button in this example. Now let's see what I get if I press an unmapped button:

~KeyPress event, serial 27, synthetic NO, window 0x2c00001,
root 0x2d, subw 0x0, time 1556704161, (10,-10), root:(14,700),
state 0x10, keycode 234 (keysym 0x0, ~NoSymbol), same_screen YES,
XLookupString gives 0 characters:  ""

This key (it's the 'browser back' key on a Microsoft Internet Pro keyboard) has a keycode, which is good, but does not have a keysym or a mapping ('~NoSymbol'). If you now do something like

xmodmap -e 'keycode 234=e'

pressing this key now returns the letter 'e'. Of course that isn't very useful. What we need is a row of unused, valid values you can map those keys to … '/usr/X11R6/lib/X11/XKeysymDB' might just be what you need. Lines 200ff look very promising. OK, now we've got a list of valid names to map the keys to. Use 'xev' to find out about the other keycodes and then create an '~/.Xmodmap' file to map them to the names you'll find in the 'XKeysymDB' file.

Once you've done that and either sourced the file with 'xmodmap' or created an automatic startup script and restarted X, you should be able to use these keys in the key binding configuration utility of your window manager or environment.

Mandrake Linux user Braden ~MacDonald suggests that "instead of mapping them to whatever is on line 200ff of XKeysymDB, it is a lot easier to just map them to F14, F15, F16, F17, etc."

Mandrake Linux user Linegod has come up with yet another way to configure these keys for KDE.

If you prefer a graphical utility, get lineakd and lineakconf. Install both packages, run

lineakd -l

to list all available keyboards and their short codes, and then

lineakd -c your_keyboard_short_code

to create the basic configuration file in '~/.lineak'.

Now you can start 'Lineakconfig' via the menu ('Configuration - Hardware') and configure your shortcuts. In order for those to work, 'lineakd' must be running in the background ('-b' option).

section index

Next Item: Windows keys and utilities

Related Resources:

man xmodmap
man xev

Revision / Modified: June 13, 2002
Author: Tom Berger

Legal: This page is covered by the GNU Free Documentation License. Standard disclaimers of warranty apply. Copyright LSTB and Mandrakesoft.

KB - Advanced Administration of the System > Keyboard in X - I - xmodmap
Version 1.20 last modified by ptyxs on 08/01/2007 at 21:22


en fr


Creator: AdminWiki on 2004/03/22 09:45
(c) Mandriva 2007