ncurses 5.2
[ncurses.git] / doc / html / man / tic.1m.html
1 <HTML>
2 <BODY>
3 <PRE>
4 <!-- Manpage converted by man2html 3.0.1 -->
5
6 </PRE>
7 <H2>NAME</H2><PRE>
8        <B>tic</B> - the <I>terminfo</I> entry-description compiler
9
10
11 </PRE>
12 <H2>SYNOPSIS</H2><PRE>
13        <B>tic</B>  [<B>-1CINRTVacfrsx</B>]  [<B>-e</B> <I>names</I>] [<B>-o</B> <I>dir</I>] [<B>-v</B>[<I>n</I>]] [<B>-w</B>[<I>n</I>]]
14        <I>file</I>
15
16
17 </PRE>
18 <H2>DESCRIPTION</H2><PRE>
19        The command <B>tic</B> translates a  <B>terminfo</B>  file  from  source
20        format  into compiled format.  The compiled format is nec-
21        essary for use with the library routines in <B><A HREF="ncurses.3x.html">ncurses(3x)</A></B>.
22
23        The results are normally placed  in  the  system  terminfo
24        directory  <B>/usr/share/terminfo</B>.   There  are  two  ways to
25        change this behavior.
26
27        First, you may override the system default by setting  the
28        variable  <B>TERMINFO</B>  in  your  shell environment to a valid
29        (existing) directory name.
30
31        Secondly, if <B>tic</B> cannot get access to  <I>/usr/share/terminfo</I>
32        or  your  TERMINFO  directory,  it looks for the directory
33        <I>$HOME/.terminfo</I>; if that directory exists,  the  entry  is
34        placed there.
35
36        Libraries that read terminfo entries are expected to check
37        for a TERMINFO directory first, look at <I>$HOME/.terminfo</I> if
38        TERMINFO  is  not set, and finally look in <I>/usr/share/ter-</I>
39        <I>minfo</I>.
40
41        <B>-a</B>     tells  <B>tic</B>  to  retain  commented-out  capabilities
42               rather than discarding them.  Capabilities are com-
43               mented by prefixing them with a period.  This  sets
44               the  <B>-x</B> option, because it treats the commented-out
45               entries as user-defined names.
46
47        <B>-c</B>     tells <B>tic</B> to only check <I>file</I> for errors,  including
48               syntax  problems and bad use links.  If you specify
49               <B>-C</B> (<B>-I</B>) with this option, the code will print warn-
50               ings about entries which, after use resolution, are
51               more than 1023 (4096) bytes long.  Due to  a  fixed
52               buffer  length  in  older  termcap libraries (and a
53               documented limit in terminfo),  these  entries  may
54               cause core dumps.
55
56        <B>-v</B><I>n</I>    specifies that (verbose) output be written to stan-
57               dard  error   trace   information   showing   <B>tic</B>'s
58               progress.   The optional integer <I>n</I> is a number from
59               1 to 10, inclusive, indicating the desired level of
60               detail  of  information.   If  <I>n</I>  is  omitted,  the
61               default level is 1.  If <I>n</I> is specified and  greater
62               than 1, the level of detail is increased.
63
64        <B>-o</B><I>dir</I>  Write   compiled   entries   to   given  directory.
65               Overrides the TERMINFO environment variable.
66
67        <B>-w</B><I>n</I>    specifies the width of the output.
68
69        <B>-1</B>     restricts the output to a single column
70
71        <B>-C</B>     Force source translation to termcap format.   Note:
72               this  differs  from the -C option of <B><A HREF="infocmp.1m.html">infocmp(1m)</A></B> in
73               that it does not merely translate capability names,
74               but  also  translates  terminfo  strings to termcap
75               format.  Capabilities that are not translatable are
76               left  in  the  entry under their terminfo names but
77               commented out with two preceding dots.
78
79        <B>-G</B>     Display constant literals in  decimal  form  rather
80               than their character equivalents.
81
82        <B>-I</B>     Force source translation to terminfo format.
83
84        <B>-L</B>     Force  source  translation to terminfo format using
85               the long C variable names listed in &lt;<B>term.h</B>&gt;
86
87        <B>-N</B>     Disable smart defaults.  Normally, when translating
88               from termcap to terminfo, the compiler makes a num-
89               ber of assumptions about  the  defaults  of  string
90               capabilities  <B>reset1_string</B>,  <B>carriage_return</B>, <B>cur-</B>
91               <B>sor_left</B>, <B>cursor_down</B>,  <B>scroll_forward</B>,  <B>tab</B>,  <B>new-</B>
92               <B>line</B>,  <B>key_backspace</B>,  <B>key_left</B>, and <B>key_down</B>, then
93               attempts to use obsolete  termcap  capabilities  to
94               deduce correct values.  It also normally suppresses
95               output of obsolete termcap capabilities such as <B>bs</B>.
96               This  option forces a more literal translation that
97               also preserves the obsolete capabilities.
98
99        <B>-R</B><I>subset</I>
100               Restrict output to a given subset.  This option  is
101               for  use  with  archaic  versions  of terminfo like
102               those on SVr1, Ultrix, or HP/UX that don't  support
103               the  full set of SVR4/XSI Curses terminfo; and out-
104               right broken ports like AIX 3.x that have their own
105               extensions  incompatible  with SVr4/XSI.  Available
106               subsets  are  "SVr1",  "Ultrix",  "HP",  "BSD"  and
107               "AIX"; see <B><A HREF="terminfo.5.html">terminfo(5)</A></B> for details.
108
109        <B>-T</B>     eliminates size-restrictions on the generated text.
110               This is mainly useful  for  testing  and  analysis,
111               since  the compiled descriptions are limited (e.g.,
112               1023 for termcap, 4096 for terminfo).
113
114        <B>-V</B>     reports the version of ncurses which  was  used  in
115               this program, and exits.
116
117        <B>-r</B>     Force  entry  resolution (so there are no remaining
118               tc capabilities) even  when  doing  translation  to
119               termcap  format.   This  may  be  needed if you are
120               preparing a termcap  file  for  a  termcap  library
121               (such as GNU termcap up to version 1.3 or BSD term-
122               cap up to 4.3BSD) that doesn't handle  multiple  tc
123               capabilities per entry.
124
125        <B>-e</B>     Limit  writes  and  translations  to  the following
126               comma-separated list of terminals.  If any name  or
127               alias of a terminal matches one of the names in the
128               list, the entry will be written  or  translated  as
129               normal.   Otherwise no output will be generated for
130               it.  The option value is interpreted as a file con-
131               taining  the  list  if  it  contains a '/'.  (Note:
132               depending on how tic was compiled, this option  may
133               require -I or -C.)
134
135        <B>-f</B>     Display  complex  terminfo  strings  which  contain
136               if/then/else/endif expressions indented  for  read-
137               ability.
138
139        <B>-g</B>     Display  constant character literals in quoted form
140               rather than their decimal equivalents.
141
142        <B>-s</B>     Summarize the compile by showing the directory into
143               which  entries  are  written,  and  the  number  of
144               entries which are compiled.
145
146        <B>-x</B>     Treat unknown capabilities as  user-defined.   That
147               is,  if you supply a capability name which <B>tic</B> does
148               not recognize, it will  infer  its  type  (boolean,
149               number  or  string)  from  the  syntax  and make an
150               extended table entry for that.
151
152        <I>file</I>   contains one or more <B>terminfo</B> terminal descriptions
153               in  source format [see <B><A HREF="terminfo.5.html">terminfo(5)</A></B>].  Each descrip-
154               tion in the file describes the  capabilities  of  a
155               particular terminal.
156
157        The debug flag levels are as follows:
158
159        1      Names of files created and linked
160
161        2      Information related to the ``use'' facility
162
163        3      Statistics from the hashing algorithm
164
165        5      String-table memory allocations
166
167        7      Entries into the string-table
168
169        8      List of tokens encountered by scanner
170
171        9      All  values  computed  in  construction of the hash
172               table
173
174        If n is not given, it is taken to be one.
175
176        All but one of the capabilities recognized by <B>tic</B> are doc-
177        umented in <B><A HREF="terminfo.5.html">terminfo(5)</A></B>.  The exception is the <B>use</B> capabil-
178        ity.
179
180        When a <B>use</B>=<I>entry</I>-<I>name</I> field is discovered  in  a  terminal
181        entry  currently  being  compiled, <B>tic</B> reads in the binary
182        from <B>/usr/share/terminfo</B> to complete the entry.   (Entries
183        created  from <I>file</I> will be used first.  If the environment
184        variable <B>TERMINFO</B>  is  set,  that  directory  is  searched
185        instead of <B>/usr/share/terminfo</B>.)  <B>tic</B> duplicates the capa-
186        bilities in <I>entry</I>-<I>name</I> for the  current  entry,  with  the
187        exception   of  those  capabilities  that  explicitly  are
188        defined in the current entry.
189
190        When   an   entry,   e.g.,   <B>entry_name_1</B>,   contains    a
191        <B>use=</B><I>entry</I>_<I>name</I>_<I>2</I>   field,  any  canceled  capabilities  in
192        <I>entry</I>_<I>name</I>_<I>2</I> must also appear in <B>entry_name_1</B> before  <B>use=</B>
193        for these capabilities to be canceled in <B>entry_name_1</B>.
194
195        If  the environment variable <B>TERMINFO</B> is set, the compiled
196        results are placed there instead of <B>/usr/share/terminfo</B>.
197
198        Total compiled entries cannot exceed 4096 bytes.  The name
199        field  cannot  exceed 512 bytes.  Terminal names exceeding
200        the maximum alias length (32 characters  on  systems  with
201        long filenames, 14 characters otherwise) will be truncated
202        to the maximum alias length and a warning message will  be
203        printed.
204
205
206 </PRE>
207 <H2>COMPATIBILITY</H2><PRE>
208        There  is  some evidence that historic <B>tic</B> implementations
209        treated description fields with no whitespace in  them  as
210        additional  aliases  or short names.  This <B>tic</B> does not do
211        that, but it does warn  when  description  fields  may  be
212        treated  that way and check them for dangerous characters.
213
214
215 </PRE>
216 <H2>EXTENSIONS</H2><PRE>
217        Unlike the stock SVr4 <B>tic</B> command, this implementation can
218        actually  compile  termcap  sources.   In fact, entries in
219        terminfo and termcap syntax  can  be  mixed  in  a  single
220        source  file.   See  <B><A HREF="terminfo.5.html">terminfo(5)</A></B>  for  the list of termcap
221        names taken to be equivalent to terminfo names.
222
223        The SVr4 manual pages are  not  clear  on  the  resolution
224        rules  for  <B>use</B>  capabilities.  This implementation of <B>tic</B>
225        will find <B>use</B> targets anywhere in the source file, or any-
226        where  in the file tree rooted at <B>TERMINFO</B> (if <B>TERMINFO</B> is
227        defined), or in the user's <I>$HOME/.terminfo</I>  directory  (if
228        it  exists),  or  (finally)  anywhere in the system's file
229        tree of compiled entries.
230
231        The error messages from this <B>tic</B> have the same  format  as
232        GNU  C  error  messages,  and can be parsed by GNU Emacs's
233        compile facility.
234
235        The <B>-C</B>, <B>-G</B>, <B>-I</B>, <B>-N</B>, <B>-R</B>, <B>-T</B>, <B>-V</B>, <B>-a</B>, <B>-e</B>, <B>-f</B>, <B>-g</B>, <B>-o</B>, <B>-r</B>, <B>-s</B>
236        and  <B>-x</B> options are not supported under SVr4.  The SVr4 -c
237        mode does not report bad use links.
238
239        System V does not compile entries to or read entries  from
240        your  <I>$HOME/.terminfo</I> directory unless TERMINFO is explic-
241        itly set to it.
242
243
244 </PRE>
245 <H2>FILES</H2><PRE>
246        <B>/usr/share/terminfo/?/*</B>
247             Compiled terminal description database.
248
249
250 </PRE>
251 <H2>SEE ALSO</H2><PRE>
252        <B><A HREF="infocmp.1m.html">infocmp(1m)</A></B>,   <B><A HREF="captoinfo.1m.html">captoinfo(1m)</A></B>,   <B><A HREF="infotocap.1m.html">infotocap(1m)</A></B>,    <B><A HREF="toe.1m.html">toe(1m)</A></B>,
253        <B><A HREF="ncurses.3x.html">curses(3x)</A></B>, <B><A HREF="terminfo.5.html">terminfo(5)</A></B>.
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290 </PRE>
291 <HR>
292 <ADDRESS>
293 Man(1) output converted with
294 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
295 </ADDRESS>
296 </BODY>
297 </HTML>