⟦d1d52117e⟧

TextFile

.\"$Header: keyboard.4,v 10.1 86/11/19 10:56:03 jg Exp $
.\"$Source: /u1/X/libibm/doc/man/RCS/keyboard.4,v $
.\" This file uses -man macros.
.TH KEYBOARD 4 "31 Mar 1986" "Space overwritten by .AC macro" " "
.UC 4
.AC 1 0 
.SH NAME
keyboard \- keyboard interface
.SH DESCRIPTION
.PP
The keyboard adapter returns scan codes that the keyboard driver translates
into ASCII characters. This translation is done through table lookup; 
\fIpf\fR(i) allows users to change the translation tables
so as to redefine the ASCII characters generated by
particular keystrokes.
.PP
There are two sets of translation tables: a standard set
not normally changed (see \fIkeyboard_codes\fR(5)),, 
and a working set the user may freely change
as desired (see \fIpf\fR(i)). 
.PP
In addition to generating ASCII characters, the keyboard interface
can invoke special functions (swapping of key definitions, etc.; 
see below).
Most of these special functions are bound to
the three keys labeled
\fB<Print-Screen/SysRq>\fR, \fB<Scroll-Lock>\fR, 
and \fB<Pause/Break>\fR.
The normal use of these keys, together with the four shift or meta-keys, 
give a total of 15 possible meta functions that can be invoked:
.nf

.ft B
Key		Normal        Shift		Ctrl	    	  Alt		 Action
.ft R
Print-Screen/	FN_PRINT    FN_IGNORE	FN_LOG          FN_IGNORE	  FN_SET
   SysRq	
Scroll-Lock	FN_SCROLL  FN_SWAP	FN_SWRESET    FN_SWITCH	  FN_CLICK

Pause/Break	FN_DEBUG   FN_DEBUG	FN_IGNORE      FN_KILL	  FN_RESET

