kbd.FAQ - version of 940406
-------------------------------------------------------------------------
Contents

0. Useful programs
1. Resetting your terminal
2. Delete and backspace
3. The console character sets (and what to do if your screen is garbled)
4. Console switching
5. Ctrl-Alt-Del and other special key combinations
6. Various properties of the console
7. How to get out of raw mode
8. How to make other programs work with non-ASCII chars
9. What precisely does XFree86-2.1 do when it initializes its keymap ?
-------------------------------------------------------------------------
0. Useful programs

The following packages contain keyboard or console related programs.

kbd-0.87.tar.gz contains loadkeys, dumpkeys, showkey, setmetamode,
	setleds, setfont, showfont, mapscrn, kbd_mode.
shellutils-1.8 contains stty.
utilb-1.3.taz contains setterm.
utile-1.5.taz contains kbdrate.
The X distribution contains xmodmap, kbd_mode. (See also X386keybd(1).)
-------------------------------------------------------------------------
1. Resetting your terminal

The command "reset" will reset the console driver. This helps when
the screen is full of funny graphic characters, and also if it is
reduced to the bottom line. If you don't have this command, or if it
does something else, make your own:
	#!/bin/sh
	echo -e \\033c
that is, you want to send the two characters Escape c to the console.
If you loaded some strange font, and want to return to the default,
	setfont
will do (provided you stored the default font in the default place).
On old terminals output involving tabs may require a dalay, and you
have to say
	stty tabs3
(see stty(1)). This usually settles the output side.
On the input side there are many things that might be wrong. If X or
some other program using raw mode crashed, your keyboard may still be
in raw (or mediumraw) mode, and it is difficult to give commands.
(See "How to get out of raw mode" below.)

-------------------------------------------------------------------------
2. Delete and backspace

A. How to tell Unix what character you want to use to delete the
last typed character.
% stty -erase ^?

If the character is erased, but in a funny way, then something is
wrong with your tty settings. If echoprt is set, then erased characters
are enclosed between \ and /. If echoe is not set, then the erase char
is echoed (which is reasonable when it is a printing character, like #).
Most people will want "stty echoe -echoprt". Saying "stty sane" will do
this and more. Saying "stty -a" shows your current settings.
How come this is not right by default? It is, if you use the right getty.

A1. "Getty used to do the right thing with delete and backspace
but is broken now?"
Earlier, the console driver would do BackSpace Space BackSpace (\010\040\010)
when it got a Del (\177). Nowadays, Del's are ignored (as they should be,
since the driver emulates a vt100). Get a better getty, i.e., one that does
not output Del.

A2. "Login behaves differently at the first and second login attempts?"
At the first attempt, you are talking to getty. At the second attempt,
you are talking to login, a different program.

B. How to tell Linux what code to generate when any key is pressed.
% loadkeys mykeys.map		(when not in (MEDIUM)RAW mode)
% xmodmap mykeys.xmap		(under X)
Note that XFree86-2.1 reads the Linux settings of the keymaps
when initialising the X keymap. Although the two systems are not
100% compatible, this should mean that in many cases the use of
xmodmap has become superfluous.

If, for example, you want your Backspace key to generate BackSpace
(Control_h), instead of the default Delete, then
% loadkeys
keycode 14 = BackSpace
%
will do.

C. How to tell X to interchange Delete and Backspace.
% xmodmap -e "keysym BackSpace = Delete" -e "keysym Delete = BackSpace" 

D. How to tell emacs what to do when it receives a delete or backspace.
Put in your .emacs file lines like
  (global-set-key "\?" 'delete-backward-char)
  (global-set-key "\C-h" 'help-command)
Of course you can bind other commands to other keys in the same way.

E. How to tell emacs to interchange Delete and Backspace.
Put in your .emacs file lines
  (setq keyboard-translate-table (make-string 128 0))
  (let ((i 0))
  (while (< i 128)
      (aset keyboard-translate-table i i)
      (setq i (1+ i))))
  (aset keyboard-translate-table ?\b ?\^?)
  (aset keyboard-translate-table ?\^? ?\b)

F. How to tell xterm about your favourite tty modes.
Normally xterm will inherit the tty modes from its invoker.
Under xdm, the default erase and kill characters are # and @,
as in good old Unix Version 6.
If you don't like that, you might put something like

  XTerm*ttymodes: erase ^? kill ^U intr ^C quit ^\ eof ^D susp ^Z start ^Q stop ^S eol ^@

in /usr/lib/X11/app-defaults/XTerm or in $HOME/.Xresources, assuming that
you have a line

  xrdb $HOME/.Xresources

in your $HOME/.xinitrc .

G. What about termcap and terminfo?
When people have problems with backspace, they tend to look at their termcap
(or terminfo) entry for the terminal, and indeed, there does exist a kb (or kbs)
capability describing the code generated by the Backspace key.
However, not many programs use it, so unless you are having problems with one
particular program only, probably the fault is elsewhere.
Of course it is a good idea anyway to correct your termcap (terminfo) entry.
------------------------------------------------------------------------------
3. The console character sets

The kernel knows about 4 translations of bytes into console-screen symbols.
The four tables are: a) Latin1 -> PC,  b) VT100 graphics -> PC, c) PC -> PC,
d) user-defined.

