1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../info/termcap.info
3 @settitle The Termcap Library
5 This file documents the termcap library of the GNU system.
7 Copyright (C) 1988 Free Software Foundation, Inc.
9 Permission is granted to make and distribute verbatim copies of
10 this manual provided the copyright notice and this permission notice
11 are preserved on all copies.
14 Permission is granted to process this file through TeX and print the
15 results, provided the printed document carries copying permission
16 notice identical to this one except for the removal of this paragraph
17 (this paragraph not being relevant to the printed manual).
20 Permission is granted to copy and distribute modified versions of this
21 manual under the conditions for verbatim copying, provided that the entire
22 resulting derived work is distributed under the terms of a permission
23 notice identical to this one.
25 Permission is granted to copy and distribute translations of this manual
26 into another language, under the above conditions for modified versions,
27 except that this permission notice may be stated in a translation approved
31 @setchapternewpage odd
34 @center @titlefont{Termcap}
36 @center The Termcap Library and Data Base
42 @center Richard M. Stallman
44 @center Free Software Foundation
46 @vskip 0pt plus 1filll
47 Copyright @copyright{} 1988 Free Software Foundation, Inc.
49 Published by the Free Software Foundation
50 (675 Mass Ave, Cambridge MA 02139).
51 Printed copies are available for $10 each.
53 Permission is granted to make and distribute verbatim copies of
54 this manual provided the copyright notice and this permission notice
55 are preserved on all copies.
57 Permission is granted to copy and distribute modified versions of this
58 manual under the conditions for verbatim copying, provided that the entire
59 resulting derived work is distributed under the terms of a permission
60 notice identical to this one.
62 Permission is granted to copy and distribute translations of this manual
63 into another language, under the above conditions for modified versions,
64 except that this permission notice may be stated in a translation approved
71 @node Top, Introduction, (DIR), (DIR)
74 * Introduction::What is termcap? Why this manual?
75 * Library:: The termcap library functions.
76 * Data Base:: What terminal descriptions in @file{/etc/termcap} look like.
77 * Capabilities::Definitions of the individual terminal capabilities:
78 how to write them in descriptions, and how to use
79 their values to do display updating.
80 * Summary:: Brief table of capability names and their meanings.
81 * Var Index:: Index of C functions and variables.
82 * Cap Index:: Index of termcap capabilities.
83 * Index:: Concept index.
86 @node Introduction, Library, Top, Top
87 @unnumbered Introduction
90 @dfn{Termcap} is a library and data base that enables programs to use
91 display terminals in a terminal-independent manner. It originated in
94 The termcap data base describes the capabilities of hundreds of different
95 display terminals in great detail. Some examples of the information
96 recorded for a terminal could include how many columns wide it is, what
97 string to send to move the cursor to an arbitrary position (including how
98 to encode the row and column numbers), how to scroll the screen up one or
99 several lines, and how much padding is needed for such a scrolling
102 The termcap library is provided for easy access this data base in programs
103 that want to do terminal-independent character-based display output.
105 This manual describes the GNU version of the termcap library, which has
106 some extensions over the Unix version. All the extensions are identified
107 as such, so this manual also tells you how to use the Unix termcap.
109 The GNU version of the termcap library is available free as source code,
110 for use in free programs, and runs on Unix and VMS systems (at least). You
111 can find it in the GNU Emacs distribution in the files @file{termcap.c} and
114 This manual was written for the GNU project, whose goal is to develop a
115 complete free operating system upward-compatible with Unix for user
116 programs. The project is approximately two thirds complete. For more
117 information on the GNU project, including the GNU Emacs editor and the
118 mostly-portable optimizing C compiler, send one dollar to
121 Free Software Foundation
126 @node Library, Data Base, Introduction, Top
127 @chapter The Termcap Library
129 The termcap library is the application programmer's interface to the
130 termcap data base. It contains functions for the following purposes:
134 Finding the description of the user's terminal type (@code{tgetent}).
137 Interrogating the description for information on various topics
138 (@code{tgetnum}, @code{tgetflag}, @code{tgetstr}).
141 Computing and performing padding (@code{tputs}).
144 Encoding numeric parameters such as cursor positions into the
145 terminal-specific form required for display commands (@code{tparam},
150 * Preparation:: Preparing to use the termcap library.
151 * Find:: Finding the description of the terminal being used.
152 * Interrogate:: Interrogating the description for particular capabilities.
153 * Initialize:: Initialization for output using termcap.
154 * Padding:: Outputting padding.
155 * Parameters:: Encoding parameters such as cursor positions.
158 @node Preparation, Find, Library, Library
159 @section Preparing to Use the Termcap Library
161 To use the termcap library in a program, you need two kinds of preparation:
165 The compiler needs declarations of the functions and variables in the
168 On GNU systems, it suffices to include the header file
169 @file{termcap.h} in each source file that uses these functions and
172 On Unix systems, there is often no such header file. Then you must
173 explictly declare the variables as external. You can do likewise for
174 the functions, or let them be implicitly declared and cast their
175 values from type @code{int} to the appropriate type.
177 We illustrate the declarations of the individual termcap library
178 functions with ANSI C prototypes because they show how to pass the
179 arguments. If you are not using the GNU C compiler, you probably
180 cannot use function prototypes, so omit the argument types and names
181 from your declarations.
184 The linker needs to search the library. Usually either
185 @samp{-ltermcap} or @samp{-ltermlib} as an argument when linking will
189 @node Find, Interrogate, Preparation, Library
190 @section Finding a Terminal Description: @code{tgetent}
193 An application program that is going to use termcap must first look up the
194 description of the terminal type in use. This is done by calling
195 @code{tgetent}, whose declaration in ANSI Standard C looks like:
198 int tgetent (char *@var{buffer}, char *@var{termtype});
202 This function finds the description and remembers it internally so that
203 you can interrogate it about specific terminal capabilities
204 (@pxref{Interrogate}).
206 The argument @var{termtype} is a string which is the name for the type of
207 terminal to look up. Usually you would obtain this from the environment
208 variable @code{TERM} using @code{getenv ("TERM")}.
210 If you are using the GNU version of termcap, you can alternatively ask
211 @code{tgetent} to allocate enough space. Pass a null pointer for
212 @var{buffer}, and @code{tgetent} itself allocates the storage using
213 @code{malloc}. In this case the returned value on success is the address
214 of the storage, cast to @code{int}. But normally there is no need for you
215 to look at the address. Do not free the storage yourself.@refill
217 With the Unix version of termcap, you must allocate space for the
218 description yourself and pass the address of the space as the argument
219 @var{buffer}. There is no way you can tell how much space is needed, so
220 the convention is to allocate a buffer 2048 characters long and assume that
221 is enough. (Formerly the convention was to allocate 1024 characters and
222 assume that was enough. But one day, for one kind of terminal, that was
225 No matter how the space to store the description has been obtained,
226 termcap records its address internally for use when you later interrogate
227 the description with @code{tgetnum}, @code{tgetstr} or @code{tgetflag}. If
228 the buffer was allocated by termcap, it will be freed by termcap too if you
229 call @code{tgetent} again. If the buffer was provided by you, you must
230 make sure that its contents remain unchanged for as long as you still plan
231 to interrogate the description.@refill
233 The return value of @code{tgetent} is @minus{}1 if there is some difficulty
234 accessing the data base of terminal types, 0 if the data base is accessible
235 but the specified type is not defined in it, and some other value
238 Here is how you might use the function @code{tgetent}:
242 static char term_buffer[2048];
244 #define term_buffer 0
247 init_terminal_data ()
249 char *termtype = getenv ("TERM");
253 fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
255 success = tgetent (term_buffer, termtype);
257 fatal ("Could not access the termcap data base.\n");
259 fatal ("Terminal type `%s' is not defined.\n", termtype);
264 Here we assume the function @code{fatal} prints an error message and exits.
266 If the environment variable @code{TERMCAP} is defined, its value is used to
267 override the terminal type data base. The function @code{tgetent} checks
268 the value of @code{TERMCAP} automatically. If the value starts with
269 @samp{/} then it is taken as a file name to use as the data base file,
270 instead of @file{/etc/termcap} which is the standard data base. If the
271 value does not start with @samp{/} then it is itself used as the terminal
272 description, provided that the terminal type @var{termtype} is among the
273 types it claims to apply to. @xref{Data Base}, for information on the
274 format of a terminal description.@refill
276 @node Interrogate, Initialize, Find, Library
277 @section Interrogating the Terminal Description
279 Each piece of information recorded in a terminal description is called a
280 @dfn{capability}. Each defined terminal capability has a two-letter code
281 name and a specific meaning. For example, the number of columns is named
282 @samp{co}. @xref{Capabilities}, for definitions of all the standard
285 Once you have found the proper terminal description with @code{tgetent}
286 (@pxref{Find}), your application program must @dfn{interrogate} it for
287 various terminal capabilities. You must specify the two-letter code of
288 the capability whose value you seek.
290 Capability values can be numeric, boolean (capability is either present or
291 absent) or strings. Any particular capability always has the same value
292 type; for example, @samp{co} always has a numeric value, while @samp{am}
293 (automatic wrap at margin) is always a flag, and @samp{cm} (cursor motion
294 command) always has a string value. The documentation of each capability
295 says which type of value it has.@refill
297 There are three functions to use to get the value of a capability,
298 depending on the type of value the capability has. Here are their
299 declarations in ANSI C:
305 int tgetnum (char *@var{name});
306 int tgetflag (char *@var{name});
307 char *tgetstr (char *@var{name}, char **@var{area});
312 Use @code{tgetnum} to get a capability value that is numeric. The
313 argument @var{name} is the two-letter code name of the capability. If
314 the capability is present, @code{tgetnum} returns the numeric value
315 (which is nonnegative). If the capability is not mentioned in the
316 terminal description, @code{tgetnum} returns @minus{}1.
319 Use @code{tgetflag} to get a boolean value. If the capability
320 @var{name} is present in the terminal description, @code{tgetflag}
321 returns 1; otherwise, it returns 0.
324 Use @code{tgetstr} to get a string value. It returns a pointer to a
325 string which is the capability value, or a null pointer if the
326 capability is not present in the terminal description.
328 There are two ways @code{tgetstr} can find space to store the string value:
332 You can ask @code{tgetstr} to allocate the space. Pass a null
333 pointer for the argument @var{area}, and @code{tgetstr} will use
334 @code{malloc} to allocate storage big enough for the value.
335 Termcap will never free this storage or refer to it again; you
336 should free it when you are finished with it.
338 This method is more robust, since there is no need to guess how
339 much space is needed. But it is supported only by the GNU
343 You can provide the space. Provide for the argument @var{area} the
344 address of a pointer variable of type @code{char *}. Before calling
345 @code{tgetstr}, initialize the variable to point at available space.
346 Then @code{tgetstr} will store the string value in that space and will
347 increment the pointer variable to point after the space that has been
348 used. You can use the same pointer variable for many calls to
351 There is no way to determine how much space is needed for a single
352 string, and no way for you to prevent or handle overflow of the area
353 you have provided. However, you can be sure that the total size of
354 all the string values you will obtain from the terminal description is
355 no greater than the size of the description (unless you get the same
356 capability twice). You can determine that size with @code{strlen} on
357 the buffer you provided to @code{tgetent}. See below for an example.
359 Providing the space yourself is the only method supported by the Unix
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 @code{tgetent}.
368 Here is an example of interrogating a terminal description for various
369 capabilities, with conditionals to select between the Unix and GNU methods
370 of providing buffer space.
375 char *cl_string, *cm_string;
380 char PC; /* For tputs. */
381 char *BC; /* For tgoto. */
384 interrogate_terminal ()
387 /* Here we assume that an explicit term_buffer
388 was provided to tgetent. */
390 = (char *) malloc (strlen (term_buffer));
391 #define BUFFADDR &buffer
398 /* Extract information we will use. */
399 cl_string = tgetstr ("cl", BUFFADDR);
400 cm_string = tgetstr ("cm", BUFFADDR);
401 auto_wrap = tgetflag ("am");
402 height = tgetnum ("li");
403 width = tgetnum ("co");
405 /* Extract information that termcap functions use. */
406 temp = tgetstr ("pc", BUFFADDR);
407 PC = temp ? *temp : 0;
408 BC = tgetstr ("le", BUFFADDR);
409 UP = tgetstr ("up", BUFFADDR);
414 @xref{Padding}, for information on the variable @code{PC}. @xref{Using
415 Parameters}, for information on @code{UP} and @code{BC}.
417 @node Initialize, Padding, Interrogate, Library
418 @section Initialization for Use of Termcap
419 @cindex terminal flags (kernel)
421 Before starting to output commands to a terminal using termcap,
422 an application program should do two things:
426 Initialize various global variables which termcap library output
427 functions refer to. These include @code{PC} and @code{ospeed} for
428 padding (@pxref{Output Padding}) and @code{UP} and @code{BC} for
429 cursor motion (@pxref{tgoto}).@refill
432 Tell the kernel to turn off alteration and padding of horizontal-tab
433 characters sent to the terminal.
436 To turn off output processing in Berkeley Unix you would use @code{ioctl}
437 with code @code{TIOCLSET} to set the bit named @code{LLITOUT}, and clear
438 the bits @code{ANYDELAY} using @code{TIOCSETN}. In POSIX or System V, you
439 must clear the bit named @code{OPOST}. Refer to the system documentation
442 If you do not set the terminal flags properly, some older terminals will
443 not work. This is because their commands may contain the characters that
444 normally signify newline, carriage return and horizontal tab---characters
445 which the kernel thinks it ought to modify before output.
447 When you change the kernel's terminal flags, you must arrange to restore
448 them to their normal state when your program exits. This implies that the
449 program must catch fatal signals such as @code{SIGQUIT} and @code{SIGINT}
450 and restore the old terminal flags before actually terminating.
452 Modern terminals' commands do not use these special characters, so if you
453 do not care about problems with old terminals, you can leave the kernel's
454 terminal flags unaltered.
456 @node Padding, Parameters, Initialize, Library
460 @dfn{Padding} means outputting null characters following a terminal display
461 command that takes a long time to execute. The terminal description says
462 which commands require padding and how much; the function @code{tputs},
463 described below, outputs a terminal command while extracting from it the
464 padding information, and then outputs the padding that is necessary.
467 * Why Pad:: Explanation of padding.
468 * Describe Padding:: The data base says how much padding a terminal needs.
469 * Output Padding:: Using @code{tputs} to output the needed padding.
472 @node Why Pad, Describe Padding, Padding, Padding
473 @subsection Why Pad, and How
475 Most types of terminal have commands that take longer to execute than they
476 do to send over a high-speed line. For example, clearing the screen may
477 take 20msec once the entire command is received. During that time, on a
478 9600 bps line, the terminal could receive about 20 additional output
479 characters while still busy clearing the screen. Every terminal has a
480 certain amount of buffering capacity to remember output characters that
481 cannot be processed yet, but too many slow commands in a row can cause the
482 buffer to fill up. Then any additional output that cannot be processed
483 immediately will be lost.
485 To avoid this problem, we normally follow each display command with enough
486 useless charaters (usually null characters) to fill up the time that the
487 display command needs to execute. This does the job if the terminal throws
488 away null characters without using up space in the buffer (which most
489 terminals do). If enough padding is used, no output can ever be lost. The
490 right amount of padding avoids loss of output without slowing down
491 operation, since the time used to transmit padding is time that nothing
494 The number of padding characters needed for an operation depends on the
495 line speed. In fact, it is proportional to the line speed. A 9600 baud
496 line transmits about one character per msec, so the clear screen command in
497 the example above would need about 20 characters of padding. At 1200 baud,
498 however, only about 3 characters of padding are needed to fill up 20msec.
500 @node Describe Padding, Output Padding, Why Pad, Padding
501 @subsection Specifying Padding in a Terminal Description
503 In the terminal description, the amount of padding required by each display
504 command is recorded as a sequence of digits at the front of the command.
505 These digits specify the padding time in msec. They can be followed
506 optionally by a decimal point and one more digit, which is a number of
509 Sometimes the padding needed by a command depends on the cursor position.
510 For example, the time taken by an ``insert line'' command is usually
511 proportional to the number of lines that need to be moved down or cleared.
512 An asterisk (@samp{*}) following the padding time says that the time
513 should be multiplied by the number of screen lines affected by the command.
520 is used to describe the ``insert line'' command for a certain terminal.
521 The padding required is 1.3 msec per line affected. The command itself is
522 @samp{@key{ESC} [ L}.
524 The padding time specified in this way tells @code{tputs} how many pad
525 characters to output. @xref{Output Padding}.
527 Two special capability values affect padding for all commands. These are
528 the @samp{pc} and @samp{pb}. The variable @samp{pc} specifies the
529 character to pad with, and @samp{pb} the speed below which no padding is
530 needed. The defaults for these variables, a null character and 0,
531 are correct for most terminals. @xref{Pad Specs}.
533 @node Output Padding,, Describe Padding, Padding
534 @subsection Performing Padding with @code{tputs}
538 Use the termcap function @code{tputs} to output a string containing an
539 optional padding spec of the form described above (@pxref{Describe
540 Padding}). The function @code{tputs} strips off and decodes the padding
541 spec, outputs the rest of the string, and then outputs the appropriate
542 padding. Here is its declaration in ANSI C:
548 int tputs (char *@var{string}, int @var{nlines}, int (*@var{outfun}) ());
551 Here @var{string} is the string (including padding spec) to be output;
552 @var{nlines} is the number of lines affected by the operation, which is
553 used to multiply the amount of padding if the padding spec ends with a
554 @samp{*}. Finally, @var{outfun} is a function (such as @code{fputchar})
555 that is called to output each character. When actually called,
556 @var{outfun} should expect one argument, a character.
560 The operation of @code{tputs} is controlled by two global variables,
561 @code{ospeed} and @code{PC}. The value of @code{ospeed} is supposed to be
562 the terminal output speed, encoded as in the @code{ioctl} system call which
563 gets the speed information. This is needed to compute the number of
564 padding characters. The value of @code{PC} is the character used for
567 You are responsible for storing suitable values into these variables before
568 using @code{tputs}. The value stored into the @code{PC} variable should be
569 taken from the @samp{pc} capability in the terminal description (@pxref{Pad
570 Specs}). Store zero in @code{PC} if there is no @samp{pc}
573 The argument @var{nlines} requires some thought. Normally, it should be
574 the number of lines whose contents will be cleared or moved by the command.
575 For cursor motion commands, or commands that do editing within one line,
576 use the value 1. For most commands that affect multiple lines, such as
577 @samp{al} (insert a line) and @samp{cd} (clear from the cursor to the end
578 of the screen), @var{nlines} should be the screen height minus the current
579 vertical position (origin 0). For multiple insert and scroll commands such
580 as @samp{AL} (insert multiple lines), that same value for @var{nlines} is
581 correct; the number of lines being inserted is @i{not} correct.@refill
583 If a ``scroll window'' feature is used to reduce the number of lines
584 affected by a command, the value of @var{nlines} should take this into
585 account. This is because the delay time required depends on how much work
586 the terminal has to do, and the scroll window feature reduces the work.
589 Commands such as @samp{ic} and @samp{dc} (insert or delete characters) are
590 problematical because the padding needed by these commands is proportional
591 to the number of characters affected, which is the number of columns from
592 the cursor to the end of the line. It would be nice to have a way to
593 specify such a dependence, and there is no need for dependence on vertical
594 position in these commands, so it is an obvious idea to say that for these
595 commands @var{nlines} should really be the number of columns affected.
596 However, the definition of termcap clearly says that @var{nlines} is always
597 the number of lines affected, even in this case, where it is always 1. It
598 is not easy to change this rule now, because too many programs and terminal
599 descriptions have been written to follow it.
601 Because @var{nlines} is always 1 for the @samp{ic} and @samp{dc} strings,
602 there is no reason for them to use @samp{*}, but some of them do. These
603 should be corrected by deleting the @samp{*}. If, some day, such entries
604 have disappeared, it may be possible to change to a more useful convention
605 for the @var{nlines} argument for these operations without breaking any
608 @node Parameters,, Padding, Library
609 @section Filling In Parameters
612 Some terminal control strings require numeric @dfn{parameters}. For
613 example, when you move the cursor, you need to say what horizontal and
614 vertical positions to move it to. The value of the terminal's @samp{cm}
615 capability, which says how to move the cursor, cannot simply be a string of
616 characters; it must say how to express the cursor position numbers and
617 where to put them within the command.
619 The specifications of termcap include conventions as to which string-valued
620 capabilities require parameters, how many parameters, and what the
621 parameters mean; for example, it defines the @samp{cm} string to take
622 two parameters, the vertical and horizontal positions, with 0,0 being the
623 upper left corner. These conventions are described where the individual
624 commands are documented.
626 Termcap also defines a language used within the capability definition for
627 specifying how and where to encode the parameters for output. This language
628 uses character sequences starting with @samp{%}. (This is the same idea as
629 @code{printf}, but the details are different.) The language for parameter
630 encoding is described in this section.
632 A program that is doing display output calls the functions @code{tparam} or
633 @code{tgoto} to encode parameters according to the specifications. These
634 functions produce a string containing the actual commands to be output (as
635 well a padding spec which must be processed with @code{tputs};
639 * Encode Parameters:: The language for encoding parameters.
640 * Using Parameters:: Outputting a string command with parameters.
643 @node Encode Parameters, Using Parameters, Parameters, Parameters
644 @subsection Describing the Encoding
647 A terminal command string that requires parameters contains special
648 character sequences starting with @samp{%} to say how to encode the
649 parameters. These sequences control the actions of @code{tparam} and
652 The parameters values passed to @code{tparam} or @code{tgoto} are
653 considered to form a vector. A pointer into this vector determines
654 the next parameter to be processed. Some of the @samp{%}-sequences
655 encode one parameter and advance the pointer to the next parameter.
656 Other @samp{%}-sequences alter the pointer or alter the parameter
657 values without generating output.
659 For example, the @samp{cm} string for a standard ANSI terminal is written
660 as @samp{\E[%i%d;%dH}. (@samp{\E} stands for @key{ESC}.) @samp{cm} by
661 convention always requires two parameters, the vertical and horizontal goal
662 positions, so this string specifies the encoding of two parameters. Here
663 @samp{%i} increments the two values supplied, and each @samp{%d} encodes
664 one of the values in decimal. If the cursor position values 20,58 are
665 encoded with this string, the result is @samp{\E[21;59H}.
667 First, here are the @samp{%}-sequences that generate output. Except for
668 @samp{%%}, each of them encodes one parameter and advances the pointer
669 to the following parameter.
673 Output a single @samp{%}. This is the only way to represent a literal
674 @samp{%} in a terminal command with parameters. @samp{%%} does not
678 As in @code{printf}, output the next parameter in decimal.
681 Like @samp{%02d} in @code{printf}: output the next parameter in
682 decimal, and always use at least two digits.
685 Like @samp{%03d} in @code{printf}: output the next parameter in
686 decimal, and always use at least three digits. Note that @samp{%4}
687 and so on are @emph{not} defined.
690 Output the next parameter as a single character whose ASCII code is
691 the parameter value. Like @samp{%c} in @code{printf}.
694 Add the next parameter to the character @var{char}, and output the
695 resulting character. For example, @samp{%+ } represents 0 as a space,
699 The following @samp{%}-sequences specify alteration of the parameters
700 (their values, or their order) rather than encoding a parameter for output.
701 They generate no output; they are used only for their side effects
702 on the parameters. Also, they do not advance the ``next parameter'' pointer
703 except as explicitly stated. Only @samp{%i}, @samp{%r} and @samp{%>} are
704 defined in standard Unix termcap. The others are GNU extensions.@refill
708 Increment the next two parameters. This is used for terminals that
709 expect cursor positions in origin 1. For example, @samp{%i%d,%d} would
710 output two parameters with @samp{1} for 0, @samp{2} for 1, etc.
713 Interchange the next two parameters. This is used for terminals whose
714 cursor positioning command expects the horizontal position first.
717 Skip the next parameter. Do not output anything.
720 Back up one parameter. The last parameter used will become once again
721 the next parameter to be output, and the next output command will use
722 it. Using @samp{%b} more than once, you can back up any number of
723 parameters, and you can refer to each parameter any number of times.
725 @item %>@var{c1}@var{c2}
726 Conditionally increment the next parameter. Here @var{c1} and
727 @var{c2} are characters which stand for their ASCII codes as numbers.
728 If the next parameter is greater than the ASCII code of @var{c1}, the
729 ASCII code of @var{c2} is added to it.@refill
731 @item %a @var{op} @var{type} @var{pos}
732 Perform arithmetic on the next parameter, do not use it up, and do not
733 output anything. Here @var{op} specifies the arithmetic operation,
734 while @var{type} and @var{pos} together specify the other operand.
736 Spaces are used above to separate the operands for clarity; the spaces
737 don't appear in the data base, where this sequence is exactly five
740 The character @var{op} says what kind of arithmetic operation to
741 perform. It can be any of these characters:
745 assign a value to the next parameter, ignoring its old value.
746 The new value comes from the other operand.
749 add the other operand to the next parameter.
752 subtract the other operand from the next parameter.
755 multiply the next parameter by the other operand.
758 divide the next parameter by the other operand.
761 The ``other operand'' may be another parameter's value or a constant;
762 the character @var{type} says which. It can be:
766 Use another parameter. The character @var{pos} says which
767 parameter to use. Subtract 64 from its ASCII code to get the
768 position of the desired parameter relative to this one. Thus,
769 the character @samp{A} as @var{pos} means the parameter after the
770 next one; the character @samp{?} means the parameter before the
774 Use a constant value. The character @var{pos} specifies the
775 value of the constant. The 0200 bit is cleared out, so that 0200
776 can be used to represent zero.
780 The following @samp{%}-sequences are special purpose hacks to compensate
781 for the weird designs of obscure terminals. They modify the next parameter
782 or the next two parameters but do not generate output and do not use up any
783 parameters. @samp{%m} is a GNU extension; the others are defined in
784 standard Unix termcap.
788 Exclusive-or the next parameter with 0140, and likewise the parameter
792 Complement all the bits of the next parameter and the parameter after next.
795 Encode the next parameter in BCD. It alters the value of the
796 parameter by adding six times the quotient of the parameter by ten.
797 Here is a C statement that shows how the new value is computed:
800 @var{parm} = (@var{parm} / 10) * 16 + @var{parm} % 10;
804 Transform the next parameter as needed by Delta Data terminals.
805 This involves subtracting twice the remainder of the parameter by 16.
808 @var{parm} -= 2 * (@var{parm} % 16);
812 @node Using Parameters,, Encode Parameters, Parameters
813 @subsection Sending Display Commands with Parameters
815 The termcap library functions @code{tparam} and @code{tgoto} serve as the
816 analog of @code{printf} for terminal string parameters. The newer function
817 @code{tparam} is a GNU extension, more general but missing from Unix
818 termcap. The original parameter-encoding function is @code{tgoto}, which
819 is preferable for cursor motion.
822 * tparam:: The general case, for GNU termcap only.
823 * tgoto:: The special case of cursor motion.
826 @node tparam, tgoto, Using Parameters, Using Parameters
827 @subsubsection @code{tparam}
830 The function @code{tparam} can encode display commands with any number of
831 parameters and allows you to specify the buffer space. It is the preferred
832 function for encoding parameters for all but the @samp{cm} capability. Its
833 ANSI C declaration is as follows:
836 char *tparam (char *@var{ctlstring}, char *@var{buffer}, int @var{size}, int @var{parm1},...)
839 The arguments are a control string @var{ctlstring} (the value of a terminal
840 capability, presumably), an output buffer @var{buffer} and @var{size}, and
841 any number of integer parameters to be encoded. The effect of
842 @code{tparam} is to copy the control string into the buffer, encoding
843 parameters according to the @samp{%} sequences in the control string.
845 You describe the output buffer by its address, @var{buffer}, and its size
846 in bytes, @var{size}. If the buffer is not big enough for the data to be
847 stored in it, @code{tparam} calls @code{malloc} to get a larger buffer. In
848 either case, @code{tparam} returns the address of the buffer it ultimately
849 uses. If the value equals @var{buffer}, your original buffer was used.
850 Otherwise, a new buffer was allocated, and you must free it after you are
851 done with printing the results. If you pass zero for @var{size} and
852 @var{buffer}, @code{tparam} always allocates the space with @code{malloc}.
854 All capabilities that require parameters also have the ability to specify
855 padding, so you should use @code{tputs} to output the string produced by
856 @code{tparam}. @xref{Padding}. Here is an example.
863 buf = tparam (command, buffer, 40, parm);
864 tputs (buf, 1, fputchar);
870 If a parameter whose value is zero is encoded with @samp{%.}-style
871 encoding, the result is a null character, which will confuse @code{tputs}.
872 This would be a serious problem, but luckily @samp{%.} encoding is used
873 only by a few old models of terminal, and only for the @samp{cm}
874 capability. To solve the problem, use @code{tgoto} rather than
875 @code{tparam} to encode the @samp{cm} capability.@refill
877 @node tgoto,, tparam, Using Parameters
878 @subsubsection @code{tgoto}
881 The special case of cursor motion is handled by @code{tgoto}. There
882 are two reasons why you might choose to use @code{tgoto}:
886 For Unix compatibility, because Unix termcap does not have @code{tparam}.
889 For the @samp{cm} capability, since @code{tgoto} has a special feature
890 to avoid problems with null characters, tabs and newlines on certain old
891 terminal types that use @samp{%.} encoding for that capability.
894 Here is how @code{tgoto} might be declared in ANSI C:
897 char *tgoto (char *@var{cstring}, int @var{hpos}, int @var{vpos})
900 There are three arguments, the terminal description's @samp{cm} string and
901 the two cursor position numbers; @code{tgoto} computes the parametrized
902 string in an internal static buffer and returns the address of that buffer.
903 The next time you use @code{tgoto} the same buffer will be reused.
907 Parameters encoded with @samp{%.} encoding can generate null characters,
908 tabs or newlines. These might cause trouble: the null character because
909 @code{tputs} would think that was the end of the string, the tab because
910 the kernel or other software might expand it into spaces, and the newline
911 becaue the kernel might add a carriage-return, or padding characters
912 normally used for a newline. To prevent such problems, @code{tgoto} is
913 careful to avoid these characters. Here is how this works: if the target
914 cursor position value is such as to cause a problem (that is to say, zero,
915 nine or ten), @code{tgoto} increments it by one, then compensates by
916 appending a string to move the cursor back or up one position.
918 The compensation strings to use for moving back or up are found in global
919 variables named @code{BC} and @code{UP}. These are actual external C
920 variables with upper case names; they are declared @code{char *}. It is up
921 to you to store suitable values in them, normally obtained from the
922 @samp{le} and @samp{up} terminal capabilities in the terminal description
923 with @code{tgetstr}. Alternatively, if these two variables are both zero,
924 the feature of avoiding nulls, tabs and newlines is turned off.
926 It is safe to use @code{tgoto} for commands other than @samp{cm} only if
927 you have stored zero in @code{BC} and @code{UP}.
929 Note that @code{tgoto} reverses the order of its operands: the horizontal
930 position comes before the vertical position in the arguments to
931 @code{tgoto}, even though the vertical position comes before the horizontal
932 in the parameters of the @samp{cm} string. If you use @code{tgoto} with a
933 command such as @samp{AL} that takes one parameter, you must pass the
934 parameter to @code{tgoto} as the ``vertical position''.@refill
936 @node Data Base, Capabilities, Library, Top
937 @chapter The Format of the Data Base
939 The termcap data base of terminal descriptions is stored in the file
940 @file{/etc/termcap}. It contains terminal descriptions, blank lines, and
943 A terminal description starts with one or more names for the terminal type.
944 The information in the description is a series of @dfn{capability names}
945 and values. The capability names have standard meanings
946 (@pxref{Capabilities}) and their values describe the terminal.
949 * Format:: Overall format of a terminal description.
950 * Capability Format:: Format of capabilities within a description.
951 * Naming:: Naming conventions for terminal types.
952 * Inheriting:: Inheriting part of a description from
953 a related terminal type.
956 @node Format, Capability Format, Data Base, Data Base
957 @section Terminal Description Format
958 @cindex description format
960 Aside from comments (lines starting with @samp{#}, which are ignored), each
961 nonblank line in the termcap data base is a terminal description.
962 A terminal description is nominally a single line, but it can be split
963 into multiple lines by inserting the two characters @samp{\ newline}.
964 This sequence is ignored wherever it appears in a description.
966 The preferred way to split the description is between capabilities: insert
967 the four characters @samp{: \ newline tab} immediately before any colon.
968 This allows each sub-line to start with some indentation. This works
969 because, after the @samp{\ newline} are ignored, the result is @samp{: tab
970 :}; the first colon ends the preceding capability and the second colon
971 starts the next capability. If you split with @samp{\ newline} alone, you
972 may not add any indentation after them.
974 Here is a real example of a terminal description:
978 :cr=^M:do=^J:nl=^J:bl=^G:\
979 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
980 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
981 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
984 Each terminal description begins with several names for the terminal type.
985 The names are separated by @samp{|} characters, and a colon ends the last
986 name. The first name should be two characters long; it exists only for the
987 sake of very old Unix systems and is never used in modern systems. The
988 last name should be a fully verbose name such as ``DEC vt52'' or ``Ann
989 Arbor Ambassador with 48 lines''. The other names should include whatever
990 the user ought to be able to specify to get this terminal type, such as
991 @samp{vt52} or @samp{aaa-48}. @xref{Naming}, for information on how to
992 choose terminal type names.
994 After the terminal type names come the terminal capabilities, separated by
995 colons and with a colon after the last one. Each capability has a
996 two-letter name, such as @samp{cm} for ``cursor motion string'' or @samp{li}
997 for ``number of display lines''.
999 @node Capability Format, Naming, Format, Data Base
1000 @section Writing the Capabilities
1002 There are three kinds of capabilities: flags, numbers, and strings. Each
1003 kind has its own way of being written in the description. Each defined
1004 capability has by convention a particular kind of value; for example,
1005 @samp{li} always has a numeric value and @samp{cm} always a string value.
1007 A flag capability is thought of as having a boolean value: the value is
1008 true if the capability is present, false if not. When the capability is
1009 present, just write its name between two colons.
1011 A numeric capability has a value which is a nonnegative number. Write the
1012 capability name, a @samp{#}, and the number, between two colons. For
1013 example, @samp{@dots{}:li#48:@dots{}} is how you specify the @samp{li}
1014 capability for 48 lines.@refill
1016 A string-valued capability has a value which is a sequence of characters.
1017 Usually these are the characters used to perform some display operation.
1018 Write the capability name, a @samp{=}, and the characters of the value,
1019 between two colons. For example, @samp{@dots{}:cm=\E[%i%d;%dH:@dots{}} is
1020 how the cursor motion command for a standard ANSI terminal would be
1023 Special characters in the string value can be expressed using
1024 @samp{\}-escape sequences as in C; in addition, @samp{\E} stands for
1025 @key{ESC}. @samp{^} is also a kind of escape character; @samp{^} followed
1026 by @var{char} stands for the control-equivalent of @var{char}. Thus,
1027 @samp{^a} stands for the character control-a, just like @samp{\001}.
1028 @samp{\} and @samp{^} themselves can be represented as @samp{\\} and
1031 To include a colon in the string, you must write @samp{\072}. You might
1032 ask, ``Why can't @samp{\:} be used to represent a colon?'' The reason is
1033 that the interrogation functions do not count slashes while looking for a
1034 capability. Even if @samp{:ce=ab\:cd:} were interpreted as giving the
1035 @samp{ce} capability the value @samp{ab:cd}, it would also appear to define
1036 @samp{cd} as a flag.
1038 The string value will often contain digits at the front to specify padding
1039 (@pxref{Padding}) and/or @samp{%}-sequences within to specify how to encode
1040 parameters (@pxref{Parameters}). Although these things are not to be
1041 output literally to the terminal, they are considered part of the value of
1042 the capability. They are special only when the string value is processed
1043 by @code{tputs}, @code{tparam} or @code{tgoto}. By contrast, @samp{\} and
1044 @samp{^} are considered part of the syntax for specifying the characters
1047 Let's look at the VT52 example again:
1051 :cr=^M:do=^J:nl=^J:bl=^G:\
1052 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
1053 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
1054 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
1057 Here we see the numeric-valued capabilities @samp{co} and @samp{li}, the
1058 flags @samp{bs} and @samp{pt}, and many string-valued capabilities. Most
1059 of the strings start with @key{ESC} represented as @samp{\E}. The rest
1060 contain control characters represented using @samp{^}. The meanings of the
1061 individual capabilities are defined elsewhere (@pxref{Capabilities}).
1063 @node Naming, Inheriting, Capability Format, Data Base
1064 @section Terminal Type Name Conventions
1065 @cindex names of terminal types
1067 There are conventions for choosing names of terminal types. For one thing,
1068 all letters should be in lower case. The terminal type for a terminal in
1069 its most usual or most fundamental mode of operation should not have a
1072 If the same terminal has other modes of operation which require
1073 different terminal descriptions, these variant descriptions are given
1074 names made by adding suffixes with hyphens. Such alternate descriptions
1075 are used for two reasons:
1079 When the terminal has a switch that changes its behavior. Since the
1080 computer cannot tell how the switch is set, the user must tell the
1081 computer by choosing the appropriate terminal type name.
1084 For example, the VT-100 has a setup flag that controls whether the
1085 cursor wraps at the right margin. If this flag is set to ``wrap'',
1086 you must use the terminal type @samp{vt100-am}. Otherwise you must
1087 use @samp{vt100-nam}. Plain @samp{vt100} is defined as a synonym for
1088 either @samp{vt100-am} or @samp{vt100-nam} depending on the
1089 preferences of the local site.@refill
1091 The standard suffix @samp{-am} stands for ``automatic margins''.
1094 To give the user a choice in how to use the terminal. This is done
1095 when the terminal has a switch that the computer normally controls.
1098 For example, the Ann Arbor Ambassador can be configured with many
1099 screen sizes ranging from 20 to 60 lines. Fewer lines make bigger
1100 characters but more lines let you see more of what you are editing.
1101 As a result, users have different preferences. Therefore, termcap
1102 provides terminal types for many screen sizes. If you choose type
1103 @samp{aaa-30}, the terminal will be configured to use 30 lines; if you
1104 choose @samp{aaa-48}, 48 lines will be used, and so on.
1107 Here is a list of standard suffixes and their conventional meanings:
1111 Short for ``wide''. This is a mode that gives the terminal more
1112 columns than usual. This is normally a user option.
1115 ``Automatic margins''. This is an alternate description for use when
1116 the terminal's margin-wrap switch is on; it contains the @samp{am}
1117 flag. The implication is that normally the switch is off and the
1118 usual description for the terminal says that the switch is off.
1121 ``No automatic margins''. The opposite of @samp{-am}, this names an
1122 alternative description which lacks the @samp{am} flag. This implies
1123 that the terminal is normally operated with the margin-wrap switch
1124 turned on, and the normal description of the terminal says so.
1127 ``No arrows''. This terminal description initializes the terminal to
1128 keep its arrow keys in local mode. This is a user option.
1131 ``Reverse video''. This terminal description causes text output for
1132 normal video to appear as reverse, and text output for reverse video
1133 to come out as normal. Often this description differs from the usual
1134 one by interchanging the two strings which turn reverse video on and
1137 This is a user option; you can choose either the ``reverse video''
1138 variant terminal type or the normal terminal type, and termcap will
1142 ``Status''. Says to enable use of a status line which ordinary output
1143 does not touch (@pxref{Status Line}).
1145 Some terminals have a special line that is used only as a status line.
1146 For these terminals, there is no need for an @samp{-s} variant; the
1147 status line commands should be defined by default. On other
1148 terminals, enabling a status line means removing one screen line from
1149 ordinary use and reducing the effective screen height. For these
1150 terminals, the user can choose the @samp{-s} variant type to request
1151 use of a status line.
1154 Says to operate with @var{nlines} lines on the screen, for terminals
1155 such as the Ambassador which provide this as an option. Normally this
1156 is a user option; by choosing the terminal type, you control how many
1157 lines termcap will use.
1159 @item -@var{npages}p
1160 Says that the terminal has @var{npages} pages worth of screen memory,
1161 for terminals where this is a hardware option.
1164 Says that description is not for direct use, but only for reference in
1165 @samp{tc} capabilities. Such a description is a kind of subroutine,
1166 because it describes the common characteristics of several variant
1167 descriptions that would use other suffixes in place of @samp{-unk}.
1170 @node Inheriting,, Naming, Data Base
1171 @section Inheriting from Related Descriptions
1174 When two terminal descriptions are similar, their identical parts do not
1175 need to be given twice. Instead, one of the two can be defined in terms of
1176 the other, using the @samp{tc} capability. We say that one description
1177 @dfn{refers to} the other, or @dfn{inherits from} the other.
1179 The @samp{tc} capability must be the last one in the terminal description,
1180 and its value is a string which is the name of another terminal type which
1181 is referred to. For example,
1184 N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
1185 :ti=\E[2J\E[30;0;0;30p:\
1186 :te=\E[60;0;0;30p\E[30;1H\E[J:\
1191 defines the terminal type @samp{aaa-30} (also known as plain @samp{aaa}) in
1192 terms of @samp{aaa-unk}, which defines everything about the Ambassador that
1193 is independent of screen height. The types @samp{aaa-36}, @samp{aaa-48}
1194 and so on for other screen heights are likewise defined to inherit from
1197 The capabilities overridden by @samp{aaa-30} include @samp{li}, which says
1198 how many lines there are, and @samp{ti} and @samp{te}, which configure the
1199 terminal to use that many lines.
1201 The effective terminal description for type @samp{aaa} consists of the text
1202 shown above followed by the text of the description of @samp{aaa-unk}. The
1203 @samp{tc} capability is handled automatically by @code{tgetent}, which
1204 finds the description thus referenced and combines the two descriptions
1205 (@pxref{Find}). Therefore, only the implementor of the terminal
1206 descriptions needs to think about using @samp{tc}. Users and application
1207 programmers do not need to be concerned with it.
1209 Since the reference terminal description is used last, capabilities
1210 specified in the referring description override any specifications of the
1211 same capabilities in the reference description.
1213 The referring description can cancel out a capability without specifying
1214 any new value for it by means of a special trick. Write the capability in
1215 the referring description, with the character @samp{@@} after the capability
1219 NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
1223 @node Capabilities, Summary, Data Base, Top
1224 @chapter Definitions of the Terminal Capabilities
1226 This section is divided into many subsections, each for one aspect of
1227 use of display terminals. For writing a display program, you usually need
1228 only check the subsections for the operations you want to use. For writing
1229 a terminal description, you must read each subsection and fill in the
1230 capabilities described there.
1232 String capabilities that are display commands may require numeric
1233 parameters (@pxref{Parameters}). Most such capabilities do not use
1234 parameters. When a capability requires parameters, this is explicitly
1235 stated at the beginning of its definition. In simple cases, the first or
1236 second sentence of the definition mentions all the parameters, in the order
1237 they should be given, using a name
1244 for each one. For example, the @samp{rp} capability is a command that
1245 requires two parameters; its definition begins as follows:
1248 String of commands to output a graphic character @var{c}, repeated @var{n}
1252 In complex cases or when there are many parameters, they are described
1255 When a capability is described as obsolete, this means that programs should
1256 not be written to look for it, but terminal descriptions should still be
1257 written to provide it.
1259 When a capability is described as very obsolete, this means that it should
1260 be omitted from terminal descriptions as well.
1263 * Basic:: Basic characteristics.
1264 * Screen Size:: Screen size, and what happens when it changes.
1265 * Cursor Motion:: Various ways to move the cursor.
1266 * Scrolling:: Pushing text up and down on the screen.
1267 * Wrapping:: What happens if you write a character in the last column.
1268 * Windows:: Limiting the part of the window that output affects.
1269 * Clearing:: Erasing one or many lines.
1270 * Insdel Line:: Making new blank lines in mid-screen; deleting lines.
1271 * Insdel Char:: Inserting and deleting characters within a line.
1272 * Standout:: Highlighting some of the text.
1273 * Underlining:: Underlining some of the text.
1274 * Cursor Visibility:: Making the cursor more or less easy to spot.
1275 * Bell:: Attracts user's attention; not localized on the screen.
1276 * Keypad:: Recognizing when function keys or arrows are typed.
1277 * Meta Key:: @key{META} acts like an extra shift key.
1278 * Initialization:: Commands used to initialize or reset the terminal.
1279 * Pad Specs:: Info for the kernel on how much padding is needed.
1280 * Status Line:: A status line displays ``background'' information.
1281 * Half-Line:: Moving by half-lines, for superscripts and subscripts.
1282 * Printer:: Controlling auxiliary printers of display terminals.
1285 @node Basic, Screen Size, Capabilities, Capabilities
1286 @section Basic Characteristics
1288 This section documents the capabilities that describe the basic and
1289 nature of the terminal, and also those that are relevant to the output
1290 of graphic characters.
1296 Flag whose presence means that the terminal can overstrike. This
1297 means that outputting a graphic character does not erase whatever was
1298 present in the same character position before. The terminals that can
1299 overstrike include printing terminals, storage tubes (all obsolete
1300 nowadays), and many bit-map displays.
1304 Flag whose presence means that outputting a space can erase an
1305 overstrike. If this is not present and overstriking is supported,
1306 output of a space has no effect except to move the cursor.
1310 @cindex generic terminal type
1311 Flag whose presence means that this terminal type is a generic type
1312 which does not really describe any particular terminal. Generic types
1313 are intended for use as the default type assigned when the user
1314 connects to the system, with the intention that the user should
1315 specify what type he really has. One example of a generic type
1316 is the type @samp{network}.
1318 Since the generic type cannot say how to do anything interesting with
1319 the terminal, termcap-using programs will always find that the
1320 terminal is too weak to be supported if the user has failed to specify
1321 a real terminal type in place of the generic one. The @samp{gn} flag
1322 directs these programs to use a different error message: ``You have
1323 not specified your real terminal type'', rather than ``Your terminal
1324 is not powerful enough to be used''.
1328 Flag whose presence means this is a hardcopy terminal.
1332 @cindex repeat output
1333 String of commands to output a graphic character @var{c}, repeated @var{n}
1334 times. The first parameter value is the ASCII code for the desired
1335 character, and the second parameter is the number of times to repeat the
1336 character. Often this command requires padding proportional to the
1337 number of times the character is repeated. This effect can be had by
1338 using parameter arithmetic with @samp{%}-sequences to compute the
1339 amount of padding, then generating the result as a number at the front
1340 of the string so that @code{tputs} will treat it as padding.
1344 Flag whose presence means that the ASCII character @samp{~} cannot be
1345 output on this terminal because it is used for display commands.
1347 Programs handle this flag by checking all text to be output and
1348 replacing each @samp{~} with some other character(s). If this is not
1349 done, the screen will be thoroughly garbled.
1351 The old Hazeltine terminals that required such treatment are probably
1352 very rare today, so you might as well not bother to support this flag.
1356 @cindex command character
1357 String whose presence means the terminal has a settable command
1358 character. The value of the string is the default command character
1359 (which is usually @key{ESC}).
1361 All the strings of commands in the terminal description should be
1362 written to use the default command character. If you are writing an
1363 application program that changes the command character, use the
1364 @samp{CC} capability to figure out how to translate all the display
1365 commands to work with the new command character.
1367 Most programs have no reason to look at the @samp{CC} capability.
1372 Flag whose presence identifies Superbee terminals which are unable to
1373 transmit the characters @key{ESC} and @kbd{Control-C}. Programs which
1374 support this flag are supposed to check the input for the code sequences
1375 sent by the @key{F1} and @key{F2} keys, and pretend that @key{ESC}
1376 or @kbd{Control-C} (respectively) had been read. But this flag is
1377 obsolete, and not worth supporting.
1380 @node Screen Size, Cursor Motion, Basic, Capabilities
1381 @section Screen Size
1384 A terminal description has two capabilities, @samp{co} and @samp{li},
1385 that describe the screen size in columns and lines. But there is more
1386 to the question of screen size than this.
1388 On some operating systems the ``screen'' is really a window and the
1389 effective width can vary. On some of these systems, @code{tgetnum}
1390 uses the actual width of the window to decide what value to return for
1391 the @samp{co} capability, overriding what is actually written in the
1392 terminal description. On other systems, it is up to the application
1393 program to check the actual window width using a system call. For
1394 example, on BSD 4.3 systems, the system call @code{ioctl} with code
1395 @code{TIOCGWINSZ} will tell you the current screen size.
1397 On all window systems, termcap is powerless to advise the application
1398 program if the user resizes the window. Application programs must
1399 deal with this possibility in a system-dependent fashion. On some
1400 systems the C shell handles part of the problem by detecting changes
1401 in window size and setting the @code{TERMCAP} environment variable
1402 appropriately. This takes care of application programs that are
1403 started subsequently. It does not help application programs already
1406 On some systems, including BSD 4.3, all programs using a terminal get
1407 a signal named @code{SIGWINCH} whenever the screen size changes.
1408 Programs that use termcap should handle this signal by using
1409 @code{ioctl TIOCGWINSZ} to learn the new screen size.
1415 Numeric value, the width of the screen in character positions. Even
1416 hardcopy terminals normally have a @samp{co} capability.
1420 Numeric value, the height of the screen in lines.
1423 @node Cursor Motion, Wrapping, Screen Size, Capabilities
1424 @section Cursor Motion
1425 @cindex cursor motion
1427 Termcap assumes that the terminal has a @dfn{cursor}, a spot on the screen
1428 where a visible mark is displayed, and that most display commands take
1429 effect at the position of the cursor. It follows that moving the cursor
1430 to a specified location is very important.
1432 There are many terminal capabilities for different cursor motion
1433 operations. A terminal description should define as many as possible, but
1434 most programs do not need to use most of them. One capability, @samp{cm},
1435 moves the cursor to an arbitrary place on the screen; this by itself is
1436 sufficient for any application as long as there is no need to support
1437 hardcopy terminals or certain old, weak displays that have only relative
1438 motion commands. Use of other cursor motion capabilities is an
1439 optimization, enabling the program to output fewer characters in some
1442 If you plan to use the relative cursor motion commands in an application
1443 program, you must know what the starting cursor position is. To do this,
1444 you must keep track of the cursor position and update the records each
1445 time anything is output to the terminal, including graphic characters.
1446 In addition, it is necessary to know whether the terminal wraps after
1447 writing in the rightmost column. @xref{Wrapping}.
1449 One other motion capability needs special mention: @samp{nw} moves the
1450 cursor to the beginning of the following line, perhaps clearing all the
1451 starting line after the cursor, or perhaps not clearing at all. This
1452 capability is a least common denominator that is probably supported even by
1453 terminals that cannot do most other things such as @samp{cm} or @samp{do}.
1454 Even hardcopy terminals can support @samp{nw}.
1459 String of commands to position the cursor at line @var{l}, column @var{c}.
1460 Both parameters are origin-zero, and are defined relative to the
1461 screen, not relative to display memory.
1463 All display terminals except a few very obsolete ones support @samp{cm},
1464 so it is acceptable for an application program to refuse to operate on
1465 terminals lacking @samp{cm}.
1469 @cindex home position
1470 String of commands to move the cursor to the upper left corner of the
1471 screen (this position is called the @dfn{home position}). In
1472 terminals where the upper left corner of the screen is not the same as
1473 the beginning of display memory, this command must go to the upper
1474 left corner of the screen, not the beginning of display memory.
1476 Every display terminal supports this capability, and many application
1477 programs refuse to operate if the @samp{ho} capability is missing.
1481 String of commands to move the cursor to the lower left corner of the
1482 screen. On some terminals, moving up from home position does this,
1483 but programs should never assume that will work. Just output the
1484 @samp{ll} string (if it is provided); if moving to home position and
1485 then moving up is the best way to get there, the @samp{ll} command
1490 String of commands to move the cursor to the beginning of the line it
1491 is on. If this capability is not specified, many programs assume
1492 they can use the ASCII carriage return character for this.
1496 String of commands to move the cursor left one column. Unless the
1497 @samp{bw} flag capability is specified, the effect is undefined if the
1498 cursor is at the left margin; do not use this command there. If
1499 @samp{bw} is present, this command may be used at the left margin, and
1500 it wraps the cursor to the last column of the preceding line.
1504 String of commands to move the cursor right one column. The effect is
1505 undefined if the cursor is at the right margin; do not use this
1506 command there, not even if @samp{am} is present.
1510 String of commands to move the cursor vertically up one line. The
1511 effect of sending this string when on the top line is undefined;
1512 programs should never use it that way.
1516 String of commands to move the cursor vertically down one line. The
1517 effect of sending this string when on the bottom line is undefined;
1518 programs should never use it that way.
1520 The original idea was that this string would not contain a newline
1521 character and therefore could be used without disabling the kernel's usual
1522 habit of converting of newline into a carriage-return newline sequence.
1523 But many terminal descriptions do use newline in the @samp{do} string, so
1524 this is not possible; a program which sends the @samp{do} string must
1525 disable output conversion in the kernel (@pxref{Initialize}).
1529 Flag whose presence says that @samp{le} may be used in column zero
1530 to move to the last column of the preceding line. If this flag
1531 is not present, @samp{le} should not be used in column zero.
1535 String of commands to move the cursor to start of next line, possibly
1536 clearing rest of line (following the cursor) before moving.
1538 @item @samp{DO}, @samp{UP}, @samp{LE}, @samp{RI}
1543 Strings of commands to move the cursor @var{n} lines down vertically,
1544 up vertically, or @var{n} columns left or right. Do not attempt to
1545 move past any edge of the screen with these commands; the effect of
1546 trying that is undefined. Only a few terminal descriptions provide
1547 these commands, and most programs do not use them.
1551 String of commands to position the cursor at line @var{l}, column
1552 @var{c}, relative to display memory. Both parameters are origin-zero.
1553 This capability is present only in terminals where there is a
1554 difference between screen-relative and memory-relative addressing, and
1555 not even in all such terminals.
1559 String of commands to position the cursor at column @var{c} in the
1560 same line it is on. This is a special case of @samp{cm} in which the
1561 vertical position is not changed. The @samp{ch} capability is
1562 provided only when it is faster to output than @samp{cm} would be in
1563 this special case. Programs should not assume most display terminals
1568 String of commands to position the cursor at line @var{l} in the same
1569 column. This is a special case of @samp{cm} in which the horizontal
1570 position is not changed. The @samp{cv} capability is provided only
1571 when it is faster to output than @samp{cm} would be in this special
1572 case. Programs should not assume most display terminals have
1577 String of commands to make the terminal save the current cursor
1578 position. Only the last saved position can be used. If this
1579 capability is present, @samp{rc} should be provided also. Most
1580 terminals have neither.
1584 String of commands to make the terminal restore the last saved cursor
1585 position. If this capability is present, @samp{sc} should be provided
1586 also. Most terminals have neither.
1590 String of commands to advance to the next page, for a hardcopy
1595 String of commands to move the cursor right to the next hardware tab
1596 stop column. Missing if the terminal does not have any kind of
1597 hardware tabs. Do not send this command if the kernel's terminal
1598 modes say that the kernel is expanding tabs into spaces.
1602 String of commands to move the cursor left to the previous hardware
1603 tab stop column. Missing if the terminal has no such ability; many
1604 terminals do not. Do not send this command if the kernel's terminal
1605 modes say that the kernel is expanding tabs into spaces.
1608 The following obsolete capabilities should be included in terminal
1609 descriptions when appropriate, but should not be looked at by new programs.
1614 Flag whose presence means the terminal does not support the ASCII
1615 carriage return character as @samp{cr}. This flag is needed because
1616 old programs assume, when the @samp{cr} capability is missing, that
1617 ASCII carriage return can be used for the purpose. We use @samp{nc}
1618 to tell the old programs that carriage return may not be used.
1620 New programs should not assume any default for @samp{cr}, so they need
1621 not look at @samp{nc}. However, descriptions should contain @samp{nc}
1622 whenever they do not contain @samp{cr}.
1626 Flag whose presence means that the ASCII tab character may not be used
1627 for cursor motion. This flag exists because old programs assume, when
1628 the @samp{ta} capability is missing, that ASCII tab can be used for
1629 the purpose. We use @samp{xt} to tell the old programs not to use tab.
1631 New programs should not assume any default for @samp{ta}, so they need
1632 not look at @samp{xt} in connection with cursor motion. Note that
1633 @samp{xt} also has implications for standout mode (@pxref{Standout}).
1634 It is obsolete in regard to cursor motion but not in regard to
1637 In fact, @samp{xt} means that the terminal is a Teleray 1061.
1641 Very obsolete alternative name for the @samp{le} capability.
1645 Flag whose presence means that the ASCII character backspace may be
1646 used to move the cursor left. Obsolete; look at @samp{le} instead.
1650 Obsolete capability which is a string that can either be used to move
1651 the cursor down or to scroll. The same string must scroll when used
1652 on the bottom line and move the cursor when used on any other line.
1653 New programs should use @samp{do} or @samp{sf}, and ignore @samp{nl}.
1655 If there is no @samp{nl} capability, some old programs assume they can
1656 use the newline character for this purpose. These programs follow a
1657 bad practice, but because they exist, it is still desirable to define
1658 the @samp{nl} capability in a terminal description if the best way to
1659 move down is @emph{not} a newline.
1662 @node Wrapping, Scrolling, Cursor Motion, Capabilities
1666 @dfn{Wrapping} means moving the cursor from the right margin to the left
1667 margin of the following line. Some terminals wrap automatically when a
1668 graphic character is output in the last column, while others do not. Most
1669 application programs that use termcap need to know whether the terminal
1670 wraps. There are two special flag capabilities to describe what the
1671 terminal does when a graphic character is output in the last column.
1676 Flag whose presence means that writing a character in the last column
1677 causes the cursor to wrap to the beginning of the next line.
1679 If @samp{am} is not present, writing in the last column leaves the
1680 cursor at the place where the character was written.
1682 Writing in the last column of the last line should be avoided on
1683 terminals with @samp{am}, as it may or may not cause scrolling to
1684 occur (@pxref{Scrolling}). Scrolling is surely not what you would
1687 If your program needs to check the @samp{am} flag, then it also needs
1688 to check the @samp{xn} flag which indicates that wrapping happens in a
1689 strange way. Many common terminals have the @samp{xn} flag.
1693 Flag whose presence means that the cursor wraps in a strange way. At
1694 least two distinct kinds of strange behavior are known; the termcap
1695 data base does not contain anything to distinguish the two.
1697 On Concept-100 terminals, output in the last column wraps the cursor
1698 almost like an ordinary @samp{am} terminal. But if the next thing
1699 output is a newline, it is ignored.
1701 DEC VT-100 terminals (when the wrap switch is on) do a different
1702 strange thing: the cursor wraps only if the next thing output is
1703 another graphic character. In fact, the wrap occurs when the
1704 following graphic character is received by the terminal, before the
1705 character is placed on the screen.
1707 On both of these terminals, after writing in the last column a
1708 following graphic character will be displayed in the first column of
1709 the following line. But the effect of relative cursor motion
1710 characters such as newline or backspace at such a time depends on the
1711 terminal. The effect of erase or scrolling commands also depends on
1712 the terminal. You can't assume anything about what they will do on a
1713 terminal that has @samp{xn}. So, to be safe, you should never do
1714 these things at such a time on such a terminal.
1716 To be sure of reliable results on a terminal which has the @samp{xn}
1717 flag, output a @samp{cm} absolute positioning command after writing in
1718 the last column. Another safe thing to do is to output carriage-return
1719 newline, which will leave the cursor at the beginning of the following
1723 @node Scrolling, Windows, Wrapping, Capabilities
1727 @dfn{Scrolling} means moving the contents of the screen up or down one or
1728 more lines. Moving the contents up is @dfn{forward scrolling}; moving them
1729 down is @dfn{reverse scrolling}.
1731 Scrolling happens after each line of output during ordinary output on most
1732 display terminals. But in an application program that uses termcap for
1733 random-access output, scrolling happens only when explicitly requested with
1734 the commands in this section.
1736 Some terminals have a @dfn{scroll region} feature. This lets you limit
1737 the effect of scrolling to a specified range of lines. Lines outside the
1738 range are unaffected when scrolling happens. The scroll region feature
1739 is available if either @samp{cs} or @samp{cS} is present.
1744 String of commands to scroll the screen one line up, assuming it is
1745 output with the cursor at the beginning of the bottom line.
1749 String of commands to scroll the screen one line down, assuming it is
1750 output with the cursor at the beginning of the top line.
1754 String of commands to scroll the screen @var{n} lines up, assuming it
1755 is output with the cursor at the beginning of the bottom line.
1759 String of commands to scroll the screen @var{n} line down, assuming it
1760 is output with the cursor at the beginning of the top line.
1764 String of commands to set the scroll region. This command takes two
1765 parameters, @var{start} and @var{end}, which are the line numbers
1766 (origin-zero) of the first line to include in the scroll region and of
1767 the last line to include in it. When a scroll region is set,
1768 scrolling is limited to the specified range of lines; lines outside
1769 the range are not affected by scroll commands.
1771 Do not try to move the cursor outside the scroll region. The region
1772 remains set until explicitly removed. To remove the scroll region,
1773 use another @samp{cs} command specifying the full height of the
1776 The cursor position is undefined after the @samp{cs} command is set,
1777 so position the cursor with @samp{cm} immediately afterward.
1781 String of commands to set the scroll region using parameters in
1782 different form. The effect is the same as if @samp{cs} were used.
1783 Four parameters are required:
1787 Total number of lines on the screen.
1789 Number of lines above desired scroll region.
1791 Number of lines below (outside of) desired scroll region.
1793 Total number of lines on the screen, the same as the first parameter.
1796 This capability is a GNU extension that was invented to allow the Ann
1797 Arbor Ambassador's scroll-region command to be described; it could
1798 also be done by putting non-Unix @samp{%}-sequences into a @samp{cs}
1799 string, but that would have confused Unix programs that used the
1800 @samp{cs} capability with the Unix termcap. Currently only GNU Emacs
1801 uses the @samp{cS} capability.
1805 Flag which means that the terminal does not normally scroll for
1806 ordinary sequential output. For modern terminals, this means that
1807 outputting a newline in ordinary sequential output with the cursor on
1808 the bottom line wraps to the top line. For some obsolete terminals,
1809 other things may happen.
1811 The terminal may be able to scroll even if it does not normally do so.
1812 If the @samp{sf} capability is provided, it can be used for scrolling
1813 regardless of @samp{ns}.
1817 Flag whose presence means that lines scrolled up off the top of the
1818 screen may come back if scrolling down is done subsequently.
1820 The @samp{da} and @samp{db} flags do not, strictly speaking, affect
1821 how to scroll. But programs that scroll usually need to clear the
1822 lines scrolled onto the screen, if these flags are present.
1826 Flag whose presence means that lines scrolled down off the bottom of
1827 the screen may come back if scrolling up is done subsequently.
1831 Numeric value, the number of lines of display memory that the terminal
1832 has. A value of zero means that the terminal has more display memory
1833 than can fit on the screen, but no fixed number of lines. (The number
1834 of lines may depend on the amount of text in each line.)
1837 Any terminal description that defines @samp{SF} should also define @samp{sf};
1838 likewise for @samp{SR} and @samp{sr}. However, many terminals can only
1839 scroll by one line at a time, so it is common to find @samp{sf} and not
1840 @samp{SF}, or @samp{sr} without @samp{SR}.@refill
1842 Therefore, all programs that use the scrolling facilities should be
1843 prepared to work with @samp{sf} in the case that @samp{SF} is absent, and
1844 likewise with @samp{sr}. On the other hand, an application program that
1845 uses only @samp{sf} and not @samp{SF} is acceptable, though slow on some
1848 When outputting a scroll command with @code{tputs}, the @var{nlines}
1849 argument should be the total number of lines in the portion of the screen
1850 being scrolled. Very often these commands require padding proportional to
1851 this number of lines. @xref{Padding}.
1853 @node Windows, Clearing, Scrolling, Capabilities
1857 A @dfn{window}, in termcap, is a rectangular portion of the screen to which
1858 all display operations are restricted. Wrapping, clearing, scrolling,
1859 insertion and deletion all operate as if the specified window were all the
1865 String of commands to set the terminal output screen window.
1866 This string requires four parameters, all origin-zero:
1869 The first line to include in the window.
1871 The last line to include in the window.
1873 The first column to include in the window.
1875 The last column to include in the window.
1879 Most terminals do not support windows.
1881 @node Clearing, Insdel Line, Windows, Capabilities
1882 @section Clearing Parts of the Screen
1884 @cindex clearing the screen
1886 There are several terminal capabilities for clearing parts of the screen
1887 to blank. All display terminals support the @samp{cl} string, and most
1888 display terminals support all of these capabilities.
1893 String of commands to clear the entire screen and position the cursor
1894 at the upper left corner.
1898 String of commands to clear the line the cursor is on, and all the
1899 lines below it, down to the bottom of the screen. This command string
1900 should be used only with the cursor in column zero; their effect is
1901 undefined if the cursor is elsewhere.
1905 String of commands to clear from the cursor to the end of the current
1910 String of commands to clear @var{n} characters, starting with the
1911 character that the cursor is on. This command string is expected to
1912 leave the cursor position unchanged. The parameter @var{n} should never
1913 be large enough to reach past the right margin; the effect of such a
1914 large parameter would be undefined.
1917 Clear to end of line (@samp{ce}) is extremely important in programs that
1918 maintain an updating display. Nearly all display terminals support this
1919 operation, so it is acceptable for a an application program to refuse to
1920 work if @samp{ce} is not present. However, if you do not want this
1921 limitation, you can accomplish clearing to end of line by outputting spaces
1922 until you reach the right margin. In order to do this, you must know the
1923 current horizontal position. Also, this technique assumes that writing a
1924 space will erase. But this happens to be true on all the display terminals
1925 that fail to support @samp{ce}.
1927 @node Insdel Line, Insdel Char, Clearing, Capabilities
1928 @section Insert/Delete Line
1932 @dfn{Inserting a line} means creating a blank line in the middle
1933 of the screen, and pushing the existing lines of text apart. In fact,
1934 the lines above the insertion point do not change, while the lines below
1935 move down, and one is normally lost at the bottom of the screen.
1937 @dfn{Deleting a line} means causing the line to disappear from the screen,
1938 closing up the gap by moving the lines below it upward. A new line
1939 appears at the bottom of the screen. Usually this line is blank, but
1940 on terminals with the @samp{db} flag it may be a line previously moved
1941 off the screen bottom by scrolling or line insertion.
1943 Insertion and deletion of lines is useful in programs that maintain an
1944 updating display some parts of which may get longer or shorter. They are
1945 also useful in editors for scrolling parts of the screen, and for
1946 redisplaying after lines of text are killed or inserted.
1948 Many terminals provide commands to insert or delete a single line at the
1949 cursor position. Some provide the ability to insert or delete several
1950 lines with one command, using the number of lines to insert or delete as a
1951 parameter. Always move the cursor to column zero before using any of
1957 String of commands to insert a blank line before the line the cursor
1958 is on. The existing line, and all lines below it, are moved down.
1959 The last line in the screen (or in the scroll region, if one is set)
1960 disappears and in most circumstances is discarded. It may not be
1961 discarded if the @samp{db} is present (@pxref{Scrolling}).
1963 The cursor must be at the left margin before this command is used.
1964 This command does not move the cursor.
1968 String of commands to delete the line the cursor is on. The following
1969 lines move up, and a blank line appears at the bottom of the screen
1970 (or bottom of the scroll region). If the terminal has the @samp{db}
1971 flag, a nonblank line previously pushed off the screen bottom may
1972 reappear at the bottom.
1974 The cursor must be at the left margin before this command is used.
1975 This command does not move the cursor.
1979 String of commands to insert @var{n} blank lines before the line that
1980 the cursor is on. It is like @samp{al} repeated @var{n} times, except
1981 that it is as fast as one @samp{al}.
1985 String of commands to delete @var{n} lines starting with the line that
1986 the cursor is on. It is like @samp{dl} repeated @var{n} times, except
1987 that it is as fast as one @samp{dl}.
1990 Any terminal description that defines @samp{AL} should also define
1991 @samp{al}; likewise for @samp{DL} and @samp{dl}. However, many terminals
1992 can only insert or delete one line at a time, so it is common to find
1993 @samp{al} and not @samp{AL}, or @samp{dl} without @samp{DL}.@refill
1995 Therefore, all programs that use the insert and delete facilities should be
1996 prepared to work with @samp{al} in the case that @samp{AL} is absent, and
1997 likewise with @samp{dl}. On the other hand, it is acceptable to write
1998 an application that uses only @samp{al} and @samp{dl} and does not look
1999 for @samp{AL} or @samp{DL} at all.@refill
2001 If a terminal does not support line insertion and deletion directly,
2002 but does support a scroll region, the effect of insertion and deletion
2003 can be obtained with scrolling. However, it is up to the individual
2004 user program to check for this possibility and use the scrolling
2005 commands to get the desired result. It is fairly important to implement
2006 this alternate strategy, since it is the only way to get the effect of
2007 line insertion and deletion on the popular VT100 terminal.
2009 Insertion and deletion of lines is affected by the scroll region on
2010 terminals that have a settable scroll region. This is useful when it is
2011 desirable to move any few consecutive lines up or down by a few lines.
2014 The line pushed off the bottom of the screen is not lost if the terminal
2015 has the @samp{db} flag capability; instead, it is pushed into display
2016 memory that does not appear on the screen. This is the same thing that
2017 happens when scrolling pushes a line off the bottom of the screen.
2018 Either reverse scrolling or deletion of a line can bring the apparently
2019 lost line back onto the bottom of the screen. If the terminal has the
2020 scroll region feature as well as @samp{db}, the pushed-out line really
2021 is lost if a scroll region is in effect.
2023 When outputting an insert or delete command with @code{tputs}, the
2024 @var{nlines} argument should be the total number of lines from the cursor
2025 to the bottom of the screen (or scroll region). Very often these commands
2026 require padding proportional to this number of lines. @xref{Padding}.
2028 For @samp{AL} and @samp{DL} the @var{nlines} argument should @emph{not}
2029 depend on the number of lines inserted or deleted; only the total number of
2030 lines affected. This is because it is just as fast to insert two or
2031 @var{n} lines with @samp{AL} as to insert one line with @samp{al}.
2033 @node Insdel Char, Standout, Insdel Line, Capabilities
2034 @section Insert/Delete Character
2035 @cindex insert character
2036 @cindex delete character
2038 @dfn{Inserting a character} means creating a blank space in the middle of a
2039 line, and pushing the rest of the line rightward. The character in the
2040 rightmost column is lost.
2042 @dfn{Deleting a character} means causing the character to disappear from
2043 the screen, closing up the gap by moving the rest of the line leftward. A
2044 blank space appears in the rightmost column.
2046 Insertion and deletion of characters is useful in programs that maintain an
2047 updating display some parts of which may get longer or shorter. It is also
2048 useful in editors for redisplaying the results of editing within a line.
2050 Many terminals provide commands to insert or delete a single character at
2051 the cursor position. Some provide the ability to insert or delete several
2052 characters with one command, using the number of characters to insert or
2053 delete as a parameter.
2056 Many terminals provide an insert mode in which outputting a graphic
2057 character has the added effect of inserting a position for that character.
2058 A special command string is used to enter insert mode and another is used
2059 to exit it. The reason for designing a terminal with an insert mode rather
2060 than an insert command is that inserting character positions is usually
2061 followed by writing characters into them. With insert mode, this is as
2062 fast as simply writing the characters, except for the fixed overhead of
2063 entering and leaving insert mode. However, when the line speed is great
2064 enough, padding may be required for the graphic characters output in insert
2067 Some terminals require you to enter insert mode and then output a special
2068 command for each position to be inserted. Or they may require special
2069 commands to be output before or after each graphic character to be
2073 Deletion of characters is usually accomplished by a straightforward command
2074 to delete one or several positions; but on some terminals, it is necessary
2075 to enter a special delete mode before using the delete command, and leave
2076 delete mode afterward. Sometimes delete mode and insert mode are the same
2079 Some terminals make a distinction between character positions in which a
2080 space character has been output and positions which have been cleared. On
2081 these terminals, the effect of insert or delete character runs to the first
2082 cleared position rather than to the end of the line. In fact, the effect
2083 may run to more than one line if there is no cleared position to stop the
2084 shift on the first line. These terminals are identified by the @samp{in}
2087 On terminals with the @samp{in} flag, the technique of skipping over
2088 characters that you know were cleared, and then outputting text later on in
2089 the same line, causes later insert and delete character operations on that
2090 line to do nonstandard things. A program that has any chance of doing this
2091 must check for the @samp{in} flag and must be careful to write explicit
2092 space characters into the intermediate columns when @samp{in} is present.
2094 A plethora of terminal capabilities are needed to describe all of this
2095 complexity. Here is a list of them all. Following the list, we present
2096 an algorithm for programs to use to take proper account of all of these
2102 String of commands to enter insert mode.
2104 If the terminal has no special insert mode, but it can insert
2105 characters with a special command, @samp{im} should be defined with a
2106 null value, because the @samp{vi} editor assumes that insertion of a
2107 character is impossible if @samp{im} is not provided.
2109 New programs should not act like @samp{vi}. They should pay attention
2110 to @samp{im} only if it is defined.
2114 String of commands to leave insert mode. This capability must be
2115 present if @samp{im} is.
2117 On a few old terminals the same string is used to enter and exit
2118 insert mode. This string turns insert mode on if it was off, and off
2119 if it was on. You can tell these terminals because the @samp{ei}
2120 string equals the @samp{im} string. If you want to support these
2121 terminals, you must always remember accurately whether insert mode is
2122 in effect. However, these terminals are obsolete, and it is
2123 reasonable to refuse to support them. On all modern terminals, you
2124 can safely output @samp{ei} at any time to ensure that insert mode is
2129 String of commands to insert one character position at the cursor.
2130 The cursor does not move.
2132 If outputting a graphic character while in insert mode is sufficient
2133 to insert the character, then the @samp{ic} capability should be
2134 defined with a null value.
2136 If your terminal offers a choice of ways to insert---either use insert
2137 mode or use a special command---then define @samp{im} and do not define
2138 @samp{ic}, since this gives the most efficient operation when several
2139 characters are to be inserted. @emph{Do not} define both strings, for
2140 that means that @emph{both} must be used each time insertion is done.
2144 String of commands to output following an inserted graphic character
2145 in insert mode. Often it is used just for a padding spec, when padding
2146 is needed after an inserted character (@pxref{Padding}).
2150 String of commands to insert @var{n} character positions at and after
2151 the cursor. It has the same effect as repeating the @samp{ic} string
2152 and a space, @var{n} times.
2154 If @samp{IC} is provided, application programs may use it without first
2155 entering insert mode.
2159 Flag whose presence means it is safe to move the cursor while in insert
2160 mode and assume the terminal remains in insert mode.
2164 Flag whose presence means that the terminal distinguishes between
2165 character positions in which space characters have been output and
2166 positions which have been cleared.
2169 An application program can assume that the terminal can do character
2170 insertion if @emph{any one of} the capabilities @samp{IC}, @samp{im},
2171 @samp{ic} or @samp{ip} is provided.
2173 To insert @var{n} blank character positions, move the cursor to the place
2174 to insert them and follow this algorithm:
2178 If an @samp{IC} string is provided, output it with parameter @var{n}
2179 and you are finished. Otherwise (or if you don't want to bother to
2180 look for an @samp{IC} string) follow the remaining steps.
2183 Output the @samp{im} string, if there is one, unless the terminal is
2184 already in insert mode.
2187 Repeat steps 4 through 6, @var{n} times.
2190 Output the @samp{ic} string if any.
2196 Output the @samp{ip} string if any.
2199 Output the @samp{ei} string, eventually, to exit insert mode. There
2200 is no need to do this right away. If the @samp{mi} flag is present,
2201 you can move the cursor and the cursor will remain in insert mode;
2202 then you can do more insertion elsewhere without reentering insert
2206 To insert @var{n} graphic characters, position the cursor and follow this
2211 If an @samp{IC} string is provided, output it with parameter @var{n},
2212 then output the graphic characters, and you are finished. Otherwise
2213 (or if you don't want to bother to look for an @samp{IC} string)
2214 follow the remaining steps.
2217 Output the @samp{im} string, if there is one, unless the terminal is
2218 already in insert mode.
2221 For each character to be output, repeat steps 4 through 6.
2224 Output the @samp{ic} string if any.
2227 Output the next graphic character.
2230 Output the @samp{ip} string if any.
2233 Output the @samp{ei} string, eventually, to exit insert mode. There
2234 is no need to do this right away. If the @samp{mi} flag is present,
2235 you can move the cursor and the cursor will remain in insert mode;
2236 then you can do more insertion elsewhere without reentering insert
2240 Note that this is not the same as the original Unix termcap specifications
2241 in one respect: it assumes that the @samp{IC} string can be used without
2242 entering insert mode. This is true as far as I know, and it allows you be
2243 able to avoid entering and leaving insert mode, and also to be able to
2244 avoid the inserted-character padding after the characters that go into the
2247 Deletion of characters is less complicated; deleting one column is done by
2248 outputting the @samp{dc} string. However, there may be a delete mode that
2249 must be entered with @samp{dm} in order to make @samp{dc} work.
2254 String of commands to delete one character position at the cursor. If
2255 @samp{dc} is not present, the terminal cannot delete characters.
2259 String of commands to delete @var{n} characters starting at the cursor.
2260 It has the same effect as repeating the @samp{dc} string @var{n} times.
2261 Any terminal description that has @samp{DC} also has @samp{dc}.
2265 String of commands to enter delete mode. If not present, there is no
2266 delete mode, and @samp{dc} can be used at any time (assuming there is
2271 String of commands to exit delete mode. This must be present if
2275 To delete @var{n} character positions, position the cursor and follow these
2280 If the @samp{DC} string is present, output it with parameter @var{n}
2281 and you are finished. Otherwise, follow the remaining steps.
2284 Output the @samp{dm} string, unless you know the terminal is already
2288 Output the @samp{dc} string @var{n} times.
2291 Output the @samp{ed} string eventually. If the flag capability
2292 @samp{mi} is present, you can move the cursor and do more deletion
2293 without leaving and reentering delete mode.
2296 As with the @samp{IC} string, we have departed from the original termcap
2297 specifications by assuming that @samp{DC} works without entering delete
2298 mode even though @samp{dc} would not.
2300 If the @samp{dm} and @samp{im} capabilities are both present and have the
2301 same value, it means that the terminal has one mode for both insertion and
2302 deletion. It is useful for a program to know this, because then it can do
2303 insertions after deletions, or vice versa, without leaving insert/delete
2304 mode and reentering it.
2306 @node Standout, Underlining, Insdel Char, Capabilities
2307 @section Standout and Appearance Modes
2308 @cindex appearance modes
2310 @cindex magic cookie
2312 @dfn{Appearance modes} are modifications to the ways characters are
2313 displayed. Typical appearance modes include reverse video, dim, bright,
2314 blinking, underlined, invisible, and alternate character set. Each kind of
2315 terminal supports various among these, or perhaps none.
2317 For each type of terminal, one appearance mode or combination of them that
2318 looks good for highlighted text is chosen as the @dfn{standout mode}. The
2319 capabilities @samp{so} and @samp{se} say how to enter and leave standout
2320 mode. Programs that use appearance modes only to highlight some text
2321 generally use the standout mode so that they can work on as many terminals
2322 as possible. Use of specific appearance modes other than ``underlined''
2323 and ``alternate character set'' is rare.
2325 Terminals that implement appearance modes fall into two general classes as
2328 In some terminals, the presence or absence of any appearance mode is
2329 recorded separately for each character position. In these terminals, each
2330 graphic character written is given the appearance modes current at the time
2331 it is written, and keeps those modes until it is erased or overwritten.
2332 There are special commands to turn the appearance modes on or off for
2333 characters to be written in the future.
2335 In other terminals, the change of appearance modes is represented by a
2336 marker that belongs to a certain screen position but affects all following
2337 screen positions until the next marker. These markers are traditionally
2338 called @dfn{magic cookies}.
2340 The same capabilities (@samp{so}, @samp{se}, @samp{mb} and so on) for
2341 turning appearance modes on and off are used for both magic-cookie
2342 terminals and per-character terminals. On magic cookie terminals, these
2343 give the commands to write the magic cookies. On per-character terminals,
2344 they change the current modes that affect future output and erasure. Some
2345 simple applications can use these commands without knowing whether or not
2346 they work by means of cookies.
2348 However, a program that maintains and updates a display needs to know
2349 whether the terminal uses magic cookies, and exactly what their effect is.
2350 This information comes from the @samp{sg} capability.
2352 The @samp{sg} capability is a numeric capability whose presence indicates
2353 that the terminal uses magic cookies for appearance modes. Its value is
2354 the number of character positions that a magic cookie occupies. Usually
2355 the cookie occupies one or more character positions on the screen, and these
2356 character positions are displayed as blank, but in some terminals the
2357 cookie has zero width.
2359 The @samp{sg} capability describes both the magic cookie to turn standout
2360 on and the cookie to turn it off. This makes the assumption that both
2361 kinds of cookie have the same width on the screen. If that is not true,
2362 the narrower cookie must be ``widened'' with spaces until it has the same
2365 On some magic cookie terminals, each line always starts with normal
2366 display; in other words, the scope of a magic cookie never extends over
2367 more than one line. But on other terminals, one magic cookie affects all
2368 the lines below it unless explicitly canceled. Termcap does not define any
2369 way to distinguish these two ways magic cookies can work. To be safe, it
2370 is best to put a cookie at the beginning of each line.
2372 On some per-character terminals, standout mode or other appearance modes
2373 may be canceled by moving the cursor. On others, moving the cursor has no
2374 effect on the state of the appearance modes. The latter class of terminals
2375 are given the flag capability @samp{ms} (``can move in standout''). All
2376 programs that might have occasion to move the cursor while appearance modes
2377 are turned on must check for this flag; if it is not present, they should
2378 reset appearance modes to normal before doing cursor motion.
2380 A program that has turned on only standout mode should use @samp{se} to
2381 reset the standout mode to normal. A program that has turned on only
2382 alternate character set mode should use @samp{ae} to return it to normal.
2383 If it is possible that any other appearance modes are turned on, use the
2384 @samp{me} capability to return them to normal.
2386 Note that the commands to turn on one appearance mode, including @samp{so}
2387 and @samp{mb} @dots{} @samp{mr}, if used while some other appearance modes
2388 are turned on, may combine the two modes on some terminals but may turn off
2389 the mode previously enabled on other terminals. This is because some
2390 terminals do not have a command to set or clear one appearance mode without
2391 changing the others. Programs should not attempt to use appearance modes
2392 in combination except with @samp{sa}, and when switching from one single
2393 mode to another should always turn off the previously enabled mode and then
2394 turn on the new desired mode.
2396 On some old terminals, the @samp{so} and @samp{se} commands may be the same
2397 command, which has the effect of turning standout on if it is off, or off
2398 it is on. It is therefore risky for a program to output extra @samp{se}
2399 commands for good measure. Fortunately, all these terminals are obsolete.
2401 Programs that update displays in which standout-text may be replaced with
2402 non-standout text must check for the @samp{xs} flag. In a per-character
2403 terminal, this flag says that the only way to remove standout once written is
2404 to clear that portion of the line with the @samp{ce} string or something
2405 even more powerful (@pxref{Clearing}); just writing new characters at those
2406 screen positions will not change the modes in effect there. In a magic
2407 cookie terminal, @samp{xs} says that the only way to remove a cookie is to
2408 clear a portion of the line that includes the cookie; writing a different
2409 cookie at the same position does not work.
2411 Such programs must also check for the @samp{xt} flag, which means that the
2412 terminal is a Teleray 1061. On this terminal it is impossible to position
2413 the cursor at the front of a magic cookie, so the only two ways to remove a
2414 cookie are (1) to delete the line it is on or (2) to position the cursor at
2415 least one character before it (possibly on a previous line) and output the
2416 @samp{se} string, which on these terminals finds and removes the next
2417 @samp{so} magic cookie on the screen. (It may also be possible to remove a
2418 cookie which is not at the beginning of a line by clearing that line.) The
2419 @samp{xt} capability also has implications for the use of tab characters,
2420 but in that regard it is obsolete (@pxref{Cursor Motion}).
2425 String of commands to enter standout mode.
2429 String of commands to leave standout mode.
2433 Numeric capability, the width on the screen of the magic cookie. This
2434 capability is absent in terminals that record appearance modes
2435 character by character.
2439 Flag whose presence means that it is safe to move the cursor while the
2440 appearance modes are not in the normal state. If this flag is absent,
2441 programs should always reset the appearance modes to normal before
2446 Flag whose presence means that the only way to reset appearance modes
2447 already on the screen is to clear to end of line. On a per-character
2448 terminal, you must clear the area where the modes are set. On a magic
2449 cookie terminal, you must clear an area containing the cookie.
2450 See the discussion above.
2454 Flag whose presence means that the cursor cannot be positioned right
2455 in front of a magic cookie, and that @samp{se} is a command to delete
2456 the next magic cookie following the cursor. See discussion above.
2460 String of commands to enter blinking mode.
2464 String of commands to enter double-bright mode.
2468 String of commands to enter half-bright mode.
2472 String of commands to enter invisible mode.
2476 String of commands to enter protected mode.
2480 String of commands to enter reverse-video mode.
2484 String of commands to turn off all appearance modes, including
2485 standout mode and underline mode. On some terminals it also turns off
2486 alternate character set mode; on others, it may not. This capability
2487 must be present if any of @samp{mb} @dots{} @samp{mr} is present.
2491 String of commands to turn on alternate character set mode. This mode
2492 assigns some or all graphic characters an alternate picture on the
2493 screen. There is no standard as to what the alternate pictures look
2498 String of commands to turn off alternate character set mode.
2502 String of commands to turn on an arbitrary combination of appearance
2503 modes. It accepts 9 parameters, each of which controls a particular
2504 kind of appearance mode. A parameter should be 1 to turn its appearance
2505 mode on, or zero to turn that mode off. Most terminals do not support
2506 the @samp{sa} capability, even among those that do have various
2509 The nine parameters are, in order, @var{standout}, @var{underline},
2510 @var{reverse}, @var{blink}, @var{half-bright}, @var{double-bright},
2511 @var{blank}, @var{protect}, @var{alt char set}.
2514 @node Underlining, Cursor Visibility, Standout, Capabilities
2515 @section Underlining
2518 Underlining on most terminals is a kind of appearance mode, much like
2519 standout mode. Therefore, it may be implemented using magic cookies or as
2520 a flag in the terminal whose current state affects each character that is
2521 output. @xref{Standout}, for a full explanation.
2523 The @samp{ug} capability is a numeric capability whose presence indicates
2524 that the terminal uses magic cookies for underlining. Its value is the
2525 number of character positions that a magic cookie for underlining occupies;
2526 it is used for underlining just as @samp{sg} is used for standout. Aside
2527 from the simplest applications, it is impossible to use underlining
2528 correctly without paying attention to the value of @samp{ug}.
2533 String of commands to turn on underline mode or to output a magic cookie
2534 to start underlining.
2538 String of commands to turn off underline mode or to output a magic
2539 cookie to stop underlining.
2543 Width of magic cookie that represents a change of underline mode;
2544 or missing, if the terminal does not use a magic cookie for this.
2548 Flag whose presence means that it is safe to move the cursor while the
2549 appearance modes are not in the normal state. Underlining is an
2550 appearance mode. If this flag is absent, programs should always turn
2551 off underlining before moving the cursor.
2554 There are two other, older ways of doing underlining: there can be a
2555 command to underline a single character, or the output of @samp{_}, the
2556 ASCII underscore character, as an overstrike could cause a character to be
2557 underlined. New programs need not bother to handle these capabilities
2558 unless the author cares strongly about the obscure terminals which support
2559 them. However, terminal descriptions should provide these capabilities
2565 String of commands to underline the character under the cursor, and
2566 move the cursor right.
2570 Flag whose presence means that the terminal can underline by
2571 overstriking an underscore character (@samp{_}); some terminals can do
2572 this even though they do not support overstriking in general. An
2573 implication of this flag is that when outputting new text to overwrite
2574 old text, underscore characters must be treated specially lest they
2575 underline the old text instead.
2578 @node Cursor Visibility, Bell, Underlining, Capabilities
2579 @section Cursor Visibility
2582 Some terminals have the ability to make the cursor invisible, or to enhance
2583 it. Enhancing the cursor is often done by programs that plan to use the
2584 cursor to indicate to the user a position of interest that may be anywhere
2585 on the screen---for example, the Emacs editor enhances the cursor on entry.
2586 Such programs should always restore the cursor to normal on exit.
2591 String of commands to enhance the cursor.
2595 String of commands to make the cursor invisible.
2599 String of commands to return the cursor to normal.
2602 If you define either @samp{vs} or @samp{vi}, you must also define @samp{ve}.
2604 @node Bell, Keypad, Cursor Visibility, Capabilities
2607 @cindex visible bell
2609 Here we describe commands to make the terminal ask for the user to pay
2615 String of commands to cause the terminal to make an audible sound. If
2616 this capability is absent, the terminal has no way to make a suitable
2621 String of commands to cause the screen to flash to attract attention
2622 (``visible bell''). If this capability is absent, the terminal has no
2623 way to do such a thing.
2626 @node Keypad, Meta Key, Bell, Capabilities
2627 @section Keypad and Function Keys
2629 Many terminals have arrow and function keys that transmit specific
2630 character sequences to the computer. Since the precise sequences used
2631 depend on the terminal, termcap defines capabilities used to say what the
2632 sequences are. Unlike most termcap string-valued capabilities, these are
2633 not strings of commands to be sent to the terminal, rather strings that
2634 are received from the terminal.
2636 Programs that expect to use keypad keys should check, initially, for a
2637 @samp{ks} capability and send it, to make the keypad actually transmit.
2638 Such programs should also send the @samp{ke} string when exiting.
2643 String of commands to make the function keys transmit. If this
2644 capability is not provided, but the others in this section are,
2645 programs may assume that the function keys always transmit.
2648 String of commands to make the function keys work locally. This
2649 capability is provided only if @samp{ks} is.
2652 String of input characters sent by typing the left-arrow key. If this
2653 capability is missing, you cannot expect the terminal to have a
2654 left-arrow key that transmits anything to the computer.
2657 String of input characters sent by typing the right-arrow key.
2660 String of input characters sent by typing the up-arrow key.
2663 String of input characters sent by typing the down-arrow key.
2666 String of input characters sent by typing the ``home-position'' key.
2668 @item @samp{K1} @dots{} @samp{K5}
2670 Strings of input characters sent by the five other keys in a 3-by-3
2671 array that includes the arrow keys, if the keyboard has such a 3-by-3
2672 array. Note that one of these keys may be the ``home-position'' key,
2673 in which case one of these capabilities will have the same value as
2677 String of input characters sent by function key 10 (or 0, if the terminal
2680 @item @samp{k1} @dots{} @samp{k9}
2682 Strings of input characters sent by function keys 1 through 9,
2683 provided for those function keys that exist.
2686 Number: the number of numbered function keys, if there are more than
2689 @item @samp{l0} @dots{} @samp{l9}
2691 Strings which are the labels appearing on the keyboard on the keys
2692 described by the capabilities @samp{k0} @dots{} @samp{l9}. These
2693 capabilities should be left undefined if the labels are @samp{f0} or
2694 @samp{f10} and @samp{f1} @dots{} @samp{f9}.@refill
2698 String of input characters sent by the ``home down'' key, if there is
2702 String of input characters sent by the ``backspace'' key, if there is
2706 String of input characters sent by the ``clear all tabs'' key, if there
2710 String of input characters sent by the ``clear tab stop this column''
2711 key, if there is one.
2714 String of input characters sent by the ``clear screen'' key, if there is
2718 String of input characters sent by the ``delete character'' key, if
2722 String of input characters sent by the ``delete line'' key, if there is
2726 String of input characters sent by the ``exit insert mode'' key, if
2730 String of input characters sent by the ``clear to end of line'' key, if
2734 String of input characters sent by the ``clear to end of screen'' key,
2738 String of input characters sent by the ``insert character'' or ``enter
2739 insert mode'' key, if there is one.
2742 String of input characters sent by the ``insert line'' key, if there is
2746 String of input characters sent by the ``next page'' key, if there is
2750 String of input characters sent by the ``previous page'' key, if there is
2754 String of input characters sent by the ``scroll forward'' key, if there
2758 String of input characters sent by the ``scroll reverse'' key, if there
2762 String of input characters sent by the ``set tab stop in this column''
2763 key, if there is one.
2766 String listing the other function keys the terminal has. This is a
2767 very obsolete way of describing the same information found in the
2768 @samp{kH} @dots{} @samp{kT} keys. The string contains a list of
2769 two-character termcap capability names, separated by commas. The
2770 meaning is that for each capability name listed, the terminal has a
2771 key which sends the string which is the value of that capability. For
2772 example, the value @samp{:ko=cl,ll,sf,sr:} says that the terminal has
2773 four function keys which mean ``clear screen'', ``home down'',
2774 ``scroll forward'' and ``scroll reverse''.@refill
2777 @node Meta Key, Initialization, Keypad, Capabilities
2781 A Meta key is a key on the keyboard that modifies each character you type
2782 by controlling the 0200 bit. This bit is on if and only if the Meta key is
2783 held down when the character is typed. Characters typed using the Meta key
2784 are called Meta characters. Emacs uses Meta characters as editing
2790 Flag whose presence means that the terminal has a Meta key.
2794 String of commands to enable the functioning of the Meta key.
2798 String of commands to disable the functioning of the Meta key.
2801 If the terminal has @samp{km} but does not have @samp{mm} and @samp{mo}, it
2802 means that the Meta key always functions. If it has @samp{mm} and
2803 @samp{mo}, it means that the Meta key can be turned on or off. Send the
2804 @samp{mm} string to turn it on, and the @samp{mo} string to turn it off.
2805 I do not know why one would ever not want it to be on.
2807 @node Initialization, Pad Specs, Meta Key, Capabilities
2808 @section Initialization
2810 @cindex initialization
2816 String of commands to put the terminal into whatever special modes are
2817 needed or appropriate for programs that move the cursor
2818 nonsequentially around the screen. Programs that use termcap to do
2819 full-screen display should output this string when they start up.
2823 String of commands to undo what is done by the @samp{ti} string.
2824 Programs that output the @samp{ti} string on entry should output this
2825 string when they exit.
2829 String of commands to initialize the terminal for each login session.
2833 String which is the name of a file containing the string of commands
2834 to initialize the terminal for each session of use. Normally @samp{is}
2835 and @samp{if} are not both used.
2841 Two more strings of commands to initialize the terminal for each login
2842 session. The @samp{i1} string (if defined) is output before @samp{is}
2843 or @samp{if}, and the @samp{i3} string (if defined) is output after.
2845 The reason for having three separate initialization strings is to make
2846 it easier to define a group of related terminal types with slightly
2847 different initializations. Define two or three of the strings in the
2848 basic type; then the other types can override one or two of the
2853 String of commands to reset the terminal from any strange mode it may
2854 be in. Normally this includes the @samp{is} string (or other commands
2855 with the same effects) and more. What would go in the @samp{rs}
2856 string but not in the @samp{is} string are annoying or slow commands
2857 to bring the terminal back from strange modes that nobody would
2862 Numeric value, the initial spacing between hardware tab stop columns
2863 when the terminal is powered up. Programs to initialize the terminal
2864 can use this to decide whether there is a need to set the tab stops.
2865 If the initial width is 8, well and good; if it is not 8, then the
2866 tab stops should be set; if they cannot be set, the kernel is told
2867 to convert tabs to spaces, and other programs will observe this and do
2872 String of commands to clear all tab stops.
2876 String of commands to set tab stop at current cursor column on all
2880 @node Pad Specs, Status Line, Initialization, Capabilities
2881 @section Padding Capabilities
2884 There are two terminal capabilities that exist just to explain the proper
2885 way to obey the padding specifications in all the command string
2886 capabilities. One, @samp{pc}, must be obeyed by all termcap-using
2892 Numeric value, the lowest baud rate at which padding is actually
2893 needed. Programs may check this and refrain from doing any padding at
2898 String of commands for padding. The first character of this string is
2899 to be used as the pad character, instead of using null characters for
2900 padding. If @samp{pc} is not provided, use null characters. Every
2901 program that uses termcap must look up this capability and use it to
2902 set the variable @code{PC} that is used by @code{tputs}.
2906 Some termcap capabilities exist just to specify the amount of padding that
2907 the kernel should give to cursor motion commands used in ordinary
2913 Numeric value, the number of msec of padding needed for the
2914 carriage-return character.
2918 Numeric value, the number of msec of padding needed for the newline
2919 (linefeed) character.
2923 Numeric value, the number of msec of padding needed for the backspace
2928 Numeric value, the number of msec of padding needed for the formfeed
2933 Numeric value, the number of msec of padding needed for the tab
2937 In some systems, the kernel uses the above capabilities; in other systems,
2938 the kernel uses the paddings specified in the string capabilities
2939 @samp{cr}, @samp{sf}, @samp{le}, @samp{ff} and @samp{ta}. Descriptions of
2940 terminals which require such padding should contain the @samp{dC} @dots{}
2941 @samp{dT} capabilities and also specify the appropriate padding in the
2942 corresponding string capabilities. Since no modern terminals require
2943 padding for ordinary sequential output, you probably won't need to do
2944 either of these things.
2946 @node Status Line, Half-Line, Pad Specs, Capabilities
2947 @section Status Line
2950 A @dfn{status line} is a line on the terminal that is not used for ordinary
2951 display output but instead used for a special message. The intended use is
2952 for a continuously updated description of what the user's program is doing,
2953 and that is where the name ``status line'' comes from, but in fact it could
2954 be used for anything. The distinguishing characteristic of a status line
2955 is that ordinary output to the terminal does not affect it; it changes only
2956 if the special status line commands of this section are used.
2961 Flag whose presence means that the terminal has a status line. If a
2962 terminal description specifies that there is a status line, it must
2963 provide the @samp{ts} and @samp{fs} capabilities.
2967 String of commands to move the terminal cursor into the status line.
2968 Usually these commands must specifically record the old cursor
2969 position for the sake of the @samp{fs} string.
2973 String of commands to move the cursor back from the status line to its
2974 previous position (outside the status line).
2978 Flag whose presence means that other display commands work while
2979 writing the status line. In other words, one can clear parts of it,
2980 insert or delete characters, move the cursor within it using @samp{ch}
2981 if there is a @samp{ch} capability, enter and leave standout mode, and
2986 String of commands to disable the display of the status line. This
2987 may be absent, if there is no way to disable the status line display.
2991 Numeric value, the width of the status line. If this capability is
2992 absent in a terminal that has a status line, it means the status line
2993 is the same width as the other lines.
2995 Note that the value of @samp{ws} is sometimes as small as 8.
2998 @node Half-Line, Printer, Status Line, Capabilities
2999 @section Half-Line Motion
3001 Some terminals have commands for moving the cursor vertically by half-lines,
3002 useful for outputting subscripts and superscripts. Mostly it is hardcopy
3003 terminals that have such features.
3008 String of commands to move the cursor up half a line. If the terminal
3009 is a display, it is your responsibility to avoid moving up past the
3010 top line; however, most likely the terminal that supports this is a
3011 hardcopy terminal and there is nothing to be concerned about.
3015 String of commands to move the cursor down half a line. If the
3016 terminal is a display, it is your responsibility to avoid moving down
3017 past the bottom line, etc.
3020 @node Printer,, Half-Line, Capabilities
3021 @section Controlling Printers Attached to Terminals
3024 Some terminals have attached hardcopy printer ports. They may be able to
3025 copy the screen contents to the printer; they may also be able to redirect
3026 output to the printer. Termcap does not have anything to tell the program
3027 whether the redirected output appears also on the screen; it does on some
3028 terminals but not all.
3033 String of commands to cause the contents of the screen to be printed.
3034 If it is absent, the screen contents cannot be printed.
3038 String of commands to redirect further output to the printer.
3042 String of commands to terminate redirection of output to the printer.
3043 This capability must be present in the description if @samp{po} is.
3047 String of commands to redirect output to the printer for next @var{n}
3048 characters of output, regardless of what they are. Redirection will
3049 end automatically after @var{n} characters of further output. Until
3050 then, nothing that is output can end redirection, not even the
3051 @samp{pf} string if there is one. The number @var{n} should not be
3054 One use of this capability is to send non-text byte sequences (such as
3055 bit-maps) to the printer.
3058 Most terminals with printers do not support all of @samp{ps}, @samp{po} and
3059 @samp{pO}; any one or two of them may be supported. To make a program that
3060 can send output to all kinds of printers, it is necessary to check for all
3061 three of these capabilities, choose the most convenient of the ones that
3062 are provided, and use it in its own appropriate fashion.
3064 @node Summary, Var Index, Capabilities, Top
3065 @chapter Summary of Capability Names
3067 Here are all the terminal capability names in alphabetical order
3068 with a brief description of each. For cross references to their definitions,
3069 see the index of capability names (@pxref{Cap Index}).
3073 String to turn off alternate character set mode.
3075 String to insert a blank line before the cursor.
3077 String to insert @var{n} blank lines before the cursor.
3079 Flag: output to last column wraps cursor to next line.
3081 String to turn on alternate character set mode.like.
3083 Very obsolete alternative name for the @samp{le} capability.
3085 String to sound the bell.
3087 Obsolete flag: ASCII backspace may be used for leftward motion.
3089 String to move the cursor left to the previous hardware tab stop column.
3091 Flag: @samp{le} at left margin wraps to end of previous line.
3093 String to change terminal's command character.
3095 String to clear the line the cursor is on, and following lines.
3097 String to clear from the cursor to the end of the line.
3099 String to position the cursor at column @var{c} in the same line.
3101 String to clear the entire screen and put cursor at upper left corner.
3103 String to position the cursor at line @var{l}, column @var{c}.
3105 String to position the cursor at line @var{l}, column
3106 @var{c}, relative to display memory.
3108 Number: width of the screen.
3110 String to move cursor sideways to left margin.
3112 String to set the scroll region.
3114 Alternate form of string to set the scroll region.
3116 String to clear all tab stops.
3118 String to position the cursor at line @var{l} in the same column.
3120 Flag: data scrolled off top of screen may be scrolled back.
3122 Flag: data scrolled off bottom of screen may be scrolled back.
3124 Obsolete number: msec of padding needed for the backspace character.
3126 String to delete one character position at the cursor.
3128 Obsolete number: msec of padding needed for the carriage-return character.
3130 String to delete @var{n} characters starting at the cursor.
3132 Obsolete number: msec of padding needed for the formfeed character.
3134 String to delete the line the cursor is on.
3136 String to delete @var{n} lines starting with the cursor's line.
3138 String to enter delete mode.
3140 Obsolete number: msec of padding needed for the newline character.
3142 String to move the cursor vertically down one line.
3144 String to move cursor vertically down @var{n} lines.
3146 String to disable the display of the status line.
3148 Obsolete number: msec of padding needed for the tab character.
3150 String of commands to clear @var{n} characters at cursor.
3152 String to exit delete mode.
3154 String to leave insert mode.
3156 Flag: output of a space can erase an overstrike.
3158 Flag: other display commands work while writing the status line.
3160 String to advance to the next page, for a hardcopy terminal.
3162 String to move the cursor back from the status line to its
3163 previous position (outside the status line).
3165 Flag: this terminal type is generic, not real.
3167 Flag: hardcopy terminal.
3169 String to move the cursor down half a line.
3171 String to position cursor at upper left corner.
3173 Flag: the terminal has a status line.
3175 String to move the cursor up half a line.
3177 Flag: terminal cannot accept @samp{~} as output.
3179 String to initialize the terminal for each login session.
3181 String to initialize the terminal for each login session.
3183 String to insert one character position at the cursor.
3185 String to insert @var{n} character positions at the cursor.
3187 String naming a file of commands to initialize the terminal.
3189 String to enter insert mode.
3191 Flag: outputting a space is different from moving over empty positions.
3193 String to output following an inserted character in insert mode.
3195 String to initialize the terminal for each login session.
3197 Number: initial spacing between hardware tab stop columns.
3199 String of input sent by function key 0 or 10.
3201 Strings of input sent by function keys 1 through 9.
3203 Strings sent by the five other keys in 3-by-3 array with arrows.
3205 String of input sent by the ``clear all tabs'' key.
3207 String of input sent by the ``insert line'' key.
3209 String of input sent by the ``backspace'' key.
3211 String of input sent by the ``clear screen'' key.
3213 String of input sent by typing the down-arrow key.
3215 String of input sent by the ``delete character'' key.
3217 String to make the function keys work locally.
3219 String of input sent by the ``clear to end of line'' key.
3221 String of input sent by the ``scroll forward'' key.
3223 String of input sent by typing the ``home-position'' key.
3225 String of input sent by the ``home down'' key.
3227 String of input sent by the ``insert character'' or ``enter
3230 String of input sent by typing the left-arrow key.
3232 String of input sent by the ``delete line'' key.
3234 Flag: the terminal has a Meta key.
3236 String of input sent by the ``exit insert mode'' key.
3238 Numeric value, the number of numbered function keys.
3240 String of input sent by the ``next page'' key.
3242 Very obsolete string listing the terminal's named function keys.
3244 String of input sent by the ``previous page'' key.
3246 String of input sent by typing the right-arrow key.
3248 String of input sent by the ``scroll reverse'' key.
3250 String to make the function keys transmit.
3252 String of input sent by the ``clear to end of screen'' key.
3254 String of input sent by the ``clear tab stop this column'' key.
3256 String of input sent by the ``set tab stop in this column'' key.
3258 String of input sent by typing the up-arrow key.
3260 String on keyboard labelling function key 0 or 10.
3262 Strings on keyboard labelling function keys 1 through 9.
3264 String to move the cursor left one column.
3266 String to move cursor left @var{n} columns.
3268 Number: height of the screen.
3270 String to position cursor at lower left corner.
3272 Number: lines of display memory.
3274 String to enter blinking mode.
3276 String to enter double-bright mode.
3278 String to turn off all appearance modes
3280 String to enter half-bright mode.
3282 Flag: cursor motion in insert mode is safe.
3284 String to enter invisible mode.
3286 String to enable the functioning of the Meta key.
3288 String to disable the functioning of the Meta key.
3290 String to enter protected mode.
3292 String to enter reverse-video mode.
3294 Flag: cursor motion in standout mode is safe.
3296 Obsolete flag: do not use ASCII carriage-return on this terminal.
3298 String to move the cursor right one column.
3300 Obsolete alternative name for the @samp{do} and @samp{sf} capabilities.
3302 Flag: the terminal does not normally scroll for sequential output.
3304 String to move to start of next line, possibly clearing rest of old line.
3306 Flag: terminal can overstrike.
3308 Number: the lowest baud rate at which padding is actually needed.
3310 String containing character for padding.
3312 String to terminate redirection of output to the printer.
3314 String to redirect further output to the printer.
3316 String to redirect @var{n} characters ofoutput to the printer.
3318 String to print the screen on the attached printer.
3320 String to move to last saved cursor position.
3322 String to move cursor right @var{n} columns.
3324 String to output character @var{c} repeated @var{n} times.
3326 String to reset the terminal from any strange modes.
3328 String to turn on an arbitrary combination of appearance modes.
3330 String to save the current cursor position.
3332 String to leave standout mode.
3334 String to scroll the screen one line up.
3336 String to scroll the screen @var{n} lines up.
3338 Number: width of magic standout cookie. Absent if magic cookies are
3341 String to enter standout mode.
3343 String to scroll the screen one line down.
3345 String to scroll the screen @var{n} line down.
3347 String to set tab stop at current cursor column on all lines.
3350 String to move the cursor right to the next hardware tab stop column.
3352 String to return terminal to settings for sequential output.
3354 String to initialize terminal for random cursor motion.
3356 String to move the terminal cursor into the status line.
3358 String to underline one character and move cursor right.
3360 String to turn off underline mode
3362 Number: width of underlining magic cookie. Absent if underlining
3363 doesn't use magic cookies.
3365 Flag: underline by overstriking with an underscore.
3367 String to move the cursor vertically up one line.
3369 String to move cursor vertically up @var{n} lines.
3371 String to turn on underline mode
3373 String to make the screen flash.
3375 String to return the cursor to normal.
3377 String to make the cursor invisible.
3379 String to enhance the cursor.
3381 String to set the terminal output screen window.
3383 Number: the width of the status line.
3385 Flag: superbee terminal.
3387 Flag: cursor wraps in a strange way.
3389 Flag: clearing a line is the only way to clear the appearance modes of
3390 positions in that line (or, only way to remove magic cookies on that
3393 Flag: Teleray 1061; several strange characteristics.
3396 @node Var Index, Cap Index, Summary, Top
3397 @unnumbered Variable and Function Index
3401 @node Cap Index, Index, Var Index, Top
3402 @unnumbered Capability Index
3406 @node Index,, Cap Index, Top
3407 @unnumbered Concept Index