xmodmap(X)

xmodmap -- utility for modifying keymaps in X

Syntax

xmodmap [-display display] [-e expression] [-grammar] [-help] [-n] [-pk] [-pke] [-pm] [-pp] [-quiet] [-verbose] [-] [filename]

Description

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 keycodes into keysyms. It is usually run from the user's session startup script to configure the keyboard according to the individual's preferences.

Options

The following options may be used with xmodmap:

-display display: specifies the host and display to use.
-e expression: specifies an expression to be executed. Any number of expressions may be specified from the command line. For details on expression grammar, see the next section.
-grammar: prints a help message describing the expression grammar used in files and with -e expressions to standard error.
-help: prints a brief description of the command line arguments to standard error whenever an unhandled argument is given to xmodmap.
-n: xmodmap does not change the mappings, but displays which mappings would change.
-pk: prints the current keymap table to standard output.
-pke: prints the current keymap table to standard output in the form of expressions that can be fed back to xmodmap.
-pm: prints the current modifier map to standard output.
-pp: prints the current pointer (mouse cursor button) map to standard output.
-quiet: turns off the verbose logging. This is the default.
-verbose: prints logging information as xmodmap parses its input.
-: reads standard input.
filename: specifies a file containing xmodmap expressions to be executed. This file is usually kept in the user's home directory with a name like .xmodmaprc.

Keywords

The xmodmap program reads a list of expressions and parses them all before attempting to execute any of them. This makes it possible to refer to keysyms that are being redefined in a natural way without having to be concerned about name conflicts.

NOTE: Expressions require spaces around the equal ``='' character.

keycode number = keysymlist: The list of keysyms, keysymlist, is assigned to keycode number in the server's keymap table. number may be specified in decimal, hex or octal and can be determined by running the xev program. For details on the format of the keymap table, see Xsco(X). Usually only one keysym is assigned to a given keycode.
keysym keysymname = keysymlist: The keymap table line containing keysymname is replaced with keysymlist. Note that this procedure may fail if keysymname is bound to multiple keys. For details on the format of the keymap table, see Xsco(X).
clear modifiername: removes all entries in the modifier map for the given modifier. The valid names are ``Shift'', ``Lock'', ``Control'', ``Mod1'', ``Mod2'', ``Mod3'', ``Mod4'' and ``Mod5'' (case does not matter in modifier names). For example, clear Lock removes all any keys bound to the shift lock modifier.
add modifiername = keysymname: adds the given keysyms to the indicated modifier map. The keysym names are evaluated after all input expressions are read to facilitate writing expressions to swap keys (see the ``Examples'' section).
remove modifiername = keysymname: removes the given keysyms from the indicated modifier map. Unlike add, the keysym names are evaluated as the line is read in. This allows you to remove keys from a modifier regardless of whether they were reassigned. If you want to change the binding of a modifier key, you must also remove it from the appropriate modifier map.
pointer = default: sets the pointer map back to its default settings (button 1 generates a code of 1, button 2 generates a 2, and so forth)
pointer = number: sets to pointer map to contain the indicated button codes. The list always starts with the first physical button.

Lines that begin with an exclamation point (!) are comments.

If you want to change the binding of a modifier key, you must also remove it from the appropriate modifier map.

Environment variables

DISPLAY: default host and display number

Examples

Most pointers are designed for right-handed users with the left button corresponding to mouse button 1. Consequently, left-handed users often need to reverse the button codes that are generated so that the right button corresponds to mouse button 1. This could be done on a three-button pointer as follows:

xmodmap -e "pointer = 3 2 1"

Many editor applications support the notion of Meta keys (similar to <Ctrl> keys, except that <Meta> is held down instead of <Ctrl>). For servers that lack a Meta keysym in the default keymap table, a Meta keysym must be added. The following command attaches Meta to the Multi-language key (sometimes labeled <Compose Character>).

xmodmap -e "keysym Multi_key = Multi_key Meta_L"

This command also takes advantage of the fact that applications that need a Meta key simply need to get the keycode and do not require the keysym to be in the first column of the keymap table. Applications looking for a Multi_key (including the default modifier map) consequently do not notice any change.

One of the more simple, yet convenient, uses of xmodmap is to set the keyboard's ``rubout'' key to generate an alternate keysym. This frequently involves exchanging <Bksp> with <Del>. If the ttyModes resource in xterm is also set, all terminal emulator windows will use the same key for erasing characters:

xmodmap -e "keysym BackSpace = Delete"
echo "XTerm*ttyModes: erase ^?" | xrdb -merge

Some keyboards do not automatically generate less than (<) and greater than (>) characters when the comma and period keys are shifted. Xmodmap can compensate for this if the user resets the bindings for the comma and period with the following scripts:

   !
   ! make shift-, be < and shift-. be >
   !
   keysym comma = comma less
   keysym period = period greater

Some users may want to reverse the location of the <Ctrl> and <Shift Lock> keys. They can use xmodmap is to reverse these two keys as follows:

   !
   ! Swap Caps_Lock and Control_L
   !
   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

The keycode command is useful for assigning the same keysym to multiple keycodes. Although unportable, it allows users to write scripts that can reset the keyboard to a known state. The following script sets the <Bksp> key to generate <Del> (as shown above), flushes all existing CapsLock bindings, makes the <CapsLock> key be a control key, make <F5> generate <Esc>, and makes <Break>/<Reset> be a shift lock.

   !
   ! the following keycodes have key caps as listed:
   !
   !     101  Backspace
   !      55  Caps
   !      14  Ctrl
   !      15  Break/Reset
   !      86  Stop
   !      89  F5
   !
   keycode 101 = Delete
   keycode 55 = Control_R
   clear Lock
   add Control = Control_R
   keycode 89 = Escape
   keycode 15 = Caps_Lock
   add Lock = Caps_Lock

Known limitations

When a keycode expression is evaluated, the server generates a MappingNotify event on every client. This can cause some thrashing. All of the changes should be batched together and completed as a group. Clients that receive keyboard input and ignore MappingNotify events do not notice any changes made to keyboard mappings.

xmodmap should generate add and remove expressions automatically whenever a keycode that is already bound to a modifier is changed.