1<!-- 2 * t 3 **************************************************************************** 4 * Copyright 2018-2023,2024 Thomas E. Dickey * 5 * Copyright 1998-2016,2017 Free Software Foundation, Inc. * 6 * * 7 * Permission is hereby granted, free of charge, to any person obtaining a * 8 * copy of this software and associated documentation files (the * 9 * "Software"), to deal in the Software without restriction, including * 10 * without limitation the rights to use, copy, modify, merge, publish, * 11 * distribute, distribute with modifications, sublicense, and/or sell * 12 * copies of the Software, and to permit persons to whom the Software is * 13 * furnished to do so, subject to the following conditions: * 14 * * 15 * The above copyright notice and this permission notice shall be included * 16 * in all copies or substantial portions of the Software. * 17 * * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * 19 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * 20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * 21 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * 22 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * 23 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * 24 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * 25 * * 26 * Except as contained in this notice, the name(s) of the above copyright * 27 * holders shall not be used in advertising or otherwise to promote the * 28 * sale, use or other dealings in this Software without prior written * 29 * authorization. * 30 **************************************************************************** 31 * @Id: term.5,v 1.77 2024/04/20 21:24:19 tom Exp @ 32--> 33<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> 34<HTML> 35<HEAD> 36<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> 37<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> 38<TITLE>term 5 2024-04-20 ncurses 6.5 File formats</TITLE> 39<link rel="author" href="mailto:bug-ncurses@gnu.org"> 40 41</HEAD> 42<BODY> 43<H1 class="no-header">term 5 2024-04-20 ncurses 6.5 File formats</H1> 44<PRE> 45<STRONG><A HREF="term.5.html">term(5)</A></STRONG> File formats <STRONG><A HREF="term.5.html">term(5)</A></STRONG> 46 47 48 49 50</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> 51 term - compiled <EM>terminfo</EM> terminal description 52 53 54</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> 55 <STRONG>term</STRONG> 56 57 58</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> 59 60</PRE><H3><a name="h3-Storage-Location">Storage Location</a></H3><PRE> 61 Compiled terminfo descriptions are placed under the directory 62 <STRONG>/usr/share/terminfo</STRONG>. Two configurations are supported (when building 63 the <EM>ncurses</EM> libraries): 64 65 <STRONG>directory</STRONG> <STRONG>tree</STRONG> 66 A two-level scheme is used to avoid a linear search of a huge Unix 67 system directory: <STRONG>/usr/share/terminfo/c/name</STRONG> where <EM>name</EM> is the 68 name of the terminal, and <EM>c</EM> is the first character of <EM>name</EM>. Thus, 69 <EM>act4</EM> can be found in the file <STRONG>/usr/share/terminfo/a/act4</STRONG>. 70 Synonyms for the same terminal are implemented by multiple links 71 to the same compiled file. 72 73 <STRONG>hashed</STRONG> <STRONG>database</STRONG> 74 Using Berkeley database, two types of records are stored: the 75 terminfo data in the same format as stored in a directory tree 76 with the terminfo's primary name as a key, and records containing 77 only aliases pointing to the primary name. 78 79 If built to write hashed databases, <EM>ncurses</EM> can still read 80 terminfo databases organized as a directory tree, but cannot write 81 entries into the directory tree. It can write (or rewrite) 82 entries in the hashed database. 83 84 <EM>ncurses</EM> distinguishes the two cases in the <EM>TERMINFO</EM> and 85 <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variable by assuming a directory tree 86 for entries that correspond to an existing directory, and hashed 87 database otherwise. 88 89 90</PRE><H3><a name="h3-Legacy-Storage-Format">Legacy Storage Format</a></H3><PRE> 91 The format has been chosen so that it will be the same on all hardware. 92 An 8 or more bit byte is assumed, but no assumptions about byte 93 ordering or sign extension are made. 94 95 The compiled file is created with the <STRONG>tic</STRONG> program, and read by the 96 routine <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>. The file is divided into six parts: 97 98 a) <EM>header</EM>, 99 100 b) <EM>terminal</EM> <EM>names</EM>, 101 102 c) <EM>Boolean</EM> <EM>flags</EM>, 103 104 d) <EM>numbers</EM>, 105 106 e) <EM>strings</EM>, and 107 108 f) <EM>string</EM> <EM>table</EM>. 109 110 The <EM>header</EM> section begins the file. This section contains six short 111 integers in the format described below. These integers are 112 113 (1) the <EM>magic</EM> <EM>number</EM> (octal 0432); 114 115 (2) the size, in bytes, of the <EM>terminal</EM> <EM>names</EM> section; 116 117 (3) the number of bytes in the <EM>Boolean</EM> <EM>flags</EM> section; 118 119 (4) the number of short integers in the <EM>numbers</EM> section; 120 121 (5) the number of offsets (short integers) in the <EM>strings</EM> section; 122 123 (6) the size, in bytes, of the <EM>string</EM> <EM>table</EM>. 124 125 The capabilities in the <EM>Boolean</EM> <EM>flags</EM>, <EM>numbers</EM>, and <EM>strings</EM> sections 126 are in the same order as the file <term.h>. 127 128 Short integers are signed, in the range -32768 to 32767. They are 129 stored as two 8-bit bytes. The first byte contains the least 130 significant 8 bits of the value, and the second byte contains the most 131 significant 8 bits. (Thus, the value represented is 256*second+first.) 132 This format corresponds to the hardware of the VAX and PDP-11 (that is, 133 little-endian machines). Machines where this does not correspond to 134 the hardware must read the integers as two bytes and compute the 135 little-endian value. 136 137 Numbers in a terminal description, whether they are entries in the 138 <EM>numbers</EM> or <EM>strings</EM> table, are positive integers. Boolean flags are 139 treated as positive one-byte integers. In each case, those positive 140 integers represent a terminal capability. The terminal compiler tic 141 uses negative integers to handle the cases where a capability is not 142 available: 143 144 <STRONG>o</STRONG> If a capability is absent from this terminal, tic stores a -1 in 145 the corresponding table. 146 147 The integer value -1 is represented by two bytes 0377, 0377. 148 Absent Boolean values are represented by the byte 0 (false). 149 150 <STRONG>o</STRONG> If a capability has been canceled from this terminal, tic stores a 151 -2 in the corresponding table. 152 153 The integer value -2 is represented by two bytes 0377, 0376. 154 The Boolean value -2 is represented by the byte 0376. 155 156 <STRONG>o</STRONG> Other negative values are illegal. 157 158 The <EM>terminal</EM> <EM>names</EM> section comes after the <EM>header</EM>. It contains the 159 first line of the terminfo description, listing the various names for 160 the terminal, separated by the "|" character. The <EM>terminal</EM> <EM>names</EM> 161 section is terminated with an ASCII NUL character. 162 163 The <EM>Boolean</EM> <EM>flags</EM> section has one byte for each flag. Boolean 164 capabilities are either 1 or 0 (true or false) according to whether the 165 terminal supports the given capability or not. 166 167 Between the <EM>Boolean</EM> <EM>flags</EM> section and the <EM>number</EM> section, a null byte 168 will be inserted, if necessary, to ensure that the <EM>number</EM> section 169 begins on an even byte This is a relic of the PDP-11's word-addressed 170 architecture, originally designed to avoid traps induced by addressing 171 a word on an odd byte boundary. All short integers are aligned on a 172 short word boundary. 173 174 The <EM>numbers</EM> section is similar to the <EM>Boolean</EM> <EM>flags</EM> section. Each 175 capability takes up two bytes, and is stored as a little-endian short 176 integer. 177 178 The <EM>strings</EM> section is also similar. Each capability is stored as a 179 short integer. The capability value is an index into the <EM>string</EM> <EM>table</EM>. 180 181 The <EM>string</EM> <EM>table</EM> is the last section. It contains all of the values of 182 string capabilities referenced in the <EM>strings</EM> section. Each string is 183 null-terminated. Special characters in ^X or \c notation are stored in 184 their interpreted form, not the printing representation. Padding 185 information $<nn> and parameter information %x are stored intact in 186 uninterpreted form. 187 188 189</PRE><H3><a name="h3-Extended-Storage-Format">Extended Storage Format</a></H3><PRE> 190 The previous section describes the conventional terminfo binary format. 191 With some minor variations of the offsets (see PORTABILITY), the same 192 binary format is used in all modern Unix systems. Each system uses a 193 predefined set of Boolean, number or string capabilities. 194 195 The <EM>ncurses</EM> libraries and applications support extended terminfo binary 196 format, allowing users to define capabilities which are loaded at 197 runtime. This extension is made possible by using the fact that the 198 other implementations stop reading the terminfo data when they have 199 reached the end of the size given in the header. <EM>ncurses</EM> checks the 200 size, and if it exceeds that due to the predefined data, continues to 201 parse according to its own scheme. 202 203 First, it reads the extended header (5 short integers): 204 205 (1) count of extended Boolean capabilities 206 207 (2) count of extended numeric capabilities 208 209 (3) count of extended string capabilities 210 211 (4) count of the items in extended string table 212 213 (5) size of the extended string table in bytes 214 215 The count- and size-values for the extended string table include the 216 extended capability <EM>names</EM> as well as extended capability <EM>values</EM>. 217 218 Using the counts and sizes, <EM>ncurses</EM> allocates arrays and reads data for 219 the extended capabilities in the same order as the header information. 220 221 The extended string table contains values for string capabilities. 222 After the end of these values, it contains the names for each of the 223 extended capabilities in order, e.g., Booleans, then numbers and 224 finally strings. 225 226 By storing terminal descriptions in this way, <EM>ncurses</EM> is able to 227 provide a database useful with legacy applications, as well as 228 providing data for applications which need more than the predefined 229 capabilities. See <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> for an overview of the way <EM>ncurses</EM> uses 230 this extended information. 231 232 Applications which manipulate terminal data can use the definitions 233 described in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> which associate the long capability 234 names with members of a <STRONG>TERMTYPE</STRONG> structure. 235 236 237</PRE><H3><a name="h3-Extended-Number-Format">Extended Number Format</a></H3><PRE> 238 On occasion, 16-bit signed integers are not large enough. With <EM>ncurses</EM> 239 6.1, a new format was introduced by making a few changes to the legacy 240 format: 241 242 <STRONG>o</STRONG> a different magic number (octal 01036) 243 244 <STRONG>o</STRONG> changing the type for the <EM>number</EM> array from signed 16-bit integers 245 to signed 32-bit integers. 246 247 To maintain compatibility, the library presents the same data 248 structures to direct users of the <STRONG>TERMTYPE</STRONG> structure as in previous 249 formats. However, that cannot provide callers with the extended 250 numbers. The library uses a similar but hidden data structure 251 <STRONG>TERMTYPE2</STRONG> to provide data for the terminfo functions. 252 253 254</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE> 255 <EM>/usr/share/terminfo</EM> 256 compiled terminal description database 257 258 259</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> 260 261</PRE><H3><a name="h3-setupterm">setupterm</a></H3><PRE> 262 Note that it is possible for <STRONG>setupterm</STRONG> to expect a different set of 263 capabilities than are actually present in the file. Either the 264 database may have been updated since <STRONG>setupterm</STRONG> was recompiled 265 (resulting in extra unrecognized entries in the file) or the program 266 may have been recompiled more recently than the database was updated 267 (resulting in missing entries). The routine <STRONG>setupterm</STRONG> must be prepared 268 for both possibilities - this is why the numbers and sizes are 269 included. Also, new capabilities must always be added at the end of 270 the lists of Boolean, number, and string capabilities. 271 272 273</PRE><H3><a name="h3-Binary-Format">Binary Format</a></H3><PRE> 274 X/Open Curses does not specify a format for the terminfo database. 275 System V curses used a directory-tree of binary files, one per terminal 276 description. 277 278 Despite the consistent use of little-endian for numbers and the 279 otherwise self-describing format, it is not wise to count on 280 portability of binary terminfo entries between commercial Unix 281 versions. The problem is that there are at least three versions of 282 terminfo (under HP-UX, AIX, and OSF/1) which diverged from System V 283 terminfo after SVr1, and have added extension capabilities to the 284 string table that (in the binary format) collide with System V and 285 X/Open Curses extensions. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for detailed discussion of 286 terminfo source compatibility issues. 287 288 This implementation is by default compatible with the binary terminfo 289 format used by Solaris curses, except in a few less-used details where 290 it was found that the latter did not match X/Open Curses. The format 291 used by the other Unix versions can be matched by building <EM>ncurses</EM> with 292 different configuration options. 293 294 295</PRE><H3><a name="h3-Magic-Codes">Magic Codes</a></H3><PRE> 296 The magic number in a binary terminfo file is the first 16-bits (two 297 bytes). Besides making it more reliable for the library to check that 298 a file is terminfo, utilities such as <STRONG>file(1)</STRONG> also use that to tell 299 what the file-format is. System V defined more than one magic number, 300 with 0433, 0435 as screen-dumps (see <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>). This implementation 301 uses 01036 as a continuation of that sequence, but with a different 302 high-order byte to avoid confusion. 303 304 <STRONG>The</STRONG> <EM>TERMTYPE</EM> <STRONG>Structure</STRONG> 305 Direct access to the <STRONG>TERMTYPE</STRONG> structure is provided for legacy 306 applications. Portable applications should use the <STRONG>tigetflag</STRONG> and 307 related functions described in <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> for reading terminal 308 capabilities. 309 310 311</PRE><H3><a name="h3-Mixed-case-Terminal-Names">Mixed-case Terminal Names</a></H3><PRE> 312 A small number of terminal descriptions use uppercase characters in 313 their names. If the underlying filesystem ignores the difference 314 between uppercase and lowercase, <EM>ncurses</EM> represents the "first 315 character" of the terminal name used as the intermediate level of a 316 directory tree in (two-character) hexadecimal form. 317 318 319</PRE><H3><a name="h3-Limits">Limits</a></H3><PRE> 320 <EM>ncurses</EM> stores compiled terminal descriptions in three related formats, 321 described in the sections 322 323 <STRONG>o</STRONG> <STRONG>LEGACY</STRONG> <STRONG>STORAGE</STRONG> <STRONG>FORMAT</STRONG>, and 324 325 <STRONG>o</STRONG> <STRONG>EXTENDED</STRONG> <STRONG>STORAGE</STRONG> <STRONG>FORMAT</STRONG>, and 326 327 <STRONG>o</STRONG> <STRONG>EXTENDED</STRONG> <STRONG>NUMBER</STRONG> <STRONG>FORMAT</STRONG>. 328 329 The legacy storage format and the extended number format differ by the 330 types of numeric capability which they can store (i.e., 16-bit versus 331 32-bit integers). The extended storage format introduced by <EM>ncurses</EM> 332 5.0 adds data to either of these formats. 333 334 Some limitations apply: 335 336 <STRONG>o</STRONG> total compiled entries cannot exceed 4096 bytes in the legacy 337 format. 338 339 <STRONG>o</STRONG> total compiled entries cannot exceed 32768 bytes in the extended 340 format. 341 342 <STRONG>o</STRONG> the name field cannot exceed 128 bytes. 343 344 Compiled entries are limited to 32768 bytes because offsets into the 345 <EM>strings</EM> <EM>table</EM> use two-byte integers. The legacy format could have 346 supported 32768-byte entries, but was limited to a virtual memory 347 page's 4096 bytes. 348 349 350</PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE> 351 As an example, here is a description for the Lear-Siegler ADM-3, a 352 popular though rather stupid early terminal: 353 354 adm3a|lsi adm3a, 355 am, 356 cols#80, lines#24, 357 bel=^G, clear=\032$<1>, cr=^M, cub1=^H, cud1=^J, 358 cuf1=^L, cup=\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K, 359 home=^^, ind=^J, 360 361 and a hexadecimal dump of the compiled terminal description: 362 363 0000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3 364 0010 61 7c 6c 73 69 20 61 64 6d 33 61 00 00 01 50 00 a|lsi ad m3a...P. 365 0020 ff ff 18 00 ff ff 00 00 02 00 ff ff ff ff 04 00 ........ ........ 366 0030 ff ff ff ff ff ff ff ff 0a 00 25 00 27 00 ff ff ........ ..%.'... 367 0040 29 00 ff ff ff ff 2b 00 ff ff 2d 00 ff ff ff ff ).....+. ..-..... 368 0050 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 369 0060 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 370 0070 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 371 0080 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 372 0090 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 373 00a0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 374 00b0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 375 00c0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 376 00d0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 377 00e0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 378 00f0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 379 0100 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 380 0110 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........ 381 0120 ff ff ff ff ff ff 2f 00 07 00 0d 00 1a 24 3c 31 ....../. .....$<1 382 0130 3e 00 1b 3d 25 70 31 25 7b 33 32 7d 25 2b 25 63 >..=%p1% {32}%+%c 383 0140 25 70 32 25 7b 33 32 7d 25 2b 25 63 00 0a 00 1e %p2%{32} %+%c.... 384 0150 00 08 00 0c 00 0b 00 0a 00 ........ . 385 386 387</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> 388 Thomas E. Dickey 389 extended terminfo format for <EM>ncurses</EM> 5.0 390 hashed database support for <EM>ncurses</EM> 5.6 391 extended number support for <EM>ncurses</EM> 6.1 392 393 Eric S. Raymond 394 documented legacy terminfo format, e.g., from <EM>pcurses</EM>. 395 396 397</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> 398 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> 399 400 401 402ncurses 6.5 2024-04-20 <STRONG><A HREF="term.5.html">term(5)</A></STRONG> 403</PRE> 404<div class="nav"> 405<ul> 406<li><a href="#h2-NAME">NAME</a></li> 407<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> 408<li><a href="#h2-DESCRIPTION">DESCRIPTION</a> 409<ul> 410<li><a href="#h3-Storage-Location">Storage Location</a></li> 411<li><a href="#h3-Legacy-Storage-Format">Legacy Storage Format</a></li> 412<li><a href="#h3-Extended-Storage-Format">Extended Storage Format</a></li> 413<li><a href="#h3-Extended-Number-Format">Extended Number Format</a></li> 414</ul> 415</li> 416<li><a href="#h2-FILES">FILES</a></li> 417<li><a href="#h2-PORTABILITY">PORTABILITY</a> 418<ul> 419<li><a href="#h3-setupterm">setupterm</a></li> 420<li><a href="#h3-Binary-Format">Binary Format</a></li> 421<li><a href="#h3-Magic-Codes">Magic Codes</a></li> 422<li><a href="#h3-Mixed-case-Terminal-Names">Mixed-case Terminal Names</a></li> 423<li><a href="#h3-Limits">Limits</a></li> 424</ul> 425</li> 426<li><a href="#h2-EXAMPLES">EXAMPLES</a></li> 427<li><a href="#h2-AUTHORS">AUTHORS</a></li> 428<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> 429</ul> 430</div> 431</BODY> 432</HTML> 433