Contents

Introduction

On a Linux system using Xorg, there are two types of keyboard values: keycodes and keysyms.

Keycode

The keycode is the numeric representation received by the Linux kernel when a keyboard key or a mouse button is pressed.

Keysym

The keysym is the value assigned to the keycode. For example, when you press the Template:Keypress key on the keyboard, it generates keycode 73. Keycode 73 is mapped to the keysym 0×61 which corresponds to the letter Template:Keypress in the ASCII table.

The keysyms are managed by Xorg in a table of keycodes defining the keycode-keysym relations which is called the keymap table. The command xmodmap can be used to show/modify that key table.

Not all keysyms have to be set, but if you want to assign a latter keysym without assigning earlier ones set them to NoSymbol.

You can check which keymap corresponds to a key on your keyboard with xev.

Tip: There are predefined descriptive keycodes that make mapping additional keys easier (e.g. XF86AudioMute, XF86Mail). Those keycodes can be found in: /usr/include/X11/XF86keysym.h

Custom table

You can create your own map and store it in a configuration file in your home directory (i.e. ~/.Xmodmap):

xmodmap -pke > ~/.Xmodmap

Make the desired changes to ~/.Xmodmap and then test the new configuration with:

xmodmap ~/.Xmodmap

Activate your custom table

If you are using GDM, XDM or KDM, there is no need to source your ~/.Xmodmap manually as these display managers source that file if it is present, whereas startx does not. Therefore, to activate your custom table when starting Xorg, add the following:

~/.xinitrc

if [ -s ~/.Xmodmap ]; then
xmodmap ~/.Xmodmap
fi

Alternatively, edit the global startup script /etc/X11/xinit/xinitrc.

Test changes

You can also make temporary changes for the current session. For example:

If you get the following error message X Error of failed request: BadValue (integer parameter out of range for operation) it means the key you are trying to add is already in another modifier, so remove it using "remove MODIFIERNAME = KEYSYMNAME". Running xmodmap gives you a list of modifiers and keys that are assigned to them.

Reverse Scrolling

The natural scrolling feature available in OS X Lion (mimicking smartphone or tablet scrolling) can be replicated with xmodmap. Since the synaptics driver uses the buttons 4/5/6/7 for up/down/left/right scrolling, you simply need to swap the order of how the buttons are declared in ~/.Xmodmap.