diff options
Diffstat (limited to 'hw/darwin/utils/dumpkeymap.man')
| -rw-r--r-- | hw/darwin/utils/dumpkeymap.man | 1004 |
1 files changed, 1004 insertions, 0 deletions
diff --git a/hw/darwin/utils/dumpkeymap.man b/hw/darwin/utils/dumpkeymap.man new file mode 100644 index 000000000..2ad6d54d2 --- /dev/null +++ b/hw/darwin/utils/dumpkeymap.man @@ -0,0 +1,1004 @@ +.ig +//============================================================================= +// +// Manual page for `dumpkeymap'. +// +// Copyright (C) 1999,2000 by Eric Sunshine <sunshine@sunshineco.com> +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// 1. Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// 2. Redistributions in binary form must reproduce the above copyright +// notice, this list of conditions and the following disclaimer in the +// documentation and/or other materials provided with the distribution. +// 3. The name of the author may not be used to endorse or promote products +// derived from this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED +// WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO +// EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; +// OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +// OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +// ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +//============================================================================= +// +// $XFree86: xc/programs/Xserver/hw/darwin/utils/dumpkeymap.man,v 1.2 2000/12/05 21:18:34 dawes Exp $ +// +.. +.ig +//----------------------------------------------------------------------------- +// Local identification information. +//----------------------------------------------------------------------------- +.. +.nr VE 4 \" Version number +.TH DUMPKEYMAP 1 "v\n(VE \-\- 1 December 2000" "Version \n(VE" +.de UP +1 December 2000 +.. +.ig +//----------------------------------------------------------------------------- +// Annotation Macros +// ----------------- +// Facilitate creation of annotated, non-filled blocks of text. An +// annotated block is initiated with the `AS' macro. Each annotated, +// non-filled line within the block must be introduced with the `AN' macro +// which takes three arguments. The first argument is the detail text to +// be annotated. The second is a string of spaces used to align the +// annotations by certain (broken) roff interpreters which fail to +// implement the proper set of roff commands (such as diversions, +// indentation, and tab stops). It is assumed that the spaces will be +// used with fixed-point font. The third argument is the annotation +// itself. The block should be terminated with the `AE' macro. For all +// roff interpreters which properly implement diversions, indentation, and +// tab stops, all anotations within the block are automatically aligned at +// the same horizontal position. This position is guaranteed to be just +// to the right of the widest `AN' detail line. For broken roff +// interpreters, such as `rman', the string of spaces from the second +// argument are used to align the annotations. Finally, the `AZ' macro, +// which takes a single argument, can be used to to insert a non-annotated +// line into the block which does not play a part in the calculation of +// the horizontal annotation alignment. +// +// Implementation Notes +// -------------------- +// *1* These macros utilize a diversion (named `AD'). Since the prevailing +// indentation is stored along with the diverted text, we must muck with +// the indentation level in order to prevent the indentation from being +// applied to the text a second time when `AD' is finally emitted. +// +// *2* Unfortunately, `.if' strips leading whitespace from following text, so +// `AN' uses \& to preserve the whitespace. +// +// *3* This manual page has been tested for proper formatting with troff, +// groff, nroff and rman (the `man' to `HTML' converter). Unfortunately, +// rman fails to implement many useful features such as diversions, +// indentation, and tab stops, and is also hideously buggy. Furthermore +// it identifies itself as nroff and fails to provide any further +// identification, so there is no way to create macros which specifically +// work around its limitations. Following is a list of several bugs in +// rman which the implementation of these macros must avoid: +// o Fails with multi-line conditionals within macros. +// o Fails on macro definition within multi-line conditionals. +// o Fails when macro arguments are not delimited by exactly 1 space. +// o String definition `.ds' ignores the value; uses empty "" instead. +// As a consequence of these problems, the following macros are written +// using a series of ugly single-line `.if' conditionals rather than the +// more natural multi-line `.if' and `.ie' conditionals. Also, rman fails +// to understand the common idiom of `.\"' to introduce a comment, which +// is why all comments in this file are wrapped in ignore `.ig' blocks. +//----------------------------------------------------------------------------- +.. +.de AS +.if t .nr AW 0 +.if t .nr AI \\n(.i +.if t .in -\\n(AI +.nf +.. +.de AN +.if t .if \w'\\$1'>\\n(AW .nr AW \w'\\$1' +.if t .da AD +.if t \\&\\$1\\t\\$3 +.if t .da +.if n \\&\\$1 \\$2\\$3 +.. +.de AZ +.if t .da AD +\\$1 +.if t .da +.. +.de AE +.if t .in +\\n(AIu +.if t .if \\n(AW .ta \\n(AWu+\w'\\(em'u +.if t .AD +.if t .DT +.if t .rm AD +.if t .rm AW +.fi +.. +.ig +//----------------------------------------------------------------------------- +// Bulleted list macros -- `BG' begins a bulleted list; `BU' delimits +// bulleted entries; `BE' ends a bulleted list. +//----------------------------------------------------------------------------- +.. +.de BG +.PP +.RS +.. +.de BU +.HP +\\(bu\\ \\c +.. +.de BE +.RE +.PP +.. +.ig +//----------------------------------------------------------------------------- +// Indented paragraph with stylized hanging tag macro. `TG' takes a single +// argument and treats it as the hanging tag of the indented paragraph. +// The tag is italicized in troff but not in nroff. +//----------------------------------------------------------------------------- +.. +.de TG +.TP +.ie t .I "\\$1" +.el \\$1 +.. +.ig +//----------------------------------------------------------------------------- +// Manual page for `dumpkeymap'. +//----------------------------------------------------------------------------- +.. +.SH NAME +dumpkeymap \- Dianostic dump of a .keymapping file +.SH SYNOPSIS +.B dumpkeymap +.RI [ options "] [-] [" file "...]" +.SH DESCRIPTION +.I dumpkeymap +prints a textual representation of each Apple/\c +.SM NeXT +.I .keymapping +file mentioned on the command-line. If no files are mentioned and if the +local machine is an Apple or +.SM NeXT +installation, then the key mapping currently in use by the WindowServer and the +AppKit is printed instead. +.SH OPTIONS +.TP +.B "\-h \-\^\-help" +Display general program instructions and option summary. +.TP +.B "\-k \-\^\-help\-keymapping" +Display a detailed description of the internal layout of a +.I .keymapping +file. This is the same information as that presented in the +.I "Key Mapping Description" +section of this document. +.TP +.B "\-o \-\^\-help\-output" +Display an explanation of the output generated by +.I dumpkeymap +when dissecting a +.I .keymapping +file. This is the same information as that presented in the +.I "Output Description" +section of this document. +.TP +.B "\-f \-\^\-help\-files" +Display a summary of the various files and directories which are related to +key mappings. This is the same information as that presented in the +.I "Files" +section of this document. +.TP +.B "\-d \-\^\-help\-diagnostics" +Display a list of the various diagnostic messages which may be emitted by +.I dumpkeymap. +This is the same information as that presented in the +.I "Diagnostics" +section of this document. +.TP +.B "\-v \-\^\-version" +Display the +.I dumpkeymap +version number and warranty information. +.TP +.B "\- \-\^\-" +Inhibit processing of options at this point in the argument list. An +occurrence of `\-' or `\-\^\-' in the argument list causes all following +arguments to be treated as file names even if an argument begins with a `\-' +character. +.SH "KEY MAPPING DESCRIPTION" +The following sections describe, in complete detail, the format of a raw key +mapping resource, as well as the format of the +.I .keymapping +file which encapsulates one or more raw mappings. +.SH "Types and Data" +The following type definitions are employed throughout this discussion: +.PP +.RS +.AS +.AZ "typedef unsigned char byte;" +.AZ "typedef unsigned short word;" +.AZ "typedef unsigned long dword;" +.AE +.RE +.PP +Additionally, the type definition +.RI ` number ' +is used generically to +indicate a numeric value. The actual size of the +.RI ` number ' +type may be one or two bytes depending upon how the data is stored in the key +map. Although most key maps use byte-sized numeric values, word-sized values +are also allowed. +.PP +Multi-byte values in a key mapping file are stored in big-endian byte order. +.SH "Key Mapping File and Device Mapping" +A key mapping file begins with a magic-number and continues with a +variable number of device-specific key mappings. +.PP +.RS +.AS +.AZ "struct KeyMappingFile {" +.AN " char magic_number[4];" " " "// `KYM1'" +.AN " DeviceMapping maps[...];" "" "// Variable number of maps" +.AZ }; +.AE +.PP +.AS +.AZ "struct DeviceMapping {" +.AN " dword interface;" " " "// Interface type" +.AN " dword handler_id;" "" "// Interface subtype" +.AN " dword map_size;" " " "// Byte count of `map' (below)" +.AN " KeyMapping map;" +.AZ }; +.AE +.RE +.PP +The value of `interface' represents a family of keyboard device types +(such as Intel +.SM "PC, ADB, NeXT," +Sun Type5, etc.), and is generally specified as one of the constant values +.SM "NX_EVS_DEVICE_INTERFACE_ADB, NX_EVS_DEVICE_INTERFACE_ACE," +etc., which are are defined in IOHIDTypes.h on MacOS/X and Darwin, and in +ev_types.h on MacOS/X Server, OpenStep, and NextStep. +.PP +The value of `handler_id' represents a specific keyboard layout within the +much broader `interface' family. For instance, for a 101-key Intel +.SM PC +keyboard (of type +.SM NX_EVS_DEVICE_INTERFACE_ACE\c +) the `handler_id' is '0', whereas for a 102-key keyboard it is `1'. +.PP +Together, `interface' and `handler_id' identify the exact keyboard hardware to +which this mapping applies. Programs which display a visual representation of +a keyboard layout, match `interface' and `handler_id' from the +.I .keymapping +file against the `interface' and `handler_id' values found in each +.I .keyboard +file. +.SH "Key Mapping" +A key mapping completely defines the relationship of all scan codes with their +associated functionality. A +.I KeyMapping +structure is embedded within the +.I DeviceMapping +structure in a +.IR KeyMappingFile . +The key mapping currently in use by the WindowServer and AppKit is also +represented by a +.I KeyMapping +structure, and can be referred to directly by calling NXGetKeyMapping() and +accessing the `mapping' data member of the returned +.I NXKeyMapping +structure. +.PP +.RS +.AS +.AZ "struct KeyMapping {" +.AN " word number_size;" " " "// 0=1 byte, non-zero=2 bytes" +.AN " number num_modifier_groups;" "" "// Modifier groups" +.AZ " ModifierGroup modifier_groups[...];" +.AN " number num_scan_codes;" " " "// Scan groups" +.AN " ScanGroup scan_table[...];" +.AN " number num_sequence_lists;" " " "// Sequence lists" +.AN " Sequence sequence_lists[...];" +.AN " number num_special_keys;" " " "// Special keys" +.AN " SpecialKey special_key[...];" +.AZ }; +.AE +.RE +.PP +The `number_size' flag determines the size, in bytes, of all remaining numeric +values (denoted by the type definition +.RI ` number ') +within the +key mapping. If its value is zero, then numbers are represented by a single +byte. If it is non-zero, then numbers are represented by a word (two bytes). +.SH "Modifier Group" +A modifier group defines all scan codes which map to a particular type of +modifier, such as +.IR shift , +.IR control , +etc. +.PP +.RS +.AS +.AZ "enum Modifier {" +.AZ " ALPHALOCK = 0," +.AZ " SHIFT," +.AZ " CONTROL," +.AZ " ALTERNATE," +.AZ " COMMAND," +.AZ " KEYPAD," +.AZ " HELP" +.AZ }; +.AE +.PP +.AS +.AZ "struct ModifierGroup {" +.AN " number modifier;" " " "// A Modifier constant" +.AN " number num_scan_codes;" +.AN " number scan_codes[...];" "" "// Variable number of scan codes" +.AZ }; +.AE +.RE +.PP +The scan_codes[] array contains a list of all scan codes which map to the +specified modifier. The +.IR shift ", " command ", and " alternate +modifiers are frequently mapped to two different scan codes, apiece, +since these modifiers often appear on both the left and right sides of +the keyboard. +.SH "Scan Group" +There is one +.I ScanGroup +for each scan code generated by the given keyboard. This number is given by +KeyMapping::num_scan_codes. The first scan group represents hardware scan +code 0, the second represents scan code 1, etc. +.PP +.RS +.AS +.AZ "enum ModifierMask {" +.AN " ALPHALOCK_MASK" " " "= 1 << 0," +.AN " SHIFT_MASK" " " "= 1 << 1," +.AN " CONTROL_MASK" " " "= 1 << 2," +.AN " ALTERNATE_MASK" " " "= 1 << 3," +.AN " CARRIAGE_RETURN_MASK" "" "= 1 << 4" +.AZ }; +.AZ "#define NOT_BOUND 0xff" +.AE +.PP +.AS +.AZ "struct ScanGroup {" +.AN " number mask;" +.AN " Character characters[...];" +.AZ }; +.AE +.RE +.PP +For each scan code, `mask' defines which modifier combinations generate +characters. If `mask' is +.SM NOT_BOUND +(0xff) then then this scan code does not generate any characters ever, and its +characters[] array is zero length. Otherwise, the characters[] array contains +one +.I Character +record for each modifier combination. +.PP +The number of records in characters[] is determined by computing (1 << +bits_set_in_mask). In other words, if mask is zero, then zero bits are set, +so characters[] contains only one record. If `mask' is +.SM "(SHIFT_MASK | CONTROL_MASK)," +then two bits are set, so characters[] contains four records. +.PP +The first record always represents the character which is generated by that +key when no modifiers are active. The remaining records represent characters +generated by the various modifier combinations. Using the example with the +.I shift +and +.I control +masks set, record two would represent the character with the +.I shift +modifier active; record three, the +.I control +modifier active; and record four, both the +.I shift +and +.I control +modifiers active. +.PP +As a special case, +.SM ALPHALOCK_MASK +implies +.SM SHIFT_MASK, +though only +.SM ALPHALOCK_MASK +appears in `mask'. In this case the same character is generated for both the +.I shift +and +.I alpha-lock +modifiers, but only needs to appear once in the characters[] array. +.PP +.SM CARRIAGE_RETURN_MASK +does not actually refer to a modifier key. Instead, it is used to +distinguish the scan code which is given the special pseudo-designation of +.I "carriage return" +key. Typically, this mask appears solo in a +.I ScanGroup +record and only the two +.I Character +records for control-M and control-C follow. This flag may be a throwback to +an earlier time or may be specially interpreted by the low-level keyboard +driver, but its purpose is otherwise enigmatic. +.SH Character +Each +.I Character +record indicates the character generated when this key is pressed, as well as +the character set which contains the character. Well known character sets are +.SM `ASCII' +and `Symbol'. The character set can also be one of the meta values +.SM FUNCTION_KEY +or +.SM KEY_SEQUENCE. +If it is +.SM FUNCTION_KEY +then `char_code' represents a generally well-known function key such as those +enumerated by +.I FunctionKey. +If the character set is +.SM KEY_SEQUENCE +then `char_code' represents is a zero-base index into +KeyMapping::sequence_lists[]. +.PP +.RS +.AS +.AZ "enum CharacterSet {" +.AN " ASCII" " " "= 0x00," +.AN " SYMBOL" " " "= 0x01," +.AN " ..." +.AN " FUNCTION_KEY" "" "= 0xfe," +.AN " KEY_SEQUENCE" "" "= 0xff" +.AZ }; +.AE +.PP +.AS +.AZ "struct Character {" +.AN " number set;" " " "// CharacterSet of generated character" +.AN " number char_code;" "" "// Actual character generated" +.AZ }; +.AE +.PP +.AS +.AZ "enum FunctionKey {" +.AZ " F1 = 0x20, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12," +.AZ " INSERT, DELETE, HOME, END, PAGE_UP, PAGE_DOWN, PRINT_SCREEN," +.AZ " SCROLL_LOCK, PAUSE, SYS_REQUEST, BREAK, RESET, STOP, MENU," +.AZ " USER, SYSTEM, PRINT, CLEAR_LINE, CLEAR_DISPLAY, INSERT_LINE," +.AZ " DELETE_LINE, INSERT_CHAR, DELETE_CHAR, PREV, NEXT, SELECT" +.AZ }; +.AE +.RE +.SH Sequence +When Character::set contains the meta value +.SM KEY_SEQUENCE, +the scan code is bound to a sequence of keys rather than a single character. +A sequence is a series of modifiers and characters which are automatically +generated when the associated key is depressed. +.PP +.RS +.AS +.AZ "#define MODIFIER_KEY 0xff" +.AE +.PP +.AS +.AZ "struct Sequence {" +.AN " number num_chars;" +.AN " Character characters[...];" +.AZ }; +.AE +.RE +.PP +Each generated +.I Character +is represented as previously described, with the exception that +.SM MODIFIER_KEY +may appear in place of +.SM KEY_SEQUENCE. +When the value of Character::set is +.SM MODIFIER_KEY +then Character::char_code represents a modifier key rather than an actual +character. If the modifier represented by `char_code' is non-zero, then it +indicates that the associated modifier key has been depressed. In this case, +the value is one of the constants enumerated by +.I Modifier +(\c +.SM "SHIFT, CONTROL, ALTERNATE," +etc.). If the value is zero then it means that the modifier keys have been +released. +.SH "Special Key" +A special key is one which is scanned directly by the Mach kernel rather than +by the WindowServer. In general, events are not generated for special keys. +.PP +.RS +.AS +.AZ "enum SpecialKeyType {" +.AZ " VOLUME_UP = 0," +.AZ " VOLUME_DOWN," +.AZ " BRIGHTNESS_UP," +.AZ " BRIGHTNESS_DOWN," +.AZ " ALPHA_LOCK," +.AZ " HELP," +.AZ " POWER," +.AZ " SECONDARY_ARROW_UP," +.AZ " SECONDARY_ARROW_DOWN" +.AZ }; +.AE +.PP +.AS +.AZ "struct SpecialKey {" +.AN " number type;" " " "// A SpecialKeyType constant" +.AN " number scan_code;" "" "// Actual scan code" +.AZ }; +.AE +.RE +.SH OUTPUT +What follows is an explanation and description of the various pieces of +information emitted by +.I dumpkeymap. +.PP +For a more thorough discussion of any particular piece of information described +here, refer to the detailed description of the internal layout of a key mapping +provided by the +.I "Key Mapping Description" +section above. +.SH Conventions +Depending upon context, some numeric values are displayed in decimal +notation, whereas others are displayed in hexadecimal notation. +Hexadecimal numbers are denoted by a `0x' prefix (for instance, `0x7b'), +except when explicitly noted otherwise. +.SH "Key Mapping Source" +The first piece of information presented about a particular key mapping is the +source from which the data was gleaned. For a +.I .keymapping +file, the title +.SM "`KEYMAP FILE'" +is emitted along with the path and name of the file in question. For the key +mapping currently in use by the WindowServer and AppKit, the title +.SM "`ACTIVE KEYMAP'" +is emitted instead. +.SH "Device Information" +Each +.I .keymapping +file may contain one or more raw key mappings. For example, a file which maps +keys to a Dvorak-style layout might contain raw mappings for Intel +.SM "PC, ADB, NeXT," +and Sun Type5 keyboards. +.PP +For each raw mapping, the following information is emitted: +.BG +.BU +The title +.SM `KEYMAP' +along with the mapping's relative position in the +.I .keymapping +file. +.BU +The `interface' identifier. +.BU +The `handler_id' sub-identifier. +.BU +The size of the raw mapping resource counted in bytes. +.BE +The `interface' and `handler_id' values, taken together, define a specific +keyboard device. A +.I .keyboard +file, which describes the visual layout of a keyboard, also contains +`interface' and `handler_id' identifiers. The +.I .keyboard +file corresponding to a particular key mapping can be found by matching the +`interface' and `handler_id' values from each resource. +.SH Modifiers +Each mapping may contain zero or more modifier records which associate hardware +scan codes with modifier descriptions such as +.I "shift, control, alternate," +etc. The title +.SM `MODIFIERS' +is printed along with the count of modifier records which follow. For each +modifier record, the modifier's name is printed along with a list of scan +codes, in hexadecimal format, which generate that modifier value. For example: +.PP +.RS +.nf +MODIFIERS [4] +alternate: 0x1d 0x60 +control: 0x3a +keypad: 0x52 0x53 ... 0x63 0x62 +shift: 0x2a 0x36 +.fi +.RE +.SH Characters +Each mapping may contain zero or more character records which associate +hardware scan codes with the actual characters generated by those scan +codes in the presence or absence of various modifier combinations. The +title +.SM `CHARACTERS' +is printed along with the count of character records which follow. Here is a +highly abbreviated example: +.PP +.RS +.nf +CHARACTERS [9] +scan 0x00: -AC-L "a" "A" "^A" "^A" ca c7 "^A" "^A" +scan 0x07: -AC-L "x" "X" "^X" "^X" 01/b4 01/ce "^X" "^X" +scan 0x0a: ---S- "<" ">" +scan 0x13: -ACS- "2" "@" "^@" "^@" b2 b3 "^@" "^@" +scan 0x24: R---- "^M" "^C" +scan 0x3e: ----- [F4] +scan 0x4a: ----- [page up] +scan 0x60: ----- {seq#3} +scan 0x68: not-bound +.fi +.RE +.PP +For each record, the hexadecimal value of the hardware scan code is printed, +followed by a list of modifier flag combinations and the actual characters +generated by this scan code with and without modifiers applied. +.PP +The modifier flags field is composed of a combination of single letter +representations of the various modifier types. The letters stand for: +.PP +.RS +.nf +L \- alpha-lock +S \- shift +C \- control +A \- alternate +R \- carriage-return +.fi +.RE +.PP +As a special case, the +.I alpha-lock +flag also implies the +.I shift +flag, so these two flags never appear together in the same record. +.PP +The combination of modifier flags determines the meaning and number of fields +which follow. The first field after the modifier flags always represents the +character that will be generated if no modifier keys are depressed. The +remaining fields represent characters generated by the various modifier +combinations. The order of the fields follows this general pattern: +.BG +.BU +The character generated by this scan code when no modifiers are in effect is +listed first. +.BU +If the `L' or `S' flag is active, then the shifted character generated by this +scan code is listed next. +.BU +If the `C' flag is active, then the control-character generated by this scan +code is listed next. Furthermore, if the `L' or `S' flag is also active, then +the shifted control-character is listed after that. +.BU +If the `A' flag is active, then the alternate-character generated by this scan +code is listed next. Furthermore, if the `L' or `S' flag is active, then the +shifted alternate-character is listed after that. If the `C' flag is also +active, then the alternate-control-character is listed next. Finally, if the +`C' and `L' or `C' and `S' flags are also active, then the shifted +alternate-control-character is listed. +.BE +The `R' flag does not actually refer to a modifier key. Instead, it is used to +distinguish the scan code which is given the special pseudo-designation of +.I "carriage return" +key. Typically, this mask appears solo and only the two fields for control-M +and control-C follow. This flag may be a throwback to an earlier time or may +be specially interpreted by the low-level keyboard driver, but its purpose is +otherwise enigmatic. +.PP +Recalling the example from above, the following fields can be identified: +.PP +.RS +.nf +scan 0x00: -AC-L "a" "A" "^A" "^A" ca c7 "^A" "^A" +.fi +.RE +.BG +.BU +Lower-case `a' is generated when no modifiers are active. +.BU +Upper-case `A' is generated when +.IR shift " or " alpha-lock +are active. +.BU +Control-A is generated when +.I control +is active. +.BU +Control-A is generated when +.IR control " and " shift +are active. +.BU +The character represented by the hexadecimal code 0xca is generated when +.I alternate +is active. +.BU +The character represented by 0xc7 is generated when +.IR alternate " and " shift " (or " alpha-lock ") are active." +.BU +Control-A is generated when +.IR alternate " and " control +are active. +.BU +Control-A is generated when +.IR "alternate, control" " and " shift " (or " alpha-lock ") are active." +.BE +The notation used to represent a particular generated character varies. +.BG +.BU +Printable +.SM ASCII +characters are quoted, as in "x" or "X". +.BU +Control-characters are quoted and prefixed with `^', as in "^X". +.BU +Characters with values greater than 127 (0x7f) are displayed as hexadecimal +values without the `0x' prefix. +.BU +Characters in a non-\c +.SM ASCII +character set (such as `Symbol') are displayed as two hexadecimal numbers +separated by a slash, as in `01/4a'. The first number is the character set's +identification code (such as `01' for the `Symbol' set), and the second number +is the value of the generated character. +.BU +Non-printing special function characters are displayed with the function's +common name enclosed in brackets, as in `[page up]' or `[F4]'. +.BU +If the binding represents a key sequence rather than a single character, then +the sequence's identification number is enclosed in braces, as in `{seq#3}'. +.BE +Recalling a few examples from above, the following interpretations can be made: +.PP +.RS +.nf +scan 0x07: -AC-L "x" "X" "^X" "^X" 01/b4 01/ce "^X" "^X" +scan 0x3e: ----- [F4] +scan 0x4a: ----- [page up] +scan 0x60: ----- {seq#3} +.fi +.RE +.BG +.BU +"x" and "X" are printable +.SM ASCII +characters. +.BU +"^X" is a control-character. +.BU +`01/b4' and `01/ce' represent the character codes 0xb4 and 0xce in the `Symbol' +character set. +.BU +Scan code 0x3e generates function-key `F4', and scan code 0x4a generates +function-key `page up'. +.BU +Scan code 0x60 is bound to key sequence #3. +.BE +Finally, if a scan code is not bound to any characters, then it is annotated +with the label `not-bound', as with example scan code 0x68 from above. +.SH Sequences +A scan code (modified and unmodified) can be bound to a key sequence rather +than generating a single character or acting as a modifier. When it is bound +to a key sequence, a series of character invocations and modifier actions are +automatically generated rather than a single keystroke. +.PP +Each mapping may contain zero or more key sequence records. The title +.SM `SEQUENCES' +is printed along with the count of sequence records which follow. For example: +.PP +.RS +.nf +SEQUENCES [3] +sequence 0: "f" "o" "o" +sequence 1: {alternate} "b" "a" "r" {unmodify} +sequence 2: [home] "b" "a" "z" +.fi +.RE +.PP +The notation used to represent the sequence of generated characters is +identical to the notation already described in the +.I Characters +section above, with the exception that modifier actions may be interposed +between generated characters. Such modifier actions are represented by the +modifier's name enclosed in braces. The special name `{unmodify}' indicates +the release of the modifier keys. +.PP +Thus, the sequences in the above example can be interpreted as follows: +.BG +.BU +Sequence\ #0 generates `foo'. +.BU +Sequence\ #1 invokes the +.I alternate +modifier, generates `bar', and then releases +.I alternate. +.BU +Sequence\ #2 invokes the +.I home +key and then generates `baz'. In a text editor, this would probably result in +`baz' being prepended to the line of text on which the cursor resides. +.BE +.SH Special Keys +Certain keyboards feature keys which perform some type of special purpose +function rather than generating a character or acting as a modifier. For +instance, Apple keyboards often contain a +.I power +key, and +.SM NeXT +keyboards have historically featured screen brightness and volume control keys. +.PP +Each mapping may contain zero or more special-key records which associate +hardware scan codes with such special purpose functions. The title +.SM `SPECIALS' +is printed along with the count of records which follow. For each record, the +special function's name is printed along with a list of scan codes, in +hexadecimal format, which are bound to that function. For example: +.PP +.RS +.nf +SPECIALS [6] +alpha-lock: 0x39 +brightness-down: 0x79 +brightness-up: 0x74 +power: 0x7f +sound-down: 0x77 +sound-up: 0x73 +.fi +.RE +.SH FILES +.IP *.keymapping +A key mapping file which precisely defines the relationship of all +hardware-specific keyboard scan-codes with their associated functionality. +.IP *.keyboard +A file describing the physical layout of keys on a particular type of +keyboard. Each `key' token in this file defines the position and shape of the +key on the keyboard, as well as the associated scan code which that key +generates. A +.I .keymapping +file, on the other hand, defines the characters which are generated by a +particular scan code depending upon the state of the various modifier keys +(such as +.I shift, +.I control, +etc.). The `interface' and `handler_id' values from a +.I .keymapping +file are matched against those in each +.I .keyboard +file in order to associate a particular +.I .keyboard +file with a key mapping. Various +.SM GUI +programs use the +.I .keyboard +file to display a visual representation of a keyboard for the user. Since +these files are just plain text, they can be easily viewed and interpreted +without the aid of a specialized program, thus +.I dumpkeymap +leaves these files alone. +.PP +/System/Library/Keyboards +.br +/Network/Library/Keyboards +.br +/Local/Library/Keyboards +.br +/Library/Keyboards +.RS +Repositories for +.I .keymapping +and +.I .keyboard +files for MacOS/X, Darwin, and MacOS/X Server. +.RE +.PP +/NextLibrary/Keyboards +.br +/LocalLibrary/Keyboards +.RS +Repositories for +.I .keymapping +and +.I .keyboard +files for OpenStep and NextStep. +.RE +.IP $(HOME)/Library/Keyboards +Repository for personal +.I .keymapping +and +.I .keyboard +files. +.SH DIGANOSTICS +The following diagnostic messages may be issued to the standard error stream. +.TG "Unrecognized option." +An unrecognized option was specified on the command-line. Invoke +.I dumpkeymap +with the +.B "\-\^\-help" +option to view a list of valid options. +.TG "Insufficient data in keymapping data stream." +The key mapping file or data stream is corrupt. Either the file has been +incorrectly truncated or a field, such as those which indicates the number of +variable records which follow, contains a corrupt value. +.PP +The following diagnostic messages have significance only when trying to print +.I .keymapping +files mentioned on the command-line. +.TG "Bad magic number." +The mentioned file is not a +.I .keymapping +file. The file's content does not start with the string `KYM1'. +.TG "Unable to open key mapping file." +The call to fopen() failed; probably because the specified path is invalid or +.I dumpkeymap +does not have permission to read the file. +.TG "Unable to determine key mapping file size." +The call to fstat() failed, thus memory can not be allocated for loading the +file. +.TG "Unable to read key mapping file." +The call to fread() failed. +.PP +The following diagnostic messages have significance only when trying to print +the currently active key mapping when no +.I .keymapping +files have been mentioned on the command-line. +.TG "Unable to open event status driver." +The call to NXOpenEventStatus() failed. +.TG "Bad key mapping length." +The call to NXKeyMappingLength() returned a bogus value. +.TG "Unable to get current key mapping." +The call to NXGetKeyMapping() failed. +.PP +The following diagnostic messages have significance only when using +.I dumpkeymap +on a non-Apple/\c +.SM NeXT +platform. +.TG "Must specify at least one .keymapping file." +No +.I .keymapping +files were mentioned on the command-line. On non-Apple/\c +.SM NeXT +platforms, there is no concept of a currently active +.I .keymapping +file, so at least one file must be mentioned on the command-line. +.SH AUTHOR +Eric Sunshine <sunshine@sunshineco.com> wrote +.I dumpkeymap +and this document, the +.I "dumpkeymap user's manual." +Both +.I dumpkeymap +and this document are copyright \(co1999,2000 by Eric Sunshine +<sunshine@sunshineco.com>. All rights reserved. +.PP +The implementation of +.I dumpkeymap +is based upon information gathered on September 3, 1997 by Eric Sunshine +<sunshine@sunshineco.com> and Paul S. McCarthy <zarnuk@zarnuk.com> during an +effort to reverse engineer the format of the +.SM NeXT +.I .keymapping +file. +.if n .PP +.if n Version \n(VE \-\- +.if n .UP |