+<!--
+ ****************************************************************************
+ * Copyright (c) 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.26 2017/02/18 16:58:21 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 http://invisible-island.net/scripts/readme.html#others_scripts">
+<TITLE>term 5</TITLE>
+<link rev=made 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>
-<!-- Manpage converted by man2html 3.0.1 -->
+<STRONG><A HREF="term.5.html">term(5)</A></STRONG> <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
-</PRE>
-<H2>NAME</H2><PRE>
+
+
+
+</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
term - format of compiled term file.
-</PRE>
-<H2>SYNOPSIS</H2><PRE>
- <B>term</B>
+</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
+ <STRONG>term</STRONG>
-</PRE>
-<H2>DESCRIPTION</H2><PRE>
- Compiled terminfo descriptions are placed under the direc-
- tory <B>@DATADIR@/terminfo</B>. In order to avoid a linear
- search of a huge UNIX system directory, a two-level scheme
- is used: <B>/c/name</B> where <I>name</I> is the name of the terminal,
- and <I>c</I> is the first character of <I>name</I>. Thus, <I>act4</I> can be
- found in the file <B>@DATADIR@/terminfo/a/act4</B>. Synonyms for
- the same terminal are implemented by multiple links to the
- same compiled file.
+</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 direc-
+ tory <STRONG>/usr/share/terminfo</STRONG>. Two configurations are sup-
+ ported (when building the ncurses 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/ter-</STRONG>
+ <STRONG>minfo/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 pri-
+ mary name as a key, and records containing only
+ aliases pointing to the primary name.
+
+ If built to write hashed databases, ncurses 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.
+
+ ncurses 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-STORAGE-FORMAT">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 <I>tic</I> program, and
- read by the routine <I>setupterm</I>. The file is divided into
- six parts: the header, terminal names, boolean flags, num-
- bers, strings, and string table.
+ 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: 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*second+first.) The
+ 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 sec-
+ tion;
+
+ (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*second+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 hard-
+ negative values are illegal. This value generally means
+ that the corresponding capability is missing from this
+ terminal. Note that this format corresponds to the hard-
ware 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
+ 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 vari-
- ous names for the terminal, separated by the `|' charac-
- ter. The section is terminated with an ASCII NUL charac-
+ The terminal names section comes next. It contains the
+ first line of the terminfo description, listing the vari-
+ ous names for the terminal, separated by the "|" charac-
+ ter. The section is terminated with an ASCII NUL charac-
ter.
- The boolean flags have one byte for each flag. This byte
- is either 0 or 1 as the flag is present or absent. The
+ 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
+ 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-
+ 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 beginning of the
+ 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 beginning of the
string table. Special characters in ^X or \c notation are
- stored in their interpreted form, not the printing repre-
+ stored in their interpreted form, not the printing repre-
sentation. Padding information $<nn> and parameter infor-
mation %x are stored intact in uninterpreted form.
- The final section is the string table. It contains all
+ 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.
- Note that it is possible for <I>setupterm</I> to expect a differ-
+
+</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 ncurses libraries and applications support extended
+ terminfo binary format, allowing users to define capabili-
+ ties 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. ncurses 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) size of the extended string table in bytes.
+
+ (5) last offset of the extended string table in
+ bytes.
+
+ Using the counts and sizes, ncurses 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 capa-
+ bilities. 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.
+
+
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+ Note that it is possible for <STRONG>setupterm</STRONG> to expect a differ-
ent set of capabilities than are actually present in the
file. Either the database may have been updated since
- <I>setupterm</I> has been recompiled (resulting in extra unrecog-
+ <STRONG>setupterm</STRONG> has been recompiled (resulting in extra unrecog-
nized entries in the file) or the program may have been
recompiled more recently than the database was updated
- (resulting in missing entries). The routine <I>setupterm</I>
+ (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,
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 <B><A HREF="terminfo.5.html">terminfo(5)</A></B> for detailed discus-
+ Curses extensions. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for detailed discus-
sion of terminfo source compatibility issues.
+
+</PRE><H2><a name="h2-EXAMPLE">EXAMPLE</a></H2><PRE>
As an example, here is a hex dump of the description for
the Lear-Siegler ADM-3, a popular though rather stupid
early terminal:
am,
cols#80, lines#24,
bel=^G, clear= 32$<1>, cr=^M, cub1=^H, cud1=^J,
- cuf1=^L, cup==%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
+ cuf1=^L, cup=\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
home=^^, ind=^J,
0000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3
0150 00 08 00 0c 00 0b 00 0a 00 ........ .
+
+</PRE><H2><a name="h2-LIMITS">LIMITS</a></H2><PRE>
Some limitations: total compiled entries cannot exceed
4096 bytes. The name field cannot exceed 128 bytes.
-</PRE>
-<H2>FILES</H2><PRE>
- @DATADIR@/terminfo/*/* compiled terminal capability data
+</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
+ /usr/share/terminfo/*/* compiled terminal capability data
base
-</PRE>
-<H2>SEE ALSO</H2><PRE>
- <B><A HREF="ncurses.3x.html">curses(3x)</A></B>, <B><A HREF="terminfo.5.html">terminfo(5)</A></B>.
-
-
-
-
-
+</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
+ Eric S. Raymond
+ <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
</PRE>
-<HR>
-<ADDRESS>
-Man(1) output converted with
-<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
-</ADDRESS>
+<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-STORAGE-FORMAT">STORAGE FORMAT</a></li>
+<li><a href="#h3-EXTENDED-STORAGE-FORMAT">EXTENDED STORAGE FORMAT</a></li>
+</ul>
+</li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a></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>
projects / ncurses.git / blobdiff