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.\" $FreeBSD$ 26.\" 27.Dd Mar 13, 2017 28.Dt TEKEN 3 29.Os 30.Sh NAME 31.Nm teken 32.Nd xterm-like terminal emulation interface 33.Sh LIBRARY 34.Lb libteken 35.Sh SYNOPSIS 36.In teken.h 37.Ft void 38.Fn teken_init "teken_t *t" "const teken_funcs_t *funcs" "void *thunk" 39.Ft void 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" 43.Ft void 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" 47.Ft void 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" 51.Ft void 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" 55.Ft void 56.Fn teken_set_defattr "teken_t *t" "const teken_attr_t *attr" 57.Ft const char * 58.Fn teken_get_sequence "teken_t *t" "unsigned int id" 59.Ft teken_color_t 60.Fn teken_256to16 "teken_color_t color" 61.Ft teken_color_t 62.Fn teken_256to8 "teken_color_t color" 63.Ft void 64.Fn teken_get_defattr_cons25 "teken_t *t" "int *fg" "int *bg" 65.Ft void 66.Fn teken_set_8bit "teken_t *t" 67.Ft void 68.Fn teken_set_cons25 "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 brigtness 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 switches terminal emulation to 198.Dv cons25 , 199which is used by versions of 200.Fx 201prior to 9.0. 202.Sh SEE ALSO 203.Xr ncurses 3 , 204.Xr termcap 3 , 205.Xr syscons 4 206.Sh HISTORY 207The 208.Nm 209library appeared in 210.Fx 8.0 , 211though it was only available and used inside the kernel. 212In 213.Fx 9.0 , 214the 215.Nm 216library appeared in userspace. 217.Sh AUTHORS 218.An Ed Schouten Aq ed@FreeBSD.org 219.Sh SECURITY CONSIDERATIONS 220The 221.Fn tf_respond 222callback is used to respond to device status requests commands generated 223by an application. 224In the past, there have been various security issues, where a malicious 225application sends a device status request before termination, causing 226the generated response to be interpreted by applications such as 227.Xr sh 1 . 228.Pp 229.Nm 230only implements a small subset of responses which are unlikely to cause 231any harm. 232Still, it is advised to leave 233.Fn tf_respond 234unimplemented. 235