]> ncurses.scripts.mit.edu Git - ncurses.git/blob - man/terminfo.tail
ncurses 4.2
[ncurses.git] / man / terminfo.tail
1 .\" $Id: terminfo.tail,v 1.15 1997/12/14 01:50:06 tom Exp $
2 .\" Beginning of terminfo.tail file
3 .ps +1
4 .PP
5 .SS A Sample Entry
6 .PP
7 The following entry, describing an ANSI-standard terminal, is representative
8 of what a \fBterminfo\fR entry for a modern terminal typically looks like.
9 .PP
10 .nf
11 .in -2
12 .ta .3i
13 .ft CW
14 \s-2ansi|ansi/pc-term compatible with color, 
15         mc5i, 
16         colors#8, ncv#3, pairs#64, 
17         cub=\\E[%p1%dD, cud=\\E[%p1%dB, cuf=\\E[%p1%dC, 
18         cuu=\\E[%p1%dA, dch=\\E[%p1%dP, dl=\\E[%p1%dM, 
19         ech=\\E[%p1%dX, el1=\\E[1K, hpa=\\E[%p1%dG, ht=\\E[I, 
20         ich=\\E[%p1%d@, il=\\E[%p1%dL, indn=\\E[%p1%dS, 
21         kbs=^H, kcbt=\\E[Z, kcub1=\\E[D, kcud1=\\E[B, 
22         kcuf1=\\E[C, kcuu1=\\E[A, kf1=\\E[M, kf10=\\E[V, 
23         kf11=\\E[W, kf12=\\E[X, kf2=\\E[N, kf3=\\E[O, kf4=\\E[P, 
24         kf5=\\E[Q, kf6=\\E[R, kf7=\\E[S, kf8=\\E[T, kf9=\\E[U, 
25         kich1=\\E[L, mc4=\\E[4i, mc5=\\E[5i, nel=\\r\\E[S, 
26         op=\\E[37;40m, rep=%p1%c\\E[%p2%{1}%-%db, 
27         rin=\\E[%p1%dT, s0ds=\\E(B, s1ds=\\E)B, s2ds=\\E*B, 
28         s3ds=\\E+B, setab=\\E[4%p1%dm, setaf=\\E[3%p1%dm, 
29         setb=\\E[4%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m, 
30         setf=\\E[3%?%p1%{1}%=%t4%e%p1%{3}%=%t6%e%p1%{4}%=%t1%e%p1%{6}%=%t3%e%p1%d%;m, 
31         sgr=\\E[0;10%?%p1%t;7%;%?%p2%t;4%;%?%p3%t;7%;%?%p4%t;5%;%?%p6%t;1%;%?%p7%t;8%;%?%p8%t;11%;%?%p9%t;12%;m, 
32         sgr0=\\E[0;10m, tbc=\\E[2g, u6=\\E[%d;%dR, u7=\\E[6n, 
33         u8=\\E[?%[;0123456789]c, u9=\\E[c, vpa=\\E[%p1%dd,\s+2
34 .in +2
35 .fi
36 .ft R
37 .PP
38 Entries may continue onto multiple lines by placing white space at
39 the beginning of each line except the first.
40 Comments may be included on lines beginning with ``#''.
41 Capabilities in
42 .I terminfo
43 are of three types:
44 Boolean capabilities which indicate that the terminal has
45 some particular feature, numeric capabilities giving the size of the terminal
46 or the size of particular delays, and string
47 capabilities, which give a sequence which can be used to perform particular
48 terminal operations.
49 .PP
50 .SS Types of Capabilities
51 .PP
52 All capabilities have names.  For instance, the fact that
53 ANSI-standard terminals have
54 .I "automatic margins"
55 (i.e., an automatic return and line-feed
56 when the end of a line is reached) is indicated by the capability \fBam\fR.
57 Hence the description of ansi includes \fBam\fR.
58 Numeric capabilities are followed by the character `#' and then the value.
59 Thus \fBcols\fR, which indicates the number of columns the terminal has,
60 gives the value `80' for ansi.
61 .PP
62 Finally, string valued capabilities, such as \fBel\fR (clear to end of line
63 sequence) are given by the two-character code, an `=', and then a string
64 ending at the next following `,'.
65 .PP
66 A number of escape sequences are provided in the string valued capabilities
67 for easy encoding of characters there.  Both \fB\eE\fR and \fB\ee\fR
68 map to an \s-1ESCAPE\s0 character,
69 \fB^x\fR maps to a control-x for any appropriate x, and the sequences
70 \fB\en \el \er \et \eb \ef \es\fR give
71 a newline, line-feed, return, tab, backspace, form-feed, and space.
72 Other escapes include \fB\e^\fR for \fB^\fR,
73 \fB\e\e\fR for \fB\e\fR,
74 \fB\e\fR, for comma,
75 \fB\e:\fR for \fB:\fR,
76 and \fB\e0\fR for null.
77 (\fB\e0\fR will produce \e200, which does not terminate a string but behaves
78 as a null character on most terminals.)
79 Finally, characters may be given as three octal digits after a \fB\e\fR.
80 .PP
81 A delay in milliseconds may appear anywhere in a string capability, enclosed in
82 $<..> brackets, as in \fBel\fP=\eEK$<5>, and padding characters are supplied by
83 .I tputs
84 to provide this delay.  The delay must be a number with at most one decimal
85 place of precision; it may be followed by suffixes `*' or '/' or both.  A `*'
86 indicates that the padding required is proportional to the number of lines
87 affected by the operation, and the amount given is the per-affected-unit
88 padding required.  (In the case of insert character, the factor is still the
89 number of
90 .IR lines
91 affected.)  Normally, padding is advisory if the device has the \fBxon\fR
92 capability; it is used for cost computation but does not trigger delays.  A `/'
93 suffix indicates that the padding is mandatory and forces a delay of the given
94 number of milliseconds even on devices for which \fBxon\fR is present to
95 indicate flow control.
96 .PP
97 Sometimes individual capabilities must be commented out.
98 To do this, put a period before the capability name.
99 For example, see the second
100 .B ind
101 in the example above.
102 .br
103 .ne 5
104 .PP
105 .SS Fetching Compiled Descriptions
106 .PP
107 If the environment variable TERMINFO is set, it is interpreted as the pathname
108 of a directory containing the compiled description you are working on.  Only
109 that directory is searched.
110 .PP
111 If TERMINFO is not set, the \fBncurses\fR version of the terminfo reader code
112 will instead look in the directory \fB$HOME/.terminfo\fR
113 for a compiled description.
114 If it fails to find one there, and the environment variable TERMINFO_DIRS is
115 set, it will interpret the contents of that variable as a list of colon-
116 separated directories to be searched (an empty entry is interpreted as a
117 command to search \fI\*d\fR).  If no description is found in any of the
118 TERMINFO_DIRS directories, the fetch fails.
119 .PP
120 If neither TERMINFO nor TERMINFO_DIRS is set, the last place tried will be the
121 system terminfo directory, \fI\*d\fR.
122 .PP
123 (Neither the \fB$HOME/.terminfo\fR lookups nor TERMINFO_DIRS extensions are
124 supported under stock System V terminfo/curses.)
125 .PP
126 .SS Preparing Descriptions
127 .PP
128 We now outline how to prepare descriptions of terminals.
129 The most effective way to prepare a terminal description is by imitating
130 the description of a similar terminal in
131 .I terminfo
132 and to build up a description gradually, using partial descriptions
133 with
134 .I vi
135 or some other screen-oriented program to check that they are correct.
136 Be aware that a very unusual terminal may expose deficiencies in
137 the ability of the
138 .I terminfo
139 file to describe it
140 or bugs in the screen-handling code of the test program.
141 .PP
142 To get the padding for insert line right (if the terminal manufacturer
143 did not document it) a severe test is to edit /etc/passwd at 9600 baud,
144 delete 16 or so lines from the middle of the screen, then hit the `u'
145 key several times quickly.
146 If the terminal messes up, more padding is usually needed.
147 A similar test can be used for insert character.
148 .PP
149 .SS Basic Capabilities
150 .PP
151 The number of columns on each line for the terminal is given by the
152 \fBcols\fR numeric capability.  If the terminal is a \s-1CRT\s0, then the
153 number of lines on the screen is given by the \fBlines\fR capability.
154 If the terminal wraps around to the beginning of the next line when
155 it reaches the right margin, then it should have the \fBam\fR capability.
156 If the terminal can clear its screen, leaving the cursor in the home
157 position, then this is given by the \fBclear\fR string capability.
158 If the terminal overstrikes
159 (rather than clearing a position when a character is struck over)
160 then it should have the \fBos\fR capability.
161 If the terminal is a printing terminal, with no soft copy unit,
162 give it both
163 .B hc
164 and
165 .BR os .
166 .RB ( os
167 applies to storage scope terminals, such as \s-1TEKTRONIX\s+1 4010
168 series, as well as hard copy and APL terminals.)
169 If there is a code to move the cursor to the left edge of the current
170 row, give this as
171 .BR cr .
172 (Normally this will be carriage return, control M.)
173 If there is a code to produce an audible signal (bell, beep, etc)
174 give this as
175 .BR bel .
176 .PP
177 If there is a code to move the cursor one position to the left
178 (such as backspace) that capability should be given as
179 .BR cub1 .
180 Similarly, codes to move to the right, up, and down should be
181 given as
182 .BR cuf1 ,
183 .BR cuu1 ,
184 and
185 .BR cud1 .
186 These local cursor motions should not alter the text they pass over,
187 for example, you would not normally use `\fBcuf1\fP=\ ' because the
188 space would erase the character moved over.
189 .PP
190 A very important point here is that the local cursor motions encoded
191 in
192 .I terminfo
193 are undefined at the left and top edges of a \s-1CRT\s0 terminal.
194 Programs should never attempt to backspace around the left edge,
195 unless
196 .B bw
197 is given,
198 and never attempt to go up locally off the top.
199 In order to scroll text up, a program will go to the bottom left corner
200 of the screen and send the
201 .B ind
202 (index) string.
203 .PP
204 To scroll text down, a program goes to the top left corner
205 of the screen and sends the
206 .B ri
207 (reverse index) string.
208 The strings
209 .B ind
210 and
211 .B ri
212 are undefined when not on their respective corners of the screen.
213 .PP
214 Parameterized versions of the scrolling sequences are
215 .B indn
216 and
217 .B rin
218 which have the same semantics as
219 .B ind
220 and
221 .B ri
222 except that they take one parameter, and scroll that many lines.
223 They are also undefined except at the appropriate edge of the screen.
224 .PP
225 The \fBam\fR capability tells whether the cursor sticks at the right
226 edge of the screen when text is output, but this does not necessarily
227 apply to a
228 .B cuf1
229 from the last column.
230 The only local motion which is defined from the left edge is if
231 .B bw
232 is given, then a
233 .B cub1
234 from the left edge will move to the right edge of the previous row.
235 If
236 .B bw
237 is not given, the effect is undefined.
238 This is useful for drawing a box around the edge of the screen, for example.
239 If the terminal has switch selectable automatic margins,
240 the
241 .I terminfo
242 file usually assumes that this is on; i.e., \fBam\fR.
243 If the terminal has a command which moves to the first column of the next
244 line, that command can be given as
245 .B nel
246 (newline).
247 It does not matter if the command clears the remainder of the current line,
248 so if the terminal has no
249 .B cr
250 and
251 .B lf
252 it may still be possible to craft a working
253 .B nel
254 out of one or both of them.
255 .PP
256 These capabilities suffice to describe hard-copy and \*(lqglass-tty\*(rq terminals.
257 Thus the model 33 teletype is described as
258 .PP
259 .DT
260 .nf
261 .ft CW
262 .in -7
263         \s-133\||\|tty33\||\|tty\||\|model 33 teletype,
264         bel=^G, cols#72, cr=^M, cud1=^J, hc, ind=^J, os,\s+1
265 .in +7
266 .ft R
267 .PP
268 while the Lear Siegler \s-1ADM\-3\s0 is described as
269 .PP
270 .DT
271 .nf
272 .ft CW
273 .in -7
274         \s-1adm3\||\|3\||\|lsi adm3,
275         am, bel=^G, clear=^Z, cols#80, cr=^M, cub1=^H, cud1=^J,
276         ind=^J, lines#24,\s+1
277 .in +7
278 .ft R
279 .fi
280 .PP
281 .SS Parameterized Strings
282 .PP
283 Cursor addressing and other strings requiring parameters
284 in the terminal are described by a
285 parameterized string capability, with 
286 .IR printf (3S)
287 like escapes \fB%x\fR in it.
288 For example, to address the cursor, the
289 .B cup
290 capability is given, using two parameters:
291 the row and column to address to.
292 (Rows and columns are numbered from zero and refer to the
293 physical screen visible to the user, not to any unseen memory.)
294 If the terminal has memory relative cursor addressing,
295 that can be indicated by
296 .BR mrcup .
297 .PP
298 The parameter mechanism uses a stack and special \fB%\fP codes
299 to manipulate it.  Typically a sequence will push one of the
300 parameters onto the stack and then print it in some format.
301 Often more complex operations are necessary.
302 .PP
303 The \fB%\fR encodings have the following meanings:
304 .PP
305 .DT
306 .nf
307 .ta .5i 1.5i
308         \s-1%%  outputs `%'
309         %d      print pop() as in printf
310         %2d     print pop() like %2d
311         %3d     print pop() like %3d
312         %02d
313         %03d    as in printf
314         %x      print pop() as in printf
315         %2x     print pop() like %2x
316         %3x     print pop() like %3x
317         %02x
318         %03x    as in printf
319         %c      print pop() gives %c
320         %s      print pop() gives %s
322         %p[1-9] push i'th parm
323         %P[a-z] set variable [a-z] to pop()
324         %g[a-z] get variable [a-z] and push it
325         %'c'    char constant c
326         %{nn}   integer constant nn
328         %+ %- %* %/ %m
329                 arithmetic (%m is mod): push(pop() op pop())
330         %& %| %^        bit operations: push(pop() op pop())
331         %= %> %<        logical operations: push(pop() op pop())
332         %A, %O  logical and & or operations (for conditionals)
333         %! %~   unary operations push(op pop())
334         %i      add 1 to first two parms (for ANSI terminals)
336         %? expr %t thenpart %e elsepart %;
337                 if-then-else, %e elsepart is optional.
338                 else-if's are possible a la Algol 68:
339                 %? c\d1\u %t b\d1\u %e c\d2\u %t b\d2\u %e c\d3\u %t b\d3\u %e c\d4\u %t b\d4\u %e %;
340 \s+1            c\di\u are conditions, b\di\u are bodies.
341 .fi
342 .PP
343 Binary operations are in postfix form with the operands in the usual order.
344 That is, to get x-5 one would use "%gx%{5}%-".  %P and %g variables are
345 persistent across escape-string evaluations.
346 .PP
347 Consider the HP2645, which, to get to row 3 and column 12, needs
348 to be sent \eE&a12c03Y padded for 6 milliseconds.  Note that the order
349 of the rows and columns is inverted here, and that the row and column
350 are printed as two digits.
351 Thus its \fBcup\fR capability is \*(lqcup=6\eE&%p2%2dc%p1%2dY\*(rq.
352 .PP
353 The Microterm \s-1ACT-IV\s0 needs the current row and column sent
354 preceded by a \fB^T\fR, with the row and column simply encoded in binary,
355 \*(lqcup=^T%p1%c%p2%c\*(rq.
356 Terminals which use \*(lq%c\*(rq need to be able to
357 backspace the cursor (\fBcub1\fR),
358 and to move the cursor up one line on the screen (\fBcuu1\fR).
359 This is necessary because it is not always safe to transmit \fB\en\fR
360 \fB^D\fR and \fB\er\fR, as the system may change or discard them.
361 (The library routines dealing with terminfo set tty modes so that
362 tabs are never expanded, so \et is safe to send.
363 This turns out to be essential for the Ann Arbor 4080.)
364 .PP
365 A final example is the \s-1LSI ADM\s0-3a, which uses row and column
366 offset by a blank character, thus \*(lqcup=\eE=%p1%' '%+%c%p2%' '%+%c\*(rq.
367 After sending `\eE=', this pushes the first parameter, pushes the
368 ASCII value for a space (32), adds them (pushing the sum on the stack
369 in place of the two previous values) and outputs that value as a character.
370 Then the same is done for the second parameter.
371 More complex arithmetic is possible using the stack.
372 .PP
373 If the terminal has row or column absolute cursor addressing,
374 these can be given as single parameter capabilities
375 .B hpa
376 (horizontal position absolute)
377 and
378 .B vpa
379 (vertical position absolute).
380 Sometimes these are shorter than the more general two parameter
381 sequence (as with the hp2645) and can be used in preference to
382 .B cup .
383 If there are parameterized local motions (e.g., move
384 .I n
385 spaces to the right) these can be given as
386 .BR cud ,
387 .BR cub ,
388 .BR cuf ,
389 and
390 .BR cuu
391 with a single parameter indicating how many spaces to move.
392 These are primarily useful if the terminal does not have
393 .BR cup ,
394 such as the \s-1TEKTRONIX\s+1 4025.
395 .PP
396 .SS Cursor Motions
397 .PP
398 If the terminal has a fast way to home the cursor
399 (to very upper left corner of screen) then this can be given as
400 \fBhome\fR; similarly a fast way of getting to the lower left-hand corner
401 can be given as \fBll\fR; this may involve going up with \fBcuu1\fR
402 from the home position,
403 but a program should never do this itself (unless \fBll\fR does) because it
404 can make no assumption about the effect of moving up from the home position.
405 Note that the home position is the same as addressing to (0,0):
406 to the top left corner of the screen, not of memory.
407 (Thus, the \eEH sequence on HP terminals cannot be used for
408 .BR home .)
409 .PP
410 .SS Area Clears
411 .PP
412 If the terminal can clear from the current position to the end of the
413 line, leaving the cursor where it is, this should be given as \fBel\fR.
414 If the terminal can clear from the current position to the end of the
415 display, then this should be given as \fBed\fR.
416 \fBEd\fR is only defined from the first column of a line.
417 (Thus, it can be simulated by a request to delete a large number of lines,
418 if a true
419 .B ed
420 is not available.)
421 .PP
422 .SS Insert/delete line and vertical motions
423 .PP
424 If the terminal can open a new blank line before the line where the cursor
425 is, this should be given as \fBil1\fR; this is done only from the first
426 position of a line.  The cursor must then appear on the newly blank line.
427 If the terminal can delete the line which the cursor is on, then this
428 should be given as \fBdl1\fR; this is done only from the first position on
429 the line to be deleted.
430 Versions of
431 .B il1
432 and
433 .B dl1
434 which take a single parameter and insert or delete that many lines can
435 be given as
436 .B il
437 and
438 .BR dl .
439 If the terminal has a settable scrolling region (like the vt100)
440 the command to set this can be described with the
441 .B csr
442 capability, which takes two parameters:
443 the top and bottom lines of the scrolling region.
444 The cursor position is, alas, undefined after using this command.
445 .PP
446 It is possible to get the effect of insert or delete line using
447 .B csr
448 on a properly chosen region; the
449 .B sc
450 and
451 .B rc
452 (save and restore cursor) commands may be useful for ensuring that 
453 your synthesized insert/delete string does not move the cursor.
454 (Note that the \fBncurses\fR(3X) library does this synthesis
455 automatically, so you need not compose insert/delete strings for
456 an entry with \fBcsr\fR).
457 .PP
458 Yet another way to construct insert and delete might be to use a combination of
459 index with the memory-lock feature found on some terminals (like the HP-700/90
460 series, which however also has insert/delete).
461 .PP
462 Inserting lines at the top or bottom of the screen can also be
463 done using
464 .B ri
465 or
466 .B ind
467 on many terminals without a true insert/delete line,
468 and is often faster even on terminals with those features.
469 .PP
470 The boolean \fBnon_dest_scroll_region\fR should be set if each scrolling
471 window is effectively a view port on a screen-sized canvas.  To test for
472 this capability, create a scrolling region in the middle of the screen, 
473 write something to the bottom line, move the cursor to the top of the region,
474 and do \fBri\fR followed by \fBdl1\fR or \fBind\fR.  If the data scrolled
475 off the bottom of the region by the \fBri\fR re-appears, then scrolling
476 is non-destructive.  System V and XSI Curses expect that \fBind\fR, \fBri\fR,
477 \fBindn\fR, and \fBrin\fR will simulate destructive scrolling; their
478 documentation cautions you not to define \fBcsr\fR unless this is true.
479 This \fBcurses\fR implementation is more liberal and will do explicit erases
480 after scrolling if \fBndstr\fR is defined.
481 .PP
482 If the terminal has the ability to define a window as part of
483 memory, which all commands affect,
484 it should be given as the parameterized string
485 .BR wind .
486 The four parameters are the starting and ending lines in memory
487 and the starting and ending columns in memory, in that order.
488 .PP
489 If the terminal can retain display memory above, then the
490 \fBda\fR capability should be given; if display memory can be retained
491 below, then \fBdb\fR should be given.  These indicate
492 that deleting a line or scrolling may bring non-blank lines up from below
493 or that scrolling back with \fBri\fR may bring down non-blank lines.
494 .PP
495 .SS Insert/Delete Character
496 .PP
497 There are two basic kinds of intelligent terminals with respect to
498 insert/delete character which can be described using
499 .I terminfo.
500 The most common insert/delete character operations affect only the characters
501 on the current line and shift characters off the end of the line rigidly.
502 Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make
503 a distinction between typed and untyped blanks on the screen, shifting
504 upon an insert or delete only to an untyped blank on the screen which is
505 either eliminated, or expanded to two untyped blanks.  You can determine the
506 kind of terminal you have by clearing the screen and then typing
507 text separated by cursor motions.  Type \*(lqabc\ \ \ \ def\*(rq using local
508 cursor motions (not spaces) between the \*(lqabc\*(rq and the \*(lqdef\*(rq.
509 Then position the cursor before the \*(lqabc\*(rq and put the terminal in insert
510 mode.  If typing characters causes the rest of the line to shift
511 rigidly and characters to fall off the end, then your terminal does
512 not distinguish between blanks and untyped positions.  If the \*(lqabc\*(rq
513 shifts over to the \*(lqdef\*(rq which then move together around the end of the
514 current line and onto the next as you insert, you have the second type of
515 terminal, and should give the capability \fBin\fR, which stands for
516 \*(lqinsert null\*(rq.
517 While these are two logically separate attributes (one line vs. multi-line
518 insert mode, and special treatment of untyped spaces) we have seen no
519 terminals whose insert mode cannot be described with the single attribute.
520 .PP
521 Terminfo can describe both terminals which have an insert mode, and terminals
522 which send a simple sequence to open a blank position on the current line.
523 Give as \fBsmir\fR the sequence to get into insert mode.
524 Give as \fBrmir\fR the sequence to leave insert mode.
525 Now give as \fBich1\fR any sequence needed to be sent just before sending
526 the character to be inserted.  Most terminals with a true insert mode
527 will not give \fBich1\fR; terminals which send a sequence to open a screen
528 position should give it here.
529 .PP
530 If your terminal has both, insert mode is usually preferable to \fBich1\fR.
531 Technically, you should not give both unless the terminal actually requires
532 both to be used in combination.  Accordingly, some non-curses applications get
533 confused if both are present; the symptom is doubled characters in an update
534 using insert.  This requirement is now rare; most \fBich\fR sequences do not
535 require previous smir, and most smir insert modes do not require \fBich1\fR
536 before each character.  Therefore, the new \fBcurses\fR actually assumes this
537 is the case and uses either \fBrmir\fR/\fBsmir\fR or \fBich\fR/\fBich1\fR as
538 appropriate (but not both).  If you have to write an entry to be used under
539 new curses for a terminal old enough to need both, include the
540 \fBrmir\fR/\fBsmir\fR sequences in \fBich1\fR.
541 .PP
542 If post insert padding is needed, give this as a number of milliseconds
543 in \fBip\fR (a string option).  Any other sequence which may need to be
544 sent after an insert of a single character may also be given in \fBip\fR.
545 If your terminal needs both to be placed into an `insert mode' and
546 a special code to precede each inserted character, then both
547 .BR smir / rmir
548 and
549 .B ich1
550 can be given, and both will be used.
551 The
552 .B ich
553 capability, with one parameter,
554 .IR n ,
555 will repeat the effects of
556 .B ich1
557 .I n
558 times.
559 .PP
560 It is occasionally necessary to move around while in insert mode
561 to delete characters on the same line (e.g., if there is a tab after
562 the insertion position).  If your terminal allows motion while in
563 insert mode you can give the capability \fBmir\fR to speed up inserting
564 in this case.  Omitting \fBmir\fR will affect only speed.   Some terminals
565 (notably Datamedia's) must not have \fBmir\fR because of the way their
566 insert mode works.
567 .PP
568 Finally, you can specify
569 .B dch1
570 to delete a single character,
571 .B dch
572 with one parameter,
573 .IR n ,
574 to delete
575 .I n characters,
576 and delete mode by giving \fBsmdc\fR and \fBrmdc\fR
577 to enter and exit delete mode (any mode the terminal needs to be placed
578 in for
579 .B dch1
580 to work).
581 .PP
582 A command to erase
583 .I n
584 characters (equivalent to outputting
585 .I n
586 blanks without moving the cursor)
587 can be given as
588 .B ech
589 with one parameter.
590 .PP
591 .SS "Highlighting, Underlining, and Visible Bells"
592 .PP
593 If your terminal has one or more kinds of display attributes,
594 these can be represented in a number of different ways.
595 You should choose one display form as
596 \f2standout mode\fR,
597 representing a good, high contrast, easy-on-the-eyes,
598 format for highlighting error messages and other attention getters.
599 (If you have a choice, reverse video plus half-bright is good,
600 or reverse video alone.)
601 The sequences to enter and exit standout mode
602 are given as \fBsmso\fR and \fBrmso\fR, respectively.
603 If the code to change into or out of standout
604 mode leaves one or even two blank spaces on the screen,
605 as the TVI 912 and Teleray 1061 do,
606 then \fBxmc\fR should be given to tell how many spaces are left.
607 .PP
608 Codes to begin underlining and end underlining can be given as \fBsmul\fR
609 and \fBrmul\fR respectively.
610 If the terminal has a code to underline the current character and move
611 the cursor one space to the right, 
612 such as the Microterm Mime,
613 this can be given as \fBuc\fR.
614 .PP
615 Other capabilities to enter various highlighting modes include
616 .B blink
617 (blinking)
618 .B bold
619 (bold or extra bright)
620 .B dim
621 (dim or half-bright)
622 .B invis
623 (blanking or invisible text)
624 .B prot
625 (protected)
626 .B rev
627 (reverse video)
628 .B sgr0
629 (turn off
630 .I all
631 attribute modes)
632 .B smacs
633 (enter alternate character set mode)
634 and
635 .B rmacs
636 (exit alternate character set mode).
637 Turning on any of these modes singly may or may not turn off other modes.
638 .PP
639 If there is a sequence to set arbitrary combinations of modes,
640 this should be given as
641 .B sgr
642 (set attributes),
643 taking 9 parameters.
644 Each parameter is either 0 or 1, as the corresponding attribute is on or off.
645 The 9 parameters are, in order:
646 standout, underline, reverse, blink, dim, bold, blank, protect, alternate
647 character set.
648 Not all modes need be supported by
649 .BR sgr ,
650 only those for which corresponding separate attribute commands exist.
651 .PP
652 Terminals with the ``magic cookie'' glitch
653 .RB ( xmc )
654 deposit special ``cookies'' when they receive mode-setting sequences,
655 which affect the display algorithm rather than having extra bits for
656 each character.
657 Some terminals, such as the HP 2621, automatically leave standout
658 mode when they move to a new line or the cursor is addressed.
659 Programs using standout mode should exit standout mode before
660 moving the cursor or sending a newline,
661 unless the
662 .B msgr
663 capability, asserting that it is safe to move in standout mode, is present.
664 .PP
665 If the terminal has
666 a way of flashing the screen to indicate an error quietly (a bell replacement)
667 then this can be given as \fBflash\fR; it must not move the cursor.
668 .PP
669 If the cursor needs to be made more visible than normal when it is
670 not on the bottom line (to make, for example, a non-blinking underline into an
671 easier to find block or blinking underline)
672 give this sequence as
673 .BR cvvis .
674 If there is a way to make the cursor completely invisible, give that as
675 .BR civis .
676 The capability
677 .BR cnorm
678 should be given which undoes the effects of both of these modes.
679 .PP
680 If the terminal needs to be in a special mode when running
681 a program that uses these capabilities,
682 the codes to enter and exit this mode can be given as \fBsmcup\fR and \fBrmcup\fR.
683 This arises, for example, from terminals like the Concept with more than
684 one page of memory.
685 If the terminal has only memory relative cursor addressing and not screen
686 relative cursor addressing, a one screen-sized window must be fixed into
687 the terminal for cursor addressing to work properly.
688 This is also used for the \s-1TEKTRONIX\s+1 4025,
689 where
690 .B smcup
691 sets the command character to be the one used by terminfo.
692 .PP
693 If your terminal correctly generates underlined characters
694 (with no special codes needed)
695 even though it does not overstrike,
696 then you should give the capability \fBul\fR.
697 If overstrikes are erasable with a blank,
698 then this should be indicated by giving \fBeo\fR.
699 .PP
700 .SS Keypad Handling
701 .PP
702 If the terminal has a keypad that transmits codes when the keys are pressed,
703 this information can be given. Note that it is not possible to handle
704 terminals where the keypad only works in local (this applies, for example,
705 to the unshifted HP 2621 keys).
706 If the keypad can be set to transmit or not transmit,
707 give these codes as \fBsmkx\fR and \fBrmkx\fR.
708 Otherwise the keypad is assumed to always transmit.
709 The codes sent by the left arrow, right arrow, up arrow, down arrow,
710 and home keys can be given as \fBkcub1, kcuf1, kcuu1, kcud1,
711 \fRand\fB khome\fR respectively.
712 If there are function keys such as f0, f1, ..., f10, the codes they send
713 can be given as \fBkf0, kf1, ..., kf10\fR.
714 If these keys have labels other than the default f0 through f10, the labels
715 can be given as \fBlf0, lf1, ..., lf10\fR.
716 The codes transmitted by certain other special keys can be given:
717 .B kll
718 (home down),
719 .B kbs
720 (backspace),
721 .B ktbc
722 (clear all tabs),
723 .B kctab
724 (clear the tab stop in this column),
725 .B kclr
726 (clear screen or erase key),
727 .B kdch1
728 (delete character),
729 .B kdl1
730 (delete line),
731 .B krmir
732 (exit insert mode),
733 .B kel
734 (clear to end of line),
735 .B ked
736 (clear to end of screen),
737 .B kich1
738 (insert character or enter insert mode),
739 .B kil1
740 (insert line),
741 .B knp
742 (next page),
743 .B kpp
744 (previous page),
745 .B kind
746 (scroll forward/down),
747 .B kri
748 (scroll backward/up),
749 .B khts
750 (set a tab stop in this column).
751 In addition, if the keypad has a 3 by 3 array of keys including the four
752 arrow keys, the other five keys can be given as
753 .BR ka1 ,
754 .BR ka3 ,
755 .BR kb2 ,
756 .BR kc1 ,
757 and
758 .BR kc3 .
759 These keys are useful when the effects of a 3 by 3 directional pad are needed.
760 .PP
761 .SS Tabs and Initialization
762 .PP
763 If the terminal has hardware tabs, the command to advance to the next
764 tab stop can be given as
765 .B ht
766 (usually control I).
767 A ``back-tab'' command which moves leftward to the next tab stop can
768 be given as
769 .BR cbt .
770 By convention, if the teletype modes indicate that tabs are being
771 expanded by the computer rather than being sent to the terminal,
772 programs should not use
773 .B ht
774 or
775 .B cbt
776 even if they are present, since the user may not have the tab stops
777 properly set.
778 If the terminal has hardware tabs which are initially set every
779 .I n
780 spaces when the terminal is powered up,
781 the numeric parameter
782 .B it
783 is given, showing the number of spaces the tabs are set to.
784 This is normally used by the
785 .IR tset
786 command to determine whether to set the mode for hardware tab expansion,
787 and whether to set the tab stops.
788 If the terminal has tab stops that can be saved in non-volatile memory,
789 the terminfo description can assume that they are properly set.
790 .PP
791 Other capabilities
792 include
793 .BR is1 ,
794 .BR is2 ,
795 and
796 .BR is3 ,
797 initialization strings for the terminal,
798 .BR iprog ,
799 the path name of a program to be run to initialize the terminal,
800 and \fBif\fR, the name of a file containing long initialization strings.
801 These strings are expected to set the terminal into modes consistent
802 with the rest of the terminfo description.
803 They are normally sent to the terminal, by the
804 .IR tset
805 program, each time the user logs in.
806 They will be printed in the following order:
807 .BR is1 ;
808 .BR is2 ;
809 setting tabs using
810 .B tbc
811 and
812 .BR hts ;
813 .BR if ;
814 running the program
815 .BR iprog ;
816 and finally
817 .BR is3 .
818 Most initialization is done with
819 .BR is2 .
820 Special terminal modes can be set up without duplicating strings
821 by putting the common sequences in
822 .B is2
823 and special cases in
824 .B is1
825 and
826 .BR is3 .
827 A pair of sequences that does a harder reset from a totally unknown state
828 can be analogously given as
829 .BR rs1 ,
830 .BR rs2 ,
831 .BR rf ,
832 and
833 .BR rs3 ,
834 analogous to
835 .B is2
836 and
837 .BR if .
838 These strings are output by the
839 .IR reset
840 program, which is used when the terminal gets into a wedged state.
841 Commands are normally placed in
842 .B rs2
843 and
844 .B rf
845 only if they produce annoying effects on the screen and are not
846 necessary when logging in.
847 For example, the command to set the vt100 into 80-column mode would
848 normally be part of
849 .BR is2 ,
850 but it causes an annoying glitch of the screen and is not normally
851 needed since the terminal is usually already in 80 column mode.
852 .PP
853 If there are commands to set and clear tab stops, they can be given as
854 .B tbc
855 (clear all tab stops)
856 and
857 .B hts
858 (set a tab stop in the current column of every row).
859 If a more complex sequence is needed to set the tabs than can be
860 described by this, the sequence can be placed in
861 .B is2
862 or
863 .BR if .
864 .SS Delays and Padding
865 .PP
866 Many older and slower terminals don't support either XON/XOFF or DTR
867 handshaking, including hard copy terminals and some very archaic CRTs
868 (including, for example, DEC VT100s).  These may require padding characters
869 after certain cursor motions and screen changes.
870 .PP
871 If the terminal uses xon/xoff handshaking for flow control (that is,
872 it automatically emits ^S back to the host when its input buffers are
873 close to full), set
874 .BR xon .
875 This capability suppresses the emission of padding.  You can also set it
876 for memory-mapped console devices effectively that don't have a speed limit.
877 Padding information should still be included so that routines can
878 make better decisions about relative costs, but actual pad characters will
879 not be transmitted.
880 .PP
881 If \fBpb\fR (padding baud rate) is given, padding is suppressed at baud rates
882 below the value of \fBpb\fR.  If the entry has no padding baud rate, then
883 whether padding is emitted or not is completely controlled by \fBxon\fR.
884 .PP
885 If the terminal requires other than a null (zero) character as a pad,
886 then this can be given as \fBpad\fR.
887 Only the first character of the
888 .B pad
889 string is used.
890 .PP
891 .SS Status Lines
892 Some terminals have an extra `status line' which is not normally used by
893 software (and thus not counted in the terminal's \fBlines\fR capability).
894 .PP
895 The simplest case is a status line which is cursor-addressable but not
896 part of the main scrolling region on the screen; the Heathkit H19 has
897 a status line of this kind, as would a 24-line VT100 with a 23-line
898 scrolling region set up on initialization.  This situation is indicated
899 by the \fBhs\fR capability.
900 .PP
901 Some terminals with status lines need special sequences to access the
902 status line.  These may be expressed as a string with single parameter
903 \fBtsl\fR which takes the cursor to a given zero-origin column on the
904 status line. The capability \fBfsl\fR must return to the main-screen
905 cursor positions before the last \fBtsl\fR.  You may need to embed the
906 string values of \fBsc\fR (save cursor) and \fBrc\fR (restore cursor)
907 in \fBtsl\fR and \fBfsl\fR to accomplish this.
908 .PP
909 The status line is normally assumed to be the same width as the width
910 of the terminal.  If this is untrue, you can specify it with the numeric
911 capability \fBwsl\fR.
912 .PP
913 A command to erase or blank the status line may be specified as \fBdsl\fR.
914 .PP
915 The boolean capability \fBeslok\fR specifies that escape sequences, tabs,
916 etc. work ordinarily in the status line.
917 .PP
918 The \fBncurses\fR implementation does not yet use any of these capabilities.
919 They are documented here in case they ever become important.
920 .PP
921 .SS Line Graphics
922 .PP
923 Many terminals have alternate character sets useful for forms-drawing.
924 Terminfo and \fBcurses\fR build in support for the drawing characters
925 supported by the VT100, with some characters from the AT&T 4410v1 added.
926 This alternate character set may be specified by the \fBacsc\fR capability.
927 .PP
928 .TS H
929 center expand;
930 c l l c
931 c l l c
932 lw25 lw6 lw2 lw20.
933 .\".TH
934 \fBGlyph        ACS     Ascii   VT100
935 Name    Name    Default Name\fR
936 upper left corner       ACS_ULCORNER    +       l
937 lower left corner       ACS_LLCORNER    +       m
938 upper right corner      ACS_URCORNER    +       k
939 lower right corner      ACS_LRCORNER    +       j
940 tee pointing right      ACS_LTEE        +       t
941 tee pointing left       ACS_RTEE        +       u
942 tee pointing up         ACS_BTEE        +       v
943 tee pointing down       ACS_TTEE        +       w
944 horizontal line         ACS_HLINE       -       q
945 vertical line           ACS_VLINE       |       x
946 large plus or crossover ACS_PLUS        +       n
947 scan line 1             ACS_S1          ~       o       
948 scan line 9             ACS_S9          \&_     s       
949 diamond                 ACS_DIAMOND     +       `
950 checker board (stipple) ACS_CKBOARD     :       a
951 degree symbol           ACS_DEGREE      \e      f
952 plus/minus              ACS_PLMINUS     #       g
953 bullet                  ACS_BULLET      o       ~
954 arrow pointing left     ACS_LARROW      <       ,
955 arrow pointing right    ACS_RARROW      >       +
956 arrow pointing down     ACS_DARROW      v       .
957 arrow pointing up       ACS_UARROW      ^       -
958 board of squares        ACS_BOARD       #       h
959 lantern symbol          ACS_LANTERN     #       I
960 solid square block      ACS_BLOCK       #       0
961 .TE
962 .PP
963 The best way to define a new device's graphics set is to add a column
964 to a copy of this table for your terminal, giving the character which
965 (when emitted between \fBsmacs\fR/\fBrmacs\fR switches) will be rendered
966 as the corresponding graphic.  Then read off the VT100/your terminal
967 character pairs right to left in sequence; these become the ACSC string.
968 .PP
969 .SS Color Handling
970 .PP
971 Most color terminals are either `Tektronix-like' or `HP-like'.  Tektronix-like
972 terminals have a predefined set of N colors (where N usually 8), and can set
973 character-cell foreground and background characters independently, mixing them
974 into N * N color-pairs.  On HP-like terminals, the use must set each color
975 pair up separately (foreground and background are not independently settable).
976 Up to M color-pairs may be set up from 2*M different colors.  ANSI-compatible
977 terminals are Tektronix-like.
978 .PP
979 Some basic color capabilities are independent of the color method.  The numeric
980 capabilities \fBcolors\fR and \fBpairs\fR specify the maximum numbers of colors
981 and color-pairs that can be displayed simultaneously.  The \fBop\fR (original
982 pair) string resets foreground and background colors to their default values
983 for the terminal.  The \fBoc\fR string resets all colors or color-pairs to
984 their default values for the terminal.  Some terminals (including many PC
985 terminal emulators) erase screen areas with the current background color rather
986 than the power-up default background; these should have the boolean capability
987 \fBbce\fR.
988 .PP
989 To change the current foreground or background color on a Tektronix-type
990 terminal, use \fBsetaf\fR (set ANSI foreground) and \fBsetab\fR (set ANSI
991 background) or \fBsetf\fR (set foreground) and \fBsetb\fR (set background).
992 These take one parameter, the color number.  The SVr4 documentation describes 
993 only \fBsetaf\fR/\fBsetab\fR; the XPG4 draft says that "If the terminal
994 supports ANSI escape sequences to set background and foreground, they should
995 be coded as \fBsetaf\fR and \fBsetab\fR, respectively.  If the terminal
996 supports other escape sequences to set background and foreground, they should
997 be coded as \fBsetf\fR and \fBsetb\fR, respectively.  The \fIvidputs()\fR
998 function and the refresh functions use \fBsetaf\fR and \fBsetab\fR if they are
999 defined."
1000 .PP
1001 The \fBsetaf\fR/\fBsetab\fR and \fBsetf\fR/\fBsetb\fR capabilities take a
1002 single numeric argument each.  Argument values 0-7 are portably defined as
1003 follows (the middle column is the symbolic #define available in the header for
1004 the \fBcurses\fR or \fBncurses\fR libraries).  The terminal hardware is free to
1005 map these as it likes, but the RGB values indicate normal locations in color
1006 space.
1007 .PP
1008 .TS H
1009 center;
1010 l c c c
1011 l l n l.
1012 \fBColor        #define         Value   RGB\fR
1013 black   \fBCOLOR_BLACK\fR       0       0, 0, 0
1014 red     \fBCOLOR_RED\ \fR       1       max,0,0
1015 green   \fBCOLOR_GREEN\fR       2       0,max,0
1016 yellow  \fBCOLOR_YELLOW\fR      3       max,max,0
1017 blue    \fBCOLOR_BLUE\fR        4       0,0,max
1018 magenta \fBCOLOR_MAGENTA\fR     5       max,0,max
1019 cyan    \fBCOLOR_CYAN\fR        6       0,max,max
1020 white   \fBCOLOR_WHITE\fR       7       max,max,max
1021 .TE
1022 .PP
1023 On an HP-like terminal, use \fBscp\fR with a color-pair number parameter to set
1024 which color pair is current.
1025 .PP
1026 On a Tektronix-like terminal, the capability \fBccc\fR may be present to
1027 indicate that colors can be modified.  If so, the \fBinitc\fR capability will
1028 take a color number (0 to \fBcolors\fR - 1)and three more parameters which
1029 describe the color.  These three parameters default to being interpreted as RGB
1030 (Red, Green, Blue) values.  If the boolean capability \fBhls\fR is present,
1031 they are instead as HLS (Hue, Lightness, Saturation) indices.  The ranges are
1032 terminal-dependent.
1033 .PP
1034 On an HP-like terminal, \fBinitp\fR may give a capability for changing a
1035 color-pair value.  It will take seven parameters; a color-pair number (0 to
1036 \fBmax_pairs\fR - 1), and two triples describing first background and then
1037 foreground colors.  These parameters must be (Red, Green, Blue) or 
1038 (Hue, Lightness, Saturation) depending on \fBhls\fR.
1039 .PP
1040 On some color terminals, colors collide with highlights.  You can register
1041 these collisions with the \fBncv\fR capability.  This is a bit-mask of
1042 attributes not to be used when colors are enabled.  The correspondence with the
1043 attributes understood by \fBcurses\fR is as follows:
1044 .PP
1045 .TS
1046 center;
1047 l c c
1048 lw25 lw2 lw10.
1049 \fBAttribute    Bit     Decimal\fR
1050 A_STANDOUT      0       1
1051 A_UNDERLINE     1       2
1052 A_REVERSE       2       4
1053 A_BLINK         3       8
1054 A_DIM           4       16
1055 A_BOLD          5       32
1056 A_INVIS         6       64
1057 A_PROTECT       7       128
1058 A_ALTCHARSET    8       256
1059 .TE
1060 .PP
1061 For example, on many IBM PC consoles, the underline attribute collides with the
1062 foreground color blue and is not available in color mode.  These should have
1063 an \fBncv\fR capability of 2.
1064 .PP
1065 .SS Miscellaneous
1066 .PP
1067 If the terminal can move up or down half a line,
1068 this can be indicated with
1069 .B hu
1070 (half-line up)
1071 and
1072 .B hd
1073 (half-line down).
1074 This is primarily useful for superscripts and subscripts on hard-copy terminals.
1075 If a hard-copy terminal can eject to the next page (form feed), give this as
1076 .B ff
1077 (usually control L).
1078 .PP
1079 If there is a command to repeat a given character a given number of
1080 times (to save time transmitting a large number of identical characters)
1081 this can be indicated with the parameterized string
1082 .BR rep .
1083 The first parameter is the character to be repeated and the second
1084 is the number of times to repeat it.
1085 Thus, tparm(repeat_char, 'x', 10) is the same as `xxxxxxxxxx'.
1086 .PP
1087 If the terminal has a settable command character, such as the \s-1TEKTRONIX\s+1 4025,
1088 this can be indicated with
1089 .BR cmdch .
1090 A prototype command character is chosen which is used in all capabilities.
1091 This character is given in the
1092 .B cmdch
1093 capability to identify it.
1094 The following convention is supported on some UNIX systems:
1095 The environment is to be searched for a
1096 .B CC
1097 variable, and if found, all
1098 occurrences of the prototype character are replaced with the character
1099 in the environment variable.
1100 .PP
1101 Terminal descriptions that do not represent a specific kind of known
1102 terminal, such as
1103 .IR switch ,
1104 .IR dialup ,
1105 .IR patch ,
1106 and
1107 .IR network ,
1108 should include the
1109 .B gn
1110 (generic) capability so that programs can complain that they do not know
1111 how to talk to the terminal.
1112 (This capability does not apply to
1113 .I virtual
1114 terminal descriptions for which the escape sequences are known.)
1115 .PP
1116 If the terminal has a ``meta key'' which acts as a shift key,
1117 setting the 8th bit of any character transmitted, this fact can
1118 be indicated with
1119 .BR km .
1120 Otherwise, software will assume that the 8th bit is parity and it
1121 will usually be cleared.
1122 If strings exist to turn this ``meta mode'' on and off, they
1123 can be given as
1124 .B smm
1125 and
1126 .BR rmm .
1127 .PP
1128 If the terminal has more lines of memory than will fit on the screen
1129 at once, the number of lines of memory can be indicated with
1130 .BR lm .
1131 A value of
1132 .BR lm #0
1133 indicates that the number of lines is not fixed,
1134 but that there is still more memory than fits on the screen.
1135 .PP
1136 If the terminal is one of those supported by the \s-1UNIX\s+1 virtual
1137 terminal protocol, the terminal number can be given as
1138 .BR vt .
1139 .PP
1140 Media copy
1141 strings which control an auxiliary printer connected to the terminal
1142 can be given as
1143 .BR mc0 :
1144 print the contents of the screen,
1145 .BR mc4 :
1146 turn off the printer, and
1147 .BR mc5 :
1148 turn on the printer.
1149 When the printer is on, all text sent to the terminal will be sent
1150 to the printer.
1151 It is undefined whether the text is also displayed on the terminal screen
1152 when the printer is on.
1153 A variation
1154 .B mc5p
1155 takes one parameter, and leaves the printer on for as many characters
1156 as the value of the parameter, then turns the printer off.
1157 The parameter should not exceed 255.
1158 All text, including
1159 .BR mc4 ,
1160 is transparently passed to the printer while an
1161 .B mc5p
1162 is in effect.
1163 .PP
1164 Strings to program function keys can be given as
1165 .BR pfkey ,
1166 .BR pfloc ,
1167 and
1168 .BR pfx .
1169 Each of these strings takes two parameters: the function key number to
1170 program (from 0 to 10) and the string to program it with.
1171 Function key numbers out of this range may program undefined keys in
1172 a terminal dependent manner.
1173 The difference between the capabilities is that
1174 .B pfkey
1175 causes pressing the given key to be the same as the user typing the
1176 given string;
1177 .B pfloc
1178 causes the string to be executed by the terminal in local; and
1179 .B pfx
1180 causes the string to be transmitted to the computer.
1181 .PP
1182 .SS Glitches and Braindamage
1183 .PP
1184 Hazeltine terminals, which do not allow `~' characters to be displayed should
1185 indicate \fBhz\fR.
1186 .PP
1187 Terminals which ignore a line-feed immediately after an \fBam\fR wrap,
1188 such as the Concept and vt100,
1189 should indicate \fBxenl\fR.
1190 .PP
1191 If
1192 .B el
1193 is required to get rid of standout
1194 (instead of merely writing normal text on top of it),
1195 \fBxhp\fP should be given.
1196 .PP
1197 Teleray terminals, where tabs turn all characters moved over to blanks,
1198 should indicate \fBxt\fR (destructive tabs).
1199 Note: the variable indicating this is now `dest_tabs_magic_smso'; in
1200 older versions, it was teleray_glitch.
1201 This glitch is also taken to mean that it is not possible to position
1202 the cursor on top of a ``magic cookie'',
1203 that to erase standout mode it is instead necessary to use
1204 delete and insert line.  The ncurses implementation ignores this glitch.
1205 .PP
1206 The Beehive Superbee, which is unable to correctly transmit the escape
1207 or control C characters, has
1208 .BR xsb ,
1209 indicating that the f1 key is used for escape and f2 for control C.
1210 (Only certain Superbees have this problem, depending on the ROM.)
1211 Note that in older terminfo versions, this capability was called
1212 `beehive_glitch'; it is now `no_esc_ctl_c'.
1213 .PP
1214 Other specific terminal problems may be corrected by adding more
1215 capabilities of the form \fBx\fIx\fR.
1216 .PP
1217 .SS Similar Terminals
1218 .PP
1219 If there are two very similar terminals,
1220 one can be defined as being just like the other with certain exceptions.
1221 The string capability \fBuse\fR can be given
1222 with the name of the similar terminal.
1223 The capabilities given before
1224 .B use
1225 override those in the terminal type invoked by
1226 .BR use .
1227 A capability can be canceled by placing \fBxx@\fR to the left of the
1228 capability definition, where xx is the capability.
1229 For example, the entry
1230 .PP
1231         2621-nl, smkx@, rmkx@, use=2621,
1232 .PP
1233 defines a 2621-nl that does not have the \fBsmkx\fR or \fBrmkx\fR capabilities,
1234 and hence does not turn on the function key labels when in visual mode.
1235 This is useful for different modes for a terminal, or for different
1236 user preferences.
1237 .PP
1238 .SS Pitfalls of Long Entries
1239 .PP
1240 Long terminfo entries are unlikely to be a problem; to date, no entry has even
1241 approached terminfo's 4K string-table maximum.  Unfortunately, the termcap
1242 translations are much more strictly limited (to 1K), thus termcap translations
1243 of long terminfo entries can cause problems.
1244 .PP
1245 The man pages for 4.3BSD and older versions of tgetent() instruct the user to
1246 allocate a 1K buffer for the termcap entry.  The entry gets null-terminated by
1247 the termcap library, so that makes the maximum safe length for a termcap entry
1248 1k-1 (1023) bytes.  Depending on what the application and the termcap library
1249 being used does, and where in the termcap file the terminal type that tgetent()
1250 is searching for is, several bad things can happen.
1251 .PP
1252 Some termcap libraries print a warning message or exit if they find an
1253 entry that's longer than 1023 bytes; others don't; others truncate the
1254 entries to 1023 bytes.  Some application programs allocate more than
1255 the recommended 1K for the termcap entry; others don't.
1256 .PP
1257 Each termcap entry has two important sizes associated with it: before
1258 "tc" expansion, and after "tc" expansion.  "tc" is the capability that
1259 tacks on another termcap entry to the end of the current one, to add
1260 on its capabilities.  If a termcap entry doesn't use the "tc"
1261 capability, then of course the two lengths are the same.
1262 .PP
1263 The "before tc expansion" length is the most important one, because it
1264 affects more than just users of that particular terminal.  This is the
1265 length of the entry as it exists in /etc/termcap, minus the
1266 backslash-newline pairs, which tgetent() strips out while reading it.
1267 Some termcap libraries strip off the final newline, too (GNU termcap does not).
1268 Now suppose:
1269 .TP 5
1270 *
1271 a termcap entry before expansion is more than 1023 bytes long,
1272 .TP 5
1273 *
1274 and the application has only allocated a 1k buffer,
1275 .TP 5
1276 *
1277 and the termcap library (like the one in BSD/OS 1.1 and GNU) reads
1278 the whole entry into the buffer, no matter what its length, to see
1279 if it's the entry it wants,
1280 .TP 5
1281 *
1282 and tgetent() is searching for a terminal type that either is the
1283 long entry, appears in the termcap file after the long entry, or
1284 doesn't appear in the file at all (so that tgetent() has to search
1285 the whole termcap file).
1286 .PP
1287 Then tgetent() will overwrite memory, perhaps its stack, and probably core dump
1288 the program.  Programs like telnet are particularly vulnerable; modern telnets
1289 pass along values like the terminal type automatically.  The results are almost
1290 as undesirable with a termcap library, like SunOS 4.1.3 and Ultrix 4.4, that
1291 prints warning messages when it reads an overly long termcap entry.  If a
1292 termcap library truncates long entries, like OSF/1 3.0, it is immune to dying
1293 here but will return incorrect data for the terminal.
1294 .PP
1295 The "after tc expansion" length will have a similar effect to the
1296 above, but only for people who actually set TERM to that terminal
1297 type, since tgetent() only does "tc" expansion once it's found the
1298 terminal type it was looking for, not while searching.
1299 .PP
1300 In summary, a termcap entry that is longer than 1023 bytes can cause,
1301 on various combinations of termcap libraries and applications, a core
1302 dump, warnings, or incorrect operation.  If it's too long even before
1303 "tc" expansion, it will have this effect even for users of some other
1304 terminal types and users whose TERM variable does not have a termcap
1305 entry.
1306 .PP
1307 When in -C (translate to termcap) mode, the \fBncurses\fR implementation of
1308 \fBtic\fR(1) issues warning messages when the pre-tc length of a termcap
1309 translation is too long.  The -c (check) option also checks resolved (after tc
1310 expansion) lengths.
1311 .SS Binary Compatibility
1312 It is not wise to count on portability of binary terminfo entries between
1313 commercial UNIX versions.  The problem is that there are at least two versions
1314 of terminfo (under HP-UX and AIX) which diverged from System V terminfo after
1315 SVr1, and have added extension capabilities to the string table that (in the
1316 binary format) collide with System V and XSI Curses extensions.
1318 The %x operator in parameterized strings is unique to the ncurses implementation
1319 of \fBtparm\fR (it is required in order to support an unfortunate choice of
1320 \fBinitc\fR format on the Linux console).
1321 .PP
1322 Some SVr4 \fBcurses\fR implementations, and all previous to SVr4, don't
1323 interpret the %A and %O operators in parameter strings.
1324 .PP
1325 SVr4/XPG4 do not specify whether \fBmsgr\fR licenses movement while in
1326 an alternate-character-set mode (such modes may, among other things, map
1327 CR and NL to characters that don't trigger local motions).
1328 The \fBncurses\fR implementation ignores \fBmsgr\fR in \fBALTCHARSET\fR
1329 mode.  This raises the possibility that an XPG4 
1330 implementation making the opposite interpretation may need terminfo
1331 entries made for \fBncurses\fR to have \fBmsgr\fR turned off.
1332 .PP
1333 The \fBncurses\fR library handles insert-character and insert-character modes
1334 in a slightly non-standard way in order to get better update efficiency.  See
1335 the \fBInsert/Delete Character\fR subsection above.
1336 .PP
1337 The parameter substitutions for \fBset_clock\fR and \fBdisplay_clock\fR are
1338 not documented in SVr4 or the XSI Curses standard.  They are deduced from the
1339 documentation for the AT&T 505 terminal.
1340 .PP
1341 Be careful assigning the \fBkmous\fR capability.  The \fBncurses\fR wants to
1342 interpret it as \fBKEY_MOUSE\fR, for use by terminals and emulators like xterm
1343 that can return mouse-tracking information in the keyboard-input stream.
1344 .PP
1345 Different commercial ports of terminfo and curses support different subsets of
1346 the XSI Curses standard and (in some cases) different extension sets.  Here
1347 is a summary, accurate as of October 1995:
1348 .PP
1349 \fBSVR4, Solaris, ncurses\fR --
1350 These support all SVr4 capabilities.
1351 .PP
1352 \fBSGI\fR --
1353 Supports the SVr4 set, adds one undocumented extended string
1354 capability (\fBset_pglen\fR).
1355 .PP
1356 \fBSVr1, Ultrix\fR --
1357 These support a restricted subset of terminfo capabilities.  The booleans
1358 end with \fBxon_xoff\fR; the numerics with \fBwidth_status_line\fR; and the 
1359 strings with \fBprtr_non\fR.
1360 .PP
1361 \fBHP/UX\fR --
1362 Supports the SVr1 subset, plus the SVr[234] numerics \fBnum_labels\fR,
1363 \fBlabel_height\fR, \fBlabel_width\fR, plus function keys 11 through 63, plus
1364 \fBplab_norm\fR, \fBlabel_on\fR, and \fBlabel_off\fR, plus some incompatible
1365 extensions in the string table.
1366 .PP
1367 \fBAIX\fR --
1368 Supports the SVr1 subset, plus function keys 11 through 63, plus a number
1369 of incompatible string table extensions.
1370 .PP
1371 \fBOSF\fR --
1372 Supports both the SVr4 set and the AIX extensions.
1373 .SH FILES
1374 .TP 25
1375 \*d/?/*
1376 files containing terminal descriptions
1377 .SH "SEE ALSO"
1378 \fBtic\fR(1M), \fBcurses\fR(3X), \fBprintf\fR(3S), \fBterm\fR(\*n).
1380 Zeyd M. Ben-Halim, Eric S. Raymond.  Descends from the original pcurses
1381 by Pavel Curtis.
1382 .\"#
1383 .\"# The following sets edit modes for GNU EMACS
1384 .\"# Local Variables:
1385 .\"# mode:nroff
1386 .\"# fill-column:79
1387 .\"# End: