| 1 | .\"***************************************************************************
|
|---|
| 2 | .\" Copyright (c) 1998-2003,2004 Free Software Foundation, Inc. *
|
|---|
| 3 | .\" *
|
|---|
| 4 | .\" Permission is hereby granted, free of charge, to any person obtaining a *
|
|---|
| 5 | .\" copy of this software and associated documentation files (the *
|
|---|
| 6 | .\" "Software"), to deal in the Software without restriction, including *
|
|---|
| 7 | .\" without limitation the rights to use, copy, modify, merge, publish, *
|
|---|
| 8 | .\" distribute, distribute with modifications, sublicense, and/or sell *
|
|---|
| 9 | .\" copies of the Software, and to permit persons to whom the Software is *
|
|---|
| 10 | .\" furnished to do so, subject to the following conditions: *
|
|---|
| 11 | .\" *
|
|---|
| 12 | .\" The above copyright notice and this permission notice shall be included *
|
|---|
| 13 | .\" in all copies or substantial portions of the Software. *
|
|---|
| 14 | .\" *
|
|---|
| 15 | .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|---|
| 16 | .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|---|
| 17 | .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|---|
| 18 | .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|---|
| 19 | .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|---|
| 20 | .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|---|
| 21 | .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|---|
| 22 | .\" *
|
|---|
| 23 | .\" Except as contained in this notice, the name(s) of the above copyright *
|
|---|
| 24 | .\" holders shall not be used in advertising or otherwise to promote the *
|
|---|
| 25 | .\" sale, use or other dealings in this Software without prior written *
|
|---|
| 26 | .\" authorization. *
|
|---|
| 27 | .\"***************************************************************************
|
|---|
| 28 | .\"
|
|---|
| 29 | .\" $Id: term.5,v 1.16 2004/07/05 13:16:08 tom Exp $
|
|---|
| 30 | .TH TERM 5
|
|---|
| 31 | .ds n 5
|
|---|
| 32 | .ds d @TERMINFO@
|
|---|
| 33 | .SH NAME
|
|---|
| 34 | term \- format of compiled term file.
|
|---|
| 35 | .SH SYNOPSIS
|
|---|
| 36 | .B term
|
|---|
| 37 | .SH DESCRIPTION
|
|---|
| 38 | .PP
|
|---|
| 39 | Compiled terminfo descriptions are placed under the directory \fB\*d\fP.
|
|---|
| 40 | In order to avoid a linear search of a huge \s-1UNIX\s+1 system directory, a
|
|---|
| 41 | two-level scheme is used: \fB\*d/c/name\fP
|
|---|
| 42 | where
|
|---|
| 43 | .I name
|
|---|
| 44 | is the name of the terminal, and
|
|---|
| 45 | .I c
|
|---|
| 46 | is the first character of
|
|---|
| 47 | .IR name .
|
|---|
| 48 | Thus,
|
|---|
| 49 | .I act4
|
|---|
| 50 | can be found in the file \fB\*d/a/act4\fP.
|
|---|
| 51 | Synonyms for the same terminal are implemented by multiple
|
|---|
| 52 | links to the same compiled file.
|
|---|
| 53 | .PP
|
|---|
| 54 | The format has been chosen so that it will be the same on all hardware.
|
|---|
| 55 | An 8 or more bit byte is assumed, but no assumptions about byte ordering
|
|---|
| 56 | or sign extension are made.
|
|---|
| 57 | .PP
|
|---|
| 58 | The compiled file is created with the
|
|---|
| 59 | .I tic
|
|---|
| 60 | program, and read by the routine
|
|---|
| 61 | .IR setupterm .
|
|---|
| 62 | The file is divided into six parts:
|
|---|
| 63 | the header,
|
|---|
| 64 | terminal names,
|
|---|
| 65 | boolean flags,
|
|---|
| 66 | numbers,
|
|---|
| 67 | strings,
|
|---|
| 68 | and
|
|---|
| 69 | string table.
|
|---|
| 70 | .PP
|
|---|
| 71 | The header section begins the file.
|
|---|
| 72 | This section contains six short integers in the format
|
|---|
| 73 | described below.
|
|---|
| 74 | These integers are
|
|---|
| 75 | (1) the magic number (octal 0432);
|
|---|
| 76 | (2) the size, in bytes, of the names section;
|
|---|
| 77 | (3) the number of bytes in the boolean section;
|
|---|
| 78 | (4) the number of short integers in the numbers section;
|
|---|
| 79 | (5) the number of offsets (short integers) in the strings section;
|
|---|
| 80 | (6) the size, in bytes, of the string table.
|
|---|
| 81 | .PP
|
|---|
| 82 | Short integers are stored in two 8-bit bytes.
|
|---|
| 83 | The first byte contains the least significant 8 bits of the value,
|
|---|
| 84 | and the second byte contains the most significant 8 bits.
|
|---|
| 85 | (Thus, the value represented is 256*second+first.)
|
|---|
| 86 | The value -1 is represented by the two bytes 0377, 0377; other negative
|
|---|
| 87 | values are illegal. This value generally
|
|---|
| 88 | means that the corresponding capability is missing from this terminal.
|
|---|
| 89 | Note that this format corresponds to the hardware of the \s-1VAX\s+1
|
|---|
| 90 | and \s-1PDP\s+1-11 (that is, little-endian machines).
|
|---|
| 91 | Machines where this does not correspond to the hardware must read the
|
|---|
| 92 | integers as two bytes and compute the little-endian value.
|
|---|
| 93 | .PP
|
|---|
| 94 | The terminal names section comes next.
|
|---|
| 95 | It contains the first line of the terminfo description,
|
|---|
| 96 | listing the various names for the terminal,
|
|---|
| 97 | separated by the `|' character.
|
|---|
| 98 | The section is terminated with an \s-1ASCII NUL\s+1 character.
|
|---|
| 99 | .PP
|
|---|
| 100 | The boolean flags have one byte for each flag.
|
|---|
| 101 | This byte is either 0 or 1 as the flag is present or absent.
|
|---|
| 102 | The capabilities are in the same order as the file <term.h>.
|
|---|
| 103 | .PP
|
|---|
| 104 | Between the boolean section and the number section,
|
|---|
| 105 | a null byte will be inserted, if necessary,
|
|---|
| 106 | to ensure that the number section begins on an even byte (this is a
|
|---|
| 107 | relic of the PDP-11's word-addressed architecture, originally
|
|---|
| 108 | designed in to avoid IOT traps induced by addressing a word on an
|
|---|
| 109 | odd byte boundary).
|
|---|
| 110 | All short integers are aligned on a short word boundary.
|
|---|
| 111 | .PP
|
|---|
| 112 | The numbers section is similar to the flags section.
|
|---|
| 113 | Each capability takes up two bytes,
|
|---|
| 114 | and is stored as a little-endian short integer.
|
|---|
| 115 | If the value represented is -1, the capability is taken to be missing.
|
|---|
| 116 | .PP
|
|---|
| 117 | The strings section is also similar.
|
|---|
| 118 | Each capability is stored as a short integer, in the format above.
|
|---|
| 119 | A value of -1 means the capability is missing.
|
|---|
| 120 | Otherwise, the value is taken as an offset from the beginning
|
|---|
| 121 | of the string table.
|
|---|
| 122 | Special characters in ^X or \ec notation are stored in their
|
|---|
| 123 | interpreted form, not the printing representation.
|
|---|
| 124 | Padding information $<nn> and parameter information %x are
|
|---|
| 125 | stored intact in uninterpreted form.
|
|---|
| 126 | .PP
|
|---|
| 127 | The final section is the string table.
|
|---|
| 128 | It contains all the values of string capabilities referenced in
|
|---|
| 129 | the string section.
|
|---|
| 130 | Each string is null terminated.
|
|---|
| 131 | .PP
|
|---|
| 132 | Note that it is possible for
|
|---|
| 133 | .I setupterm
|
|---|
| 134 | to expect a different set of capabilities
|
|---|
| 135 | than are actually present in the file.
|
|---|
| 136 | Either the database may have been updated since
|
|---|
| 137 | .I setupterm
|
|---|
| 138 | has been recompiled
|
|---|
| 139 | (resulting in extra unrecognized entries in the file)
|
|---|
| 140 | or the program may have been recompiled more recently
|
|---|
| 141 | than the database was updated
|
|---|
| 142 | (resulting in missing entries).
|
|---|
| 143 | The routine
|
|---|
| 144 | .I setupterm
|
|---|
| 145 | must be prepared for both possibilities \-
|
|---|
| 146 | this is why the numbers and sizes are included.
|
|---|
| 147 | Also, new capabilities must always be added at the end of the lists
|
|---|
| 148 | of boolean, number, and string capabilities.
|
|---|
| 149 | .PP
|
|---|
| 150 | Despite the consistent use of little-endian for numbers and the otherwise
|
|---|
| 151 | self-describing format, it is not wise to count on portability of binary
|
|---|
| 152 | terminfo entries between commercial UNIX versions. The problem is that there
|
|---|
| 153 | are at least three versions of terminfo (under HP-UX, AIX, and OSF/1) which
|
|---|
| 154 | diverged from System V terminfo after SVr1, and have added extension
|
|---|
| 155 | capabilities to the string table that (in the binary format) collide with
|
|---|
| 156 | System V and XSI Curses extensions. See \fBterminfo\fR(\*n) for detailed
|
|---|
| 157 | discussion of terminfo source compatibility issues.
|
|---|
| 158 | .PP
|
|---|
| 159 | As an example, here is a hex dump of the description for the Lear-Siegler
|
|---|
| 160 | ADM-3, a popular though rather stupid early terminal:
|
|---|
| 161 | .nf
|
|---|
| 162 | .sp
|
|---|
| 163 | adm3a|lsi adm3a,
|
|---|
| 164 | am,
|
|---|
| 165 | cols#80, lines#24,
|
|---|
| 166 | bel=^G, clear=\032$<1>, cr=^M, cub1=^H, cud1=^J,
|
|---|
| 167 | cuf1=^L, cup=\\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
|
|---|
| 168 | home=^^, ind=^J,
|
|---|
| 169 | .sp
|
|---|
| 170 | .ft CW
|
|---|
| 171 | \s-20000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3
|
|---|
| 172 | 0010 61 7c 6c 73 69 20 61 64 6d 33 61 00 00 01 50 00 a|lsi ad m3a...P.
|
|---|
| 173 | 0020 ff ff 18 00 ff ff 00 00 02 00 ff ff ff ff 04 00 ........ ........
|
|---|
| 174 | 0030 ff ff ff ff ff ff ff ff 0a 00 25 00 27 00 ff ff ........ ..%.'...
|
|---|
| 175 | 0040 29 00 ff ff ff ff 2b 00 ff ff 2d 00 ff ff ff ff ).....+. ..-.....
|
|---|
| 176 | 0050 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 177 | 0060 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 178 | 0070 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 179 | 0080 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 180 | 0090 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 181 | 00a0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 182 | 00b0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 183 | 00c0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 184 | 00d0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 185 | 00e0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 186 | 00f0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 187 | 0100 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 188 | 0110 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........
|
|---|
| 189 | 0120 ff ff ff ff ff ff 2f 00 07 00 0d 00 1a 24 3c 31 ....../. .....$<1
|
|---|
| 190 | 0130 3e 00 1b 3d 25 70 31 25 7b 33 32 7d 25 2b 25 63 >..=%p1% {32}%+%c
|
|---|
| 191 | 0140 25 70 32 25 7b 33 32 7d 25 2b 25 63 00 0a 00 1e %p2%{32} %+%c....
|
|---|
| 192 | 0150 00 08 00 0c 00 0b 00 0a 00 ........ .\s+2
|
|---|
| 193 | .ft R
|
|---|
| 194 | .fi
|
|---|
| 195 | .sp
|
|---|
| 196 | .PP
|
|---|
| 197 | Some limitations: total compiled entries cannot exceed 4096 bytes.
|
|---|
| 198 | The name field cannot exceed 128 bytes.
|
|---|
| 199 | .SH FILES
|
|---|
| 200 | \*d/*/* compiled terminal capability data base
|
|---|
| 201 | .SH SEE ALSO
|
|---|
| 202 | \fBcurses\fR(3X), \fBterminfo\fR(\*n).
|
|---|
| 203 | .\"#
|
|---|
| 204 | .\"# The following sets edit modes for GNU EMACS
|
|---|
| 205 | .\"# Local Variables:
|
|---|
| 206 | .\"# mode:nroff
|
|---|
| 207 | .\"# fill-column:79
|
|---|
| 208 | .\"# End:
|
|---|
