doc/html/man/tic.1m.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
   4   *                                                                          *
   5   * Permission is hereby granted, free of charge, to any person obtaining a  *
   6   * copy of this software and associated documentation files (the            *
   7   * "Software"), to deal in the Software without restriction, including      *
   8   * without limitation the rights to use, copy, modify, merge, publish,      *
   9   * distribute, distribute with modifications, sublicense, and/or sell       *
  10   * copies of the Software, and to permit persons to whom the Software is    *
  11   * furnished to do so, subject to the following conditions:                 *
  12   *                                                                          *
  13   * The above copyright notice and this permission notice shall be included  *
  14   * in all copies or substantial portions of the Software.                   *
  15   *                                                                          *
  16   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23   *                                                                          *
  24   * Except as contained in this notice, the name(s) of the above copyright   *
  25   * holders shall not be used in advertising or otherwise to promote the     *
  26   * sale, use or other dealings in this Software without prior written       *
  27   * authorization.                                                           *
  28   ****************************************************************************
  29   * @Id: tic.1m,v 1.65 2017/07/08 19:48:37 tom Exp @
  30 -->
  31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  32 <HTML>
  33 <HEAD>
  34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
  36 <TITLE>tic 1m</TITLE>
  37 <link rev=made href="mailto:bug-ncurses@gnu.org">
  38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  39 </HEAD>
  40 <BODY>
  41 <H1 class="no-header">tic 1m</H1>
  42 <PRE>
  43 <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>                                                                <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>
  44
  45
  46
  47
  48 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  49        <STRONG>tic</STRONG> - the <EM>terminfo</EM> entry-description compiler
  50
  51
  52 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  53        <STRONG>tic</STRONG>  [<STRONG>-01CDGIKLNTUVWacfgqrstx</STRONG>]  [<STRONG>-e</STRONG> <EM>names</EM>] [<STRONG>-o</STRONG> <EM>dir</EM>] [<STRONG>-Q</STRONG>[<EM>n</EM>]] [<STRONG>-R</STRONG> <EM>subset</EM>]
  54        [<STRONG>-v</STRONG>[<EM>n</EM>]] [<STRONG>-w</STRONG>[<EM>n</EM>]] <EM>file</EM>
  55
  56
  57 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  58        The <STRONG>tic</STRONG> command translates a <STRONG>terminfo</STRONG> file from source format into com-
  59        piled  format.   The  compiled  format  is  necessary  for use with the
  60        library routines in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
  61
  62        As described in <STRONG><A HREF="term.5.html">term(5)</A></STRONG>, the database may be either  a  directory  tree
  63        (one  file  per  terminal  entry)  or a hashed database (one record per
  64        entry).  The <STRONG>tic</STRONG> command writes only one type of  entry,  depending  on
  65        how it was built:
  66
  67        <STRONG>o</STRONG>   For directory trees, the top-level directory, e.g., /usr/share/ter-
  68            minfo, specifies the location of the database.
  69
  70        <STRONG>o</STRONG>   For hashed databases, a filename is needed.  If the given  file  is
  71            not  found  by  that  name,  but  can be found by adding the suffix
  72            ".db", then that is used.
  73
  74            The default name for the hashed database is the same as the default
  75            directory name (only adding a ".db" suffix).
  76
  77        In either case (directory or hashed database), <STRONG>tic</STRONG> will create the con-
  78        tainer if it does not exist.  For a directory, this would be the  "ter-
  79        minfo" leaf, versus a "terminfo.db" file.
  80
  81        The  results  are  normally  placed  in  the  system  terminfo database
  82        <STRONG>/usr/local/ncurses/lib/terminfo</STRONG>.  The compiled terminal description can
  83        be  placed  in  a  different  terminfo database.  There are two ways to
  84        achieve this:
  85
  86        <STRONG>o</STRONG>   First, you may override the system default either by using  the  <STRONG>-o</STRONG>
  87            option,  or by setting the variable <STRONG>TERMINFO</STRONG> in your shell environ-
  88            ment to a valid database location.
  89
  90        <STRONG>o</STRONG>   Secondly, if <STRONG>tic</STRONG> cannot write in <EM>/usr/local/ncurses/lib/terminfo</EM> or
  91            the  location  specified using your TERMINFO variable, it looks for
  92            the  directory  <EM>$HOME/.terminfo</EM>  (or  hashed  database  <EM>$HOME/.ter-</EM>
  93            <EM>minfo.db)</EM>; if that location exists, the entry is placed there.
  94
  95        Libraries  that  read terminfo entries are expected to check in succes-
  96        sion
  97
  98        <STRONG>o</STRONG>   a location specified with the TERMINFO environment variable,
  99
 100        <STRONG>o</STRONG>   <EM>$HOME/.terminfo</EM>,
 101
 102        <STRONG>o</STRONG>   directories listed in the TERMINFO_DIRS environment variable,
 103
 104        <STRONG>o</STRONG>   a compiled-in list  of  directories  (/usr/local/ncurses/share/ter-
 105            minfo:/usr/share/terminfo), and
 106
 107        <STRONG>o</STRONG>   the system terminfo database (<EM>/usr/local/ncurses/lib/terminfo</EM>).
 108
 109
 110 </PRE><H3><a name="h3-OPTIONS">OPTIONS</a></H3><PRE>
 111        <STRONG>-0</STRONG>     restricts the output to a single line
 112
 113        <STRONG>-1</STRONG>     restricts the output to a single column
 114
 115        <STRONG>-a</STRONG>     tells  <STRONG>tic</STRONG> to retain commented-out capabilities rather than dis-
 116               carding them.  Capabilities are commented by prefixing them with
 117               a  period.   This sets the <STRONG>-x</STRONG> option, because it treats the com-
 118               mented-out entries as user-defined  names.   If  the  source  is
 119               termcap,  accept  the  2-character  names required by version 6.
 120               Otherwise these are ignored.
 121
 122        <STRONG>-C</STRONG>     Force source translation to termcap format.  Note: this  differs
 123               from  the  <STRONG>-C</STRONG>  option  of <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG> in that it does not merely
 124               translate capability names, but also translates terminfo strings
 125               to  termcap  format.  Capabilities that are not translatable are
 126               left in the entry under their terminfo names but  commented  out
 127               with  two  preceding  dots.  The actual format used incorporates
 128               some improvements for escaped characters from  terminfo  format.
 129               For a stricter BSD-compatible translation, add the <STRONG>-K</STRONG> option.
 130
 131               If  this  is  combined  with  <STRONG>-c</STRONG>, <STRONG>tic</STRONG> makes additional checks to
 132               report cases where the terminfo values  do  not  have  an  exact
 133               equivalent in termcap form.  For example:
 134
 135               <STRONG>o</STRONG>   <STRONG>sgr</STRONG>  usually  will  not  convert,  because termcap lacks the
 136                   ability to work with more than two parameters,  and  because
 137                   termcap  lacks many of the arithmetic/logical operators used
 138                   in terminfo.
 139
 140               <STRONG>o</STRONG>   capabilities with more than one delay or with delays  before
 141                   the end of the string will not convert completely.
 142
 143        <STRONG>-c</STRONG>     tells  <STRONG>tic</STRONG> to only check <EM>file</EM> for errors, including syntax prob-
 144               lems and bad use links.   If  you  specify  <STRONG>-C</STRONG>  (<STRONG>-I</STRONG>)  with  this
 145               option,  the code will print warnings about entries which, after
 146               use resolution, are more than 1023 (4096) bytes long.  Due to  a
 147               fixed buffer length in older termcap libraries, as well as buggy
 148               checking for the buffer length (and a documented limit  in  ter-
 149               minfo),  these entries may cause core dumps with other implemen-
 150               tations.
 151
 152               <STRONG>tic</STRONG> checks string capabilities to ensure that those with parame-
 153               ters will be valid expressions.  It does this check only for the
 154               predefined string capabilities; those which are defined with the
 155               <STRONG>-x</STRONG> option are ignored.
 156
 157        <STRONG>-D</STRONG>     tells  <STRONG>tic</STRONG>  to print the database locations that it knows about,
 158               and exit.  The first location shown is the one to which it would
 159               write  compiled  terminal  descriptions.   If <STRONG>tic</STRONG> is not able to
 160               find a writable database location according to the rules  summa-
 161               rized  above,  it will print a diagnostic and exit with an error
 162               rather than printing a list of database locations.
 163
 164        <STRONG>-e</STRONG> <EM>names</EM>
 165               Limit writes and translations to the  following  comma-separated
 166               list  of  terminals.  If any name or alias of a terminal matches
 167               one of the names in the list,  the  entry  will  be  written  or
 168               translated as normal.  Otherwise no output will be generated for
 169               it.  The option value is interpreted as a  file  containing  the
 170               list if it contains a '/'.  (Note: depending on how tic was com-
 171               piled, this option may require <STRONG>-I</STRONG> or <STRONG>-C</STRONG>.)
 172
 173        <STRONG>-f</STRONG>     Display    complex    terminfo     strings     which     contain
 174               if/then/else/endif expressions indented for readability.
 175
 176        <STRONG>-G</STRONG>     Display  constant  literals  in  decimal  form rather than their
 177               character equivalents.
 178
 179        <STRONG>-g</STRONG>     Display constant character literals in quoted form  rather  than
 180               their decimal equivalents.
 181
 182        <STRONG>-I</STRONG>     Force source translation to terminfo format.
 183
 184        <STRONG>-K</STRONG>     Suppress some longstanding ncurses extensions to termcap format,
 185               e.g., "\s" for space.
 186
 187        <STRONG>-L</STRONG>     Force source translation to terminfo format  using  the  long  C
 188               variable names listed in &lt;<STRONG>term.h</STRONG>&gt;
 189
 190        <STRONG>-N</STRONG>     Disable smart defaults.  Normally, when translating from termcap
 191               to terminfo, the compiler makes a number  of  assumptions  about
 192               the   defaults   of   string  capabilities  <STRONG>reset1_string</STRONG>,  <STRONG>car-</STRONG>
 193               <STRONG>riage_return</STRONG>,  <STRONG>cursor_left</STRONG>,  <STRONG>cursor_down</STRONG>,  <STRONG>scroll_forward</STRONG>,  <STRONG>tab</STRONG>,
 194               <STRONG>newline</STRONG>, <STRONG>key_backspace</STRONG>, <STRONG>key_left</STRONG>, and <STRONG>key_down</STRONG>, then attempts to
 195               use obsolete termcap capabilities to deduce correct values.   It
 196               also normally suppresses output of obsolete termcap capabilities
 197               such as <STRONG>bs</STRONG>.  This option forces a more literal translation  that
 198               also preserves the obsolete capabilities.
 199
 200        <STRONG>-o</STRONG><EM>dir</EM>  Write  compiled  entries  to given database location.  Overrides
 201               the TERMINFO environment variable.
 202
 203        <STRONG>-Q</STRONG><EM>n</EM>    Rather than show source in terminfo  (text)  format,  print  the
 204               compiled  (binary) format in hexadecimal or base64 form, depend-
 205               ing on the option's value:
 206
 207                1  hexadecimal
 208
 209                2  base64
 210
 211                3  hexadecimal and base64
 212
 213        <STRONG>-q</STRONG>     Suppress  comments  and  blank  lines  when  showing  translated
 214               source.
 215
 216        <STRONG>-R</STRONG><EM>subset</EM>
 217               Restrict  output to a given subset.  This option is for use with
 218               archaic versions of terminfo like  those  on  SVr1,  Ultrix,  or
 219               HP/UX  that  do not support the full set of SVR4/XSI Curses ter-
 220               minfo; and outright broken ports like AIX 3.x  that  have  their
 221               own  extensions  incompatible  with SVr4/XSI.  Available subsets
 222               are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for
 223               details.
 224
 225        <STRONG>-r</STRONG>     Force  entry  resolution (so there are no remaining tc capabili-
 226               ties) even when doing translation to termcap format.   This  may
 227               be  needed  if  you  are  preparing a termcap file for a termcap
 228               library (such as GNU termcap through version 1.3 or BSD  termcap
 229               through  4.3BSD)  that  does not handle multiple tc capabilities
 230               per entry.
 231
 232        <STRONG>-s</STRONG>     Summarize the compile by  showing  the  database  location  into
 233               which  entries  are written, and the number of entries which are
 234               compiled.
 235
 236        <STRONG>-T</STRONG>     eliminates size-restrictions on the  generated  text.   This  is
 237               mainly  useful  for  testing  and  analysis,  since the compiled
 238               descriptions are limited (e.g., 1023 for termcap, 4096 for  ter-
 239               minfo).
 240
 241        <STRONG>-t</STRONG>     tells  <STRONG>tic</STRONG> to discard commented-out capabilities.  Normally when
 242               translating from terminfo to termcap,  untranslatable  capabili-
 243               ties are commented-out.
 244
 245        <STRONG>-U</STRONG>   tells  <STRONG>tic</STRONG>  to  not post-process the data after parsing the source
 246             file.  Normally, it infers data which is commonly missing in older
 247             terminfo data, or in termcaps.
 248
 249        <STRONG>-V</STRONG>   reports the version of ncurses which was used in this program, and
 250             exits.
 251
 252        <STRONG>-v</STRONG><EM>n</EM>  specifies that (verbose) output be written to standard error trace
 253             information showing <STRONG>tic</STRONG>'s progress.
 254
 255             The  optional  parameter  <EM>n</EM>  is  a number from 1 to 10, inclusive,
 256             indicating the desired level of detail of information.  If ncurses
 257             is  built  without  tracing  support,  the  optional  parameter is
 258             ignored.  If <EM>n</EM> is omitted, the default level is 1.  If <EM>n</EM> is speci-
 259             fied and greater than 1, the level of detail is increased.
 260
 261             The debug flag levels are as follows:
 262
 263             1      Names of files created and linked
 264
 265             2      Information related to the "use" facility
 266
 267             3      Statistics from the hashing algorithm
 268
 269             5      String-table memory allocations
 270
 271             7      Entries into the string-table
 272
 273             8      List of tokens encountered by scanner
 274
 275             9      All values computed in construction of the hash table
 276
 277             If the debug level <EM>n</EM> is not given, it is taken to be one.
 278
 279        <STRONG>-W</STRONG>   By  itself,  the  <STRONG>-w</STRONG>  option  will  not  force  long strings to be
 280             wrapped.  Use the <STRONG>-W</STRONG> option to do this.
 281
 282             If you specify both <STRONG>-f</STRONG> and <STRONG>-W</STRONG> options, the latter is ignored  when
 283             <STRONG>-f</STRONG> has already split the line.
 284
 285        <STRONG>-w</STRONG><EM>n</EM>  specifies the width of the output.  The parameter is optional.  If
 286             it is omitted, it defaults to 60.
 287
 288        <STRONG>-x</STRONG>   Treat unknown capabilities as user-defined.  That is, if you  sup-
 289             ply  a capability name which <STRONG>tic</STRONG> does not recognize, it will infer
 290             its type (boolean, number or string) from the syntax and  make  an
 291             extended  table  entry  for that.  User-defined capability strings
 292             whose name begins with "k" are treated as function keys.
 293
 294
 295 </PRE><H3><a name="h3-PARAMETERS">PARAMETERS</a></H3><PRE>
 296        <EM>file</EM>   contains one or more <STRONG>terminfo</STRONG> terminal  descriptions  in  source
 297               format   [see   <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].   Each  description  in  the  file
 298               describes the capabilities of a particular terminal.
 299
 300               If <EM>file</EM> is "-", then the data is read from the  standard  input.
 301               The <EM>file</EM> parameter may also be the path of a character-device.
 302
 303
 304 </PRE><H3><a name="h3-PROCESSING">PROCESSING</a></H3><PRE>
 305        All  but  one  of  the capabilities recognized by <STRONG>tic</STRONG> are documented in
 306        <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.  The exception is the <STRONG>use</STRONG> capability.
 307
 308        When a <STRONG>use</STRONG>=<EM>entry</EM>-<EM>name</EM> field is discovered in a terminal entry currently
 309        being     compiled,     <STRONG>tic</STRONG>     reads     in     the     binary    from
 310        <STRONG>/usr/local/ncurses/lib/terminfo</STRONG> to complete the entry.   (Entries  cre-
 311        ated  from <EM>file</EM> will be used first.  <STRONG>tic</STRONG> duplicates the capabilities in
 312        <EM>entry</EM>-<EM>name</EM> for the current entry, with the exception of those capabili-
 313        ties that explicitly are defined in the current entry.
 314
 315        When  an  entry, e.g., <STRONG>entry_name_1</STRONG>, contains a <STRONG>use=</STRONG><EM>entry</EM>_<EM>name</EM>_<EM>2</EM> field,
 316        any  canceled  capabilities  in  <EM>entry</EM>_<EM>name</EM>_<EM>2</EM>  must  also   appear   in
 317        <STRONG>entry_name_1</STRONG>  before  <STRONG>use=</STRONG>  for  these  capabilities  to be canceled in
 318        <STRONG>entry_name_1</STRONG>.
 319
 320        Total compiled entries cannot exceed 4096 bytes.  The name field cannot
 321        exceed  512  bytes.   Terminal names exceeding the maximum alias length
 322        (32 characters on systems with long filenames, 14 characters otherwise)
 323        will  be  truncated  to  the maximum alias length and a warning message
 324        will be printed.
 325
 326
 327 </PRE><H2><a name="h2-COMPATIBILITY">COMPATIBILITY</a></H2><PRE>
 328        There is  some  evidence  that  historic  <STRONG>tic</STRONG>  implementations  treated
 329        description  fields with no whitespace in them as additional aliases or
 330        short names.  This <STRONG>tic</STRONG> does not do that, but it does warn when descrip-
 331        tion  fields may be treated that way and check them for dangerous char-
 332        acters.
 333
 334
 335 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 336        Unlike the SVr4 <STRONG>tic</STRONG> command, this implementation can  actually  compile
 337        termcap  sources.   In fact, entries in terminfo and termcap syntax can
 338        be mixed in a single source file.  See  <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>  for  the  list  of
 339        termcap names taken to be equivalent to terminfo names.
 340
 341        The  SVr4  manual  pages  are not clear on the resolution rules for <STRONG>use</STRONG>
 342        capabilities.  This implementation of <STRONG>tic</STRONG> will find  <STRONG>use</STRONG>  targets  any-
 343        where  in  the source file, or anywhere in the file tree rooted at <STRONG>TER-</STRONG>
 344        <STRONG>MINFO</STRONG> (if <STRONG>TERMINFO</STRONG> is defined), or in the user's <EM>$HOME/.terminfo</EM>  data-
 345        base (if it exists), or (finally) anywhere in the system's file tree of
 346        compiled entries.
 347
 348        The error messages from this <STRONG>tic</STRONG> have the same format as  GNU  C  error
 349        messages, and can be parsed by GNU Emacs's compile facility.
 350
 351        The  <STRONG>-0</STRONG>, <STRONG>-1</STRONG>, <STRONG>-C</STRONG>, <STRONG>-G</STRONG>, <STRONG>-I</STRONG>, <STRONG>-N</STRONG>, <STRONG>-R</STRONG>, <STRONG>-T</STRONG>, <STRONG>-V</STRONG>, <STRONG>-a</STRONG>, <STRONG>-e</STRONG>, <STRONG>-f</STRONG>, <STRONG>-g</STRONG>, <STRONG>-o</STRONG>, <STRONG>-r</STRONG>, <STRONG>-s</STRONG>, <STRONG>-t</STRONG>
 352        and <STRONG>-x</STRONG> options are not supported under SVr4.  The SVr4 <STRONG>-c</STRONG> mode does not
 353        report bad use links.
 354
 355        System  V  does  not  compile  entries  to  or  read  entries from your
 356        <EM>$HOME/.terminfo</EM> database unless TERMINFO is explicitly set to it.
 357
 358
 359 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
 360        <STRONG>/usr/local/ncurses/lib/terminfo/?/*</STRONG>
 361             Compiled terminal description database.
 362
 363
 364 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 365        <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>,
 366        <STRONG><A HREF="term.5.html">term(5)</A></STRONG>.  <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
 367
 368        This describes <STRONG>ncurses</STRONG> version 6.0 (patch 20170819).
 369
 370
 371 </PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
 372        Eric S. Raymond &lt;esr@snark.thyrsus.com&gt; and
 373        Thomas E. Dickey &lt;dickey@invisible-island.net&gt;
 374
 375
 376
 377                                                                        <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>
 378 </PRE>
 379 <div class="nav">
 380 <ul>
 381 <li><a href="#h2-NAME">NAME</a></li>
 382 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 383 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 384 <ul>
 385 <li><a href="#h3-OPTIONS">OPTIONS</a></li>
 386 <li><a href="#h3-PARAMETERS">PARAMETERS</a></li>
 387 <li><a href="#h3-PROCESSING">PROCESSING</a></li>
 388 </ul>
 389 </li>
 390 <li><a href="#h2-COMPATIBILITY">COMPATIBILITY</a></li>
 391 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 392 <li><a href="#h2-FILES">FILES</a></li>
 393 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 394 <li><a href="#h2-AUTHOR">AUTHOR</a></li>
 395 </ul>
 396 </div>
 397 </BODY>
 398 </HTML>