X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fterm.5;h=19af62a350ed48c68b3f45fcee6c9e38f88b353d;hp=e999b2e8c5142e5edf1138d8b2b5c64c0f3edbdb;hb=ce7b402c144d2b6d3773ef5b42aad9daf1ad76fe;hpb=55ccd2b959766810cf7db8d1c4462f338ce0afc8 diff --git a/man/term.5 b/man/term.5 index e999b2e8..19af62a3 100644 --- a/man/term.5 +++ b/man/term.5 @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2003,2004 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2004,2006 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * @@ -26,8 +26,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: term.5,v 1.16 2004/07/05 13:16:08 tom Exp $ -.TH TERM 5 +.\" $Id: term.5,v 1.19 2006/12/24 18:12:38 tom Exp $ +.TH term 5 .ds n 5 .ds d @TERMINFO@ .SH NAME @@ -35,11 +35,13 @@ term \- format of compiled term file. .SH SYNOPSIS .B term .SH DESCRIPTION -.PP +.SS STORAGE LOCATION Compiled terminfo descriptions are placed under the directory \fB\*d\fP. -In order to avoid a linear search of a huge \s-1UNIX\s+1 system directory, a -two-level scheme is used: \fB\*d/c/name\fP -where +Two configurations are supported (when building the ncurses libraries): +.TP 5 +.B directory tree +A two-level scheme is used to avoid a linear search +of a huge \s-1UNIX\s+1 system directory: \fB\*d/c/name\fP where .I name is the name of the terminal, and .I c @@ -50,13 +52,29 @@ Thus, can be found in the file \fB\*d/a/act4\fP. Synonyms for the same terminal are implemented by multiple links to the same compiled file. -.PP +.TP 5 +.B hashed database +Using Berkeley database, two types of records are stored: +the terminfo data in the same format as stored in a directory tree with +the terminfo's primary name as a key, +and records containing only aliases pointing to the primary name. +.IP +If built to write hashed databases, +ncurses can still read terminfo databases organized as a directory tree, +but cannot write entries into the directory tree. +It can write (or rewrite) entries in the hashed database. +.IP +ncurses distinguishes the two cases in the TERMINFO and TERMINFO_DIRS +environment variable by assuming a directory tree for entries that +correspond to an existing directory, +and hashed database otherwise. +.SS STORAGE FORMAT The format has been chosen so that it will be the same on all hardware. An 8 or more bit byte is assumed, but no assumptions about byte ordering or sign extension are made. .PP The compiled file is created with the -.I tic +.B @TIC@ program, and read by the routine .IR setupterm . The file is divided into six parts: @@ -72,12 +90,20 @@ The header section begins the file. This section contains six short integers in the format described below. These integers are +.RS 5 +.TP 5 (1) the magic number (octal 0432); +.TP 5 (2) the size, in bytes, of the names section; +.TP 5 (3) the number of bytes in the boolean section; +.TP 5 (4) the number of short integers in the numbers section; +.TP 5 (5) the number of offsets (short integers) in the strings section; +.TP 5 (6) the size, in bytes, of the string table. +.RE .PP Short integers are stored in two 8-bit bytes. The first byte contains the least significant 8 bits of the value, @@ -128,7 +154,48 @@ The final section is the string table. It contains all the values of string capabilities referenced in the string section. Each string is null terminated. +.SS EXTENDED STORAGE FORMAT +The previous section describes the conventional terminfo binary format. +With some minor variations of the offsets (see PORTABILITY), +the same binary format is used in all modern UNIX systems. +Each system uses a predefined set of boolean, number or string capabilities. +.PP +The ncurses libraries and applications support extended terminfo binary format, +allowing users to define capabilities which are loaded at runtime. This +extension is made possible by using the fact that the other implementations +stop reading the terminfo data when they have reached the end of the size given +in the header. +ncurses checks the size, and if it exceeds that due to the predefined data, +continues to parse according to its own scheme. +.PP +First, it reads the extended header (5 short integers): +.RS 5 +.TP 5 +(1) +count of extended boolean capabilities +.TP 5 +(2) +count of extended numeric capabilities +.TP 5 +(3) +count of extended string capabilities +.TP 5 +(4) +size of the extended string table in bytes. +.TP 5 +(5) +last offset of the extended string table in bytes. +.RE .PP +Using the counts and sizes, ncurses allocates arrays and reads data +for the extended capabilties in the same order as the header information. +.PP +The extended string table contains values for string capabilities. +After the end of these values, it contains the names for each of +the extended capabilities in order, e.g., booleans, then numbers and +finally strings. +. +.SH PORTABILITY Note that it is possible for .I setupterm to expect a different set of capabilities @@ -155,7 +222,7 @@ diverged from System V terminfo after SVr1, and have added extension capabilities to the string table that (in the binary format) collide with System V and XSI Curses extensions. See \fBterminfo\fR(\*n) for detailed discussion of terminfo source compatibility issues. -.PP +.SH EXAMPLE As an example, here is a hex dump of the description for the Lear-Siegler ADM-3, a popular though rather stupid early terminal: .nf @@ -193,13 +260,21 @@ adm3a|lsi adm3a, .ft R .fi .sp -.PP +.SH LIMITS Some limitations: total compiled entries cannot exceed 4096 bytes. The name field cannot exceed 128 bytes. .SH FILES \*d/*/* compiled terminal capability data base .SH SEE ALSO \fBcurses\fR(3X), \fBterminfo\fR(\*n). +.SH AUTHORS +Thomas E. Dickey +.br +extended terminfo format for ncurses 5.0 +.br +hashed database support for ncurses 5.6 +.sp +Eric S. Raymond .\"# .\"# The following sets edit modes for GNU EMACS .\"# Local Variables: