ncurses 5.7 - patch 20100918
[ncurses.git] / man / term.5
index 1dcb87dec670dc8029b471444e613f096e4873f2..608f0d0f080f56306a0a3f3a28edfac88730ff15 100644 (file)
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998,2002 Free Software Foundation, Inc.                   *
+.\" Copyright (c) 1998-2006,2010 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.14 2002/08/10 21:59:37 tom Exp $
-.TH TERM 5
+.\" $Id: term.5,v 1.20 2010/07/31 16:13:27 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,19 +90,27 @@ 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,
 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 
+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).
@@ -104,7 +130,7 @@ The capabilities are in the same order as the file <term.h>.
 Between the boolean section and the number section,
 a null byte will be inserted, if necessary,
 to ensure that the number section begins on an even byte (this is a
-relic of the PDP-11's word-addressed architecture, originally
+relic of the PDP\-11's word-addressed architecture, originally
 designed in to avoid IOT traps induced by addressing a word on an
 odd byte boundary).
 All short integers are aligned on a short word boundary.
@@ -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
@@ -150,22 +217,22 @@ of boolean, number, and string capabilities.
 Despite the consistent use of little-endian for numbers and the otherwise
 self-describing format, it is not wise to count on portability of binary
 terminfo entries between commercial UNIX versions.  The problem is that there
-are at least three versions of terminfo (under HP-UX, AIX, and OSF/1) which
+are at least three versions of terminfo (under HP\-UX, AIX, and OSF/1) which
 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:
+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
@@ -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: