console-keyboard-map 5 file formats nosh console-keyboard-map format of keyboard map files for user-space virtual terminals Unfortunately, Linux and the BSDs do not agree on a single set of keycode numbers, and cannot share one another's keyboard layout definitions. So the user-space virtual terminal subsystem uses its own portable keyboard map file, stored in machine-readable form, with a common keyboard matrix that is a superset of USB HID keyboards, PC/AT keyboards, and others. A keyboard input realizer (console-ugen-hid-realizer1, console-evdev-realizer1, console-uhid-realizer1, console-wscons-realizer1, or console-pcat-keyboard-realizer1) translates from the non-portable Linux and BSD keyboard codes, or (portable, but insufficient) USB HID "usages", provided by the various devices to this set of common codes. It then uses a portable keyboard map, supplied to it, to determine what actions to take; which may range from internal state changes to sending key events to an input FIFO of a user-space virtual terminal. FreeBSD keymaps can be compiled from the BSD/SCO kbdmap5 human-readable form to this portable machine-readable form with the console-convert-kbdmap1 command. There is no tool for converting Linux keymaps, which are syntactically a lot more complex than BSD/SCO ones, requiring complex parsers for pre-processing include files and X11-like or old 8-bit non-Unicode features that aren't applicable to user-space virtual terminals anyway (e.g. composition is handled by console-input-method1 and CIN files, not keymaps, and both user-space virtual terminals and BSD/SCO keymaps are native Unicode). See the terminal resources section of the nosh Guide for detailed information about systems where FreeBSD keymaps are not supplied with the operating system. In machine-readable form, a map is a simple 2-dimensional array of 96-octet map entries, representing 17 "rows" of 16 "columns" per row, in row-major order. This is the "matrix" of a common keyboard denoted by the aforementioned common codeset. It is modelled on the ISO 9995 keyboard standard. It has extra rows for the many USB keys not covered by ISO 9995. It also has accomodations for the keys that have different physical ISO 9995 positions on 101/104-key, 102/105-key, 103/106-key, 104/107-key, and 106/109-key keyboards but that are actually the same PC/AT or USB key code; and vice versa, keys that are in the same physical locations on those keyboards that are actually different PC/AT or USB key codes. These rows are, in order: ISO 9995 "E" row The ⎋ Escape key; positions E01 to E12; the additional key from the 106/109-key PC keyboard at E13; one more unused position; then position E14. E00 is a source of much confusion. On PC/XT keyboards it was the ⎋ Escape key. In BSD/SCO keyboard map files (c.f. kbdmap5) it remains at E00. It is at E00 here. IBM PC/AT, Model M, and Windows keyboards move ⎋ Escape to the function row, and misleadingly place the language-variant key (called grave in the USB specification) at position E00. That key is here is grouped with other similar keys in the "C" row after C11 (q.v.), where the IBM PC/AT keyboard code numbering in reality placed it. ISO 9995 "D" row Positions D00 to D12; two unused positions; then position D14. The key sometimes found at position D13 is grouped with other similar keys in the third row, where most IBM PC/AT layouts actually place it. ISO 9995 "C" row An unused position; positions C01 to C11; the language-variant key usually found in position E00; the key usually found in position C12; then two more unused positions. The key usually found at position C12 on 102/105-key, 103/106-key, 104/107-key, and 106/109-key PC keyboards is sometimes found in position D13 on 101/104-key PC keyboards, but is placed in this row per the majority. The language-variant (a.k.a. grave) key from 106/109-key PC keyboards, physically at E00 but (in accordance with the true IBM PC/AT numbering under the covers) placed here, is engraved misleadingly on those keyboards, implying that it is is USB's 半角/全角 (Zenkaku/Hankaku) key. That latter in fact is a different key in the USB specification, and is in the sixth row. Despite the engraving, on 106/109-key PC keyboards the key is still the language-variant (grave) key in hardware and on the wire from the keyboard. ISO 9995 "B" row An unused position; the additional "Europe 2" key from the 102/105-key and 104/107-key PC keyboards at B00; positions B01 to B10; the additional key from the 104/107-key and 106/109-key PC keyboards at B11; and three more unused positions. Modifier keys that are on this row per ISO 9995 are factored out into a separate modifiers row. Modifiers 1st ⇧ Level 2 shift; 2nd ⇧ Level 2 shift; ⇮ Level 3 shift; 1st ⎈ Control; 2nd ⎈ Control; 3rd ⎈ Control; 1st ⌘ Super; 2nd ⌘ Super; 1st ⎇ Alt; three unused positions; ⇬ Caps Lock; Scroll Lock; ⇭ Num Lock; and an unused position. ⇮ Level 3 shift is also known as ⌥ Option or AltGr, and there is only 1 such key; as there is only 1 ⎇ Alt. No keyboard has two of either. The 3rd ⎈ Control key is fakery employed by PC/AT and later keyboards for compound sequences that used to involve an actual ⎈ Control key on the PC/XT keyboard, so that those compound sequences did not erroneously affect the recorded state of the modifiers for the two real ⎈ Control keys. This has no USB HID equivalent. ISO 9995 "A" row An unused position; the ひらツな/カタカナ/ローマ字 (Hiragana/Katakana/Romaji) key from USB; the 半角/全角 (Zenkaku/Hankaku) key from USB; the ひらツな (Hiragana) key from USB; the カタカナ (Katakana) key from USB; the 変換 (Henkan) or XFER key from the 106/109-key PC keyboard; the 無変換 (Muhenkan) or NFER key from the 106/109-key PC keyboard; an unused position; the 한/영 (Han/Yeong) key from the 103/106-key PC keyboard; the 変換 (Kanji) or 한영 (Hanja) key, from the 106/109-key or 103/106-key PC keyboards; three unused positions; Alternate Erase; ⎄ Compose; and ␣ Space. Modifier keys that are on this row per ISO 9995 are factored out into a separate modifiers row, so as not to cause ambiguity with the various additional input method keys that can be on this row. The 半角/全角 (Zenkaku/Hankaku) key from USB is not to be confused with the PC keyboard key at E00, which is a language-variant (grave) key and a different key with a different identity in the USB specification. The ひらツな (Hiragana) and カタカナ (Katakana) keys are separate keys in the USB specification, and not to be confused with the ひらツな/カタカナ/ローマ字 key in the USB specification; thus all three have separate key identities. The key with the ひらツな/カタカナ/ローマ字 engraving on the 106/109-key PC keyboard is in fact the language-variant key (called grave in the USB specification) in the "C" row (q.v.). There is no ローマ字 (Romaji) key in the USB specification or on the PC keyboard, so there is no map for it; although an extended key message code for it exists, to permit realizers to generate it by some other means. The 変換 (Kanji) key from the 106/109-key PC keyboard and the 한영 (Hanja) key from the 103/106-key PC keyboard are considered identical, a single key with only the latter having an identity in the USB specification; no keyboard anywhere having them both. Cursor/Editing keypad ⇱ Home; ⭡ Up Arrow; ⎗ Page Up; ⭠ Left Arrow; ⭢ Right Arrow; ⇲ End; ⭣ Down Arrow; ⎘ Page Down; ⎀ Insert; Delete; Cut; Copy; Paste; Find; ⎌ Undo; and Redo. The final 6 keys are found on Sun Microsystems and "Office" keyboards. Calculator keypad 1 * Multiply; 7; 8; 9; - Minus; 4; 5; 6; + Plus; 1; 2; 3; 0; . Decimal Point; Enter; and / Divide. Calculator keypad 2 , Thousands Separator from the Apple Pro JIS and 104/107-key (ABNT2) PC keyboards; , JP Comma; = from the Apple Pro JIS keyboard; AS/400 =; ± Sign Change; (; ); {; }; and 7 unused positions. Function row 1 F0 to F15. In reality, F0 does not exist and the lowest real function key is F1. The ⎋ Escape key is not considered part of this row. Function row 2 F16 to F31. Function row 3 F32 to F47. Function row 4 An unused position; Fn-Locked F1 to F12; and 7 unused positions. Various PS/2 "Office" keyboards report modified scancodes for the F1 to F12 keys when Fn lock is on. PS/2 HID realizers use this part of the keyboard map in order to allow the function keys in that mode to have alternative mappings. System Commands keypad Task Manager; ⏼ Power; ⏾ Sleep; Wake; Debug; Lock; Logoff; Logon; Hibernate; Next Task; Previous Task; Select Task; Halt Task; and 3 more unused positions. Application shortcuts keypad 1 Calculator; File Manager; WWW Browser; ⌂ Home Page; Mail; Computer; CLI; Word Processor; Spreadsheet; My Computer; Instant Messaging; Media Player; My Pictures; Text Editor; Spell; and Calendar. These are present on "Office", "Internet", and "Multimedia" keyboards. In the USB HID specification they are consumer keys. Application shortcuts keypad 2 16 unused positions reserved for future shortcuts. The USB HID specification defines many more shortcuts as consumer keys. Application Commands keypad 1 ⯉ Popup menu; ⏹ Stop Playing; ⏭ Next Track; ⏮ Previous Track; ⏯ Play/Pause; Mute; Volume Up; Volume Down; ⏪ Rewind; ⏩ Fast Forward; ⏏ Eject; ⏺ Record; Application Back; Application Forward; Application Left; and Application Right. These are present on "Multimedia" keyboards. These are primarily media player control keys. Application Commands keypad 2 Help; Pause; ⎙ Print Screen; Attention; Refresh; New; Exit; Save; Stop/Break; Search; Bookmarks; Stop Loading; Execute; Menu; Open; and Close. This is a mixture of long-standing PC/AT command keys (usually located on row "F") and keys found on "Office" and "Internet" keyboards. Application Commands keypad 3 Select; Stop; Again; Cancel; Clear; Prior; App Return; Separator; Out; Oper; Clear/again; Properties; Ex Sel; and 3 unused positions. Each 96-octet map entry comprises twenty-four big-endian 32-bit integers. A map entry describes two things: a set of possible actions to be taken when the key is pressed and released, and how to select which action based upon the momentary keyboard modifier state. A selection class determines how the set of modifiers is reduced to a four-bit action index (giving sixteen possible combinations) by combining modifiers with one another. Keyboard modifiers comprise (in ISO 9995-1 terminology) modifiers for level 2, level 3, and group 2; for caps, num, level2 shift, and level3 shift locks; and for super, alt, and control. What keys act as these modifiers is of course determined by the keyboard layout: but often the level 2 modifiers are the ⇧ Shift keys; the level 3 modifier is the right ⌥ Option/Closed Apple (Apple keyboards) or ⇮ AltGr (Windows and IBM PC/AT keyboards) key; the alt modifier is the left ⌥ Option/Closed Apple (Apple keyboards) or ⎇ Alt (Windows and IBM PC/AT keyboards) key; and super is the ⌘ Command/Open Apple (Apple keyboards), Meta (Sun keyboards), or Windows (Windows keyboards) key. The initial state of all locks is off. The selection class code is first in each entry, and the code values are here designated by their UCS-4 code points. 'p' (U+00000070, "plain") The keyboard modifier state is entirely ignored and the first action is always chosen. s (U+00000073, "shiftable") When selecting an action, the sense of the level2 modifier state is inverted by the level2 shift lock state, and the sense of the level3 modifier state is inverted by the level3 shift lock state. This is generally used for non-alphabetic keys that obey shift lock but not caps lock. l (U+0000006C, "semi-shiftable") When selecting an action, the sense of the level2 and level 3 modifier states are taken as they are. This is generally used for non-alphabetic keys that ignore all locks but obey pressed modifiers. In particular, this is used for lock keys that involve modifiers being pressed, as otherwise their own locks would affect them. c (U+00000063, "capsable") When selecting an action, the sense of the level2 modifier state is inverted by the OR-combined caps lock and shift lock states. This is generally used for alphabetic keys that obey caps lock and shift lock. n (U+0000006E, "numable") When selecting an action, the sense of the level2 modifier state is inverted by the OR-combined num lock and shift lock states. This is generally used for auxiliary keys that obey num lock and shift lock. f (U+00000066, "funcable") When selecting an action, the sense of the level2 modifier state is inverted by the shift lock state, and the level3 modifier state is replaced by the alt state. This is generally used for function block keys that obey shift lock but not caps lock. The next seven 32-bit numbers are reserved, and should be set to zero. The remaining sixteen 32-bit numbers are the actions, chosen according to the selection class. These denote the actions for various combinations of modifiers: none, level2, control, control+level2, level3, level2+level3, control+level3, control+level2+level3, group2, group2+level2, group2+control, group2+control+level2, group2+level3, group2+level2+level3, group2+control+level3, and group2+control+level2+level3, with inversions and replacements as aforementioned. An individual action in a map entry is a big-endian 32-bit integer, which comprises three or four sub-fields. The most significant byte denotes the action type and the interpretation of the remainder of the action. (These are, intentionally, similar to the input protocol used by user-space virtual terminals (c.f. user-vt5), aimed at making debugging and trace analysis simpler. They are two distinct and separate protocols, however.) 0x00xxxxxx No-operation, Take no action. This is used for keys that have no action in the key map. 0x01nnnnnn UCS-3 key. On press or autorepeat, a Unicode character message for the code point U+00nnnnnn is sent to the input FIFO. If the alt modifier is in effect, a Unicode accelerator message is sent instead. 0x03nnnncc Modifier key. Modifiers do not autorepeat. On press or release, the modifier key nnnn is enacted against the current keyboard modifier state according to the cc command. Commands are: 0x01 Momentary. The modifier is on when the key is pressed, and off when the key is released. 0x02 Latching. Pressing the key latches the modifier on until a non-modifier key is pressed. 0x03 Locking. Pressing the key locks the modifier on; releasing and pressing it again locks it back off. 0x0Annnnzz Session selection key. On press or autorepeat, a session selection message for the session number nnnn is sent to the input FIFO. zz is ignored and should be set to zero for upwards compatibility. 0x0Cnnnnzz Consumer key. On press or autorepeat, a consumer key message for the consumer key number nnnn is sent to the input FIFO. zz is ignored and should be set to zero for upwards compatibility. 0x0Ennnnzz Extended key. On press or autorepeat, an extended key message for the extended key number nnnn is sent to the input FIFO. zz is ignored and should be set to zero for upwards compatibility. 0x1Ennnnzz Unshiftable extended key. On press or autorepeat, an extended key message for the extended key number nnnn is sent to the input FIFO. zz is ignored and should be set to zero for upwards compatibility. The accompanying keyboard modifier state does not incorporate the level 2 modifier, which will never be seen by the terminal emulator or processes connected to the terminal. This is used for keyboard layouts where shift inverts the sense of numlock on calculator keys, and that shift is not considered to further modify the key or be visible to applications. 0x0Fnnnnzz Function key. On press or autorepeat, a function key message for the function key number nnnn is sent. zz is ignored and should be set to zero for upwards compatibility. This is used for keyboard layouts where the function key block has a large number of actual keys. The terminal emulator, and processes connected to the terminal, will see function keys with modifiers. 0x1Fnnnnzz Unmodifiable function key. On press or autorepeat, a function key message for the function key number nnnn is sent. zz is ignored and should be set to zero for upwards compatibility. The accompanying keyboard modifier state does not incorporate the level or group modifiers, which will never be seen by the terminal emulator or processes connected to the terminal. This is used for keyboard layouts where the function key block has a small number of actual keys and the level+group modifiers are used "locally" (within the realizer) to simulate a larger key block. It is (of course) the keyboard map that handles function key mapping. The function key entries in the matrix represent physical function keys, not composed keys created by combining modifiers with function keys. Those are, after all, represented by the individual actions in each function key's entry. A keyboard map defines what input messages a combination of modifiers and a function key generates. It will usually be one of: a function key (if the map maps physical function keys straight to terminal emulator function keys, passing the modifier state through to the terminal emulator); an unmodified function key (if the map uses modifiers to extend the function key set, and thus does not pass the modifier state that it has already consumed through to the terminal emulator); or an extended key. See console-terminal-emulator1 for why usually keyboard maps map function keys F1 to F5 to the cursor keypad extended keys PAD_F1 to PAD_F5 in input messages, and not to the input messages for function keys 1 to 5. Keyboard maps are tailored, of course, to country, layout (QWERTY, AZERTY, Dvorak, Maltron, and so forth), and the physical layout of the keyboard (104 keys, 109 keys, 124 keys, and so forth). Here are some example keymap entries: 0x00000063, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x01000073, 0x01000053, 0x01000013, 0x01000013, 0x010000DF, 0x010000A7, 0x01000013, 0x01000013. 0x01000073, 0x01000053, 0x01000013, 0x01000013, 0x010000DF, 0x010000A7, 0x01000013, 0x01000013. 'S' on the U.S. International IBM PC/AT keyboard, QWERTY layout. It varies according to caps lock, and produces 'ß' and '§' with the level 3 modifier. The control modifier always produces DC3 (U+0013). 0x00000066, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x0E0F0100, 0x1F000D00, 0x1F001900, 0x1F002500, 0x0A000100, 0x0A000D00, 0x0A001900, 0x0A002500. 0x0E0F0100, 0x1F000D00, 0x1F001900, 0x1F002500, 0x0A000100, 0x0A000D00, 0x0A001900, 0x0A002500. F1 on the U.S. International IBM PC/AT keyboard, QWERTY layout. It ignores level 3, varying according to the level 2, alt, and control modifiers to produce either PAD_F1, F13, F25, and F37 or session switch commands for sessions 1, 13, 25, and 37. Jonathan de Boyne Pollard