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