1 .\" Copyright (c) 2011 Ed Schouten <ed@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd xterm-like terminal emulation interface
38 .Fn teken_init "teken_t *t" "const teken_funcs_t *funcs" "void *thunk"
40 .Fn teken_input "teken_t *t" "const void *buf" "size_t nbytes"
41 .Ft const teken_pos_t *
42 .Fn teken_get_winsize "teken_t *t"
44 .Fn teken_set_winsize "teken_t *t" "const teken_pos_t *size"
45 .Ft const teken_pos_t *
46 .Fn teken_get_cursor "teken_t *t"
48 .Fn teken_set_cursor "teken_t *t" "const teken_pos_t *pos"
49 .Ft const teken_attr_t *
50 .Fn teken_get_curattr "teken_t *t"
52 .Fn teken_set_curattr "teken_t *t" "const teken_attr_t *attr"
53 .Ft const teken_attr_t *
54 .Fn teken_get_defattr "teken_t *t"
56 .Fn teken_set_defattr "teken_t *t" "const teken_attr_t *attr"
58 .Fn teken_get_sequence "teken_t *t" "unsigned int id"
60 .Fn teken_256to8 "teken_color_t color"
62 .Fn teken_get_defattr_cons25 "teken_t *t" "int *fg" "int *bg"
64 .Fn teken_set_8bit "teken_t *t"
66 .Fn teken_set_cons25 "teken_t *t"
70 library implements the input parser of a 256-color xterm-like terminal.
71 It converts a stream of UTF-8 encoded characters into a series of
72 primitive drawing instructions that can be used by a console driver or
73 terminal emulator to render a terminal application.
77 function is used to initialize terminal state object
85 contains a set of callback functions, which are called when supplying
90 argument stores an arbitrary pointer, which is passed to each invocation
91 of the callback functions.
95 structure stores the following callbacks:
96 .Bd -literal -offset indent
98 tf_bell_t *tf_bell; /* Audible/visible bell. */
99 tf_cursor_t *tf_cursor; /* Move cursor to x/y. */
100 tf_putchar_t *tf_putchar; /* Put Unicode character at x/y. */
101 tf_fill_t *tf_fill; /* Fill rectangle with character. */
102 tf_copy_t *tf_copy; /* Copy rectangle to new location. */
103 tf_param_t *tf_param; /* Miscellaneous options. */
104 tf_respond_t *tf_respond; /* Send response string to user. */
108 All callbacks must be provided, though unimplemented callbacks may some
110 The actual types of these callbacks can be found in
117 structure to emulate a terminal having 24 rows and 80 columns.
119 .Fn teken_get_winsize
121 .Fn teken_set_winsize
122 functions can be used to obtain and modify the dimensions of the
125 Even though the cursor position is normally controlled by input of data
130 callback, it can be obtained and modified manually using the
136 .Fn teken_get_curattr
138 .Fn teken_set_curattr ,
139 which can be used to change the currently selected font attributes and
140 foreground and background color.
144 emulates a white-on-black terminal, which means the default foreground
145 color is white, while the background color is black.
146 These defaults can be modified using
147 .Fn teken_get_defattr
149 .Fn teken_set_defattr .
152 .Fn teken_get_sequence
153 function is a utility function that can be used to obtain escape
154 sequences of special keyboard keys, generated by user input.
157 parameter must be one of the
162 This library also provides a set of functions that shouldn't be used in
163 any modern applications.
167 function converts a color code to one of the 8 primary colors, allowing
168 the terminal to be rendered on graphics hardware that only supports 8 or
169 16 colors (e.g. VGA).
172 .Fn teken_get_defattr_cons25
173 function obtains the default terminal attributes as a pair of foreground
174 and background colors, using ANSI color numbering.
178 function disables UTF-8 processing and switches to 8-bit character mode,
179 which can be used to support character sets like CP437 and ISO-8859-1.
183 function switches terminal emulation to
185 which is used by versions of
197 though it was only available and used inside the kernel.
202 library appeared in userspace.
204 .An Ed Schouten Aq ed@FreeBSD.org
205 .Sh SECURITY CONSIDERATIONS
208 callback is used to respond to device status requests commands generated
210 In the past, there have been various security issues, where a malicious
211 application sends a device status request before termination, causing
212 the generated response to be interpreted by applications such as
216 only implements a small subset of responses which are unlikely to cause
218 Still, it is advised to leave