| .\"*************************************************************************** |
| .\" Copyright 2018-2020,2021 Thomas E. Dickey * |
| .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * |
| .\" * |
| .\" Permission is hereby granted, free of charge, to any person obtaining a * |
| .\" copy of this software and associated documentation files (the * |
| .\" "Software"), to deal in the Software without restriction, including * |
| .\" without limitation the rights to use, copy, modify, merge, publish, * |
| .\" distribute, distribute with modifications, sublicense, and/or sell * |
| .\" copies of the Software, and to permit persons to whom the Software is * |
| .\" furnished to do so, subject to the following conditions: * |
| .\" * |
| .\" The above copyright notice and this permission notice shall be included * |
| .\" in all copies or substantial portions of the Software. * |
| .\" * |
| .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| .\" * |
| .\" Except as contained in this notice, the name(s) of the above copyright * |
| .\" holders shall not be used in advertising or otherwise to promote the * |
| .\" sale, use or other dealings in this Software without prior written * |
| .\" authorization. * |
| .\"*************************************************************************** |
| .\" |
| .\" $Id: tic.1m,v 1.80 2021/08/15 20:01:19 tom Exp $ |
| .TH @TIC@ 1M "" |
| .ie \n(.g .ds `` \(lq |
| .el .ds `` `` |
| .ie \n(.g .ds '' \(rq |
| .el .ds '' '' |
| .ds n 5 |
| .ds d @TERMINFO@ |
| .de bP |
| .ie n .IP \(bu 4 |
| .el .IP \(bu 2 |
| .. |
| .SH NAME |
| \fB@TIC@\fR \- the \fIterminfo\fR entry-description compiler |
| .SH SYNOPSIS |
| \fB@TIC@\fR |
| [\fB\-\ |
| 0\ |
| 1\ |
| C\ |
| D\ |
| G\ |
| I\ |
| K\ |
| L\ |
| N\ |
| T\ |
| U\ |
| V\ |
| W\ |
| a\ |
| c\ |
| f\ |
| g\ |
| q\ |
| r\ |
| s\ |
| t\ |
| x\ |
| \fR] |
| [\fB\-e\fR \fInames\fR] |
| [\fB\-o\fR \fIdir\fR] |
| [\fB\-Q\fR[\fIn\fR]] |
| [\fB\-R\fR \fIsubset\fR] |
| [\fB\-v\fR[\fIn\fR]] |
| [\fB\-w\fR[\fIn\fR]] |
| \fIfile\fR |
| .br |
| .SH DESCRIPTION |
| The \fB@TIC@\fR command translates a \fBterminfo\fR file from source |
| format into compiled format. |
| The compiled format is necessary for use with |
| the library routines in \fBncurses\fR(3X). |
| .PP |
| As described in \fBterm\fR(\*n), the database may be either a directory |
| tree (one file per terminal entry) or a hashed database (one record per entry). |
| The \fB@TIC@\fR command writes only one type of entry, |
| depending on how it was built: |
| .bP |
| For directory trees, the top-level directory, e.g., /usr/share/terminfo, |
| specifies the location of the database. |
| .bP |
| For hashed databases, a filename is needed. |
| If the given file is not found by that name, |
| but can be found by adding the suffix ".db", |
| then that is used. |
| .IP |
| The default name for the hashed database is the same as the |
| default directory name (only adding a ".db" suffix). |
| .PP |
| In either case (directory or hashed database), |
| \fB@TIC@\fP will create the container if it does not exist. |
| For a directory, this would be the \*(``terminfo\*('' leaf, |
| versus a "terminfo.db" file. |
| .PP |
| The results are normally placed in the system terminfo database \fB\*d\fR. |
| The compiled terminal description can be placed |
| in a different terminfo database. |
| There are two ways to achieve this: |
| .bP |
| First, you may override the system default either by |
| using the \fB\-o\fP option, |
| or by setting the variable \fBTERMINFO\fR |
| in your shell environment to a valid database location. |
| .bP |
| Secondly, if \fB@TIC@\fR cannot write in \fI\*d\fR |
| or the location specified using your TERMINFO variable, |
| it looks for the directory \fI$HOME/.terminfo\fR |
| (or hashed database \fI$HOME/.terminfo.db)\fR; |
| if that location exists, the entry is placed there. |
| .PP |
| Libraries that read terminfo entries are expected to check in succession |
| .bP |
| a location specified with the TERMINFO environment variable, |
| .bP |
| \fI$HOME/.terminfo\fR, |
| .bP |
| directories listed in the TERMINFO_DIRS environment variable, |
| .bP |
| a compiled-in list of directories (@TERMINFO_DIRS@), and |
| .bP |
| the system terminfo database (\fI\*d\fR). |
| .SS ALIASES |
| .PP |
| This is the same program as @INFOTOCAP@ and @CAPTOINFO@; |
| usually those are linked to, or copied from this program: |
| .bP |
| When invoked as @INFOTOCAP@, @TIC@ sets the \fB\-I\fP option. |
| .bP |
| When invoked as @CAPTOINFO@, @TIC@ sets the \fB\-C\fP option. |
| .SS OPTIONS |
| .TP |
| \fB\-0\fR |
| restricts the output to a single line |
| .TP |
| \fB\-1\fR |
| restricts the output to a single column |
| .TP |
| \fB\-a\fR |
| tells \fB@TIC@\fP to retain commented-out capabilities rather than discarding |
| them. |
| Capabilities are commented by prefixing them with a period. |
| This sets the \fB\-x\fR option, because it treats the commented-out |
| entries as user-defined names. |
| If the source is termcap, accept the 2-character names required by version 6. |
| Otherwise these are ignored. |
| .TP |
| \fB\-C\fR |
| Force source translation to termcap format. |
| Note: this differs from the \fB\-C\fR |
| option of \fB@INFOCMP@\fR(1M) in that it does not merely translate capability |
| names, but also translates terminfo strings to termcap format. |
| Capabilities |
| that are not translatable are left in the entry under their terminfo names |
| but commented out with two preceding dots. |
| The actual format used incorporates some improvements for escaped characters |
| from terminfo format. |
| For a stricter BSD-compatible translation, add the \fB\-K\fR option. |
| .IP |
| If this is combined with \fB\-c\fR, \fB@TIC@\fR makes additional checks |
| to report cases where the terminfo values do not have an exact equivalent |
| in termcap form. |
| For example: |
| .RS |
| .bP |
| \fBsgr\fP usually will not convert, because termcap lacks the ability to |
| work with more than two parameters, and because termcap lacks many of |
| the arithmetic/logical operators used in terminfo. |
| .bP |
| capabilities with more than one delay or with delays before the end of |
| the string will not convert completely. |
| .RE |
| .TP |
| \fB\-c\fR |
| tells \fB@TIC@\fP to only check \fIfile\fR for errors, |
| including syntax problems and bad use-links. |
| If you specify \fB\-C\fR (\fB\-I\fR) with this option, the code |
| will print warnings about entries which, after use resolution, are more than |
| 1023 (4096) bytes long. |
| Due to a fixed buffer length in older termcap libraries, |
| as well as buggy checking for the buffer length |
| (and a documented limit in terminfo), |
| these entries may cause core |
| dumps with other implementations. |
| .IP |
| \fB@TIC@\fP checks string capabilities to ensure that those with parameters |
| will be valid expressions. |
| It does this check only for the predefined string capabilities; |
| those which are defined with the \fB\-x\fP option are ignored. |
| .TP |
| \fB\-D\fR |
| tells \fB@TIC@\fP to print the database locations that it knows about, and exit. |
| The first location shown is the one to which it would write compiled |
| terminal descriptions. |
| If \fB@TIC@\fP is not able to find a writable database location |
| according to the rules summarized above, |
| it will print a diagnostic and exit with an error rather than |
| printing a list of database locations. |
| .TP |
| \fB\-e \fR\fInames\fR |
| Limit writes and translations to the following comma-separated list of |
| terminals. |
| If any name or alias of a terminal matches one of the names in |
| the list, the entry will be written or translated as normal. |
| Otherwise no output will be generated for it. |
| The option value is interpreted as a file containing the list if it |
| contains a '/'. |
| (Note: depending on how @TIC@ was compiled, |
| this option may require \fB\-I\fR or \fB\-C\fR.) |
| .TP |
| \fB\-f\fR |
| Display complex terminfo strings which contain if/then/else/endif expressions |
| indented for readability. |
| .TP |
| \fB\-G\fR |
| Display constant literals in decimal form |
| rather than their character equivalents. |
| .TP |
| \fB\-g\fR |
| Display constant character literals in quoted form |
| rather than their decimal equivalents. |
| .TP |
| \fB\-I\fR |
| Force source translation to terminfo format. |
| .TP |
| \fB\-K\fR |
| Suppress some longstanding ncurses extensions to termcap format, |
| e.g., "\\s" for space. |
| .TP |
| \fB\-L\fR |
| Force source translation to terminfo format |
| using the long C variable names listed in <\fBterm.h\fR> |
| .TP |
| \fB\-N\fR |
| Disable smart defaults. |
| Normally, when translating from termcap to terminfo, the compiler makes |
| a number of assumptions about the defaults of string capabilities |
| \fBreset1_string\fR, \fBcarriage_return\fR, \fBcursor_left\fR, |
| \fBcursor_down\fR, \fBscroll_forward\fR, \fBtab\fR, \fBnewline\fR, |
| \fBkey_backspace\fR, \fBkey_left\fR, and \fBkey_down\fR, then attempts |
| to use obsolete termcap capabilities to deduce correct values. |
| It also |
| normally suppresses output of obsolete termcap capabilities such as \fBbs\fR. |
| This option forces a more literal translation that also preserves the |
| obsolete capabilities. |
| .TP |
| \fB\-o\fR\fIdir\fR |
| Write compiled entries to given database location. |
| Overrides the TERMINFO environment variable. |
| .TP |
| \fB\-Q\fR\fIn\fR |
| Rather than show source in terminfo (text) format, |
| print the compiled (binary) format in hexadecimal or base64 form, |
| depending on the option's value: |
| .RS 8 |
| .TP 3 |
| 1 |
| hexadecimal |
| .TP 3 |
| 2 |
| base64 |
| .TP 3 |
| 3 |
| hexadecimal and base64 |
| .RE |
| .TP |
| \fB\-q\fR |
| Suppress comments and blank lines when showing translated source. |
| .TP |
| \fB\-R\fR\fIsubset\fR |
| Restrict output to a given subset. |
| This option is for use with archaic |
| versions of terminfo like those on SVr1, Ultrix, or HP-UX that do not support |
| the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX 3.x |
| that have their own extensions incompatible with SVr4/XSI. |
| Available subsets |
| are \*(``SVr1\*('', \*(``Ultrix\*('', \*(``HP\*('', \*(``BSD\*('' and \*(``AIX\*(''; |
| see \fBterminfo\fR(\*n) for details. |
| .TP |
| \fB\-r\fR |
| Force entry resolution (so there are no remaining tc capabilities) even |
| when doing translation to termcap format. |
| This may be needed if you are |
| preparing a termcap file for a termcap library (such as GNU termcap through |
| version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple |
| tc capabilities per entry. |
| .TP |
| \fB\-s\fR |
| Summarize the compile by showing the database location into which entries |
| are written, and the number of entries which are compiled. |
| .TP |
| \fB\-T\fR |
| eliminates size-restrictions on the generated text. |
| This is mainly useful for testing and analysis, since the compiled |
| descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). |
| .TP |
| \fB\-t\fR |
| tells \fB@TIC@\fP to discard commented-out capabilities. |
| Normally when translating from terminfo to termcap, |
| untranslatable capabilities are commented-out. |
| .TP 5 |
| \fB\-U\fR |
| tells \fB@TIC@\fP to not post-process the data after parsing the source file. |
| Normally, it infers data which is commonly missing in older terminfo data, |
| or in termcaps. |
| .TP |
| \fB\-V\fR |
| reports the version of ncurses which was used in this program, and exits. |
| .TP |
| \fB\-v\fR\fIn\fR |
| specifies that (verbose) output be written to standard error trace |
| information showing \fB@TIC@\fR's progress. |
| .IP |
| The optional parameter \fIn\fR is a number from 1 to 10, inclusive, |
| indicating the desired level of detail of information. |
| If ncurses is built without tracing support, the optional parameter is ignored. |
| If \fIn\fR is omitted, the default level is 1. |
| If \fIn\fR is specified and greater than 1, the level of |
| detail is increased. |
| .RS |
| .PP |
| The debug flag levels are as follows: |
| .TP |
| 1 |
| Names of files created and linked |
| .TP |
| 2 |
| Information related to the \*(``use\*('' facility |
| .TP |
| 3 |
| Statistics from the hashing algorithm |
| .TP |
| 5 |
| String-table memory allocations |
| .TP |
| 7 |
| Entries into the string-table |
| .TP |
| 8 |
| List of tokens encountered by scanner |
| .TP |
| 9 |
| All values computed in construction of the hash table |
| .LP |
| If the debug level \fIn\fR is not given, it is taken to be one. |
| .RE |
| .TP |
| \fB\-W\fR |
| By itself, the \fB\-w\fP option will not force long strings to be wrapped. |
| Use the \fB\-W\fP option to do this. |
| .IP |
| If you specify both \fB\-f\fP and \fB\-W\fP options, |
| the latter is ignored when \fB\-f\fP has already split the line. |
| .TP |
| \fB\-w\fR\fIn\fR |
| specifies the width of the output. |
| The parameter is optional. |
| If it is omitted, it defaults to 60. |
| .TP |
| \fB\-x\fR |
| Treat unknown capabilities as user-defined (see \fBuser_caps(\*n)\fP). |
| That is, if you supply a capability name which \fB@TIC@\fP does not recognize, |
| it will infer its type (boolean, number or string) from the syntax and |
| make an extended table entry for that. |
| User-defined capability strings |
| whose name begins with \*(``k\*('' are treated as function keys. |
| .SS PARAMETERS |
| .TP |
| \fIfile\fR |
| contains one or more \fBterminfo\fR terminal descriptions in source |
| format [see \fBterminfo\fR(\*n)]. |
| Each description in the file |
| describes the capabilities of a particular terminal. |
| .IP |
| If \fIfile\fR is \*(``-\*('', then the data is read from the standard input. |
| The \fIfile\fR parameter may also be the path of a character-device. |
| .SS PROCESSING |
| .PP |
| All but one of the capabilities recognized by \fB@TIC@\fR are documented |
| in \fBterminfo\fR(\*n). |
| The exception is the \fBuse\fR capability. |
| .PP |
| When a \fBuse\fR=\fIentry\fR\-\fIname\fR field is discovered in a |
| terminal entry currently being compiled, \fB@TIC@\fR reads in the binary |
| from \fB\*d\fR to complete the entry. |
| (Entries created from |
| \fIfile\fR will be used first. |
| \fB@TIC@\fR duplicates the capabilities in |
| \fIentry\fR\-\fIname\fR for the current entry, with the exception of |
| those capabilities that explicitly are defined in the current entry. |
| .PP |
| When an entry, e.g., \fBentry_name_1\fR, contains a |
| \fBuse=\fR\fIentry\fR_\fIname\fR_\fI2\fR field, any canceled |
| capabilities in \fIentry\fR_\fIname\fR_\fI2\fR must also appear in |
| \fBentry_name_1\fR before \fBuse=\fR for these capabilities to be |
| canceled in \fBentry_name_1\fR. |
| .PP |
| Total compiled entries cannot exceed 4096 bytes. |
| The name field cannot |
| exceed 512 bytes. |
| Terminal names exceeding the maximum alias length |
| (32 characters on systems with long filenames, 14 characters otherwise) |
| will be truncated to the maximum alias length |
| and a warning message will be printed. |
| .SH HISTORY |
| .PP |
| System V Release 2 provided a \fBtic\fP utility. |
| It accepted a single option: \fB\-v\fP (optionally followed by a number). |
| According to Ross Ridge's comment in \fImytinfo\fP, |
| this version of \fBtic\fP was |
| unable to represent cancelled capabilities. |
| .PP |
| System V Release 3 provided a different \fBtic\fP utility, |
| written by Pavel Curtis, |
| (originally named \*(``compile\*('' in \fIpcurses\fP). |
| This added an option \fB\-c\fP to check the file for |
| errors, with the caveat that errors in \*(``use=\*('' links |
| would not be reported. |
| System V Release 3 documented a few warning messages which |
| did not appear in \fIpcurses\fP. |
| While the program itself was changed little as development |
| continued with System V Release 4, |
| the table of capabilities grew from 180 (\fIpcurses\fP) to 464 (Solaris). |
| .PP |
| In early development of ncurses (1993), |
| Zeyd Ben-Halim used the table from \fImytinfo\fP to |
| extend the \fIpcurses\fP table to 469 capabilities |
| (456 matched SVr4, 8 were only in SVr4, 13 were not in SVr4). |
| Of those 13, 11 were ultimately discarded |
| (perhaps to match the draft of X/Open Curses). |
| The exceptions were |
| \fBmemory_lock_above\fP and |
| \fBmemory_unlock\fP (see \fBuser_caps\fP(5)). |
| .PP |
| Eric Raymond incorporated parts of \fImytinfo\fP into ncurses |
| to implement the termcap-to-terminfo source conversion, |
| and extended that to begin development of |
| the corresponding terminfo-to-termcap source conversion, |
| Thomas Dickey completed that development over the course of several years. |
| .PP |
| In 1999, Thomas Dickey added the \fB\-x\fP option |
| to support user-defined capabilities. |
| .PP |
| In 2010, Roy Marples provided a \fBtic\fP program |
| and terminfo library for NetBSD. |
| That implementation adapts several features from ncurses, |
| including \fB@TIC@\fP's \fB\-x\fP option. |
| .PP |
| The \fB\-c\fP option tells \fB@TIC@\fP to check for problems in the |
| terminfo source file. |
| Continued development provides additional checks: |
| .bP |
| \fIpcurses\fP had 8 warnings |
| .bP |
| ncurses in 1996 had 16 warnings |
| .bP |
| Solaris (SVr4) curses has 28 warnings |
| .bP |
| NetBSD tic in 2019 has 19 warnings. |
| .bP |
| ncurses in 2019 has 96 warnings |
| .PP |
| The checking done in ncurses' \fB@TIC@\fP helps with the conversion to |
| termcap, as well as pointing out errors and inconsistencies. |
| It is also used to ensure consistency with the user-defined capabilities. |
| There are 527 distinct capabilities in ncurses' terminal database; |
| 128 of those are user-defined. |
| .SH PORTABILITY |
| .PP |
| X/Open Curses, Issue 7 (2009) provides a brief description of \fBtic\fP. |
| It lists one option: \fB\-c\fP. |
| The omission of \fB\-v\fP is unexpected. |
| The change history states that the description is derived from True64 UNIX. |
| According to its manual pages, that system also supported the \fB\-v\fP option. |
| .PP |
| Shortly after Issue 7 was released, Tru64 was discontinued. |
| As of 2019, the surviving implementations of \fBtic\fP |
| are SVr4 (AIX, HP-UX and Solaris), |
| ncurses |
| and NetBSD curses. |
| The SVr4 \fBtic\fP programs all support the \fB\-v\fP option. |
| The NetBSD \fBtic\fP program follows X/Open's documentation, |
| omitting the \fB\-v\fP option. |
| .PP |
| The X/Open rationale states that some implementations of \fBtic\fP |
| read terminal descriptions from the standard input if the \fIfile\fP |
| parameter is omitted. |
| None of these implementations do that. |
| Further, it comments that some may choose to read from \*(''./terminfo.src\*('' |
| but that is obsolescent behavior from SVr2, |
| and is not (for example) a documented feature of SVr3. |
| .SS COMPATIBILITY |
| There is some evidence that historic \fB@TIC@\fR implementations treated |
| description fields with no whitespace in them as additional aliases or |
| short names. |
| This \fB@TIC@\fR does not do that, but it does warn when |
| description fields may be treated that way and check them for dangerous |
| characters. |
| .SS EXTENSIONS |
| Unlike the SVr4 \fB@TIC@\fR command, this implementation can actually |
| compile termcap sources. |
| In fact, entries in terminfo and termcap syntax can |
| be mixed in a single source file. |
| See \fBterminfo\fR(\*n) for the list of |
| termcap names taken to be equivalent to terminfo names. |
| .PP |
| The SVr4 manual pages are not clear on the resolution rules for \fBuse\fR |
| capabilities. |
| This implementation of \fB@TIC@\fR will find \fBuse\fR targets anywhere |
| in the source file, or anywhere in the file tree rooted at \fBTERMINFO\fR (if |
| \fBTERMINFO\fR is defined), |
| or in the user's \fI$HOME/.terminfo\fR database |
| (if it exists), |
| or (finally) anywhere in the system's file tree of |
| compiled entries. |
| .PP |
| The error messages from this \fB@TIC@\fR have the same format as GNU C |
| error messages, and can be parsed by GNU Emacs's compile facility. |
| .PP |
| Aside from \fB\-c\fP and \fB\-v\fP, options are not portable: |
| .bP |
| Most of @TIC@'s options |
| are not supported by SVr4 \fBtic\fP: |
| .sp |
| .RS |
| \fB\-0\fR |
| \fB\-1\fR |
| \fB\-C\fR |
| \fB\-G\fR |
| \fB\-I\fR |
| \fB\-N\fR |
| \fB\-R\fR |
| \fB\-T\fR |
| \fB\-V\fR |
| \fB\-a\fR |
| \fB\-e\fR |
| \fB\-f\fR |
| \fB\-g\fR |
| \fB\-o\fR |
| \fB\-r\fR |
| \fB\-s\fR |
| \fB\-t\fR |
| \fB\-x\fR |
| .RE |
| .bP |
| The NetBSD \fBtic\fP supports a few of the ncurses options |
| .sp |
| .RS |
| \fB\-a\fP |
| \fB\-o\fP |
| \fB\-x\fP |
| .RE |
| .IP |
| and adds \fB\-S\fP |
| (a feature which does the same thing |
| as @INFOCMP@'s \fB\-e\fP and \fB\-E\fP options). |
| .PP |
| The SVr4 \fB\-c\fR mode does not report bad \*(``use=\*('' links. |
| .PP |
| System V does not compile entries to or read entries from your |
| \fI$HOME/.terminfo\fR database unless TERMINFO is explicitly set to it. |
| .SH FILES |
| .TP 5 |
| \fB\*d/?/*\fR |
| Compiled terminal description database. |
| .SH SEE ALSO |
| \fB@CAPTOINFO@\fR(1M), |
| \fB@INFOCMP@\fR(1M), |
| \fB@INFOTOCAP@\fR(1M), |
| \fB@TOE@\fR(1M), |
| \fBcurses\fR(3X), |
| \fBterm\fR(\*n). |
| \fBterminfo\fR(\*n). |
| \fBuser_caps\fR(\*n). |
| .PP |
| This describes \fBncurses\fR |
| version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@). |
| .SH AUTHOR |
| Eric S. Raymond <esr@snark.thyrsus.com> |
| and |
| .br |
| Thomas E. Dickey <dickey@invisible-island.net> |