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 "const 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 "const 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 "const teken_t *t"
56 .Fn teken_set_defattr "teken_t *t" "const teken_attr_t *attr"
58 .Fn teken_get_sequence "const teken_t *t" "unsigned int id"
60 .Fn teken_256to16 "teken_color_t color"
62 .Fn teken_256to8 "teken_color_t color"
64 .Fn teken_get_defattr_cons25 "const teken_t *t" "int *fg" "int *bg"
66 .Fn teken_set_8bit "teken_t *t"
68 .Fn teken_set_cons25 "teken_t *t"
70 .Fn teken_set_cons25keys "teken_t *t"
74 library implements the input parser of a 256-color xterm-like terminal.
75 It converts a stream of UTF-8 encoded characters into a series of
76 primitive drawing instructions that can be used by a console driver or
77 terminal emulator to render a terminal application.
81 function is used to initialize terminal state object
89 contains a set of callback functions, which are called when supplying
94 argument stores an arbitrary pointer, which is passed to each invocation
95 of the callback functions.
99 structure stores the following callbacks:
100 .Bd -literal -offset indent
102 tf_bell_t *tf_bell; /* Audible/visible bell. */
103 tf_cursor_t *tf_cursor; /* Move cursor to x/y. */
104 tf_putchar_t *tf_putchar; /* Put Unicode character at x/y. */
105 tf_fill_t *tf_fill; /* Fill rectangle with character. */
106 tf_copy_t *tf_copy; /* Copy rectangle to new location. */
107 tf_param_t *tf_param; /* Miscellaneous options. */
108 tf_respond_t *tf_respond; /* Send response string to user. */
112 All callbacks must be provided, though unimplemented callbacks may some
114 The actual types of these callbacks can be found in
121 structure to emulate a terminal having 24 rows and 80 columns.
123 .Fn teken_get_winsize
125 .Fn teken_set_winsize
126 functions can be used to obtain and modify the dimensions of the
129 Even though the cursor position is normally controlled by input of data
134 callback, it can be obtained and modified manually using the
140 .Fn teken_get_curattr
142 .Fn teken_set_curattr ,
143 which can be used to change the currently selected font attributes and
144 foreground and background color.
148 emulates a white-on-black terminal, which means the default foreground
149 color is white, while the background color is black.
150 These defaults can be modified using
151 .Fn teken_get_defattr
153 .Fn teken_set_defattr .
156 .Fn teken_get_sequence
157 function is a utility function that can be used to obtain escape
158 sequences of special keyboard keys, generated by user input.
161 parameter must be one of the
166 This library also provides a set of functions that shouldn't be used in
167 any modern applications.
171 function converts an xterm-256 256-color code to an xterm 16-color code
172 whose color with default palettes is as similar as possible (not very
174 The lower 3 bits of the result are the ANSI color and the next lowest
176 Other layers (hardare and software) that only support 16 colors can use
177 this to avoid knowing the details of 256-color codes.
181 function is similar to
183 except it converts to an ANSI 8-color code.
184 This is more accurate than discarding the brigtness bit in the result of
188 .Fn teken_get_defattr_cons25
189 function obtains the default terminal attributes as a pair of foreground
190 and background colors, using ANSI color numbering.
194 function disables UTF-8 processing and switches to 8-bit character mode,
195 which can be used to support character sets like CP437 and ISO-8859-1.
199 function sets the terminal emulation to
201 which was the default for
206 This function is only useful for initialization.
207 The emulation can be changed at any time using an escape sequence,
208 and this function is not used then.
211 .Fn teken_set_cons25keys
213 .Fn teken_get_sequence
214 function to not interpret special keys in
226 though it was only available and used inside the kernel.
231 library appeared in userspace.
233 .An Ed Schouten Aq ed@FreeBSD.org
234 .Sh SECURITY CONSIDERATIONS
237 callback is used to respond to device status requests commands generated
239 In the past, there have been various security issues, where a malicious
240 application sends a device status request before termination, causing
241 the generated response to be interpreted by applications such as
245 only implements a small subset of responses which are unlikely to cause
247 Still, it is advised to leave