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