1 This is ../info/termcap.info, produced by makeinfo version 4.0 from
5 * Termcap: (termcap). Termcap library of the GNU system.
8 This file documents the termcap library of the GNU system.
10 Copyright (C) 1988 Free Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of this
13 manual provided the copyright notice and this permission notice are
14 preserved on all copies.
16 Permission is granted to copy and distribute modified versions of
17 this manual under the conditions for verbatim copying, provided that
18 the entire resulting derived work is distributed under the terms of a
19 permission notice identical to this one.
21 Permission is granted to copy and distribute translations of this
22 manual into another language, under the above conditions for modified
23 versions, except that this permission notice may be stated in a
24 translation approved by the Foundation.
27 File: termcap.info, Node: Top, Next: Introduction, Prev: (DIR), Up: (DIR)
31 * Introduction::What is termcap? Why this manual?
32 * Library:: The termcap library functions.
33 * Data Base:: What terminal descriptions in `/etc/termcap' look like.
34 * Capabilities::Definitions of the individual terminal capabilities:
35 how to write them in descriptions, and how to use
36 their values to do display updating.
37 * Summary:: Brief table of capability names and their meanings.
38 * Var Index:: Index of C functions and variables.
39 * Cap Index:: Index of termcap capabilities.
40 * Index:: Concept index.
43 File: termcap.info, Node: Introduction, Next: Library, Prev: Top, Up: Top
48 "Termcap" is a library and data base that enables programs to use
49 display terminals in a terminal-independent manner. It originated in
52 The termcap data base describes the capabilities of hundreds of
53 different display terminals in great detail. Some examples of the
54 information recorded for a terminal could include how many columns wide
55 it is, what string to send to move the cursor to an arbitrary position
56 (including how to encode the row and column numbers), how to scroll the
57 screen up one or several lines, and how much padding is needed for such
58 a scrolling operation.
60 The termcap library is provided for easy access this data base in
61 programs that want to do terminal-independent character-based display
64 This manual describes the GNU version of the termcap library, which
65 has some extensions over the Unix version. All the extensions are
66 identified as such, so this manual also tells you how to use the Unix
69 The GNU version of the termcap library is available free as source
70 code, for use in free programs, and runs on Unix and VMS systems (at
71 least). You can find it in the GNU Emacs distribution in the files
72 `termcap.c' and `tparam.c'.
74 This manual was written for the GNU project, whose goal is to
75 develop a complete free operating system upward-compatible with Unix
76 for user programs. The project is approximately two thirds complete.
77 For more information on the GNU project, including the GNU Emacs editor
78 and the mostly-portable optimizing C compiler, send one dollar to
80 Free Software Foundation
85 File: termcap.info, Node: Library, Next: Data Base, Prev: Introduction, Up: Top
90 The termcap library is the application programmer's interface to the
91 termcap data base. It contains functions for the following purposes:
93 * Finding the description of the user's terminal type (`tgetent').
95 * Interrogating the description for information on various topics
96 (`tgetnum', `tgetflag', `tgetstr').
98 * Computing and performing padding (`tputs').
100 * Encoding numeric parameters such as cursor positions into the
101 terminal-specific form required for display commands (`tparam',
106 * Preparation:: Preparing to use the termcap library.
107 * Find:: Finding the description of the terminal being used.
108 * Interrogate:: Interrogating the description for particular capabilities.
109 * Initialize:: Initialization for output using termcap.
110 * Padding:: Outputting padding.
111 * Parameters:: Encoding parameters such as cursor positions.
114 File: termcap.info, Node: Preparation, Next: Find, Prev: Library, Up: Library
116 Preparing to Use the Termcap Library
117 ====================================
119 To use the termcap library in a program, you need two kinds of
122 * The compiler needs declarations of the functions and variables in
125 On GNU systems, it suffices to include the header file `termcap.h'
126 in each source file that uses these functions and variables.
128 On Unix systems, there is often no such header file. Then you must
129 explictly declare the variables as external. You can do likewise
130 for the functions, or let them be implicitly declared and cast
131 their values from type `int' to the appropriate type.
133 We illustrate the declarations of the individual termcap library
134 functions with ANSI C prototypes because they show how to pass the
135 arguments. If you are not using the GNU C compiler, you probably
136 cannot use function prototypes, so omit the argument types and
137 names from your declarations.
139 * The linker needs to search the library. Usually either
140 `-ltermcap' or `-ltermlib' as an argument when linking will do
144 File: termcap.info, Node: Find, Next: Interrogate, Prev: Preparation, Up: Library
146 Finding a Terminal Description: `tgetent'
147 =========================================
149 An application program that is going to use termcap must first look
150 up the description of the terminal type in use. This is done by calling
151 `tgetent', whose declaration in ANSI Standard C looks like:
153 int tgetent (char *BUFFER, char *TERMTYPE);
155 This function finds the description and remembers it internally so that
156 you can interrogate it about specific terminal capabilities (*note
159 The argument TERMTYPE is a string which is the name for the type of
160 terminal to look up. Usually you would obtain this from the environment
161 variable `TERM' using `getenv ("TERM")'.
163 If you are using the GNU version of termcap, you can alternatively
164 ask `tgetent' to allocate enough space. Pass a null pointer for
165 BUFFER, and `tgetent' itself allocates the storage using `malloc'. In
166 this case the returned value on success is the address of the storage,
167 cast to `int'. But normally there is no need for you to look at the
168 address. Do not free the storage yourself.
170 With the Unix version of termcap, you must allocate space for the
171 description yourself and pass the address of the space as the argument
172 BUFFER. There is no way you can tell how much space is needed, so the
173 convention is to allocate a buffer 2048 characters long and assume that
174 is enough. (Formerly the convention was to allocate 1024 characters and
175 assume that was enough. But one day, for one kind of terminal, that was
178 No matter how the space to store the description has been obtained,
179 termcap records its address internally for use when you later
180 interrogate the description with `tgetnum', `tgetstr' or `tgetflag'. If
181 the buffer was allocated by termcap, it will be freed by termcap too if
182 you call `tgetent' again. If the buffer was provided by you, you must
183 make sure that its contents remain unchanged for as long as you still
184 plan to interrogate the description.
186 The return value of `tgetent' is -1 if there is some difficulty
187 accessing the data base of terminal types, 0 if the data base is
188 accessible but the specified type is not defined in it, and some other
191 Here is how you might use the function `tgetent':
194 static char term_buffer[2048];
196 #define term_buffer 0
199 init_terminal_data ()
201 char *termtype = getenv ("TERM");
205 fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
207 success = tgetent (term_buffer, termtype);
209 fatal ("Could not access the termcap data base.\n");
211 fatal ("Terminal type `%s' is not defined.\n", termtype);
214 Here we assume the function `fatal' prints an error message and exits.
216 If the environment variable `TERMCAP' is defined, its value is used
217 to override the terminal type data base. The function `tgetent' checks
218 the value of `TERMCAP' automatically. If the value starts with `/'
219 then it is taken as a file name to use as the data base file, instead
220 of `/etc/termcap' which is the standard data base. If the value does
221 not start with `/' then it is itself used as the terminal description,
222 provided that the terminal type TERMTYPE is among the types it claims
223 to apply to. *Note Data Base::, for information on the format of a
224 terminal description.
227 File: termcap.info, Node: Interrogate, Next: Initialize, Prev: Find, Up: Library
229 Interrogating the Terminal Description
230 ======================================
232 Each piece of information recorded in a terminal description is
233 called a "capability". Each defined terminal capability has a
234 two-letter code name and a specific meaning. For example, the number
235 of columns is named `co'. *Note Capabilities::, for definitions of all
236 the standard capability names.
238 Once you have found the proper terminal description with `tgetent'
239 (*note Find::), your application program must "interrogate" it for
240 various terminal capabilities. You must specify the two-letter code of
241 the capability whose value you seek.
243 Capability values can be numeric, boolean (capability is either
244 present or absent) or strings. Any particular capability always has
245 the same value type; for example, `co' always has a numeric value,
246 while `am' (automatic wrap at margin) is always a flag, and `cm'
247 (cursor motion command) always has a string value. The documentation
248 of each capability says which type of value it has.
250 There are three functions to use to get the value of a capability,
251 depending on the type of value the capability has. Here are their
252 declarations in ANSI C:
254 int tgetnum (char *NAME);
255 int tgetflag (char *NAME);
256 char *tgetstr (char *NAME, char **AREA);
259 Use `tgetnum' to get a capability value that is numeric. The
260 argument NAME is the two-letter code name of the capability. If
261 the capability is present, `tgetnum' returns the numeric value
262 (which is nonnegative). If the capability is not mentioned in the
263 terminal description, `tgetnum' returns -1.
266 Use `tgetflag' to get a boolean value. If the capability NAME is
267 present in the terminal description, `tgetflag' returns 1;
268 otherwise, it returns 0.
271 Use `tgetstr' to get a string value. It returns a pointer to a
272 string which is the capability value, or a null pointer if the
273 capability is not present in the terminal description.
275 There are two ways `tgetstr' can find space to store the string
278 * You can ask `tgetstr' to allocate the space. Pass a null
279 pointer for the argument AREA, and `tgetstr' will use
280 `malloc' to allocate storage big enough for the value.
281 Termcap will never free this storage or refer to it again; you
282 should free it when you are finished with it.
284 This method is more robust, since there is no need to guess
285 how much space is needed. But it is supported only by the GNU
288 * You can provide the space. Provide for the argument AREA the
289 address of a pointer variable of type `char *'. Before
290 calling `tgetstr', initialize the variable to point at
291 available space. Then `tgetstr' will store the string value
292 in that space and will increment the pointer variable to
293 point after the space that has been used. You can use the
294 same pointer variable for many calls to `tgetstr'.
296 There is no way to determine how much space is needed for a
297 single string, and no way for you to prevent or handle
298 overflow of the area you have provided. However, you can be
299 sure that the total size of all the string values you will
300 obtain from the terminal description is no greater than the
301 size of the description (unless you get the same capability
302 twice). You can determine that size with `strlen' on the
303 buffer you provided to `tgetent'. See below for an example.
305 Providing the space yourself is the only method supported by
306 the Unix version of termcap.
308 Note that you do not have to specify a terminal type or terminal
309 description for the interrogation functions. They automatically use the
310 description found by the most recent call to `tgetent'.
312 Here is an example of interrogating a terminal description for
313 various capabilities, with conditionals to select between the Unix and
314 GNU methods of providing buffer space.
318 char *cl_string, *cm_string;
323 char PC; /* For tputs. */
324 char *BC; /* For tgoto. */
327 interrogate_terminal ()
330 /* Here we assume that an explicit term_buffer
331 was provided to tgetent. */
333 = (char *) malloc (strlen (term_buffer));
334 #define BUFFADDR &buffer
341 /* Extract information we will use. */
342 cl_string = tgetstr ("cl", BUFFADDR);
343 cm_string = tgetstr ("cm", BUFFADDR);
344 auto_wrap = tgetflag ("am");
345 height = tgetnum ("li");
346 width = tgetnum ("co");
348 /* Extract information that termcap functions use. */
349 temp = tgetstr ("pc", BUFFADDR);
350 PC = temp ? *temp : 0;
351 BC = tgetstr ("le", BUFFADDR);
352 UP = tgetstr ("up", BUFFADDR);
355 *Note Padding::, for information on the variable `PC'. *Note Using
356 Parameters::, for information on `UP' and `BC'.
359 File: termcap.info, Node: Initialize, Next: Padding, Prev: Interrogate, Up: Library
361 Initialization for Use of Termcap
362 =================================
364 Before starting to output commands to a terminal using termcap, an
365 application program should do two things:
367 * Initialize various global variables which termcap library output
368 functions refer to. These include `PC' and `ospeed' for padding
369 (*note Output Padding::) and `UP' and `BC' for cursor motion
372 * Tell the kernel to turn off alteration and padding of
373 horizontal-tab characters sent to the terminal.
375 To turn off output processing in Berkeley Unix you would use `ioctl'
376 with code `TIOCLSET' to set the bit named `LLITOUT', and clear the bits
377 `ANYDELAY' using `TIOCSETN'. In POSIX or System V, you must clear the
378 bit named `OPOST'. Refer to the system documentation for details.
380 If you do not set the terminal flags properly, some older terminals
381 will not work. This is because their commands may contain the
382 characters that normally signify newline, carriage return and
383 horizontal tab--characters which the kernel thinks it ought to modify
386 When you change the kernel's terminal flags, you must arrange to
387 restore them to their normal state when your program exits. This
388 implies that the program must catch fatal signals such as `SIGQUIT' and
389 `SIGINT' and restore the old terminal flags before actually terminating.
391 Modern terminals' commands do not use these special characters, so
392 if you do not care about problems with old terminals, you can leave the
393 kernel's terminal flags unaltered.
396 File: termcap.info, Node: Padding, Next: Parameters, Prev: Initialize, Up: Library
401 "Padding" means outputting null characters following a terminal
402 display command that takes a long time to execute. The terminal
403 description says which commands require padding and how much; the
404 function `tputs', described below, outputs a terminal command while
405 extracting from it the padding information, and then outputs the
406 padding that is necessary.
410 * Why Pad:: Explanation of padding.
411 * Describe Padding:: The data base says how much padding a terminal needs.
412 * Output Padding:: Using `tputs' to output the needed padding.
415 File: termcap.info, Node: Why Pad, Next: Describe Padding, Prev: Padding, Up: Padding
420 Most types of terminal have commands that take longer to execute
421 than they do to send over a high-speed line. For example, clearing the
422 screen may take 20msec once the entire command is received. During
423 that time, on a 9600 bps line, the terminal could receive about 20
424 additional output characters while still busy clearing the screen.
425 Every terminal has a certain amount of buffering capacity to remember
426 output characters that cannot be processed yet, but too many slow
427 commands in a row can cause the buffer to fill up. Then any additional
428 output that cannot be processed immediately will be lost.
430 To avoid this problem, we normally follow each display command with
431 enough useless charaters (usually null characters) to fill up the time
432 that the display command needs to execute. This does the job if the
433 terminal throws away null characters without using up space in the
434 buffer (which most terminals do). If enough padding is used, no output
435 can ever be lost. The right amount of padding avoids loss of output
436 without slowing down operation, since the time used to transmit padding
437 is time that nothing else could be done.
439 The number of padding characters needed for an operation depends on
440 the line speed. In fact, it is proportional to the line speed. A 9600
441 baud line transmits about one character per msec, so the clear screen
442 command in the example above would need about 20 characters of padding.
443 At 1200 baud, however, only about 3 characters of padding are needed
447 File: termcap.info, Node: Describe Padding, Next: Output Padding, Prev: Why Pad, Up: Padding
449 Specifying Padding in a Terminal Description
450 --------------------------------------------
452 In the terminal description, the amount of padding required by each
453 display command is recorded as a sequence of digits at the front of the
454 command. These digits specify the padding time in msec. They can be
455 followed optionally by a decimal point and one more digit, which is a
456 number of tenths of msec.
458 Sometimes the padding needed by a command depends on the cursor
459 position. For example, the time taken by an "insert line" command is
460 usually proportional to the number of lines that need to be moved down
461 or cleared. An asterisk (`*') following the padding time says that the
462 time should be multiplied by the number of screen lines affected by the
467 is used to describe the "insert line" command for a certain terminal.
468 The padding required is 1.3 msec per line affected. The command itself
471 The padding time specified in this way tells `tputs' how many pad
472 characters to output. *Note Output Padding::.
474 Two special capability values affect padding for all commands.
475 These are the `pc' and `pb'. The variable `pc' specifies the character
476 to pad with, and `pb' the speed below which no padding is needed. The
477 defaults for these variables, a null character and 0, are correct for
478 most terminals. *Note Pad Specs::.
481 File: termcap.info, Node: Output Padding, Prev: Describe Padding, Up: Padding
483 Performing Padding with `tputs'
484 -------------------------------
486 Use the termcap function `tputs' to output a string containing an
487 optional padding spec of the form described above (*note Describe
488 Padding::). The function `tputs' strips off and decodes the padding
489 spec, outputs the rest of the string, and then outputs the appropriate
490 padding. Here is its declaration in ANSI C:
495 int tputs (char *STRING, int NLINES, int (*OUTFUN) ());
497 Here STRING is the string (including padding spec) to be output;
498 NLINES is the number of lines affected by the operation, which is used
499 to multiply the amount of padding if the padding spec ends with a `*'.
500 Finally, OUTFUN is a function (such as `fputchar') that is called to
501 output each character. When actually called, OUTFUN should expect one
502 argument, a character.
504 The operation of `tputs' is controlled by two global variables,
505 `ospeed' and `PC'. The value of `ospeed' is supposed to be the
506 terminal output speed, encoded as in the `ioctl' system call which gets
507 the speed information. This is needed to compute the number of padding
508 characters. The value of `PC' is the character used for padding.
510 You are responsible for storing suitable values into these variables
511 before using `tputs'. The value stored into the `PC' variable should be
512 taken from the `pc' capability in the terminal description (*note Pad
513 Specs::). Store zero in `PC' if there is no `pc' capability.
515 The argument NLINES requires some thought. Normally, it should be
516 the number of lines whose contents will be cleared or moved by the
517 command. For cursor motion commands, or commands that do editing
518 within one line, use the value 1. For most commands that affect
519 multiple lines, such as `al' (insert a line) and `cd' (clear from the
520 cursor to the end of the screen), NLINES should be the screen height
521 minus the current vertical position (origin 0). For multiple insert
522 and scroll commands such as `AL' (insert multiple lines), that same
523 value for NLINES is correct; the number of lines being inserted is not
526 If a "scroll window" feature is used to reduce the number of lines
527 affected by a command, the value of NLINES should take this into
528 account. This is because the delay time required depends on how much
529 work the terminal has to do, and the scroll window feature reduces the
530 work. *Note Scrolling::.
532 Commands such as `ic' and `dc' (insert or delete characters) are
533 problematical because the padding needed by these commands is
534 proportional to the number of characters affected, which is the number
535 of columns from the cursor to the end of the line. It would be nice to
536 have a way to specify such a dependence, and there is no need for
537 dependence on vertical position in these commands, so it is an obvious
538 idea to say that for these commands NLINES should really be the number
539 of columns affected. However, the definition of termcap clearly says
540 that NLINES is always the number of lines affected, even in this case,
541 where it is always 1. It is not easy to change this rule now, because
542 too many programs and terminal descriptions have been written to follow
545 Because NLINES is always 1 for the `ic' and `dc' strings, there is
546 no reason for them to use `*', but some of them do. These should be
547 corrected by deleting the `*'. If, some day, such entries have
548 disappeared, it may be possible to change to a more useful convention
549 for the NLINES argument for these operations without breaking any
553 File: termcap.info, Node: Parameters, Prev: Padding, Up: Library
555 Filling In Parameters
556 =====================
558 Some terminal control strings require numeric "parameters". For
559 example, when you move the cursor, you need to say what horizontal and
560 vertical positions to move it to. The value of the terminal's `cm'
561 capability, which says how to move the cursor, cannot simply be a
562 string of characters; it must say how to express the cursor position
563 numbers and where to put them within the command.
565 The specifications of termcap include conventions as to which
566 string-valued capabilities require parameters, how many parameters, and
567 what the parameters mean; for example, it defines the `cm' string to
568 take two parameters, the vertical and horizontal positions, with 0,0
569 being the upper left corner. These conventions are described where the
570 individual commands are documented.
572 Termcap also defines a language used within the capability
573 definition for specifying how and where to encode the parameters for
574 output. This language uses character sequences starting with `%'.
575 (This is the same idea as `printf', but the details are different.)
576 The language for parameter encoding is described in this section.
578 A program that is doing display output calls the functions `tparam'
579 or `tgoto' to encode parameters according to the specifications. These
580 functions produce a string containing the actual commands to be output
581 (as well a padding spec which must be processed with `tputs'; *note
586 * Encode Parameters:: The language for encoding parameters.
587 * Using Parameters:: Outputting a string command with parameters.
590 File: termcap.info, Node: Encode Parameters, Next: Using Parameters, Prev: Parameters, Up: Parameters
592 Describing the Encoding
593 -----------------------
595 A terminal command string that requires parameters contains special
596 character sequences starting with `%' to say how to encode the
597 parameters. These sequences control the actions of `tparam' and
600 The parameters values passed to `tparam' or `tgoto' are considered
601 to form a vector. A pointer into this vector determines the next
602 parameter to be processed. Some of the `%'-sequences encode one
603 parameter and advance the pointer to the next parameter. Other
604 `%'-sequences alter the pointer or alter the parameter values without
607 For example, the `cm' string for a standard ANSI terminal is written
608 as `\E[%i%d;%dH'. (`\E' stands for <ESC>.) `cm' by convention always
609 requires two parameters, the vertical and horizontal goal positions, so
610 this string specifies the encoding of two parameters. Here `%i'
611 increments the two values supplied, and each `%d' encodes one of the
612 values in decimal. If the cursor position values 20,58 are encoded
613 with this string, the result is `\E[21;59H'.
615 First, here are the `%'-sequences that generate output. Except for
616 `%%', each of them encodes one parameter and advances the pointer to
617 the following parameter.
620 Output a single `%'. This is the only way to represent a literal
621 `%' in a terminal command with parameters. `%%' does not use up a
625 As in `printf', output the next parameter in decimal.
628 Like `%02d' in `printf': output the next parameter in decimal, and
629 always use at least two digits.
632 Like `%03d' in `printf': output the next parameter in decimal, and
633 always use at least three digits. Note that `%4' and so on are
637 Output the next parameter as a single character whose ASCII code is
638 the parameter value. Like `%c' in `printf'.
641 Add the next parameter to the character CHAR, and output the
642 resulting character. For example, `%+ ' represents 0 as a space,
645 The following `%'-sequences specify alteration of the parameters
646 (their values, or their order) rather than encoding a parameter for
647 output. They generate no output; they are used only for their side
648 effects on the parameters. Also, they do not advance the "next
649 parameter" pointer except as explicitly stated. Only `%i', `%r' and
650 `%>' are defined in standard Unix termcap. The others are GNU
654 Increment the next two parameters. This is used for terminals that
655 expect cursor positions in origin 1. For example, `%i%d,%d' would
656 output two parameters with `1' for 0, `2' for 1, etc.
659 Interchange the next two parameters. This is used for terminals
660 whose cursor positioning command expects the horizontal position
664 Skip the next parameter. Do not output anything.
667 Back up one parameter. The last parameter used will become once
668 again the next parameter to be output, and the next output command
669 will use it. Using `%b' more than once, you can back up any
670 number of parameters, and you can refer to each parameter any
674 Conditionally increment the next parameter. Here C1 and C2 are
675 characters which stand for their ASCII codes as numbers. If the
676 next parameter is greater than the ASCII code of C1, the ASCII
677 code of C2 is added to it.
680 Perform arithmetic on the next parameter, do not use it up, and do
681 not output anything. Here OP specifies the arithmetic operation,
682 while TYPE and POS together specify the other operand.
684 Spaces are used above to separate the operands for clarity; the
685 spaces don't appear in the data base, where this sequence is
686 exactly five characters long.
688 The character OP says what kind of arithmetic operation to
689 perform. It can be any of these characters:
692 assign a value to the next parameter, ignoring its old value.
693 The new value comes from the other operand.
696 add the other operand to the next parameter.
699 subtract the other operand from the next parameter.
702 multiply the next parameter by the other operand.
705 divide the next parameter by the other operand.
707 The "other operand" may be another parameter's value or a constant;
708 the character TYPE says which. It can be:
711 Use another parameter. The character POS says which
712 parameter to use. Subtract 64 from its ASCII code to get the
713 position of the desired parameter relative to this one. Thus,
714 the character `A' as POS means the parameter after the next
715 one; the character `?' means the parameter before the next
719 Use a constant value. The character POS specifies the value
720 of the constant. The 0200 bit is cleared out, so that 0200
721 can be used to represent zero.
723 The following `%'-sequences are special purpose hacks to compensate
724 for the weird designs of obscure terminals. They modify the next
725 parameter or the next two parameters but do not generate output and do
726 not use up any parameters. `%m' is a GNU extension; the others are
727 defined in standard Unix termcap.
730 Exclusive-or the next parameter with 0140, and likewise the
731 parameter after next.
734 Complement all the bits of the next parameter and the parameter
738 Encode the next parameter in BCD. It alters the value of the
739 parameter by adding six times the quotient of the parameter by ten.
740 Here is a C statement that shows how the new value is computed:
742 PARM = (PARM / 10) * 16 + PARM % 10;
745 Transform the next parameter as needed by Delta Data terminals.
746 This involves subtracting twice the remainder of the parameter by
749 PARM -= 2 * (PARM % 16);
752 File: termcap.info, Node: Using Parameters, Prev: Encode Parameters, Up: Parameters
754 Sending Display Commands with Parameters
755 ----------------------------------------
757 The termcap library functions `tparam' and `tgoto' serve as the
758 analog of `printf' for terminal string parameters. The newer function
759 `tparam' is a GNU extension, more general but missing from Unix
760 termcap. The original parameter-encoding function is `tgoto', which is
761 preferable for cursor motion.
765 * tparam:: The general case, for GNU termcap only.
766 * tgoto:: The special case of cursor motion.
769 File: termcap.info, Node: tparam, Next: tgoto, Prev: Using Parameters, Up: Using Parameters
774 The function `tparam' can encode display commands with any number of
775 parameters and allows you to specify the buffer space. It is the
776 preferred function for encoding parameters for all but the `cm'
777 capability. Its ANSI C declaration is as follows:
779 char *tparam (char *CTLSTRING, char *BUFFER, int SIZE, int PARM1,...)
781 The arguments are a control string CTLSTRING (the value of a terminal
782 capability, presumably), an output buffer BUFFER and SIZE, and any
783 number of integer parameters to be encoded. The effect of `tparam' is
784 to copy the control string into the buffer, encoding parameters
785 according to the `%' sequences in the control string.
787 You describe the output buffer by its address, BUFFER, and its size
788 in bytes, SIZE. If the buffer is not big enough for the data to be
789 stored in it, `tparam' calls `malloc' to get a larger buffer. In
790 either case, `tparam' returns the address of the buffer it ultimately
791 uses. If the value equals BUFFER, your original buffer was used.
792 Otherwise, a new buffer was allocated, and you must free it after you
793 are done with printing the results. If you pass zero for SIZE and
794 BUFFER, `tparam' always allocates the space with `malloc'.
796 All capabilities that require parameters also have the ability to
797 specify padding, so you should use `tputs' to output the string
798 produced by `tparam'. *Note Padding::. Here is an example.
804 buf = tparam (command, buffer, 40, parm);
805 tputs (buf, 1, fputchar);
810 If a parameter whose value is zero is encoded with `%.'-style
811 encoding, the result is a null character, which will confuse `tputs'.
812 This would be a serious problem, but luckily `%.' encoding is used only
813 by a few old models of terminal, and only for the `cm' capability. To
814 solve the problem, use `tgoto' rather than `tparam' to encode the `cm'
818 File: termcap.info, Node: tgoto, Prev: tparam, Up: Using Parameters
823 The special case of cursor motion is handled by `tgoto'. There are
824 two reasons why you might choose to use `tgoto':
826 * For Unix compatibility, because Unix termcap does not have
829 * For the `cm' capability, since `tgoto' has a special feature to
830 avoid problems with null characters, tabs and newlines on certain
831 old terminal types that use `%.' encoding for that capability.
833 Here is how `tgoto' might be declared in ANSI C:
835 char *tgoto (char *CSTRING, int HPOS, int VPOS)
837 There are three arguments, the terminal description's `cm' string and
838 the two cursor position numbers; `tgoto' computes the parametrized
839 string in an internal static buffer and returns the address of that
840 buffer. The next time you use `tgoto' the same buffer will be reused.
842 Parameters encoded with `%.' encoding can generate null characters,
843 tabs or newlines. These might cause trouble: the null character because
844 `tputs' would think that was the end of the string, the tab because the
845 kernel or other software might expand it into spaces, and the newline
846 becaue the kernel might add a carriage-return, or padding characters
847 normally used for a newline. To prevent such problems, `tgoto' is
848 careful to avoid these characters. Here is how this works: if the
849 target cursor position value is such as to cause a problem (that is to
850 say, zero, nine or ten), `tgoto' increments it by one, then compensates
851 by appending a string to move the cursor back or up one position.
853 The compensation strings to use for moving back or up are found in
854 global variables named `BC' and `UP'. These are actual external C
855 variables with upper case names; they are declared `char *'. It is up
856 to you to store suitable values in them, normally obtained from the
857 `le' and `up' terminal capabilities in the terminal description with
858 `tgetstr'. Alternatively, if these two variables are both zero, the
859 feature of avoiding nulls, tabs and newlines is turned off.
861 It is safe to use `tgoto' for commands other than `cm' only if you
862 have stored zero in `BC' and `UP'.
864 Note that `tgoto' reverses the order of its operands: the horizontal
865 position comes before the vertical position in the arguments to
866 `tgoto', even though the vertical position comes before the horizontal
867 in the parameters of the `cm' string. If you use `tgoto' with a
868 command such as `AL' that takes one parameter, you must pass the
869 parameter to `tgoto' as the "vertical position".
872 File: termcap.info, Node: Data Base, Next: Capabilities, Prev: Library, Up: Top
874 The Format of the Data Base
875 ***************************
877 The termcap data base of terminal descriptions is stored in the file
878 `/etc/termcap'. It contains terminal descriptions, blank lines, and
881 A terminal description starts with one or more names for the
882 terminal type. The information in the description is a series of
883 "capability names" and values. The capability names have standard
884 meanings (*note Capabilities::) and their values describe the terminal.
888 * Format:: Overall format of a terminal description.
889 * Capability Format:: Format of capabilities within a description.
890 * Naming:: Naming conventions for terminal types.
891 * Inheriting:: Inheriting part of a description from
892 a related terminal type.
895 File: termcap.info, Node: Format, Next: Capability Format, Prev: Data Base, Up: Data Base
897 Terminal Description Format
898 ===========================
900 Aside from comments (lines starting with `#', which are ignored),
901 each nonblank line in the termcap data base is a terminal description.
902 A terminal description is nominally a single line, but it can be split
903 into multiple lines by inserting the two characters `\ newline'. This
904 sequence is ignored wherever it appears in a description.
906 The preferred way to split the description is between capabilities:
907 insert the four characters `: \ newline tab' immediately before any
908 colon. This allows each sub-line to start with some indentation. This
909 works because, after the `\ newline' are ignored, the result is `: tab
910 :'; the first colon ends the preceding capability and the second colon
911 starts the next capability. If you split with `\ newline' alone, you
912 may not add any indentation after them.
914 Here is a real example of a terminal description:
917 :cr=^M:do=^J:nl=^J:bl=^G:\
918 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
919 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
920 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
922 Each terminal description begins with several names for the terminal
923 type. The names are separated by `|' characters, and a colon ends the
924 last name. The first name should be two characters long; it exists
925 only for the sake of very old Unix systems and is never used in modern
926 systems. The last name should be a fully verbose name such as "DEC
927 vt52" or "Ann Arbor Ambassador with 48 lines". The other names should
928 include whatever the user ought to be able to specify to get this
929 terminal type, such as `vt52' or `aaa-48'. *Note Naming::, for
930 information on how to choose terminal type names.
932 After the terminal type names come the terminal capabilities,
933 separated by colons and with a colon after the last one. Each
934 capability has a two-letter name, such as `cm' for "cursor motion
935 string" or `li' for "number of display lines".
938 File: termcap.info, Node: Capability Format, Next: Naming, Prev: Format, Up: Data Base
940 Writing the Capabilities
941 ========================
943 There are three kinds of capabilities: flags, numbers, and strings.
944 Each kind has its own way of being written in the description. Each
945 defined capability has by convention a particular kind of value; for
946 example, `li' always has a numeric value and `cm' always a string value.
948 A flag capability is thought of as having a boolean value: the value
949 is true if the capability is present, false if not. When the
950 capability is present, just write its name between two colons.
952 A numeric capability has a value which is a nonnegative number.
953 Write the capability name, a `#', and the number, between two colons.
954 For example, `...:li#48:...' is how you specify the `li' capability for
957 A string-valued capability has a value which is a sequence of
958 characters. Usually these are the characters used to perform some
959 display operation. Write the capability name, a `=', and the
960 characters of the value, between two colons. For example,
961 `...:cm=\E[%i%d;%dH:...' is how the cursor motion command for a
962 standard ANSI terminal would be specified.
964 Special characters in the string value can be expressed using
965 `\'-escape sequences as in C; in addition, `\E' stands for <ESC>. `^'
966 is also a kind of escape character; `^' followed by CHAR stands for the
967 control-equivalent of CHAR. Thus, `^a' stands for the character
968 control-a, just like `\001'. `\' and `^' themselves can be represented
971 To include a colon in the string, you must write `\072'. You might
972 ask, "Why can't `\:' be used to represent a colon?" The reason is that
973 the interrogation functions do not count slashes while looking for a
974 capability. Even if `:ce=ab\:cd:' were interpreted as giving the `ce'
975 capability the value `ab:cd', it would also appear to define `cd' as a
978 The string value will often contain digits at the front to specify
979 padding (*note Padding::) and/or `%'-sequences within to specify how to
980 encode parameters (*note Parameters::). Although these things are not
981 to be output literally to the terminal, they are considered part of the
982 value of the capability. They are special only when the string value
983 is processed by `tputs', `tparam' or `tgoto'. By contrast, `\' and `^'
984 are considered part of the syntax for specifying the characters in the
987 Let's look at the VT52 example again:
990 :cr=^M:do=^J:nl=^J:bl=^G:\
991 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
992 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
993 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
995 Here we see the numeric-valued capabilities `co' and `li', the flags
996 `bs' and `pt', and many string-valued capabilities. Most of the
997 strings start with <ESC> represented as `\E'. The rest contain control
998 characters represented using `^'. The meanings of the individual
999 capabilities are defined elsewhere (*note Capabilities::).
1002 File: termcap.info, Node: Naming, Next: Inheriting, Prev: Capability Format, Up: Data Base
1004 Terminal Type Name Conventions
1005 ==============================
1007 There are conventions for choosing names of terminal types. For one
1008 thing, all letters should be in lower case. The terminal type for a
1009 terminal in its most usual or most fundamental mode of operation should
1010 not have a hyphen in it.
1012 If the same terminal has other modes of operation which require
1013 different terminal descriptions, these variant descriptions are given
1014 names made by adding suffixes with hyphens. Such alternate descriptions
1015 are used for two reasons:
1017 * When the terminal has a switch that changes its behavior. Since
1018 the computer cannot tell how the switch is set, the user must tell
1019 the computer by choosing the appropriate terminal type name.
1021 For example, the VT-100 has a setup flag that controls whether the
1022 cursor wraps at the right margin. If this flag is set to "wrap",
1023 you must use the terminal type `vt100-am'. Otherwise you must use
1024 `vt100-nam'. Plain `vt100' is defined as a synonym for either
1025 `vt100-am' or `vt100-nam' depending on the preferences of the
1028 The standard suffix `-am' stands for "automatic margins".
1030 * To give the user a choice in how to use the terminal. This is done
1031 when the terminal has a switch that the computer normally controls.
1033 For example, the Ann Arbor Ambassador can be configured with many
1034 screen sizes ranging from 20 to 60 lines. Fewer lines make bigger
1035 characters but more lines let you see more of what you are editing.
1036 As a result, users have different preferences. Therefore, termcap
1037 provides terminal types for many screen sizes. If you choose type
1038 `aaa-30', the terminal will be configured to use 30 lines; if you
1039 choose `aaa-48', 48 lines will be used, and so on.
1041 Here is a list of standard suffixes and their conventional meanings:
1044 Short for "wide". This is a mode that gives the terminal more
1045 columns than usual. This is normally a user option.
1048 "Automatic margins". This is an alternate description for use when
1049 the terminal's margin-wrap switch is on; it contains the `am'
1050 flag. The implication is that normally the switch is off and the
1051 usual description for the terminal says that the switch is off.
1054 "No automatic margins". The opposite of `-am', this names an
1055 alternative description which lacks the `am' flag. This implies
1056 that the terminal is normally operated with the margin-wrap switch
1057 turned on, and the normal description of the terminal says so.
1060 "No arrows". This terminal description initializes the terminal to
1061 keep its arrow keys in local mode. This is a user option.
1064 "Reverse video". This terminal description causes text output for
1065 normal video to appear as reverse, and text output for reverse
1066 video to come out as normal. Often this description differs from
1067 the usual one by interchanging the two strings which turn reverse
1070 This is a user option; you can choose either the "reverse video"
1071 variant terminal type or the normal terminal type, and termcap will
1075 "Status". Says to enable use of a status line which ordinary
1076 output does not touch (*note Status Line::).
1078 Some terminals have a special line that is used only as a status
1079 line. For these terminals, there is no need for an `-s' variant;
1080 the status line commands should be defined by default. On other
1081 terminals, enabling a status line means removing one screen line
1082 from ordinary use and reducing the effective screen height. For
1083 these terminals, the user can choose the `-s' variant type to
1084 request use of a status line.
1087 Says to operate with NLINES lines on the screen, for terminals
1088 such as the Ambassador which provide this as an option. Normally
1089 this is a user option; by choosing the terminal type, you control
1090 how many lines termcap will use.
1093 Says that the terminal has NPAGES pages worth of screen memory,
1094 for terminals where this is a hardware option.
1097 Says that description is not for direct use, but only for
1098 reference in `tc' capabilities. Such a description is a kind of
1099 subroutine, because it describes the common characteristics of
1100 several variant descriptions that would use other suffixes in
1104 File: termcap.info, Node: Inheriting, Prev: Naming, Up: Data Base
1106 Inheriting from Related Descriptions
1107 ====================================
1109 When two terminal descriptions are similar, their identical parts do
1110 not need to be given twice. Instead, one of the two can be defined in
1111 terms of the other, using the `tc' capability. We say that one
1112 description "refers to" the other, or "inherits from" the other.
1114 The `tc' capability must be the last one in the terminal description,
1115 and its value is a string which is the name of another terminal type
1116 which is referred to. For example,
1118 N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
1119 :ti=\E[2J\E[30;0;0;30p:\
1120 :te=\E[60;0;0;30p\E[30;1H\E[J:\
1123 defines the terminal type `aaa-30' (also known as plain `aaa') in terms
1124 of `aaa-unk', which defines everything about the Ambassador that is
1125 independent of screen height. The types `aaa-36', `aaa-48' and so on
1126 for other screen heights are likewise defined to inherit from `aaa-unk'.
1128 The capabilities overridden by `aaa-30' include `li', which says how
1129 many lines there are, and `ti' and `te', which configure the terminal
1130 to use that many lines.
1132 The effective terminal description for type `aaa' consists of the
1133 text shown above followed by the text of the description of `aaa-unk'.
1134 The `tc' capability is handled automatically by `tgetent', which finds
1135 the description thus referenced and combines the two descriptions
1136 (*note Find::). Therefore, only the implementor of the terminal
1137 descriptions needs to think about using `tc'. Users and application
1138 programmers do not need to be concerned with it.
1140 Since the reference terminal description is used last, capabilities
1141 specified in the referring description override any specifications of
1142 the same capabilities in the reference description.
1144 The referring description can cancel out a capability without
1145 specifying any new value for it by means of a special trick. Write the
1146 capability in the referring description, with the character `@' after
1147 the capability name, as follows:
1149 NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\