| <!-- |
| **************************************************************************** |
| * 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.43 2021/12/25 21:28:59 tom Exp @ |
| --> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
| <HTML> |
| <HEAD> |
| <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
| <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> |
| <TITLE>term 5</TITLE> |
| <link rel="author" href="mailto:bug-ncurses@gnu.org"> |
| |
| </HEAD> |
| <BODY> |
| <H1 class="no-header">term 5</H1> |
| <PRE> |
| <STRONG><A HREF="term.5.html">term(5)</A></STRONG> File Formats Manual <STRONG><A HREF="term.5.html">term(5)</A></STRONG> |
| |
| |
| |
| |
| </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> |
| term - format of compiled term file. |
| |
| |
| </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> |
| <STRONG>term</STRONG> |
| |
| |
| </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> |
| |
| </PRE><H3><a name="h3-STORAGE-LOCATION">STORAGE LOCATION</a></H3><PRE> |
| Compiled terminfo descriptions are placed under the directory |
| <STRONG>/usr/share/terminfo</STRONG>. Two configurations are supported (when building |
| the <STRONG>ncurses</STRONG> libraries): |
| |
| <STRONG>directory</STRONG> <STRONG>tree</STRONG> |
| A two-level scheme is used to avoid a linear search of a huge UNIX |
| system directory: <STRONG>/usr/share/terminfo/c/name</STRONG> where <EM>name</EM> is the |
| name of the terminal, and <EM>c</EM> is the first character of <EM>name</EM>. Thus, |
| <EM>act4</EM> can be found in the file <STRONG>/usr/share/terminfo/a/act4</STRONG>. |
| Synonyms for the same terminal are implemented by multiple links |
| to the same compiled file. |
| |
| <STRONG>hashed</STRONG> <STRONG>database</STRONG> |
| 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. |
| |
| If built to write hashed databases, <STRONG>ncurses</STRONG> 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. |
| |
| <STRONG>ncurses</STRONG> 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. |
| |
| |
| </PRE><H3><a name="h3-LEGACY-STORAGE-FORMAT">LEGACY STORAGE FORMAT</a></H3><PRE> |
| 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 <STRONG>tic</STRONG> program, and read by the |
| routine <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>. The file is divided into six parts: |
| |
| a) <EM>header</EM>, |
| |
| b) <EM>terminal</EM> <EM>names</EM>, |
| |
| c) <EM>boolean</EM> <EM>flags</EM>, |
| |
| d) <EM>numbers</EM>, |
| |
| e) <EM>strings</EM>, and |
| |
| f) <EM>string</EM> <EM>table</EM>. |
| |
| The <EM>header</EM> section begins the file. This section contains six short |
| integers in the format described below. These integers are |
| |
| (1) the <EM>magic</EM> <EM>number</EM> (octal 0432); |
| |
| (2) the size, in bytes, of the <EM>terminal</EM> <EM>names</EM> section; |
| |
| (3) the number of bytes in the <EM>boolean</EM> <EM>flags</EM> section; |
| |
| (4) the number of short integers in the <EM>numbers</EM> section; |
| |
| (5) the number of offsets (short integers) in the <EM>strings</EM> section; |
| |
| (6) the size, in bytes, of the <EM>string</EM> <EM>table</EM>. |
| |
| The capabilities in the <EM>boolean</EM> <EM>flags</EM>, <EM>numbers</EM>, and <EM>strings</EM> sections |
| are in the same order as the file <term.h>. |
| |
| 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 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. |
| |
| Numbers in a terminal description, whether they are entries in the |
| <EM>numbers</EM> or <EM>strings</EM> 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: |
| |
| <STRONG>o</STRONG> 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). |
| |
| <STRONG>o</STRONG> 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. |
| |
| <STRONG>o</STRONG> Other negative values are illegal. |
| |
| The <EM>terminal</EM> <EM>names</EM> section comes after the <EM>header</EM>. It contains the |
| first line of the terminfo description, listing the various names for |
| the terminal, separated by the "|" character. The <EM>terminal</EM> <EM>names</EM> |
| section is terminated with an ASCII NUL character. |
| |
| The <EM>boolean</EM> <EM>flags</EM> 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 <EM>boolean</EM> <EM>flags</EM> section and the <EM>number</EM> section, a null byte |
| will be inserted, if necessary, to ensure that the <EM>number</EM> 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 <EM>numbers</EM> section is similar to the <EM>boolean</EM> <EM>flags</EM> section. Each |
| capability takes up two bytes, and is stored as a little-endian short |
| integer. |
| |
| The <EM>strings</EM> section is also similar. Each capability is stored as a |
| short integer. The capability value is an index into the <EM>string</EM> <EM>table</EM>. |
| |
| The <EM>string</EM> <EM>table</EM> is the last section. It contains all of the values of |
| string capabilities referenced in the <EM>strings</EM> 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. |
| |
| |
| </PRE><H3><a name="h3-EXTENDED-STORAGE-FORMAT">EXTENDED STORAGE FORMAT</a></H3><PRE> |
| 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 <STRONG>ncurses</STRONG> 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. <STRONG>ncurses</STRONG> 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 |
| |
| (2) count of extended numeric capabilities |
| |
| (3) count of extended string capabilities |
| |
| (4) count of the items in extended string table |
| |
| (5) size of the extended string table in bytes |
| |
| The count- and size-values for the extended string table include the |
| extended capability <EM>names</EM> as well as extended capability <EM>values</EM>. |
| |
| Using the counts and sizes, <STRONG>ncurses</STRONG> 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, e.g., booleans, then numbers and |
| finally strings. |
| |
| Applications which manipulate terminal data can use the definitions |
| described in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> which associate the long capability |
| names with members of a <STRONG>TERMTYPE</STRONG> structure. |
| |
| |
| </PRE><H3><a name="h3-EXTENDED-NUMBER-FORMAT">EXTENDED NUMBER FORMAT</a></H3><PRE> |
| On occasion, 16-bit signed integers are not large enough. With <STRONG>ncurses</STRONG> |
| 6.1, a new format was introduced by making a few changes to the legacy |
| format: |
| |
| <STRONG>o</STRONG> a different magic number (octal 01036) |
| |
| <STRONG>o</STRONG> changing the type for the <EM>number</EM> 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 <STRONG>TERMTYPE</STRONG> structure as in previous |
| formats. However, that cannot provide callers with the extended |
| numbers. The library uses a similar but hidden data structure |
| <STRONG>TERMTYPE2</STRONG> to provide data for the terminfo functions. |
| |
| |
| </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> |
| |
| </PRE><H3><a name="h3-setupterm">setupterm</a></H3><PRE> |
| Note that it is possible for <STRONG>setupterm</STRONG> to expect a different set of |
| capabilities than are actually present in the file. Either the |
| database may have been updated since <STRONG>setupterm</STRONG> 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 <STRONG>setupterm</STRONG> 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. |
| |
| |
| </PRE><H3><a name="h3-Binary-format">Binary format</a></H3><PRE> |
| 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. |
| |
| 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 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> 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. |
| |
| |
| </PRE><H3><a name="h3-Magic-codes">Magic codes</a></H3><PRE> |
| 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 <STRONG>file(1)</STRONG> 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 <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>). This implementation |
| uses 01036 as a continuation of that sequence, but with a different |
| high-order byte to avoid confusion. |
| |
| |
| </PRE><H3><a name="h3-The-TERMTYPE-structure">The TERMTYPE structure</a></H3><PRE> |
| Direct access to the <STRONG>TERMTYPE</STRONG> structure is provided for legacy |
| applications. Portable applications should use the <STRONG>tigetflag</STRONG> and |
| related functions described in <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> for reading terminal |
| capabilities. |
| |
| |
| </PRE><H3><a name="h3-Mixed-case-terminal-names">Mixed-case terminal names</a></H3><PRE> |
| A small number of terminal descriptions use uppercase characters in |
| their names. If the underlying filesystem ignores the difference |
| between uppercase and lowercase, <STRONG>ncurses</STRONG> represents the "first |
| character" of the terminal name used as the intermediate level of a |
| directory tree in (two-character) hexadecimal form. |
| |
| |
| </PRE><H2><a name="h2-EXAMPLE">EXAMPLE</a></H2><PRE> |
| As an example, here is a description for the Lear-Siegler ADM-3, a |
| popular though rather stupid early terminal: |
| |
| adm3a|lsi adm3a, |
| am, |
| cols#80, lines#24, |
| bel=^G, clear= 32$<1>, cr=^M, cub1=^H, cud1=^J, |
| cuf1=^L, cup=\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K, |
| home=^^, ind=^J, |
| |
| |
| and a hexadecimal dump of the compiled terminal description: |
| |
| 0000 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 ........ . |
| |
| |
| |
| </PRE><H2><a name="h2-LIMITS">LIMITS</a></H2><PRE> |
| Some limitations: |
| |
| <STRONG>o</STRONG> total compiled entries cannot exceed 4096 bytes in the legacy |
| format. |
| |
| <STRONG>o</STRONG> total compiled entries cannot exceed 32768 bytes in the extended |
| format. |
| |
| <STRONG>o</STRONG> the name field cannot exceed 128 bytes. |
| |
| Compiled entries are limited to 32768 bytes because offsets into the |
| <EM>strings</EM> <EM>table</EM> use two-byte integers. The legacy format could have |
| supported 32768-byte entries, but was limited a virtual memory page's |
| 4096 bytes. |
| |
| |
| </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE> |
| /usr/share/terminfo/*/* compiled terminal capability database |
| |
| |
| </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> |
| <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. |
| |
| |
| </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> |
| Thomas E. Dickey |
| 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, e.g., from <EM>pcurses</EM>. |
| |
| |
| |
| <STRONG><A HREF="term.5.html">term(5)</A></STRONG> |
| </PRE> |
| <div class="nav"> |
| <ul> |
| <li><a href="#h2-NAME">NAME</a></li> |
| <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> |
| <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> |
| <ul> |
| <li><a href="#h3-STORAGE-LOCATION">STORAGE LOCATION</a></li> |
| <li><a href="#h3-LEGACY-STORAGE-FORMAT">LEGACY STORAGE FORMAT</a></li> |
| <li><a href="#h3-EXTENDED-STORAGE-FORMAT">EXTENDED STORAGE FORMAT</a></li> |
| <li><a href="#h3-EXTENDED-NUMBER-FORMAT">EXTENDED NUMBER FORMAT</a></li> |
| </ul> |
| </li> |
| <li><a href="#h2-PORTABILITY">PORTABILITY</a> |
| <ul> |
| <li><a href="#h3-setupterm">setupterm</a></li> |
| <li><a href="#h3-Binary-format">Binary format</a></li> |
| <li><a href="#h3-Magic-codes">Magic codes</a></li> |
| <li><a href="#h3-The-TERMTYPE-structure">The TERMTYPE structure</a></li> |
| <li><a href="#h3-Mixed-case-terminal-names">Mixed-case terminal names</a></li> |
| </ul> |
| </li> |
| <li><a href="#h2-EXAMPLE">EXAMPLE</a></li> |
| <li><a href="#h2-LIMITS">LIMITS</a></li> |
| <li><a href="#h2-FILES">FILES</a></li> |
| <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> |
| <li><a href="#h2-AUTHORS">AUTHORS</a></li> |
| </ul> |
| </div> |
| </BODY> |
| </HTML> |
