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