diff options
Diffstat (limited to 'hw/darwin/utils/dumpkeymap.man')
| -rw-r--r-- | hw/darwin/utils/dumpkeymap.man | 1004 |
1 files changed, 0 insertions, 1004 deletions
diff --git a/hw/darwin/utils/dumpkeymap.man b/hw/darwin/utils/dumpkeymap.man deleted file mode 100644 index 90a2cd051..000000000 --- a/hw/darwin/utils/dumpkeymap.man +++ /dev/null @@ -1,1004 +0,0 @@ -.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$ -// -.. -.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 annotations 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 |