kb - keyboard STREAMS module


     #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");


     The kb STREAMS module processes byte streams generated by  a
     keyboard  attached  to  a  CPU  serial port. Definitions for
     altering keyboard translation 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 charac-
     ters that invoke more complicated actions.

  Keyboard Translation Mode
     The keyboard can be in  one  of  the  following  translation

           Keyboard translation is turned  off  and  up/down  key
           codes are reported.

           ISO 8859/1 codes are reported.

           firm_events are reported.

           firm_events containing unencoded keystation codes  are
           reported  for  all input events within the window sys-

  Keyboard Translation-Table Entries

     All instances of  the  kb  module  share  seven  translation
     tables  that  convert  raw keystation codes to event values.
     The tables are:

                Used when a key is depressed and no shifts are in

                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

          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

                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 number 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

     If the entry in the translation table is higher than 255, it
     is  a  special  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

                 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-accessible bucky
                      bit. It is ORed in as the 0x80  bit;  since
                      this  bit  is a legitimate bit in a charac-
                      ter, 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 position-code should not
                      be used.

                RESET 0x306
                      Keyboard reset.

                ERROR 0x307
                      The keyboard driver  detected  an  internal

                IDLE 0x308
                      The keyboard is idle (no keys down).

                COMPOSE 0x309
                      The COMPOSE key; the next two  keys  should
                      comprise   a   two-character   COMPOSE  key

                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

                FA_CFLEX 0x401

                FA_TILDE 0x402

                FA_CEDILLA 0x403

                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 char-
                acters in the null-terminated string for that key
                are  sent,  character-by-character.   The maximum
                length is defined as:


     Individual string numbers are defined as:






          String numbers 0x05 - 0x0F  are  available  for  custom

     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  func-
           tion keys:



           TOPFUNC 0x610


     The low 4 bits indicate the function key number  within  the

     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

           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 follow-
     ing escape sequence is sent:


     where  ESC is a single escape character  and  "0...9"  indi-
     cates  the decimal representation of the function-key value.
     For example, function key R1 sends the sequence:


     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 ques-
     tion, 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 compatibil-
     ity with older versions of the keyboard  driver,  the  event
     code is ISO_FIRST plus the character value. When compatibil-
     ity mode is turned off, ISO 8859/1 characters are  presented
     as events with codes equal to the character code.


     The following ioctl() requests set and retrieve the  current
     translation mode of a keyboard:

           Pointer to an int. The translation mode is set to  the
           value in the int pointed to by the argument.

           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) */

           Pointer to a  kiockeymap  structure.  The  translation
           table  entry  referred to by the values in that struc-
           ture is changed. The kio_tablemask  request  specifies
           which of the following translation tables contains the
           entry to be modified:

           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 moni-
     tor" sequence without having superuser permission results in
     an  EPERM error.

           The argument is a pointer to a  kiockeymap  structure.
           The  current  value  of the keyboard translation table
           entry specified 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 argu-

           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:

                 Sun Type 3 keyboard

                 Sun Type 4 keyboard

                 ASCII terminal masquerading as keyboard

           KB_PC Type 101 PC keyboard

                  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  argu-

           The argument is a pointer to an int. On a Sun  Type  4
           keyboard,  the layout code specified by the keyboard's
           DIP switches is stored in the int pointed  to  by  the

           The argument is a  pointer  to  an  int.  The  command
           specified  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:

                 Reset keyboard as if power-up.

                 Turn on the bell.

                 Turn off the bell.

                 Turn on the click annunciator.

                 Turn off the click annunciator.

     Commands to the Sun Type 4 keyboard:

                 Set keyboard LEDs.

                 Request that keyboard indicate layout.

     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.

           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:

                 "Caps Lock" light.

                 "Compose" light.

                 "Scroll Lock" light.

                 "Num Lock" light.

           On some Japanese layouts, the value for the fifth  LED

                      "Kana" light.

           Pointer to a char. The current state of  the  LEDs  is
           stored in the char pointed to by the argument.

           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.

           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.

           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. When the Alternate Break sequence is in  effect,
           binary  protocols  including  PPP, SLIP, file transfer
           and others should not be run over the  console  serial

           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.

           Has no effect.

           Always returns 1.


     See attributes(5) for descriptions of the  following  attri-

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Interface Stability         | Stable                      |


     kbd(1),  loadkeys(1), kadb(1M), keytables(4), attributes(5),
     zs(7D),  se(7D),  asy(7D)  termio(7I)


     Many of the keyboards released after  Sun  Type  4  keyboard
     also report themselves  as Sun Type 4 keyboard.

Man(1) output converted with man2html