KEYBIND(1)

NAME
keybind - key-map editor for XENIX and UNIX V.3.2 386 machines

SYNOPSIS
keybind [-mdr] [-] [files...] [ -o outfile ]

DESCRIPTION
This utility enables you to inspect and modify the console keyboard driver tables on for any UNIX version using the XENIX/386 keyboard driver (this includes recent and future AT&T UNIX releases).

  Theory of Operation
At startup, keybind reads in the current keyboard maps. After interpreting all switches and digesting whatever input sources are specified, it attempts to write the resulting map and any changes in string assignments back to the mapping tables for your tty.

Called with no arguments or with the argument - representing standard input, keybind may be used interactively or fed from a keyboard map file; the mini-language used to describe key definitions is documented below.

The -d flag dumps the current keyboard table in a format keybind will accept as input; this is useful for inspecting key definitions. The -r and -m flags are intended to facilitate noninteractive use from scripts; the former restores the default key mappings, and the latter enables Alt as a true Meta key.

The flags (and -) may be used in any combination and will trigger their actions in the order they are given. Arguments mixed with the flags are taken as the names of keyboard map files to be processed.

The -o flag (which requires a filename argument) causes the contents of the keymap and stringmap tables at the end of a keybind run to be dumped in binary form to the given filename. These dump files will be read in properly (and their contents loaded into the program's map-table space) when presented as filename arguments to later keybind runs.

This is much faster than an interpreting the equivalent text, because it concentrates the I/O into one belt and avoids the lexer/parser execution time cost. Thus you can use -o to precompile a keyboard setup so that subsequent keymap runs are very quick.

  Enabling Alt as a Meta key
The -m option or the `meta' directive will remap the keyboard on so that the Alt key acts as a meta key when combined with any printable character, or any shift-control modification of a printable; that is, it turns on the high (0x80) bit of the character.

This is useful with GNU EMACS. To see why, run it, pull up an EMACS, set the meta-flag global to non-nil, type ALT-x, and notice that it works! To arrange this behavior by default, you might put a `keybind -m' in an initialization script under /etc/rc2.d to be executed whenever the system enters multiuser mode.

Note: the ISTRIP bit must be off in your termio structure for your meta key to work (otherwise the driver will happily strip the meta bit off your input keystroke before making it available to the application). GNU EMACS does this itself; for other applications you may need to do an explicit stty -istrip or a TCSETA{W} ioctl.

Function keys and control-character keys and other special keys are not affected by the alt-enable operation. Pains are also taken that this change not step on window manager keys or other important special functions; specifically, it only modifies key/state pairs that are bound to the nop, escl, escn or esco functions.

  Keymap Definition Files
The output of keybind -d is a keymap definition file describing the current state of your keyboard. The syntax has been designed to resemble the conventions used in the keyboard(7) entry as closely as possible.

Each map file is parsed as a sequence of newline- or semicolon-separated commands or comments. Case of alphabetics and whitespace are ignored everywhere except within character literals and strings. Comments may begin at any point with # and continue to end of line. Each command may be a directive, a key definition, a string assignment, or a shift modifier.

The following directives are defined:

restore -- resets to the default bindings given in the keyboard(7) manual. Must be used with caution, see the BUGS note below.

meta -- enables the Alt key to function as a true meta, as with the -m option (see above).

dump -- dumps portions of the keymap table. Without arguments it dumps the entire table. It may take a list of scan-code ranges (see below) as arguments, in which case it dumps only the relevant characters.

funkeys -- dumps portions of the function key table. Without arguments it dumps the entire table. It may take a list of function-key ranges (that is, fkey special values or dash-separated pairs of same) as arguments, in which case it dumps only those function keys.

clearstrings -- normally, strings assigned to function keys are added to those already present in the keyboard driver's string table. If you don't need the defaults, this wastes some of the limited space available for key mappings. The clearstrings directive clears the string assignment table (no defaults are saved). Try using it if you get the `out of string space' abort message.

capslock -- dumps information on which keys are affected by caps lock.

numlock -- dumps information on which keys are affected by num lock.

execute -- sends pending keymap changes to the tty immediately using the code normally called just before program exit. Intended for interactive use.

help -- prints a command summary. Intended for interactive use; it also turns on an asterisk prompt, which is turned off on EOF.

As a convenience for interactive use, any directive may be abbreviated to its first two letters.

Key definitions may consist of scan-code assignments or key-state assignments. The output of `keybind -d' is a list of scan-code assignments for all defined scan-codes. Each one consists of a scan-code specifier followed by at most eight key values, one for each shift state. If fewer than eight values are given, states changed start from the left of the table. A state may be skipped by putting a dash in its place in the list.

Scan-code specifiers always begin with a @ (at-sign). There are two kinds; numeric and mnemonic. The former always consists of three zero filled decimal digits after the @, giving the scan code's value. Mnemonic specifiers, usually duplicate the graphic on the key cap to which the scan code corresponds after the @. The output of `keybind -d' includes all valid mnemonic scan-code specifiers in the leftmost column. The two sets are not mutually exclusive; the unlisted numeric specifiers corresponding to mnemonics are also valid.

Key values may consist of character values or special values. Special values are those listed in keyboard(7), plus the following additions:

vt[0-9]* - the virtual terminal selectors.

mgr[0-9]* - the virtual terminal manager selectors.

pfx[0-9]* - undocumented, but in sys/kd.h; you tell me.

A character value may consist of any of the standard mnemonics for control characters (refer to keybind -rd output for a nearly complete list; `nl' (0x0a), `ht' (0x08) and `csi' (0x9b) are also accepted) or a Iliteral.

Literals have the syntax of C character constants, with some additions. The backslash escape form \xnn permits the use of two-digit hex constants. The backslash escape form \dnnn permits the use of three-digit decimal constants. C-style octal escapes and special characters \n, \r, \t, \b, \v are correcrtly interpreted. Also, the literal '\e' is interpreted as ASCII escape (0x1b). Two-character literals of the form '^c' are interpreted as control characters. Two-character literals of the form '!c' are interpreted as meta characters; that is, the value is that of the second character with the meta (0x80) bit turned on. The case of literals is preserved.

Key-state assignments set the value of a single key/state combination. They consist of an optional shift prefix, a scan-code specifier, an equals sign and a key value. The shift prefix identifies the state of the key corresponding to the scan code to which the key value should be assigned. The shift prefix may consist of the combination of the words alt, shift, ctrl, optionally trailed by hyphens. A key-state assignment with no prefix applies to the normal (unshifted) state of the key.

String assignments consist of a function key name, followed by an equals sign, followed by a string literal. String literals preserve case and have the syntax of C strings, with the same additional escape conventions as described above for character literals.

Finally, shift modifiers are used to control which characters are subject to shift-key modification. Each should begin with one of the keywords shiftlock, capslock, or numlock; shiftlock and capslock are equivalent. This should be followed by one of the words `enabled' or `disabled' and a list of ranges of scan codes. If the list is empty, the shift modifier is applied to all scan codes.

A range may be either a single scan code or a dash-separated pair of scan codes; the latter is interpreted as all scan codes numerically greater than or equal to the first and less than or equal to the second.

EXAMPLE
The author finds the command file given as figure 1 below quite useful. To understand what it does, first note the following:

If keybind is run from the console before vtlmgr, the key mappings will apply to all virtual terminals. However, string-key loadings will be changed on the console only. Thus, to give a key/state combination the same value (usable by an application that can do its own key bindings, such as EMACS) across all virtual terminals, it is best to bind it to an esco/escn/escl value rather than indirecting through a function key.
Fig 1: sample.kmf

BUGS
Due to the absence of a reset ioctl(), the mappings that -r and the `restore' command reset to come from tables dumped out of 3.2u, tweaked to match the defaults tables in keyboard(7) and included into the code. If you have reason to suspect that the system defaults have changed, you can recompile with -DREGEN and replace the system-default initializers with the output of a `keybind -c'.

Restoring defaults doesn't undo changes in the enabling of the shift-lock and num-lock keys.

Error handling in the keyboard map description parser is rudimentary.

Beware of confusing @[0-9] with @00[9]; the former are mnemonics for the digit-key scan codes, the latter represent numeric scan codes.

PORTABILITY NOTE
This code should work on any AT/ISA/EISA box running XENIX/386 or an un-munged port of AT&T UNIX at release 3.2 or later. To check this, look for the GIO_KEYMAP and SIO_KEYMAP ioctls in keyboard(7); if these are present, you have the XENIX keyboard driver and keybind should do the right thing.

AUTHOR
Eric S. Raymond <esr@snark.thyrsus.com)

SEE ALSO
keyboard(7)