sys/teken/libteken/teken.3

   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
  72 The
  73 .Nm
  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.
  78 .Pp
  79 The
  80 .Fn teken_init
  81 function is used to initialize terminal state object
  82 .Fa t ,
  83 having type
  84 .Vt teken_t .
  85 The supplied
  86 .Vt teken_funcs_t
  87 structure
  88 .Fa funcs
  89 contains a set of callback functions, which are called when supplying
  90 data to
  91 .Fn teken_input .
  92 The
  93 .Fa thunk
  94 argument stores an arbitrary pointer, which is passed to each invocation
  95 of the callback functions.
  96 .Pp
  97 The
  98 .Vt teken_funcs_t
  99 structure stores the following callbacks:
 100 .Bd -literal -offset indent
 101 typedef 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
 112 All callbacks must be provided, though unimplemented callbacks may some
 113 times be sufficient.
 114 The actual types of these callbacks can be found in
 115 .In teken.h .
 116 .Pp
 117 By default,
 118 .Fn teken_init
 119 initializes the
 120 .Vt teken_t
 121 structure to emulate a terminal having 24 rows and 80 columns.
 122 The
 123 .Fn teken_get_winsize
 124 and
 125 .Fn teken_set_winsize
 126 functions can be used to obtain and modify the dimensions of the
 127 terminal.
 128 .Pp
 129 Even though the cursor position is normally controlled by input of data
 130 through
 131 .Fn teken_input
 132 and returned by the
 133 .Fn tf_cursor
 134 callback, it can be obtained and modified manually using the
 135 .Fn teken_get_cursor
 136 and
 137 .Fn teken_set_cursor
 138 functions.
 139 The same holds for
 140 .Fn teken_get_curattr
 141 and
 142 .Fn teken_set_curattr ,
 143 which can be used to change the currently selected font attributes and
 144 foreground and background color.
 145 .Pp
 146 By default,
 147 .Nm
 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
 152 and
 153 .Fn teken_set_defattr .
 154 .Pp
 155 The
 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.
 159 The
 160 .Fa id
 161 parameter must be one of the
 162 .Dv TKEY_*
 163 parameters listed in
 164 .In teken.h .
 165 .Sh LEGACY FEATURES
 166 This library also provides a set of functions that shouldn't be used in
 167 any modern applications.
 168 .Pp
 169 The
 170 .Fn teken_256to16
 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
 173 similar).
 174 The lower 3 bits of the result are the ANSI color and the next lowest
 175 bit is brightness.
 176 Other layers (hardare and software) that only support 16 colors can use
 177 this to avoid knowing the details of 256-color codes.
 178 .Pp
 179 The
 180 .Fn teken_256to8
 181 function is similar to
 182 .Fn teken_256to16
 183 except it converts to an ANSI 8-color code.
 184 This is more accurate than discarding the brigtness bit in the result of
 185 .Fn teken_256to16 .
 186 .Pp
 187 The
 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.
 191 .Pp
 192 The
 193 .Fn teken_set_8bit
 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.
 196 .Pp
 197 The
 198 .Fn teken_set_cons25
 199 function sets the terminal emulation to
 200 .Dv cons25 ,
 201 which was the default for
 202 .Xr syscons 4
 203 in versions of
 204 .Fx
 205 prior to 9.0.
 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.
 209 .Pp
 210 The
 211 .Fn teken_set_cons25keys
 212 function tells the
 213 .Fn teken_get_sequence
 214 function to not interpret special keys in
 215 .Dv cons25
 216 mode.
 217 .Sh SEE ALSO
 218 .Xr ncurses 3 ,
 219 .Xr termcap 3 ,
 220 .Xr syscons 4
 221 .Sh HISTORY
 222 The
 223 .Nm
 224 library appeared in
 225 .Fx 8.0 ,
 226 though it was only available and used inside the kernel.
 227 In
 228 .Fx 9.0 ,
 229 the
 230 .Nm
 231 library appeared in userspace.
 232 .Sh AUTHORS
 233 .An Ed Schouten Aq ed@FreeBSD.org
 234 .Sh SECURITY CONSIDERATIONS
 235 The
 236 .Fn tf_respond
 237 callback is used to respond to device status requests commands generated
 238 by an application.
 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
 242 .Xr sh 1 .
 243 .Pp
 244 .Nm
 245 only implements a small subset of responses which are unlikely to cause
 246 any harm.
 247 Still, it is advised to leave
 248 .Fn tf_respond
 249 unimplemented.