xmodmap(X) 06 January 1993 xmodmap(X) Name 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 prefer- ences. 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 expres- sions 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 xmod- map. -n xmodmap does not change the mappings, but displays which map- pings 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 stan- dard 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 key- code. 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 key- map 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 ``Exam- ples'' 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 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 fre- quently 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 MappingNo- tify 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. See also xev(X), X(X), Xlib documentation on key and pointer events