1term(5)                       File Formats Manual                      term(5)
2
3
4

NAME

6       term - format of compiled term file.
7

SYNOPSIS

9       term
10

DESCRIPTION

12   STORAGE LOCATION
13       Compiled   terminfo   descriptions   are  placed  under  the  directory
14       /usr/share/terminfo.  Two configurations are supported  (when  building
15       the ncurses libraries):
16
17       directory tree
18            A two-level scheme is used to avoid a linear search of a huge UNIX
19            system directory: /usr/share/terminfo/c/name  where  name  is  the
20            name of the terminal, and c is the first character of name.  Thus,
21            act4 can be found in the  file  /usr/share/terminfo/a/act4.   Syn‐
22            onyms  for  the same terminal are implemented by multiple links to
23            the same compiled file.
24
25       hashed database
26            Using Berkeley database, two types of records are stored: the ter‐
27            minfo  data  in the same format as stored in a directory tree with
28            the terminfo's primary name as a key, and records containing  only
29            aliases pointing to the primary name.
30
31            If  built  to  write hashed databases, ncurses can still read ter‐
32            minfo databases organized as a directory tree,  but  cannot  write
33            entries  into  the  directory tree.  It can write (or rewrite) en‐
34            tries in the hashed database.
35
36            ncurses distinguishes the two  cases  in  the  TERMINFO  and  TER‐
37            MINFO_DIRS  environment  variable by assuming a directory tree for
38            entries that correspond to an existing directory, and hashed data‐
39            base otherwise.
40
41   LEGACY STORAGE FORMAT
42       The format has been chosen so that it will be the same on all hardware.
43       An 8 or more bit byte is assumed, but no assumptions about byte  order‐
44       ing or sign extension are made.
45
46       The compiled file is created with the tic program, and read by the rou‐
47       tine setupterm(3X).  The file is divided into six parts:
48
49            a) header,
50
51            b) terminal names,
52
53            c) boolean flags,
54
55            d) numbers,
56
57            e) strings, and
58
59            f) string table.
60
61       The header section begins the file.  This section  contains  six  short
62       integers in the format described below.  These integers are
63
64            (1) the magic number (octal 0432);
65
66            (2) the size, in bytes, of the terminal names section;
67
68            (3) the number of bytes in the boolean flags section;
69
70            (4) the number of short integers in the numbers section;
71
72            (5) the number of offsets (short integers) in the strings section;
73
74            (6) the size, in bytes, of the string table.
75
76       The  capabilities  in  the boolean flags, numbers, and strings sections
77       are in the same order as the file <term.h>.
78
79       Short integers are signed, in the range  -32768  to  32767.   They  are
80       stored  as two 8-bit bytes.  The first byte contains the least signifi‐
81       cant 8 bits of the value, and the second byte contains the most signif‐
82       icant 8 bits.  (Thus, the value represented is 256*second+first.)  This
83       format corresponds to the hardware of the VAX and PDP-11 (that is, lit‐
84       tle-endian  machines).   Machines where this does not correspond to the
85       hardware must read the integers as two bytes and compute the little-en‐
86       dian value.
87
88       Numbers in a terminal description, whether they are entries in the num‐
89       bers or strings  table,  are  positive  integers.   Boolean  flags  are
90       treated  as  positive  one-byte integers.  In each case, those positive
91       integers represent a terminal capability.  The  terminal  compiler  tic
92       uses  negative  integers  to handle the cases where a capability is not
93       available:
94
95       •   If a capability is absent from this terminal, tic stores  a  -1  in
96           the corresponding table.
97
98           The integer value -1 is represented by two bytes 0377, 0377.
99           Absent boolean values are represented by the byte 0 (false).
100
101       •   If  a capability has been canceled from this terminal, tic stores a
102           -2 in the corresponding table.
103
104           The integer value -2 is represented by two bytes 0377, 0376.
105           The boolean value -2 is represented by the byte 0376.
106
107       •   Other negative values are illegal.
108
109       The terminal names section comes after the  header.   It  contains  the
110       first  line  of the terminfo description, listing the various names for
111       the terminal, separated by the “|” character.  The terminal names  sec‐
112       tion is terminated with an ASCII NUL character.
113
114       The boolean flags section has one byte for each flag.  Boolean capabil‐
115       ities are either 1 or 0 (true or false) according to whether the termi‐
116       nal supports the given capability or not.
117
118       Between  the  boolean flags section and the number section, a null byte
119       will be inserted, if necessary, to ensure that the number  section  be‐
120       gins on an even byte This is a relic of the PDP-11's word-addressed ar‐
121       chitecture, originally designed to avoid traps induced by addressing  a
122       word  on  an  odd  byte  boundary.  All short integers are aligned on a
123       short word boundary.
124
125       The numbers section is similar to the boolean flags section.  Each  ca‐
126       pability takes up two bytes, and is stored as a little-endian short in‐
127       teger.
128
129       The strings section is also similar.  Each capability is  stored  as  a
130       short integer.  The capability value is an index into the string table.
131
132       The string table is the last section.  It contains all of the values of
133       string capabilities referenced in the strings section.  Each string  is
134       null-terminated.  Special characters in ^X or \c notation are stored in
135       their interpreted form, not the printing representation.   Padding  in‐
136       formation $<nn> and parameter information %x are stored intact in unin‐
137       terpreted form.
138
139   EXTENDED STORAGE FORMAT
140       The previous section describes the conventional terminfo binary format.
141       With  some  minor variations of the offsets (see PORTABILITY), the same
142       binary format is used in all modern UNIX systems.  Each system  uses  a
143       predefined set of boolean, number or string capabilities.
144
145       The ncurses libraries and applications support extended terminfo binary
146       format, allowing users to define capabilities which are loaded at  run‐
147       time.  This extension is made possible by using the fact that the other
148       implementations stop reading the terminfo data when they  have  reached
149       the  end of the size given in the header.  ncurses checks the size, and
150       if it exceeds that due to the predefined data, continues to  parse  ac‐
151       cording to its own scheme.
152
153       First, it reads the extended header (5 short integers):
154
155            (1)  count of extended boolean capabilities
156
157            (2)  count of extended numeric capabilities
158
159            (3)  count of extended string capabilities
160
161            (4)  count of the items in extended string table
162
163            (5)  size of the extended string table in bytes
164
165       The  count-  and  size-values for the extended string table include the
166       extended capability names as well as extended capability values.
167
168       Using the counts and sizes, ncurses allocates arrays and reads data for
169       the extended capabilities in the same order as the header information.
170
171       The extended string table contains values for string capabilities.  Af‐
172       ter the end of these values, it contains the names for each of the  ex‐
173       tended  capabilities in order, e.g., booleans, then numbers and finally
174       strings.
175
176       Applications which manipulate terminal data can use the definitions de‐
177       scribed in term_variables(3X) which associate the long capability names
178       with members of a TERMTYPE structure.
179
180   EXTENDED NUMBER FORMAT
181       On occasion, 16-bit signed integers are not large enough.  With ncurses
182       6.1,  a new format was introduced by making a few changes to the legacy
183       format:
184
185       •   a different magic number (octal 01036)
186
187       •   changing the type for the number array from signed 16-bit  integers
188           to signed 32-bit integers.
189
190       To  maintain  compatibility,  the library presents the same data struc‐
191       tures to direct users of the TERMTYPE structure as in previous formats.
192       However,  that  cannot  provide callers with the extended numbers.  The
193       library uses a similar but hidden data structure TERMTYPE2  to  provide
194       data for the terminfo functions.
195

