TEKEN(3)

NAME
teken - xterm-like terminal emulation interface

LIBRARY
libteken

SYNOPSIS
#include <teken.h>
void
teken_init(teken_t *t, const teken_funcs_t *funcs, void *thunk);
void
teken_input(teken_t *t, const void *buf, size_t nbytes);
const teken_pos_t *
teken_get_winsize(teken_t *t);
void
teken_set_winsize(teken_t *t, const teken_pos_t *size);
const teken_pos_t *
teken_get_cursor(teken_t *t);
void
teken_set_cursor(teken_t *t, const teken_pos_t *pos);
const teken_attr_t *
teken_get_curattr(teken_t *t);
void
teken_set_curattr(teken_t *t, const teken_attr_t *attr);
const teken_attr_t *
teken_get_defattr(teken_t *t);
void
teken_set_defattr(teken_t *t, const teken_attr_t *attr);
const char *
teken_get_sequence(teken_t *t, unsigned int id);
teken_color_t
teken_256to16(teken_color_t color);
teken_color_t
teken_256to8(teken_color_t color);
void
teken_get_defattr_cons25(teken_t *t, int *fg, int *bg);
void
teken_set_8bit(teken_t *t);
void
teken_set_cons25(teken_t *t);

DESCRIPTION
The teken library implements the input parser of a 256-color xterm-like terminal. It converts a stream of UTF-8 encoded characters into a series of primitive drawing instructions that can be used by a console driver or terminal emulator to render a terminal application.

The teken_init() function is used to initialize terminal state object t, having type teken_t. The supplied teken_funcs_t structure funcs contains a set of callback functions, which are called when supplying data to teken_input(). The thunk argument stores an arbitrary pointer, which is passed to each invocation of the callback functions.

The teken_funcs_t structure stores the following callbacks:

    typedef struct {
    	tf_bell_t     *tf_bell;     /* Audible/visible bell. */
    	tf_cursor_t   *tf_cursor;   /* Move cursor to x/y. */
    	tf_putchar_t  *tf_putchar;  /* Put Unicode character at x/y. */
    	tf_fill_t     *tf_fill;     /* Fill rectangle with character. */
    	tf_copy_t     *tf_copy;     /* Copy rectangle to new location. */
    	tf_param_t    *tf_param;    /* Miscellaneous options. */
    	tf_respond_t  *tf_respond;  /* Send response string to user. */
    } teken_funcs_t;

All callbacks must be provided, though unimplemented callbacks may some times be sufficient. The actual types of these callbacks can be found in <teken.h>.

By default, teken_init() initializes the teken_t structure to emulate a terminal having 24 rows and 80 columns. The teken_get_winsize() and teken_set_winsize() functions can be used to obtain and modify the dimensions of the terminal.

Even though the cursor position is normally controlled by input of data through teken_input() and returned by the tf_cursor() callback, it can be obtained and modified manually using the teken_get_cursor() and teken_set_cursor() functions. The same holds for teken_get_curattr() and teken_set_curattr(), which can be used to change the currently selected font attributes and foreground and background color.

By default, teken emulates a white-on-black terminal, which means the default foreground color is white, while the background color is black. These defaults can be modified using teken_get_defattr() and teken_set_defattr().

The teken_get_sequence() function is a utility function that can be used to obtain escape sequences of special keyboard keys, generated by user input. The id parameter must be one of the TKEY_* parameters listed in <teken.h>.

LEGACY FEATURES
This library also provides a set of functions that shouldn't be used in any modern applications.

The teken_256to16() function converts an xterm-256 256-color code to an xterm 16-color code whose color with default palettes is as similar as possible (not very similar). The lower 3 bits of the result are the ANSI color and the next lowest bit is brightness. Other layers (hardare and software) that only support 16 colors can use this to avoid knowing the details of 256-color codes.

The teken_256to8() function is similar to teken_256to16() except it converts to an ANSI 8-color code. This is more accurate than discarding the brigtness bit in the result of teken_256to16().

The teken_get_defattr_cons25() function obtains the default terminal attributes as a pair of foreground and background colors, using ANSI color numbering.

The teken_set_8bit() function disables UTF-8 processing and switches to 8-bit character mode, which can be used to support character sets like CP437 and ISO-8859-1.

The teken_set_cons25() function switches terminal emulation to cons25, which is used by versions of FreeBSD prior to 9.0.

SEE ALSO
ncurses(3), termcap(3), syscons(4)

HISTORY
The teken library appeared in FreeBSD 8.0, though it was only available and used inside the kernel. In FreeBSD 9.0, the teken library appeared in userspace.

AUTHORS
Ed Schouten <ed@FreeBSD.org>

SECURITY CONSIDERATIONS
The tf_respond() callback is used to respond to device status requests commands generated by an application. In the past, there have been various security issues, where a malicious application sends a device status request before termination, causing the generated response to be interpreted by applications such as sh(1).

teken only implements a small subset of responses which are unlikely to cause any harm. Still, it is advised to leave tf_respond() unimplemented.