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