X Version 11 (Release 6.1)
utility for modifying keymaps in X
xmodmap [-display display]
[-e expression] [-grammar] [-help]
[-n] [-pk] [-pke] [-pm]
[-pp] [-quiet] [-verbose] [-]
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.
The following options may be used with xmodmap:
specifies the host and display to use.
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.
prints a help message describing the expression grammar used in files
and with -e expressions to standard error.
prints a brief description of the command line arguments to standard
error whenever an unhandled argument is given to xmodmap.
does not change the mappings, but displays which mappings would change.
prints the current keymap table to standard output.
prints the current keymap table to
standard output in the form of expressions that can be fed back to
prints the current modifier map to standard output.
prints the current pointer (mouse cursor button) map to
turns off the verbose logging. This is the default.
prints logging information as xmodmap parses its input.
reads standard input.
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.
keycode any = keysymname
If no existing key has the specified list of keysyms assigned to it,
a spare key on the keyboard is selected and the keysyms are assigned to it.
The list of keysyms may be specified in decimal, hex or octal.
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
Expressions require spaces around the equal ``='' character.
Lines that begin with an exclamation point (!) are comments.
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
For details on the format of the keymap table,
Usually only one keysym is assigned to a given keycode.
keysym keysymname = keysymlist
The keymap table line containing keysymname is replaced
Note that this procedure may fail
if keysymname is bound to multiple keys.
For details on the format of the keymap table,
removes all entries in the modifier map for the
The valid names are ``Shift'', ``Lock'',
``Control'', ``Mod1'', ``Mod2'', ``Mod3'',
``Mod4'' and ``Mod5'' (case does
not matter in modifier names).
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
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
If you want to change the binding of a modifier key, you must also remove it
from the appropriate modifier map.
default host and display number
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.
should generate add and remove expressions automatically
whenever a keycode that is already bound to a modifier is changed.
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 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.
Similarly, some keyboards have an <Alt> key but no Meta key.
In that case the following may be useful:
xmodmap -e "keysym Alt_L = Meta_L Alt_L"
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
add Control = Control_R
keycode 89 = Escape
keycode 15 = Caps_Lock
add Lock = Caps_Lock
Xlib documentation on key and pointer events
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004