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 "const 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 "const 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 "const 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 "const 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 "const 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.Ft void 70.Fn teken_set_cons25keys "teken_t *t" 71.Sh DESCRIPTION 72The 73.Nm 74library implements the input parser of a 256-color xterm-like terminal. 75It converts a stream of UTF-8 encoded characters into a series of 76primitive drawing instructions that can be used by a console driver or 77terminal emulator to render a terminal application. 78.Pp 79The 80.Fn teken_init 81function is used to initialize terminal state object 82.Fa t , 83having type 84.Vt teken_t . 85The supplied 86.Vt teken_funcs_t 87structure 88.Fa funcs 89contains a set of callback functions, which are called when supplying 90data to 91.Fn teken_input . 92The 93.Fa thunk 94argument stores an arbitrary pointer, which is passed to each invocation 95of the callback functions. 96.Pp 97The 98.Vt teken_funcs_t 99structure stores the following callbacks: 100.Bd -literal -offset indent 101typedef struct { 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. */ 109} teken_funcs_t; 110.Ed 111.Pp 112All callbacks must be provided, though unimplemented callbacks may some 113times be sufficient. 114The actual types of these callbacks can be found in 115.In teken.h . 116.Pp 117By default, 118.Fn teken_init 119initializes the 120.Vt teken_t 121structure to emulate a terminal having 24 rows and 80 columns. 122The 123.Fn teken_get_winsize 124and 125.Fn teken_set_winsize 126functions can be used to obtain and modify the dimensions of the 127terminal. 128.Pp 129Even though the cursor position is normally controlled by input of data 130through 131.Fn teken_input 132and returned by the 133.Fn tf_cursor 134callback, it can be obtained and modified manually using the 135.Fn teken_get_cursor 136and 137.Fn teken_set_cursor 138functions. 139The same holds for 140.Fn teken_get_curattr 141and 142.Fn teken_set_curattr , 143which can be used to change the currently selected font attributes and 144foreground and background color. 145.Pp 146By default, 147.Nm 148emulates a white-on-black terminal, which means the default foreground 149color is white, while the background color is black. 150These defaults can be modified using 151.Fn teken_get_defattr 152and 153.Fn teken_set_defattr . 154.Pp 155The 156.Fn teken_get_sequence 157function is a utility function that can be used to obtain escape 158sequences of special keyboard keys, generated by user input. 159The 160.Fa id 161parameter must be one of the 162.Dv TKEY_* 163parameters listed in 164.In teken.h . 165.Sh LEGACY FEATURES 166This library also provides a set of functions that shouldn't be used in 167any modern applications. 168.Pp 169The 170.Fn teken_256to16 171function converts an xterm-256 256-color code to an xterm 16-color code 172whose color with default palettes is as similar as possible (not very 173similar). 174The lower 3 bits of the result are the ANSI color and the next lowest 175bit is brightness. 176Other layers (hardare and software) that only support 16 colors can use 177this to avoid knowing the details of 256-color codes. 178.Pp 179The 180.Fn teken_256to8 181function is similar to 182.Fn teken_256to16 183except it converts to an ANSI 8-color code. 184This is more accurate than discarding the brigtness bit in the result of 185.Fn teken_256to16 . 186.Pp 187The 188.Fn teken_get_defattr_cons25 189function obtains the default terminal attributes as a pair of foreground 190and background colors, using ANSI color numbering. 191.Pp 192The 193.Fn teken_set_8bit 194function disables UTF-8 processing and switches to 8-bit character mode, 195which can be used to support character sets like CP437 and ISO-8859-1. 196.Pp 197The 198.Fn teken_set_cons25 199function sets the terminal emulation to 200.Dv cons25 , 201which was the default for 202.Xr syscons 4 203in versions of 204.Fx 205prior to 9.0. 206This function is only useful for initialization. 207The emulation can be changed at any time using an escape sequence, 208and this function is not used then. 209.Pp 210The 211.Fn teken_set_cons25keys 212function tells the 213.Fn teken_get_sequence 214function to not interpret special keys in 215.Dv cons25 216mode. 217.Sh SEE ALSO 218.Xr ncurses 3 , 219.Xr termcap 3 , 220.Xr syscons 4 221.Sh HISTORY 222The 223.Nm 224library appeared in 225.Fx 8.0 , 226though it was only available and used inside the kernel. 227In 228.Fx 9.0 , 229the 230.Nm 231library appeared in userspace. 232.Sh AUTHORS 233.An Ed Schouten Aq ed@FreeBSD.org 234.Sh SECURITY CONSIDERATIONS 235The 236.Fn tf_respond 237callback is used to respond to device status requests commands generated 238by an application. 239In the past, there have been various security issues, where a malicious 240application sends a device status request before termination, causing 241the generated response to be interpreted by applications such as 242.Xr sh 1 . 243.Pp 244.Nm 245only implements a small subset of responses which are unlikely to cause 246any harm. 247Still, it is advised to leave 248.Fn tf_respond 249unimplemented. 250