diff options
Diffstat (limited to 'lib/termcap/grot/termcap.texi')
| -rw-r--r-- | lib/termcap/grot/termcap.texi | 3617 |
1 files changed, 3617 insertions, 0 deletions
diff --git a/lib/termcap/grot/termcap.texi b/lib/termcap/grot/termcap.texi new file mode 100644 index 0000000..eab49e8 --- /dev/null +++ b/lib/termcap/grot/termcap.texi @@ -0,0 +1,3617 @@ +\input texinfo @c -*-texinfo-*- +@setfilename termcap.info +@settitle The Termcap Library +@smallbook + +@ifinfo +This file documents the termcap library of the GNU system. + +Copyright (C) 1988 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end ifinfo + +@setchapternewpage odd + +@c @shorttitlepage The Termcap Manual + +@titlepage +@ignore +@sp 6 +@center @titlefont{Termcap} +@sp 1 +@center The Termcap Library and Data Base +@sp 4 +@center Second Edition +@sp 1 +@center December 1992 +@sp 5 +@center Richard M. Stallman +@sp 1 +@center Free Software Foundation +@end ignore + +@c Real title page +@title The Termcap Manual +@subtitle The Termcap Library and Data Base +@subtitle Second Edition +@subtitle December 1992 +@author Richard M. Stallman +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1988 Free Software Foundation, Inc. + +Published by the Free Software Foundation +(59 Temple Place, Suite 330, Boston, MA 02111 USA). +Printed copies are available for $10 each. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@sp 2 +Cover art by Etienne Suvasa. +@end titlepage +@page + +@synindex vr fn + +@node Top, Introduction, (dir), (dir) + +@menu +* Introduction:: What is termcap? Why this manual? +* Library:: The termcap library functions. +* Data Base:: What terminal descriptions in @file{/etc/termcap} look like. +* Capabilities:: Definitions of the individual terminal capabilities: + how to write them in descriptions, and how to use + their values to do display updating. +* Summary:: Brief table of capability names and their meanings. +* Var Index:: Index of C functions and variables. +* Cap Index:: Index of termcap capabilities. +* Index:: Concept index. + + --- The Detailed Node Listing --- + +The Termcap Library + +* Preparation:: Preparing to use the termcap library. +* Find:: Finding the description of the terminal being used. +* Interrogate:: Interrogating the description for particular capabilities. +* Initialize:: Initialization for output using termcap. +* Padding:: Outputting padding. +* Parameters:: Encoding parameters such as cursor positions. + +Padding + +* Why Pad:: Explanation of padding. +* Not Enough:: When there is not enough padding. +* Describe Padding:: The data base says how much padding a terminal needs. +* Output Padding:: Using @code{tputs} to output the needed padding. + +Filling In Parameters + +* Encode Parameters:: The language for encoding parameters. +* Using Parameters:: Outputting a string command with parameters. + +Sending Display Commands with Parameters + +* tparam:: The general case, for GNU termcap only. +* tgoto:: The special case of cursor motion. + +The Format of the Data Base + +* Format:: Overall format of a terminal description. +* Capability Format:: Format of capabilities within a description. +* Naming:: Naming conventions for terminal types. +* Inheriting:: Inheriting part of a description from +a related terminal type. +* Changing:: When changes in the data base take effect. + +Definitions of the Terminal Capabilities + +* Basic:: Basic characteristics. +* Screen Size:: Screen size, and what happens when it changes. +* Cursor Motion:: Various ways to move the cursor. +* Wrapping:: What happens if you write a character in the last column. +* Scrolling:: Pushing text up and down on the screen. +* Windows:: Limiting the part of the window that output affects. +* Clearing:: Erasing one or many lines. +* Insdel Line:: Making new blank lines in mid-screen; deleting lines. +* Insdel Char:: Inserting and deleting characters within a line. +* Standout:: Highlighting some of the text. +* Underlining:: Underlining some of the text. +* Cursor Visibility:: Making the cursor more or less easy to spot. +* Bell:: Attracts user's attention; not localized on the screen. +* Keypad:: Recognizing when function keys or arrows are typed. +* Meta Key:: @key{META} acts like an extra shift key. +* Initialization:: Commands used to initialize or reset the terminal. +* Pad Specs:: Info for the kernel on how much padding is needed. +* Status Line:: A status line displays ``background'' information. +* Half-Line:: Moving by half-lines, for superscripts and subscripts. +* Printer:: Controlling auxiliary printers of display terminals. +@end menu + +@node Introduction, Library, Top, Top +@unnumbered Introduction + +@cindex termcap +@dfn{Termcap} is a library and data base that enables programs to use +display terminals in a terminal-independent manner. It originated in +Berkeley Unix. + +The termcap data base describes the capabilities of hundreds of different +display terminals in great detail. Some examples of the information +recorded for a terminal could include how many columns wide it is, what +string to send to move the cursor to an arbitrary position (including how +to encode the row and column numbers), how to scroll the screen up one or +several lines, and how much padding is needed for such a scrolling +operation. + +The termcap library is provided for easy access this data base in programs +that want to do terminal-independent character-based display output. + +This manual describes the GNU version of the termcap library, which has +some extensions over the Unix version. All the extensions are identified +as such, so this manual also tells you how to use the Unix termcap. + +The GNU version of the termcap library is available free as source code, +for use in free programs, and runs on Unix and VMS systems (at least). You +can find it in the GNU Emacs distribution in the files @file{termcap.c} and +@file{tparam.c}. + +This manual was written for the GNU project, whose goal is to develop a +complete free operating system upward-compatible with Unix for user +programs. The project is approximately two thirds complete. For more +information on the GNU project, including the GNU Emacs editor and the +mostly-portable optimizing C compiler, send one dollar to + +@display +Free Software Foundation +675 Mass Ave +Cambridge, MA 02139 +@end display + +@node Library, Data Base, Introduction, Top +@chapter The Termcap Library + +The termcap library is the application programmer's interface to the +termcap data base. It contains functions for the following purposes: + +@itemize @bullet +@item +Finding the description of the user's terminal type (@code{tgetent}). + +@item +Interrogating the description for information on various topics +(@code{tgetnum}, @code{tgetflag}, @code{tgetstr}). + +@item +Computing and performing padding (@code{tputs}). + +@item +Encoding numeric parameters such as cursor positions into the +terminal-specific form required for display commands (@code{tparam}, +@code{tgoto}). +@end itemize + +@menu +* Preparation:: Preparing to use the termcap library. +* Find:: Finding the description of the terminal being used. +* Interrogate:: Interrogating the description for particular capabilities. +* Initialize:: Initialization for output using termcap. +* Padding:: Outputting padding. +* Parameters:: Encoding parameters such as cursor positions. +@end menu + +@node Preparation, Find, , Library +@section Preparing to Use the Termcap Library + +To use the termcap library in a program, you need two kinds of preparation: + +@itemize @bullet +@item +The compiler needs declarations of the functions and variables in the +library. + +On GNU systems, it suffices to include the header file +@file{termcap.h} in each source file that uses these functions and +variables.@refill + +On Unix systems, there is often no such header file. Then you must +explictly declare the variables as external. You can do likewise for +the functions, or let them be implicitly declared and cast their +values from type @code{int} to the appropriate type. + +We illustrate the declarations of the individual termcap library +functions with ANSI C prototypes because they show how to pass the +arguments. If you are not using the GNU C compiler, you probably +cannot use function prototypes, so omit the argument types and names +from your declarations. + +@item +The linker needs to search the library. Usually either +@samp{-ltermcap} or @samp{-ltermlib} as an argument when linking will +do this.@refill +@end itemize + +@node Find, Interrogate, Preparation, Library +@section Finding a Terminal Description: @code{tgetent} + +@findex tgetent +An application program that is going to use termcap must first look up the +description of the terminal type in use. This is done by calling +@code{tgetent}, whose declaration in ANSI Standard C looks like: + +@example +int tgetent (char *@var{buffer}, char *@var{termtype}); +@end example + +@noindent +This function finds the description and remembers it internally so that +you can interrogate it about specific terminal capabilities +(@pxref{Interrogate}). + +The argument @var{termtype} is a string which is the name for the type of +terminal to look up. Usually you would obtain this from the environment +variable @code{TERM} using @code{getenv ("TERM")}. + +If you are using the GNU version of termcap, you can alternatively ask +@code{tgetent} to allocate enough space. Pass a null pointer for +@var{buffer}, and @code{tgetent} itself allocates the storage using +@code{malloc}. There is no way to get the address that was allocated, +and you shouldn't try to free the storage.@refill + +With the Unix version of termcap, you must allocate space for the +description yourself and pass the address of the space as the argument +@var{buffer}. There is no way you can tell how much space is needed, so +the convention is to allocate a buffer 2048 characters long and assume that +is enough. (Formerly the convention was to allocate 1024 characters and +assume that was enough. But one day, for one kind of terminal, that was +not enough.) + +No matter how the space to store the description has been obtained, +termcap records its address internally for use when you later interrogate +the description with @code{tgetnum}, @code{tgetstr} or @code{tgetflag}. If +the buffer was allocated by termcap, it will be freed by termcap too if you +call @code{tgetent} again. If the buffer was provided by you, you must +make sure that its contents remain unchanged for as long as you still plan +to interrogate the description.@refill + +The return value of @code{tgetent} is @minus{}1 if there is some difficulty +accessing the data base of terminal types, 0 if the data base is accessible +but the specified type is not defined in it, and some other value +otherwise. + +Here is how you might use the function @code{tgetent}: + +@smallexample +#ifdef unix +static char term_buffer[2048]; +#else +#define term_buffer 0 +#endif + +init_terminal_data () +@{ + char *termtype = getenv ("TERM"); + int success; + + if (termtype == 0) + fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n"); + + success = tgetent (term_buffer, termtype); + if (success < 0) + fatal ("Could not access the termcap data base.\n"); + if (success == 0) + fatal ("Terminal type `%s' is not defined.\n", termtype); +@} +@end smallexample + +@noindent +Here we assume the function @code{fatal} prints an error message and exits. + +If the environment variable @code{TERMCAP} is defined, its value is used to +override the terminal type data base. The function @code{tgetent} checks +the value of @code{TERMCAP} automatically. If the value starts with +@samp{/} then it is taken as a file name to use as the data base file, +instead of @file{/etc/termcap} which is the standard data base. If the +value does not start with @samp{/} then it is itself used as the terminal +description, provided that the terminal type @var{termtype} is among the +types it claims to apply to. @xref{Data Base}, for information on the +format of a terminal description.@refill + +@node Interrogate, Initialize, Find, Library +@section Interrogating the Terminal Description + +Each piece of information recorded in a terminal description is called a +@dfn{capability}. Each defined terminal capability has a two-letter code +name and a specific meaning. For example, the number of columns is named +@samp{co}. @xref{Capabilities}, for definitions of all the standard +capability names. + +Once you have found the proper terminal description with @code{tgetent} +(@pxref{Find}), your application program must @dfn{interrogate} it for +various terminal capabilities. You must specify the two-letter code of +the capability whose value you seek. + +Capability values can be numeric, boolean (capability is either present or +absent) or strings. Any particular capability always has the same value +type; for example, @samp{co} always has a numeric value, while @samp{am} +(automatic wrap at margin) is always a flag, and @samp{cm} (cursor motion +command) always has a string value. The documentation of each capability +says which type of value it has.@refill + +There are three functions to use to get the value of a capability, +depending on the type of value the capability has. Here are their +declarations in ANSI C: + +@findex tgetnum +@findex tgetflag +@findex tgetstr +@example +int tgetnum (char *@var{name}); +int tgetflag (char *@var{name}); +char *tgetstr (char *@var{name}, char **@var{area}); +@end example + +@table @code +@item tgetnum +Use @code{tgetnum} to get a capability value that is numeric. The +argument @var{name} is the two-letter code name of the capability. If +the capability is present, @code{tgetnum} returns the numeric value +(which is nonnegative). If the capability is not mentioned in the +terminal description, @code{tgetnum} returns @minus{}1. + +@item tgetflag +Use @code{tgetflag} to get a boolean value. If the capability +@var{name} is present in the terminal description, @code{tgetflag} +returns 1; otherwise, it returns 0. + +@item tgetstr +Use @code{tgetstr} to get a string value. It returns a pointer to a +string which is the capability value, or a null pointer if the +capability is not present in the terminal description. + +There are two ways @code{tgetstr} can find space to store the string value: + +@itemize @bullet +@item +You can ask @code{tgetstr} to allocate the space. Pass a null +pointer for the argument @var{area}, and @code{tgetstr} will use +@code{malloc} to allocate storage big enough for the value. +Termcap will never free this storage or refer to it again; you +should free it when you are finished with it. + +This method is more robust, since there is no need to guess how +much space is needed. But it is supported only by the GNU +termcap library. + +@item +You can provide the space. Provide for the argument @var{area} the +address of a pointer variable of type @code{char *}. Before calling +@code{tgetstr}, initialize the variable to point at available space. +Then @code{tgetstr} will store the string value in that space and will +increment the pointer variable to point after the space that has been +used. You can use the same pointer variable for many calls to +@code{tgetstr}. + +There is no way to determine how much space is needed for a single +string, and no way for you to prevent or handle overflow of the area +you have provided. However, you can be sure that the total size of +all the string values you will obtain from the terminal description is +no greater than the size of the description (unless you get the same +capability twice). You can determine that size with @code{strlen} on +the buffer you provided to @code{tgetent}. See below for an example. + +Providing the space yourself is the only method supported by the Unix +version of termcap. +@end itemize +@end table + +Note that you do not have to specify a terminal type or terminal +description for the interrogation functions. They automatically use the +description found by the most recent call to @code{tgetent}. + +Here is an example of interrogating a terminal description for various +capabilities, with conditionals to select between the Unix and GNU methods +of providing buffer space. + +@example +char *tgetstr (); + +char *cl_string, *cm_string; +int height; +int width; +int auto_wrap; + +char PC; /* For tputs. */ +char *BC; /* For tgoto. */ +char *UP; + +interrogate_terminal () +@{ +#ifdef UNIX + /* Here we assume that an explicit term_buffer + was provided to tgetent. */ + char *buffer + = (char *) malloc (strlen (term_buffer)); +#define BUFFADDR &buffer +#else +#define BUFFADDR 0 +#endif + + char *temp; + + /* Extract information we will use. */ + cl_string = tgetstr ("cl", BUFFADDR); + cm_string = tgetstr ("cm", BUFFADDR); + auto_wrap = tgetflag ("am"); + height = tgetnum ("li"); + width = tgetnum ("co"); + + /* Extract information that termcap functions use. */ + temp = tgetstr ("pc", BUFFADDR); + PC = temp ? *temp : 0; + BC = tgetstr ("le", BUFFADDR); + UP = tgetstr ("up", BUFFADDR); +@} +@end example + +@noindent +@xref{Padding}, for information on the variable @code{PC}. @xref{Using +Parameters}, for information on @code{UP} and @code{BC}. + +@node Initialize, Padding, Interrogate, Library +@section Initialization for Use of Termcap +@cindex terminal flags (kernel) + +Before starting to output commands to a terminal using termcap, +an application program should do two things: + +@itemize @bullet +@item +Initialize various global variables which termcap library output +functions refer to. These include @code{PC} and @code{ospeed} for +padding (@pxref{Output Padding}) and @code{UP} and @code{BC} for +cursor motion (@pxref{tgoto}).@refill + +@item +Tell the kernel to turn off alteration and padding of horizontal-tab +characters sent to the terminal. +@end itemize + +To turn off output processing in Berkeley Unix you would use @code{ioctl} +with code @code{TIOCLSET} to set the bit named @code{LLITOUT}, and clear +the bits @code{ANYDELAY} using @code{TIOCSETN}. In POSIX or System V, you +must clear the bit named @code{OPOST}. Refer to the system documentation +for details.@refill + +If you do not set the terminal flags properly, some older terminals will +not work. This is because their commands may contain the characters that +normally signify newline, carriage return and horizontal tab---characters +which the kernel thinks it ought to modify before output. + +When you change the kernel's terminal flags, you must arrange to restore +them to their normal state when your program exits. This implies that the +program must catch fatal signals such as @code{SIGQUIT} and @code{SIGINT} +and restore the old terminal flags before actually terminating. + +Modern terminals' commands do not use these special characters, so if you +do not care about problems with old terminals, you can leave the kernel's +terminal flags unaltered. + +@node Padding, Parameters, Initialize, Library +@section Padding +@cindex padding + +@dfn{Padding} means outputting null characters following a terminal display +command that takes a long time to execute. The terminal description says +which commands require padding and how much; the function @code{tputs}, +described below, outputs a terminal command while extracting from it the +padding information, and then outputs the padding that is necessary. + +@menu +* Why Pad:: Explanation of padding. +* Not Enough:: When there is not enough padding. +* Describe Padding:: The data base says how much padding a terminal needs. +* Output Padding:: Using @code{tputs} to output the needed padding. +@end menu + +@node Why Pad, Not Enough, , Padding +@subsection Why Pad, and How + +Most types of terminal have commands that take longer to execute than they +do to send over a high-speed line. For example, clearing the screen may +take 20msec once the entire command is received. During that time, on a +9600 bps line, the terminal could receive about 20 additional output +characters while still busy clearing the screen. Every terminal has a +certain amount of buffering capacity to remember output characters that +cannot be processed yet, but too many slow commands in a row can cause the +buffer to fill up. Then any additional output that cannot be processed +immediately will be lost. + +To avoid this problem, we normally follow each display command with enough +useless charaters (usually null characters) to fill up the time that the +display command needs to execute. This does the job if the terminal throws +away null characters without using up space in the buffer (which most +terminals do). If enough padding is used, no output can ever be lost. The +right amount of padding avoids loss of output without slowing down +operation, since the time used to transmit padding is time that nothing +else could be done. + +The number of padding characters needed for an operation depends on the +line speed. In fact, it is proportional to the line speed. A 9600 baud +line transmits about one character per msec, so the clear screen command in +the example above would need about 20 characters of padding. At 1200 baud, +however, only about 3 characters of padding are needed to fill up 20msec. + +@node Not Enough, Describe Padding, Why Pad, Padding +@subsection When There Is Not Enough Padding + +There are several common manifestations of insufficient padding. + +@itemize @bullet +@item +Emacs displays @samp{I-search: ^Q-} at the bottom of the screen. + +This means that the terminal thought its buffer was getting full of +display commands, so it tried to tell the computer to stop sending +any. + +@item +The screen is garbled intermittently, or the details of garbling vary +when you repeat the action. (A garbled screen could be due to a +command which is simply incorrect, or to user option in the terminal +which doesn't match the assumptions of the terminal description, but +this usually leads to reproducible failure.) + +This means that the buffer did get full, and some commands were lost. +Many changeable factors can change which ones are lost. + +@item +Screen is garbled at high output speeds but not at low speeds. +Padding problems nearly always go away at low speeds, usually even at +1200 baud. + +This means that a high enough speed permits commands to arrive faster +than they can be executed. +@end itemize + +Although any obscure command on an obscure terminal might lack padding, +in practice problems arise most often from the clearing commands +@samp{cl} and @samp{cd} (@pxref{Clearing}), the scrolling commands +@samp{sf} and @samp{sr} (@pxref{Scrolling}), and the line insert/delete +commands @samp{al} and @samp{dl} (@pxref{Insdel Line}). + +Occasionally the terminal description fails to define @samp{sf} and some +programs will use @samp{do} instead, so you may get a problem with +@samp{do}. If so, first define @samp{sf} just like @samp{do}, then +add some padding to @samp{sf}. + +The best strategy is to add a lot of padding at first, perhaps 200 msec. +This is much more than enough; in fact, it should cause a visible slowdown. +(If you don't see a slowdown, the change has not taken effect; +@pxref{Changing}.) If this makes the problem go away, you have found the +right place to add padding; now reduce the amount until the problem comes +back, then increase it again. If the problem remains, either it is in some +other capability or it is not a matter of padding at all. + +Keep in mind that on many terminals the correct padding for insert/delete +line or for scrolling is cursor-position dependent. If you get problems +from scrolling a large region of the screen but not from scrolling a small +part (just a few lines moving), it may mean that fixed padding should be +replaced with position-dependent padding. + +@node Describe Padding, Output Padding, Not Enough, Padding +@subsection Specifying Padding in a Terminal Description + +In the terminal description, the amount of padding required by each display +command is recorded as a sequence of digits at the front of the command. +These digits specify the padding time in milliseconds (msec). They can be +followed optionally by a decimal point and one more digit, which is a +number of tenths of msec. + +Sometimes the padding needed by a command depends on the cursor position. +For example, the time taken by an ``insert line'' command is usually +proportional to the number of lines that need to be moved down or cleared. +An asterisk (@samp{*}) following the padding time says that the time +should be multiplied by the number of screen lines affected by the command. + +@example +:al=1.3*\E[L: +@end example + +@noindent +is used to describe the ``insert line'' command for a certain terminal. +The padding required is 1.3 msec per line affected. The command itself is +@samp{@key{ESC} [ L}. + +The padding time specified in this way tells @code{tputs} how many pad +characters to output. @xref{Output Padding}. + +Two special capability values affect padding for all commands. These are +the @samp{pc} and @samp{pb}. The variable @samp{pc} specifies the +character to pad with, and @samp{pb} the speed below which no padding is +needed. The defaults for these variables, a null character and 0, +are correct for most terminals. @xref{Pad Specs}. + +@node Output Padding, , Describe Padding, Padding +@subsection Performing Padding with @code{tputs} +@cindex line speed + +@findex tputs +Use the termcap function @code{tputs} to output a string containing an +optional padding spec of the form described above (@pxref{Describe +Padding}). The function @code{tputs} strips off and decodes the padding +spec, outputs the rest of the string, and then outputs the appropriate +padding. Here is its declaration in ANSI C: + +@example +char PC; +short ospeed; + +int tputs (char *@var{string}, int @var{nlines}, int (*@var{outfun}) ()); +@end example + +Here @var{string} is the string (including padding spec) to be output; +@var{nlines} is the number of lines affected by the operation, which is +used to multiply the amount of padding if the padding spec ends with a +@samp{*}. Finally, @var{outfun} is a function (such as @code{fputchar}) +that is called to output each character. When actually called, +@var{outfun} should expect one argument, a character. + +@vindex ospeed +@vindex PC +The operation of @code{tputs} is controlled by two global variables, +@code{ospeed} and @code{PC}. The value of @code{ospeed} is supposed to be +the terminal output speed, encoded as in the @code{ioctl} system call which +gets the speed information. This is needed to compute the number of +padding characters. The value of @code{PC} is the character used for +padding. + +You are responsible for storing suitable values into these variables before +using @code{tputs}. The value stored into the @code{PC} variable should be +taken from the @samp{pc} capability in the terminal description (@pxref{Pad +Specs}). Store zero in @code{PC} if there is no @samp{pc} +capability.@refill + +The argument @var{nlines} requires some thought. Normally, it should be +the number of lines whose contents will be cleared or moved by the command. +For cursor motion commands, or commands that do editing within one line, +use the value 1. For most commands that affect multiple lines, such as +@samp{al} (insert a line) and @samp{cd} (clear from the cursor to the end +of the screen), @var{nlines} should be the screen height minus the current +vertical position (origin 0). For multiple insert and scroll commands such +as @samp{AL} (insert multiple lines), that same value for @var{nlines} is +correct; the number of lines being inserted is @i{not} correct.@refill + +If a ``scroll window'' feature is used to reduce the number of lines +affected by a command, the value of @var{nlines} should take this into +account. This is because the delay time required depends on how much work +the terminal has to do, and the scroll window feature reduces the work. +@xref{Scrolling}. + +Commands such as @samp{ic} and @samp{dc} (insert or delete characters) are +problematical because the padding needed by these commands is proportional +to the number of characters affected, which is the number of columns from +the cursor to the end of the line. It would be nice to have a way to +specify such a dependence, and there is no need for dependence on vertical +position in these commands, so it is an obvious idea to say that for these +commands @var{nlines} should really be the number of columns affected. +However, the definition of termcap clearly says that @var{nlines} is always +the number of lines affected, even in this case, where it is always 1. It +is not easy to change this rule now, because too many programs and terminal +descriptions have been written to follow it. + +Because @var{nlines} is always 1 for the @samp{ic} and @samp{dc} strings, +there is no reason for them to use @samp{*}, but some of them do. These +should be corrected by deleting the @samp{*}. If, some day, such entries +have disappeared, it may be possible to change to a more useful convention +for the @var{nlines} argument for these operations without breaking any +programs. + +@node Parameters, , Padding, Library +@section Filling In Parameters +@cindex parameters + +Some terminal control strings require numeric @dfn{parameters}. For +example, when you move the cursor, you need to say what horizontal and +vertical positions to move it to. The value of the terminal's @samp{cm} +capability, which says how to move the cursor, cannot simply be a string of +characters; it must say how to express the cursor position numbers and +where to put them within the command. + +The specifications of termcap include conventions as to which string-valued +capabilities require parameters, how many parameters, and what the +parameters mean; for example, it defines the @samp{cm} string to take +two parameters, the vertical and horizontal positions, with 0,0 being the +upper left corner. These conventions are described where the individual +commands are documented. + +Termcap also defines a language used within the capability definition for +specifying how and where to encode the parameters for output. This language +uses character sequences starting with @samp{%}. (This is the same idea as +@code{printf}, but the details are different.) The language for parameter +encoding is described in this section. + +A program that is doing display output calls the functions @code{tparam} or +@code{tgoto} to encode parameters according to the specifications. These +functions produce a string containing the actual commands to be output (as +well a padding spec which must be processed with @code{tputs}; +@pxref{Padding}). + +@menu +* Encode Parameters:: The language for encoding parameters. +* Using Parameters:: Outputting a string command with parameters. +@end menu + +@node Encode Parameters, Using Parameters, , Parameters +@subsection Describing the Encoding +@cindex % + +A terminal command string that requires parameters contains special +character sequences starting with @samp{%} to say how to encode the +parameters. These sequences control the actions of @code{tparam} and +@code{tgoto}. + +The parameters values passed to @code{tparam} or @code{tgoto} are +considered to form a vector. A pointer into this vector determines +the next parameter to be processed. Some of the @samp{%}-sequences +encode one parameter and advance the pointer to the next parameter. +Other @samp{%}-sequences alter the pointer or alter the parameter +values without generating output. + +For example, the @samp{cm} string for a standard ANSI terminal is written +as @samp{\E[%i%d;%dH}. (@samp{\E} stands for @key{ESC}.) @samp{cm} by +convention always requires two parameters, the vertical and horizontal goal +positions, so this string specifies the encoding of two parameters. Here +@samp{%i} increments the two values supplied, and each @samp{%d} encodes +one of the values in decimal. If the cursor position values 20,58 are +encoded with this string, the result is @samp{\E[21;59H}. + +First, here are the @samp{%}-sequences that generate output. Except for +@samp{%%}, each of them encodes one parameter and advances the pointer +to the following parameter. + +@table @samp +@item %% +Output a single @samp{%}. This is the only way to represent a literal +@samp{%} in a terminal command with parameters. @samp{%%} does not +use up a parameter. + +@item %d +As in @code{printf}, output the next parameter in decimal. + +@item %2 +Like @samp{%02d} in @code{printf}: output the next parameter in +decimal, and always use at least two digits. + +@item %3 +Like @samp{%03d} in @code{printf}: output the next parameter in +decimal, and always use at least three digits. Note that @samp{%4} +and so on are @emph{not} defined. + +@item %. +Output the next parameter as a single character whose ASCII code is +the parameter value. Like @samp{%c} in @code{printf}. + +@item %+@var{char} +Add the next parameter to the character @var{char}, and output the +resulting character. For example, @samp{%+ } represents 0 as a space, +1 as @samp{!}, etc. +@end table + +The following @samp{%}-sequences specify alteration of the parameters +(their values, or their order) rather than encoding a parameter for output. +They generate no output; they are used only for their side effects +on the parameters. Also, they do not advance the ``next parameter'' pointer +except as explicitly stated. Only @samp{%i}, @samp{%r} and @samp{%>} are +defined in standard Unix termcap. The others are GNU extensions.@refill + +@table @samp +@item %i +Increment the next two parameters. This is used for terminals that +expect cursor positions in origin 1. For example, @samp{%i%d,%d} would +output two parameters with @samp{1} for 0, @samp{2} for 1, etc. + +@item %r +Interchange the next two parameters. This is used for terminals whose +cursor positioning command expects the horizontal position first. + +@item %s +Skip the next parameter. Do not output anything. + +@item %b +Back up one parameter. The last parameter used will become once again +the next parameter to be output, and the next output command will use +it. Using @samp{%b} more than once, you can back up any number of +parameters, and you can refer to each parameter any number of times. + +@item %>@var{c1}@var{c2} +Conditionally increment the next parameter. Here @var{c1} and +@var{c2} are characters which stand for their ASCII codes as numbers. +If the next parameter is greater than the ASCII code of @var{c1}, the +ASCII code of @var{c2} is added to it.@refill + +@item %a @var{op} @var{type} @var{pos} +Perform arithmetic on the next parameter, do not use it up, and do not +output anything. Here @var{op} specifies the arithmetic operation, +while @var{type} and @var{pos} together specify the other operand. + +Spaces are used above to separate the operands for clarity; the spaces +don't appear in the data base, where this sequence is exactly five +characters long. + +The character @var{op} says what kind of arithmetic operation to +perform. It can be any of these characters: + +@table @samp +@item = +assign a value to the next parameter, ignoring its old value. +The new value comes from the other operand. + +@item + +add the other operand to the next parameter. + +@item - +subtract the other operand from the next parameter. + +@item * +multiply the next parameter by the other operand. + +@item / +divide the next parameter by the other operand. +@end table + +The ``other operand'' may be another parameter's value or a constant; +the character @var{type} says which. It can be: + +@table @samp +@item p +Use another parameter. The character @var{pos} says which +parameter to use. Subtract 64 from its ASCII code to get the +position of the desired parameter relative to this one. Thus, +the character @samp{A} as @var{pos} means the parameter after the +next one; the character @samp{?} means the parameter before the +next one. + +@item c +Use a constant value. The character @var{pos} specifies the +value of the constant. The 0200 bit is cleared out, so that 0200 +can be used to represent zero. +@end table +@end table + +The following @samp{%}-sequences are special purpose hacks to compensate +for the weird designs of obscure terminals. They modify the next parameter +or the next two parameters but do not generate output and do not use up any +parameters. @samp{%m} is a GNU extension; the others are defined in +standard Unix termcap. + +@table @samp +@item %n +Exclusive-or the next parameter with 0140, and likewise the parameter +after next. + +@item %m +Complement all the bits of the next parameter and the parameter after next. + +@item %B +Encode the next parameter in BCD. It alters the value of the +parameter by adding six times the quotient of the parameter by ten. +Here is a C statement that shows how the new value is computed: + +@example +@var{parm} = (@var{parm} / 10) * 16 + @var{parm} % 10; +@end example + +@item %D +Transform the next parameter as needed by Delta Data terminals. +This involves subtracting twice the remainder of the parameter by 16. + +@example +@var{parm} -= 2 * (@var{parm} % 16); +@end example +@end table + +@node Using Parameters, , Encode Parameters, Parameters +@subsection Sending Display Commands with Parameters + +The termcap library functions @code{tparam} and @code{tgoto} serve as the +analog of @code{printf} for terminal string parameters. The newer function +@code{tparam} is a GNU extension, more general but missing from Unix +termcap. The original parameter-encoding function is @code{tgoto}, which +is preferable for cursor motion. + +@menu +* tparam:: The general case, for GNU termcap only. +* tgoto:: The special case of cursor motion. +@end menu + +@node tparam, tgoto, , Using Parameters +@subsubsection @code{tparam} + +@findex tparam +The function @code{tparam} can encode display commands with any number of +parameters and allows you to specify the buffer space. It is the preferred +function for encoding parameters for all but the @samp{cm} capability. Its +ANSI C declaration is as follows: + +@smallexample +char *tparam (char *@var{ctlstring}, char *@var{buffer}, int @var{size}, int @var{parm1},...) +@end smallexample + +The arguments are a control string @var{ctlstring} (the value of a terminal +capability, presumably), an output buffer @var{buffer} and @var{size}, and +any number of integer parameters to be encoded. The effect of +@code{tparam} is to copy the control string into the buffer, encoding +parameters according to the @samp{%} sequences in the control string. + +You describe the output buffer by its address, @var{buffer}, and its size +in bytes, @var{size}. If the buffer is not big enough for the data to be +stored in it, @code{tparam} calls @code{malloc} to get a larger buffer. In +either case, @code{tparam} returns the address of the buffer it ultimately +uses. If the value equals @var{buffer}, your original buffer was used. +Otherwise, a new buffer was allocated, and you must free it after you are +done with printing the results. If you pass zero for @var{size} and +@var{buffer}, @code{tparam} always allocates the space with @code{malloc}. + +All capabilities that require parameters also have the ability to specify +padding, so you should use @code{tputs} to output the string produced by +@code{tparam}. @xref{Padding}. Here is an example. + +@example +@{ +char *buf; +char buffer[40]; + +buf = tparam (command, buffer, 40, parm); +tputs (buf, 1, fputchar); +if (buf != buffer) +free (buf); +@} +@end example + +If a parameter whose value is zero is encoded with @samp{%.}-style +encoding, the result is a null character, which will confuse @code{tputs}. +This would be a serious problem, but luckily @samp{%.} encoding is used +only by a few old models of terminal, and only for the @samp{cm} +capability. To solve the problem, use @code{tgoto} rather than +@code{tparam} to encode the @samp{cm} capability.@refill + +@node tgoto, , tparam, Using Parameters +@subsubsection @code{tgoto} + +@findex tgoto +The special case of cursor motion is handled by @code{tgoto}. There +are two reasons why you might choose to use @code{tgoto}: + +@itemize @bullet +@item +For Unix compatibility, because Unix termcap does not have @code{tparam}. + +@item +For the @samp{cm} capability, since @code{tgoto} has a special feature +to avoid problems with null characters, tabs and newlines on certain old +terminal types that use @samp{%.} encoding for that capability. +@end itemize + +Here is how @code{tgoto} might be declared in ANSI C: + +@example +char *tgoto (char *@var{cstring}, int @var{hpos}, int @var{vpos}) +@end example + +There are three arguments, the terminal description's @samp{cm} string and +the two cursor position numbers; @code{tgoto} computes the parametrized +string in an internal static buffer and returns the address of that buffer. +The next time you use @code{tgoto} the same buffer will be reused. + +@vindex UP +@vindex BC +Parameters encoded with @samp{%.} encoding can generate null characters, +tabs or newlines. These might cause trouble: the null character because +@code{tputs} would think that was the end of the string, the tab because +the kernel or other software might expand it into spaces, and the newline +becaue the kernel might add a carriage-return, or padding characters +normally used for a newline. To prevent such problems, @code{tgoto} is +careful to avoid these characters. Here is how this works: if the target +cursor position value is such as to cause a problem (that is to say, zero, +nine or ten), @code{tgoto} increments it by one, then compensates by +appending a string to move the cursor back or up one position. + +The compensation strings to use for moving back or up are found in global +variables named @code{BC} and @code{UP}. These are actual external C +variables with upper case names; they are declared @code{char *}. It is up +to you to store suitable values in them, normally obtained from the +@samp{le} and @samp{up} terminal capabilities in the terminal description +with @code{tgetstr}. Alternatively, if these two variables are both zero, +the feature of avoiding nulls, tabs and newlines is turned off. + +It is safe to use @code{tgoto} for commands other than @samp{cm} only if +you have stored zero in @code{BC} and @code{UP}. + +Note that @code{tgoto} reverses the order of its operands: the horizontal +position comes before the vertical position in the arguments to +@code{tgoto}, even though the vertical position comes before the horizontal +in the parameters of the @samp{cm} string. If you use @code{tgoto} with a +command such as @samp{AL} that takes one parameter, you must pass the +parameter to @code{tgoto} as the ``vertical position''.@refill + +@node Data Base, Capabilities, Library, Top +@chapter The Format of the Data Base + +The termcap data base of terminal descriptions is stored in the file +@file{/etc/termcap}. It contains terminal descriptions, blank lines, and +comments. + +A terminal description starts with one or more names for the terminal type. +The information in the description is a series of @dfn{capability names} +and values. The capability names have standard meanings +(@pxref{Capabilities}) and their values describe the terminal. + +@menu +* Format:: Overall format of a terminal description. +* Capability Format:: Format of capabilities within a description. +* Naming:: Naming conventions for terminal types. +* Inheriting:: Inheriting part of a description from +a related terminal type. +* Changing:: When changes in the data base take effect. +@end menu + +@node Format, Capability Format, , Data Base +@section Terminal Description Format +@cindex description format + +Aside from comments (lines starting with @samp{#}, which are ignored), each +nonblank line in the termcap data base is a terminal description. +A terminal description is nominally a single line, but it can be split +into multiple lines by inserting the two characters @samp{\ newline}. +This sequence is ignored wherever it appears in a description. + +The preferred way to split the description is between capabilities: insert +the four characters @samp{: \ newline tab} immediately before any colon. +This allows each sub-line to start with some indentation. This works +because, after the @samp{\ newline} are ignored, the result is @samp{: tab +:}; the first colon ends the preceding capability and the second colon +starts the next capability. If you split with @samp{\ newline} alone, you +may not add any indentation after them. + +Here is a real example of a terminal description: + +@example +dw|vt52|DEC vt52:\ + :cr=^M:do=^J:nl=^J:bl=^G:\ + :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\ + :cm=\EY%+ %+ :co#80:li#24:\ + :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\ + :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H: +@end example + +Each terminal description begins with several names for the terminal type. +The names are separated by @samp{|} characters, and a colon ends the last +name. The first name should be two characters long; it exists only for the +sake of very old Unix systems and is never used in modern systems. The +last name should be a fully verbose name such as ``DEC vt52'' or ``Ann +Arbor Ambassador with 48 lines''. The other names should include whatever +the user ought to be able to specify to get this terminal type, such as +@samp{vt52} or @samp{aaa-48}. @xref{Naming}, for information on how to +choose terminal type names. + +After the terminal type names come the terminal capabilities, separated by +colons and with a colon after the last one. Each capability has a +two-letter name, such as @samp{cm} for ``cursor motion string'' or @samp{li} +for ``number of display lines''. + +@node Capability Format, Naming, Format, Data Base +@section Writing the Capabilities + +There are three kinds of capabilities: flags, numbers, and strings. Each +kind has its own way of being written in the description. Each defined +capability has by convention a particular kind of value; for example, +@samp{li} always has a numeric value and @samp{cm} always a string value. + +A flag capability is thought of as having a boolean value: the value is +true if the capability is present, false if not. When the capability is +present, just write its name between two colons. + +A numeric capability has a value which is a nonnegative number. Write the +capability name, a @samp{#}, and the number, between two colons. For +example, @samp{@dots{}:li#48:@dots{}} is how you specify the @samp{li} +capability for 48 lines.@refill + +A string-valued capability has a value which is a sequence of characters. +Usually these are the characters used to perform some display operation. +Write the capability name, a @samp{=}, and the characters of the value, +between two colons. For example, @samp{@dots{}:cm=\E[%i%d;%dH:@dots{}} is +how the cursor motion command for a standard ANSI terminal would be +specified.@refill + +Special characters in the string value can be expressed using +@samp{\}-escape sequences as in C; in addition, @samp{\E} stands for +@key{ESC}. @samp{^} is also a kind of escape character; @samp{^} followed +by @var{char} stands for the control-equivalent of @var{char}. Thus, +@samp{^a} stands for the character control-a, just like @samp{\001}. +@samp{\} and @samp{^} themselves can be represented as @samp{\\} and +@samp{\^}.@refill + +To include a colon in the string, you must write @samp{\072}. You might +ask, ``Why can't @samp{\:} be used to represent a colon?'' The reason is +that the interrogation functions do not count slashes while looking for a +capability. Even if @samp{:ce=ab\:cd:} were interpreted as giving the +@samp{ce} capability the value @samp{ab:cd}, it would also appear to define +@samp{cd} as a flag. + +The string value will often contain digits at the front to specify padding +(@pxref{Padding}) and/or @samp{%}-sequences within to specify how to encode +parameters (@pxref{Parameters}). Although these things are not to be +output literally to the terminal, they are considered part of the value of +the capability. They are special only when the string value is processed +by @code{tputs}, @code{tparam} or @code{tgoto}. By contrast, @samp{\} and +@samp{^} are considered part of the syntax for specifying the characters +in the string. + +Let's look at the VT52 example again: + +@example +dw|vt52|DEC vt52:\ + :cr=^M:do=^J:nl=^J:bl=^G:\ + :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\ + :cm=\EY%+ %+ :co#80:li#24:\ + :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\ + :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H: +@end example + +Here we see the numeric-valued capabilities @samp{co} and @samp{li}, the +flags @samp{bs} and @samp{pt}, and many string-valued capabilities. Most +of the strings start with @key{ESC} represented as @samp{\E}. The rest +contain control characters represented using @samp{^}. The meanings of the +individual capabilities are defined elsewhere (@pxref{Capabilities}). + +@node Naming, Inheriting, Capability Format, Data Base +@section Terminal Type Name Conventions +@cindex names of terminal types + +There are conventions for choosing names of terminal types. For one thing, +all letters should be in lower case. The terminal type for a terminal in +its most usual or most fundamental mode of operation should not have a +hyphen in it. + +If the same terminal has other modes of operation which require +different terminal descriptions, these variant descriptions are given +names made by adding suffixes with hyphens. Such alternate descriptions +are used for two reasons: + +@itemize @bullet +@item +When the terminal has a switch that changes its behavior. Since the +computer cannot tell how the switch is set, the user must tell the +computer by choosing the appropriate terminal type name. + +@cindex wrapping +For example, the VT-100 has a setup flag that controls whether the +cursor wraps at the right margin. If this flag is set to ``wrap'', +you must use the terminal type @samp{vt100-am}. Otherwise you must +use @samp{vt100-nam}. Plain @samp{vt100} is defined as a synonym for +either @samp{vt100-am} or @samp{vt100-nam} depending on the +preferences of the local site.@refill + +The standard suffix @samp{-am} stands for ``automatic margins''. + +@item +To give the user a choice in how to use the terminal. This is done +when the terminal has a switch that the computer normally controls. + +@cindex screen size +For example, the Ann Arbor Ambassador can be configured with many +screen sizes ranging from 20 to 60 lines. Fewer lines make bigger +characters but more lines let you see more of what you are editing. +As a result, users have different preferences. Therefore, termcap +provides terminal types for many screen sizes. If you choose type +@samp{aaa-30}, the terminal will be configured to use 30 lines; if you +choose @samp{aaa-48}, 48 lines will be used, and so on. +@end itemize + +Here is a list of standard suffixes and their conventional meanings: + +@table @samp +@item -w +Short for ``wide''. This is a mode that gives the terminal more +columns than usual. This is normally a user option. + +@item -am +``Automatic margins''. This is an alternate description for use when +the terminal's margin-wrap switch is on; it contains the @samp{am} +flag. The implication is that normally the switch is off and the +usual description for the terminal says that the switch is off. + +@item -nam +``No automatic margins''. The opposite of @samp{-am}, this names an +alternative description which lacks the @samp{am} flag. This implies +that the terminal is normally operated with the margin-wrap switch +turned on, and the normal description of the terminal says so. + +@item -na +``No arrows''. This terminal description initializes the terminal to +keep its arrow keys in local mode. This is a user option. + +@item -rv +``Reverse video''. This terminal description causes text output for +normal video to appear as reverse, and text output for reverse video +to come out as normal. Often this description differs from the usual +one by interchanging the two strings which turn reverse video on and +off.@refill + +This is a user option; you can choose either the ``reverse video'' +variant terminal type or the normal terminal type, and termcap will +obey. + +@item -s +``Status''. Says to enable use of a status line which ordinary output +does not touch (@pxref{Status Line}). + +Some terminals have a special line that is used only as a status line. +For these terminals, there is no need for an @samp{-s} variant; the +status line commands should be defined by default. On other +terminals, enabling a status line means removing one screen line from +ordinary use and reducing the effective screen height. For these +terminals, the user can choose the @samp{-s} variant type to request +use of a status line. + +@item -@var{nlines} +Says to operate with @var{nlines} lines on the screen, for terminals +such as the Ambassador which provide this as an option. Normally this +is a user option; by choosing the terminal type, you control how many +lines termcap will use. + +@item -@var{npages}p +Says that the terminal has @var{npages} pages worth of screen memory, +for terminals where this is a hardware option. + +@item -unk +Says that description is not for direct use, but only for reference in +@samp{tc} capabilities. Such a description is a kind of subroutine, +because it describes the common characteristics of several variant +descriptions that would use other suffixes in place of @samp{-unk}. +@end table + +@node Inheriting, Changing, Naming, Data Base +@section Inheriting from Related Descriptions + +@cindex inheritance +When two terminal descriptions are similar, their identical parts do not +need to be given twice. Instead, one of the two can be defined in terms of +the other, using the @samp{tc} capability. We say that one description +@dfn{refers to} the other, or @dfn{inherits from} the other. + +The @samp{tc} capability must be the last one in the terminal description, +and its value is a string which is the name of another terminal type which +is referred to. For example, + +@example +N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\ + :ti=\E[2J\E[30;0;0;30p:\ + :te=\E[60;0;0;30p\E[30;1H\E[J:\ + :li#30:tc=aaa-unk: +@end example + +@noindent +defines the terminal type @samp{aaa-30} (also known as plain @samp{aaa}) in +terms of @samp{aaa-unk}, which defines everything about the Ambassador that +is independent of screen height. The types @samp{aaa-36}, @samp{aaa-48} +and so on for other screen heights are likewise defined to inherit from +@samp{aaa-unk}. + +The capabilities overridden by @samp{aaa-30} include @samp{li}, which says +how many lines there are, and @samp{ti} and @samp{te}, which configure the +terminal to use that many lines. + +The effective terminal description for type @samp{aaa} consists of the text +shown above followed by the text of the description of @samp{aaa-unk}. The +@samp{tc} capability is handled automatically by @code{tgetent}, which +finds the description thus referenced and combines the two descriptions +(@pxref{Find}). Therefore, only the implementor of the terminal +descriptions needs to think about using @samp{tc}. Users and application +programmers do not need to be concerned with it. + +Since the reference terminal description is used last, capabilities +specified in the referring description override any specifications of the +same capabilities in the reference description. + +The referring description can cancel out a capability without specifying +any new value for it by means of a special trick. Write the capability in +the referring description, with the character @samp{@@} after the capability +name, as follows: + +@smallexample +NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\ + :am@@:tc=aaa-30: +@end smallexample + +@node Changing, , Inheriting, Data Base +@section When Changes in the Data Base Take Effect + +Each application program must read the terminal description from the +data base, so a change in the data base is effective for all jobs started +after the change is made. + +The change will usually have no effect on a job that have been in existence +since before the change. The program probably read the terminal description +once, when it was started, and is continuing to use what it read then. +If the program does not have a feature for reexamining the data base, then +you will need to run it again (probably killing the old job). + +If the description in use is coming from the @code{TERMCAP} environment +variable, then the data base file is effectively overridden, and changes in +it will have no effect until you change the @code{TERMCAP} variable as +well. For example, some users' @file{.login} files automatically copy the +terminal description into @code{TERMCAP} to speed startup of applications. +If you have done this, you will need to change the @code{TERMCAP} variable +to make the changed data base take effect. + +@node Capabilities, Summary, Data Base, Top +@chapter Definitions of the Terminal Capabilities + +This section is divided into many subsections, each for one aspect of +use of display terminals. For writing a display program, you usually need +only check the subsections for the operations you want to use. For writing +a terminal description, you must read each subsection and fill in the +capabilities described there. + +String capabilities that are display commands may require numeric +parameters (@pxref{Parameters}). Most such capabilities do not use +parameters. When a capability requires parameters, this is explicitly +stated at the beginning of its definition. In simple cases, the first or +second sentence of the definition mentions all the parameters, in the order +they should be given, using a name +@iftex +in italics +@end iftex +@ifinfo +in upper case +@end ifinfo +for each one. For example, the @samp{rp} capability is a command that +requires two parameters; its definition begins as follows: + +@quotation +String of commands to output a graphic character @var{c}, repeated @var{n} +times. +@end quotation + +In complex cases or when there are many parameters, they are described +explicitly. + +When a capability is described as obsolete, this means that programs should +not be written to look for it, but terminal descriptions should still be +written to provide it. + +When a capability is described as very obsolete, this means that it should +be omitted from terminal descriptions as well. + +@menu +* Basic:: Basic characteristics. +* Screen Size:: Screen size, and what happens when it changes. +* Cursor Motion:: Various ways to move the cursor. +* Wrapping:: What happens if you write a character in the last column. +* Scrolling:: Pushing text up and down on the screen. +* Windows:: Limiting the part of the window that output affects. +* Clearing:: Erasing one or many lines. +* Insdel Line:: Making new blank lines in mid-screen; deleting lines. +* Insdel Char:: Inserting and deleting characters within a line. +* Standout:: Highlighting some of the text. +* Underlining:: Underlining some of the text. +* Cursor Visibility:: Making the cursor more or less easy to spot. +* Bell:: Attracts user's attention; not localized on the screen. +* Keypad:: Recognizing when function keys or arrows are typed. +* Meta Key:: @key{META} acts like an extra shift key. +* Initialization:: Commands used to initialize or reset the terminal. +* Pad Specs:: Info for the kernel on how much padding is needed. +* Status Line:: A status line displays ``background'' information. +* Half-Line:: Moving by half-lines, for superscripts and subscripts. +* Printer:: Controlling auxiliary printers of display terminals. +@end menu + +@node Basic, Screen Size, , Capabilities +@section Basic Characteristics + +This section documents the capabilities that describe the basic and +nature of the terminal, and also those that are relevant to the output +of graphic characters. + +@table @samp +@item os +@kindex os +@cindex overstrike +Flag whose presence means that the terminal can overstrike. This +means that outputting a graphic character does not erase whatever was +present in the same character position before. The terminals that can +overstrike include printing terminals, storage tubes (all obsolete +nowadays), and many bit-map displays. + +@item eo +@kindex eo +Flag whose presence means that outputting a space erases a character +position even if the terminal supports overstriking. If this flag is +not present and overstriking is supported, output of a space has no +effect except to move the cursor. + +(On terminals that do not support overstriking, you can always assume +that outputting a space at a position erases whatever character was +previously displayed there.) + +@item gn +@kindex gn +@cindex generic terminal type +Flag whose presence means that this terminal type is a generic type +which does not really describe any particular terminal. Generic types +are intended for use as the default type assigned when the user +connects to the system, with the intention that the user should +specify what type he really has. One example of a generic type +is the type @samp{network}. + +Since the generic type cannot say how to do anything interesting with +the terminal, termcap-using programs will always find that the +terminal is too weak to be supported if the user has failed to specify +a real terminal type in place of the generic one. The @samp{gn} flag +directs these programs to use a different error message: ``You have +not specified your real terminal type'', rather than ``Your terminal +is not powerful enough to be used''. + +@item hc +@kindex hc +Flag whose presence means this is a hardcopy terminal. + +@item rp +@kindex rp +@cindex repeat output +String of commands to output a graphic character @var{c}, repeated @var{n} +times. The first parameter value is the ASCII code for the desired +character, and the second parameter is the number of times to repeat the +character. Often this command requires padding proportional to the +number of times the character is repeated. This effect can be had by +using parameter arithmetic with @samp{%}-sequences to compute the +amount of padding, then generating the result as a number at the front +of the string so that @code{tputs} will treat it as padding. + +@item hz +@kindex hz +Flag whose presence means that the ASCII character @samp{~} cannot be +output on this terminal because it is used for display commands. + +Programs handle this flag by checking all text to be output and +replacing each @samp{~} with some other character(s). If this is not +done, the screen will be thoroughly garbled. + +The old Hazeltine terminals that required such treatment are probably +very rare today, so you might as well not bother to support this flag. + +@item CC +@kindex CC +@cindex command character +String whose presence means the terminal has a settable command +character. The value of the string is the default command character +(which is usually @key{ESC}). + +All the strings of commands in the terminal description should be +written to use the default command character. If you are writing an +application program that changes the command character, use the +@samp{CC} capability to figure out how to translate all the display +commands to work with the new command character. + +Most programs have no reason to look at the @samp{CC} capability. + +@item xb +@kindex xb +@cindex Superbee +Flag whose presence identifies Superbee terminals which are unable to +transmit the characters @key{ESC} and @kbd{Control-C}. Programs which +support this flag are supposed to check the input for the code sequences +sent by the @key{F1} and @key{F2} keys, and pretend that @key{ESC} +or @kbd{Control-C} (respectively) had been read. But this flag is +obsolete, and not worth supporting. +@end table + +@node Screen Size, Cursor Motion, Basic, Capabilities +@section Screen Size +@cindex screen size + +A terminal description has two capabilities, @samp{co} and @samp{li}, +that describe the screen size in columns and lines. But there is more +to the question of screen size than this. + +On some operating systems the ``screen'' is really a window and the +effective width can vary. On some of these systems, @code{tgetnum} +uses the actual width of the window to decide what value to return for +the @samp{co} capability, overriding what is actually written in the +terminal description. On other systems, it is up to the application +program to check the actual window width using a system call. For +example, on BSD 4.3 systems, the system call @code{ioctl} with code +@code{TIOCGWINSZ} will tell you the current screen size. + +On all window systems, termcap is powerless to advise the application +program if the user resizes the window. Application programs must +deal with this possibility in a system-dependent fashion. On some +systems the C shell handles part of the problem by detecting changes +in window size and setting the @code{TERMCAP} environment variable +appropriately. This takes care of application programs that are +started subsequently. It does not help application programs already +running. + +On some systems, including BSD 4.3, all programs using a terminal get +a signal named @code{SIGWINCH} whenever the screen size changes. +Programs that use termcap should handle this signal by using +@code{ioctl TIOCGWINSZ} to learn the new screen size. + +@table @samp +@item co +@kindex co +@cindex screen size +Numeric value, the width of the screen in character positions. Even +hardcopy terminals normally have a @samp{co} capability. + +@item li +@kindex li +Numeric value, the height of the screen in lines. +@end table + +@node Cursor Motion, Wrapping, Screen Size, Capabilities +@section Cursor Motion +@cindex cursor motion + +Termcap assumes that the terminal has a @dfn{cursor}, a spot on the screen +where a visible mark is displayed, and that most display commands take +effect at the position of the cursor. It follows that moving the cursor +to a specified location is very important. + +There are many terminal capabilities for different cursor motion +operations. A terminal description should define as many as possible, but +most programs do not need to use most of them. One capability, @samp{cm}, +moves the cursor to an arbitrary place on the screen; this by itself is +sufficient for any application as long as there is no need to support +hardcopy terminals or certain old, weak displays that have only relative +motion commands. Use of other cursor motion capabilities is an +optimization, enabling the program to output fewer characters in some +common cases. + +If you plan to use the relative cursor motion commands in an application +program, you must know what the starting cursor position is. To do this, +you must keep track of the cursor position and update the records each +time anything is output to the terminal, including graphic characters. +In addition, it is necessary to know whether the terminal wraps after +writing in the rightmost column. @xref{Wrapping}. + +One other motion capability needs special mention: @samp{nw} moves the +cursor to the beginning of the following line, perhaps clearing all the +starting line after the cursor, or perhaps not clearing at all. This +capability is a least common denominator that is probably supported even by +terminals that cannot do most other things such as @samp{cm} or @samp{do}. +Even hardcopy terminals can support @samp{nw}. + +@table @asis +@item @samp{cm} +@kindex cm +String of commands to position the cursor at line @var{l}, column @var{c}. +Both parameters are origin-zero, and are defined relative to the +screen, not relative to display memory. + +All display terminals except a few very obsolete ones support @samp{cm}, +so it is acceptable for an application program to refuse to operate on +terminals lacking @samp{cm}. + +@item @samp{ho} +@kindex ho +@cindex home position +String of commands to move the cursor to the upper left corner of the +screen (this position is called the @dfn{home position}). In +terminals where the upper left corner of the screen is not the same as +the beginning of display memory, this command must go to the upper +left corner of the screen, not the beginning of display memory. + +Every display terminal supports this capability, and many application +programs refuse to operate if the @samp{ho} capability is missing. + +@item @samp{ll} +@kindex ll +String of commands to move the cursor to the lower left corner of the +screen. On some terminals, moving up from home position does this, +but programs should never assume that will work. Just output the +@samp{ll} string (if it is provided); if moving to home position and +then moving up is the best way to get there, the @samp{ll} command +will do that. + +@item @samp{cr} +@kindex cr +String of commands to move the cursor to the beginning of the line it +is on. If this capability is not specified, many programs assume +they can use the ASCII carriage return character for this. + +@item @samp{le} +@kindex le +String of commands to move the cursor left one column. Unless the +@samp{bw} flag capability is specified, the effect is undefined if the +cursor is at the left margin; do not use this command there. If +@samp{bw} is present, this command may be used at the left margin, and +it wraps the cursor to the last column of the preceding line. + +@item @samp{nd} +@kindex nd +String of commands to move the cursor right one column. The effect is +undefined if the cursor is at the right margin; do not use this +command there, not even if @samp{am} is present. + +@item @samp{up} +@kindex up +String of commands to move the cursor vertically up one line. The +effect of sending this string when on the top line is undefined; +programs should never use it that way. + +@item @samp{do} +@kindex do +String of commands to move the cursor vertically down one line. The +effect of sending this string when on the bottom line is undefined; +programs should never use it that way. + +Some programs do use @samp{do} to scroll up one line if used at the +bottom line, if @samp{sf} is not defined but @samp{sr} is. This is +only to compensate for certain old, incorrect terminal descriptions. +(In principle this might actually lead to incorrect behavior on other +terminals, but that seems to happen rarely if ever.) But the proper +solution is that the terminal description should define @samp{sf} as +well as @samp{do} if the command is suitable for scrolling. + +The original idea was that this string would not contain a newline +character and therefore could be used without disabling the kernel's +usual habit of converting of newline into a carriage-return newline +sequence. But many terminal descriptions do use newline in the +@samp{do} string, so this is not possible; a program which sends the +@samp{do} string must disable output conversion in the kernel +(@pxref{Initialize}). + +@item @samp{bw} +@kindex bw +Flag whose presence says that @samp{le} may be used in column zero +to move to the last column of the preceding line. If this flag +is not present, @samp{le} should not be used in column zero. + +@item @samp{nw} +@kindex nw +String of commands to move the cursor to start of next line, possibly +clearing rest of line (following the cursor) before moving. + +@item @samp{DO}, @samp{UP}, @samp{LE}, @samp{RI} +@kindex DO +@kindex LE +@kindex RI +@kindex UP +Strings of commands to move the cursor @var{n} lines down vertically, +up vertically, or @var{n} columns left or right. Do not attempt to +move past any edge of the screen with these commands; the effect of +trying that is undefined. Only a few terminal descriptions provide +these commands, and most programs do not use them. + +@item @samp{CM} +@kindex CM +String of commands to position the cursor at line @var{l}, column +@var{c}, relative to display memory. Both parameters are origin-zero. +This capability is present only in terminals where there is a +difference between screen-relative and memory-relative addressing, and +not even in all such terminals. + +@item @samp{ch} +@kindex ch +String of commands to position the cursor at column @var{c} in the +same line it is on. This is a special case of @samp{cm} in which the +vertical position is not changed. The @samp{ch} capability is +provided only when it is faster to output than @samp{cm} would be in +this special case. Programs should not assume most display terminals +have @samp{ch}. + +@item @samp{cv} +@kindex cv +String of commands to position the cursor at line @var{l} in the same +column. This is a special case of @samp{cm} in which the horizontal +position is not changed. The @samp{cv} capability is provided only +when it is faster to output than @samp{cm} would be in this special +case. Programs should not assume most display terminals have +@samp{cv}. + +@item @samp{sc} +@kindex sc +String of commands to make the terminal save the current cursor +position. Only the last saved position can be used. If this +capability is present, @samp{rc} should be provided also. Most +terminals have neither. + +@item @samp{rc} +@kindex rc +String of commands to make the terminal restore the last saved cursor +position. If this capability is present, @samp{sc} should be provided +also. Most terminals have neither. + +@item @samp{ff} +@kindex ff +String of commands to advance to the next page, for a hardcopy +terminal. + +@item @samp{ta} +@kindex ta +String of commands to move the cursor right to the next hardware tab +stop column. Missing if the terminal does not have any kind of +hardware tabs. Do not send this command if the kernel's terminal +modes say that the kernel is expanding tabs into spaces. + +@item @samp{bt} +@kindex bt +String of commands to move the cursor left to the previous hardware +tab stop column. Missing if the terminal has no such ability; many +terminals do not. Do not send this command if the kernel's terminal +modes say that the kernel is expanding tabs into spaces. +@end table + +The following obsolete capabilities should be included in terminal +descriptions when appropriate, but should not be looked at by new programs. + +@table @samp +@item nc +@kindex nc +Flag whose presence means the terminal does not support the ASCII +carriage return character as @samp{cr}. This flag is needed because +old programs assume, when the @samp{cr} capability is missing, that +ASCII carriage return can be used for the purpose. We use @samp{nc} +to tell the old programs that carriage return may not be used. + +New programs should not assume any default for @samp{cr}, so they need +not look at @samp{nc}. However, descriptions should contain @samp{nc} +whenever they do not contain @samp{cr}. + +@item xt +@kindex xt +Flag whose presence means that the ASCII tab character may not be used +for cursor motion. This flag exists because old programs assume, when +the @samp{ta} capability is missing, that ASCII tab can be used for +the purpose. We use @samp{xt} to tell the old programs not to use tab. + +New programs should not assume any default for @samp{ta}, so they need +not look at @samp{xt} in connection with cursor motion. Note that +@samp{xt} also has implications for standout mode (@pxref{Standout}). +It is obsolete in regard to cursor motion but not in regard to +standout. + +In fact, @samp{xt} means that the terminal is a Teleray 1061. + +@item bc +@kindex bc +Very obsolete alternative name for the @samp{le} capability. + +@item bs +@kindex bs +Flag whose presence means that the ASCII character backspace may be +used to move the cursor left. Obsolete; look at @samp{le} instead. + +@item nl +@kindex nl +Obsolete capability which is a string that can either be used to move +the cursor down or to scroll. The same string must scroll when used +on the bottom line and move the cursor when used on any other line. +New programs should use @samp{do} or @samp{sf}, and ignore @samp{nl}. + +If there is no @samp{nl} capability, some old programs assume they can +use the newline character for this purpose. These programs follow a +bad practice, but because they exist, it is still desirable to define +the @samp{nl} capability in a terminal description if the best way to +move down is @emph{not} a newline. +@end table + +@node Wrapping, Scrolling, Cursor Motion, Capabilities +@section Wrapping +@cindex wrapping + +@dfn{Wrapping} means moving the cursor from the right margin to the left +margin of the following line. Some terminals wrap automatically when a +graphic character is output in the last column, while others do not. Most +application programs that use termcap need to know whether the terminal +wraps. There are two special flag capabilities to describe what the +terminal does when a graphic character is output in the last column. + +@table @samp +@item am +@kindex am +Flag whose presence means that writing a character in the last column +causes the cursor to wrap to the beginning of the next line. + +If @samp{am} is not present, writing in the last column leaves the +cursor at the place where the character was written. + +Writing in the last column of the last line should be avoided on +terminals with @samp{am}, as it may or may not cause scrolling to +occur (@pxref{Scrolling}). Scrolling is surely not what you would +intend. + +If your program needs to check the @samp{am} flag, then it also needs +to check the @samp{xn} flag which indicates that wrapping happens in a +strange way. Many common terminals have the @samp{xn} flag. + +@item xn +@kindex xn +Flag whose presence means that the cursor wraps in a strange way. At +least two distinct kinds of strange behavior are known; the termcap +data base does not contain anything to distinguish the two. + +On Concept-100 terminals, output in the last column wraps the cursor +almost like an ordinary @samp{am} terminal. But if the next thing +output is a newline, it is ignored. + +DEC VT-100 terminals (when the wrap switch is on) do a different +strange thing: the cursor wraps only if the next thing output is +another graphic character. In fact, the wrap occurs when the +following graphic character is received by the terminal, before the +character is placed on the screen. + +On both of these terminals, after writing in the last column a +following graphic character will be displayed in the first column of +the following line. But the effect of relative cursor motion +characters such as newline or backspace at such a time depends on the +terminal. The effect of erase or scrolling commands also depends on +the terminal. You can't assume anything about what they will do on a +terminal that has @samp{xn}. So, to be safe, you should never do +these things at such a time on such a terminal. + +To be sure of reliable results on a terminal which has the @samp{xn} +flag, output a @samp{cm} absolute positioning command after writing in +the last column. Another safe thing to do is to output carriage-return +newline, which will leave the cursor at the beginning of the following +line. + +@item LP +@kindex LP +Flag whose presence means that it is safe to write in the last column of +the last line without worrying about undesired scrolling. @samp{LP} +indicates the DEC flavor of @samp{xn} strangeness. +@end table + +@node Scrolling, Windows, Wrapping, Capabilities +@section Scrolling +@cindex scrolling + +@dfn{Scrolling} means moving the contents of the screen up or down one or +more lines. Moving the contents up is @dfn{forward scrolling}; moving them +down is @dfn{reverse scrolling}. + +Scrolling happens after each line of output during ordinary output on most +display terminals. But in an application program that uses termcap for +random-access output, scrolling happens only when explicitly requested with +the commands in this section. + +Some terminals have a @dfn{scroll region} feature. This lets you limit +the effect of scrolling to a specified range of lines. Lines outside the +range are unaffected when scrolling happens. The scroll region feature +is available if either @samp{cs} or @samp{cS} is present. + +@table @samp +@item sf +@kindex sf +String of commands to scroll the screen one line up, assuming it is +output with the cursor at the beginning of the bottom line. + +@item sr +@kindex sr +String of commands to scroll the screen one line down, assuming it is +output with the cursor at the beginning of the top line. + +@item do +A few programs will try to use @samp{do} to do the work of @samp{sf}. +This is not really correct---it is an attempt to compensate for the +absence of a @samp{sf} command in some old terminal descriptions. + +Since these terminal descriptions do define @samp{sr}, perhaps at one +time the definition of @samp{do} was different and it could be used +for scrolling as well. But it isn't desirable to combine these two +functions in one capability, since scrolling often requires more +padding than simply moving the cursor down. Defining @samp{sf} and +@samp{do} separately allows you to specify the padding properly. +Also, all sources agree that @samp{do} should not be relied on to do +scrolling. + +So the best approach is to add @samp{sf} capabilities to the +descriptions of these terminals, copying the definition of @samp{do} +if that does scroll. + +@item SF +@kindex SF +String of commands to scroll the screen @var{n} lines up, assuming it +is output with the cursor at the beginning of the bottom line. + +@item SR +@kindex SR +String of commands to scroll the screen @var{n} lines down, assuming it +is output with the cursor at the beginning of the top line. + +@item cs +@kindex cs +String of commands to set the scroll region. This command takes two +parameters, @var{start} and @var{end}, which are the line numbers +(origin-zero) of the first line to include in the scroll region and of +the last line to include in it. When a scroll region is set, +scrolling is limited to the specified range of lines; lines outside +the range are not affected by scroll commands. + +Do not try to move the cursor outside the scroll region. The region +remains set until explicitly removed. To remove the scroll region, +use another @samp{cs} command specifying the full height of the +screen. + +The cursor position is undefined after the @samp{cs} command is set, +so position the cursor with @samp{cm} immediately afterward. + +@item cS +@kindex cS +String of commands to set the scroll region using parameters in +different form. The effect is the same as if @samp{cs} were used. +Four parameters are required: + +@enumerate +@item +Total number of lines on the screen. +@item +Number of lines above desired scroll region. +@item +Number of lines below (outside of) desired scroll region. +@item +Total number of lines on the screen, the same as the first parameter. +@end enumerate + +This capability is a GNU extension that was invented to allow the Ann +Arbor Ambassador's scroll-region command to be described; it could +also be done by putting non-Unix @samp{%}-sequences into a @samp{cs} +string, but that would have confused Unix programs that used the +@samp{cs} capability with the Unix termcap. Currently only GNU Emacs +uses the @samp{cS} capability. + +@item ns +@kindex ns +Flag which means that the terminal does not normally scroll for +ordinary sequential output. For modern terminals, this means that +outputting a newline in ordinary sequential output with the cursor on +the bottom line wraps to the top line. For some obsolete terminals, +other things may happen. + +The terminal may be able to scroll even if it does not normally do so. +If the @samp{sf} capability is provided, it can be used for scrolling +regardless of @samp{ns}. + +@item da +@kindex da +Flag whose presence means that lines scrolled up off the top of the +screen may come back if scrolling down is done subsequently. + +The @samp{da} and @samp{db} flags do not, strictly speaking, affect +how to scroll. But programs that scroll usually need to clear the +lines scrolled onto the screen, if these flags are present. + +@item db +@kindex db +Flag whose presence means that lines scrolled down off the bottom of +the screen may come back if scrolling up is done subsequently. + +@item lm +@kindex lm +Numeric value, the number of lines of display memory that the terminal +has. A value of zero means that the terminal has more display memory +than can fit on the screen, but no fixed number of lines. (The number +of lines may depend on the amount of text in each line.) +@end table + +Any terminal description that defines @samp{SF} should also define @samp{sf}; +likewise for @samp{SR} and @samp{sr}. However, many terminals can only +scroll by one line at a time, so it is common to find @samp{sf} and not +@samp{SF}, or @samp{sr} without @samp{SR}.@refill + +Therefore, all programs that use the scrolling facilities should be +prepared to work with @samp{sf} in the case that @samp{SF} is absent, and +likewise with @samp{sr}. On the other hand, an application program that +uses only @samp{sf} and not @samp{SF} is acceptable, though slow on some +terminals.@refill + +When outputting a scroll command with @code{tputs}, the @var{nlines} +argument should be the total number of lines in the portion of the screen +being scrolled. Very often these commands require padding proportional to +this number of lines. @xref{Padding}. + +@node Windows, Clearing, Scrolling, Capabilities +@section Windows +@cindex window + +A @dfn{window}, in termcap, is a rectangular portion of the screen to which +all display operations are restricted. Wrapping, clearing, scrolling, +insertion and deletion all operate as if the specified window were all the +screen there was. + +@table @samp +@item wi +@kindex wi +String of commands to set the terminal output screen window. +This string requires four parameters, all origin-zero: +@enumerate +@item +The first line to include in the window. +@item +The last line to include in the window. +@item +The first column to include in the window. +@item +The last column to include in the window. +@end enumerate +@end table + +Most terminals do not support windows. + +@node Clearing, Insdel Line, Windows, Capabilities +@section Clearing Parts of the Screen +@cindex erasing +@cindex clearing the screen + +There are several terminal capabilities for clearing parts of the screen +to blank. All display terminals support the @samp{cl} string, and most +display terminals support all of these capabilities. + +@table @samp +@item cl +@kindex cl +String of commands to clear the entire screen and position the cursor +at the upper left corner. + +@item cd +@kindex cd +String of commands to clear the line the cursor is on, and all the +lines below it, down to the bottom of the screen. This command string +should be used only with the cursor in column zero; their effect is +undefined if the cursor is elsewhere. + +@item ce +@kindex ce +String of commands to clear from the cursor to the end of the current +line. + +@item ec +@kindex ec +String of commands to clear @var{n} characters, starting with the +character that the cursor is on. This command string is expected to +leave the cursor position unchanged. The parameter @var{n} should never +be large enough to reach past the right margin; the effect of such a +large parameter would be undefined. +@end table + +Clear to end of line (@samp{ce}) is extremely important in programs that +maintain an updating display. Nearly all display terminals support this +operation, so it is acceptable for a an application program to refuse to +work if @samp{ce} is not present. However, if you do not want this +limitation, you can accomplish clearing to end of line by outputting spaces +until you reach the right margin. In order to do this, you must know the +current horizontal position. Also, this technique assumes that writing a +space will erase. But this happens to be true on all the display terminals +that fail to support @samp{ce}. + +@node Insdel Line, Insdel Char, Clearing, Capabilities +@section Insert/Delete Line + +@cindex insert line +@cindex delete line +@dfn{Inserting a line} means creating a blank line in the middle +of the screen, and pushing the existing lines of text apart. In fact, +the lines above the insertion point do not change, while the lines below +move down, and one is normally lost at the bottom of the screen. + +@dfn{Deleting a line} means causing the line to disappear from the screen, +closing up the gap by moving the lines below it upward. A new line +appears at the bottom of the screen. Usually this line is blank, but +on terminals with the @samp{db} flag it may be a line previously moved +off the screen bottom by scrolling or line insertion. + +Insertion and deletion of lines is useful in programs that maintain an +updating display some parts of which may get longer or shorter. They are +also useful in editors for scrolling parts of the screen, and for +redisplaying after lines of text are killed or inserted. + +Many terminals provide commands to insert or delete a single line at the +cursor position. Some provide the ability to insert or delete several +lines with one command, using the number of lines to insert or delete as a +parameter. Always move the cursor to column zero before using any of +these commands. + +@table @samp +@item al +@kindex al +String of commands to insert a blank line before the line the cursor +is on. The existing line, and all lines below it, are moved down. +The last line in the screen (or in the scroll region, if one is set) +disappears and in most circumstances is discarded. It may not be +discarded if the @samp{db} is present (@pxref{Scrolling}). + +The cursor must be at the left margin before this command is used. +This command does not move the cursor. + +@item dl +@kindex dl +String of commands to delete the line the cursor is on. The following +lines move up, and a blank line appears at the bottom of the screen +(or bottom of the scroll region). If the terminal has the @samp{db} +flag, a nonblank line previously pushed off the screen bottom may +reappear at the bottom. + +The cursor must be at the left margin before this command is used. +This command does not move the cursor. + +@item AL +@kindex AL +String of commands to insert @var{n} blank lines before the line that +the cursor is on. It is like @samp{al} repeated @var{n} times, except +that it is as fast as one @samp{al}. + +@item DL +@kindex DL +String of commands to delete @var{n} lines starting with the line that +the cursor is on. It is like @samp{dl} repeated @var{n} times, except +that it is as fast as one @samp{dl}. +@end table + +Any terminal description that defines @samp{AL} should also define +@samp{al}; likewise for @samp{DL} and @samp{dl}. However, many terminals +can only insert or delete one line at a time, so it is common to find +@samp{al} and not @samp{AL}, or @samp{dl} without @samp{DL}.@refill + +Therefore, all programs that use the insert and delete facilities should be +prepared to work with @samp{al} in the case that @samp{AL} is absent, and +likewise with @samp{dl}. On the other hand, it is acceptable to write +an application that uses only @samp{al} and @samp{dl} and does not look +for @samp{AL} or @samp{DL} at all.@refill + +If a terminal does not support line insertion and deletion directly, +but does support a scroll region, the effect of insertion and deletion +can be obtained with scrolling. However, it is up to the individual +user program to check for this possibility and use the scrolling +commands to get the desired result. It is fairly important to implement +this alternate strategy, since it is the only way to get the effect of +line insertion and deletion on the popular VT100 terminal. + +Insertion and deletion of lines is affected by the scroll region on +terminals that have a settable scroll region. This is useful when it is +desirable to move any few consecutive lines up or down by a few lines. +@xref{Scrolling}. + +The line pushed off the bottom of the screen is not lost if the terminal +has the @samp{db} flag capability; instead, it is pushed into display +memory that does not appear on the screen. This is the same thing that +happens when scrolling pushes a line off the bottom of the screen. +Either reverse scrolling or deletion of a line can bring the apparently +lost line back onto the bottom of the screen. If the terminal has the +scroll region feature as well as @samp{db}, the pushed-out line really +is lost if a scroll region is in effect. + +When outputting an insert or delete command with @code{tputs}, the +@var{nlines} argument should be the total number of lines from the cursor +to the bottom of the screen (or scroll region). Very often these commands +require padding proportional to this number of lines. @xref{Padding}. + +For @samp{AL} and @samp{DL} the @var{nlines} argument should @emph{not} +depend on the number of lines inserted or deleted; only the total number of +lines affected. This is because it is just as fast to insert two or +@var{n} lines with @samp{AL} as to insert one line with @samp{al}. + +@node Insdel Char, Standout, Insdel Line, Capabilities +@section Insert/Delete Character +@cindex insert character +@cindex delete character + +@dfn{Inserting a character} means creating a blank space in the middle of a +line, and pushing the rest of the line rightward. The character in the +rightmost column is lost. + +@dfn{Deleting a character} means causing the character to disappear from +the screen, closing up the gap by moving the rest of the line leftward. A +blank space appears in the rightmost column. + +Insertion and deletion of characters is useful in programs that maintain an +updating display some parts of which may get longer or shorter. It is also +useful in editors for redisplaying the results of editing within a line. + +Many terminals provide commands to insert or delete a single character at +the cursor position. Some provide the ability to insert or delete several +characters with one command, using the number of characters to insert or +delete as a parameter. + +@cindex insert mode +Many terminals provide an insert mode in which outputting a graphic +character has the added effect of inserting a position for that character. +A special command string is used to enter insert mode and another is used +to exit it. The reason for designing a terminal with an insert mode rather +than an insert command is that inserting character positions is usually +followed by writing characters into them. With insert mode, this is as +fast as simply writing the characters, except for the fixed overhead of +entering and leaving insert mode. However, when the line speed is great +enough, padding may be required for the graphic characters output in insert +mode. + +Some terminals require you to enter insert mode and then output a special +command for each position to be inserted. Or they may require special +commands to be output before or after each graphic character to be +inserted. + +@cindex delete mode +Deletion of characters is usually accomplished by a straightforward command +to delete one or several positions; but on some terminals, it is necessary +to enter a special delete mode before using the delete command, and leave +delete mode afterward. Sometimes delete mode and insert mode are the same +mode. + +Some terminals make a distinction between character positions in which a +space character has been output and positions which have been cleared. On +these terminals, the effect of insert or delete character runs to the first +cleared position rather than to the end of the line. In fact, the effect +may run to more than one line if there is no cleared position to stop the +shift on the first line. These terminals are identified by the @samp{in} +flag capability. + +On terminals with the @samp{in} flag, the technique of skipping over +characters that you know were cleared, and then outputting text later on in +the same line, causes later insert and delete character operations on that +line to do nonstandard things. A program that has any chance of doing this +must check for the @samp{in} flag and must be careful to write explicit +space characters into the intermediate columns when @samp{in} is present. + +A plethora of terminal capabilities are needed to describe all of this +complexity. Here is a list of them all. Following the list, we present +an algorithm for programs to use to take proper account of all of these +capabilities. + +@table @samp +@item im +@kindex im +String of commands to enter insert mode. + +If the terminal has no special insert mode, but it can insert +characters with a special command, @samp{im} should be defined with a +null value, because the @samp{vi} editor assumes that insertion of a +character is impossible if @samp{im} is not provided. + +New programs should not act like @samp{vi}. They should pay attention +to @samp{im} only if it is defined. + +@item ei +@kindex ei +String of commands to leave insert mode. This capability must be +present if @samp{im} is. + +On a few old terminals the same string is used to enter and exit +insert mode. This string turns insert mode on if it was off, and off +it it was on. You can tell these terminals because the @samp{ei} +string equals the @samp{im} string. If you want to support these +terminals, you must always remember accurately whether insert mode is +in effect. However, these terminals are obsolete, and it is +reasonable to refuse to support them. On all modern terminals, you +can safely output @samp{ei} at any time to ensure that insert mode is +turned off. + +@item ic +@kindex ic +String of commands to insert one character position at the cursor. +The cursor does not move. + +If outputting a graphic character while in insert mode is sufficient +to insert the character, then the @samp{ic} capability should be +defined with a null value. + +If your terminal offers a choice of ways to insert---either use insert +mode or use a special command---then define @samp{im} and do not define +@samp{ic}, since this gives the most efficient operation when several +characters are to be inserted. @emph{Do not} define both strings, for +that means that @emph{both} must be used each time insertion is done. + +@item ip +@kindex ip +String of commands to output following an inserted graphic character +in insert mode. Often it is used just for a padding spec, when padding +is needed after an inserted character (@pxref{Padding}). + +@item IC +@kindex IC +String of commands to insert @var{n} character positions at and after +the cursor. It has the same effect as repeating the @samp{ic} string +and a space, @var{n} times. + +If @samp{IC} is provided, application programs may use it without first +entering insert mode. + +@item mi +@kindex mi +Flag whose presence means it is safe to move the cursor while in insert +mode and assume the terminal remains in insert mode. + +@item in +@kindex in +Flag whose presence means that the terminal distinguishes between +character positions in which space characters have been output and +positions which have been cleared. +@end table + +An application program can assume that the terminal can do character +insertion if @emph{any one of} the capabilities @samp{IC}, @samp{im}, +@samp{ic} or @samp{ip} is provided. + +To insert @var{n} blank character positions, move the cursor to the place +to insert them and follow this algorithm: + +@enumerate +@item +If an @samp{IC} string is provided, output it with parameter @var{n} +and you are finished. Otherwise (or if you don't want to bother to +look for an @samp{IC} string) follow the remaining steps. + +@item +Output the @samp{im} string, if there is one, unless the terminal is +already in insert mode. + +@item +Repeat steps 4 through 6, @var{n} times. + +@item +Output the @samp{ic} string if any. + +@item +Output a space. + +@item +Output the @samp{ip} string if any. + +@item +Output the @samp{ei} string, eventually, to exit insert mode. There +is no need to do this right away. If the @samp{mi} flag is present, +you can move the cursor and the cursor will remain in insert mode; +then you can do more insertion elsewhere without reentering insert +mode. +@end enumerate + +To insert @var{n} graphic characters, position the cursor and follow this +algorithm: + +@enumerate +@item +If an @samp{IC} string is provided, output it with parameter @var{n}, +then output the graphic characters, and you are finished. Otherwise +(or if you don't want to bother to look for an @samp{IC} string) +follow the remaining steps. + +@item +Output the @samp{im} string, if there is one, unless the terminal is +already in insert mode. + +@item +For each character to be output, repeat steps 4 through 6. + +@item +Output the @samp{ic} string if any. + +@item +Output the next graphic character. + +@item +Output the @samp{ip} string if any. + +@item +Output the @samp{ei} string, eventually, to exit insert mode. There +is no need to do this right away. If the @samp{mi} flag is present, +you can move the cursor and the cursor will remain in insert mode; +then you can do more insertion elsewhere without reentering insert +mode. +@end enumerate + +Note that this is not the same as the original Unix termcap specifications +in one respect: it assumes that the @samp{IC} string can be used without +entering insert mode. This is true as far as I know, and it allows you be +able to avoid entering and leaving insert mode, and also to be able to +avoid the inserted-character padding after the characters that go into the +inserted positions. + +Deletion of characters is less complicated; deleting one column is done by +outputting the @samp{dc} string. However, there may be a delete mode that +must be entered with @samp{dm} in order to make @samp{dc} work. + +@table @samp +@item dc +@kindex dc +String of commands to delete one character position at the cursor. If +@samp{dc} is not present, the terminal cannot delete characters. + +@item DC +@kindex DC +String of commands to delete @var{n} characters starting at the cursor. +It has the same effect as repeating the @samp{dc} string @var{n} times. +Any terminal description that has @samp{DC} also has @samp{dc}. + +@item dm +@kindex dm +String of commands to enter delete mode. If not present, there is no +delete mode, and @samp{dc} can be used at any time (assuming there is +a @samp{dc}). + +@item ed +@kindex ed +String of commands to exit delete mode. This must be present if +@samp{dm} is. +@end table + +To delete @var{n} character positions, position the cursor and follow these +steps: + +@enumerate +@item +If the @samp{DC} string is present, output it with parameter @var{n} +and you are finished. Otherwise, follow the remaining steps. + +@item +Output the @samp{dm} string, unless you know the terminal is already +in delete mode. + +@item +Output the @samp{dc} string @var{n} times. + +@item +Output the @samp{ed} string eventually. If the flag capability +@samp{mi} is present, you can move the cursor and do more deletion +without leaving and reentering delete mode. +@end enumerate + +As with the @samp{IC} string, we have departed from the original termcap +specifications by assuming that @samp{DC} works without entering delete +mode even though @samp{dc} would not. + +If the @samp{dm} and @samp{im} capabilities are both present and have the +same value, it means that the terminal has one mode for both insertion and +deletion. It is useful for a program to know this, because then it can do +insertions after deletions, or vice versa, without leaving insert/delete +mode and reentering it. + +@node Standout, Underlining, Insdel Char, Capabilities +@section Standout and Appearance Modes +@cindex appearance modes +@cindex standout +@cindex magic cookie + +@dfn{Appearance modes} are modifications to the ways characters are +displayed. Typical appearance modes include reverse video, dim, bright, +blinking, underlined, invisible, and alternate character set. Each kind of +terminal supports various among these, or perhaps none. + +For each type of terminal, one appearance mode or combination of them that +looks good for highlighted text is chosen as the @dfn{standout mode}. The +capabilities @samp{so} and @samp{se} say how to enter and leave standout +mode. Programs that use appearance modes only to highlight some text +generally use the standout mode so that they can work on as many terminals +as possible. Use of specific appearance modes other than ``underlined'' +and ``alternate character set'' is rare. + +Terminals that implement appearance modes fall into two general classes as +to how they do it. + +In some terminals, the presence or absence of any appearance mode is +recorded separately for each character position. In these terminals, each +graphic character written is given the appearance modes current at the time +it is written, and keeps those modes until it is erased or overwritten. +There are special commands to turn the appearance modes on or off for +characters to be written in the future. + +In other terminals, the change of appearance modes is represented by a +marker that belongs to a certain screen position but affects all following +screen positions until the next marker. These markers are traditionally +called @dfn{magic cookies}. + +The same capabilities (@samp{so}, @samp{se}, @samp{mb} and so on) for +turning appearance modes on and off are used for both magic-cookie +terminals and per-character terminals. On magic cookie terminals, these +give the commands to write the magic cookies. On per-character terminals, +they change the current modes that affect future output and erasure. Some +simple applications can use these commands without knowing whether or not +they work by means of cookies. + +However, a program that maintains and updates a display needs to know +whether the terminal uses magic cookies, and exactly what their effect is. +This information comes from the @samp{sg} capability. + +The @samp{sg} capability is a numeric capability whose presence indicates +that the terminal uses magic cookies for appearance modes. Its value is +the number of character positions that a magic cookie occupies. Usually +the cookie occupies one or more character positions on the screen, and these +character positions are displayed as blank, but in some terminals the +cookie has zero width. + +The @samp{sg} capability describes both the magic cookie to turn standout +on and the cookie to turn it off. This makes the assumption that both +kinds of cookie have the same width on the screen. If that is not true, +the narrower cookie must be ``widened'' with spaces until it has the same +width as the other. + +On some magic cookie terminals, each line always starts with normal +display; in other words, the scope of a magic cookie never extends over +more than one line. But on other terminals, one magic cookie affects all +the lines below it unless explicitly canceled. Termcap does not define any +way to distinguish these two ways magic cookies can work. To be safe, it +is best to put a cookie at the beginning of each line. + +On some per-character terminals, standout mode or other appearance modes +may be canceled by moving the cursor. On others, moving the cursor has no +effect on the state of the appearance modes. The latter class of terminals +are given the flag capability @samp{ms} (``can move in standout''). All +programs that might have occasion to move the cursor while appearance modes +are turned on must check for this flag; if it is not present, they should +reset appearance modes to normal before doing cursor motion. + +A program that has turned on only standout mode should use @samp{se} to +reset the standout mode to normal. A program that has turned on only +alternate character set mode should use @samp{ae} to return it to normal. +If it is possible that any other appearance modes are turned on, use the +@samp{me} capability to return them to normal. + +Note that the commands to turn on one appearance mode, including @samp{so} +and @samp{mb} @dots{} @samp{mr}, if used while some other appearance modes +are turned on, may combine the two modes on some terminals but may turn off +the mode previously enabled on other terminals. This is because some +terminals do not have a command to set or clear one appearance mode without +changing the others. Programs should not attempt to use appearance modes +in combination except with @samp{sa}, and when switching from one single +mode to another should always turn off the previously enabled mode and then +turn on the new desired mode. + +On some old terminals, the @samp{so} and @samp{se} commands may be the same +command, which has the effect of turning standout on if it is off, or off +it is on. It is therefore risky for a program to output extra @samp{se} +commands for good measure. Fortunately, all these terminals are obsolete. + +Programs that update displays in which standout-text may be replaced with +non-standout text must check for the @samp{xs} flag. In a per-character +terminal, this flag says that the only way to remove standout once written is +to clear that portion of the line with the @samp{ce} string or something +even more powerful (@pxref{Clearing}); just writing new characters at those +screen positions will not change the modes in effect there. In a magic +cookie terminal, @samp{xs} says that the only way to remove a cookie is to +clear a portion of the line that includes the cookie; writing a different +cookie at the same position does not work. + +Such programs must also check for the @samp{xt} flag, which means that the +terminal is a Teleray 1061. On this terminal it is impossible to position +the cursor at the front of a magic cookie, so the only two ways to remove a +cookie are (1) to delete the line it is on or (2) to position the cursor at +least one character before it (possibly on a previous line) and output the +@samp{se} string, which on these terminals finds and removes the next +@samp{so} magic cookie on the screen. (It may also be possible to remove a +cookie which is not at the beginning of a line by clearing that line.) The +@samp{xt} capability also has implications for the use of tab characters, +but in that regard it is obsolete (@xref{Cursor Motion}). + +@table @samp +@item so +@kindex so +String of commands to enter standout mode. + +@item se +@kindex se +String of commands to leave standout mode. + +@item sg +@kindex sg +Numeric capability, the width on the screen of the magic cookie. This +capability is absent in terminals that record appearance modes +character by character. + +@item ms +@kindex ms +Flag whose presence means that it is safe to move the cursor while the +appearance modes are not in the normal state. If this flag is absent, +programs should always reset the appearance modes to normal before +moving the cursor. + +@item xs +@kindex xs +Flag whose presence means that the only way to reset appearance modes +already on the screen is to clear to end of line. On a per-character +terminal, you must clear the area where the modes are set. On a magic +cookie terminal, you must clear an area containing the cookie. +See the discussion above. + +@item xt +@kindex xt +Flag whose presence means that the cursor cannot be positioned right +in front of a magic cookie, and that @samp{se} is a command to delete +the next magic cookie following the cursor. See discussion above. + +@item mb +@kindex mb +String of commands to enter blinking mode. + +@item md +@kindex md +String of commands to enter double-bright mode. + +@item mh +@kindex mh +String of commands to enter half-bright mode. + +@item mk +@kindex mk +String of commands to enter invisible mode. + +@item mp +@kindex mp +String of commands to enter protected mode. + +@item mr +@kindex mr +String of commands to enter reverse-video mode. + +@item me +@kindex me +String of commands to turn off all appearance modes, including +standout mode and underline mode. On some terminals it also turns off +alternate character set mode; on others, it may not. This capability +must be present if any of @samp{mb} @dots{} @samp{mr} is present. + +@item as +@kindex as +String of commands to turn on alternate character set mode. This mode +assigns some or all graphic characters an alternate picture on the +screen. There is no standard as to what the alternate pictures look +like. + +@item ae +@kindex ae +String of commands to turn off alternate character set mode. + +@item sa +@kindex sa +String of commands to turn on an arbitrary combination of appearance +modes. It accepts 9 parameters, each of which controls a particular +kind of appearance mode. A parameter should be 1 to turn its appearance +mode on, or zero to turn that mode off. Most terminals do not support +the @samp{sa} capability, even among those that do have various +appearance modes. + +The nine parameters are, in order, @var{standout}, @var{underline}, +@var{reverse}, @var{blink}, @var{half-bright}, @var{double-bright}, +@var{blank}, @var{protect}, @var{alt char set}. +@end table + +@node Underlining, Cursor Visibility, Standout, Capabilities +@section Underlining +@cindex underlining + +Underlining on most terminals is a kind of appearance mode, much like +standout mode. Therefore, it may be implemented using magic cookies or as +a flag in the terminal whose current state affects each character that is +output. @xref{Standout}, for a full explanation. + +The @samp{ug} capability is a numeric capability whose presence indicates +that the terminal uses magic cookies for underlining. Its value is the +number of character positions that a magic cookie for underlining occupies; +it is used for underlining just as @samp{sg} is used for standout. Aside +from the simplest applications, it is impossible to use underlining +correctly without paying attention to the value of @samp{ug}. + +@table @samp +@item us +@kindex us +String of commands to turn on underline mode or to output a magic cookie +to start underlining. + +@item ue +@kindex ue +String of commands to turn off underline mode or to output a magic +cookie to stop underlining. + +@item ug +@kindex ug +Width of magic cookie that represents a change of underline mode; +or missing, if the terminal does not use a magic cookie for this. + +@item ms +@kindex ms +Flag whose presence means that it is safe to move the cursor while the +appearance modes are not in the normal state. Underlining is an +appearance mode. If this flag is absent, programs should always turn +off underlining before moving the cursor. +@end table + +There are two other, older ways of doing underlining: there can be a +command to underline a single character, or the output of @samp{_}, the +ASCII underscore character, as an overstrike could cause a character to be +underlined. New programs need not bother to handle these capabilities +unless the author cares strongly about the obscure terminals which support +them. However, terminal descriptions should provide these capabilities +when appropriate. + +@table @samp +@item uc +@kindex uc +String of commands to underline the character under the cursor, and +move the cursor right. + +@item ul +@kindex ul +Flag whose presence means that the terminal can underline by +overstriking an underscore character (@samp{_}); some terminals can do +this even though they do not support overstriking in general. An +implication of this flag is that when outputting new text to overwrite +old text, underscore characters must be treated specially lest they +underline the old text instead. +@end table + +@node Cursor Visibility, Bell, Underlining, Capabilities +@section Cursor Visibility +@cindex visibility + +Some terminals have the ability to make the cursor invisible, or to enhance +it. Enhancing the cursor is often done by programs that plan to use the +cursor to indicate to the user a position of interest that may be anywhere +on the screen---for example, the Emacs editor enhances the cursor on entry. +Such programs should always restore the cursor to normal on exit. + +@table @samp +@item vs +@kindex vs +String of commands to enhance the cursor. + +@item vi +@kindex vi +String of commands to make the cursor invisible. + +@item ve +@kindex ve +String of commands to return the cursor to normal. +@end table + +If you define either @samp{vs} or @samp{vi}, you must also define @samp{ve}. + +@node Bell, Keypad, Cursor Visibility, Capabilities +@section Bell +@cindex bell +@cindex visible bell + +Here we describe commands to make the terminal ask for the user to pay +attention to it. + +@table @samp +@item bl +@kindex bl +String of commands to cause the terminal to make an audible sound. If +this capability is absent, the terminal has no way to make a suitable +sound. + +@item vb +@kindex vb +String of commands to cause the screen to flash to attract attention +(``visible bell''). If this capability is absent, the terminal has no +way to do such a thing. +@end table + +@node Keypad, Meta Key, Bell, Capabilities +@section Keypad and Function Keys + +Many terminals have arrow and function keys that transmit specific +character sequences to the computer. Since the precise sequences used +depend on the terminal, termcap defines capabilities used to say what the +sequences are. Unlike most termcap string-valued capabilities, these are +not strings of commands to be sent to the terminal, rather strings that +are received from the terminal. + +Programs that expect to use keypad keys should check, initially, for a +@samp{ks} capability and send it, to make the keypad actually transmit. +Such programs should also send the @samp{ke} string when exiting. + +@table @asis +@item @samp{ks} +@kindex ka@dots{}ku +String of commands to make the keypad keys transmit. If this +capability is not provided, but the others in this section are, +programs may assume that the keypad keys always transmit. + +@item @samp{ke} +String of commands to make the keypad keys work locally. This +capability is provided only if @samp{ks} is. + +@item @samp{kl} +String of input characters sent by typing the left-arrow key. If this +capability is missing, you cannot expect the terminal to have a +left-arrow key that transmits anything to the computer. + +@item @samp{kr} +String of input characters sent by typing the right-arrow key. + +@item @samp{ku} +String of input characters sent by typing the up-arrow key. + +@item @samp{kd} +String of input characters sent by typing the down-arrow key. + +@item @samp{kh} +String of input characters sent by typing the ``home-position'' key. + +@item @samp{K1} @dots{} @samp{K5} +@kindex K1@dots{}K5 +Strings of input characters sent by the five other keys in a 3-by-3 +array that includes the arrow keys, if the keyboard has such a 3-by-3 +array. Note that one of these keys may be the ``home-position'' key, +in which case one of these capabilities will have the same value as +the @samp{kh} key. + +@item @samp{k0} +String of input characters sent by function key 10 (or 0, if the terminal +has one labeled 0). + +@item @samp{k1} @dots{} @samp{k9} +@kindex k1@dots{}k9 +Strings of input characters sent by function keys 1 through 9, +provided for those function keys that exist. + +@item @samp{kn} +Number: the number of numbered function keys, if there are more than +10. + +@item @samp{l0} @dots{} @samp{l9} +@kindex l0@dots{}l9 +Strings which are the labels appearing on the keyboard on the keys +described by the capabilities @samp{k0} @dots{} @samp{l9}. These +capabilities should be left undefined if the labels are @samp{f0} or +@samp{f10} and @samp{f1} @dots{} @samp{f9}.@refill + +@item @samp{kH} +@kindex kA@dots{}kT +String of input characters sent by the ``home down'' key, if there is +one. + +@item @samp{kb} +String of input characters sent by the ``backspace'' key, if there is +one. + +@item @samp{ka} +String of input characters sent by the ``clear all tabs'' key, if there +is one. + +@item @samp{kt} +String of input characters sent by the ``clear tab stop this column'' +key, if there is one. + +@item @samp{kC} +String of input characters sent by the ``clear screen'' key, if there is +one. + +@item @samp{kD} +String of input characters sent by the ``delete character'' key, if +there is one. + +@item @samp{kL} +String of input characters sent by the ``delete line'' key, if there is +one. + +@item @samp{kM} +String of input characters sent by the ``exit insert mode'' key, if +there is one. + +@item @samp{kE} +String of input characters sent by the ``clear to end of line'' key, if +there is one. + +@item @samp{kS} +String of input characters sent by the ``clear to end of screen'' key, +if there is one. + +@item @samp{kI} +String of input characters sent by the ``insert character'' or ``enter +insert mode'' key, if there is one. + +@item @samp{kA} +String of input characters sent by the ``insert line'' key, if there is +one. + +@item @samp{kN} +String of input characters sent by the ``next page'' key, if there is +one. + +@item @samp{kP} +String of input characters sent by the ``previous page'' key, if there is +one. + +@item @samp{kF} +String of input characters sent by the ``scroll forward'' key, if there +is one. + +@item @samp{kR} +String of input characters sent by the ``scroll reverse'' key, if there +is one. + +@item @samp{kT} +String of input characters sent by the ``set tab stop in this column'' +key, if there is one. + +@item @samp{ko} +String listing the other function keys the terminal has. This is a +very obsolete way of describing the same information found in the +@samp{kH} @dots{} @samp{kT} keys. The string contains a list of +two-character termcap capability names, separated by commas. The +meaning is that for each capability name listed, the terminal has a +key which sends the string which is the value of that capability. For +example, the value @samp{:ko=cl,ll,sf,sr:} says that the terminal has +four function keys which mean ``clear screen'', ``home down'', +``scroll forward'' and ``scroll reverse''.@refill +@end table + +@node Meta Key, Initialization, Keypad, Capabilities +@section Meta Key + +@cindex meta key +A Meta key is a key on the keyboard that modifies each character you type +by controlling the 0200 bit. This bit is on if and only if the Meta key is +held down when the character is typed. Characters typed using the Meta key +are called Meta characters. Emacs uses Meta characters as editing +commands. + +@table @samp +@item km +@kindex km +Flag whose presence means that the terminal has a Meta key. + +@item mm +@kindex mm +String of commands to enable the functioning of the Meta key. + +@item mo +@kindex mo +String of commands to disable the functioning of the Meta key. +@end table + +If the terminal has @samp{km} but does not have @samp{mm} and @samp{mo}, it +means that the Meta key always functions. If it has @samp{mm} and +@samp{mo}, it means that the Meta key can be turned on or off. Send the +@samp{mm} string to turn it on, and the @samp{mo} string to turn it off. +I do not know why one would ever not want it to be on. + +@node Initialization, Pad Specs, Meta Key, Capabilities +@section Initialization +@cindex reset +@cindex initialization +@cindex tab stops + +@table @samp +@item ti +@kindex ti +String of commands to put the terminal into whatever special modes are +needed or appropriate for programs that move the cursor +nonsequentially around the screen. Programs that use termcap to do +full-screen display should output this string when they start up. + +@item te +@kindex te +String of commands to undo what is done by the @samp{ti} string. +Programs that output the @samp{ti} string on entry should output this +string when they exit. + +@item is +@kindex is +String of commands to initialize the terminal for each login session. + +@item if +@kindex if +String which is the name of a file containing the string of commands +to initialize the terminal for each session of use. Normally @samp{is} +and @samp{if} are not both used. + +@item i1 +@itemx i3 +@kindex i1 +@kindex i3 +Two more strings of commands to initialize the terminal for each login +session. The @samp{i1} string (if defined) is output before @samp{is} +or @samp{if}, and the @samp{i3} string (if defined) is output after. + +The reason for having three separate initialization strings is to make +it easier to define a group of related terminal types with slightly +different initializations. Define two or three of the strings in the +basic type; then the other types can override one or two of the +strings. + +@item rs +@kindex rs +String of commands to reset the terminal from any strange mode it may +be in. Normally this includes the @samp{is} string (or other commands +with the same effects) and more. What would go in the @samp{rs} +string but not in the @samp{is} string are annoying or slow commands +to bring the terminal back from strange modes that nobody would +normally use. + +@item it +@kindex it +Numeric value, the initial spacing between hardware tab stop columns +when the terminal is powered up. Programs to initialize the terminal +can use this to decide whether there is a need to set the tab stops. +If the initial width is 8, well and good; if it is not 8, then the +tab stops should be set; if they cannot be set, the kernel is told +to convert tabs to spaces, and other programs will observe this and do +likewise. + +@item ct +@kindex ct +String of commands to clear all tab stops. + +@item st +@kindex st +String of commands to set tab stop at current cursor column on all +lines. + +@item NF +@kindex NF +Flag whose presence means that the terminal does not support XON/XOFF +flow control. Programs should not send XON (@kbd{C-q}) or XOFF +(@kbd{C-s}) characters to the terminal. +@end table + +@node Pad Specs, Status Line, Initialization, Capabilities +@section Padding Capabilities +@cindex padding + +There are two terminal capabilities that exist just to explain the proper +way to obey the padding specifications in all the command string +capabilities. One, @samp{pc}, must be obeyed by all termcap-using +programs. + +@table @samp +@item pb +@kindex pb +Numeric value, the lowest baud rate at which padding is actually +needed. Programs may check this and refrain from doing any padding at +lower speeds. + +@item pc +@kindex pc +String of commands for padding. The first character of this string is +to be used as the pad character, instead of using null characters for +padding. If @samp{pc} is not provided, use null characters. Every +program that uses termcap must look up this capability and use it to +set the variable @code{PC} that is used by @code{tputs}. +@xref{Padding}. +@end table + +Some termcap capabilities exist just to specify the amount of padding that +the kernel should give to cursor motion commands used in ordinary +sequential output. + +@table @samp +@item dC +@kindex dC +Numeric value, the number of msec of padding needed for the +carriage-return character. + +@item dN +@kindex dN +Numeric value, the number of msec of padding needed for the newline +(linefeed) character. + +@item dB +@kindex dB +Numeric value, the number of msec of padding needed for the backspace +character. + +@item dF +@kindex dF +Numeric value, the number of msec of padding needed for the formfeed +character. + +@item dT +@kindex dT +Numeric value, the number of msec of padding needed for the tab +character. +@end table + +In some systems, the kernel uses the above capabilities; in other systems, +the kernel uses the paddings specified in the string capabilities +@samp{cr}, @samp{sf}, @samp{le}, @samp{ff} and @samp{ta}. Descriptions of +terminals which require such padding should contain the @samp{dC} @dots{} +@samp{dT} capabilities and also specify the appropriate padding in the +corresponding string capabilities. Since no modern terminals require +padding for ordinary sequential output, you probably won't need to do +either of these things. + +@node Status Line, Half-Line, Pad Specs, Capabilities +@section Status Line + +@cindex status line +A @dfn{status line} is a line on the terminal that is not used for ordinary +display output but instead used for a special message. The intended use is +for a continuously updated description of what the user's program is doing, +and that is where the name ``status line'' comes from, but in fact it could +be used for anything. The distinguishing characteristic of a status line +is that ordinary output to the terminal does not affect it; it changes only +if the special status line commands of this section are used. + +@table @samp +@item hs +@kindex hs +Flag whose presence means that the terminal has a status line. If a +terminal description specifies that there is a status line, it must +provide the @samp{ts} and @samp{fs} capabilities. + +@item ts +@kindex ts +String of commands to move the terminal cursor into the status line. +Usually these commands must specifically record the old cursor +position for the sake of the @samp{fs} string. + +@item fs +@kindex fs +String of commands to move the cursor back from the status line to its +previous position (outside the status line). + +@item es +@kindex es +Flag whose presence means that other display commands work while +writing the status line. In other words, one can clear parts of it, +insert or delete characters, move the cursor within it using @samp{ch} +if there is a @samp{ch} capability, enter and leave standout mode, and +so on. + +@item ds +@kindex ds +String of commands to disable the display of the status line. This +may be absent, if there is no way to disable the status line display. + +@item ws +@kindex ws +Numeric value, the width of the status line. If this capability is +absent in a terminal that has a status line, it means the status line +is the same width as the other lines. + +Note that the value of @samp{ws} is sometimes as small as 8. +@end table + +@node Half-Line, Printer, Status Line, Capabilities +@section Half-Line Motion + +Some terminals have commands for moving the cursor vertically by half-lines, +useful for outputting subscripts and superscripts. Mostly it is hardcopy +terminals that have such features. + +@table @samp +@item hu +@kindex hu +String of commands to move the cursor up half a line. If the terminal +is a display, it is your responsibility to avoid moving up past the +top line; however, most likely the terminal that supports this is a +hardcopy terminal and there is nothing to be concerned about. + +@item hd +@kindex hd +String of commands to move the cursor down half a line. If the +terminal is a display, it is your responsibility to avoid moving down +past the bottom line, etc. +@end table + +@node Printer, , Half-Line, Capabilities +@section Controlling Printers Attached to Terminals +@cindex printer + +Some terminals have attached hardcopy printer ports. They may be able to +copy the screen contents to the printer; they may also be able to redirect +output to the printer. Termcap does not have anything to tell the program +whether the redirected output appears also on the screen; it does on some +terminals but not all. + +@table @samp +@item ps +@kindex ps +String of commands to cause the contents of the screen to be printed. +If it is absent, the screen contents cannot be printed. + +@item po +@kindex po +String of commands to redirect further output to the printer. + +@item pf +@kindex pf +String of commands to terminate redirection of output to the printer. +This capability must be present in the description if @samp{po} is. + +@item pO +@kindex pO +String of commands to redirect output to the printer for next @var{n} +characters of output, regardless of what they are. Redirection will +end automatically after @var{n} characters of further output. Until +then, nothing that is output can end redirection, not even the +@samp{pf} string if there is one. The number @var{n} should not be +more than 255. + +One use of this capability is to send non-text byte sequences (such as +bit-maps) to the printer. +@end table + +Most terminals with printers do not support all of @samp{ps}, @samp{po} and +@samp{pO}; any one or two of them may be supported. To make a program that +can send output to all kinds of printers, it is necessary to check for all +three of these capabilities, choose the most convenient of the ones that +are provided, and use it in its own appropriate fashion. + +@node Summary, Var Index, Capabilities, Top +@chapter Summary of Capability Names + +Here are all the terminal capability names in alphabetical order +with a brief description of each. For cross references to their definitions, +see the index of capability names (@pxref{Cap Index}). + +@table @samp +@item ae +String to turn off alternate character set mode. +@item al +String to insert a blank line before the cursor. +@item AL +String to insert @var{n} blank lines before the cursor. +@item am +Flag: output to last column wraps cursor to next line. +@item as +String to turn on alternate character set mode.like. +@item bc +Very obsolete alternative name for the @samp{le} capability. +@item bl +String to sound the bell. +@item bs +Obsolete flag: ASCII backspace may be used for leftward motion. +@item bt +String to move the cursor left to the previous hardware tab stop column. +@item bw +Flag: @samp{le} at left margin wraps to end of previous line. +@item CC +String to change terminal's command character. +@item cd +String to clear the line the cursor is on, and following lines. +@item ce +String to clear from the cursor to the end of the line. +@item ch +String to position the cursor at column @var{c} in the same line. +@item cl +String to clear the entire screen and put cursor at upper left corner. +@item cm +String to position the cursor at line @var{l}, column @var{c}. +@item CM +String to position the cursor at line @var{l}, column +@var{c}, relative to display memory. +@item co +Number: width of the screen. +@item cr +String to move cursor sideways to left margin. +@item cs +String to set the scroll region. +@item cS +Alternate form of string to set the scroll region. +@item ct +String to clear all tab stops. +@item cv +String to position the cursor at line @var{l} in the same column. +@item da +Flag: data scrolled off top of screen may be scrolled back. +@item db +Flag: data scrolled off bottom of screen may be scrolled back. +@item dB +Obsolete number: msec of padding needed for the backspace character. +@item dc +String to delete one character position at the cursor. +@item dC +Obsolete number: msec of padding needed for the carriage-return character. +@item DC +String to delete @var{n} characters starting at the cursor. +@item dF +Obsolete number: msec of padding needed for the formfeed character. +@item dl +String to delete the line the cursor is on. +@item DL +String to delete @var{n} lines starting with the cursor's line. +@item dm +String to enter delete mode. +@item dN +Obsolete number: msec of padding needed for the newline character. +@item do +String to move the cursor vertically down one line. +@item DO +String to move cursor vertically down @var{n} lines. +@item ds +String to disable the display of the status line. +@item dT +Obsolete number: msec of padding needed for the tab character. +@item ec +String of commands to clear @var{n} characters at cursor. +@item ed +String to exit delete mode. +@item ei +String to leave insert mode. +@item eo +Flag: output of a space can erase an overstrike. +@item es +Flag: other display commands work while writing the status line. +@item ff +String to advance to the next page, for a hardcopy terminal. +@item fs +String to move the cursor back from the status line to its +previous position (outside the status line). +@item gn +Flag: this terminal type is generic, not real. +@item hc +Flag: hardcopy terminal. +@item hd +String to move the cursor down half a line. +@item ho +String to position cursor at upper left corner. +@item hs +Flag: the terminal has a status line. +@item hu +String to move the cursor up half a line. +@item hz +Flag: terminal cannot accept @samp{~} as output. +@item i1 +String to initialize the terminal for each login session. +@item i3 +String to initialize the terminal for each login session. +@item ic +String to insert one character position at the cursor. +@item IC +String to insert @var{n} character positions at the cursor. +@item if +String naming a file of commands to initialize the terminal. +@item im +String to enter insert mode. +@item in +Flag: outputting a space is different from moving over empty positions. +@item ip +String to output following an inserted character in insert mode. +@item is +String to initialize the terminal for each login session. +@item it +Number: initial spacing between hardware tab stop columns. +@item k0 +String of input sent by function key 0 or 10. +@item k1 @dots{} k9 +Strings of input sent by function keys 1 through 9. +@item K1 @dots{} K5 +Strings sent by the five other keys in 3-by-3 array with arrows. +@item ka +String of input sent by the ``clear all tabs'' key. +@item kA +String of input sent by the ``insert line'' key. +@item kb +String of input sent by the ``backspace'' key. +@item kC +String of input sent by the ``clear screen'' key. +@item kd +String of input sent by typing the down-arrow key. +@item kD +String of input sent by the ``delete character'' key. +@item ke +String to make the function keys work locally. +@item kE +String of input sent by the ``clear to end of line'' key. +@item kF +String of input sent by the ``scroll forward'' key. +@item kh +String of input sent by typing the ``home-position'' key. +@item kH +String of input sent by the ``home down'' key. +@item kI +String of input sent by the ``insert character'' or ``enter +insert mode'' key. +@item kl +String of input sent by typing the left-arrow key. +@item kL +String of input sent by the ``delete line'' key. +@item km +Flag: the terminal has a Meta key. +@item kM +String of input sent by the ``exit insert mode'' key. +@item kn +Numeric value, the number of numbered function keys. +@item kN +String of input sent by the ``next page'' key. +@item ko +Very obsolete string listing the terminal's named function keys. +@item kP +String of input sent by the ``previous page'' key. +@item kr +String of input sent by typing the right-arrow key. +@item kR +String of input sent by the ``scroll reverse'' key. +@item ks +String to make the function keys transmit. +@item kS +String of input sent by the ``clear to end of screen'' key. +@item kt +String of input sent by the ``clear tab stop this column'' key. +@item kT +String of input sent by the ``set tab stop in this column'' key. +@item ku +String of input sent by typing the up-arrow key. +@item l0 +String on keyboard labelling function key 0 or 10. +@item l1 @dots{} l9 +Strings on keyboard labelling function keys 1 through 9. +@item le +String to move the cursor left one column. +@item LE +String to move cursor left @var{n} columns. +@item li +Number: height of the screen. +@item ll +String to position cursor at lower left corner. +@item lm +Number: lines of display memory. +@item LP +Flag: writing to last column of last line will not scroll. +@item mb +String to enter blinking mode. +@item md +String to enter double-bright mode. +@item me +String to turn off all appearance modes +@item mh +String to enter half-bright mode. +@item mi +Flag: cursor motion in insert mode is safe. +@item mk +String to enter invisible mode. +@item mm +String to enable the functioning of the Meta key. +@item mo +String to disable the functioning of the Meta key. +@item mp +String to enter protected mode. +@item mr +String to enter reverse-video mode. +@item ms +Flag: cursor motion in standout mode is safe. +@item nc +Obsolete flag: do not use ASCII carriage-return on this terminal. +@item nd +String to move the cursor right one column. +@item NF +Flag: do not use XON/XOFF flow control. +@item nl +Obsolete alternative name for the @samp{do} and @samp{sf} capabilities. +@item ns +Flag: the terminal does not normally scroll for sequential output. +@item nw +String to move to start of next line, possibly clearing rest of old line. +@item os +Flag: terminal can overstrike. +@item pb +Number: the lowest baud rate at which padding is actually needed. +@item pc +String containing character for padding. +@item pf +String to terminate redirection of output to the printer. +@item po +String to redirect further output to the printer. +@item pO +String to redirect @var{n} characters ofoutput to the printer. +@item ps +String to print the screen on the attached printer. +@item rc +String to move to last saved cursor position. +@item RI +String to move cursor right @var{n} columns. +@item rp +String to output character @var{c} repeated @var{n} times. +@item rs +String to reset the terminal from any strange modes. +@item sa +String to turn on an arbitrary combination of appearance modes. +@item sc +String to save the current cursor position. +@item se +String to leave standout mode. +@item sf +String to scroll the screen one line up. +@item SF +String to scroll the screen @var{n} lines up. +@item sg +Number: width of magic standout cookie. Absent if magic cookies are +not used. +@item so +String to enter standout mode. +@item sr +String to scroll the screen one line down. +@item SR +String to scroll the screen @var{n} line down. +@item st +String to set tab stop at current cursor column on all lines. +programs. +@item ta +String to move the cursor right to the next hardware tab stop column. +@item te +String to return terminal to settings for sequential output. +@item ti +String to initialize terminal for random cursor motion. +@item ts +String to move the terminal cursor into the status line. +@item uc +String to underline one character and move cursor right. +@item ue +String to turn off underline mode +@item ug +Number: width of underlining magic cookie. Absent if underlining +doesn't use magic cookies. +@item ul +Flag: underline by overstriking with an underscore. +@item up +String to move the cursor vertically up one line. +@item UP +String to move cursor vertically up @var{n} lines. +@item us +String to turn on underline mode +@item vb +String to make the screen flash. +@item ve +String to return the cursor to normal. +@item vi +String to make the cursor invisible. +@item vs +String to enhance the cursor. +@item wi +String to set the terminal output screen window. +@item ws +Number: the width of the status line. +@item xb +Flag: superbee terminal. +@item xn +Flag: cursor wraps in a strange way. +@item xs +Flag: clearing a line is the only way to clear the appearance modes of +positions in that line (or, only way to remove magic cookies on that +line). +@item xt +Flag: Teleray 1061; several strange characteristics. +@end table + +@node Var Index, Cap Index, Summary, Top +@unnumbered Variable and Function Index + +@printindex fn + +@node Cap Index, Index, Var Index, Top +@unnumbered Capability Index + +@printindex ky + +@node Index, , Cap Index, Top +@unnumbered Concept Index + +@printindex cp + +@contents +@bye |