usr.bin/tic/tic.1

   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
  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 .
  56 There are two ways to change this behavior.
  57 .Pp
  58 First, you may override the system default by setting the variable
  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 .
  80 .Bl -tag -width ".Fl R subset"
  81 .It Fl 0
  82 restricts the output to a single line
  83 .It Fl 1
  84 restricts the output to a single column
  85 .It Fl a
  86 tells
  87 .Nm
  88 to retain commented-out capabilities rather than discarding them.
  89 Capabilities are commented by prefixing them with a period.
  90 This sets the
  91 .Fl x
  92 option, because it treats the commented-out entries as user-defined names.
  93 If the source is termcap, accept the 2-character names required by version 6.
  94 Otherwise these are ignored.
  95 .It Fl C
  96 Force source translation to termcap format.
  97 Capabilities that are not translatable are left in the entry under
  98 their terminfo names but commented out with two preceding dots.
  99 The actual format used incorporates some improvements for escaped characters
 100 from terminfo format.
 101 For a stricter BSD-compatible translation, add the
 102 .Fl K
 103 option.
 104 .Pp
 105 If this is combined with
 106 .Fl c ,
 107 .Nm
 108 makes additional checks to report cases
 109 where the terminfo values do not have an exact equivalent in termcap form.
 110 For example:
 111 .Bl -bullet
 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
 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),
 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
 137 valid expressions.
 138 It does this check only for the predefined string
 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
 147 terminal descriptions.
 148 If
 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.
 153 .It Fl e Ar names
 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
 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
 169 Display complex terminfo strings which contain if/then/else/endif expressions
 170 indented for readability.
 171 .It Fl G
 172 Display constant literals in decimal form
 173 rather than their character equivalents.
 174 .It Fl g
 175 Display constant character literals in quoted form
 176 rather than their decimal equivalents.
 177 .It Fl I
 178 Force source translation to terminfo format.
 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.
 186 .It Fl L
 187 Force source translation to terminfo format
 188 using the long C variable names listed in
 189 .In term.h
 190 .It Fl N
 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
 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 .
 208 This option forces a more literal translation that also preserves the
 209 obsolete capabilities.
 210 .It Fl o Ar dir
 211 Write compiled entries to given directory.
 212 Overrides the
 213 .Ev TERMINFO
 214 environment variable.
 215 .It Fl R Ar subset
 216 Restrict output to a given subset.
 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
 221 that have their own extensions incompatible with SVr4/XSI.
 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
 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
 238 .Bx 4.3 )
 239 that does not handle multiple tc capabilities per entry.
 240 .It Fl s
 241 Summarize the compile by showing the directory into which entries
 242 are written, and the number of entries which are compiled.
 243 .It Fl T
 244 eliminates size-restrictions on the generated text.
 245 This is mainly useful for testing and analysis, since the compiled
 246 descriptions are limited (e.g.\& 1023 for termcap, 4096 for terminfo).
 247 .It Fl t
 248 tells
 249 .Nm
 250 to discard commented-out capabilities.
 251 Normally when translating from terminfo to termcap,
 252 untranslatable capabilities are commented-out.
 253 .It Fl U
 254 tells
 255 .Nm
 256 to not post-process the data after parsing the source file.
 257 Normally, it infers data which is commonly missing in older terminfo data,
 258 or in termcaps.
 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
 264 specifies that (verbose) output be written to standard error trace
 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,
 271 indicating the desired level of detail of information.
 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
 278 detail is increased.
 279 .Pp
 280 The debug flag levels are as follows:
 281 .Bl -tag -width "1xxx" -compact
 282 .It 1
 283 Names of files created and linked
 284 .It 2
 285 Information related to the
 286 .Dq use
 287 facility
 288 .It 3
 289 Statistics from the hashing algorithm
 290 .It 5
 291 String-table memory allocations
 292 .It 7
 293 Entries into the string-table
 294 .It 8
 295 List of tokens encountered by scanner
 296 .It 9
 297 All values computed in construction of the hash table
 298 .El
 299 .Pp
 300 If the debug level
 301 .Ar n
 302 is not given, it is taken to be one.
 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.
 317 .El
 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
 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.
 346 (Entries created from
 347 .Ar file
 348 will be used first.
 349 If the environment variable
 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
 357 those capabilities that explicitly are defined in the current entry.
 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
 377 Total compiled entries cannot exceed 4096 bytes.
 378 The name field cannot exceed 512 bytes.
 379 Terminal names exceeding the maximum alias length
 380 (32 characters on systems with long filenames, 14 characters otherwise)
 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.
 396 In fact, entries in terminfo and termcap syntax can
 397 be mixed in a single source file.
 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
 404 capabilities.
 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
 422 The
 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
 445 System V does not compile entries to or read entries from your
 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/?/*
 453 Compiled 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