1This is Info file ./termcap.info, produced by Makeinfo-1.55 from the 2input file ./termcap.texi. 3 4 This file documents the termcap library of the GNU system. 5 6 Copyright (C) 1988 Free Software Foundation, Inc. 7 8 Permission is granted to make and distribute verbatim copies of this 9manual provided the copyright notice and this permission notice are 10preserved on all copies. 11 12 Permission is granted to copy and distribute modified versions of 13this manual under the conditions for verbatim copying, provided that 14the entire resulting derived work is distributed under the terms of a 15permission notice identical to this one. 16 17 Permission is granted to copy and distribute translations of this 18manual into another language, under the above conditions for modified 19versions, except that this permission notice may be stated in a 20translation approved by the Foundation. 21 22 23File: termcap.info, Node: Naming, Next: Inheriting, Prev: Capability Format, Up: Data Base 24 25Terminal Type Name Conventions 26============================== 27 28 There are conventions for choosing names of terminal types. For one 29thing, all letters should be in lower case. The terminal type for a 30terminal in its most usual or most fundamental mode of operation should 31not have a hyphen in it. 32 33 If the same terminal has other modes of operation which require 34different terminal descriptions, these variant descriptions are given 35names made by adding suffixes with hyphens. Such alternate descriptions 36are used for two reasons: 37 38 * When the terminal has a switch that changes its behavior. Since 39 the computer cannot tell how the switch is set, the user must tell 40 the computer by choosing the appropriate terminal type name. 41 42 For example, the VT-100 has a setup flag that controls whether the 43 cursor wraps at the right margin. If this flag is set to "wrap", 44 you must use the terminal type `vt100-am'. Otherwise you must use 45 `vt100-nam'. Plain `vt100' is defined as a synonym for either 46 `vt100-am' or `vt100-nam' depending on the preferences of the 47 local site. 48 49 The standard suffix `-am' stands for "automatic margins". 50 51 * To give the user a choice in how to use the terminal. This is done 52 when the terminal has a switch that the computer normally controls. 53 54 For example, the Ann Arbor Ambassador can be configured with many 55 screen sizes ranging from 20 to 60 lines. Fewer lines make bigger 56 characters but more lines let you see more of what you are editing. 57 As a result, users have different preferences. Therefore, termcap 58 provides terminal types for many screen sizes. If you choose type 59 `aaa-30', the terminal will be configured to use 30 lines; if you 60 choose `aaa-48', 48 lines will be used, and so on. 61 62 Here is a list of standard suffixes and their conventional meanings: 63 64`-w' 65 Short for "wide". This is a mode that gives the terminal more 66 columns than usual. This is normally a user option. 67 68`-am' 69 "Automatic margins". This is an alternate description for use when 70 the terminal's margin-wrap switch is on; it contains the `am' 71 flag. The implication is that normally the switch is off and the 72 usual description for the terminal says that the switch is off. 73 74`-nam' 75 "No automatic margins". The opposite of `-am', this names an 76 alternative description which lacks the `am' flag. This implies 77 that the terminal is normally operated with the margin-wrap switch 78 turned on, and the normal description of the terminal says so. 79 80`-na' 81 "No arrows". This terminal description initializes the terminal to 82 keep its arrow keys in local mode. This is a user option. 83 84`-rv' 85 "Reverse video". This terminal description causes text output for 86 normal video to appear as reverse, and text output for reverse 87 video to come out as normal. Often this description differs from 88 the usual one by interchanging the two strings which turn reverse 89 video on and off. 90 91 This is a user option; you can choose either the "reverse video" 92 variant terminal type or the normal terminal type, and termcap will 93 obey. 94 95`-s' 96 "Status". Says to enable use of a status line which ordinary 97 output does not touch (*note Status Line::.). 98 99 Some terminals have a special line that is used only as a status 100 line. For these terminals, there is no need for an `-s' variant; 101 the status line commands should be defined by default. On other 102 terminals, enabling a status line means removing one screen line 103 from ordinary use and reducing the effective screen height. For 104 these terminals, the user can choose the `-s' variant type to 105 request use of a status line. 106 107`-NLINES' 108 Says to operate with NLINES lines on the screen, for terminals 109 such as the Ambassador which provide this as an option. Normally 110 this is a user option; by choosing the terminal type, you control 111 how many lines termcap will use. 112 113`-NPAGESp' 114 Says that the terminal has NPAGES pages worth of screen memory, 115 for terminals where this is a hardware option. 116 117`-unk' 118 Says that description is not for direct use, but only for 119 reference in `tc' capabilities. Such a description is a kind of 120 subroutine, because it describes the common characteristics of 121 several variant descriptions that would use other suffixes in 122 place of `-unk'. 123 124 125File: termcap.info, Node: Inheriting, Next: Changing, Prev: Naming, Up: Data Base 126 127Inheriting from Related Descriptions 128==================================== 129 130 When two terminal descriptions are similar, their identical parts do 131not need to be given twice. Instead, one of the two can be defined in 132terms of the other, using the `tc' capability. We say that one 133description "refers to" the other, or "inherits from" the other. 134 135 The `tc' capability must be the last one in the terminal description, 136and its value is a string which is the name of another terminal type 137which is referred to. For example, 138 139 N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\ 140 :ti=\E[2J\E[30;0;0;30p:\ 141 :te=\E[60;0;0;30p\E[30;1H\E[J:\ 142 :li#30:tc=aaa-unk: 143 144defines the terminal type `aaa-30' (also known as plain `aaa') in terms 145of `aaa-unk', which defines everything about the Ambassador that is 146independent of screen height. The types `aaa-36', `aaa-48' and so on 147for other screen heights are likewise defined to inherit from `aaa-unk'. 148 149 The capabilities overridden by `aaa-30' include `li', which says how 150many lines there are, and `ti' and `te', which configure the terminal 151to use that many lines. 152 153 The effective terminal description for type `aaa' consists of the 154text shown above followed by the text of the description of `aaa-unk'. 155The `tc' capability is handled automatically by `tgetent', which finds 156the description thus referenced and combines the two descriptions 157(*note Find::.). Therefore, only the implementor of the terminal 158descriptions needs to think about using `tc'. Users and application 159programmers do not need to be concerned with it. 160 161 Since the reference terminal description is used last, capabilities 162specified in the referring description override any specifications of 163the same capabilities in the reference description. 164 165 The referring description can cancel out a capability without 166specifying any new value for it by means of a special trick. Write the 167capability in the referring description, with the character `@' after 168the capability name, as follows: 169 170 NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\ 171 :am@:tc=aaa-30: 172 173 174File: termcap.info, Node: Changing, Prev: Inheriting, Up: Data Base 175 176When Changes in the Data Base Take Effect 177========================================= 178 179 Each application program must read the terminal description from the 180data base, so a change in the data base is effective for all jobs 181started after the change is made. 182 183 The change will usually have no effect on a job that have been in 184existence since before the change. The program probably read the 185terminal description once, when it was started, and is continuing to 186use what it read then. If the program does not have a feature for 187reexamining the data base, then you will need to run it again (probably 188killing the old job). 189 190 If the description in use is coming from the `TERMCAP' environment 191variable, then the data base file is effectively overridden, and 192changes in it will have no effect until you change the `TERMCAP' 193variable as well. For example, some users' `.login' files 194automatically copy the terminal description into `TERMCAP' to speed 195startup of applications. If you have done this, you will need to 196change the `TERMCAP' variable to make the changed data base take effect. 197 198 199File: termcap.info, Node: Capabilities, Next: Summary, Prev: Data Base, Up: Top 200 201Definitions of the Terminal Capabilities 202**************************************** 203 204 This section is divided into many subsections, each for one aspect of 205use of display terminals. For writing a display program, you usually 206need only check the subsections for the operations you want to use. 207For writing a terminal description, you must read each subsection and 208fill in the capabilities described there. 209 210 String capabilities that are display commands may require numeric 211parameters (*note Parameters::.). Most such capabilities do not use 212parameters. When a capability requires parameters, this is explicitly 213stated at the beginning of its definition. In simple cases, the first 214or second sentence of the definition mentions all the parameters, in 215the order they should be given, using a name in upper case for each 216one. For example, the `rp' capability is a command that requires two 217parameters; its definition begins as follows: 218 219 String of commands to output a graphic character C, repeated N 220 times. 221 222 In complex cases or when there are many parameters, they are 223described explicitly. 224 225 When a capability is described as obsolete, this means that programs 226should not be written to look for it, but terminal descriptions should 227still be written to provide it. 228 229 When a capability is described as very obsolete, this means that it 230should be omitted from terminal descriptions as well. 231 232* Menu: 233 234* Basic:: Basic characteristics. 235* Screen Size:: Screen size, and what happens when it changes. 236* Cursor Motion:: Various ways to move the cursor. 237* Wrapping:: What happens if you write a character in the last column. 238* Scrolling:: Pushing text up and down on the screen. 239* Windows:: Limiting the part of the window that output affects. 240* Clearing:: Erasing one or many lines. 241* Insdel Line:: Making new blank lines in mid-screen; deleting lines. 242* Insdel Char:: Inserting and deleting characters within a line. 243* Standout:: Highlighting some of the text. 244* Underlining:: Underlining some of the text. 245* Cursor Visibility:: Making the cursor more or less easy to spot. 246* Bell:: Attracts user's attention; not localized on the screen. 247* Keypad:: Recognizing when function keys or arrows are typed. 248* Meta Key:: META acts like an extra shift key. 249* Initialization:: Commands used to initialize or reset the terminal. 250* Pad Specs:: Info for the kernel on how much padding is needed. 251* Status Line:: A status line displays "background" information. 252* Half-Line:: Moving by half-lines, for superscripts and subscripts. 253* Printer:: Controlling auxiliary printers of display terminals. 254 255 256File: termcap.info, Node: Basic, Next: Screen Size, Up: Capabilities 257 258Basic Characteristics 259===================== 260 261 This section documents the capabilities that describe the basic and 262nature of the terminal, and also those that are relevant to the output 263of graphic characters. 264 265`os' 266 Flag whose presence means that the terminal can overstrike. This 267 means that outputting a graphic character does not erase whatever 268 was present in the same character position before. The terminals 269 that can overstrike include printing terminals, storage tubes (all 270 obsolete nowadays), and many bit-map displays. 271 272`eo' 273 Flag whose presence means that outputting a space erases a 274 character position even if the terminal supports overstriking. If 275 this flag is not present and overstriking is supported, output of 276 a space has no effect except to move the cursor. 277 278 (On terminals that do not support overstriking, you can always 279 assume that outputting a space at a position erases whatever 280 character was previously displayed there.) 281 282`gn' 283 Flag whose presence means that this terminal type is a generic type 284 which does not really describe any particular terminal. Generic 285 types are intended for use as the default type assigned when the 286 user connects to the system, with the intention that the user 287 should specify what type he really has. One example of a generic 288 type is the type `network'. 289 290 Since the generic type cannot say how to do anything interesting 291 with the terminal, termcap-using programs will always find that the 292 terminal is too weak to be supported if the user has failed to 293 specify a real terminal type in place of the generic one. The 294 `gn' flag directs these programs to use a different error message: 295 "You have not specified your real terminal type", rather than 296 "Your terminal is not powerful enough to be used". 297 298`hc' 299 Flag whose presence means this is a hardcopy terminal. 300 301`rp' 302 String of commands to output a graphic character C, repeated N 303 times. The first parameter value is the ASCII code for the desired 304 character, and the second parameter is the number of times to 305 repeat the character. Often this command requires padding 306 proportional to the number of times the character is repeated. 307 This effect can be had by using parameter arithmetic with 308 `%'-sequences to compute the amount of padding, then generating 309 the result as a number at the front of the string so that `tputs' 310 will treat it as padding. 311 312`hz' 313 Flag whose presence means that the ASCII character `~' cannot be 314 output on this terminal because it is used for display commands. 315 316 Programs handle this flag by checking all text to be output and 317 replacing each `~' with some other character(s). If this is not 318 done, the screen will be thoroughly garbled. 319 320 The old Hazeltine terminals that required such treatment are 321 probably very rare today, so you might as well not bother to 322 support this flag. 323 324`CC' 325 String whose presence means the terminal has a settable command 326 character. The value of the string is the default command 327 character (which is usually ESC). 328 329 All the strings of commands in the terminal description should be 330 written to use the default command character. If you are writing 331 an application program that changes the command character, use the 332 `CC' capability to figure out how to translate all the display 333 commands to work with the new command character. 334 335 Most programs have no reason to look at the `CC' capability. 336 337`xb' 338 Flag whose presence identifies Superbee terminals which are unable 339 to transmit the characters ESC and `Control-C'. Programs which 340 support this flag are supposed to check the input for the code 341 sequences sent by the F1 and F2 keys, and pretend that ESC or 342 `Control-C' (respectively) had been read. But this flag is 343 obsolete, and not worth supporting. 344 345 346File: termcap.info, Node: Screen Size, Next: Cursor Motion, Prev: Basic, Up: Capabilities 347 348Screen Size 349=========== 350 351 A terminal description has two capabilities, `co' and `li', that 352describe the screen size in columns and lines. But there is more to 353the question of screen size than this. 354 355 On some operating systems the "screen" is really a window and the 356effective width can vary. On some of these systems, `tgetnum' uses the 357actual width of the window to decide what value to return for the `co' 358capability, overriding what is actually written in the terminal 359description. On other systems, it is up to the application program to 360check the actual window width using a system call. For example, on BSD 3614.3 systems, the system call `ioctl' with code `TIOCGWINSZ' will tell 362you the current screen size. 363 364 On all window systems, termcap is powerless to advise the application 365program if the user resizes the window. Application programs must deal 366with this possibility in a system-dependent fashion. On some systems 367the C shell handles part of the problem by detecting changes in window 368size and setting the `TERMCAP' environment variable appropriately. 369This takes care of application programs that are started subsequently. 370It does not help application programs already running. 371 372 On some systems, including BSD 4.3, all programs using a terminal get 373a signal named `SIGWINCH' whenever the screen size changes. Programs 374that use termcap should handle this signal by using `ioctl TIOCGWINSZ' 375to learn the new screen size. 376 377`co' 378 Numeric value, the width of the screen in character positions. 379 Even hardcopy terminals normally have a `co' capability. 380 381`li' 382 Numeric value, the height of the screen in lines. 383 384 385File: termcap.info, Node: Cursor Motion, Next: Wrapping, Prev: Screen Size, Up: Capabilities 386 387Cursor Motion 388============= 389 390 Termcap assumes that the terminal has a "cursor", a spot on the 391screen where a visible mark is displayed, and that most display 392commands take effect at the position of the cursor. It follows that 393moving the cursor to a specified location is very important. 394 395 There are many terminal capabilities for different cursor motion 396operations. A terminal description should define as many as possible, 397but most programs do not need to use most of them. One capability, 398`cm', moves the cursor to an arbitrary place on the screen; this by 399itself is sufficient for any application as long as there is no need to 400support hardcopy terminals or certain old, weak displays that have only 401relative motion commands. Use of other cursor motion capabilities is an 402optimization, enabling the program to output fewer characters in some 403common cases. 404 405 If you plan to use the relative cursor motion commands in an 406application program, you must know what the starting cursor position 407is. To do this, you must keep track of the cursor position and update 408the records each time anything is output to the terminal, including 409graphic characters. In addition, it is necessary to know whether the 410terminal wraps after writing in the rightmost column. *Note Wrapping::. 411 412 One other motion capability needs special mention: `nw' moves the 413cursor to the beginning of the following line, perhaps clearing all the 414starting line after the cursor, or perhaps not clearing at all. This 415capability is a least common denominator that is probably supported 416even by terminals that cannot do most other things such as `cm' or `do'. 417Even hardcopy terminals can support `nw'. 418 419`cm' 420 String of commands to position the cursor at line L, column C. 421 Both parameters are origin-zero, and are defined relative to the 422 screen, not relative to display memory. 423 424 All display terminals except a few very obsolete ones support `cm', 425 so it is acceptable for an application program to refuse to 426 operate on terminals lacking `cm'. 427 428`ho' 429 String of commands to move the cursor to the upper left corner of 430 the screen (this position is called the "home position"). In 431 terminals where the upper left corner of the screen is not the 432 same as the beginning of display memory, this command must go to 433 the upper left corner of the screen, not the beginning of display 434 memory. 435 436 Every display terminal supports this capability, and many 437 application programs refuse to operate if the `ho' capability is 438 missing. 439 440`ll' 441 String of commands to move the cursor to the lower left corner of 442 the screen. On some terminals, moving up from home position does 443 this, but programs should never assume that will work. Just 444 output the `ll' string (if it is provided); if moving to home 445 position and then moving up is the best way to get there, the `ll' 446 command will do that. 447 448`cr' 449 String of commands to move the cursor to the beginning of the line 450 it is on. If this capability is not specified, many programs 451 assume they can use the ASCII carriage return character for this. 452 453`le' 454 String of commands to move the cursor left one column. Unless the 455 `bw' flag capability is specified, the effect is undefined if the 456 cursor is at the left margin; do not use this command there. If 457 `bw' is present, this command may be used at the left margin, and 458 it wraps the cursor to the last column of the preceding line. 459 460`nd' 461 String of commands to move the cursor right one column. The 462 effect is undefined if the cursor is at the right margin; do not 463 use this command there, not even if `am' is present. 464 465`up' 466 String of commands to move the cursor vertically up one line. The 467 effect of sending this string when on the top line is undefined; 468 programs should never use it that way. 469 470`do' 471 String of commands to move the cursor vertically down one line. 472 The effect of sending this string when on the bottom line is 473 undefined; programs should never use it that way. 474 475 Some programs do use `do' to scroll up one line if used at the 476 bottom line, if `sf' is not defined but `sr' is. This is only to 477 compensate for certain old, incorrect terminal descriptions. (In 478 principle this might actually lead to incorrect behavior on other 479 terminals, but that seems to happen rarely if ever.) But the 480 proper solution is that the terminal description should define 481 `sf' as well as `do' if the command is suitable for scrolling. 482 483 The original idea was that this string would not contain a newline 484 character and therefore could be used without disabling the 485 kernel's usual habit of converting of newline into a 486 carriage-return newline sequence. But many terminal descriptions 487 do use newline in the `do' string, so this is not possible; a 488 program which sends the `do' string must disable output conversion 489 in the kernel (*note Initialize::.). 490 491`bw' 492 Flag whose presence says that `le' may be used in column zero to 493 move to the last column of the preceding line. If this flag is 494 not present, `le' should not be used in column zero. 495 496`nw' 497 String of commands to move the cursor to start of next line, 498 possibly clearing rest of line (following the cursor) before 499 moving. 500 501`DO', `UP', `LE', `RI' 502 Strings of commands to move the cursor N lines down vertically, up 503 vertically, or N columns left or right. Do not attempt to move 504 past any edge of the screen with these commands; the effect of 505 trying that is undefined. Only a few terminal descriptions provide 506 these commands, and most programs do not use them. 507 508`CM' 509 String of commands to position the cursor at line L, column C, 510 relative to display memory. Both parameters are origin-zero. 511 This capability is present only in terminals where there is a 512 difference between screen-relative and memory-relative addressing, 513 and not even in all such terminals. 514 515`ch' 516 String of commands to position the cursor at column C in the same 517 line it is on. This is a special case of `cm' in which the 518 vertical position is not changed. The `ch' capability is provided 519 only when it is faster to output than `cm' would be in this 520 special case. Programs should not assume most display terminals 521 have `ch'. 522 523`cv' 524 String of commands to position the cursor at line L in the same 525 column. This is a special case of `cm' in which the horizontal 526 position is not changed. The `cv' capability is provided only 527 when it is faster to output than `cm' would be in this special 528 case. Programs should not assume most display terminals have `cv'. 529 530`sc' 531 String of commands to make the terminal save the current cursor 532 position. Only the last saved position can be used. If this 533 capability is present, `rc' should be provided also. Most 534 terminals have neither. 535 536`rc' 537 String of commands to make the terminal restore the last saved 538 cursor position. If this capability is present, `sc' should be 539 provided also. Most terminals have neither. 540 541`ff' 542 String of commands to advance to the next page, for a hardcopy 543 terminal. 544 545`ta' 546 String of commands to move the cursor right to the next hardware 547 tab stop column. Missing if the terminal does not have any kind of 548 hardware tabs. Do not send this command if the kernel's terminal 549 modes say that the kernel is expanding tabs into spaces. 550 551`bt' 552 String of commands to move the cursor left to the previous hardware 553 tab stop column. Missing if the terminal has no such ability; many 554 terminals do not. Do not send this command if the kernel's 555 terminal modes say that the kernel is expanding tabs into spaces. 556 557 The following obsolete capabilities should be included in terminal 558descriptions when appropriate, but should not be looked at by new 559programs. 560 561`nc' 562 Flag whose presence means the terminal does not support the ASCII 563 carriage return character as `cr'. This flag is needed because 564 old programs assume, when the `cr' capability is missing, that 565 ASCII carriage return can be used for the purpose. We use `nc' to 566 tell the old programs that carriage return may not be used. 567 568 New programs should not assume any default for `cr', so they need 569 not look at `nc'. However, descriptions should contain `nc' 570 whenever they do not contain `cr'. 571 572`xt' 573 Flag whose presence means that the ASCII tab character may not be 574 used for cursor motion. This flag exists because old programs 575 assume, when the `ta' capability is missing, that ASCII tab can be 576 used for the purpose. We use `xt' to tell the old programs not to 577 use tab. 578 579 New programs should not assume any default for `ta', so they need 580 not look at `xt' in connection with cursor motion. Note that `xt' 581 also has implications for standout mode (*note Standout::.). It 582 is obsolete in regard to cursor motion but not in regard to 583 standout. 584 585 In fact, `xt' means that the terminal is a Teleray 1061. 586 587`bc' 588 Very obsolete alternative name for the `le' capability. 589 590`bs' 591 Flag whose presence means that the ASCII character backspace may be 592 used to move the cursor left. Obsolete; look at `le' instead. 593 594`nl' 595 Obsolete capability which is a string that can either be used to 596 move the cursor down or to scroll. The same string must scroll 597 when used on the bottom line and move the cursor when used on any 598 other line. New programs should use `do' or `sf', and ignore `nl'. 599 600 If there is no `nl' capability, some old programs assume they can 601 use the newline character for this purpose. These programs follow 602 a bad practice, but because they exist, it is still desirable to 603 define the `nl' capability in a terminal description if the best 604 way to move down is *not* a newline. 605 606 607File: termcap.info, Node: Wrapping, Next: Scrolling, Prev: Cursor Motion, Up: Capabilities 608 609Wrapping 610======== 611 612 "Wrapping" means moving the cursor from the right margin to the left 613margin of the following line. Some terminals wrap automatically when a 614graphic character is output in the last column, while others do not. 615Most application programs that use termcap need to know whether the 616terminal wraps. There are two special flag capabilities to describe 617what the terminal does when a graphic character is output in the last 618column. 619 620`am' 621 Flag whose presence means that writing a character in the last 622 column causes the cursor to wrap to the beginning of the next line. 623 624 If `am' is not present, writing in the last column leaves the 625 cursor at the place where the character was written. 626 627 Writing in the last column of the last line should be avoided on 628 terminals with `am', as it may or may not cause scrolling to occur 629 (*note Scrolling::.). Scrolling is surely not what you would 630 intend. 631 632 If your program needs to check the `am' flag, then it also needs 633 to check the `xn' flag which indicates that wrapping happens in a 634 strange way. Many common terminals have the `xn' flag. 635 636`xn' 637 Flag whose presence means that the cursor wraps in a strange way. 638 At least two distinct kinds of strange behavior are known; the 639 termcap data base does not contain anything to distinguish the two. 640 641 On Concept-100 terminals, output in the last column wraps the 642 cursor almost like an ordinary `am' terminal. But if the next 643 thing output is a newline, it is ignored. 644 645 DEC VT-100 terminals (when the wrap switch is on) do a different 646 strange thing: the cursor wraps only if the next thing output is 647 another graphic character. In fact, the wrap occurs when the 648 following graphic character is received by the terminal, before the 649 character is placed on the screen. 650 651 On both of these terminals, after writing in the last column a 652 following graphic character will be displayed in the first column 653 of the following line. But the effect of relative cursor motion 654 characters such as newline or backspace at such a time depends on 655 the terminal. The effect of erase or scrolling commands also 656 depends on the terminal. You can't assume anything about what 657 they will do on a terminal that has `xn'. So, to be safe, you 658 should never do these things at such a time on such a terminal. 659 660 To be sure of reliable results on a terminal which has the `xn' 661 flag, output a `cm' absolute positioning command after writing in 662 the last column. Another safe thing to do is to output 663 carriage-return newline, which will leave the cursor at the 664 beginning of the following line. 665 666`LP' 667 Flag whose presence means that it is safe to write in the last 668 column of the last line without worrying about undesired 669 scrolling. `LP' indicates the DEC flavor of `xn' strangeness. 670 671 672File: termcap.info, Node: Scrolling, Next: Windows, Prev: Wrapping, Up: Capabilities 673 674Scrolling 675========= 676 677 "Scrolling" means moving the contents of the screen up or down one or 678more lines. Moving the contents up is "forward scrolling"; moving them 679down is "reverse scrolling". 680 681 Scrolling happens after each line of output during ordinary output 682on most display terminals. But in an application program that uses 683termcap for random-access output, scrolling happens only when 684explicitly requested with the commands in this section. 685 686 Some terminals have a "scroll region" feature. This lets you limit 687the effect of scrolling to a specified range of lines. Lines outside 688the range are unaffected when scrolling happens. The scroll region 689feature is available if either `cs' or `cS' is present. 690 691`sf' 692 String of commands to scroll the screen one line up, assuming it is 693 output with the cursor at the beginning of the bottom line. 694 695`sr' 696 String of commands to scroll the screen one line down, assuming it 697 is output with the cursor at the beginning of the top line. 698 699`do' 700 A few programs will try to use `do' to do the work of `sf'. This 701 is not really correct--it is an attempt to compensate for the 702 absence of a `sf' command in some old terminal descriptions. 703 704 Since these terminal descriptions do define `sr', perhaps at one 705 time the definition of `do' was different and it could be used for 706 scrolling as well. But it isn't desirable to combine these two 707 functions in one capability, since scrolling often requires more 708 padding than simply moving the cursor down. Defining `sf' and 709 `do' separately allows you to specify the padding properly. Also, 710 all sources agree that `do' should not be relied on to do 711 scrolling. 712 713 So the best approach is to add `sf' capabilities to the 714 descriptions of these terminals, copying the definition of `do' if 715 that does scroll. 716 717`SF' 718 String of commands to scroll the screen N lines up, assuming it is 719 output with the cursor at the beginning of the bottom line. 720 721`SR' 722 String of commands to scroll the screen N lines down, assuming it 723 is output with the cursor at the beginning of the top line. 724 725`cs' 726 String of commands to set the scroll region. This command takes 727 two parameters, START and END, which are the line numbers 728 (origin-zero) of the first line to include in the scroll region 729 and of the last line to include in it. When a scroll region is 730 set, scrolling is limited to the specified range of lines; lines 731 outside the range are not affected by scroll commands. 732 733 Do not try to move the cursor outside the scroll region. The 734 region remains set until explicitly removed. To remove the scroll 735 region, use another `cs' command specifying the full height of the 736 screen. 737 738 The cursor position is undefined after the `cs' command is set, so 739 position the cursor with `cm' immediately afterward. 740 741`cS' 742 String of commands to set the scroll region using parameters in 743 different form. The effect is the same as if `cs' were used. 744 Four parameters are required: 745 746 1. Total number of lines on the screen. 747 748 2. Number of lines above desired scroll region. 749 750 3. Number of lines below (outside of) desired scroll region. 751 752 4. Total number of lines on the screen, the same as the first 753 parameter. 754 755 This capability is a GNU extension that was invented to allow the 756 Ann Arbor Ambassador's scroll-region command to be described; it 757 could also be done by putting non-Unix `%'-sequences into a `cs' 758 string, but that would have confused Unix programs that used the 759 `cs' capability with the Unix termcap. Currently only GNU Emacs 760 uses the `cS' capability. 761 762`ns' 763 Flag which means that the terminal does not normally scroll for 764 ordinary sequential output. For modern terminals, this means that 765 outputting a newline in ordinary sequential output with the cursor 766 on the bottom line wraps to the top line. For some obsolete 767 terminals, other things may happen. 768 769 The terminal may be able to scroll even if it does not normally do 770 so. If the `sf' capability is provided, it can be used for 771 scrolling regardless of `ns'. 772 773`da' 774 Flag whose presence means that lines scrolled up off the top of the 775 screen may come back if scrolling down is done subsequently. 776 777 The `da' and `db' flags do not, strictly speaking, affect how to 778 scroll. But programs that scroll usually need to clear the lines 779 scrolled onto the screen, if these flags are present. 780 781`db' 782 Flag whose presence means that lines scrolled down off the bottom 783 of the screen may come back if scrolling up is done subsequently. 784 785`lm' 786 Numeric value, the number of lines of display memory that the 787 terminal has. A value of zero means that the terminal has more 788 display memory than can fit on the screen, but no fixed number of 789 lines. (The number of lines may depend on the amount of text in 790 each line.) 791 792 Any terminal description that defines `SF' should also define `sf'; 793likewise for `SR' and `sr'. However, many terminals can only scroll by 794one line at a time, so it is common to find `sf' and not `SF', or `sr' 795without `SR'. 796 797 Therefore, all programs that use the scrolling facilities should be 798prepared to work with `sf' in the case that `SF' is absent, and 799likewise with `sr'. On the other hand, an application program that 800uses only `sf' and not `SF' is acceptable, though slow on some 801terminals. 802 803 When outputting a scroll command with `tputs', the NLINES argument 804should be the total number of lines in the portion of the screen being 805scrolled. Very often these commands require padding proportional to 806this number of lines. *Note Padding::. 807 808 809File: termcap.info, Node: Windows, Next: Clearing, Prev: Scrolling, Up: Capabilities 810 811Windows 812======= 813 814 A "window", in termcap, is a rectangular portion of the screen to 815which all display operations are restricted. Wrapping, clearing, 816scrolling, insertion and deletion all operate as if the specified 817window were all the screen there was. 818 819`wi' 820 String of commands to set the terminal output screen window. This 821 string requires four parameters, all origin-zero: 822 1. The first line to include in the window. 823 824 2. The last line to include in the window. 825 826 3. The first column to include in the window. 827 828 4. The last column to include in the window. 829 830 Most terminals do not support windows. 831 832 833File: termcap.info, Node: Clearing, Next: Insdel Line, Prev: Windows, Up: Capabilities 834 835Clearing Parts of the Screen 836============================ 837 838 There are several terminal capabilities for clearing parts of the 839screen to blank. All display terminals support the `cl' string, and 840most display terminals support all of these capabilities. 841 842`cl' 843 String of commands to clear the entire screen and position the 844 cursor at the upper left corner. 845 846`cd' 847 String of commands to clear the line the cursor is on, and all the 848 lines below it, down to the bottom of the screen. This command 849 string should be used only with the cursor in column zero; their 850 effect is undefined if the cursor is elsewhere. 851 852`ce' 853 String of commands to clear from the cursor to the end of the 854 current line. 855 856`ec' 857 String of commands to clear N characters, starting with the 858 character that the cursor is on. This command string is expected 859 to leave the cursor position unchanged. The parameter N should 860 never be large enough to reach past the right margin; the effect 861 of such a large parameter would be undefined. 862 863 Clear to end of line (`ce') is extremely important in programs that 864maintain an updating display. Nearly all display terminals support this 865operation, so it is acceptable for a an application program to refuse to 866work if `ce' is not present. However, if you do not want this 867limitation, you can accomplish clearing to end of line by outputting 868spaces until you reach the right margin. In order to do this, you must 869know the current horizontal position. Also, this technique assumes 870that writing a space will erase. But this happens to be true on all 871the display terminals that fail to support `ce'. 872 873 874File: termcap.info, Node: Insdel Line, Next: Insdel Char, Prev: Clearing, Up: Capabilities 875 876Insert/Delete Line 877================== 878 879 "Inserting a line" means creating a blank line in the middle of the 880screen, and pushing the existing lines of text apart. In fact, the 881lines above the insertion point do not change, while the lines below 882move down, and one is normally lost at the bottom of the screen. 883 884 "Deleting a line" means causing the line to disappear from the 885screen, closing up the gap by moving the lines below it upward. A new 886line appears at the bottom of the screen. Usually this line is blank, 887but on terminals with the `db' flag it may be a line previously moved 888off the screen bottom by scrolling or line insertion. 889 890 Insertion and deletion of lines is useful in programs that maintain 891an updating display some parts of which may get longer or shorter. 892They are also useful in editors for scrolling parts of the screen, and 893for redisplaying after lines of text are killed or inserted. 894 895 Many terminals provide commands to insert or delete a single line at 896the cursor position. Some provide the ability to insert or delete 897several lines with one command, using the number of lines to insert or 898delete as a parameter. Always move the cursor to column zero before 899using any of these commands. 900 901`al' 902 String of commands to insert a blank line before the line the 903 cursor is on. The existing line, and all lines below it, are 904 moved down. The last line in the screen (or in the scroll region, 905 if one is set) disappears and in most circumstances is discarded. 906 It may not be discarded if the `db' is present (*note 907 Scrolling::.). 908 909 The cursor must be at the left margin before this command is used. 910 This command does not move the cursor. 911 912`dl' 913 String of commands to delete the line the cursor is on. The 914 following lines move up, and a blank line appears at the bottom of 915 the screen (or bottom of the scroll region). If the terminal has 916 the `db' flag, a nonblank line previously pushed off the screen 917 bottom may reappear at the bottom. 918 919 The cursor must be at the left margin before this command is used. 920 This command does not move the cursor. 921 922`AL' 923 String of commands to insert N blank lines before the line that 924 the cursor is on. It is like `al' repeated N times, except that 925 it is as fast as one `al'. 926 927`DL' 928 String of commands to delete N lines starting with the line that 929 the cursor is on. It is like `dl' repeated N times, except that 930 it is as fast as one `dl'. 931 932 Any terminal description that defines `AL' should also define `al'; 933likewise for `DL' and `dl'. However, many terminals can only insert or 934delete one line at a time, so it is common to find `al' and not `AL', 935or `dl' without `DL'. 936 937 Therefore, all programs that use the insert and delete facilities 938should be prepared to work with `al' in the case that `AL' is absent, 939and likewise with `dl'. On the other hand, it is acceptable to write 940an application that uses only `al' and `dl' and does not look for `AL' 941or `DL' at all. 942 943 If a terminal does not support line insertion and deletion directly, 944but does support a scroll region, the effect of insertion and deletion 945can be obtained with scrolling. However, it is up to the individual 946user program to check for this possibility and use the scrolling 947commands to get the desired result. It is fairly important to implement 948this alternate strategy, since it is the only way to get the effect of 949line insertion and deletion on the popular VT100 terminal. 950 951 Insertion and deletion of lines is affected by the scroll region on 952terminals that have a settable scroll region. This is useful when it is 953desirable to move any few consecutive lines up or down by a few lines. 954*Note Scrolling::. 955 956 The line pushed off the bottom of the screen is not lost if the 957terminal has the `db' flag capability; instead, it is pushed into 958display memory that does not appear on the screen. This is the same 959thing that happens when scrolling pushes a line off the bottom of the 960screen. Either reverse scrolling or deletion of a line can bring the 961apparently lost line back onto the bottom of the screen. If the 962terminal has the scroll region feature as well as `db', the pushed-out 963line really is lost if a scroll region is in effect. 964 965 When outputting an insert or delete command with `tputs', the NLINES 966argument should be the total number of lines from the cursor to the 967bottom of the screen (or scroll region). Very often these commands 968require padding proportional to this number of lines. *Note Padding::. 969 970 For `AL' and `DL' the NLINES argument should *not* depend on the 971number of lines inserted or deleted; only the total number of lines 972affected. This is because it is just as fast to insert two or N lines 973with `AL' as to insert one line with `al'. 974 975