ncurses 5.9 - patch 20150214
[ncurses.git] / doc / html / man / tic.1m.html
index 6539e200af5ee007b0e52f058f4beb797435c536..a45e6e9def41d2ceb3f729c57cb238a29cefc0c7 100644 (file)
@@ -1,7 +1,6 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
 <!-- 
   ****************************************************************************
-  * Copyright (c) 1998-2010,2011 Free Software Foundation, Inc.              *
+  * Copyright (c) 1998-2013,2014 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: tic.1m,v 1.53 2011/12/17 23:13:19 tom Exp @
+  * @Id: tic.1m,v 1.60 2014/05/24 22:00:11 tom Exp @
 -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 <HEAD>
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+<meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
 <TITLE>tic 1m</TITLE>
 <link rev=made href="mailto:bug-ncurses@gnu.org">
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 <H1>tic 1m</H1>
 <HR>
 <PRE>
-<!-- Manpage converted by man2html 3.0.1 -->
 <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>                                                         <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>
 
 
 
 
 </PRE>
-<H2>NAME</H2><PRE>
+<H2><a name="h2-NAME">NAME</a></H2><PRE>
        <STRONG>tic</STRONG> - the <EM>terminfo</EM> entry-description compiler
 
 
 </PRE>
-<H2>SYNOPSIS</H2><PRE>
+<H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
        <STRONG>tic</STRONG>  [<STRONG>-01CDGIKLNTUVacfgrstx</STRONG>]  [<STRONG>-e</STRONG> <EM>names</EM>] [<STRONG>-o</STRONG> <EM>dir</EM>] [<STRONG>-R</STRONG> <EM>sub-</EM>
        <EM>set</EM>] [<STRONG>-v</STRONG>[<EM>n</EM>]] [<STRONG>-w</STRONG>[<EM>n</EM>]] <EM>file</EM>
 
 
 </PRE>
-<H2>DESCRIPTION</H2><PRE>
+<H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
        The <STRONG>tic</STRONG> command translates a  <STRONG>terminfo</STRONG>  file  from  source
        format  into compiled format.  The compiled format is nec-
        essary for use with the library routines in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
 
        As described in <STRONG><A HREF="term.5.html">term(5)</A></STRONG>, the  database  may  be  either  a
        directory  tree  (one file per terminal entry) or a hashed
-       database (one record per entry).  The <STRONG>tic</STRONG> writes only  one
-       type of entry, depending on how it was built:
+       database (one record per entry).  The <STRONG>tic</STRONG>  command  writes
+       only one type of entry, depending on how it was built:
 
        <STRONG>o</STRONG>   For  directory  trees,  the top-level directory, e.g.,
            /usr/share/terminfo, specifies  the  location  of  the
            as the default directory name  (only  adding  a  ".db"
            suffix).
 
-       The  results  are  normally  placed in the system terminfo
-       database  <STRONG>/usr/share/terminfo</STRONG>.   The   compiled   terminal
-       description   can   be  placed  in  a  different  terminfo
-       database.  There are two ways to achieve this:
+       In  either  case  (directory or hashed database), <STRONG>tic</STRONG> will
+       create the container if it does not exist.  For  a  direc-
+       tory,  this  would  be the "terminfo" leaf, versus a "ter-
+       minfo.db" file.
 
-       <STRONG>o</STRONG>   First, you may override the system default by  setting
-           the  variable  <STRONG>TERMINFO</STRONG> in your shell environment to a
-           valid database location, e.g., an  existing  directory
-           (for  directory  trees) or valid location for a hashed
-           database.
+       The results are normally placed  in  the  system  terminfo
+       database   <STRONG>/usr/share/terminfo</STRONG>.    The  compiled  terminal
+       description can be placed in a  different  terminfo  data-
+       base.  There are two ways to achieve this:
+
+       <STRONG>o</STRONG>   First,  you  may override the system default either by
+           using the <STRONG>-o</STRONG> option, or by setting the  variable  <STRONG>TER-</STRONG>
+           <STRONG>MINFO</STRONG>  in  your  shell environment to a valid database
+           location.
 
        <STRONG>o</STRONG>   Secondly, if <STRONG>tic</STRONG> cannot write  in  <EM>/usr/share/terminfo</EM>
            or  the  location  specified using your TERMINFO vari-
            exists, the entry is placed there.
 
        Libraries that read terminfo entries are expected to check
