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