teken/libteken/teken.3

.\" $MidnightBSD$
.\" Copyright (c) 2011 Ed Schouten <ed@FreeBSD.org>
.\" All rights reserved.
.\"
.\" 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 AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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: stable/11/sys/teken/libteken/teken.3 330916 2018-03-14 07:47:26Z eadler $
.\"
.Dd Mar 13, 2017
.Dt TEKEN 3
.Os
.Sh NAME
.Nm teken
.Nd xterm-like terminal emulation interface
.Sh LIBRARY
.Lb libteken
.Sh SYNOPSIS
.In teken.h
.Ft void
.Fn teken_init "teken_t *t" "const teken_funcs_t *funcs" "void *thunk"
.Ft void
.Fn teken_input "teken_t *t" "const void *buf" "size_t nbytes"
.Ft const teken_pos_t *
.Fn teken_get_winsize "teken_t *t"
.Ft void
.Fn teken_set_winsize "teken_t *t" "const teken_pos_t *size"
.Ft const teken_pos_t *
.Fn teken_get_cursor "teken_t *t"
.Ft void
.Fn teken_set_cursor "teken_t *t" "const teken_pos_t *pos"
.Ft const teken_attr_t *
.Fn teken_get_curattr "teken_t *t"
.Ft void
.Fn teken_set_curattr "teken_t *t" "const teken_attr_t *attr"
.Ft const teken_attr_t *
.Fn teken_get_defattr "teken_t *t"
.Ft void
.Fn teken_set_defattr "teken_t *t" "const teken_attr_t *attr"
.Ft const char *
.Fn teken_get_sequence "teken_t *t" "unsigned int id"
.Ft teken_color_t
.Fn teken_256to16 "teken_color_t color"
.Ft teken_color_t
.Fn teken_256to8 "teken_color_t color"
.Ft void
.Fn teken_get_defattr_cons25 "teken_t *t" "int *fg" "int *bg"
.Ft void
.Fn teken_set_8bit "teken_t *t"
.Ft void
.Fn teken_set_cons25 "teken_t *t"
.Sh DESCRIPTION
The
.Nm
library implements the input parser of a 256-color xterm-like terminal.
It converts a stream of UTF-8 encoded characters into a series of
primitive drawing instructions that can be used by a console driver or
terminal emulator to render a terminal application.
.Pp
The
.Fn teken_init
function is used to initialize terminal state object
.Fa t ,
having type
.Vt teken_t .
The supplied
.Vt teken_funcs_t
structure
.Fa funcs
contains a set of callback functions, which are called when supplying
data to
.Fn teken_input .
The
.Fa thunk
argument stores an arbitrary pointer, which is passed to each invocation
of the callback functions.
.Pp
The
.Vt teken_funcs_t
structure stores the following callbacks:
.Bd -literal -offset indent
typedef struct {
        tf_bell_t     *tf_bell;     /* Audible/visible bell. */
        tf_cursor_t   *tf_cursor;   /* Move cursor to x/y. */
        tf_putchar_t  *tf_putchar;  /* Put Unicode character at x/y. */
        tf_fill_t     *tf_fill;     /* Fill rectangle with character. */
        tf_copy_t     *tf_copy;     /* Copy rectangle to new location. */
        tf_param_t    *tf_param;    /* Miscellaneous options. */
        tf_respond_t  *tf_respond;  /* Send response string to user. */
} teken_funcs_t;
.Ed
.Pp
All callbacks must be provided, though unimplemented callbacks may some
times be sufficient.
The actual types of these callbacks can be found in
.In teken.h .
.Pp
By default,
.Fn teken_init
initializes the
.Vt teken_t
structure to emulate a terminal having 24 rows and 80 columns.
The
.Fn teken_get_winsize
and
.Fn teken_set_winsize
functions can be used to obtain and modify the dimensions of the
terminal.
.Pp
Even though the cursor position is normally controlled by input of data
through
.Fn teken_input
and returned by the
.Fn tf_cursor
callback, it can be obtained and modified manually using the
.Fn teken_get_cursor
and
.Fn teken_set_cursor
functions.
The same holds for
.Fn teken_get_curattr
and
.Fn teken_set_curattr ,
which can be used to change the currently selected font attributes and
foreground and background color.
.Pp
By default,
.Nm
emulates a white-on-black terminal, which means the default foreground
color is white, while the background color is black.
These defaults can be modified using
.Fn teken_get_defattr
and
.Fn teken_set_defattr .
.Pp
The
.Fn teken_get_sequence
function is a utility function that can be used to obtain escape
sequences of special keyboard keys, generated by user input.
The
.Fa id
parameter must be one of the
.Dv TKEY_*
parameters listed in
.In teken.h .
.Sh LEGACY FEATURES
This library also provides a set of functions that shouldn't be used in
any modern applications.
.Pp
The
.Fn teken_256to16
function converts an xterm-256 256-color code to an xterm 16-color code
whose color with default palettes is as similar as possible (not very
similar).
The lower 3 bits of the result are the ANSI color and the next lowest
bit is brightness.
Other layers (hardare and software) that only support 16 colors can use
this to avoid knowing the details of 256-color codes.
.Pp
The
.Fn teken_256to8
function is similar to
.Fn teken_256to16
except it converts to an ANSI 8-color code.
This is more accurate than discarding the brigtness bit in the result of
.Fn teken_256to16 .
.Pp
The
.Fn teken_get_defattr_cons25
function obtains the default terminal attributes as a pair of foreground
and background colors, using ANSI color numbering.
.Pp
The
.Fn teken_set_8bit
function disables UTF-8 processing and switches to 8-bit character mode,
which can be used to support character sets like CP437 and ISO-8859-1.
.Pp
The
.Fn teken_set_cons25
function switches terminal emulation to
.Dv cons25 ,
which is used by versions of
.Fx
prior to 9.0.
.Sh SEE ALSO
.Xr ncurses 3 ,
.Xr termcap 3 ,
.Xr syscons 4
.Sh HISTORY
The
.Nm
library appeared in
.Fx 8.0 ,
though it was only available and used inside the kernel.
In
.Fx 9.0 ,
the
.Nm
library appeared in userspace.
.Sh AUTHORS
.An Ed Schouten Aq ed@FreeBSD.org
.Sh SECURITY CONSIDERATIONS
The
.Fn tf_respond
callback is used to respond to device status requests commands generated
by an application.
In the past, there have been various security issues, where a malicious
application sends a device status request before termination, causing
the generated response to be interpreted by applications such as
.Xr sh 1 .
.Pp
.Nm
only implements a small subset of responses which are unlikely to cause
any harm.
Still, it is advised to leave
.Fn tf_respond
unimplemented.
Revision:	12320
Committed:	Sat Feb 8 19:46:22 2020 UTC (4 years, 3 months ago) by laffer1
File size:	7134 byte(s)
Log Message:	sync with FreeBSD 11-stable
#	Content
1	.\" $MidnightBSD$
2	.\" Copyright (c) 2011 Ed Schouten <ed@FreeBSD.org>
3	.\" All rights reserved.
4	.\"
5	.\" Redistribution and use in source and binary forms, with or without
6	.\" modification, are permitted provided that the following conditions
7	.\" are met:
8	.\" 1. Redistributions of source code must retain the above copyright
9	.\" notice, this list of conditions and the following disclaimer.
10	.\" 2. Redistributions in binary form must reproduce the above copyright
11	.\" notice, this list of conditions and the following disclaimer in the
12	.\" documentation and/or other materials provided with the distribution.
13	.\"
14	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24	.\" SUCH DAMAGE.
25	.\"
26	.\" $FreeBSD: stable/11/sys/teken/libteken/teken.3 330916 2018-03-14 07:47:26Z eadler $
27	.\"
28	.Dd Mar 13, 2017
29	.Dt TEKEN 3
30	.Os
31	.Sh NAME
32	.Nm teken
33	.Nd xterm-like terminal emulation interface
34	.Sh LIBRARY
35	.Lb libteken
36	.Sh SYNOPSIS
37	.In teken.h
38	.Ft void
39	.Fn teken_init "teken_t t" "const teken_funcs_t funcs" "void *thunk"
40	.Ft void
41	.Fn teken_input "teken_t t" "const void buf" "size_t nbytes"
42	.Ft const teken_pos_t *
43	.Fn teken_get_winsize "teken_t *t"
44	.Ft void
45	.Fn teken_set_winsize "teken_t t" "const teken_pos_t size"
46	.Ft const teken_pos_t *
47	.Fn teken_get_cursor "teken_t *t"
48	.Ft void
49	.Fn teken_set_cursor "teken_t t" "const teken_pos_t pos"
50	.Ft const teken_attr_t *
51	.Fn teken_get_curattr "teken_t *t"
52	.Ft void
53	.Fn teken_set_curattr "teken_t t" "const teken_attr_t attr"
54	.Ft const teken_attr_t *
55	.Fn teken_get_defattr "teken_t *t"
56	.Ft void
57	.Fn teken_set_defattr "teken_t t" "const teken_attr_t attr"
58	.Ft const char *
59	.Fn teken_get_sequence "teken_t *t" "unsigned int id"
60	.Ft teken_color_t
61	.Fn teken_256to16 "teken_color_t color"
62	.Ft teken_color_t
63	.Fn teken_256to8 "teken_color_t color"
64	.Ft void
65	.Fn teken_get_defattr_cons25 "teken_t t" "int fg" "int *bg"
66	.Ft void
67	.Fn teken_set_8bit "teken_t *t"
68	.Ft void
69	.Fn teken_set_cons25 "teken_t *t"
70	.Sh DESCRIPTION
71	The
72	.Nm
73	library implements the input parser of a 256-color xterm-like terminal.
74	It converts a stream of UTF-8 encoded characters into a series of
75	primitive drawing instructions that can be used by a console driver or
76	terminal emulator to render a terminal application.
77	.Pp
78	The
79	.Fn teken_init
80	function is used to initialize terminal state object
81	.Fa t ,
82	having type
83	.Vt teken_t .
84	The supplied
85	.Vt teken_funcs_t
86	structure
87	.Fa funcs
88	contains a set of callback functions, which are called when supplying
89	data to
90	.Fn teken_input .
91	The
92	.Fa thunk
93	argument stores an arbitrary pointer, which is passed to each invocation
94	of the callback functions.
95	.Pp
96	The
97	.Vt teken_funcs_t
98	structure stores the following callbacks:
99	.Bd -literal -offset indent
100	typedef struct {
101	tf_bell_t tf_bell; / Audible/visible bell. */
102	tf_cursor_t tf_cursor; / Move cursor to x/y. */
103	tf_putchar_t tf_putchar; / Put Unicode character at x/y. */
104	tf_fill_t tf_fill; / Fill rectangle with character. */
105	tf_copy_t tf_copy; / Copy rectangle to new location. */
106	tf_param_t tf_param; / Miscellaneous options. */
107	tf_respond_t tf_respond; / Send response string to user. */
108	} teken_funcs_t;
109	.Ed
110	.Pp
111	All callbacks must be provided, though unimplemented callbacks may some
112	times be sufficient.
113	The actual types of these callbacks can be found in
114	.In teken.h .
115	.Pp
116	By default,
117	.Fn teken_init
118	initializes the
119	.Vt teken_t
120	structure to emulate a terminal having 24 rows and 80 columns.
121	The
122	.Fn teken_get_winsize
123	and
124	.Fn teken_set_winsize
125	functions can be used to obtain and modify the dimensions of the
126	terminal.
127	.Pp
128	Even though the cursor position is normally controlled by input of data
129	through
130	.Fn teken_input
131	and returned by the
132	.Fn tf_cursor
133	callback, it can be obtained and modified manually using the
134	.Fn teken_get_cursor
135	and
136	.Fn teken_set_cursor
137	functions.
138	The same holds for
139	.Fn teken_get_curattr
140	and
141	.Fn teken_set_curattr ,
142	which can be used to change the currently selected font attributes and
143	foreground and background color.
144	.Pp
145	By default,
146	.Nm
147	emulates a white-on-black terminal, which means the default foreground
148	color is white, while the background color is black.
149	These defaults can be modified using
150	.Fn teken_get_defattr
151	and
152	.Fn teken_set_defattr .
153	.Pp
154	The
155	.Fn teken_get_sequence
156	function is a utility function that can be used to obtain escape
157	sequences of special keyboard keys, generated by user input.
158	The
159	.Fa id
160	parameter must be one of the
161	.Dv TKEY_*
162	parameters listed in
163	.In teken.h .
164	.Sh LEGACY FEATURES
165	This library also provides a set of functions that shouldn't be used in
166	any modern applications.
167	.Pp
168	The
169	.Fn teken_256to16
170	function converts an xterm-256 256-color code to an xterm 16-color code
171	whose color with default palettes is as similar as possible (not very
172	similar).
173	The lower 3 bits of the result are the ANSI color and the next lowest
174	bit is brightness.
175	Other layers (hardare and software) that only support 16 colors can use
176	this to avoid knowing the details of 256-color codes.
177	.Pp
178	The
179	.Fn teken_256to8
180	function is similar to
181	.Fn teken_256to16
182	except it converts to an ANSI 8-color code.
183	This is more accurate than discarding the brigtness bit in the result of
184	.Fn teken_256to16 .
185	.Pp
186	The
187	.Fn teken_get_defattr_cons25
188	function obtains the default terminal attributes as a pair of foreground
189	and background colors, using ANSI color numbering.
190	.Pp
191	The
192	.Fn teken_set_8bit
193	function disables UTF-8 processing and switches to 8-bit character mode,
194	which can be used to support character sets like CP437 and ISO-8859-1.
195	.Pp
196	The
197	.Fn teken_set_cons25
198	function switches terminal emulation to
199	.Dv cons25 ,
200	which is used by versions of
201	.Fx
202	prior to 9.0.
203	.Sh SEE ALSO
204	.Xr ncurses 3 ,
205	.Xr termcap 3 ,
206	.Xr syscons 4
207	.Sh HISTORY
208	The
209	.Nm
210	library appeared in
211	.Fx 8.0 ,
212	though it was only available and used inside the kernel.
213	In
214	.Fx 9.0 ,
215	the
216	.Nm
217	library appeared in userspace.
218	.Sh AUTHORS
219	.An Ed Schouten Aq ed@FreeBSD.org
220	.Sh SECURITY CONSIDERATIONS
221	The
222	.Fn tf_respond
223	callback is used to respond to device status requests commands generated
224	by an application.
225	In the past, there have been various security issues, where a malicious
226	application sends a device status request before termination, causing
227	the generated response to be interpreted by applications such as
228	.Xr sh 1 .
229	.Pp
230	.Nm
231	only implements a small subset of responses which are unlikely to cause
232	any harm.
233	Still, it is advised to leave
234	.Fn tf_respond
235	unimplemented.