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, 0 insertions, 2579 deletions
diff --git a/nx-X11/programs/Xserver/hw/darwin/utils/Imakefile b/nx-X11/programs/Xserver/hw/darwin/utils/Imakefile deleted file mode 100644 index b6ad53d8b..000000000 --- a/nx-X11/programs/Xserver/hw/darwin/utils/Imakefile +++ /dev/null @@ -1,10 +0,0 @@ -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 deleted file mode 100644 index fb6d4399e..000000000 --- a/nx-X11/programs/Xserver/hw/darwin/utils/README.txt +++ /dev/null @@ -1,111 +0,0 @@ -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 deleted file mode 100644 index 8f3340b15..000000000 --- a/nx-X11/programs/Xserver/hw/darwin/utils/dumpkeymap.c +++ /dev/null @@ -1,1454 +0,0 @@ -// $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 deleted file mode 100644 index 12983bada..000000000 --- a/nx-X11/programs/Xserver/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 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 |