man/term.5

   1 '\" t
   2 .\"***************************************************************************
   3 .\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
   4 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   5 .\"                                                                          *
   6 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   7 .\" copy of this software and associated documentation files (the            *
   8 .\" "Software"), to deal in the Software without restriction, including      *
   9 .\" without limitation the rights to use, copy, modify, merge, publish,      *
  10 .\" distribute, distribute with modifications, sublicense, and/or sell       *
  11 .\" copies of the Software, and to permit persons to whom the Software is    *
  12 .\" furnished to do so, subject to the following conditions:                 *
  13 .\"                                                                          *
  14 .\" The above copyright notice and this permission notice shall be included  *
  15 .\" in all copies or substantial portions of the Software.                   *
  16 .\"                                                                          *
  17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24 .\"                                                                          *
  25 .\" Except as contained in this notice, the name(s) of the above copyright   *
  26 .\" holders shall not be used in advertising or otherwise to promote the     *
  27 .\" sale, use or other dealings in this Software without prior written       *
  28 .\" authorization.                                                           *
  29 .\"***************************************************************************
  30 .\"
  31 .\" $Id: term.5,v 1.78 2024/05/11 20:39:53 tom Exp $
  32 .TH term 5 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
  33 .ie \n(.g \{\
  34 .ds `` \(lq
  35 .ds '' \(rq
  36 .ds '  \(aq
  37 .ds ^  \(ha
  38 .\}
  39 .el \{\
  40 .ie t .ds `` ``
  41 .el   .ds `` ""
  42 .ie t .ds '' ''
  43 .el   .ds '' ""
  44 .ds       '  '
  45 .ds       ^  ^
  46 .\}
  47 .ie n .ds CW R
  48 .el   \{
  49 .ie \n(.g .ds CW CR
  50 .el       .ds CW CW
  51 .\}
  52 .
  53 .de bP
  54 .ie n  .IP \(bu 4
  55 .el    .IP \(bu 2
  56 ..
  57 .
  58 .SH NAME
  59 term \-
  60 compiled \fI\%term\%info\fP terminal description
  61 .SH DESCRIPTION
  62 \fB\%@TIC@\fP(1) compiles a
  63 .I \%term\%info
  64 terminal type description,
  65 and \fB\%setupterm\fP(3X) reads it.
  66 A compiled description may be stored in a file or in a database of,
  67 potentially,
  68 many such descriptions.
  69 Further,
  70 a compiled description may be in one of two formats:
  71 one similar to that used by System\ V,
  72 and a newer,
  73 extensible format employed exclusively by
  74 .IR \%ncurses .
  75 .SS "Storage Location"
  76 Compiled
  77 .I \%term\%info descriptions are placed
  78 under the directory
  79 .IR \%@TERMINFO@ .
  80 One of two configurations is selected
  81 when building the
  82 .I \%ncurses
  83 libraries.
  84 .TP 5
  85 .B directory tree
  86 A two-level scheme is used to avoid a linear search
  87 of a huge Unix system directory:
  88 .IR \%@TERMINFO@/ c / name
  89 where
  90 .I name
  91 is the name of the terminal,
  92 and
  93 .I c
  94 is the first character of
  95 .IR name .
  96 Thus,
  97 the compiled description of terminal type \*(``act4\*(''
  98 is found in the file
  99 .IR \%@TERMINFO@/a/act4 .
 100 Synonyms for the same terminal are implemented by multiple
 101 links to the same compiled file.
 102 .TP 5
 103 .B hashed database
 104 Using the Berkeley database API,
 105 two types of records are stored:
 106 the
 107 .I \%term\%info
 108 data in the same format as that stored in a directory tree with
 109 the terminal's primary type name as a key,
 110 and records containing only aliases pointing to the primary name.
 111 .IP
 112 If built to write hashed databases,
 113 .I \%ncurses
 114 can still read
 115 .I \%term\%info
 116 databases organized as a
 117 directory tree,
 118 but cannot write entries into the directory tree.
 119 It can write
 120 (or rewrite)
 121 entries in the hashed database.
 122 .IP
 123 .I \%ncurses
 124 distinguishes the two cases in the
 125 .I \%TERMINFO
 126 and
 127 .I \%TERMINFO_DIRS
 128 environment variable by assuming a directory tree for entries that
 129 correspond to an existing directory,
 130 and a hashed database otherwise.
 131 .SS "Legacy Storage Format"
 132 The format has been chosen so that it will be the same on all hardware.
 133 A byte of at least eight bits' width is assumed,
 134 but no assumptions about bit ordering
 135 or sign extension are made.
 136 .PP
 137 The file is divided into six parts:
 138 .RS 5
 139 .IP (a) 4
 140 .IR header ,
 141 .IP (b)
 142 .IR "terminal names" ,
 143 .IP (c)
 144 .IR "Boolean flags" ,
 145 .IP (d)
 146 .IR numbers ,
 147 .IP (e)
 148 .IR strings ,
 149 and
 150 .IP (f)
 151 a
 152 .IR "string table" .
 153 .RE
 154 .PP
 155 The \fIheader\fP section begins the file.
 156 This section contains six short integers in the format
 157 described below.
 158 These integers are
 159 .RS 5
 160 .TP 5
 161 (1) the \fImagic number\fP
 162 (octal 0432);
 163 .TP 5
 164 (2) the size,
 165 in bytes,
 166 of the \fIterminal names\fP section;
 167 .TP 5
 168 (3) the number of bytes in the \fIBoolean flags\fP section;
 169 .TP 5
 170 (4) the number of short integers in the \fInumbers\fP section;
 171 .TP 5
 172 (5) the number of offsets
 173 (short integers)
 174 in the \fIstrings\fP section;
 175 .TP 5
 176 (6) the size,
 177 in bytes,
 178 of the \fIstring table\fP.
 179 .RE
 180 .PP
 181 The capabilities in the
 182 \fIBoolean flags\fP,
 183 \fInumbers\fP,
 184 and
 185 \fIstrings\fP
 186 sections are in the same order as in the header file
 187 .IR term.h .
 188 .PP
 189 Short integers are signed,
 190 in the range \-32768 to 32767,
 191 and stored in little-endian format.
 192 .PP
 193 Numbers in a terminal description,
 194 whether they are entries in the \fInumbers\fP or \fIstrings\fP table,
 195 are positive integers.
 196 Boolean flags are treated as positive one-byte integers.
 197 In each case,
 198 those positive integers represent a terminal capability.
 199 The terminal compiler
 200 .I \%@TIC@
 201 uses negative integers to handle the cases where a capability is not
 202 available:
 203 .bP
 204 If a capability is absent from this terminal,
 205 .I \%@TIC@
 206 stores a \-1 in the corresponding table.
 207 .IP
 208 The integer value \-1 is represented by two bytes 0377,
 209 0377.
 210 .br
 211 Absent Boolean values are represented by the byte 0 (false).
 212 .bP
 213 If a capability has been canceled from this terminal,
 214 .I \%@TIC@
 215 stores a \-2 in the corresponding table.
 216 .IP
 217 The integer value \-2 is represented by two bytes 0377,
 218 0376.
 219 .br
 220 The Boolean value \-2 is represented by the byte 0376.
 221 .br
 222 .bP
 223 Other negative values are illegal.
 224 .PP
 225 The \fIterminal names\fP section comes after the \fIheader\fP.
 226 It contains the first line of the
 227 .I \%term\%info
 228 description,
 229 listing the various names for the terminal,
 230 separated by the \*(``|\*('' character.
 231 The \fIterminal names\fP section is terminated
 232 with an \s-1ASCII NUL\s+1 character.
 233 .PP
 234 The \fIBoolean flags\fP section has one byte for each flag.
 235 Boolean capabilities are either 1 or 0
 236 (true or false)
 237 according to whether the terminal supports the given capability or not.
 238 .PP
 239 Between the \fIBoolean flags\fP section and the \fInumber\fP section,
 240 a null byte will be inserted,
 241 if necessary,
 242 to ensure that the \fInumber\fP section begins on an even byte
 243 This is a relic of the PDP\-11's word-addressed architecture,
 244 originally designed to avoid traps induced
 245 by addressing a word on an odd byte boundary.
 246 All short integers are aligned on a short word boundary.
 247 .PP
 248 The \fInumbers\fP section is similar to the \fIBoolean flags\fP section.
 249 Each capability takes up two bytes,
 250 and is stored as a little-endian short integer.
 251 .PP
 252 The \fIstrings\fP section is also similar.
 253 Each capability is stored as a short integer.
 254 The capability value is an index into the \fIstring table\fP.
 255 .PP
 256 The \fIstring table\fP is the last section.
 257 It contains all of the values of string capabilities referenced in
 258 the \fIstrings\fP section.
 259 Each string is null-terminated.
 260 Special characters in \*^X or \ec notation are stored in their
 261 interpreted form,
 262 not the printing representation.
 263 Padding information
 264 .BI $< nn >
 265 and parameter information
 266 .B %x
 267 are stored intact in uninterpreted form.
 268 .SS "Extended Storage Format"
 269 The previous section describes the conventional
 270 .I \%term\%info
 271 binary format.
 272 With some minor variations of the offsets
 273 (see PORTABILITY),
 274 the same binary format is used in all modern Unix systems.
 275 Each system uses a predefined set of Boolean,
 276 number or string capabilities.
 277 .PP
 278 The
 279 .I \%ncurses
 280 libraries and applications support extended
 281 .I \%term\%info
 282 binary format,
 283 allowing users to define capabilities that are loaded at runtime.
 284 This extension is made possible by using the fact that the other
 285 implementations stop reading the
 286 .I \%term\%info
 287 data when they reach the end of the size given in the header.
 288 .I \%ncurses
 289 checks the size,
 290 and if it exceeds that due to the predefined data,
 291 continues to parse according to its own scheme.
 292 .PP
 293 First,
 294 it reads the extended header
 295 (5 short integers):
 296 .RS 5
 297 .TP 5
 298 (1)
 299 count of extended Boolean capabilities
 300 .TP 5
 301 (2)
 302 count of extended numeric capabilities
 303 .TP 5
 304 (3)
 305 count of extended string capabilities
 306 .TP 5
 307 (4)
 308 count of the items in extended string table
 309 .TP 5
 310 (5)
 311 size of the extended string table in bytes
 312 .RE
 313 .PP
 314 The count- and size-values for the extended string table
 315 include the extended capability \fInames\fP as well as
 316 extended capability \fIvalues\fP.
 317 .PP
 318 Using the counts and sizes,
 319 .I \%ncurses
 320 allocates arrays and reads data for the extended capabilities in the
 321 same order as the header information.
 322 .PP
 323 The extended string table contains values for string capabilities.
 324 After the end of these values,
 325 it contains the names for each of
 326 the extended capabilities in order:
 327 Boolean,
 328 numeric,
 329 and string.
 330 .PP
 331 By storing terminal descriptions in this way,
 332 .I \%ncurses
 333 is able to provide a database useful with legacy applications,
 334 as well as providing data for applications that require more information
 335 about a terminal type than was anticipated
 336 by X/Open Curses.
 337 See \fB\%user_caps\fP(5) for an overview of the way
 338 .I \%ncurses
 339 uses this extended information.
 340 .PP
 341 Applications that manipulate terminal data can use the definitions
 342 described in \fB\%term_variables\fP(3X) associating the long capability
 343 names with members of a
 344 .I \%TERMTYPE
 345 structure.
 346 .
 347 .SS "Extended Number Format"
 348 On occasion,
 349 16-bit signed integers are not large enough.
 350 .I \%ncurses
 351 6.1 introduced a new format
 352 by making a few changes to the legacy format:
 353 .bP
 354 a different magic number
 355 (octal 01036)
 356 .bP
 357 changing the type for the \fInumber\fP array from signed 16-bit integers
 358 to signed 32-bit integers.
 359 .PP
 360 To maintain compatibility,
 361 the library presents the same data structures
 362 to direct users of the
 363 .I \%TERMTYPE
 364 structure as in previous formats.
 365 However,
 366 that cannot provide callers with the extended numbers.
 367 The library uses a similar but hidden data structure
 368 .I \%TERMTYPE2
 369 to provide data for the
 370 .I \%term\%info
 371 functions.
 372 .SH FILES
 373 .TP
 374 .I @TERMINFO@
 375 compiled terminal description database
 376 .SH PORTABILITY
 377 .SS setupterm
 378 Note that it is possible for
 379 .B setupterm
 380 to expect a different set of capabilities
 381 than are actually present in the file.
 382 Either the database may have been updated since
 383 .B setupterm
 384 was recompiled
 385 (resulting in extra unrecognized entries in the file)
 386 or the program may have been recompiled more recently
 387 than the database was updated
 388 (resulting in missing entries).
 389 The routine
 390 .B setupterm
 391 must be prepared for both possibilities \-
 392 this is why the numbers and sizes are included.
 393 Also,
 394 new capabilities must always be added at the end of the lists
 395 of Boolean,
 396 number,
 397 and string capabilities.
 398 .SS "Binary Format"
 399 X/Open Curses does not specify a format for the
 400 .I \%term\%info
 401 database.
 402 System\ V
 403 .I curses
 404 used a directory-tree of binary files,
 405 one per terminal description.
 406 .PP
 407 Despite the consistent use of little-endian numbers and the otherwise
 408 self-describing format,
 409 it is not wise to count on portability of binary
 410 .I \%term\%info
 411 entries between commercial Unix versions.
 412 The problem is that there are at least three versions of
 413 .I \%term\%info
 414 (under HP\-UX,
 415 AIX,
 416 and OSF/1)
 417 each of which diverged from System\ V
 418 .I \%term\%info
 419 after SVr1,
 420 and added extension capabilities to the string table that
 421 (in the binary format)
 422 collide with System\ V and X/Open Curses extensions.
 423 See \fB\%terminfo\fP(5) for detailed
 424 discussion of
 425 .I \%term\%info
 426 source compatibility issues.
 427 .PP
 428 This implementation is by default compatible with the binary
 429 .I \%term\%info
 430 format used by Solaris
 431 .IR curses ,
 432 except in a few less-used details
 433 where it was found that the latter did not match X/Open Curses.
 434 The format used by the other Unix versions
 435 can be matched by building
 436 .I \%ncurses
 437 with different configuration options.
 438 .SS "Magic Codes"
 439 The magic number in a binary
 440 .I \%term\%info
 441 file is the first 16 bits
 442 (two bytes).
 443 Besides making it more reliable for the library to check that a file is
 444 .IR \%term\%info ,
 445 utilities such as \fIfile\fP(1) also use that to tell what the
 446 file-format is.
 447 System\ V defined more than one magic number,
 448 with 0433,
 449 0435 as screen-dumps
 450 (see \fB\%scr_dump\fP(5)).
 451 This implementation uses 01036 as a continuation of that sequence,
 452 but with a different high-order byte to avoid confusion.
 453 .SS "The \fITERMTYPE\fP Structure"
 454 Direct access to the
 455 .I \%TERMTYPE
 456 structure is provided for legacy applications.
 457 Portable applications should use \fB\%tigetflag\fP(3X) and related
 458 functions to read terminal capabilities.
 459 .SS "Mixed-case Terminal Names"
 460 A small number of terminal descriptions use uppercase characters in
 461 their names.
 462 If the underlying file system ignores the difference between
 463 uppercase and lowercase,
 464 .I \%ncurses
 465 represents the \*(``first character\*('' of the terminal name used as
 466 the intermediate level of a directory tree in (two-character)
 467 hexadecimal form.
 468 .SS Limits
 469 .I \%ncurses
 470 stores compiled terminal descriptions in three related formats,
 471 described in the subsections
 472 .bP
 473 .BR "Legacy Storage Format" ,
 474 and
 475 .bP
 476 .BR "Extended Storage Format" ,
 477 and
 478 .bP
 479 .BR "Extended Number Format" .
 480 .PP
 481 The legacy storage format and the extended number format differ by
 482 the types of numeric capability that they can store
 483 (for example,
 484 16- versus 32-bit integers).
 485 The extended storage format introduced by
 486 .I \%ncurses
 487 5.0 adds data to either of these formats.
 488 .PP
 489 Some limitations apply:
 490 .bP
 491 total compiled entries cannot exceed 4096 bytes in the legacy format.
 492 .bP
 493 total compiled entries cannot exceed 32768 bytes in the extended format.
 494 .bP
 495 the name field cannot exceed 128 bytes.
 496 .PP
 497 Compiled entries are limited to 32768 bytes because offsets into the
 498 \fIstrings table\fP use two-byte integers.
 499 The legacy format could have supported 32768-byte entries,
 500 but was limited to a virtual memory page's 4096 bytes.
 501 .SH EXAMPLES
 502 Here is a
 503 .I \%term\%info
 504 description of the Lear-Siegler ADM-3,
 505 a popular though rather stupid early terminal.
 506 .PP
 507 .EX
 508 adm3a|lsi adm3a,
 509         am,
 510         cols#80, lines#24,
 511         bel=\*^G, clear=\e032$<1>, cr=\*^M, cub1=\*^H, cud1=\*^J,
 512         cuf1=\*^L, cup=\eE=%p1%{32}%+%c%p2%{32}%+%c, cuu1=\*^K,
 513         home=\*^\*^, ind=\*^J,
 514 .EE
 515 .PP
 516 A hexadecimal dump of its compiled terminal description
 517 (in legacy format)
 518 follows.
 519 .PP
 520 .if t .in +4n
 521 .ft \*(CW
 522 .TS
 523 Lp-1.
 524 0000  1a 01 10 00 02 00 03 00  82 00 31 00 61 64 6d 33  ........ ..1.adm3
 525 0010  61 7c 6c 73 69 20 61 64  6d 33 61 00 00 01 50 00  a|lsi ad m3a...P.
 526 0020  ff ff 18 00 ff ff 00 00  02 00 ff ff ff ff 04 00  ........ ........
 527 0030  ff ff ff ff ff ff ff ff  0a 00 25 00 27 00 ff ff  ........ ..%.\*'...
 528 0040  29 00 ff ff ff ff 2b 00  ff ff 2d 00 ff ff ff ff  ).....+. ..\-.....
 529 0050  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 530 0060  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 531 0070  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 532 0080  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 533 0090  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 534 00a0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 535 00b0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 536 00c0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 537 00d0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 538 00e0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 539 00f0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 540 0100  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 541 0110  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 542 0120  ff ff ff ff ff ff 2f 00  07 00 0d 00 1a 24 3c 31  ....../. .....$<1
 543 0130  3e 00 1b 3d 25 70 31 25  7b 33 32 7d 25 2b 25 63  >..=%p1% {32}%+%c
 544 0140  25 70 32 25 7b 33 32 7d  25 2b 25 63 00 0a 00 1e  %p2%{32} %+%c....
 545 0150  00 08 00 0c 00 0b 00 0a  00                       ........ .
 546 .TE
 547 .ft
 548 .in
 549 .SH AUTHORS
 550 Thomas E. Dickey
 551 .br
 552 extended
 553 .I \%term\%info
 554 format for
 555 .I \%ncurses
 556 5.0
 557 .br
 558 hashed database support for
 559 .I \%ncurses
 560 5.6
 561 .br
 562 extended number support for
 563 .I \%ncurses
 564 6.1
 565 .sp
 566 Eric S. Raymond
 567 .br
 568 documented legacy
 569 .I \%term\%info
 570 format
 571 (that used by
 572 .IR \%pcurses ).
 573 .SH SEE ALSO
 574 \fB\%curses\fP(3X),
 575 \fB\%curs_terminfo\fP(3X),
 576 \fB\%terminfo\fP(5),
 577 \fB\%user_caps\fP(5)