| 1 |
.\" Copyright (c) 1987, 2010, Oracle and/or its affiliates. All rights reserved. |
| 2 |
.\" |
| 3 |
.\" Permission is hereby granted, free of charge, to any person obtaining a |
| 4 |
.\" copy of this software and associated documentation files (the "Software"), |
| 5 |
.\" to deal in the Software without restriction, including without limitation |
| 6 |
.\" the rights to use, copy, modify, merge, publish, distribute, sublicense, |
| 7 |
.\" and/or sell copies of the Software, and to permit persons to whom the |
| 8 |
.\" Software is furnished to do so, subject to the following conditions: |
| 9 |
.\" |
| 10 |
.\" The above copyright notice and this permission notice (including the next |
| 11 |
.\" paragraph) shall be included in all copies or substantial portions of the |
| 12 |
.\" Software. |
| 13 |
.\" |
| 14 |
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 15 |
.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 16 |
.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
| 17 |
.\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 18 |
.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
| 19 |
.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
| 20 |
.\" DEALINGS IN THE SOFTWARE. |
| 21 |
.\" |
| 22 |
.\" Copyright 1988, 1989, 1990, 1998 The Open Group |
| 23 |
.\" |
| 24 |
.\" Permission to use, copy, modify, distribute, and sell this software and its |
| 25 |
.\" documentation for any purpose is hereby granted without fee, provided that |
| 26 |
.\" the above copyright notice appear in all copies and that both that |
| 27 |
.\" copyright notice and this permission notice appear in supporting |
| 28 |
.\" documentation. |
| 29 |
.\" |
| 30 |
.\" The above copyright notice and this permission notice shall be included |
| 31 |
.\" in all copies or substantial portions of the Software. |
| 32 |
.\" |
| 33 |
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS |
| 34 |
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
| 35 |
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
| 36 |
.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR |
| 37 |
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, |
| 38 |
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR |
| 39 |
.\" OTHER DEALINGS IN THE SOFTWARE. |
| 40 |
.\" |
| 41 |
.\" Except as contained in this notice, the name of The Open Group shall |
| 42 |
.\" not be used in advertising or otherwise to promote the sale, use or |
| 43 |
.\" other dealings in this Software without prior written authorization |
| 44 |
.\" from The Open Group. |
| 45 |
.\" |
| 46 |
.de EX \"Begin example |
| 47 |
.ne 5 |
| 48 |
.if n .sp 1 |
| 49 |
.if t .sp .5 |
| 50 |
.nf |
| 51 |
.in +.5i |
| 52 |
.. |
| 53 |
.de EE |
| 54 |
.fi |
| 55 |
.in -.5i |
| 56 |
.if n .sp 1 |
| 57 |
.if t .sp .5 |
| 58 |
.. |
| 59 |
.TH XMODMAP 1 "xmodmap 1.0.11" "X Version 11" |
| 60 |
.SH NAME |
| 61 |
xmodmap - utility for modifying keymaps and pointer button mappings in X |
| 62 |
.SH SYNOPSIS |
| 63 |
.B xmodmap |
| 64 |
[-options ...] [filename] |
| 65 |
.SH DESCRIPTION |
| 66 |
.PP |
| 67 |
The \fIxmodmap\fP program is used to edit and display the |
| 68 |
keyboard \fImodifier map\fP and \fIkeymap table\fP that are used by client |
| 69 |
applications to convert event keycodes into keysyms. It is usually run from |
| 70 |
the user's session startup script to configure the keyboard according to |
| 71 |
personal tastes. |
| 72 |
.SH OPTIONS |
| 73 |
.PP |
| 74 |
The following options may be used with \fIxmodmap\fP: |
| 75 |
.TP 8 |
| 76 |
.B \-display \fIdisplay\fP |
| 77 |
This option specifies the host and display to use. |
| 78 |
.TP 8 |
| 79 |
.B \-help |
| 80 |
This option indicates that a brief description of the command line arguments |
| 81 |
should be printed on the standard error channel. This will be done whenever an |
| 82 |
unhandled argument is given to |
| 83 |
.I xmodmap. |
| 84 |
.TP 8 |
| 85 |
.B \-grammar |
| 86 |
This option indicates that a help message describing the expression grammar |
| 87 |
used in files and with \-e expressions should be printed on the standard error. |
| 88 |
.TP 8 |
| 89 |
.B \-version |
| 90 |
This option indicates that |
| 91 |
.I xmodmap |
| 92 |
should print its version information and exit. |
| 93 |
.TP 8 |
| 94 |
.B \-verbose |
| 95 |
This option indicates that |
| 96 |
.I xmodmap |
| 97 |
should print logging information as it parses its input. |
| 98 |
.TP 8 |
| 99 |
.B \-quiet |
| 100 |
This option turns off the verbose logging. This is the default. |
| 101 |
.TP 8 |
| 102 |
.B \-n |
| 103 |
This option indicates that |
| 104 |
.I xmodmap |
| 105 |
should not change the mappings, but should display what it would do, like |
| 106 |
\fImake(1)\fP does when given this option. |
| 107 |
.TP 8 |
| 108 |
.B \-e \fIexpression\fB |
| 109 |
This option specifies an expression to be executed. Any number of expressions |
| 110 |
may be specified from the command line. |
| 111 |
.TP 8 |
| 112 |
.B \-pm |
| 113 |
This option indicates that the current modifier map should be printed on the |
| 114 |
standard output. This is the default mode of operation if no other mode |
| 115 |
options are specified. |
| 116 |
.TP 8 |
| 117 |
.B \-pk |
| 118 |
This option indicates that the current keymap table should be printed on the |
| 119 |
standard output. |
| 120 |
.TP 8 |
| 121 |
.B \-pke |
| 122 |
This option indicates that the current keymap table should be printed on the |
| 123 |
standard output in the form of expressions that can be fed back to |
| 124 |
\fIxmodmap\fP. |
| 125 |
.TP 8 |
| 126 |
.B \-pp |
| 127 |
This option indicates that the current pointer map should be printed on the |
| 128 |
standard output. |
| 129 |
.TP 8 |
| 130 |
.B \- |
| 131 |
A lone dash means that the standard input should be used as the input file. |
| 132 |
.PP |
| 133 |
The \fIfilename\fP specifies a file containing \fIxmodmap\fP expressions |
| 134 |
to be executed. This file is usually kept in the user's home directory with |
| 135 |
a name like \fI.xmodmaprc\fP. |
| 136 |
.SH EXPRESSION GRAMMAR |
| 137 |
.PP |
| 138 |
The |
| 139 |
.I xmodmap |
| 140 |
program reads a list of expressions and parses them all before attempting |
| 141 |
to execute any of them. This makes it possible to refer to keysyms that are |
| 142 |
being redefined in a natural way without having to worry as much about name |
| 143 |
conflicts. |
| 144 |
.PP |
| 145 |
The list of keysym names may be found in the header file |
| 146 |
\fI<X11/keysymdef.h>\fP (without the \fIXK_\fP prefix). |
| 147 |
Keysyms matching Unicode characters may be specified as "U0020" to "U007E" |
| 148 |
and "U00A0" to "U10FFFF" for all possible Unicode characters. |
| 149 |
.TP 8 |
| 150 |
.B keycode \fINUMBER\fP = \fIKEYSYMNAME ...\fP |
| 151 |
The list of keysyms is assigned to the indicated keycode |
| 152 |
(which may be specified in decimal, hex or octal and can be determined by |
| 153 |
running the |
| 154 |
.I xev |
| 155 |
program). Up to eight keysyms may be attached to a key, however the last four |
| 156 |
are not used in any major X server implementation. The first keysym is used |
| 157 |
when no modifier key is pressed in conjunction with this key, the second with |
| 158 |
Shift, the third when the Mode_switch key is used with this key and the fourth |
| 159 |
when both the Mode_switch and Shift keys are used. |
| 160 |
.TP 8 |
| 161 |
.B keycode any = \fIKEYSYMNAME ...\fP |
| 162 |
If no existing key has the specified list of keysyms assigned to it, |
| 163 |
a spare key on the keyboard is selected and the keysyms are assigned to it. |
| 164 |
The list of keysyms may be specified in decimal, hex or octal. |
| 165 |
.TP 8 |
| 166 |
.B keysym \fIKEYSYMNAME\fP = \fIKEYSYMNAME ...\fP |
| 167 |
The \fIKEYSYMNAME\fP on the left hand side is translated into matching keycodes |
| 168 |
used to perform the corresponding set of \fBkeycode\fP expressions. Note that |
| 169 |
if the same keysym is bound to multiple keys, the expression is executed |
| 170 |
for each matching keycode. |
| 171 |
.TP 8 |
| 172 |
.B clear \fIMODIFIERNAME\fP |
| 173 |
This removes all entries in the modifier map for the given modifier, where |
| 174 |
valid name are: |
| 175 |
.BR Shift , |
| 176 |
.BR Lock , |
| 177 |
.BR Control , |
| 178 |
.BR Mod1 , |
| 179 |
.BR Mod2 , |
| 180 |
.BR Mod3 , |
| 181 |
.BR Mod4 , |
| 182 |
and \fBMod5\fP (case |
| 183 |
does not matter in modifier names, although it does matter for all other |
| 184 |
names). For example, ``clear Lock'' will remove |
| 185 |
all any keys that were bound to the shift lock modifier. |
| 186 |
.TP 8 |
| 187 |
.B add \fIMODIFIERNAME\fP = \fIKEYSYMNAME ...\fP |
| 188 |
This adds all keys containing the given keysyms to the indicated modifier map. |
| 189 |
The keysym names |
| 190 |
are evaluated after all input expressions are read to make it easy to write |
| 191 |
expressions to swap keys (see the EXAMPLES section). |
| 192 |
.TP 8 |
| 193 |
.B remove \fIMODIFIERNAME\fP = \fIKEYSYMNAME ...\fP |
| 194 |
This removes all keys containing the given keysyms from the indicated |
| 195 |
modifier map. Unlike |
| 196 |
.B add, |
| 197 |
the keysym names are evaluated as the line is read in. This allows you to |
| 198 |
remove keys from a modifier without having to worry about whether or not they |
| 199 |
have been reassigned. |
| 200 |
.TP 8 |
| 201 |
.B "pointer = default" |
| 202 |
This sets the pointer map back to its default settings (button 1 generates a |
| 203 |
code of 1, button 2 generates a 2, etc.). |
| 204 |
.TP 8 |
| 205 |
.B pointer = \fINUMBER ...\fP |
| 206 |
This sets the pointer map to contain the indicated button codes. The list |
| 207 |
always starts with the first physical button. Setting a button code to 0 |
| 208 |
disables events from that button. |
| 209 |
.PP |
| 210 |
Lines that begin with an exclamation point (!) are taken as comments. |
| 211 |
.PP |
| 212 |
If you want to change the binding of a modifier key, you must also remove it |
| 213 |
from the appropriate modifier map. |
| 214 |
.SH EXAMPLES |
| 215 |
.PP |
| 216 |
Many pointers are designed such that the first button is pressed using the |
| 217 |
index finger of the right hand. People who are left-handed frequently find |
| 218 |
that it is more comfortable to reverse the button codes that get generated |
| 219 |
so that the primary button is pressed using the index finger of the left hand. |
| 220 |
This could be done on a 3 button pointer as follows: |
| 221 |
.EX |
| 222 |
% xmodmap -e "pointer = 3 2 1" |
| 223 |
.EE |
| 224 |
.PP |
| 225 |
Many applications support the notion of Meta keys (similar to Control |
| 226 |
keys except that Meta is held down instead of Control). However, |
| 227 |
some servers do not have a Meta keysym in the default keymap table, so one |
| 228 |
needs to be added by hand. |
| 229 |
The following command will attach Meta to the Multi-language key (sometimes |
| 230 |
labeled Compose Character). It also takes advantage of the fact that |
| 231 |
applications that need a Meta key simply need to get the keycode and don't |
| 232 |
require the keysym to be in the first column of the keymap table. This |
| 233 |
means that applications that are looking for a Multi_key (including the |
| 234 |
default modifier map) won't notice any change. |
| 235 |
.EX |
| 236 |
% xmodmap -e "keysym Multi_key = Multi_key Meta_L" |
| 237 |
.EE |
| 238 |
.PP |
| 239 |
Similarly, some keyboards have an Alt key but no Meta key. |
| 240 |
In that case the following may be useful: |
| 241 |
.EX |
| 242 |
% xmodmap -e "keysym Alt_L = Meta_L Alt_L" |
| 243 |
.EE |
| 244 |
.PP |
| 245 |
One of the more simple, yet convenient, uses of \fIxmodmap\fP is to set the |
| 246 |
keyboard's "rubout" key to generate an alternate keysym. This frequently |
| 247 |
involves exchanging Backspace with Delete to be more comfortable to the user. |
| 248 |
If the \fIttyModes\fP resource in \fIxterm\fP is set as well, all terminal |
| 249 |
emulator windows will use the same key for erasing characters: |
| 250 |
.EX |
| 251 |
% xmodmap -e "keysym BackSpace = Delete" |
| 252 |
% echo "XTerm*ttyModes: erase ^?" | xrdb -merge |
| 253 |
.EE |
| 254 |
.PP |
| 255 |
Some keyboards do not automatically generate less than and greater than |
| 256 |
characters when the comma and period keys are shifted. This can be remedied |
| 257 |
with \fIxmodmap\fP by resetting the bindings for the comma and period with |
| 258 |
the following scripts: |
| 259 |
.EX |
| 260 |
! |
| 261 |
! make shift-, be < and shift-. be > |
| 262 |
! |
| 263 |
keysym comma = comma less |
| 264 |
keysym period = period greater |
| 265 |
.EE |
| 266 |
.PP |
| 267 |
One of the more irritating differences between keyboards is the location of the |
| 268 |
Control and CapsLock keys. A common use of \fIxmodmap\fP is to swap these |
| 269 |
two keys as follows: |
| 270 |
.EX |
| 271 |
! |
| 272 |
! Swap Caps_Lock and Control_L |
| 273 |
! |
| 274 |
remove Lock = Caps_Lock |
| 275 |
remove Control = Control_L |
| 276 |
keysym Control_L = Caps_Lock |
| 277 |
keysym Caps_Lock = Control_L |
| 278 |
add Lock = Caps_Lock |
| 279 |
add Control = Control_L |
| 280 |
.EE |
| 281 |
.PP |
| 282 |
This example can be run again to swap the keys back to their previous |
| 283 |
assignments. |
| 284 |
.PP |
| 285 |
The \fIkeycode\fP command is useful for assigning the same keysym to |
| 286 |
multiple keycodes. Although unportable, it also makes it possible to write |
| 287 |
scripts that can reset the keyboard to a known state. The following script |
| 288 |
sets the backspace key to generate Delete (as shown above), flushes all |
| 289 |
existing caps lock bindings, makes the CapsLock |
| 290 |
key be a control key, make F5 generate Escape, and makes Break/Reset be a |
| 291 |
shift lock. |
| 292 |
.EX |
| 293 |
! |
| 294 |
! On the HP, the following keycodes have key caps as listed: |
| 295 |
! |
| 296 |
! 101 Backspace |
| 297 |
! 55 Caps |
| 298 |
! 14 Ctrl |
| 299 |
! 15 Break/Reset |
| 300 |
! 86 Stop |
| 301 |
! 89 F5 |
| 302 |
! |
| 303 |
keycode 101 = Delete |
| 304 |
keycode 55 = Control_R |
| 305 |
clear Lock |
| 306 |
add Control = Control_R |
| 307 |
keycode 89 = Escape |
| 308 |
keycode 15 = Caps_Lock |
| 309 |
add Lock = Caps_Lock |
| 310 |
.EE |
| 311 |
.SH ENVIRONMENT |
| 312 |
.PP |
| 313 |
.TP 8 |
| 314 |
.B DISPLAY |
| 315 |
to get default host and display number. |
| 316 |
.SH SEE ALSO |
| 317 |
X(7), xev(1), setxkbmap(1), |
| 318 |
XStringToKeysym(3), |
| 319 |
\fIXlib\fP documentation on key and pointer events |
| 320 |
.SH BUGS |
| 321 |
.PP |
| 322 |
Every time a \fBkeycode\fP expression is evaluated, the server generates |
| 323 |
a \fIMappingNotify\fP event on every client. This can cause some thrashing. |
| 324 |
All of the changes should be batched together and done at once. |
| 325 |
Clients that receive keyboard input and ignore \fIMappingNotify\fP events |
| 326 |
will not notice any changes made to keyboard mappings. |
| 327 |
.PP |
| 328 |
.I Xmodmap |
| 329 |
should generate "add" and "remove" expressions automatically |
| 330 |
whenever a keycode that is already bound to a modifier is changed. |
| 331 |
.PP |
| 332 |
There should be a way to have the |
| 333 |
.I remove |
| 334 |
expression accept keycodes as well as keysyms for those times when you really |
| 335 |
mess up your mappings. |
| 336 |
.SH AUTHOR |
| 337 |
Jim Fulton, MIT X Consortium, rewritten from an earlier version by |
| 338 |
David Rosenthal of Sun Microsystems. |
| 339 |
|