| .\"*************************************************************************** |
| .\" Copyright 2018-2020,2021 Thomas E. Dickey * |
| .\" Copyright 1998-2016,2017 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.40 2021/08/15 19:38:47 tom Exp $ |
| .TH term 5 |
| .ie \n(.g .ds `` \(lq |
| .el .ds `` `` |
| .ie \n(.g .ds '' \(rq |
| .el .ds '' '' |
| .de NS |
| .ie n .sp |
| .el .sp .5 |
| .ie n .in +4 |
| .el .in +2 |
| .nf |
| .ft C \" Courier |
| .. |
| .de NE |
| .fi |
| .ft R |
| .ie n .in -4 |
| .el .in -2 |
| .. |
| .de bP |
| .ie n .IP \(bu 4 |
| .el .IP \(bu 2 |
| .. |
| .ds n 5 |
| .ds d @TERMINFO@ |
| .SH NAME |
| term \- format of compiled term file. |
| .SH SYNOPSIS |
| .B term |
| .SH DESCRIPTION |
| .SS STORAGE LOCATION |
| Compiled terminfo descriptions are placed under the directory \fB\*d\fP. |
| Two configurations are supported (when building the \fBncurses\fP 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 |
| is the first character of |
| .IR name . |
| Thus, |
| .I act4 |
| 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. |
| .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, |
| \fBncurses\fP 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 |
| \fBncurses\fP 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 LEGACY 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 \fB@TIC@\fP program, |
| and read by the routine \fBsetupterm\fP(3X). |
| The file is divided into six parts: |
| .RS 5 |
| .TP 3 |
| a) \fIheader\fP, |
| .TP 3 |
| b) \fIterminal names\fP, |
| .TP 3 |
| c) \fIboolean flags\fP, |
| .TP 3 |
| d) \fInumbers\fP, |
| .TP 3 |
| e) \fIstrings\fP, and |
| .TP 3 |
| f) \fIstring table\fP. |
| .RE |
| .PP |
| The \fIheader\fP section begins the file. |
| This section contains six short integers in the format |
| described below. |
| These integers are |
| .RS 5 |
| .TP 5 |
| (1) the \fImagic number\fP (octal 0432); |
| .TP 5 |
| (2) the size, in bytes, of the \fIterminal names\fP section; |
| .TP 5 |
| (3) the number of bytes in the \fIboolean flags\fP section; |
| .TP 5 |
| (4) the number of short integers in the \fInumbers\fP section; |
| .TP 5 |
| (5) the number of offsets (short integers) in the \fIstrings\fP section; |
| .TP 5 |
| (6) the size, in bytes, of the \fIstring table\fP. |
| .RE |
| .PP |
| The capabilities in the |
| \fIboolean flags\fP, |
| \fInumbers\fP, and |
| \fIstrings\fP |
| sections are in the same order as the file <term.h>. |
| .PP |
| Short integers are signed, in the range \-32768 to 32767. |
| They are stored as 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.) |
| This format corresponds to the hardware of the \s-1VAX\s+1 |
| and \s-1PDP\s+1-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. |
| .PP |
| Numbers in a terminal description, |
| whether they are entries in the \fInumbers\fP or \fIstrings\fP 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: |
| .bP |
| If a capability is absent from this terminal, |
| @TIC@ stores a \-1 in the corresponding table. |
| .IP |
| The integer value \-1 is represented by two bytes 0377, 0377. |
| .br |
| Absent boolean values are represented by the byte 0 (false). |
| .bP |
| If a capability has been canceled from this terminal, |
| @TIC@ stores a \-2 in the corresponding table. |
| .IP |
| The integer value \-2 is represented by two bytes 0377, 0376. |
| .br |
| The boolean value \-2 is represented by the byte 0376. |
| .br |
| .bP |
| Other negative values are illegal. |
| .PP |
| The \fIterminal names\fP section comes after the \fIheader\fP. |
| It contains the first line of the terminfo description, |
| listing the various names for the terminal, |
| separated by the \*(``|\*('' character. |
| The \fIterminal names\fP section is terminated |
| with an \s-1ASCII NUL\s+1 character. |
| .PP |
| The \fIboolean flags\fP 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. |
| .PP |
| Between the \fIboolean flags\fP section and the \fInumber\fP section, |
| a null byte will be inserted, if necessary, |
| to ensure that the \fInumber\fP 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. |
| .PP |
| The \fInumbers\fP section is similar to the \fIboolean flags\fP section. |
| Each capability takes up two bytes, |
| and is stored as a little-endian short integer. |
| .PP |
| The \fIstrings\fP section is also similar. |
| Each capability is stored as a short integer. |
| The capability value is an index into the \fIstring table\fP. |
| .PP |
| The \fIstring table\fP is the last section. |
| It contains all of the values of string capabilities referenced in |
| the \fIstrings\fP section. |
| Each string is null-terminated. |
| Special characters in ^X or \ec notation are stored in their |
| interpreted form, not the printing representation. |
| Padding information $<nn> and parameter information %x are |
| stored intact in uninterpreted form. |
| .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 \fBncurses\fP 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. |
| \fBncurses\fP 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) |
| count of the items in extended string table |
| .TP 5 |
| (5) |
| size of the extended string table in bytes |
| .RE |
| .PP |
| The count- and size-values for the extended string table |
| include the extended capability \fInames\fP as well as |
| extended capability \fIvalues\fP. |
| .PP |
| Using the counts and sizes, \fBncurses\fP allocates arrays and reads data |
| for the extended capabilities 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. |
| .PP |
| Applications which manipulate terminal data can use the definitions |
| described in \fBterm_variables\fP(3X) which associate the long capability |
| names with members of a \fBTERMTYPE\fP structure. |
| . |
| .SS EXTENDED NUMBER FORMAT |
| .PP |
| On occasion, 16-bit signed integers are not large enough. |
| With \fBncurses\fP 6.1, a new format was introduced by making a few changes |
| to the legacy format: |
| .bP |
| a different magic number (octal 01036) |
| .bP |
| changing the type for the \fInumber\fP array from signed 16-bit integers |
| to signed 32-bit integers. |
| .PP |
| To maintain compatibility, the library presents the same data structures |
| to direct users of the \fBTERMTYPE\fP structure as in previous formats. |
| However, that cannot provide callers with the extended numbers. |
| The library uses a similar but hidden data structure \fBTERMTYPE2\fP |
| to provide data for the terminfo functions. |
| .SH PORTABILITY |
| .SS setupterm |
| .PP |
| Note that it is possible for |
| .B setupterm |
| to expect a different set of capabilities |
| than are actually present in the file. |
| Either the database may have been updated since |
| .B 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 |
| .B 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. |
| .SS Binary format |
| .PP |
| X/Open Curses does not specify a format for the terminfo database. |
| UNIX System V curses used a directory-tree of binary files, |
| one per terminal description. |
| .PP |
| 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 \fBterminfo\fR(\*n) for detailed |
| discussion of terminfo source compatibility issues. |
| .PP |
| 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. |
| .SS Magic codes |
| .PP |
| 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 \fBfile\fP 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 \fBscr_dump\fP(5)). |
| This implementation uses 01036 as a continuation of that sequence, |
| but with a different high-order byte to avoid confusion. |
| .SS The TERMTYPE structure |
| .PP |
| Direct access to the \fBTERMTYPE\fP structure is provided for legacy |
| applications. |
| Portable applications should use the \fBtigetflag\fP and related functions |
| described in \fBcurs_terminfo\fP(3X) for reading terminal capabilities. |
| .SS Mixed-case terminal names |
| .PP |
| A small number of terminal descriptions use uppercase characters in |
| their names. |
| If the underlying filesystem ignores the difference between |
| uppercase and lowercase, |
| \fBncurses\fP represents the \*(``first character\*('' |
| of the terminal name used as |
| the intermediate level of a directory tree in (two-character) hexadecimal form. |
| .SH EXAMPLE |
| As an example, here is a description for the Lear-Siegler |
| ADM\-3, a popular though rather stupid early terminal: |
| .NS |
| 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, |
| .NS |
| .PP |
| and a hexadecimal dump of the compiled terminal description: |
| .NS |
| .ft CW |
| \s-20000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3 |
| 0010 61 7c 6c 73 69 20 61 64 6d 33 61 00 00 01 50 00 a|lsi ad m3a...P. |
| 0020 ff ff 18 00 ff ff 00 00 02 00 ff ff ff ff 04 00 ........ ........ |
| 0030 ff ff ff ff ff ff ff ff 0a 00 25 00 27 00 ff ff ........ ..%.'... |
| 0040 29 00 ff ff ff ff 2b 00 ff ff 2d 00 ff ff ff ff ).....+. ..-..... |
| 0050 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 0060 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 0070 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 0080 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 0090 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 00a0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 00b0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 00c0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 00d0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 00e0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 00f0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 0100 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 0110 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ |
| 0120 ff ff ff ff ff ff 2f 00 07 00 0d 00 1a 24 3c 31 ....../. .....$<1 |
| 0130 3e 00 1b 3d 25 70 31 25 7b 33 32 7d 25 2b 25 63 >..=%p1% {32}%+%c |
| 0140 25 70 32 25 7b 33 32 7d 25 2b 25 63 00 0a 00 1e %p2%{32} %+%c.... |
| 0150 00 08 00 0c 00 0b 00 0a 00 ........ .\s+2 |
| .ft R |
| .NE |
| .sp |
| .SH LIMITS |
| Some limitations: |
| .bP |
| total compiled entries cannot exceed 4096 bytes in the legacy format. |
| .bP |
| total compiled entries cannot exceed 32768 bytes in the extended format. |
| .bP |
| the name field cannot exceed 128 bytes. |
| .PP |
| Compiled entries are limited to 32768 bytes because offsets into the |
| \fIstrings table\fP use two-byte integers. |
| The legacy format could have supported 32768-byte entries, |
| but was limited a virtual memory page's 4096 bytes. |
| .SH FILES |
| \*d/*/* compiled terminal capability database |
| .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 |
| .br |
| extended number support for ncurses 6.1 |
| .sp |
| Eric S. Raymond |
| .br |
| documented legacy terminfo format, e.g., from pcurses. |