xmodmap

xmodmap

xmodmap is a utility that allows to remap keyboard and mouse keys (change what each key does) when using the X Window System.

Terminology

If you tried reading the xmodmap manpage, you have probably seen passages like this:

The xmodmap program is used to edit and display the keyboard modifier map and keymap table that are used by client applications to convert event key‐ codes into keysyms. It is usually run from the user's session startup script to configure the keyboard according to personal tastes.

What the heck does that all mean? In order to understand the xmodmap manpage, you need to know the following terms first:

• keycode - something (a number) that your keyboard sends to the OS when you press a key. To see which keycode corresponds to which key on your keyboard, use the xev utility.

  Example:

  Here's the output of the xev command when I press the 'a' key on my keyboard:

  KeyPress event, serial 25, synthetic NO, window 0x1000001,
      root 0x111, subw 0x0, time 409681015, (340,260), root:(341,277),
      state 0x0, keycode 38 (keysym 0x61, a), same_screen YES,
      XLookupString gives 1 bytes: (61) "a"
      XmbLookupString gives 1 bytes: (61) "a"
      XFilterEvent returns: False
  
  
  KeyRelease event, serial 28, synthetic NO, window 0x1000001,
      root 0x111, subw 0x0, time 409681102, (340,260), root:(341,277),
      state 0x0, keycode 38 (keysym 0x61, a), same_screen YES,
      XLookupString gives 1 bytes: (61) "a"
      XFilterEvent returns: False
  

  You can see that the keycode for key 'a' is 38.

• keysym - to provide compatibility with a myriad of different keyboards, X introduces a keycode abstraction called a keysym. A keysym usually corresponds to a single keycode, but not necessarily: you can map a single keysym to multiple keycodes. A keysym is also a number, but in addition has an easier-to-remember keysym name. You can get a current mapping of keycodes to keysyms on your machine by doing xmodmap -pke. To see all available keysyms on your machine, do dumpkeys -l.

  Example:

  Using the output above, the keysym for the 'a' key on my machine is 0x61 and its keysym name is also 'a'.

• modifier - one or more keysyms that change the way how X handles a keyboard or a mouse event. Can be thought of as another level of abstraction above keysyms. There are only 8 modifiers in X: shift, lock, control, mod1, mod2, mod3, mod4 and mod5.

  Example:

  Running xmodmap without any command line arguments should produce a listing of modifiers and their corresponding keysyms. Here is the output of xmodmap on my machine (should be fairly common):

  % xmodmap
  xmodmap:  up to 4 keys per modifier, (keycodes in parentheses):
  
  
  shift       Shift_L (0x32),  Shift_R (0x3e)
  lock        Caps_Lock (0x42)
  control     Control_L (0x25),  Control_R (0x69)
  mod1        Alt_L (0x40),  Alt_R (0x6c),  Meta_L (0xcd)
  mod2        Num_Lock (0x4d)
  mod3      
  mod4        Super_L (0x85),  Super_R (0x86),  Super_L (0xce),  Hyper_L (0xcf)
  mod5        ISO_Level3_Shift (0x5c),  Mode_switch (0xcb)
  

  You can see that both Shift_L and Shift_R keysyms, for example, correspond to a single modifier: shift.

Usage

NOTE: this section does not properly explain what we are doing and needs further work.

xmodmap expressions to make Caps_Lock keysym synonymous with Super_L and make Scroll_Lock function like a lock modifier:

! Caps_Lock should no longer be a lock modifier
remove Lock = Caps_Lock
! but Scroll_Lock should be a lock modifier instead
add Lock = Scroll_Lock
! make Caps_Lock the same as Super_L
keysym Caps_Lock = Super_L

References

1. Doug Hogan's Using xev and xmodmap
2. Xmodmap (or how I hate Caps Lock)