Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
kb(7M)				STREAMS	Modules				kb(7M)

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

	     Keyboard translation is turned off	and up/down key	codes are  re-

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

		    Used when a	key is depressed and no	shifts are in effect.

		    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

	      Num Lock
		    Used when a	key is depressed and Num Lock is in effect.

		    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

	      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-

       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.

			  "Shift Lock" key.

			  Left-hand Shift key.

			  Right-hand Shift key.

		    LEFTCTRL 4
			  Left-hand (or	only) Control key.

			  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 ac-
		    tual 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 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.

			  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 error.

		    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 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 ac-
		    cents" 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 characters	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 entries.

       FUNCKEYS	0x600
	     There  are	 64  keys reserved for function	keys. The actual posi-
	     tions are usually on the left/right/top/bottom of the keyboard.

	     The next-to-lowest	4 bits indicate	the group of function keys:



	     TOPFUNC 0x610


       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  pressing	 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:


       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:


       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.

       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,
       #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 structure is changed. The
	     kio_tablemask request specifies which of the  following  transla-
	     tion 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	 monitor"  se-
       quence 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  in-
	     valid arguments.

	     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  key-
		   board  type	is  unknown. In	case of	error, -1 is stored in
		   the int pointed to by the argument.

	     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 argument.

	     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 key-
	     board. 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 ap-
       propriate  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 is:

			  "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 IA sys-
	     tems, and BREAK on	the serial console device) is enabled  if  the
	     int has a value of	KIOCABORTENABLE(1). If the value is KIOCABORT-
	     DISABLE(0)	, the keyboard abort sequence effect is	 disabled.  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 ap-
	     plicable  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 port.

	     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  de-
	     bugger  (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  dis-
	     abled  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 attributes:

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

SunOS 5.9			  14 May 1999				kb(7M)


Want to link to this manual page? Use this URL:

home | help