PORTABILITY

197   setupterm
198       Note that it is possible for setupterm to expect a different set of ca‐
199       pabilities than are actually present in the file.  Either the  database
200       may  have been updated since setupterm was recompiled (resulting in ex‐
201       tra unrecognized entries in the file) or the program may have been  re‐
202       compiled  more  recently  than  the  database was updated (resulting in
203       missing entries).  The routine setupterm must be prepared for both pos‐
204       sibilities - this is why the numbers and sizes are included.  Also, new
205       capabilities must always be added at the end of the lists  of  boolean,
206       number, and string capabilities.
207
208   Binary format
209       X/Open  Curses  does  not  specify  a format for the terminfo database.
210       UNIX System V curses used a directory-tree of  binary  files,  one  per
211       terminal description.
212
213       Despite  the consistent use of little-endian for numbers and the other‐
214       wise self-describing format, it is not wise to count on portability  of
215       binary  terminfo entries between commercial UNIX versions.  The problem
216       is that there are at least three versions  of  terminfo  (under  HP-UX,
217       AIX,  and  OSF/1) which diverged from System V terminfo after SVr1, and
218       have added extension capabilities to the string table that (in the  bi‐
219       nary format) collide with System V and XSI Curses extensions.  See ter‐
220       minfo(5) for detailed discussion of terminfo source  compatibility  is‐
221       sues.
222
223       This  implementation  is by default compatible with the binary terminfo
224       format used by Solaris curses, except in a few less-used details  where
225       it  was  found that the latter did not match X/Open Curses.  The format
226       used by the other Unix versions can be matched by building ncurses with
227       different configuration options.
228
229   Magic codes
230       The  magic  number  in a binary terminfo file is the first 16-bits (two
231       bytes).  Besides making it more reliable for the library to check  that
232       a  file  is  terminfo,  utilities such as file(1) also use that to tell
233       what the file-format is.  System V defined more than one magic  number,
234       with 0433, 0435 as screen-dumps (see scr_dump(5)).  This implementation
235       uses 01036 as a continuation of that sequence,  but  with  a  different
236       high-order byte to avoid confusion.
237
238   The TERMTYPE structure
239       Direct access to the TERMTYPE structure is provided for legacy applica‐
240       tions.  Portable applications should  use  the  tigetflag  and  related
241       functions described in curs_terminfo(3X) for reading terminal capabili‐
242       ties.
243
244   Mixed-case terminal names
245       A small number of terminal descriptions  use  uppercase  characters  in
246       their  names.   If the underlying filesystem ignores the difference be‐
247       tween uppercase and lowercase, ncurses represents the “first character”
248       of the terminal name used as the intermediate level of a directory tree
249       in (two-character) hexadecimal form.
250

