![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to termcap-1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info|
Return to termcap-1 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info |
1.1 root 1: Info file: termcap, -*-Text-*-
2: produced by texinfo-format-buffer
3: from file: termcap.texinfo
4:
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: Permission is granted to copy and distribute modified versions of this
14: manual under the conditions for verbatim copying, provided that the entire
15: resulting derived work is distributed under the terms of a permission
16: notice identical to this one.
17:
18: Permission is granted to copy and distribute translations of this manual
19: into another language, under the above conditions for modified versions,
20: except that this permission notice may be stated in a translation approved
21: by the Foundation.
22:
23:
24:
25:
26: File: termcap Node: Top, Prev: (DIR), Up: (DIR), Next: Introduction
27:
28: * Menu:
29:
30: * Introduction::What is termcap? Why this manual?
31: * Library:: The termcap library functions.
32: * Data Base:: What terminal descriptions in `/etc/termcap' look like.
33: * Capabilities::Definitions of the individual terminal capabilities:
34: how to write them in descriptions, and how to use
35: their values to do display updating.
36: * Var Index:: Index of C functions and variables.
37: * Cap Index:: Index of termcap capabilities.
38: * Index:: Concept index.
39:
40:
41: File: termcap Node: Introduction, Prev: Top, Up: Top, Next: Library
42:
43: Introduction
44: ************
45:
46: "Termcap" is a library and data base that enables programs to use
47: display terminals in a terminal-independent manner. It originated in
48: Berkeley Unix.
49:
50: The termcap data base describes the capabilities of hundreds of different
51: display terminals in great detail. Some examples of the information
52: recorded for a terminal could include how many columns wide it is, what
53: string to send to move the cursor to an arbitrary position (including how
54: to encode the row and column numbers), how to scroll the screen up one or
55: several lines, and how much padding is needed for such a scrolling
56: operation.
57:
58: The termcap library is provided for easy access this data base in programs
59: that want to do terminal-independent character-based display output.
60:
61: This manual describes the GNU version of the termcap library, which has
62: some extensions over the Unix version. All the extensions are identified
63: as such, so this manual also tells you how to use the Unix termcap.
64:
65: The GNU version of the termcap library is available free as source code,
66: for use in free programs, and runs on Unix and VMS systems (at least). You
67: can find it in the GNU Emacs distribution in the files `termcap.c' and
68: `tparam.c'.
69:
70: This manual was written for the GNU project, whose goal is to develop a
71: complete free operating system upward-compatible with Unix for user
72: programs. The project is approximately two thirds complete. For more
73: information on the GNU project, including the GNU Emacs editor and the
74: mostly-portable optimizing C compiler, send one dollar to
75:
76: Free Software Foundation
77: 675 Mass Ave
78: Cambridge, MA 02139
79:
80:
81: File: termcap Node: Library, Prev: Top, Up: Top, Next: Data Base
82:
83: The Termcap Library
84: *******************
85:
86: The termcap library is the application programmer's interface to the
87: termcap data base. It contains functions for the following purposes:
88:
89: * Finding the description of the user's terminal type (`tgetent').
90:
91: * Interrogating the description for information on various topics
92: (`tgetnum', `tgetflag', `tgetstr').
93:
94: * Computing and performing padding (`tputs').
95:
96: * Encoding numeric parameters such as cursor positions into the
97: terminal-specific form required for display commands (`tparam',
98: `tgoto').
99:
100: * Menu:
101:
102: * Preparation:: Preparing to use the termcap library.
103: * Find:: Finding the description of the terminal being used.
104: * Interrogate:: Interrogating the description for particular capabilities.
105: * Initialize:: Initialization for output using termcap.
106: * Padding:: Outputting padding.
107: * Parameters:: Encoding parameters such as cursor positions.
108:
109:
110: File: termcap Node: Preparation, Prev: Library, Up: Library, Next: Find
111:
112: Preparing to Use the Termcap Library
113: ====================================
114:
115: To use the termcap library in a program, you need two kinds of preparation:
116:
117: * The compiler needs declarations of the functions and variables in the
118: library.
119:
120: On GNU systems, it suffices to include the header file `termcap.h'
121: in each source file that uses these functions and variables.
122:
123: On Unix systems, there is often no such header file. Then you must
124: explictly declare the variables as external. You can do likewise for
125: the functions, or let them be implicitly declared and cast their
126: values from type `int' to the appropriate type.
127:
128: We illustrate the declarations of the individual termcap library
129: functions with ANSI C prototypes because they show how to pass the
130: arguments. If you are not using the GNU C compiler, you probably
131: cannot use function prototypes, so omit the argument types and names
132: from your declarations.
133:
134: * The linker needs to search the library. Usually either `-ltermcap'
135: or `-ltermlib' as an argument when linking will do this.
136:
137:
138: File: termcap Node: Find, Prev: Preparation, Up: Library, Next: Interrogate
139:
140: Finding a Terminal Description: `tgetent'
141: =========================================
142:
143: An application program that is going to use termcap must first look up the
144: description of the terminal type in use. This is done by calling
145: `tgetent', whose declaration in ANSI Standard C looks like:
146:
147: int tgetent (char *BUFFER, char *TERMTYPE);
148:
149: This function finds the description and remembers it internally so that
150: you can interrogate it about specific terminal capabilities
151: (*Note Interrogate::).
152:
153: The argument TERMTYPE is a string which is the name for the type of
154: terminal to look up. Usually you would obtain this from the environment
155: variable `TERM' using `getenv ("TERM")'.
156:
157: If you are using the GNU version of termcap, you can alternatively ask
158: `tgetent' to allocate enough space. Pass a null pointer for BUFFER, and
159: `tgetent' itself allocates the storage using `malloc'. In this case the
160: returned value on success is the address of the storage, cast to `int'.
161: But normally there is no need for you to look at the address. Do not
162: free the storage yourself.
163:
164: With the Unix version of termcap, you must allocate space for the
165: description yourself and pass the address of the space as the argument
166: BUFFER. There is no way you can tell how much space is needed, so
167: the convention is to allocate a buffer 2048 characters long and assume that
168: is enough. (Formerly the convention was to allocate 1024 characters and
169: assume that was enough. But one day, for one kind of terminal, that was
170: not enough.)
171:
172: No matter how the space to store the description has been obtained,
173: termcap records its address internally for use when you later
174: interrogate the description with `tgetnum', `tgetstr' or `tgetflag'. If
175: the buffer was allocated by termcap, it will be freed by termcap too if
176: you call `tgetent' again. If the buffer was provided by you, you must
177: make sure that its contents remain unchanged for as long as you still
178: plan to interrogate the description.
179:
180: The return value of `tgetent' is -1 if there is some difficulty
181: accessing the data base of terminal types, 0 if the data base is accessible
182: but the specified type is not defined in it, and some other value
183: otherwise.
184:
185: Here is how you might use the function `tgetent':
186:
187: #ifdef unix
188: static char term_buffer[2048];
189: #else
190: #define term_buffer 0
191: #endif
192:
193: init_terminal_data ()
194: {
195: char *termtype = getenv ("TERM");
196: int success;
197:
198: if (termtype == 0)
199: fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
200:
201: success = tgetent (term_buffer, termtype);
202: if (success < 0)
203: fatal ("Could not access the termcap data base.\n");
204: if (success == 0)
205: fatal ("Terminal type `%s' is not defined.\n", termtype);
206: }
207:
208: Here we assume the function `fatal' prints an error message and exits.
209:
210: If the environment variable `TERMCAP' is defined, its value is used to
211: override the terminal type data base. The function `tgetent' checks the
212: value of `TERMCAP' automatically. If the value starts with `/' then it
213: is taken as a file name to use as the data base file, instead of
214: `/etc/termcap' which is the standard data base. If the value does not
215: start with `/' then it is itself used as the terminal description,
216: provided that the terminal type TERMTYPE is among the types it claims to
217: apply to. *Note Data Base::, for information on the format of a
218: terminal description.
219:
220:
221: File: termcap Node: Interrogate, Prev: Find, Up: Library, Next: Initialize
222:
223: Interrogating the Terminal Description
224: ======================================
225:
226: Each piece of information recorded in a terminal description is called a
227: "capability". Each defined terminal capability has a two-letter code
228: name and a specific meaning. For example, the number of columns is named
229: `co'. *Note Capabilities::, for definitions of all the standard
230: capability names.
231:
232: Once you have found the proper terminal description with `tgetent'
233: (*Note Find::), your application program must "interrogate" it for
234: various terminal capabilities. You must specify the two-letter code of
235: the capability whose value you seek.
236:
237: Capability values can be numeric, boolean (capability is either present
238: or absent) or strings. Any particular capability always has the same
239: value type; for example, `co' always has a numeric value, while `am'
240: (automatic wrap at margin) is always a flag, and `cm' (cursor motion
241: command) always has a string value. The documentation of each
242: capability says which type of value it has.
243:
244: There are three functions to use to get the value of a capability,
245: depending on the type of value the capability has. Here are their
246: declarations in ANSI C:
247:
248: int tgetnum (char *NAME);
249: int tgetflag (char *NAME);
250: char *tgetstr (char *NAME, char **AREA);
251:
252: `tgetnum'
253: Use `tgetnum' to get a capability value that is numeric. The
254: argument NAME is the two-letter code name of the capability. If
255: the capability is present, `tgetnum' returns the numeric value
256: (which is nonnegative). If the capability is not mentioned in the
257: terminal description, `tgetnum' returns -1.
258:
259: `tgetflag'
260: Use `tgetflag' to get a boolean value. If the capability
261: NAME is present in the terminal description, `tgetflag'
262: returns 1; otherwise, it returns 0.
263:
264: `tgetstr'
265: Use `tgetstr' to get a string value. It returns a pointer to a
266: string which is the capability value, or a null pointer if the
267: capability is not present in the terminal description.
268:
269: There are two ways `tgetstr' can find space to store the string value:
270:
271: * You can ask `tgetstr' to allocate the space. Pass a null
272: pointer for the argument AREA, and `tgetstr' will use
273: `malloc' to allocate storage big enough for the value.
274: Termcap will never free this storage or refer to it again; you
275: should free it when you are finished with it.
276:
277: This method is more robust, since there is no need to guess how
278: much space is needed. But it is supported only by the GNU
279: termcap library.
280:
281: * You can provide the space. Provide for the argument AREA the
282: address of a pointer variable of type `char *'. Before calling
283: `tgetstr', initialize the variable to point at available space.
284: Then `tgetstr' will store the string value in that space and will
285: increment the pointer variable to point after the space that has been
286: used. You can use the same pointer variable for many calls to
287: `tgetstr'.
288:
289: There is no way to determine how much space is needed for a single
290: string, and no way for you to prevent or handle overflow of the area
291: you have provided. However, you can be sure that the total size of
292: all the string values you will obtain from the terminal description is
293: no greater than the size of the description (unless you get the same
294: capability twice). You can determine that size with `strlen' on
295: the buffer you provided to `tgetent'. See below for an example.
296:
297: Providing the space yourself is the only method supported by the Unix
298: version of termcap.
299:
300: Note that you do not have to specify a terminal type or terminal
301: description for the interrogation functions. They automatically use the
302: description found by the most recent call to `tgetent'.
303:
304: Here is an example of interrogating a terminal description for various
305: capabilities, with conditionals to select between the Unix and GNU methods
306: of providing buffer space.
307:
308: char *tgetstr ();
309:
310: char *cl_string, *cm_string;
311: int height;
312: int width;
313: int auto_wrap;
314:
315: char PC; /* For tputs. */
316: char *BC; /* For tgoto. */
317: char *UP;
318:
319: interrogate_terminal ()
320: {
321: #ifdef UNIX
322: /* Here we assume that an explicit term_buffer
323: was provided to tgetent. */
324: char *buffer
325: = (char *) malloc (strlen (term_buffer));
326: #define BUFFADDR &buffer
327: #else
328: #define BUFFADDR 0
329: #endif
330:
331: char *temp;
332:
333: /* Extract information we will use. */
334: cl_string = tgetstr ("cl", BUFFADDR);
335: cm_string = tgetstr ("cm", BUFFADDR);
336: auto_wrap = tgetflag ("am");
337: height = tgetnum ("li");
338: width = tgetnum ("co");
339:
340: /* Extract information that termcap functions use. */
341: temp = tgetstr ("pc", BUFFADDR);
342: PC = temp ? *temp : 0;
343: BC = tgetstr ("le", BUFFADDR);
344: UP = tgetstr ("up", BUFFADDR);
345: }
346:
347: *Note Padding::, for information on the variable `PC'. *Note Using Parameters::, for information on `UP' and `BC'.
348:
349:
350: File: termcap Node: Initialize, Prev: Interrogate, Up: Library, Next: Padding
351:
352: Initialization for Use of Termcap
353: =================================
354:
355: Before starting to output commands to a terminal using termcap,
356: an application program should do two things:
357:
358: * Initialize various global variables which termcap library output
359: functions refer to. These include `PC' and `ospeed' for padding
360: (*Note Output Padding::) and `UP' and `BC' for cursor motion (*Note
361: tgoto::).
362:
363: * Tell the kernel to turn off alteration and padding of horizontal-tab
364: characters sent to the terminal.
365:
366: To turn off output processing in Berkeley Unix you would use `ioctl'
367: with code `TIOCLSET' to set the bit named `LLITOUT', and clear the bits
368: `ANYDELAY' using `TIOCSETN'. In POSIX or System V, you must clear the
369: bit named `OPOST'. Refer to the system documentation for details.
370:
371: If you do not set the terminal flags properly, some older terminals will
372: not work. This is because their commands may contain the characters that
373: normally signify newline, carriage return and horizontal tab---characters
374: which the kernel thinks it ought to modify before output.
375:
376: When you change the kernel's terminal flags, you must arrange to restore
377: them to their normal state when your program exits. This implies that the
378: program must catch fatal signals such as `SIGQUIT' and `SIGINT'
379: and restore the old terminal flags before actually terminating.
380:
381: Modern terminals' commands do not use these special characters, so if you
382: do not care about problems with old terminals, you can leave the kernel's
383: terminal flags unaltered.
384:
385:
386: File: termcap Node: Padding, Prev: Initialize, Up: Library, Next: Parameters
387:
388: Padding
389: =======
390:
391: "Padding" means outputting null characters following a terminal display
392: command that takes a long time to execute. The terminal description says
393: which commands require padding and how much; the function `tputs',
394: described below, outputs a terminal command while extracting from it the
395: padding information, and then outputs the padding that is necessary.
396:
397: * Menu:
398:
399: * Why Pad:: Explanation of padding.
400: * Describe Padding:: The data base says how much padding a terminal needs.
401: * Output Padding:: Using `tputs' to output the needed padding.
402:
403:
404: File: termcap Node: Why Pad, Prev: Padding, Up: Padding, Next: Describe Padding
405:
406: Why Pad, and How
407: ----------------
408:
409: Most types of terminal have commands that take longer to execute than they
410: do to send over a high-speed line. For example, clearing the screen may
411: take 20msec once the entire command is received. During that time, on a
412: 9600 bps line, the terminal could receive about 20 additional output
413: characters while still busy clearing the screen. Every terminal has a
414: certain amount of buffering capacity to remember output characters that
415: cannot be processed yet, but too many slow commands in a row can cause the
416: buffer to fill up. Then any additional output that cannot be processed
417: immediately will be lost.
418:
419: To avoid this problem, we normally follow each display command with enough
420: useless charaters (usually null characters) to fill up the time that the
421: display command needs to execute. This does the job if the terminal throws
422: away null characters without using up space in the buffer (which most
423: terminals do). If enough padding is used, no output can ever be lost. The
424: right amount of padding avoids loss of output without slowing down
425: operation, since the time used to transmit padding is time that nothing
426: else could be done.
427:
428: The number of padding characters needed for an operation depends on the
429: line speed. In fact, it is proportional to the line speed. A 9600 baud
430: line transmits about one character per msec, so the clear screen command in
431: the example above would need about 20 characters of padding. At 1200 baud,
432: however, only about 3 characters of padding are needed to fill up 20msec.
433:
434:
435: File: termcap Node: Describe Padding, Prev: Why Pad, Up: Padding, Next: Output Padding
436:
437: Specifying Padding in a Terminal Description
438: --------------------------------------------
439:
440: In the terminal description, the amount of padding required by each display
441: command is recorded as a sequence of digits at the front of the command.
442: These digits specify the padding time in msec. They can be followed
443: optionally by a decimal point and one more digit, which is a number of
444: tenths of msec.
445:
446: Sometimes the padding needed by a command depends on the cursor position.
447: For example, the time taken by an "insert line" command is usually
448: proportional to the number of lines that need to be moved down or cleared.
449: An asterisk (`*') following the padding time says that the time
450: should be multiplied by the number of screen lines affected by the command.
451:
452: :al=1.3*\E[L:
453:
454: is used to describe the "insert line" command for a certain terminal.
455: The padding required is 1.3 msec per line affected. The command itself is
456: `ESC [ L'.
457:
458: The padding time specified in this way tells `tputs' how many pad
459: characters to output. *Note Output Padding::.
460:
461: Two special capability values affect padding for all commands. These are
462: the `pc' and `pb'. The variable `pc' specifies the
463: character to pad with, and `pb' the speed below which no padding is
464: needed. The defaults for these variables, a null character and 0,
465: are correct for most terminals. *Note Pad Specs::.
466:
467:
468: File: termcap Node: Output Padding, Prev: Describe Padding, Up: Padding
469:
470: Performing Padding with `tputs'
471: -------------------------------
472:
473: Use the termcap function `tputs' to output a string containing an
474: optional padding spec of the form described above (*Note Describe Padding::). The function `tputs' strips off and decodes the padding
475: spec, outputs the rest of the string, and then outputs the appropriate
476: padding. Here is its declaration in ANSI C:
477:
478: char PC;
479: short ospeed;
480:
481: int tputs (char *STRING, int NLINES, int (*OUTFUN) ());
482:
483: Here STRING is the string (including padding spec) to be output;
484: NLINES is the number of lines affected by the operation, which is
485: used to multiply the amount of padding if the padding spec ends with a
486: `*'. Finally, OUTFUN is a function (such as `fputchar')
487: that is called to output each character. When actually called,
488: OUTFUN should expect one argument, a character.
489:
490: The operation of `tputs' is controlled by two global variables,
491: `ospeed' and `PC'. The value of `ospeed' is supposed to be
492: the terminal output speed, encoded as in the `ioctl' system call which
493: gets the speed information. This is needed to compute the number of
494: padding characters. The value of `PC' is the character used for
495: padding.
496:
497: You are responsible for storing suitable values into these variables
498: before using `tputs'. The value stored into the `PC' variable should be
499: taken from the `pc' capability in the terminal description (*Note Pad
500: Specs::). Store zero in `PC' if there is no `pc' capability.
501:
502: The argument NLINES requires some thought. Normally, it should be the
503: number of lines whose contents will be cleared or moved by the command.
504: For cursor motion commands, or commands that do editing within one line,
505: use the value 1. For most commands that affect multiple lines, such as
506: `al' (insert a line) and `cd' (clear from the cursor to the end of the
507: screen), NLINES should be the screen height minus the current vertical
508: position (origin 0). For multiple insert and scroll commands such as
509: `AL' (insert multiple lines), that same value for NLINES is correct; the
510: number of lines being inserted is not correct.
511:
512: If a "scroll window" feature is used to reduce the number of lines
513: affected by a command, the value of NLINES should take this into
514: account. This is because the delay time required depends on how much work
515: the terminal has to do, and the scroll window feature reduces the work.
516: *Note Scrolling::.
517:
518: Commands such as `ic' and `dc' (insert or delete characters) are
519: problematical because the padding needed by these commands is proportional
520: to the number of characters affected, which is the number of columns from
521: the cursor to the end of the line. It would be nice to have a way to
522: specify such a dependence, and there is no need for dependence on vertical
523: position in these commands, so it is an obvious idea to say that for these
524: commands NLINES should really be the number of columns affected.
525: However, the definition of termcap clearly says that NLINES is always
526: the number of lines affected, even in this case, where it is always 1. It
527: is not easy to change this rule now, because too many programs and terminal
528: descriptions have been written to follow it.
529:
530: Because NLINES is always 1 for the `ic' and `dc' strings,
531: there is no reason for them to use `*', but some of them do. These
532: should be corrected by deleting the `*'. If, some day, such entries
533: have disappeared, it may be possible to change to a more useful convention
534: for the NLINES argument for these operations without breaking any
535: programs.
536:
537:
538: File: termcap Node: Parameters, Prev: Padding, Up: Library
539:
540: Filling In Parameters
541: =====================
542:
543: Some terminal control strings require numeric "parameters". For
544: example, when you move the cursor, you need to say what horizontal and
545: vertical positions to move it to. The value of the terminal's `cm'
546: capability, which says how to move the cursor, cannot simply be a string of
547: characters; it must say how to express the cursor position numbers and
548: where to put them within the command.
549:
550: The specifications of termcap include conventions as to which string-valued
551: capabilities require parameters, how many parameters, and what the
552: parameters mean; for example, it defines the `cm' string to take
553: two parameters, the vertical and horizontal positions, with 0,0 being the
554: upper left corner. These conventions are described where the individual
555: commands are documented.
556:
557: Termcap also defines a language used within the capability definition for
558: specifying how and where to encode the parameters for output. This language
559: uses character sequences starting with `%'. (This is the same idea as
560: `printf', but the details are different.) The language for parameter
561: encoding is described in this section.
562:
563: A program that is doing display output calls the functions `tparam' or
564: `tgoto' to encode parameters according to the specifications. These
565: functions produce a string containing the actual commands to be output (as
566: well a padding spec which must be processed with `tputs';
567: *Note Padding::).
568:
569: * Menu:
570:
571: * Encode Parameters:: The language for encoding parameters.
572: * Using Parameters:: Outputting a string command with parameters.
573:
574:
575: File: termcap Node: Encode Parameters, Prev: Parameters, Up: Parameters, Next: Using Parameters
576:
577: Describing the Encoding
578: -----------------------
579:
580: A terminal command string that requires parameters contains special
581: character sequences starting with `%' to say how to encode the
582: parameters. These sequences control the actions of `tparam' and
583: `tgoto'.
584:
585: The parameters values passed to `tparam' or `tgoto' are
586: considered to form a vector. A pointer into this vector determines
587: the next parameter to be processed. Some of the `%'-sequences
588: encode one parameter and advance the pointer to the next parameter.
589: Other `%'-sequences alter the pointer or alter the parameter
590: values without generating output.
591:
592: For example, the `cm' string for a standard ANSI terminal is written
593: as `\E[%i%d;%dH'. (`\E' stands for ESC.) `cm' by
594: convention always requires two parameters, the vertical and horizontal goal
595: positions, so this string specifies the encoding of two parameters. Here
596: `%i' increments the two values supplied, and each `%d' encodes
597: one of the values in decimal. If the cursor position values 20,58 are
598: encoded with this string, the result is `\E[21;59H'.
599:
600: First, here are the `%'-sequences that generate output. Except for
601: `%%', each of them encodes one parameter and advances the pointer
602: to the following parameter.
603:
604: `%%'
605: Output a single `%'. This is the only way to represent a literal
606: `%' in a terminal command with parameters. `%%' does not
607: use up a parameter.
608:
609: `%d'
610: As in `printf', output the next parameter in decimal.
611:
612: `%2'
613: Like `%02d' in `printf': output the next parameter in
614: decimal, and always use at least two digits.
615:
616: `%3'
617: Like `%03d' in `printf': output the next parameter in
618: decimal, and always use at least three digits. Note that `%4'
619: and so on are *not* defined.
620:
621: `%.'
622: Output the next parameter as a single character whose ASCII code is
623: the parameter value. Like `%c' in `printf'.
624:
625: `%+CHAR'
626: Add the next parameter to the character CHAR, and output the
627: resulting character. For example, `%+ ' represents 0 as a space,
628: 1 as `!', etc.
629:
630: The following `%'-sequences specify alteration of the parameters (their
631: values, or their order) rather than encoding a parameter for output.
632: They generate no output; they are used only for their side effects on
633: the parameters. Also, they do not advance the "next parameter" pointer
634: except as explicitly stated. Only `%i', `%r' and `%>' are defined in
635: standard Unix termcap. The others are GNU extensions.
636:
637: `%i'
638: Increment the next two parameters. This is used for terminals that
639: expect cursor positions in origin 1. For example, `%i%d,%d' would
640: output two parameters with `1' for 0, `2' for 1, etc.
641:
642: `%r'
643: Interchange the next two parameters. This is used for terminals whose
644: cursor positioning command expects the horizontal position first.
645:
646: `%s'
647: Skip the next parameter. Do not output anything.
648:
649: `%b'
650: Back up one parameter. The last parameter used will become once again
651: the next parameter to be output, and the next output command will use
652: it. Using `%b' more than once, you can back up any number of
653: parameters, and you can refer to each parameter any number of times.
654:
655: `%>C1C2'
656: Conditionally increment the next parameter. Here C1 and C2 are
657: characters which stand for their ASCII codes as numbers. If the
658: next parameter is greater than the ASCII code of C1, the ASCII code
659: of C2 is added to it.
660:
661: `%a OP TYPE POS'
662: Perform arithmetic on the next parameter, do not use it up, and do not
663: output anything. Here OP specifies the arithmetic operation,
664: while TYPE and POS together specify the other operand.
665:
666: Spaces are used above to separate the operands for clarity; the spaces
667: don't appear in the data base, where this sequence is exactly five
668: characters long.
669:
670: The character OP says what kind of arithmetic operation to
671: perform. It can be any of these characters:
672:
673: `='
674: assign a value to the next parameter, ignoring its old value.
675: The new value comes from the other operand.
676:
677: `+'
678: add the other operand to the next parameter.
679:
680: `-'
681: subtract the other operand from the next parameter.
682:
683: `*'
684: multiply the next parameter by the other operand.
685:
686: `/'
687: divide the next parameter by the other operand.
688:
689: The "other operand" may be another parameter's value or a constant;
690: the character TYPE says which. It can be:
691:
692: `p'
693: Use another parameter. The character POS says which
694: parameter to use. Subtract 64 from its ASCII code to get the
695: position of the desired parameter relative to this one. Thus,
696: the character `A' as POS means the parameter after the
697: next one; the character `?' means the parameter before the
698: next one.
699:
700: `c'
701: Use a constant value. The character POS specifies the
702: value of the constant. The 0200 bit is cleared out, so that 0200
703: can be used to represent zero.
704:
705: The following `%'-sequences are special purpose hacks to compensate
706: for the weird designs of obscure terminals. They modify the next parameter
707: or the next two parameters but do not generate output and do not use up any
708: parameters. `%m' is a GNU extension; the others are defined in
709: standard Unix termcap.
710:
711: `%n'
712: Exclusive-or the next parameter with 0140, and likewise the parameter
713: after next.
714:
715: `%m'
716: Complement all the bits of the next parameter and the parameter after next.
717:
718: `%B'
719: Encode the next parameter in BCD. It alters the value of the
720: parameter by adding six times the quotient of the parameter by ten.
721: Here is a C statement that shows how the new value is computed:
722:
723: PARM = (PARM / 10) * 16 + PARM % 10;
724:
725: `%D'
726: Transform the next parameter as needed by Delta Data terminals.
727: This involves subtracting twice the remainder of the parameter by 16.
728:
729: PARM -= 2 * (PARM % 16);
730:
731:
732: File: termcap Node: Using Parameters, Prev: Encode Parameters, Up: Parameters
733:
734: Sending Display Commands with Parameters
735: ----------------------------------------
736:
737: The termcap library functions `tparam' and `tgoto' serve as the
738: analog of `printf' for terminal string parameters. The newer function
739: `tparam' is a GNU extension, more general but missing from Unix
740: termcap. The original parameter-encoding function is `tgoto', which
741: is preferable for cursor motion.
742:
743: * Menu:
744:
745: * tparam:: The general case, for GNU termcap only.
746: * tgoto:: The special case of cursor motion.
747:
748:
749: File: termcap Node: tparam, Prev: Using Parameters, Up: Using Parameters, Next: tgoto
750:
751: `tparam'
752: ........
753:
754: The function `tparam' can encode display commands with any number of
755: parameters and allows you to specify the buffer space. It is the preferred
756: function for encoding parameters for all but the `cm' capability. Its
757: ANSI C declaration is as follows:
758:
759: char *tparam (char *CTLSTRING, char *BUFFER, int SIZE, int PARM1,...)
760:
761: The arguments are a control string CTLSTRING (the value of a terminal
762: capability, presumably), an output buffer BUFFER and SIZE, and
763: any number of integer parameters to be encoded. The effect of
764: `tparam' is to copy the control string into the buffer, encoding
765: parameters according to the `%' sequences in the control string.
766:
767: You describe the output buffer by its address, BUFFER, and its size
768: in bytes, SIZE. If the buffer is not big enough for the data to be
769: stored in it, `tparam' calls `malloc' to get a larger buffer. In
770: either case, `tparam' returns the address of the buffer it ultimately
771: uses. If the value equals BUFFER, your original buffer was used.
772: Otherwise, a new buffer was allocated, and you must free it after you are
773: done with printing the results. If you pass zero for SIZE and
774: BUFFER, `tparam' always allocates the space with `malloc'.
775:
776: All capabilities that require parameters also have the ability to specify
777: padding, so you should use `tputs' to output the string produced by
778: `tparam'. *Note Padding::. Here is an example.
779:
780: {
781: char *buf;
782: char buffer[40];
783:
784: buf = tparam (command, buffer, 40, parm);
785: tputs (buf, 1, fputchar);
786: if (buf != buffer)
787: free (buf);
788: }
789:
790: If a parameter whose value is zero is encoded with `%.'-style encoding,
791: the result is a null character, which will confuse `tputs'. This would
792: be a serious problem, but luckily `%.' encoding is used only by a few
793: old models of terminal, and only for the `cm' capability. To solve the
794: problem, use `tgoto' rather than `tparam' to encode the `cm' capability.
795:
796:
797: File: termcap Node: tgoto, Prev: tparam, Up: Using Parameters
798:
799: `tgoto'
800: .......
801:
802: The special case of cursor motion is handled by `tgoto'. There
803: are two reasons why you might choose to use `tgoto':
804:
805: * For Unix compatibility, because Unix termcap does not have `tparam'.
806:
807: * For the `cm' capability, since `tgoto' has a special feature
808: to avoid problems with null characters, tabs and newlines on certain old
809: terminal types that use `%.' encoding for that capability.
810:
811: Here is how `tgoto' might be declared in ANSI C:
812:
813: char *tgoto (char *CSTRING, int HPOS, int VPOS)
814:
815: There are three arguments, the terminal description's `cm' string and
816: the two cursor position numbers; `tgoto' computes the parametrized
817: string in an internal static buffer and returns the address of that buffer.
818: The next time you use `tgoto' the same buffer will be reused.
819:
820: Parameters encoded with `%.' encoding can generate null characters,
821: tabs or newlines. These might cause trouble: the null character because
822: `tputs' would think that was the end of the string, the tab because
823: the kernel or other software might expand it into spaces, and the newline
824: becaue the kernel might add a carriage-return, or padding characters
825: normally used for a newline. To prevent such problems, `tgoto' is
826: careful to avoid these characters. Here is how this works: if the target
827: cursor position value is such as to cause a problem (that is to say, zero,
828: nine or ten), `tgoto' increments it by one, then compensates by
829: appending a string to move the cursor back or up one position.
830:
831: The compensation strings to use for moving back or up are found in global
832: variables named `BC' and `UP'. These are actual external C
833: variables with upper case names; they are declared `char *'. It is up
834: to you to store suitable values in them, normally obtained from the
835: `le' and `up' terminal capabilities in the terminal description
836: with `tgetstr'. Alternatively, if these two variables are both zero,
837: the feature of avoiding nulls, tabs and newlines is turned off.
838:
839: It is safe to use `tgoto' for commands other than `cm' only if
840: you have stored zero in `BC' and `UP'.
841:
842: Note that `tgoto' reverses the order of its operands: the horizontal
843: position comes before the vertical position in the arguments to `tgoto',
844: even though the vertical position comes before the horizontal in the
845: parameters of the `cm' string. If you use `tgoto' with a command such
846: as `AL' that takes one parameter, you must pass the parameter to `tgoto'
847: as the "vertical position".
848:
849:
850: File: termcap Node: Data Base, Prev: Library, Up: Top, Next: Capabilities
851:
852: The Format of the Data Base
853: ***************************
854:
855: The termcap data base of terminal descriptions is stored in the file
856: `/etc/termcap'. It contains terminal descriptions, blank lines, and
857: comments.
858:
859: A terminal description starts with one or more names for the terminal type.
860: The information in the description is a series of "capability names"
861: and values. The capability names have standard meanings
862: (*Note Capabilities::) and their values describe the terminal.
863:
864: * Menu:
865:
866: * Format:: Overall format of a terminal description.
867: * Capability Format:: Format of capabilities within a description.
868: * Naming:: Naming conventions for terminal types.
869: * Inheriting:: Inheriting part of a description from
870: a related terminal type.
871:
872:
873: File: termcap Node: Format, Prev: Data Base, Up: Data Base, Next: Capability Format
874:
875: Terminal Description Format
876: ===========================
877:
878: Aside from comments (lines starting with `#', which are ignored), each
879: nonblank line in the termcap data base is a terminal description.
880: A terminal description is nominally a single line, but it can be split
881: into multiple lines by inserting the two characters `\ newline'.
882: This sequence is ignored wherever it appears in a description.
883:
884: The preferred way to split the description is between capabilities: insert
885: the four characters `: \ newline tab' immediately before any colon.
886: This allows each sub-line to start with some indentation. This works
887: because, after the `\ newline' are ignored, the result is `: tab
888: :'; the first colon ends the preceding capability and the second colon
889: starts the next capability. If you split with `\ newline' alone, you
890: may not add any indentation after them.
891:
892: Here is a real example of a terminal description:
893:
894: dw|vt52|DEC vt52:\
895: :cr=^M:do=^J:nl=^J:bl=^G:\
896: :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
897: :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
898: :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
899:
900: Each terminal description begins with several names for the terminal type.
901: The names are separated by `|' characters, and a colon ends the last
902: name. The first name should be two characters long; it exists only for the
903: sake of very old Unix systems and is never used in modern systems. The
904: last name should be a fully verbose name such as "DEC vt52" or "Ann
905: Arbor Ambassador with 48 lines". The other names should include whatever
906: the user ought to be able to specify to get this terminal type, such as
907: `vt52' or `aaa-48'. *Note Naming::, for information on how to
908: choose terminal type names.
909:
910: After the terminal type names come the terminal capabilities, separated by
911: colons and with a colon after the last one. Each capability has a
912: two-letter name, such as `cm' for "cursor motion string" or `li'
913: for "number of display lines".
914:
915:
916: File: termcap Node: Capability Format, Prev: Format, Up: Data Base, Next: Naming
917:
918: Writing the Capabilities
919: ========================
920:
921: There are three kinds of capabilities: flags, numbers, and strings. Each
922: kind has its own way of being written in the description. Each defined
923: capability has by convention a particular kind of value; for example,
924: `li' always has a numeric value and `cm' always a string value.
925:
926: A flag capability is thought of as having a boolean value: the value is
927: true if the capability is present, false if not. When the capability is
928: present, just write its name between two colons.
929:
930: A numeric capability has a value which is a nonnegative number. Write
931: the capability name, a `#', and the number, between two colons. For
932: example, `...:li#48:...' is how you specify the `li' capability for 48
933: lines.
934:
935: A string-valued capability has a value which is a sequence of
936: characters. Usually these are the characters used to perform some
937: display operation. Write the capability name, a `=', and the characters
938: of the value, between two colons. For example, `...:cm=\E[%i%d;%dH:...'
939: is how the cursor motion command for a standard ANSI terminal would be
940: specified.
941:
942: Special characters in the string value can be expressed using `\'-escape
943: sequences as in C; in addition, `\E' stands for ESC. `^' is also a kind
944: of escape character; `^' followed by CHAR stands for the
945: control-equivalent of CHAR. Thus, `^a' stands for the character
946: control-a, just like `\001'. `\' and `^' themselves can be represented
947: as `\\' and `\^'.
948:
949: To include a colon in the string, you must write `\072'. You might
950: ask, "Why can't `\:' be used to represent a colon?" The reason is
951: that the interrogation functions do not count slashes while looking for a
952: capability. Even if `:ce=ab\:cd:' were interpreted as giving the
953: `ce' capability the value `ab:cd', it would also appear to define
954: `cd' as a flag.
955:
956: The string value will often contain digits at the front to specify padding
957: (*Note Padding::) and/or `%'-sequences within to specify how to encode
958: parameters (*Note Parameters::). Although these things are not to be
959: output literally to the terminal, they are considered part of the value of
960: the capability. They are special only when the string value is processed
961: by `tputs', `tparam' or `tgoto'. By contrast, `\' and
962: `^' are considered part of the syntax for specifying the characters
963: in the string.
964:
965: Let's look at the VT52 example again:
966:
967: dw|vt52|DEC vt52:\
968: :cr=^M:do=^J:nl=^J:bl=^G:\
969: :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
970: :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
971: :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
972:
973: Here we see the numeric-valued capabilities `co' and `li', the
974: flags `bs' and `pt', and many string-valued capabilities. Most
975: of the strings start with ESC represented as `\E'. The rest
976: contain control characters represented using `^'. The meanings of the
977: individual capabilities are defined elsewhere (*Note Capabilities::).
978:
979:
980: File: termcap Node: Naming, Prev: Capability Format, Up: Data Base, Next: Inheriting
981:
982: Terminal Type Name Conventions
983: ==============================
984:
985: There are conventions for choosing names of terminal types. For one thing,
986: all letters should be in lower case. The terminal type for a terminal in
987: its most usual or most fundamental mode of operation should not have a
988: hyphen in it.
989:
990: If the same terminal has other modes of operation which require
991: different terminal descriptions, these variant descriptions are given
992: names made by adding suffixes with hyphens. Such alternate descriptions
993: are used for two reasons:
994:
995: * When the terminal has a switch that changes its behavior. Since the
996: computer cannot tell how the switch is set, the user must tell the
997: computer by choosing the appropriate terminal type name.
998:
999: For example, the VT-100 has a setup flag that controls whether the
1000: cursor wraps at the right margin. If this flag is set to "wrap",
1001: you must use the terminal type `vt100-am'. Otherwise you must use
1002: `vt100-nam'. Plain `vt100' is defined as a synonym for either
1003: `vt100-am' or `vt100-nam' depending on the preferences of the local
1004: site.
1005:
1006: The standard suffix `-am' stands for "automatic margins".
1007:
1008: * To give the user a choice in how to use the terminal. This is done
1009: when the terminal has a switch that the computer normally controls.
1010:
1011: For example, the Ann Arbor Ambassador can be configured with many
1012: screen sizes ranging from 20 to 60 lines. Fewer lines make bigger
1013: characters but more lines let you see more of what you are editing.
1014: As a result, users have different preferences. Therefore, termcap
1015: provides terminal types for many screen sizes. If you choose type
1016: `aaa-30', the terminal will be configured to use 30 lines; if you
1017: choose `aaa-48', 48 lines will be used, and so on.
1018:
1019: Here is a list of standard suffixes and their conventional meanings:
1020:
1021: `-w'
1022: Short for "wide". This is a mode that gives the terminal more
1023: columns than usual. This is normally a user option.
1024:
1025: `-am'
1026: "Automatic margins". This is an alternate description for use when
1027: the terminal's margin-wrap switch is on; it contains the `am'
1028: flag. The implication is that normally the switch is off and the
1029: usual description for the terminal says that the switch is off.
1030:
1031: `-nam'
1032: "No automatic margins". The opposite of `-am', this names an
1033: alternative description which lacks the `am' flag. This implies
1034: that the terminal is normally operated with the margin-wrap switch
1035: turned on, and the normal description of the terminal says so.
1036:
1037: `-na'
1038: "No arrows". This terminal description initializes the terminal to
1039: keep its arrow keys in local mode. This is a user option.
1040:
1041: `-rv'
1042: "Reverse video". This terminal description causes text output for
1043: normal video to appear as reverse, and text output for reverse
1044: video to come out as normal. Often this description differs from
1045: the usual one by interchanging the two strings which turn reverse
1046: video on and off.
1047:
1048: This is a user option; you can choose either the "reverse video"
1049: variant terminal type or the normal terminal type, and termcap will
1050: obey.
1051:
1052: `-s'
1053: "Status". Says to enable use of a status line which ordinary output
1054: does not touch (*Note Status Line::).
1055:
1056: Some terminals have a special line that is used only as a status line.
1057: For these terminals, there is no need for an `-s' variant; the
1058: status line commands should be defined by default. On other
1059: terminals, enabling a status line means removing one screen line from
1060: ordinary use and reducing the effective screen height. For these
1061: terminals, the user can choose the `-s' variant type to request
1062: use of a status line.
1063:
1064: `-NLINES'
1065: Says to operate with NLINES lines on the screen, for terminals
1066: such as the Ambassador which provide this as an option. Normally this
1067: is a user option; by choosing the terminal type, you control how many
1068: lines termcap will use.
1069:
1070: `-NPAGESp'
1071: Says that the terminal has NPAGES pages worth of screen memory,
1072: for terminals where this is a hardware option.
1073:
1074: `-unk'
1075: Says that description is not for direct use, but only for reference in
1076: `tc' capabilities. Such a description is a kind of subroutine,
1077: because it describes the common characteristics of several variant
1078: descriptions that would use other suffixes in place of `-unk'.
1079:
1080:
1081: File: termcap Node: Inheriting, Prev: Naming, Up: Data Base
1082:
1083: Inheriting from Related Descriptions
1084: ====================================
1085:
1086: When two terminal descriptions are similar, their identical parts do not
1087: need to be given twice. Instead, one of the two can be defined in terms of
1088: the other, using the `tc' capability. We say that one description
1089: "refers to" the other, or "inherits from" the other.
1090:
1091: The `tc' capability must be the last one in the terminal description,
1092: and its value is a string which is the name of another terminal type which
1093: is referred to. For example,
1094:
1095: N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
1096: :ti=\E[2J\E[30;0;0;30p:\
1097: :te=\E[60;0;0;30p\E[30;1H\E[J:\
1098: :li#30:tc=aaa-unk:
1099:
1100: defines the terminal type `aaa-30' (also known as plain `aaa') in
1101: terms of `aaa-unk', which defines everything about the Ambassador that
1102: is independent of screen height. The types `aaa-36', `aaa-48'
1103: and so on for other screen heights are likewise defined to inherit from
1104: `aaa-unk'.
1105:
1106: The capabilities overridden by `aaa-30' include `li', which says
1107: how many lines there are, and `ti' and `te', which configure the
1108: terminal to use that many lines.
1109:
1110: The effective terminal description for type `aaa' consists of the text
1111: shown above followed by the text of the description of `aaa-unk'. The
1112: `tc' capability is handled automatically by `tgetent', which
1113: finds the description thus referenced and combines the two descriptions
1114: (*Note Find::). Therefore, only the implementor of the terminal
1115: descriptions needs to think about using `tc'. Users and application
1116: programmers do not need to be concerned with it.
1117:
1118: Since the reference terminal description is used last, capabilities
1119: specified in the referring description override any specifications of the
1120: same capabilities in the reference description.
1121:
1122: The referring description can cancel out a capability without specifying
1123: any new value for it by means of a special trick. Write the capability in
1124: the referring description, with the character `@' after the capability
1125: name, as follows:
1126:
1127: NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
1128: :am@:tc=aaa-30:
1129:
1130:
1131: File: termcap Node: Capabilities, Prev: Data Base, Up: Top, Next: Summary
1132:
1133: Definitions of the Terminal Capabilities
1134: ****************************************
1135:
1136: This section is divided into many subsections, each for one aspect of
1137: use of display terminals. For writing a display program, you usually need
1138: only check the subsections for the operations you want to use. For writing
1139: a terminal description, you must read each subsection and fill in the
1140: capabilities described there.
1141:
1142: String capabilities that are display commands may require numeric
1143: parameters (*Note Parameters::). Most such capabilities do not use
1144: parameters. When a capability requires parameters, this is explicitly
1145: stated at the beginning of its definition. In simple cases, the first or
1146: second sentence of the definition mentions all the parameters, in the order
1147: they should be given, using a name
1148: in upper case
1149: for each one. For example, the `rp' capability is a command that
1150: requires two parameters; its definition begins as follows:
1151:
1152: String of commands to output a graphic character C, repeated N
1153: times.
1154:
1155: In complex cases or when there are many parameters, they are described
1156: explicitly.
1157:
1158: When a capability is described as obsolete, this means that programs should
1159: not be written to look for it, but terminal descriptions should still be
1160: written to provide it.
1161:
1162: When a capability is described as very obsolete, this means that it should
1163: be omitted from terminal descriptions as well.
1164:
1165: * Menu:
1166:
1167: * Basic:: Basic characteristics.
1168: * Screen Size:: Screen size, and what happens when it changes.
1169: * Cursor Motion:: Various ways to move the cursor.
1170: * Scrolling:: Pushing text up and down on the screen.
1171: * Wrapping:: What happens if you write a character in the last column.
1172: * Windows:: Limiting the part of the window that output affects.
1173: * Clearing:: Erasing one or many lines.
1174: * Insdel Line:: Making new blank lines in mid-screen; deleting lines.
1175: * Insdel Char:: Inserting and deleting characters within a line.
1176: * Standout:: Highlighting some of the text.
1177: * Underlining:: Underlining some of the text.
1178: * Cursor Visibility:: Making the cursor more or less easy to spot.
1179: * Bell:: Attracts user's attention; not localized on the screen.
1180: * Keypad:: Recognizing when function keys or arrows are typed.
1181: * Meta Key:: META acts like an extra shift key.
1182: * Initialization:: Commands used to initialize or reset the terminal.
1183: * Pad Specs:: Info for the kernel on how much padding is needed.
1184: * Status Line:: A status line displays "background" information.
1185: * Half-Line:: Moving by half-lines, for superscripts and subscripts.
1186: * Printer:: Controlling auxiliary printers of display terminals.
1187:
1188:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.