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: Top, Next: Introduction, Prev: (dir), Up: (dir) 24 25* Menu: 26 27* Introduction:: What is termcap? Why this manual? 28* Library:: The termcap library functions. 29* Data Base:: What terminal descriptions in `/etc/termcap' look like. 30* Capabilities:: Definitions of the individual terminal capabilities: 31 how to write them in descriptions, and how to use 32 their values to do display updating. 33* Summary:: Brief table of capability names and their meanings. 34* Var Index:: Index of C functions and variables. 35* Cap Index:: Index of termcap capabilities. 36* Index:: Concept index. 37 38 -- The Detailed Node Listing -- 39 40The Termcap Library 41 42* Preparation:: Preparing to use the termcap library. 43* Find:: Finding the description of the terminal being used. 44* Interrogate:: Interrogating the description for particular capabilities. 45* Initialize:: Initialization for output using termcap. 46* Padding:: Outputting padding. 47* Parameters:: Encoding parameters such as cursor positions. 48 49Padding 50 51* Why Pad:: Explanation of padding. 52* Not Enough:: When there is not enough padding. 53* Describe Padding:: The data base says how much padding a terminal needs. 54* Output Padding:: Using `tputs' to output the needed padding. 55 56Filling In Parameters 57 58* Encode Parameters:: The language for encoding parameters. 59* Using Parameters:: Outputting a string command with parameters. 60 61Sending Display Commands with Parameters 62 63* tparam:: The general case, for GNU termcap only. 64* tgoto:: The special case of cursor motion. 65 66The Format of the Data Base 67 68* Format:: Overall format of a terminal description. 69* Capability Format:: Format of capabilities within a description. 70* Naming:: Naming conventions for terminal types. 71* Inheriting:: Inheriting part of a description from 72a related terminal type. 73* Changing:: When changes in the data base take effect. 74 75Definitions of the Terminal Capabilities 76 77* Basic:: Basic characteristics. 78* Screen Size:: Screen size, and what happens when it changes. 79* Cursor Motion:: Various ways to move the cursor. 80* Wrapping:: What happens if you write a character in the last column. 81* Scrolling:: Pushing text up and down on the screen. 82* Windows:: Limiting the part of the window that output affects. 83* Clearing:: Erasing one or many lines. 84* Insdel Line:: Making new blank lines in mid-screen; deleting lines. 85* Insdel Char:: Inserting and deleting characters within a line. 86* Standout:: Highlighting some of the text. 87* Underlining:: Underlining some of the text. 88* Cursor Visibility:: Making the cursor more or less easy to spot. 89* Bell:: Attracts user's attention; not localized on the screen. 90* Keypad:: Recognizing when function keys or arrows are typed. 91* Meta Key:: META acts like an extra shift key. 92* Initialization:: Commands used to initialize or reset the terminal. 93* Pad Specs:: Info for the kernel on how much padding is needed. 94* Status Line:: A status line displays "background" information. 95* Half-Line:: Moving by half-lines, for superscripts and subscripts. 96* Printer:: Controlling auxiliary printers of display terminals. 97 98 99File: termcap.info, Node: Introduction, Next: Library, Prev: Top, Up: Top 100 101Introduction 102************ 103 104 "Termcap" is a library and data base that enables programs to use 105display terminals in a terminal-independent manner. It originated in 106Berkeley Unix. 107 108 The termcap data base describes the capabilities of hundreds of 109different display terminals in great detail. Some examples of the 110information recorded for a terminal could include how many columns wide 111it is, what string to send to move the cursor to an arbitrary position 112(including how to encode the row and column numbers), how to scroll the 113screen up one or several lines, and how much padding is needed for such 114a scrolling operation. 115 116 The termcap library is provided for easy access this data base in 117programs that want to do terminal-independent character-based display 118output. 119 120 This manual describes the GNU version of the termcap library, which 121has some extensions over the Unix version. All the extensions are 122identified as such, so this manual also tells you how to use the Unix 123termcap. 124 125 The GNU version of the termcap library is available free as source 126code, for use in free programs, and runs on Unix and VMS systems (at 127least). You can find it in the GNU Emacs distribution in the files 128`termcap.c' and `tparam.c'. 129 130 This manual was written for the GNU project, whose goal is to 131develop a complete free operating system upward-compatible with Unix 132for user programs. The project is approximately two thirds complete. 133For more information on the GNU project, including the GNU Emacs editor 134and the mostly-portable optimizing C compiler, send one dollar to 135 136 Free Software Foundation 137 675 Mass Ave 138 Cambridge, MA 02139 139 140 141File: termcap.info, Node: Library, Next: Data Base, Prev: Introduction, Up: Top 142 143The Termcap Library 144******************* 145 146 The termcap library is the application programmer's interface to the 147termcap data base. It contains functions for the following purposes: 148 149 * Finding the description of the user's terminal type (`tgetent'). 150 151 * Interrogating the description for information on various topics 152 (`tgetnum', `tgetflag', `tgetstr'). 153 154 * Computing and performing padding (`tputs'). 155 156 * Encoding numeric parameters such as cursor positions into the 157 terminal-specific form required for display commands (`tparam', 158 `tgoto'). 159 160* Menu: 161 162* Preparation:: Preparing to use the termcap library. 163* Find:: Finding the description of the terminal being used. 164* Interrogate:: Interrogating the description for particular capabilities. 165* Initialize:: Initialization for output using termcap. 166* Padding:: Outputting padding. 167* Parameters:: Encoding parameters such as cursor positions. 168 169 170File: termcap.info, Node: Preparation, Next: Find, Up: Library 171 172Preparing to Use the Termcap Library 173==================================== 174 175 To use the termcap library in a program, you need two kinds of 176preparation: 177 178 * The compiler needs declarations of the functions and variables in 179 the library. 180 181 On GNU systems, it suffices to include the header file `termcap.h' 182 in each source file that uses these functions and variables. 183 184 On Unix systems, there is often no such header file. Then you must 185 explictly declare the variables as external. You can do likewise 186 for the functions, or let them be implicitly declared and cast 187 their values from type `int' to the appropriate type. 188 189 We illustrate the declarations of the individual termcap library 190 functions with ANSI C prototypes because they show how to pass the 191 arguments. If you are not using the GNU C compiler, you probably 192 cannot use function prototypes, so omit the argument types and 193 names from your declarations. 194 195 * The linker needs to search the library. Usually either 196 `-ltermcap' or `-ltermlib' as an argument when linking will do 197 this. 198 199 200File: termcap.info, Node: Find, Next: Interrogate, Prev: Preparation, Up: Library 201 202Finding a Terminal Description: `tgetent' 203========================================= 204 205 An application program that is going to use termcap must first look 206up the description of the terminal type in use. This is done by calling 207`tgetent', whose declaration in ANSI Standard C looks like: 208 209 int tgetent (char *BUFFER, char *TERMTYPE); 210 211This function finds the description and remembers it internally so that 212you can interrogate it about specific terminal capabilities (*note 213Interrogate::.). 214 215 The argument TERMTYPE is a string which is the name for the type of 216terminal to look up. Usually you would obtain this from the environment 217variable `TERM' using `getenv ("TERM")'. 218 219 If you are using the GNU version of termcap, you can alternatively 220ask `tgetent' to allocate enough space. Pass a null pointer for 221BUFFER, and `tgetent' itself allocates the storage using `malloc'. 222There is no way to get the address that was allocated, and you 223shouldn't try to free the storage. 224 225 With the Unix version of termcap, you must allocate space for the 226description yourself and pass the address of the space as the argument 227BUFFER. There is no way you can tell how much space is needed, so the 228convention is to allocate a buffer 2048 characters long and assume that 229is enough. (Formerly the convention was to allocate 1024 characters and 230assume that was enough. But one day, for one kind of terminal, that was 231not enough.) 232 233 No matter how the space to store the description has been obtained, 234termcap records its address internally for use when you later 235interrogate the description with `tgetnum', `tgetstr' or `tgetflag'. If 236the buffer was allocated by termcap, it will be freed by termcap too if 237you call `tgetent' again. If the buffer was provided by you, you must 238make sure that its contents remain unchanged for as long as you still 239plan to interrogate the description. 240 241 The return value of `tgetent' is -1 if there is some difficulty 242accessing the data base of terminal types, 0 if the data base is 243accessible but the specified type is not defined in it, and some other 244value otherwise. 245 246 Here is how you might use the function `tgetent': 247 248 #ifdef unix 249 static char term_buffer[2048]; 250 #else 251 #define term_buffer 0 252 #endif 253 254 init_terminal_data () 255 { 256 char *termtype = getenv ("TERM"); 257 int success; 258 259 if (termtype == 0) 260 fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n"); 261 262 success = tgetent (term_buffer, termtype); 263 if (success < 0) 264 fatal ("Could not access the termcap data base.\n"); 265 if (success == 0) 266 fatal ("Terminal type `%s' is not defined.\n", termtype); 267 } 268 269Here we assume the function `fatal' prints an error message and exits. 270 271 If the environment variable `TERMCAP' is defined, its value is used 272to override the terminal type data base. The function `tgetent' checks 273the value of `TERMCAP' automatically. If the value starts with `/' 274then it is taken as a file name to use as the data base file, instead 275of `/etc/termcap' which is the standard data base. If the value does 276not start with `/' then it is itself used as the terminal description, 277provided that the terminal type TERMTYPE is among the types it claims 278to apply to. *Note Data Base::, for information on the format of a 279terminal description. 280 281 282File: termcap.info, Node: Interrogate, Next: Initialize, Prev: Find, Up: Library 283 284Interrogating the Terminal Description 285====================================== 286 287 Each piece of information recorded in a terminal description is 288called a "capability". Each defined terminal capability has a 289two-letter code name and a specific meaning. For example, the number 290of columns is named `co'. *Note Capabilities::, for definitions of all 291the standard capability names. 292 293 Once you have found the proper terminal description with `tgetent' 294(*note Find::.), your application program must "interrogate" it for 295various terminal capabilities. You must specify the two-letter code of 296the capability whose value you seek. 297 298 Capability values can be numeric, boolean (capability is either 299present or absent) or strings. Any particular capability always has 300the same value type; for example, `co' always has a numeric value, 301while `am' (automatic wrap at margin) is always a flag, and `cm' 302(cursor motion command) always has a string value. The documentation 303of each capability says which type of value it has. 304 305 There are three functions to use to get the value of a capability, 306depending on the type of value the capability has. Here are their 307declarations in ANSI C: 308 309 int tgetnum (char *NAME); 310 int tgetflag (char *NAME); 311 char *tgetstr (char *NAME, char **AREA); 312 313`tgetnum' 314 Use `tgetnum' to get a capability value that is numeric. The 315 argument NAME is the two-letter code name of the capability. If 316 the capability is present, `tgetnum' returns the numeric value 317 (which is nonnegative). If the capability is not mentioned in the 318 terminal description, `tgetnum' returns -1. 319 320`tgetflag' 321 Use `tgetflag' to get a boolean value. If the capability NAME is 322 present in the terminal description, `tgetflag' returns 1; 323 otherwise, it returns 0. 324 325`tgetstr' 326 Use `tgetstr' to get a string value. It returns a pointer to a 327 string which is the capability value, or a null pointer if the 328 capability is not present in the terminal description. 329 330 There are two ways `tgetstr' can find space to store the string 331 value: 332 333 * You can ask `tgetstr' to allocate the space. Pass a null 334 pointer for the argument AREA, and `tgetstr' will use 335 `malloc' to allocate storage big enough for the value. 336 Termcap will never free this storage or refer to it again; you 337 should free it when you are finished with it. 338 339 This method is more robust, since there is no need to guess 340 how much space is needed. But it is supported only by the GNU 341 termcap library. 342 343 * You can provide the space. Provide for the argument AREA the 344 address of a pointer variable of type `char *'. Before 345 calling `tgetstr', initialize the variable to point at 346 available space. Then `tgetstr' will store the string value 347 in that space and will increment the pointer variable to 348 point after the space that has been used. You can use the 349 same pointer variable for many calls to `tgetstr'. 350 351 There is no way to determine how much space is needed for a 352 single string, and no way for you to prevent or handle 353 overflow of the area you have provided. However, you can be 354 sure that the total size of all the string values you will 355 obtain from the terminal description is no greater than the 356 size of the description (unless you get the same capability 357 twice). You can determine that size with `strlen' on the 358 buffer you provided to `tgetent'. See below for an example. 359 360 Providing the space yourself is the only method supported by 361 the Unix version of termcap. 362 363 Note that you do not have to specify a terminal type or terminal 364description for the interrogation functions. They automatically use the 365description found by the most recent call to `tgetent'. 366 367 Here is an example of interrogating a terminal description for 368various capabilities, with conditionals to select between the Unix and 369GNU methods of providing buffer space. 370 371 char *tgetstr (); 372 373 char *cl_string, *cm_string; 374 int height; 375 int width; 376 int auto_wrap; 377 378 char PC; /* For tputs. */ 379 char *BC; /* For tgoto. */ 380 char *UP; 381 382 interrogate_terminal () 383 { 384 #ifdef UNIX 385 /* Here we assume that an explicit term_buffer 386 was provided to tgetent. */ 387 char *buffer 388 = (char *) malloc (strlen (term_buffer)); 389 #define BUFFADDR &buffer 390 #else 391 #define BUFFADDR 0 392 #endif 393 394 char *temp; 395 396 /* Extract information we will use. */ 397 cl_string = tgetstr ("cl", BUFFADDR); 398 cm_string = tgetstr ("cm", BUFFADDR); 399 auto_wrap = tgetflag ("am"); 400 height = tgetnum ("li"); 401 width = tgetnum ("co"); 402 403 /* Extract information that termcap functions use. */ 404 temp = tgetstr ("pc", BUFFADDR); 405 PC = temp ? *temp : 0; 406 BC = tgetstr ("le", BUFFADDR); 407 UP = tgetstr ("up", BUFFADDR); 408 } 409 410*Note Padding::, for information on the variable `PC'. *Note Using 411Parameters::, for information on `UP' and `BC'. 412 413 414File: termcap.info, Node: Initialize, Next: Padding, Prev: Interrogate, Up: Library 415 416Initialization for Use of Termcap 417================================= 418 419 Before starting to output commands to a terminal using termcap, an 420application program should do two things: 421 422 * Initialize various global variables which termcap library output 423 functions refer to. These include `PC' and `ospeed' for padding 424 (*note Output Padding::.) and `UP' and `BC' for cursor motion 425 (*note tgoto::.). 426 427 * Tell the kernel to turn off alteration and padding of 428 horizontal-tab characters sent to the terminal. 429 430 To turn off output processing in Berkeley Unix you would use `ioctl' 431with code `TIOCLSET' to set the bit named `LLITOUT', and clear the bits 432`ANYDELAY' using `TIOCSETN'. In POSIX or System V, you must clear the 433bit named `OPOST'. Refer to the system documentation for details. 434 435 If you do not set the terminal flags properly, some older terminals 436will not work. This is because their commands may contain the 437characters that normally signify newline, carriage return and 438horizontal tab--characters which the kernel thinks it ought to modify 439before output. 440 441 When you change the kernel's terminal flags, you must arrange to 442restore them to their normal state when your program exits. This 443implies that the program must catch fatal signals such as `SIGQUIT' and 444`SIGINT' and restore the old terminal flags before actually terminating. 445 446 Modern terminals' commands do not use these special characters, so 447if you do not care about problems with old terminals, you can leave the 448kernel's terminal flags unaltered. 449 450 451File: termcap.info, Node: Padding, Next: Parameters, Prev: Initialize, Up: Library 452 453Padding 454======= 455 456 "Padding" means outputting null characters following a terminal 457display command that takes a long time to execute. The terminal 458description says which commands require padding and how much; the 459function `tputs', described below, outputs a terminal command while 460extracting from it the padding information, and then outputs the 461padding that is necessary. 462 463* Menu: 464 465* Why Pad:: Explanation of padding. 466* Not Enough:: When there is not enough padding. 467* Describe Padding:: The data base says how much padding a terminal needs. 468* Output Padding:: Using `tputs' to output the needed padding. 469 470 471File: termcap.info, Node: Why Pad, Next: Not Enough, Up: Padding 472 473Why Pad, and How 474---------------- 475 476 Most types of terminal have commands that take longer to execute 477than they do to send over a high-speed line. For example, clearing the 478screen may take 20msec once the entire command is received. During 479that time, on a 9600 bps line, the terminal could receive about 20 480additional output characters while still busy clearing the screen. 481Every terminal has a certain amount of buffering capacity to remember 482output characters that cannot be processed yet, but too many slow 483commands in a row can cause the buffer to fill up. Then any additional 484output that cannot be processed immediately will be lost. 485 486 To avoid this problem, we normally follow each display command with 487enough useless charaters (usually null characters) to fill up the time 488that the display command needs to execute. This does the job if the 489terminal throws away null characters without using up space in the 490buffer (which most terminals do). If enough padding is used, no output 491can ever be lost. The right amount of padding avoids loss of output 492without slowing down operation, since the time used to transmit padding 493is time that nothing else could be done. 494 495 The number of padding characters needed for an operation depends on 496the line speed. In fact, it is proportional to the line speed. A 9600 497baud line transmits about one character per msec, so the clear screen 498command in the example above would need about 20 characters of padding. 499At 1200 baud, however, only about 3 characters of padding are needed 500to fill up 20msec. 501 502 503File: termcap.info, Node: Not Enough, Next: Describe Padding, Prev: Why Pad, Up: Padding 504 505When There Is Not Enough Padding 506-------------------------------- 507 508 There are several common manifestations of insufficient padding. 509 510 * Emacs displays `I-search: ^Q-' at the bottom of the screen. 511 512 This means that the terminal thought its buffer was getting full of 513 display commands, so it tried to tell the computer to stop sending 514 any. 515 516 * The screen is garbled intermittently, or the details of garbling 517 vary when you repeat the action. (A garbled screen could be due 518 to a command which is simply incorrect, or to user option in the 519 terminal which doesn't match the assumptions of the terminal 520 description, but this usually leads to reproducible failure.) 521 522 This means that the buffer did get full, and some commands were 523 lost. Many changeable factors can change which ones are lost. 524 525 * Screen is garbled at high output speeds but not at low speeds. 526 Padding problems nearly always go away at low speeds, usually even 527 at 1200 baud. 528 529 This means that a high enough speed permits commands to arrive 530 faster than they can be executed. 531 532 Although any obscure command on an obscure terminal might lack 533padding, in practice problems arise most often from the clearing 534commands `cl' and `cd' (*note Clearing::.), the scrolling commands `sf' 535and `sr' (*note Scrolling::.), and the line insert/delete commands `al' 536and `dl' (*note Insdel Line::.). 537 538 Occasionally the terminal description fails to define `sf' and some 539programs will use `do' instead, so you may get a problem with `do'. If 540so, first define `sf' just like `do', then add some padding to `sf'. 541 542 The best strategy is to add a lot of padding at first, perhaps 200 543msec. This is much more than enough; in fact, it should cause a 544visible slowdown. (If you don't see a slowdown, the change has not 545taken effect; *note Changing::..) If this makes the problem go away, 546you have found the right place to add padding; now reduce the amount 547until the problem comes back, then increase it again. If the problem 548remains, either it is in some other capability or it is not a matter of 549padding at all. 550 551 Keep in mind that on many terminals the correct padding for 552insert/delete line or for scrolling is cursor-position dependent. If 553you get problems from scrolling a large region of the screen but not 554from scrolling a small part (just a few lines moving), it may mean that 555fixed padding should be replaced with position-dependent padding. 556 557 558File: termcap.info, Node: Describe Padding, Next: Output Padding, Prev: Not Enough, Up: Padding 559 560Specifying Padding in a Terminal Description 561-------------------------------------------- 562 563 In the terminal description, the amount of padding required by each 564display command is recorded as a sequence of digits at the front of the 565command. These digits specify the padding time in milliseconds (msec). 566They can be followed optionally by a decimal point and one more digit, 567which is a number of tenths of msec. 568 569 Sometimes the padding needed by a command depends on the cursor 570position. For example, the time taken by an "insert line" command is 571usually proportional to the number of lines that need to be moved down 572or cleared. An asterisk (`*') following the padding time says that the 573time should be multiplied by the number of screen lines affected by the 574command. 575 576 :al=1.3*\E[L: 577 578is used to describe the "insert line" command for a certain terminal. 579The padding required is 1.3 msec per line affected. The command itself 580is `ESC [ L'. 581 582 The padding time specified in this way tells `tputs' how many pad 583characters to output. *Note Output Padding::. 584 585 Two special capability values affect padding for all commands. 586These are the `pc' and `pb'. The variable `pc' specifies the character 587to pad with, and `pb' the speed below which no padding is needed. The 588defaults for these variables, a null character and 0, are correct for 589most terminals. *Note Pad Specs::. 590 591 592File: termcap.info, Node: Output Padding, Prev: Describe Padding, Up: Padding 593 594Performing Padding with `tputs' 595------------------------------- 596 597 Use the termcap function `tputs' to output a string containing an 598optional padding spec of the form described above (*note Describe 599Padding::.). The function `tputs' strips off and decodes the padding 600spec, outputs the rest of the string, and then outputs the appropriate 601padding. Here is its declaration in ANSI C: 602 603 char PC; 604 short ospeed; 605 606 int tputs (char *STRING, int NLINES, int (*OUTFUN) ()); 607 608 Here STRING is the string (including padding spec) to be output; 609NLINES is the number of lines affected by the operation, which is used 610to multiply the amount of padding if the padding spec ends with a `*'. 611Finally, OUTFUN is a function (such as `fputchar') that is called to 612output each character. When actually called, OUTFUN should expect one 613argument, a character. 614 615 The operation of `tputs' is controlled by two global variables, 616`ospeed' and `PC'. The value of `ospeed' is supposed to be the 617terminal output speed, encoded as in the `ioctl' system call which gets 618the speed information. This is needed to compute the number of padding 619characters. The value of `PC' is the character used for padding. 620 621 You are responsible for storing suitable values into these variables 622before using `tputs'. The value stored into the `PC' variable should be 623taken from the `pc' capability in the terminal description (*note Pad 624Specs::.). Store zero in `PC' if there is no `pc' capability. 625 626 The argument NLINES requires some thought. Normally, it should be 627the number of lines whose contents will be cleared or moved by the 628command. For cursor motion commands, or commands that do editing 629within one line, use the value 1. For most commands that affect 630multiple lines, such as `al' (insert a line) and `cd' (clear from the 631cursor to the end of the screen), NLINES should be the screen height 632minus the current vertical position (origin 0). For multiple insert 633and scroll commands such as `AL' (insert multiple lines), that same 634value for NLINES is correct; the number of lines being inserted is not 635correct. 636 637 If a "scroll window" feature is used to reduce the number of lines 638affected by a command, the value of NLINES should take this into 639account. This is because the delay time required depends on how much 640work the terminal has to do, and the scroll window feature reduces the 641work. *Note Scrolling::. 642 643 Commands such as `ic' and `dc' (insert or delete characters) are 644problematical because the padding needed by these commands is 645proportional to the number of characters affected, which is the number 646of columns from the cursor to the end of the line. It would be nice to 647have a way to specify such a dependence, and there is no need for 648dependence on vertical position in these commands, so it is an obvious 649idea to say that for these commands NLINES should really be the number 650of columns affected. However, the definition of termcap clearly says 651that NLINES is always the number of lines affected, even in this case, 652where it is always 1. It is not easy to change this rule now, because 653too many programs and terminal descriptions have been written to follow 654it. 655 656 Because NLINES is always 1 for the `ic' and `dc' strings, there is 657no reason for them to use `*', but some of them do. These should be 658corrected by deleting the `*'. If, some day, such entries have 659disappeared, it may be possible to change to a more useful convention 660for the NLINES argument for these operations without breaking any 661programs. 662 663 664File: termcap.info, Node: Parameters, Prev: Padding, Up: Library 665 666Filling In Parameters 667===================== 668 669 Some terminal control strings require numeric "parameters". For 670example, when you move the cursor, you need to say what horizontal and 671vertical positions to move it to. The value of the terminal's `cm' 672capability, which says how to move the cursor, cannot simply be a 673string of characters; it must say how to express the cursor position 674numbers and where to put them within the command. 675 676 The specifications of termcap include conventions as to which 677string-valued capabilities require parameters, how many parameters, and 678what the parameters mean; for example, it defines the `cm' string to 679take two parameters, the vertical and horizontal positions, with 0,0 680being the upper left corner. These conventions are described where the 681individual commands are documented. 682 683 Termcap also defines a language used within the capability 684definition for specifying how and where to encode the parameters for 685output. This language uses character sequences starting with `%'. 686(This is the same idea as `printf', but the details are different.) 687The language for parameter encoding is described in this section. 688 689 A program that is doing display output calls the functions `tparam' 690or `tgoto' to encode parameters according to the specifications. These 691functions produce a string containing the actual commands to be output 692(as well a padding spec which must be processed with `tputs'; *note 693Padding::.). 694 695* Menu: 696 697* Encode Parameters:: The language for encoding parameters. 698* Using Parameters:: Outputting a string command with parameters. 699 700 701File: termcap.info, Node: Encode Parameters, Next: Using Parameters, Up: Parameters 702 703Describing the Encoding 704----------------------- 705 706 A terminal command string that requires parameters contains special 707character sequences starting with `%' to say how to encode the 708parameters. These sequences control the actions of `tparam' and 709`tgoto'. 710 711 The parameters values passed to `tparam' or `tgoto' are considered 712to form a vector. A pointer into this vector determines the next 713parameter to be processed. Some of the `%'-sequences encode one 714parameter and advance the pointer to the next parameter. Other 715`%'-sequences alter the pointer or alter the parameter values without 716generating output. 717 718 For example, the `cm' string for a standard ANSI terminal is written 719as `\E[%i%d;%dH'. (`\E' stands for ESC.) `cm' by convention always 720requires two parameters, the vertical and horizontal goal positions, so 721this string specifies the encoding of two parameters. Here `%i' 722increments the two values supplied, and each `%d' encodes one of the 723values in decimal. If the cursor position values 20,58 are encoded 724with this string, the result is `\E[21;59H'. 725 726 First, here are the `%'-sequences that generate output. Except for 727`%%', each of them encodes one parameter and advances the pointer to 728the following parameter. 729 730`%%' 731 Output a single `%'. This is the only way to represent a literal 732 `%' in a terminal command with parameters. `%%' does not use up a 733 parameter. 734 735`%d' 736 As in `printf', output the next parameter in decimal. 737 738`%2' 739 Like `%02d' in `printf': output the next parameter in decimal, and 740 always use at least two digits. 741 742`%3' 743 Like `%03d' in `printf': output the next parameter in decimal, and 744 always use at least three digits. Note that `%4' and so on are 745 *not* defined. 746 747`%.' 748 Output the next parameter as a single character whose ASCII code is 749 the parameter value. Like `%c' in `printf'. 750 751`%+CHAR' 752 Add the next parameter to the character CHAR, and output the 753 resulting character. For example, `%+ ' represents 0 as a space, 754 1 as `!', etc. 755 756 The following `%'-sequences specify alteration of the parameters 757(their values, or their order) rather than encoding a parameter for 758output. They generate no output; they are used only for their side 759effects on the parameters. Also, they do not advance the "next 760parameter" pointer except as explicitly stated. Only `%i', `%r' and 761`%>' are defined in standard Unix termcap. The others are GNU 762extensions. 763 764`%i' 765 Increment the next two parameters. This is used for terminals that 766 expect cursor positions in origin 1. For example, `%i%d,%d' would 767 output two parameters with `1' for 0, `2' for 1, etc. 768 769`%r' 770 Interchange the next two parameters. This is used for terminals 771 whose cursor positioning command expects the horizontal position 772 first. 773 774`%s' 775 Skip the next parameter. Do not output anything. 776 777`%b' 778 Back up one parameter. The last parameter used will become once 779 again the next parameter to be output, and the next output command 780 will use it. Using `%b' more than once, you can back up any 781 number of parameters, and you can refer to each parameter any 782 number of times. 783 784`%>C1C2' 785 Conditionally increment the next parameter. Here C1 and C2 are 786 characters which stand for their ASCII codes as numbers. If the 787 next parameter is greater than the ASCII code of C1, the ASCII 788 code of C2 is added to it. 789 790`%a OP TYPE POS' 791 Perform arithmetic on the next parameter, do not use it up, and do 792 not output anything. Here OP specifies the arithmetic operation, 793 while TYPE and POS together specify the other operand. 794 795 Spaces are used above to separate the operands for clarity; the 796 spaces don't appear in the data base, where this sequence is 797 exactly five characters long. 798 799 The character OP says what kind of arithmetic operation to 800 perform. It can be any of these characters: 801 802 `=' 803 assign a value to the next parameter, ignoring its old value. 804 The new value comes from the other operand. 805 806 `+' 807 add the other operand to the next parameter. 808 809 `-' 810 subtract the other operand from the next parameter. 811 812 `*' 813 multiply the next parameter by the other operand. 814 815 `/' 816 divide the next parameter by the other operand. 817 818 The "other operand" may be another parameter's value or a constant; 819 the character TYPE says which. It can be: 820 821 `p' 822 Use another parameter. The character POS says which 823 parameter to use. Subtract 64 from its ASCII code to get the 824 position of the desired parameter relative to this one. Thus, 825 the character `A' as POS means the parameter after the next 826 one; the character `?' means the parameter before the next 827 one. 828 829 `c' 830 Use a constant value. The character POS specifies the value 831 of the constant. The 0200 bit is cleared out, so that 0200 832 can be used to represent zero. 833 834 The following `%'-sequences are special purpose hacks to compensate 835for the weird designs of obscure terminals. They modify the next 836parameter or the next two parameters but do not generate output and do 837not use up any parameters. `%m' is a GNU extension; the others are 838defined in standard Unix termcap. 839 840`%n' 841 Exclusive-or the next parameter with 0140, and likewise the 842 parameter after next. 843 844`%m' 845 Complement all the bits of the next parameter and the parameter 846 after next. 847 848`%B' 849 Encode the next parameter in BCD. It alters the value of the 850 parameter by adding six times the quotient of the parameter by ten. 851 Here is a C statement that shows how the new value is computed: 852 853 PARM = (PARM / 10) * 16 + PARM % 10; 854 855`%D' 856 Transform the next parameter as needed by Delta Data terminals. 857 This involves subtracting twice the remainder of the parameter by 858 16. 859 860 PARM -= 2 * (PARM % 16); 861 862 863File: termcap.info, Node: Using Parameters, Prev: Encode Parameters, Up: Parameters 864 865Sending Display Commands with Parameters 866---------------------------------------- 867 868 The termcap library functions `tparam' and `tgoto' serve as the 869analog of `printf' for terminal string parameters. The newer function 870`tparam' is a GNU extension, more general but missing from Unix 871termcap. The original parameter-encoding function is `tgoto', which is 872preferable for cursor motion. 873 874* Menu: 875 876* tparam:: The general case, for GNU termcap only. 877* tgoto:: The special case of cursor motion. 878 879 880File: termcap.info, Node: tparam, Next: tgoto, Up: Using Parameters 881 882`tparam' 883........ 884 885 The function `tparam' can encode display commands with any number of 886parameters and allows you to specify the buffer space. It is the 887preferred function for encoding parameters for all but the `cm' 888capability. Its ANSI C declaration is as follows: 889 890 char *tparam (char *CTLSTRING, char *BUFFER, int SIZE, int PARM1,...) 891 892 The arguments are a control string CTLSTRING (the value of a terminal 893capability, presumably), an output buffer BUFFER and SIZE, and any 894number of integer parameters to be encoded. The effect of `tparam' is 895to copy the control string into the buffer, encoding parameters 896according to the `%' sequences in the control string. 897 898 You describe the output buffer by its address, BUFFER, and its size 899in bytes, SIZE. If the buffer is not big enough for the data to be 900stored in it, `tparam' calls `malloc' to get a larger buffer. In 901either case, `tparam' returns the address of the buffer it ultimately 902uses. If the value equals BUFFER, your original buffer was used. 903Otherwise, a new buffer was allocated, and you must free it after you 904are done with printing the results. If you pass zero for SIZE and 905BUFFER, `tparam' always allocates the space with `malloc'. 906 907 All capabilities that require parameters also have the ability to 908specify padding, so you should use `tputs' to output the string 909produced by `tparam'. *Note Padding::. Here is an example. 910 911 { 912 char *buf; 913 char buffer[40]; 914 915 buf = tparam (command, buffer, 40, parm); 916 tputs (buf, 1, fputchar); 917 if (buf != buffer) 918 free (buf); 919 } 920 921 If a parameter whose value is zero is encoded with `%.'-style 922encoding, the result is a null character, which will confuse `tputs'. 923This would be a serious problem, but luckily `%.' encoding is used only 924by a few old models of terminal, and only for the `cm' capability. To 925solve the problem, use `tgoto' rather than `tparam' to encode the `cm' 926capability. 927 928 929File: termcap.info, Node: tgoto, Prev: tparam, Up: Using Parameters 930 931`tgoto' 932....... 933 934 The special case of cursor motion is handled by `tgoto'. There are 935two reasons why you might choose to use `tgoto': 936 937 * For Unix compatibility, because Unix termcap does not have 938 `tparam'. 939 940 * For the `cm' capability, since `tgoto' has a special feature to 941 avoid problems with null characters, tabs and newlines on certain 942 old terminal types that use `%.' encoding for that capability. 943 944 Here is how `tgoto' might be declared in ANSI C: 945 946 char *tgoto (char *CSTRING, int HPOS, int VPOS) 947 948 There are three arguments, the terminal description's `cm' string and 949the two cursor position numbers; `tgoto' computes the parametrized 950string in an internal static buffer and returns the address of that 951buffer. The next time you use `tgoto' the same buffer will be reused. 952 953 Parameters encoded with `%.' encoding can generate null characters, 954tabs or newlines. These might cause trouble: the null character because 955`tputs' would think that was the end of the string, the tab because the 956kernel or other software might expand it into spaces, and the newline 957becaue the kernel might add a carriage-return, or padding characters 958normally used for a newline. To prevent such problems, `tgoto' is 959careful to avoid these characters. Here is how this works: if the 960target cursor position value is such as to cause a problem (that is to 961say, zero, nine or ten), `tgoto' increments it by one, then compensates 962by appending a string to move the cursor back or up one position. 963 964 The compensation strings to use for moving back or up are found in 965global variables named `BC' and `UP'. These are actual external C 966variables with upper case names; they are declared `char *'. It is up 967to you to store suitable values in them, normally obtained from the 968`le' and `up' terminal capabilities in the terminal description with 969`tgetstr'. Alternatively, if these two variables are both zero, the 970feature of avoiding nulls, tabs and newlines is turned off. 971 972 It is safe to use `tgoto' for commands other than `cm' only if you 973have stored zero in `BC' and `UP'. 974 975 Note that `tgoto' reverses the order of its operands: the horizontal 976position comes before the vertical position in the arguments to 977`tgoto', even though the vertical position comes before the horizontal 978in the parameters of the `cm' string. If you use `tgoto' with a 979command such as `AL' that takes one parameter, you must pass the 980parameter to `tgoto' as the "vertical position". 981 982 983File: termcap.info, Node: Data Base, Next: Capabilities, Prev: Library, Up: Top 984 985The Format of the Data Base 986*************************** 987 988 The termcap data base of terminal descriptions is stored in the file 989`/etc/termcap'. It contains terminal descriptions, blank lines, and 990comments. 991 992 A terminal description starts with one or more names for the 993terminal type. The information in the description is a series of 994"capability names" and values. The capability names have standard 995meanings (*note Capabilities::.) and their values describe the terminal. 996 997* Menu: 998 999* Format:: Overall format of a terminal description. 1000* Capability Format:: Format of capabilities within a description. 1001* Naming:: Naming conventions for terminal types. 1002* Inheriting:: Inheriting part of a description from 1003a related terminal type. 1004* Changing:: When changes in the data base take effect. 1005 1006 1007File: termcap.info, Node: Format, Next: Capability Format, Up: Data Base 1008 1009Terminal Description Format 1010=========================== 1011 1012 Aside from comments (lines starting with `#', which are ignored), 1013each nonblank line in the termcap data base is a terminal description. 1014A terminal description is nominally a single line, but it can be split 1015into multiple lines by inserting the two characters `\ newline'. This 1016sequence is ignored wherever it appears in a description. 1017 1018 The preferred way to split the description is between capabilities: 1019insert the four characters `: \ newline tab' immediately before any 1020colon. This allows each sub-line to start with some indentation. This 1021works because, after the `\ newline' are ignored, the result is `: tab 1022:'; the first colon ends the preceding capability and the second colon 1023starts the next capability. If you split with `\ newline' alone, you 1024may not add any indentation after them. 1025 1026 Here is a real example of a terminal description: 1027 1028 dw|vt52|DEC vt52:\ 1029 :cr=^M:do=^J:nl=^J:bl=^G:\ 1030 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\ 1031 :cm=\EY%+ %+ :co#80:li#24:\ 1032 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\ 1033 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H: 1034 1035 Each terminal description begins with several names for the terminal 1036type. The names are separated by `|' characters, and a colon ends the 1037last name. The first name should be two characters long; it exists 1038only for the sake of very old Unix systems and is never used in modern 1039systems. The last name should be a fully verbose name such as "DEC 1040vt52" or "Ann Arbor Ambassador with 48 lines". The other names should 1041include whatever the user ought to be able to specify to get this 1042terminal type, such as `vt52' or `aaa-48'. *Note Naming::, for 1043information on how to choose terminal type names. 1044 1045 After the terminal type names come the terminal capabilities, 1046separated by colons and with a colon after the last one. Each 1047capability has a two-letter name, such as `cm' for "cursor motion 1048string" or `li' for "number of display lines". 1049 1050 1051File: termcap.info, Node: Capability Format, Next: Naming, Prev: Format, Up: Data Base 1052 1053Writing the Capabilities 1054======================== 1055 1056 There are three kinds of capabilities: flags, numbers, and strings. 1057Each kind has its own way of being written in the description. Each 1058defined capability has by convention a particular kind of value; for 1059example, `li' always has a numeric value and `cm' always a string value. 1060 1061 A flag capability is thought of as having a boolean value: the value 1062is true if the capability is present, false if not. When the 1063capability is present, just write its name between two colons. 1064 1065 A numeric capability has a value which is a nonnegative number. 1066Write the capability name, a `#', and the number, between two colons. 1067For example, `...:li#48:...' is how you specify the `li' capability for 106848 lines. 1069 1070 A string-valued capability has a value which is a sequence of 1071characters. Usually these are the characters used to perform some 1072display operation. Write the capability name, a `=', and the 1073characters of the value, between two colons. For example, 1074`...:cm=\E[%i%d;%dH:...' is how the cursor motion command for a 1075standard ANSI terminal would be specified. 1076 1077 Special characters in the string value can be expressed using 1078`\'-escape sequences as in C; in addition, `\E' stands for ESC. `^' is 1079also a kind of escape character; `^' followed by CHAR stands for the 1080control-equivalent of CHAR. Thus, `^a' stands for the character 1081control-a, just like `\001'. `\' and `^' themselves can be represented 1082as `\\' and `\^'. 1083 1084 To include a colon in the string, you must write `\072'. You might 1085ask, "Why can't `\:' be used to represent a colon?" The reason is that 1086the interrogation functions do not count slashes while looking for a 1087capability. Even if `:ce=ab\:cd:' were interpreted as giving the `ce' 1088capability the value `ab:cd', it would also appear to define `cd' as a 1089flag. 1090 1091 The string value will often contain digits at the front to specify 1092padding (*note Padding::.) and/or `%'-sequences within to specify how 1093to encode parameters (*note Parameters::.). Although these things are 1094not to be output literally to the terminal, they are considered part of 1095the value of the capability. They are special only when the string 1096value is processed by `tputs', `tparam' or `tgoto'. By contrast, `\' 1097and `^' are considered part of the syntax for specifying the characters 1098in the string. 1099 1100 Let's look at the VT52 example again: 1101 1102 dw|vt52|DEC vt52:\ 1103 :cr=^M:do=^J:nl=^J:bl=^G:\ 1104 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\ 1105 :cm=\EY%+ %+ :co#80:li#24:\ 1106 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\ 1107 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H: 1108 1109 Here we see the numeric-valued capabilities `co' and `li', the flags 1110`bs' and `pt', and many string-valued capabilities. Most of the 1111strings start with ESC represented as `\E'. The rest contain control 1112characters represented using `^'. The meanings of the individual 1113capabilities are defined elsewhere (*note Capabilities::.). 1114 1115