-.TH TERM 5
+.\"***************************************************************************
+.\" 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 *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" $Id: term.5,v 1.19 2006/12/24 18:12:38 tom Exp $
+.TH term 5
.ds n 5
-.ds d @DATADIR@/terminfo
+.ds d @TERMINFO@
.SH NAME
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\*b/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
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:
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,
and the second byte contains the most significant 8 bits.
(Thus, the value represented is 256*second+first.)
-The value \-1 is represented by the two bytes 0377, 0377; other negative
-values are illegal. This value generally
+The value -1 is represented by the two bytes 0377, 0377; other negative
+values are illegal. This value generally
means that the corresponding capability is missing from this terminal.
Note that this format corresponds to the hardware of the \s-1VAX\s+1
and \s-1PDP\s+1-11 (that is, little-endian machines).
The numbers section is similar to the flags section.
Each capability takes up two bytes,
and is stored as a little-endian short integer.
-If the value represented is \-1, the capability is taken to be missing.
+If the value represented is -1, the capability is taken to be missing.
.PP
The strings section is also similar.
Each capability is stored as a short integer, in the format above.
-A value of \-1 means the capability is missing.
+A value of -1 means the capability is missing.
Otherwise, the value is taken as an offset from the beginning
of the string table.
Special characters in ^X or \ec notation are stored in their
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
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
.sp
-adm3a|lsi adm3a,
- am,
- cols#80, lines#24,
- bel=^G, clear=\032$<1>, cr=^M, cub1=^H, cud1=^J,
- cuf1=^L, cup=\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
- home=^^, ind=^J,
+adm3a|lsi adm3a,
+ am,
+ cols#80, lines#24,
+ bel=^G, clear=\032$<1>, cr=^M, cub1=^H, cud1=^J,
+ cuf1=^L, cup=\\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
+ home=^^, ind=^J,
.sp
.ft CW
\s-20000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3
.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"
-curses(3X), terminfo(\*n).
+.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:
projects / ncurses.git / blobdiff