.fi
.SH "Keyboard META Functions"
.TP 
FN_ACTION
(Usually bound to the 
.B <Action>
key.)
Puts the keyboard into action mode.
Action mode selects the ``action'' set of key values.
.TP 
FN_ALT
(Usually bound to 
\fB<Alt>\fR.)
Puts the keyboard into alt mode.
Alt mode selects the ``alt'' set of key values.
.TP 
FN_BREAK
Not usually specified by the user; it is invoked when a
``make-break'' key is released by the user and should only be bound to 
that single hardware code.
.TP 
FN_CLICK
(Usually bound to
.BR <Action><Scroll/Lock> .)
Causes a different ``key click'' mode to be selected.  There are four such
modes:  no click, hardware click, software click, and both hardware
and software click.
.TP
FN_DEBUG
(Usually bound to the
.B <Pause/Break>
key.) 
Invokes the debugger (see \fIdebug\fR(8)).
Once in console-debugger mode, a ``go'' command can be used to restart 
the system. On systems without the debugger, the screen still displays
DEBUG in the status line; but the debugger will not be entered.
.br
A system-attention sequence
.RB ( "<Ctrl>-<Alt>-<SysRq>" )
can also be used to enter the
debugger; use this only if the 
FN-DEBUG function
does not work.
.TP 
FN_IGNORE
(Usually bound to keys that neither generate characters nor
activate meta-functions.) Causes that key to be ignored.
.TP 
FN_KILL
(Usually bound to 
\fB<Alt><Pause/Break>\fR.)
Causes a HANGUP signal (see 
.IR signal (2))
to be sent to the processes currently in the console terminal process group. 
It also marks the console terminal as closed. This is sufficient to stop most 
programs that do not catch or ignore the HANGUP signal. This is analogous
to hanging up a dialup line to drop the connection.
If the 
function is invoked again while the console terminal is marked as closed, it 
generates a KILL signal to all processes
in the current process group. 
.TP 
FN_NUM_LOCK
(Usually bound to
\fB<Num-Lock>\fR.)
Puts the keyboard into num-lock mode.
.TP 
FN_PRINT
(Usually bound to
\fB<Print-Screen>\fR.)
Causes the current console screen image to be sent to the line printer.
.TP 
FN_LOG
(Usually bound to
\fB<Ctrl>-<Print-Screen>\fR.)
Turns hardcopy logging of the screen on and off.
Kernel/user hardcopy is independent of debugger hardcopy.
.TP 
FN_RESET
(Usually bound to
\fB<Action><Pause-Break>\fR.)
Causes the keyboard definitions to be reset to their standard values.
This is also automatically done when the console terminal is closed, in order
to ensure that the next user to log in receives a normal keyboard.
.TP 
FN_SWAP
(Usually bound to
\fB<Shift><Scroll-Lock>\fR.)
Exchanges the bindings of the next two keys typed.
This is particularly useful for swapping the definitions
of the 
.B "<Caps-Lock>" 
key and the 
.B "<Ctrl>" 
key.
.TP 
FN_SHIFT
(Usually bound to the keys labeled
.B <Shift>
on either side of the keyboard.)
Puts the keyboard into shifted mode.
.TP 
FN_SWITCH
(Usually bound to
\fB<Alt><Scroll-Lock>\fR.)
Causes the console output to be switched to the next available display
device (see \fIconsole\fR(4)).
.TP 
FN_SWRESET
(Usually bound to
\fB<Ctrl><Scroll-Lock>\fR.)
Causes the console output to be switched to the next available display device,
and the display to be re-initialized. 
If necessary, this involves loading
microcode; in all cases, the display is cleared and the cursor moved to the 
top left corner.
.TP 
FN_SCROLL
(Usually bound to
\fB<Scroll-Lock>\fR.)
Causes normal output to the console display to be locked out by generating
the current XOFF character (see \fItty\fR(4)).  
Output stops, and the Scroll-Lock
light on the keyboard comes on. 
When the Scroll-Lock light is on, pressing the
.B <Scroll Lock> 
key again generates the current XON character, which
causes output to resume and the Scroll Lock to go off. 
Note that if the console is in RAW mode, 
the 
.B <Scroll Lock> 
key only generates XOFF characters.
.TP 
FN_SET
(Usually bound to
\fB<Action><Print-Screen>\fR.)
Sets a new value into the keyboard translation table that determines
the ASCII characters generated for particular scan codes (see below).
.TP 
FN_BEEP
(Not usually bound to a key.)
Sounds the bell (a beep) when invoked.
.TP
FN_CAPS_LOCK
(Usually bound to
\fB<Caps-Lock>\fR
or to
\fB<Ctrl>\fR.)
Causes the keyboard to go into Caps-Lock mode.  The keyboard
leaves Caps-Lock mode when the FN_CAPS_LOCK function is
next generated or when the next FN_SHIFT is generated.  This
behavior is similar to that of many typewriters.  Caps-Lock mode
selects the ``Shift'' set of key values.
.TP
FN_CONTROL
(Usually bound to 
\fB<Ctrl>\fR or to
\fB<Caps-Lock>fR.)
Causes the keyboard to go into Control mode.  Control mode
selects the ``control'' set of key values.
.SH NOTES
.PP
When the keyboard has more than one mode in effect, the key value 
selected is that of the highest priority mode.  
The mode priority ordering is: normal,
shift, control, alt, and action (normal being low and action being high).
.PP
The keyboard adapter also supports the speaker, which is activated 
when the ASCII character \fBbel\fP 
.RB ( ^G )
is sent to the display.
.PP
It is possible to change the association of keyboard functions and the 
ASCII strings generated by the keyboard driver in two ways: from the 
keyboard and from within a program. 
It is convenient to have a set of definitions (or bindings)
done every time a user logs on the system; this is best
done via the 
.IR pf (i)
utility invoked from one's
.I .login
file during login. If this utility is unavailable, or the user wishes
to redefine a key temporarily, it may be done from the keyboard.
The keyboard procedure is:
.IP 1. 5
Invoke the FN_SET function (normally bound to 
\fB<Action><Print-Screen>\fR).
This causes 
.B "KEY?"
to be displayed in the status line.
.IP 2. 5
Enter the keystroke for the key to be set (this includes using the
appropriate shift (or meta) key such as 
\fB<Shift>\fR, \fB<Alt>\fR, \fB<Ctrl>\fR, or
\fB<Action>\fR).
The status line will show 
.B DEF
when the keystroke has been accepted.
.IP 3. 5
Enter the definition. It echoes on the status line as it is 
accepted. Note that control keys are displayed as ^, followed by the
appropriate letter.
.IP 4. 5
Enter the keystroke for the key being set (as for step 2). This completes
the definition. 
.PP
If during definition you decide to cancel the definition being 
entered, re-invoke the FN_SET function.
.PP
A few \fIioctl\fP(2) calls apply to the 
\fIkeyboard\fR device, and have the form:

.RS
.nf
.ft B
#include <machinecons/keyboard.h>
struct kbdarg {
	char kbd_scan;			/* scan code */
	char kbd_index;			/* the position to change */
	char kbd_length;		/* the length following */
	char kbd_text[KBD_STRING_LENGTH];	/* the text */
	char kbd_end;			/* a nullend flag just in case */
};
ioctl(files, code, arg)
int *arg;

