-.TH tic 1M ""
+.\"***************************************************************************
+.\" Copyright (c) 1998-2015,2016 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.62 2016/10/01 17:14:50 tom Exp $
+.TH @TIC@ 1M ""
+.ie \n(.g .ds `` \(lq
+.el .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el .ds '' ''
.ds n 5
-.ds d @DATADIR@/terminfo
+.ds d @TERMINFO@
+.de bP
+.IP \(bu 4
+..
.SH NAME
-\fBtic\fR - the \fIterminfo\fR entry-description compiler
+\fB@TIC@\fR \- the \fIterminfo\fR entry-description compiler
.SH SYNOPSIS
-\fBtic\fR [\fB-v\fR[\fIn\fR]] [\fB-w\fR[\fIn\fR]] [\fB-1hcpICNRrsTu\fR] [\fB-e\fR \fInames\fR] \fIfile\fR
+\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 command \fBtic\fR translates a \fBterminfo\fR file from source
-format into compiled format. The compiled format is necessary for use with
+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
-The results are normally placed in the system terminfo
-directory \fB\*d\fR. There are two ways to change this behavior.
+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
-First, you may override the system default by setting the variable
-\fBTERMINFO\fR in your shell environment to a valid (existing) directory name.
+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
-Secondly, if \fBtic\fR cannot get access to \fI\*d\fR or your TERMINFO
-directory, it looks for the directory \fI$HOME/.terminfo\fR; if that directory
-exists, the entry is placed there.
+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 for a TERMINFO
-directory first, look at \fI$HOME/.terminfo\fR if TERMINFO is not set, and
-finally look in \fI\*d\fR.
+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 OPTIONS
+.TP
+\fB\-0\fR
+restricts the output to a single line
.TP
-\fB-h\fR
-Print help message and exit.
+\fB\-1\fR
+restricts the output to a single column
.TP
-\fB-c\fR
-specifies 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
+\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 (and a documented limit in terminfo), these entries may cause core
-dumps.
+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-v\fR\fIn\fR
-specifies that (verbose) output be written to standard error trace
-information showing \fBtic\fR's progress. The optional integer
-\fIn\fR is a number from 1 to 10, inclusive, indicating the desired
-level of detail of information. 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.
+\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-o\fR\fIdir\fR
-Write compiled entries to given directory. Overrides the TERMINFO environment
-variable.
+\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-w\fR\fIn\fR
-specifies the width of the output.
+\fB\-f\fR
+Display complex terminfo strings which contain if/then/else/endif expressions
+indented for readability.
.TP
-\fB-1\fR
-restricts the output to a single column
+\fB\-G\fR
+Display constant literals in decimal form
+rather than their character equivalents.
.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).
+\fB\-g\fR
+Display constant character literals in quoted form
+rather than their decimal equivalents.
.TP
-\fB-I\fR
+\fB\-I\fR
Force source translation to terminfo format.
.TP
-\fB-L\fR
+\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-C\fR
-Force source translation to termcap format. Note: this differs from the -C
-option of \fIinfocmp\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.
-.TP
-\fB-N\fR
-Disable smart defaults.
-Normally, when translating from termcap to terminfo, the compiler makes
+\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,
+\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
+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-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 don't support
-the full set of SVR4/XSI Curses terminfo; and outright broken ports like AIX
-that have their own extensions incompatible with SVr4/XSI. Available subsets
+\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
-\fI-r\fR
+\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 up
-to version 1.3 or BSD termcap up to 4.3BSD) that doesn't handle multiple
+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
-\fI-s\fR
-Summarize the compile by showing the directory into which entries
+\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
-\fI-e\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 -I or -C.)
+\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
-\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.
+\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.
+The optional parameter \fIn\fR is a number from 1 to 10, inclusive,
+indicating the desired level of detail of information.
+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
Names of files created and linked
.TP
2
-Information related to the ``use'' facility
+Information related to the \*(``use\*('' facility
.TP
3
Statistics from the hashing algorithm
9
All values computed in construction of the hash table
.LP
-If n is not given, it is taken to be one.
+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.
+.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.
+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
-All but one of the capabilities recognized by \fBtic\fR are documented
-in \fBterminfo\fR(\*n). The exception is the \fBuse\fR capability.
-
-When a \fBuse\fR=\fIentry\fR-\fIname\fR field is discovered in a
-terminal entry currently being compiled, \fBtic\fR reads in the binary
-from \fB\*d\fR to complete the entry. (Entries created from
-\fIfile\fR will be used first. If the environment variable
-\fBTERMINFO\fR is set, that directory is searched instead of
-\fB\*d\fR.) \fBtic\fR duplicates the capabilities in
-\fIentry\fR-\fIname\fR for the current entry, with the exception of
+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.
-
-If the environment variable \fBTERMINFO\fR is set, the compiled
-results are placed there instead of \fB\*d\fR.
-
-Total compiled entries cannot exceed 4096 bytes. The name field cannot
-exceed 128 bytes. Terminal names exceeding 14 characters will be
-truncated to 14 characters and a warning message will be printed.
+.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 COMPATIBILITY
-There is some evidence that historic \fBtic\fR implementations treated
+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 \fBtic\fR does not do that, but it does warn when
+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.
.SH EXTENSIONS
-Unlike the stock SVr4 \fBtic\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
+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 \fBtic\fR will find \fBuse\fR targets anywhere
+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 directory
-(if it exists), or (finally) anywhere in the system's file tree of
+\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.
-
-The error messages from this \fBtic\fR have the same format as GNU C
+.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.
-
-The -o, -I, -C, -N, -R, -h, -e, -T, -r and -s options
+.PP
+The
+\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 and
+\fB\-x\fR
+options
are not supported under SVr4.
-The SVr4 -c mode does not report bad use links.
-
+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 directory unless TERMINFO is explicitly set to it.
+\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
-\fBinfocmp\fR(1m), \fBcaptoinfo\fR(1m), \fBinfotocap\fR(1m), \fBtoe\fR(1m),
-\fBcurses\fR(3X), \fBterminfo\fR(\*n).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fB@INFOCMP@\fR(1M),
+\fB@CAPTOINFO@\fR(1M),
+\fB@INFOTOCAP@\fR(1M),
+\fB@TOE@\fR(1M),
+\fBcurses\fR(3X),
+\fBterm\fR(\*n).
+\fBterminfo\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>
projects / ncurses.git / blobdiff