kb(7M) STREAMS Modules kb(7M)NAMEkb - keyboard STREAMS module
SYNOPSIS
#include <sys/types.h>
#include <sys/stream.h>
#include <sys/stropts.h>
#include <sys/vuid_event.h>
#include <sys/kbio.h>
#include <sys/kbd.h>
ioctl(fd, I_PUSH, "kb");
DESCRIPTION
The kb STREAMS module processes byte streams generated by a keyboard
attached to a CPU serial port. Definitions for altering keyboard trans‐
lation and reading events from the keyboard are contained in
<sys/kbio.h> and <sys/kbd.h>.
The kb STREAMS module utilizes a set of keyboard tables to recognize
which keys have been typed. Each translation table is an array of 128
16-bit words (unsigned shorts). If a table entry is less than 0x100,
the entry is treated as an ISO 8859/1 character. Higher values indicate
special characters that invoke more complicated actions.
Keyboard Translation Mode
The keyboard can be in one of the following translation modes:
TR_NONE Keyboard translation is turned off and up/down key
codes are reported.
TR_ASCII ISO 8859/1 codes are reported.
TR_EVENT firm_events are reported.
TR_UNTRANS_EVENT firm_events containing unencoded keystation codes
are reported for all input events within the window
system.
Keyboard Translation-Table Entries
All instances of the kb module share seven translation tables that con‐
vert raw keystation codes to event values. The tables are:
Unshifted Used when a key is depressed and no shifts are in effect.
Shifted Used when a key is depressed and a Shift key is held
down.
Caps Lock Used when a key is depressed and Caps Lock is in effect.
Alt Graph Used when a key is depressed and the Alt Graph key is
held down.
Num Lock Used when a key is depressed and Num Lock is in effect.
Controlled Used when a key is depressed and the Control key is held
down. (Regardless of whether a Shift key or the Alt Graph
is being held down, or whether Caps Lock or Num Lock is
in effect).
Key Up Used when a key is released.
Each key on the keyboard has a key station code that represents a num‐
ber from 0 to 127. The number is used as an index into the translation
table that is currently in effect. If the corresponding entry in the
translation table is a value from 0 to 255, the value is treated as an
ISO 8859/1 character, and the character is the result of the transla‐
tion.
If the entry in the translation table is higher than 255, it is a spe‐
cial entry. Special entry values are classified according to the value
of the high-order bits. The high-order value for each class is defined
as a constant, as shown below. When added to the constant, the value of
the low-order bits distinguish between keys within each class:
SHIFTKEYS 0x100 A shift key. The value of the particular shift key
is added to determine which shift mask to apply:
CAPSLOCK 0 Caps Lock key.
SHIFTLOCK 1 "Shift Lock" key.
LEFTSHIFT 2 Left-hand Shift key.
RIGHTSHIFT 3 Right-hand Shift key.
LEFTCTRL 4 Left-hand (or only) Control key.
RIGHTCTRL 5 Right-hand Control key.
ALTGRAPH 9 Alt Graph key.
ALT 10 Alternate or Alt key.
NUMLOCK 11 Num Lock key.
BUCKYBITS 0x200 Used to toggle mode-key-up/down status without
altering the value of an accompanying ISO 8859/1
character. The actual bit-position value, minus 7,
is added.
METABIT 0 The Meta key was pressed along with
the key. This is the only user-acces‐
sible bucky bit. It is ORed in as the
0x80 bit; since this bit is a legiti‐
mate bit in a character, the only way
to distinguish between, for example,
0xA0 as META+0x20 and 0xA0 as an
8-bit character is to watch for META
key up and META key down events and
keep track of whether the META key
was down.
SYSTEMBIT 1 The System key was pressed. This is a
place holder to indicate which key is
the system-abort key.
FUNNY 0x300 Performs various functions depending on the value of
the low 4 bits:
NOP 0x300 Does nothing.
OOPS 0x301 Exists, but is undefined.
HOLE 0x302 There is no key in this position
on the keyboard, and the posi‐
tion-code should not be used.
RESET 0x306 Keyboard reset.
ERROR 0x307 The keyboard driver detected an
internal error.
IDLE 0x308 The keyboard is idle (no keys
down).
COMPOSE 0x309 The COMPOSE key; the next two
keys should comprise a two-char‐
acter COMPOSE key sequence.
NONL 0x30A Used only in the Num Lock table;
indicates that this key is not
affected by the Num Lock state,
so that the translation table to
use to translate this key should
be the one that would have been
used had Num Lock not been in
effect.
0x30B — 0x30F Reserved for non-parameterized
functions.
FA_CLASS 0x400 A floating accent or "dead key." When this key is
pressed, the next key generates an event for an
accented character; for example, "floating accent
grave" followed by the "a" key generates an event
with the ISO 8859/1 code for the "a with grave
accent" character. The low-order bits indicate which
accent; the codes for the individual "floating
accents" are as follows:
FA_UMLAUT 0x400 umlaut
FA_CFLEX 0x401 circumflex
FA_TILDE 0x402 tilde
FA_CEDILLA 0x403 cedilla
FA_ACUTE 0x404 acute accent
FA_GRAVE 0x405 grave accent
STRING 0x500 The low-order bits index a table of strings. When a
key with a STRING entry is depressed, the characters
in the null-terminated string for that key are sent,
character-by-character. The maximum length is
defined as:
KTAB_STRLEN 10
Individual string numbers are defined as:
HOMEARROW 0x00
UPARROW 0x01
DOWNARROW 0x02
LEFTARROW 0x03
RIGHTARROW 0x04
String numbers 0x05 — 0x0F are available for custom
entries.
FUNCKEYS 0x600 There are 64 keys reserved for function keys. The
actual positions are usually on the
left/right/top/bottom of the keyboard.
The next-to-lowest 4 bits indicate the group of
function keys:
LEFTFUNC 0x600
RIGHTFUNC 0x610
TOPFUNC 0x610 0x610
BOTTOMFUNC 0x630
The low 4 bits indicate the function key number
within the group:
LF(n) (LEFTFUNC+(n)-1)
RF(n) (RIGHTFUNC+(n)-1)
TF(n) (TOPFUNC+(n)-1)
BF(n) (BOTTOMFUNC+(n)-1)
PADKEYS 0x700 A "numeric keypad key." These entries should appear
only in the Num Lock translation table; when Num Lock
is in effect, these events will be generated by press‐
ing keys on the right-hand keypad. The low-order bits
indicate which key. The codes for the individual keys
are:
PADEQUAL 0x700 "=" key
PADSLASH 0x701 "/" key
PADSTAR 0x702 "*" key
PADMINUS 0x703 "-" key
PADSEP 0x704 "," key
PAD7 0x705 "7" key
PAD8 0x706 "8" key
PAD9 0x707 "9" key
PADPLUS 0x708 "+" key
PAD4 0x709 "4" key
PAD5 0x70A "5" key
PAD6 0x70B "6" key
PAD1 0x70C "1" key
PAD2 0x70D "2" key
PAD3 0x70E "3" key
PAD0 0x70F "0" key
PADDOT 0x710 "." key
PADENTER 0x711 "Enter" key
When a function key is pressed in TR_ASCII mode, the following escape
sequence is sent:
ESC[0....9z
where ESC is a single escape character and "0...9" indicates the deci‐
mal representation of the function-key value. For example, function key
R1 sends the sequence:
ESC[208z
because the decimal value of RF(1) is 208. In TR_EVENT mode, if there
is a VUID event code for the function key in question, an event with
that event code is generated; otherwise, individual events for the
characters of the escape sequence are generated.
Keyboard Compatibility Mode
When started, the kb STREAMS module is in the compatibility mode. When
the keyboard is in the TR_EVENT translation mode, ISO 8859/1 characters
from the upper half of the character set (that is, characters with the
eighth bit set) , are presented as events with codes in the ISO_FIRST
range (as defined in <<sys/vuid_event.h>>). For backwards compatibility
with older versions of the keyboard driver, the event code is ISO_FIRST
plus the character value. When compatibility mode is turned off, ISO
8859/1 characters are presented as events with codes equal to the char‐
acter code.
DESCRIPTION
The following ioctl() requests set and retrieve the current translation
mode of a keyboard:
KIOCTRANS Pointer to an int. The translation mode is set to the
value in the int pointed to by the argument.
KIOCGTRANS Pointer to an int. The current translation mode is stored
in the int pointed to by the argument.
ioctl() requests for changing and retrieving entries from the keyboard
translation table use the kiockeymap structure:
struct kiockeymap {
int kio_tablemask; /* Translation table (one of: 0, CAPSMASK,
* SHIFTMASK, CTRLMASK, UPMASK,
* ALTGRAPHMASK, NUMLOCKMASK)
*/
#define KIOCABORT1 -1 /* Special "mask": abort1 keystation */
#define KIOCABORT2 -2 /* Special "mask": abort2 keystation */
uchar_t kio_station; /* Physical keyboard key station (0-127) */
ushort_t kio_entry; /* Translation table station's entry */
char kio_string[10]; /* Value for STRING entries-null terminated */
};
KIOCSKEY Pointer to a kiockeymap structure. The translation table
entry referred to by the values in that structure is
changed. The kio_tablemask request specifies which of the
following translation tables contains the entry to be modi‐
fied:
UPMASK 0x0080
"Key Up" translation table.
NUMLOCKMASK 0x0800
"Num Lock" translation table.
CTRLMASK 0x0030
"Controlled" translation table.
ALTGRAPHMASK 0x0200
"Alt Graph" translation table.
SHIFTMASK 0x000E
"Shifted" translation table.
CAPSMASK 0x0001
"Caps Lock" translation table.
(No shift keys pressed or locked)
"Unshifted" translation table.
The kio_station request specifies the keystation code for the entry to
be modified. The value of kio_entry is stored in the entry in question.
If kio_entry is between STRING and STRING+15, the string contained in
kio_string is copied to the appropriate string table entry. This call
may return EINVAL if there are invalid arguments.
Special values of kio_tablemask can affect the two step "break to the
PROM monitor" sequence. The usual sequence is L1-a or Stop-. If
kio_tablemask is KIOCABORT1, then the value of kio_station is set to be
the first keystation in the sequence. If kio_tablemask, is KIOCABORT2
then the value of kio_station is set to be the second keystation in the
sequence. An attempt to change the "break to the PROM monitor"
sequence without having superuser permission results in an EPERM
error.
KIOCGKEY The argument is a pointer to a kiockeymap structure. The
current value of the keyboard translation table entry spec‐
ified by kio_tablemask and kio_station is stored in the
structure pointed to by the argument. This call may return
EINVAL if there are invalid arguments.
KIOCTYPE The argument is a pointer to an int. A code indicating the
type of the keyboard is stored in the int pointed to by the
argument:
KB_SUN3 Sun Type 3 keyboard
KB_SUN4 Sun Type 4 or 5 keyboard, or non-USB Sun Type
6 keyboard
KB_USB USB standard HID keyboard, including Sun Type
6 USB keyboards
KB_ASCII ASCII terminal masquerading as keyboard
KB_PC Type 101 PC keyboard
KB_DEFAULT Stored in the int pointed to by the argument
if the keyboard type is unknown. In case of
error, -1 is stored in the int pointed to by
the argument.
KIOCLAYOUT The argument is a pointer to an int. On a Sun Type 4 key‐
board, the layout code specified by the keyboard's DIP
switches is stored in the int pointed to by the argument.
KIOCCMD The argument is a pointer to an int. The command speci‐
fied by the value of the int pointed to by the argument
is sent to the keyboard. The commands that can be sent
are:
Commands to the Sun Type 3 and Sun Type 4 keyboards:
KBD_CMD_RESET Reset keyboard as if power-up.
KBD_CMD_BELL Turn on the bell.
KBD_CMD_NOBELL Turn off the bell.
KBD_CMD_CLICK Turn on the click annunciator.
KBD_CMD_NOCLICK Turn off the click annunciator.
Commands to the Sun Type 4 keyboard:
KBD_CMD_SETLED Set keyboard LEDs.
KBD_CMD_GETLAYOUT Request that keyboard indicate lay‐
out.
Inappropriate commands for particular keyboard types are ignored. Since
there is no reliable way to get the state of the bell or click (because
the keyboard cannot be queried and a process could do writes to the
appropriate serial driver — circumventing this ioctl() request) an
equivalent ioctl() to query its state is not provided.
KIOCSLED The argument is a pointer to an char. On the Sun Type 4
keyboard, the LEDs are set to the value specified in that
char. The values for the four LEDs are:
LED_CAPS_LOCK "Caps Lock" light.
LED_COMPOSE "Compose" light.
LED_SCROLL_LOCK "Scroll Lock" light.
LED_NUM_LOCK "Num Lock" light.
On some Japanese layouts, the value for the fifth LED is:
LED_KANA "Kana" light.
KIOCGLED Pointer to a char. The current state of the LEDs is
stored in the char pointed to by the argument.
KIOCSCOMPAT Pointer to an int. "Compatibility mode" is turned on if
the int has a value of 1, and is turned off if the int
has a value of 0.
KIOCGCOMPAT Pointer to an int. The current state of "compatibility
mode" is stored in the int pointed to by the argument.
The following ioctl() request allows the default effect of the keyboard
abort sequence to be changed.
KIOCSKABORTEN Pointer to an int. The keyboard abort sequence effect
(typically L1-A or Stop-A on the keyboard on SPARC
systems, F1-A on x86 systems, and BREAK on the serial
console device) is enabled if the int has a value of
KIOCABORTENABLE(1). If the value is KIOCABORTDIS‐
ABLE(0) , the keyboard abort sequence effect is dis‐
abled. If the value is KIOCABORTALTERNATE(2), the
Alternate Break sequence is in effect and is defined
by the serial console drivers zs(7D)se(7D) and
asy(7D). Any other value of the parameter for this
ioctl() is treated as enable. The Alternate Break
sequence is applicable to the serial console devices
only.
Due to a risk of incorrect sequence interpretation,
SLIP and certain other binary protocols should not be
run over the serial console port when Alternate Break
sequence is in effect. Although PPP is a binary proto‐
col, it is able to avoid these sequences using the
ACCM feature in RFC 1662. For Solaris PPP 4.0, you do
this by adding the following line to the
/etc/ppp/options file (or other configuration files
used for the connection; see pppd(1M) for details):
asyncmap 0x00002000
SLIP has no comparable capability, and must not be
used if the Alternate Break sequence is in use.
This ioctl() will be active and retain state even if
there is no physical keyboard in the system. The
default effect (enable) causes the operating system to
suspend and enter the kernel debugger (if present) or
the system prom (on most systems with OpenBoot proms).
The default effect is enabled on most systems, but may
be different on server systems with key switches in
the 'secure' position. On these systems, the effect is
always disabled when the key switch is in the 'secure'
position. This ioctl()returns EPERM if the caller is
not the superuser.
These ioctl() requests are supported for compatibility with the system
keyboard device /dev/kbd.
KIOCSDIRECT Has no effect.
KIOCGDIRECT Always returns 1.
The following ioctl() requests are used to set and get the keyboard
autorepeat delay and rate.
KIOCSRPTDELAY This argument is a pointer to an int, which is the kb
autorepeat delay, unit in millisecond.
KIOCGRPTDELAY This argument is a pointer to an int. The current auto
repeat delay setting is stored in the integer pointed
by the argument, unit in millisecond.
KIOCSRPTRATE This argument is a pointer to an int, which is the kb
autorepeat rate, unit in millisecond.
KIOCGRPTRATE This argument is a pointer to an int. The current auto
repeat rate setting is stored in the integer pointed
by the argument, unit in millisecond.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ATTRIBUTE TYPE │ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOkbd(1), kmdb(1), loadkeys(1), pppd(1M), keytables(4), attributes(5),
zs(7D), se(7D), asy(7D), virtualkm(7D), termio(7I), usbkbm(7M)NOTES
Many keyboards released after Sun Type 4 keyboard also report them‐
selves as Sun Type 4 keyboards.
SunOS 5.11 26 Feb 2004 kb(7M)
