-.\" $Id: terminfo.tail,v 1.68 2013/11/09 15:20:48 tom Exp $
+.\" $Id: terminfo.tail,v 1.75 2016/12/24 22:54:11 tom Exp $
.\" Beginning of terminfo.tail file
.\" This file is part of ncurses.
.\" See "terminfo.head" for copyright.
Finally, characters may be given as three octal digits after a \fB\e\fR.
.PP
A delay in milliseconds may appear anywhere in a string capability, enclosed in
-$<..> brackets, as in \fBel\fP=\eEK$<5>, and padding characters are supplied by
-.I tputs
+$<..> brackets, as in \fBel\fP=\eEK$<5>,
+and padding characters are supplied by \fBtputs\fP
to provide this delay.
+.bP
The delay must be a number with at most one decimal
place of precision; it may be followed by suffixes \*(``*\*('' or \*(``/\*('' or both.
+.bP
A \*(``*\*(''
indicates that the padding required is proportional to the number of lines
affected by the operation, and the amount given is the per-affected-unit
padding required.
(In the case of insert character, the factor is still the
-number of
-.IR lines
-affected.) Normally, padding is advisory if the device has the \fBxon\fR
+number of \fIlines\fP affected.)
+.IP
+Normally, padding is advisory if the device has the \fBxon\fR
capability; it is used for cost computation but does not trigger delays.
+.bP
A \*(``/\*(''
suffix indicates that the padding is mandatory and forces a delay of the given
number of milliseconds even on devices for which \fBxon\fR is present to
as a list of colon-separated directories (or database files) to be searched.
.IP
An empty directory name (i.e., if the variable begins or ends
-with a colon, or contains adacent colons)
+with a colon, or contains adjacent colons)
is interpreted as the system location \fI\*d\fR.
.bP
Finally, \fBncurses\fP searches these compiled-in locations:
avoiding interpreting "%\-" as an operator.
.TP
\f(CW%c\fP
-print pop() like %c in \fBprintf\fP
+print \fIpop()\fP like %c in \fBprintf\fP
.TP
\fB%s\fP
-print pop() like %s in \fBprintf\fP
+print \fIpop()\fP like %s in \fBprintf\fP
.TP
\fB%p\fP\fI[1\-9]\fP
push \fIi\fP'th parameter
.TP
\fB%P\fP\fI[a\-z]\fP
-set dynamic variable \fI[a\-z]\fP to pop()
+set dynamic variable \fI[a\-z]\fP to \fIpop()\fP
.TP
\fB%g\fP\fI[a\-z]/\fP
get dynamic variable \fI[a\-z]\fP and push it
push strlen(pop)
.TP
\fB%+\fP, \fB%\-\fP, \fB%*\fP, \fB%/\fP, \fB%m\fP
-arithmetic (%m is mod): \fIpush(pop() op pop())\fP
+arithmetic (%m is \fImod\fP): \fIpush(pop() op pop())\fP
.TP
\fB%&\fP, \fB%|\fP, \fB%^\fP
bit operations (AND, OR and exclusive-OR): \fIpush(pop() op pop())\fP
logical AND and OR operations (for conditionals)
.TP
\fB%!\fP, \fB%~\fP
-unary operations (logical and bit complement): push(op pop())
+unary operations (logical and bit complement): \fIpush(op pop())\fP
.TP
\fB%i\fP
add 1 to first two parameters (for ANSI terminals)
\fBindn\fR, and \fBrin\fR will simulate destructive scrolling; their
documentation cautions you not to define \fBcsr\fR unless this is true.
This \fBcurses\fR implementation is more liberal and will do explicit erases
-after scrolling if \fBndstr\fR is defined.
+after scrolling if \fBndsrc\fR is defined.
.PP
If the terminal has the ability to define a window as part of
memory, which all commands affect,
the numeric parameter
.B it
is given, showing the number of spaces the tabs are set to.
-This is normally used by the
-.IR @TSET@
+This is normally used by the \fB@TSET@\fP
command to determine whether to set the mode for hardware tab expansion,
and whether to set the tab stops.
If the terminal has tab stops that can be saved in non-volatile memory,
with the rest of the terminfo description.
They are normally sent to the terminal, by the
.I init
-option of the
-.IR @TPUT@
-program, each time the user logs in.
+option of the \fB@TPUT@\fP program, each time the user logs in.
They will be printed in the following order:
.RS
.TP
and
.BR is3
respectively.
-These strings are output by the
-.IR reset
-program, which is used when the terminal gets into a wedged state.
+These strings are output by the \fB@RESET@\fP program,
+which is used when the terminal gets into a wedged state.
Commands are normally placed in
.BR rs1 ,
.BR rs2
but it causes an annoying glitch of the screen and is not normally
needed since the terminal is usually already in 80 column mode.
.PP
-The
-.IR reset
-program writes strings
-including
+The \fB@RESET@\fP program writes strings including
.BR iprog ,
etc., in the same order as the
.IR init
.BR rs3 ,
or
.BR rf
-reset capability strings are missing, the
-.IR reset
+reset capability strings are missing, the \fB@RESET@\fP
program falls back upon the corresponding initialization capability string.
.PP
If there are commands to set and clear tab stops, they can be given as
.PP
.SS Color Handling
.PP
-Most color terminals are either \*(``Tektronix-like\*('' or \*(``HP-like\*(''.
+The curses library functions \fBinit_pair\fP and \fBinit_color\fP
+manipulate the \fIcolor pairs\fP and \fIcolor values\fP discussed in this
+section
+(see \fBcurs_color\fP(3X) for details on these and related functions).
+.PP
+Most color terminals are either \*(``Tektronix-like\*('' or \*(``HP-like\*('':
+.bP
Tektronix-like
-terminals have a predefined set of N colors (where N usually 8), and can set
+terminals have a predefined set of \fIN\fP colors
+(where \fIN\fP is usually 8),
+and can set
character-cell foreground and background characters independently, mixing them
-into N\ *\ N color-pairs.
-On HP-like terminals, the use must set each color
+into \fIN\fP\ *\ \fIN\fP color-pairs.
+.bP
+On HP-like terminals, the user must set each color
pair up separately (foreground and background are not independently settable).
-Up to M color-pairs may be set up from 2*M different colors.
-ANSI-compatible
-terminals are Tektronix-like.
+Up to \fIM\fP color-pairs may be set up from 2*\fIM\fP different colors.
+ANSI-compatible terminals are Tektronix-like.
.PP
Some basic color capabilities are independent of the color method.
The numeric
than the power-up default background; these should have the boolean capability
\fBbce\fR.
.PP
+While the curses library works with \fIcolor pairs\fP
+(reflecting the inability of some devices to set foreground
+and background colors independently),
+there are separate capabilities for setting these features:
+.bP
To change the current foreground or background color on a Tektronix-type
terminal, use \fBsetaf\fR (set ANSI foreground) and \fBsetab\fR (set ANSI
background) or \fBsetf\fR (set foreground) and \fBsetb\fR (set background).
only \fBsetaf\fR/\fBsetab\fR; the XPG4 draft says that "If the terminal
supports ANSI escape sequences to set background and foreground, they should
be coded as \fBsetaf\fR and \fBsetab\fR, respectively.
+.bP
If the terminal
supports other escape sequences to set background and foreground, they should
be coded as \fBsetf\fR and \fBsetb\fR, respectively.
-The \fIvidputs()\fR
-function and the refresh functions use \fBsetaf\fR and \fBsetab\fR if they are
-defined."
+The \fBvidputs\fR and the \fBrefresh\fP functions
+use the \fBsetaf\fR and \fBsetab\fR capabilities if they are defined.
.PP
The \fBsetaf\fR/\fBsetab\fR and \fBsetf\fR/\fBsetb\fR capabilities take a
single numeric argument each.
On an HP-like terminal, use \fBscp\fR with a color-pair number parameter to set
which color pair is current.
.PP
+Some terminals allow the \fIcolor values\fP to be modified:
+.bP
On a Tektronix-like terminal, the capability \fBccc\fR may be present to
indicate that colors can be modified.
If so, the \fBinitc\fR capability will
they are instead as HLS (Hue, Lightness, Saturation) indices.
The ranges are
terminal-dependent.
-.PP
+.bP
On an HP-like terminal, \fBinitp\fR may give a capability for changing a
color-pair value.
It will take seven parameters; a color-pair number (0 to
translations are much more strictly limited (to 1023 bytes), thus termcap translations
of long terminfo entries can cause problems.
.PP
-The man pages for 4.3BSD and older versions of \fBtgetent()\fP instruct the user to
+The man pages for 4.3BSD and older versions of \fBtgetent\fP instruct the user to
allocate a 1024-byte buffer for the termcap entry.
The entry gets null-terminated by
the termcap library, so that makes the maximum safe length for a termcap entry
1k\-1 (1023) bytes.
Depending on what the application and the termcap library
-being used does, and where in the termcap file the terminal type that \fBtgetent()\fP
+being used does, and where in the termcap file the terminal type that \fBtgetent\fP
is searching for is, several bad things can happen.
.PP
Some termcap libraries print a warning message or exit if they find an
affects more than just users of that particular terminal.
This is the
length of the entry as it exists in /etc/termcap, minus the
-backslash-newline pairs, which \fBtgetent()\fP strips out while reading it.
+backslash-newline pairs, which \fBtgetent\fP strips out while reading it.
Some termcap libraries strip off the final newline, too (GNU termcap does not).
Now suppose:
.bP
the whole entry into the buffer, no matter what its length, to see
if it is the entry it wants,
.bP
-and \fBtgetent()\fP is searching for a terminal type that either is the
+and \fBtgetent\fP is searching for a terminal type that either is the
long entry, appears in the termcap file after the long entry, or
-does not appear in the file at all (so that \fBtgetent()\fP has to search
+does not appear in the file at all (so that \fBtgetent\fP has to search
the whole termcap file).
.PP
-Then \fBtgetent()\fP will overwrite memory, perhaps its stack, and probably core dump
+Then \fBtgetent\fP will overwrite memory, perhaps its stack, and probably core dump
the program.
Programs like telnet are particularly vulnerable; modern telnets
pass along values like the terminal type automatically.
.PP
The "after tc expansion" length will have a similar effect to the
above, but only for people who actually set TERM to that terminal
-type, since \fBtgetent()\fP only does "tc" expansion once it is found the
+type, since \fBtgetent\fP only does "tc" expansion once it is found the
terminal type it was looking for, not while searching.
.PP
In summary, a termcap entry that is longer than 1023 bytes can cause,
\fB@TIC@\fR(1M),
\fB@INFOCMP@\fR(1M),
\fBcurses\fR(3X),
+\fBcurs_color\fR(3X),
\fBprintf\fR(3),
\fBterm\fR(\*n).
\fBterm_variables\fR(3X).
projects / ncurses.git / blobdiff