X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fterminfo.tail;h=80ce6432f3e83af9023e60f4490a6f48ed99709f;hp=ec076483fe83bfab5dd2760707ffd892fe71c312;hb=62ca6190a9a8ddccb2c4d5ca7b2ef9f88432da65;hpb=67ab4b308e932639a3a832052228d445c41c54b4 diff --git a/man/terminfo.tail b/man/terminfo.tail index ec076483..80ce6432 100644 --- a/man/terminfo.tail +++ b/man/terminfo.tail @@ -1,4 +1,4 @@ -.\" $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. @@ -156,20 +156,23 @@ which would not work with other implementations. 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 @@ -205,7 +208,7 @@ Next, if the environment variable TERMINFO_DIRS is set, 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: @@ -409,16 +412,16 @@ Use a \*(``:\*('' to allow the next character to be a \*(``\-\*('' flag, 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 @@ -445,7 +448,7 @@ integer constant \fInn\fP 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 @@ -457,7 +460,7 @@ logical operations: \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) @@ -645,7 +648,7 @@ System V and XSI Curses expect that \fBind\fR, \fBri\fR, \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, @@ -1079,8 +1082,7 @@ spaces when the terminal is powered up, 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, @@ -1100,9 +1102,7 @@ These strings are expected to set the terminal into modes consistent 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 @@ -1156,9 +1156,8 @@ analogous to 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 @@ -1173,10 +1172,7 @@ normally be part of 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 @@ -1191,8 +1187,7 @@ If any of .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 @@ -1329,16 +1324,24 @@ character pairs right to left in sequence; these become the ACSC string. .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 @@ -1354,6 +1357,11 @@ terminal emulators) erase screen areas with the current background color rather 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). @@ -1362,12 +1370,12 @@ The SVr4 documentation describes 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. @@ -1416,6 +1424,8 @@ otherwise red/blue will be interchanged on the display. 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 @@ -1427,7 +1437,7 @@ If the boolean capability \fBhls\fR is present, 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 @@ -1656,13 +1666,13 @@ Unfortunately, the termcap 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 @@ -1683,7 +1693,7 @@ The "before tc expansion" length is the most important one, because it 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 @@ -1695,12 +1705,12 @@ and the termcap library (like the one in BSD/OS 1.1 and GNU) reads 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. @@ -1713,7 +1723,7 @@ here but will return incorrect data for the terminal. .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, @@ -1816,6 +1826,7 @@ files containing terminal descriptions \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).