GNUtools/emacs/man/termcap.texi - annotate

Return to termcap.texi CVS log

Up to [Apple XNU] / GNUtools / emacs / man

Annotation of GNUtools/emacs/man/termcap.texi, revision 1.1.1.1

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

unix.superglobalmegacorp.com

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.