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