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