Debian Codegraph @

upstream/fedora-44/man5/keymaps.5

raw
1 .\" keymaps.5 - Copyright (C) Andries Brouwer 1998
2 .\" May be freely distributed.
3 .\" @(#)keymaps.5 1.10 940130 aeb
4 .TH KEYMAPS 5 "24 April 1998" "kbd"
5 .SH NAME
6 keymaps \- keyboard table descriptions for loadkeys and dumpkeys
7 .SH DESCRIPTION
8 .IX "keymaps" "" "\fLkeymaps\fR \(em keyboard table descriptions for loadkeys and dumpkeys" ""
9 .IX "loadkeys" "keyboard table descriptions" "\fLloadkeys\fR" "keyboard table descriptions"
10 .IX "dumpkeys" "keyboard table descriptions" "\fLdumpkeys\fR" "keyboard table descriptions"
11 .IX keyboard "table descriptions for loadkeys and dumpkeys" keyboard "table descriptions for \fLloadkeys\fR and \fLdumpkeys\fR"
12 .IX "translation tables"
13 .LP
14 These files are used by
15 .BR loadkeys (1)
16 to modify the translation tables used by the kernel keyboard driver
17 and generated by
18 .BR dumpkeys (1)
19 from those translation tables.
20 .LP
21 The format of these files is vaguely similar to the one accepted by
22 .BR xmodmap (1).
23 The file consists of charset or key or string definition lines
24 interspersed with comments.
25 .LP
26 Comments are introduced with
27 .B !
28 or
29 .B #
30 characters and continue to the end of the line. Anything following one
31 of these characters on that line is ignored. Note that comments need
32 not begin from column one as with
33 .BR xmodmap (1).
34 .LP
35 The syntax of keymap files is line oriented; a complete definition
36 must fit on a single logical line. Logical lines can, however, be split
37 into multiple physical lines by ending each subline with the backslash
38 character (\\).
39 .SH "INCLUDE FILES"
40 A keymap can include other keymaps using the syntax
41 .LP
42 .RS
43 include "pathname"
44 .RE
45 .LP
46 .SH "CHARSET DEFINITIONS"
47 A character set definition line is of the form:
48 .LP
49 .RS
50 .EX
51 charset "iso-8859-x"
52 .EE
53 .RE
54 .LP
55 It defines how following keysyms are to be interpreted.
56 For example, in iso-8859-1 the symbol mu (or micro) has code 0265,
57 while in iso-8859-7 the letter mu has code 0354.
58 .SH "COMPLETE KEYCODE DEFINITIONS"
59 Each complete key definition line is of the form:
60 .LP
61 .RS
62 .nf
63 .BI keycode " keynumber " = " keysym keysym keysym" \fR...
64 .fi
65 .RE
66 .LP
67 .I keynumber
68 is the internal identification number of the key, roughly equivalent to
69 the scan code of it.
70 .I keynumber
71 can be given in decimal, octal or hexadecimal notation.
72 Octal is denoted by a leading zero and hexadecimal by the prefix
73 .B 0x.
74 .LP
75 Each of the
76 .I keysyms
77 represent keyboard actions, of which up to 256 can be bound to a single
78 key. The actions available include outputting character codes or
79 character sequences, switching consoles or keymaps, booting the machine
80 etc. (The complete list can be obtained from
81 .BR dumpkeys (1)
82 by saying
83 .B " dumpkeys -l"
84 \&.)
85 .LP
86 Each
87 .I keysym
88 may be prefixed by a '+' (plus sign), in which case this keysym is treated
89 as a "letter" and therefore affected by the "CapsLock" the same way as by
90 "Shift" (to be correct, the CapsLock inverts the Shift state).
91 The ASCII letters ('a'-'z' and 'A'-'Z') are made CapsLock'able by default.
92 If Shift+CapsLock should not produce a lower case symbol, put lines like
93 .LP
94 .RS
95 .nf
96 .B "keycode 30 = +a A"
97 .fi
98 .RE
99 .LP
100 in the map file.
101 .LP
102 Which of the actions bound to a given key is taken when it is pressed
103 depends on what modifiers are in effect at that moment.
104 The keyboard driver supports 9 modifiers. These modifiers are labeled
105 (completely arbitrarily) Shift, AltGr, Control, Alt, ShiftL, ShiftR,
106 CtrlL, CtrlR and CapsShift.
107 Each of these modifiers has an associated weight of power of two
108 according to the following table:
109
110 .ev table
111 .LP
112 .RS
113 .TP 20
114 .I modifier
115 .I weight
116 .P
117 .ta T 24R
118 Shift 1
119 .br
120 AltGr 2
121 .br
122 Control 4
123 .br
124 Alt 8
125 .br
126 ShiftL 16
127 .br
128 ShiftR 32
129 .br
130 CtrlL 64
131 .br
132 CtrlR 128
133 .br
134 CapsShift 256
135 .RE
136 .LP
137 .ev
138 The effective action of a key is found out by adding up the weights of
139 all the modifiers in effect. By default, no modifiers are in effect, so
140 action number zero, i.e. the one in the first column in a key definition
141 line, is taken when the key is pressed or released. When e.g. Shift and
142 Alt modifiers are in effect, action number nine (from the 10th column)
143 is the effective one.
144 .LP
145 Changing the state of what modifiers are in effect can be achieved by
146 binding appropriate key actions to desired keys. For example, binding
147 the symbol Shift to a key sets the Shift modifier in effect when that
148 key is pressed and cancels the effect of that modifier when the key is
149 released. Binding AltGr_Lock to a key sets AltGr in effect when the key
150 is pressed and cancels the effect when the key is pressed again.
151 (By default Shift, AltGr, Control and Alt are bound to the keys that bear
152 a similar label; AltGr may denote the right Alt key.)
153 .LP
154 Note that you should be very careful when binding the modifier keys,
155 otherwise you can end up with an unusable keyboard mapping. If you for
156 example define a key to have Control in its first column and leave the
157 rest of the columns to be VoidSymbols, you're in trouble. This is
158 because pressing the key puts Control modifier in effect and the
159 following actions are looked up from the fifth column (see the table
160 above). So, when you release the key, the action from the fifth column
161 is taken. It has VoidSymbol in it, so nothing happens. This means that
162 the Control modifier is still in effect, although you have released the key.
163 Re-pressing and releasing the key has no effect. To avoid this,
164 you should always define all the columns to have the same modifier
165 symbol. There is a handy short-hand notation for this, see below.
166 .LP
167 .I keysyms
168 can be given in decimal, octal, hexadecimal, unicode or symbolic notation.
169 The numeric notations use the same format as with
170 .IR keynumber .
171 Unicode notation is "U+" followed by four hexadecimal digits.
172 The symbolic notation resembles that used by
173 .BR xmodmap (1).
174 Notable differences are the number symbols. The numeric
175 symbols '0', ..., '9' of
176 .BR xmodmap (1)
177 are replaced with the corresponding words 'zero', 'one', ... 'nine' to
178 avoid confusion with the numeric notation.
179 .LP
180 It should be noted that using numeric notation for the
181 .I keysyms
182 is highly unportable as the key action numbers may vary from one kernel
183 version to another and the use of numeric notations is thus strongly
184 discouraged. They are intended to be used only when you know there is a
185 supported keyboard action in your kernel for which your current version
186 of
187 .BR loadkeys (1)
188 has no symbolic name.
189 .LP
190 There is a number of short-hand notations to add readability and reduce
191 typing work and the probability of typing-errors.
192 .LP
193 First of all, you can give a map specification line, of the form
194 .LP
195 .RS
196 .EX
197 keymaps 0-2,4-5,8,12
198 .EE
199 .RE
200 .LP
201 to indicate that the lines of the keymap will not specify all 256 columns,
202 but only the indicated ones. (In the example: only the plain, Shift,
203 AltGr, Control, Control+Shift, Alt and Control+Alt maps, that is, 7 columns
204 instead of 256.)
205 When no such line is given, the keymaps 0-M will be defined, where
206 M+1 is the maximum number of entries found in any definition line.
207 .LP
208 Next, you can leave off any trailing VoidSymbol entries from a key
209 definition line. VoidSymbol denotes a keyboard action which produces no
210 output and has no other effects either. For example, to define key
211 number 30 to output 'a' unshifted, 'A' when pressed with Shift and do
212 nothing when pressed with AltGr or other modifiers, you can write
213 .LP
214 .RS
215 .nf
216 keycode 30 = a A
217 .fi
218 .RE
219 .LP
220 instead of the more verbose
221 .LP
222 .RS
223 .nf
224 keycode 30 = a A VoidSymbol VoidSymbol \\
225 VoidSymbol VoidSymbol VoidSymbol ...
226 .fi
227 .RE
228 .LP
229 For added convenience, you can usually get off with still more terse
230 definitions. If you enter a key definition line with only and exactly
231 one action code after the equals sign, it has a special meaning. If the
232 code (numeric or symbolic) is not an ASCII letter, it means the code
233 is implicitly replicated through all columns being defined.
234 If, on the other hand, the action code is an ASCII character in the
235 range 'a', ..., 'z' or 'A', ..., 'Z' in the ASCII collating sequence,
236 the following definitions are made for the different modifier combinations,
237 provided these are actually being defined.
238 (The table lists the two possible cases:
239 either the single action code is a lower case letter,
240 denoted by 'x' or an upper case letter, denoted by 'Y'.)
241 .LP
242 .RS 4
243 .TP 24
244 .I modifier
245 .I symbol
246 .TP 24
247 none
248 x Y
249 .PD 0
250 .TP 24
251 Shift
252 X y
253 .TP 24
254 AltGr
255 x Y
256 .TP 24
257 Shift+AltGr
258 X y
259 .TP 24
260 Control
261 Control_x Control_y
262 .TP 24
263 Shift+Control
264 Control_x Control_y
265 .TP 24
266 AltGr+Control
267 Control_x Control_y
268 .TP 24
269 Shift+AltGr+Control
270 Control_x Control_y
271 .TP 24
272 Alt
273 Meta_x Meta_Y
274 .TP 24
275 Shift+Alt
276 Meta_X Meta_y
277 .TP 24
278 AltGr+Alt
279 Meta_x Meta_Y
280 .TP 24
281 Shift+AltGr+Alt
282 Meta_X Meta_y
283 .TP 24
284 Control+Alt
285 Meta_Control_x Meta_Control_y
286 .TP 24
287 Shift+Control+Alt
288 Meta_Control_x Meta_Control_y
289 .TP 24
290 AltGr+Control+Alt
291 Meta_Control_x Meta_Control_y
292 .TP 24
293 Shift+AltGr+Control+Alt
294 Meta_Control_x Meta_Control_y
295 .PD
296 .RE
297 .LP
298 .SH "SINGLE MODIFIER DEFINITIONS"
299 All the previous forms of key definition lines always define all the M+1
300 possible modifier combinations being defined, whether the line actually
301 contains that many action codes or not.
302 There is, however, a variation of the definition
303 syntax for defining only single actions to a particular modifier
304 combination of a key. This is especially useful, if you load a keymap
305 which doesn't match your needs in only some modifier combinations, like
306 AltGr+function keys. You can then make a small local file redefining
307 only those modifier combinations and loading it after the main file.
308 The syntax of this form is:
309 .LP
310 .BR "" { " plain " "| <modifier sequence> } " keycode
311 .I keynumber
312 .B =
313 .I keysym
314 .LP
315 , e.g.,
316 .RS
317 .EX
318 .nf
319 plain keycode 14 = BackSpace
320 control alt keycode 83 = Boot
321 alt keycode 105 = Decr_Console
322 alt keycode 106 = Incr_Console
323 .fi
324 .EE
325 .RE
326 Using "plain" will define only the base entry of a
327 key (i.e. the one with no modifiers in effect) without affecting the
328 bindings of other modifier combinations of that key.
329 .SH "STRING DEFINITIONS"
330 In addition to comments and key definition lines, a keymap can
331 contain string definitions. These are used to define what each function
332 key action code sends. The syntax of string definitions is:
333 .LP
334 .RS
335 .B string
336 .I keysym
337 .B =
338 .BI """" text """"
339 .RE
340 .LP
341 .I text
342 can contain literal characters, octal character codes in the format of
343 backslash followed by up to three octal digits, and the three escape
344 sequences \fB\\n\fP, \fB\\\\\fP, and \fB\\"\fP,
345 for newline, backslash and quote, respectively.
346 .SH "COMPOSE DEFINITIONS"
347 Then there may also be compose definitions. They have syntax
348 .LP
349 .RS
350 .BI "compose '" char "' '" char "' to '" char "'"
351 .RE
352 and describe how two bytes are combined to form a third one
353 (when a dead accent or compose key is used).
354 This is used to get accented letters and the like on a standard
355 keyboard.
356 .SH ABBREVIATIONS
357 Various abbreviations can be used with kbd-0.96 and later.
358 .TP
359 .B "strings as usual"
360 Defines the usual values of the strings (but not the keys
361 they are bound to).
362 .TP
363 \fBcompose as usual for "iso-8859-1"\fP
364 Defines the usual compose combinations.
365 .LP
366 To find out what
367 .I keysyms
368 there are available for use in keymaps, use the command
369 .LP
370 .RS
371 .nf
372 .B dumpkeys --long-info
373 .fi
374 .RE
375 .LP
376 Unfortunately, there is currently no description of what each symbol
377 does. It has to be guessed from the name or figured out from the kernel
378 sources.
379 .LP
380 .SH EXAMPLES
381 (Be careful to use a keymaps line, like the first line of `dumpkeys`,
382 or "keymaps 0-15" or so.)
383 .LP
384 The following entry exchanges the left Control key and the Caps Lock
385 key on the keyboard:
386 .LP
387 .RS
388 .nf
389 keycode 58 = Control
390 keycode 29 = Caps_Lock
391 .fi
392 .RE
393 .LP
394 Key number 58 is normally the Caps Lock key, and key number 29 is
395 normally the Control key.
396 .LP
397 The following entry sets the Shift and Caps Lock keys to behave more
398 nicely, like in older typewriters. That is, pressing Caps Lock key once
399 or more sets the keyboard in CapsLock state and pressing either of the
400 Shift keys releases it.
401 .LP
402 .RS
403 .nf
404 keycode 42 = Uncaps_Shift
405 keycode 54 = Uncaps_Shift
406 keycode 58 = Caps_On
407 .fi
408 .RE
409 .LP
410 The following entry sets the layout of the edit pad in the enhanced
411 keyboard to be more like that in the VT200 series terminals:
412 .LP
413 .RS
414 .nf
415 keycode 102 = Insert
416 keycode 104 = Remove
417 keycode 107 = Prior
418 shift keycode 107 = Scroll_Backward
419 keycode 110 = Find
420 keycode 111 = Select
421 control alt keycode 111 = Boot
422 control altgr keycode 111 = Boot
423 .fi
424 .RE
425 .LP
426 Here's an example to bind the string "du\\ndf\\n" to the key AltGr-D. We use
427 the "spare" action code F100 not normally bound to any key.
428 .LP
429 .RS
430 .nf
431 altgr keycode 32 = F100
432 string F100 = "du\\ndf\\n"
433 .RE
434 .LP
435 .SH AUTHORS
436 Andries Brouwer <[email protected]>
437 .LP
438 .SH "SEE ALSO"
439 .BR loadkeys (1),
440 .BR dumpkeys (1),
441 .BR showkey (1),
442 .BR xmodmap (1)