-       for a location specified with the TERMINFO variable first,
-       look at  <EM>$HOME/.terminfo</EM>  if  TERMINFO  is  not  set,  and
-       finally look in <EM>/usr/share/terminfo</EM>.
+       in succession
+
+       <STRONG>o</STRONG>   a  location  specified  with  the TERMINFO environment
+           variable,
+
+       <STRONG>o</STRONG>   <EM>$HOME/.terminfo</EM>,
+
+       <STRONG>o</STRONG>   directories listed in  the  TERMINFO_DIRS  environment
+           variable,
+
+       <STRONG>o</STRONG>   a       compiled-in      list      of      directories
+           (/usr/local/ncurses/share/terminfo:/usr/share/ter-
+           minfo), and
+
+       <STRONG>o</STRONG>   the system terminfo database (<EM>/usr/share/terminfo</EM>).
+
 
+</PRE>
+<H3><a name="h3-OPTIONS">OPTIONS</a></H3><PRE>
        <STRONG>-0</STRONG>     restricts the output to a single line
 
        <STRONG>-1</STRONG>     restricts the output to a single column
               stricter BSD-compatible  translation,  add  the  <STRONG>-K</STRONG>
               option.
 
-       <STRONG>-c</STRONG>     tells  <STRONG>tic</STRONG> to only check <EM>file</EM> for errors, including
-              syntax problems and bad use links.  If you  specify
+              If  this  is combined with <STRONG>-c</STRONG>, <STRONG>tic</STRONG> makes additional
+              checks to report cases where the terminfo values do
+              not  have an exact equivalent in termcap form.  For
+              example:
+
+              <STRONG>o</STRONG>   <STRONG>sgr</STRONG> usually will not convert,  because  termcap
+                  lacks  the  ability  to work with more than two
+                  parameters, and because termcap lacks  many  of
+                  the  arithmetic/logical  operators used in ter-
+                  minfo.
+
+              <STRONG>o</STRONG>   capabilities with more than one delay  or  with
+                  delays  before  the  end of the string will not
+                  convert completely.
+
+       <STRONG>-c</STRONG>     tells <STRONG>tic</STRONG> to only check <EM>file</EM> for errors,  including
+              syntax  problems and bad use links.  If you specify
               <STRONG>-C</STRONG> (<STRONG>-I</STRONG>) with this option, the code will print warn-
               ings about entries which, after use resolution, are
-              more  than  1023 (4096) bytes long.  Due to a fixed
-              buffer length in older termcap libraries,  as  well
+              more than 1023 (4096) bytes long.  Due to  a  fixed
+              buffer  length  in older termcap libraries, as well
               as buggy checking for the buffer length (and a doc-
               umented limit in terminfo), these entries may cause
               core dumps with other implementations.
 
-       <STRONG>-D</STRONG>     tells  <STRONG>tic</STRONG>  to print the database locations that it
+              <STRONG>tic</STRONG> checks string capabilities to ensure that those
+              with parameters will be valid expressions.  It does
+              this check only for the predefined string capabili-
+              ties;  those  which  are defined with the <STRONG>-x</STRONG> option
+              are ignored.
+
+       <STRONG>-D</STRONG>     tells <STRONG>tic</STRONG> to print the database locations  that  it
               knows about, and exit.  The first location shown is
-              the  one  to which it would write compiled terminal
+              the one to which it would write  compiled  terminal
               descriptions.   If  <STRONG>tic</STRONG>  is  not  able  to  find  a
-              writable  database  location according to the rules
-              summarized above, it will print  a  diagnostic  and
-              exit  with  an error rather than printing a list of
+              writable database location according to  the  rules
+              summarized  above,  it  will print a diagnostic and
+              exit with an error rather than printing a  list  of
               database locations.
 
        <STRONG>-e</STRONG> <EM>names</EM>
-              Limit writes  and  translations  to  the  following
-              comma-separated  list of terminals.  If any name or
+              Limit  writes  and  translations  to  the following
+              comma-separated list of terminals.  If any name  or
               alias of a terminal matches one of the names in the