There are two character sets, called G0 and G1, and one of them
is the current character set. [Initially G0.] 
Typing ^N causes G1 to become current, ^O causes G0 to become current.

These variables G0 and G1 point at a translation table, and can be changed
by the user. Initially they point at tables a) and b), respectively.
The sequences ESC ( B and ESC ( 0 and ESC ( U and ESC ( K cause G0 to point
at translation table a), b), c) and d), respectively.
The sequences ESC ) B and ESC ) 0 and ESC ) U and ESC ) K cause G1 to point
at translation table a), b), c) and d), respectively.

The sequence ESC c causes a terminal reset, which is what you want if the
screen is all garbled. The oft-advised "echo ^V^O" will only make G0 current,
but there is no guarantee that G0 points at table a).
In some distributions there is a program reset(1) that just does "echo ^[c".
If your termcap entry for the console is correct (and has an entry :rs=\Ec:),
then also "setterm -reset" will work.

The user-defined mapping table can be set using mapscrn(8).
The result of the mapping is that if a symbol c is printed, the symbol
s = map[c] is sent to the video memory. The bitmap that corresponds to
s is found in the character ROM, and can be changed using setfont(8).

------------------------------------------------------------------------------
4. Console switching

XFree86 1.3 does not know that Alt is down when you switch to the X
window. Thus, you cannot switch immediately to some other VT again
but have to release Alt first.
In the other direction this should work: the kernel always keeps
track of the up/down status of all keys.

XFree86 1.3 saves the fonts loaded in the character ROMs when started,
and restores it on a console switch. Thus, the result of setfont on
a VT is wiped out when you go to X and back.

------------------------------------------------------------------------------
5. Ctrl-Alt-Del and other special key combinations

A. Ctrl-Alt-Del (Boot)
If you press Ctrl-Alt-Del (or whatever key was assigned the keysym Boot by
loadkeys) then either the machine reboots immediately (without sync), or
init is sent a SIGINT. The former behaviour is the default. The default can
be changed by root, using the system call reboot(), see ctrlaltdel(8).
Some init's change the default. What happens when init gets SIGINT depends
on the version of init used - often it will be determined by the pf entry
in /etc/inittab [which means that you can run an arbitrary program in this case].

B. Other combinations

Name		Default binding
-------------------------------
Show_Memory	Shift-Scrollock
Show_Registers	AltGr-ScrollLock
Show_State	Ctrl-ScrollLock
Console_n	Alt-Fn			(1 <= n <= 12)
Console_{n+12}	AltGr-Fn		(1 <= n <= 12)
Last_Console	Alt[Gr]-PrintScreen
Scroll_Backward	Shift-PageUp
Scroll_Forward	Shift-PageDown
Caps_On					(CapsLock is a toggle; this key sets)
Compose		Ctrl-.

C. X Combinations

Ctrl-Alt-Fn	Switch to VT n
Ctrl-Alt-KP+	Next mode
Ctrl-Alt-KP-	Previous mode
Ctrl-Alt-Backspace	Kill X

D. Composing symbols.

One symbol may be constructed using several keystrokes.
- LeftAlt-press, followed by a decimal number typed on the keypad, followed
  by LeftAlt-release, yields the symbol with code given by this number.
- A dead diacritic followed by a symbol, yields that symbol adorned with
  that diacritic. If the combination is undefined, both keys are taken
  separately.
  Which keys are dead diacritics is user-settable; none is by default.
  Five dead diacritics can be defined (using loadkeys(1)): dead_grave,
  dead_acute, dead_circumflex, dead_tilde, dead_diaeresis.
  Precisely what this adorning means is also user-settable:
  dead-diacritic + symbol is equivalent to Compose + diacritic + symbol.
- Compose followed by two symbols yields a combination symbol. These
  combinations are user-settable. Today there are 68 combinations
  defined by default; you can see them by saying "dumpkeys | grep compose".

Note that there are at least three such composition mechanisms:
1. The Linux keyboard driver mechanism, used in conjunction with loadkeys.
2. The X mechanism - see X386keybd(1).
3. The emacs mechanism obtained by loading "iso-insert.el".
For X the order of the two symbols is arbitrary: both Compose-,-c and
Compose-c-, yield a c-cedilla; for Linux and emacs only the former sequence
works by default. For X the list of compose combinations is fixed. Linux
and emacs are flexible.
The three default lists are somewhat similar, but the details are different.
------------------------------------------------------------------------------
6. Various properties of the console

See loadkeys(1), setleds(1), setmetamode(1) for the codes generated by the
various keys and the setting of leds when not under X. Under X, see xmodmap(1).

See setterm(1), kbdrate(8) for properties such as foreground and background
colors, screen blanking, character repeat rate when not under X.
Under X, see xset(1), also for key click and bell volume.

