KBD(7) RISC/os Reference Manual 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 overstriking
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 key-
boards, or providing Dvorak keyboard emulation for QWERTY
keyboards). kbdcomp(1M) discusses table construction, the
input language, and contains sample uses. This document is
intended mainly to aid administrators in configuring the
module on a particular system; the user interface to the
module is solely through the commands kdbload 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 sys-
tem 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 avail-
able 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 beginning 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
Printed 11/19/92 Page 1
KBD(7) RISC/os Reference Manual KBD(7)
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 may be used in either the read or write directions,
or both simultaneously. Maps and hot-keys may be specified
independently for input and output.
The kbd also supports the use of external kernel-resident
functions as if they were tables; once declared and attached
(via kdbload 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 defini-
tion is contained in alp(7). External functions are espe-
cially useful in supporting multi-byte codeset conversions
that would be difficult or impossible with normal kbd
tables.
LIMITATIONS
It is not an error to attach multiple tables without defin-
ing 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 attachment
(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 otherwise 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
Page 2 Printed 11/19/92
KBD(7) RISC/os Reference Manual KBD(7)
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 allocated 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 pro-
duces a 1/5 second timeout.) Values from 5 to 400 inclusive
are allowed by the module; if the value set for KBDTIME 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
kbdcomp(1M), kbdload(1M), alp(7).
kbdset(1) in the User's Reference Manual.
Printed 11/19/92 Page 3