[unix-history] / usr.sbin / keymap / lib / keycap.3

.\" Contributed to 386bsd 0.1 and later versions
.\"
.\"	Copyright 1992 by Holger Veit
.\"	May be freely used with Bill Jolitz's port of 
.\"	386bsd and may be included in a 386bsd collection
.\"	as long as binary and source are available and reproduce the above
.\"	copyright.
.\"	 
.\"	You may freely modify this code and contribute improvements based
.\"	on this code as long as you don't claim to be the original author.
.\"	Commercial use of this source requires permittance of the copyright 
.\"	holder. A general license for 386bsd will override this restriction.
.\"
.\"	Use at your own risk. The copyright holder or any person who makes
.\"	this code available for the public (administrators of public archives
.\"	for instance) are not responsible for any harm to hardware or software
.\"	that might happen due to wrong application or program faults.
.\"
.\"	You must have the codriver driver in the same package generated
.\"	into the 386bsd kernel, otherwise this program does not work.
.\"
.\"     @(#)keycap.3	1.0 (contributed to 386bsd) 10/25/92
.\"
.Dd October 25, 1992
.Dt CONSUTIL 3
.Os 386bsd 0.2
.Sh NAME
.Nm kgetent ,
.Nm kgetnum ,
.Nm kgetflag ,
.Nm kgetstr
.Nd keyboard independent operation routines
.Sh SYNOPSIS
.Fn kgetent "char *bp" "char *name"
.Fn kgetnum "char *id"
.Fn kgetflag "char *id"
.Ft char *
.Fn kgetstr "char *id" "char *area"
.Sh DESCRIPTION
These functions extract and use capabilities from a keyboard capability data
base, usually
.Pa /usr/share/misc/keycap ,
the format of which is described in
.Xr keycap 5 .
.Pp
The
.Fn kgetent
function
extracts the entry for a keyboard entry
.Fa name
into the buffer at
.Fa bp .
The
.Fa bp
argument
should be a character buffer of size
1024 and must be retained through all subsequent calls to
.Fn kgetnum ,
.Fn kgetflag ,
and
.Fn kgetstr .
The
.Fn kgetent
function
returns \-1 if none of the
.Nm keycap
data base files could be opened,
0 if the keyboard name given does not have an entry,
and 1 if all goes well.
It will look in the environment for a
.Ev KEYCAP
variable.
If found, and the value does not begin with a slash, 
and the keyboard type
.Fa name
is the same as the environment string
.Ev KEYBOARD ,
the
.Ev KEYCAP
string is used instead of reading a
.Nm keycap
file.
If it does begin with a slash, the string is used as a path name
of the
.Nm keycap
file to search.
If
.Ev KEYCAP
does not begin with a slash,
.Fn kgetent
searches the file
.Pp
The
.Fn kgetnum
function
gets the numeric value of capability
.Fa id ,
returning \-1 if is not given for the keyboard
The
.Fn kgetflag
function
returns 1 if the specified capability is present in
the keyboard's entry, 0 if it is not.
The
.Fn kgetstr
function
returns the string value of the capability
.Fa id ,
places it in the buffer at
.Fa area ,
and advances the
.Fa area
pointer.
It decodes the abbreviations for this field described in
.Xr keycap 5 .
The
.Fn kgetstr
function
returns
.Dv NULL
if the capability was not found.
.Pp
.Sh FILES
.Bl -tag -width /usr/share/misc/keycap -compact
.It Pa /usr/lib/libconsutil.a
.Fl l Ar consutil
keycap utilities library
.It Pa /usr/share/misc/keycap
standard keyboard capability data base
.El
.Sh SEE ALSO
.Xr co 4 ,
.Xr keycap 5
.Sh HISTORY
The
.Nm
keyboard capability data base is a new feature of 386bsd 0.2 and later.
Commit	Line	Data
15637ed4 RG	1	.\" Contributed to 386bsd 0.1 and later versions
	2	.\"
	3	.\" Copyright 1992 by Holger Veit
	4	.\" May be freely used with Bill Jolitz's port of
	5	.\" 386bsd and may be included in a 386bsd collection
	6	.\" as long as binary and source are available and reproduce the above
	7	.\" copyright.
	8	.\"
	9	.\" You may freely modify this code and contribute improvements based
	10	.\" on this code as long as you don't claim to be the original author.
	11	.\" Commercial use of this source requires permittance of the copyright
	12	.\" holder. A general license for 386bsd will override this restriction.
	13	.\"
	14	.\" Use at your own risk. The copyright holder or any person who makes
	15	.\" this code available for the public (administrators of public archives
	16	.\" for instance) are not responsible for any harm to hardware or software
	17	.\" that might happen due to wrong application or program faults.
	18	.\"
	19	.\" You must have the codriver driver in the same package generated
	20	.\" into the 386bsd kernel, otherwise this program does not work.
	21	.\"
	22	.\" @(#)keycap.3 1.0 (contributed to 386bsd) 10/25/92
	23	.\"
	24	.Dd October 25, 1992
	25	.Dt CONSUTIL 3
	26	.Os 386bsd 0.2
	27	.Sh NAME
	28	.Nm kgetent ,
	29	.Nm kgetnum ,
	30	.Nm kgetflag ,
	31	.Nm kgetstr
	32	.Nd keyboard independent operation routines
	33	.Sh SYNOPSIS
	34	.Fn kgetent "char bp" "char name"
	35	.Fn kgetnum "char *id"
	36	.Fn kgetflag "char *id"
	37	.Ft char *
	38	.Fn kgetstr "char id" "char area"
	39	.Sh DESCRIPTION
	40	These functions extract and use capabilities from a keyboard capability data
	41	base, usually
	42	.Pa /usr/share/misc/keycap ,
	43	the format of which is described in
	44	.Xr keycap 5 .
	45	.Pp
	46	The
	47	.Fn kgetent
	48	function
	49	extracts the entry for a keyboard entry
	50	.Fa name
	51	into the buffer at
	52	.Fa bp .
	53	The
	54	.Fa bp
	55	argument
	56	should be a character buffer of size
	57	1024 and must be retained through all subsequent calls to
	58	.Fn kgetnum ,
	59	.Fn kgetflag ,
	60	and
	61	.Fn kgetstr .
	62	The
	63	.Fn kgetent
	64	function
