ncurses 5.7 - patch 20100918
[ncurses.git] / doc / html / man / term.5.html
index a0c144cc7ed20b1de9489ecd29c2d42e77f6c59b..47aca858d7f849c0a56aadea5030deb2445f22b4 100644 (file)
@@ -1,7 +1,7 @@
 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
 <!-- 
   ****************************************************************************
-  * Copyright (c) 1998-2002,2003 Free Software Foundation, Inc.              *
+  * Copyright (c) 1998-2006,2010 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            *
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: term.5,v 1.15 2003/05/10 20:33:49 jmc Exp @
+  * @Id: term.5,v 1.20 2010/07/31 16:13:27 tom Exp @
 -->
 <HTML>
 <HEAD>
-<TITLE>TERM 5</TITLE>
+<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>TERM 5</H1>
+<H1>term 5</H1>
 <HR>
 <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>
+<STRONG><A HREF="term.5.html">term(5)</A></STRONG>                                                         <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
 
 
 
 
 </PRE>
 <H2>DESCRIPTION</H2><PRE>
+   <STRONG>STORAGE</STRONG> <STRONG>LOCATION</STRONG>
        Compiled terminfo descriptions are placed under the direc-
-       tory <STRONG>/usr/share/terminfo</STRONG>.  In  order  to  avoid  a  linear
-       search of a huge UNIX system directory, a two-level scheme
-       is used: <STRONG>/usr/share/terminfo/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/ter-</STRONG>
-       <STRONG>minfo/a/act4</STRONG>.   Synonyms  for the same terminal are imple-
-       mented by multiple links to the same compiled file.
-
+       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.
+
+   <STRONG>STORAGE</STRONG> <STRONG>FORMAT</STRONG>
        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 <EM>tic</EM> program, and
+       The  compiled  file  is  created with the <STRONG>tic</STRONG> program, and
        read by the routine <EM>setupterm</EM>.  The file is  divided  into
        six parts: the header, terminal names, boolean flags, num-
        bers, 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 &lt;term.h&gt;.
 
        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 $&lt;nn&gt; 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.
 
+   <STRONG>EXTENDED</STRONG> <STRONG>STORAGE</STRONG> <STRONG>FORMAT</STRONG>
+       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 capabilties 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>PORTABILITY</H2><PRE>
        Note that it is possible for <EM>setupterm</EM> to expect a differ-
        ent  set  of capabilities than are actually present in the
        file.  Either the database may  have  been  updated  since
        Curses extensions.  See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for  detailed  discus-
        sion of terminfo source compatibility issues.
 
+
+</PRE>
+<H2>EXAMPLE</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:
        0150  00 08 00 0c 00 0b 00 0a  00                       ........ .
 
 
+
+</PRE>
+<H2>LIMITS</H2><PRE>
        Some  limitations:  total  compiled  entries cannot exceed
        4096 bytes.  The name field cannot exceed 128 bytes.
 
        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 
 
+</PRE>
+<H2>AUTHORS</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>
+                                                                <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
 </PRE>
 <HR>
 <ADDRESS>