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