doc/html/man/term.5.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2019,2020 Thomas E. Dickey                                *
   4   * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: term.5,v 1.38 2020/07/25 21:56:02 tom Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>term 5</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">term 5</H1>
  43 <PRE>
  44 <STRONG><A HREF="term.5.html">term(5)</A></STRONG>                       File Formats Manual                      <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        term - format of compiled term file.
  51
  52
  53 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  54        <STRONG>term</STRONG>
  55
  56
  57 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  58
  59 </PRE><H3><a name="h3-STORAGE-LOCATION">STORAGE LOCATION</a></H3><PRE>
  60        Compiled   terminfo   descriptions   are  placed  under  the  directory
  61        <STRONG>/usr/local/ncurses/lib/terminfo</STRONG>.   Two  configurations  are   supported
  62        (when building the <STRONG>ncurses</STRONG> libraries):
  63
  64        <STRONG>directory</STRONG> <STRONG>tree</STRONG>
  65             A two-level scheme is used to avoid a linear search of a huge UNIX
  66             system  directory:  <STRONG>/usr/local/ncurses/lib/terminfo/c/name</STRONG>   where
  67             <EM>name</EM>  is the name of the terminal, and <EM>c</EM> is the first character of
  68             <EM>name</EM>.     Thus,    <EM>act4</EM>    can    be    found    in    the    file
  69             <STRONG>/usr/local/ncurses/lib/terminfo/a/act4</STRONG>.   Synonyms  for  the  same
  70             terminal are implemented by multiple links to  the  same  compiled
  71             file.
  72
  73        <STRONG>hashed</STRONG> <STRONG>database</STRONG>
  74             Using Berkeley database, two types of records are stored: the ter-
  75             minfo data in the same format as stored in a directory  tree  with
  76             the  terminfo's primary name as a key, and records containing only
  77             aliases pointing to the primary name.
  78
  79             If built to write hashed databases, <STRONG>ncurses</STRONG> can  still  read  ter-
  80             minfo  databases  organized  as a directory tree, but cannot write
  81             entries into the  directory  tree.   It  can  write  (or  rewrite)
  82             entries in the hashed database.
  83
  84             <STRONG>ncurses</STRONG>  distinguishes  the  two  cases  in  the TERMINFO and TER-
  85             MINFO_DIRS environment variable by assuming a directory  tree  for
  86             entries that correspond to an existing directory, and hashed data-
  87             base otherwise.
  88
  89
  90 </PRE><H3><a name="h3-LEGACY-STORAGE-FORMAT">LEGACY STORAGE FORMAT</a></H3><PRE>
  91        The format has been chosen so that it will be the same on all hardware.
  92        An  8 or more bit byte is assumed, but no assumptions about byte order-
  93        ing or sign extension are made.
  94
  95        The compiled file is created with the <STRONG>tic</STRONG> program, and read by the rou-
  96        tine <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>.  The file is divided into six parts:
  97
  98             a) <EM>header</EM>,
  99
 100             b) <EM>terminal</EM> <EM>names</EM>,
 101
 102             c) <EM>boolean</EM> <EM>flags</EM>,
 103
 104             d) <EM>numbers</EM>,
 105
 106             e) <EM>strings</EM>, and
 107
 108             f) <EM>string</EM> <EM>table</EM>.
 109
 110        The  <EM>header</EM>  section  begins the file.  This section contains six short
 111        integers in the format described below.  These integers are
 112
 113             (1) the <EM>magic</EM> <EM>number</EM> (octal 0432);
 114
 115             (2) the size, in bytes, of the <EM>terminal</EM> <EM>names</EM> section;
 116
 117             (3) the number of bytes in the <EM>boolean</EM> <EM>flags</EM> section;
 118
 119             (4) the number of short integers in the <EM>numbers</EM> section;
 120
 121             (5) the number of offsets (short integers) in the <EM>strings</EM> section;
 122
 123             (6) the size, in bytes, of the <EM>string</EM> <EM>table</EM>.
 124
 125        The capabilities in the <EM>boolean</EM> <EM>flags</EM>, <EM>numbers</EM>,  and  <EM>strings</EM>  sections
 126        are in the same order as the file &lt;term.h&gt;.
 127
 128        Short  integers  are  signed,  in  the range -32768 to 32767.  They are
 129        stored as two 8-bit bytes.  The first byte contains the least  signifi-
 130        cant 8 bits of the value, and the second byte contains the most signif-
 131        icant 8 bits.  (Thus, the value represented is 256*second+first.)  This
 132        format corresponds to the hardware of the VAX and PDP-11 (that is, lit-
 133        tle-endian machines).  Machines where this does not correspond  to  the
 134        hardware  must  read  the integers as two bytes and compute the little-
 135        endian value.
 136
 137        Numbers in a terminal description, whether they are entries in the <EM>num-</EM>
 138        <EM>bers</EM>  or  <EM>strings</EM>  table,  are  positive  integers.   Boolean flags are
 139        treated as positive one-byte integers.  In each  case,  those  positive
 140        integers  represent  a  terminal capability.  The terminal compiler tic
 141        uses negative integers to handle the cases where a  capability  is  not
 142        available:
 143
 144        <STRONG>o</STRONG>   If  a  capability  is absent from this terminal, tic stores a -1 in
 145            the corresponding table.
 146
 147            The integer value -1 is represented by two bytes 0377, 0377.
 148            Absent boolean values are represented by the byte 0 (false).
 149
 150        <STRONG>o</STRONG>   If a capability has been canceled from this terminal, tic stores  a
 151            -2 in the corresponding table.
 152
 153            The integer value -2 is represented by two bytes 0377, 0376.
 154            The boolean value -2 is represented by the byte 0376.
 155
 156        <STRONG>o</STRONG>   Other negative values are illegal.
 157
 158        The  <EM>terminal</EM>  <EM>names</EM>  section  comes after the <EM>header</EM>.  It contains the
 159        first line of the terminfo description, listing the various  names  for
 160        the  terminal, separated by the "|" character.  The <EM>terminal</EM> <EM>names</EM> sec-
 161        tion is terminated with an ASCII NUL character.
 162
 163        The <EM>boolean</EM> <EM>flags</EM> section has one byte for each flag.  Boolean capabil-
 164        ities are either 1 or 0 (true or false) according to whether the termi-
 165        nal supports the given capability or not.
 166
 167        Between the <EM>boolean</EM> <EM>flags</EM> section and the <EM>number</EM> section, a  null  byte
 168        will  be  inserted,  if  necessary,  to  ensure that the <EM>number</EM> section
 169        begins on an even byte This is a relic of the  PDP-11's  word-addressed
 170        architecture,  originally designed to avoid traps induced by addressing
 171        a word on an odd byte boundary.  All short integers are  aligned  on  a
 172        short word boundary.
 173
 174        The  <EM>numbers</EM>  section  is  similar  to the <EM>boolean</EM> <EM>flags</EM> section.  Each
 175        capability takes up two bytes, and is stored as a  little-endian  short
 176        integer.
 177
 178        The  <EM>strings</EM>  section  is also similar.  Each capability is stored as a
 179        short integer.  The capability value is an index into the <EM>string</EM> <EM>table</EM>.
 180
 181        The <EM>string</EM> <EM>table</EM> is the last section.  It contains all of the values of
 182        string  capabilities referenced in the <EM>strings</EM> section.  Each string is
 183        null-terminated.  Special characters in ^X or \c notation are stored in
 184        their  interpreted  form,  not  the  printing  representation.  Padding
 185        information $&lt;nn&gt; and parameter information %x  are  stored  intact  in
 186        uninterpreted form.
 187
 188
 189 </PRE><H3><a name="h3-EXTENDED-STORAGE-FORMAT">EXTENDED STORAGE FORMAT</a></H3><PRE>
 190        The previous section describes the conventional terminfo binary format.
 191        With some minor variations of the offsets (see PORTABILITY),  the  same
 192        binary  format  is used in all modern UNIX systems.  Each system uses a
 193        predefined set of boolean, number or string capabilities.
 194
 195        The <STRONG>ncurses</STRONG> libraries and applications support extended terminfo binary
 196        format,  allowing users to define capabilities which are loaded at run-
 197        time.  This extension is made possible by using the fact that the other
 198        implementations  stop  reading the terminfo data when they have reached
 199        the end of the size given in the header.  <STRONG>ncurses</STRONG> checks the size,  and
 200        if  it  exceeds  that  due  to  the predefined data, continues to parse
 201        according to its own scheme.
 202
 203        First, it reads the extended header (5 short integers):
 204
 205             (1)  count of extended boolean capabilities
 206
 207             (2)  count of extended numeric capabilities
 208
 209             (3)  count of extended string capabilities
 210
 211             (4)  count of the items in extended string table
 212
 213             (5)  size of the extended string table in bytes
 214
 215        The count- and size-values for the extended string  table  include  the
 216        extended capability <EM>names</EM> as well as extended capability <EM>values</EM>.
 217
 218        Using the counts and sizes, <STRONG>ncurses</STRONG> allocates arrays and reads data for
 219        the extended capabilities in the same order as the header information.
 220
 221        The extended string table  contains  values  for  string  capabilities.
 222        After  the  end  of these values, it contains the names for each of the
 223        extended capabilities  in  order,  e.g.,  booleans,  then  numbers  and
 224        finally strings.
 225
 226        Applications  which  manipulate  terminal  data can use the definitions
 227        described in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> which  associate  the  long  capability
 228        names with members of a <STRONG>TERMTYPE</STRONG> structure.
 229
 230
 231 </PRE><H3><a name="h3-EXTENDED-NUMBER-FORMAT">EXTENDED NUMBER FORMAT</a></H3><PRE>
 232        On occasion, 16-bit signed integers are not large enough.  With <STRONG>ncurses</STRONG>
 233        6.1, a new format was introduced by making a few changes to the  legacy
 234        format:
 235
 236        <STRONG>o</STRONG>   a different magic number (octal 01036)
 237
 238        <STRONG>o</STRONG>   changing  the type for the <EM>number</EM> array from signed 16-bit integers
 239            to signed 32-bit integers.
 240
 241        To maintain compatibility, the library presents the  same  data  struc-
 242        tures to direct users of the <STRONG>TERMTYPE</STRONG> structure as in previous formats.
 243        However, that cannot provide callers with the  extended  numbers.   The
 244        library  uses  a similar but hidden data structure <STRONG>TERMTYPE2</STRONG> to provide
 245        data for the terminfo functions.
 246
 247
 248 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 249
 250 </PRE><H3><a name="h3-setupterm">setupterm</a></H3><PRE>
 251        Note that it is possible for <STRONG>setupterm</STRONG> to expect  a  different  set  of
 252        capabilities  than  are actually present in the file.  Either the data-
 253        base may have been updated since <STRONG>setupterm</STRONG> has been recompiled (result-
 254        ing  in extra unrecognized entries in the file) or the program may have
 255        been recompiled more recently than the database was updated  (resulting
 256        in  missing  entries).  The routine <STRONG>setupterm</STRONG> must be prepared for both
 257        possibilities - this is why the numbers and sizes are included.   Also,
 258        new  capabilities must always be added at the end of the lists of bool-
 259        ean, number, and string capabilities.
 260
 261
 262 </PRE><H3><a name="h3-Binary-format">Binary format</a></H3><PRE>
 263        X/Open Curses does not specify a  format  for  the  terminfo  database.
 264        UNIX  System  V  curses  used a directory-tree of binary files, one per
 265        terminal description.
 266
 267        Despite the consistent use of little-endian for numbers and the  other-
 268        wise  self-describing format, it is not wise to count on portability of
 269        binary terminfo entries between commercial UNIX versions.  The  problem
 270        is  that  there  are  at least three versions of terminfo (under HP-UX,
 271        AIX, and OSF/1) which diverged from System V terminfo after  SVr1,  and
 272        have  added  extension  capabilities  to  the string table that (in the
 273        binary format) collide with System V and XSI  Curses  extensions.   See
 274        <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>  for  detailed  discussion of terminfo source compatibility
 275        issues.
 276
 277        This implementation is by default compatible with the  binary  terminfo
 278        format  used by Solaris curses, except in a few less-used details where
 279        it was found that the latter did not match X/Open Curses.   The  format
 280        used by the other Unix versions can be matched by building ncurses with
 281        different configuration options.
 282
 283
 284 </PRE><H3><a name="h3-Magic-codes">Magic codes</a></H3><PRE>
 285        The magic number in a binary terminfo file is the  first  16-bits  (two
 286        bytes).   Besides making it more reliable for the library to check that
 287        a file is terminfo, utilities such as <STRONG>file</STRONG> also use that to  tell  what
 288        the  file-format is.  System V defined more than one magic number, with
 289        0433, 0435 as screen-dumps (see <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>).  This implementation uses
 290        01036  as  a  continuation of that sequence, but with a different high-
 291        order byte to avoid confusion.
 292
 293
 294 </PRE><H3><a name="h3-The-TERMTYPE-structure">The TERMTYPE structure</a></H3><PRE>
 295        Direct access to the <STRONG>TERMTYPE</STRONG> structure is provided for legacy applica-
 296        tions.   Portable  applications  should  use  the <STRONG>tigetflag</STRONG> and related
 297        functions described in <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> for reading terminal capabili-
 298        ties.
 299
 300
 301 </PRE><H3><a name="h3-Mixed-case-terminal-names">Mixed-case terminal names</a></H3><PRE>
 302        A  small  number  of  terminal descriptions use uppercase characters in
 303        their names.  If  the  underlying  filesystem  ignores  the  difference
 304        between  uppercase and lowercase, <STRONG>ncurses</STRONG> represents the "first charac-
 305        ter" of the terminal name used as the intermediate level of a directory
 306        tree in (two-character) hexadecimal form.
 307
 308
 309 </PRE><H2><a name="h2-EXAMPLE">EXAMPLE</a></H2><PRE>
 310        As an example, here is a description for the Lear-Siegler ADM-3, a pop-
 311        ular though rather stupid early terminal:
 312
 313            adm3a|lsi adm3a,
 314                    am,
 315                    cols#80, lines#24,
 316                    bel=^G, clear= 32$&lt;1&gt;, cr=^M, cub1=^H, cud1=^J,
 317                    cuf1=^L, cup=\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
 318                    home=^^, ind=^J,
 319
 320
 321        and a hexadecimal dump of the compiled terminal description:
 322
 323            0000  1a 01 10 00 02 00 03 00  82 00 31 00 61 64 6d 33  ........ ..1.adm3
 324            0010  61 7c 6c 73 69 20 61 64  6d 33 61 00 00 01 50 00  a|lsi ad m3a...P.
 325            0020  ff ff 18 00 ff ff 00 00  02 00 ff ff ff ff 04 00  ........ ........
 326            0030  ff ff ff ff ff ff ff ff  0a 00 25 00 27 00 ff ff  ........ ..%.'...
 327            0040  29 00 ff ff ff ff 2b 00  ff ff 2d 00 ff ff ff ff  ).....+. ..-.....
 328            0050  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 329            0060  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 330            0070  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 331            0080  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 332            0090  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 333            00a0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 334            00b0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 335            00c0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 336            00d0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 337            00e0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 338            00f0  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 339            0100  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 340            0110  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  ........ ........
 341            0120  ff ff ff ff ff ff 2f 00  07 00 0d 00 1a 24 3c 31  ....../. .....$&lt;1
 342            0130  3e 00 1b 3d 25 70 31 25  7b 33 32 7d 25 2b 25 63  &gt;..=%p1% {32}%+%c
 343            0140  25 70 32 25 7b 33 32 7d  25 2b 25 63 00 0a 00 1e  %p2%{32} %+%c....
 344            0150  00 08 00 0c 00 0b 00 0a  00                       ........ .
 345
 346
 347
 348 </PRE><H2><a name="h2-LIMITS">LIMITS</a></H2><PRE>
 349        Some limitations:
 350
 351        <STRONG>o</STRONG>   total compiled entries cannot exceed 4096 bytes in the legacy  for-
 352            mat.
 353
 354        <STRONG>o</STRONG>   total  compiled  entries  cannot exceed 32768 bytes in the extended
 355            format.
 356
 357        <STRONG>o</STRONG>   the name field cannot exceed 128 bytes.
 358
 359        Compiled entries are limited to 32768 bytes because  offsets  into  the
 360        <EM>strings</EM> <EM>table</EM> use two-byte integers.  The legacy format could have sup-
 361        ported 32768-byte entries, but was limited a virtual memory page's 4096
 362        bytes.
 363
 364
 365 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
 366        /usr/local/ncurses/lib/terminfo/*/*     compiled   terminal  capability
 367        data base
 368
 369
 370 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 371        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 372
 373
 374 </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
 375        Thomas E. Dickey
 376        extended terminfo format for ncurses 5.0
 377        hashed database support for ncurses 5.6
 378        extended number support for ncurses 6.1
 379
 380        Eric S. Raymond
 381        documented legacy terminfo format, e.g., from pcurses.
 382
 383
 384
 385                                                                        <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
 386 </PRE>
 387 <div class="nav">
 388 <ul>
 389 <li><a href="#h2-NAME">NAME</a></li>
 390 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 391 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 392 <ul>
 393 <li><a href="#h3-STORAGE-LOCATION">STORAGE LOCATION</a></li>
 394 <li><a href="#h3-LEGACY-STORAGE-FORMAT">LEGACY STORAGE FORMAT</a></li>
 395 <li><a href="#h3-EXTENDED-STORAGE-FORMAT">EXTENDED STORAGE FORMAT</a></li>
 396 <li><a href="#h3-EXTENDED-NUMBER-FORMAT">EXTENDED NUMBER FORMAT</a></li>
 397 </ul>
 398 </li>
 399 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 400 <ul>
 401 <li><a href="#h3-setupterm">setupterm</a></li>
 402 <li><a href="#h3-Binary-format">Binary format</a></li>
 403 <li><a href="#h3-Magic-codes">Magic codes</a></li>
 404 <li><a href="#h3-The-TERMTYPE-structure">The TERMTYPE structure</a></li>
 405 <li><a href="#h3-Mixed-case-terminal-names">Mixed-case terminal names</a></li>
 406 </ul>
 407 </li>
 408 <li><a href="#h2-EXAMPLE">EXAMPLE</a></li>
 409 <li><a href="#h2-LIMITS">LIMITS</a></li>
 410 <li><a href="#h2-FILES">FILES</a></li>
 411 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 412 <li><a href="#h2-AUTHORS">AUTHORS</a></li>
 413 </ul>
 414 </div>
 415 </BODY>
 416 </HTML>