+ tic(1) compiles a terminfo terminal type description, and setupterm(3x)
+ reads it. A compiled description may be stored in a file or in a
+ database of, potentially, many such descriptions. Further, a compiled
+ description may be in one of two formats: one similar to that used by
+ System V, and a newer, extensible format employed exclusively by
+ ncurses.
-
-
DESCRIPTION
- STORAGELOCATION
- Compiled terminfo descriptions are placed under the direc-
- tory /usr/share/terminfo. Two configurations are sup-
- ported (when building the ncurses libraries):
+
+ Compiled terminfodescriptionsareplaced under the directory
+ /usr/share/terminfo. One of two configurations is selected when
+ building the ncurses libraries.
directorytree
- A two-level scheme is used to avoid a linear search
- of a huge UNIX system directory: /usr/share/ter-
- minfo/c/name where name is the name of the terminal,
- and c is the first character of name. Thus, act4 can
- be found in the file /usr/share/terminfo/a/act4.
- Synonyms for the same terminal are implemented by
- multiple links to the same compiled file.
+ A two-level scheme is used to avoid a linear search of a huge Unix
+ system directory: /usr/share/terminfo/c/name where name is the
+ name of the terminal, and c is the first character of name. Thus,
+ the compiled description of terminal type "act4" is found in the
+ file /usr/share/terminfo/a/act4. Synonyms for the same terminal
+ are implemented by multiple links to the same compiled file.
hasheddatabase
- 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 pri-
- mary name as a key, and records containing only
- aliases pointing to the primary name.
-
- 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.
-
- 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.
-
- STORAGEFORMAT
- 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.
-
- The compiled file is created with the tic program, and
- read by the routine setupterm. The file is divided into
- six parts: the header, terminal names, boolean flags, num-
- bers, strings, and string table.
-
- The header section begins the file. This section contains
- six short integers in the format described below. These
- integers are
-
- (1) the magic number (octal 0432);
-
- (2) the size, in bytes, of the names section;
-
- (3) the number of bytes in the boolean section;
-
- (4) the number of short integers in the numbers sec-
- tion;
-
- (5) the number of offsets (short integers) in the
- strings section;
-
- (6) the size, in bytes, of the string table.
-
- 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 means
- that the corresponding capability is missing from this
- terminal. Note that this format corresponds to the hard-
- ware of the VAX and PDP-11 (that is, little-endian
- machines). Machines where this does not correspond to the
- hardware must read the integers as two bytes and compute
- the little-endian value.
-
- The terminal names section comes next. It contains the
- first line of the terminfo description, listing the vari-
- ous names for the terminal, separated by the `|' charac-
- ter. The section is terminated with an ASCII NUL charac-
- ter.
-
- The boolean flags have one byte for each flag. This byte
- is either 0 or 1 as the flag is present or absent. 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
- 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.
-
- 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.
-
- 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. Otherwise, the
- value is taken as an offset from the beginning of the
- string table. Special characters in ^X or \c notation are
- stored in their interpreted form, not the printing repre-
- sentation. Padding information $<nn> and parameter infor-
- mation %x are stored intact in uninterpreted form.
-
- 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.
-
- EXTENDEDSTORAGEFORMAT
- 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.
-
- The ncurses libraries and applications support extended
- terminfo binary format, allowing users to define capabili-
- ties 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.
+ Using the Berkeley database API, two types of records are stored:
+ the terminfo data in the same format as that stored in a directory
+ tree with the terminal's primary type name as a key, and records
+ containing only aliases pointing to the primary name.
+
+ If built to write hashed databases, ncurses can still read term-
+ info databases organized as a directory tree, but cannot write
+ entries into the directory tree. It can write (or rewrite)
+ entries in the hashed database.
+
+ 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 a hashed
+ database otherwise.
+
+
+
+ The format has been chosen so that it will be the same on all hardware.
+ A byte of at least eight bits' width is assumed, but no assumptions
+ about bit ordering or sign extension are made.
+
+ The file is divided into six parts:
+
+ (a) header,
+
+ (b) terminalnames,
+
+ (c) Booleanflags,
+
+ (d) numbers,
+
+ (e) strings, and
+
+ (f) a stringtable.
+
+ The header section begins the file. This section contains six short
+ integers in the format described below. These integers are
+
+ (1) the magicnumber
+ (octal 0432);
+
+ (2) the size,
+ in bytes, of the terminalnames section;
+
+ (3) the number of bytes in the Booleanflags section;
+
+ (4) the number of short integers in the numbers section;
+
+ (5) the number of offsets
+ (short integers) in the strings section;
+
+ (6) the size,
+ in bytes, of the stringtable.
+
+ The capabilities in the Booleanflags, numbers, and strings sections
+ are in the same order as in the header file term.h.
+
+ Short integers are signed, in the range -32768 to 32767, and stored in
+ little-endian format.
+
+ Numbers in a terminal description, whether they are entries in the
+ numbers or strings table, are positive integers. Boolean flags are
+ treated as positive one-byte integers. In each case, those positive
+ integers represent a terminal capability. The terminal compiler tic
+ uses negative integers to handle the cases where a capability is not
+ available:
+
+ o If a capability is absent from this terminal, tic stores a -1 in
+ the corresponding table.
+
+ The integer value -1 is represented by two bytes 0377, 0377.
+ Absent Boolean values are represented by the byte 0 (false).
+
+ o If a capability has been canceled from this terminal, tic stores a
+ -2 in the corresponding table.
+
+ The integer value -2 is represented by two bytes 0377, 0376.
+ The Boolean value -2 is represented by the byte 0376.
+
+ o Other negative values are illegal.
+
+ The terminalnames section comes after the header. It contains the
+ first line of the terminfo description, listing the various names for
+ the terminal, separated by the "|" character. The terminalnames
+ section is terminated with an ASCII NUL character.
+
+ The Booleanflags section has one byte for each flag. Boolean
+ capabilities are either 1 or 0 (true or false) according to whether the
+ terminal supports the given capability or not.
+
+ Between the Booleanflags 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 designed to avoid traps induced by addressing
+ a word on an odd byte boundary. All short integers are aligned on a
+ short word boundary.
+
+ The numbers section is similar to the Booleanflags section. Each
+ capability takes up two bytes, and is stored as a little-endian short
+ integer.
+
+ The strings section is also similar. Each capability is stored as a
+ short integer. The capability value is an index into the stringtable.
+
+ The stringtable is the last section. It contains all of the values of
+ string capabilities referenced in the strings section. Each string is
+ null-terminated. Special characters in ^X or \c notation are stored in
+ their interpreted form, not the printing representation. Padding
+ information $<nn> and parameter information %x are stored intact in
+ uninterpreted form.
+
+
+
+ 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.
+
+ The ncurses libraries and applications support extended terminfo binary
+ format, allowing users to define capabilities that are loaded at
+ runtime. This extension is made possible by using the fact that the
+ other implementations stop reading the terminfo data when they reach
+ 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.
First, it reads the extended header (5 short integers):
- (1) count of extended boolean capabilities
+ (1) count of extended Boolean capabilities
(2) count of extended numeric capabilities
(3) count of extended string capabilities
- (4) size of the extended string table in bytes.
+ (4) count of the items in extended string table
- (5) last offset of the extended string table in
- bytes.
+ (5) size of the extended string table in bytes
- Using the counts and sizes, ncurses allocates arrays and
- reads data for the extended capabilties in the same order
- as the header information.
+ The count- and size-values for the extended string table include the
+ extended capability names as well as extended capability values.
- The extended string table contains values for string capa-
- bilities. 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.
+ Using the counts and sizes, ncurses allocates arrays and reads data for
+ the extended capabilities in the same order as the header information.
+ 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: Boolean, numeric, and string.
-
-
PORTABILITY
- Note that it is possible for setupterm to expect a differ-
- ent set of capabilities than are actually present in the
- file. Either the database may have been updated since
- setupterm has been recompiled (resulting in extra unrecog-
- nized entries in the file) or the program may have been
- recompiled more recently than the database was updated
- (resulting in missing entries). The routine setupterm
- must be prepared for both possibilities - this is why the
- numbers and sizes are included. Also, new capabilities
- must always be added at the end of the lists 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 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 terminfo(5) for detailed discus-
- sion of terminfo source compatibility issues.
+ By storing terminal descriptions in this way, ncurses is able to
+ provide a database useful with legacy applications, as well as
+ providing data for applications that require more information about a
+ terminal type than was anticipated by X/Open Curses. See user_caps(5)
+ for an overview of the way ncurses uses this extended information.
+ Applications that manipulate terminal data can use the definitions
+ described in term_variables(3x) associating the long capability names
+ with members of a TERMTYPE structure.
-
-
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:
+
+
+ On occasion, 16-bit signed integers are not large enough. ncurses 6.1
+ introduced a new format by making a few changes to the legacy format:
+
+ o a different magic number (octal 01036)
+
+ o changing the type for the number array from signed 16-bit integers
+ to signed 32-bit integers.
+
+ To maintain compatibility, the library presents the same data
+ structures to direct users of the TERMTYPE structure as in previous
+ formats. However, that cannot provide callers with the extended
+ numbers. The library uses a similar but hidden data structure
+ TERMTYPE2 to provide data for the terminfo functions.
+
+
+
+ Note that it is possible for setupterm to expect a different set of
+ capabilities than are actually present in the file. Either the
+ database may have been updated since setupterm was recompiled
+ (resulting in extra unrecognized entries in the file) or the program
+ may have been recompiled more recently than the database was updated
+ (resulting in missing entries). The routine setupterm must be prepared
+ for both possibilities - this is why the numbers and sizes are
+ included. Also, new capabilities must always be added at the end of
+ the lists of Boolean, number, and string capabilities.
+
+
+
+ X/Open Curses does not specify a format for the terminfo database.
+ System V curses used a directory-tree of binary files, one per terminal
+ description.
+
+ Despite the consistent use of little-endian 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) each of which diverged from System V terminfo after
+ SVr1, and added extension capabilities to the string table that (in the
+ binary format) collide with System V and X/Open Curses extensions. See
+ terminfo(5) for detailed discussion of terminfo source compatibility
+ issues.
+
+ This implementation is by default compatible with the binary terminfo
+ format used by Solaris curses, except in a few less-used details where
+ it was found that the latter did not match X/Open Curses. The format
+ used by the other Unix versions can be matched by building ncurses with
+ different configuration options.
+
+
+
+ The magic number in a binary terminfo file is the first 16 bits (two
+ bytes). Besides making it more reliable for the library to check that
+ a file is terminfo, utilities such as file(1) also use that to tell
+ what the file-format is. System V defined more than one magic number,
+ with 0433, 0435 as screen-dumps (see scr_dump(5)). This implementation
+ uses 01036 as a continuation of that sequence, but with a different
+ high-order byte to avoid confusion.
+
+ TheTERMTYPEStructure
+ Direct access to the TERMTYPE structure is provided for legacy
+ applications. Portable applications should use tigetflag(3x) and
+ related functions to read terminal capabilities.
+
+
+
+ A small number of terminal descriptions use uppercase characters in
+ their names. If the underlying file system ignores the difference
+ between uppercase and lowercase, ncurses represents the "first
+ character" of the terminal name used as the intermediate level of a
+ directory tree in (two-character) hexadecimal form.
+
+
+
+ ncurses stores compiled terminal descriptions in three related formats,
+ described in the subsections
+
+ oLegacyStorageFormat, and
+
+ oExtendedStorageFormat, and
+
+ oExtendedNumberFormat.
+
+ The legacy storage format and the extended number format differ by the
+ types of numeric capability that they can store (for example, 16-
+ versus 32-bit integers). The extended storage format introduced by
+ ncurses 5.0 adds data to either of these formats.
+
+ Some limitations apply:
+
+ o total compiled entries cannot exceed 4096 bytes in the legacy
+ format.
+
+ o total compiled entries cannot exceed 32768 bytes in the extended
+ format.
+
+ o the name field cannot exceed 128 bytes.
+
+ Compiled entries are limited to 32768 bytes because offsets into the
+ stringstable use two-byte integers. The legacy format could have
+ supported 32768-byte entries, but was limited to a virtual memory
+ page's 4096 bytes.
+
+
+
Thomas E. Dickey
- extended terminfo format for ncurses 5.0
- hashed database support for ncurses 5.6
+ extended terminfo format for ncurses 5.0
+ hashed database support for ncurses 5.6
+ extended number support for ncurses 6.1
Eric S. Raymond
+ documented legacy terminfo format (that used by pcurses).
+
+
+