-              list,  the  entry  will be written or translated as
-              normal.  Otherwise no output will be generated  for
+              list, the entry will be written  or  translated  as
+              normal.   Otherwise no output will be generated for
               it.  The option value is interpreted as a file con-
-              taining the list if  it  contains  a  '/'.   (Note:
-              depending  on how tic was compiled, this option may
+              taining  the  list  if  it  contains a '/'.  (Note:
+              depending on how tic was compiled, this option  may
               require <STRONG>-I</STRONG> or <STRONG>-C</STRONG>.)
 
        <STRONG>-f</STRONG>     Display  complex  terminfo  strings  which  contain
-              if/then/else/endif  expressions  indented for read-
+              if/then/else/endif expressions indented  for  read-
               ability.
 
-       <STRONG>-G</STRONG>     Display constant literals in  decimal  form  rather
+       <STRONG>-G</STRONG>     Display  constant  literals  in decimal form rather
               than their character equivalents.
 
-       <STRONG>-g</STRONG>     Display  constant character literals in quoted form
+       <STRONG>-g</STRONG>     Display constant character literals in quoted  form
               rather than their decimal equivalents.
 
        <STRONG>-I</STRONG>     Force source translation to terminfo format.
 
-       <STRONG>-K</STRONG>     Suppress some longstanding  ncurses  extensions  to
+       <STRONG>-K</STRONG>     Suppress  some  longstanding  ncurses extensions to
               termcap format, e.g., "\s" for space.
 
-       <STRONG>-L</STRONG>     Force  source  translation to terminfo format using
+       <STRONG>-L</STRONG>     Force source translation to terminfo  format  using
               the long C variable names listed in &lt;<STRONG>term.h</STRONG>&gt;
 
        <STRONG>-N</STRONG>     Disable smart defaults.  Normally, when translating
               from termcap to terminfo, the compiler makes a num-
-              ber of assumptions about  the  defaults  of  string
-              capabilities  <STRONG>reset1_string</STRONG>,  <STRONG>carriage_return</STRONG>, <STRONG>cur-</STRONG>
-              <STRONG>sor_left</STRONG>,   <STRONG>cursor_down</STRONG>,    <STRONG>scroll_forward</STRONG>,    <STRONG>tab</STRONG>,
-              <STRONG>newline</STRONG>,  <STRONG>key_backspace</STRONG>,  <STRONG>key_left</STRONG>,  and  <STRONG>key_down</STRONG>,
-              then attempts to use obsolete termcap  capabilities
-              to  deduce  correct  values.  It also normally sup-
-              presses output  of  obsolete  termcap  capabilities
-              such  as  <STRONG>bs</STRONG>.   This  option  forces a more literal
-              translation that also preserves the obsolete  capa-
-              bilities.
+              ber  of  assumptions  about  the defaults of string
+              capabilities <STRONG>reset1_string</STRONG>,  <STRONG>carriage_return</STRONG>,  <STRONG>cur-</STRONG>
+              <STRONG>sor_left</STRONG>,  <STRONG>cursor_down</STRONG>,  <STRONG>scroll_forward</STRONG>,  <STRONG>tab</STRONG>, <STRONG>new-</STRONG>
+              <STRONG>line</STRONG>, <STRONG>key_backspace</STRONG>, <STRONG>key_left</STRONG>, and  <STRONG>key_down</STRONG>,  then
+              attempts  to  use  obsolete termcap capabilities to
+              deduce correct values.  It also normally suppresses
+              output of obsolete termcap capabilities such as <STRONG>bs</STRONG>.
+              This option forces a more literal translation  that
+              also preserves the obsolete capabilities.
 
        <STRONG>-o</STRONG><EM>dir</EM>  Write  compiled entries to given database location.
               Overrides the TERMINFO environment variable.
 
        <STRONG>-r</STRONG>     Force  entry  resolution (so there are no remaining
               tc capabilities) even  when  doing  translation  to
-              termcap  format.   This  may  be  needed if you are
-              preparing a termcap  file  for  a  termcap  library
-              (such  as  GNU  termcap  through version 1.3 or BSD
-              termcap through 4.3BSD) that does not handle multi-
-              ple tc capabilities per entry.
+              termcap format.  This may be needed if you are pre-
+              paring a termcap file for a termcap  library  (such
+              as  GNU  termcap through version 1.3 or BSD termcap
+              through 4.3BSD) that does not  handle  multiple  tc
+              capabilities per entry.
 
        <STRONG>-s</STRONG>     Summarize the compile by showing the database loca-
               tion into which entries are written, and the number
             1.   If  <EM>n</EM> is specified and greater than 1, the level
             of detail is increased.
 
+            The debug flag levels are as follows:
+
+            1      Names of files created and linked
+
+            2      Information related to the "use" facility
+
+            3      Statistics from the hashing algorithm
+
+            5      String-table memory allocations
+
+            7      Entries into the string-table
+
+            8      List of tokens encountered by scanner
+
+            9      All values computed  in  construction  of  the
+                   hash table
+
+            If  the debug level <EM>n</EM> is not given, it is taken to be
+            one.
+
        <STRONG>-w</STRONG><EM>n</EM>  specifies the width of the output.  The parameter  is
             optional.  If it is omitted, it defaults to 60.
 
             recognize, it will infer its type (boolean, number or
             string) from the syntax and make  an  extended  table
             entry  for  that.   User-defined  capability  strings
-            whose name begins with ``k'' are treated as  function
+            whose name begins with "k" are  treated  as  function
             keys.
 
-       <EM>file</EM> contains  one  or more <STRONG>terminfo</STRONG> terminal descriptions
-            in source format [see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].  Each description
-            in  the file describes the capabilities of a particu-
-            lar terminal.
-
-       The debug flag levels are as follows:
-
-       1      Names of files created and linked
 
-       2      Information related to the ``use'' facility
-
-       3      Statistics from the hashing algorithm
-
-       5      String-table memory allocations
-
-       7      Entries into the string-table
-
-       8      List of tokens encountered by scanner
+</PRE>
+<H3><a name="h3-PARAMETERS">PARAMETERS</a></H3><PRE>
+       <EM>file</EM>   contains one or more <STRONG>terminfo</STRONG> terminal descriptions
+              in source format [see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].  Each  descrip-
+              tion  in  the  file describes the capabilities of a
+              particular terminal.
 
-       9      All values computed in construction of the hash ta-
-              ble
+              If <EM>file</EM> is "-", then the  data  is  read  from  the
+              standard input.  The <EM>file</EM> parameter may also be the
+              path of a character-device.
 
-       If  the debug level <EM>n</EM> is not given, it is taken to be one.
 
+</PRE>
+<H3><a name="h3-PROCESSING">PROCESSING</a></H3><PRE>
        All but one of the capabilities recognized by <STRONG>tic</STRONG> are doc-
        umented in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.  The exception is the <STRONG>use</STRONG> capabil-
        ity.
        When a <STRONG>use</STRONG>=<EM>entry</EM>-<EM>name</EM> field is discovered  in  a  terminal
        entry  currently  being  compiled, <STRONG>tic</STRONG> reads in the binary
        from <STRONG>/usr/share/terminfo</STRONG> to complete the entry.   (Entries
-       created  from <EM>file</EM> will be used first.  If the environment
-       variable  <STRONG>TERMINFO</STRONG>  is  set,  that  database  location  is
-       searched  instead of <STRONG>/usr/share/terminfo</STRONG>.)  <STRONG>tic</STRONG> duplicates
-       the capabilities in <EM>entry</EM>-<EM>name</EM> for the current entry, with
-       the  exception  of  those capabilities that explicitly are
+       created  from <EM>file</EM> will be used first.  <STRONG>tic</STRONG> duplicates the
+       capabilities in <EM>entry</EM>-<EM>name</EM> for the current entry, with the
+       exception   of  those  capabilities  that  explicitly  are
        defined in the current entry.
 
        When   an   entry,   e.g.,   <STRONG>entry_name_1</STRONG>,   contains    a
        <EM>entry</EM>_<EM>name</EM>_<EM>2</EM> must also appear in <STRONG>entry_name_1</STRONG> before  <STRONG>use=</STRONG>
        for these capabilities to be canceled in <STRONG>entry_name_1</STRONG>.
 
-       If  the environment variable <STRONG>TERMINFO</STRONG> is set, the compiled
-       results are placed there instead of <STRONG>/usr/share/terminfo</STRONG>.
-
        Total compiled entries cannot exceed 4096 bytes.  The name
-       field  cannot  exceed 512 bytes.  Terminal names exceeding
-       the maximum alias length (32 characters  on  systems  with
+       field cannot exceed 512 bytes.  Terminal  names  exceeding
+       the  maximum  alias  length (32 characters on systems with
        long filenames, 14 characters otherwise) will be truncated
-       to the maximum alias length and a warning message will  be
+       to  the maximum alias length and a warning message will be
        printed.
 
 
 </PRE>
-<H2>COMPATIBILITY</H2><PRE>
-       There  is  some evidence that historic <STRONG>tic</STRONG> implementations
-       treated description fields with no whitespace in  them  as
-       additional  aliases  or short names.  This <STRONG>tic</STRONG> does not do
-       that, but it does warn  when  description  fields  may  be
-       treated  that way and check them for dangerous characters.
+<H2><a name="h2-COMPATIBILITY">COMPATIBILITY</a></H2><PRE>
+       There is some evidence that historic  <STRONG>tic</STRONG>  implementations
+       treated  description  fields with no whitespace in them as
+       additional aliases or short names.  This <STRONG>tic</STRONG> does  not  do
+       that,  but  it  does  warn  when description fields may be
+       treated that way and check them for dangerous characters.
 
 
 </PRE>
-<H2>EXTENSIONS</H2><PRE>
-       Unlike the stock SVr4 <STRONG>tic</STRONG> command, this implementation can
-       actually  compile  termcap  sources.   In fact, entries in
-       terminfo and termcap syntax  can  be  mixed  in  a  single
-       source  file.   See  <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>  for  the list of termcap
-       names taken to be equivalent to terminfo names.
+<H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
+       Unlike the SVr4 <STRONG>tic</STRONG> command, this implementation can actu-
+       ally  compile  termcap  sources.  In fact, entries in ter-
+       minfo and termcap syntax can be mixed in a  single  source
+       file.  See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for the list of termcap names taken
+       to be equivalent to terminfo names.
 
        The SVr4 manual pages are  not  clear  on  the  resolution
        rules  for  <STRONG>use</STRONG>  capabilities.  This implementation of <STRONG>tic</STRONG>
 
 
 </PRE>
-<H2>FILES</H2><PRE>
+<H2><a name="h2-FILES">FILES</a></H2><PRE>
        <STRONG>/usr/share/terminfo/?/*</STRONG>
             Compiled terminal description database.
 
 
 </PRE>
-<H2>SEE ALSO</H2><PRE>
+<H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
        <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>,   <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG>,   <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>,    <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG>,
        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="term.5.html">term(5)</A></STRONG>.  <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 
-       This describes <STRONG>ncurses</STRONG> version 5.9 (patch 20120107).
+       This describes <STRONG>ncurses</STRONG> version 5.9 (patch 20150215).
 
 
 </PRE>
-<H2>AUTHOR</H2><PRE>
+<H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
        Eric S. Raymond &lt;esr@snark.thyrsus.com&gt; and
        Thomas E. Dickey &lt;dickey@invisible-island.net&gt;
 
 
                                                                 <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>
 </PRE>
-<HR>
-<ADDRESS>
-Man(1) output converted with
-<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
-</ADDRESS>
+<div class="nav">
+<ul>
+<li><a href="#h2-NAME">NAME</a></li>
+<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
+<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
+<ul>
+<li><a href="#h3-OPTIONS">OPTIONS</a></li>
+<li><a href="#h3-PARAMETERS">PARAMETERS</a></li>
+<li><a href="#h3-PROCESSING">PROCESSING</a></li>
+</ul>
+</li>
+<li><a href="#h2-COMPATIBILITY">COMPATIBILITY</a></li>
+<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
+<li><a href="#h2-FILES">FILES</a></li>
+<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
+<li><a href="#h2-AUTHOR">AUTHOR</a></li>
+</ul>
+</div>
 </BODY>
 </HTML>