1 \input texinfo @c -*-texinfo-*-
2 @setfilename termcap.info
3 @settitle The Termcap Library
7 This file documents the termcap library of the GNU system.
9 Copyright (C) 1988 Free Software Foundation, Inc.
11 Permission is granted to make and distribute verbatim copies of
12 this manual provided the copyright notice and this permission notice
13 are preserved on all copies.
16 Permission is granted to process this file through TeX and print the
17 results, provided the printed document carries copying permission
18 notice identical to this one except for the removal of this paragraph
19 (this paragraph not being relevant to the printed manual).
22 Permission is granted to copy and distribute modified versions of this
23 manual under the conditions for verbatim copying, provided that the entire
24 resulting derived work is distributed under the terms of a permission
25 notice identical to this one.
27 Permission is granted to copy and distribute translations of this manual
28 into another language, under the above conditions for modified versions,
29 except that this permission notice may be stated in a translation approved
33 @setchapternewpage odd
35 @c @shorttitlepage The Termcap Manual
40 @center @titlefont{Termcap}
42 @center The Termcap Library and Data Base
44 @center Second Edition
48 @center Richard M. Stallman
50 @center Free Software Foundation
54 @title The Termcap Manual
55 @subtitle The Termcap Library and Data Base
56 @subtitle Second Edition
57 @subtitle December 1992
58 @author Richard M. Stallman
60 @vskip 0pt plus 1filll
61 Copyright @copyright{} 1988 Free Software Foundation, Inc.
63 Published by the Free Software Foundation
64 (59 Temple Place, Suite 330, Boston, MA 02111 USA).
65 Printed copies are available for $10 each.
67 Permission is granted to make and distribute verbatim copies of
68 this manual provided the copyright notice and this permission notice
69 are preserved on all copies.
71 Permission is granted to copy and distribute modified versions of this
72 manual under the conditions for verbatim copying, provided that the entire
73 resulting derived work is distributed under the terms of a permission
74 notice identical to this one.
76 Permission is granted to copy and distribute translations of this manual
77 into another language, under the above conditions for modified versions,
78 except that this permission notice may be stated in a translation approved
81 Cover art by Etienne Suvasa.
87 @node Top, Introduction, (dir), (dir)
90 * Introduction:: What is termcap? Why this manual?
91 * Library:: The termcap library functions.
92 * Data Base:: What terminal descriptions in @file{/etc/termcap} look like.
93 * Capabilities:: Definitions of the individual terminal capabilities:
94 how to write them in descriptions, and how to use
95 their values to do display updating.
96 * Summary:: Brief table of capability names and their meanings.
97 * Var Index:: Index of C functions and variables.
98 * Cap Index:: Index of termcap capabilities.
99 * Index:: Concept index.
101 --- The Detailed Node Listing ---
105 * Preparation:: Preparing to use the termcap library.
106 * Find:: Finding the description of the terminal being used.
107 * Interrogate:: Interrogating the description for particular capabilities.
108 * Initialize:: Initialization for output using termcap.
109 * Padding:: Outputting padding.
110 * Parameters:: Encoding parameters such as cursor positions.
114 * Why Pad:: Explanation of padding.
115 * Not Enough:: When there is not enough padding.
116 * Describe Padding:: The data base says how much padding a terminal needs.
117 * Output Padding:: Using @code{tputs} to output the needed padding.
119 Filling In Parameters
121 * Encode Parameters:: The language for encoding parameters.
122 * Using Parameters:: Outputting a string command with parameters.
124 Sending Display Commands with Parameters
126 * tparam:: The general case, for GNU termcap only.
127 * tgoto:: The special case of cursor motion.
129 The Format of the Data Base
131 * Format:: Overall format of a terminal description.
132 * Capability Format:: Format of capabilities within a description.
133 * Naming:: Naming conventions for terminal types.
134 * Inheriting:: Inheriting part of a description from
135 a related terminal type.
136 * Changing:: When changes in the data base take effect.
138 Definitions of the Terminal Capabilities
140 * Basic:: Basic characteristics.
141 * Screen Size:: Screen size, and what happens when it changes.
142 * Cursor Motion:: Various ways to move the cursor.
143 * Wrapping:: What happens if you write a character in the last column.
144 * Scrolling:: Pushing text up and down on the screen.
145 * Windows:: Limiting the part of the window that output affects.
146 * Clearing:: Erasing one or many lines.
147 * Insdel Line:: Making new blank lines in mid-screen; deleting lines.
148 * Insdel Char:: Inserting and deleting characters within a line.
149 * Standout:: Highlighting some of the text.
150 * Underlining:: Underlining some of the text.
151 * Cursor Visibility:: Making the cursor more or less easy to spot.
152 * Bell:: Attracts user's attention; not localized on the screen.
153 * Keypad:: Recognizing when function keys or arrows are typed.
154 * Meta Key:: @key{META} acts like an extra shift key.
155 * Initialization:: Commands used to initialize or reset the terminal.
156 * Pad Specs:: Info for the kernel on how much padding is needed.
157 * Status Line:: A status line displays ``background'' information.
158 * Half-Line:: Moving by half-lines, for superscripts and subscripts.
159 * Printer:: Controlling auxiliary printers of display terminals.
162 @node Introduction, Library, Top, Top
163 @unnumbered Introduction
166 @dfn{Termcap} is a library and data base that enables programs to use
167 display terminals in a terminal-independent manner. It originated in
170 The termcap data base describes the capabilities of hundreds of different
171 display terminals in great detail. Some examples of the information
172 recorded for a terminal could include how many columns wide it is, what
173 string to send to move the cursor to an arbitrary position (including how
174 to encode the row and column numbers), how to scroll the screen up one or
175 several lines, and how much padding is needed for such a scrolling
178 The termcap library is provided for easy access this data base in programs
179 that want to do terminal-independent character-based display output.
181 This manual describes the GNU version of the termcap library, which has
182 some extensions over the Unix version. All the extensions are identified
183 as such, so this manual also tells you how to use the Unix termcap.
185 The GNU version of the termcap library is available free as source code,
186 for use in free programs, and runs on Unix and VMS systems (at least). You
187 can find it in the GNU Emacs distribution in the files @file{termcap.c} and
190 This manual was written for the GNU project, whose goal is to develop a
191 complete free operating system upward-compatible with Unix for user
192 programs. The project is approximately two thirds complete. For more
193 information on the GNU project, including the GNU Emacs editor and the
194 mostly-portable optimizing C compiler, send one dollar to
197 Free Software Foundation
202 @node Library, Data Base, Introduction, Top
203 @chapter The Termcap Library
205 The termcap library is the application programmer's interface to the
206 termcap data base. It contains functions for the following purposes:
210 Finding the description of the user's terminal type (@code{tgetent}).
213 Interrogating the description for information on various topics
214 (@code{tgetnum}, @code{tgetflag}, @code{tgetstr}).
217 Computing and performing padding (@code{tputs}).
220 Encoding numeric parameters such as cursor positions into the
221 terminal-specific form required for display commands (@code{tparam},
226 * Preparation:: Preparing to use the termcap library.
227 * Find:: Finding the description of the terminal being used.
228 * Interrogate:: Interrogating the description for particular capabilities.
229 * Initialize:: Initialization for output using termcap.
230 * Padding:: Outputting padding.
231 * Parameters:: Encoding parameters such as cursor positions.
234 @node Preparation, Find, , Library
235 @section Preparing to Use the Termcap Library
237 To use the termcap library in a program, you need two kinds of preparation:
241 The compiler needs declarations of the functions and variables in the
244 On GNU systems, it suffices to include the header file
245 @file{termcap.h} in each source file that uses these functions and
248 On Unix systems, there is often no such header file. Then you must
249 explictly declare the variables as external. You can do likewise for
250 the functions, or let them be implicitly declared and cast their
251 values from type @code{int} to the appropriate type.
253 We illustrate the declarations of the individual termcap library
254 functions with ANSI C prototypes because they show how to pass the
255 arguments. If you are not using the GNU C compiler, you probably
256 cannot use function prototypes, so omit the argument types and names
257 from your declarations.
260 The linker needs to search the library. Usually either
261 @samp{-ltermcap} or @samp{-ltermlib} as an argument when linking will
265 @node Find, Interrogate, Preparation, Library
266 @section Finding a Terminal Description: @code{tgetent}
269 An application program that is going to use termcap must first look up the
270 description of the terminal type in use. This is done by calling
271 @code{tgetent}, whose declaration in ANSI Standard C looks like:
274 int tgetent (char *@var{buffer}, char *@var{termtype});
278 This function finds the description and remembers it internally so that
279 you can interrogate it about specific terminal capabilities
280 (@pxref{Interrogate}).
282 The argument @var{termtype} is a string which is the name for the type of
283 terminal to look up. Usually you would obtain this from the environment
284 variable @code{TERM} using @code{getenv ("TERM")}.
286 If you are using the GNU version of termcap, you can alternatively ask
287 @code{tgetent} to allocate enough space. Pass a null pointer for
288 @var{buffer}, and @code{tgetent} itself allocates the storage using
289 @code{malloc}. There is no way to get the address that was allocated,
290 and you shouldn't try to free the storage.@refill
292 With the Unix version of termcap, you must allocate space for the
293 description yourself and pass the address of the space as the argument
294 @var{buffer}. There is no way you can tell how much space is needed, so
295 the convention is to allocate a buffer 2048 characters long and assume that
296 is enough. (Formerly the convention was to allocate 1024 characters and
297 assume that was enough. But one day, for one kind of terminal, that was
300 No matter how the space to store the description has been obtained,
301 termcap records its address internally for use when you later interrogate
302 the description with @code{tgetnum}, @code{tgetstr} or @code{tgetflag}. If
303 the buffer was allocated by termcap, it will be freed by termcap too if you
304 call @code{tgetent} again. If the buffer was provided by you, you must
305 make sure that its contents remain unchanged for as long as you still plan
306 to interrogate the description.@refill
308 The return value of @code{tgetent} is @minus{}1 if there is some difficulty
309 accessing the data base of terminal types, 0 if the data base is accessible
310 but the specified type is not defined in it, and some other value
313 Here is how you might use the function @code{tgetent}:
317 static char term_buffer[2048];
319 #define term_buffer 0
322 init_terminal_data ()
324 char *termtype = getenv ("TERM");
328 fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
330 success = tgetent (term_buffer, termtype);
332 fatal ("Could not access the termcap data base.\n");
334 fatal ("Terminal type `%s' is not defined.\n", termtype);
339 Here we assume the function @code{fatal} prints an error message and exits.
341 If the environment variable @code{TERMCAP} is defined, its value is used to
342 override the terminal type data base. The function @code{tgetent} checks
343 the value of @code{TERMCAP} automatically. If the value starts with
344 @samp{/} then it is taken as a file name to use as the data base file,
345 instead of @file{/etc/termcap} which is the standard data base. If the
346 value does not start with @samp{/} then it is itself used as the terminal
347 description, provided that the terminal type @var{termtype} is among the
348 types it claims to apply to. @xref{Data Base}, for information on the
349 format of a terminal description.@refill
351 @node Interrogate, Initialize, Find, Library
352 @section Interrogating the Terminal Description
354 Each piece of information recorded in a terminal description is called a
355 @dfn{capability}. Each defined terminal capability has a two-letter code
356 name and a specific meaning. For example, the number of columns is named
357 @samp{co}. @xref{Capabilities}, for definitions of all the standard
360 Once you have found the proper terminal description with @code{tgetent}
361 (@pxref{Find}), your application program must @dfn{interrogate} it for
362 various terminal capabilities. You must specify the two-letter code of
363 the capability whose value you seek.
365 Capability values can be numeric, boolean (capability is either present or
366 absent) or strings. Any particular capability always has the same value
367 type; for example, @samp{co} always has a numeric value, while @samp{am}
368 (automatic wrap at margin) is always a flag, and @samp{cm} (cursor motion
369 command) always has a string value. The documentation of each capability
370 says which type of value it has.@refill
372 There are three functions to use to get the value of a capability,
373 depending on the type of value the capability has. Here are their
374 declarations in ANSI C:
380 int tgetnum (char *@var{name});
381 int tgetflag (char *@var{name});
382 char *tgetstr (char *@var{name}, char **@var{area});
387 Use @code{tgetnum} to get a capability value that is numeric. The
388 argument @var{name} is the two-letter code name of the capability. If
389 the capability is present, @code{tgetnum} returns the numeric value
390 (which is nonnegative). If the capability is not mentioned in the
391 terminal description, @code{tgetnum} returns @minus{}1.
394 Use @code{tgetflag} to get a boolean value. If the capability
395 @var{name} is present in the terminal description, @code{tgetflag}
396 returns 1; otherwise, it returns 0.
399 Use @code{tgetstr} to get a string value. It returns a pointer to a
400 string which is the capability value, or a null pointer if the
401 capability is not present in the terminal description.
403 There are two ways @code{tgetstr} can find space to store the string value:
407 You can ask @code{tgetstr} to allocate the space. Pass a null
408 pointer for the argument @var{area}, and @code{tgetstr} will use
409 @code{malloc} to allocate storage big enough for the value.
410 Termcap will never free this storage or refer to it again; you
411 should free it when you are finished with it.
413 This method is more robust, since there is no need to guess how
414 much space is needed. But it is supported only by the GNU
418 You can provide the space. Provide for the argument @var{area} the
419 address of a pointer variable of type @code{char *}. Before calling
420 @code{tgetstr}, initialize the variable to point at available space.
421 Then @code{tgetstr} will store the string value in that space and will
422 increment the pointer variable to point after the space that has been
423 used. You can use the same pointer variable for many calls to
426 There is no way to determine how much space is needed for a single
427 string, and no way for you to prevent or handle overflow of the area
428 you have provided. However, you can be sure that the total size of
429 all the string values you will obtain from the terminal description is
430 no greater than the size of the description (unless you get the same
431 capability twice). You can determine that size with @code{strlen} on
432 the buffer you provided to @code{tgetent}. See below for an example.
434 Providing the space yourself is the only method supported by the Unix
439 Note that you do not have to specify a terminal type or terminal
440 description for the interrogation functions. They automatically use the
441 description found by the most recent call to @code{tgetent}.
443 Here is an example of interrogating a terminal description for various
444 capabilities, with conditionals to select between the Unix and GNU methods
445 of providing buffer space.
450 char *cl_string, *cm_string;
455 char PC; /* For tputs. */
456 char *BC; /* For tgoto. */
459 interrogate_terminal ()
462 /* Here we assume that an explicit term_buffer
463 was provided to tgetent. */
465 = (char *) malloc (strlen (term_buffer));
466 #define BUFFADDR &buffer
473 /* Extract information we will use. */
474 cl_string = tgetstr ("cl", BUFFADDR);
475 cm_string = tgetstr ("cm", BUFFADDR);
476 auto_wrap = tgetflag ("am");
477 height = tgetnum ("li");
478 width = tgetnum ("co");
480 /* Extract information that termcap functions use. */
481 temp = tgetstr ("pc", BUFFADDR);
482 PC = temp ? *temp : 0;
483 BC = tgetstr ("le", BUFFADDR);
484 UP = tgetstr ("up", BUFFADDR);
489 @xref{Padding}, for information on the variable @code{PC}. @xref{Using
490 Parameters}, for information on @code{UP} and @code{BC}.
492 @node Initialize, Padding, Interrogate, Library
493 @section Initialization for Use of Termcap
494 @cindex terminal flags (kernel)
496 Before starting to output commands to a terminal using termcap,
497 an application program should do two things:
501 Initialize various global variables which termcap library output
502 functions refer to. These include @code{PC} and @code{ospeed} for
503 padding (@pxref{Output Padding}) and @code{UP} and @code{BC} for
504 cursor motion (@pxref{tgoto}).@refill
507 Tell the kernel to turn off alteration and padding of horizontal-tab
508 characters sent to the terminal.
511 To turn off output processing in Berkeley Unix you would use @code{ioctl}
512 with code @code{TIOCLSET} to set the bit named @code{LLITOUT}, and clear
513 the bits @code{ANYDELAY} using @code{TIOCSETN}. In POSIX or System V, you
514 must clear the bit named @code{OPOST}. Refer to the system documentation
517 If you do not set the terminal flags properly, some older terminals will
518 not work. This is because their commands may contain the characters that
519 normally signify newline, carriage return and horizontal tab---characters
520 which the kernel thinks it ought to modify before output.
522 When you change the kernel's terminal flags, you must arrange to restore
523 them to their normal state when your program exits. This implies that the
524 program must catch fatal signals such as @code{SIGQUIT} and @code{SIGINT}
525 and restore the old terminal flags before actually terminating.
527 Modern terminals' commands do not use these special characters, so if you
528 do not care about problems with old terminals, you can leave the kernel's
529 terminal flags unaltered.
531 @node Padding, Parameters, Initialize, Library
535 @dfn{Padding} means outputting null characters following a terminal display
536 command that takes a long time to execute. The terminal description says
537 which commands require padding and how much; the function @code{tputs},
538 described below, outputs a terminal command while extracting from it the
539 padding information, and then outputs the padding that is necessary.
542 * Why Pad:: Explanation of padding.
543 * Not Enough:: When there is not enough padding.
544 * Describe Padding:: The data base says how much padding a terminal needs.
545 * Output Padding:: Using @code{tputs} to output the needed padding.
548 @node Why Pad, Not Enough, , Padding
549 @subsection Why Pad, and How
551 Most types of terminal have commands that take longer to execute than they
552 do to send over a high-speed line. For example, clearing the screen may
553 take 20msec once the entire command is received. During that time, on a
554 9600 bps line, the terminal could receive about 20 additional output
555 characters while still busy clearing the screen. Every terminal has a
556 certain amount of buffering capacity to remember output characters that
557 cannot be processed yet, but too many slow commands in a row can cause the
558 buffer to fill up. Then any additional output that cannot be processed
559 immediately will be lost.
561 To avoid this problem, we normally follow each display command with enough
562 useless charaters (usually null characters) to fill up the time that the
563 display command needs to execute. This does the job if the terminal throws
564 away null characters without using up space in the buffer (which most
565 terminals do). If enough padding is used, no output can ever be lost. The
566 right amount of padding avoids loss of output without slowing down
567 operation, since the time used to transmit padding is time that nothing
570 The number of padding characters needed for an operation depends on the
571 line speed. In fact, it is proportional to the line speed. A 9600 baud
572 line transmits about one character per msec, so the clear screen command in
573 the example above would need about 20 characters of padding. At 1200 baud,
574 however, only about 3 characters of padding are needed to fill up 20msec.
576 @node Not Enough, Describe Padding, Why Pad, Padding
577 @subsection When There Is Not Enough Padding
579 There are several common manifestations of insufficient padding.
583 Emacs displays @samp{I-search: ^Q-} at the bottom of the screen.
585 This means that the terminal thought its buffer was getting full of
586 display commands, so it tried to tell the computer to stop sending
590 The screen is garbled intermittently, or the details of garbling vary
591 when you repeat the action. (A garbled screen could be due to a
592 command which is simply incorrect, or to user option in the terminal
593 which doesn't match the assumptions of the terminal description, but
594 this usually leads to reproducible failure.)
596 This means that the buffer did get full, and some commands were lost.
597 Many changeable factors can change which ones are lost.
600 Screen is garbled at high output speeds but not at low speeds.
601 Padding problems nearly always go away at low speeds, usually even at
604 This means that a high enough speed permits commands to arrive faster
605 than they can be executed.
608 Although any obscure command on an obscure terminal might lack padding,
609 in practice problems arise most often from the clearing commands
610 @samp{cl} and @samp{cd} (@pxref{Clearing}), the scrolling commands
611 @samp{sf} and @samp{sr} (@pxref{Scrolling}), and the line insert/delete
612 commands @samp{al} and @samp{dl} (@pxref{Insdel Line}).
614 Occasionally the terminal description fails to define @samp{sf} and some
615 programs will use @samp{do} instead, so you may get a problem with
616 @samp{do}. If so, first define @samp{sf} just like @samp{do}, then
617 add some padding to @samp{sf}.
619 The best strategy is to add a lot of padding at first, perhaps 200 msec.
620 This is much more than enough; in fact, it should cause a visible slowdown.
621 (If you don't see a slowdown, the change has not taken effect;
622 @pxref{Changing}.) If this makes the problem go away, you have found the
623 right place to add padding; now reduce the amount until the problem comes
624 back, then increase it again. If the problem remains, either it is in some
625 other capability or it is not a matter of padding at all.
627 Keep in mind that on many terminals the correct padding for insert/delete
628 line or for scrolling is cursor-position dependent. If you get problems
629 from scrolling a large region of the screen but not from scrolling a small
630 part (just a few lines moving), it may mean that fixed padding should be
631 replaced with position-dependent padding.
633 @node Describe Padding, Output Padding, Not Enough, Padding
634 @subsection Specifying Padding in a Terminal Description
636 In the terminal description, the amount of padding required by each display
637 command is recorded as a sequence of digits at the front of the command.
638 These digits specify the padding time in milliseconds (msec). They can be
639 followed optionally by a decimal point and one more digit, which is a
640 number of tenths of msec.
642 Sometimes the padding needed by a command depends on the cursor position.
643 For example, the time taken by an ``insert line'' command is usually
644 proportional to the number of lines that need to be moved down or cleared.
645 An asterisk (@samp{*}) following the padding time says that the time
646 should be multiplied by the number of screen lines affected by the command.
653 is used to describe the ``insert line'' command for a certain terminal.
654 The padding required is 1.3 msec per line affected. The command itself is
655 @samp{@key{ESC} [ L}.
657 The padding time specified in this way tells @code{tputs} how many pad
658 characters to output. @xref{Output Padding}.
660 Two special capability values affect padding for all commands. These are
661 the @samp{pc} and @samp{pb}. The variable @samp{pc} specifies the
662 character to pad with, and @samp{pb} the speed below which no padding is
663 needed. The defaults for these variables, a null character and 0,
664 are correct for most terminals. @xref{Pad Specs}.
666 @node Output Padding, , Describe Padding, Padding
667 @subsection Performing Padding with @code{tputs}
671 Use the termcap function @code{tputs} to output a string containing an
672 optional padding spec of the form described above (@pxref{Describe
673 Padding}). The function @code{tputs} strips off and decodes the padding
674 spec, outputs the rest of the string, and then outputs the appropriate
675 padding. Here is its declaration in ANSI C:
681 int tputs (char *@var{string}, int @var{nlines}, int (*@var{outfun}) ());
684 Here @var{string} is the string (including padding spec) to be output;
685 @var{nlines} is the number of lines affected by the operation, which is
686 used to multiply the amount of padding if the padding spec ends with a
687 @samp{*}. Finally, @var{outfun} is a function (such as @code{fputchar})
688 that is called to output each character. When actually called,
689 @var{outfun} should expect one argument, a character.
693 The operation of @code{tputs} is controlled by two global variables,
694 @code{ospeed} and @code{PC}. The value of @code{ospeed} is supposed to be
695 the terminal output speed, encoded as in the @code{ioctl} system call which
696 gets the speed information. This is needed to compute the number of
697 padding characters. The value of @code{PC} is the character used for
700 You are responsible for storing suitable values into these variables before
701 using @code{tputs}. The value stored into the @code{PC} variable should be
702 taken from the @samp{pc} capability in the terminal description (@pxref{Pad
703 Specs}). Store zero in @code{PC} if there is no @samp{pc}
706 The argument @var{nlines} requires some thought. Normally, it should be
707 the number of lines whose contents will be cleared or moved by the command.
708 For cursor motion commands, or commands that do editing within one line,
709 use the value 1. For most commands that affect multiple lines, such as
710 @samp{al} (insert a line) and @samp{cd} (clear from the cursor to the end
711 of the screen), @var{nlines} should be the screen height minus the current
712 vertical position (origin 0). For multiple insert and scroll commands such
713 as @samp{AL} (insert multiple lines), that same value for @var{nlines} is
714 correct; the number of lines being inserted is @i{not} correct.@refill
716 If a ``scroll window'' feature is used to reduce the number of lines
717 affected by a command, the value of @var{nlines} should take this into
718 account. This is because the delay time required depends on how much work
719 the terminal has to do, and the scroll window feature reduces the work.
722 Commands such as @samp{ic} and @samp{dc} (insert or delete characters) are
723 problematical because the padding needed by these commands is proportional
724 to the number of characters affected, which is the number of columns from
725 the cursor to the end of the line. It would be nice to have a way to
726 specify such a dependence, and there is no need for dependence on vertical
727 position in these commands, so it is an obvious idea to say that for these
728 commands @var{nlines} should really be the number of columns affected.
729 However, the definition of termcap clearly says that @var{nlines} is always
730 the number of lines affected, even in this case, where it is always 1. It
731 is not easy to change this rule now, because too many programs and terminal
732 descriptions have been written to follow it.
734 Because @var{nlines} is always 1 for the @samp{ic} and @samp{dc} strings,
735 there is no reason for them to use @samp{*}, but some of them do. These
736 should be corrected by deleting the @samp{*}. If, some day, such entries
737 have disappeared, it may be possible to change to a more useful convention
738 for the @var{nlines} argument for these operations without breaking any
741 @node Parameters, , Padding, Library
742 @section Filling In Parameters
745 Some terminal control strings require numeric @dfn{parameters}. For
746 example, when you move the cursor, you need to say what horizontal and
747 vertical positions to move it to. The value of the terminal's @samp{cm}
748 capability, which says how to move the cursor, cannot simply be a string of
749 characters; it must say how to express the cursor position numbers and
750 where to put them within the command.
752 The specifications of termcap include conventions as to which string-valued
753 capabilities require parameters, how many parameters, and what the
754 parameters mean; for example, it defines the @samp{cm} string to take
755 two parameters, the vertical and horizontal positions, with 0,0 being the
756 upper left corner. These conventions are described where the individual
757 commands are documented.
759 Termcap also defines a language used within the capability definition for
760 specifying how and where to encode the parameters for output. This language
761 uses character sequences starting with @samp{%}. (This is the same idea as
762 @code{printf}, but the details are different.) The language for parameter
763 encoding is described in this section.
765 A program that is doing display output calls the functions @code{tparam} or
766 @code{tgoto} to encode parameters according to the specifications. These
767 functions produce a string containing the actual commands to be output (as
768 well a padding spec which must be processed with @code{tputs};
772 * Encode Parameters:: The language for encoding parameters.
773 * Using Parameters:: Outputting a string command with parameters.
776 @node Encode Parameters, Using Parameters, , Parameters
777 @subsection Describing the Encoding
780 A terminal command string that requires parameters contains special
781 character sequences starting with @samp{%} to say how to encode the
782 parameters. These sequences control the actions of @code{tparam} and
785 The parameters values passed to @code{tparam} or @code{tgoto} are
786 considered to form a vector. A pointer into this vector determines
787 the next parameter to be processed. Some of the @samp{%}-sequences
788 encode one parameter and advance the pointer to the next parameter.
789 Other @samp{%}-sequences alter the pointer or alter the parameter
790 values without generating output.
792 For example, the @samp{cm} string for a standard ANSI terminal is written
793 as @samp{\E[%i%d;%dH}. (@samp{\E} stands for @key{ESC}.) @samp{cm} by
794 convention always requires two parameters, the vertical and horizontal goal
795 positions, so this string specifies the encoding of two parameters. Here
796 @samp{%i} increments the two values supplied, and each @samp{%d} encodes
797 one of the values in decimal. If the cursor position values 20,58 are
798 encoded with this string, the result is @samp{\E[21;59H}.
800 First, here are the @samp{%}-sequences that generate output. Except for
801 @samp{%%}, each of them encodes one parameter and advances the pointer
802 to the following parameter.
806 Output a single @samp{%}. This is the only way to represent a literal
807 @samp{%} in a terminal command with parameters. @samp{%%} does not
811 As in @code{printf}, output the next parameter in decimal.
814 Like @samp{%02d} in @code{printf}: output the next parameter in
815 decimal, and always use at least two digits.
818 Like @samp{%03d} in @code{printf}: output the next parameter in
819 decimal, and always use at least three digits. Note that @samp{%4}
820 and so on are @emph{not} defined.
823 Output the next parameter as a single character whose ASCII code is
824 the parameter value. Like @samp{%c} in @code{printf}.
827 Add the next parameter to the character @var{char}, and output the
828 resulting character. For example, @samp{%+ } represents 0 as a space,
832 The following @samp{%}-sequences specify alteration of the parameters
833 (their values, or their order) rather than encoding a parameter for output.
834 They generate no output; they are used only for their side effects
835 on the parameters. Also, they do not advance the ``next parameter'' pointer
836 except as explicitly stated. Only @samp{%i}, @samp{%r} and @samp{%>} are
837 defined in standard Unix termcap. The others are GNU extensions.@refill
841 Increment the next two parameters. This is used for terminals that
842 expect cursor positions in origin 1. For example, @samp{%i%d,%d} would
843 output two parameters with @samp{1} for 0, @samp{2} for 1, etc.
846 Interchange the next two parameters. This is used for terminals whose
847 cursor positioning command expects the horizontal position first.
850 Skip the next parameter. Do not output anything.
853 Back up one parameter. The last parameter used will become once again
854 the next parameter to be output, and the next output command will use
855 it. Using @samp{%b} more than once, you can back up any number of
856 parameters, and you can refer to each parameter any number of times.
858 @item %>@var{c1}@var{c2}
859 Conditionally increment the next parameter. Here @var{c1} and
860 @var{c2} are characters which stand for their ASCII codes as numbers.
861 If the next parameter is greater than the ASCII code of @var{c1}, the
862 ASCII code of @var{c2} is added to it.@refill
864 @item %a @var{op} @var{type} @var{pos}
865 Perform arithmetic on the next parameter, do not use it up, and do not
866 output anything. Here @var{op} specifies the arithmetic operation,
867 while @var{type} and @var{pos} together specify the other operand.
869 Spaces are used above to separate the operands for clarity; the spaces
870 don't appear in the data base, where this sequence is exactly five
873 The character @var{op} says what kind of arithmetic operation to
874 perform. It can be any of these characters:
878 assign a value to the next parameter, ignoring its old value.
879 The new value comes from the other operand.
882 add the other operand to the next parameter.
885 subtract the other operand from the next parameter.
888 multiply the next parameter by the other operand.
891 divide the next parameter by the other operand.
894 The ``other operand'' may be another parameter's value or a constant;
895 the character @var{type} says which. It can be:
899 Use another parameter. The character @var{pos} says which
900 parameter to use. Subtract 64 from its ASCII code to get the
901 position of the desired parameter relative to this one. Thus,
902 the character @samp{A} as @var{pos} means the parameter after the
903 next one; the character @samp{?} means the parameter before the
907 Use a constant value. The character @var{pos} specifies the
908 value of the constant. The 0200 bit is cleared out, so that 0200
909 can be used to represent zero.
913 The following @samp{%}-sequences are special purpose hacks to compensate
914 for the weird designs of obscure terminals. They modify the next parameter
915 or the next two parameters but do not generate output and do not use up any
916 parameters. @samp{%m} is a GNU extension; the others are defined in
917 standard Unix termcap.
921 Exclusive-or the next parameter with 0140, and likewise the parameter
925 Complement all the bits of the next parameter and the parameter after next.
928 Encode the next parameter in BCD. It alters the value of the
929 parameter by adding six times the quotient of the parameter by ten.
930 Here is a C statement that shows how the new value is computed:
933 @var{parm} = (@var{parm} / 10) * 16 + @var{parm} % 10;
937 Transform the next parameter as needed by Delta Data terminals.
938 This involves subtracting twice the remainder of the parameter by 16.
941 @var{parm} -= 2 * (@var{parm} % 16);
945 @node Using Parameters, , Encode Parameters, Parameters
946 @subsection Sending Display Commands with Parameters
948 The termcap library functions @code{tparam} and @code{tgoto} serve as the
949 analog of @code{printf} for terminal string parameters. The newer function
950 @code{tparam} is a GNU extension, more general but missing from Unix
951 termcap. The original parameter-encoding function is @code{tgoto}, which
952 is preferable for cursor motion.
955 * tparam:: The general case, for GNU termcap only.
956 * tgoto:: The special case of cursor motion.
959 @node tparam, tgoto, , Using Parameters
960 @subsubsection @code{tparam}
963 The function @code{tparam} can encode display commands with any number of
964 parameters and allows you to specify the buffer space. It is the preferred
965 function for encoding parameters for all but the @samp{cm} capability. Its
966 ANSI C declaration is as follows:
969 char *tparam (char *@var{ctlstring}, char *@var{buffer}, int @var{size}, int @var{parm1},...)
972 The arguments are a control string @var{ctlstring} (the value of a terminal
973 capability, presumably), an output buffer @var{buffer} and @var{size}, and
974 any number of integer parameters to be encoded. The effect of
975 @code{tparam} is to copy the control string into the buffer, encoding
976 parameters according to the @samp{%} sequences in the control string.
978 You describe the output buffer by its address, @var{buffer}, and its size
979 in bytes, @var{size}. If the buffer is not big enough for the data to be
980 stored in it, @code{tparam} calls @code{malloc} to get a larger buffer. In
981 either case, @code{tparam} returns the address of the buffer it ultimately
982 uses. If the value equals @var{buffer}, your original buffer was used.
983 Otherwise, a new buffer was allocated, and you must free it after you are
984 done with printing the results. If you pass zero for @var{size} and
985 @var{buffer}, @code{tparam} always allocates the space with @code{malloc}.
987 All capabilities that require parameters also have the ability to specify
988 padding, so you should use @code{tputs} to output the string produced by
989 @code{tparam}. @xref{Padding}. Here is an example.
996 buf = tparam (command, buffer, 40, parm);
997 tputs (buf, 1, fputchar);
1003 If a parameter whose value is zero is encoded with @samp{%.}-style
1004 encoding, the result is a null character, which will confuse @code{tputs}.
1005 This would be a serious problem, but luckily @samp{%.} encoding is used
1006 only by a few old models of terminal, and only for the @samp{cm}
1007 capability. To solve the problem, use @code{tgoto} rather than
1008 @code{tparam} to encode the @samp{cm} capability.@refill
1010 @node tgoto, , tparam, Using Parameters
1011 @subsubsection @code{tgoto}
1014 The special case of cursor motion is handled by @code{tgoto}. There
1015 are two reasons why you might choose to use @code{tgoto}:
1019 For Unix compatibility, because Unix termcap does not have @code{tparam}.
1022 For the @samp{cm} capability, since @code{tgoto} has a special feature
1023 to avoid problems with null characters, tabs and newlines on certain old
1024 terminal types that use @samp{%.} encoding for that capability.
1027 Here is how @code{tgoto} might be declared in ANSI C:
1030 char *tgoto (char *@var{cstring}, int @var{hpos}, int @var{vpos})
1033 There are three arguments, the terminal description's @samp{cm} string and
1034 the two cursor position numbers; @code{tgoto} computes the parametrized
1035 string in an internal static buffer and returns the address of that buffer.
1036 The next time you use @code{tgoto} the same buffer will be reused.
1040 Parameters encoded with @samp{%.} encoding can generate null characters,
1041 tabs or newlines. These might cause trouble: the null character because
1042 @code{tputs} would think that was the end of the string, the tab because
1043 the kernel or other software might expand it into spaces, and the newline
1044 becaue the kernel might add a carriage-return, or padding characters
1045 normally used for a newline. To prevent such problems, @code{tgoto} is
1046 careful to avoid these characters. Here is how this works: if the target
1047 cursor position value is such as to cause a problem (that is to say, zero,
1048 nine or ten), @code{tgoto} increments it by one, then compensates by
1049 appending a string to move the cursor back or up one position.
1051 The compensation strings to use for moving back or up are found in global
1052 variables named @code{BC} and @code{UP}. These are actual external C
1053 variables with upper case names; they are declared @code{char *}. It is up
1054 to you to store suitable values in them, normally obtained from the
1055 @samp{le} and @samp{up} terminal capabilities in the terminal description
1056 with @code{tgetstr}. Alternatively, if these two variables are both zero,
1057 the feature of avoiding nulls, tabs and newlines is turned off.
1059 It is safe to use @code{tgoto} for commands other than @samp{cm} only if
1060 you have stored zero in @code{BC} and @code{UP}.
1062 Note that @code{tgoto} reverses the order of its operands: the horizontal
1063 position comes before the vertical position in the arguments to
1064 @code{tgoto}, even though the vertical position comes before the horizontal
1065 in the parameters of the @samp{cm} string. If you use @code{tgoto} with a
1066 command such as @samp{AL} that takes one parameter, you must pass the
1067 parameter to @code{tgoto} as the ``vertical position''.@refill
1069 @node Data Base, Capabilities, Library, Top
1070 @chapter The Format of the Data Base
1072 The termcap data base of terminal descriptions is stored in the file
1073 @file{/etc/termcap}. It contains terminal descriptions, blank lines, and
1076 A terminal description starts with one or more names for the terminal type.
1077 The information in the description is a series of @dfn{capability names}
1078 and values. The capability names have standard meanings
1079 (@pxref{Capabilities}) and their values describe the terminal.
1082 * Format:: Overall format of a terminal description.
1083 * Capability Format:: Format of capabilities within a description.
1084 * Naming:: Naming conventions for terminal types.
1085 * Inheriting:: Inheriting part of a description from
1086 a related terminal type.
1087 * Changing:: When changes in the data base take effect.
1090 @node Format, Capability Format, , Data Base
1091 @section Terminal Description Format
1092 @cindex description format
1094 Aside from comments (lines starting with @samp{#}, which are ignored), each
1095 nonblank line in the termcap data base is a terminal description.
1096 A terminal description is nominally a single line, but it can be split
1097 into multiple lines by inserting the two characters @samp{\ newline}.
1098 This sequence is ignored wherever it appears in a description.
1100 The preferred way to split the description is between capabilities: insert
1101 the four characters @samp{: \ newline tab} immediately before any colon.
1102 This allows each sub-line to start with some indentation. This works
1103 because, after the @samp{\ newline} are ignored, the result is @samp{: tab
1104 :}; the first colon ends the preceding capability and the second colon
1105 starts the next capability. If you split with @samp{\ newline} alone, you
1106 may not add any indentation after them.
1108 Here is a real example of a terminal description:
1112 :cr=^M:do=^J:nl=^J:bl=^G:\
1113 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\
1114 :cm=\EY%+ %+ :co#80:li#24:\
1115 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
1116 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
1119 Each terminal description begins with several names for the terminal type.
1120 The names are separated by @samp{|} characters, and a colon ends the last
1121 name. The first name should be two characters long; it exists only for the
1122 sake of very old Unix systems and is never used in modern systems. The
1123 last name should be a fully verbose name such as ``DEC vt52'' or ``Ann
1124 Arbor Ambassador with 48 lines''. The other names should include whatever
1125 the user ought to be able to specify to get this terminal type, such as
1126 @samp{vt52} or @samp{aaa-48}. @xref{Naming}, for information on how to
1127 choose terminal type names.
1129 After the terminal type names come the terminal capabilities, separated by
1130 colons and with a colon after the last one. Each capability has a
1131 two-letter name, such as @samp{cm} for ``cursor motion string'' or @samp{li}
1132 for ``number of display lines''.
1134 @node Capability Format, Naming, Format, Data Base
1135 @section Writing the Capabilities
1137 There are three kinds of capabilities: flags, numbers, and strings. Each
1138 kind has its own way of being written in the description. Each defined
1139 capability has by convention a particular kind of value; for example,
1140 @samp{li} always has a numeric value and @samp{cm} always a string value.
1142 A flag capability is thought of as having a boolean value: the value is
1143 true if the capability is present, false if not. When the capability is
1144 present, just write its name between two colons.
1146 A numeric capability has a value which is a nonnegative number. Write the
1147 capability name, a @samp{#}, and the number, between two colons. For
1148 example, @samp{@dots{}:li#48:@dots{}} is how you specify the @samp{li}
1149 capability for 48 lines.@refill
1151 A string-valued capability has a value which is a sequence of characters.
1152 Usually these are the characters used to perform some display operation.
1153 Write the capability name, a @samp{=}, and the characters of the value,
1154 between two colons. For example, @samp{@dots{}:cm=\E[%i%d;%dH:@dots{}} is
1155 how the cursor motion command for a standard ANSI terminal would be
1158 Special characters in the string value can be expressed using
1159 @samp{\}-escape sequences as in C; in addition, @samp{\E} stands for
1160 @key{ESC}. @samp{^} is also a kind of escape character; @samp{^} followed
1161 by @var{char} stands for the control-equivalent of @var{char}. Thus,
1162 @samp{^a} stands for the character control-a, just like @samp{\001}.
1163 @samp{\} and @samp{^} themselves can be represented as @samp{\\} and
1166 To include a colon in the string, you must write @samp{\072}. You might
1167 ask, ``Why can't @samp{\:} be used to represent a colon?'' The reason is
1168 that the interrogation functions do not count slashes while looking for a
1169 capability. Even if @samp{:ce=ab\:cd:} were interpreted as giving the
1170 @samp{ce} capability the value @samp{ab:cd}, it would also appear to define
1171 @samp{cd} as a flag.
1173 The string value will often contain digits at the front to specify padding
1174 (@pxref{Padding}) and/or @samp{%}-sequences within to specify how to encode
1175 parameters (@pxref{Parameters}). Although these things are not to be
1176 output literally to the terminal, they are considered part of the value of
1177 the capability. They are special only when the string value is processed
1178 by @code{tputs}, @code{tparam} or @code{tgoto}. By contrast, @samp{\} and
1179 @samp{^} are considered part of the syntax for specifying the characters
1182 Let's look at the VT52 example again:
1186 :cr=^M:do=^J:nl=^J:bl=^G:\
1187 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\
1188 :cm=\EY%+ %+ :co#80:li#24:\
1189 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
1190 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
1193 Here we see the numeric-valued capabilities @samp{co} and @samp{li}, the
1194 flags @samp{bs} and @samp{pt}, and many string-valued capabilities. Most
1195 of the strings start with @key{ESC} represented as @samp{\E}. The rest
1196 contain control characters represented using @samp{^}. The meanings of the
1197 individual capabilities are defined elsewhere (@pxref{Capabilities}).
1199 @node Naming, Inheriting, Capability Format, Data Base
1200 @section Terminal Type Name Conventions
1201 @cindex names of terminal types
1203 There are conventions for choosing names of terminal types. For one thing,
1204 all letters should be in lower case. The terminal type for a terminal in
1205 its most usual or most fundamental mode of operation should not have a
1208 If the same terminal has other modes of operation which require
1209 different terminal descriptions, these variant descriptions are given
1210 names made by adding suffixes with hyphens. Such alternate descriptions
1211 are used for two reasons:
1215 When the terminal has a switch that changes its behavior. Since the
1216 computer cannot tell how the switch is set, the user must tell the
1217 computer by choosing the appropriate terminal type name.
1220 For example, the VT-100 has a setup flag that controls whether the
1221 cursor wraps at the right margin. If this flag is set to ``wrap'',
1222 you must use the terminal type @samp{vt100-am}. Otherwise you must
1223 use @samp{vt100-nam}. Plain @samp{vt100} is defined as a synonym for
1224 either @samp{vt100-am} or @samp{vt100-nam} depending on the
1225 preferences of the local site.@refill
1227 The standard suffix @samp{-am} stands for ``automatic margins''.
1230 To give the user a choice in how to use the terminal. This is done
1231 when the terminal has a switch that the computer normally controls.
1234 For example, the Ann Arbor Ambassador can be configured with many
1235 screen sizes ranging from 20 to 60 lines. Fewer lines make bigger
1236 characters but more lines let you see more of what you are editing.
1237 As a result, users have different preferences. Therefore, termcap
1238 provides terminal types for many screen sizes. If you choose type
1239 @samp{aaa-30}, the terminal will be configured to use 30 lines; if you
1240 choose @samp{aaa-48}, 48 lines will be used, and so on.
1243 Here is a list of standard suffixes and their conventional meanings:
1247 Short for ``wide''. This is a mode that gives the terminal more
1248 columns than usual. This is normally a user option.
1251 ``Automatic margins''. This is an alternate description for use when
1252 the terminal's margin-wrap switch is on; it contains the @samp{am}
1253 flag. The implication is that normally the switch is off and the
1254 usual description for the terminal says that the switch is off.
1257 ``No automatic margins''. The opposite of @samp{-am}, this names an
1258 alternative description which lacks the @samp{am} flag. This implies
1259 that the terminal is normally operated with the margin-wrap switch
1260 turned on, and the normal description of the terminal says so.
1263 ``No arrows''. This terminal description initializes the terminal to
1264 keep its arrow keys in local mode. This is a user option.
1267 ``Reverse video''. This terminal description causes text output for
1268 normal video to appear as reverse, and text output for reverse video
1269 to come out as normal. Often this description differs from the usual
1270 one by interchanging the two strings which turn reverse video on and
1273 This is a user option; you can choose either the ``reverse video''
1274 variant terminal type or the normal terminal type, and termcap will
1278 ``Status''. Says to enable use of a status line which ordinary output
1279 does not touch (@pxref{Status Line}).
1281 Some terminals have a special line that is used only as a status line.
1282 For these terminals, there is no need for an @samp{-s} variant; the
1283 status line commands should be defined by default. On other
1284 terminals, enabling a status line means removing one screen line from
1285 ordinary use and reducing the effective screen height. For these
1286 terminals, the user can choose the @samp{-s} variant type to request
1287 use of a status line.
1290 Says to operate with @var{nlines} lines on the screen, for terminals
1291 such as the Ambassador which provide this as an option. Normally this
1292 is a user option; by choosing the terminal type, you control how many
1293 lines termcap will use.
1295 @item -@var{npages}p
1296 Says that the terminal has @var{npages} pages worth of screen memory,
1297 for terminals where this is a hardware option.
1300 Says that description is not for direct use, but only for reference in
1301 @samp{tc} capabilities. Such a description is a kind of subroutine,
1302 because it describes the common characteristics of several variant
1303 descriptions that would use other suffixes in place of @samp{-unk}.
1306 @node Inheriting, Changing, Naming, Data Base
1307 @section Inheriting from Related Descriptions
1310 When two terminal descriptions are similar, their identical parts do not
1311 need to be given twice. Instead, one of the two can be defined in terms of
1312 the other, using the @samp{tc} capability. We say that one description
1313 @dfn{refers to} the other, or @dfn{inherits from} the other.
1315 The @samp{tc} capability must be the last one in the terminal description,
1316 and its value is a string which is the name of another terminal type which
1317 is referred to. For example,
1320 N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
1321 :ti=\E[2J\E[30;0;0;30p:\
1322 :te=\E[60;0;0;30p\E[30;1H\E[J:\
1327 defines the terminal type @samp{aaa-30} (also known as plain @samp{aaa}) in
1328 terms of @samp{aaa-unk}, which defines everything about the Ambassador that
1329 is independent of screen height. The types @samp{aaa-36}, @samp{aaa-48}
1330 and so on for other screen heights are likewise defined to inherit from
1333 The capabilities overridden by @samp{aaa-30} include @samp{li}, which says
1334 how many lines there are, and @samp{ti} and @samp{te}, which configure the
1335 terminal to use that many lines.
1337 The effective terminal description for type @samp{aaa} consists of the text
1338 shown above followed by the text of the description of @samp{aaa-unk}. The
1339 @samp{tc} capability is handled automatically by @code{tgetent}, which
1340 finds the description thus referenced and combines the two descriptions
1341 (@pxref{Find}). Therefore, only the implementor of the terminal
1342 descriptions needs to think about using @samp{tc}. Users and application
1343 programmers do not need to be concerned with it.
1345 Since the reference terminal description is used last, capabilities
1346 specified in the referring description override any specifications of the
1347 same capabilities in the reference description.
1349 The referring description can cancel out a capability without specifying
1350 any new value for it by means of a special trick. Write the capability in
1351 the referring description, with the character @samp{@@} after the capability
1355 NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
1359 @node Changing, , Inheriting, Data Base
1360 @section When Changes in the Data Base Take Effect
1362 Each application program must read the terminal description from the
1363 data base, so a change in the data base is effective for all jobs started
1364 after the change is made.
1366 The change will usually have no effect on a job that have been in existence
1367 since before the change. The program probably read the terminal description
1368 once, when it was started, and is continuing to use what it read then.
1369 If the program does not have a feature for reexamining the data base, then
1370 you will need to run it again (probably killing the old job).
1372 If the description in use is coming from the @code{TERMCAP} environment
1373 variable, then the data base file is effectively overridden, and changes in
1374 it will have no effect until you change the @code{TERMCAP} variable as
1375 well. For example, some users' @file{.login} files automatically copy the
1376 terminal description into @code{TERMCAP} to speed startup of applications.
1377 If you have done this, you will need to change the @code{TERMCAP} variable
1378 to make the changed data base take effect.
1380 @node Capabilities, Summary, Data Base, Top
1381 @chapter Definitions of the Terminal Capabilities
1383 This section is divided into many subsections, each for one aspect of
1384 use of display terminals. For writing a display program, you usually need
1385 only check the subsections for the operations you want to use. For writing
1386 a terminal description, you must read each subsection and fill in the
1387 capabilities described there.
1389 String capabilities that are display commands may require numeric
1390 parameters (@pxref{Parameters}). Most such capabilities do not use
1391 parameters. When a capability requires parameters, this is explicitly
1392 stated at the beginning of its definition. In simple cases, the first or
1393 second sentence of the definition mentions all the parameters, in the order
1394 they should be given, using a name
1401 for each one. For example, the @samp{rp} capability is a command that
1402 requires two parameters; its definition begins as follows:
1405 String of commands to output a graphic character @var{c}, repeated @var{n}
1409 In complex cases or when there are many parameters, they are described
1412 When a capability is described as obsolete, this means that programs should
1413 not be written to look for it, but terminal descriptions should still be
1414 written to provide it.
1416 When a capability is described as very obsolete, this means that it should
1417 be omitted from terminal descriptions as well.
1420 * Basic:: Basic characteristics.
1421 * Screen Size:: Screen size, and what happens when it changes.
1422 * Cursor Motion:: Various ways to move the cursor.
1423 * Wrapping:: What happens if you write a character in the last column.
1424 * Scrolling:: Pushing text up and down on the screen.
1425 * Windows:: Limiting the part of the window that output affects.
1426 * Clearing:: Erasing one or many lines.
1427 * Insdel Line:: Making new blank lines in mid-screen; deleting lines.
1428 * Insdel Char:: Inserting and deleting characters within a line.
1429 * Standout:: Highlighting some of the text.
1430 * Underlining:: Underlining some of the text.
1431 * Cursor Visibility:: Making the cursor more or less easy to spot.
1432 * Bell:: Attracts user's attention; not localized on the screen.
1433 * Keypad:: Recognizing when function keys or arrows are typed.
1434 * Meta Key:: @key{META} acts like an extra shift key.
1435 * Initialization:: Commands used to initialize or reset the terminal.
1436 * Pad Specs:: Info for the kernel on how much padding is needed.
1437 * Status Line:: A status line displays ``background'' information.
1438 * Half-Line:: Moving by half-lines, for superscripts and subscripts.
1439 * Printer:: Controlling auxiliary printers of display terminals.
1442 @node Basic, Screen Size, , Capabilities
1443 @section Basic Characteristics
1445 This section documents the capabilities that describe the basic and
1446 nature of the terminal, and also those that are relevant to the output
1447 of graphic characters.
1453 Flag whose presence means that the terminal can overstrike. This
1454 means that outputting a graphic character does not erase whatever was
1455 present in the same character position before. The terminals that can
1456 overstrike include printing terminals, storage tubes (all obsolete
1457 nowadays), and many bit-map displays.
1461 Flag whose presence means that outputting a space erases a character
1462 position even if the terminal supports overstriking. If this flag is
1463 not present and overstriking is supported, output of a space has no
1464 effect except to move the cursor.
1466 (On terminals that do not support overstriking, you can always assume
1467 that outputting a space at a position erases whatever character was
1468 previously displayed there.)
1472 @cindex generic terminal type
1473 Flag whose presence means that this terminal type is a generic type
1474 which does not really describe any particular terminal. Generic types
1475 are intended for use as the default type assigned when the user
1476 connects to the system, with the intention that the user should
1477 specify what type he really has. One example of a generic type
1478 is the type @samp{network}.
1480 Since the generic type cannot say how to do anything interesting with
1481 the terminal, termcap-using programs will always find that the
1482 terminal is too weak to be supported if the user has failed to specify
1483 a real terminal type in place of the generic one. The @samp{gn} flag
1484 directs these programs to use a different error message: ``You have
1485 not specified your real terminal type'', rather than ``Your terminal
1486 is not powerful enough to be used''.
1490 Flag whose presence means this is a hardcopy terminal.
1494 @cindex repeat output
1495 String of commands to output a graphic character @var{c}, repeated @var{n}
1496 times. The first parameter value is the ASCII code for the desired
1497 character, and the second parameter is the number of times to repeat the
1498 character. Often this command requires padding proportional to the
1499 number of times the character is repeated. This effect can be had by
1500 using parameter arithmetic with @samp{%}-sequences to compute the
1501 amount of padding, then generating the result as a number at the front
1502 of the string so that @code{tputs} will treat it as padding.
1506 Flag whose presence means that the ASCII character @samp{~} cannot be
1507 output on this terminal because it is used for display commands.
1509 Programs handle this flag by checking all text to be output and
1510 replacing each @samp{~} with some other character(s). If this is not
1511 done, the screen will be thoroughly garbled.
1513 The old Hazeltine terminals that required such treatment are probably
1514 very rare today, so you might as well not bother to support this flag.
1518 @cindex command character
1519 String whose presence means the terminal has a settable command
1520 character. The value of the string is the default command character
1521 (which is usually @key{ESC}).
1523 All the strings of commands in the terminal description should be
1524 written to use the default command character. If you are writing an
1525 application program that changes the command character, use the
1526 @samp{CC} capability to figure out how to translate all the display
1527 commands to work with the new command character.
1529 Most programs have no reason to look at the @samp{CC} capability.
1534 Flag whose presence identifies Superbee terminals which are unable to
1535 transmit the characters @key{ESC} and @kbd{Control-C}. Programs which
1536 support this flag are supposed to check the input for the code sequences
1537 sent by the @key{F1} and @key{F2} keys, and pretend that @key{ESC}
1538 or @kbd{Control-C} (respectively) had been read. But this flag is
1539 obsolete, and not worth supporting.
1542 @node Screen Size, Cursor Motion, Basic, Capabilities
1543 @section Screen Size
1546 A terminal description has two capabilities, @samp{co} and @samp{li},
1547 that describe the screen size in columns and lines. But there is more
1548 to the question of screen size than this.
1550 On some operating systems the ``screen'' is really a window and the
1551 effective width can vary. On some of these systems, @code{tgetnum}
1552 uses the actual width of the window to decide what value to return for
1553 the @samp{co} capability, overriding what is actually written in the
1554 terminal description. On other systems, it is up to the application
1555 program to check the actual window width using a system call. For
1556 example, on BSD 4.3 systems, the system call @code{ioctl} with code
1557 @code{TIOCGWINSZ} will tell you the current screen size.
1559 On all window systems, termcap is powerless to advise the application
1560 program if the user resizes the window. Application programs must
1561 deal with this possibility in a system-dependent fashion. On some
1562 systems the C shell handles part of the problem by detecting changes
1563 in window size and setting the @code{TERMCAP} environment variable
1564 appropriately. This takes care of application programs that are
1565 started subsequently. It does not help application programs already
1568 On some systems, including BSD 4.3, all programs using a terminal get
1569 a signal named @code{SIGWINCH} whenever the screen size changes.
1570 Programs that use termcap should handle this signal by using
1571 @code{ioctl TIOCGWINSZ} to learn the new screen size.
1577 Numeric value, the width of the screen in character positions. Even
1578 hardcopy terminals normally have a @samp{co} capability.
1582 Numeric value, the height of the screen in lines.
1585 @node Cursor Motion, Wrapping, Screen Size, Capabilities
1586 @section Cursor Motion
1587 @cindex cursor motion
1589 Termcap assumes that the terminal has a @dfn{cursor}, a spot on the screen
1590 where a visible mark is displayed, and that most display commands take
1591 effect at the position of the cursor. It follows that moving the cursor
1592 to a specified location is very important.
1594 There are many terminal capabilities for different cursor motion
1595 operations. A terminal description should define as many as possible, but
1596 most programs do not need to use most of them. One capability, @samp{cm},
1597 moves the cursor to an arbitrary place on the screen; this by itself is
1598 sufficient for any application as long as there is no need to support
1599 hardcopy terminals or certain old, weak displays that have only relative
1600 motion commands. Use of other cursor motion capabilities is an
1601 optimization, enabling the program to output fewer characters in some
1604 If you plan to use the relative cursor motion commands in an application
1605 program, you must know what the starting cursor position is. To do this,
1606 you must keep track of the cursor position and update the records each
1607 time anything is output to the terminal, including graphic characters.
1608 In addition, it is necessary to know whether the terminal wraps after
1609 writing in the rightmost column. @xref{Wrapping}.
1611 One other motion capability needs special mention: @samp{nw} moves the
1612 cursor to the beginning of the following line, perhaps clearing all the
1613 starting line after the cursor, or perhaps not clearing at all. This
1614 capability is a least common denominator that is probably supported even by
1615 terminals that cannot do most other things such as @samp{cm} or @samp{do}.
1616 Even hardcopy terminals can support @samp{nw}.
1621 String of commands to position the cursor at line @var{l}, column @var{c}.
1622 Both parameters are origin-zero, and are defined relative to the
1623 screen, not relative to display memory.
1625 All display terminals except a few very obsolete ones support @samp{cm},
1626 so it is acceptable for an application program to refuse to operate on
1627 terminals lacking @samp{cm}.
1631 @cindex home position
1632 String of commands to move the cursor to the upper left corner of the
1633 screen (this position is called the @dfn{home position}). In
1634 terminals where the upper left corner of the screen is not the same as
1635 the beginning of display memory, this command must go to the upper
1636 left corner of the screen, not the beginning of display memory.
1638 Every display terminal supports this capability, and many application
1639 programs refuse to operate if the @samp{ho} capability is missing.
1643 String of commands to move the cursor to the lower left corner of the
1644 screen. On some terminals, moving up from home position does this,
1645 but programs should never assume that will work. Just output the
1646 @samp{ll} string (if it is provided); if moving to home position and
1647 then moving up is the best way to get there, the @samp{ll} command
1652 String of commands to move the cursor to the beginning of the line it
1653 is on. If this capability is not specified, many programs assume
1654 they can use the ASCII carriage return character for this.
1658 String of commands to move the cursor left one column. Unless the
1659 @samp{bw} flag capability is specified, the effect is undefined if the
1660 cursor is at the left margin; do not use this command there. If
1661 @samp{bw} is present, this command may be used at the left margin, and
1662 it wraps the cursor to the last column of the preceding line.
1666 String of commands to move the cursor right one column. The effect is
1667 undefined if the cursor is at the right margin; do not use this
1668 command there, not even if @samp{am} is present.
1672 String of commands to move the cursor vertically up one line. The
1673 effect of sending this string when on the top line is undefined;
1674 programs should never use it that way.
1678 String of commands to move the cursor vertically down one line. The
1679 effect of sending this string when on the bottom line is undefined;
1680 programs should never use it that way.
1682 Some programs do use @samp{do} to scroll up one line if used at the
1683 bottom line, if @samp{sf} is not defined but @samp{sr} is. This is
1684 only to compensate for certain old, incorrect terminal descriptions.
1685 (In principle this might actually lead to incorrect behavior on other
1686 terminals, but that seems to happen rarely if ever.) But the proper
1687 solution is that the terminal description should define @samp{sf} as
1688 well as @samp{do} if the command is suitable for scrolling.
1690 The original idea was that this string would not contain a newline
1691 character and therefore could be used without disabling the kernel's
1692 usual habit of converting of newline into a carriage-return newline
1693 sequence. But many terminal descriptions do use newline in the
1694 @samp{do} string, so this is not possible; a program which sends the
1695 @samp{do} string must disable output conversion in the kernel
1696 (@pxref{Initialize}).
1700 Flag whose presence says that @samp{le} may be used in column zero
1701 to move to the last column of the preceding line. If this flag
1702 is not present, @samp{le} should not be used in column zero.
1706 String of commands to move the cursor to start of next line, possibly
1707 clearing rest of line (following the cursor) before moving.
1709 @item @samp{DO}, @samp{UP}, @samp{LE}, @samp{RI}
1714 Strings of commands to move the cursor @var{n} lines down vertically,
1715 up vertically, or @var{n} columns left or right. Do not attempt to
1716 move past any edge of the screen with these commands; the effect of
1717 trying that is undefined. Only a few terminal descriptions provide
1718 these commands, and most programs do not use them.
1722 String of commands to position the cursor at line @var{l}, column
1723 @var{c}, relative to display memory. Both parameters are origin-zero.
1724 This capability is present only in terminals where there is a
1725 difference between screen-relative and memory-relative addressing, and
1726 not even in all such terminals.
1730 String of commands to position the cursor at column @var{c} in the
1731 same line it is on. This is a special case of @samp{cm} in which the
1732 vertical position is not changed. The @samp{ch} capability is
1733 provided only when it is faster to output than @samp{cm} would be in
1734 this special case. Programs should not assume most display terminals
1739 String of commands to position the cursor at line @var{l} in the same
1740 column. This is a special case of @samp{cm} in which the horizontal
1741 position is not changed. The @samp{cv} capability is provided only
1742 when it is faster to output than @samp{cm} would be in this special
1743 case. Programs should not assume most display terminals have
1748 String of commands to make the terminal save the current cursor
1749 position. Only the last saved position can be used. If this
1750 capability is present, @samp{rc} should be provided also. Most
1751 terminals have neither.
1755 String of commands to make the terminal restore the last saved cursor
1756 position. If this capability is present, @samp{sc} should be provided
1757 also. Most terminals have neither.
1761 String of commands to advance to the next page, for a hardcopy
1766 String of commands to move the cursor right to the next hardware tab
1767 stop column. Missing if the terminal does not have any kind of
1768 hardware tabs. Do not send this command if the kernel's terminal
1769 modes say that the kernel is expanding tabs into spaces.
1773 String of commands to move the cursor left to the previous hardware
1774 tab stop column. Missing if the terminal has no such ability; many
1775 terminals do not. Do not send this command if the kernel's terminal
1776 modes say that the kernel is expanding tabs into spaces.
1779 The following obsolete capabilities should be included in terminal
1780 descriptions when appropriate, but should not be looked at by new programs.
1785 Flag whose presence means the terminal does not support the ASCII
1786 carriage return character as @samp{cr}. This flag is needed because
1787 old programs assume, when the @samp{cr} capability is missing, that
1788 ASCII carriage return can be used for the purpose. We use @samp{nc}
1789 to tell the old programs that carriage return may not be used.
1791 New programs should not assume any default for @samp{cr}, so they need
1792 not look at @samp{nc}. However, descriptions should contain @samp{nc}
1793 whenever they do not contain @samp{cr}.
1797 Flag whose presence means that the ASCII tab character may not be used
1798 for cursor motion. This flag exists because old programs assume, when
1799 the @samp{ta} capability is missing, that ASCII tab can be used for
1800 the purpose. We use @samp{xt} to tell the old programs not to use tab.
1802 New programs should not assume any default for @samp{ta}, so they need
1803 not look at @samp{xt} in connection with cursor motion. Note that
1804 @samp{xt} also has implications for standout mode (@pxref{Standout}).
1805 It is obsolete in regard to cursor motion but not in regard to
1808 In fact, @samp{xt} means that the terminal is a Teleray 1061.
1812 Very obsolete alternative name for the @samp{le} capability.
1816 Flag whose presence means that the ASCII character backspace may be
1817 used to move the cursor left. Obsolete; look at @samp{le} instead.
1821 Obsolete capability which is a string that can either be used to move
1822 the cursor down or to scroll. The same string must scroll when used
1823 on the bottom line and move the cursor when used on any other line.
1824 New programs should use @samp{do} or @samp{sf}, and ignore @samp{nl}.
1826 If there is no @samp{nl} capability, some old programs assume they can
1827 use the newline character for this purpose. These programs follow a
1828 bad practice, but because they exist, it is still desirable to define
1829 the @samp{nl} capability in a terminal description if the best way to
1830 move down is @emph{not} a newline.
1833 @node Wrapping, Scrolling, Cursor Motion, Capabilities
1837 @dfn{Wrapping} means moving the cursor from the right margin to the left
1838 margin of the following line. Some terminals wrap automatically when a
1839 graphic character is output in the last column, while others do not. Most
1840 application programs that use termcap need to know whether the terminal
1841 wraps. There are two special flag capabilities to describe what the
1842 terminal does when a graphic character is output in the last column.
1847 Flag whose presence means that writing a character in the last column
1848 causes the cursor to wrap to the beginning of the next line.
1850 If @samp{am} is not present, writing in the last column leaves the
1851 cursor at the place where the character was written.
1853 Writing in the last column of the last line should be avoided on
1854 terminals with @samp{am}, as it may or may not cause scrolling to
1855 occur (@pxref{Scrolling}). Scrolling is surely not what you would
1858 If your program needs to check the @samp{am} flag, then it also needs
1859 to check the @samp{xn} flag which indicates that wrapping happens in a
1860 strange way. Many common terminals have the @samp{xn} flag.
1864 Flag whose presence means that the cursor wraps in a strange way. At
1865 least two distinct kinds of strange behavior are known; the termcap
1866 data base does not contain anything to distinguish the two.
1868 On Concept-100 terminals, output in the last column wraps the cursor
1869 almost like an ordinary @samp{am} terminal. But if the next thing
1870 output is a newline, it is ignored.
1872 DEC VT-100 terminals (when the wrap switch is on) do a different
1873 strange thing: the cursor wraps only if the next thing output is
1874 another graphic character. In fact, the wrap occurs when the
1875 following graphic character is received by the terminal, before the
1876 character is placed on the screen.
1878 On both of these terminals, after writing in the last column a
1879 following graphic character will be displayed in the first column of
1880 the following line. But the effect of relative cursor motion
1881 characters such as newline or backspace at such a time depends on the
1882 terminal. The effect of erase or scrolling commands also depends on
1883 the terminal. You can't assume anything about what they will do on a
1884 terminal that has @samp{xn}. So, to be safe, you should never do
1885 these things at such a time on such a terminal.
1887 To be sure of reliable results on a terminal which has the @samp{xn}
1888 flag, output a @samp{cm} absolute positioning command after writing in
1889 the last column. Another safe thing to do is to output carriage-return
1890 newline, which will leave the cursor at the beginning of the following
1895 Flag whose presence means that it is safe to write in the last column of
1896 the last line without worrying about undesired scrolling. @samp{LP}
1897 indicates the DEC flavor of @samp{xn} strangeness.
1900 @node Scrolling, Windows, Wrapping, Capabilities
1904 @dfn{Scrolling} means moving the contents of the screen up or down one or
1905 more lines. Moving the contents up is @dfn{forward scrolling}; moving them
1906 down is @dfn{reverse scrolling}.
1908 Scrolling happens after each line of output during ordinary output on most
1909 display terminals. But in an application program that uses termcap for
1910 random-access output, scrolling happens only when explicitly requested with
1911 the commands in this section.
1913 Some terminals have a @dfn{scroll region} feature. This lets you limit
1914 the effect of scrolling to a specified range of lines. Lines outside the
1915 range are unaffected when scrolling happens. The scroll region feature
1916 is available if either @samp{cs} or @samp{cS} is present.
1921 String of commands to scroll the screen one line up, assuming it is
1922 output with the cursor at the beginning of the bottom line.
1926 String of commands to scroll the screen one line down, assuming it is
1927 output with the cursor at the beginning of the top line.
1930 A few programs will try to use @samp{do} to do the work of @samp{sf}.
1931 This is not really correct---it is an attempt to compensate for the
1932 absence of a @samp{sf} command in some old terminal descriptions.
1934 Since these terminal descriptions do define @samp{sr}, perhaps at one
1935 time the definition of @samp{do} was different and it could be used
1936 for scrolling as well. But it isn't desirable to combine these two
1937 functions in one capability, since scrolling often requires more
1938 padding than simply moving the cursor down. Defining @samp{sf} and
1939 @samp{do} separately allows you to specify the padding properly.
1940 Also, all sources agree that @samp{do} should not be relied on to do
1943 So the best approach is to add @samp{sf} capabilities to the
1944 descriptions of these terminals, copying the definition of @samp{do}
1945 if that does scroll.
1949 String of commands to scroll the screen @var{n} lines up, assuming it
1950 is output with the cursor at the beginning of the bottom line.
1954 String of commands to scroll the screen @var{n} lines down, assuming it
1955 is output with the cursor at the beginning of the top line.
1959 String of commands to set the scroll region. This command takes two
1960 parameters, @var{start} and @var{end}, which are the line numbers
1961 (origin-zero) of the first line to include in the scroll region and of
1962 the last line to include in it. When a scroll region is set,
1963 scrolling is limited to the specified range of lines; lines outside
1964 the range are not affected by scroll commands.
1966 Do not try to move the cursor outside the scroll region. The region
1967 remains set until explicitly removed. To remove the scroll region,
1968 use another @samp{cs} command specifying the full height of the
1971 The cursor position is undefined after the @samp{cs} command is set,
1972 so position the cursor with @samp{cm} immediately afterward.
1976 String of commands to set the scroll region using parameters in
1977 different form. The effect is the same as if @samp{cs} were used.
1978 Four parameters are required:
1982 Total number of lines on the screen.
1984 Number of lines above desired scroll region.
1986 Number of lines below (outside of) desired scroll region.
1988 Total number of lines on the screen, the same as the first parameter.
1991 This capability is a GNU extension that was invented to allow the Ann
1992 Arbor Ambassador's scroll-region command to be described; it could
1993 also be done by putting non-Unix @samp{%}-sequences into a @samp{cs}
1994 string, but that would have confused Unix programs that used the
1995 @samp{cs} capability with the Unix termcap. Currently only GNU Emacs
1996 uses the @samp{cS} capability.
2000 Flag which means that the terminal does not normally scroll for
2001 ordinary sequential output. For modern terminals, this means that
2002 outputting a newline in ordinary sequential output with the cursor on
2003 the bottom line wraps to the top line. For some obsolete terminals,
2004 other things may happen.
2006 The terminal may be able to scroll even if it does not normally do so.
2007 If the @samp{sf} capability is provided, it can be used for scrolling
2008 regardless of @samp{ns}.
2012 Flag whose presence means that lines scrolled up off the top of the
2013 screen may come back if scrolling down is done subsequently.
2015 The @samp{da} and @samp{db} flags do not, strictly speaking, affect
2016 how to scroll. But programs that scroll usually need to clear the
2017 lines scrolled onto the screen, if these flags are present.
2021 Flag whose presence means that lines scrolled down off the bottom of
2022 the screen may come back if scrolling up is done subsequently.
2026 Numeric value, the number of lines of display memory that the terminal
2027 has. A value of zero means that the terminal has more display memory
2028 than can fit on the screen, but no fixed number of lines. (The number
2029 of lines may depend on the amount of text in each line.)
2032 Any terminal description that defines @samp{SF} should also define @samp{sf};
2033 likewise for @samp{SR} and @samp{sr}. However, many terminals can only
2034 scroll by one line at a time, so it is common to find @samp{sf} and not
2035 @samp{SF}, or @samp{sr} without @samp{SR}.@refill
2037 Therefore, all programs that use the scrolling facilities should be
2038 prepared to work with @samp{sf} in the case that @samp{SF} is absent, and
2039 likewise with @samp{sr}. On the other hand, an application program that
2040 uses only @samp{sf} and not @samp{SF} is acceptable, though slow on some
2043 When outputting a scroll command with @code{tputs}, the @var{nlines}
2044 argument should be the total number of lines in the portion of the screen
2045 being scrolled. Very often these commands require padding proportional to
2046 this number of lines. @xref{Padding}.
2048 @node Windows, Clearing, Scrolling, Capabilities
2052 A @dfn{window}, in termcap, is a rectangular portion of the screen to which
2053 all display operations are restricted. Wrapping, clearing, scrolling,
2054 insertion and deletion all operate as if the specified window were all the
2060 String of commands to set the terminal output screen window.
2061 This string requires four parameters, all origin-zero:
2064 The first line to include in the window.
2066 The last line to include in the window.
2068 The first column to include in the window.
2070 The last column to include in the window.
2074 Most terminals do not support windows.
2076 @node Clearing, Insdel Line, Windows, Capabilities
2077 @section Clearing Parts of the Screen
2079 @cindex clearing the screen
2081 There are several terminal capabilities for clearing parts of the screen
2082 to blank. All display terminals support the @samp{cl} string, and most
2083 display terminals support all of these capabilities.
2088 String of commands to clear the entire screen and position the cursor
2089 at the upper left corner.
2093 String of commands to clear the line the cursor is on, and all the
2094 lines below it, down to the bottom of the screen. This command string
2095 should be used only with the cursor in column zero; their effect is
2096 undefined if the cursor is elsewhere.
2100 String of commands to clear from the cursor to the end of the current
2105 String of commands to clear @var{n} characters, starting with the
2106 character that the cursor is on. This command string is expected to
2107 leave the cursor position unchanged. The parameter @var{n} should never
2108 be large enough to reach past the right margin; the effect of such a
2109 large parameter would be undefined.
2112 Clear to end of line (@samp{ce}) is extremely important in programs that
2113 maintain an updating display. Nearly all display terminals support this
2114 operation, so it is acceptable for a an application program to refuse to
2115 work if @samp{ce} is not present. However, if you do not want this
2116 limitation, you can accomplish clearing to end of line by outputting spaces
2117 until you reach the right margin. In order to do this, you must know the
2118 current horizontal position. Also, this technique assumes that writing a
2119 space will erase. But this happens to be true on all the display terminals
2120 that fail to support @samp{ce}.
2122 @node Insdel Line, Insdel Char, Clearing, Capabilities
2123 @section Insert/Delete Line
2127 @dfn{Inserting a line} means creating a blank line in the middle
2128 of the screen, and pushing the existing lines of text apart. In fact,
2129 the lines above the insertion point do not change, while the lines below
2130 move down, and one is normally lost at the bottom of the screen.
2132 @dfn{Deleting a line} means causing the line to disappear from the screen,
2133 closing up the gap by moving the lines below it upward. A new line
2134 appears at the bottom of the screen. Usually this line is blank, but
2135 on terminals with the @samp{db} flag it may be a line previously moved
2136 off the screen bottom by scrolling or line insertion.
2138 Insertion and deletion of lines is useful in programs that maintain an
2139 updating display some parts of which may get longer or shorter. They are
2140 also useful in editors for scrolling parts of the screen, and for
2141 redisplaying after lines of text are killed or inserted.
2143 Many terminals provide commands to insert or delete a single line at the
2144 cursor position. Some provide the ability to insert or delete several
2145 lines with one command, using the number of lines to insert or delete as a
2146 parameter. Always move the cursor to column zero before using any of
2152 String of commands to insert a blank line before the line the cursor
2153 is on. The existing line, and all lines below it, are moved down.
2154 The last line in the screen (or in the scroll region, if one is set)
2155 disappears and in most circumstances is discarded. It may not be
2156 discarded if the @samp{db} is present (@pxref{Scrolling}).
2158 The cursor must be at the left margin before this command is used.
2159 This command does not move the cursor.
2163 String of commands to delete the line the cursor is on. The following
2164 lines move up, and a blank line appears at the bottom of the screen
2165 (or bottom of the scroll region). If the terminal has the @samp{db}
2166 flag, a nonblank line previously pushed off the screen bottom may
2167 reappear at the bottom.
2169 The cursor must be at the left margin before this command is used.
2170 This command does not move the cursor.
2174 String of commands to insert @var{n} blank lines before the line that
2175 the cursor is on. It is like @samp{al} repeated @var{n} times, except
2176 that it is as fast as one @samp{al}.
2180 String of commands to delete @var{n} lines starting with the line that
2181 the cursor is on. It is like @samp{dl} repeated @var{n} times, except
2182 that it is as fast as one @samp{dl}.
2185 Any terminal description that defines @samp{AL} should also define
2186 @samp{al}; likewise for @samp{DL} and @samp{dl}. However, many terminals
2187 can only insert or delete one line at a time, so it is common to find
2188 @samp{al} and not @samp{AL}, or @samp{dl} without @samp{DL}.@refill
2190 Therefore, all programs that use the insert and delete facilities should be
2191 prepared to work with @samp{al} in the case that @samp{AL} is absent, and
2192 likewise with @samp{dl}. On the other hand, it is acceptable to write
2193 an application that uses only @samp{al} and @samp{dl} and does not look
2194 for @samp{AL} or @samp{DL} at all.@refill
2196 If a terminal does not support line insertion and deletion directly,
2197 but does support a scroll region, the effect of insertion and deletion
2198 can be obtained with scrolling. However, it is up to the individual
2199 user program to check for this possibility and use the scrolling
2200 commands to get the desired result. It is fairly important to implement
2201 this alternate strategy, since it is the only way to get the effect of
2202 line insertion and deletion on the popular VT100 terminal.
2204 Insertion and deletion of lines is affected by the scroll region on
2205 terminals that have a settable scroll region. This is useful when it is
2206 desirable to move any few consecutive lines up or down by a few lines.
2209 The line pushed off the bottom of the screen is not lost if the terminal
2210 has the @samp{db} flag capability; instead, it is pushed into display
2211 memory that does not appear on the screen. This is the same thing that
2212 happens when scrolling pushes a line off the bottom of the screen.
2213 Either reverse scrolling or deletion of a line can bring the apparently
2214 lost line back onto the bottom of the screen. If the terminal has the
2215 scroll region feature as well as @samp{db}, the pushed-out line really
2216 is lost if a scroll region is in effect.
2218 When outputting an insert or delete command with @code{tputs}, the
2219 @var{nlines} argument should be the total number of lines from the cursor
2220 to the bottom of the screen (or scroll region). Very often these commands
2221 require padding proportional to this number of lines. @xref{Padding}.
2223 For @samp{AL} and @samp{DL} the @var{nlines} argument should @emph{not}
2224 depend on the number of lines inserted or deleted; only the total number of
2225 lines affected. This is because it is just as fast to insert two or
2226 @var{n} lines with @samp{AL} as to insert one line with @samp{al}.
2228 @node Insdel Char, Standout, Insdel Line, Capabilities
2229 @section Insert/Delete Character
2230 @cindex insert character
2231 @cindex delete character
2233 @dfn{Inserting a character} means creating a blank space in the middle of a
2234 line, and pushing the rest of the line rightward. The character in the
2235 rightmost column is lost.
2237 @dfn{Deleting a character} means causing the character to disappear from
2238 the screen, closing up the gap by moving the rest of the line leftward. A
2239 blank space appears in the rightmost column.
2241 Insertion and deletion of characters is useful in programs that maintain an
2242 updating display some parts of which may get longer or shorter. It is also
2243 useful in editors for redisplaying the results of editing within a line.
2245 Many terminals provide commands to insert or delete a single character at
2246 the cursor position. Some provide the ability to insert or delete several
2247 characters with one command, using the number of characters to insert or
2248 delete as a parameter.
2251 Many terminals provide an insert mode in which outputting a graphic
2252 character has the added effect of inserting a position for that character.
2253 A special command string is used to enter insert mode and another is used
2254 to exit it. The reason for designing a terminal with an insert mode rather
2255 than an insert command is that inserting character positions is usually
2256 followed by writing characters into them. With insert mode, this is as
2257 fast as simply writing the characters, except for the fixed overhead of
2258 entering and leaving insert mode. However, when the line speed is great
2259 enough, padding may be required for the graphic characters output in insert
2262 Some terminals require you to enter insert mode and then output a special
2263 command for each position to be inserted. Or they may require special
2264 commands to be output before or after each graphic character to be
2268 Deletion of characters is usually accomplished by a straightforward command
2269 to delete one or several positions; but on some terminals, it is necessary
2270 to enter a special delete mode before using the delete command, and leave
2271 delete mode afterward. Sometimes delete mode and insert mode are the same
2274 Some terminals make a distinction between character positions in which a
2275 space character has been output and positions which have been cleared. On
2276 these terminals, the effect of insert or delete character runs to the first
2277 cleared position rather than to the end of the line. In fact, the effect
2278 may run to more than one line if there is no cleared position to stop the
2279 shift on the first line. These terminals are identified by the @samp{in}
2282 On terminals with the @samp{in} flag, the technique of skipping over
2283 characters that you know were cleared, and then outputting text later on in
2284 the same line, causes later insert and delete character operations on that
2285 line to do nonstandard things. A program that has any chance of doing this
2286 must check for the @samp{in} flag and must be careful to write explicit
2287 space characters into the intermediate columns when @samp{in} is present.
2289 A plethora of terminal capabilities are needed to describe all of this
2290 complexity. Here is a list of them all. Following the list, we present
2291 an algorithm for programs to use to take proper account of all of these
2297 String of commands to enter insert mode.
2299 If the terminal has no special insert mode, but it can insert
2300 characters with a special command, @samp{im} should be defined with a
2301 null value, because the @samp{vi} editor assumes that insertion of a
2302 character is impossible if @samp{im} is not provided.
2304 New programs should not act like @samp{vi}. They should pay attention
2305 to @samp{im} only if it is defined.
2309 String of commands to leave insert mode. This capability must be
2310 present if @samp{im} is.
2312 On a few old terminals the same string is used to enter and exit
2313 insert mode. This string turns insert mode on if it was off, and off
2314 it it was on. You can tell these terminals because the @samp{ei}
2315 string equals the @samp{im} string. If you want to support these
2316 terminals, you must always remember accurately whether insert mode is
2317 in effect. However, these terminals are obsolete, and it is
2318 reasonable to refuse to support them. On all modern terminals, you
2319 can safely output @samp{ei} at any time to ensure that insert mode is
2324 String of commands to insert one character position at the cursor.
2325 The cursor does not move.
2327 If outputting a graphic character while in insert mode is sufficient
2328 to insert the character, then the @samp{ic} capability should be
2329 defined with a null value.
2331 If your terminal offers a choice of ways to insert---either use insert
2332 mode or use a special command---then define @samp{im} and do not define
2333 @samp{ic}, since this gives the most efficient operation when several
2334 characters are to be inserted. @emph{Do not} define both strings, for
2335 that means that @emph{both} must be used each time insertion is done.
2339 String of commands to output following an inserted graphic character
2340 in insert mode. Often it is used just for a padding spec, when padding
2341 is needed after an inserted character (@pxref{Padding}).
2345 String of commands to insert @var{n} character positions at and after
2346 the cursor. It has the same effect as repeating the @samp{ic} string
2347 and a space, @var{n} times.
2349 If @samp{IC} is provided, application programs may use it without first
2350 entering insert mode.
2354 Flag whose presence means it is safe to move the cursor while in insert
2355 mode and assume the terminal remains in insert mode.
2359 Flag whose presence means that the terminal distinguishes between
2360 character positions in which space characters have been output and
2361 positions which have been cleared.
2364 An application program can assume that the terminal can do character
2365 insertion if @emph{any one of} the capabilities @samp{IC}, @samp{im},
2366 @samp{ic} or @samp{ip} is provided.
2368 To insert @var{n} blank character positions, move the cursor to the place
2369 to insert them and follow this algorithm:
2373 If an @samp{IC} string is provided, output it with parameter @var{n}
2374 and you are finished. Otherwise (or if you don't want to bother to
2375 look for an @samp{IC} string) follow the remaining steps.
2378 Output the @samp{im} string, if there is one, unless the terminal is
2379 already in insert mode.
2382 Repeat steps 4 through 6, @var{n} times.
2385 Output the @samp{ic} string if any.
2391 Output the @samp{ip} string if any.
2394 Output the @samp{ei} string, eventually, to exit insert mode. There
2395 is no need to do this right away. If the @samp{mi} flag is present,
2396 you can move the cursor and the cursor will remain in insert mode;
2397 then you can do more insertion elsewhere without reentering insert
2401 To insert @var{n} graphic characters, position the cursor and follow this
2406 If an @samp{IC} string is provided, output it with parameter @var{n},
2407 then output the graphic characters, and you are finished. Otherwise
2408 (or if you don't want to bother to look for an @samp{IC} string)
2409 follow the remaining steps.
2412 Output the @samp{im} string, if there is one, unless the terminal is
2413 already in insert mode.
2416 For each character to be output, repeat steps 4 through 6.
2419 Output the @samp{ic} string if any.
2422 Output the next graphic character.
2425 Output the @samp{ip} string if any.
2428 Output the @samp{ei} string, eventually, to exit insert mode. There
2429 is no need to do this right away. If the @samp{mi} flag is present,
2430 you can move the cursor and the cursor will remain in insert mode;
2431 then you can do more insertion elsewhere without reentering insert
2435 Note that this is not the same as the original Unix termcap specifications
2436 in one respect: it assumes that the @samp{IC} string can be used without
2437 entering insert mode. This is true as far as I know, and it allows you be
2438 able to avoid entering and leaving insert mode, and also to be able to
2439 avoid the inserted-character padding after the characters that go into the
2442 Deletion of characters is less complicated; deleting one column is done by
2443 outputting the @samp{dc} string. However, there may be a delete mode that
2444 must be entered with @samp{dm} in order to make @samp{dc} work.
2449 String of commands to delete one character position at the cursor. If
2450 @samp{dc} is not present, the terminal cannot delete characters.
2454 String of commands to delete @var{n} characters starting at the cursor.
2455 It has the same effect as repeating the @samp{dc} string @var{n} times.
2456 Any terminal description that has @samp{DC} also has @samp{dc}.
2460 String of commands to enter delete mode. If not present, there is no
2461 delete mode, and @samp{dc} can be used at any time (assuming there is
2466 String of commands to exit delete mode. This must be present if
2470 To delete @var{n} character positions, position the cursor and follow these
2475 If the @samp{DC} string is present, output it with parameter @var{n}
2476 and you are finished. Otherwise, follow the remaining steps.
2479 Output the @samp{dm} string, unless you know the terminal is already
2483 Output the @samp{dc} string @var{n} times.
2486 Output the @samp{ed} string eventually. If the flag capability
2487 @samp{mi} is present, you can move the cursor and do more deletion
2488 without leaving and reentering delete mode.
2491 As with the @samp{IC} string, we have departed from the original termcap
2492 specifications by assuming that @samp{DC} works without entering delete
2493 mode even though @samp{dc} would not.
2495 If the @samp{dm} and @samp{im} capabilities are both present and have the
2496 same value, it means that the terminal has one mode for both insertion and
2497 deletion. It is useful for a program to know this, because then it can do
2498 insertions after deletions, or vice versa, without leaving insert/delete
2499 mode and reentering it.
2501 @node Standout, Underlining, Insdel Char, Capabilities
2502 @section Standout and Appearance Modes
2503 @cindex appearance modes
2505 @cindex magic cookie
2507 @dfn{Appearance modes} are modifications to the ways characters are
2508 displayed. Typical appearance modes include reverse video, dim, bright,
2509 blinking, underlined, invisible, and alternate character set. Each kind of
2510 terminal supports various among these, or perhaps none.
2512 For each type of terminal, one appearance mode or combination of them that
2513 looks good for highlighted text is chosen as the @dfn{standout mode}. The
2514 capabilities @samp{so} and @samp{se} say how to enter and leave standout
2515 mode. Programs that use appearance modes only to highlight some text
2516 generally use the standout mode so that they can work on as many terminals
2517 as possible. Use of specific appearance modes other than ``underlined''
2518 and ``alternate character set'' is rare.
2520 Terminals that implement appearance modes fall into two general classes as
2523 In some terminals, the presence or absence of any appearance mode is
2524 recorded separately for each character position. In these terminals, each
2525 graphic character written is given the appearance modes current at the time
2526 it is written, and keeps those modes until it is erased or overwritten.
2527 There are special commands to turn the appearance modes on or off for
2528 characters to be written in the future.
2530 In other terminals, the change of appearance modes is represented by a
2531 marker that belongs to a certain screen position but affects all following
2532 screen positions until the next marker. These markers are traditionally
2533 called @dfn{magic cookies}.
2535 The same capabilities (@samp{so}, @samp{se}, @samp{mb} and so on) for
2536 turning appearance modes on and off are used for both magic-cookie
2537 terminals and per-character terminals. On magic cookie terminals, these
2538 give the commands to write the magic cookies. On per-character terminals,
2539 they change the current modes that affect future output and erasure. Some
2540 simple applications can use these commands without knowing whether or not
2541 they work by means of cookies.
2543 However, a program that maintains and updates a display needs to know
2544 whether the terminal uses magic cookies, and exactly what their effect is.
2545 This information comes from the @samp{sg} capability.
2547 The @samp{sg} capability is a numeric capability whose presence indicates
2548 that the terminal uses magic cookies for appearance modes. Its value is
2549 the number of character positions that a magic cookie occupies. Usually
2550 the cookie occupies one or more character positions on the screen, and these
2551 character positions are displayed as blank, but in some terminals the
2552 cookie has zero width.
2554 The @samp{sg} capability describes both the magic cookie to turn standout
2555 on and the cookie to turn it off. This makes the assumption that both
2556 kinds of cookie have the same width on the screen. If that is not true,
2557 the narrower cookie must be ``widened'' with spaces until it has the same
2560 On some magic cookie terminals, each line always starts with normal
2561 display; in other words, the scope of a magic cookie never extends over
2562 more than one line. But on other terminals, one magic cookie affects all
2563 the lines below it unless explicitly canceled. Termcap does not define any
2564 way to distinguish these two ways magic cookies can work. To be safe, it
2565 is best to put a cookie at the beginning of each line.
2567 On some per-character terminals, standout mode or other appearance modes
2568 may be canceled by moving the cursor. On others, moving the cursor has no
2569 effect on the state of the appearance modes. The latter class of terminals
2570 are given the flag capability @samp{ms} (``can move in standout''). All
2571 programs that might have occasion to move the cursor while appearance modes
2572 are turned on must check for this flag; if it is not present, they should
2573 reset appearance modes to normal before doing cursor motion.
2575 A program that has turned on only standout mode should use @samp{se} to
2576 reset the standout mode to normal. A program that has turned on only
2577 alternate character set mode should use @samp{ae} to return it to normal.
2578 If it is possible that any other appearance modes are turned on, use the
2579 @samp{me} capability to return them to normal.
2581 Note that the commands to turn on one appearance mode, including @samp{so}
2582 and @samp{mb} @dots{} @samp{mr}, if used while some other appearance modes
2583 are turned on, may combine the two modes on some terminals but may turn off
2584 the mode previously enabled on other terminals. This is because some
2585 terminals do not have a command to set or clear one appearance mode without
2586 changing the others. Programs should not attempt to use appearance modes
2587 in combination except with @samp{sa}, and when switching from one single
2588 mode to another should always turn off the previously enabled mode and then
2589 turn on the new desired mode.
2591 On some old terminals, the @samp{so} and @samp{se} commands may be the same
2592 command, which has the effect of turning standout on if it is off, or off
2593 it is on. It is therefore risky for a program to output extra @samp{se}
2594 commands for good measure. Fortunately, all these terminals are obsolete.
2596 Programs that update displays in which standout-text may be replaced with
2597 non-standout text must check for the @samp{xs} flag. In a per-character
2598 terminal, this flag says that the only way to remove standout once written is
2599 to clear that portion of the line with the @samp{ce} string or something
2600 even more powerful (@pxref{Clearing}); just writing new characters at those
2601 screen positions will not change the modes in effect there. In a magic
2602 cookie terminal, @samp{xs} says that the only way to remove a cookie is to
2603 clear a portion of the line that includes the cookie; writing a different
2604 cookie at the same position does not work.
2606 Such programs must also check for the @samp{xt} flag, which means that the
2607 terminal is a Teleray 1061. On this terminal it is impossible to position
2608 the cursor at the front of a magic cookie, so the only two ways to remove a
2609 cookie are (1) to delete the line it is on or (2) to position the cursor at
2610 least one character before it (possibly on a previous line) and output the
2611 @samp{se} string, which on these terminals finds and removes the next
2612 @samp{so} magic cookie on the screen. (It may also be possible to remove a
2613 cookie which is not at the beginning of a line by clearing that line.) The
2614 @samp{xt} capability also has implications for the use of tab characters,
2615 but in that regard it is obsolete (@xref{Cursor Motion}).
2620 String of commands to enter standout mode.
2624 String of commands to leave standout mode.
2628 Numeric capability, the width on the screen of the magic cookie. This
2629 capability is absent in terminals that record appearance modes
2630 character by character.
2634 Flag whose presence means that it is safe to move the cursor while the
2635 appearance modes are not in the normal state. If this flag is absent,
2636 programs should always reset the appearance modes to normal before
2641 Flag whose presence means that the only way to reset appearance modes
2642 already on the screen is to clear to end of line. On a per-character
2643 terminal, you must clear the area where the modes are set. On a magic
2644 cookie terminal, you must clear an area containing the cookie.
2645 See the discussion above.
2649 Flag whose presence means that the cursor cannot be positioned right
2650 in front of a magic cookie, and that @samp{se} is a command to delete
2651 the next magic cookie following the cursor. See discussion above.
2655 String of commands to enter blinking mode.
2659 String of commands to enter double-bright mode.
2663 String of commands to enter half-bright mode.
2667 String of commands to enter invisible mode.
2671 String of commands to enter protected mode.
2675 String of commands to enter reverse-video mode.
2679 String of commands to turn off all appearance modes, including
2680 standout mode and underline mode. On some terminals it also turns off
2681 alternate character set mode; on others, it may not. This capability
2682 must be present if any of @samp{mb} @dots{} @samp{mr} is present.
2686 String of commands to turn on alternate character set mode. This mode
2687 assigns some or all graphic characters an alternate picture on the
2688 screen. There is no standard as to what the alternate pictures look
2693 String of commands to turn off alternate character set mode.
2697 String of commands to turn on an arbitrary combination of appearance
2698 modes. It accepts 9 parameters, each of which controls a particular
2699 kind of appearance mode. A parameter should be 1 to turn its appearance
2700 mode on, or zero to turn that mode off. Most terminals do not support
2701 the @samp{sa} capability, even among those that do have various
2704 The nine parameters are, in order, @var{standout}, @var{underline},
2705 @var{reverse}, @var{blink}, @var{half-bright}, @var{double-bright},
2706 @var{blank}, @var{protect}, @var{alt char set}.
2709 @node Underlining, Cursor Visibility, Standout, Capabilities
2710 @section Underlining
2713 Underlining on most terminals is a kind of appearance mode, much like
2714 standout mode. Therefore, it may be implemented using magic cookies or as
2715 a flag in the terminal whose current state affects each character that is
2716 output. @xref{Standout}, for a full explanation.
2718 The @samp{ug} capability is a numeric capability whose presence indicates
2719 that the terminal uses magic cookies for underlining. Its value is the
2720 number of character positions that a magic cookie for underlining occupies;
2721 it is used for underlining just as @samp{sg} is used for standout. Aside
2722 from the simplest applications, it is impossible to use underlining
2723 correctly without paying attention to the value of @samp{ug}.
2728 String of commands to turn on underline mode or to output a magic cookie
2729 to start underlining.
2733 String of commands to turn off underline mode or to output a magic
2734 cookie to stop underlining.
2738 Width of magic cookie that represents a change of underline mode;
2739 or missing, if the terminal does not use a magic cookie for this.
2743 Flag whose presence means that it is safe to move the cursor while the
2744 appearance modes are not in the normal state. Underlining is an
2745 appearance mode. If this flag is absent, programs should always turn
2746 off underlining before moving the cursor.
2749 There are two other, older ways of doing underlining: there can be a
2750 command to underline a single character, or the output of @samp{_}, the
2751 ASCII underscore character, as an overstrike could cause a character to be
2752 underlined. New programs need not bother to handle these capabilities
2753 unless the author cares strongly about the obscure terminals which support
2754 them. However, terminal descriptions should provide these capabilities
2760 String of commands to underline the character under the cursor, and
2761 move the cursor right.
2765 Flag whose presence means that the terminal can underline by
2766 overstriking an underscore character (@samp{_}); some terminals can do
2767 this even though they do not support overstriking in general. An
2768 implication of this flag is that when outputting new text to overwrite
2769 old text, underscore characters must be treated specially lest they
2770 underline the old text instead.
2773 @node Cursor Visibility, Bell, Underlining, Capabilities
2774 @section Cursor Visibility
2777 Some terminals have the ability to make the cursor invisible, or to enhance
2778 it. Enhancing the cursor is often done by programs that plan to use the
2779 cursor to indicate to the user a position of interest that may be anywhere
2780 on the screen---for example, the Emacs editor enhances the cursor on entry.
2781 Such programs should always restore the cursor to normal on exit.
2786 String of commands to enhance the cursor.
2790 String of commands to make the cursor invisible.
2794 String of commands to return the cursor to normal.
2797 If you define either @samp{vs} or @samp{vi}, you must also define @samp{ve}.
2799 @node Bell, Keypad, Cursor Visibility, Capabilities
2802 @cindex visible bell
2804 Here we describe commands to make the terminal ask for the user to pay
2810 String of commands to cause the terminal to make an audible sound. If
2811 this capability is absent, the terminal has no way to make a suitable
2816 String of commands to cause the screen to flash to attract attention
2817 (``visible bell''). If this capability is absent, the terminal has no
2818 way to do such a thing.
2821 @node Keypad, Meta Key, Bell, Capabilities
2822 @section Keypad and Function Keys
2824 Many terminals have arrow and function keys that transmit specific
2825 character sequences to the computer. Since the precise sequences used
2826 depend on the terminal, termcap defines capabilities used to say what the
2827 sequences are. Unlike most termcap string-valued capabilities, these are
2828 not strings of commands to be sent to the terminal, rather strings that
2829 are received from the terminal.
2831 Programs that expect to use keypad keys should check, initially, for a
2832 @samp{ks} capability and send it, to make the keypad actually transmit.
2833 Such programs should also send the @samp{ke} string when exiting.
2838 String of commands to make the keypad keys transmit. If this
2839 capability is not provided, but the others in this section are,
2840 programs may assume that the keypad keys always transmit.
2843 String of commands to make the keypad keys work locally. This
2844 capability is provided only if @samp{ks} is.
2847 String of input characters sent by typing the left-arrow key. If this
2848 capability is missing, you cannot expect the terminal to have a
2849 left-arrow key that transmits anything to the computer.
2852 String of input characters sent by typing the right-arrow key.
2855 String of input characters sent by typing the up-arrow key.
2858 String of input characters sent by typing the down-arrow key.
2861 String of input characters sent by typing the ``home-position'' key.
2863 @item @samp{K1} @dots{} @samp{K5}
2865 Strings of input characters sent by the five other keys in a 3-by-3
2866 array that includes the arrow keys, if the keyboard has such a 3-by-3
2867 array. Note that one of these keys may be the ``home-position'' key,
2868 in which case one of these capabilities will have the same value as
2872 String of input characters sent by function key 10 (or 0, if the terminal
2875 @item @samp{k1} @dots{} @samp{k9}
2877 Strings of input characters sent by function keys 1 through 9,
2878 provided for those function keys that exist.
2881 Number: the number of numbered function keys, if there are more than
2884 @item @samp{l0} @dots{} @samp{l9}
2886 Strings which are the labels appearing on the keyboard on the keys
2887 described by the capabilities @samp{k0} @dots{} @samp{l9}. These
2888 capabilities should be left undefined if the labels are @samp{f0} or
2889 @samp{f10} and @samp{f1} @dots{} @samp{f9}.@refill
2893 String of input characters sent by the ``home down'' key, if there is
2897 String of input characters sent by the ``backspace'' key, if there is
2901 String of input characters sent by the ``clear all tabs'' key, if there
2905 String of input characters sent by the ``clear tab stop this column''
2906 key, if there is one.
2909 String of input characters sent by the ``clear screen'' key, if there is
2913 String of input characters sent by the ``delete character'' key, if
2917 String of input characters sent by the ``delete line'' key, if there is
2921 String of input characters sent by the ``exit insert mode'' key, if
2925 String of input characters sent by the ``clear to end of line'' key, if
2929 String of input characters sent by the ``clear to end of screen'' key,
2933 String of input characters sent by the ``insert character'' or ``enter
2934 insert mode'' key, if there is one.
2937 String of input characters sent by the ``insert line'' key, if there is
2941 String of input characters sent by the ``next page'' key, if there is
2945 String of input characters sent by the ``previous page'' key, if there is
2949 String of input characters sent by the ``scroll forward'' key, if there
2953 String of input characters sent by the ``scroll reverse'' key, if there
2957 String of input characters sent by the ``set tab stop in this column''
2958 key, if there is one.
2961 String listing the other function keys the terminal has. This is a
2962 very obsolete way of describing the same information found in the
2963 @samp{kH} @dots{} @samp{kT} keys. The string contains a list of
2964 two-character termcap capability names, separated by commas. The
2965 meaning is that for each capability name listed, the terminal has a
2966 key which sends the string which is the value of that capability. For
2967 example, the value @samp{:ko=cl,ll,sf,sr:} says that the terminal has
2968 four function keys which mean ``clear screen'', ``home down'',
2969 ``scroll forward'' and ``scroll reverse''.@refill
2972 @node Meta Key, Initialization, Keypad, Capabilities
2976 A Meta key is a key on the keyboard that modifies each character you type
2977 by controlling the 0200 bit. This bit is on if and only if the Meta key is
2978 held down when the character is typed. Characters typed using the Meta key
2979 are called Meta characters. Emacs uses Meta characters as editing
2985 Flag whose presence means that the terminal has a Meta key.
2989 String of commands to enable the functioning of the Meta key.
2993 String of commands to disable the functioning of the Meta key.
2996 If the terminal has @samp{km} but does not have @samp{mm} and @samp{mo}, it
2997 means that the Meta key always functions. If it has @samp{mm} and
2998 @samp{mo}, it means that the Meta key can be turned on or off. Send the
2999 @samp{mm} string to turn it on, and the @samp{mo} string to turn it off.
3000 I do not know why one would ever not want it to be on.
3002 @node Initialization, Pad Specs, Meta Key, Capabilities
3003 @section Initialization
3005 @cindex initialization
3011 String of commands to put the terminal into whatever special modes are
3012 needed or appropriate for programs that move the cursor
3013 nonsequentially around the screen. Programs that use termcap to do
3014 full-screen display should output this string when they start up.
3018 String of commands to undo what is done by the @samp{ti} string.
3019 Programs that output the @samp{ti} string on entry should output this
3020 string when they exit.
3024 String of commands to initialize the terminal for each login session.
3028 String which is the name of a file containing the string of commands
3029 to initialize the terminal for each session of use. Normally @samp{is}
3030 and @samp{if} are not both used.
3036 Two more strings of commands to initialize the terminal for each login
3037 session. The @samp{i1} string (if defined) is output before @samp{is}
3038 or @samp{if}, and the @samp{i3} string (if defined) is output after.
3040 The reason for having three separate initialization strings is to make
3041 it easier to define a group of related terminal types with slightly
3042 different initializations. Define two or three of the strings in the
3043 basic type; then the other types can override one or two of the
3048 String of commands to reset the terminal from any strange mode it may
3049 be in. Normally this includes the @samp{is} string (or other commands
3050 with the same effects) and more. What would go in the @samp{rs}
3051 string but not in the @samp{is} string are annoying or slow commands
3052 to bring the terminal back from strange modes that nobody would
3057 Numeric value, the initial spacing between hardware tab stop columns
3058 when the terminal is powered up. Programs to initialize the terminal
3059 can use this to decide whether there is a need to set the tab stops.
3060 If the initial width is 8, well and good; if it is not 8, then the
3061 tab stops should be set; if they cannot be set, the kernel is told
3062 to convert tabs to spaces, and other programs will observe this and do
3067 String of commands to clear all tab stops.
3071 String of commands to set tab stop at current cursor column on all
3076 Flag whose presence means that the terminal does not support XON/XOFF
3077 flow control. Programs should not send XON (@kbd{C-q}) or XOFF
3078 (@kbd{C-s}) characters to the terminal.
3081 @node Pad Specs, Status Line, Initialization, Capabilities
3082 @section Padding Capabilities
3085 There are two terminal capabilities that exist just to explain the proper
3086 way to obey the padding specifications in all the command string
3087 capabilities. One, @samp{pc}, must be obeyed by all termcap-using
3093 Numeric value, the lowest baud rate at which padding is actually
3094 needed. Programs may check this and refrain from doing any padding at
3099 String of commands for padding. The first character of this string is
3100 to be used as the pad character, instead of using null characters for
3101 padding. If @samp{pc} is not provided, use null characters. Every
3102 program that uses termcap must look up this capability and use it to
3103 set the variable @code{PC} that is used by @code{tputs}.
3107 Some termcap capabilities exist just to specify the amount of padding that
3108 the kernel should give to cursor motion commands used in ordinary
3114 Numeric value, the number of msec of padding needed for the
3115 carriage-return character.
3119 Numeric value, the number of msec of padding needed for the newline
3120 (linefeed) character.
3124 Numeric value, the number of msec of padding needed for the backspace
3129 Numeric value, the number of msec of padding needed for the formfeed
3134 Numeric value, the number of msec of padding needed for the tab
3138 In some systems, the kernel uses the above capabilities; in other systems,
3139 the kernel uses the paddings specified in the string capabilities
3140 @samp{cr}, @samp{sf}, @samp{le}, @samp{ff} and @samp{ta}. Descriptions of
3141 terminals which require such padding should contain the @samp{dC} @dots{}
3142 @samp{dT} capabilities and also specify the appropriate padding in the
3143 corresponding string capabilities. Since no modern terminals require
3144 padding for ordinary sequential output, you probably won't need to do
3145 either of these things.
3147 @node Status Line, Half-Line, Pad Specs, Capabilities
3148 @section Status Line
3151 A @dfn{status line} is a line on the terminal that is not used for ordinary
3152 display output but instead used for a special message. The intended use is
3153 for a continuously updated description of what the user's program is doing,
3154 and that is where the name ``status line'' comes from, but in fact it could
3155 be used for anything. The distinguishing characteristic of a status line
3156 is that ordinary output to the terminal does not affect it; it changes only
3157 if the special status line commands of this section are used.
3162 Flag whose presence means that the terminal has a status line. If a
3163 terminal description specifies that there is a status line, it must
3164 provide the @samp{ts} and @samp{fs} capabilities.
3168 String of commands to move the terminal cursor into the status line.
3169 Usually these commands must specifically record the old cursor
3170 position for the sake of the @samp{fs} string.
3174 String of commands to move the cursor back from the status line to its
3175 previous position (outside the status line).
3179 Flag whose presence means that other display commands work while
3180 writing the status line. In other words, one can clear parts of it,
3181 insert or delete characters, move the cursor within it using @samp{ch}
3182 if there is a @samp{ch} capability, enter and leave standout mode, and
3187 String of commands to disable the display of the status line. This
3188 may be absent, if there is no way to disable the status line display.
3192 Numeric value, the width of the status line. If this capability is
3193 absent in a terminal that has a status line, it means the status line
3194 is the same width as the other lines.
3196 Note that the value of @samp{ws} is sometimes as small as 8.
3199 @node Half-Line, Printer, Status Line, Capabilities
3200 @section Half-Line Motion
3202 Some terminals have commands for moving the cursor vertically by half-lines,
3203 useful for outputting subscripts and superscripts. Mostly it is hardcopy
3204 terminals that have such features.
3209 String of commands to move the cursor up half a line. If the terminal
3210 is a display, it is your responsibility to avoid moving up past the
3211 top line; however, most likely the terminal that supports this is a
3212 hardcopy terminal and there is nothing to be concerned about.
3216 String of commands to move the cursor down half a line. If the
3217 terminal is a display, it is your responsibility to avoid moving down
3218 past the bottom line, etc.
3221 @node Printer, , Half-Line, Capabilities
3222 @section Controlling Printers Attached to Terminals
3225 Some terminals have attached hardcopy printer ports. They may be able to
3226 copy the screen contents to the printer; they may also be able to redirect
3227 output to the printer. Termcap does not have anything to tell the program
3228 whether the redirected output appears also on the screen; it does on some
3229 terminals but not all.
3234 String of commands to cause the contents of the screen to be printed.
3235 If it is absent, the screen contents cannot be printed.
3239 String of commands to redirect further output to the printer.
3243 String of commands to terminate redirection of output to the printer.
3244 This capability must be present in the description if @samp{po} is.
3248 String of commands to redirect output to the printer for next @var{n}
3249 characters of output, regardless of what they are. Redirection will
3250 end automatically after @var{n} characters of further output. Until
3251 then, nothing that is output can end redirection, not even the
3252 @samp{pf} string if there is one. The number @var{n} should not be
3255 One use of this capability is to send non-text byte sequences (such as
3256 bit-maps) to the printer.
3259 Most terminals with printers do not support all of @samp{ps}, @samp{po} and
3260 @samp{pO}; any one or two of them may be supported. To make a program that
3261 can send output to all kinds of printers, it is necessary to check for all
3262 three of these capabilities, choose the most convenient of the ones that
3263 are provided, and use it in its own appropriate fashion.
3265 @node Summary, Var Index, Capabilities, Top
3266 @chapter Summary of Capability Names
3268 Here are all the terminal capability names in alphabetical order
3269 with a brief description of each. For cross references to their definitions,
3270 see the index of capability names (@pxref{Cap Index}).
3274 String to turn off alternate character set mode.
3276 String to insert a blank line before the cursor.
3278 String to insert @var{n} blank lines before the cursor.
3280 Flag: output to last column wraps cursor to next line.
3282 String to turn on alternate character set mode.like.
3284 Very obsolete alternative name for the @samp{le} capability.
3286 String to sound the bell.
3288 Obsolete flag: ASCII backspace may be used for leftward motion.
3290 String to move the cursor left to the previous hardware tab stop column.
3292 Flag: @samp{le} at left margin wraps to end of previous line.
3294 String to change terminal's command character.
3296 String to clear the line the cursor is on, and following lines.
3298 String to clear from the cursor to the end of the line.
3300 String to position the cursor at column @var{c} in the same line.
3302 String to clear the entire screen and put cursor at upper left corner.
3304 String to position the cursor at line @var{l}, column @var{c}.
3306 String to position the cursor at line @var{l}, column
3307 @var{c}, relative to display memory.
3309 Number: width of the screen.
3311 String to move cursor sideways to left margin.
3313 String to set the scroll region.
3315 Alternate form of string to set the scroll region.
3317 String to clear all tab stops.
3319 String to position the cursor at line @var{l} in the same column.
3321 Flag: data scrolled off top of screen may be scrolled back.
3323 Flag: data scrolled off bottom of screen may be scrolled back.
3325 Obsolete number: msec of padding needed for the backspace character.
3327 String to delete one character position at the cursor.
3329 Obsolete number: msec of padding needed for the carriage-return character.
3331 String to delete @var{n} characters starting at the cursor.
3333 Obsolete number: msec of padding needed for the formfeed character.
3335 String to delete the line the cursor is on.
3337 String to delete @var{n} lines starting with the cursor's line.
3339 String to enter delete mode.
3341 Obsolete number: msec of padding needed for the newline character.
3343 String to move the cursor vertically down one line.
3345 String to move cursor vertically down @var{n} lines.
3347 String to disable the display of the status line.
3349 Obsolete number: msec of padding needed for the tab character.
3351 String of commands to clear @var{n} characters at cursor.
3353 String to exit delete mode.
3355 String to leave insert mode.
3357 Flag: output of a space can erase an overstrike.
3359 Flag: other display commands work while writing the status line.
3361 String to advance to the next page, for a hardcopy terminal.
3363 String to move the cursor back from the status line to its
3364 previous position (outside the status line).
3366 Flag: this terminal type is generic, not real.
3368 Flag: hardcopy terminal.
3370 String to move the cursor down half a line.
3372 String to position cursor at upper left corner.
3374 Flag: the terminal has a status line.
3376 String to move the cursor up half a line.
3378 Flag: terminal cannot accept @samp{~} as output.
3380 String to initialize the terminal for each login session.
3382 String to initialize the terminal for each login session.
3384 String to insert one character position at the cursor.
3386 String to insert @var{n} character positions at the cursor.
3388 String naming a file of commands to initialize the terminal.
3390 String to enter insert mode.
3392 Flag: outputting a space is different from moving over empty positions.
3394 String to output following an inserted character in insert mode.
3396 String to initialize the terminal for each login session.
3398 Number: initial spacing between hardware tab stop columns.
3400 String of input sent by function key 0 or 10.
3402 Strings of input sent by function keys 1 through 9.
3404 Strings sent by the five other keys in 3-by-3 array with arrows.
3406 String of input sent by the ``clear all tabs'' key.
3408 String of input sent by the ``insert line'' key.
3410 String of input sent by the ``backspace'' key.
3412 String of input sent by the ``clear screen'' key.
3414 String of input sent by typing the down-arrow key.
3416 String of input sent by the ``delete character'' key.
3418 String to make the function keys work locally.
3420 String of input sent by the ``clear to end of line'' key.
3422 String of input sent by the ``scroll forward'' key.
3424 String of input sent by typing the ``home-position'' key.
3426 String of input sent by the ``home down'' key.
3428 String of input sent by the ``insert character'' or ``enter
3431 String of input sent by typing the left-arrow key.
3433 String of input sent by the ``delete line'' key.
3435 Flag: the terminal has a Meta key.
3437 String of input sent by the ``exit insert mode'' key.
3439 Numeric value, the number of numbered function keys.
3441 String of input sent by the ``next page'' key.
3443 Very obsolete string listing the terminal's named function keys.
3445 String of input sent by the ``previous page'' key.
3447 String of input sent by typing the right-arrow key.
3449 String of input sent by the ``scroll reverse'' key.
3451 String to make the function keys transmit.
3453 String of input sent by the ``clear to end of screen'' key.
3455 String of input sent by the ``clear tab stop this column'' key.
3457 String of input sent by the ``set tab stop in this column'' key.
3459 String of input sent by typing the up-arrow key.
3461 String on keyboard labelling function key 0 or 10.
3463 Strings on keyboard labelling function keys 1 through 9.
3465 String to move the cursor left one column.
3467 String to move cursor left @var{n} columns.
3469 Number: height of the screen.
3471 String to position cursor at lower left corner.
3473 Number: lines of display memory.
3475 Flag: writing to last column of last line will not scroll.
3477 String to enter blinking mode.
3479 String to enter double-bright mode.
3481 String to turn off all appearance modes
3483 String to enter half-bright mode.
3485 Flag: cursor motion in insert mode is safe.
3487 String to enter invisible mode.
3489 String to enable the functioning of the Meta key.
3491 String to disable the functioning of the Meta key.
3493 String to enter protected mode.
3495 String to enter reverse-video mode.
3497 Flag: cursor motion in standout mode is safe.
3499 Obsolete flag: do not use ASCII carriage-return on this terminal.
3501 String to move the cursor right one column.
3503 Flag: do not use XON/XOFF flow control.
3505 Obsolete alternative name for the @samp{do} and @samp{sf} capabilities.
3507 Flag: the terminal does not normally scroll for sequential output.
3509 String to move to start of next line, possibly clearing rest of old line.
3511 Flag: terminal can overstrike.
3513 Number: the lowest baud rate at which padding is actually needed.
3515 String containing character for padding.
3517 String to terminate redirection of output to the printer.
3519 String to redirect further output to the printer.
3521 String to redirect @var{n} characters ofoutput to the printer.
3523 String to print the screen on the attached printer.
3525 String to move to last saved cursor position.
3527 String to move cursor right @var{n} columns.
3529 String to output character @var{c} repeated @var{n} times.
3531 String to reset the terminal from any strange modes.
3533 String to turn on an arbitrary combination of appearance modes.
3535 String to save the current cursor position.
3537 String to leave standout mode.
3539 String to scroll the screen one line up.
3541 String to scroll the screen @var{n} lines up.
3543 Number: width of magic standout cookie. Absent if magic cookies are
3546 String to enter standout mode.
3548 String to scroll the screen one line down.
3550 String to scroll the screen @var{n} line down.
3552 String to set tab stop at current cursor column on all lines.
3555 String to move the cursor right to the next hardware tab stop column.
3557 String to return terminal to settings for sequential output.
3559 String to initialize terminal for random cursor motion.
3561 String to move the terminal cursor into the status line.
3563 String to underline one character and move cursor right.
3565 String to turn off underline mode
3567 Number: width of underlining magic cookie. Absent if underlining
3568 doesn't use magic cookies.
3570 Flag: underline by overstriking with an underscore.
3572 String to move the cursor vertically up one line.
3574 String to move cursor vertically up @var{n} lines.
3576 String to turn on underline mode
3578 String to make the screen flash.
3580 String to return the cursor to normal.
3582 String to make the cursor invisible.
3584 String to enhance the cursor.
3586 String to set the terminal output screen window.
3588 Number: the width of the status line.
3590 Flag: superbee terminal.
3592 Flag: cursor wraps in a strange way.
3594 Flag: clearing a line is the only way to clear the appearance modes of
3595 positions in that line (or, only way to remove magic cookies on that
3598 Flag: Teleray 1061; several strange characteristics.
3601 @node Var Index, Cap Index, Summary, Top
3602 @unnumbered Variable and Function Index
3606 @node Cap Index, Index, Var Index, Top
3607 @unnumbered Capability Index
3611 @node Index, , Cap Index, Top
3612 @unnumbered Concept Index