d0d08765504c21c1a09fdcd9bcb00c1b785ec7e2
[ncurses.git] / man / tic.1m
1 .\"***************************************************************************
2 .\" Copyright (c) 1998-2012,2013 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.57 2013/02/02 22:09:02 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 command writes only one type of entry,
78 depending on how it was built:
79 .bP
80 For directory trees, the top-level directory, e.g., /usr/share/terminfo,
81 specifies the location of the database.
82 .bP
83 For hashed databases, a filename is needed.
84 If the given file is not found by that name,
85 but can be found by adding the suffix ".db",
86 then that is used.
87 .IP
88 The default name for the hashed database is the same as the
89 default directory name (only adding a ".db" suffix).
90 .PP
91 In either case (directory or hashed database),
92 \fB@TIC@\fP will create the container if it does not exist.
93 For a directory, this would be the "terminfo" leaf,
94 versus a "terminfo.db" file.
95 .PP
96 The results are normally placed in the system terminfo database \fB\*d\fR.
97 The compiled terminal description can be placed
98 in a different terminfo database.
99 There are two ways to achieve this:
100 .bP
101 First, you may override the system default either by
102 using the \fB\-o\fP option,
103 or by setting the variable \fBTERMINFO\fR
104 in your shell environment to a valid database location.
105 .bP
106 Secondly, if \fB@TIC@\fR cannot write in \fI\*d\fR
107 or the location specified using your TERMINFO variable,
108 it looks for the directory \fI$HOME/.terminfo\fR
109 (or hashed database \fI$HOME/.terminfo.db)\fR;
110 if that location exists, the entry is placed there.
111 .PP
112 Libraries that read terminfo entries are expected to check in succession
113 .bP
114 a location specified with the TERMINFO environment variable,
115 .bP
116 \fI$HOME/.terminfo\fR,
117 .bP
118 directories listed in the TERMINFO_DIRS environment variable,
119 .bP
120 a compiled-in list of directories (@TERMINFO_DIRS@), and
121 .bP
122 the system terminfo database (\fI\*d\fR).
123 .SS OPTIONS
124 .TP
125 \fB\-0\fR
126 restricts the output to a single line
127 .TP
128 \fB\-1\fR
129 restricts the output to a single column
130 .TP
131 \fB\-a\fR
132 tells \fB@TIC@\fP to retain commented-out capabilities rather than discarding
133 them.
134 Capabilities are commented by prefixing them with a period.
135 This sets the \fB\-x\fR option, because it treats the commented-out
136 entries as user-defined names.
137 If the source is termcap, accept the 2-character names required by version 6.
138 Otherwise these are ignored.
139 .TP
140 \fB\-C\fR
141 Force source translation to termcap format.
142 Note: this differs from the \fB\-C\fR
143 option of \fB@INFOCMP@\fR(1M) in that it does not merely translate capability
144 names, but also translates terminfo strings to termcap format.
145 Capabilities
146 that are not translatable are left in the entry under their terminfo names
147 but commented out with two preceding dots.
148 The actual format used incorporates some improvements for escaped characters
149 from terminfo format.
150 For a stricter BSD-compatible translation, add the \fB\-K\fR option.
151 .TP
152 \fB\-c\fR
153 tells \fB@TIC@\fP to only check \fIfile\fR for errors, including syntax problems and
154 bad use links.
155 If you specify \fB\-C\fR (\fB\-I\fR) with this option, the code
156 will print warnings about entries which, after use resolution, are more than
157 1023 (4096) bytes long.
158 Due to a fixed buffer length in older termcap libraries,
159 as well as buggy checking for the buffer length
160 (and a documented limit in terminfo),
161 these entries may cause core
162 dumps with other implementations.
163 .TP
164 \fB\-D\fR
165 tells \fB@TIC@\fP to print the database locations that it knows about, and exit.
166 The first location shown is the one to which it would write compiled
167 terminal descriptions.
168 If \fB@TIC@\fP is not able to find a writable database location
169 according to the rules summarized above,
170 it will print a diagnostic and exit with an error rather than
171 printing a list of database locations.
172 .TP
173 \fB\-e \fR\fInames\fR
174 Limit writes and translations to the following comma-separated list of
175 terminals.
176 If any name or alias of a terminal matches one of the names in
177 the list, the entry will be written or translated as normal.
178 Otherwise no output will be generated for it.
179 The option value is interpreted as a file containing the list if it
180 contains a '/'.
181 (Note: depending on how tic was compiled, this option may require \fB\-I\fR or \fB\-C\fR.)
182 .TP
183 \fB\-f\fR
184 Display complex terminfo strings which contain if/then/else/endif expressions
185 indented for readability.
186 .TP
187 \fB\-G\fR
188 Display constant literals in decimal form
189 rather than their character equivalents.
190 .TP
191 \fB\-g\fR
192 Display constant character literals in quoted form
193 rather than their decimal equivalents.
194 .TP
195 \fB\-I\fR
196 Force source translation to terminfo format.
197 .TP
198 \fB\-K\fR
199 Suppress some longstanding ncurses extensions to termcap format,
200 e.g., "\\s" for space.
201 .TP
202 \fB\-L\fR
203 Force source translation to terminfo format
204 using the long C variable names listed in <\fBterm.h\fR>
205 .TP
206 \fB\-N\fR
207 Disable smart defaults.
208 Normally, when translating from termcap to terminfo, the compiler makes
209 a number of assumptions about the defaults of string capabilities
210 \fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR,
211 \fBcursor_down\fR, \fBscroll_forward\fR, \fBtab\fR, \fBnewline\fR,
212 \fBkey_backspace\fR, \fBkey_left\fR, and \fBkey_down\fR, then attempts
213 to use obsolete termcap capabilities to deduce correct values.
214 It also
215 normally suppresses output of obsolete termcap capabilities such as \fBbs\fR.
216 This option forces a more literal translation that also preserves the
217 obsolete capabilities.
218 .TP
219 \fB\-o\fR\fIdir\fR
220 Write compiled entries to given database location.
221 Overrides the TERMINFO environment variable.
222 .TP
223 \fB\-R\fR\fIsubset\fR
224 Restrict output to a given subset.
225 This option is for use with archaic
226 versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support
227 the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x
228 that have their own extensions incompatible with SVr4/XSI.
229 Available subsets
230 are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; see \fBterminfo\fR(\*n) for details.
231 .TP
232 \fB\-r\fR
233 Force entry resolution (so there are no remaining tc capabilities) even
234 when doing translation to termcap format.
235 This may be needed if you are
236 preparing a termcap file for a termcap library (such as GNU termcap through
237 version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple
238 tc capabilities per entry.
239 .TP
240 \fB\-s\fR
241 Summarize the compile by showing the database location into which entries
242 are written, and the number of entries which are compiled.
243 .TP
244 \fB\-T\fR
245 eliminates size-restrictions on the generated text.
246 This is mainly useful for testing and analysis, since the compiled
247 descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
248 .TP
249 \fB\-t\fR
250 tells \fB@TIC@\fP to discard commented-out capabilities.
251 Normally when translating from terminfo to termcap,
252 untranslatable capabilities are commented-out.
253 .TP 5
254 \fB\-U\fR
255 tells \fB@TIC@\fP to not post-process the data after parsing the source file.
256 Normally, it infers data which is commonly missing in older terminfo data,
257 or in termcaps.
258 .TP
259 \fB\-V\fR
260 reports the version of ncurses which was used in this program, and exits.
261 .TP
262 \fB\-v\fR\fIn\fR
263 specifies that (verbose) output be written to standard error trace
264 information showing \fB@TIC@\fR's progress.
265 The optional parameter \fIn\fR is a number from 1 to 10, inclusive,
266 indicating the desired level of detail of information.
267 If \fIn\fR is omitted, the default level is 1.
268 If \fIn\fR is specified and greater than 1, the level of
269 detail is increased.
270 .RS
271 .PP
272 The debug flag levels are as follows:
273 .TP
274 1
275 Names of files created and linked
276 .TP
277 2
278 Information related to the ``use'' facility
279 .TP
280 3
281 Statistics from the hashing algorithm
282 .TP
283 5
284 String-table memory allocations
285 .TP
286 7
287 Entries into the string-table
288 .TP
289 8
290 List of tokens encountered by scanner
291 .TP
292 9
293 All values computed in construction of the hash table
294 .LP
295 If the debug level \fIn\fR is not given, it is taken to be one.
296 .RE
297 .TP
298 \fB\-w\fR\fIn\fR
299 specifies the width of the output.
300 The parameter is optional.
301 If it is omitted, it defaults to 60.
302 .TP
303 \fB\-x\fR
304 Treat unknown capabilities as user-defined.
305 That is, if you supply a capability name which \fB@TIC@\fP does not recognize,
306 it will infer its type (boolean, number or string) from the syntax and
307 make an extended table entry for that.
308 User-defined capability strings
309 whose name begins with ``k'' are treated as function keys.
310 .SS PARAMETERS
311 .TP
312 \fIfile\fR
313 contains one or more \fBterminfo\fR terminal descriptions in source
314 format [see \fBterminfo\fR(\*n)].
315 Each description in the file
316 describes the capabilities of a particular terminal.
317 .IP
318 If \fIfile\fR is ``-'', then the data is read from the standard input.
319 The \fIfile\fR parameter may also be the path of a character-device.
320 .SS PROCESSING
321 .PP
322 All but one of the capabilities recognized by \fB@TIC@\fR are documented
323 in \fBterminfo\fR(\*n).
324 The exception is the \fBuse\fR capability.
325 .PP
326 When a \fBuse\fR=\fIentry\fR\-\fIname\fR field is discovered in a
327 terminal entry currently being compiled, \fB@TIC@\fR reads in the binary
328 from \fB\*d\fR to complete the entry.
329 (Entries created from
330 \fIfile\fR will be used first.
331 \fB@TIC@\fR duplicates the capabilities in
332 \fIentry\fR\-\fIname\fR for the current entry, with the exception of
333 those capabilities that explicitly are defined in the current entry.
334 .PP
335 When an entry, e.g., \fBentry_name_1\fR, contains a
336 \fBuse=\fR\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled
337 capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in
338 \fBentry_name_1\fR before \fBuse=\fR for these capabilities to be
339 canceled in \fBentry_name_1\fR.
340 .PP
341 Total compiled entries cannot exceed 4096 bytes.
342 The name field cannot
343 exceed 512 bytes.
344 Terminal names exceeding the maximum alias length
345 (32 characters on systems with long filenames, 14 characters otherwise)
346 will be truncated to the maximum alias length and a warning message will be printed.
347 .SH COMPATIBILITY
348 There is some evidence that historic \fB@TIC@\fR implementations treated
349 description fields with no whitespace in them as additional aliases or
350 short names.
351 This \fB@TIC@\fR does not do that, but it does warn when
352 description fields may be treated that way and check them for dangerous
353 characters.
354 .SH EXTENSIONS
355 Unlike the SVr4 \fB@TIC@\fR command, this implementation can actually
356 compile termcap sources.
357 In fact, entries in terminfo and termcap syntax can
358 be mixed in a single source file.
359 See \fBterminfo\fR(\*n) for the list of
360 termcap names taken to be equivalent to terminfo names.
361 .PP
362 The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR
363 capabilities.
364 This implementation of \fB@TIC@\fR will find \fBuse\fR targets anywhere
365 in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if
366 \fBTERMINFO\fR is defined),
367 or in the user's \fI$HOME/.terminfo\fR database
368 (if it exists),
369 or (finally) anywhere in the system's file tree of
370 compiled entries.
371 .PP
372 The error messages from this \fB@TIC@\fR have the same format as GNU C
373 error messages, and can be parsed by GNU Emacs's compile facility.
374 .PP
375 The
376 \fB\-0\fR,
377 \fB\-1\fR,
378 \fB\-C\fR,
379 \fB\-G\fR,
380 \fB\-I\fR,
381 \fB\-N\fR,
382 \fB\-R\fR,
383 \fB\-T\fR,
384 \fB\-V\fR,
385 \fB\-a\fR,
386 \fB\-e\fR,
387 \fB\-f\fR,
388 \fB\-g\fR,
389 \fB\-o\fR,
390 \fB\-r\fR,
391 \fB\-s\fR,
392 \fB\-t\fR and
393 \fB\-x\fR
394 options
395 are not supported under SVr4.
396 The SVr4 \fB\-c\fR mode does not report bad use links.
397 .PP
398 System V does not compile entries to or read entries from your
399 \fI$HOME/.terminfo\fR database unless TERMINFO is explicitly set to it.
400 .SH FILES
401 .TP 5
402 \fB\*d/?/*\fR
403 Compiled terminal description database.
404 .SH SEE ALSO
405 \fB@INFOCMP@\fR(1M),
406 \fB@CAPTOINFO@\fR(1M),
407 \fB@INFOTOCAP@\fR(1M),
408 \fB@TOE@\fR(1M),
409 \fBcurses\fR(3X),
410 \fBterm\fR(\*n).
411 \fBterminfo\fR(\*n).
412 .PP
413 This describes \fBncurses\fR
414 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
415 .SH AUTHOR
416 Eric S. Raymond <esr@snark.thyrsus.com>
417 and
418 .br
419 Thomas E. Dickey <dickey@invisible-island.net>