diff options
Diffstat (limited to 'nx-X11/programs/Xserver/hw/darwin/utils')
| -rw-r--r-- | nx-X11/programs/Xserver/hw/darwin/utils/Imakefile | 10 | ||||
| -rw-r--r-- | nx-X11/programs/Xserver/hw/darwin/utils/README.txt | 111 | ||||
| -rw-r--r-- | nx-X11/programs/Xserver/hw/darwin/utils/dumpkeymap.c | 1454 | ||||
| -rw-r--r-- | nx-X11/programs/Xserver/hw/darwin/utils/dumpkeymap.man | 1004 |
4 files changed, 2579 insertions, 0 deletions
diff --git a/nx-X11/programs/Xserver/hw/darwin/utils/Imakefile b/nx-X11/programs/Xserver/hw/darwin/utils/Imakefile new file mode 100644 index 000000000..b6ad53d8b --- /dev/null +++ b/nx-X11/programs/Xserver/hw/darwin/utils/Imakefile @@ -0,0 +1,10 @@ +XCOMM $XFree86: xc/programs/Xserver/hw/darwin/utils/Imakefile,v 1.2 2000/11/16 03:22:18 dawes Exp $ + + SRCS = dumpkeymap.c + OBJS = dumpkeymap.o +EXTRA_LOAD_FLAGS = -framework IOKit + +AllTarget(ProgramTargetName(dumpkeymap)) + +SimpleProgramTarget(dumpkeymap) + diff --git a/nx-X11/programs/Xserver/hw/darwin/utils/README.txt b/nx-X11/programs/Xserver/hw/darwin/utils/README.txt new file mode 100644 index 000000000..fb6d4399e --- /dev/null +++ b/nx-X11/programs/Xserver/hw/darwin/utils/README.txt @@ -0,0 +1,111 @@ +dumpkeymap - Diagnostic dump and detailed description of .keymapping files +Version 4 + +Copyright (C)1999,2000 by Eric Sunshine <sunshine@sunshineco.com> +Eric Sunshine, 1 December 2000 + +OVERVIEW +======== +This package contains the diagnostic utility dumpkeymap, as well as highly +detailed documentation describing the internal layout of the Apple/NeXT +.keymapping file. + +The dumpkeymap utility displays detailed information about each .keymapping +file mentioned on the command-line. On Apple and NeXT platforms, if no +.keymapping files are mentioned on the command-line, then it will instead +dissect the key mapping currently in use by the WindowServer and AppKit. + +Documentation includes a thorough and detailed description of the internal +layout of the .keymapping file, as well as an explanation of how to interpret +the output of dumpkeymap. + +The complete set of documentation is available for perusal via dumpkeymap's +manual page (dumpkeymap.1), as well as via the command-line options described +below. + + --help + Usage summary. + --help-keymapping + Detailed discussion of the internal format of a .keymapping file. + --help-output + Explanation of dumpkeymap's output. + --help-files + List of key mapping-related files and directories. + --help-diagnostics + Explanation of diagnostic messages. + +Once the manual page is been installed, documentation can also be accessed +with the Unix `man' command: + + % man dumpkeymap + + +COMPILATION +=========== +MacOS/X, Darwin + + cc -Wall -o dumpkeymap dumpkeymap.c -framework IOKit + +MacOS/X DP4 (Developer Preview 4) + + cc -Wall -o dumpkeymap dumpkeymap.c -FKernel -framework IOKit + +MacOS/X Server, OpenStep, NextStep + + cc -Wall -o dumpkeymap dumpkeymap.c + +By default, dumpkeymap is configured to interface with the HID driver (Apple) +or event-status driver (NeXT), thus allowing it to dump the key mapping which +is currently in use by the WindowServer and AppKit. However, these facilities +are specific to Apple/NeXT. In order to build dumpkeymap for non-Apple/NeXT +platforms, you must define the DUMPKEYMAP_FILE_ONLY flag when compiling the +program. This flag inhibits use of the HID and event-status drivers and +configures dumpkeymap to work strictly with raw key mapping files. + +For example, to compile for Linux: + + gcc -Wall -DDUMPKEYMAP_FILE_ONLY -o dumpkeymap dumpkeymap.c + + +INSTALLATION +============ +Install the dumpkeymap executable image in a location mentioned in the PATH +environment variable. Typicall locations for executable files are: + + /usr/local/bin + $(HOME)/bin + +Install the manual page, dumpkeymap.1, in the `man1' subdirectory one of the +standard manual page locations or in any other location mentioned by the +MANPATH environment variable. + +Typical locations for manual pages on most Unix platforms are: + + /usr/local/man/man1 + +Typical locations for manual pages on MacOS/X, Darwin, and MacOS/X Server are: + + /usr/local/man/man1 + /Local/Documentation/ManPages/man1 + /Network/Documentation/ManPages/man1 + +Typical locations for manual pages on OpenStep and NextStep are: + + /usr/local/man/man1 + /LocalLibrary/Documentation/ManPages/man1 + /LocalDeveloper/Documentation/ManPages/man1 + + +CONCLUSION +========== +This program and its accompanying documentation were written by Eric Sunshine +and are copyright (C)1999,2000 by Eric Sunshine <sunshine@sunshineco.com>. + +The implementation of 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 NeXT .keymapping file. + + + +$XFree86: xc/programs/Xserver/hw/darwin/utils/README.txt,v 1.1 2000/12/01 19:47:39 dawes Exp $ diff --git a/nx-X11/programs/Xserver/hw/darwin/utils/dumpkeymap.c b/nx-X11/programs/Xserver/hw/darwin/utils/dumpkeymap.c new file mode 100644 index 000000000..8f3340b15 --- /dev/null +++ b/nx-X11/programs/Xserver/hw/darwin/utils/dumpkeymap.c @@ -0,0 +1,1454 @@ +// $XFree86: dumpkeymap.c,v 1.3 2000/12/05 21:18:34 dawes Exp $ +//============================================================================= +// +// 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. +// +//============================================================================= +//----------------------------------------------------------------------------- +// dumpkeymap.c +// +// Prints a textual representation of each Apple/NeXT .keymapping file +// mentioned on the command-line. If no files are mentioned and if the +// local machine is an Apple or NeXT installation, then the key mapping +// currently in use by the WindowServer and the AppKit is printed +// instead. +// +// Invoke dumpkeymap with one of the options listed below in order to +// view detailed documentation about .keymapping files and the use of +// this program. +// +// --help: Usage summary. +// --help-keymapping: Detailed discussion of the internal format of a +// .keymapping file. +// --help-output: Explanation of dumpkeymap's output. +// --help-files: List of key mapping-related files and directories. +// --help-diagnostics: Explanation of diagnostic messages. +// +// COMPILATION INSTRUCTIONS +// +// MacOS/X, Darwin +// cc -Wall -o dumpkeymap dumpkeymap.c -framework IOKit +// +// MacOS/X DP4 (Developer Preview 4) +// cc -Wall -o dumpkeymap dumpkeymap.c -FKernel -framework IOKit +// +// MacOS/X Server, OpenStep, NextStep +// cc -Wall -o dumpkeymap dumpkeymap.c +// +// By default, dumpkeymap is configured to interface with the HID driver +// (Apple) or event-status driver (NeXT), thus allowing it to dump the +// key mapping which is currently in use by the WindowServer and AppKit. +// However, these facilities are specific to Apple/NeXT. In order to +// build dumpkeymap for non-Apple/NeXT platforms, you must define the +// DUMPKEYMAP_FILE_ONLY flag when compiling the program. This flag +// inhibits use of the HID and event-status drivers and configures +// dumpkeymap to work strictly with raw key mapping files. +// +// For example, to compile for Linux: +// gcc -Wall -DDUMPKEYMAP_FILE_ONLY -o dumpkeymap dumpkeymap.c +// +// CONCLUSION +// +// This program and its accompanying documentation were written by Eric +// Sunshine and are copyright (C)1999,2000 by Eric Sunshine +// <sunshine@sunshineco.com>. +// +// The implementation of 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 NeXT .keymapping file. +// +// HISTORY +// +// v4 2000/12/01 Eric Sunshine <sunshine@sunshineco.com> +// Updated manual page to work with `rman', the `man' to `HTML' +// translator. Unfortunately, however, rman is missing important +// roff features such as diversions, indentation, and tab stops, +// and is also hideously buggy, so getting the manual to work with +// rman required quite a few work-arounds. +// The manual page has now been tested with nroff (plain text), troff +// (PostScript, etc.), groff (PostScript), and rman (HTML, etc.) +// +// v3 2000/11/28 Eric Sunshine <sunshine@sunshineco.com> +// Considerably expanded the documentation. +// Augmented the existing description of .keymapping internals. +// Added these new documentation topics: +// - Output: Very important section describing how to interpret +// the output of dumpkeymap. +// - Files: Lists files and directories related to key mappings. +// - Diagnostics: Explains diagnostic messages issued by +// dumpkeymap. +// Created a manual page (dumpkeymap.1) which contains the complete +// set of documentation for key mapping files and dumpkeymap. +// Added command-line options (--help, --help-keymapping, +// --help-output, --help-files, --help-diagnostics) which allow +// access to all key mapping documentation. Previously the +// description of the internal layout of a .keymapping file was +// only available as source code comments. +// Added --version option. +// Ported to non-Apple/NeXT platforms. Defining the pre-processor +// flag DUMPKEYMAP_FILE_ONLY at compilation time inhibits use of +// Apple/NeXT-specific API. +// Added a README file. +// +// v2 2000/11/13 Eric Sunshine <sunshine@sunshineco.com> +// Converted from C++ to plain-C. +// Now parses and takes into account the "number-size" flag stored +// with each key map. This flag indicates the size, in bytes, of +// all remaining numeric values in the mapping. Updated all code +// to respect this flag. (Previously, the purpose of this field +// was unknown, and it was thus denoted as +// `KeyMapping::fill[2]'.) +// Updated all documentation; especially the "KEY MAPPING +// DESCRIPTION" section. Added discussion of the "number-size" +// flag and revamped all structure definitions to use the generic +// data type `number' instead of `uchar' or 'byte'. Clarified +// several sections of the documentation and added missing +// discussions about type definitions and the relationship of +// `interface' and `handler_id' to .keymapping and .keyboard +// files. +// Updated compilation instructions to include directions for all +// platforms on which this program might be built. +// Now published under the formal BSD license rather than a +// home-grown license. +// +// v1 1999/09/08 Eric Sunshine <sunshine@sunshineco.com> +// Created. +//----------------------------------------------------------------------------- +#include <ctype.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/stat.h> +#if !defined(DUMPKEYMAP_FILE_ONLY) +#include <drivers/event_status_driver.h> +#endif + +#define PROG_NAME "dumpkeymap" +#define PROG_VERSION "4" +#define AUTHOR_NAME "Eric Sunshine" +#define AUTHOR_EMAIL "sunshine@sunshineco.com" +#define AUTHOR_INFO AUTHOR_NAME " <" AUTHOR_EMAIL ">" +#define COPYRIGHT "Copyright (C) 1999,2000 by " AUTHOR_INFO + +typedef unsigned char byte; +typedef unsigned short word; +typedef unsigned int natural; +typedef unsigned long dword; +typedef dword number; + +#define ASCII_SET 0x00 +#define BIND_FUNCTION 0xfe +#define BIND_SPECIAL 0xff + +#define OPT_SWITCH(X) { char const* switched_str__=(X); if (0) { +#define OPT_CASE(X,Y) } else if (strcmp(switched_str__,(#X)) == 0 || \ + strcmp(switched_str__,(#Y)) == 0) { +#define OPT_DEFAULT } else { +#define OPT_SWITCH_END }} + +//----------------------------------------------------------------------------- +// Translation Tables +//----------------------------------------------------------------------------- +static char const* const SPECIAL_CODE[] = + { + "sound-up", + "sound-down", + "brightness-up", + "brightness-down", + "alpha-lock", + "help", + "power", + "secondary-up-arrow", + "secondary-down-arrow" + }; +#define N_SPECIAL_CODE (sizeof(SPECIAL_CODE) / sizeof(SPECIAL_CODE[0])) + +static char const* const MODIFIER_CODE[] = + { + "alpha-lock", + "shift", + "control", + "alternate", + "command", + "keypad", + "help" + }; +#define N_MODIFIER_CODE (sizeof(MODIFIER_CODE) / sizeof(MODIFIER_CODE[0])) + +static char const* const MODIFIER_MASK[] = + { + "-----", // R = carriage-return + "----L", // A = alternate + "---S-", // C = control + "---SL", // S = shift + "--C--", // L = alpha-lock + "--C-L", + "--CS-", + "--CSL", + "-A---", + "-A--L", + "-A-S-", + "-A-SL", + "-AC--", + "-AC-L", + "-ACS-", + "-ACSL", + "R----", + "R---L", + "R--S-", + "R--SL", + "R-C--", + "R-C-L", + "R-CS-", + "R-CSL", + "RA---", + "RA--L", + "RA-S-", + "RA-SL", + "RAC--", + "RAC-L", + "RACS-", + "RACSL", + }; +#define N_MODIFIER_MASK (sizeof(MODIFIER_MASK) / sizeof(MODIFIER_MASK[0])) + +#define FUNCTION_KEY_FIRST 0x20 +static char const* const FUNCTION_KEY[] = + { + "F1", // 0x20 + "F2", // 0x21 + "F3", // 0x22 + "F4", // 0x23 + "F5", // 0x24 + "F6", // 0x25 + "F7", // 0x26 + "F8", // 0x27 + "F9", // 0x28 + "F10", // 0x29 + "F11", // 0x2a + "F12", // 0x2b + "insert", // 0x2c + "delete", // 0x2d + "home", // 0x2e + "end", // 0x2f + "page up", // 0x30 + "page down", // 0x31 + "print screen", // 0x32 + "scroll lock", // 0x33 + "pause", // 0x34 + "sys-request", // 0x35 + "break", // 0x36 + "reset (HIL)", // 0x37 + "stop (HIL)", // 0x38 + "menu (HIL)", // 0x39 + "user (HIL)", // 0x3a + "system (HIL)", // 0x3b + "print (HIL)", // 0x3c + "clear line (HIL)", // 0x3d + "clear display (HIL)", // 0x3e + "insert line (HIL)", // 0x3f + "delete line (HIL)", // 0x40 + "insert char (HIL)", // 0x41 + "delete char (HIL)", // 0x42 + "prev (HIL)", // 0x43 + "next (HIL)", // 0x44 + "select (HIL)", // 0x45 + }; +#define N_FUNCTION_KEY (sizeof(FUNCTION_KEY) / sizeof(FUNCTION_KEY[0])) + + +//----------------------------------------------------------------------------- +// Data Stream Object +// Can be configured to treat embedded "numbers" as being composed of +// either 1, 2, or 4 bytes, apiece. +//----------------------------------------------------------------------------- +typedef struct _DataStream + { + byte const* data; + byte const* data_end; + natural number_size; // Size in bytes of a "number" in the stream. + } DataStream; + +static DataStream* new_data_stream( byte const* data, int size ) + { + DataStream* s = (DataStream*)malloc( sizeof(DataStream) ); + s->data = data; + s->data_end = data + size; + s->number_size = 1; // Default to byte-sized numbers. + return s; + } + +static void destroy_data_stream( DataStream* s ) + { + free(s); + } + +static int end_of_stream( DataStream* s ) + { + return (s->data >= s->data_end); + } + +static void expect_nbytes( DataStream* s, int nbytes ) + { + if (s->data + nbytes > s->data_end) + { + fputs( "Insufficient data in keymapping data stream.\n", stderr ); + exit(-1); + } + } + +static byte get_byte( DataStream* s ) + { + expect_nbytes( s, 1 ); + return *s->data++; + } + +static word get_word( DataStream* s ) + { + word hi, lo; + expect_nbytes( s, 2 ); + hi = *s->data++; + lo = *s->data++; + return ((hi << 8) | lo); + } + +static dword get_dword( DataStream* s ) + { + dword b1, b2, b3, b4; + expect_nbytes( s, 4 ); + b4 = *s->data++; + b3 = *s->data++; + b2 = *s->data++; + b1 = *s->data++; + return ((b4 << 24) | (b3 << 16) | (b2 << 8) | b1); + } + +static number get_number( DataStream* s ) + { + switch (s->number_size) + { + case 4: return get_dword(s); + case 2: return get_word(s); + default: return get_byte(s); + } + } + + +//----------------------------------------------------------------------------- +// Translation Utility Functions +//----------------------------------------------------------------------------- +static char const* special_code_desc( number n ) + { + if (n < N_SPECIAL_CODE) + return SPECIAL_CODE[n]; + else + return "invalid"; + } + +static char const* modifier_code_desc( number n ) + { + if (n < N_MODIFIER_CODE) + return MODIFIER_CODE[n]; + else + return "invalid"; + } + +static char const* modifier_mask_desc( number n ) + { + if (n < N_MODIFIER_MASK) + return MODIFIER_MASK[n]; + else + return "?????"; + } + +static char const* function_key_desc( number n ) + { + if (n >= FUNCTION_KEY_FIRST && n < N_FUNCTION_KEY + FUNCTION_KEY_FIRST) + return FUNCTION_KEY[ n - FUNCTION_KEY_FIRST ]; + else + return "unknown"; + } + +static number bits_set( number mask ) + { + number n = 0; + for ( ; mask != 0; mask >>= 1) + if ((mask & 0x01) != 0) + n++; + return n; + } + + +//----------------------------------------------------------------------------- +// Unparse a list of Modifier records. +//----------------------------------------------------------------------------- +static void unparse_modifiers( DataStream* s ) + { + number nmod = get_number(s); // Modifier count + printf( "MODIFIERS [%lu]\n", nmod ); + while (nmod-- > 0) + { + number nscan; + number const code = get_number(s); + printf( "%s:", modifier_code_desc(code) ); + nscan = get_number(s); + while (nscan-- > 0) + printf( " 0x%02x", (natural)get_number(s) ); + putchar( '\n' ); + } + putchar( '\n' ); + } + + +//----------------------------------------------------------------------------- +// Unparse a list of Character records. +//----------------------------------------------------------------------------- +typedef void (*UnparseSpecialFunc)( number code ); + +static void unparse_char_codes( + DataStream* s, number ncodes, UnparseSpecialFunc unparse_special ) + { + if (ncodes != 0) + { + while (ncodes-- > 0) + { + number const char_set = get_number(s); + number const code = get_number(s); + putchar(' '); + switch (char_set) + { + case ASCII_SET: + { + int const c = (int)code; + if (isprint(c)) + printf( "\"%c\"", c ); + else if (code < ' ') + printf( "\"^%c\"", c + '@' ); + else + printf( "%02x", c ); + break; + } + case BIND_FUNCTION: + printf( "[%s]", function_key_desc(code) ); + break; + case BIND_SPECIAL: + unparse_special( code ); + break; + default: + printf( "%02x/%02x", (natural)char_set, (natural)code ); + break; + } + } + } + } + + +//----------------------------------------------------------------------------- +// Unparse a list of scan code bindings. +//----------------------------------------------------------------------------- +static void unparse_key_special( number code ) + { + printf( "{seq#%lu}", code ); + } + +static void unparse_characters( DataStream* s ) + { + number const NOT_BOUND = 0xff; + number const nscans = get_number(s); + number scan; + printf( "CHARACTERS [%lu]\n", nscans ); + for (scan = 0; scan < nscans; scan++) + { + number const mask = get_number(s); + printf( "scan 0x%02x: ", (natural)scan ); + if (mask == NOT_BOUND) + fputs( "not-bound\n", stdout ); + else + { + number const bits = bits_set( mask ); + number const codes = 1 << bits; + printf( "%s ", modifier_mask_desc(mask) ); + unparse_char_codes( s, codes, unparse_key_special ); + putchar( '\n' ); + } + } + putchar( '\n' ); + } + + +//----------------------------------------------------------------------------- +// Unparse a list of key sequences. +//----------------------------------------------------------------------------- +static void unparse_sequence_special( number code ) + { + printf( "{%s}", (code == 0 ? "unmodify" : modifier_code_desc(code)) ); + } + +static void unparse_sequences( DataStream* s ) + { + number const nseqs = get_number(s); + number seq; + printf( "SEQUENCES [%lu]\n", nseqs ); + for (seq = 0; seq < nseqs; seq++) + { + number const nchars = get_number(s); + printf( "sequence %lu:", seq ); + unparse_char_codes( s, nchars, unparse_sequence_special ); + putchar( '\n' ); + } + putchar( '\n' ); + } + + +//----------------------------------------------------------------------------- +// Unparse a list of special keys. +//----------------------------------------------------------------------------- +static void unparse_specials( DataStream* s ) + { + number nspecials = get_number(s); + printf( "SPECIALS [%lu]\n", nspecials ); + while (nspecials-- > 0) + { + number const special = get_number(s); + number const scan = get_number(s); + printf( "%s: 0x%02x\n", special_code_desc(special), (natural)scan ); + } + putchar( '\n' ); + } + + +//----------------------------------------------------------------------------- +// Unparse the number-size flag. +//----------------------------------------------------------------------------- +static void unparse_numeric_size( DataStream* s ) + { + word const numbers_are_shorts = get_word(s); + s->number_size = numbers_are_shorts ? 2 : 1; + } + + +//----------------------------------------------------------------------------- +// Unparse an entire key map. +//----------------------------------------------------------------------------- +static void unparse_keymap_data( DataStream* s ) + { + unparse_numeric_size(s); + unparse_modifiers(s); + unparse_characters(s); + unparse_sequences(s); + unparse_specials(s); + } + + +//----------------------------------------------------------------------------- +// Unparse the active key map. +//----------------------------------------------------------------------------- +#if !defined(DUMPKEYMAP_FILE_ONLY) +static int unparse_active_keymap( void ) + { + int rc = 1; + NXEventHandle const h = NXOpenEventStatus(); + if (h == 0) + fputs( "Unable to open event status driver.\n", stderr ); + else + { + NXKeyMapping km; + km.size = NXKeyMappingLength(h); + if (km.size <= 0) + fprintf( stderr, "Bad key mapping length (%d).\n", km.size ); + else + { + km.mapping = (char*)malloc( km.size ); + if (NXGetKeyMapping( h, &km ) == 0) + fputs( "Unable to get current key mapping.\n", stderr ); + else + { + DataStream* stream = + new_data_stream( (byte const*)km.mapping, km.size ); + fputs( "=============\nACTIVE KEYMAP\n=============\n\n", + stdout); + unparse_keymap_data( stream ); + destroy_data_stream( stream ); + rc = 0; + } + free( km.mapping ); + } + NXCloseEventStatus(h); + } + return rc; + } +#endif + + +//----------------------------------------------------------------------------- +// Unparse one key map from a keymapping file. +//----------------------------------------------------------------------------- +static void unparse_keymap( DataStream* s ) + { + dword const interface = get_dword(s); + dword const handler_id = get_dword(s); + dword const map_size = get_dword(s); + printf( "interface: 0x%02lx\nhandler_id: 0x%02lx\nmap_size: %lu bytes\n\n", + interface, handler_id, map_size ); + unparse_keymap_data(s); + } + + +//----------------------------------------------------------------------------- +// Check the magic number of a keymapping file. +//----------------------------------------------------------------------------- +static int check_magic_number( DataStream* s ) + { + return (get_byte(s) == 'K' && + get_byte(s) == 'Y' && + get_byte(s) == 'M' && + get_byte(s) == '1'); + } + + +//----------------------------------------------------------------------------- +// Unparse all key maps within a keymapping file. +//----------------------------------------------------------------------------- +static int unparse_keymaps( DataStream* s ) + { + int rc = 0; + if (check_magic_number(s)) + { + int n = 1; + while (!end_of_stream(s)) + { + printf( "---------\nKEYMAP #%d\n---------\n", n++ ); + unparse_keymap(s); + } + } + else + { + fputs( "Bad magic number.\n", stderr ); + rc = 1; + } + return rc; + } + + +//----------------------------------------------------------------------------- +// Unparse a keymapping file. +//----------------------------------------------------------------------------- +static int unparse_keymap_file( char const* const path ) + { + int rc = 1; + FILE* file; + printf( "===========\nKEYMAP FILE\n===========\n%s\n\n", path ); + file = fopen( path, "rb" ); + if (file == 0) + perror( "Unable to open key mapping file" ); + else + { + struct stat st; + if (fstat( fileno(file), &st ) != 0) + perror( "Unable to determine key mapping file size" ); + else + { + byte* buffer = (byte*)malloc( st.st_size ); + if (fread( buffer, st.st_size, 1, file ) != 1) + perror( "Unable to read key mapping file" ); + else + { + DataStream* stream = new_data_stream(buffer, (int)st.st_size); + fclose( file ); file = 0; + rc = unparse_keymaps( stream ); + destroy_data_stream( stream ); + } + free( buffer ); + } + if (file != 0) + fclose( file ); + } + return rc; + } + + +//----------------------------------------------------------------------------- +// Handle the case when no documents are mentioned on the command-line. For +// Apple/NeXT platforms, dump the currently active key mapping; else display +// an error message. +//----------------------------------------------------------------------------- +static int handle_empty_document_list( void ) + { +#if !defined(DUMPKEYMAP_FILE_ONLY) + return unparse_active_keymap(); +#else + fputs( "ERROR: Must specify at least one .keymapping file.\n\n", stderr ); + return 1; +#endif + } + + +//----------------------------------------------------------------------------- +// Print a detailed description of the internal layout of a key mapping. +//----------------------------------------------------------------------------- +static void print_internal_layout_info( FILE* f ) + { + fputs( +"What follows is a detailed descriptions of the internal layout of an\n" +"Apple/NeXT .keymapping file.\n" +"\n" +"Types and Data\n" +"--------------\n" +"The following type definitions are employed throughout this discussion:\n" +"\n" +" typedef unsigned char byte;\n" +" typedef unsigned short word;\n" +" typedef unsigned long dword;\n" +"\n" +"Additionally, the type definition `number' is used generically to indicate\n" +"a numeric value. The actual size of the `number' type may be one or two\n" +"bytes depending upon how the data is stored in the key map. Although most\n" +"key maps use byte-sized numeric values, word-sized values are also allowed.\n" +"\n" +"Multi-byte values in a key mapping file are stored in big-endian byte\n" +"order.\n" +"\n" +"Key Mapping File and Device Mapping\n" +"-----------------------------------\n" +"A key mapping file begins with a magic-number and continues with a variable\n" +"number of device-specific key mappings.\n" +"\n" +" struct KeyMappingFile {\n" +" char magic_number[4]; // `KYM1'\n" +" DeviceMapping maps[...]; // Variable number of maps\n" +" };\n" +"\n" +" struct DeviceMapping {\n" +" dword interface; // Interface type\n" +" dword handler_id; // Interface subtype\n" +" dword map_size; // Byte count of `map' (below)\n" +" KeyMapping map;\n" +" };\n" +"\n" +"The value of `interface' represents a family of keyboard device types\n" +"(such as Intel PC, ADB, NeXT, Sun Type5, etc.), and is generally\n" +"specified as one of the constant values NX_EVS_DEVICE_INTERFACE_ADB,\n" +"NX_EVS_DEVICE_INTERFACE_ACE, etc., which are are defined in IOHIDTypes.h on\n" +"MacOS/X and Darwin, and in ev_types.h on MacOS/X Server, OpenStep, and\n" +"NextStep.\n" +"\n" +"The value of `handler_id' represents a specific keyboard layout within the\n" +"much broader `interface' family. For instance, for a 101-key Intel PC\n" +"keyboard (of type NX_EVS_DEVICE_INTERFACE_ACE) the `handler_id' is '0',\n" +"whereas for a 102-key keyboard it is `1'.\n" +"\n" +"Together, `interface' and `handler_id' identify the exact keyboard hardware\n" +"to which this mapping applies. Programs which display a visual\n" +"representation of a keyboard layout, match `interface' and `handler_id'\n" +"from the .keymapping file against the `interface' and `handler_id' values\n" +"found in each .keyboard file.\n" +"\n" +"Key Mapping\n" +"-----------\n" +"A key mapping completely defines the relationship of all scan codes with\n" +"their associated functionality. A KeyMapping structure is embedded within\n" +"the DeviceMapping structure in a KeyMappingFile. The key mapping currently\n" +"in use by the WindowServer and AppKit is also represented by a KeyMapping\n" +"structure, and can be referred to directly by calling NXGetKeyMapping() and\n" +"accessing the `mapping' data member of the returned NXKeyMapping structure.\n" +"\n" +" struct KeyMapping {\n" +" word number_size; // 0=1 byte, non-zero=2 bytes\n" +" number num_modifier_groups; // Modifier groups\n" +" ModifierGroup modifier_groups[...];\n" +" number num_scan_codes; // Scan groups\n" +" ScanGroup scan_table[...];\n" +" number num_sequence_lists; // Sequence lists\n" +" Sequence sequence_lists[...];\n" +" number num_special_keys; // Special keys\n" +" SpecialKey special_key[...];\n" +" };\n" +"\n" +"The `number_size' flag determines the size, in bytes, of all remaining\n" +"numeric values (denoted by the type definition `number') within the key\n" +"mapping. If its value is zero, then numbers are represented by a single\n" +"byte. If it is non-zero, then numbers are represented by a word (two\n" +"bytes).\n" +"\n" +"Modifier Group\n" +"--------------\n" +"A modifier group defines all scan codes which map to a particular type of\n" +"modifier, such as `shift', `control', etc.\n" +"\n" +" enum Modifier {\n" +" ALPHALOCK = 0,\n" +" SHIFT,\n" +" CONTROL,\n" +" ALTERNATE,\n" +" COMMAND,\n" +" KEYPAD,\n" +" HELP\n" +" };\n" +"\n" +" struct ModifierGroup {\n" +" number modifier; // A Modifier constant\n" +" number num_scan_codes;\n" +" number scan_codes[...]; // Variable number of scan codes\n" +" };\n" +"\n" +"The scan_codes[] array contains a list of all scan codes which map to the\n" +"specified modifier. The `shift', `command', and `alternate' modifiers are\n" +"frequently mapped to two different scan codes, apiece, since these\n" +"modifiers often appear on both the left and right sides of the keyboard.\n" +"\n" +"Scan Group\n" +"----------\n" +"There is one ScanGroup for each scan code generated by the given keyboard.\n" +"This number is given by KeyMapping::num_scan_codes. The first scan group\n" +"represents hardware scan code 0, the second represents scan code 1, etc.\n" +"\n" +" enum ModifierMask {\n" +" ALPHALOCK_MASK = 1 << 0,\n" +" SHIFT_MASK = 1 << 1,\n" +" CONTROL_MASK = 1 << 2,\n" +" ALTERNATE_MASK = 1 << 3,\n" +" CARRIAGE_RETURN_MASK = 1 << 4\n" +" };\n" +" #define NOT_BOUND 0xff\n" +"\n" +" struct ScanGroup {\n" +" number mask;\n" +" Character characters[...];\n" +" };\n" +"\n" +"For each scan code, `mask' defines which modifier combinations generate\n" +"characters. If `mask' is NOT_BOUND (0xff) then then this scan code does\n" +"not generate any characters ever, and its characters[] array is zero\n" +"length. Otherwise, the characters[] array contains one Character record\n" +"for each modifier combination.\n" +"\n" +"The number of records in characters[] is determined by computing (1 <<\n" +"bits_set_in_mask). In other words, if mask is zero, then zero bits are\n" +"set, so characters[] contains only one record. If `mask' is (SHIFT_MASK |\n" +"CONTROL_MASK), then two bits are set, so characters[] contains four\n" +"records.\n" +"\n" +"The first record always represents the character which is generated by that\n" +"key when no modifiers are active. The remaining records represent\n" +"characters generated by the various modifier combinations. Using the\n" +"example with the `shift' and `control' masks set, record two would\n" +"represent the character with the `shift' modifier active; record three, the\n" +"`control' modifier active; and record four, both the `shift' and `control'\n" +"modifiers active.\n" +"\n" +"As a special case, ALPHALOCK_MASK implies SHIFT_MASK, though only\n" +"ALPHALOCK_MASK appears in `mask'. In this case the same character is\n" +"generated for both the `shift' and `alpha-lock' modifiers, but only needs\n" +"to appear once in the characters[] array.\n" +"\n" +"CARRIAGE_RETURN_MASK does not actually refer to a modifier key. Instead,\n" +"it is used to distinguish the scan code which is given the special\n" +"pseudo-designation of `carriage return' key. Typically, this mask appears\n" +"solo in a ScanGroup record and only the two Character records for control-M\n" +"and control-C follow. This flag may be a throwback to an earlier time or\n" +"may be specially interpreted by the low-level keyboard driver, but its\n" +"purpose is otherwise enigmatic.\n" +"Character\n" +"---------\n" +"Each Character record indicates the character generated when this key is\n" +"pressed, as well as the character set which contains the character. Well\n" +"known character sets are `ASCII' and `Symbol'. The character set can also\n" +"be one of the meta values FUNCTION_KEY or KEY_SEQUENCE. If it is\n" +"FUNCTION_KEY then `char_code' represents a generally well-known function\n" +"key such as those enumerated by FunctionKey. If the character set is\n" +"KEY_SEQUENCE then `char_code' represents a zero-base index into\n" +"KeyMapping::sequence_lists[].\n" +"\n" +" enum CharacterSet {\n" +" ASCII = 0x00,\n" +" SYMBOL = 0x01,\n" +" ...\n" +" FUNCTION_KEY = 0xfe,\n" +" KEY_SEQUENCE = 0xff\n" +" };\n" +"\n" +" struct Character {\n" +" number set; // CharacterSet of generated character\n" +" number char_code; // Actual character generated\n" +" };\n" +"\n" +" enum FunctionKey {\n" +" F1 = 0x20, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,\n" +" INSERT, DELETE, HOME, END, PAGE_UP, PAGE_DOWN, PRINT_SCREEN,\n" +" SCROLL_LOCK, PAUSE, SYS_REQUEST, BREAK, RESET, STOP, MENU, USER,\n" +" SYSTEM, PRINT, CLEAR_LINE, CLEAR_DISPLAY, INSERT_LINE,\n" +" DELETE_LINE, INSERT_CHAR, DELETE_CHAR, PREV, NEXT, SELECT\n" +" };\n" +"\n" +"Sequence\n" +"--------\n" +"When Character::set contains the meta value KEY_SEQUENCE, the scan code is\n" +"bound to a sequence of keys rather than a single character. A sequence is\n" +"a series of modifiers and characters which are automatically generated when\n" +"the associated key is depressed.\n" +"\n" +" #define MODIFIER_KEY 0xff\n" +"\n" +" struct Sequence {\n" +" number num_chars;\n" +" Character characters[...];\n" +" };\n" +"\n" +"Each generated Character is represented as previously described, with the\n" +"exception that MODIFIER_KEY may appear in place of KEY_SEQUENCE. When the\n" +"value of Character::set is MODIFIER_KEY then Character::char_code\n" +"represents a modifier key rather than an actual character. If the modifier\n" +"represented by `char_code' is non-zero, then it indicates that the\n" +"associated modifier key has been depressed. In this case, the value is one\n" +"of the constants enumerated by Modifier (SHIFT, CONTROL, ALTERNATE, etc.).\n" +"If the value is zero then it means that the modifier keys have been\n" +"released.\n" +"\n" +"Special Key\n" +"-----------\n" +"A special key is one which is scanned directly by the Mach kernel rather\n" +"than by the WindowServer. In general, events are not generated for special\n" +"keys.\n" +"\n" +" enum SpecialKeyType {\n" +" VOLUME_UP = 0,\n" +" VOLUME_DOWN,\n" +" BRIGHTNESS_UP,\n" +" BRIGHTNESS_DOWN,\n" +" ALPHA_LOCK,\n" +" HELP,\n" +" POWER,\n" +" SECONDARY_ARROW_UP,\n" +" SECONDARY_ARROW_DOWN\n" +" };\n" +"\n" +" struct SpecialKey {\n" +" number type; // A SpecialKeyType constant\n" +" number scan_code; // Actual scan code\n" +" };\n" +"\n", f ); + } + + +//----------------------------------------------------------------------------- +// Print an explanation of the output generated by this program. +//----------------------------------------------------------------------------- +static void print_output_info( FILE* f ) + { + fputs( +"What follows is an explanation and description of the various pieces of\n" +"information emitted by dumpkeymap.\n" +"\n" +"For a more thorough discussion of any particular piece of information\n" +"described here, refer to the detailed description of the internal layout of\n" +"a key mapping given by the --help-layout option.\n" +"\n" +"Conventions\n" +"-----------\n" +"Depending upon context, some numeric values are displayed in decimal\n" +"notation, whereas others are displayed in hexadecimal notation.\n" +"Hexadecimal numbers are denoted by a `0x' prefix (for instance, `0x7b'),\n" +"except when explicitly noted otherwise.\n" +"\n" +"Key Mapping Source\n" +"------------------\n" +"The first piece of information presented about a particular key mapping is\n" +"the source from which the data was gleaned. For a .keymapping file, the\n" +"title `KEYMAP FILE' is emitted along with the path and name of the file in\n" +"question. For the key mapping currently in use by the WindowServer and\n" +"AppKit, the title `ACTIVE KEYMAP' is emitted instead.\n" +"\n" +"Device Information\n" +"------------------\n" +"Each .keymapping file may contain one or more raw key mappings. For\n" +"example, a file which maps keys to a Dvorak-style layout might contain raw\n" +"mappings for Intel PC, ADB, NeXT, and Sun Type5 keyboards.\n" +"\n" +"For each raw mapping, the following information is emitted:\n" +"\n" +" o The title `KEYMAP' along with the mapping's relative position in the\n" +" .keymapping file.\n" +" o The `interface' identifier.\n" +" o The `handler_id' sub-identifier.\n" +" o The size of the raw mapping resource counted in bytes.\n" +"\n" +"The `interface' and `handler_id' values, taken together, define a specific\n" +"keyboard device. A .keyboard file, which describes the visual layout of a\n" +"keyboard, also contains `interface' and `handler_id' identifiers. The\n" +".keyboard file corresponding to a particular key mapping can be found by\n" +"matching the `interface' and `handler_id' values from each resource.\n" +"\n" +"Modifiers\n" +"---------\n" +"Each mapping may contain zero or more modifier records which associate\n" +"hardware scan codes with modifier descriptions such as `shift', `control',\n" +"`alternate', etc. The title `MODIFIERS' is printed along with the count of\n" +"modifier records which follow. For each modifier record, the modifier's\n" +"name is printed along with a list of scan codes, in hexadecimal format,\n" +"which generate that modifier value. For example:\n" +"\n" +" MODIFIERS [4]\n" +" alternate: 0x1d 0x60\n" +" control: 0x3a\n" +" keypad: 0x52 0x53 ... 0x63 0x62\n" +" shift: 0x2a 0x36\n" +"\n" +"Characters\n" +"----------\n" +"Each mapping may contain zero or more character records which associate\n" +"hardware scan codes with the actual characters generated by those scan\n" +"codes in the presence or absence of various modifier combinations. The\n" +"title `CHARACTERS' is printed along with the count of character records\n" +"which follow. Here is a highly abbreviated example:\n" +"\n" +" CHARACTERS [9]\n" +" scan 0x00: -AC-L \"a\" \"A\" \"^A\" \"^A\" ca c7 \"^A\" \"^A\"\n" +" scan 0x07: -AC-L \"x\" \"X\" \"^X\" \"^X\" 01/b4 01/ce \"^X\" \"^X\"\n" +" scan 0x0a: ---S- \"<\" \">\"\n" +" scan 0x13: -ACS- \"2\" \"@\" \"^@\" \"^@\" b2 b3 \"^@\" \"^@\"\n" +" scan 0x24: R---- \"^M\" \"^C\"\n" +" scan 0x3e: ----- [F4]\n" +" scan 0x4a: ----- [page up]\n" +" scan 0x60: ----- {seq#3}\n" +" scan 0x68: not-bound\n" +"\n" +"For each record, the hexadecimal value of the hardware scan code is\n" +"printed, followed by a list of modifier flag combinations and the actual\n" +"characters generated by this scan code with and without modifiers applied.\n" +"\n" +"The modifier flags field is composed of a combination of single letter\n" +"representations of the various modifier types. The letters stand for:\n" +"\n" +" L - alpha-lock\n" +" S - shift\n" +" C - control\n" +" A - alternate\n" +" R - carriage-return\n" +"\n" +"As a special case, the `alpha-lock' flag also implies the `shift' flag, so\n" +"these two flags never appear together in the same record.\n" +"\n" +"The combination of modifier flags determines the meaning and number of\n" +"fields which follow. The first field after the modifier flags always\n" +"represents the character that will be generated if no modifier keys are\n" +"depressed. The remaining fields represent characters generated by the\n" +"various modifier combinations. The order of the fields follows this\n" +"general pattern:\n" +"\n" +" o The character generated by this scan code when no modifiers are in\n" +" effect is listed first.\n" +"\n" +" o If the `L' or `S' flag is active, then the shifted character\n" +" generated by this scan code is listed next.\n" +"\n" +" o If the `C' flag is active, then the control-character generated by\n" +" this scan code is listed next. Furthermore, if the `L' or `S' flag\n" +" is also active, then the shifted control-character is listed after\n" +" that.\n" +"\n" +" o If the `A' flag is active, then the alternate-character generated by\n" +" this scan code is listed next. Furthermore, if the `L' or `S' flag\n" +" is active, then the shifted alternate-character is listed after that.\n" +" If the `C' flag is also active, then the alternate-control-character\n" +" is listed next. Finally, if the `C' and `L' or `C' and `S' flags are\n" +" also active, then the shifted alternate-control-character is listed.\n" +"\n" +"The `R' flag does not actually refer to a modifier key. Instead, it is\n" +"used to distinguish the scan code which is given the special\n" +"pseudo-designation of `carriage return' key. Typically, this mask appears\n" +"solo and only the two fields for control-M and control-C follow. This flag\n" +"may be a throwback to an earlier time or may be specially interpreted by\n" +"the low-level keyboard driver, but its purpose is otherwise enigmatic.\n" +"\n" +"Recalling the example from above, the following fields can be identified:\n" +"\n" +" scan 0x00: -AC-L \"a\" \"A\" \"^A\" \"^A\" ca c7 \"^A\" \"^A\"\n" +"\n" +" o Lower-case `a' is generated when no modifiers are active.\n" +" o Upper-case `A' is generated when `shift' or `alpha-lock' are active.\n" +" o Control-A is generated when `control' is active.\n" +" o Control-A is generated when `control' and `shift' are active.\n" +" o The character represented by the hexadecimal code 0xca is generated\n" +" when `alternate' is active.\n" +" o The character represented by 0xc7 is generated when `alternate' and\n" +" `shift' (or `alpha-lock') are active.\n" +" o Control-A is generated when `alternate' and `control' are active.\n" +" o Control-A is generated when `alternate', `control' and `shift' (or\n" +" `alpha-lock') are active.\n" +"\n" +"The notation used to represent a particular generated character varies.\n" +"\n" +" o Printable ASCII characters are quoted, as in \"x\" or \"X\".\n" +"\n" +" o Control-characters are quoted and prefixed with `^', as in \"^X\".\n" +"\n" +" o Characters with values greater than 127 (0x7f) are displayed as\n" +" hexadecimal values without the `0x' prefix.\n" +"\n" +" o Characters in a non-ASCII character set (such as `Symbol') are\n" +" displayed as two hexadecimal numbers separated by a slash, as in\n" +" `01/4a'. The first number is the character set's identification code\n" +" (such as `01' for the `Symbol' set), and the second number is the\n" +" value of the generated character.\n" +"\n" +" o Non-printing special function characters are displayed with the\n" +" function's common name enclosed in brackets, as in `[page up]' or\n" +" `[F4]'.\n" +"\n" +" o If the binding represents a key sequence rather than a single\n" +" character, then the sequence's identification number is enclosed in\n" +" braces, as in `{seq#3}'.\n" +"\n" +"Recalling a few examples from above, the following interpretations can be\n" +"made:\n" +"\n" +" scan 0x07: -AC-L \"x\" \"X\" \"^X\" \"^X\" 01/b4 01/ce \"^X\" \"^X\"\n" +" scan 0x3e: ----- [F4]\n" +" scan 0x4a: ----- [page up]\n" +" scan 0x60: ----- {seq#3}\n" +"\n" +" o \"x\" and \"X\" are printable ASCII characters.\n" +" o \"^X\" is a control-character.\n" +" o `01/b4' and `01/ce' represent the character codes 0xb4 and 0xce in\n" +" the `Symbol' character set.\n" +" o Scan code 0x3e generates function-key `F4', and scan code 0x4a\n" +" generates function-key `page up'.\n" +" o Scan code 0x60 is bound to key sequence #3.\n" +"\n" +"Finally, if a scan code is not bound to any characters, then it is\n" +"annotated with the label `not-bound', as with example scan code 0x68 from\n" +"above.\n" +"\n" +"Sequences\n" +"---------\n" +"A scan code (modified and unmodified) can be bound to a key sequence rather\n" +"than generating a single character or acting as a modifier. When it is\n" +"bound to a key sequence, a series of character invocations and modifier\n" +"actions are automatically generated rather than a single keystroke.\n" +"\n" +"Each mapping may contain zero or more key sequence records. The title\n" +"`SEQUENCES' is printed along with the count of sequence records which\n" +"follow. For example:\n" +"\n" +" SEQUENCES [3]\n" +" sequence 0: \"f\" \"o\" \"o\"\n" +" sequence 1: {alternate} \"b\" \"a\" \"r\" {unmodify}\n" +" sequence 2: [home] \"b\" \"a\" \"z\"\n" +"\n" +"The notation used to represent the sequence of generated characters is\n" +"identical to the notation already described in the `Characters' section\n" +"above, with the exception that modifier actions may be interposed between\n" +"generated characters. Such modifier actions are represented by the\n" +"modifier's name enclosed in braces. The special name `{unmodify}'\n" +"indicates the release of the modifier keys.\n" +"\n" +"Thus, the sequences in the above example can be interpreted as follows:\n" +"\n" +" o Sequence #0 generates `foo'.\n" +" o Sequence #1 invokes the `alternate' modifier, generates `bar', and\n" +" then releases `alternate'.\n" +" o Sequence #2 invokes the `home' key and then generates `baz'. In a\n" +" text editor, this would probably result in `baz' being prepended to\n" +" the line of text on which the cursor resides.\n" +"\n" +"Special Keys\n" +"------------\n" +"Certain keyboards feature keys which perform some type of special purpose\n" +"function rather than generating a character or acting as a modifier. For\n" +"instance, Apple keyboards often contain a `power' key, and NeXT keyboards\n" +"have historically featured screen brightness and volume control keys.\n" +"\n" +"Each mapping may contain zero or more special-key records which associate\n" +"hardware scan codes with such special purpose functions. The title\n" +"`SPECIALS' is printed along with the count of records which follow. For\n" +"each record, the special function's name is printed along with a list of\n" +"scan codes, in hexadecimal format, which are bound to that function. For\n" +"example:\n" +"\n" +" SPECIALS [6]\n" +" alpha-lock: 0x39\n" +" brightness-down: 0x79\n" +" brightness-up: 0x74\n" +" power: 0x7f\n" +" sound-down: 0x77\n" +" sound-up: 0x73\n" +"\n", f ); + } + + +//----------------------------------------------------------------------------- +// Print a summary of the various files and directories which are related to +// key mappings. +//----------------------------------------------------------------------------- +static void print_files_info( FILE* f ) + { + fputs( +"This is a summary of the various files and directories which are related to\n" +"key mappings.\n" +"\n" +"*.keymapping\n" +" A key mapping file which precisely defines the relationship of all\n" +" hardware-specific keyboard scan-codes with their associated\n" +" functionality.\n" +"\n" +"*.keyboard\n" +" A file describing the physical layout of keys on a particular type of\n" +" keyboard. Each `key' token in this file defines the position and shape\n" +" of the key on the keyboard, as well as the associated scan code which\n" +" that key generates. A .keymapping file, on the other hand, defines the\n" +" characters which are generated by a particular scan code depending upon\n" +" the state of the various modifier keys (such as shift, control, etc.).\n" +" The `interface' and `handler_id' values from a .keymapping file are\n" +" matched against those in each .keyboard file in order to associate a\n" +" particular .keyboard file with a key mapping. Various GUI programs use\n" +" the .keyboard file to display a visual representation of a keyboard for\n" +" the user. Since these files are just plain text, they can be easily\n" +" viewed and interpreted without the aid of a specialized program, thus\n" +" dumpkeymap leaves these files alone.\n" +"\n" +"/System/Library/Keyboards\n" +"/Network/Library/Keyboards\n" +"/Local/Library/Keyboards\n" +"/Library/Keyboards\n" +" Repositories for .keymapping and .keyboard files for MacOS/X, Darwin,\n" +" and MacOS/X Server.\n" +"\n" +"/NextLibrary/Keyboards\n" +"/LocalLibrary/Keyboards\n" +" Repositories for .keymapping and .keyboard files for OpenStep and\n" +" NextStep.\n" +"\n" +"$(HOME)/Library/Keyboards\n" +" Repository for personal .keymapping and .keyboard files.\n" +"\n", f ); + } + + +//----------------------------------------------------------------------------- +// Print a list of the various diagnostic messages which may be emitted. +//----------------------------------------------------------------------------- +static void print_diagnostics_info( FILE* f ) + { + fputs( +"The following diagnostic messages may be issued to the standard error\n" +"stream.\n" +"\n" +"Unrecognized option.\n" +" An unrecognized option was specified on the command-line. Invoke\n" +" dumpkeymap with the --help option to view a list of valid options.\n" +"\n" +"Insufficient data in keymapping data stream.\n" +" The key mapping file or data stream is corrupt. Either the file has\n" +" been incorrectly truncated or a field, such as those which indicates\n" +" the number of variable records which follow, contains a corrupt value.\n" +"\n" +"The following diagnostic messages have significance only when trying to\n" +"print .keymapping files mentioned on the command-line.\n" +"\n" +"Bad magic number.\n" +" The mentioned file is not a .keymapping file. The file's content does\n" +" not start with the string `KYM1'.\n" +"\n" +"Unable to open key mapping file.\n" +" The call to fopen() failed; probably because the specified path is\n" +" invalid or dumpkeymap does not have permission to read the file.\n" +"\n" +"Unable to determine key mapping file size.\n" +" The call to fstat() failed, thus memory can not be allocated for\n" +" loading the file.\n" +"\n" +"Unable to read key mapping file.\n" +" The call to fread() failed.\n" +"\n" +"The following diagnostic messages have significance only when trying to\n" +"print the currently active key mapping when no .keymapping files have been\n" +"mentioned on the command-line.\n" +"\n" +"Unable to open event status driver.\n" +" The call to NXOpenEventStatus() failed.\n" +"\n" +"Bad key mapping length.\n" +" The call to NXKeyMappingLength() returned a bogus value.\n" +"\n" +"Unable to get current key mapping.\n" +" The call to NXGetKeyMapping() failed.\n" +"\n" +"The following diagnostic messages have significance only when using\n" +"dumpkeymap on a non-Apple/NeXT platform.\n" +"\n" +"Must specify at least one .keymapping file.\n" +" No .keymapping files were mentioned on the command-line. On\n" +" non-Apple/NeXT platforms, there is no concept of a currently active\n" +" .keymapping file, so at least one file must be mentioned on the\n" +" command-line.\n" +"\n", f ); + } + + +//----------------------------------------------------------------------------- +// Print warranty. +//----------------------------------------------------------------------------- +static void print_warranty( FILE* f ) + { + fputs( +"This software is provided by the author `AS IS' and any express or implied\n" +"WARRANTIES, including, but not limited to, the implied warranties of\n" +"MERCHANTABILITY and FITNESS FOR A PARTICULAR PURPOSE are DISCLAIMED. In NO\n" +"EVENT shall the author be LIABLE for any DIRECT, INDIRECT, INCIDENTAL,\n" +"SPECIAL, EXEMPLARY, or CONSEQUENTIAL damages (including, but not limited\n" +"to, procurement of substitute goods or services; loss of use, data, or\n" +"profits; or business interruption) however caused and on any theory of\n" +"liability, whether in contract, strict liability, or tort (including\n" +"negligence or otherwise) arising in any way out of the use of this\n" +"software, even if advised of the possibility of such damage.\n" +"\n", f ); + } + + +//----------------------------------------------------------------------------- +// Print this program's version number. +//----------------------------------------------------------------------------- +static void print_version( FILE* f ) + { + fputs( "Version " PROG_VERSION " (built " __DATE__ ")\n\n", f ); + } + + +//----------------------------------------------------------------------------- +// Print a usage summary. +//----------------------------------------------------------------------------- +static void print_usage( FILE* f ) + { + fputs( +"Usage: dumpkeymap [options] [-] [file ...]\n" +"\n" +"Prints a textual representation of each Apple/NeXT .keymapping file\n" +"mentioned on the command-line. If no files are mentioned and if the local\n" +"machine is an Apple or NeXT installation, then the key mapping currently in\n" +"use by the WindowServer and the AppKit is printed instead.\n" +"\n" +"Options:\n" +" -h --help\n" +" Display general program instructions and option summary.\n" +"\n" +" -k --help-keymapping\n" +" Display a detailed description of the internal layout of a\n" +" .keymapping file.\n" +"\n" +" -o --help-output\n" +" Display an explanation of the output generated by dumpkeymap when\n" +" dissecting a .keymapping file.\n" +"\n" +" -f --help-files\n" +" Display a summary of the various files and directories which are\n" +" related to key mappings.\n" +"\n" +" -d --help-diagnostics\n" +" Display a list of the various diagnostic messages which may be\n" +" emitted by dumpkeymap.\n" +"\n" +" -v --version\n" +" Display the dumpkeymap version number and warranty information.\n" +"\n" +" - --\n" +" Inhibit processing of options at this point in the argument list.\n" +" An occurrence of `-' or `--' in the argument list causes all\n" +" following arguments to be treated as file names even if an argument\n" +" begins with a `-' character.\n" +"\n", f ); + } + + +//----------------------------------------------------------------------------- +// Print an informational banner. +//----------------------------------------------------------------------------- +static void print_banner( FILE* f ) + { + fputs( "\n" PROG_NAME " v" PROG_VERSION " by " AUTHOR_INFO "\n" + COPYRIGHT "\n\n", f ); + } + + +//----------------------------------------------------------------------------- +// Process command-line arguments. Examine options first; collecting files +// along the way. If all is well, process collected file list. +//----------------------------------------------------------------------------- +int main( int const argc, char const* const argv[] ) + { + int rc = 0, i, nfiles = 0, more_options = 1, process_files = 1; + int* files = (int*)calloc( argc - 1, sizeof(int) ); + print_banner( stdout ); + + for (i = 1; i < argc; i++) + { + char const* const s = argv[i]; + if (!more_options || *s != '-') + files[ nfiles++ ] = i; + else + { + OPT_SWITCH(s) + OPT_CASE(-,--) + more_options = 0; + OPT_CASE(-h,--help) + print_usage( stdout ); + process_files = 0; + OPT_CASE(-k,--help-keymapping) + print_internal_layout_info( stdout ); + process_files = 0; + OPT_CASE(-o,--help-output) + print_output_info( stdout ); + process_files = 0; + OPT_CASE(-f,--help-files) + print_files_info( stdout ); + process_files = 0; + OPT_CASE(-d,--help-diagnostics) + print_diagnostics_info( stdout ); + process_files = 0; + OPT_CASE(-v,--version) + print_version( stdout ); + print_warranty( stdout ); + process_files = 0; + OPT_DEFAULT + fprintf( stderr, "ERROR: Unrecognized option: %s\n\n", s ); + process_files = 0; + rc = 1; + OPT_SWITCH_END + } + } + + if (process_files) + { + if (nfiles == 0) + rc = handle_empty_document_list(); + else + for (i = 0; i < nfiles; i++) + rc |= unparse_keymap_file( argv[files[i]] ); + } + + free( files ); + return rc; + } diff --git a/nx-X11/programs/Xserver/hw/darwin/utils/dumpkeymap.man b/nx-X11/programs/Xserver/hw/darwin/utils/dumpkeymap.man new file mode 100644 index 000000000..12983bada --- /dev/null +++ b/nx-X11/programs/Xserver/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$ +// +.. +.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 |