Reformatted.
[chise/xemacs-chise.git.1] / man / termcap.texi
1 \input texinfo  @c -*-texinfo-*-
2 @setfilename ../info/termcap.info
3 @settitle The Termcap Library
4 @ifinfo
5 @direntry
6 * Termcap: (termcap).           Termcap library of the GNU system.
7 @end direntry
8
9 This file documents the termcap library of the GNU system.
10
11 Copyright (C) 1988 Free Software Foundation, Inc.
12
13 Permission is granted to make and distribute verbatim copies of
14 this manual provided the copyright notice and this permission notice
15 are preserved on all copies.
16
17 @ignore
18 Permission is granted to process this file through TeX and print the
19 results, provided the printed document carries copying permission
20 notice identical to this one except for the removal of this paragraph
21 (this paragraph not being relevant to the printed manual).
22
23 @end ignore
24 Permission is granted to copy and distribute modified versions of this
25 manual under the conditions for verbatim copying, provided that the entire
26 resulting derived work is distributed under the terms of a permission
27 notice identical to this one.
28
29 Permission is granted to copy and distribute translations of this manual
30 into another language, under the above conditions for modified versions,
31 except that this permission notice may be stated in a translation approved
32 by the Foundation.
33 @end ifinfo
34
35 @setchapternewpage odd
36 @titlepage
37 @sp 6
38 @center @titlefont{Termcap}
39 @sp 1
40 @center The Termcap Library and Data Base
41 @sp 4
42 @center First Edition
43 @sp 1
44 @center April 1988
45 @sp 5
46 @center Richard M. Stallman
47 @sp 1
48 @center Free Software Foundation
49 @page
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 1988 Free Software Foundation, Inc.
52
53 Published by the Free Software Foundation
54 (675 Mass Ave, Cambridge MA 02139).
55 Printed copies are available for $10 each.
56
57 Permission is granted to make and distribute verbatim copies of
58 this manual provided the copyright notice and this permission notice
59 are preserved on all copies.
60
61 Permission is granted to copy and distribute modified versions of this
62 manual under the conditions for verbatim copying, provided that the entire
63 resulting derived work is distributed under the terms of a permission
64 notice identical to this one.
65
66 Permission is granted to copy and distribute translations of this manual
67 into another language, under the above conditions for modified versions,
68 except that this permission notice may be stated in a translation approved
69 by the Foundation.
70 @end titlepage
71 @page
72
73 @synindex vr fn
74
75 @node Top, Introduction, (DIR), (DIR)
76
77 @menu
78 * Introduction::What is termcap?  Why this manual?
79 * Library::     The termcap library functions.
80 * Data Base::   What terminal descriptions in @file{/etc/termcap} look like.
81 * Capabilities::Definitions of the individual terminal capabilities:
82                  how to write them in descriptions, and how to use
83                  their values to do display updating.
84 * Summary::     Brief table of capability names and their meanings.
85 * Var Index::   Index of C functions and variables.
86 * Cap Index::   Index of termcap capabilities.
87 * Index::       Concept index.
88 @end menu
89
90 @node Introduction, Library, Top, Top
91 @unnumbered Introduction
92
93 @cindex termcap
94 @dfn{Termcap} is a library and data base that enables programs to use
95 display terminals in a terminal-independent manner.  It originated in
96 Berkeley Unix.
97
98 The termcap data base describes the capabilities of hundreds of different
99 display terminals in great detail.  Some examples of the information
100 recorded for a terminal could include how many columns wide it is, what
101 string to send to move the cursor to an arbitrary position (including how
102 to encode the row and column numbers), how to scroll the screen up one or
103 several lines, and how much padding is needed for such a scrolling
104 operation.
105
106 The termcap library is provided for easy access this data base in programs
107 that want to do terminal-independent character-based display output.
108
109 This manual describes the GNU version of the termcap library, which has
110 some extensions over the Unix version.  All the extensions are identified
111 as such, so this manual also tells you how to use the Unix termcap.
112
113 The GNU version of the termcap library is available free as source code,
114 for use in free programs, and runs on Unix and VMS systems (at least).  You
115 can find it in the GNU Emacs distribution in the files @file{termcap.c} and
116 @file{tparam.c}.
117
118 This manual was written for the GNU project, whose goal is to develop a
119 complete free operating system upward-compatible with Unix for user
120 programs.  The project is approximately two thirds complete.  For more
121 information on the GNU project, including the GNU Emacs editor and the
122 mostly-portable optimizing C compiler, send one dollar to
123
124 @display
125 Free Software Foundation
126 675 Mass Ave
127 Cambridge, MA 02139
128 @end display
129
130 @node Library, Data Base, Introduction, Top
131 @chapter The Termcap Library
132
133 The termcap library is the application programmer's interface to the
134 termcap data base.  It contains functions for the following purposes:
135
136 @itemize @bullet
137 @item
138 Finding the description of the user's terminal type (@code{tgetent}).
139
140 @item
141 Interrogating the description for information on various topics
142 (@code{tgetnum}, @code{tgetflag}, @code{tgetstr}).
143
144 @item
145 Computing and performing padding (@code{tputs}).
146
147 @item
148 Encoding numeric parameters such as cursor positions into the
149 terminal-specific form required for display commands (@code{tparam},
150 @code{tgoto}).
151 @end itemize
152
153 @menu
154 * Preparation:: Preparing to use the termcap library.
155 * Find::        Finding the description of the terminal being used.
156 * Interrogate:: Interrogating the description for particular capabilities.
157 * Initialize::  Initialization for output using termcap.
158 * Padding::     Outputting padding.
159 * Parameters::  Encoding parameters such as cursor positions.
160 @end menu
161
162 @node Preparation, Find, Library, Library
163 @section Preparing to Use the Termcap Library
164
165 To use the termcap library in a program, you need two kinds of preparation:
166
167 @itemize @bullet
168 @item
169 The compiler needs declarations of the functions and variables in the
170 library.
171
172 On GNU systems, it suffices to include the header file
173 @file{termcap.h} in each source file that uses these functions and
174 variables.@refill
175
176 On Unix systems, there is often no such header file.  Then you must
177 explictly declare the variables as external.  You can do likewise for
178 the functions, or let them be implicitly declared and cast their
179 values from type @code{int} to the appropriate type.
180
181 We illustrate the declarations of the individual termcap library
182 functions with ANSI C prototypes because they show how to pass the
183 arguments.  If you are not using the GNU C compiler, you probably
184 cannot use function prototypes, so omit the argument types and names
185 from your declarations.
186
187 @item
188 The linker needs to search the library.  Usually either
189 @samp{-ltermcap} or @samp{-ltermlib} as an argument when linking will
190 do this.@refill
191 @end itemize
192
193 @node Find, Interrogate, Preparation, Library
194 @section Finding a Terminal Description: @code{tgetent}
195
196 @findex tgetent
197 An application program that is going to use termcap must first look up the
198 description of the terminal type in use.  This is done by calling
199 @code{tgetent}, whose declaration in ANSI Standard C looks like:
200
201 @example
202 int tgetent (char *@var{buffer}, char *@var{termtype});
203 @end example
204
205 @noindent
206 This function finds the description and remembers it internally so that
207 you can interrogate it about specific terminal capabilities
208 (@pxref{Interrogate}).
209
210 The argument @var{termtype} is a string which is the name for the type of
211 terminal to look up.  Usually you would obtain this from the environment
212 variable @code{TERM} using @code{getenv ("TERM")}.
213
214 If you are using the GNU version of termcap, you can alternatively ask
215 @code{tgetent} to allocate enough space.  Pass a null pointer for
216 @var{buffer}, and @code{tgetent} itself allocates the storage using
217 @code{malloc}.  In this case the returned value on success is the address
218 of the storage, cast to @code{int}.  But normally there is no need for you
219 to look at the address.  Do not free the storage yourself.@refill
220
221 With the Unix version of termcap, you must allocate space for the
222 description yourself and pass the address of the space as the argument
223 @var{buffer}.  There is no way you can tell how much space is needed, so
224 the convention is to allocate a buffer 2048 characters long and assume that
225 is enough.  (Formerly the convention was to allocate 1024 characters and
226 assume that was enough.  But one day, for one kind of terminal, that was
227 not enough.)
228
229 No matter how the space to store the description has been obtained,
230 termcap records its address internally for use when you later interrogate
231 the description with @code{tgetnum}, @code{tgetstr} or @code{tgetflag}.  If
232 the buffer was allocated by termcap, it will be freed by termcap too if you
233 call @code{tgetent} again.  If the buffer was provided by you, you must
234 make sure that its contents remain unchanged for as long as you still plan
235 to interrogate the description.@refill
236
237 The return value of @code{tgetent} is @minus{}1 if there is some difficulty
238 accessing the data base of terminal types, 0 if the data base is accessible
239 but the specified type is not defined in it, and some other value
240 otherwise.
241
242 Here is how you might use the function @code{tgetent}:
243
244 @example
245 #ifdef unix
246 static char term_buffer[2048];
247 #else
248 #define term_buffer 0
249 #endif
250
251 init_terminal_data ()
252 @{
253   char *termtype = getenv ("TERM");
254   int success;
255
256   if (termtype == 0)
257     fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
258
259   success = tgetent (term_buffer, termtype);
260   if (success < 0)
261     fatal ("Could not access the termcap data base.\n");
262   if (success == 0)
263     fatal ("Terminal type `%s' is not defined.\n", termtype);
264 @}
265 @end example
266
267 @noindent
268 Here we assume the function @code{fatal} prints an error message and exits.
269
270 If the environment variable @code{TERMCAP} is defined, its value is used to
271 override the terminal type data base.  The function @code{tgetent} checks
272 the value of @code{TERMCAP} automatically.  If the value starts with
273 @samp{/} then it is taken as a file name to use as the data base file,
274 instead of @file{/etc/termcap} which is the standard data base.  If the
275 value does not start with @samp{/} then it is itself used as the terminal
276 description, provided that the terminal type @var{termtype} is among the
277 types it claims to apply to.  @xref{Data Base}, for information on the
278 format of a terminal description.@refill
279
280 @node Interrogate, Initialize, Find, Library
281 @section Interrogating the Terminal Description
282
283 Each piece of information recorded in a terminal description is called a
284 @dfn{capability}.  Each defined terminal capability has a two-letter code
285 name and a specific meaning.  For example, the number of columns is named
286 @samp{co}.  @xref{Capabilities}, for definitions of all the standard
287 capability names.
288
289 Once you have found the proper terminal description with @code{tgetent}
290 (@pxref{Find}), your application program must @dfn{interrogate} it for
291 various terminal capabilities.  You must specify the two-letter code of
292 the capability whose value you seek.
293
294 Capability values can be numeric, boolean (capability is either present or
295 absent) or strings.  Any particular capability always has the same value
296 type; for example, @samp{co} always has a numeric value, while @samp{am}
297 (automatic wrap at margin) is always a flag, and @samp{cm} (cursor motion
298 command) always has a string value.  The documentation of each capability
299 says which type of value it has.@refill
300
301 There are three functions to use to get the value of a capability,
302 depending on the type of value the capability has.  Here are their
303 declarations in ANSI C:
304
305 @findex tgetnum
306 @findex tgetflag
307 @findex tgetstr
308 @example
309 int tgetnum (char *@var{name});
310 int tgetflag (char *@var{name});
311 char *tgetstr (char *@var{name}, char **@var{area});
312 @end example
313
314 @table @code
315 @item tgetnum
316 Use @code{tgetnum} to get a capability value that is numeric.  The
317 argument @var{name} is the two-letter code name of the capability.  If
318 the capability is present, @code{tgetnum} returns the numeric value
319 (which is nonnegative).  If the capability is not mentioned in the
320 terminal description, @code{tgetnum} returns @minus{}1.
321
322 @item tgetflag
323 Use @code{tgetflag} to get a boolean value.  If the capability
324 @var{name} is present in the terminal description, @code{tgetflag}
325 returns 1; otherwise, it returns 0.
326
327 @item tgetstr
328 Use @code{tgetstr} to get a string value.  It returns a pointer to a
329 string which is the capability value, or a null pointer if the
330 capability is not present in the terminal description.
331
332 There are two ways @code{tgetstr} can find space to store the string value:
333
334 @itemize @bullet
335 @item
336 You can ask @code{tgetstr} to allocate the space.  Pass a null
337 pointer for the argument @var{area}, and @code{tgetstr} will use
338 @code{malloc} to allocate storage big enough for the value.
339 Termcap will never free this storage or refer to it again; you
340 should free it when you are finished with it.
341
342 This method is more robust, since there is no need to guess how
343 much space is needed.  But it is supported only by the GNU
344 termcap library.
345
346 @item
347 You can provide the space.  Provide for the argument @var{area} the
348 address of a pointer variable of type @code{char *}.  Before calling
349 @code{tgetstr}, initialize the variable to point at available space.
350 Then @code{tgetstr} will store the string value in that space and will
351 increment the pointer variable to point after the space that has been
352 used.  You can use the same pointer variable for many calls to
353 @code{tgetstr}.
354
355 There is no way to determine how much space is needed for a single
356 string, and no way for you to prevent or handle overflow of the area
357 you have provided.  However, you can be sure that the total size of
358 all the string values you will obtain from the terminal description is
359 no greater than the size of the description (unless you get the same
360 capability twice).  You can determine that size with @code{strlen} on
361 the buffer you provided to @code{tgetent}.  See below for an example.
362
363 Providing the space yourself is the only method supported by the Unix
364 version of termcap.
365 @end itemize
366 @end table
367
368 Note that you do not have to specify a terminal type or terminal
369 description for the interrogation functions.  They automatically use the
370 description found by the most recent call to @code{tgetent}.
371
372 Here is an example of interrogating a terminal description for various
373 capabilities, with conditionals to select between the Unix and GNU methods
374 of providing buffer space.
375
376 @example
377 char *tgetstr ();
378
379 char *cl_string, *cm_string;
380 int height;
381 int width;
382 int auto_wrap;
383
384 char PC;   /* For tputs.  */
385 char *BC;  /* For tgoto.  */
386 char *UP;
387
388 interrogate_terminal ()
389 @{
390 #ifdef UNIX
391   /* Here we assume that an explicit term_buffer
392      was provided to tgetent.  */
393   char *buffer
394     = (char *) malloc (strlen (term_buffer));
395 #define BUFFADDR &buffer
396 #else
397 #define BUFFADDR 0
398 #endif
399
400   char *temp;
401
402   /* Extract information we will use.  */
403   cl_string = tgetstr ("cl", BUFFADDR);
404   cm_string = tgetstr ("cm", BUFFADDR);
405   auto_wrap = tgetflag ("am");
406   height = tgetnum ("li");
407   width = tgetnum ("co");
408
409   /* Extract information that termcap functions use.  */
410   temp = tgetstr ("pc", BUFFADDR);
411   PC = temp ? *temp : 0;
412   BC = tgetstr ("le", BUFFADDR);
413   UP = tgetstr ("up", BUFFADDR);
414 @}
415 @end example
416
417 @noindent
418 @xref{Padding}, for information on the variable @code{PC}.  @xref{Using
419 Parameters}, for information on @code{UP} and @code{BC}.
420
421 @node Initialize, Padding, Interrogate, Library
422 @section Initialization for Use of Termcap
423 @cindex terminal flags (kernel)
424
425 Before starting to output commands to a terminal using termcap,
426 an application program should do two things:
427
428 @itemize @bullet
429 @item
430 Initialize various global variables which termcap library output
431 functions refer to.  These include @code{PC} and @code{ospeed} for
432 padding (@pxref{Output Padding}) and @code{UP} and @code{BC} for
433 cursor motion (@pxref{tgoto}).@refill
434
435 @item
436 Tell the kernel to turn off alteration and padding of horizontal-tab
437 characters sent to the terminal.
438 @end itemize
439
440 To turn off output processing in Berkeley Unix you would use @code{ioctl}
441 with code @code{TIOCLSET} to set the bit named @code{LLITOUT}, and clear
442 the bits @code{ANYDELAY} using @code{TIOCSETN}.  In POSIX or System V, you
443 must clear the bit named @code{OPOST}.  Refer to the system documentation
444 for details.@refill
445
446 If you do not set the terminal flags properly, some older terminals will
447 not work.  This is because their commands may contain the characters that
448 normally signify newline, carriage return and horizontal tab---characters
449 which the kernel thinks it ought to modify before output.
450
451 When you change the kernel's terminal flags, you must arrange to restore
452 them to their normal state when your program exits.  This implies that the
453 program must catch fatal signals such as @code{SIGQUIT} and @code{SIGINT}
454 and restore the old terminal flags before actually terminating.
455
456 Modern terminals' commands do not use these special characters, so if you
457 do not care about problems with old terminals, you can leave the kernel's
458 terminal flags unaltered.
459
460 @node Padding, Parameters, Initialize, Library
461 @section Padding
462 @cindex padding
463
464 @dfn{Padding} means outputting null characters following a terminal display
465 command that takes a long time to execute.  The terminal description says
466 which commands require padding and how much; the function @code{tputs},
467 described below, outputs a terminal command while extracting from it the
468 padding information, and then outputs the padding that is necessary.
469
470 @menu
471 * Why Pad::          Explanation of padding.
472 * Describe Padding:: The data base says how much padding a terminal needs.
473 * Output Padding::   Using @code{tputs} to output the needed padding.
474 @end menu
475
476 @node Why Pad, Describe Padding, Padding, Padding
477 @subsection Why Pad, and How
478
479 Most types of terminal have commands that take longer to execute than they
480 do to send over a high-speed line.  For example, clearing the screen may
481 take 20msec once the entire command is received.  During that time, on a
482 9600 bps line, the terminal could receive about 20 additional output
483 characters while still busy clearing the screen.  Every terminal has a
484 certain amount of buffering capacity to remember output characters that
485 cannot be processed yet, but too many slow commands in a row can cause the
486 buffer to fill up.  Then any additional output that cannot be processed
487 immediately will be lost.
488
489 To avoid this problem, we normally follow each display command with enough
490 useless charaters (usually null characters) to fill up the time that the
491 display command needs to execute.  This does the job if the terminal throws
492 away null characters without using up space in the buffer (which most
493 terminals do).  If enough padding is used, no output can ever be lost.  The
494 right amount of padding avoids loss of output without slowing down
495 operation, since the time used to transmit padding is time that nothing
496 else could be done.
497
498 The number of padding characters needed for an operation depends on the
499 line speed.  In fact, it is proportional to the line speed.  A 9600 baud
500 line transmits about one character per msec, so the clear screen command in
501 the example above would need about 20 characters of padding.  At 1200 baud,
502 however, only about 3 characters of padding are needed to fill up 20msec.
503
504 @node Describe Padding, Output Padding, Why Pad, Padding
505 @subsection Specifying Padding in a Terminal Description
506
507 In the terminal description, the amount of padding required by each display
508 command is recorded as a sequence of digits at the front of the command.
509 These digits specify the padding time in msec.  They can be followed
510 optionally by a decimal point and one more digit, which is a number of
511 tenths of msec.
512
513 Sometimes the padding needed by a command depends on the cursor position.
514 For example, the time taken by an ``insert line'' command is usually
515 proportional to the number of lines that need to be moved down or cleared.
516 An asterisk (@samp{*}) following the padding time says that the time
517 should be multiplied by the number of screen lines affected by the command.
518
519 @example
520 :al=1.3*\E[L:
521 @end example
522
523 @noindent
524 is used to describe the ``insert line'' command for a certain terminal.
525 The padding required is 1.3 msec per line affected.  The command itself is
526 @samp{@key{ESC} [ L}.
527
528 The padding time specified in this way tells @code{tputs} how many pad
529 characters to output.  @xref{Output Padding}.
530
531 Two special capability values affect padding for all commands.  These are
532 the @samp{pc} and @samp{pb}.  The variable @samp{pc} specifies the
533 character to pad with, and @samp{pb} the speed below which no padding is
534 needed.  The defaults for these variables, a null character and 0,
535 are correct for most terminals.  @xref{Pad Specs}.
536
537 @node Output Padding,, Describe Padding, Padding
538 @subsection Performing Padding with @code{tputs}
539 @cindex line speed
540
541 @findex tputs
542 Use the termcap function @code{tputs} to output a string containing an
543 optional padding spec of the form described above (@pxref{Describe
544 Padding}).  The function @code{tputs} strips off and decodes the padding
545 spec, outputs the rest of the string, and then outputs the appropriate
546 padding.  Here is its declaration in ANSI C:
547
548 @example
549 char PC;
550 short ospeed;
551
552 int tputs (char *@var{string}, int @var{nlines}, int (*@var{outfun}) ());
553 @end example
554
555 Here @var{string} is the string (including padding spec) to be output;
556 @var{nlines} is the number of lines affected by the operation, which is
557 used to multiply the amount of padding if the padding spec ends with a
558 @samp{*}.  Finally, @var{outfun} is a function (such as @code{fputchar})
559 that is called to output each character.  When actually called,
560 @var{outfun} should expect one argument, a character.
561
562 @vindex ospeed
563 @vindex PC
564 The operation of @code{tputs} is controlled by two global variables,
565 @code{ospeed} and @code{PC}.  The value of @code{ospeed} is supposed to be
566 the terminal output speed, encoded as in the @code{ioctl} system call which
567 gets the speed information.  This is needed to compute the number of
568 padding characters.  The value of @code{PC} is the character used for
569 padding.
570
571 You are responsible for storing suitable values into these variables before
572 using @code{tputs}.  The value stored into the @code{PC} variable should be
573 taken from the @samp{pc} capability in the terminal description (@pxref{Pad
574 Specs}).  Store zero in @code{PC} if there is no @samp{pc}
575 capability.@refill
576
577 The argument @var{nlines} requires some thought.  Normally, it should be
578 the number of lines whose contents will be cleared or moved by the command.
579 For cursor motion commands, or commands that do editing within one line,
580 use the value 1.  For most commands that affect multiple lines, such as
581 @samp{al} (insert a line) and @samp{cd} (clear from the cursor to the end
582 of the screen), @var{nlines} should be the screen height minus the current
583 vertical position (origin 0).  For multiple insert and scroll commands such
584 as @samp{AL} (insert multiple lines), that same value for @var{nlines} is
585 correct; the number of lines being inserted is @i{not} correct.@refill
586
587 If a ``scroll window'' feature is used to reduce the number of lines
588 affected by a command, the value of @var{nlines} should take this into
589 account.  This is because the delay time required depends on how much work
590 the terminal has to do, and the scroll window feature reduces the work.
591 @xref{Scrolling}.
592
593 Commands such as @samp{ic} and @samp{dc} (insert or delete characters) are
594 problematical because the padding needed by these commands is proportional
595 to the number of characters affected, which is the number of columns from
596 the cursor to the end of the line.  It would be nice to have a way to
597 specify such a dependence, and there is no need for dependence on vertical
598 position in these commands, so it is an obvious idea to say that for these
599 commands @var{nlines} should really be the number of columns affected.
600 However, the definition of termcap clearly says that @var{nlines} is always
601 the number of lines affected, even in this case, where it is always 1.  It
602 is not easy to change this rule now, because too many programs and terminal
603 descriptions have been written to follow it.
604
605 Because @var{nlines} is always 1 for the @samp{ic} and @samp{dc} strings,
606 there is no reason for them to use @samp{*}, but some of them do.  These
607 should be corrected by deleting the @samp{*}.  If, some day, such entries
608 have disappeared, it may be possible to change to a more useful convention
609 for the @var{nlines} argument for these operations without breaking any
610 programs.
611
612 @node Parameters,, Padding, Library
613 @section Filling In Parameters
614 @cindex parameters
615
616 Some terminal control strings require numeric @dfn{parameters}.  For
617 example, when you move the cursor, you need to say what horizontal and
618 vertical positions to move it to.  The value of the terminal's @samp{cm}
619 capability, which says how to move the cursor, cannot simply be a string of
620 characters; it must say how to express the cursor position numbers and
621 where to put them within the command.
622
623 The specifications of termcap include conventions as to which string-valued
624 capabilities require parameters, how many parameters, and what the
625 parameters mean; for example, it defines the @samp{cm} string to take
626 two parameters, the vertical and horizontal positions, with 0,0 being the
627 upper left corner.  These conventions are described where the individual
628 commands are documented.
629
630 Termcap also defines a language used within the capability definition for
631 specifying how and where to encode the parameters for output.  This language
632 uses character sequences starting with @samp{%}.  (This is the same idea as
633 @code{printf}, but the details are different.)  The language for parameter
634 encoding is described in this section.
635
636 A program that is doing display output calls the functions @code{tparam} or
637 @code{tgoto} to encode parameters according to the specifications.  These
638 functions produce a string containing the actual commands to be output (as
639 well a padding spec which must be processed with @code{tputs};
640 @pxref{Padding}).
641
642 @menu
643 * Encode Parameters:: The language for encoding parameters.
644 * Using Parameters::  Outputting a string command with parameters.
645 @end menu
646
647 @node Encode Parameters, Using Parameters, Parameters, Parameters
648 @subsection Describing the Encoding
649 @cindex %
650
651 A terminal command string that requires parameters contains special
652 character sequences starting with @samp{%} to say how to encode the
653 parameters.  These sequences control the actions of @code{tparam} and
654 @code{tgoto}.
655
656 The parameters values passed to @code{tparam} or @code{tgoto} are
657 considered to form a vector.  A pointer into this vector determines
658 the next parameter to be processed.  Some of the @samp{%}-sequences
659 encode one parameter and advance the pointer to the next parameter.
660 Other @samp{%}-sequences alter the pointer or alter the parameter
661 values without generating output.
662
663 For example, the @samp{cm} string for a standard ANSI terminal is written
664 as @samp{\E[%i%d;%dH}.  (@samp{\E} stands for @key{ESC}.)  @samp{cm} by
665 convention always requires two parameters, the vertical and horizontal goal
666 positions, so this string specifies the encoding of two parameters.  Here
667 @samp{%i} increments the two values supplied, and each @samp{%d} encodes
668 one of the values in decimal.  If the cursor position values 20,58 are
669 encoded with this string, the result is @samp{\E[21;59H}.
670
671 First, here are the @samp{%}-sequences that generate output.  Except for
672 @samp{%%}, each of them encodes one parameter and advances the pointer
673 to the following parameter.
674
675 @table @samp
676 @item %%
677 Output a single @samp{%}.  This is the only way to represent a literal
678 @samp{%} in a terminal command with parameters.  @samp{%%} does not
679 use up a parameter.
680
681 @item %d
682 As in @code{printf}, output the next parameter in decimal.
683
684 @item %2
685 Like @samp{%02d} in @code{printf}: output the next parameter in
686 decimal, and always use at least two digits.
687
688 @item %3
689 Like @samp{%03d} in @code{printf}: output the next parameter in
690 decimal, and always use at least three digits.  Note that @samp{%4}
691 and so on are @emph{not} defined.
692
693 @item %.
694 Output the next parameter as a single character whose ASCII code is
695 the parameter value.  Like @samp{%c} in @code{printf}.
696
697 @item %+@var{char}
698 Add the next parameter to the character @var{char}, and output the
699 resulting character.  For example, @samp{%+ } represents 0 as a space,
700 1 as @samp{!}, etc.
701 @end table
702
703 The following @samp{%}-sequences specify alteration of the parameters
704 (their values, or their order) rather than encoding a parameter for output.
705 They generate no output; they are used only for their side effects
706 on the parameters.  Also, they do not advance the ``next parameter'' pointer
707 except as explicitly stated.  Only @samp{%i}, @samp{%r} and @samp{%>} are
708 defined in standard Unix termcap.  The others are GNU extensions.@refill
709
710 @table @samp
711 @item %i
712 Increment the next two parameters.  This is used for terminals that
713 expect cursor positions in origin 1.  For example, @samp{%i%d,%d} would
714 output two parameters with @samp{1} for 0, @samp{2} for 1, etc.
715
716 @item %r
717 Interchange the next two parameters.  This is used for terminals whose
718 cursor positioning command expects the horizontal position first.
719
720 @item %s
721 Skip the next parameter.  Do not output anything.
722
723 @item %b
724 Back up one parameter.  The last parameter used will become once again
725 the next parameter to be output, and the next output command will use
726 it.  Using @samp{%b} more than once, you can back up any number of
727 parameters, and you can refer to each parameter any number of times.
728
729 @item %>@var{c1}@var{c2}
730 Conditionally increment the next parameter.  Here @var{c1} and
731 @var{c2} are characters which stand for their ASCII codes as numbers.
732 If the next parameter is greater than the ASCII code of @var{c1}, the
733 ASCII code of @var{c2} is added to it.@refill
734
735 @item %a @var{op} @var{type} @var{pos}
736 Perform arithmetic on the next parameter, do not use it up, and do not
737 output anything.  Here @var{op} specifies the arithmetic operation,
738 while @var{type} and @var{pos} together specify the other operand.
739
740 Spaces are used above to separate the operands for clarity; the spaces
741 don't appear in the data base, where this sequence is exactly five
742 characters long.
743
744 The character @var{op} says what kind of arithmetic operation to
745 perform.  It can be any of these characters:
746
747 @table @samp
748 @item =
749 assign a value to the next parameter, ignoring its old value.
750 The new value comes from the other operand.
751
752 @item +
753 add the other operand to the next parameter.
754
755 @item -
756 subtract the other operand from the next parameter.
757
758 @item *
759 multiply the next parameter by the other operand.
760
761 @item /
762 divide the next parameter by the other operand.
763 @end table
764
765 The ``other operand'' may be another parameter's value or a constant;
766 the character @var{type} says which.  It can be:
767
768 @table @samp
769 @item p
770 Use another parameter.  The character @var{pos} says which
771 parameter to use.  Subtract 64 from its ASCII code to get the
772 position of the desired parameter relative to this one.  Thus,
773 the character @samp{A} as @var{pos} means the parameter after the
774 next one; the character @samp{?} means the parameter before the
775 next one.
776
777 @item c
778 Use a constant value.  The character @var{pos} specifies the
779 value of the constant.  The 0200 bit is cleared out, so that 0200
780 can be used to represent zero.
781 @end table
782 @end table
783
784 The following @samp{%}-sequences are special purpose hacks to compensate
785 for the weird designs of obscure terminals.  They modify the next parameter
786 or the next two parameters but do not generate output and do not use up any
787 parameters.  @samp{%m} is a GNU extension; the others are defined in
788 standard Unix termcap.
789
790 @table @samp
791 @item %n
792 Exclusive-or the next parameter with 0140, and likewise the parameter
793 after next.
794
795 @item %m
796 Complement all the bits of the next parameter and the parameter after next.
797
798 @item %B
799 Encode the next parameter in BCD.  It alters the value of the
800 parameter by adding six times the quotient of the parameter by ten.
801 Here is a C statement that shows how the new value is computed:
802
803 @example
804 @var{parm} = (@var{parm} / 10) * 16 + @var{parm} % 10;
805 @end example
806
807 @item %D
808 Transform the next parameter as needed by Delta Data terminals.
809 This involves subtracting twice the remainder of the parameter by 16.
810
811 @example
812 @var{parm} -= 2 * (@var{parm} % 16);
813 @end example
814 @end table
815
816 @node Using Parameters,, Encode Parameters, Parameters
817 @subsection Sending Display Commands with Parameters
818
819 The termcap library functions @code{tparam} and @code{tgoto} serve as the
820 analog of @code{printf} for terminal string parameters.  The newer function
821 @code{tparam} is a GNU extension, more general but missing from Unix
822 termcap.  The original parameter-encoding function is @code{tgoto}, which
823 is preferable for cursor motion.
824
825 @menu
826 * tparam::   The general case, for GNU termcap only.
827 * tgoto::    The special case of cursor motion.
828 @end menu
829
830 @node tparam, tgoto, Using Parameters, Using Parameters
831 @subsubsection @code{tparam}
832
833 @findex tparam
834 The function @code{tparam} can encode display commands with any number of
835 parameters and allows you to specify the buffer space.  It is the preferred
836 function for encoding parameters for all but the @samp{cm} capability.  Its
837 ANSI C declaration is as follows:
838
839 @example
840 char *tparam (char *@var{ctlstring}, char *@var{buffer}, int @var{size}, int @var{parm1},...)
841 @end example
842
843 The arguments are a control string @var{ctlstring} (the value of a terminal
844 capability, presumably), an output buffer @var{buffer} and @var{size}, and
845 any number of integer parameters to be encoded.  The effect of
846 @code{tparam} is to copy the control string into the buffer, encoding
847 parameters according to the @samp{%} sequences in the control string.
848
849 You describe the output buffer by its address, @var{buffer}, and its size
850 in bytes, @var{size}.  If the buffer is not big enough for the data to be
851 stored in it, @code{tparam} calls @code{malloc} to get a larger buffer.  In
852 either case, @code{tparam} returns the address of the buffer it ultimately
853 uses.  If the value equals @var{buffer}, your original buffer was used.
854 Otherwise, a new buffer was allocated, and you must free it after you are
855 done with printing the results.  If you pass zero for @var{size} and
856 @var{buffer}, @code{tparam} always allocates the space with @code{malloc}.
857
858 All capabilities that require parameters also have the ability to specify
859 padding, so you should use @code{tputs} to output the string produced by
860 @code{tparam}.  @xref{Padding}.  Here is an example.
861
862 @example
863 @{
864   char *buf;
865   char buffer[40];
866
867   buf = tparam (command, buffer, 40, parm);
868   tputs (buf, 1, fputchar);
869   if (buf != buffer)
870     free (buf);
871 @}
872 @end example
873
874 If a parameter whose value is zero is encoded with @samp{%.}-style
875 encoding, the result is a null character, which will confuse @code{tputs}.
876 This would be a serious problem, but luckily @samp{%.} encoding is used
877 only by a few old models of terminal, and only for the @samp{cm}
878 capability.  To solve the problem, use @code{tgoto} rather than
879 @code{tparam} to encode the @samp{cm} capability.@refill
880
881 @node tgoto,, tparam, Using Parameters
882 @subsubsection @code{tgoto}
883
884 @findex tgoto
885 The special case of cursor motion is handled by @code{tgoto}.  There
886 are two reasons why you might choose to use @code{tgoto}:
887
888 @itemize @bullet
889 @item
890 For Unix compatibility, because Unix termcap does not have @code{tparam}.
891
892 @item
893 For the @samp{cm} capability, since @code{tgoto} has a special feature
894 to avoid problems with null characters, tabs and newlines on certain old
895 terminal types that use @samp{%.} encoding for that capability.
896 @end itemize
897
898 Here is how @code{tgoto} might be declared in ANSI C:
899
900 @example
901 char *tgoto (char *@var{cstring}, int @var{hpos}, int @var{vpos})
902 @end example
903
904 There are three arguments, the terminal description's @samp{cm} string and
905 the two cursor position numbers; @code{tgoto} computes the parametrized
906 string in an internal static buffer and returns the address of that buffer.
907 The next time you use @code{tgoto} the same buffer will be reused.
908
909 @vindex UP
910 @vindex BC
911 Parameters encoded with @samp{%.} encoding can generate null characters,
912 tabs or newlines.  These might cause trouble: the null character because
913 @code{tputs} would think that was the end of the string, the tab because
914 the kernel or other software might expand it into spaces, and the newline
915 becaue the kernel might add a carriage-return, or padding characters
916 normally used for a newline.  To prevent such problems, @code{tgoto} is
917 careful to avoid these characters.  Here is how this works: if the target
918 cursor position value is such as to cause a problem (that is to say, zero,
919 nine or ten), @code{tgoto} increments it by one, then compensates by
920 appending a string to move the cursor back or up one position.
921
922 The compensation strings to use for moving back or up are found in global
923 variables named @code{BC} and @code{UP}.  These are actual external C
924 variables with upper case names; they are declared @code{char *}.  It is up
925 to you to store suitable values in them, normally obtained from the
926 @samp{le} and @samp{up} terminal capabilities in the terminal description
927 with @code{tgetstr}.  Alternatively, if these two variables are both zero,
928 the feature of avoiding nulls, tabs and newlines is turned off.
929
930 It is safe to use @code{tgoto} for commands other than @samp{cm} only if
931 you have stored zero in @code{BC} and @code{UP}.
932
933 Note that @code{tgoto} reverses the order of its operands: the horizontal
934 position comes before the vertical position in the arguments to
935 @code{tgoto}, even though the vertical position comes before the horizontal
936 in the parameters of the @samp{cm} string.  If you use @code{tgoto} with a
937 command such as @samp{AL} that takes one parameter, you must pass the
938 parameter to @code{tgoto} as the ``vertical position''.@refill
939
940 @node Data Base, Capabilities, Library, Top
941 @chapter The Format of the Data Base
942
943 The termcap data base of terminal descriptions is stored in the file
944 @file{/etc/termcap}.  It contains terminal descriptions, blank lines, and
945 comments.
946
947 A terminal description starts with one or more names for the terminal type.
948 The information in the description is a series of @dfn{capability names}
949 and values.  The capability names have standard meanings
950 (@pxref{Capabilities}) and their values describe the terminal.
951
952 @menu
953 * Format::            Overall format of a terminal description.
954 * Capability Format:: Format of capabilities within a description.
955 * Naming::            Naming conventions for terminal types.
956 * Inheriting::        Inheriting part of a description from
957                         a related terminal type.
958 @end menu
959
960 @node Format, Capability Format, Data Base, Data Base
961 @section Terminal Description Format
962 @cindex description format
963
964 Aside from comments (lines starting with @samp{#}, which are ignored), each
965 nonblank line in the termcap data base is a terminal description.
966 A terminal description is nominally a single line, but it can be split
967 into multiple lines by inserting the two characters @samp{\ newline}.
968 This sequence is ignored wherever it appears in a description.
969
970 The preferred way to split the description is between capabilities: insert
971 the four characters @samp{: \ newline tab} immediately before any colon.
972 This allows each sub-line to start with some indentation.  This works
973 because, after the @samp{\ newline} are ignored, the result is @samp{: tab
974 :}; the first colon ends the preceding capability and the second colon
975 starts the next capability.  If you split with @samp{\ newline} alone, you
976 may not add any indentation after them.
977
978 Here is a real example of a terminal description:
979
980 @example
981 dw|vt52|DEC vt52:\
982         :cr=^M:do=^J:nl=^J:bl=^G:\
983         :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
984         :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
985         :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
986 @end example
987
988 Each terminal description begins with several names for the terminal type.
989 The names are separated by @samp{|} characters, and a colon ends the last
990 name.  The first name should be two characters long; it exists only for the
991 sake of very old Unix systems and is never used in modern systems.  The
992 last name should be a fully verbose name such as ``DEC vt52'' or ``Ann
993 Arbor Ambassador with 48 lines''.  The other names should include whatever
994 the user ought to be able to specify to get this terminal type, such as
995 @samp{vt52} or @samp{aaa-48}.  @xref{Naming}, for information on how to
996 choose terminal type names.
997
998 After the terminal type names come the terminal capabilities, separated by
999 colons and with a colon after the last one.  Each capability has a
1000 two-letter name, such as @samp{cm} for ``cursor motion string'' or @samp{li}
1001 for ``number of display lines''.
1002
1003 @node Capability Format, Naming, Format, Data Base
1004 @section Writing the Capabilities
1005
1006 There are three kinds of capabilities: flags, numbers, and strings.  Each
1007 kind has its own way of being written in the description.  Each defined
1008 capability has by convention a particular kind of value; for example,
1009 @samp{li} always has a numeric value and @samp{cm} always a string value.
1010
1011 A flag capability is thought of as having a boolean value: the value is
1012 true if the capability is present, false if not.  When the capability is
1013 present, just write its name between two colons.
1014
1015 A numeric capability has a value which is a nonnegative number.  Write the
1016 capability name, a @samp{#}, and the number, between two colons.  For
1017 example, @samp{@dots{}:li#48:@dots{}} is how you specify the @samp{li}
1018 capability for 48 lines.@refill
1019
1020 A string-valued capability has a value which is a sequence of characters.
1021 Usually these are the characters used to perform some display operation.
1022 Write the capability name, a @samp{=}, and the characters of the value,
1023 between two colons.  For example, @samp{@dots{}:cm=\E[%i%d;%dH:@dots{}} is
1024 how the cursor motion command for a standard ANSI terminal would be
1025 specified.@refill
1026
1027 Special characters in the string value can be expressed using
1028 @samp{\}-escape sequences as in C; in addition, @samp{\E} stands for
1029 @key{ESC}.  @samp{^} is also a kind of escape character; @samp{^} followed
1030 by @var{char} stands for the control-equivalent of @var{char}.  Thus,
1031 @samp{^a} stands for the character control-a, just like @samp{\001}.
1032 @samp{\} and @samp{^} themselves can be represented as @samp{\\} and
1033 @samp{\^}.@refill
1034
1035 To include a colon in the string, you must write @samp{\072}.  You might
1036 ask, ``Why can't @samp{\:} be used to represent a colon?''  The reason is
1037 that the interrogation functions do not count slashes while looking for a
1038 capability.  Even if @samp{:ce=ab\:cd:} were interpreted as giving the
1039 @samp{ce} capability the value @samp{ab:cd}, it would also appear to define
1040 @samp{cd} as a flag.
1041
1042 The string value will often contain digits at the front to specify padding
1043 (@pxref{Padding}) and/or @samp{%}-sequences within to specify how to encode
1044 parameters (@pxref{Parameters}).  Although these things are not to be
1045 output literally to the terminal, they are considered part of the value of
1046 the capability.  They are special only when the string value is processed
1047 by @code{tputs}, @code{tparam} or @code{tgoto}.  By contrast, @samp{\} and
1048 @samp{^} are considered part of the syntax for specifying the characters
1049 in the string.
1050
1051 Let's look at the VT52 example again:
1052
1053 @example
1054 dw|vt52|DEC vt52:\
1055         :cr=^M:do=^J:nl=^J:bl=^G:\
1056         :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
1057         :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
1058         :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
1059 @end example
1060
1061 Here we see the numeric-valued capabilities @samp{co} and @samp{li}, the
1062 flags @samp{bs} and @samp{pt}, and many string-valued capabilities.  Most
1063 of the strings start with @key{ESC} represented as @samp{\E}.  The rest
1064 contain control characters represented using @samp{^}.  The meanings of the
1065 individual capabilities are defined elsewhere (@pxref{Capabilities}).
1066
1067 @node Naming, Inheriting, Capability Format, Data Base
1068 @section Terminal Type Name Conventions
1069 @cindex names of terminal types
1070
1071 There are conventions for choosing names of terminal types.  For one thing,
1072 all letters should be in lower case.  The terminal type for a terminal in
1073 its most usual or most fundamental mode of operation should not have a
1074 hyphen in it.
1075
1076 If the same terminal has other modes of operation which require
1077 different terminal descriptions, these variant descriptions are given
1078 names made by adding suffixes with hyphens.  Such alternate descriptions
1079 are used for two reasons:
1080
1081 @itemize @bullet
1082 @item
1083 When the terminal has a switch that changes its behavior.  Since the
1084 computer cannot tell how the switch is set, the user must tell the
1085 computer by choosing the appropriate terminal type name.
1086
1087 @cindex wrapping
1088 For example, the VT-100 has a setup flag that controls whether the
1089 cursor wraps at the right margin.  If this flag is set to ``wrap'',
1090 you must use the terminal type @samp{vt100-am}.  Otherwise you must
1091 use @samp{vt100-nam}.  Plain @samp{vt100} is defined as a synonym for
1092 either @samp{vt100-am} or @samp{vt100-nam} depending on the
1093 preferences of the local site.@refill
1094
1095 The standard suffix @samp{-am} stands for ``automatic margins''.
1096
1097 @item
1098 To give the user a choice in how to use the terminal.  This is done
1099 when the terminal has a switch that the computer normally controls.
1100
1101 @cindex screen size
1102 For example, the Ann Arbor Ambassador can be configured with many
1103 screen sizes ranging from 20 to 60 lines.  Fewer lines make bigger
1104 characters but more lines let you see more of what you are editing.
1105 As a result, users have different preferences.  Therefore, termcap
1106 provides terminal types for many screen sizes.  If you choose type
1107 @samp{aaa-30}, the terminal will be configured to use 30 lines; if you
1108 choose @samp{aaa-48}, 48 lines will be used, and so on.
1109 @end itemize
1110
1111 Here is a list of standard suffixes and their conventional meanings:
1112
1113 @table @samp
1114 @item -w
1115 Short for ``wide''.  This is a mode that gives the terminal more
1116 columns than usual.  This is normally a user option.
1117
1118 @item -am
1119 ``Automatic margins''.  This is an alternate description for use when
1120 the terminal's margin-wrap switch is on; it contains the @samp{am}
1121 flag.  The implication is that normally the switch is off and the
1122 usual description for the terminal says that the switch is off.
1123
1124 @item -nam
1125 ``No automatic margins''.  The opposite of @samp{-am}, this names an
1126 alternative description which lacks the @samp{am} flag.  This implies
1127 that the terminal is normally operated with the margin-wrap switch
1128 turned on, and the normal description of the terminal says so.
1129
1130 @item -na
1131 ``No arrows''.  This terminal description initializes the terminal to
1132 keep its arrow keys in local mode.  This is a user option.
1133
1134 @item -rv
1135 ``Reverse video''.  This terminal description causes text output for
1136 normal video to appear as reverse, and text output for reverse video
1137 to come out as normal.  Often this description differs from the usual
1138 one by interchanging the two strings which turn reverse video on and
1139 off.@refill
1140
1141 This is a user option; you can choose either the ``reverse video''
1142 variant terminal type or the normal terminal type, and termcap will
1143 obey.
1144
1145 @item -s
1146 ``Status''.  Says to enable use of a status line which ordinary output
1147 does not touch (@pxref{Status Line}).
1148
1149 Some terminals have a special line that is used only as a status line.
1150 For these terminals, there is no need for a @samp{-s} variant; the
1151 status line commands should be defined by default.  On other
1152 terminals, enabling a status line means removing one screen line from
1153 ordinary use and reducing the effective screen height.  For these
1154 terminals, the user can choose the @samp{-s} variant type to request
1155 use of a status line.
1156
1157 @item -@var{nlines}
1158 Says to operate with @var{nlines} lines on the screen, for terminals
1159 such as the Ambassador which provide this as an option.  Normally this
1160 is a user option; by choosing the terminal type, you control how many
1161 lines termcap will use.
1162
1163 @item -@var{npages}p
1164 Says that the terminal has @var{npages} pages worth of screen memory,
1165 for terminals where this is a hardware option.
1166
1167 @item -unk
1168 Says that description is not for direct use, but only for reference in
1169 @samp{tc} capabilities.  Such a description is a kind of subroutine,
1170 because it describes the common characteristics of several variant
1171 descriptions that would use other suffixes in place of @samp{-unk}.
1172 @end table
1173
1174 @node Inheriting,, Naming, Data Base
1175 @section Inheriting from Related Descriptions
1176
1177 @cindex inheritance
1178 When two terminal descriptions are similar, their identical parts do not
1179 need to be given twice.  Instead, one of the two can be defined in terms of
1180 the other, using the @samp{tc} capability.  We say that one description
1181 @dfn{refers to} the other, or @dfn{inherits from} the other.
1182
1183 The @samp{tc} capability must be the last one in the terminal description,
1184 and its value is a string which is the name of another terminal type which
1185 is referred to.  For example,
1186
1187 @example
1188 N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
1189         :ti=\E[2J\E[30;0;0;30p:\
1190         :te=\E[60;0;0;30p\E[30;1H\E[J:\
1191         :li#30:tc=aaa-unk:
1192 @end example
1193
1194 @noindent
1195 defines the terminal type @samp{aaa-30} (also known as plain @samp{aaa}) in
1196 terms of @samp{aaa-unk}, which defines everything about the Ambassador that
1197 is independent of screen height.  The types @samp{aaa-36}, @samp{aaa-48}
1198 and so on for other screen heights are likewise defined to inherit from
1199 @samp{aaa-unk}.
1200
1201 The capabilities overridden by @samp{aaa-30} include @samp{li}, which says
1202 how many lines there are, and @samp{ti} and @samp{te}, which configure the
1203 terminal to use that many lines.
1204
1205 The effective terminal description for type @samp{aaa} consists of the text
1206 shown above followed by the text of the description of @samp{aaa-unk}.  The
1207 @samp{tc} capability is handled automatically by @code{tgetent}, which
1208 finds the description thus referenced and combines the two descriptions
1209 (@pxref{Find}).  Therefore, only the implementor of the terminal
1210 descriptions needs to think about using @samp{tc}.  Users and application
1211 programmers do not need to be concerned with it.
1212
1213 Since the reference terminal description is used last, capabilities
1214 specified in the referring description override any specifications of the
1215 same capabilities in the reference description.
1216
1217 The referring description can cancel out a capability without specifying
1218 any new value for it by means of a special trick.  Write the capability in
1219 the referring description, with the character @samp{@@} after the capability
1220 name, as follows:
1221
1222 @example
1223 NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
1224         :am@@:tc=aaa-30:
1225 @end example
1226
1227 @node Capabilities, Summary, Data Base, Top
1228 @chapter Definitions of the Terminal Capabilities
1229
1230 This section is divided into many subsections, each for one aspect of
1231 use of display terminals.  For writing a display program, you usually need
1232 only check the subsections for the operations you want to use.  For writing
1233 a terminal description, you must read each subsection and fill in the
1234 capabilities described there.
1235
1236 String capabilities that are display commands may require numeric
1237 parameters (@pxref{Parameters}).  Most such capabilities do not use
1238 parameters.  When a capability requires parameters, this is explicitly
1239 stated at the beginning of its definition.  In simple cases, the first or
1240 second sentence of the definition mentions all the parameters, in the order
1241 they should be given, using a name
1242 @iftex
1243 in italics
1244 @end iftex
1245 @ifinfo
1246 in upper case
1247 @end ifinfo
1248 for each one.  For example, the @samp{rp} capability is a command that
1249 requires two parameters; its definition begins as follows:
1250
1251 @quotation
1252 String of commands to output a graphic character @var{c}, repeated @var{n}
1253 times.
1254 @end quotation
1255
1256 In complex cases or when there are many parameters, they are described
1257 explicitly.
1258
1259 When a capability is described as obsolete, this means that programs should
1260 not be written to look for it, but terminal descriptions should still be
1261 written to provide it.
1262
1263 When a capability is described as very obsolete, this means that it should
1264 be omitted from terminal descriptions as well.
1265
1266 @menu
1267 * Basic::             Basic characteristics.
1268 * Screen Size::       Screen size, and what happens when it changes.
1269 * Cursor Motion::     Various ways to move the cursor.
1270 * Scrolling::         Pushing text up and down on the screen.
1271 * Wrapping::          What happens if you write a character in the last column.
1272 * Windows::           Limiting the part of the window that output affects.
1273 * Clearing::          Erasing one or many lines.
1274 * Insdel Line::       Making new blank lines in mid-screen; deleting lines.
1275 * Insdel Char::       Inserting and deleting characters within a line.
1276 * Standout::          Highlighting some of the text.
1277 * Underlining::       Underlining some of the text.
1278 * Cursor Visibility:: Making the cursor more or less easy to spot.
1279 * Bell::              Attracts user's attention; not localized on the screen.
1280 * Keypad::            Recognizing when function keys or arrows are typed.
1281 * Meta Key::          @key{META} acts like an extra shift key.
1282 * Initialization::    Commands used to initialize or reset the terminal.
1283 * Pad Specs::         Info for the kernel on how much padding is needed.
1284 * Status Line::       A status line displays ``background'' information.
1285 * Half-Line::         Moving by half-lines, for superscripts and subscripts.
1286 * Printer::           Controlling auxiliary printers of display terminals.
1287 @end menu
1288
1289 @node Basic, Screen Size, Capabilities, Capabilities
1290 @section Basic Characteristics
1291
1292 This section documents the capabilities that describe the basic and
1293 nature of the terminal, and also those that are relevant to the output
1294 of graphic characters.
1295
1296 @table @samp
1297 @item os
1298 @kindex os
1299 @cindex overstrike
1300 Flag whose presence means that the terminal can overstrike.  This
1301 means that outputting a graphic character does not erase whatever was
1302 present in the same character position before.  The terminals that can
1303 overstrike include printing terminals, storage tubes (all obsolete
1304 nowadays), and many bit-map displays.
1305
1306 @item eo
1307 @kindex eo
1308 Flag whose presence means that outputting a space can erase an
1309 overstrike.  If this is not present and overstriking is supported,
1310 output of a space has no effect except to move the cursor.
1311
1312 @item gn
1313 @kindex gn
1314 @cindex generic terminal type
1315 Flag whose presence means that this terminal type is a generic type
1316 which does not really describe any particular terminal.  Generic types
1317 are intended for use as the default type assigned when the user
1318 connects to the system, with the intention that the user should
1319 specify what type he really has.  One example of a generic type
1320 is the type @samp{network}.
1321
1322 Since the generic type cannot say how to do anything interesting with
1323 the terminal, termcap-using programs will always find that the
1324 terminal is too weak to be supported if the user has failed to specify
1325 a real terminal type in place of the generic one.  The @samp{gn} flag
1326 directs these programs to use a different error message: ``You have
1327 not specified your real terminal type'', rather than ``Your terminal
1328 is not powerful enough to be used''.
1329
1330 @item hc
1331 @kindex hc
1332 Flag whose presence means this is a hardcopy terminal.
1333
1334 @item rp
1335 @kindex rp
1336 @cindex repeat output
1337 String of commands to output a graphic character @var{c}, repeated @var{n}
1338 times.  The first parameter value is the ASCII code for the desired
1339 character, and the second parameter is the number of times to repeat the
1340 character.  Often this command requires padding proportional to the 
1341 number of times the character is repeated.  This effect can be had by
1342 using parameter arithmetic with @samp{%}-sequences to compute the
1343 amount of padding, then generating the result as a number at the front
1344 of the string so that @code{tputs} will treat it as padding.
1345
1346 @item hz
1347 @kindex hz
1348 Flag whose presence means that the ASCII character @samp{~} cannot be
1349 output on this terminal because it is used for display commands.
1350
1351 Programs handle this flag by checking all text to be output and
1352 replacing each @samp{~} with some other character(s).  If this is not
1353 done, the screen will be thoroughly garbled.
1354
1355 The old Hazeltine terminals that required such treatment are probably
1356 very rare today, so you might as well not bother to support this flag.
1357
1358 @item CC
1359 @kindex CC
1360 @cindex command character
1361 String whose presence means the terminal has a settable command
1362 character.  The value of the string is the default command character
1363 (which is usually @key{ESC}).
1364
1365 All the strings of commands in the terminal description should be
1366 written to use the default command character.  If you are writing an
1367 application program that changes the command character, use the
1368 @samp{CC} capability to figure out how to translate all the display
1369 commands to work with the new command character.
1370
1371 Most programs have no reason to look at the @samp{CC} capability.
1372
1373 @item xb
1374 @kindex xb
1375 @cindex Superbee
1376 Flag whose presence identifies Superbee terminals which are unable to
1377 transmit the characters @key{ESC} and @kbd{Control-C}.  Programs which
1378 support this flag are supposed to check the input for the code sequences
1379 sent by the @key{F1} and @key{F2} keys, and pretend that @key{ESC}
1380 or @kbd{Control-C} (respectively) had been read.  But this flag is
1381 obsolete, and not worth supporting.
1382 @end table
1383
1384 @node Screen Size, Cursor Motion, Basic, Capabilities
1385 @section Screen Size
1386 @cindex screen size
1387
1388 A terminal description has two capabilities, @samp{co} and @samp{li},
1389 that describe the screen size in columns and lines.  But there is more
1390 to the question of screen size than this.
1391
1392 On some operating systems the ``screen'' is really a window and the
1393 effective width can vary.  On some of these systems, @code{tgetnum}
1394 uses the actual width of the window to decide what value to return for
1395 the @samp{co} capability, overriding what is actually written in the
1396 terminal description.  On other systems, it is up to the application
1397 program to check the actual window width using a system call.  For
1398 example, on BSD 4.3 systems, the system call @code{ioctl} with code
1399 @code{TIOCGWINSZ} will tell you the current screen size.
1400
1401 On all window systems, termcap is powerless to advise the application
1402 program if the user resizes the window.  Application programs must
1403 deal with this possibility in a system-dependent fashion.  On some
1404 systems the C shell handles part of the problem by detecting changes
1405 in window size and setting the @code{TERMCAP} environment variable
1406 appropriately.  This takes care of application programs that are
1407 started subsequently.  It does not help application programs already
1408 running.
1409
1410 On some systems, including BSD 4.3, all programs using a terminal get
1411 a signal named @code{SIGWINCH} whenever the screen size changes.
1412 Programs that use termcap should handle this signal by using
1413 @code{ioctl TIOCGWINSZ} to learn the new screen size.
1414
1415 @table @samp
1416 @item co
1417 @kindex co
1418 @cindex screen size
1419 Numeric value, the width of the screen in character positions.  Even
1420 hardcopy terminals normally have a @samp{co} capability.
1421
1422 @item li
1423 @kindex li
1424 Numeric value, the height of the screen in lines.
1425 @end table
1426
1427 @node Cursor Motion, Wrapping, Screen Size, Capabilities
1428 @section Cursor Motion
1429 @cindex cursor motion
1430
1431 Termcap assumes that the terminal has a @dfn{cursor}, a spot on the screen
1432 where a visible mark is displayed, and that most display commands take
1433 effect at the position of the cursor.  It follows that moving the cursor
1434 to a specified location is very important.
1435
1436 There are many terminal capabilities for different cursor motion
1437 operations.  A terminal description should define as many as possible, but
1438 most programs do not need to use most of them.  One capability, @samp{cm},
1439 moves the cursor to an arbitrary place on the screen; this by itself is
1440 sufficient for any application as long as there is no need to support
1441 hardcopy terminals or certain old, weak displays that have only relative
1442 motion commands.  Use of other cursor motion capabilities is an
1443 optimization, enabling the program to output fewer characters in some
1444 common cases.
1445
1446 If you plan to use the relative cursor motion commands in an application
1447 program, you must know what the starting cursor position is.  To do this,
1448 you must keep track of the cursor position and update the records each
1449 time anything is output to the terminal, including graphic characters.
1450 In addition, it is necessary to know whether the terminal wraps after
1451 writing in the rightmost column.  @xref{Wrapping}.
1452
1453 One other motion capability needs special mention: @samp{nw} moves the
1454 cursor to the beginning of the following line, perhaps clearing all the
1455 starting line after the cursor, or perhaps not clearing at all.  This
1456 capability is a least common denominator that is probably supported even by
1457 terminals that cannot do most other things such as @samp{cm} or @samp{do}.
1458 Even hardcopy terminals can support @samp{nw}.
1459
1460 @table @asis
1461 @item @samp{cm}
1462 @kindex cm
1463 String of commands to position the cursor at line @var{l}, column @var{c}.
1464 Both parameters are origin-zero, and are defined relative to the
1465 screen, not relative to display memory.
1466
1467 All display terminals except a few very obsolete ones support @samp{cm},
1468 so it is acceptable for an application program to refuse to operate on
1469 terminals lacking @samp{cm}.
1470
1471 @item @samp{ho}
1472 @kindex ho
1473 @cindex home position
1474 String of commands to move the cursor to the upper left corner of the
1475 screen (this position is called the @dfn{home position}).  In
1476 terminals where the upper left corner of the screen is not the same as
1477 the beginning of display memory, this command must go to the upper
1478 left corner of the screen, not the beginning of display memory.
1479
1480 Every display terminal supports this capability, and many application
1481 programs refuse to operate if the @samp{ho} capability is missing.
1482
1483 @item @samp{ll}
1484 @kindex ll
1485 String of commands to move the cursor to the lower left corner of the
1486 screen.  On some terminals, moving up from home position does this,
1487 but programs should never assume that will work.  Just output the
1488 @samp{ll} string (if it is provided); if moving to home position and
1489 then moving up is the best way to get there, the @samp{ll} command
1490 will do that.
1491
1492 @item @samp{cr}
1493 @kindex cr
1494 String of commands to move the cursor to the beginning of the line it
1495 is on.  If this capability is not specified, many programs assume
1496 they can use the ASCII carriage return character for this.
1497
1498 @item @samp{le}
1499 @kindex le
1500 String of commands to move the cursor left one column.  Unless the
1501 @samp{bw} flag capability is specified, the effect is undefined if the
1502 cursor is at the left margin; do not use this command there.  If
1503 @samp{bw} is present, this command may be used at the left margin, and
1504 it wraps the cursor to the last column of the preceding line.
1505
1506 @item @samp{nd}
1507 @kindex nd
1508 String of commands to move the cursor right one column.  The effect is
1509 undefined if the cursor is at the right margin; do not use this
1510 command there, not even if @samp{am} is present.
1511
1512 @item @samp{up}
1513 @kindex up
1514 String of commands to move the cursor vertically up one line.  The
1515 effect of sending this string when on the top line is undefined;
1516 programs should never use it that way.
1517
1518 @item @samp{do}
1519 @kindex do
1520 String of commands to move the cursor vertically down one line.  The
1521 effect of sending this string when on the bottom line is undefined;
1522 programs should never use it that way.
1523
1524 The original idea was that this string would not contain a newline
1525 character and therefore could be used without disabling the kernel's usual
1526 habit of converting of newline into a carriage-return newline sequence.
1527 But many terminal descriptions do use newline in the @samp{do} string, so
1528 this is not possible; a program which sends the @samp{do} string must
1529 disable output conversion in the kernel (@pxref{Initialize}).
1530
1531 @item @samp{bw}
1532 @kindex bw
1533 Flag whose presence says that @samp{le} may be used in column zero
1534 to move to the last column of the preceding line.  If this flag
1535 is not present, @samp{le} should not be used in column zero.
1536
1537 @item @samp{nw}
1538 @kindex nw
1539 String of commands to move the cursor to start of next line, possibly
1540 clearing rest of line (following the cursor) before moving.
1541
1542 @item @samp{DO}, @samp{UP}, @samp{LE}, @samp{RI}
1543 @kindex DO
1544 @kindex LE
1545 @kindex RI
1546 @kindex UP
1547 Strings of commands to move the cursor @var{n} lines down vertically,
1548 up vertically, or @var{n} columns left or right.  Do not attempt to
1549 move past any edge of the screen with these commands; the effect of
1550 trying that is undefined.  Only a few terminal descriptions provide
1551 these commands, and most programs do not use them.
1552
1553 @item @samp{CM}
1554 @kindex CM
1555 String of commands to position the cursor at line @var{l}, column
1556 @var{c}, relative to display memory.  Both parameters are origin-zero.
1557 This capability is present only in terminals where there is a
1558 difference between screen-relative and memory-relative addressing, and
1559 not even in all such terminals.
1560
1561 @item @samp{ch}
1562 @kindex ch
1563 String of commands to position the cursor at column @var{c} in the
1564 same line it is on.  This is a special case of @samp{cm} in which the
1565 vertical position is not changed.  The @samp{ch} capability is
1566 provided only when it is faster to output than @samp{cm} would be in
1567 this special case.  Programs should not assume most display terminals
1568 have @samp{ch}.
1569
1570 @item @samp{cv}
1571 @kindex cv
1572 String of commands to position the cursor at line @var{l} in the same
1573 column.  This is a special case of @samp{cm} in which the horizontal
1574 position is not changed.  The @samp{cv} capability is provided only
1575 when it is faster to output than @samp{cm} would be in this special
1576 case.  Programs should not assume most display terminals have
1577 @samp{cv}.
1578
1579 @item @samp{sc}
1580 @kindex sc
1581 String of commands to make the terminal save the current cursor
1582 position.  Only the last saved position can be used.  If this
1583 capability is present, @samp{rc} should be provided also.  Most
1584 terminals have neither.
1585
1586 @item @samp{rc}
1587 @kindex rc
1588 String of commands to make the terminal restore the last saved cursor
1589 position.  If this capability is present, @samp{sc} should be provided
1590 also.  Most terminals have neither.
1591
1592 @item @samp{ff}
1593 @kindex ff
1594 String of commands to advance to the next page, for a hardcopy
1595 terminal.
1596
1597 @item @samp{ta}
1598 @kindex ta
1599 String of commands to move the cursor right to the next hardware tab
1600 stop column.  Missing if the terminal does not have any kind of
1601 hardware tabs.  Do not send this command if the kernel's terminal
1602 modes say that the kernel is expanding tabs into spaces.
1603
1604 @item @samp{bt}
1605 @kindex bt
1606 String of commands to move the cursor left to the previous hardware
1607 tab stop column.  Missing if the terminal has no such ability; many
1608 terminals do not.  Do not send this command if the kernel's terminal
1609 modes say that the kernel is expanding tabs into spaces.
1610 @end table
1611
1612 The following obsolete capabilities should be included in terminal
1613 descriptions when appropriate, but should not be looked at by new programs.
1614
1615 @table @samp
1616 @item nc
1617 @kindex nc
1618 Flag whose presence means the terminal does not support the ASCII
1619 carriage return character as @samp{cr}.  This flag is needed because
1620 old programs assume, when the @samp{cr} capability is missing, that
1621 ASCII carriage return can be used for the purpose.  We use @samp{nc}
1622 to tell the old programs that carriage return may not be used.
1623
1624 New programs should not assume any default for @samp{cr}, so they need
1625 not look at @samp{nc}.  However, descriptions should contain @samp{nc}
1626 whenever they do not contain @samp{cr}.
1627
1628 @item xt
1629 @kindex xt
1630 Flag whose presence means that the ASCII tab character may not be used
1631 for cursor motion.  This flag exists because old programs assume, when
1632 the @samp{ta} capability is missing, that ASCII tab can be used for
1633 the purpose.  We use @samp{xt} to tell the old programs not to use tab.
1634
1635 New programs should not assume any default for @samp{ta}, so they need
1636 not look at @samp{xt} in connection with cursor motion.  Note that
1637 @samp{xt} also has implications for standout mode (@pxref{Standout}).
1638 It is obsolete in regard to cursor motion but not in regard to
1639 standout.
1640
1641 In fact, @samp{xt} means that the terminal is a Teleray 1061.
1642
1643 @item bc
1644 @kindex bc
1645 Very obsolete alternative name for the @samp{le} capability.
1646
1647 @item bs
1648 @kindex bs
1649 Flag whose presence means that the ASCII character backspace may be
1650 used to move the cursor left.  Obsolete; look at @samp{le} instead.
1651
1652 @item nl
1653 @kindex nl
1654 Obsolete capability which is a string that can either be used to move
1655 the cursor down or to scroll.  The same string must scroll when used
1656 on the bottom line and move the cursor when used on any other line.
1657 New programs should use @samp{do} or @samp{sf}, and ignore @samp{nl}.
1658
1659 If there is no @samp{nl} capability, some old programs assume they can
1660 use the newline character for this purpose.  These programs follow a
1661 bad practice, but because they exist, it is still desirable to define
1662 the @samp{nl} capability in a terminal description if the best way to
1663 move down is @emph{not} a newline.
1664 @end table
1665
1666 @node Wrapping, Scrolling, Cursor Motion, Capabilities
1667 @section Wrapping
1668 @cindex wrapping
1669
1670 @dfn{Wrapping} means moving the cursor from the right margin to the left
1671 margin of the following line.  Some terminals wrap automatically when a
1672 graphic character is output in the last column, while others do not.  Most
1673 application programs that use termcap need to know whether the terminal
1674 wraps.  There are two special flag capabilities to describe what the
1675 terminal does when a graphic character is output in the last column.
1676
1677 @table @samp
1678 @item am
1679 @kindex am
1680 Flag whose presence means that writing a character in the last column
1681 causes the cursor to wrap to the beginning of the next line.
1682
1683 If @samp{am} is not present, writing in the last column leaves the
1684 cursor at the place where the character was written.
1685
1686 Writing in the last column of the last line should be avoided on
1687 terminals with @samp{am}, as it may or may not cause scrolling to
1688 occur (@pxref{Scrolling}).  Scrolling is surely not what you would
1689 intend.
1690
1691 If your program needs to check the @samp{am} flag, then it also needs
1692 to check the @samp{xn} flag which indicates that wrapping happens in a
1693 strange way.  Many common terminals have the @samp{xn} flag.
1694
1695 @item xn
1696 @kindex xn
1697 Flag whose presence means that the cursor wraps in a strange way.  At
1698 least two distinct kinds of strange behavior are known; the termcap
1699 data base does not contain anything to distinguish the two.
1700
1701 On Concept-100 terminals, output in the last column wraps the cursor
1702 almost like an ordinary @samp{am} terminal.  But if the next thing
1703 output is a newline, it is ignored.
1704
1705 DEC VT-100 terminals (when the wrap switch is on) do a different
1706 strange thing: the cursor wraps only if the next thing output is
1707 another graphic character.  In fact, the wrap occurs when the
1708 following graphic character is received by the terminal, before the
1709 character is placed on the screen.
1710
1711 On both of these terminals, after writing in the last column a
1712 following graphic character will be displayed in the first column of
1713 the following line.  But the effect of relative cursor motion
1714 characters such as newline or backspace at such a time depends on the
1715 terminal.  The effect of erase or scrolling commands also depends on
1716 the terminal.  You can't assume anything about what they will do on a
1717 terminal that has @samp{xn}.  So, to be safe, you should never do
1718 these things at such a time on such a terminal.
1719
1720 To be sure of reliable results on a terminal which has the @samp{xn}
1721 flag, output a @samp{cm} absolute positioning command after writing in
1722 the last column.  Another safe thing to do is to output carriage-return
1723 newline, which will leave the cursor at the beginning of the following
1724 line.
1725 @end table
1726
1727 @node Scrolling, Windows, Wrapping, Capabilities
1728 @section Scrolling
1729 @cindex scrolling
1730
1731 @dfn{Scrolling} means moving the contents of the screen up or down one or
1732 more lines.  Moving the contents up is @dfn{forward scrolling}; moving them
1733 down is @dfn{reverse scrolling}.
1734
1735 Scrolling happens after each line of output during ordinary output on most
1736 display terminals.  But in an application program that uses termcap for
1737 random-access output, scrolling happens only when explicitly requested with
1738 the commands in this section.
1739
1740 Some terminals have a @dfn{scroll region} feature.  This lets you limit
1741 the effect of scrolling to a specified range of lines.  Lines outside the
1742 range are unaffected when scrolling happens.  The scroll region feature
1743 is available if either @samp{cs} or @samp{cS} is present.
1744
1745 @table @samp
1746 @item sf
1747 @kindex sf
1748 String of commands to scroll the screen one line up, assuming it is
1749 output with the cursor at the beginning of the bottom line.
1750
1751 @item sr
1752 @kindex sr
1753 String of commands to scroll the screen one line down, assuming it is
1754 output with the cursor at the beginning of the top line.
1755
1756 @item SF
1757 @kindex SF
1758 String of commands to scroll the screen @var{n} lines up, assuming it
1759 is output with the cursor at the beginning of the bottom line.
1760
1761 @item SR
1762 @kindex SR
1763 String of commands to scroll the screen @var{n} line down, assuming it
1764 is output with the cursor at the beginning of the top line.
1765
1766 @item cs
1767 @kindex cs
1768 String of commands to set the scroll region.  This command takes two
1769 parameters, @var{start} and @var{end}, which are the line numbers
1770 (origin-zero) of the first line to include in the scroll region and of
1771 the last line to include in it.  When a scroll region is set,
1772 scrolling is limited to the specified range of lines; lines outside
1773 the range are not affected by scroll commands.
1774
1775 Do not try to move the cursor outside the scroll region.  The region
1776 remains set until explicitly removed.  To remove the scroll region,
1777 use another @samp{cs} command specifying the full height of the
1778 screen.
1779
1780 The cursor position is undefined after the @samp{cs} command is set,
1781 so position the cursor with @samp{cm} immediately afterward.
1782
1783 @item cS
1784 @kindex cS
1785 String of commands to set the scroll region using parameters in
1786 different form.  The effect is the same as if @samp{cs} were used.
1787 Four parameters are required:
1788
1789 @enumerate
1790 @item
1791 Total number of lines on the screen.
1792 @item
1793 Number of lines above desired scroll region.
1794 @item
1795 Number of lines below (outside of) desired scroll region.
1796 @item
1797 Total number of lines on the screen, the same as the first parameter.
1798 @end enumerate
1799
1800 This capability is a GNU extension that was invented to allow the Ann
1801 Arbor Ambassador's scroll-region command to be described; it could
1802 also be done by putting non-Unix @samp{%}-sequences into a @samp{cs}
1803 string, but that would have confused Unix programs that used the
1804 @samp{cs} capability with the Unix termcap.  Currently only GNU Emacs
1805 uses the @samp{cS} capability.
1806
1807 @item ns
1808 @kindex ns
1809 Flag which means that the terminal does not normally scroll for
1810 ordinary sequential output.  For modern terminals, this means that
1811 outputting a newline in ordinary sequential output with the cursor on
1812 the bottom line wraps to the top line.  For some obsolete terminals,
1813 other things may happen.
1814
1815 The terminal may be able to scroll even if it does not normally do so.
1816 If the @samp{sf} capability is provided, it can be used for scrolling
1817 regardless of @samp{ns}.
1818
1819 @item da
1820 @kindex da
1821 Flag whose presence means that lines scrolled up off the top of the
1822 screen may come back if scrolling down is done subsequently.
1823
1824 The @samp{da} and @samp{db} flags do not, strictly speaking, affect
1825 how to scroll.  But programs that scroll usually need to clear the
1826 lines scrolled onto the screen, if these flags are present.
1827
1828 @item db
1829 @kindex db
1830 Flag whose presence means that lines scrolled down off the bottom of
1831 the screen may come back if scrolling up is done subsequently.
1832
1833 @item lm
1834 @kindex lm
1835 Numeric value, the number of lines of display memory that the terminal
1836 has.  A value of zero means that the terminal has more display memory
1837 than can fit on the screen, but no fixed number of lines.  (The number
1838 of lines may depend on the amount of text in each line.)
1839 @end table
1840
1841 Any terminal description that defines @samp{SF} should also define @samp{sf};
1842 likewise for @samp{SR} and @samp{sr}.  However, many terminals can only
1843 scroll by one line at a time, so it is common to find @samp{sf} and not
1844 @samp{SF}, or @samp{sr} without @samp{SR}.@refill
1845
1846 Therefore, all programs that use the scrolling facilities should be
1847 prepared to work with @samp{sf} in the case that @samp{SF} is absent, and
1848 likewise with @samp{sr}.  On the other hand, an application program that
1849 uses only @samp{sf} and not @samp{SF} is acceptable, though slow on some
1850 terminals.@refill
1851
1852 When outputting a scroll command with @code{tputs}, the @var{nlines}
1853 argument should be the total number of lines in the portion of the screen
1854 being scrolled.  Very often these commands require padding proportional to
1855 this number of lines.  @xref{Padding}.
1856
1857 @node Windows, Clearing, Scrolling, Capabilities
1858 @section Windows
1859 @cindex window
1860
1861 A @dfn{window}, in termcap, is a rectangular portion of the screen to which
1862 all display operations are restricted.  Wrapping, clearing, scrolling,
1863 insertion and deletion all operate as if the specified window were all the
1864 screen there was.
1865
1866 @table @samp
1867 @item wi
1868 @kindex wi
1869 String of commands to set the terminal output screen window.
1870 This string requires four parameters, all origin-zero:
1871 @enumerate
1872 @item
1873 The first line to include in the window.
1874 @item
1875 The last line to include in the window.
1876 @item
1877 The first column to include in the window.
1878 @item
1879 The last column to include in the window.
1880 @end enumerate
1881 @end table
1882
1883 Most terminals do not support windows.
1884
1885 @node Clearing, Insdel Line, Windows, Capabilities
1886 @section Clearing Parts of the Screen
1887 @cindex erasing
1888 @cindex clearing the screen
1889
1890 There are several terminal capabilities for clearing parts of the screen
1891 to blank.  All display terminals support the @samp{cl} string, and most
1892 display terminals support all of these capabilities.
1893
1894 @table @samp
1895 @item cl
1896 @kindex cl
1897 String of commands to clear the entire screen and position the cursor
1898 at the upper left corner.
1899
1900 @item cd
1901 @kindex cd
1902 String of commands to clear the line the cursor is on, and all the
1903 lines below it, down to the bottom of the screen.  This command string
1904 should be used only with the cursor in column zero; their effect is
1905 undefined if the cursor is elsewhere.
1906
1907 @item ce
1908 @kindex ce
1909 String of commands to clear from the cursor to the end of the current
1910 line.
1911
1912 @item ec
1913 @kindex ec
1914 String of commands to clear @var{n} characters, starting with the
1915 character that the cursor is on.  This command string is expected to
1916 leave the cursor position unchanged.  The parameter @var{n} should never
1917 be large enough to reach past the right margin; the effect of such a
1918 large parameter would be undefined.
1919 @end table
1920
1921 Clear to end of line (@samp{ce}) is extremely important in programs that
1922 maintain an updating display.  Nearly all display terminals support this
1923 operation, so it is acceptable for an application program to refuse to
1924 work if @samp{ce} is not present.  However, if you do not want this
1925 limitation, you can accomplish clearing to end of line by outputting spaces
1926 until you reach the right margin.  In order to do this, you must know the
1927 current horizontal position.  Also, this technique assumes that writing a
1928 space will erase.  But this happens to be true on all the display terminals
1929 that fail to support @samp{ce}.
1930
1931 @node Insdel Line, Insdel Char, Clearing, Capabilities
1932 @section Insert/Delete Line
1933
1934 @cindex insert line
1935 @cindex delete line
1936 @dfn{Inserting a line} means creating a blank line in the middle
1937 of the screen, and pushing the existing lines of text apart.  In fact,
1938 the lines above the insertion point do not change, while the lines below
1939 move down, and one is normally lost at the bottom of the screen.
1940
1941 @dfn{Deleting a line} means causing the line to disappear from the screen,
1942 closing up the gap by moving the lines below it upward.  A new line
1943 appears at the bottom of the screen.  Usually this line is blank, but
1944 on terminals with the @samp{db} flag it may be a line previously moved
1945 off the screen bottom by scrolling or line insertion.
1946
1947 Insertion and deletion of lines is useful in programs that maintain an
1948 updating display some parts of which may get longer or shorter.  They are
1949 also useful in editors for scrolling parts of the screen, and for
1950 redisplaying after lines of text are killed or inserted.
1951
1952 Many terminals provide commands to insert or delete a single line at the
1953 cursor position.  Some provide the ability to insert or delete several
1954 lines with one command, using the number of lines to insert or delete as a
1955 parameter.  Always move the cursor to column zero before using any of
1956 these commands.
1957
1958 @table @samp
1959 @item al
1960 @kindex al
1961 String of commands to insert a blank line before the line the cursor
1962 is on.  The existing line, and all lines below it, are moved down.
1963 The last line in the screen (or in the scroll region, if one is set)
1964 disappears and in most circumstances is discarded.  It may not be
1965 discarded if the @samp{db} is present (@pxref{Scrolling}).
1966
1967 The cursor must be at the left margin before this command is used.
1968 This command does not move the cursor.
1969
1970 @item dl
1971 @kindex dl
1972 String of commands to delete the line the cursor is on.  The following
1973 lines move up, and a blank line appears at the bottom of the screen
1974 (or bottom of the scroll region).  If the terminal has the @samp{db}
1975 flag, a nonblank line previously pushed off the screen bottom may
1976 reappear at the bottom.
1977
1978 The cursor must be at the left margin before this command is used.
1979 This command does not move the cursor.
1980
1981 @item AL
1982 @kindex AL
1983 String of commands to insert @var{n} blank lines before the line that
1984 the cursor is on.  It is like @samp{al} repeated @var{n} times, except
1985 that it is as fast as one @samp{al}.
1986
1987 @item DL
1988 @kindex DL
1989 String of commands to delete @var{n} lines starting with the line that
1990 the cursor is on.  It is like @samp{dl} repeated @var{n} times, except
1991 that it is as fast as one @samp{dl}.
1992 @end table
1993
1994 Any terminal description that defines @samp{AL} should also define
1995 @samp{al}; likewise for @samp{DL} and @samp{dl}.  However, many terminals
1996 can only insert or delete one line at a time, so it is common to find
1997 @samp{al} and not @samp{AL}, or @samp{dl} without @samp{DL}.@refill
1998
1999 Therefore, all programs that use the insert and delete facilities should be
2000 prepared to work with @samp{al} in the case that @samp{AL} is absent, and
2001 likewise with @samp{dl}.  On the other hand, it is acceptable to write
2002 an application that uses only @samp{al} and @samp{dl} and does not look
2003 for @samp{AL} or @samp{DL} at all.@refill
2004
2005 If a terminal does not support line insertion and deletion directly,
2006 but does support a scroll region, the effect of insertion and deletion
2007 can be obtained with scrolling.  However, it is up to the individual
2008 user program to check for this possibility and use the scrolling
2009 commands to get the desired result.  It is fairly important to implement
2010 this alternate strategy, since it is the only way to get the effect of
2011 line insertion and deletion on the popular VT100 terminal.
2012
2013 Insertion and deletion of lines is affected by the scroll region on
2014 terminals that have a settable scroll region.  This is useful when it is
2015 desirable to move any few consecutive lines up or down by a few lines.
2016 @xref{Scrolling}.
2017
2018 The line pushed off the bottom of the screen is not lost if the terminal
2019 has the @samp{db} flag capability; instead, it is pushed into display
2020 memory that does not appear on the screen.  This is the same thing that
2021 happens when scrolling pushes a line off the bottom of the screen.
2022 Either reverse scrolling or deletion of a line can bring the apparently
2023 lost line back onto the bottom of the screen.  If the terminal has the
2024 scroll region feature as well as @samp{db}, the pushed-out line really
2025 is lost if a scroll region is in effect.
2026
2027 When outputting an insert or delete command with @code{tputs}, the
2028 @var{nlines} argument should be the total number of lines from the cursor
2029 to the bottom of the screen (or scroll region).  Very often these commands
2030 require padding proportional to this number of lines.  @xref{Padding}.
2031
2032 For @samp{AL} and @samp{DL} the @var{nlines} argument should @emph{not}
2033 depend on the number of lines inserted or deleted; only the total number of
2034 lines affected.  This is because it is just as fast to insert two or
2035 @var{n} lines with @samp{AL} as to insert one line with @samp{al}.
2036
2037 @node Insdel Char, Standout, Insdel Line, Capabilities
2038 @section Insert/Delete Character
2039 @cindex insert character
2040 @cindex delete character
2041
2042 @dfn{Inserting a character} means creating a blank space in the middle of a
2043 line, and pushing the rest of the line rightward.  The character in the
2044 rightmost column is lost.
2045
2046 @dfn{Deleting a character} means causing the character to disappear from
2047 the screen, closing up the gap by moving the rest of the line leftward.  A
2048 blank space appears in the rightmost column.
2049
2050 Insertion and deletion of characters is useful in programs that maintain an
2051 updating display some parts of which may get longer or shorter.  It is also
2052 useful in editors for redisplaying the results of editing within a line.
2053
2054 Many terminals provide commands to insert or delete a single character at
2055 the cursor position.  Some provide the ability to insert or delete several
2056 characters with one command, using the number of characters to insert or
2057 delete as a parameter.
2058
2059 @cindex insert mode
2060 Many terminals provide an insert mode in which outputting a graphic
2061 character has the added effect of inserting a position for that character.
2062 A special command string is used to enter insert mode and another is used
2063 to exit it.  The reason for designing a terminal with an insert mode rather
2064 than an insert command is that inserting character positions is usually
2065 followed by writing characters into them.  With insert mode, this is as
2066 fast as simply writing the characters, except for the fixed overhead of
2067 entering and leaving insert mode.  However, when the line speed is great
2068 enough, padding may be required for the graphic characters output in insert
2069 mode.
2070
2071 Some terminals require you to enter insert mode and then output a special
2072 command for each position to be inserted.  Or they may require special
2073 commands to be output before or after each graphic character to be
2074 inserted.
2075
2076 @cindex delete mode
2077 Deletion of characters is usually accomplished by a straightforward command
2078 to delete one or several positions; but on some terminals, it is necessary
2079 to enter a special delete mode before using the delete command, and leave
2080 delete mode afterward.  Sometimes delete mode and insert mode are the same
2081 mode.
2082
2083 Some terminals make a distinction between character positions in which a
2084 space character has been output and positions which have been cleared.  On
2085 these terminals, the effect of insert or delete character runs to the first
2086 cleared position rather than to the end of the line.  In fact, the effect
2087 may run to more than one line if there is no cleared position to stop the
2088 shift on the first line.  These terminals are identified by the @samp{in}
2089 flag capability.
2090
2091 On terminals with the @samp{in} flag, the technique of skipping over
2092 characters that you know were cleared, and then outputting text later on in
2093 the same line, causes later insert and delete character operations on that
2094 line to do nonstandard things.  A program that has any chance of doing this
2095 must check for the @samp{in} flag and must be careful to write explicit
2096 space characters into the intermediate columns when @samp{in} is present.
2097
2098 A plethora of terminal capabilities are needed to describe all of this
2099 complexity.  Here is a list of them all.  Following the list, we present
2100 an algorithm for programs to use to take proper account of all of these
2101 capabilities.
2102
2103 @table @samp
2104 @item im
2105 @kindex im
2106 String of commands to enter insert mode.
2107
2108 If the terminal has no special insert mode, but it can insert
2109 characters with a special command, @samp{im} should be defined with a
2110 null value, because the @samp{vi} editor assumes that insertion of a
2111 character is impossible if @samp{im} is not provided.
2112
2113 New programs should not act like @samp{vi}.  They should pay attention
2114 to @samp{im} only if it is defined.
2115
2116 @item ei
2117 @kindex ei
2118 String of commands to leave insert mode.  This capability must be
2119 present if @samp{im} is.
2120
2121 On a few old terminals the same string is used to enter and exit
2122 insert mode.  This string turns insert mode on if it was off, and off
2123 if it was on.  You can tell these terminals because the @samp{ei}
2124 string equals the @samp{im} string.  If you want to support these
2125 terminals, you must always remember accurately whether insert mode is
2126 in effect.  However, these terminals are obsolete, and it is
2127 reasonable to refuse to support them.  On all modern terminals, you
2128 can safely output @samp{ei} at any time to ensure that insert mode is
2129 turned off.
2130
2131 @item ic
2132 @kindex ic
2133 String of commands to insert one character position at the cursor.
2134 The cursor does not move.
2135
2136 If outputting a graphic character while in insert mode is sufficient
2137 to insert the character, then the @samp{ic} capability should be
2138 defined with a null value.
2139
2140 If your terminal offers a choice of ways to insert---either use insert
2141 mode or use a special command---then define @samp{im} and do not define
2142 @samp{ic}, since this gives the most efficient operation when several
2143 characters are to be inserted.  @emph{Do not} define both strings, for
2144 that means that @emph{both} must be used each time insertion is done.
2145
2146 @item ip
2147 @kindex ip
2148 String of commands to output following an inserted graphic character
2149 in insert mode.  Often it is used just for a padding spec, when padding
2150 is needed after an inserted character (@pxref{Padding}).
2151
2152 @item IC
2153 @kindex IC
2154 String of commands to insert @var{n} character positions at and after
2155 the cursor.  It has the same effect as repeating the @samp{ic} string
2156 and a space, @var{n} times.
2157
2158 If @samp{IC} is provided, application programs may use it without first
2159 entering insert mode.
2160
2161 @item mi
2162 @kindex mi
2163 Flag whose presence means it is safe to move the cursor while in insert
2164 mode and assume the terminal remains in insert mode.
2165
2166 @item in
2167 @kindex in
2168 Flag whose presence means that the terminal distinguishes between
2169 character positions in which space characters have been output and
2170 positions which have been cleared.
2171 @end table
2172
2173 An application program can assume that the terminal can do character
2174 insertion if @emph{any one of} the capabilities @samp{IC}, @samp{im},
2175 @samp{ic} or @samp{ip} is provided.
2176
2177 To insert @var{n} blank character positions, move the cursor to the place
2178 to insert them and follow this algorithm:
2179
2180 @enumerate
2181 @item
2182 If an @samp{IC} string is provided, output it with parameter @var{n}
2183 and you are finished.  Otherwise (or if you don't want to bother to
2184 look for an @samp{IC} string) follow the remaining steps.
2185
2186 @item
2187 Output the @samp{im} string, if there is one, unless the terminal is
2188 already in insert mode.
2189
2190 @item
2191 Repeat steps 4 through 6, @var{n} times.
2192
2193 @item
2194 Output the @samp{ic} string if any.
2195
2196 @item
2197 Output a space.
2198
2199 @item
2200 Output the @samp{ip} string if any.
2201
2202 @item
2203 Output the @samp{ei} string, eventually, to exit insert mode.  There
2204 is no need to do this right away.  If the @samp{mi} flag is present,
2205 you can move the cursor and the cursor will remain in insert mode;
2206 then you can do more insertion elsewhere without reentering insert
2207 mode.
2208 @end enumerate
2209
2210 To insert @var{n} graphic characters, position the cursor and follow this
2211 algorithm:
2212
2213 @enumerate
2214 @item
2215 If an @samp{IC} string is provided, output it with parameter @var{n},
2216 then output the graphic characters, and you are finished.  Otherwise
2217 (or if you don't want to bother to look for an @samp{IC} string)
2218 follow the remaining steps.
2219
2220 @item
2221 Output the @samp{im} string, if there is one, unless the terminal is
2222 already in insert mode.
2223
2224 @item
2225 For each character to be output, repeat steps 4 through 6.
2226
2227 @item
2228 Output the @samp{ic} string if any.
2229
2230 @item
2231 Output the next graphic character.
2232
2233 @item
2234 Output the @samp{ip} string if any.
2235
2236 @item
2237 Output the @samp{ei} string, eventually, to exit insert mode.  There
2238 is no need to do this right away.  If the @samp{mi} flag is present,
2239 you can move the cursor and the cursor will remain in insert mode;
2240 then you can do more insertion elsewhere without reentering insert
2241 mode.
2242 @end enumerate
2243
2244 Note that this is not the same as the original Unix termcap specifications
2245 in one respect: it assumes that the @samp{IC} string can be used without
2246 entering insert mode.  This is true as far as I know, and it allows you be
2247 able to avoid entering and leaving insert mode, and also to be able to
2248 avoid the inserted-character padding after the characters that go into the
2249 inserted positions.
2250
2251 Deletion of characters is less complicated; deleting one column is done by
2252 outputting the @samp{dc} string.  However, there may be a delete mode that
2253 must be entered with @samp{dm} in order to make @samp{dc} work.
2254
2255 @table @samp
2256 @item dc
2257 @kindex dc
2258 String of commands to delete one character position at the cursor.  If
2259 @samp{dc} is not present, the terminal cannot delete characters.
2260
2261 @item DC
2262 @kindex DC
2263 String of commands to delete @var{n} characters starting at the cursor.
2264 It has the same effect as repeating the @samp{dc} string @var{n} times.
2265 Any terminal description that has @samp{DC} also has @samp{dc}.
2266
2267 @item dm
2268 @kindex dm
2269 String of commands to enter delete mode.  If not present, there is no
2270 delete mode, and @samp{dc} can be used at any time (assuming there is
2271 a @samp{dc}).
2272
2273 @item ed
2274 @kindex ed
2275 String of commands to exit delete mode.  This must be present if
2276 @samp{dm} is.
2277 @end table
2278
2279 To delete @var{n} character positions, position the cursor and follow these
2280 steps:
2281
2282 @enumerate
2283 @item
2284 If the @samp{DC} string is present, output it with parameter @var{n}
2285 and you are finished.  Otherwise, follow the remaining steps.
2286
2287 @item
2288 Output the @samp{dm} string, unless you know the terminal is already
2289 in delete mode.
2290
2291 @item
2292 Output the @samp{dc} string @var{n} times.
2293
2294 @item
2295 Output the @samp{ed} string eventually.  If the flag capability
2296 @samp{mi} is present, you can move the cursor and do more deletion
2297 without leaving and reentering delete mode.
2298 @end enumerate
2299
2300 As with the @samp{IC} string, we have departed from the original termcap
2301 specifications by assuming that @samp{DC} works without entering delete
2302 mode even though @samp{dc} would not.
2303
2304 If the @samp{dm} and @samp{im} capabilities are both present and have the
2305 same value, it means that the terminal has one mode for both insertion and
2306 deletion.  It is useful for a program to know this, because then it can do
2307 insertions after deletions, or vice versa, without leaving insert/delete
2308 mode and reentering it.
2309
2310 @node Standout, Underlining, Insdel Char, Capabilities
2311 @section Standout and Appearance Modes
2312 @cindex appearance modes
2313 @cindex standout
2314 @cindex magic cookie
2315
2316 @dfn{Appearance modes} are modifications to the ways characters are
2317 displayed.  Typical appearance modes include reverse video, dim, bright,
2318 blinking, underlined, invisible, and alternate character set.  Each kind of
2319 terminal supports various among these, or perhaps none.
2320
2321 For each type of terminal, one appearance mode or combination of them that
2322 looks good for highlighted text is chosen as the @dfn{standout mode}.  The
2323 capabilities @samp{so} and @samp{se} say how to enter and leave standout
2324 mode.  Programs that use appearance modes only to highlight some text
2325 generally use the standout mode so that they can work on as many terminals
2326 as possible.  Use of specific appearance modes other than ``underlined''
2327 and ``alternate character set'' is rare.
2328
2329 Terminals that implement appearance modes fall into two general classes as
2330 to how they do it.
2331
2332 In some terminals, the presence or absence of any appearance mode is
2333 recorded separately for each character position.  In these terminals, each
2334 graphic character written is given the appearance modes current at the time
2335 it is written, and keeps those modes until it is erased or overwritten.
2336 There are special commands to turn the appearance modes on or off for
2337 characters to be written in the future.
2338
2339 In other terminals, the change of appearance modes is represented by a
2340 marker that belongs to a certain screen position but affects all following
2341 screen positions until the next marker.  These markers are traditionally
2342 called @dfn{magic cookies}.
2343
2344 The same capabilities (@samp{so}, @samp{se}, @samp{mb} and so on) for
2345 turning appearance modes on and off are used for both magic-cookie
2346 terminals and per-character terminals.  On magic cookie terminals, these
2347 give the commands to write the magic cookies.  On per-character terminals,
2348 they change the current modes that affect future output and erasure.  Some
2349 simple applications can use these commands without knowing whether or not
2350 they work by means of cookies.
2351
2352 However, a program that maintains and updates a display needs to know
2353 whether the terminal uses magic cookies, and exactly what their effect is.
2354 This information comes from the @samp{sg} capability.
2355
2356 The @samp{sg} capability is a numeric capability whose presence indicates
2357 that the terminal uses magic cookies for appearance modes.  Its value is
2358 the number of character positions that a magic cookie occupies.  Usually
2359 the cookie occupies one or more character positions on the screen, and these
2360 character positions are displayed as blank, but in some terminals the
2361 cookie has zero width.
2362
2363 The @samp{sg} capability describes both the magic cookie to turn standout
2364 on and the cookie to turn it off.  This makes the assumption that both
2365 kinds of cookie have the same width on the screen.  If that is not true,
2366 the narrower cookie must be ``widened'' with spaces until it has the same
2367 width as the other.
2368
2369 On some magic cookie terminals, each line always starts with normal
2370 display; in other words, the scope of a magic cookie never extends over
2371 more than one line.  But on other terminals, one magic cookie affects all
2372 the lines below it unless explicitly canceled.  Termcap does not define any
2373 way to distinguish these two ways magic cookies can work.  To be safe, it
2374 is best to put a cookie at the beginning of each line.
2375
2376 On some per-character terminals, standout mode or other appearance modes
2377 may be canceled by moving the cursor.  On others, moving the cursor has no
2378 effect on the state of the appearance modes.  The latter class of terminals
2379 are given the flag capability @samp{ms} (``can move in standout'').  All
2380 programs that might have occasion to move the cursor while appearance modes
2381 are turned on must check for this flag; if it is not present, they should
2382 reset appearance modes to normal before doing cursor motion.
2383
2384 A program that has turned on only standout mode should use @samp{se} to
2385 reset the standout mode to normal.  A program that has turned on only
2386 alternate character set mode should use @samp{ae} to return it to normal.
2387 If it is possible that any other appearance modes are turned on, use the
2388 @samp{me} capability to return them to normal.
2389
2390 Note that the commands to turn on one appearance mode, including @samp{so}
2391 and @samp{mb} @dots{} @samp{mr}, if used while some other appearance modes
2392 are turned on, may combine the two modes on some terminals but may turn off
2393 the mode previously enabled on other terminals.  This is because some
2394 terminals do not have a command to set or clear one appearance mode without
2395 changing the others.  Programs should not attempt to use appearance modes
2396 in combination except with @samp{sa}, and when switching from one single
2397 mode to another should always turn off the previously enabled mode and then
2398 turn on the new desired mode.
2399
2400 On some old terminals, the @samp{so} and @samp{se} commands may be the same
2401 command, which has the effect of turning standout on if it is off, or off
2402 it is on.  It is therefore risky for a program to output extra @samp{se}
2403 commands for good measure.  Fortunately, all these terminals are obsolete.
2404
2405 Programs that update displays in which standout-text may be replaced with
2406 non-standout text must check for the @samp{xs} flag.  In a per-character
2407 terminal, this flag says that the only way to remove standout once written is
2408 to clear that portion of the line with the @samp{ce} string or something
2409 even more powerful (@pxref{Clearing}); just writing new characters at those
2410 screen positions will not change the modes in effect there.  In a magic
2411 cookie terminal, @samp{xs} says that the only way to remove a cookie is to
2412 clear a portion of the line that includes the cookie; writing a different
2413 cookie at the same position does not work.
2414
2415 Such programs must also check for the @samp{xt} flag, which means that the
2416 terminal is a Teleray 1061.  On this terminal it is impossible to position
2417 the cursor at the front of a magic cookie, so the only two ways to remove a
2418 cookie are (1) to delete the line it is on or (2) to position the cursor at
2419 least one character before it (possibly on a previous line) and output the
2420 @samp{se} string, which on these terminals finds and removes the next
2421 @samp{so} magic cookie on the screen.  (It may also be possible to remove a
2422 cookie which is not at the beginning of a line by clearing that line.)  The
2423 @samp{xt} capability also has implications for the use of tab characters,
2424 but in that regard it is obsolete (@pxref{Cursor Motion}).
2425
2426 @table @samp
2427 @item so
2428 @kindex so
2429 String of commands to enter standout mode.
2430
2431 @item se
2432 @kindex se
2433 String of commands to leave standout mode.
2434
2435 @item sg
2436 @kindex sg
2437 Numeric capability, the width on the screen of the magic cookie.  This
2438 capability is absent in terminals that record appearance modes
2439 character by character.
2440
2441 @item ms
2442 @kindex ms
2443 Flag whose presence means that it is safe to move the cursor while the
2444 appearance modes are not in the normal state.  If this flag is absent,
2445 programs should always reset the appearance modes to normal before
2446 moving the cursor.
2447
2448 @item xs
2449 @kindex xs
2450 Flag whose presence means that the only way to reset appearance modes
2451 already on the screen is to clear to end of line.  On a per-character
2452 terminal, you must clear the area where the modes are set.  On a magic
2453 cookie terminal, you must clear an area containing the cookie.
2454 See the discussion above.
2455
2456 @item xt
2457 @kindex xt
2458 Flag whose presence means that the cursor cannot be positioned right
2459 in front of a magic cookie, and that @samp{se} is a command to delete
2460 the next magic cookie following the cursor.  See discussion above.
2461
2462 @item mb
2463 @kindex mb
2464 String of commands to enter blinking mode.
2465
2466 @item md
2467 @kindex md
2468 String of commands to enter double-bright mode.
2469
2470 @item mh
2471 @kindex mh
2472 String of commands to enter half-bright mode.
2473
2474 @item mk
2475 @kindex mk
2476 String of commands to enter invisible mode.
2477
2478 @item mp
2479 @kindex mp
2480 String of commands to enter protected mode.
2481
2482 @item mr
2483 @kindex mr
2484 String of commands to enter reverse-video mode.
2485
2486 @item me
2487 @kindex me
2488 String of commands to turn off all appearance modes, including
2489 standout mode and underline mode.  On some terminals it also turns off
2490 alternate character set mode; on others, it may not.  This capability
2491 must be present if any of @samp{mb} @dots{} @samp{mr} is present.
2492
2493 @item as
2494 @kindex as
2495 String of commands to turn on alternate character set mode.  This mode
2496 assigns some or all graphic characters an alternate picture on the
2497 screen.  There is no standard as to what the alternate pictures look
2498 like.
2499
2500 @item ae
2501 @kindex ae
2502 String of commands to turn off alternate character set mode.
2503
2504 @item sa
2505 @kindex sa
2506 String of commands to turn on an arbitrary combination of appearance
2507 modes.  It accepts 9 parameters, each of which controls a particular
2508 kind of appearance mode.  A parameter should be 1 to turn its appearance
2509 mode on, or zero to turn that mode off.  Most terminals do not support
2510 the @samp{sa} capability, even among those that do have various
2511 appearance modes.
2512
2513 The nine parameters are, in order, @var{standout}, @var{underline},
2514 @var{reverse}, @var{blink}, @var{half-bright}, @var{double-bright},
2515 @var{blank}, @var{protect}, @var{alt char set}.
2516 @end table
2517
2518 @node Underlining, Cursor Visibility, Standout, Capabilities
2519 @section Underlining
2520 @cindex underlining
2521
2522 Underlining on most terminals is a kind of appearance mode, much like
2523 standout mode.  Therefore, it may be implemented using magic cookies or as
2524 a flag in the terminal whose current state affects each character that is
2525 output.  @xref{Standout}, for a full explanation.
2526
2527 The @samp{ug} capability is a numeric capability whose presence indicates
2528 that the terminal uses magic cookies for underlining.  Its value is the
2529 number of character positions that a magic cookie for underlining occupies;
2530 it is used for underlining just as @samp{sg} is used for standout.  Aside
2531 from the simplest applications, it is impossible to use underlining
2532 correctly without paying attention to the value of @samp{ug}.
2533
2534 @table @samp
2535 @item us
2536 @kindex us
2537 String of commands to turn on underline mode or to output a magic cookie
2538 to start underlining.
2539
2540 @item ue
2541 @kindex ue
2542 String of commands to turn off underline mode or to output a magic
2543 cookie to stop underlining.
2544
2545 @item ug
2546 @kindex ug
2547 Width of magic cookie that represents a change of underline mode;
2548 or missing, if the terminal does not use a magic cookie for this.
2549
2550 @item ms
2551 @kindex ms
2552 Flag whose presence means that it is safe to move the cursor while the
2553 appearance modes are not in the normal state.  Underlining is an
2554 appearance mode.  If this flag is absent, programs should always turn
2555 off underlining before moving the cursor.
2556 @end table
2557
2558 There are two other, older ways of doing underlining: there can be a
2559 command to underline a single character, or the output of @samp{_}, the
2560 ASCII underscore character, as an overstrike could cause a character to be
2561 underlined.  New programs need not bother to handle these capabilities
2562 unless the author cares strongly about the obscure terminals which support
2563 them.  However, terminal descriptions should provide these capabilities
2564 when appropriate.
2565
2566 @table @samp
2567 @item uc
2568 @kindex uc
2569 String of commands to underline the character under the cursor, and
2570 move the cursor right.
2571
2572 @item ul
2573 @kindex ul
2574 Flag whose presence means that the terminal can underline by
2575 overstriking an underscore character (@samp{_}); some terminals can do
2576 this even though they do not support overstriking in general.  An
2577 implication of this flag is that when outputting new text to overwrite
2578 old text, underscore characters must be treated specially lest they
2579 underline the old text instead.
2580 @end table
2581
2582 @node Cursor Visibility, Bell, Underlining, Capabilities
2583 @section Cursor Visibility
2584 @cindex visibility
2585
2586 Some terminals have the ability to make the cursor invisible, or to enhance
2587 it.  Enhancing the cursor is often done by programs that plan to use the
2588 cursor to indicate to the user a position of interest that may be anywhere
2589 on the screen---for example, the Emacs editor enhances the cursor on entry.
2590 Such programs should always restore the cursor to normal on exit.
2591
2592 @table @samp
2593 @item vs
2594 @kindex vs
2595 String of commands to enhance the cursor.
2596
2597 @item vi
2598 @kindex vi
2599 String of commands to make the cursor invisible.
2600
2601 @item ve
2602 @kindex ve
2603 String of commands to return the cursor to normal.
2604 @end table
2605
2606 If you define either @samp{vs} or @samp{vi}, you must also define @samp{ve}.
2607
2608 @node Bell, Keypad, Cursor Visibility, Capabilities
2609 @section Bell
2610 @cindex bell
2611 @cindex visible bell
2612
2613 Here we describe commands to make the terminal ask for the user to pay
2614 attention to it.
2615
2616 @table @samp
2617 @item bl
2618 @kindex bl
2619 String of commands to cause the terminal to make an audible sound.  If
2620 this capability is absent, the terminal has no way to make a suitable
2621 sound.
2622
2623 @item vb
2624 @kindex vb
2625 String of commands to cause the screen to flash to attract attention
2626 (``visible bell'').  If this capability is absent, the terminal has no
2627 way to do such a thing.
2628 @end table
2629
2630 @node Keypad, Meta Key, Bell, Capabilities
2631 @section Keypad and Function Keys
2632
2633 Many terminals have arrow and function keys that transmit specific
2634 character sequences to the computer.  Since the precise sequences used
2635 depend on the terminal, termcap defines capabilities used to say what the
2636 sequences are.  Unlike most termcap string-valued capabilities, these are
2637 not strings of commands to be sent to the terminal, rather strings that
2638 are received from the terminal.
2639
2640 Programs that expect to use keypad keys should check, initially, for a
2641 @samp{ks} capability and send it, to make the keypad actually transmit.
2642 Such programs should also send the @samp{ke} string when exiting.
2643
2644 @table @asis
2645 @item @samp{ks}
2646 @kindex ka@dots{}ku
2647 String of commands to make the function keys transmit.  If this
2648 capability is not provided, but the others in this section are,
2649 programs may assume that the function keys always transmit.
2650
2651 @item @samp{ke}
2652 String of commands to make the function keys work locally.  This
2653 capability is provided only if @samp{ks} is.
2654
2655 @item @samp{kl}
2656 String of input characters sent by typing the left-arrow key.  If this
2657 capability is missing, you cannot expect the terminal to have a
2658 left-arrow key that transmits anything to the computer.
2659
2660 @item @samp{kr}
2661 String of input characters sent by typing the right-arrow key.
2662
2663 @item @samp{ku}
2664 String of input characters sent by typing the up-arrow key.
2665
2666 @item @samp{kd}
2667 String of input characters sent by typing the down-arrow key.
2668
2669 @item @samp{kh}
2670 String of input characters sent by typing the ``home-position'' key.
2671
2672 @item @samp{K1} @dots{} @samp{K5}
2673 @kindex K1@dots{}K5
2674 Strings of input characters sent by the five other keys in a 3-by-3
2675 array that includes the arrow keys, if the keyboard has such a 3-by-3
2676 array.  Note that one of these keys may be the ``home-position'' key,
2677 in which case one of these capabilities will have the same value as
2678 the @samp{kh} key.
2679
2680 @item @samp{k0}
2681 String of input characters sent by function key 10 (or 0, if the terminal
2682 has one labeled 0).
2683
2684 @item @samp{k1} @dots{} @samp{k9}
2685 @kindex k1@dots{}k9
2686 Strings of input characters sent by function keys 1 through 9,
2687 provided for those function keys that exist.
2688
2689 @item @samp{kn}
2690 Number: the number of numbered function keys, if there are more than
2691 10.
2692
2693 @item @samp{l0} @dots{} @samp{l9}
2694 @kindex l0@dots{}l9
2695 Strings which are the labels appearing on the keyboard on the keys
2696 described by the capabilities @samp{k0} @dots{} @samp{l9}.  These
2697 capabilities should be left undefined if the labels are @samp{f0} or
2698 @samp{f10} and @samp{f1} @dots{} @samp{f9}.@refill
2699
2700 @item @samp{kH}
2701 @kindex kA@dots{}kT
2702 String of input characters sent by the ``home down'' key, if there is
2703 one.
2704
2705 @item @samp{kb}
2706 String of input characters sent by the ``backspace'' key, if there is
2707 one.
2708
2709 @item @samp{ka}
2710 String of input characters sent by the ``clear all tabs'' key, if there
2711 is one.
2712
2713 @item @samp{kt}
2714 String of input characters sent by the ``clear tab stop this column''
2715 key, if there is one.
2716
2717 @item @samp{kC}
2718 String of input characters sent by the ``clear screen'' key, if there is
2719 one.
2720
2721 @item @samp{kD}
2722 String of input characters sent by the ``delete character'' key, if
2723 there is one.
2724
2725 @item @samp{kL}
2726 String of input characters sent by the ``delete line'' key, if there is
2727 one.
2728
2729 @item @samp{kM}
2730 String of input characters sent by the ``exit insert mode'' key, if
2731 there is one.
2732
2733 @item @samp{kE}
2734 String of input characters sent by the ``clear to end of line'' key, if
2735 there is one.
2736
2737 @item @samp{kS}
2738 String of input characters sent by the ``clear to end of screen'' key,
2739 if there is one.
2740
2741 @item @samp{kI}
2742 String of input characters sent by the ``insert character'' or ``enter
2743 insert mode'' key, if there is one.
2744
2745 @item @samp{kA}
2746 String of input characters sent by the ``insert line'' key, if there is
2747 one.
2748
2749 @item @samp{kN}
2750 String of input characters sent by the ``next page'' key, if there is
2751 one.
2752
2753 @item @samp{kP}
2754 String of input characters sent by the ``previous page'' key, if there is
2755 one.
2756
2757 @item @samp{kF}
2758 String of input characters sent by the ``scroll forward'' key, if there
2759 is one.
2760
2761 @item @samp{kR}
2762 String of input characters sent by the ``scroll reverse'' key, if there
2763 is one.
2764
2765 @item @samp{kT}
2766 String of input characters sent by the ``set tab stop in this column''
2767 key, if there is one.
2768
2769 @item @samp{ko}
2770 String listing the other function keys the terminal has.  This is a
2771 very obsolete way of describing the same information found in the
2772 @samp{kH} @dots{} @samp{kT} keys.  The string contains a list of
2773 two-character termcap capability names, separated by commas.  The
2774 meaning is that for each capability name listed, the terminal has a
2775 key which sends the string which is the value of that capability.  For
2776 example, the value @samp{:ko=cl,ll,sf,sr:} says that the terminal has
2777 four function keys which mean ``clear screen'', ``home down'',
2778 ``scroll forward'' and ``scroll reverse''.@refill
2779 @end table
2780
2781 @node Meta Key, Initialization, Keypad, Capabilities
2782 @section Meta Key
2783
2784 @cindex meta key
2785 A Meta key is a key on the keyboard that modifies each character you type
2786 by controlling the 0200 bit.  This bit is on if and only if the Meta key is
2787 held down when the character is typed.  Characters typed using the Meta key
2788 are called Meta characters.  Emacs uses Meta characters as editing
2789 commands.
2790
2791 @table @samp
2792 @item km
2793 @kindex km
2794 Flag whose presence means that the terminal has a Meta key.
2795
2796 @item mm
2797 @kindex mm
2798 String of commands to enable the functioning of the Meta key.
2799
2800 @item mo
2801 @kindex mo
2802 String of commands to disable the functioning of the Meta key.
2803 @end table
2804
2805 If the terminal has @samp{km} but does not have @samp{mm} and @samp{mo}, it
2806 means that the Meta key always functions.  If it has @samp{mm} and
2807 @samp{mo}, it means that the Meta key can be turned on or off.  Send the
2808 @samp{mm} string to turn it on, and the @samp{mo} string to turn it off.
2809 I do not know why one would ever not want it to be on.
2810
2811 @node Initialization, Pad Specs, Meta Key, Capabilities
2812 @section Initialization
2813 @cindex reset
2814 @cindex initialization
2815 @cindex tab stops
2816
2817 @table @samp
2818 @item ti
2819 @kindex ti
2820 String of commands to put the terminal into whatever special modes are
2821 needed or appropriate for programs that move the cursor
2822 nonsequentially around the screen.  Programs that use termcap to do
2823 full-screen display should output this string when they start up.
2824
2825 @item te
2826 @kindex te
2827 String of commands to undo what is done by the @samp{ti} string.
2828 Programs that output the @samp{ti} string on entry should output this
2829 string when they exit.
2830
2831 @item is
2832 @kindex is
2833 String of commands to initialize the terminal for each login session.
2834
2835 @item if
2836 @kindex if
2837 String which is the name of a file containing the string of commands
2838 to initialize the terminal for each session of use.  Normally @samp{is}
2839 and @samp{if} are not both used.
2840
2841 @item i1
2842 @itemx i3
2843 @kindex i1
2844 @kindex i3
2845 Two more strings of commands to initialize the terminal for each login
2846 session.  The @samp{i1} string (if defined) is output before @samp{is}
2847 or @samp{if}, and the @samp{i3} string (if defined) is output after.
2848
2849 The reason for having three separate initialization strings is to make
2850 it easier to define a group of related terminal types with slightly
2851 different initializations.  Define two or three of the strings in the
2852 basic type; then the other types can override one or two of the
2853 strings.
2854
2855 @item rs
2856 @kindex rs
2857 String of commands to reset the terminal from any strange mode it may
2858 be in.  Normally this includes the @samp{is} string (or other commands
2859 with the same effects) and more.  What would go in the @samp{rs}
2860 string but not in the @samp{is} string are annoying or slow commands
2861 to bring the terminal back from strange modes that nobody would
2862 normally use.
2863
2864 @item it
2865 @kindex it
2866 Numeric value, the initial spacing between hardware tab stop columns
2867 when the terminal is powered up.  Programs to initialize the terminal
2868 can use this to decide whether there is a need to set the tab stops.
2869 If the initial width is 8, well and good; if it is not 8, then the
2870 tab stops should be set; if they cannot be set, the kernel is told
2871 to convert tabs to spaces, and other programs will observe this and do
2872 likewise.
2873
2874 @item ct
2875 @kindex ct
2876 String of commands to clear all tab stops.
2877
2878 @item st
2879 @kindex st
2880 String of commands to set tab stop at current cursor column on all
2881 lines.
2882 @end table
2883
2884 @node Pad Specs, Status Line, Initialization, Capabilities
2885 @section Padding Capabilities
2886 @cindex padding
2887
2888 There are two terminal capabilities that exist just to explain the proper
2889 way to obey the padding specifications in all the command string
2890 capabilities.  One, @samp{pc}, must be obeyed by all termcap-using
2891 programs.
2892
2893 @table @samp
2894 @item pb
2895 @kindex pb
2896 Numeric value, the lowest baud rate at which padding is actually
2897 needed.  Programs may check this and refrain from doing any padding at
2898 lower speeds.
2899
2900 @item pc
2901 @kindex pc
2902 String of commands for padding.  The first character of this string is
2903 to be used as the pad character, instead of using null characters for
2904 padding.  If @samp{pc} is not provided, use null characters.  Every
2905 program that uses termcap must look up this capability and use it to
2906 set the variable @code{PC} that is used by @code{tputs}.
2907 @xref{Padding}.
2908 @end table
2909
2910 Some termcap capabilities exist just to specify the amount of padding that
2911 the kernel should give to cursor motion commands used in ordinary
2912 sequential output.
2913
2914 @table @samp
2915 @item dC
2916 @kindex dC
2917 Numeric value, the number of msec of padding needed for the
2918 carriage-return character.
2919
2920 @item dN
2921 @kindex dN
2922 Numeric value, the number of msec of padding needed for the newline
2923 (linefeed) character.
2924
2925 @item dB
2926 @kindex dB
2927 Numeric value, the number of msec of padding needed for the backspace
2928 character.
2929
2930 @item dF
2931 @kindex dF
2932 Numeric value, the number of msec of padding needed for the formfeed
2933 character.
2934
2935 @item dT
2936 @kindex dT
2937 Numeric value, the number of msec of padding needed for the tab
2938 character.
2939 @end table
2940
2941 In some systems, the kernel uses the above capabilities; in other systems,
2942 the kernel uses the paddings specified in the string capabilities
2943 @samp{cr}, @samp{sf}, @samp{le}, @samp{ff} and @samp{ta}.  Descriptions of
2944 terminals which require such padding should contain the @samp{dC} @dots{}
2945 @samp{dT} capabilities and also specify the appropriate padding in the
2946 corresponding string capabilities.  Since no modern terminals require
2947 padding for ordinary sequential output, you probably won't need to do
2948 either of these things.
2949
2950 @node Status Line, Half-Line, Pad Specs, Capabilities
2951 @section Status Line
2952
2953 @cindex status line
2954 A @dfn{status line} is a line on the terminal that is not used for ordinary
2955 display output but instead used for a special message.  The intended use is
2956 for a continuously updated description of what the user's program is doing,
2957 and that is where the name ``status line'' comes from, but in fact it could
2958 be used for anything.  The distinguishing characteristic of a status line
2959 is that ordinary output to the terminal does not affect it; it changes only
2960 if the special status line commands of this section are used.
2961
2962 @table @samp
2963 @item hs
2964 @kindex hs
2965 Flag whose presence means that the terminal has a status line.  If a
2966 terminal description specifies that there is a status line, it must
2967 provide the @samp{ts} and @samp{fs} capabilities.
2968
2969 @item ts
2970 @kindex ts
2971 String of commands to move the terminal cursor into the status line.
2972 Usually these commands must specifically record the old cursor
2973 position for the sake of the @samp{fs} string.
2974
2975 @item fs
2976 @kindex fs
2977 String of commands to move the cursor back from the status line to its
2978 previous position (outside the status line).
2979
2980 @item es
2981 @kindex es
2982 Flag whose presence means that other display commands work while
2983 writing the status line.  In other words, one can clear parts of it,
2984 insert or delete characters, move the cursor within it using @samp{ch}
2985 if there is a @samp{ch} capability, enter and leave standout mode, and
2986 so on.
2987
2988 @item ds
2989 @kindex ds
2990 String of commands to disable the display of the status line.  This
2991 may be absent, if there is no way to disable the status line display.
2992
2993 @item ws
2994 @kindex ws
2995 Numeric value, the width of the status line.  If this capability is
2996 absent in a terminal that has a status line, it means the status line
2997 is the same width as the other lines.
2998
2999 Note that the value of @samp{ws} is sometimes as small as 8.
3000 @end table
3001
3002 @node Half-Line, Printer, Status Line, Capabilities
3003 @section Half-Line Motion
3004
3005 Some terminals have commands for moving the cursor vertically by half-lines,
3006 useful for outputting subscripts and superscripts.  Mostly it is hardcopy
3007 terminals that have such features.
3008
3009 @table @samp
3010 @item hu
3011 @kindex hu
3012 String of commands to move the cursor up half a line.  If the terminal
3013 is a display, it is your responsibility to avoid moving up past the
3014 top line; however, most likely the terminal that supports this is a
3015 hardcopy terminal and there is nothing to be concerned about.
3016
3017 @item hd
3018 @kindex hd
3019 String of commands to move the cursor down half a line.  If the
3020 terminal is a display, it is your responsibility to avoid moving down
3021 past the bottom line, etc.
3022 @end table
3023
3024 @node Printer,, Half-Line, Capabilities
3025 @section Controlling Printers Attached to Terminals
3026 @cindex printer
3027
3028 Some terminals have attached hardcopy printer ports.  They may be able to
3029 copy the screen contents to the printer; they may also be able to redirect
3030 output to the printer.  Termcap does not have anything to tell the program
3031 whether the redirected output appears also on the screen; it does on some
3032 terminals but not all.
3033
3034 @table @samp
3035 @item ps
3036 @kindex ps
3037 String of commands to cause the contents of the screen to be printed.
3038 If it is absent, the screen contents cannot be printed.
3039
3040 @item po
3041 @kindex po
3042 String of commands to redirect further output to the printer.
3043
3044 @item pf
3045 @kindex pf
3046 String of commands to terminate redirection of output to the printer.
3047 This capability must be present in the description if @samp{po} is.
3048
3049 @item pO
3050 @kindex pO
3051 String of commands to redirect output to the printer for next @var{n}
3052 characters of output, regardless of what they are.  Redirection will
3053 end automatically after @var{n} characters of further output.  Until
3054 then, nothing that is output can end redirection, not even the
3055 @samp{pf} string if there is one.  The number @var{n} should not be
3056 more than 255.
3057
3058 One use of this capability is to send non-text byte sequences (such as
3059 bit-maps) to the printer.
3060 @end table
3061
3062 Most terminals with printers do not support all of @samp{ps}, @samp{po} and
3063 @samp{pO}; any one or two of them may be supported.  To make a program that
3064 can send output to all kinds of printers, it is necessary to check for all
3065 three of these capabilities, choose the most convenient of the ones that
3066 are provided, and use it in its own appropriate fashion.
3067
3068 @node Summary, Var Index, Capabilities, Top
3069 @chapter Summary of Capability Names
3070
3071 Here are all the terminal capability names in alphabetical order
3072 with a brief description of each.  For cross references to their definitions,
3073 see the index of capability names (@pxref{Cap Index}).
3074
3075 @table @samp
3076 @item ae
3077 String to turn off alternate character set mode.
3078 @item al
3079 String to insert a blank line before the cursor.
3080 @item AL
3081 String to insert @var{n} blank lines before the cursor.
3082 @item am
3083 Flag: output to last column wraps cursor to next line.
3084 @item as
3085 String to turn on alternate character set mode.like.
3086 @item bc
3087 Very obsolete alternative name for the @samp{le} capability.
3088 @item bl
3089 String to sound the bell.
3090 @item bs
3091 Obsolete flag: ASCII backspace may be used for leftward motion.
3092 @item bt
3093 String to move the cursor left to the previous hardware tab stop column.
3094 @item bw
3095 Flag: @samp{le} at left margin wraps to end of previous line.
3096 @item CC
3097 String to change terminal's command character.
3098 @item cd
3099 String to clear the line the cursor is on, and following lines.
3100 @item ce
3101 String to clear from the cursor to the end of the line.
3102 @item ch
3103 String to position the cursor at column @var{c} in the same line.
3104 @item cl
3105 String to clear the entire screen and put cursor at upper left corner.
3106 @item cm
3107 String to position the cursor at line @var{l}, column @var{c}.
3108 @item CM
3109 String to position the cursor at line @var{l}, column
3110 @var{c}, relative to display memory.
3111 @item co
3112 Number: width of the screen.
3113 @item cr
3114 String to move cursor sideways to left margin.
3115 @item cs
3116 String to set the scroll region.
3117 @item cS
3118 Alternate form of string to set the scroll region.
3119 @item ct
3120 String to clear all tab stops.
3121 @item cv
3122 String to position the cursor at line @var{l} in the same column.
3123 @item da
3124 Flag: data scrolled off top of screen may be scrolled back.
3125 @item db
3126 Flag: data scrolled off bottom of screen may be scrolled back.
3127 @item dB
3128 Obsolete number: msec of padding needed for the backspace character.
3129 @item dc
3130 String to delete one character position at the cursor.
3131 @item dC
3132 Obsolete number: msec of padding needed for the carriage-return character.
3133 @item DC
3134 String to delete @var{n} characters starting at the cursor.
3135 @item dF
3136 Obsolete number: msec of padding needed for the formfeed character.
3137 @item dl
3138 String to delete the line the cursor is on.
3139 @item DL
3140 String to delete @var{n} lines starting with the cursor's line.
3141 @item dm
3142 String to enter delete mode.
3143 @item dN
3144 Obsolete number: msec of padding needed for the newline character.
3145 @item do
3146 String to move the cursor vertically down one line.
3147 @item DO
3148 String to move cursor vertically down @var{n} lines.
3149 @item ds
3150 String to disable the display of the status line.
3151 @item dT
3152 Obsolete number: msec of padding needed for the tab character.
3153 @item ec
3154 String of commands to clear @var{n} characters at cursor.
3155 @item ed
3156 String to exit delete mode.
3157 @item ei
3158 String to leave insert mode.
3159 @item eo
3160 Flag: output of a space can erase an overstrike.
3161 @item es
3162 Flag: other display commands work while writing the status line.
3163 @item ff
3164 String to advance to the next page, for a hardcopy terminal.
3165 @item fs
3166 String to move the cursor back from the status line to its
3167 previous position (outside the status line).
3168 @item gn
3169 Flag: this terminal type is generic, not real.
3170 @item hc
3171 Flag: hardcopy terminal.
3172 @item hd
3173 String to move the cursor down half a line.
3174 @item ho
3175 String to position cursor at upper left corner.
3176 @item hs
3177 Flag: the terminal has a status line.
3178 @item hu
3179 String to move the cursor up half a line.
3180 @item hz
3181 Flag: terminal cannot accept @samp{~} as output.
3182 @item i1
3183 String to initialize the terminal for each login session.
3184 @item i3
3185 String to initialize the terminal for each login session.
3186 @item ic
3187 String to insert one character position at the cursor.
3188 @item IC
3189 String to insert @var{n} character positions at the cursor.
3190 @item if
3191 String naming a file of commands to initialize the terminal.
3192 @item im
3193 String to enter insert mode.
3194 @item in
3195 Flag: outputting a space is different from moving over empty positions.
3196 @item ip
3197 String to output following an inserted character in insert mode.
3198 @item is
3199 String to initialize the terminal for each login session.
3200 @item it
3201 Number: initial spacing between hardware tab stop columns.
3202 @item k0
3203 String of input sent by function key 0 or 10.
3204 @item k1 @dots{} k9
3205 Strings of input sent by function keys 1 through 9.
3206 @item K1 @dots{} K5
3207 Strings sent by the five other keys in 3-by-3 array with arrows.
3208 @item ka
3209 String of input sent by the ``clear all tabs'' key.
3210 @item kA
3211 String of input sent by the ``insert line'' key.
3212 @item kb
3213 String of input sent by the ``backspace'' key.
3214 @item kC
3215 String of input sent by the ``clear screen'' key.
3216 @item kd
3217 String of input sent by typing the down-arrow key.
3218 @item kD
3219 String of input sent by the ``delete character'' key.
3220 @item ke
3221 String to make the function keys work locally.
3222 @item kE
3223 String of input sent by the ``clear to end of line'' key.
3224 @item kF
3225 String of input sent by the ``scroll forward'' key.
3226 @item kh
3227 String of input sent by typing the ``home-position'' key.
3228 @item kH
3229 String of input sent by the ``home down'' key.
3230 @item kI
3231 String of input sent by the ``insert character'' or ``enter
3232 insert mode'' key.
3233 @item kl
3234 String of input sent by typing the left-arrow key.
3235 @item kL
3236 String of input sent by the ``delete line'' key.
3237 @item km
3238 Flag: the terminal has a Meta key.
3239 @item kM
3240 String of input sent by the ``exit insert mode'' key.
3241 @item kn
3242 Numeric value, the number of numbered function keys.
3243 @item kN
3244 String of input sent by the ``next page'' key.
3245 @item ko
3246 Very obsolete string listing the terminal's named function keys.
3247 @item kP
3248 String of input sent by the ``previous page'' key.
3249 @item kr
3250 String of input sent by typing the right-arrow key.
3251 @item kR
3252 String of input sent by the ``scroll reverse'' key.
3253 @item ks
3254 String to make the function keys transmit.
3255 @item kS
3256 String of input sent by the ``clear to end of screen'' key.
3257 @item kt
3258 String of input sent by the ``clear tab stop this column'' key.
3259 @item kT
3260 String of input sent by the ``set tab stop in this column'' key.
3261 @item ku
3262 String of input sent by typing the up-arrow key.
3263 @item l0
3264 String on keyboard labelling function key 0 or 10.
3265 @item l1 @dots{} l9
3266 Strings on keyboard labelling function keys 1 through 9.
3267 @item le
3268 String to move the cursor left one column.
3269 @item LE
3270 String to move cursor left @var{n} columns.
3271 @item li
3272 Number: height of the screen.
3273 @item ll
3274 String to position cursor at lower left corner.
3275 @item lm
3276 Number: lines of display memory.
3277 @item mb
3278 String to enter blinking mode.
3279 @item md
3280 String to enter double-bright mode.
3281 @item me
3282 String to turn off all appearance modes
3283 @item mh
3284 String to enter half-bright mode.
3285 @item mi
3286 Flag: cursor motion in insert mode is safe.
3287 @item mk
3288 String to enter invisible mode.
3289 @item mm
3290 String to enable the functioning of the Meta key.
3291 @item mo
3292 String to disable the functioning of the Meta key.
3293 @item mp
3294 String to enter protected mode.
3295 @item mr
3296 String to enter reverse-video mode.
3297 @item ms
3298 Flag: cursor motion in standout mode is safe.
3299 @item nc
3300 Obsolete flag: do not use ASCII carriage-return on this terminal.
3301 @item nd
3302 String to move the cursor right one column.
3303 @item nl
3304 Obsolete alternative name for the @samp{do} and @samp{sf} capabilities.
3305 @item ns
3306 Flag: the terminal does not normally scroll for sequential output.
3307 @item nw
3308 String to move to start of next line, possibly clearing rest of old line.
3309 @item os
3310 Flag: terminal can overstrike.
3311 @item pb
3312 Number: the lowest baud rate at which padding is actually needed.
3313 @item pc
3314 String containing character for padding.
3315 @item pf
3316 String to terminate redirection of output to the printer.
3317 @item po
3318 String to redirect further output to the printer.
3319 @item pO
3320 String to redirect @var{n} characters ofoutput to the printer.
3321 @item ps
3322 String to print the screen on the attached printer.
3323 @item rc
3324 String to move to last saved cursor position.
3325 @item RI
3326 String to move cursor right @var{n} columns.
3327 @item rp
3328 String to output character @var{c} repeated @var{n} times.
3329 @item rs
3330 String to reset the terminal from any strange modes.
3331 @item sa
3332 String to turn on an arbitrary combination of appearance modes.
3333 @item sc
3334 String to save the current cursor position.
3335 @item se
3336 String to leave standout mode.
3337 @item sf
3338 String to scroll the screen one line up.
3339 @item SF
3340 String to scroll the screen @var{n} lines up.
3341 @item sg
3342 Number: width of magic standout cookie.  Absent if magic cookies are
3343 not used.
3344 @item so
3345 String to enter standout mode.
3346 @item sr
3347 String to scroll the screen one line down.
3348 @item SR
3349 String to scroll the screen @var{n} line down.
3350 @item st
3351 String to set tab stop at current cursor column on all lines.
3352 programs.
3353 @item ta
3354 String to move the cursor right to the next hardware tab stop column.
3355 @item te
3356 String to return terminal to settings for sequential output.
3357 @item ti
3358 String to initialize terminal for random cursor motion.
3359 @item ts
3360 String to move the terminal cursor into the status line.
3361 @item uc
3362 String to underline one character and move cursor right.
3363 @item ue
3364 String to turn off underline mode
3365 @item ug
3366 Number: width of underlining magic cookie.  Absent if underlining
3367 doesn't use magic cookies.
3368 @item ul
3369 Flag: underline by overstriking with an underscore.
3370 @item up
3371 String to move the cursor vertically up one line.
3372 @item UP
3373 String to move cursor vertically up @var{n} lines.
3374 @item us
3375 String to turn on underline mode
3376 @item vb
3377 String to make the screen flash.
3378 @item ve
3379 String to return the cursor to normal.
3380 @item vi
3381 String to make the cursor invisible.
3382 @item vs
3383 String to enhance the cursor.
3384 @item wi
3385 String to set the terminal output screen window.
3386 @item ws
3387 Number: the width of the status line.
3388 @item xb
3389 Flag: superbee terminal.
3390 @item xn
3391 Flag: cursor wraps in a strange way.
3392 @item xs
3393 Flag: clearing a line is the only way to clear the appearance modes of
3394 positions in that line (or, only way to remove magic cookies on that
3395 line).
3396 @item xt
3397 Flag: Teleray 1061; several strange characteristics.
3398 @end table
3399
3400 @node Var Index, Cap Index, Summary, Top
3401 @unnumbered Variable and Function Index
3402
3403 @printindex fn
3404
3405 @node Cap Index, Index, Var Index, Top
3406 @unnumbered Capability Index
3407
3408 @printindex ky
3409
3410 @node Index,, Cap Index, Top
3411 @unnumbered Concept Index
3412
3413 @printindex cp
3414
3415 @contents
3416 @bye