ncurses 6.1 - patch 20190727
[ncurses.git] / man / terminfo.tail
1 .\"***************************************************************************
2 .\" Copyright (c) 1998-2018,2019 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: terminfo.tail,v 1.97 2019/07/20 10:20:57 tom Exp $
30 .ps +1
31 .SS User-Defined Capabilities
32 .
33 The preceding section listed the \fIpredefined\fP capabilities.
34 They deal with some special features for terminals no longer
35 (or possibly never) produced.
36 Occasionally there are special features of newer terminals which
37 are awkward or impossible to represent by reusing the predefined
38 capabilities.
39 .PP
40 \fBncurses\fP addresses this limitation by allowing user-defined capabilities.
41 The \fB@TIC@\fP and \fB@INFOCMP@\fP programs provide
42 the \fB\-x\fP option for this purpose.
43 When \fB\-x\fP is set,
44 \fB@TIC@\fP treats unknown capabilities as user-defined.
45 That is, if \fB@TIC@\fP encounters a capability name
46 which it does not recognize,
47 it infers its type (boolean, number or string) from the syntax
48 and makes an extended table entry for that capability.
49 The \fBuse_extended_names\fP(3X) function makes this information
50 conditionally available to applications.
51 The ncurses library provides the data leaving most of the behavior
52 to applications:
53 .bP
54 User-defined capability strings whose name begins
55 with \*(``k\*('' are treated as function keys.
56 .bP
57 The types (boolean, number, string) determined by \fB@TIC@\fP
58 can be inferred by successful calls on \fBtigetflag\fP, etc.
59 .bP
60 If the capability name happens to be two characters,
61 the capability is also available through the termcap interface.
62 .PP
63 While termcap is said to be extensible because it does not use a predefined set
64 of capabilities,
65 in practice it has been limited to the capabilities defined by
66 terminfo implementations.
67 As a rule,
68 user-defined capabilities intended for use by termcap applications should
69 be limited to booleans and numbers to avoid running past the 1023 byte
70 limit assumed by termcap implementations and their applications.
71 In particular, providing extended sets of function keys (past the 60
72 numbered keys and the handful of special named keys) is best done using
73 the longer names available using terminfo.
74 .
75 .SS A Sample Entry
76 .
77 The following entry, describing an ANSI-standard terminal, is representative
78 of what a \fBterminfo\fR entry for a modern terminal typically looks like.
79 .PP
80 .nf
81 .ft CW
82 \s-2ansi|ansi/pc-term compatible with color,
83         am, mc5i, mir, msgr,
84         colors#8, cols#80, it#8, lines#24, ncv#3, pairs#64,
85         acsc=+\\020\\,\\021-\\030.^Y0\\333`\\004a\\261f\\370g\\361h\\260
86              j\\331k\\277l\\332m\\300n\\305o~p\\304q\\304r\\304s_t\\303
87              u\\264v\\301w\\302x\\263y\\363z\\362{\\343|\\330}\\234~\\376,
88         bel=^G, blink=\\E[5m, bold=\\E[1m, cbt=\\E[Z, clear=\\E[H\\E[J,
89         cr=^M, cub=\\E[%p1%dD, cub1=\\E[D, cud=\\E[%p1%dB, cud1=\\E[B,
90         cuf=\\E[%p1%dC, cuf1=\\E[C, cup=\\E[%i%p1%d;%p2%dH,
91         cuu=\\E[%p1%dA, cuu1=\\E[A, dch=\\E[%p1%dP, dch1=\\E[P,
92         dl=\\E[%p1%dM, dl1=\\E[M, ech=\\E[%p1%dX, ed=\\E[J, el=\\E[K,
93         el1=\\E[1K, home=\\E[H, hpa=\\E[%i%p1%dG, ht=\\E[I, hts=\\EH,
94         ich=\\E[%p1%d@, il=\\E[%p1%dL, il1=\\E[L, ind=^J,
95         indn=\\E[%p1%dS, invis=\\E[8m, kbs=^H, kcbt=\\E[Z, kcub1=\\E[D,
96         kcud1=\\E[B, kcuf1=\\E[C, kcuu1=\\E[A, khome=\\E[H, kich1=\\E[L,
97         mc4=\\E[4i, mc5=\\E[5i, nel=\\r\\E[S, op=\\E[39;49m,
98         rep=%p1%c\\E[%p2%{1}%-%db, rev=\\E[7m, rin=\\E[%p1%dT,
99         rmacs=\\E[10m, rmpch=\\E[10m, rmso=\\E[m, rmul=\\E[m,
100         s0ds=\\E(B, s1ds=\\E)B, s2ds=\\E*B, s3ds=\\E+B,
101         setab=\\E[4%p1%dm, setaf=\\E[3%p1%dm,
102         sgr=\\E[0;10%?%p1%t;7%;
103                    %?%p2%t;4%;
104                    %?%p3%t;7%;
105                    %?%p4%t;5%;
106                    %?%p6%t;1%;
107                    %?%p7%t;8%;
108                    %?%p9%t;11%;m,
109         sgr0=\\E[0;10m, smacs=\\E[11m, smpch=\\E[11m, smso=\\E[7m,
110         smul=\\E[4m, tbc=\\E[3g, u6=\\E[%i%d;%dR, u7=\\E[6n,
111         u8=\\E[?%[;0123456789]c, u9=\\E[c, vpa=\\E[%i%p1%dd,
112 .fi
113 .ft R
114 .PP
115 Entries may continue onto multiple lines by placing white space at
116 the beginning of each line except the first.
117 Comments may be included on lines beginning with \*(``#\*(''.
118 Capabilities in
119 .I terminfo
120 are of three types:
121 .bP
122 Boolean capabilities which indicate that the terminal has
123 some particular feature,
124 .bP
125 numeric capabilities giving the size of the terminal
126 or the size of particular delays, and
127 .bP
128 string
129 capabilities, which give a sequence which can be used to perform particular
130 terminal operations.
131 .PP
132 .SS Types of Capabilities
133 .PP
134 All capabilities have names.
135 For instance, the fact that
136 ANSI-standard terminals have
137 .I "automatic margins"
138 (i.e., an automatic return and line-feed
139 when the end of a line is reached) is indicated by the capability \fBam\fR.
140 Hence the description of ansi includes \fBam\fR.
141 Numeric capabilities are followed by the character \*(``#\*('' and then a positive value.
142 Thus \fBcols\fR, which indicates the number of columns the terminal has,
143 gives the value \*(``80\*('' for ansi.
144 Values for numeric capabilities may be specified in decimal, octal or hexadecimal,
145 using the C programming language conventions (e.g., 255, 0377 and 0xff or 0xFF).
146 .PP
147 Finally, string valued capabilities, such as \fBel\fR (clear to end of line
148 sequence) are given by the two-character code, an \*(``=\*('', and then a string
149 ending at the next following \*(``,\*(''.
150 .PP
151 A number of escape sequences are provided in the string valued capabilities
152 for easy encoding of characters there:
153 .bP
154 Both \fB\eE\fR and \fB\ee\fR
155 map to an \s-1ESCAPE\s0 character,
156 .bP
157 \fB^x\fR maps to a control-x for any appropriate \fIx\fP, and
158 .bP
159 the sequences
160 .RS 6
161 .PP
162 \fB\en\fP, \fB\el\fP, \fB\er\fP, \fB\et\fP, \fB\eb\fP, \fB\ef\fP, and \fB\es\fR
163 .RE
164 .IP
165 produce
166 .RS 6
167 .PP
168 \fInewline\fP, \fIline-feed\fP, \fIreturn\fP, \fItab\fP, \fIbackspace\fP, \fIform-feed\fP, and \fIspace\fP,
169 .RE
170 .IP
171 respectively.
172 .PP
173 X/Open Curses does not say what \*(``appropriate \fIx\fP\*('' might be.
174 In practice, that is a printable ASCII graphic character.
175 The special case \*(``^?\*('' is interpreted as DEL (127).
176 In all other cases, the character value is AND'd with 0x1f,
177 mapping to ASCII control codes in the range 0 through 31.
178 .PP
179 Other escapes include
180 .bP
181 \fB\e^\fR for \fB^\fR,
182 .bP
183 \fB\e\e\fR for \fB\e\fR,
184 .bP
185 \fB\e\fR, for comma,
186 .bP
187 \fB\e:\fR for \fB:\fR,
188 .bP
189 and \fB\e0\fR for null.
190 .IP
191 \fB\e0\fR will produce \e200, which does not terminate a string but behaves
192 as a null character on most terminals, providing CS7 is specified.
193 See \fBstty\fP(1).
194 .IP
195 The reason for this quirk is to maintain binary compatibility of the
196 compiled terminfo files with other implementations,
197 e.g., the SVr4 systems, which document this.
198 Compiled terminfo files use null-terminated strings, with no lengths.
199 Modifying this would require a new binary format, 
200 which would not work with other implementations.
201 .PP
202 Finally, characters may be given as three octal digits after a \fB\e\fR.
203 .PP
204 A delay in milliseconds may appear anywhere in a string capability, enclosed in
205 $<..> brackets, as in \fBel\fP=\eEK$<5>,
206 and padding characters are supplied by \fBtputs\fP(3X)
207 to provide this delay.
208 .bP
209 The delay must be a number with at most one decimal
210 place of precision; it may be followed by suffixes \*(``*\*('' or \*(``/\*('' or both.
211 .bP
212 A \*(``*\*(''
213 indicates that the padding required is proportional to the number of lines
214 affected by the operation, and the amount given is the per-affected-unit
215 padding required.
216 (In the case of insert character, the factor is still the
217 number of \fIlines\fP affected.)
218 .IP
219 Normally, padding is advisory if the device has the \fBxon\fR
220 capability; it is used for cost computation but does not trigger delays.
221 .bP
222 A \*(``/\*(''
223 suffix indicates that the padding is mandatory and forces a delay of the given
224 number of milliseconds even on devices for which \fBxon\fR is present to
225 indicate flow control.
226 .PP
227 Sometimes individual capabilities must be commented out.
228 To do this, put a period before the capability name.
229 For example, see the second
230 .B ind
231 in the example above.
232 .br
233 .ne 5
234 .PP
235 .SS Fetching Compiled Descriptions
236 .PP
237 The \fBncurses\fP library searches for terminal descriptions in several places.
238 It uses only the first description found.
239 The library has a compiled-in list of places to search
240 which can be overridden by environment variables.
241 Before starting to search,
242 \fBncurses\fP eliminates duplicates in its search list.
243 .bP
244 If the environment variable TERMINFO is set, it is interpreted as the pathname
245 of a directory containing the compiled description you are working on.
246 Only that directory is searched.
247 .bP
248 If TERMINFO is not set,
249 \fBncurses\fR will instead look in the directory \fB$HOME/.terminfo\fR
250 for a compiled description.
251 .bP
252 Next, if the environment variable TERMINFO_DIRS is set,
253 \fBncurses\fR will interpret the contents of that variable
254 as a list of colon-separated directories (or database files) to be searched.
255 .IP
256 An empty directory name (i.e., if the variable begins or ends
257 with a colon, or contains adjacent colons)
258 is interpreted as the system location \fI\*d\fR.
259 .bP
260 Finally, \fBncurses\fP searches these compiled-in locations:
261 .RS
262 .bP
263 a list of directories (@TERMINFO_DIRS@), and
264 .bP
265 the system terminfo directory, \fI\*d\fR (the compiled-in default).
266 .RE
267 .SS Preparing Descriptions
268 .PP
269 We now outline how to prepare descriptions of terminals.
270 The most effective way to prepare a terminal description is by imitating
271 the description of a similar terminal in
272 .I terminfo
273 and to build up a description gradually, using partial descriptions
274 with
275 .I vi
276 or some other screen-oriented program to check that they are correct.
277 Be aware that a very unusual terminal may expose deficiencies in
278 the ability of the
279 .I terminfo
280 file to describe it
281 or bugs in the screen-handling code of the test program.
282 .PP
283 To get the padding for insert line right (if the terminal manufacturer
284 did not document it) a severe test is to edit a large file at 9600 baud,
285 delete 16 or so lines from the middle of the screen, then hit the \*(``u\*(''
286 key several times quickly.
287 If the terminal messes up, more padding is usually needed.
288 A similar test can be used for insert character.
289 .PP
290 .SS Basic Capabilities
291 .PP
292 The number of columns on each line for the terminal is given by the
293 \fBcols\fR numeric capability.
294 If the terminal is a \s-1CRT\s0, then the
295 number of lines on the screen is given by the \fBlines\fR capability.
296 If the terminal wraps around to the beginning of the next line when
297 it reaches the right margin, then it should have the \fBam\fR capability.
298 If the terminal can clear its screen, leaving the cursor in the home
299 position, then this is given by the \fBclear\fR string capability.
300 If the terminal overstrikes
301 (rather than clearing a position when a character is struck over)
302 then it should have the \fBos\fR capability.
303 If the terminal is a printing terminal, with no soft copy unit,
304 give it both
305 .B hc
306 and
307 .BR os .
308 .RB ( os
309 applies to storage scope terminals, such as \s-1TEKTRONIX\s+1 4010
310 series, as well as hard copy and APL terminals.)
311 If there is a code to move the cursor to the left edge of the current
312 row, give this as
313 .BR cr .
314 (Normally this will be carriage return, control/M.)
315 If there is a code to produce an audible signal (bell, beep, etc)
316 give this as
317 .BR bel .
318 .PP
319 If there is a code to move the cursor one position to the left
320 (such as backspace) that capability should be given as
321 .BR cub1 .
322 Similarly, codes to move to the right, up, and down should be
323 given as
324 .BR cuf1 ,
325 .BR cuu1 ,
326 and
327 .BR cud1 .
328 These local cursor motions should not alter the text they pass over,
329 for example, you would not normally use \*(``\fBcuf1\fP=\ \*('' because the
330 space would erase the character moved over.
331 .PP
332 A very important point here is that the local cursor motions encoded
333 in
334 .I terminfo
335 are undefined at the left and top edges of a \s-1CRT\s0 terminal.
336 Programs should never attempt to backspace around the left edge,
337 unless
338 .B bw
339 is given,
340 and never attempt to go up locally off the top.
341 In order to scroll text up, a program will go to the bottom left corner
342 of the screen and send the
343 .B ind
344 (index) string.
345 .PP
346 To scroll text down, a program goes to the top left corner
347 of the screen and sends the
348 .B ri
349 (reverse index) string.
350 The strings
351 .B ind
352 and
353 .B ri
354 are undefined when not on their respective corners of the screen.
355 .PP
356 Parameterized versions of the scrolling sequences are
357 .B indn
358 and
359 .B rin
360 which have the same semantics as
361 .B ind
362 and
363 .B ri
364 except that they take one parameter, and scroll that many lines.
365 They are also undefined except at the appropriate edge of the screen.
366 .PP
367 The \fBam\fR capability tells whether the cursor sticks at the right
368 edge of the screen when text is output, but this does not necessarily
369 apply to a
370 .B cuf1
371 from the last column.
372 The only local motion which is defined from the left edge is if
373 .B bw
374 is given, then a
375 .B cub1
376 from the left edge will move to the right edge of the previous row.
377 If
378 .B bw
379 is not given, the effect is undefined.
380 This is useful for drawing a box around the edge of the screen, for example.
381 If the terminal has switch selectable automatic margins,
382 the
383 .I terminfo
384 file usually assumes that this is on; i.e., \fBam\fR.
385 If the terminal has a command which moves to the first column of the next
386 line, that command can be given as
387 .B nel
388 (newline).
389 It does not matter if the command clears the remainder of the current line,
390 so if the terminal has no
391 .B cr
392 and
393 .B lf
394 it may still be possible to craft a working
395 .B nel
396 out of one or both of them.
397 .PP
398 These capabilities suffice to describe hard-copy and \*(``glass-tty\*('' terminals.
399 Thus the model 33 teletype is described as
400 .PP
401 .DT
402 .nf
403 .ft CW
404 .\".in -2
405 \s-133\||\|tty33\||\|tty\||\|model 33 teletype,
406         bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1
407 .\".in +2
408 .ft R
409 .fi
410 .PP
411 while the Lear Siegler \s-1ADM-3\s0 is described as
412 .PP
413 .DT
414 .nf
415 .ft CW
416 .\".in -2
417 \s-1adm3\||\|3\||\|lsi adm3,
418         am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J,
419         ind=^J, lines#24,\s+1
420 .\".in +2
421 .ft R
422 .fi
423 .PP
424 .SS Parameterized Strings
425 .PP
426 Cursor addressing and other strings requiring parameters
427 in the terminal are described by a
428 parameterized string capability,
429 with \fIprintf\fP-like escapes such as \fI%x\fR in it.
430 For example, to address the cursor, the
431 .B cup
432 capability is given, using two parameters:
433 the row and column to address to.
434 (Rows and columns are numbered from zero and refer to the
435 physical screen visible to the user, not to any unseen memory.)
436 If the terminal has memory relative cursor addressing,
437 that can be indicated by
438 .BR mrcup .
439 .PP
440 The parameter mechanism uses a stack and special \fB%\fP codes
441 to manipulate it.
442 Typically a sequence will push one of the
443 parameters onto the stack and then print it in some format.
444 Print (e.g., "%d") is a special case.
445 Other operations, including "%t" pop their operand from the stack.
446 It is noted that more complex operations are often necessary,
447 e.g., in the \fBsgr\fP string.
448 .PP
449 The \fB%\fR encodings have the following meanings:
450 .PP
451 .TP 5
452 \fB%%\fP
453 outputs \*(``%\*(''
454 .TP
455 \fB%\fP\fI[[\fP:\fI]flags][width[.precision]][\fP\fBdoxXs\fP\fI]\fP
456 as in \fBprintf\fP(3), flags are \fI[\-+#]\fP and \fIspace\fP.
457 Use a \*(``:\*('' to allow the next character to be a \*(``\-\*('' flag,
458 avoiding interpreting \*(``%\-\*('' as an operator.
459 .TP
460 \f(CW%c\fP
461 print \fIpop()\fP like %c in \fBprintf\fP
462 .TP
463 \fB%s\fP
464 print \fIpop()\fP like %s in \fBprintf\fP
465 .TP
466 \fB%p\fP\fI[1\-9]\fP
467 push \fIi\fP'th parameter
468 .TP
469 \fB%P\fP\fI[a\-z]\fP
470 set dynamic variable \fI[a\-z]\fP to \fIpop()\fP
471 .TP
472 \fB%g\fP\fI[a\-z]/\fP
473 get dynamic variable \fI[a\-z]\fP and push it
474 .TP
475 \fB%P\fP\fI[A\-Z]\fP
476 set static variable \fI[a\-z]\fP to \fIpop()\fP
477 .TP
478 \fB%g\fP\fI[A\-Z]\fP
479 get static variable \fI[a\-z]\fP and push it
480 .IP
481 The terms "static" and "dynamic" are misleading.
482 Historically, these are simply two different sets of variables,
483 whose values are not reset between calls to \fBtparm\fP(3X).
484 However, that fact is not documented in other implementations.
485 Relying on it will adversely impact portability to other implementations.
486 .TP
487 \fB%'\fP\fIc\fP\fB'\fP
488 char constant \fIc\fP
489 .TP
490 \fB%{\fP\fInn\fP\fB}\fP
491 integer constant \fInn\fP
492 .TP
493 \fB%l\fP
494 push strlen(pop)
495 .TP
496 \fB%+\fP, \fB%\-\fP, \fB%*\fP, \fB%/\fP, \fB%m\fP
497 arithmetic (%m is \fImod\fP): \fIpush(pop() op pop())\fP
498 .TP
499 \fB%&\fP, \fB%|\fP, \fB%^\fP
500 bit operations (AND, OR and exclusive-OR): \fIpush(pop() op pop())\fP
501 .TP
502 \fB%=\fP, \fB%>\fP, \fB%<\fP
503 logical operations: \fIpush(pop() op pop())\fP
504 .TP
505 \fB%A\fP, \fB%O\fP
506 logical AND and OR operations (for conditionals)
507 .TP
508 \fB%!\fP, \fB%~\fP
509 unary operations (logical and bit complement): \fIpush(op pop())\fP
510 .TP
511 \fB%i\fP
512 add 1 to first two parameters (for ANSI terminals)
513 .TP
514 \fB%?\fP \fIexpr\fP \fB%t\fP \fIthenpart\fP \fB%e\fP \fIelsepart\fP \fB%;\fP
515 This forms an if-then-else.
516 The \fB%e\fP \fIelsepart\fP is optional.
517 Usually the \fB%?\fP \fIexpr\fP part pushes a value onto the stack,
518 and \fB%t\fP pops it from the stack, testing if it is nonzero (true).
519 If it is zero (false), control passes to the \fB%e\fP (else) part.
520 .IP
521 It is possible to form else-if's a la Algol 68:
522 .RS
523 \fB%?\fP c\d1\u \fB%t\fP b\d1\u \fB%e\fP c\d2\u \fB%t\fP b\d2\u \fB%e\fP c\d3\u \fB%t\fP b\d3\u \fB%e\fP c\d4\u \fB%t\fP b\d4\u \fB%e\fP \fB%;\fP
524 .RE
525 .IP
526 where c\di\u are conditions, b\di\u are bodies.
527 .IP
528 Use the \fB\-f\fP option of \fB@TIC@\fP or \fB@INFOCMP@\fP to see
529 the structure of if-then-else's.
530 Some strings, e.g., \fBsgr\fP can be very complicated when written
531 on one line.
532 The \fB\-f\fP option splits the string into lines with the parts indented.
533 .PP
534 Binary operations are in postfix form with the operands in the usual order.
535 That is, to get x\-5 one would use "%gx%{5}%-".
536 \fB%P\fP and \fB%g\fP variables are
537 persistent across escape-string evaluations.
538 .PP
539 Consider the HP2645, which, to get to row 3 and column 12, needs
540 to be sent \eE&a12c03Y padded for 6 milliseconds.
541 Note that the order
542 of the rows and columns is inverted here, and that the row and column
543 are printed as two digits.
544 Thus its \fBcup\fR capability is \*(``cup=6\eE&%p2%2dc%p1%2dY\*(''.
545 .PP
546 The Microterm \s-1ACT-IV\s0 needs the current row and column sent
547 preceded by a \fB^T\fR, with the row and column simply encoded in binary,
548 \*(``cup=^T%p1%c%p2%c\*(''.
549 Terminals which use \*(``%c\*('' need to be able to
550 backspace the cursor (\fBcub1\fR),
551 and to move the cursor up one line on the screen (\fBcuu1\fR).
552 This is necessary because it is not always safe to transmit \fB\en\fR
553 \fB^D\fR and \fB\er\fR, as the system may change or discard them.
554 (The library routines dealing with terminfo set tty modes so that
555 tabs are never expanded, so \et is safe to send.
556 This turns out to be essential for the Ann Arbor 4080.)
557 .PP
558 A final example is the \s-1LSI ADM\s0-3a, which uses row and column
559 offset by a blank character, thus \*(``cup=\eE=%p1%' '%+%c%p2%' '%+%c\*(''.
560 After sending \*(``\eE=\*('', this pushes the first parameter, pushes the
561 ASCII value for a space (32), adds them (pushing the sum on the stack
562 in place of the two previous values) and outputs that value as a character.
563 Then the same is done for the second parameter.
564 More complex arithmetic is possible using the stack.
565 .PP
566 .SS Cursor Motions
567 .PP
568 If the terminal has a fast way to home the cursor
569 (to very upper left corner of screen) then this can be given as
570 \fBhome\fR; similarly a fast way of getting to the lower left-hand corner
571 can be given as \fBll\fR; this may involve going up with \fBcuu1\fR
572 from the home position,
573 but a program should never do this itself (unless \fBll\fR does) because it
574 can make no assumption about the effect of moving up from the home position.
575 Note that the home position is the same as addressing to (0,0):
576 to the top left corner of the screen, not of memory.
577 (Thus, the \eEH sequence on HP terminals cannot be used for
578 .BR home .)
579 .PP
580 If the terminal has row or column absolute cursor addressing,
581 these can be given as single parameter capabilities
582 .B hpa
583 (horizontal position absolute)
584 and
585 .B vpa
586 (vertical position absolute).
587 Sometimes these are shorter than the more general two parameter
588 sequence (as with the hp2645) and can be used in preference to
589 .BR cup .
590 If there are parameterized local motions (e.g., move
591 .I n
592 spaces to the right) these can be given as
593 .BR cud ,
594 .BR cub ,
595 .BR cuf ,
596 and
597 .B cuu
598 with a single parameter indicating how many spaces to move.
599 These are primarily useful if the terminal does not have
600 .BR cup ,
601 such as the \s-1TEKTRONIX\s+1 4025.
602 .PP
603 If the terminal needs to be in a special mode when running
604 a program that uses these capabilities,
605 the codes to enter and exit this mode can be given as \fBsmcup\fR and \fBrmcup\fR.
606 This arises, for example, from terminals like the Concept with more than
607 one page of memory.
608 If the terminal has only memory relative cursor addressing and not screen
609 relative cursor addressing, a one screen-sized window must be fixed into
610 the terminal for cursor addressing to work properly.
611 This is also used for the \s-1TEKTRONIX\s+1 4025,
612 where
613 .B smcup
614 sets the command character to be the one used by terminfo.
615 If the \fBsmcup\fP sequence will not restore the screen after an
616 \fBrmcup\fP sequence is output (to the state prior to outputting
617 \fBrmcup\fP), specify \fBnrrmc\fP.
618 .PP
619 .SS Area Clears
620 .PP
621 If the terminal can clear from the current position to the end of the
622 line, leaving the cursor where it is, this should be given as \fBel\fR.
623 If the terminal can clear from the beginning of the line to the current
624 position inclusive, leaving
625 the cursor where it is, this should be given as \fBel1\fP.
626 If the terminal can clear from the current position to the end of the
627 display, then this should be given as \fBed\fR.
628 \fBEd\fR is only defined from the first column of a line.
629 (Thus, it can be simulated by a request to delete a large number of lines,
630 if a true
631 .B ed
632 is not available.)
633 .PP
634 .SS Insert/delete line and vertical motions
635 .PP
636 If the terminal can open a new blank line before the line where the cursor
637 is, this should be given as \fBil1\fR; this is done only from the first
638 position of a line.
639 The cursor must then appear on the newly blank line.
640 If the terminal can delete the line which the cursor is on, then this
641 should be given as \fBdl1\fR; this is done only from the first position on
642 the line to be deleted.
643 Versions of
644 .B il1
645 and
646 .B dl1
647 which take a single parameter and insert or delete that many lines can
648 be given as
649 .B il
650 and
651 .BR dl .
652 .PP
653 If the terminal has a settable scrolling region (like the vt100)
654 the command to set this can be described with the
655 .B csr
656 capability, which takes two parameters:
657 the top and bottom lines of the scrolling region.
658 The cursor position is, alas, undefined after using this command.
659 .PP
660 It is possible to get the effect of insert or delete line using
661 .B csr
662 on a properly chosen region; the
663 .B sc
664 and
665 .B rc
666 (save and restore cursor) commands may be useful for ensuring that
667 your synthesized insert/delete string does not move the cursor.
668 (Note that the \fBncurses\fR(3X) library does this synthesis
669 automatically, so you need not compose insert/delete strings for
670 an entry with \fBcsr\fR).
671 .PP
672 Yet another way to construct insert and delete might be to use a combination of
673 index with the memory-lock feature found on some terminals (like the HP\-700/90
674 series, which however also has insert/delete).
675 .PP
676 Inserting lines at the top or bottom of the screen can also be
677 done using
678 .B ri
679 or
680 .B ind
681 on many terminals without a true insert/delete line,
682 and is often faster even on terminals with those features.
683 .PP
684 The boolean \fBnon_dest_scroll_region\fR should be set if each scrolling
685 window is effectively a view port on a screen-sized canvas.
686 To test for
687 this capability, create a scrolling region in the middle of the screen,
688 write something to the bottom line, move the cursor to the top of the region,
689 and do \fBri\fR followed by \fBdl1\fR or \fBind\fR.
690 If the data scrolled
691 off the bottom of the region by the \fBri\fR re-appears, then scrolling
692 is non-destructive.
693 System V and XSI Curses expect that \fBind\fR, \fBri\fR,
694 \fBindn\fR, and \fBrin\fR will simulate destructive scrolling; their
695 documentation cautions you not to define \fBcsr\fR unless this is true.
696 This \fBcurses\fR implementation is more liberal and will do explicit erases
697 after scrolling if \fBndsrc\fR is defined.
698 .PP
699 If the terminal has the ability to define a window as part of
700 memory, which all commands affect,
701 it should be given as the parameterized string
702 .BR wind .
703 The four parameters are the starting and ending lines in memory
704 and the starting and ending columns in memory, in that order.
705 .PP
706 If the terminal can retain display memory above, then the
707 \fBda\fR capability should be given; if display memory can be retained
708 below, then \fBdb\fR should be given.
709 These indicate
710 that deleting a line or scrolling may bring non-blank lines up from below
711 or that scrolling back with \fBri\fR may bring down non-blank lines.
712 .PP
713 .SS Insert/Delete Character
714 .PP
715 There are two basic kinds of intelligent terminals with respect to
716 insert/delete character which can be described using
717 .I terminfo.
718 The most common insert/delete character operations affect only the characters
719 on the current line and shift characters off the end of the line rigidly.
720 Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make
721 a distinction between typed and untyped blanks on the screen, shifting
722 upon an insert or delete only to an untyped blank on the screen which is
723 either eliminated, or expanded to two untyped blanks.
724 .PP
725 You can determine the
726 kind of terminal you have by clearing the screen and then typing
727 text separated by cursor motions.
728 Type \*(``abc\ \ \ \ def\*('' using local
729 cursor motions (not spaces) between the \*(``abc\*('' and the \*(``def\*(''.
730 Then position the cursor before the \*(``abc\*('' and put the terminal in insert
731 mode.
732 If typing characters causes the rest of the line to shift
733 rigidly and characters to fall off the end, then your terminal does
734 not distinguish between blanks and untyped positions.
735 If the \*(``abc\*(''
736 shifts over to the \*(``def\*('' which then move together around the end of the
737 current line and onto the next as you insert, you have the second type of
738 terminal, and should give the capability \fBin\fR, which stands for
739 \*(``insert null\*(''.
740 .PP
741 While these are two logically separate attributes (one line versus multi-line
742 insert mode, and special treatment of untyped spaces) we have seen no
743 terminals whose insert mode cannot be described with the single attribute.
744 .PP
745 Terminfo can describe both terminals which have an insert mode, and terminals
746 which send a simple sequence to open a blank position on the current line.
747 Give as \fBsmir\fR the sequence to get into insert mode.
748 Give as \fBrmir\fR the sequence to leave insert mode.
749 Now give as \fBich1\fR any sequence needed to be sent just before sending
750 the character to be inserted.
751 Most terminals with a true insert mode
752 will not give \fBich1\fR; terminals which send a sequence to open a screen
753 position should give it here.
754 .PP
755 If your terminal has both, insert mode is usually preferable to \fBich1\fR.
756 Technically, you should not give both unless the terminal actually requires
757 both to be used in combination.
758 Accordingly, some non-curses applications get
759 confused if both are present; the symptom is doubled characters in an update
760 using insert.
761 This requirement is now rare; most \fBich\fR sequences do not
762 require previous smir, and most smir insert modes do not require \fBich1\fR
763 before each character.
764 Therefore, the new \fBcurses\fR actually assumes this
765 is the case and uses either \fBrmir\fR/\fBsmir\fR or \fBich\fR/\fBich1\fR as
766 appropriate (but not both).
767 If you have to write an entry to be used under
768 new curses for a terminal old enough to need both, include the
769 \fBrmir\fR/\fBsmir\fR sequences in \fBich1\fR.
770 .PP
771 If post insert padding is needed, give this as a number of milliseconds
772 in \fBip\fR (a string option).
773 Any other sequence which may need to be
774 sent after an insert of a single character may also be given in \fBip\fR.
775 If your terminal needs both to be placed into an \*(``insert mode\*('' and
776 a special code to precede each inserted character, then both
777 .BR smir / rmir
778 and
779 .B ich1
780 can be given, and both will be used.
781 The
782 .B ich
783 capability, with one parameter,
784 .IR n ,
785 will repeat the effects of
786 .B ich1
787 .I n
788 times.
789 .PP
790 If padding is necessary between characters typed while not
791 in insert mode, give this as a number of milliseconds padding in \fBrmp\fP.
792 .PP
793 It is occasionally necessary to move around while in insert mode
794 to delete characters on the same line (e.g., if there is a tab after
795 the insertion position).
796 If your terminal allows motion while in
797 insert mode you can give the capability \fBmir\fR to speed up inserting
798 in this case.
799 Omitting \fBmir\fR will affect only speed.
800 Some terminals
801 (notably Datamedia's) must not have \fBmir\fR because of the way their
802 insert mode works.
803 .PP
804 Finally, you can specify
805 .B dch1
806 to delete a single character,
807 .B dch
808 with one parameter,
809 .IR n ,
810 to delete
811 .I n characters,
812 and delete mode by giving \fBsmdc\fR and \fBrmdc\fR
813 to enter and exit delete mode (any mode the terminal needs to be placed
814 in for
815 .B dch1
816 to work).
817 .PP
818 A command to erase
819 .I n
820 characters (equivalent to outputting
821 .I n
822 blanks without moving the cursor)
823 can be given as
824 .B ech
825 with one parameter.
826 .PP
827 .SS "Highlighting, Underlining, and Visible Bells"
828 .PP
829 If your terminal has one or more kinds of display attributes,
830 these can be represented in a number of different ways.
831 You should choose one display form as
832 \f2standout mode\fR,
833 representing a good, high contrast, easy-on-the-eyes,
834 format for highlighting error messages and other attention getters.
835 (If you have a choice, reverse video plus half-bright is good,
836 or reverse video alone.)
837 The sequences to enter and exit standout mode
838 are given as \fBsmso\fR and \fBrmso\fR, respectively.
839 If the code to change into or out of standout
840 mode leaves one or even two blank spaces on the screen,
841 as the TVI 912 and Teleray 1061 do,
842 then \fBxmc\fR should be given to tell how many spaces are left.
843 .PP
844 Codes to begin underlining and end underlining can be given as \fBsmul\fR
845 and \fBrmul\fR respectively.
846 If the terminal has a code to underline the current character and move
847 the cursor one space to the right,
848 such as the Microterm Mime,
849 this can be given as \fBuc\fR.
850 .PP
851 Other capabilities to enter various highlighting modes include
852 .B blink
853 (blinking)
854 .B bold
855 (bold or extra bright)
856 .B dim
857 (dim or half-bright)
858 .B invis
859 (blanking or invisible text)
860 .B prot
861 (protected)
862 .B rev
863 (reverse video)
864 .B sgr0
865 (turn off
866 .I all
867 attribute modes)
868 .B smacs
869 (enter alternate character set mode)
870 and
871 .B rmacs
872 (exit alternate character set mode).
873 Turning on any of these modes singly may or may not turn off other modes.
874 .PP
875 If there is a sequence to set arbitrary combinations of modes,
876 this should be given as
877 .B sgr
878 (set attributes),
879 taking 9 parameters.
880 Each parameter is either 0 or nonzero, as the corresponding attribute is on or off.
881 The 9 parameters are, in order:
882 standout, underline, reverse, blink, dim, bold, blank, protect, alternate
883 character set.
884 Not all modes need be supported by
885 .BR sgr ,
886 only those for which corresponding separate attribute commands exist.
887 .PP
888 For example, the DEC vt220 supports most of the modes:
889 .PP
890 .TS
891 center;
892 l l l
893 l l l
894 lw18 lw14 lw18.
895 \fBtparm parameter      attribute       escape sequence\fP
896
897 none    none    \\E[0m
898 p1      standout        \\E[0;1;7m
899 p2      underline       \\E[0;4m
900 p3      reverse \\E[0;7m
901 p4      blink   \\E[0;5m
902 p5      dim     not available
903 p6      bold    \\E[0;1m
904 p7      invis   \\E[0;8m
905 p8      protect not used
906 p9      altcharset      ^O (off) ^N (on)
907 .TE
908 .PP
909 We begin each escape sequence by turning off any existing modes, since
910 there is no quick way to determine whether they are active.
911 Standout is set up to be the combination of reverse and bold.
912 The vt220 terminal has a protect mode,
913 though it is not commonly used in sgr
914 because it protects characters on the screen from the host's erasures.
915 The altcharset mode also is different in that it is either ^O or ^N,
916 depending on whether it is off or on.
917 If all modes are turned on, the resulting sequence is \\E[0;1;4;5;7;8m^N.
918 .PP
919 Some sequences are common to different modes.
920 For example, ;7 is output when either p1 or p3 is true, that is, if
921 either standout or reverse modes are turned on.
922 .PP
923 Writing out the above sequences, along with their dependencies yields
924 .PP
925 .ne 11
926 .TS
927 center;
928 l l l
929 l l l
930 lw18 lw14 lw18.
931 \fBsequence     when to output  terminfo translation\fP
932
933 .ft CW
934 \\E[0   always  \\E[0
935 ;1      if p1 or p6     %?%p1%p6%|%t;1%;
936 ;4      if p2   %?%p2%|%t;4%;
937 ;5      if p4   %?%p4%|%t;5%;
938 ;7      if p1 or p3     %?%p1%p3%|%t;7%;
939 ;8      if p7   %?%p7%|%t;8%;
940 m       always  m
941 ^N or ^O        if p9 ^N, else ^O       %?%p9%t^N%e^O%;
942 .ft R
943 .TE
944 .PP
945 Putting this all together into the sgr sequence gives:
946 .PP
947 .ft CW
948 .nf
949     sgr=\\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p4%t;5%;
950         %?%p1%p3%|%t;7%;%?%p7%t;8%;m%?%p9%t\\016%e\\017%;,
951 .fi
952 .ft R
953 .PP
954 Remember that if you specify sgr, you must also specify sgr0.
955 Also, some implementations rely on sgr being given if sgr0 is,
956 Not all terminfo entries necessarily have an sgr string, however.
957 Many terminfo entries are derived from termcap entries
958 which have no sgr string.
959 The only drawback to adding an sgr string is that termcap also
960 assumes that sgr0 does not exit alternate character set mode.
961 .PP
962 Terminals with the \*(``magic cookie\*('' glitch
963 .RB ( xmc )
964 deposit special \*(``cookies\*('' when they receive mode-setting sequences,
965 which affect the display algorithm rather than having extra bits for
966 each character.
967 Some terminals, such as the HP 2621, automatically leave standout
968 mode when they move to a new line or the cursor is addressed.
969 Programs using standout mode should exit standout mode before
970 moving the cursor or sending a newline,
971 unless the
972 .B msgr
973 capability, asserting that it is safe to move in standout mode, is present.
974 .PP
975 If the terminal has
976 a way of flashing the screen to indicate an error quietly (a bell replacement)
977 then this can be given as \fBflash\fR; it must not move the cursor.
978 .PP
979 If the cursor needs to be made more visible than normal when it is
980 not on the bottom line (to make, for example, a non-blinking underline into an
981 easier to find block or blinking underline)
982 give this sequence as
983 .BR cvvis .
984 If there is a way to make the cursor completely invisible, give that as
985 .BR civis .
986 The capability
987 .B cnorm
988 should be given which undoes the effects of both of these modes.
989 .PP
990 If your terminal correctly generates underlined characters
991 (with no special codes needed)
992 even though it does not overstrike,
993 then you should give the capability \fBul\fR.
994 If a character overstriking another leaves both characters on the screen,
995 specify the capability \fBos\fP.
996 If overstrikes are erasable with a blank,
997 then this should be indicated by giving \fBeo\fR.
998 .PP
999 .SS Keypad and Function Keys
1000 .PP
1001 If the terminal has a keypad that transmits codes when the keys are pressed,
1002 this information can be given.
1003 Note that it is not possible to handle
1004 terminals where the keypad only works in local (this applies, for example,
1005 to the unshifted HP 2621 keys).
1006 If the keypad can be set to transmit or not transmit,
1007 give these codes as \fBsmkx\fR and \fBrmkx\fR.
1008 Otherwise the keypad is assumed to always transmit.
1009 .PP
1010 The codes sent by the left arrow, right arrow, up arrow, down arrow,
1011 and home keys can be given as
1012 \fBkcub1, kcuf1, kcuu1, kcud1, \fRand\fB khome\fR respectively.
1013 If there are function keys such as f0, f1, ..., f10, the codes they send
1014 can be given as \fBkf0, kf1, ..., kf10\fR.
1015 If these keys have labels other than the default f0 through f10, the labels
1016 can be given as \fBlf0, lf1, ..., lf10\fR.
1017 .PP
1018 The codes transmitted by certain other special keys can be given:
1019 .bP
1020 .B kll
1021 (home down),
1022 .bP
1023 .B kbs
1024 (backspace),
1025 .bP
1026 .B ktbc
1027 (clear all tabs),
1028 .bP
1029 .B kctab
1030 (clear the tab stop in this column),
1031 .bP
1032 .B kclr
1033 (clear screen or erase key),
1034 .bP
1035 .B kdch1
1036 (delete character),
1037 .bP
1038 .B kdl1
1039 (delete line),
1040 .bP
1041 .B krmir
1042 (exit insert mode),
1043 .bP
1044 .B kel
1045 (clear to end of line),
1046 .bP
1047 .B ked
1048 (clear to end of screen),
1049 .bP
1050 .B kich1
1051 (insert character or enter insert mode),
1052 .bP
1053 .B kil1
1054 (insert line),
1055 .bP
1056 .B knp
1057 (next page),
1058 .bP
1059 .B kpp
1060 (previous page),
1061 .bP
1062 .B kind
1063 (scroll forward/down),
1064 .bP
1065 .B kri
1066 (scroll backward/up),
1067 .bP
1068 .B khts
1069 (set a tab stop in this column).
1070 .PP
1071 In addition, if the keypad has a 3 by 3 array of keys including the four
1072 arrow keys, the other five keys can be given as
1073 .BR ka1 ,
1074 .BR ka3 ,
1075 .BR kb2 ,
1076 .BR kc1 ,
1077 and
1078 .BR kc3 .
1079 These keys are useful when the effects of a 3 by 3 directional pad are needed.
1080 .PP
1081 Strings to program function keys can be given as
1082 .BR pfkey ,
1083 .BR pfloc ,
1084 and
1085 .BR pfx .
1086 A string to program screen labels should be specified as \fBpln\fP.
1087 Each of these strings takes two parameters: the function key number to
1088 program (from 0 to 10) and the string to program it with.
1089 Function key numbers out of this range may program undefined keys in
1090 a terminal dependent manner.
1091 The difference between the capabilities is that
1092 .B pfkey
1093 causes pressing the given key to be the same as the user typing the
1094 given string;
1095 .B pfloc
1096 causes the string to be executed by the terminal in local; and
1097 .B pfx
1098 causes the string to be transmitted to the computer.
1099 .PP
1100 The capabilities \fBnlab\fP, \fBlw\fP and \fBlh\fP
1101 define the number of programmable
1102 screen labels and their width and height.
1103 If there are commands to turn the labels on and off,
1104 give them in \fBsmln\fP and \fBrmln\fP.
1105 \fBsmln\fP is normally output after one or more pln
1106 sequences to make sure that the change becomes visible.
1107 .PP
1108 .SS Tabs and Initialization
1109 .PP
1110 A few capabilities are used only for tabs:
1111 .bP
1112 If the terminal has hardware tabs, the command to advance to the next
1113 tab stop can be given as
1114 .B ht
1115 (usually control/I).
1116 .bP
1117 A \*(``back-tab\*('' command which moves leftward to the preceding tab stop can
1118 be given as
1119 .BR cbt .
1120 .IP
1121 By convention, if the teletype modes indicate that tabs are being
1122 expanded by the computer rather than being sent to the terminal,
1123 programs should not use
1124 .B ht
1125 or
1126 .B cbt
1127 even if they are present, since the user may not have the tab stops
1128 properly set.
1129 .bP
1130 If the terminal has hardware tabs which are initially set every
1131 .I n
1132 spaces when the terminal is powered up,
1133 the numeric parameter
1134 .B it
1135 is given, showing the number of spaces the tabs are set to.
1136 .IP
1137 The \fBit\fP capability is normally used by the \fB@TSET@\fP
1138 command to determine whether to set the mode for hardware tab expansion,
1139 and whether to set the tab stops.
1140 If the terminal has tab stops that can be saved in non-volatile memory,
1141 the terminfo description can assume that they are properly set.
1142 .PP
1143 Other capabilities
1144 include
1145 .bP
1146 .BR is1 ,
1147 .BR is2 ,
1148 and
1149 .BR is3 ,
1150 initialization strings for the terminal,
1151 .bP
1152 .BR iprog ,
1153 the path name of a program to be run to initialize the terminal,
1154 .bP
1155 and \fBif\fR, the name of a file containing long initialization strings.
1156 .PP
1157 These strings are expected to set the terminal into modes consistent
1158 with the rest of the terminfo description.
1159 They are normally sent to the terminal, by the
1160 .I init
1161 option of the \fB@TPUT@\fP program, each time the user logs in.
1162 They will be printed in the following order:
1163 .RS
1164 .TP
1165 run the program
1166 .B iprog
1167 .TP
1168 output
1169 .br
1170 \fBis1\fP and
1171 .br
1172 \fBis2\fP
1173 .TP
1174 set the margins using
1175 \fBmgc\fP or
1176 .br
1177 \fBsmglp\fP and \fBsmgrp\fP or
1178 .br
1179 \fBsmgl\fP and \fBsmgr\fP
1180 .TP
1181 set tabs using
1182 .B tbc
1183 and
1184 .B hts
1185 .TP
1186 print the file
1187 \fBif\fP
1188 .TP
1189 and finally output
1190 \fBis3\fP.
1191 .RE
1192 .PP
1193 Most initialization is done with
1194 .BR is2 .
1195 Special terminal modes can be set up without duplicating strings
1196 by putting the common sequences in
1197 .B is2
1198 and special cases in
1199 .B is1
1200 and
1201 .BR is3 .
1202 .PP
1203 A set of sequences that does a harder reset from a totally unknown state
1204 can be given as
1205 .BR rs1 ,
1206 .BR rs2 ,
1207 .B rf
1208 and
1209 .BR rs3 ,
1210 analogous to
1211 .B is1 ,
1212 .B is2 ,
1213 .B if
1214 and
1215 .B is3
1216 respectively.
1217 These strings are output
1218 by \fIreset\fP option of \fB@TPUT@\fP,
1219 or by the \fB@RESET@\fP program
1220 (an alias of \fB@TSET@\fP),
1221 which is used when the terminal gets into a wedged state.
1222 Commands are normally placed in
1223 .BR rs1 ,
1224 .B rs2
1225 .B rs3
1226 and
1227 .B rf
1228 only if they produce annoying effects on the screen and are not
1229 necessary when logging in.
1230 For example, the command to set the vt100 into 80-column mode would
1231 normally be part of
1232 .BR is2 ,
1233 but it causes an annoying glitch of the screen and is not normally
1234 needed since the terminal is usually already in 80-column mode.
1235 .PP
1236 The \fB@RESET@\fP program writes strings including
1237 .BR iprog ,
1238 etc., in the same order as the
1239 .I init
1240 program, using 
1241 .BR rs1 ,
1242 etc., instead of
1243 .BR is1 ,
1244 etc.
1245 If any of
1246 .BR rs1 ,
1247 .BR rs2 ,
1248 .BR rs3 ,
1249 or
1250 .B rf
1251 reset capability strings are missing,
1252 the \fB@RESET@\fP program
1253 falls back upon the corresponding initialization capability string.
1254 .PP
1255 If there are commands to set and clear tab stops, they can be given as
1256 .B tbc
1257 (clear all tab stops)
1258 and
1259 .B hts
1260 (set a tab stop in the current column of every row).
1261 If a more complex sequence is needed to set the tabs than can be
1262 described by this, the sequence can be placed in
1263 .B is2
1264 or
1265 .BR if .
1266 .PP
1267 The \fB@TPUT@ reset\fP command uses the same capability strings
1268 as the \fB@RESET@\fP command,
1269 although the two programs (\fB@TPUT@\fP and \fB@RESET@\fP)
1270 provide different command-line options.
1271 .PP
1272 In practice, these terminfo capabilities are not often used in
1273 initialization of tabs
1274 (though they are required for the \fB@TABS@\fP program):
1275 .bP
1276 Almost all hardware terminals (at least those which supported tabs)
1277 initialized those to every \fIeight\fP columns:
1278 .IP
1279 The only exception was the AT&T 2300 series,
1280 which set tabs to every \fIfive\fP columns.
1281 .bP
1282 In particular, developers of the hardware terminals which are commonly used
1283 as models for modern terminal emulators provided documentation demonstrating
1284 that \fIeight\fP columns were the standard.
1285 .bP
1286 Because of this, the terminal initialization programs
1287 \fB@TPUT@\fP and \fB@TSET@\fP
1288 use the
1289 \fBtbc\fP (\fBclear_all_tabs\fP) and
1290 \fBhts\fP (\fBset_tab\fP) capabilities directly
1291 only when the \fBit\fP (\fBinit_tabs\fP) capability
1292 is set to a value other than \fIeight\fP.
1293 .SS Delays and Padding
1294 .PP
1295 Many older and slower terminals do not support either XON/XOFF or DTR
1296 handshaking, including hard copy terminals and some very archaic CRTs
1297 (including, for example, DEC VT100s).
1298 These may require padding characters
1299 after certain cursor motions and screen changes.
1300 .PP
1301 If the terminal uses xon/xoff handshaking for flow control (that is,
1302 it automatically emits ^S back to the host when its input buffers are
1303 close to full), set
1304 .BR xon .
1305 This capability suppresses the emission of padding.
1306 You can also set it
1307 for memory-mapped console devices effectively that do not have a speed limit.
1308 Padding information should still be included so that routines can
1309 make better decisions about relative costs, but actual pad characters will
1310 not be transmitted.
1311 .PP
1312 If \fBpb\fR (padding baud rate) is given, padding is suppressed at baud rates
1313 below the value of \fBpb\fR.
1314 If the entry has no padding baud rate, then
1315 whether padding is emitted or not is completely controlled by \fBxon\fR.
1316 .PP
1317 If the terminal requires other than a null (zero) character as a pad,
1318 then this can be given as \fBpad\fR.
1319 Only the first character of the
1320 .B pad
1321 string is used.
1322 .PP
1323 .SS Status Lines
1324 Some terminals have an extra \*(``status line\*('' which is not normally used by
1325 software (and thus not counted in the terminal's \fBlines\fR capability).
1326 .PP
1327 The simplest case is a status line which is cursor-addressable but not
1328 part of the main scrolling region on the screen; the Heathkit H19 has
1329 a status line of this kind, as would a 24-line VT100 with a 23-line
1330 scrolling region set up on initialization.
1331 This situation is indicated
1332 by the \fBhs\fR capability.
1333 .PP
1334 Some terminals with status lines need special sequences to access the
1335 status line.
1336 These may be expressed as a string with single parameter
1337 \fBtsl\fR which takes the cursor to a given zero-origin column on the
1338 status line.
1339 The capability \fBfsl\fR must return to the main-screen
1340 cursor positions before the last \fBtsl\fR.
1341 You may need to embed the
1342 string values of \fBsc\fR (save cursor) and \fBrc\fR (restore cursor)
1343 in \fBtsl\fR and \fBfsl\fR to accomplish this.
1344 .PP
1345 The status line is normally assumed to be the same width as the width
1346 of the terminal.
1347 If this is untrue, you can specify it with the numeric
1348 capability \fBwsl\fR.
1349 .PP
1350 A command to erase or blank the status line may be specified as \fBdsl\fR.
1351 .PP
1352 The boolean capability \fBeslok\fR specifies that escape sequences, tabs,
1353 etc., work ordinarily in the status line.
1354 .PP
1355 The \fBncurses\fR implementation does not yet use any of these capabilities.
1356 They are documented here in case they ever become important.
1357 .PP
1358 .SS Line Graphics
1359 .PP
1360 Many terminals have alternate character sets useful for forms-drawing.
1361 Terminfo and \fBcurses\fR have built-in support
1362 for most of the drawing characters
1363 supported by the VT100, with some characters from the AT&T 4410v1 added.
1364 This alternate character set may be specified by the \fBacsc\fR capability.
1365 .PP
1366 .TS H
1367 center expand;
1368 l l l l l
1369 l l l l l
1370 _ _ _ _ _
1371 lw25 lw10 lw6 lw6 lw6.
1372 .\".TH
1373 \fBGlyph        ACS     Ascii   acsc    acsc\fR
1374 \fBName Name    Default Char    Value\fR
1375 arrow pointing right    ACS_RARROW      >       +       0x2b
1376 arrow pointing left     ACS_LARROW      <       ,       0x2c
1377 arrow pointing up       ACS_UARROW      ^       \-      0x2d
1378 arrow pointing down     ACS_DARROW      v       .       0x2e
1379 solid square block      ACS_BLOCK       #       0       0x30
1380 diamond                 ACS_DIAMOND     +       `       0x60
1381 checker board (stipple) ACS_CKBOARD     :       a       0x61
1382 degree symbol           ACS_DEGREE      \e      f       0x66
1383 plus/minus              ACS_PLMINUS     #       g       0x67
1384 board of squares        ACS_BOARD       #       h       0x68
1385 lantern symbol          ACS_LANTERN     #       i       0x69
1386 lower right corner      ACS_LRCORNER    +       j       0x6a
1387 upper right corner      ACS_URCORNER    +       k       0x6b
1388 upper left corner       ACS_ULCORNER    +       l       0x6c
1389 lower left corner       ACS_LLCORNER    +       m       0x6d
1390 large plus or crossover ACS_PLUS        +       n       0x6e
1391 scan line 1             ACS_S1          ~       o       0x6f
1392 scan line 3             ACS_S3          \-      p       0x70
1393 horizontal line         ACS_HLINE       \-      q       0x71
1394 scan line 7             ACS_S7          \-      r       0x72
1395 scan line 9             ACS_S9          \&_     s       0x73
1396 tee pointing right      ACS_LTEE        +       t       0x74
1397 tee pointing left       ACS_RTEE        +       u       0x75
1398 tee pointing up         ACS_BTEE        +       v       0x76
1399 tee pointing down       ACS_TTEE        +       w       0x77
1400 vertical line           ACS_VLINE       |       x       0x78
1401 less-than-or-equal-to   ACS_LEQUAL      <       y       0x79
1402 greater-than-or-equal-to        ACS_GEQUAL      >       z       0x7a
1403 greek pi                ACS_PI  *       {       0x7b
1404 not-equal               ACS_NEQUAL      !       |       0x7c
1405 UK pound sign           ACS_STERLING    f       }       0x7d
1406 bullet                  ACS_BULLET      o       ~       0x7e
1407 .TE
1408 .PP
1409 A few notes apply to the table itself:
1410 .bP
1411 X/Open Curses incorrectly states that the mapping for \fIlantern\fP is
1412 uppercase \*(``I\*('' although Unix implementations use the
1413 lowercase \*(``i\*('' mapping.
1414 .bP
1415 The DEC VT100 implemented graphics using the alternate character set
1416 feature, temporarily switching \fImodes\fP and sending characters
1417 in the range 0x60 (96) to 0x7e (126)
1418 (the \fBacsc Value\fP column in the table).
1419 .bP
1420 The AT&T terminal added graphics characters outside that range.
1421 .IP
1422 Some of the characters within the range do not match the VT100;
1423 presumably they were used in the AT&T terminal:
1424 \fIboard of squares\fP replaces the VT100 \fInewline\fP symbol, while
1425 \fIlantern symbol\fP replaces the VT100 \fIvertical tab\fP symbol.
1426 The other VT100 symbols for control characters (\fIhorizontal tab\fP,
1427 \fIcarriage return\fP and \fIline-feed\fP) are not (re)used in curses.
1428 .PP
1429 The best way to define a new device's graphics set is to add a column
1430 to a copy of this table for your terminal, giving the character which
1431 (when emitted between \fBsmacs\fR/\fBrmacs\fR switches) will be rendered
1432 as the corresponding graphic.
1433 Then read off the VT100/your terminal
1434 character pairs right to left in sequence; these become the ACSC string.
1435 .PP
1436 .SS Color Handling
1437 .PP
1438 The curses library functions \fBinit_pair\fP and \fBinit_color\fP
1439 manipulate the \fIcolor pairs\fP and \fIcolor values\fP discussed in this
1440 section
1441 (see \fBcurs_color\fP(3X) for details on these and related functions).
1442 .PP
1443 Most color terminals are either \*(``Tektronix-like\*('' or \*(``HP-like\*('':
1444 .bP
1445 Tektronix-like
1446 terminals have a predefined set of \fIN\fP colors
1447 (where \fIN\fP is usually 8),
1448 and can set
1449 character-cell foreground and background characters independently, mixing them
1450 into \fIN\fP\ *\ \fIN\fP color-pairs.
1451 .bP
1452 On HP-like terminals, the user must set each color
1453 pair up separately (foreground and background are not independently settable).
1454 Up to \fIM\fP color-pairs may be set up from 2*\fIM\fP different colors.
1455 ANSI-compatible terminals are Tektronix-like.
1456 .PP
1457 Some basic color capabilities are independent of the color method.
1458 The numeric
1459 capabilities \fBcolors\fR and \fBpairs\fR specify the maximum numbers of colors
1460 and color-pairs that can be displayed simultaneously.
1461 The \fBop\fR (original
1462 pair) string resets foreground and background colors to their default values
1463 for the terminal.
1464 The \fBoc\fR string resets all colors or color-pairs to
1465 their default values for the terminal.
1466 Some terminals (including many PC
1467 terminal emulators) erase screen areas with the current background color rather
1468 than the power-up default background; these should have the boolean capability
1469 \fBbce\fR.
1470 .PP
1471 While the curses library works with \fIcolor pairs\fP
1472 (reflecting the inability of some devices to set foreground
1473 and background colors independently),
1474 there are separate capabilities for setting these features:
1475 .bP
1476 To change the current foreground or background color on a Tektronix-type
1477 terminal, use \fBsetaf\fR (set ANSI foreground) and \fBsetab\fR (set ANSI
1478 background) or \fBsetf\fR (set foreground) and \fBsetb\fR (set background).
1479 These take one parameter, the color number.
1480 The SVr4 documentation describes
1481 only \fBsetaf\fR/\fBsetab\fR; the XPG4 draft says that "If the terminal
1482 supports ANSI escape sequences to set background and foreground, they should
1483 be coded as \fBsetaf\fR and \fBsetab\fR, respectively.
1484 .bP
1485 If the terminal
1486 supports other escape sequences to set background and foreground, they should
1487 be coded as \fBsetf\fR and \fBsetb\fR, respectively.
1488 The \fBvidputs\fR and the \fBrefresh\fP(3X) functions
1489 use the \fBsetaf\fR and \fBsetab\fR capabilities if they are defined.
1490 .PP
1491 The \fBsetaf\fR/\fBsetab\fR and \fBsetf\fR/\fBsetb\fR capabilities take a
1492 single numeric argument each.
1493 Argument values 0-7 of \fBsetaf\fR/\fBsetab\fR are portably defined as
1494 follows (the middle column is the symbolic #define available in the header for
1495 the \fBcurses\fR or \fBncurses\fR libraries).
1496 The terminal hardware is free to
1497 map these as it likes, but the RGB values indicate normal locations in color
1498 space.
1499 .PP
1500 .TS H
1501 center;
1502 l c c c
1503 l l n l.
1504 \fBColor        #define         Value   RGB\fR
1505 black   \fBCOLOR_BLACK\fR       0       0, 0, 0
1506 red     \fBCOLOR_RED\ \fR       1       max,0,0
1507 green   \fBCOLOR_GREEN\fR       2       0,max,0
1508 yellow  \fBCOLOR_YELLOW\fR      3       max,max,0
1509 blue    \fBCOLOR_BLUE\fR        4       0,0,max
1510 magenta \fBCOLOR_MAGENTA\fR     5       max,0,max
1511 cyan    \fBCOLOR_CYAN\fR        6       0,max,max
1512 white   \fBCOLOR_WHITE\fR       7       max,max,max
1513 .TE
1514 .PP
1515 The argument values of \fBsetf\fR/\fBsetb\fR historically correspond to
1516 a different mapping, i.e.,
1517 .TS H
1518 center;
1519 l c c c
1520 l l n l.
1521 \fBColor        #define         Value   RGB\fR
1522 black   \fBCOLOR_BLACK\fR       0       0, 0, 0
1523 blue    \fBCOLOR_BLUE\fR        1       0,0,max
1524 green   \fBCOLOR_GREEN\fR       2       0,max,0
1525 cyan    \fBCOLOR_CYAN\fR        3       0,max,max
1526 red     \fBCOLOR_RED\ \fR       4       max,0,0
1527 magenta \fBCOLOR_MAGENTA\fR     5       max,0,max
1528 yellow  \fBCOLOR_YELLOW\fR      6       max,max,0
1529 white   \fBCOLOR_WHITE\fR       7       max,max,max
1530 .TE
1531 .PP
1532 It is important to not confuse the two sets of color capabilities;
1533 otherwise red/blue will be interchanged on the display.
1534 .PP
1535 On an HP-like terminal, use \fBscp\fR with a color-pair number parameter to set
1536 which color pair is current.
1537 .PP
1538 Some terminals allow the \fIcolor values\fP to be modified:
1539 .bP
1540 On a Tektronix-like terminal, the capability \fBccc\fR may be present to
1541 indicate that colors can be modified.
1542 If so, the \fBinitc\fR capability will
1543 take a color number (0 to \fBcolors\fR \- 1)and three more parameters which
1544 describe the color.
1545 These three parameters default to being interpreted as RGB
1546 (Red, Green, Blue) values.
1547 If the boolean capability \fBhls\fR is present,
1548 they are instead as HLS (Hue, Lightness, Saturation) indices.
1549 The ranges are
1550 terminal-dependent.
1551 .bP
1552 On an HP-like terminal, \fBinitp\fR may give a capability for changing a
1553 color-pair value.
1554 It will take seven parameters; a color-pair number (0 to
1555 \fBmax_pairs\fR \- 1), and two triples describing first background and then
1556 foreground colors.
1557 These parameters must be (Red, Green, Blue) or
1558 (Hue, Lightness, Saturation) depending on \fBhls\fR.
1559 .PP
1560 On some color terminals, colors collide with highlights.
1561 You can register
1562 these collisions with the \fBncv\fR capability.
1563 This is a bit-mask of
1564 attributes not to be used when colors are enabled.
1565 The correspondence with the
1566 attributes understood by \fBcurses\fR is as follows:
1567 .PP
1568 .TS
1569 center;
1570 l l l l
1571 lw20 lw2 lw10 lw10.
1572 \fBAttribute    Bit     Decimal Set by\fR
1573 A_STANDOUT      0       1       sgr
1574 A_UNDERLINE     1       2       sgr
1575 A_REVERSE       2       4       sgr
1576 A_BLINK         3       8       sgr
1577 A_DIM           4       16      sgr
1578 A_BOLD          5       32      sgr
1579 A_INVIS         6       64      sgr
1580 A_PROTECT       7       128     sgr
1581 A_ALTCHARSET    8       256     sgr
1582 A_HORIZONTAL    9       512     sgr1
1583 A_LEFT  10      1024    sgr1
1584 A_LOW   11      2048    sgr1
1585 A_RIGHT 12      4096    sgr1
1586 A_TOP   13      8192    sgr1
1587 A_VERTICAL      14      16384   sgr1
1588 A_ITALIC        15      32768   sitm
1589 .TE
1590 .PP
1591 For example, on many IBM PC consoles, the underline attribute collides with the
1592 foreground color blue and is not available in color mode.
1593 These should have
1594 an \fBncv\fR capability of 2.
1595 .PP
1596 SVr4 curses does nothing with \fBncv\fR, ncurses recognizes it and optimizes
1597 the output in favor of colors.
1598 .PP
1599 .SS Miscellaneous
1600 If the terminal requires other than a null (zero) character as a pad, then this
1601 can be given as pad.
1602 Only the first character of the pad string is used.
1603 If the terminal does not have a pad character, specify npc.
1604 Note that ncurses implements the termcap-compatible \fBPC\fR variable;
1605 though the application may set this value to something other than
1606 a null, ncurses will test \fBnpc\fR first and use napms if the terminal
1607 has no pad character.
1608 .PP
1609 If the terminal can move up or down half a line,
1610 this can be indicated with
1611 .B hu
1612 (half-line up)
1613 and
1614 .B hd
1615 (half-line down).
1616 This is primarily useful for superscripts and subscripts on hard-copy terminals.
1617 If a hard-copy terminal can eject to the next page (form feed), give this as
1618 .B ff
1619 (usually control/L).
1620 .PP
1621 If there is a command to repeat a given character a given number of
1622 times (to save time transmitting a large number of identical characters)
1623 this can be indicated with the parameterized string
1624 .BR rep .
1625 The first parameter is the character to be repeated and the second
1626 is the number of times to repeat it.
1627 Thus, tparm(repeat_char, 'x', 10) is the same as \*(``xxxxxxxxxx\*(''.
1628 .PP
1629 If the terminal has a settable command character, such as the \s-1TEKTRONIX\s+1 4025,
1630 this can be indicated with
1631 .BR cmdch .
1632 A prototype command character is chosen which is used in all capabilities.
1633 This character is given in the
1634 .B cmdch
1635 capability to identify it.
1636 The following convention is supported on some UNIX systems:
1637 The environment is to be searched for a
1638 .B CC
1639 variable, and if found, all
1640 occurrences of the prototype character are replaced with the character
1641 in the environment variable.
1642 .PP
1643 Terminal descriptions that do not represent a specific kind of known
1644 terminal, such as
1645 .IR switch ,
1646 .IR dialup ,
1647 .IR patch ,
1648 and
1649 .IR network ,
1650 should include the
1651 .B gn
1652 (generic) capability so that programs can complain that they do not know
1653 how to talk to the terminal.
1654 (This capability does not apply to
1655 .I virtual
1656 terminal descriptions for which the escape sequences are known.)
1657 .PP
1658 If the terminal has a \*(``meta key\*('' which acts as a shift key,
1659 setting the 8th bit of any character transmitted, this fact can
1660 be indicated with
1661 .BR km .
1662 Otherwise, software will assume that the 8th bit is parity and it
1663 will usually be cleared.
1664 If strings exist to turn this \*(``meta mode\*('' on and off, they
1665 can be given as
1666 .B smm
1667 and
1668 .BR rmm .
1669 .PP
1670 If the terminal has more lines of memory than will fit on the screen
1671 at once, the number of lines of memory can be indicated with
1672 .BR lm .
1673 A value of
1674 .BR lm #0
1675 indicates that the number of lines is not fixed,
1676 but that there is still more memory than fits on the screen.
1677 .PP
1678 If the terminal is one of those supported by the \s-1UNIX\s+1 virtual
1679 terminal protocol, the terminal number can be given as
1680 .BR vt .
1681 .PP
1682 Media copy
1683 strings which control an auxiliary printer connected to the terminal
1684 can be given as
1685 .BR mc0 :
1686 print the contents of the screen,
1687 .BR mc4 :
1688 turn off the printer, and
1689 .BR mc5 :
1690 turn on the printer.
1691 When the printer is on, all text sent to the terminal will be sent
1692 to the printer.
1693 It is undefined whether the text is also displayed on the terminal screen
1694 when the printer is on.
1695 A variation
1696 .B mc5p
1697 takes one parameter, and leaves the printer on for as many characters
1698 as the value of the parameter, then turns the printer off.
1699 The parameter should not exceed 255.
1700 All text, including
1701 .BR mc4 ,
1702 is transparently passed to the printer while an
1703 .B mc5p
1704 is in effect.
1705 .PP
1706 .SS Glitches and Braindamage
1707 .PP
1708 Hazeltine terminals, which do not allow \*(``~\*('' characters to be displayed should
1709 indicate \fBhz\fR.
1710 .PP
1711 Terminals which ignore a line-feed immediately after an \fBam\fR wrap,
1712 such as the Concept and vt100,
1713 should indicate \fBxenl\fR.
1714 .PP
1715 If
1716 .B el
1717 is required to get rid of standout
1718 (instead of merely writing normal text on top of it),
1719 \fBxhp\fP should be given.
1720 .PP
1721 Teleray terminals, where tabs turn all characters moved over to blanks,
1722 should indicate \fBxt\fR (destructive tabs).
1723 Note: the variable indicating this is now \*(``dest_tabs_magic_smso\*(''; in
1724 older versions, it was teleray_glitch.
1725 This glitch is also taken to mean that it is not possible to position
1726 the cursor on top of a \*(``magic cookie\*('',
1727 that to erase standout mode it is instead necessary to use
1728 delete and insert line.
1729 The ncurses implementation ignores this glitch.
1730 .PP
1731 The Beehive Superbee, which is unable to correctly transmit the escape
1732 or control/C characters, has
1733 .BR xsb ,
1734 indicating that the f1 key is used for escape and f2 for control/C.
1735 (Only certain Superbees have this problem, depending on the ROM.)
1736 Note that in older terminfo versions, this capability was called
1737 \*(``beehive_glitch\*(''; it is now \*(``no_esc_ctl_c\*(''.
1738 .PP
1739 Other specific terminal problems may be corrected by adding more
1740 capabilities of the form \fBx\fR\fIx\fR.
1741 .PP
1742 .SS Pitfalls of Long Entries
1743 .PP
1744 Long terminfo entries are unlikely to be a problem; to date, no entry has even
1745 approached terminfo's 4096-byte string-table maximum.
1746 Unfortunately, the termcap
1747 translations are much more strictly limited (to 1023 bytes), thus termcap translations
1748 of long terminfo entries can cause problems.
1749 .PP
1750 The man pages for 4.3BSD and older versions of \fBtgetent\fP instruct the user to
1751 allocate a 1024-byte buffer for the termcap entry.
1752 The entry gets null-terminated by
1753 the termcap library, so that makes the maximum safe length for a termcap entry
1754 1k\-1 (1023) bytes.
1755 Depending on what the application and the termcap library
1756 being used does, and where in the termcap file the terminal type that \fBtgetent\fP
1757 is searching for is, several bad things can happen.
1758 .PP
1759 Some termcap libraries print a warning message or exit if they find an
1760 entry that's longer than 1023 bytes; others do not; others truncate the
1761 entries to 1023 bytes.
1762 Some application programs allocate more than
1763 the recommended 1K for the termcap entry; others do not.
1764 .PP
1765 Each termcap entry has two important sizes associated with it: before
1766 "tc" expansion, and after "tc" expansion.
1767 "tc" is the capability that
1768 tacks on another termcap entry to the end of the current one, to add
1769 on its capabilities.
1770 If a termcap entry does not use the "tc"
1771 capability, then of course the two lengths are the same.
1772 .PP
1773 The "before tc expansion" length is the most important one, because it
1774 affects more than just users of that particular terminal.
1775 This is the
1776 length of the entry as it exists in /etc/termcap, minus the
1777 backslash-newline pairs, which \fBtgetent\fP strips out while reading it.
1778 Some termcap libraries strip off the final newline, too (GNU termcap does not).
1779 Now suppose:
1780 .bP
1781 a termcap entry before expansion is more than 1023 bytes long,
1782 .bP
1783 and the application has only allocated a 1k buffer,
1784 .bP
1785 and the termcap library (like the one in BSD/OS 1.1 and GNU) reads
1786 the whole entry into the buffer, no matter what its length, to see
1787 if it is the entry it wants,
1788 .bP
1789 and \fBtgetent\fP is searching for a terminal type that either is the
1790 long entry, appears in the termcap file after the long entry, or
1791 does not appear in the file at all (so that \fBtgetent\fP has to search
1792 the whole termcap file).
1793 .PP
1794 Then \fBtgetent\fP will overwrite memory, perhaps its stack, and probably core dump
1795 the program.
1796 Programs like telnet are particularly vulnerable; modern telnets
1797 pass along values like the terminal type automatically.
1798 The results are almost
1799 as undesirable with a termcap library, like SunOS 4.1.3 and Ultrix 4.4, that
1800 prints warning messages when it reads an overly long termcap entry.
1801 If a
1802 termcap library truncates long entries, like OSF/1 3.0, it is immune to dying
1803 here but will return incorrect data for the terminal.
1804 .PP
1805 The "after tc expansion" length will have a similar effect to the
1806 above, but only for people who actually set TERM to that terminal
1807 type, since \fBtgetent\fP only does "tc" expansion once it is found the
1808 terminal type it was looking for, not while searching.
1809 .PP
1810 In summary, a termcap entry that is longer than 1023 bytes can cause,
1811 on various combinations of termcap libraries and applications, a core
1812 dump, warnings, or incorrect operation.
1813 If it is too long even before
1814 "tc" expansion, it will have this effect even for users of some other
1815 terminal types and users whose TERM variable does not have a termcap
1816 entry.
1817 .PP
1818 When in \-C (translate to termcap) mode, the \fBncurses\fR implementation of
1819 \fB@TIC@\fR(1M) issues warning messages when the pre-tc length of a termcap
1820 translation is too long.
1821 The \-c (check) option also checks resolved (after tc
1822 expansion) lengths.
1823 .SS Binary Compatibility
1824 It is not wise to count on portability of binary terminfo entries between
1825 commercial UNIX versions.
1826 The problem is that there are at least two versions
1827 of terminfo (under HP\-UX and AIX) which diverged from System V terminfo after
1828 SVr1, and have added extension capabilities to the string table that (in the
1829 binary format) collide with System V and XSI Curses extensions.
1830 .SH EXTENSIONS
1831 .PP
1832 Searching for terminal descriptions in
1833 \fB$HOME/.terminfo\fR and TERMINFO_DIRS 
1834 is not supported by older implementations.
1835 .PP
1836 Some SVr4 \fBcurses\fR implementations, and all previous to SVr4, do not
1837 interpret the %A and %O operators in parameter strings.
1838 .PP
1839 SVr4/XPG4 do not specify whether \fBmsgr\fR licenses movement while in
1840 an alternate-character-set mode (such modes may, among other things, map
1841 CR and NL to characters that do not trigger local motions).
1842 The \fBncurses\fR implementation ignores \fBmsgr\fR in \fBALTCHARSET\fR
1843 mode.
1844 This raises the possibility that an XPG4
1845 implementation making the opposite interpretation may need terminfo
1846 entries made for \fBncurses\fR to have \fBmsgr\fR turned off.
1847 .PP
1848 The \fBncurses\fR library handles insert-character and insert-character modes
1849 in a slightly non-standard way to get better update efficiency.
1850 See
1851 the \fBInsert/Delete Character\fR subsection above.
1852 .PP
1853 The parameter substitutions for \fBset_clock\fR and \fBdisplay_clock\fR are
1854 not documented in SVr4 or the XSI Curses standard.
1855 They are deduced from the
1856 documentation for the AT&T 505 terminal.
1857 .PP
1858 Be careful assigning the \fBkmous\fR capability.
1859 The \fBncurses\fR library wants to interpret it as \fBKEY_MOUSE\fR,
1860 for use by terminals and emulators like xterm
1861 that can return mouse-tracking information in the keyboard-input stream.
1862 .PP
1863 X/Open Curses does not mention italics.
1864 Portable applications must assume that numeric capabilities are
1865 signed 16-bit values.
1866 This includes the \fIno_color_video\fP (ncv) capability.
1867 The 32768 mask value used for italics with ncv can be confused with
1868 an absent or cancelled ncv.
1869 If italics should work with colors,
1870 then the ncv value must be specified, even if it is zero.
1871 .PP
1872 Different commercial ports of terminfo and curses support different subsets of
1873 the XSI Curses standard and (in some cases) different extension sets.
1874 Here
1875 is a summary, accurate as of October 1995:
1876 .bP
1877 \fBSVR4, Solaris, ncurses\fR \-\-
1878 These support all SVr4 capabilities.
1879 .bP
1880 \fBSGI\fR \-\-
1881 Supports the SVr4 set, adds one undocumented extended string
1882 capability (\fBset_pglen\fR).
1883 .bP
1884 \fBSVr1, Ultrix\fR \-\-
1885 These support a restricted subset of terminfo capabilities.
1886 The booleans end with \fBxon_xoff\fR;
1887 the numerics with \fBwidth_status_line\fR;
1888 and the strings with \fBprtr_non\fR.
1889 .bP
1890 \fBHP/UX\fR \-\-
1891 Supports the SVr1 subset, plus the SVr[234] numerics \fBnum_labels\fR,
1892 \fBlabel_height\fR, \fBlabel_width\fR, plus function keys 11 through 63, plus
1893 \fBplab_norm\fR, \fBlabel_on\fR, and \fBlabel_off\fR, plus some incompatible
1894 extensions in the string table.
1895 .bP
1896 \fBAIX\fR \-\-
1897 Supports the SVr1 subset, plus function keys 11 through 63, plus a number
1898 of incompatible string table extensions.
1899 .bP
1900 \fBOSF\fR \-\-
1901 Supports both the SVr4 set and the AIX extensions.
1902 .SH FILES
1903 .TP 25
1904 \*d/?/*
1905 files containing terminal descriptions
1906 .SH SEE ALSO
1907 \fB@TABS@\fR(1),
1908 \fB@TIC@\fR(1M),
1909 \fB@INFOCMP@\fR(1M),
1910 \fBcurses\fR(3X),
1911 \fBcurs_color\fR(3X),
1912 \fBcurs_variables\fR(3X),
1913 \fBprintf\fR(3),
1914 \fBterm\fR(\*n).
1915 \fBterm_variables\fR(3X).
1916 \fBuser_caps\fR(5).
1917 .SH AUTHORS
1918 Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
1919 Based on pcurses by Pavel Curtis.