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