mirror of
https://github.com/freebsd/freebsd-src
synced 2024-10-15 21:05:08 +00:00
453 lines
17 KiB
Groff
453 lines
17 KiB
Groff
'\" t
|
|
.\"***************************************************************************
|
|
.\" Copyright 2018-2023,2024 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.77 2024/04/20 21:24:19 tom Exp $
|
|
.TH term 5 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
|
|
.ie \n(.g \{\
|
|
.ds `` \(lq
|
|
.ds '' \(rq
|
|
.ds ' \(aq
|
|
.ds ^ \(ha
|
|
.\}
|
|
.el \{\
|
|
.ie t .ds `` ``
|
|
.el .ds `` ""
|
|
.ie t .ds '' ''
|
|
.el .ds '' ""
|
|
.ds ' '
|
|
.ds ^ ^
|
|
.\}
|
|
.ie n .ds CW R
|
|
.el \{
|
|
.ie \n(.g .ds CW CR
|
|
.el .ds CW CW
|
|
.\}
|
|
.
|
|
.de bP
|
|
.ie n .IP \(bu 4
|
|
.el .IP \(bu 2
|
|
..
|
|
.
|
|
.ds d @TERMINFO@
|
|
.SH NAME
|
|
term \-
|
|
compiled \fIterminfo\fR terminal description
|
|
.SH SYNOPSIS
|
|
.B term
|
|
.SH DESCRIPTION
|
|
.SS "Storage Location"
|
|
Compiled terminfo descriptions are placed under the directory \fB\*d\fP.
|
|
Two configurations are supported
|
|
(when building the \fI\%ncurses\fP libraries):
|
|
.TP 5
|
|
.B directory tree
|
|
A two-level scheme is used to avoid a linear search
|
|
of a huge Unix system directory: \fB\*d/c/name\fP where
|
|
.I name
|
|
is the name of the terminal, and
|
|
.I c
|
|
is the first character of
|
|
.IR name .
|
|
Thus,
|
|
.I act4
|
|
can be found in the file \fB\*d/a/act4\fP.
|
|
Synonyms for the same terminal are implemented by multiple
|
|
links to the same compiled file.
|
|
.TP 5
|
|
.B hashed database
|
|
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.
|
|
.IP
|
|
If built to write hashed databases,
|
|
\fI\%ncurses\fP 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.
|
|
.IP
|
|
\fI\%ncurses\fP distinguishes the two cases in the \fI\%TERMINFO\fP and
|
|
\fI\%TERMINFO_DIRS\fP environment variable by assuming a directory tree
|
|
for entries that correspond to an existing directory,
|
|
and hashed database otherwise.
|
|
.SS "Legacy Storage Format"
|
|
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.
|
|
.PP
|
|
The compiled file is created with the \fB@TIC@\fP program,
|
|
and read by the routine \fBsetupterm\fP(3X).
|
|
The file is divided into six parts:
|
|
.RS 5
|
|
.TP 3
|
|
a) \fIheader\fP,
|
|
.TP 3
|
|
b) \fIterminal names\fP,
|
|
.TP 3
|
|
c) \fIBoolean flags\fP,
|
|
.TP 3
|
|
d) \fInumbers\fP,
|
|
.TP 3
|
|
e) \fIstrings\fP, and
|
|
.TP 3
|
|
f) \fIstring table\fP.
|
|
.RE
|
|
.PP
|
|
The \fIheader\fP section begins the file.
|
|
This section contains six short integers in the format
|
|
described below.
|
|
These integers are
|
|
.RS 5
|
|
.TP 5
|
|
(1) the \fImagic number\fP (octal 0432);
|
|
.TP 5
|
|
(2) the size, in bytes, of the \fIterminal names\fP section;
|
|
.TP 5
|
|
(3) the number of bytes in the \fIBoolean flags\fP section;
|
|
.TP 5
|
|
(4) the number of short integers in the \fInumbers\fP section;
|
|
.TP 5
|
|
(5) the number of offsets (short integers) in the \fIstrings\fP section;
|
|
.TP 5
|
|
(6) the size, in bytes, of the \fIstring table\fP.
|
|
.RE
|
|
.PP
|
|
The capabilities in the
|
|
\fIBoolean flags\fP,
|
|
\fInumbers\fP, and
|
|
\fIstrings\fP
|
|
sections are in the same order as the file <term.h>.
|
|
.PP
|
|
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 \s-1VAX\s+1
|
|
and \s-1PDP\s+1-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.
|
|
.PP
|
|
Numbers in a terminal description,
|
|
whether they are entries in the \fInumbers\fP or \fIstrings\fP 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:
|
|
.bP
|
|
If a capability is absent from this terminal,
|
|
@TIC@ stores a \-1 in the corresponding table.
|
|
.IP
|
|
The integer value \-1 is represented by two bytes 0377, 0377.
|
|
.br
|
|
Absent Boolean values are represented by the byte 0 (false).
|
|
.bP
|
|
If a capability has been canceled from this terminal,
|
|
@TIC@ stores a \-2 in the corresponding table.
|
|
.IP
|
|
The integer value \-2 is represented by two bytes 0377, 0376.
|
|
.br
|
|
The Boolean value \-2 is represented by the byte 0376.
|
|
.br
|
|
.bP
|
|
Other negative values are illegal.
|
|
.PP
|
|
The \fIterminal names\fP section comes after the \fIheader\fP.
|
|
It contains the first line of the terminfo description,
|
|
listing the various names for the terminal,
|
|
separated by the \*(``|\*('' character.
|
|
The \fIterminal names\fP section is terminated
|
|
with an \s-1ASCII NUL\s+1 character.
|
|
.PP
|
|
The \fIBoolean flags\fP 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.
|
|
.PP
|
|
Between the \fIBoolean flags\fP section and the \fInumber\fP section,
|
|
a null byte will be inserted, if necessary,
|
|
to ensure that the \fInumber\fP 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.
|
|
.PP
|
|
The \fInumbers\fP section is similar to the \fIBoolean flags\fP section.
|
|
Each capability takes up two bytes,
|
|
and is stored as a little-endian short integer.
|
|
.PP
|
|
The \fIstrings\fP section is also similar.
|
|
Each capability is stored as a short integer.
|
|
The capability value is an index into the \fIstring table\fP.
|
|
.PP
|
|
The \fIstring table\fP is the last section.
|
|
It contains all of the values of string capabilities referenced in
|
|
the \fIstrings\fP section.
|
|
Each string is null-terminated.
|
|
Special characters in \*^X or \ec notation are stored in their
|
|
interpreted form, not the printing representation.
|
|
Padding information $<nn> and parameter information %x are
|
|
stored intact in uninterpreted form.
|
|
.SS "Extended Storage Format"
|
|
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.
|
|
.PP
|
|
The \fI\%ncurses\fP 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.
|
|
\fI\%ncurses\fP checks the size,
|
|
and if it exceeds that due to the predefined data,
|
|
continues to parse according to its own scheme.
|
|
.PP
|
|
First, it reads the extended header (5 short integers):
|
|
.RS 5
|
|
.TP 5
|
|
(1)
|
|
count of extended Boolean capabilities
|
|
.TP 5
|
|
(2)
|
|
count of extended numeric capabilities
|
|
.TP 5
|
|
(3)
|
|
count of extended string capabilities
|
|
.TP 5
|
|
(4)
|
|
count of the items in extended string table
|
|
.TP 5
|
|
(5)
|
|
size of the extended string table in bytes
|
|
.RE
|
|
.PP
|
|
The count- and size-values for the extended string table
|
|
include the extended capability \fInames\fP as well as
|
|
extended capability \fIvalues\fP.
|
|
.PP
|
|
Using the counts and sizes,
|
|
\fI\%ncurses\fP allocates arrays and reads data for the extended
|
|
capabilities in the same order as the header information.
|
|
.PP
|
|
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.
|
|
.PP
|
|
By storing terminal descriptions in this way,
|
|
\fI\%ncurses\fP is able to provide a database useful with legacy
|
|
applications,
|
|
as well as providing data for applications which need more than the
|
|
predefined capabilities.
|
|
See \fBuser_caps\fP(5) for an overview
|
|
of the way \fI\%ncurses\fP uses this extended information.
|
|
.PP
|
|
Applications which manipulate terminal data can use the definitions
|
|
described in \fBterm_variables\fP(3X) which associate the long capability
|
|
names with members of a \fBTERMTYPE\fP structure.
|
|
.
|
|
.SS "Extended Number Format"
|
|
On occasion, 16-bit signed integers are not large enough.
|
|
With \fI\%ncurses\fP 6.1,
|
|
a new format was introduced by making a few changes
|
|
to the legacy format:
|
|
.bP
|
|
a different magic number (octal 01036)
|
|
.bP
|
|
changing the type for the \fInumber\fP array from signed 16-bit integers
|
|
to signed 32-bit integers.
|
|
.PP
|
|
To maintain compatibility, the library presents the same data structures
|
|
to direct users of the \fBTERMTYPE\fP structure as in previous formats.
|
|
However, that cannot provide callers with the extended numbers.
|
|
The library uses a similar but hidden data structure \fBTERMTYPE2\fP
|
|
to provide data for the terminfo functions.
|
|
.SH FILES
|
|
.TP
|
|
.I \*d
|
|
compiled terminal description database
|
|
.SH PORTABILITY
|
|
.SS setupterm
|
|
Note that it is possible for
|
|
.B setupterm
|
|
to expect a different set of capabilities
|
|
than are actually present in the file.
|
|
Either the database may have been updated since
|
|
.B setupterm
|
|
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
|
|
.B setupterm
|
|
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.
|
|
.SS "Binary Format"
|
|
X/Open Curses does not specify a format for the terminfo database.
|
|
System V curses used a directory-tree of binary files,
|
|
one per terminal description.
|
|
.PP
|
|
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 X/Open Curses extensions.
|
|
See \fBterminfo\fP(5) for detailed
|
|
discussion of terminfo source compatibility issues.
|
|
.PP
|
|
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 \fI\%ncurses\fP
|
|
with different configuration options.
|
|
.SS "Magic Codes"
|
|
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 \fBfile\fP(1) 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 \fBscr_dump\fP(5)).
|
|
This implementation uses 01036 as a continuation of that sequence,
|
|
but with a different high-order byte to avoid confusion.
|
|
.SS "The \fITERMTYPE\fP Structure"
|
|
Direct access to the \fBTERMTYPE\fP structure is provided for legacy
|
|
applications.
|
|
Portable applications should use the \fBtigetflag\fP and related functions
|
|
described in \fBcurs_terminfo\fP(3X) for reading terminal capabilities.
|
|
.SS "Mixed-case Terminal Names"
|
|
A small number of terminal descriptions use uppercase characters in
|
|
their names.
|
|
If the underlying filesystem ignores the difference between
|
|
uppercase and lowercase,
|
|
\fI\%ncurses\fP represents the \*(``first character\*(''
|
|
of the terminal name used as
|
|
the intermediate level of a directory tree in (two-character) hexadecimal form.
|
|
.SS Limits
|
|
\fI\%ncurses\fP stores compiled terminal descriptions
|
|
in three related formats,
|
|
described in the sections
|
|
.bP
|
|
\fBLEGACY STORAGE FORMAT\fP, and
|
|
.bP
|
|
\fBEXTENDED STORAGE FORMAT\fP, and
|
|
.bP
|
|
\fBEXTENDED NUMBER FORMAT\fP.
|
|
.PP
|
|
The legacy storage format and the extended number format differ by
|
|
the types of numeric capability which they can store
|
|
(i.e., 16-bit versus 32-bit integers).
|
|
The extended storage format introduced by \fI\%ncurses\fP 5.0 adds data
|
|
to either of these formats.
|
|
.PP
|
|
Some limitations apply:
|
|
.bP
|
|
total compiled entries cannot exceed 4096 bytes in the legacy format.
|
|
.bP
|
|
total compiled entries cannot exceed 32768 bytes in the extended format.
|
|
.bP
|
|
the name field cannot exceed 128 bytes.
|
|
.PP
|
|
Compiled entries are limited to 32768 bytes because offsets into the
|
|
\fIstrings table\fP use two-byte integers.
|
|
The legacy format could have supported 32768-byte entries,
|
|
but was limited to a virtual memory page's 4096 bytes.
|
|
.SH EXAMPLES
|
|
As an example, here is a description for the Lear-Siegler
|
|
ADM\-3, a popular though rather stupid early terminal:
|
|
.PP
|
|
.EX
|
|
adm3a|lsi adm3a,
|
|
am,
|
|
cols#80, lines#24,
|
|
bel=\*^G, clear=\e032$<1>, cr=\*^M, cub1=\*^H, cud1=\*^J,
|
|
cuf1=\*^L, cup=\eE=%p1%{32}%+%c%p2%{32}%+%c, cuu1=\*^K,
|
|
home=\*^\*^, ind=\*^J,
|
|
.EE
|
|
.PP
|
|
and a hexadecimal dump of the compiled terminal description:
|
|
.PP
|
|
.if t .in +4n
|
|
.ft \*(CW
|
|
.TS
|
|
Lp-1.
|
|
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 ........ .
|
|
.TE
|
|
.ft
|
|
.in
|
|
.SH AUTHORS
|
|
Thomas E. Dickey
|
|
.br
|
|
extended terminfo format for \fI\%ncurses\fP 5.0
|
|
.br
|
|
hashed database support for \fI\%ncurses\fP 5.6
|
|
.br
|
|
extended number support for \fI\%ncurses\fP 6.1
|
|
.sp
|
|
Eric S. Raymond
|
|
.br
|
|
documented legacy terminfo format, e.g., from \fIpcurses\fP.
|
|
.SH SEE ALSO
|
|
\fB\%curses\fP(3X),
|
|
\fB\%curs_terminfo\fP(3X),
|
|
\fB\%terminfo\fP(5),
|
|
\fB\%user_caps\fP(5)
|