\fRor:\fB

struct kbdarg *arg;

#define KBD_INDEX_NORMAL	0	/* normal position */
#define KBD_INDEX_SHIFT	1	/* shifted */
#define KBD_INDEX_CONTROL	2	/* control'ed */
#define KBD_INDEX_ALT		3	/* alt'ed */
#define KBD_INDEX_ACTION	4	/* action'ed */

#define CLICK_OFF	0x00
#define CLICK_HARD	0x01		/* hardware click */
#define CLICK_SOFT	0x02		/* software click */
#define CLICK_BOTH	0x03		/* both */
 
#define KBDCGET		_IOWR(k,0,struct kbdarg)  /* get current def'n */
#define KBDCSET		_IOW(k,1,struct kbdarg)	/* set new definition */
#define KBDCRESET	_IO(k,2)	/* reset keyboard to standard */
#define KBDCRST		_IO(k,3)		/* reset (clear) string table */
#define KBDCSSTD		_IO(k,4)	/* set standard table */
#define KBDSGET		_IOR(k,5,int)	/* get available string space */
#define KBDGCLICK	_IOR(k,6,int)	/*  get click */
#define KBDSCLICK	_IOW(k,7,int)	/*  set click */

.ft R
.fi
.RE
The applicable codes are:
.IP KBDCRESET 18
Reset the keyboard definitions to the standard definitions.
The
.I arg
argument is unused.
.IP KBDRST
Clear the string definitions. This makes space available for
a new set of strings to be defined. It causes any key with a definition
of more than two bytes to be set to the 
FN_IGNORE function.
.IP KBDSSTD
Replace the standard definition with the current definition.
.IP KBDSGET
Store the number of bytes available for string definitions
in the \fIint\fP pointed to by \fIarg\fP.
.IP KBDCGET
Store the current definition for 
scancode \fIkbd_scan\fP at index \fIkbd_index\fP 
in the \fIstruct kbdarg\fP pointed to by \fIarg\fP.
The keyboard
index is one of KBD_INDEX_NORMAL, KBD_INDEX_SHIFT, 
KBD_INDEX_CONTROL, KBD_INDEX_ALT or KBD_INDEX_ACTION. 
On the \fIioctl\fP, the \fIkbd_length\fP contains the maximum length to 
return; upon return it contains the actual length stored in the keyboard.
The definition is returned into \fIkbd_text\fP.
.IP KBDCSET
Store a new definition for scancode \fIkbd_scan\fP at index \fIkbd_index\fP
in the keyboard from \fIstruct kbdarg\fP pointed to by \fIarg\fP.
The keyboard index is one of KBD_INDEX_NORMAL, KBD_INDEX_SHIFT, 
KBD_INDEX_CONTROL, KBD_INDEX_ALT or KBD_INDEX_ACTION. 
\fIkbd_length\fP contains the length of the definition text
in \fIkbd_text\fP.
.IP KBDGCLICK
Store the current keyboard click status into the \fIint\fP pointed to by
\fIarg\fP. The value is one of CLICK_OFF, CLICK_HARD,
CLICK_SOFT or CLICK_BOTH.
.IP KBDSCLICK
Set the current keyboard click status from the \fIint\fP pointed to by
\fIarg\fP. The value must be one of CLICK_OFF, CLICK_HARD,
CLICK_SOFT or CLICK_BOTH.
.IP 
.SH ERRORS
The following errors can be returned by the driver:
.TP 12
[EINVAL]
The \fIkbd_scan\fP or \fIkbd_index\fP is invalid.
.TP 12
[E2BIG]
The string being defined exceeds the available space.
.TP 12
[EPERM]
The caller is not the super-user (for the KBDSSTD ioctl).
.SH FILES
/dev/console
.SH "SEE ALSO"
cons(4), ibm5151(4), ibmaed(4), tty(4), reboot(8), debug(i), pf(i)
.SH DIAGNOSTICS
None.
.SH BUGS
.PP
The console screen print function works only for the monochrome display
and the IBM Academic Information Systems experimental display.
.PP 
The only user output to the speaker is a beep (\fBbel\fR).
It should be possible to
control the speaker's frequency and duration parameters.
.PP
Caps-Lock mode should be enhanced.
Using the shift key when in Caps-Lock mode should generate lower case
letters; also, Caps-Lock should not shift non-alphabetic characters.
.PP
Num-Lock mode does not do anything; the numeric pad generates numbers 
regardless of mode.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦d1d52117e⟧ TextFile

Derivation

TextFile
