1 This is Info file ../info/termcap.info, produced by Makeinfo version
2 1.68 from the input file termcap.texi.
5 * Termcap: (termcap). Termcap library of the GNU system.
8 This file documents the termcap library of the GNU system.
10 Copyright (C) 1988 Free Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of this
13 manual provided the copyright notice and this permission notice are
14 preserved on all copies.
16 Permission is granted to copy and distribute modified versions of
17 this manual under the conditions for verbatim copying, provided that
18 the entire resulting derived work is distributed under the terms of a
19 permission notice identical to this one.
21 Permission is granted to copy and distribute translations of this
22 manual into another language, under the above conditions for modified
23 versions, except that this permission notice may be stated in a
24 translation approved by the Foundation.
27 File: termcap.info, Node: Capabilities, Next: Summary, Prev: Data Base, Up: Top
29 Definitions of the Terminal Capabilities
30 ****************************************
32 This section is divided into many subsections, each for one aspect of
33 use of display terminals. For writing a display program, you usually
34 need only check the subsections for the operations you want to use.
35 For writing a terminal description, you must read each subsection and
36 fill in the capabilities described there.
38 String capabilities that are display commands may require numeric
39 parameters (*note Parameters::.). Most such capabilities do not use
40 parameters. When a capability requires parameters, this is explicitly
41 stated at the beginning of its definition. In simple cases, the first
42 or second sentence of the definition mentions all the parameters, in
43 the order they should be given, using a name in upper case for each
44 one. For example, the `rp' capability is a command that requires two
45 parameters; its definition begins as follows:
47 String of commands to output a graphic character C, repeated N
50 In complex cases or when there are many parameters, they are
53 When a capability is described as obsolete, this means that programs
54 should not be written to look for it, but terminal descriptions should
55 still be written to provide it.
57 When a capability is described as very obsolete, this means that it
58 should be omitted from terminal descriptions as well.
62 * Basic:: Basic characteristics.
63 * Screen Size:: Screen size, and what happens when it changes.
64 * Cursor Motion:: Various ways to move the cursor.
65 * Scrolling:: Pushing text up and down on the screen.
66 * Wrapping:: What happens if you write a character in the last column.
67 * Windows:: Limiting the part of the window that output affects.
68 * Clearing:: Erasing one or many lines.
69 * Insdel Line:: Making new blank lines in mid-screen; deleting lines.
70 * Insdel Char:: Inserting and deleting characters within a line.
71 * Standout:: Highlighting some of the text.
72 * Underlining:: Underlining some of the text.
73 * Cursor Visibility:: Making the cursor more or less easy to spot.
74 * Bell:: Attracts user's attention; not localized on the screen.
75 * Keypad:: Recognizing when function keys or arrows are typed.
76 * Meta Key:: <META> acts like an extra shift key.
77 * Initialization:: Commands used to initialize or reset the terminal.
78 * Pad Specs:: Info for the kernel on how much padding is needed.
79 * Status Line:: A status line displays "background" information.
80 * Half-Line:: Moving by half-lines, for superscripts and subscripts.
81 * Printer:: Controlling auxiliary printers of display terminals.
84 File: termcap.info, Node: Basic, Next: Screen Size, Prev: Capabilities, Up: Capabilities
89 This section documents the capabilities that describe the basic and
90 nature of the terminal, and also those that are relevant to the output
91 of graphic characters.
94 Flag whose presence means that the terminal can overstrike. This
95 means that outputting a graphic character does not erase whatever
96 was present in the same character position before. The terminals
97 that can overstrike include printing terminals, storage tubes (all
98 obsolete nowadays), and many bit-map displays.
101 Flag whose presence means that outputting a space can erase an
102 overstrike. If this is not present and overstriking is supported,
103 output of a space has no effect except to move the cursor.
106 Flag whose presence means that this terminal type is a generic type
107 which does not really describe any particular terminal. Generic
108 types are intended for use as the default type assigned when the
109 user connects to the system, with the intention that the user
110 should specify what type he really has. One example of a generic
111 type is the type `network'.
113 Since the generic type cannot say how to do anything interesting
114 with the terminal, termcap-using programs will always find that the
115 terminal is too weak to be supported if the user has failed to
116 specify a real terminal type in place of the generic one. The
117 `gn' flag directs these programs to use a different error message:
118 "You have not specified your real terminal type", rather than
119 "Your terminal is not powerful enough to be used".
122 Flag whose presence means this is a hardcopy terminal.
125 String of commands to output a graphic character C, repeated N
126 times. The first parameter value is the ASCII code for the desired
127 character, and the second parameter is the number of times to
128 repeat the character. Often this command requires padding
129 proportional to the number of times the character is repeated.
130 This effect can be had by using parameter arithmetic with
131 `%'-sequences to compute the amount of padding, then generating
132 the result as a number at the front of the string so that `tputs'
133 will treat it as padding.
136 Flag whose presence means that the ASCII character `~' cannot be
137 output on this terminal because it is used for display commands.
139 Programs handle this flag by checking all text to be output and
140 replacing each `~' with some other character(s). If this is not
141 done, the screen will be thoroughly garbled.
143 The old Hazeltine terminals that required such treatment are
144 probably very rare today, so you might as well not bother to
148 String whose presence means the terminal has a settable command
149 character. The value of the string is the default command
150 character (which is usually <ESC>).
152 All the strings of commands in the terminal description should be
153 written to use the default command character. If you are writing
154 an application program that changes the command character, use the
155 `CC' capability to figure out how to translate all the display
156 commands to work with the new command character.
158 Most programs have no reason to look at the `CC' capability.
161 Flag whose presence identifies Superbee terminals which are unable
162 to transmit the characters <ESC> and `Control-C'. Programs which
163 support this flag are supposed to check the input for the code
164 sequences sent by the <F1> and <F2> keys, and pretend that <ESC>
165 or `Control-C' (respectively) had been read. But this flag is
166 obsolete, and not worth supporting.
169 File: termcap.info, Node: Screen Size, Next: Cursor Motion, Prev: Basic, Up: Capabilities
174 A terminal description has two capabilities, `co' and `li', that
175 describe the screen size in columns and lines. But there is more to
176 the question of screen size than this.
178 On some operating systems the "screen" is really a window and the
179 effective width can vary. On some of these systems, `tgetnum' uses the
180 actual width of the window to decide what value to return for the `co'
181 capability, overriding what is actually written in the terminal
182 description. On other systems, it is up to the application program to
183 check the actual window width using a system call. For example, on BSD
184 4.3 systems, the system call `ioctl' with code `TIOCGWINSZ' will tell
185 you the current screen size.
187 On all window systems, termcap is powerless to advise the application
188 program if the user resizes the window. Application programs must deal
189 with this possibility in a system-dependent fashion. On some systems
190 the C shell handles part of the problem by detecting changes in window
191 size and setting the `TERMCAP' environment variable appropriately.
192 This takes care of application programs that are started subsequently.
193 It does not help application programs already running.
195 On some systems, including BSD 4.3, all programs using a terminal get
196 a signal named `SIGWINCH' whenever the screen size changes. Programs
197 that use termcap should handle this signal by using `ioctl TIOCGWINSZ'
198 to learn the new screen size.
201 Numeric value, the width of the screen in character positions.
202 Even hardcopy terminals normally have a `co' capability.
205 Numeric value, the height of the screen in lines.
208 File: termcap.info, Node: Cursor Motion, Next: Wrapping, Prev: Screen Size, Up: Capabilities
213 Termcap assumes that the terminal has a "cursor", a spot on the
214 screen where a visible mark is displayed, and that most display
215 commands take effect at the position of the cursor. It follows that
216 moving the cursor to a specified location is very important.
218 There are many terminal capabilities for different cursor motion
219 operations. A terminal description should define as many as possible,
220 but most programs do not need to use most of them. One capability,
221 `cm', moves the cursor to an arbitrary place on the screen; this by
222 itself is sufficient for any application as long as there is no need to
223 support hardcopy terminals or certain old, weak displays that have only
224 relative motion commands. Use of other cursor motion capabilities is an
225 optimization, enabling the program to output fewer characters in some
228 If you plan to use the relative cursor motion commands in an
229 application program, you must know what the starting cursor position
230 is. To do this, you must keep track of the cursor position and update
231 the records each time anything is output to the terminal, including
232 graphic characters. In addition, it is necessary to know whether the
233 terminal wraps after writing in the rightmost column. *Note Wrapping::.
235 One other motion capability needs special mention: `nw' moves the
236 cursor to the beginning of the following line, perhaps clearing all the
237 starting line after the cursor, or perhaps not clearing at all. This
238 capability is a least common denominator that is probably supported
239 even by terminals that cannot do most other things such as `cm' or `do'.
240 Even hardcopy terminals can support `nw'.
243 String of commands to position the cursor at line L, column C.
244 Both parameters are origin-zero, and are defined relative to the
245 screen, not relative to display memory.
247 All display terminals except a few very obsolete ones support `cm',
248 so it is acceptable for an application program to refuse to
249 operate on terminals lacking `cm'.
252 String of commands to move the cursor to the upper left corner of
253 the screen (this position is called the "home position"). In
254 terminals where the upper left corner of the screen is not the
255 same as the beginning of display memory, this command must go to
256 the upper left corner of the screen, not the beginning of display
259 Every display terminal supports this capability, and many
260 application programs refuse to operate if the `ho' capability is
264 String of commands to move the cursor to the lower left corner of
265 the screen. On some terminals, moving up from home position does
266 this, but programs should never assume that will work. Just
267 output the `ll' string (if it is provided); if moving to home
268 position and then moving up is the best way to get there, the `ll'
269 command will do that.
272 String of commands to move the cursor to the beginning of the line
273 it is on. If this capability is not specified, many programs
274 assume they can use the ASCII carriage return character for this.
277 String of commands to move the cursor left one column. Unless the
278 `bw' flag capability is specified, the effect is undefined if the
279 cursor is at the left margin; do not use this command there. If
280 `bw' is present, this command may be used at the left margin, and
281 it wraps the cursor to the last column of the preceding line.
284 String of commands to move the cursor right one column. The
285 effect is undefined if the cursor is at the right margin; do not
286 use this command there, not even if `am' is present.
289 String of commands to move the cursor vertically up one line. The
290 effect of sending this string when on the top line is undefined;
291 programs should never use it that way.
294 String of commands to move the cursor vertically down one line.
295 The effect of sending this string when on the bottom line is
296 undefined; programs should never use it that way.
298 The original idea was that this string would not contain a newline
299 character and therefore could be used without disabling the
300 kernel's usual habit of converting of newline into a
301 carriage-return newline sequence. But many terminal descriptions
302 do use newline in the `do' string, so this is not possible; a
303 program which sends the `do' string must disable output conversion
304 in the kernel (*note Initialize::.).
307 Flag whose presence says that `le' may be used in column zero to
308 move to the last column of the preceding line. If this flag is
309 not present, `le' should not be used in column zero.
312 String of commands to move the cursor to start of next line,
313 possibly clearing rest of line (following the cursor) before
316 `DO', `UP', `LE', `RI'
317 Strings of commands to move the cursor N lines down vertically, up
318 vertically, or N columns left or right. Do not attempt to move
319 past any edge of the screen with these commands; the effect of
320 trying that is undefined. Only a few terminal descriptions provide
321 these commands, and most programs do not use them.
324 String of commands to position the cursor at line L, column C,
325 relative to display memory. Both parameters are origin-zero.
326 This capability is present only in terminals where there is a
327 difference between screen-relative and memory-relative addressing,
328 and not even in all such terminals.
331 String of commands to position the cursor at column C in the same
332 line it is on. This is a special case of `cm' in which the
333 vertical position is not changed. The `ch' capability is provided
334 only when it is faster to output than `cm' would be in this
335 special case. Programs should not assume most display terminals
339 String of commands to position the cursor at line L in the same
340 column. This is a special case of `cm' in which the horizontal
341 position is not changed. The `cv' capability is provided only
342 when it is faster to output than `cm' would be in this special
343 case. Programs should not assume most display terminals have `cv'.
346 String of commands to make the terminal save the current cursor
347 position. Only the last saved position can be used. If this
348 capability is present, `rc' should be provided also. Most
349 terminals have neither.
352 String of commands to make the terminal restore the last saved
353 cursor position. If this capability is present, `sc' should be
354 provided also. Most terminals have neither.
357 String of commands to advance to the next page, for a hardcopy
361 String of commands to move the cursor right to the next hardware
362 tab stop column. Missing if the terminal does not have any kind of
363 hardware tabs. Do not send this command if the kernel's terminal
364 modes say that the kernel is expanding tabs into spaces.
367 String of commands to move the cursor left to the previous hardware
368 tab stop column. Missing if the terminal has no such ability; many
369 terminals do not. Do not send this command if the kernel's
370 terminal modes say that the kernel is expanding tabs into spaces.
372 The following obsolete capabilities should be included in terminal
373 descriptions when appropriate, but should not be looked at by new
377 Flag whose presence means the terminal does not support the ASCII
378 carriage return character as `cr'. This flag is needed because
379 old programs assume, when the `cr' capability is missing, that
380 ASCII carriage return can be used for the purpose. We use `nc' to
381 tell the old programs that carriage return may not be used.
383 New programs should not assume any default for `cr', so they need
384 not look at `nc'. However, descriptions should contain `nc'
385 whenever they do not contain `cr'.
388 Flag whose presence means that the ASCII tab character may not be
389 used for cursor motion. This flag exists because old programs
390 assume, when the `ta' capability is missing, that ASCII tab can be
391 used for the purpose. We use `xt' to tell the old programs not to
394 New programs should not assume any default for `ta', so they need
395 not look at `xt' in connection with cursor motion. Note that `xt'
396 also has implications for standout mode (*note Standout::.). It
397 is obsolete in regard to cursor motion but not in regard to
400 In fact, `xt' means that the terminal is a Teleray 1061.
403 Very obsolete alternative name for the `le' capability.
406 Flag whose presence means that the ASCII character backspace may be
407 used to move the cursor left. Obsolete; look at `le' instead.
410 Obsolete capability which is a string that can either be used to
411 move the cursor down or to scroll. The same string must scroll
412 when used on the bottom line and move the cursor when used on any
413 other line. New programs should use `do' or `sf', and ignore `nl'.
415 If there is no `nl' capability, some old programs assume they can
416 use the newline character for this purpose. These programs follow
417 a bad practice, but because they exist, it is still desirable to
418 define the `nl' capability in a terminal description if the best
419 way to move down is *not* a newline.
422 File: termcap.info, Node: Wrapping, Next: Scrolling, Prev: Cursor Motion, Up: Capabilities
427 "Wrapping" means moving the cursor from the right margin to the left
428 margin of the following line. Some terminals wrap automatically when a
429 graphic character is output in the last column, while others do not.
430 Most application programs that use termcap need to know whether the
431 terminal wraps. There are two special flag capabilities to describe
432 what the terminal does when a graphic character is output in the last
436 Flag whose presence means that writing a character in the last
437 column causes the cursor to wrap to the beginning of the next line.
439 If `am' is not present, writing in the last column leaves the
440 cursor at the place where the character was written.
442 Writing in the last column of the last line should be avoided on
443 terminals with `am', as it may or may not cause scrolling to occur
444 (*note Scrolling::.). Scrolling is surely not what you would
447 If your program needs to check the `am' flag, then it also needs
448 to check the `xn' flag which indicates that wrapping happens in a
449 strange way. Many common terminals have the `xn' flag.
452 Flag whose presence means that the cursor wraps in a strange way.
453 At least two distinct kinds of strange behavior are known; the
454 termcap data base does not contain anything to distinguish the two.
456 On Concept-100 terminals, output in the last column wraps the
457 cursor almost like an ordinary `am' terminal. But if the next
458 thing output is a newline, it is ignored.
460 DEC VT-100 terminals (when the wrap switch is on) do a different
461 strange thing: the cursor wraps only if the next thing output is
462 another graphic character. In fact, the wrap occurs when the
463 following graphic character is received by the terminal, before the
464 character is placed on the screen.
466 On both of these terminals, after writing in the last column a
467 following graphic character will be displayed in the first column
468 of the following line. But the effect of relative cursor motion
469 characters such as newline or backspace at such a time depends on
470 the terminal. The effect of erase or scrolling commands also
471 depends on the terminal. You can't assume anything about what
472 they will do on a terminal that has `xn'. So, to be safe, you
473 should never do these things at such a time on such a terminal.
475 To be sure of reliable results on a terminal which has the `xn'
476 flag, output a `cm' absolute positioning command after writing in
477 the last column. Another safe thing to do is to output
478 carriage-return newline, which will leave the cursor at the
479 beginning of the following line.
482 File: termcap.info, Node: Scrolling, Next: Windows, Prev: Wrapping, Up: Capabilities
487 "Scrolling" means moving the contents of the screen up or down one or
488 more lines. Moving the contents up is "forward scrolling"; moving them
489 down is "reverse scrolling".
491 Scrolling happens after each line of output during ordinary output
492 on most display terminals. But in an application program that uses
493 termcap for random-access output, scrolling happens only when
494 explicitly requested with the commands in this section.
496 Some terminals have a "scroll region" feature. This lets you limit
497 the effect of scrolling to a specified range of lines. Lines outside
498 the range are unaffected when scrolling happens. The scroll region
499 feature is available if either `cs' or `cS' is present.
502 String of commands to scroll the screen one line up, assuming it is
503 output with the cursor at the beginning of the bottom line.
506 String of commands to scroll the screen one line down, assuming it
507 is output with the cursor at the beginning of the top line.
510 String of commands to scroll the screen N lines up, assuming it is
511 output with the cursor at the beginning of the bottom line.
514 String of commands to scroll the screen N line down, assuming it
515 is output with the cursor at the beginning of the top line.
518 String of commands to set the scroll region. This command takes
519 two parameters, START and END, which are the line numbers
520 (origin-zero) of the first line to include in the scroll region
521 and of the last line to include in it. When a scroll region is
522 set, scrolling is limited to the specified range of lines; lines
523 outside the range are not affected by scroll commands.
525 Do not try to move the cursor outside the scroll region. The
526 region remains set until explicitly removed. To remove the scroll
527 region, use another `cs' command specifying the full height of the
530 The cursor position is undefined after the `cs' command is set, so
531 position the cursor with `cm' immediately afterward.
534 String of commands to set the scroll region using parameters in
535 different form. The effect is the same as if `cs' were used.
536 Four parameters are required:
538 1. Total number of lines on the screen.
540 2. Number of lines above desired scroll region.
542 3. Number of lines below (outside of) desired scroll region.
544 4. Total number of lines on the screen, the same as the first
547 This capability is a GNU extension that was invented to allow the
548 Ann Arbor Ambassador's scroll-region command to be described; it
549 could also be done by putting non-Unix `%'-sequences into a `cs'
550 string, but that would have confused Unix programs that used the
551 `cs' capability with the Unix termcap. Currently only GNU Emacs
552 uses the `cS' capability.
555 Flag which means that the terminal does not normally scroll for
556 ordinary sequential output. For modern terminals, this means that
557 outputting a newline in ordinary sequential output with the cursor
558 on the bottom line wraps to the top line. For some obsolete
559 terminals, other things may happen.
561 The terminal may be able to scroll even if it does not normally do
562 so. If the `sf' capability is provided, it can be used for
563 scrolling regardless of `ns'.
566 Flag whose presence means that lines scrolled up off the top of the
567 screen may come back if scrolling down is done subsequently.
569 The `da' and `db' flags do not, strictly speaking, affect how to
570 scroll. But programs that scroll usually need to clear the lines
571 scrolled onto the screen, if these flags are present.
574 Flag whose presence means that lines scrolled down off the bottom
575 of the screen may come back if scrolling up is done subsequently.
578 Numeric value, the number of lines of display memory that the
579 terminal has. A value of zero means that the terminal has more
580 display memory than can fit on the screen, but no fixed number of
581 lines. (The number of lines may depend on the amount of text in
584 Any terminal description that defines `SF' should also define `sf';
585 likewise for `SR' and `sr'. However, many terminals can only scroll by
586 one line at a time, so it is common to find `sf' and not `SF', or `sr'
589 Therefore, all programs that use the scrolling facilities should be
590 prepared to work with `sf' in the case that `SF' is absent, and
591 likewise with `sr'. On the other hand, an application program that
592 uses only `sf' and not `SF' is acceptable, though slow on some
595 When outputting a scroll command with `tputs', the NLINES argument
596 should be the total number of lines in the portion of the screen being
597 scrolled. Very often these commands require padding proportional to
598 this number of lines. *Note Padding::.
601 File: termcap.info, Node: Windows, Next: Clearing, Prev: Scrolling, Up: Capabilities
606 A "window", in termcap, is a rectangular portion of the screen to
607 which all display operations are restricted. Wrapping, clearing,
608 scrolling, insertion and deletion all operate as if the specified
609 window were all the screen there was.
612 String of commands to set the terminal output screen window. This
613 string requires four parameters, all origin-zero:
614 1. The first line to include in the window.
616 2. The last line to include in the window.
618 3. The first column to include in the window.
620 4. The last column to include in the window.
622 Most terminals do not support windows.
625 File: termcap.info, Node: Clearing, Next: Insdel Line, Prev: Windows, Up: Capabilities
627 Clearing Parts of the Screen
628 ============================
630 There are several terminal capabilities for clearing parts of the
631 screen to blank. All display terminals support the `cl' string, and
632 most display terminals support all of these capabilities.
635 String of commands to clear the entire screen and position the
636 cursor at the upper left corner.
639 String of commands to clear the line the cursor is on, and all the
640 lines below it, down to the bottom of the screen. This command
641 string should be used only with the cursor in column zero; their
642 effect is undefined if the cursor is elsewhere.
645 String of commands to clear from the cursor to the end of the
649 String of commands to clear N characters, starting with the
650 character that the cursor is on. This command string is expected
651 to leave the cursor position unchanged. The parameter N should
652 never be large enough to reach past the right margin; the effect
653 of such a large parameter would be undefined.
655 Clear to end of line (`ce') is extremely important in programs that
656 maintain an updating display. Nearly all display terminals support this
657 operation, so it is acceptable for a an application program to refuse to
658 work if `ce' is not present. However, if you do not want this
659 limitation, you can accomplish clearing to end of line by outputting
660 spaces until you reach the right margin. In order to do this, you must
661 know the current horizontal position. Also, this technique assumes
662 that writing a space will erase. But this happens to be true on all
663 the display terminals that fail to support `ce'.
666 File: termcap.info, Node: Insdel Line, Next: Insdel Char, Prev: Clearing, Up: Capabilities
671 "Inserting a line" means creating a blank line in the middle of the
672 screen, and pushing the existing lines of text apart. In fact, the
673 lines above the insertion point do not change, while the lines below
674 move down, and one is normally lost at the bottom of the screen.
676 "Deleting a line" means causing the line to disappear from the
677 screen, closing up the gap by moving the lines below it upward. A new
678 line appears at the bottom of the screen. Usually this line is blank,
679 but on terminals with the `db' flag it may be a line previously moved
680 off the screen bottom by scrolling or line insertion.
682 Insertion and deletion of lines is useful in programs that maintain
683 an updating display some parts of which may get longer or shorter.
684 They are also useful in editors for scrolling parts of the screen, and
685 for redisplaying after lines of text are killed or inserted.
687 Many terminals provide commands to insert or delete a single line at
688 the cursor position. Some provide the ability to insert or delete
689 several lines with one command, using the number of lines to insert or
690 delete as a parameter. Always move the cursor to column zero before
691 using any of these commands.
694 String of commands to insert a blank line before the line the
695 cursor is on. The existing line, and all lines below it, are
696 moved down. The last line in the screen (or in the scroll region,
697 if one is set) disappears and in most circumstances is discarded.
698 It may not be discarded if the `db' is present (*note
701 The cursor must be at the left margin before this command is used.
702 This command does not move the cursor.
705 String of commands to delete the line the cursor is on. The
706 following lines move up, and a blank line appears at the bottom of
707 the screen (or bottom of the scroll region). If the terminal has
708 the `db' flag, a nonblank line previously pushed off the screen
709 bottom may reappear at the bottom.
711 The cursor must be at the left margin before this command is used.
712 This command does not move the cursor.
715 String of commands to insert N blank lines before the line that
716 the cursor is on. It is like `al' repeated N times, except that
717 it is as fast as one `al'.
720 String of commands to delete N lines starting with the line that
721 the cursor is on. It is like `dl' repeated N times, except that
722 it is as fast as one `dl'.
724 Any terminal description that defines `AL' should also define `al';
725 likewise for `DL' and `dl'. However, many terminals can only insert or
726 delete one line at a time, so it is common to find `al' and not `AL',
727 or `dl' without `DL'.
729 Therefore, all programs that use the insert and delete facilities
730 should be prepared to work with `al' in the case that `AL' is absent,
731 and likewise with `dl'. On the other hand, it is acceptable to write
732 an application that uses only `al' and `dl' and does not look for `AL'
735 If a terminal does not support line insertion and deletion directly,
736 but does support a scroll region, the effect of insertion and deletion
737 can be obtained with scrolling. However, it is up to the individual
738 user program to check for this possibility and use the scrolling
739 commands to get the desired result. It is fairly important to implement
740 this alternate strategy, since it is the only way to get the effect of
741 line insertion and deletion on the popular VT100 terminal.
743 Insertion and deletion of lines is affected by the scroll region on
744 terminals that have a settable scroll region. This is useful when it is
745 desirable to move any few consecutive lines up or down by a few lines.
748 The line pushed off the bottom of the screen is not lost if the
749 terminal has the `db' flag capability; instead, it is pushed into
750 display memory that does not appear on the screen. This is the same
751 thing that happens when scrolling pushes a line off the bottom of the
752 screen. Either reverse scrolling or deletion of a line can bring the
753 apparently lost line back onto the bottom of the screen. If the
754 terminal has the scroll region feature as well as `db', the pushed-out
755 line really is lost if a scroll region is in effect.
757 When outputting an insert or delete command with `tputs', the NLINES
758 argument should be the total number of lines from the cursor to the
759 bottom of the screen (or scroll region). Very often these commands
760 require padding proportional to this number of lines. *Note Padding::.
762 For `AL' and `DL' the NLINES argument should *not* depend on the
763 number of lines inserted or deleted; only the total number of lines
764 affected. This is because it is just as fast to insert two or N lines
765 with `AL' as to insert one line with `al'.
768 File: termcap.info, Node: Insdel Char, Next: Standout, Prev: Insdel Line, Up: Capabilities
770 Insert/Delete Character
771 =======================
773 "Inserting a character" means creating a blank space in the middle
774 of a line, and pushing the rest of the line rightward. The character
775 in the rightmost column is lost.
777 "Deleting a character" means causing the character to disappear from
778 the screen, closing up the gap by moving the rest of the line leftward.
779 A blank space appears in the rightmost column.
781 Insertion and deletion of characters is useful in programs that
782 maintain an updating display some parts of which may get longer or
783 shorter. It is also useful in editors for redisplaying the results of
784 editing within a line.
786 Many terminals provide commands to insert or delete a single
787 character at the cursor position. Some provide the ability to insert
788 or delete several characters with one command, using the number of
789 characters to insert or delete as a parameter.
791 Many terminals provide an insert mode in which outputting a graphic
792 character has the added effect of inserting a position for that
793 character. A special command string is used to enter insert mode and
794 another is used to exit it. The reason for designing a terminal with
795 an insert mode rather than an insert command is that inserting
796 character positions is usually followed by writing characters into
797 them. With insert mode, this is as fast as simply writing the
798 characters, except for the fixed overhead of entering and leaving
799 insert mode. However, when the line speed is great enough, padding may
800 be required for the graphic characters output in insert mode.
802 Some terminals require you to enter insert mode and then output a
803 special command for each position to be inserted. Or they may require
804 special commands to be output before or after each graphic character to
807 Deletion of characters is usually accomplished by a straightforward
808 command to delete one or several positions; but on some terminals, it
809 is necessary to enter a special delete mode before using the delete
810 command, and leave delete mode afterward. Sometimes delete mode and
811 insert mode are the same mode.
813 Some terminals make a distinction between character positions in
814 which a space character has been output and positions which have been
815 cleared. On these terminals, the effect of insert or delete character
816 runs to the first cleared position rather than to the end of the line.
817 In fact, the effect may run to more than one line if there is no
818 cleared position to stop the shift on the first line. These terminals
819 are identified by the `in' flag capability.
821 On terminals with the `in' flag, the technique of skipping over
822 characters that you know were cleared, and then outputting text later
823 on in the same line, causes later insert and delete character
824 operations on that line to do nonstandard things. A program that has
825 any chance of doing this must check for the `in' flag and must be
826 careful to write explicit space characters into the intermediate
827 columns when `in' is present.
829 A plethora of terminal capabilities are needed to describe all of
830 this complexity. Here is a list of them all. Following the list, we
831 present an algorithm for programs to use to take proper account of all
832 of these capabilities.
835 String of commands to enter insert mode.
837 If the terminal has no special insert mode, but it can insert
838 characters with a special command, `im' should be defined with a
839 null value, because the `vi' editor assumes that insertion of a
840 character is impossible if `im' is not provided.
842 New programs should not act like `vi'. They should pay attention
843 to `im' only if it is defined.
846 String of commands to leave insert mode. This capability must be
849 On a few old terminals the same string is used to enter and exit
850 insert mode. This string turns insert mode on if it was off, and
851 off if it was on. You can tell these terminals because the `ei'
852 string equals the `im' string. If you want to support these
853 terminals, you must always remember accurately whether insert mode
854 is in effect. However, these terminals are obsolete, and it is
855 reasonable to refuse to support them. On all modern terminals, you
856 can safely output `ei' at any time to ensure that insert mode is
860 String of commands to insert one character position at the cursor.
861 The cursor does not move.
863 If outputting a graphic character while in insert mode is
864 sufficient to insert the character, then the `ic' capability
865 should be defined with a null value.
867 If your terminal offers a choice of ways to insert--either use
868 insert mode or use a special command--then define `im' and do not
869 define `ic', since this gives the most efficient operation when
870 several characters are to be inserted. *Do not* define both
871 strings, for that means that *both* must be used each time
875 String of commands to output following an inserted graphic
876 character in insert mode. Often it is used just for a padding
877 spec, when padding is needed after an inserted character (*note
881 String of commands to insert N character positions at and after
882 the cursor. It has the same effect as repeating the `ic' string
883 and a space, N times.
885 If `IC' is provided, application programs may use it without first
886 entering insert mode.
889 Flag whose presence means it is safe to move the cursor while in
890 insert mode and assume the terminal remains in insert mode.
893 Flag whose presence means that the terminal distinguishes between
894 character positions in which space characters have been output and
895 positions which have been cleared.
897 An application program can assume that the terminal can do character
898 insertion if *any one of* the capabilities `IC', `im', `ic' or `ip' is
901 To insert N blank character positions, move the cursor to the place
902 to insert them and follow this algorithm:
904 1. If an `IC' string is provided, output it with parameter N and you
905 are finished. Otherwise (or if you don't want to bother to look
906 for an `IC' string) follow the remaining steps.
908 2. Output the `im' string, if there is one, unless the terminal is
909 already in insert mode.
911 3. Repeat steps 4 through 6, N times.
913 4. Output the `ic' string if any.
917 6. Output the `ip' string if any.
919 7. Output the `ei' string, eventually, to exit insert mode. There is
920 no need to do this right away. If the `mi' flag is present, you
921 can move the cursor and the cursor will remain in insert mode;
922 then you can do more insertion elsewhere without reentering insert
925 To insert N graphic characters, position the cursor and follow this
928 1. If an `IC' string is provided, output it with parameter N, then
929 output the graphic characters, and you are finished. Otherwise
930 (or if you don't want to bother to look for an `IC' string) follow
933 2. Output the `im' string, if there is one, unless the terminal is
934 already in insert mode.
936 3. For each character to be output, repeat steps 4 through 6.
938 4. Output the `ic' string if any.
940 5. Output the next graphic character.
942 6. Output the `ip' string if any.
944 7. Output the `ei' string, eventually, to exit insert mode. There is
945 no need to do this right away. If the `mi' flag is present, you
946 can move the cursor and the cursor will remain in insert mode;
947 then you can do more insertion elsewhere without reentering insert
950 Note that this is not the same as the original Unix termcap
951 specifications in one respect: it assumes that the `IC' string can be
952 used without entering insert mode. This is true as far as I know, and
953 it allows you be able to avoid entering and leaving insert mode, and
954 also to be able to avoid the inserted-character padding after the
955 characters that go into the inserted positions.
957 Deletion of characters is less complicated; deleting one column is
958 done by outputting the `dc' string. However, there may be a delete
959 mode that must be entered with `dm' in order to make `dc' work.
962 String of commands to delete one character position at the cursor.
963 If `dc' is not present, the terminal cannot delete characters.
966 String of commands to delete N characters starting at the cursor.
967 It has the same effect as repeating the `dc' string N times. Any
968 terminal description that has `DC' also has `dc'.
971 String of commands to enter delete mode. If not present, there is
972 no delete mode, and `dc' can be used at any time (assuming there is
976 String of commands to exit delete mode. This must be present if
979 To delete N character positions, position the cursor and follow these
982 1. If the `DC' string is present, output it with parameter N and you
983 are finished. Otherwise, follow the remaining steps.
985 2. Output the `dm' string, unless you know the terminal is already in
988 3. Output the `dc' string N times.
990 4. Output the `ed' string eventually. If the flag capability `mi' is
991 present, you can move the cursor and do more deletion without
992 leaving and reentering delete mode.
994 As with the `IC' string, we have departed from the original termcap
995 specifications by assuming that `DC' works without entering delete mode
996 even though `dc' would not.
998 If the `dm' and `im' capabilities are both present and have the same
999 value, it means that the terminal has one mode for both insertion and
1000 deletion. It is useful for a program to know this, because then it can
1001 do insertions after deletions, or vice versa, without leaving
1002 insert/delete mode and reentering it.