mirror of
https://github.com/ThomasDickey/ncurses-snapshots.git
synced 2026-01-26 11:04:35 +00:00
413 lines
21 KiB
HTML
413 lines
21 KiB
HTML
<!--
|
|
****************************************************************************
|
|
* Copyright 2018-2021,2023 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.52 2023/09/09 17:14:44 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 2023-09-09 ncurses 6.4 File formats</TITLE>
|
|
<link rel="author" href="mailto:bug-ncurses@gnu.org">
|
|
|
|
</HEAD>
|
|
<BODY>
|
|
<H1 class="no-header">term 5 2023-09-09 ncurses 6.4 File formats</H1>
|
|
<PRE>
|
|
<STRONG><A HREF="term.5.html">term(5)</A></STRONG> File formats <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>.
|
|
|
|
|
|
|
|
ncurses 6.4 2023-09-09 <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>
|