diff options
author | ed <ed@FreeBSD.org> | 2011-05-09 16:27:39 +0000 |
---|---|---|
committer | ed <ed@FreeBSD.org> | 2011-05-09 16:27:39 +0000 |
commit | a42bf7d6cd085fcc310938672242fb996a5d8859 (patch) | |
tree | 982b102e875149ab6f283138dde03e668b420bf0 /sys/teken/libteken/teken.3 | |
parent | 123df40267b7a490c45762b08babb5d166a7f6f9 (diff) | |
download | FreeBSD-src-a42bf7d6cd085fcc310938672242fb996a5d8859.zip FreeBSD-src-a42bf7d6cd085fcc310938672242fb996a5d8859.tar.gz |
Add proper build infrastructure for teken.
I'm not sure whether we should install teken as a library on any stock
FreeBSD installation, but I can imagine people want to tinker around
with it now and then. Create a /sys/teken/libteken, which holds a
Makefile to install a shared library version of the terminal emulator,
complete with a manpage.
Also add Makefiles for the demo/stress applications, to build it against
the shared library.
Diffstat (limited to 'sys/teken/libteken/teken.3')
-rw-r--r-- | sys/teken/libteken/teken.3 | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/sys/teken/libteken/teken.3 b/sys/teken/libteken/teken.3 new file mode 100644 index 0000000..bcc0db0 --- /dev/null +++ b/sys/teken/libteken/teken.3 @@ -0,0 +1,220 @@ +.\" Copyright (c) 2011 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 9, 2011 +.Dt TEKEN 3 +.Os +.Sh NAME +.Nm teken +.Nd xterm-like terminal emulation interface +.Sh LIBRARY +.Lb libteken +.Sh SYNOPSIS +.In teken.h +.Ft void +.Fn teken_init "teken_t *t" "const teken_funcs_t *funcs" "void *thunk" +.Ft void +.Fn teken_input "teken_t *t" "const void *buf" "size_t nbytes" +.Ft const teken_pos_t * +.Fn teken_get_winsize "teken_t *t" +.Ft void +.Fn teken_set_winsize "teken_t *t" "const teken_pos_t *size" +.Ft const teken_pos_t * +.Fn teken_get_cursor "teken_t *t" +.Ft void +.Fn teken_set_cursor "teken_t *t" "const teken_pos_t *pos" +.Ft const teken_attr_t * +.Fn teken_get_curattr "teken_t *t" +.Ft void +.Fn teken_set_curattr "teken_t *t" "const teken_attr_t *attr" +.Ft const teken_attr_t * +.Fn teken_get_defattr "teken_t *t" +.Ft void +.Fn teken_set_defattr "teken_t *t" "const teken_attr_t *attr" +.Ft const char * +.Fn teken_get_sequence "teken_t *t" "unsigned int id" +.Ft teken_color_t +.Fn teken_256to8 "teken_color_t color" +.Ft void +.Fn teken_get_defattr_cons25 "teken_t *t" "int *fg" "int *bg" +.Ft void +.Fn teken_set_8bit "teken_t *t" +.Ft void +.Fn teken_set_cons25 "teken_t *t" +.Sh DESCRIPTION +The +.Nm +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. +.Pp +The +.Fn teken_init +function is used to initialize terminal state object +.Fa t , +having type +.Vt teken_t . +The supplied +.Vt teken_funcs_t +structure +.Fa funcs +contains a set of callback functions, which are called when supplying +data to +.Fn teken_input . +The +.Fa thunk +argument stores an arbitrary pointer, which is passed to each invocation +of the callback functions. +.Pp +The +.Vt teken_funcs_t +structure stores the following callbacks: +.Bd -literal -offset indent +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; +.Ed +.Pp +All callbacks must be provided, though unimplemented callbacks may some +times be sufficient. +The actual types of these callbacks can be found in +.In teken.h . +.Pp +By default, +.Fn teken_init +initializes the +.Vt teken_t +structure to emulate a terminal having 24 rows and 80 columns. +The +.Fn teken_get_winsize +and +.Fn teken_set_winsize +functions can be used to obtain and modify the dimensions of the +terminal. +.Pp +Even though the cursor position is normally controlled by input of data +through +.Fn teken_input +and returned by the +.Fn tf_cursor +callback, it can be obtained and modified manually using the +.Fn teken_get_cursor +and +.Fn teken_set_cursor +functions. +The same holds for +.Fn teken_get_curattr +and +.Fn teken_set_curattr , +which can be used to change the currently selected font attributes and +foreground and background color. +.Pp +By default, +.Nm +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 +.Fn teken_get_defattr +and +.Fn teken_set_defattr . +.Pp +The +.Fn 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 +.Fa id +parameter must be one of the +.Dv TKEY_* +parameters listed in +.In teken.h . +.Sh LEGACY FEATURES +This library also provides a set of functions that shouldn't be used in +any modern applications. +.Pp +The +.Fn teken_256to8 +function converts a color code to one of the 8 primary colors, allowing +the terminal to be rendered on graphics hardware that only supports 8 or +16 colors (e.g. VGA). +.Pp +The +.Fn teken_get_defattr_cons25 +function obtains the default terminal attributes as a pair of foreground +and background colors, using ANSI color numbering. +.Pp +The +.Fn 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. +.Pp +The +.Fn teken_set_cons25 +function switches terminal emulation to +.Dv cons25 , +which is used by versions of +.Fx +prior to 9.0. +.Sh SECURITY CONSIDERATIONS +The +.Fn 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 +.Xr sh 1 . +.Pp +.Nm +only implements a small subset of responses which are unlikely to cause +any harm. +Still, it is advised to leave +.Fn tf_respond +unimplemented. +.Sh SEE ALSO +.Xr ncurses 3 , +.Xr termcap 3 , +.Xr syscons 4 . +.Sh HISTORY +The +.Nm +library appeared in +.Fx 8.0 , +though it was only available and used inside the kernel. +In +.Fx 9.0 , +the +.Nm +library appeared in userspace. +.Sh AUTHORS +.An Ed Schouten Aq ed@FreeBSD.org |