65	returns \-1 if none of the
66	.Nm keycap
67	data base files could be opened,
68	0 if the keyboard name given does not have an entry,
69	and 1 if all goes well.
70	It will look in the environment for a
71	.Ev KEYCAP
72	variable.
73	If found, and the value does not begin with a slash,
74	and the keyboard type
75	.Fa name
76	is the same as the environment string
77	.Ev KEYBOARD ,
78	the
79	.Ev KEYCAP
80	string is used instead of reading a
81	.Nm keycap
82	file.
83	If it does begin with a slash, the string is used as a path name
84	of the
85	.Nm keycap
86	file to search.
87	If
88	.Ev KEYCAP
89	does not begin with a slash,
90	.Fn kgetent
91	searches the file
92	.Pp
93	The
94	.Fn kgetnum
95	function
96	gets the numeric value of capability
97	.Fa id ,
98	returning \-1 if is not given for the keyboard
99	The
100	.Fn kgetflag
101	function
102	returns 1 if the specified capability is present in
103	the keyboard's entry, 0 if it is not.
104	The
105	.Fn kgetstr
106	function
107	returns the string value of the capability
108	.Fa id ,
109	places it in the buffer at
110	.Fa area ,
111	and advances the
112	.Fa area
113	pointer.
114	It decodes the abbreviations for this field described in
115	.Xr keycap 5 .
116	The
117	.Fn kgetstr
118	function
119	returns
120	.Dv NULL
121	if the capability was not found.
122	.Pp
123	.Sh FILES
124	.Bl -tag -width /usr/share/misc/keycap -compact
125	.It Pa /usr/lib/libconsutil.a
126	.Fl l Ar consutil
127	keycap utilities library
128	.It Pa /usr/share/misc/keycap
129	standard keyboard capability data base
130	.El
131	.Sh SEE ALSO
132	.Xr co 4 ,
133	.Xr keycap 5
134	.Sh HISTORY
135	The
136	.Nm
137	keyboard capability data base is a new feature of 386bsd 0.2 and later.