man/tic.1m

   1 .\"***************************************************************************
   2 .\" Copyright (c) 1998-2010,2011 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.53 2011/12/17 23:13:19 tom Exp $
  30 .TH @TIC@ 1M ""
  31 .ds n 5
  32 .ds d @TERMINFO@
  33 .de bP
  34 .IP \(bu 4
  35 ..
  36 .SH NAME
  37 \fB@TIC@\fR \- the \fIterminfo\fR entry-description compiler
  38 .SH SYNOPSIS
  39 \fB@TIC@\fR
  40 [\fB\-\
  41 0\
  42 1\
  43 C\
  44 D\
  45 G\
  46 I\
  47 K\
  48 L\
  49 N\
  50 T\
  51 U\
  52 V\
  53 a\
  54 c\
  55 f\
  56 g\
  57 r\
  58 s\
  59 t\
  60 x\
  61 \fR]
  62 [\fB\-e\fR \fInames\fR]
  63 [\fB\-o\fR \fIdir\fR]
  64 [\fB\-R\fR \fIsubset\fR]
  65 [\fB\-v\fR[\fIn\fR]]
  66 [\fB\-w\fR[\fIn\fR]]
  67 \fIfile\fR
  68 .br
  69 .SH DESCRIPTION
  70 The \fB@TIC@\fR command translates a \fBterminfo\fR file from source
  71 format into compiled format.
  72 The compiled format is necessary for use with
  73 the library routines in \fBncurses\fR(3X).
  74 .PP
  75 As described in \fBterm\fR(\*n), the database may be either a directory
  76 tree (one file per terminal entry) or a hashed database (one record per entry).
  77 The \fB@TIC@\fR writes only one type of entry, depending on how it was built:
  78 .bP
  79 For directory trees, the top-level directory, e.g., /usr/share/terminfo,
  80 specifies the location of the database.
  81 .bP
  82 For hashed databases, a filename is needed.
  83 If the given file is not found by that name,
  84 but can be found by adding the suffix ".db",
  85 then that is used.
  86 .IP
  87 The default name for the hashed database is the same as the
  88 default directory name (only adding a ".db" suffix).
  89 .PP
  90 The results are normally placed in the system terminfo database \fB\*d\fR.
  91 The compiled terminal description can be placed in a different terminfo database.
  92 There are two ways to achieve this:
  93 .bP
  94 First, you may override the system default by setting the variable
  95 \fBTERMINFO\fR in your shell environment to a valid database
  96 location, e.g., an existing directory (for directory trees) or
  97 valid location for a hashed database.
  98 .bP
  99 Secondly, if \fB@TIC@\fR cannot write in \fI\*d\fR
 100 or the location specified using your TERMINFO variable,
 101 it looks for the directory \fI$HOME/.terminfo\fR
 102 (or hashed database \fI$HOME/.terminfo.db)\fR;
 103 if that location exists, the entry is placed there.
 104 .PP
 105 Libraries that read terminfo entries are expected to check for
 106 a location specified with the TERMINFO variable first,
 107 look at \fI$HOME/.terminfo\fR if TERMINFO is not set, and
 108 finally look in \fI\*d\fR.
 109 .TP
 110 \fB\-0\fR
 111 restricts the output to a single line
 112 .TP
 113 \fB\-1\fR
 114 restricts the output to a single column
 115 .TP
 116 \fB\-a\fR
 117 tells \fB@TIC@\fP to retain commented-out capabilities rather than discarding
 118 them.
 119 Capabilities are commented by prefixing them with a period.
 120 This sets the \fB\-x\fR option, because it treats the commented-out
 121 entries as user-defined names.
 122 If the source is termcap, accept the 2-character names required by version 6.
 123 Otherwise these are ignored.
 124 .TP
 125 \fB\-C\fR
 126 Force source translation to termcap format.
 127 Note: this differs from the \fB\-C\fR
 128 option of \fB@INFOCMP@\fR(1M) in that it does not merely translate capability
 129 names, but also translates terminfo strings to termcap format.
 130 Capabilities
 131 that are not translatable are left in the entry under their terminfo names
 132 but commented out with two preceding dots.
 133 The actual format used incorporates some improvements for escaped characters
 134 from terminfo format.
 135 For a stricter BSD-compatible translation, add the \fB\-K\fR option.
 136 .TP
 137 \fB\-c\fR
 138 tells \fB@TIC@\fP to only check \fIfile\fR for errors, including syntax problems and
 139 bad use links.
 140 If you specify \fB\-C\fR (\fB\-I\fR) with this option, the code
 141 will print warnings about entries which, after use resolution, are more than
 142 1023 (4096) bytes long.
 143 Due to a fixed buffer length in older termcap libraries,
 144 as well as buggy checking for the buffer length
 145 (and a documented limit in terminfo),
 146 these entries may cause core
 147 dumps with other implementations.
 148 .TP
 149 \fB\-D\fR
 150 tells \fB@TIC@\fP to print the database locations that it knows about, and exit.
 151 The first location shown is the one to which it would write compiled
 152 terminal descriptions.
 153 If \fB@TIC@\fP is not able to find a writable database location
 154 according to the rules summarized above,
 155 it will print a diagnostic and exit with an error rather than
 156 printing a list of database locations.
 157 .TP
 158 \fB\-e \fR\fInames\fR
 159 Limit writes and translations to the following comma-separated list of
 160 terminals.
 161 If any name or alias of a terminal matches one of the names in
 162 the list, the entry will be written or translated as normal.
 163 Otherwise no output will be generated for it.
 164 The option value is interpreted as a file containing the list if it
 165 contains a '/'.
 166 (Note: depending on how tic was compiled, this option may require \fB\-I\fR or \fB\-C\fR.)
 167 .TP
 168 \fB\-f\fR
 169 Display complex terminfo strings which contain if/then/else/endif expressions
 170 indented for readability.
 171 .TP
 172 \fB\-G\fR
 173 Display constant literals in decimal form
 174 rather than their character equivalents.
 175 .TP
 176 \fB\-g\fR
 177 Display constant character literals in quoted form
 178 rather than their decimal equivalents.
 179 .TP
 180 \fB\-I\fR
 181 Force source translation to terminfo format.
 182 .TP
 183 \fB\-K\fR
 184 Suppress some longstanding ncurses extensions to termcap format,
 185 e.g., "\\s" for space.
 186 .TP
 187 \fB\-L\fR
 188 Force source translation to terminfo format
 189 using the long C variable names listed in <\fBterm.h\fR>
 190 .TP
 191 \fB\-N\fR
 192 Disable smart defaults.
 193 Normally, when translating from termcap to terminfo, the compiler makes
 194 a number of assumptions about the defaults of string capabilities
 195 \fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR,
 196 \fBcursor_down\fR, \fBscroll_forward\fR, \fBtab\fR, \fBnewline\fR,
 197 \fBkey_backspace\fR, \fBkey_left\fR, and \fBkey_down\fR, then attempts
 198 to use obsolete termcap capabilities to deduce correct values.
 199 It also
 200 normally suppresses output of obsolete termcap capabilities such as \fBbs\fR.
 201 This option forces a more literal translation that also preserves the
 202 obsolete capabilities.
 203 .TP
 204 \fB\-o\fR\fIdir\fR
 205 Write compiled entries to given database location.
 206 Overrides the TERMINFO environment variable.
 207 .TP
 208 \fB\-R\fR\fIsubset\fR
 209 Restrict output to a given subset.
 210 This option is for use with archaic
 211 versions of terminfo like those on SVr1, Ultrix, or HP/UX that do not support
 212 the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x
 213 that have their own extensions incompatible with SVr4/XSI.
 214 Available subsets
 215 are "SVr1", "Ultrix", "HP", "BSD" and "AIX"; see \fBterminfo\fR(\*n) for details.
 216 .TP
 217 \fB\-r\fR
 218 Force entry resolution (so there are no remaining tc capabilities) even
 219 when doing translation to termcap format.
 220 This may be needed if you are
 221 preparing a termcap file for a termcap library (such as GNU termcap through
 222 version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple
 223 tc capabilities per entry.
 224 .TP
 225 \fB\-s\fR
 226 Summarize the compile by showing the database location into which entries
 227 are written, and the number of entries which are compiled.
 228 .TP
 229 \fB\-T\fR
 230 eliminates size-restrictions on the generated text.
 231 This is mainly useful for testing and analysis, since the compiled
 232 descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo).
 233 .TP
 234 \fB\-t\fR
 235 tells \fB@TIC@\fP to discard commented-out capabilities.
 236 Normally when translating from terminfo to termcap,
 237 untranslatable capabilities are commented-out.
 238 .TP 5
 239 \fB\-U\fR
 240 tells \fB@TIC@\fP to not post-process the data after parsing the source file.
 241 Normally, it infers data which is commonly missing in older terminfo data,
 242 or in termcaps.
 243 .TP
 244 \fB\-V\fR
 245 reports the version of ncurses which was used in this program, and exits.
 246 .TP
 247 \fB\-v\fR\fIn\fR
 248 specifies that (verbose) output be written to standard error trace
 249 information showing \fB@TIC@\fR's progress.
 250 The optional parameter \fIn\fR is a number from 1 to 10, inclusive,
 251 indicating the desired level of detail of information.
 252 If \fIn\fR is omitted, the default level is 1.
 253 If \fIn\fR is specified and greater than 1, the level of
 254 detail is increased.
 255 .TP
 256 \fB\-w\fR\fIn\fR
 257 specifies the width of the output.
 258 The parameter is optional.
 259 If it is omitted, it defaults to 60.
 260 .TP
 261 \fB\-x\fR
 262 Treat unknown capabilities as user-defined.
 263 That is, if you supply a capability name which \fB@TIC@\fP does not recognize,
 264 it will infer its type (boolean, number or string) from the syntax and
 265 make an extended table entry for that.
 266 User-defined capability strings
 267 whose name begins with ``k'' are treated as function keys.
 268 .TP
 269 \fIfile\fR
 270 contains one or more \fBterminfo\fR terminal descriptions in source
 271 format [see \fBterminfo\fR(\*n)].
 272 Each description in the file
 273 describes the capabilities of a particular terminal.
 274 .PP
 275 The debug flag levels are as follows:
 276 .TP
 277 1
 278 Names of files created and linked
 279 .TP
 280 2
 281 Information related to the ``use'' facility
 282 .TP
 283 3
 284 Statistics from the hashing algorithm
 285 .TP
 286 5
 287 String-table memory allocations
 288 .TP
 289 7
 290 Entries into the string-table
 291 .TP
 292 8
 293 List of tokens encountered by scanner
 294 .TP
 295 9
 296 All values computed in construction of the hash table
 297 .LP
 298 If the debug level \fIn\fR is not given, it is taken to be one.
 299 .PP
 300 All but one of the capabilities recognized by \fB@TIC@\fR are documented
 301 in \fBterminfo\fR(\*n).
 302 The exception is the \fBuse\fR capability.
 303 .PP
 304 When a \fBuse\fR=\fIentry\fR\-\fIname\fR field is discovered in a
 305 terminal entry currently being compiled, \fB@TIC@\fR reads in the binary
 306 from \fB\*d\fR to complete the entry.
 307 (Entries created from
 308 \fIfile\fR will be used first.
 309 If the environment variable
 310 \fBTERMINFO\fR is set, that database location is searched instead of
 311 \fB\*d\fR.)  \fB@TIC@\fR duplicates the capabilities in
 312 \fIentry\fR\-\fIname\fR for the current entry, with the exception of
 313 those capabilities that explicitly are defined in the current entry.
 314 .PP
 315 When an entry, e.g., \fBentry_name_1\fR, contains a
 316 \fBuse=\fR\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled
 317 capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in
 318 \fBentry_name_1\fR before \fBuse=\fR for these capabilities to be
 319 canceled in \fBentry_name_1\fR.
 320 .PP
 321 If the environment variable \fBTERMINFO\fR is set, the compiled
 322 results are placed there instead of \fB\*d\fR.
 323 .PP
 324 Total compiled entries cannot exceed 4096 bytes.
 325 The name field cannot
 326 exceed 512 bytes.
 327 Terminal names exceeding the maximum alias length
 328 (32 characters on systems with long filenames, 14 characters otherwise)
 329 will be truncated to the maximum alias length and a warning message will be printed.
 330 .SH COMPATIBILITY
 331 There is some evidence that historic \fB@TIC@\fR implementations treated
 332 description fields with no whitespace in them as additional aliases or
 333 short names.
 334 This \fB@TIC@\fR does not do that, but it does warn when
 335 description fields may be treated that way and check them for dangerous
 336 characters.
 337 .SH EXTENSIONS
 338 Unlike the stock SVr4 \fB@TIC@\fR command, this implementation can actually
 339 compile termcap sources.
 340 In fact, entries in terminfo and termcap syntax can
 341 be mixed in a single source file.
 342 See \fBterminfo\fR(\*n) for the list of
 343 termcap names taken to be equivalent to terminfo names.
 344 .PP
 345 The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR
 346 capabilities.
 347 This implementation of \fB@TIC@\fR will find \fBuse\fR targets anywhere
 348 in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if
 349 \fBTERMINFO\fR is defined),
 350 or in the user's \fI$HOME/.terminfo\fR database
 351 (if it exists),
 352 or (finally) anywhere in the system's file tree of
 353 compiled entries.
 354 .PP
 355 The error messages from this \fB@TIC@\fR have the same format as GNU C
 356 error messages, and can be parsed by GNU Emacs's compile facility.
 357 .PP
 358 The
 359 \fB\-0\fR,
 360 \fB\-1\fR,
 361 \fB\-C\fR,
 362 \fB\-G\fR,
 363 \fB\-I\fR,
 364 \fB\-N\fR,
 365 \fB\-R\fR,
 366 \fB\-T\fR,
 367 \fB\-V\fR,
 368 \fB\-a\fR,
 369 \fB\-e\fR,
 370 \fB\-f\fR,
 371 \fB\-g\fR,
 372 \fB\-o\fR,
 373 \fB\-r\fR,
 374 \fB\-s\fR,
 375 \fB\-t\fR and
 376 \fB\-x\fR
 377 options
 378 are not supported under SVr4.
 379 The SVr4 \fB\-c\fR mode does not report bad use links.
 380 .PP
 381 System V does not compile entries to or read entries from your
 382 \fI$HOME/.terminfo\fR database unless TERMINFO is explicitly set to it.
 383 .SH FILES
 384 .TP 5
 385 \fB\*d/?/*\fR
 386 Compiled terminal description database.
 387 .SH SEE ALSO
 388 \fB@INFOCMP@\fR(1M),
 389 \fB@CAPTOINFO@\fR(1M),
 390 \fB@INFOTOCAP@\fR(1M),
 391 \fB@TOE@\fR(1M),
 392 \fBcurses\fR(3X),
 393 \fBterm\fR(\*n).
 394 \fBterminfo\fR(\*n).
 395 .PP
 396 This describes \fBncurses\fR
 397 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
 398 .SH AUTHOR
 399 Eric S. Raymond <esr@snark.thyrsus.com>
 400 and
 401 .br
 402 Thomas E. Dickey <dickey@invisible-island.net>