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