path: root/sys/man/8/kbdfs

.TH KBDFS 8
.SH NAME
kbdfs, console \- keyboard and console filesystem
.SH SYNOPSIS
.B aux/kbdfs
[
.B -Dd
] [
.B -s
.I srv
] [
.B -m
.I mntpnt
] [
.I consfile
]
.nf

.B mount -b /srv/cons /dev
.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 
.IR boot (8),
.IR kbdfs
translates raw keyboard scancodes from 
.B /dev/scancode
(see
.IR kbd (3))
and its
.BR kbin
and
.BR kbdin
file and optionally reads console input from
.I consfile
to provide initial keyboard and console input.
.PP
It serves a one-level directory containing the files
.BR cons,
.BR consctl,
.BR kbd,
.BR kbdin,
.BR kbin
and
.BR kbmap.
.PP
The
.B -D
flag enables a debug trace of
.I 9p
messages and
.B -d
prevents 
.IR kbdfs
from making its memory private.
.PP
The
.B -s
option causes
.IR kbdfs
to post its channel on
.B /srv/\fIsrv\fP.
On system startup,
.IR boot (8)
sets this to
.B cons.
With the
.B -m
option,
.IR kbdfs
mounts itself on
.I mntpnt
(see
.IR bind (2)),
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, 
.LR ^U ,
typed at the keyboard
.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.
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)),
but the runes are translated into the variable-length
.SM UTF
encoding (see
.IR utf (6))
before putting them into the buffer. A
.IR read (2)
of a length greater than zero causes the process to wait until a newline
or a
.LR ^D
ends the buffer, and then returns as much of the buffer as the
argument to read allows, but only up to one complete line.  A
terminating
.LR ^D
is not put into the buffer.  If part of the line remains, the next
read will return bytes from that remainder and not part of any new
line that has been typed since.
.PP
If the string
.B rawon
has been written to the
.BR consctl
file and the file
is still open,
.BR cons
is in
.IR "raw mode" :
characters are not echoed as they are typed,
backspace,
.L ^U,
.L ^W
and
.L ^D
are not treated specially, and characters are
available to read as soon as they are typed.  Ordinary mode is
reentered when
.B rawoff
is written to
.BR consctl
or this file is closed.
.PP
A write (see 
.IR read (2))
to
.BR cons
causes the characters to be printed on the console screen.
.PP
When a
.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 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 useful for programs like
.IR vnc (1)
and
.IR vmx (1).
.SS Keyboard
A read on the
.BR kbd
file returns the character
.B k,
.B K
or
.B c
followed by a null terminated, variable-length,
.SM UTF
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)
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"
PS/2 keyboards generate one and two byte scancodes sequences
which give keyboard events relative to physical key location.
These codes are then translated to Unicode runes using a series
of tables hereafter referred to as layers. The true mapping
of scancodes is locale and potentially device specific.
.PP
The PS/2 interface presents two physical layers, switched on if
the input scancode is one or two bytes. This second "escaped" layer
is typically generated for keys like
.LR Home
and
.LR Ins .
.IR Kbdfs
additionally maintains eight more virtual layers that are switched on
.LR Shift ,
.LR Ctl ,
.LR AltGr ,
and
.LR Mod4
modifier key state. Not all permutations of these modifiers are represented
as layers, the exhaustive list is as follows:
.TP \w'shiftaltgr\ \ \ \ \ 'u
.I none
Key
.PD 0
.TP
.I shift
Shift + Key
.TP
.I esc
Escaped Key
.TP
.I altgr
AltGr + Key
.TP
.I ctl
Ctl + Key
.TP
.I ctlesc
Ctl + Escaped Key
.TP
.I shiftesc
Shift + Escaped Key
.TP
.I shiftaltgr
Shift + AltGr + Key
.TP
.I mod4
Mod4 + Key
.TP
.I altgrmod4
AltGr + Mod4 + Key
.PD
.PP
These layers can be accessed with the
.BR kbmap
file. A map entry is a line containing
three whitespace separated fields:
the layer name, the scancode, and the resulting
Unicode value. A layer may also historically
be addressed by its numeric index in the above list.
A Unicode value of zero indicates to drop that particular
input.
.PP
Reads return the current contents of the map.
Each map entry has its fields padded to 11
characters.
.PP
Writes accept new map entries.
Numeric values are taken to be decimal
unless they start with
.B 0x
(hexadecimal) or
.B 0
(octal).
The Unicode character can also be represented as
.BI ' x
where
.I x
gives the UTF-8 representation of the character
(see
.IR utf (6)),
or as 
.BI ^ X
to represent a control character.
.PP
Opening
.BR kbmap
with
.BR OTRUNC
resets the map back to the preloaded
ascii defaults.
.SH "SEE ALSO"
.IR cons (3),
.IR keyboard (6),
.IR utf (6),
.IR kbd (3),
.IR plan9.ini (8)
.SH FILES
.B /sys/lib/kbmap/*
.SH SOURCE
.B /sys/src/cmd/aux/kbdfs
.br
.B /rc/bin/console
.SH HISTORY
.I Kbdfs
first appeared in 9front (May, 2011).