While trying to figure out if you can have a "halt" key as well as
a "reboot" key I noticed there is no man page describing the keymap
files which kbdcontrol loads.  This is actually noted in
usr.sbin/kbdmap/TODO (dated 95/04/03) saying refering to kbdmap.5.
There is also a reference at the bottom of the syscons man page to
keymap(5), which doesn't exist.

Fix: 

I wrote the following man page based on the 5.X version of kbdcontrol
and reading the source for syscons and kbd to figure out what was
going on. I guess it should probably go in share/man/man5 or
usr.sbin/kbdcontrol. I've written it as kbdmap(5), but it would
probably be worth having it also available as keymap(5).

People who understand mdoc will probably want to read over it to make
sure it's OK. My spelling sucks too, but I've run it throug a spell
checker, so it shouldn't be too bad.


.\" Copyright (c) 2000
.\"	David Malone
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: $
.\"
.Dd June 14, 2000
.Dt KBDMAP 5
.Os FreeBSD
.Sh NAME
.Nm kbdmap
.Nd keyboard map file format for kbdcontrol
.Sh DESCRIPTION
A
.Nm kbdmap
file describes how the keys on a keyboard should behave. These
files can be loaded using
.Xr kbdcontrol 1 ,
or
.Xr kbdmap 1
can be used to select one of the default
.Nm kbdmap
files interactively.
A
.Nm kbdmap
file can be specified in
.Xr rc.conf 5
to be loaded at boot time. The current keymap may also be printed
using
.Xr kbdcontrol.
.Pp
Each line in the file can describe a key or an accent. A # character
begins a comment, which extends to the end of the line.
.Pp
The description
of a key begins with the scancode for that key. Then the effect of the
key under combinations of shift, control and alt are listed in the
following order: no modifier, shift, control, control and shift, alt,
alt and shift, alt and control, alt and control and shift. The action
of the key under each modifier can be:
.Bl -tag -width Ar
.It Ar 'symbol'
The symbol the key should produce, in single quotes.
.It Ar number
The ASCII value to produce as a decimal number. For example 32 for space.
.It Ar 0xhexnum
The ASCII value to produce as a hexadecimal number. For example 0x20 for space.
.It Ar ctrlname
One of the standard names for the ASCII control characters: nul,
soh, stx, etx, eot, enq, ack, bel, bs, ht, nl, vt, np, cr, so, si,
dle, dc1 , dc2, dc3, dc4, nak, syn, etb, can, em, sub, esc, fs,
gs, rs, ns, us, sp, del.
.It Ar accentname
By giving one of the accent names, the next key pressed will produce
an accented character in accordance with that accent. See the
description of accents below. The accent names are: dgra, dacu,
dcir, dtil, dmac, dbre, ddot, duml, ddia, dsla, drin, dced, dapo,
ddac, dogo, dcar.
.It Ar fkeyN
Act as the the Nth function key, where N is a decimal number.
.It Ar lshift 
Act as left shift key.
.It Ar rshift 
Act as right shift key.
.It Ar clock 
Act as caps lock key.
.It Ar nlock 
Act as num lock key.
.It Ar slock 
Act as scroll lock key.
.It Ar lalt|alt 
Act as left alt key.
.It Ar btab 
Act as backwards tab.
.It Ar lctrl|ctrl 
Act as left control key.
.It Ar rctrl 
Act as right control key.
.It Ar ralt 
Act as right alt (altgr) key.
.It Ar alock 
Act as alt lock key.
.It Ar ashift 
Act as alt shift key.
.It Ar meta 
Act as meta key.
.It Ar lshifta|shifta 
Act as left shift key / alt lock.
.It Ar rshifta 
Act as right shift key / alt lock.
.It Ar lctrla|ctrla 
Act as left ctrl key / alt lock.
.It Ar rctrla 
Act as right ctrl key / alt lock.
.It Ar lalta|alta 
Act as left alt key / alt lock.
.It Ar ralta 
Act as right alt key / alt lock.
.It Ar nscr 
Act as switch to next screen.
.It Ar pscr 
Act as switch to previous screen.
.It Ar scrN
switch to screen N, where N is a decimal number.
.It Ar boot 
Reboot machine.
.It Ar debug 
Call the debugger.
.It Ar susp 
Use APM to suspend power.
.It Ar saver 
Activate screen saver by toggling between splash/text screen.
.It Ar panic 
Panic the system.
.El
.Pp
Finally, to complete the description of a key, a flag which describes
the effect of caps lock and num lock on that key is given. The flag can
be
.Ql C
to indicate caps lock effects the key,
.Ql N
to indicate that num lock effects the key,
.Ql B
to indicate both caps lock and num lock effect the key
or
.Ql O
to indicate neither effect the key.
.Pp
An accent key works works by modifying the behavior of the next key
pressed.  The description of an accent begins with one of the accent
names given above.  This is followed by the symbol for the accent,
given in single quotes or as a decimal or hexadecimal ascii value.
This symbol will be produced if the accent key is pressed and then
the space key is pressed.
.Pp
The description of the accent key continues with a list showing
how it modifies various symbols, by giving pairs giving the normal
symbol and the modified symbol enclosed in parentheses. Both symbols
can be given in single quotes or as decimal or hexadecimal ascii values.
.Pp
For example, the following extract from a
.Nm kbdmap :
.Bd -literal -offset indent
  041   dgra   172    nop    nop    '|'    '|'    nop    nop     O
  dgra  '`'  ( 'a' 224 ) ( 'A' 192 ) ( 'e' 232 ) ( 'E' 200 )
             ( 'i' 236 ) ( 'I' 204 ) ( 'o' 242 ) ( 'O' 210 )
             ( 'u' 249 ) ( 'U' 217 )
.Ed
configures the backtick key on a UK keyboard to act as a grave accent
key. Pressing backtick followed by space produces a backtick, and
pressing a backtick followed by a vowel produces the ISO-8859-1 symbol
for that vowel with a grave accent.
.Sh FILES
.Bl -tag -width /usr/share/syscons/keymaps/* -compact
.It Pa /usr/share/syscons/keymaps/*

standard keyboard map files
.El
.Sh SEE ALSO
.Xr kbdcontrol 1 ,
.Xr kbdmap 1 ,
.Xr keyboard 4 ,
.Xr syscons 4 ,
.Xr ascii 7
.Sh HISTORY
This man page first appeared in
.Fx 5.0
How-To-Repeat: 
man 5 kbdmap
man 5 keymap