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