ncurses 6.2 - patch 20200425
[ncurses.git] / doc / html / man / tic.1m.html
index 3f273d35907d639f80409f5bc12afaf22569aa39..70212a6b10bd768a0f261c0da84ea9cff879c762 100644 (file)
@@ -1,6 +1,7 @@
 <!-- 
   ****************************************************************************
-  * Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
+  * Copyright 2018-2019,2020 Thomas E. Dickey                                *
+  * Copyright 1998-2016,2017 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.65 2017/07/08 19:48:37 tom Exp @
+  * @Id: tic.1m,v 1.77 2020/02/02 23:34:34 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">
+<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
 <TITLE>tic 1m</TITLE>
-<link rev=made href="mailto:bug-ncurses@gnu.org">
+<link rel="author" href="mailto:bug-ncurses@gnu.org">
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 </HEAD>
 <BODY>
        minfo" leaf, versus a "terminfo.db" file.
 
        The  results  are  normally  placed  in  the  system  terminfo database
-       <STRONG>/usr/local/ncurses/lib/terminfo</STRONG>.  The compiled terminal description can
-       be  placed  in  a  different  terminfo database.  There are two ways to
-       achieve this:
+       <STRONG>/usr/share/terminfo</STRONG>.  The compiled terminal description can  be  placed
+       in a different terminfo database.  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>TERMINFO</STRONG> in your shell environ-
+       <STRONG>o</STRONG>   First,  you  may override the system default either by using the <STRONG>-o</STRONG>
+           option, or by setting the variable <STRONG>TERMINFO</STRONG> in your shell  environ-
            ment to a valid database location.
 
-       <STRONG>o</STRONG>   Secondly, if <STRONG>tic</STRONG> cannot write in <EM>/usr/local/ncurses/lib/terminfo</EM> or
-           the  location  specified using your TERMINFO variable, it looks for
-           the  directory  <EM>$HOME/.terminfo</EM>  (or  hashed  database  <EM>$HOME/.ter-</EM>
-           <EM>minfo.db)</EM>; if that location exists, the entry is placed there.
+       <STRONG>o</STRONG>   Secondly,  if  <STRONG>tic</STRONG> cannot write in <EM>/usr/share/terminfo</EM> or the loca-
+           tion specified using your  TERMINFO  variable,  it  looks  for  the
+           directory  <EM>$HOME/.terminfo</EM> (or hashed database <EM>$HOME/.terminfo.db)</EM>;
+           if that location exists, the entry is placed there.
 
-       Libraries  that  read terminfo entries are expected to check in succes-
+       Libraries that read terminfo entries are expected to check  in  succes-
        sion
 
        <STRONG>o</STRONG>   a location specified with the TERMINFO environment variable,
 
        <STRONG>o</STRONG>   directories listed in the TERMINFO_DIRS environment variable,
 
