1 This is Info file /home/gd/gnu/termcap/termcap.info, produced by
2 Makeinfo-1.52 from the input file /home/gd/gnu/termcap/termcap.texi.
4 This file documents the termcap library of the GNU system.
6 Copyright (C) 1988 Free Software Foundation, Inc.
8 Permission is granted to make and distribute verbatim copies of this
9 manual provided the copyright notice and this permission notice are
10 preserved on all copies.
12 Permission is granted to copy and distribute modified versions of
13 this manual under the conditions for verbatim copying, provided that
14 the entire resulting derived work is distributed under the terms of a
15 permission notice identical to this one.
17 Permission is granted to copy and distribute translations of this
18 manual into another language, under the above conditions for modified
19 versions, except that this permission notice may be stated in a
20 translation approved by the Foundation.
23 File: termcap.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
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.
38 -- The Detailed Node Listing --
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.
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.
58 * Encode Parameters:: The language for encoding parameters.
59 * Using Parameters:: Outputting a string command with parameters.
61 Sending Display Commands with Parameters
63 * tparam:: The general case, for GNU termcap only.
64 * tgoto:: The special case of cursor motion.
66 The Format of the Data Base
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
72 a related terminal type.
73 * Changing:: When changes in the data base take effect.
75 Definitions of the Terminal Capabilities
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.
99 File: termcap.info, Node: Introduction, Next: Library, Prev: Top, Up: Top
104 "Termcap" is a library and data base that enables programs to use
105 display terminals in a terminal-independent manner. It originated in
108 The termcap data base describes the capabilities of hundreds of
109 different display terminals in great detail. Some examples of the
110 information recorded for a terminal could include how many columns wide
111 it 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
113 screen up one or several lines, and how much padding is needed for such
114 a scrolling operation.
116 The termcap library is provided for easy access this data base in
117 programs that want to do terminal-independent character-based display
120 This manual describes the GNU version of the termcap library, which
121 has some extensions over the Unix version. All the extensions are
122 identified as such, so this manual also tells you how to use the Unix
125 The GNU version of the termcap library is available free as source
126 code, for use in free programs, and runs on Unix and VMS systems (at
127 least). You can find it in the GNU Emacs distribution in the files
128 `termcap.c' and `tparam.c'.
130 This manual was written for the GNU project, whose goal is to
131 develop a complete free operating system upward-compatible with Unix
132 for user programs. The project is approximately two thirds complete.
133 For more information on the GNU project, including the GNU Emacs editor
134 and the mostly-portable optimizing C compiler, send one dollar to
136 Free Software Foundation
141 File: termcap.info, Node: Library, Next: Data Base, Prev: Introduction, Up: Top
146 The termcap library is the application programmer's interface to the
147 termcap data base. It contains functions for the following purposes:
149 * Finding the description of the user's terminal type (`tgetent').
151 * Interrogating the description for information on various topics
152 (`tgetnum', `tgetflag', `tgetstr').
154 * Computing and performing padding (`tputs').
156 * Encoding numeric parameters such as cursor positions into the
157 terminal-specific form required for display commands (`tparam',
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.
170 File: termcap.info, Node: Preparation, Next: Find, Up: Library
172 Preparing to Use the Termcap Library
173 ====================================
175 To use the termcap library in a program, you need two kinds of
178 * The compiler needs declarations of the functions and variables in
181 On GNU systems, it suffices to include the header file `termcap.h'
182 in each source file that uses these functions and variables.
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.
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.
195 * The linker needs to search the library. Usually either
196 `-ltermcap' or `-ltermlib' as an argument when linking will do
200 File: termcap.info, Node: Find, Next: Interrogate, Prev: Preparation, Up: Library
202 Finding a Terminal Description: `tgetent'
203 =========================================
205 An application program that is going to use termcap must first look
206 up the description of the terminal type in use. This is done by calling
207 `tgetent', whose declaration in ANSI Standard C looks like:
209 int tgetent (char *BUFFER, char *TERMTYPE);
211 This function finds the description and remembers it internally so that
212 you can interrogate it about specific terminal capabilities (*note
215 The argument TERMTYPE is a string which is the name for the type of
216 terminal to look up. Usually you would obtain this from the environment
217 variable `TERM' using `getenv ("TERM")'.
219 If you are using the GNU version of termcap, you can alternatively
220 ask `tgetent' to allocate enough space. Pass a null pointer for
221 BUFFER, and `tgetent' itself allocates the storage using `malloc'. In
222 this case the returned value on success is the address of the storage,
223 cast to `int'. But normally there is no need for you to look at the
224 address. Do not free the storage yourself.
226 With the Unix version of termcap, you must allocate space for the
227 description yourself and pass the address of the space as the argument
228 BUFFER. There is no way you can tell how much space is needed, so the
229 convention is to allocate a buffer 2048 characters long and assume that
230 is enough. (Formerly the convention was to allocate 1024 characters and
231 assume that was enough. But one day, for one kind of terminal, that was
234 No matter how the space to store the description has been obtained,
235 termcap records its address internally for use when you later
236 interrogate the description with `tgetnum', `tgetstr' or `tgetflag'. If
237 the buffer was allocated by termcap, it will be freed by termcap too if
238 you call `tgetent' again. If the buffer was provided by you, you must
239 make sure that its contents remain unchanged for as long as you still
240 plan to interrogate the description.
242 The return value of `tgetent' is -1 if there is some difficulty
243 accessing the data base of terminal types, 0 if the data base is
244 accessible but the specified type is not defined in it, and some other
247 Here is how you might use the function `tgetent':
250 static char term_buffer[2048];
252 #define term_buffer 0
255 init_terminal_data ()
257 char *termtype = getenv ("TERM");
261 fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
263 success = tgetent (term_buffer, termtype);
265 fatal ("Could not access the termcap data base.\n");
267 fatal ("Terminal type `%s' is not defined.\n", termtype);
270 Here we assume the function `fatal' prints an error message and exits.
272 If the environment variable `TERMCAP' is defined, its value is used
273 to override the terminal type data base. The function `tgetent' checks
274 the value of `TERMCAP' automatically. If the value starts with `/'
275 then it is taken as a file name to use as the data base file, instead
276 of `/etc/termcap' which is the standard data base. If the value does
277 not start with `/' then it is itself used as the terminal description,
278 provided that the terminal type TERMTYPE is among the types it claims
279 to apply to. *Note Data Base::, for information on the format of a
280 terminal description.
283 File: termcap.info, Node: Interrogate, Next: Initialize, Prev: Find, Up: Library
285 Interrogating the Terminal Description
286 ======================================
288 Each piece of information recorded in a terminal description is
289 called a "capability". Each defined terminal capability has a
290 two-letter code name and a specific meaning. For example, the number
291 of columns is named `co'. *Note Capabilities::, for definitions of all
292 the standard capability names.
294 Once you have found the proper terminal description with `tgetent'
295 (*note Find::.), your application program must "interrogate" it for
296 various terminal capabilities. You must specify the two-letter code of
297 the capability whose value you seek.
299 Capability values can be numeric, boolean (capability is either
300 present or absent) or strings. Any particular capability always has
301 the same value type; for example, `co' always has a numeric value,
302 while `am' (automatic wrap at margin) is always a flag, and `cm'
303 (cursor motion command) always has a string value. The documentation
304 of each capability says which type of value it has.
306 There are three functions to use to get the value of a capability,
307 depending on the type of value the capability has. Here are their
308 declarations in ANSI C:
310 int tgetnum (char *NAME);
311 int tgetflag (char *NAME);
312 char *tgetstr (char *NAME, char **AREA);
315 Use `tgetnum' to get a capability value that is numeric. The
316 argument NAME is the two-letter code name of the capability. If
317 the capability is present, `tgetnum' returns the numeric value
318 (which is nonnegative). If the capability is not mentioned in the
319 terminal description, `tgetnum' returns -1.
322 Use `tgetflag' to get a boolean value. If the capability NAME is
323 present in the terminal description, `tgetflag' returns 1;
324 otherwise, it returns 0.
327 Use `tgetstr' to get a string value. It returns a pointer to a
328 string which is the capability value, or a null pointer if the
329 capability is not present in the terminal description.
331 There are two ways `tgetstr' can find space to store the string
334 * You can ask `tgetstr' to allocate the space. Pass a null
335 pointer for the argument AREA, and `tgetstr' will use
336 `malloc' to allocate storage big enough for the value.
337 Termcap will never free this storage or refer to it again; you
338 should free it when you are finished with it.
340 This method is more robust, since there is no need to guess
341 how much space is needed. But it is supported only by the GNU
344 * You can provide the space. Provide for the argument AREA the
345 address of a pointer variable of type `char *'. Before
346 calling `tgetstr', initialize the variable to point at
347 available space. Then `tgetstr' will store the string value
348 in that space and will increment the pointer variable to
349 point after the space that has been used. You can use the
350 same pointer variable for many calls to `tgetstr'.
352 There is no way to determine how much space is needed for a
353 single string, and no way for you to prevent or handle
354 overflow of the area you have provided. However, you can be
355 sure that the total size of all the string values you will
356 obtain from the terminal description is no greater than the
357 size of the description (unless you get the same capability
358 twice). You can determine that size with `strlen' on the
359 buffer you provided to `tgetent'. See below for an example.
361 Providing the space yourself is the only method supported by
362 the Unix version of termcap.
364 Note that you do not have to specify a terminal type or terminal
365 description for the interrogation functions. They automatically use the
366 description found by the most recent call to `tgetent'.
368 Here is an example of interrogating a terminal description for
369 various capabilities, with conditionals to select between the Unix and
370 GNU methods of providing buffer space.
374 char *cl_string, *cm_string;
379 char PC; /* For tputs. */
380 char *BC; /* For tgoto. */
383 interrogate_terminal ()
386 /* Here we assume that an explicit term_buffer
387 was provided to tgetent. */
389 = (char *) malloc (strlen (term_buffer));
390 #define BUFFADDR &buffer
397 /* Extract information we will use. */
398 cl_string = tgetstr ("cl", BUFFADDR);
399 cm_string = tgetstr ("cm", BUFFADDR);
400 auto_wrap = tgetflag ("am");
401 height = tgetnum ("li");
402 width = tgetnum ("co");
404 /* Extract information that termcap functions use. */
405 temp = tgetstr ("pc", BUFFADDR);
406 PC = temp ? *temp : 0;
407 BC = tgetstr ("le", BUFFADDR);
408 UP = tgetstr ("up", BUFFADDR);
411 *Note Padding::, for information on the variable `PC'. *Note Using
412 Parameters::, for information on `UP' and `BC'.
415 File: termcap.info, Node: Initialize, Next: Padding, Prev: Interrogate, Up: Library
417 Initialization for Use of Termcap
418 =================================
420 Before starting to output commands to a terminal using termcap, an
421 application program should do two things:
423 * Initialize various global variables which termcap library output
424 functions refer to. These include `PC' and `ospeed' for padding
425 (*note Output Padding::.) and `UP' and `BC' for cursor motion
428 * Tell the kernel to turn off alteration and padding of
429 horizontal-tab characters sent to the terminal.
431 To turn off output processing in Berkeley Unix you would use `ioctl'
432 with code `TIOCLSET' to set the bit named `LLITOUT', and clear the bits
433 `ANYDELAY' using `TIOCSETN'. In POSIX or System V, you must clear the
434 bit named `OPOST'. Refer to the system documentation for details.
436 If you do not set the terminal flags properly, some older terminals
437 will not work. This is because their commands may contain the
438 characters that normally signify newline, carriage return and
439 horizontal tab--characters which the kernel thinks it ought to modify
442 When you change the kernel's terminal flags, you must arrange to
443 restore them to their normal state when your program exits. This
444 implies that the program must catch fatal signals such as `SIGQUIT' and
445 `SIGINT' and restore the old terminal flags before actually terminating.
447 Modern terminals' commands do not use these special characters, so
448 if you do not care about problems with old terminals, you can leave the
449 kernel's terminal flags unaltered.
452 File: termcap.info, Node: Padding, Next: Parameters, Prev: Initialize, Up: Library
457 "Padding" means outputting null characters following a terminal
458 display command that takes a long time to execute. The terminal
459 description says which commands require padding and how much; the
460 function `tputs', described below, outputs a terminal command while
461 extracting from it the padding information, and then outputs the
462 padding that is necessary.
466 * Why Pad:: Explanation of padding.
467 * Not Enough:: When there is not enough padding.
468 * Describe Padding:: The data base says how much padding a terminal needs.
469 * Output Padding:: Using `tputs' to output the needed padding.
472 File: termcap.info, Node: Why Pad, Next: Not Enough, Up: Padding
477 Most types of terminal have commands that take longer to execute
478 than they do to send over a high-speed line. For example, clearing the
479 screen may take 20msec once the entire command is received. During
480 that time, on a 9600 bps line, the terminal could receive about 20
481 additional output characters while still busy clearing the screen.
482 Every terminal has a certain amount of buffering capacity to remember
483 output characters that cannot be processed yet, but too many slow
484 commands in a row can cause the buffer to fill up. Then any additional
485 output that cannot be processed immediately will be lost.
487 To avoid this problem, we normally follow each display command with
488 enough useless charaters (usually null characters) to fill up the time
489 that the display command needs to execute. This does the job if the
490 terminal throws away null characters without using up space in the
491 buffer (which most terminals do). If enough padding is used, no output
492 can ever be lost. The right amount of padding avoids loss of output
493 without slowing down operation, since the time used to transmit padding
494 is time that nothing else could be done.
496 The number of padding characters needed for an operation depends on
497 the line speed. In fact, it is proportional to the line speed. A 9600
498 baud line transmits about one character per msec, so the clear screen
499 command in the example above would need about 20 characters of padding.
500 At 1200 baud, however, only about 3 characters of padding are needed
504 File: termcap.info, Node: Not Enough, Next: Describe Padding, Prev: Why Pad, Up: Padding
506 When There Is Not Enough Padding
507 --------------------------------
509 There are several common manifestations of insufficient padding.
511 * Emacs displays `I-search: ^Q-' at the bottom of the screen.
513 This means that the terminal thought its buffer was getting full of
514 display commands, so it tried to tell the computer to stop sending
517 * The screen is garbled intermittently, or the details of garbling
518 vary when you repeat the action. (A garbled screen could be due
519 to a command which is simply incorrect, or to user option in the
520 terminal which doesn't match the assumptions of the terminal
521 description, but this usually leads to reproducible failure.)
523 This means that the buffer did get full, and some commands were
524 lost. Many changeable factors can change which ones are lost.
526 * Screen is garbled at high output speeds but not at low speeds.
527 Padding problems nearly always go away at low speeds, usually even
530 This means that a high enough speed permits commands to arrive
531 faster than they can be executed.
533 Although any obscure command on an obscure terminal might lack
534 padding, in practice problems arise most often from the clearing
535 commands `cl' and `cd' (*note Clearing::.), the scrolling commands `sf'
536 and `sr' (*note Scrolling::.), and the line insert/delete commands `al'
537 and `dl' (*note Insdel Line::.).
539 Occasionally the terminal description fails to define `sf' and some
540 programs will use `do' instead, so you may get a problem with `do'. If
541 so, first define `sf' just like `do', then add some padding to `sf'.
543 The best strategy is to add a lot of padding at first, perhaps 200
544 msec. This is much more than enough; in fact, it should cause a
545 visible slowdown. (If you don't see a slowdown, the change has not
546 taken effect; *note Changing::..) If this makes the problem go away,
547 you have found the right place to add padding; now reduce the amount
548 until the problem comes back, then increase it again. If the problem
549 remains, either it is in some other capability or it is not a matter of
552 Keep in mind that on many terminals the correct padding for
553 insert/delete line or for scrolling is cursor-position dependent. If
554 you get problems from scrolling a large region of the screen but not
555 from scrolling a small part (just a few lines moving), it may mean that
556 fixed padding should be replaced with position-dependent padding.
559 File: termcap.info, Node: Describe Padding, Next: Output Padding, Prev: Not Enough, Up: Padding
561 Specifying Padding in a Terminal Description
562 --------------------------------------------
564 In the terminal description, the amount of padding required by each
565 display command is recorded as a sequence of digits at the front of the
566 command. These digits specify the padding time in milliseconds (msec).
567 They can be followed optionally by a decimal point and one more digit,
568 which is a number of tenths of msec.
570 Sometimes the padding needed by a command depends on the cursor
571 position. For example, the time taken by an "insert line" command is
572 usually proportional to the number of lines that need to be moved down
573 or cleared. An asterisk (`*') following the padding time says that the
574 time should be multiplied by the number of screen lines affected by the
579 is used to describe the "insert line" command for a certain terminal.
580 The padding required is 1.3 msec per line affected. The command itself
583 The padding time specified in this way tells `tputs' how many pad
584 characters to output. *Note Output Padding::.
586 Two special capability values affect padding for all commands.
587 These are the `pc' and `pb'. The variable `pc' specifies the character
588 to pad with, and `pb' the speed below which no padding is needed. The
589 defaults for these variables, a null character and 0, are correct for
590 most terminals. *Note Pad Specs::.
593 File: termcap.info, Node: Output Padding, Prev: Describe Padding, Up: Padding
595 Performing Padding with `tputs'
596 -------------------------------
598 Use the termcap function `tputs' to output a string containing an
599 optional padding spec of the form described above (*note Describe
600 Padding::.). The function `tputs' strips off and decodes the padding
601 spec, outputs the rest of the string, and then outputs the appropriate
602 padding. Here is its declaration in ANSI C:
607 int tputs (char *STRING, int NLINES, int (*OUTFUN) ());
609 Here STRING is the string (including padding spec) to be output;
610 NLINES is the number of lines affected by the operation, which is used
611 to multiply the amount of padding if the padding spec ends with a `*'.
612 Finally, OUTFUN is a function (such as `fputchar') that is called to
613 output each character. When actually called, OUTFUN should expect one
614 argument, a character.
616 The operation of `tputs' is controlled by two global variables,
617 `ospeed' and `PC'. The value of `ospeed' is supposed to be the
618 terminal output speed, encoded as in the `ioctl' system call which gets
619 the speed information. This is needed to compute the number of padding
620 characters. The value of `PC' is the character used for padding.
622 You are responsible for storing suitable values into these variables
623 before using `tputs'. The value stored into the `PC' variable should be
624 taken from the `pc' capability in the terminal description (*note Pad
625 Specs::.). Store zero in `PC' if there is no `pc' capability.
627 The argument NLINES requires some thought. Normally, it should be
628 the number of lines whose contents will be cleared or moved by the
629 command. For cursor motion commands, or commands that do editing
630 within one line, use the value 1. For most commands that affect
631 multiple lines, such as `al' (insert a line) and `cd' (clear from the
632 cursor to the end of the screen), NLINES should be the screen height
633 minus the current vertical position (origin 0). For multiple insert
634 and scroll commands such as `AL' (insert multiple lines), that same
635 value for NLINES is correct; the number of lines being inserted is not
638 If a "scroll window" feature is used to reduce the number of lines
639 affected by a command, the value of NLINES should take this into
640 account. This is because the delay time required depends on how much
641 work the terminal has to do, and the scroll window feature reduces the
642 work. *Note Scrolling::.
644 Commands such as `ic' and `dc' (insert or delete characters) are
645 problematical because the padding needed by these commands is
646 proportional to the number of characters affected, which is the number
647 of columns from the cursor to the end of the line. It would be nice to
648 have a way to specify such a dependence, and there is no need for
649 dependence on vertical position in these commands, so it is an obvious
650 idea to say that for these commands NLINES should really be the number
651 of columns affected. However, the definition of termcap clearly says
652 that NLINES is always the number of lines affected, even in this case,
653 where it is always 1. It is not easy to change this rule now, because
654 too many programs and terminal descriptions have been written to follow
657 Because NLINES is always 1 for the `ic' and `dc' strings, there is
658 no reason for them to use `*', but some of them do. These should be
659 corrected by deleting the `*'. If, some day, such entries have
660 disappeared, it may be possible to change to a more useful convention
661 for the NLINES argument for these operations without breaking any
665 File: termcap.info, Node: Parameters, Prev: Padding, Up: Library
667 Filling In Parameters
668 =====================
670 Some terminal control strings require numeric "parameters". For
671 example, when you move the cursor, you need to say what horizontal and
672 vertical positions to move it to. The value of the terminal's `cm'
673 capability, which says how to move the cursor, cannot simply be a
674 string of characters; it must say how to express the cursor position
675 numbers and where to put them within the command.
677 The specifications of termcap include conventions as to which
678 string-valued capabilities require parameters, how many parameters, and
679 what the parameters mean; for example, it defines the `cm' string to
680 take two parameters, the vertical and horizontal positions, with 0,0
681 being the upper left corner. These conventions are described where the
682 individual commands are documented.
684 Termcap also defines a language used within the capability
685 definition for specifying how and where to encode the parameters for
686 output. This language uses character sequences starting with `%'.
687 (This is the same idea as `printf', but the details are different.)
688 The language for parameter encoding is described in this section.
690 A program that is doing display output calls the functions `tparam'
691 or `tgoto' to encode parameters according to the specifications. These
692 functions produce a string containing the actual commands to be output
693 (as well a padding spec which must be processed with `tputs'; *note
698 * Encode Parameters:: The language for encoding parameters.
699 * Using Parameters:: Outputting a string command with parameters.
702 File: termcap.info, Node: Encode Parameters, Next: Using Parameters, Up: Parameters
704 Describing the Encoding
705 -----------------------
707 A terminal command string that requires parameters contains special
708 character sequences starting with `%' to say how to encode the
709 parameters. These sequences control the actions of `tparam' and
712 The parameters values passed to `tparam' or `tgoto' are considered
713 to form a vector. A pointer into this vector determines the next
714 parameter to be processed. Some of the `%'-sequences encode one
715 parameter and advance the pointer to the next parameter. Other
716 `%'-sequences alter the pointer or alter the parameter values without
719 For example, the `cm' string for a standard ANSI terminal is written
720 as `\E[%i%d;%dH'. (`\E' stands for ESC.) `cm' by convention always
721 requires two parameters, the vertical and horizontal goal positions, so
722 this string specifies the encoding of two parameters. Here `%i'
723 increments the two values supplied, and each `%d' encodes one of the
724 values in decimal. If the cursor position values 20,58 are encoded
725 with this string, the result is `\E[21;59H'.
727 First, here are the `%'-sequences that generate output. Except for
728 `%%', each of them encodes one parameter and advances the pointer to
729 the following parameter.
732 Output a single `%'. This is the only way to represent a literal
733 `%' in a terminal command with parameters. `%%' does not use up a
737 As in `printf', output the next parameter in decimal.
740 Like `%02d' in `printf': output the next parameter in decimal, and
741 always use at least two digits.
744 Like `%03d' in `printf': output the next parameter in decimal, and
745 always use at least three digits. Note that `%4' and so on are
749 Output the next parameter as a single character whose ASCII code is
750 the parameter value. Like `%c' in `printf'.
753 Add the next parameter to the character CHAR, and output the
754 resulting character. For example, `%+ ' represents 0 as a space,
757 The following `%'-sequences specify alteration of the parameters
758 (their values, or their order) rather than encoding a parameter for
759 output. They generate no output; they are used only for their side
760 effects on the parameters. Also, they do not advance the "next
761 parameter" pointer except as explicitly stated. Only `%i', `%r' and
762 `%>' are defined in standard Unix termcap. The others are GNU
766 Increment the next two parameters. This is used for terminals that
767 expect cursor positions in origin 1. For example, `%i%d,%d' would
768 output two parameters with `1' for 0, `2' for 1, etc.
771 Interchange the next two parameters. This is used for terminals
772 whose cursor positioning command expects the horizontal position
776 Skip the next parameter. Do not output anything.
779 Back up one parameter. The last parameter used will become once
780 again the next parameter to be output, and the next output command
781 will use it. Using `%b' more than once, you can back up any
782 number of parameters, and you can refer to each parameter any
786 Conditionally increment the next parameter. Here C1 and C2 are
787 characters which stand for their ASCII codes as numbers. If the
788 next parameter is greater than the ASCII code of C1, the ASCII
789 code of C2 is added to it.
792 Perform arithmetic on the next parameter, do not use it up, and do
793 not output anything. Here OP specifies the arithmetic operation,
794 while TYPE and POS together specify the other operand.
796 Spaces are used above to separate the operands for clarity; the
797 spaces don't appear in the data base, where this sequence is
798 exactly five characters long.
800 The character OP says what kind of arithmetic operation to
801 perform. It can be any of these characters:
804 assign a value to the next parameter, ignoring its old value.
805 The new value comes from the other operand.
808 add the other operand to the next parameter.
811 subtract the other operand from the next parameter.
814 multiply the next parameter by the other operand.
817 divide the next parameter by the other operand.
819 The "other operand" may be another parameter's value or a constant;
820 the character TYPE says which. It can be:
823 Use another parameter. The character POS says which
824 parameter to use. Subtract 64 from its ASCII code to get the
825 position of the desired parameter relative to this one. Thus,
826 the character `A' as POS means the parameter after the next
827 one; the character `?' means the parameter before the next
831 Use a constant value. The character POS specifies the value
832 of the constant. The 0200 bit is cleared out, so that 0200
833 can be used to represent zero.
835 The following `%'-sequences are special purpose hacks to compensate
836 for the weird designs of obscure terminals. They modify the next
837 parameter or the next two parameters but do not generate output and do
838 not use up any parameters. `%m' is a GNU extension; the others are
839 defined in standard Unix termcap.
842 Exclusive-or the next parameter with 0140, and likewise the
843 parameter after next.
846 Complement all the bits of the next parameter and the parameter
850 Encode the next parameter in BCD. It alters the value of the
851 parameter by adding six times the quotient of the parameter by ten.
852 Here is a C statement that shows how the new value is computed:
854 PARM = (PARM / 10) * 16 + PARM % 10;
857 Transform the next parameter as needed by Delta Data terminals.
858 This involves subtracting twice the remainder of the parameter by
861 PARM -= 2 * (PARM % 16);
864 File: termcap.info, Node: Using Parameters, Prev: Encode Parameters, Up: Parameters
866 Sending Display Commands with Parameters
867 ----------------------------------------
869 The termcap library functions `tparam' and `tgoto' serve as the
870 analog of `printf' for terminal string parameters. The newer function
871 `tparam' is a GNU extension, more general but missing from Unix
872 termcap. The original parameter-encoding function is `tgoto', which is
873 preferable for cursor motion.
877 * tparam:: The general case, for GNU termcap only.
878 * tgoto:: The special case of cursor motion.
881 File: termcap.info, Node: tparam, Next: tgoto, Up: Using Parameters
886 The function `tparam' can encode display commands with any number of
887 parameters and allows you to specify the buffer space. It is the
888 preferred function for encoding parameters for all but the `cm'
889 capability. Its ANSI C declaration is as follows:
891 char *tparam (char *CTLSTRING, char *BUFFER, int SIZE, int PARM1,...)
893 The arguments are a control string CTLSTRING (the value of a terminal
894 capability, presumably), an output buffer BUFFER and SIZE, and any
895 number of integer parameters to be encoded. The effect of `tparam' is
896 to copy the control string into the buffer, encoding parameters
897 according to the `%' sequences in the control string.
899 You describe the output buffer by its address, BUFFER, and its size
900 in bytes, SIZE. If the buffer is not big enough for the data to be
901 stored in it, `tparam' calls `malloc' to get a larger buffer. In
902 either case, `tparam' returns the address of the buffer it ultimately
903 uses. If the value equals BUFFER, your original buffer was used.
904 Otherwise, a new buffer was allocated, and you must free it after you
905 are done with printing the results. If you pass zero for SIZE and
906 BUFFER, `tparam' always allocates the space with `malloc'.
908 All capabilities that require parameters also have the ability to
909 specify padding, so you should use `tputs' to output the string
910 produced by `tparam'. *Note Padding::. Here is an example.
916 buf = tparam (command, buffer, 40, parm);
917 tputs (buf, 1, fputchar);
922 If a parameter whose value is zero is encoded with `%.'-style
923 encoding, the result is a null character, which will confuse `tputs'.
924 This would be a serious problem, but luckily `%.' encoding is used only
925 by a few old models of terminal, and only for the `cm' capability. To
926 solve the problem, use `tgoto' rather than `tparam' to encode the `cm'
930 File: termcap.info, Node: tgoto, Prev: tparam, Up: Using Parameters
935 The special case of cursor motion is handled by `tgoto'. There are
936 two reasons why you might choose to use `tgoto':
938 * For Unix compatibility, because Unix termcap does not have
941 * For the `cm' capability, since `tgoto' has a special feature to
942 avoid problems with null characters, tabs and newlines on certain
943 old terminal types that use `%.' encoding for that capability.
945 Here is how `tgoto' might be declared in ANSI C:
947 char *tgoto (char *CSTRING, int HPOS, int VPOS)
949 There are three arguments, the terminal description's `cm' string and
950 the two cursor position numbers; `tgoto' computes the parametrized
951 string in an internal static buffer and returns the address of that
952 buffer. The next time you use `tgoto' the same buffer will be reused.
954 Parameters encoded with `%.' encoding can generate null characters,
955 tabs or newlines. These might cause trouble: the null character because
956 `tputs' would think that was the end of the string, the tab because the
957 kernel or other software might expand it into spaces, and the newline
958 becaue the kernel might add a carriage-return, or padding characters
959 normally used for a newline. To prevent such problems, `tgoto' is
960 careful to avoid these characters. Here is how this works: if the
961 target cursor position value is such as to cause a problem (that is to
962 say, zero, nine or ten), `tgoto' increments it by one, then compensates
963 by appending a string to move the cursor back or up one position.
965 The compensation strings to use for moving back or up are found in
966 global variables named `BC' and `UP'. These are actual external C
967 variables with upper case names; they are declared `char *'. It is up
968 to you to store suitable values in them, normally obtained from the
969 `le' and `up' terminal capabilities in the terminal description with
970 `tgetstr'. Alternatively, if these two variables are both zero, the
971 feature of avoiding nulls, tabs and newlines is turned off.
973 It is safe to use `tgoto' for commands other than `cm' only if you
974 have stored zero in `BC' and `UP'.
976 Note that `tgoto' reverses the order of its operands: the horizontal
977 position comes before the vertical position in the arguments to
978 `tgoto', even though the vertical position comes before the horizontal
979 in the parameters of the `cm' string. If you use `tgoto' with a
980 command such as `AL' that takes one parameter, you must pass the
981 parameter to `tgoto' as the "vertical position".
984 File: termcap.info, Node: Data Base, Next: Capabilities, Prev: Library, Up: Top
986 The Format of the Data Base
987 ***************************
989 The termcap data base of terminal descriptions is stored in the file
990 `/etc/termcap'. It contains terminal descriptions, blank lines, and
993 A terminal description starts with one or more names for the
994 terminal type. The information in the description is a series of
995 "capability names" and values. The capability names have standard
996 meanings (*note Capabilities::.) and their values describe the terminal.
1000 * Format:: Overall format of a terminal description.
1001 * Capability Format:: Format of capabilities within a description.
1002 * Naming:: Naming conventions for terminal types.
1003 * Inheriting:: Inheriting part of a description from
1004 a related terminal type.
1005 * Changing:: When changes in the data base take effect.
1008 File: termcap.info, Node: Format, Next: Capability Format, Up: Data Base
1010 Terminal Description Format
1011 ===========================
1013 Aside from comments (lines starting with `#', which are ignored),
1014 each nonblank line in the termcap data base is a terminal description.
1015 A terminal description is nominally a single line, but it can be split
1016 into multiple lines by inserting the two characters `\ newline'. This
1017 sequence is ignored wherever it appears in a description.
1019 The preferred way to split the description is between capabilities:
1020 insert the four characters `: \ newline tab' immediately before any
1021 colon. This allows each sub-line to start with some indentation. This
1022 works because, after the `\ newline' are ignored, the result is `: tab
1023 :'; the first colon ends the preceding capability and the second colon
1024 starts the next capability. If you split with `\ newline' alone, you
1025 may not add any indentation after them.
1027 Here is a real example of a terminal description:
1030 :cr=^M:do=^J:nl=^J:bl=^G:\
1031 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\
1032 :cm=\EY%+ %+ :co#80:li#24:\
1033 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
1034 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
1036 Each terminal description begins with several names for the terminal
1037 type. The names are separated by `|' characters, and a colon ends the
1038 last name. The first name should be two characters long; it exists
1039 only for the sake of very old Unix systems and is never used in modern
1040 systems. The last name should be a fully verbose name such as "DEC
1041 vt52" or "Ann Arbor Ambassador with 48 lines". The other names should
1042 include whatever the user ought to be able to specify to get this
1043 terminal type, such as `vt52' or `aaa-48'. *Note Naming::, for
1044 information on how to choose terminal type names.
1046 After the terminal type names come the terminal capabilities,
1047 separated by colons and with a colon after the last one. Each
1048 capability has a two-letter name, such as `cm' for "cursor motion
1049 string" or `li' for "number of display lines".
1052 File: termcap.info, Node: Capability Format, Next: Naming, Prev: Format, Up: Data Base
1054 Writing the Capabilities
1055 ========================
1057 There are three kinds of capabilities: flags, numbers, and strings.
1058 Each kind has its own way of being written in the description. Each
1059 defined capability has by convention a particular kind of value; for
1060 example, `li' always has a numeric value and `cm' always a string value.
1062 A flag capability is thought of as having a boolean value: the value
1063 is true if the capability is present, false if not. When the
1064 capability is present, just write its name between two colons.
1066 A numeric capability has a value which is a nonnegative number.
1067 Write the capability name, a `#', and the number, between two colons.
1068 For example, `...:li#48:...' is how you specify the `li' capability for
1071 A string-valued capability has a value which is a sequence of
1072 characters. Usually these are the characters used to perform some
1073 display operation. Write the capability name, a `=', and the
1074 characters of the value, between two colons. For example,
1075 `...:cm=\E[%i%d;%dH:...' is how the cursor motion command for a
1076 standard ANSI terminal would be specified.
1078 Special characters in the string value can be expressed using
1079 `\'-escape sequences as in C; in addition, `\E' stands for ESC. `^' is
1080 also a kind of escape character; `^' followed by CHAR stands for the
1081 control-equivalent of CHAR. Thus, `^a' stands for the character
1082 control-a, just like `\001'. `\' and `^' themselves can be represented
1085 To include a colon in the string, you must write `\072'. You might
1086 ask, "Why can't `\:' be used to represent a colon?" The reason is that
1087 the interrogation functions do not count slashes while looking for a
1088 capability. Even if `:ce=ab\:cd:' were interpreted as giving the `ce'
1089 capability the value `ab:cd', it would also appear to define `cd' as a
1092 The string value will often contain digits at the front to specify
1093 padding (*note Padding::.) and/or `%'-sequences within to specify how
1094 to encode parameters (*note Parameters::.). Although these things are
1095 not to be output literally to the terminal, they are considered part of
1096 the value of the capability. They are special only when the string
1097 value is processed by `tputs', `tparam' or `tgoto'. By contrast, `\'
1098 and `^' are considered part of the syntax for specifying the characters
1101 Let's look at the VT52 example again:
1104 :cr=^M:do=^J:nl=^J:bl=^G:\
1105 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\
1106 :cm=\EY%+ %+ :co#80:li#24:\
1107 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
1108 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
1110 Here we see the numeric-valued capabilities `co' and `li', the flags
1111 `bs' and `pt', and many string-valued capabilities. Most of the
1112 strings start with ESC represented as `\E'. The rest contain control
1113 characters represented using `^'. The meanings of the individual
1114 capabilities are defined elsewhere (*note Capabilities::.).