kbdfs: allow to escape ctlr-alt-del with shift for vmx and vnc.

[plan9front.git] / sys / man / 8 / kbdfs

diff --git a/sys/man/8/kbdfs b/sys/man/8/kbdfs
index 7149cbd621a1f2d56000f5f6cc9ab6d9513738c2..93e0a2e61cc42a9630f151946008fb30586f176d 100644 (file)
--- a/sys/man/8/kbdfs
+++ b/sys/man/8/kbdfs
@@ -1,6 +1,6 @@
 .TH KBDFS 8
 .SH NAME
-kbdfs \- keyboard and console filesystem
+kbdfs, console \- keyboard and console filesystem
 .SH SYNOPSIS
 .B aux/kbdfs
 [
@@ -12,7 +12,7 @@ kbdfs \- keyboard and console filesystem
 .B -m
 .I mntpnt
 ] [
-.I filename
+.I consfile
 ]
 .nf
 
@@ -20,9 +20,16 @@ kbdfs \- keyboard and console filesystem
 .B /dev/cons
 .B /dev/consctl
 .B /dev/kbd
+.B /dev/kbdin
 .B /dev/kbin
 .B /dev/kbmap
 .fi
+.PP
+.B console
+[
+.I cmd
+.I args...
+]
 .SH DESCRIPTION
 .PP
 Started on 
@@ -34,7 +41,9 @@ translates raw keyboard scancodes from
 .IR kbd (3))
 and its
 .BR kbin
-file and optionaly reads console input from
+and
+.BR kbdin
+file and optionally reads console input from
 .I consfile
 to provide initial keyboard and console input.
 .PP
@@ -42,6 +51,7 @@ It serves a one-level directory containing the files
 .BR cons,
 .BR consctl,
 .BR kbd,
+.BR kbdin,
 .BR kbin
 and
 .BR kbmap.
@@ -77,21 +87,37 @@ mounts itself on
 otherwise on
 .B /dev
 (the default).
+.PP
+The
+.B console
+command executes
+.I cmd
+(defaults to the system shell)
+under its own
+.I kbdfs
+instance providing a serial console if
+.B $console
+environment variable is set.
 .SS Console
 .PP
 Reading the
 .BR cons
 file returns characters typed on the console.  Normally, characters
-are buffered to enable erase and kill processing.  A control-U, 
+are buffered to enable erase and kill processing.  
+A control-U, 
 .LR ^U ,
 typed at the keyboard
-.I kills
+.I erases
 the current input line (removes all
 characters from the buffer of characters not yet read via cons), and a
 backspace
 .I erases
 the previous non-kill, non-erase character from the
-input buffer.  Killing and erasing only delete characters back to, but
+input buffer.
+The combination control-W,
+.LR ^W ,
+deletes the input last word.
+Killing and erasing only delete characters back to, but
 not including, the last newline.  Characters typed at the keyboard
 actually produce 16-bit runes (see
 .IR utf (6)),
@@ -123,7 +149,8 @@ is in
 .IR "raw mode" :
 characters are not echoed as they are typed,
 backspace,
-.L ^U
+.L ^U,
+.L ^W
 and
 .L ^D
 are not treated specially, and characters are
@@ -141,47 +168,102 @@ to
 causes the characters to be printed on the console screen.
 .PP
 When a
-.I filename
+.I consfile
 is passed to
 .IR kbdfs (8)
 as its last argument, it reads and processes the
 characters from that file and forwards them to the
 .BR cons
 file with the same text processing applied as on keyboard input.
-This is used on serial consoles.
+This is used to provide a serial console when
+.B $console
+environment variable is set. (see
+.IR plan9.ini (8)).
+.PP
+Holding
+.LR Ctrl
++
+.LR Alt
+and then pressing the
+.LR Del
+key will
+trigger a reboot of the terminal.
+To forward this sequence downstream,
+.LR Shift
++
+.LR Ctrl
++
+.LR Alt
+and then pressing
+.LR Del
+will cause to send a
+.LR Shift
+up before the
+.LR Del
+key.
+This is usefull for programs like
+.IR vnc (1)
+and
+.IR vmx (1).
 .SS Keyboard
 A read on the
 .BR kbd
-file returns a null terminated, variable-length,
+file returns the character
+.B k,
+.B K
+or
+.B c
+followed by a null terminated, variable-length,
 .SM UTF
-encoded string of all the keys that are currently pressed (key is
-down) on the keyboard.  This includes all keys that have a keyboard
-mapping and modifier keys.  No key is treated specially. A new event
-is generated on each state change or at keyboard repeat rate and put
-in a buffer. Each
+encoded string. The
+.B k
+message is sent when a key is pressed down
+and
+.B K
+when a key is released. The following string contains all the keycodes
+of the keys that are currently pressed down in unshifted form. 
+This includes all keys that have a keyboard mapping and modifier keys.
+The string following the
+.B c
+message contains the single character that would have been returned
+on the
+.BR cons
+file instead. The
+.B c
+message will be resent at the keyboard repeat rate.
+A single
 .IR read (2)
-will return a single event or block until there are new events
-available.  The read data is always terminated with a null-byte,
-so when all keys are released (all keys are up), a single
-null-byte will be returned.  Newly pressed keys are appended to the
-string before the null-byte.  Key releases remove the
-character from the string.  Change on a modifier key like
-.B Shift
-or
-.B Num
-will not change
-the characters already present in the string, but will
-take effect on newly pressed keys. Opening the
+can return multiple concatenated messages at once (delimited by the null byte)
+or block when there are no messages queued. Opening the
 .BR kbd
 file disables input processing on the
 .BR cons
 file until it is closed again.
 .PP
+.B K,
+.B k
+and
+.B c
+messages can be written to
+.BR kbdin
+and will forwarded to the reader of
+.BR cons
+or
+.BR kbd.
+Writing a
+.B r
+or
+.B R
+message followed by a
+.SM UTF
+encoded rune will simulate the press or
+release of that particular rune.
+.PP
 Raw scancodes can be written to the
 .BR kbin
 file for external keyboard input (used for USB keyboards).
 .SS "Keyboard map"
-Scancodes are maped to Unicode characters with a number of
+Scancodes are mapped to Unicode characters with a number of
 translation tables. These tables can be accessed with the
 .BR kbmap
 file.
@@ -218,8 +300,14 @@ to represent a control character.
 .IR cons (3),
 .IR keyboard (6),
 .IR utf (6),
-.IR kbd (3)
+.IR kbd (3),
+.IR plan9.ini (8)
 .SH FILES
-.B /dev/lib/kbmap/*
+.B /sys/lib/kbmap/*
 .SH SOURCE
-.B /sys/src/cmd/aux/kbdfs.c
+.B /sys/src/cmd/aux/kbdfs
+.br
+.B /rc/bin/console
+.SH HISTORY
+.I Kbdfs
+first appeared in 9front (May, 2011).