-       <STRONG>o</STRONG>   a compiled-in list  of  directories  (/usr/local/ncurses/share/ter-
+       <STRONG>o</STRONG>   a  compiled-in  list  of directories (/usr/local/ncurses/share/ter-
            minfo:/usr/share/terminfo), and
 
-       <STRONG>o</STRONG>   the system terminfo database (<EM>/usr/local/ncurses/lib/terminfo</EM>).
+       <STRONG>o</STRONG>   the system terminfo database (<EM>/usr/share/terminfo</EM>).
+
+
+</PRE><H3><a name="h3-ALIASES">ALIASES</a></H3><PRE>
+       This is the same program as infotocap and captoinfo; usually those  are
+       linked to, or copied from this program:
+
+       <STRONG>o</STRONG>   When invoked as infotocap, tic sets the <STRONG>-I</STRONG> option.
+
+       <STRONG>o</STRONG>   When invoked as captoinfo, tic sets the <STRONG>-C</STRONG> option.
 
 
 </PRE><H3><a name="h3-OPTIONS">OPTIONS</a></H3><PRE>
                   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 prob-
-              lems and bad use links.   If  you  specify  <STRONG>-C</STRONG>  (<STRONG>-I</STRONG>)  with  this
+              lems and bad use-links.   If  you  specify  <STRONG>-C</STRONG>  (<STRONG>-I</STRONG>)  with  this
               option,  the code will print warnings 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 as buggy
        <STRONG>-w</STRONG><EM>n</EM>  specifies the width of the output.  The parameter is optional.  If
             it is omitted, it defaults to 60.
 
-       <STRONG>-x</STRONG>   Treat unknown capabilities as user-defined.  That is, if you  sup-
-            ply  a capability name which <STRONG>tic</STRONG> does not 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 keys.
+       <STRONG>-x</STRONG>   Treat unknown capabilities  as  user-defined  (see  <STRONG>user_caps(5)</STRONG>).
+            That is, if you supply a capability name which <STRONG>tic</STRONG> does not recog-
+            nize, 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 func-
+            tion keys.
 
 
 </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  description  in  the  file
+       <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 particular terminal.
 
-              If <EM>file</EM> is "-", then the data is read from the  standard  input.
+              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.
 
 
 </PRE><H3><a name="h3-PROCESSING">PROCESSING</a></H3><PRE>
-       All  but  one  of  the capabilities recognized by <STRONG>tic</STRONG> are documented in
+       All but one of the capabilities recognized by  <STRONG>tic</STRONG>  are  documented  in
        <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.  The exception is the <STRONG>use</STRONG> capability.
 
        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/local/ncurses/lib/terminfo</STRONG> to complete the entry.   (Entries  cre-
-       ated  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 capabili-
-       ties that explicitly are defined in the current entry.
-
-       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,
-       any  canceled  capabilities  in  <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
+       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.
+       <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  <STRONG>use=</STRONG><EM>entry</EM>_<EM>name</EM>_<EM>2</EM>  field,
+       any   canceled   capabilities  in  <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>.
 
        Total compiled entries cannot exceed 4096 bytes.  The name field cannot
-       exceed  512  bytes.   Terminal names exceeding the maximum alias length
+       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 truncated to the maximum alias length  and  a  warning  message
        will be printed.
 
 
-</PRE><H2><a name="h2-COMPATIBILITY">COMPATIBILITY</a></H2><PRE>
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+       System  V  Release  2  provided  a  <STRONG>tic</STRONG>  utility.  It accepted a single
+       option: <STRONG>-v</STRONG> (optionally  followed  by  a  number).   According  to  Ross
+       Ridge's comment in <EM>mytinfo</EM>, this version of <STRONG>tic</STRONG> was unable to represent
+       cancelled capabilities.
+
+       System V Release 3 provided a different <STRONG>tic</STRONG> utility, written  by  Pavel
+       Curtis,  (originally named "compile" in <EM>pcurses</EM>).  This added an option
+       <STRONG>-c</STRONG> to check the file for errors, with the caveat that errors in  "use="
+       links would not be reported.  System V Release 3 documented a few warn-
+       ing messages which did not appear in <EM>pcurses</EM>.  While the program itself
+       was  changed  little  as development continued with System V Release 4,
+       the table of capabilities grew from 180 (<EM>pcurses</EM>) to 464 (Solaris).
+
+       In early development of ncurses (1993), Zeyd Ben-Halim used  the  table
+       from  <EM>mytinfo</EM>  to  extend  the  <EM>pcurses</EM>  table to 469 capabilities (456
+       matched SVr4, 8 were only in SVr4, 13 were not in SVr4).  Of those  13,
+       11  were  ultimately  discarded  (perhaps  to match the draft of X/Open
+       Curses).  The exceptions were <STRONG>memory_lock_above</STRONG> and <STRONG>memory_unlock</STRONG>  (see
+       <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>).
+
+       Eric  Raymond  incorporated  parts of <EM>mytinfo</EM> into ncurses to implement
+       the termcap-to-terminfo source conversion, and extended that  to  begin
+       development of the corresponding terminfo-to-termcap source conversion,
+       Thomas Dickey completed that development over  the  course  of  several
+       years.
+
+       In  1999,  Thomas  Dickey  added  the <STRONG>-x</STRONG> option to support user-defined
+       capabilities.
+
+       In 2010, Roy Marples provided a <STRONG>tic</STRONG> program and  terminfo  library  for
+       NetBSD.   That  implementation  adapts  several  features from ncurses,
+       including <STRONG>tic</STRONG>'s <STRONG>-x</STRONG> option.
+
+       The <STRONG>-c</STRONG> option tells <STRONG>tic</STRONG> to check for problems in  the  terminfo  source
+       file.  Continued development provides additional checks:
+
+       <STRONG>o</STRONG>   <EM>pcurses</EM> had 8 warnings
+
+       <STRONG>o</STRONG>   ncurses in 1996 had 16 warnings
+
+       <STRONG>o</STRONG>   Solaris (SVr4) curses has 28 warnings
+
+       <STRONG>o</STRONG>   NetBSD tic in 2019 has 19 warnings.
+
+       <STRONG>o</STRONG>   ncurses in 2019 has 96 warnings
+
+       The checking done in ncurses' <STRONG>tic</STRONG> helps with the conversion to termcap,
+       as well as pointing out errors and inconsistencies.  It is also used to
+       ensure  consistency  with the user-defined capabilities.  There are 527
+       distinct capabilities in ncurses' terminal database; 128 of  those  are
+       user-defined.
+
+
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+       X/Open  Curses, Issue 7 (2009) provides a brief description of <STRONG>tic</STRONG>.  It
+       lists one option: <STRONG>-c</STRONG>.  The omission of <STRONG>-v</STRONG> is  unexpected.   The  change
+       history  states  that  the  description  is  derived  from True64 UNIX.
+       According to its manual  pages,  that  system  also  supported  the  <STRONG>-v</STRONG>
+       option.
+
+       Shortly  after  Issue  7  was  released, Tru64 was discontinued.  As of
+       2019, the surviving implementations of <STRONG>tic</STRONG> are  SVr4  (AIX,  HP-UX  and
+       Solaris), ncurses and NetBSD curses.  The SVr4 <STRONG>tic</STRONG> programs all support
+       the <STRONG>-v</STRONG> option.  The NetBSD <STRONG>tic</STRONG> program follows X/Open's  documentation,
+       omitting the <STRONG>-v</STRONG> option.
+
+       The  X/Open rationale states that some implementations of <STRONG>tic</STRONG> read ter-
+       minal descriptions from the standard input if  the  <EM>file</EM>  parameter  is
+       omitted.   None of these implementations do that.  Further, it comments
+       that some may choose to read from "./terminfo.src" but that is obsoles-
+       cent  behavior from SVr2, and is not (for example) a documented feature
+       of SVr3.
+
+
+</PRE><H3><a name="h3-COMPATIBILITY">COMPATIBILITY</a></H3><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 descrip-
        acters.
 
 
-</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
+</PRE><H3><a name="h3-EXTENSIONS">EXTENSIONS</a></H3><PRE>
        Unlike the 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
        The error messages from this <STRONG>tic</STRONG> have the same format as  GNU  C  error
        messages, and can be parsed by GNU Emacs's compile facility.
 
-       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>
-       and <STRONG>-x</STRONG> options are not supported under SVr4.  The SVr4 <STRONG>-c</STRONG> mode does not
-       report bad use links.
+       Aside from <STRONG>-c</STRONG> and <STRONG>-v</STRONG>, options are not portable:
+
+       <STRONG>o</STRONG>   Most of tic's options are not supported by SVr4 <STRONG>tic</STRONG>:
+
+           <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> <STRONG>-x</STRONG>
 
-       System  V  does  not  compile  entries  to  or  read  entries from your
+       <STRONG>o</STRONG>   The NetBSD <STRONG>tic</STRONG>  supports a few of the ncurses options
+
+           <STRONG>-a</STRONG> <STRONG>-o</STRONG> <STRONG>-x</STRONG>
+
+           and  adds  <STRONG>-S</STRONG>  (a feature which does the same thing as infocmp's <STRONG>-e</STRONG>
+           and <STRONG>-E</STRONG> options).
+
+       The SVr4 <STRONG>-c</STRONG> mode does not report bad "use=" links.
+
+       System V does  not  compile  entries  to  or  read  entries  from  your
        <EM>$HOME/.terminfo</EM> database unless TERMINFO is explicitly set to it.
 
 
 </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
-       <STRONG>/usr/local/ncurses/lib/terminfo/?/*</STRONG>
+       <STRONG>/usr/share/terminfo/?/*</STRONG>
             Compiled terminal description database.
 
 
 </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>.
+       <STRONG><A HREF="term.5.html">term(5)</A></STRONG>.  <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.  <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>.
 
-       This describes <STRONG>ncurses</STRONG> version 6.0 (patch 20170819).
+       This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20200425).
 
 
 </PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 <ul>
+<li><a href="#h3-ALIASES">ALIASES</a></li>
 <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-HISTORY">HISTORY</a></li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a>
+<ul>
+<li><a href="#h3-COMPATIBILITY">COMPATIBILITY</a></li>
+<li><a href="#h3-EXTENSIONS">EXTENSIONS</a></li>
+</ul>
+</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>