| <!-- |
| **************************************************************************** |
| * Copyright 2018-2019,2020 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.33 2020/02/02 23:34:34 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"> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| </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>. Syn- |
| onyms 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 ter- |
| minfo 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 ter- |
| minfo 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 TER- |
| MINFO_DIRS environment variable by assuming a directory tree for |
| entries that correspond to an existing directory, and hashed data- |
| base 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 order- |
| ing or sign extension are made. |
| |
| The compiled file is created with the <STRONG>tic</STRONG> program, and read by the rou- |
| tine <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>. The file is divided into six parts: the header, |
| terminal names, boolean flags, numbers, strings, and string table. |
| |
| The header section begins the file. This section contains six short |
| integers in the format described below. These integers are |
| |
| (1) the magic number (octal 0432); |
| |
| (2) the size, in bytes, of the names section; |
| |
| (3) the number of bytes in the boolean section; |
| |
| (4) the number of short integers in the numbers section; |
| |
| (5) the number of offsets (short integers) in the strings section; |
| |
| (6) the size, in bytes, of the string table. |
| |
| Short integers are stored in 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*sec- |
| ond+first.) The value -1 is represented by the two bytes 0377, 0377; |
| other negative values are illegal. This value generally means that the |
| corresponding capability is missing from this terminal. Note that this |
| format corresponds to the hardware of the VAX and PDP-11 (that is, lit- |
| tle-endian machines). Machines where this does not correspond to the |
| hardware must read the integers as two bytes and compute the little- |
| endian value. |
| |
| The terminal names section comes next. It contains the first line of |
| the terminfo description, listing the various names for the terminal, |
| separated by the "|" character. The section is terminated with an |
| ASCII NUL character. |
| |
| The boolean flags have one byte for each flag. This byte is either 0 |
| or 1 as the flag is present or absent. The capabilities are in the |
| same order as the file <term.h>. |
| |
| Between the boolean section and the number section, a null byte will be |
| inserted, if necessary, to ensure that the number section begins on an |
| even byte (this is a relic of the PDP-11's word-addressed architecture, |
| originally designed in to avoid IOT traps induced by addressing a word |
| on an odd byte boundary). All short integers are aligned on a short |
| word boundary. |
| |
| The numbers section is similar to the flags section. Each capability |
| takes up two bytes, and is stored as a little-endian short integer. If |
| the value represented is -1, the capability is taken to be missing. |
| |
| The strings section is also similar. Each capability is stored as a |
| short integer, in the format above. A value of -1 means the capability |
| is missing. Otherwise, the value is taken as an offset from the begin- |
| ning of the string table. 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. |
| |
| The final section is the string table. It contains all the values of |
| string capabilities referenced in the string section. Each string is |
| null terminated. |
| |
| |
| </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 run- |
| time. 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 struc- |
| tures 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 data- |
| base may have been updated since <STRONG>setupterm</STRONG> has been recompiled (result- |
| ing 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 bool- |
| ean, 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 other- |
| wise 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</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 applica- |
| tions. 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 capabili- |
| ties. |
| |
| |
| </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 charac- |
| ter" 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 pop- |
| ular 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 for- |
| mat. |
| |
| <STRONG>o</STRONG> total compiled entries cannot exceed 32768 bytes in the extended |
| format. |
| |
| <STRONG>o</STRONG> the name field cannot exceed 128 bytes. |
| |
| |
| </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE> |
| /usr/share/terminfo/*/* compiled terminal capability data base |
| |
| |
| </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 pcurses. |
| |
| |
| |
| <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> |
