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