Commit | Line | Data |
---|---|---|
8331b1d2 JM |
1 | .\"*************************************************************************** |
2 | .\" Copyright (c) 1998-2006,2010 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.47 2010/12/04 18:38:55 tom Exp $ | |
3eec8774 | 30 | .Dd March 11, 2016 |
ff2cf2db FF |
31 | .Dt TIC 1 |
32 | .Os | |
33 | .Sh NAME | |
34 | .Nm tic | |
35 | .Nd the terminfo entry-description compiler | |
36 | .Sh SYNOPSIS | |
37 | .Nm | |
38 | .Op Fl 1CGILNTUVacfgrstx | |
39 | .Op Fl e Ar names | |
40 | .Op Fl o Ar dir | |
41 | .Op Fl R Ar subset | |
42 | .Op Fl v Ns Op Ar n | |
43 | .Op Fl w Ns Op Ar n | |
44 | .Ar file | |
45 | .Sh DESCRIPTION | |
46 | The command | |
47 | .Nm | |
48 | translates a | |
49 | .Xr terminfo 5 | |
50 | file from source format into compiled format. | |
51 | The compiled format is necessary for use with the library routines in | |
52 | .Xr ncurses 3 . | |
53 | .Pp | |
54 | The results are normally placed in the system terminfo directory | |
55 | .Pa /usr/share/terminfo . | |
8331b1d2 | 56 | There are two ways to change this behavior. |
ff2cf2db | 57 | .Pp |
8331b1d2 | 58 | First, you may override the system default by setting the variable |
ff2cf2db FF |
59 | .Ev TERMINFO |
60 | in your shell environment to a valid (existing) directory name. | |
61 | .Pp | |
62 | Secondly, if | |
63 | .Nm | |
64 | cannot get access to | |
65 | .Pa /usr/share/terminfo | |
66 | or your | |
67 | .Ev TERMINFO | |
68 | directory, it looks for the directory | |
69 | .Pa $HOME/.terminfo ; | |
70 | if that directory exists, the entry is placed there. | |
71 | .Pp | |
72 | Libraries that read terminfo entries are expected to check for a | |
73 | .Ev TERMINFO | |
74 | directory first, look at | |
75 | .Pa $HOME/.terminfo | |
76 | if | |
77 | .Ev TERMINFO | |
78 | is not set, and finally look in | |
79 | .Pa /usr/share/terminfo . | |
073f874b | 80 | .Bl -tag -width ".Fl R subset" |
3eec8774 JM |
81 | .It Fl 0 |
82 | restricts the output to a single line | |
ff2cf2db | 83 | .It Fl 1 |
8331b1d2 | 84 | restricts the output to a single column |
ff2cf2db FF |
85 | .It Fl a |
86 | tells | |
87 | .Nm | |
88 | to retain commented-out capabilities rather than discarding them. | |
8331b1d2 | 89 | Capabilities are commented by prefixing them with a period. |
ff2cf2db FF |
90 | This sets the |
91 | .Fl x | |
92 | option, because it treats the commented-out entries as user-defined names. | |
8331b1d2 JM |
93 | If the source is termcap, accept the 2-character names required by version 6. |
94 | Otherwise these are ignored. | |
ff2cf2db | 95 | .It Fl C |
8331b1d2 | 96 | Force source translation to termcap format. |
ff2cf2db FF |
97 | Capabilities that are not translatable are left in the entry under |
98 | their terminfo names but commented out with two preceding dots. | |
3eec8774 | 99 | The actual format used incorporates some improvements for escaped characters |
073f874b SW |
100 | from terminfo format. |
101 | For a stricter BSD-compatible translation, add the | |
3eec8774 JM |
102 | .Fl K |
103 | option. | |
104 | .Pp | |
073f874b SW |
105 | If this is combined with |
106 | .Fl c , | |
107 | .Nm | |
108 | makes additional checks to report cases | |
3eec8774 JM |
109 | where the terminfo values do not have an exact equivalent in termcap form. |
110 | For example: | |
073f874b | 111 | .Bl -bullet |
3eec8774 JM |
112 | .It |
113 | sgr usually will not convert, because termcap lacks the ability to work | |
114 | with more than two parameters, and because termcap lacks many of the | |
115 | arithmetic/logical operators used in terminfo. | |
116 | .It | |
117 | capabilities with more than one delay or with delays before the end of | |
118 | the string will not convert completely. | |
119 | .El | |
ff2cf2db FF |
120 | .It Fl c |
121 | tells | |
122 | .Nm | |
123 | to only check | |
124 | .Ar file | |
125 | for errors, including syntax problems and bad use links. | |
126 | If you specify | |
127 | .Fl C | |
128 | .Pq Fl I | |
129 | with this option, the code will print warnings about entries which, | |
130 | after use resolution, are more than 1023 (4096) bytes long. | |
131 | Due to a fixed buffer length in older termcap libraries | |
132 | (and a documented limit in terminfo), | |
3eec8774 JM |
133 | these entries may cause core dumps with other implementations. |
134 | .Pp | |
135 | .Nm | |
136 | checks string capabilities to ensure that those with parameters will be | |
073f874b SW |
137 | valid expressions. |
138 | It does this check only for the predefined string | |
3eec8774 JM |
139 | capabilities; those which are defined with the |
140 | .Fl x | |
141 | option are ignored. | |
142 | .It Fl D | |
143 | tells | |
144 | .Nm | |
145 | to print the database locations that it knows about, and exit. | |
146 | The first location shown is the one to which it would write compiled | |
073f874b SW |
147 | terminal descriptions. |
148 | If | |
3eec8774 JM |
149 | .Nm |
150 | is not able to find a writable database location according to the rules | |
151 | summarized above, it will print a diagnostic and exit with an | |
152 | error rather than printing a list of database locations. | |
ff2cf2db | 153 | .It Fl e Ar names |
8331b1d2 JM |
154 | Limit writes and translations to the following comma-separated list of |
155 | terminals. | |
156 | If any name or alias of a terminal matches one of the names in | |
157 | the list, the entry will be written or translated as normal. | |
158 | Otherwise no output will be generated for it. | |
159 | The option value is interpreted as a file containing the list if it | |
ff2cf2db FF |
160 | contains a |
161 | .Sq / . | |
162 | Note: depending on how | |
163 | .Nm | |
164 | was compiled, this option may require | |
165 | .Fl I | |
166 | or | |
167 | .Fl C . | |
168 | .It Fl f | |
8331b1d2 JM |
169 | Display complex terminfo strings which contain if/then/else/endif expressions |
170 | indented for readability. | |
ff2cf2db | 171 | .It Fl G |
8331b1d2 JM |
172 | Display constant literals in decimal form |
173 | rather than their character equivalents. | |
ff2cf2db | 174 | .It Fl g |
8331b1d2 JM |
175 | Display constant character literals in quoted form |
176 | rather than their decimal equivalents. | |
ff2cf2db | 177 | .It Fl I |
8331b1d2 | 178 | Force source translation to terminfo format. |
3eec8774 JM |
179 | .It Fl K |
180 | Suppress some longstanding ncurses extensions to termcap format, | |
181 | e.g., | |
182 | .Do | |
183 | \\s | |
184 | .Dc | |
185 | for space. | |
ff2cf2db | 186 | .It Fl L |
8331b1d2 | 187 | Force source translation to terminfo format |
ff2cf2db FF |
188 | using the long C variable names listed in |
189 | .In term.h | |
190 | .It Fl N | |
8331b1d2 JM |
191 | Disable smart defaults. |
192 | Normally, when translating from termcap to terminfo, the compiler makes | |
193 | a number of assumptions about the defaults of string capabilities | |
ff2cf2db FF |
194 | .Cm reset1_string , |
195 | .Cm carriage_return , | |
196 | .Cm cursor_left , | |
197 | .Cm cursor_down , | |
198 | .Cm scroll_forward , | |
199 | .Cm tab , | |
200 | .Cm newline , | |
201 | .Cm key_backspace , | |
202 | .Cm key_left , | |
203 | and | |
204 | .Cm key_down , | |
205 | then attempts to use obsolete termcap capabilities to deduce correct values. | |
206 | It also normally suppresses output of obsolete termcap capabilities such as | |
207 | .Cm bs . | |
8331b1d2 JM |
208 | This option forces a more literal translation that also preserves the |
209 | obsolete capabilities. | |
ff2cf2db | 210 | .It Fl o Ar dir |
8331b1d2 | 211 | Write compiled entries to given directory. |
ff2cf2db FF |
212 | Overrides the |
213 | .Ev TERMINFO | |
214 | environment variable. | |
215 | .It Fl R Ar subset | |
8331b1d2 | 216 | Restrict output to a given subset. |
ff2cf2db FF |
217 | This option is for use with archaic versions of terminfo like those on |
218 | SVr1, Ultrix, or HP/UX that do not support the full set of | |
219 | SVR4/XSI Curses terminfo; | |
220 | and outright broken ports like AIX 3.x | |
8331b1d2 | 221 | that have their own extensions incompatible with SVr4/XSI. |
ff2cf2db FF |
222 | Available subsets are |
223 | .Dq SVr1 , | |
224 | .Dq Ultrix , | |
225 | .Dq HP , | |
226 | .Dq BSD | |
227 | and | |
228 | .Dq AIX ; | |
229 | see | |
230 | .Xr terminfo 5 | |
231 | for details. | |
232 | .It Fl r | |
8331b1d2 JM |
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 | |
ff2cf2db FF |
237 | version 1.3 or BSD termcap through |
238 | .Bx 4.3 ) | |
239 | that does not handle multiple tc capabilities per entry. | |
240 | .It Fl s | |
8331b1d2 JM |
241 | Summarize the compile by showing the directory into which entries |
242 | are written, and the number of entries which are compiled. | |
ff2cf2db | 243 | .It Fl T |
8331b1d2 JM |
244 | eliminates size-restrictions on the generated text. |
245 | This is mainly useful for testing and analysis, since the compiled | |
073f874b | 246 | descriptions are limited (e.g.\& 1023 for termcap, 4096 for terminfo). |
ff2cf2db FF |
247 | .It Fl t |
248 | tells | |
249 | .Nm | |
250 | to discard commented-out capabilities. | |
8331b1d2 JM |
251 | Normally when translating from terminfo to termcap, |
252 | untranslatable capabilities are commented-out. | |
ff2cf2db FF |
253 | .It Fl U |
254 | tells | |
255 | .Nm | |
256 | to not post-process the data after parsing the source file. | |
8331b1d2 JM |
257 | Normally, it infers data which is commonly missing in older terminfo data, |
258 | or in termcaps. | |
ff2cf2db FF |
259 | .It Fl V |
260 | reports the version of | |
261 | .Xr ncurses 3 | |
262 | which was used in this program, and exits. | |
263 | .It Fl v Ns Op Ar n | |
8331b1d2 | 264 | specifies that (verbose) output be written to standard error trace |
ff2cf2db FF |
265 | information showing |
266 | .Nm Ns 's | |
267 | progress. | |
268 | The optional parameter | |
269 | .Ar n | |
270 | is a number from 1 to 10, inclusive, | |
8331b1d2 | 271 | indicating the desired level of detail of information. |
ff2cf2db FF |
272 | If |
273 | .Ar n | |
274 | is omitted, the default level is 1. | |
275 | If | |
276 | .Ar n | |
277 | is specified and greater than 1, the level of | |
8331b1d2 | 278 | detail is increased. |
ff2cf2db | 279 | .Pp |
8331b1d2 | 280 | The debug flag levels are as follows: |
3eec8774 | 281 | .Bl -tag -width "1xxx" -compact |
ff2cf2db | 282 | .It 1 |
8331b1d2 | 283 | Names of files created and linked |
ff2cf2db FF |
284 | .It 2 |
285 | Information related to the | |
286 | .Dq use | |
287 | facility | |
288 | .It 3 | |
8331b1d2 | 289 | Statistics from the hashing algorithm |
ff2cf2db | 290 | .It 5 |
8331b1d2 | 291 | String-table memory allocations |
ff2cf2db | 292 | .It 7 |
8331b1d2 | 293 | Entries into the string-table |
ff2cf2db | 294 | .It 8 |
8331b1d2 | 295 | List of tokens encountered by scanner |
ff2cf2db | 296 | .It 9 |
8331b1d2 | 297 | All values computed in construction of the hash table |
ff2cf2db FF |
298 | .El |
299 | .Pp | |
300 | If the debug level | |
301 | .Ar n | |
302 | is not given, it is taken to be one. | |
3eec8774 JM |
303 | .It Fl w Ns Op Ar n |
304 | specifies the width of the output. | |
305 | The parameter is optional. | |
306 | If it is omitted, it defaults to 60. | |
307 | .It Fl x | |
308 | Treat unknown capabilities as user-defined. | |
309 | That is, if you supply a capability name which | |
310 | .Nm | |
311 | does not recognize, it will infer its type (boolean, number or string) | |
312 | from the syntax and make an extended table entry for that. | |
313 | User-defined capability strings | |
314 | whose name begins with | |
315 | .Sq k | |
316 | are treated as function keys. | |
073f874b | 317 | .El |
3eec8774 JM |
318 | .Sh PARAMETERS |
319 | .Bl -tag -width "file" | |
320 | .It Ar file | |
321 | contains one or more | |
322 | .Xr terminfo 5 | |
323 | terminal descriptions in source format. | |
324 | Each description in the file | |
325 | describes the capabilities of a particular terminal. | |
326 | .Pp | |
327 | If file is "-", then the data is read from the standard input. | |
328 | The file parameter may also be the path of a character-device. | |
329 | .El | |
330 | .Sh PROCESSING | |
ff2cf2db FF |
331 | All but one of the capabilities recognized by |
332 | .Nm | |
333 | are documented in | |
334 | .Xr terminfo 5 . | |
335 | The exception is the | |
336 | .Cm use | |
337 | capability. | |
338 | .Pp | |
339 | When a | |
340 | .Cm use Ns Li = Ns Ar entry-name | |
341 | field is discovered in a terminal entry currently being compiled, | |
342 | .Nm | |
343 | reads in the binary from | |
344 | .Pa /usr/share/terminfo | |
345 | to complete the entry. | |
8331b1d2 | 346 | (Entries created from |
ff2cf2db FF |
347 | .Ar file |
348 | will be used first. | |
8331b1d2 | 349 | If the environment variable |
ff2cf2db FF |
350 | .Ev TERMINFO |
351 | is set, that directory is searched instead of | |
352 | .Pa /usr/share/terminfo . ) | |
353 | .Nm | |
354 | duplicates the capabilities in | |
355 | .Ar entry-name | |
356 | for the current entry, with the exception of | |
8331b1d2 | 357 | those capabilities that explicitly are defined in the current entry. |
ff2cf2db FF |
358 | .Pp |
359 | When an entry, e.g.\& | |
360 | .Li entry_name_1 , | |
361 | contains a | |
362 | .Cm use Ns Li = Ns Li entry_name_2 | |
363 | field, any canceled capabilities in | |
364 | .Li entry_name_2 | |
365 | must also appear in | |
366 | .Li entry_name_1 | |
367 | before | |
368 | .Cm use Ns Li = | |
369 | for these capabilities to be canceled in | |
370 | .Li entry_name_1 . | |
371 | .Pp | |
372 | If the environment variable | |
373 | .Ev TERMINFO | |
374 | is set, the compiled results are placed there instead of | |
375 | .Pa /usr/share/terminfo . | |
376 | .Pp | |
8331b1d2 | 377 | Total compiled entries cannot exceed 4096 bytes. |
ff2cf2db | 378 | The name field cannot exceed 512 bytes. |
8331b1d2 JM |
379 | Terminal names exceeding the maximum alias length |
380 | (32 characters on systems with long filenames, 14 characters otherwise) | |
ff2cf2db FF |
381 | will be truncated to the maximum alias length and a warning message |
382 | will be printed. | |
383 | .Ss COMPATIBILITY | |
384 | There is some evidence that historic | |
385 | .Nm | |
386 | implementations treated description fields with no whitespace | |
387 | in them as additional aliases or short names. | |
388 | This | |
389 | .Nm | |
390 | does not do that, but it does warn when description fields may be | |
391 | treated that way and check them for dangerous characters. | |
392 | .Ss EXTENSIONS | |
393 | Unlike the stock SVr4 | |
394 | .Nm | |
395 | command, this implementation can actually compile termcap sources. | |
8331b1d2 JM |
396 | In fact, entries in terminfo and termcap syntax can |
397 | be mixed in a single source file. | |
ff2cf2db FF |
398 | See |
399 | .Xr terminfo 5 | |
400 | for the list of termcap names taken to be equivalent to terminfo names. | |
401 | .Pp | |
402 | The SVr4 manual pages are not clear on the resolution rules for | |
403 | .Cm use | |
8331b1d2 | 404 | capabilities. |
ff2cf2db FF |
405 | This implementation of |
406 | .Nm | |
407 | will find | |
408 | .Cm use | |
409 | targets anywhere in the source file, | |
410 | or anywhere in the file tree rooted at | |
411 | .Ev TERMINFO | |
412 | (if it is defined), or in the user's | |
413 | .Pa $HOME/.terminfo | |
414 | directory (if it exists), or (finally) anywhere in the system's | |
415 | file tree of compiled entries. | |
416 | .Pp | |
417 | The error messages from this | |
418 | .Nm | |
419 | have the same format as GNU C error messages, | |
420 | and can be parsed by GNU Emacs's compile facility. | |
421 | .Pp | |
8331b1d2 | 422 | The |
ff2cf2db FF |
423 | .Fl C , |
424 | .Fl G , | |
425 | .Fl I , | |
426 | .Fl N , | |
427 | .Fl R , | |
428 | .Fl T , | |
429 | .Fl V , | |
430 | .Fl a , | |
431 | .Fl e , | |
432 | .Fl f , | |
433 | .Fl g , | |
434 | .Fl o , | |
435 | .Fl r , | |
436 | .Fl s , | |
437 | .Fl t | |
438 | and | |
439 | .Fl x | |
440 | options are not supported under SVr4. | |
441 | The SVr4 | |
442 | .Fl c | |
443 | mode does not report bad use links. | |
444 | .Pp | |
8331b1d2 | 445 | System V does not compile entries to or read entries from your |
ff2cf2db FF |
446 | .Pa $HOME/.terminfo |
447 | directory unless | |
448 | .Ev TERMINFO | |
449 | is explicitly set to it. | |
450 | .Sh FILES | |
451 | .Bl -tag -width "Pa /usr/share/terminfo/?/*" | |
452 | .It Pa /usr/share/terminfo/?/* | |
8331b1d2 | 453 | Compiled terminal description database. |
ff2cf2db FF |
454 | .El |
455 | .Sh SEE ALSO | |
456 | .Xr ncurses 3 , | |
457 | .Xr terminfo 5 | |
458 | .Sh AUTHORS | |
459 | .An Eric S. Raymond Aq Mt esr@snark.thyrsus.com | |
460 | .An Thomas E. Dickey Aq Mt dickey@invisible-island.net |