kbd(7) 04 Jun 1992 kbd(7)
NAME
kbd - generalized string translation module
DESCRIPTION
The STREAMS module kbd is a programmable string translation module.
It can perform two types of operations on an input stream: the first
type is simple byte-swapping via a lookup table, the second is string
translation. It is useful for codeset conversion and compose-key or
dead-key character production on terminals and production of over-
striking sequences on printers. It may also be used for minor types
of key-rebinding, expansion of abbreviations, and keyboard re-
arrangement (an example of the latter would be swapping the positions
of the Y and Z keys, required for German keyboards, or providing
Dvorak keyboard emulation for QWERTY keyboards). The manual entry
kbdcomp(1M) discusses table construction, the input language, and con-
tains sample uses. This document is intended mainly to aid administra-
tors in configuring the module on a particular system; the user inter-
face to the module is solely through the commands kbdload and kbdset.
The kbd module works by modifying an input stream according to
instructions embodied in tables. It has no built in ``default''
tables. Some tables may be loaded when the system is first brought up
by pushing the module and loading standard or often-used tables [see
kbdload(1M)] which are retained in main-memory across invocations and
made available to all users. These are called public tables. Users
may also load private tables at any time-these do not remain resident.
With the kbdset command, users may query the module for a list of
available and attached tables, attach various tables, and set the
optional per-user hot-key, hot-key mode, and verbose string for their
particular invocation.
When a user attaches more than one table, the user's hot-key may be
used to cycle to the next table in the list. If only one table is
specified, the hot-key may be used to toggle translation on and off.
When multiple tables are in use, the hot-key may be used to cycle
through the list of tables [see kbdset(1) for a description of the
available modes].
In its initial state, kbd scans input for occurrences of bytes begin-
ning a translation sequence. Upon receiving such a byte, it attempts
to match subsequent bytes of the input to programmed sequences. Input
is buffered beginning with the byte which caused the state change and
is released if a match is not found. When a match fails, the first
byte of the invalid sequence is sent upstream, the buffered input is
``shifted,'' and the scan begins again with the resulting input
sequence. If the current table contains an error entry, its value (one
or more bytes) is substituted for the offending input byte. When a
sequence is found to be valid, the entire sequence is replaced with
the result string specified for it.
The kbd module may be used in either the read or write directions, or
Page 1 Reliant UNIX 5.44 6, 194
kbd(7) 04 Jun 1992 kbd(7)
both simultaneously. Maps and hot-keys may be specified independently
for input and output.
The kbd module also supports the use of external kernel-resident func-
tions as if they were tables; once declared and attached (via kbdload
and kbdset respectively) they may be used as simple tables or members
of composites. To accomplish this, kbd understands the registration
functions of the alp module and can access any function registered
with that module. Further information on external functions and their
definition is contained in alp(7). External functions are especially
useful in supporting multi-byte codeset conversions that would be dif-
ficult or impossible with normal kbd tables.
LIMITATIONS
It is not an error to attach multiple tables without defining a hot-
key (but the tables will not all be accessible). It is recommended
that the user's hot-key be set before loading and attaching tables to
avoid unpleasant side effects when an unfamiliar arrangement is first
loaded.
Each user has a limitation on the amount of memory that may be used
for private and attached tables. This ``quota'' is controlled by the
kbd_umem variable described below. When a user that is not the super-
user attempts to load a table or create a composite table, the quota
is checked, and the load will fail if it would cause the quota to be
exceeded. When a composite table is attached, the space for attach-
ment (which requires more space than the composite table itself) is
charged against this quota (attachment of simple tables is not charged
against the quota). The quota is enforced only when loading new
tables. Detaching temporarily from un-needed composite tables may
reduce the current allocation enough to load a table that would other-
wise fail due to quota enforcement. To minimize chances of failure
while loading tables, it is advisable to load all required tables and
make all required composite tables before attaching any of them.
CONFIGURATION PARAMETERS
The master (or space.c) file contains some configurable parameters.
NKBDU is the maximum number of tables that may be attached by a single
user. The number should be enough to cover uncommon cases, but must
be at least 2. Default: 6.
ZUMEM, from which the variable kbd_umem is assigned, is the maximum
number of bytes that a user (other than the super user) may have allo-
cated to private tables (i.e., the quota). Default: 4096.
KBDTIME is the default timer value for timeout mode. It is the number
of clock ticks allowed before timing out. The value of one ``clock
tick'' depends on the hardware, but is usually 1/100 or 1/60 of a
second. A timeout value of 20 is 1/5 second at 100Hz; with a 60Hz
clock, a value of 12 produces a 1/5 second timeout.) Values from 5 to
400 inclusive are allowed by the module; if the value set for KBDTIME
Page 2 Reliant UNIX 5.44 6, 194
kbd(7) 04 Jun 1992 kbd(7)
is outside this range, the module forces it to the nearest limit.
(This value is only a default; users may change their particular
Stream to use a different value depending on their own preferences,
terminal baud-rate, and typing speed.)
CAVEATS
NULL characters may not be used in result or input strings, because
they are used as string delimiters.
One should be able to obtain information on timeout values of
currently attached tables, and be able to reset values more easily.
FILES
/usr/lib/kbd directory containing system standard table
files.
/usr/lib/kbd/*.map source for some system table files.
SEE ALSO
kbdset(1), kbdcomp(1M), kbdload(1M), alp(7).
Page 3 Reliant UNIX 5.44 6, 194