EXAMPLE

252       As an example, here is a description for the Lear-Siegler ADM-3, a pop‐
253       ular though rather stupid early terminal:
254
255           adm3a|lsi adm3a,
256                   am,
257                   cols#80, lines#24,
258                   bel=^G, clear= 32$<1>, cr=^M, cub1=^H, cud1=^J,
259                   cuf1=^L, cup=\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
260                   home=^^, ind=^J,
261
262
263       and a hexadecimal dump of the compiled terminal description:
264
265           0000  1a 01 10 00 02 00 03 00  82 00 31 00 61 64 6d 33  ........ ..1.adm3
266           0010  61 7c 6c 73 69 20 61 64  6d 33 61 00 00 01 50 00  a|lsi ad m3a...P.
267           0020  ff ff 18 00 ff ff 00 00  02 00 ff ff ff ff 04 00  ........ ........
268           0030  ff ff ff ff ff ff ff ff  0a 00 25 00 27 00 ff ff  ........ ..%.'...
269           0040  29 00 ff ff ff ff 2b 00  ff ff 2d 00 ff ff ff ff  ).....+. ..-.....
270           0050  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
271           0060  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
272           0070  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
273           0080  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
274           0090  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
275           00a0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
276           00b0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
277           00c0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
278           00d0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
279           00e0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
280           00f0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
281           0100  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
282           0110  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
283           0120  ff ff ff ff ff ff 2f 00  07 00 0d 00 1a 24 3c 31  ....../. .....$<1
284           0130  3e 00 1b 3d 25 70 31 25  7b 33 32 7d 25 2b 25 63  >..=%p1% {32}%+%c
285           0140  25 70 32 25 7b 33 32 7d  25 2b 25 63 00 0a 00 1e  %p2%{32} %+%c....
286           0150  00 08 00 0c 00 0b 00 0a  00                       ........ .
287
288

LIMITS

290       Some limitations:
291
292       •   total  compiled entries cannot exceed 4096 bytes in the legacy for‐
293           mat.
294
295       •   total compiled entries cannot exceed 32768 bytes  in  the  extended
296           format.
297
298       •   the name field cannot exceed 128 bytes.
299
300       Compiled  entries  are  limited to 32768 bytes because offsets into the
301       strings table use two-byte integers.  The legacy format could have sup‐
302       ported 32768-byte entries, but was limited a virtual memory page's 4096
303       bytes.
304

FILES

306       /usr/share/terminfo/*/*  compiled terminal capability database
307

SEE ALSO

309       curses(3X), terminfo(5).
310

AUTHORS

312       Thomas E. Dickey
313       extended terminfo format for ncurses 5.0
314       hashed database support for ncurses 5.6
315       extended number support for ncurses 6.1
316
317       Eric S. Raymond
318       documented legacy terminfo format, e.g., from pcurses.
319
320
321
322                                                                       term(5)
Impressum