The file /etc/termcap defines the escape sequences used by many programs
addressing the console (or any other terminal). A more modern version is
found in /usr/lib/terminfo. (See terminfo(5). Terminfo files are compiled
by the terminfo compiler /usr/lib/terminfo/tic, see tic(1).)

(On my machine) /dev/console is a symbolic link to /dev/tty0, and the
kernel regards /dev/tty0 as a synonym for the current vt.
XFree86 1.3 changes the owner of /dev/tty0, but does not reset this after
finishing. Thus, dumpkeys might fail because someone else owns /dev/tty0;
in such a case you might run X first.

------------------------------------------------------------------------------
7. How to get out of raw mode

If some program using K_RAW keyboard mode exits without restoring the keyboard
mode to K_XLATE, then it is difficult to do anything - not even Ctrl-Alt-Del
works. However, it is sometimes possible to avoid hitting the reset button.
(And desirable as well: your users may get angry if you kill their Hack game
by rebooting; you might also damage your file system.)
Easy solutions involve logging in from another terminal or another machine
and doing "kbd_mode -a".
The procedure below assumes that no X is running, that the display is in
text mode, and that you are at your bash prompt, that you are using a US
keyboard layout, and that your interrupt character is Ctrl-C.

Step 1. Start X.
As follows: press 2 (and don't release), press F12 (and don't release)
and immediately afterwards press = . This starts X.
  (Explanation: if a key press produces keycode K, then the key release
  produces keycode K+128. Probably your shell does not like these high
  characters, so we avoid generating them by not releasing any key.
  However, we have to be quick, otherwise key repeat starts. The digit 2
  produces a Ctrl-C that discards previous junk, the F12 produces an X
  and the = a Return.)
Probably your screen will be grey now, since no .xinitrc was specified.
However, Ctrl-Alt-Fn will work and you can go to another VT.
(Ctrl-Alt-Backspace also works, but that exits X, and gets you back into
the previous state, which is not what you want.)

Step 2. Setup to change the keyboard mode.
(For example, by "sleep 5; kbd_mode -a".)

Step 3. Leave X again.
(Alt-Fx [often Alt-F7] brings you back to X, and then Ctrl-Alt-Backspace
exits X.)
Within 5 seconds your keyboard will be usable again.

If you want to prepare for the occasion, then make "\215A\201" (3 symbols) an
alias for "kbd_mode -a". Now just hitting F7 and = will return you to sanity.
------------------------------------------------------------------------------
8. How to make other programs work with non-ASCII chars

A. In emacs, put lines
	(standard-display-european t)
	(set-input-mode nil nil 1)
	(require 'iso-syntax)
and perhaps also
	(load-file "iso-insert.el")
	(define-key global-map [?\C-.] 8859-1-map)
into your $HOME/.emacs.
(The latter line will not work under xterm, if you use "emacs -nw", but in that
case you can put
	XTerm*VT100.Translations:       #override\n\
        Ctrl <KeyPress> . : string("\0308")
in your .Xresources.)

B. For less, put
	LESSCHARSET=latin1
in the environment.

C. For ls, give the option -N. (Probably you want to make an alias.)

D. For bash (version 1.13.*), put
	set meta-flag on
	set convert-meta off
into your $HOME/.inputrc.

E. For flex, give the option -8 if the parser it generates must be
able to handle 8-bit input.

------------------------------------------------------------------------------
9. What precisely does XFree86-2.1 do when it initializes its keymap ?

Since version 2.1, XFree86 will initialize its keymap from the Linux keymap,
as far as possible. However, Linux has 16 entries per key (one for each
combination of the Shift, AltGr, Ctrl, Alt modifiers), and X has 4 entries
per key (one for each combination of Shift, Mod), so some information
is lost.

First X reads the Xconfig file, where definitions of the LeftAlt, RightAlt,
RightCtl, ScrollLock keys as Meta, ModeShift, Compose, ModeLock or ScrollLock
might be found - see X386keybd(1).

For Mod the LeftAlt key is taken, unless RightCtl was defined as ModeShift or
ModeLock, in which case RightCtl is taken, or RightAlt was so defined, in which
case RightAlt is taken.
This determines how the 4 XFree86 meanings of a key are selected from the 16
Linux meanings.
Note that Linux today does not distinguish bewteen the two Ctrl keys or between
the two Shift keys, but probably that will change. X does distinguish.

Now the kernel keymap is read and the usually obvious corresponding X
bindings are made. The bindings for the "action keys" Show_Memory, Show_State,
Show_Registers, Last_Console, Console_n, Scroll_Backward, Scroll_Forward,
Caps_On and Boot are ignored, as are the dead diacriticals, and the locks
(except for ShiftLock), and the "ASCII-x" keys.

Next, the definitions in the Xconfig file are used. (Thus, a definition
of Compose in Xconfig will override its value as found in the Linux keymap.)

What happens to the strings associated with the function keys? Nothing,
X does not have such a concept. (But it is possible to define strings
for function keys in xterm - note that the window manager gets the keys
first.)
------------------------------------------------------------------------------
Additions and corrections are welcome.
Andries Brouwer - aeb@cwi.nl
