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