diff options
Diffstat (limited to 'lib/termcap/grot/termcap.info-1')
| -rw-r--r-- | lib/termcap/grot/termcap.info-1 | 1114 |
1 files changed, 1114 insertions, 0 deletions
diff --git a/lib/termcap/grot/termcap.info-1 b/lib/termcap/grot/termcap.info-1 new file mode 100644 index 0000000..a5b5da0 --- /dev/null +++ b/lib/termcap/grot/termcap.info-1 @@ -0,0 +1,1114 @@ +This is Info file ./termcap.info, produced by Makeinfo-1.55 from the +input file ./termcap.texi. + + This file documents the termcap library of the GNU system. + + Copyright (C) 1988 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + +File: termcap.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +* Menu: + +* Introduction:: What is termcap? Why this manual? +* Library:: The termcap library functions. +* Data Base:: What terminal descriptions in `/etc/termcap' look like. +* Capabilities:: Definitions of the individual terminal capabilities: + how to write them in descriptions, and how to use + their values to do display updating. +* Summary:: Brief table of capability names and their meanings. +* Var Index:: Index of C functions and variables. +* Cap Index:: Index of termcap capabilities. +* Index:: Concept index. + + -- The Detailed Node Listing -- + +The Termcap Library + +* Preparation:: Preparing to use the termcap library. +* Find:: Finding the description of the terminal being used. +* Interrogate:: Interrogating the description for particular capabilities. +* Initialize:: Initialization for output using termcap. +* Padding:: Outputting padding. +* Parameters:: Encoding parameters such as cursor positions. + +Padding + +* Why Pad:: Explanation of padding. +* Not Enough:: When there is not enough padding. +* Describe Padding:: The data base says how much padding a terminal needs. +* Output Padding:: Using `tputs' to output the needed padding. + +Filling In Parameters + +* Encode Parameters:: The language for encoding parameters. +* Using Parameters:: Outputting a string command with parameters. + +Sending Display Commands with Parameters + +* tparam:: The general case, for GNU termcap only. +* tgoto:: The special case of cursor motion. + +The Format of the Data Base + +* Format:: Overall format of a terminal description. +* Capability Format:: Format of capabilities within a description. +* Naming:: Naming conventions for terminal types. +* Inheriting:: Inheriting part of a description from +a related terminal type. +* Changing:: When changes in the data base take effect. + +Definitions of the Terminal Capabilities + +* Basic:: Basic characteristics. +* Screen Size:: Screen size, and what happens when it changes. +* Cursor Motion:: Various ways to move the cursor. +* Wrapping:: What happens if you write a character in the last column. +* Scrolling:: Pushing text up and down on the screen. +* Windows:: Limiting the part of the window that output affects. +* Clearing:: Erasing one or many lines. +* Insdel Line:: Making new blank lines in mid-screen; deleting lines. +* Insdel Char:: Inserting and deleting characters within a line. +* Standout:: Highlighting some of the text. +* Underlining:: Underlining some of the text. +* Cursor Visibility:: Making the cursor more or less easy to spot. +* Bell:: Attracts user's attention; not localized on the screen. +* Keypad:: Recognizing when function keys or arrows are typed. +* Meta Key:: META acts like an extra shift key. +* Initialization:: Commands used to initialize or reset the terminal. +* Pad Specs:: Info for the kernel on how much padding is needed. +* Status Line:: A status line displays "background" information. +* Half-Line:: Moving by half-lines, for superscripts and subscripts. +* Printer:: Controlling auxiliary printers of display terminals. + + +File: termcap.info, Node: Introduction, Next: Library, Prev: Top, Up: Top + +Introduction +************ + + "Termcap" is a library and data base that enables programs to use +display terminals in a terminal-independent manner. It originated in +Berkeley Unix. + + The termcap data base describes the capabilities of hundreds of +different display terminals in great detail. Some examples of the +information recorded for a terminal could include how many columns wide +it is, what string to send to move the cursor to an arbitrary position +(including how to encode the row and column numbers), how to scroll the +screen up one or several lines, and how much padding is needed for such +a scrolling operation. + + The termcap library is provided for easy access this data base in +programs that want to do terminal-independent character-based display +output. + + This manual describes the GNU version of the termcap library, which +has some extensions over the Unix version. All the extensions are +identified as such, so this manual also tells you how to use the Unix +termcap. + + The GNU version of the termcap library is available free as source +code, for use in free programs, and runs on Unix and VMS systems (at +least). You can find it in the GNU Emacs distribution in the files +`termcap.c' and `tparam.c'. + + This manual was written for the GNU project, whose goal is to +develop a complete free operating system upward-compatible with Unix +for user programs. The project is approximately two thirds complete. +For more information on the GNU project, including the GNU Emacs editor +and the mostly-portable optimizing C compiler, send one dollar to + + Free Software Foundation + 675 Mass Ave + Cambridge, MA 02139 + + +File: termcap.info, Node: Library, Next: Data Base, Prev: Introduction, Up: Top + +The Termcap Library +******************* + + The termcap library is the application programmer's interface to the +termcap data base. It contains functions for the following purposes: + + * Finding the description of the user's terminal type (`tgetent'). + + * Interrogating the description for information on various topics + (`tgetnum', `tgetflag', `tgetstr'). + + * Computing and performing padding (`tputs'). + + * Encoding numeric parameters such as cursor positions into the + terminal-specific form required for display commands (`tparam', + `tgoto'). + +* Menu: + +* Preparation:: Preparing to use the termcap library. +* Find:: Finding the description of the terminal being used. +* Interrogate:: Interrogating the description for particular capabilities. +* Initialize:: Initialization for output using termcap. +* Padding:: Outputting padding. +* Parameters:: Encoding parameters such as cursor positions. + + +File: termcap.info, Node: Preparation, Next: Find, Up: Library + +Preparing to Use the Termcap Library +==================================== + + To use the termcap library in a program, you need two kinds of +preparation: + + * The compiler needs declarations of the functions and variables in + the library. + + On GNU systems, it suffices to include the header file `termcap.h' + in each source file that uses these functions and variables. + + On Unix systems, there is often no such header file. Then you must + explictly declare the variables as external. You can do likewise + for the functions, or let them be implicitly declared and cast + their values from type `int' to the appropriate type. + + We illustrate the declarations of the individual termcap library + functions with ANSI C prototypes because they show how to pass the + arguments. If you are not using the GNU C compiler, you probably + cannot use function prototypes, so omit the argument types and + names from your declarations. + + * The linker needs to search the library. Usually either + `-ltermcap' or `-ltermlib' as an argument when linking will do + this. + + +File: termcap.info, Node: Find, Next: Interrogate, Prev: Preparation, Up: Library + +Finding a Terminal Description: `tgetent' +========================================= + + An application program that is going to use termcap must first look +up the description of the terminal type in use. This is done by calling +`tgetent', whose declaration in ANSI Standard C looks like: + + int tgetent (char *BUFFER, char *TERMTYPE); + +This function finds the description and remembers it internally so that +you can interrogate it about specific terminal capabilities (*note +Interrogate::.). + + The argument TERMTYPE is a string which is the name for the type of +terminal to look up. Usually you would obtain this from the environment +variable `TERM' using `getenv ("TERM")'. + + If you are using the GNU version of termcap, you can alternatively +ask `tgetent' to allocate enough space. Pass a null pointer for +BUFFER, and `tgetent' itself allocates the storage using `malloc'. +There is no way to get the address that was allocated, and you +shouldn't try to free the storage. + + With the Unix version of termcap, you must allocate space for the +description yourself and pass the address of the space as the argument +BUFFER. There is no way you can tell how much space is needed, so the +convention is to allocate a buffer 2048 characters long and assume that +is enough. (Formerly the convention was to allocate 1024 characters and +assume that was enough. But one day, for one kind of terminal, that was +not enough.) + + No matter how the space to store the description has been obtained, +termcap records its address internally for use when you later +interrogate the description with `tgetnum', `tgetstr' or `tgetflag'. If +the buffer was allocated by termcap, it will be freed by termcap too if +you call `tgetent' again. If the buffer was provided by you, you must +make sure that its contents remain unchanged for as long as you still +plan to interrogate the description. + + The return value of `tgetent' is -1 if there is some difficulty +accessing the data base of terminal types, 0 if the data base is +accessible but the specified type is not defined in it, and some other +value otherwise. + + Here is how you might use the function `tgetent': + + #ifdef unix + static char term_buffer[2048]; + #else + #define term_buffer 0 + #endif + + init_terminal_data () + { + char *termtype = getenv ("TERM"); + int success; + + if (termtype == 0) + fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n"); + + success = tgetent (term_buffer, termtype); + if (success < 0) + fatal ("Could not access the termcap data base.\n"); + if (success == 0) + fatal ("Terminal type `%s' is not defined.\n", termtype); + } + +Here we assume the function `fatal' prints an error message and exits. + + If the environment variable `TERMCAP' is defined, its value is used +to override the terminal type data base. The function `tgetent' checks +the value of `TERMCAP' automatically. If the value starts with `/' +then it is taken as a file name to use as the data base file, instead +of `/etc/termcap' which is the standard data base. If the value does +not start with `/' then it is itself used as the terminal description, +provided that the terminal type TERMTYPE is among the types it claims +to apply to. *Note Data Base::, for information on the format of a +terminal description. + + +File: termcap.info, Node: Interrogate, Next: Initialize, Prev: Find, Up: Library + +Interrogating the Terminal Description +====================================== + + Each piece of information recorded in a terminal description is +called a "capability". Each defined terminal capability has a +two-letter code name and a specific meaning. For example, the number +of columns is named `co'. *Note Capabilities::, for definitions of all +the standard capability names. + + Once you have found the proper terminal description with `tgetent' +(*note Find::.), your application program must "interrogate" it for +various terminal capabilities. You must specify the two-letter code of +the capability whose value you seek. + + Capability values can be numeric, boolean (capability is either +present or absent) or strings. Any particular capability always has +the same value type; for example, `co' always has a numeric value, +while `am' (automatic wrap at margin) is always a flag, and `cm' +(cursor motion command) always has a string value. The documentation +of each capability says which type of value it has. + + There are three functions to use to get the value of a capability, +depending on the type of value the capability has. Here are their +declarations in ANSI C: + + int tgetnum (char *NAME); + int tgetflag (char *NAME); + char *tgetstr (char *NAME, char **AREA); + +`tgetnum' + Use `tgetnum' to get a capability value that is numeric. The + argument NAME is the two-letter code name of the capability. If + the capability is present, `tgetnum' returns the numeric value + (which is nonnegative). If the capability is not mentioned in the + terminal description, `tgetnum' returns -1. + +`tgetflag' + Use `tgetflag' to get a boolean value. If the capability NAME is + present in the terminal description, `tgetflag' returns 1; + otherwise, it returns 0. + +`tgetstr' + Use `tgetstr' to get a string value. It returns a pointer to a + string which is the capability value, or a null pointer if the + capability is not present in the terminal description. + + There are two ways `tgetstr' can find space to store the string + value: + + * You can ask `tgetstr' to allocate the space. Pass a null + pointer for the argument AREA, and `tgetstr' will use + `malloc' to allocate storage big enough for the value. + Termcap will never free this storage or refer to it again; you + should free it when you are finished with it. + + This method is more robust, since there is no need to guess + how much space is needed. But it is supported only by the GNU + termcap library. + + * You can provide the space. Provide for the argument AREA the + address of a pointer variable of type `char *'. Before + calling `tgetstr', initialize the variable to point at + available space. Then `tgetstr' will store the string value + in that space and will increment the pointer variable to + point after the space that has been used. You can use the + same pointer variable for many calls to `tgetstr'. + + There is no way to determine how much space is needed for a + single string, and no way for you to prevent or handle + overflow of the area you have provided. However, you can be + sure that the total size of all the string values you will + obtain from the terminal description is no greater than the + size of the description (unless you get the same capability + twice). You can determine that size with `strlen' on the + buffer you provided to `tgetent'. See below for an example. + + Providing the space yourself is the only method supported by + the Unix version of termcap. + + Note that you do not have to specify a terminal type or terminal +description for the interrogation functions. They automatically use the +description found by the most recent call to `tgetent'. + + Here is an example of interrogating a terminal description for +various capabilities, with conditionals to select between the Unix and +GNU methods of providing buffer space. + + char *tgetstr (); + + char *cl_string, *cm_string; + int height; + int width; + int auto_wrap; + + char PC; /* For tputs. */ + char *BC; /* For tgoto. */ + char *UP; + + interrogate_terminal () + { + #ifdef UNIX + /* Here we assume that an explicit term_buffer + was provided to tgetent. */ + char *buffer + = (char *) malloc (strlen (term_buffer)); + #define BUFFADDR &buffer + #else + #define BUFFADDR 0 + #endif + + char *temp; + + /* Extract information we will use. */ + cl_string = tgetstr ("cl", BUFFADDR); + cm_string = tgetstr ("cm", BUFFADDR); + auto_wrap = tgetflag ("am"); + height = tgetnum ("li"); + width = tgetnum ("co"); + + /* Extract information that termcap functions use. */ + temp = tgetstr ("pc", BUFFADDR); + PC = temp ? *temp : 0; + BC = tgetstr ("le", BUFFADDR); + UP = tgetstr ("up", BUFFADDR); + } + +*Note Padding::, for information on the variable `PC'. *Note Using +Parameters::, for information on `UP' and `BC'. + + +File: termcap.info, Node: Initialize, Next: Padding, Prev: Interrogate, Up: Library + +Initialization for Use of Termcap +================================= + + Before starting to output commands to a terminal using termcap, an +application program should do two things: + + * Initialize various global variables which termcap library output + functions refer to. These include `PC' and `ospeed' for padding + (*note Output Padding::.) and `UP' and `BC' for cursor motion + (*note tgoto::.). + + * Tell the kernel to turn off alteration and padding of + horizontal-tab characters sent to the terminal. + + To turn off output processing in Berkeley Unix you would use `ioctl' +with code `TIOCLSET' to set the bit named `LLITOUT', and clear the bits +`ANYDELAY' using `TIOCSETN'. In POSIX or System V, you must clear the +bit named `OPOST'. Refer to the system documentation for details. + + If you do not set the terminal flags properly, some older terminals +will not work. This is because their commands may contain the +characters that normally signify newline, carriage return and +horizontal tab--characters which the kernel thinks it ought to modify +before output. + + When you change the kernel's terminal flags, you must arrange to +restore them to their normal state when your program exits. This +implies that the program must catch fatal signals such as `SIGQUIT' and +`SIGINT' and restore the old terminal flags before actually terminating. + + Modern terminals' commands do not use these special characters, so +if you do not care about problems with old terminals, you can leave the +kernel's terminal flags unaltered. + + +File: termcap.info, Node: Padding, Next: Parameters, Prev: Initialize, Up: Library + +Padding +======= + + "Padding" means outputting null characters following a terminal +display command that takes a long time to execute. The terminal +description says which commands require padding and how much; the +function `tputs', described below, outputs a terminal command while +extracting from it the padding information, and then outputs the +padding that is necessary. + +* Menu: + +* Why Pad:: Explanation of padding. +* Not Enough:: When there is not enough padding. +* Describe Padding:: The data base says how much padding a terminal needs. +* Output Padding:: Using `tputs' to output the needed padding. + + +File: termcap.info, Node: Why Pad, Next: Not Enough, Up: Padding + +Why Pad, and How +---------------- + + Most types of terminal have commands that take longer to execute +than they do to send over a high-speed line. For example, clearing the +screen may take 20msec once the entire command is received. During +that time, on a 9600 bps line, the terminal could receive about 20 +additional output characters while still busy clearing the screen. +Every terminal has a certain amount of buffering capacity to remember +output characters that cannot be processed yet, but too many slow +commands in a row can cause the buffer to fill up. Then any additional +output that cannot be processed immediately will be lost. + + To avoid this problem, we normally follow each display command with +enough useless charaters (usually null characters) to fill up the time +that the display command needs to execute. This does the job if the +terminal throws away null characters without using up space in the +buffer (which most terminals do). If enough padding is used, no output +can ever be lost. The right amount of padding avoids loss of output +without slowing down operation, since the time used to transmit padding +is time that nothing else could be done. + + The number of padding characters needed for an operation depends on +the line speed. In fact, it is proportional to the line speed. A 9600 +baud line transmits about one character per msec, so the clear screen +command in the example above would need about 20 characters of padding. +At 1200 baud, however, only about 3 characters of padding are needed +to fill up 20msec. + + +File: termcap.info, Node: Not Enough, Next: Describe Padding, Prev: Why Pad, Up: Padding + +When There Is Not Enough Padding +-------------------------------- + + There are several common manifestations of insufficient padding. + + * Emacs displays `I-search: ^Q-' at the bottom of the screen. + + This means that the terminal thought its buffer was getting full of + display commands, so it tried to tell the computer to stop sending + any. + + * The screen is garbled intermittently, or the details of garbling + vary when you repeat the action. (A garbled screen could be due + to a command which is simply incorrect, or to user option in the + terminal which doesn't match the assumptions of the terminal + description, but this usually leads to reproducible failure.) + + This means that the buffer did get full, and some commands were + lost. Many changeable factors can change which ones are lost. + + * Screen is garbled at high output speeds but not at low speeds. + Padding problems nearly always go away at low speeds, usually even + at 1200 baud. + + This means that a high enough speed permits commands to arrive + faster than they can be executed. + + Although any obscure command on an obscure terminal might lack +padding, in practice problems arise most often from the clearing +commands `cl' and `cd' (*note Clearing::.), the scrolling commands `sf' +and `sr' (*note Scrolling::.), and the line insert/delete commands `al' +and `dl' (*note Insdel Line::.). + + Occasionally the terminal description fails to define `sf' and some +programs will use `do' instead, so you may get a problem with `do'. If +so, first define `sf' just like `do', then add some padding to `sf'. + + The best strategy is to add a lot of padding at first, perhaps 200 +msec. This is much more than enough; in fact, it should cause a +visible slowdown. (If you don't see a slowdown, the change has not +taken effect; *note Changing::..) If this makes the problem go away, +you have found the right place to add padding; now reduce the amount +until the problem comes back, then increase it again. If the problem +remains, either it is in some other capability or it is not a matter of +padding at all. + + Keep in mind that on many terminals the correct padding for +insert/delete line or for scrolling is cursor-position dependent. If +you get problems from scrolling a large region of the screen but not +from scrolling a small part (just a few lines moving), it may mean that +fixed padding should be replaced with position-dependent padding. + + +File: termcap.info, Node: Describe Padding, Next: Output Padding, Prev: Not Enough, Up: Padding + +Specifying Padding in a Terminal Description +-------------------------------------------- + + In the terminal description, the amount of padding required by each +display command is recorded as a sequence of digits at the front of the +command. These digits specify the padding time in milliseconds (msec). +They can be followed optionally by a decimal point and one more digit, +which is a number of tenths of msec. + + Sometimes the padding needed by a command depends on the cursor +position. For example, the time taken by an "insert line" command is +usually proportional to the number of lines that need to be moved down +or cleared. An asterisk (`*') following the padding time says that the +time should be multiplied by the number of screen lines affected by the +command. + + :al=1.3*\E[L: + +is used to describe the "insert line" command for a certain terminal. +The padding required is 1.3 msec per line affected. The command itself +is `ESC [ L'. + + The padding time specified in this way tells `tputs' how many pad +characters to output. *Note Output Padding::. + + Two special capability values affect padding for all commands. +These are the `pc' and `pb'. The variable `pc' specifies the character +to pad with, and `pb' the speed below which no padding is needed. The +defaults for these variables, a null character and 0, are correct for +most terminals. *Note Pad Specs::. + + +File: termcap.info, Node: Output Padding, Prev: Describe Padding, Up: Padding + +Performing Padding with `tputs' +------------------------------- + + Use the termcap function `tputs' to output a string containing an +optional padding spec of the form described above (*note Describe +Padding::.). The function `tputs' strips off and decodes the padding +spec, outputs the rest of the string, and then outputs the appropriate +padding. Here is its declaration in ANSI C: + + char PC; + short ospeed; + + int tputs (char *STRING, int NLINES, int (*OUTFUN) ()); + + Here STRING is the string (including padding spec) to be output; +NLINES is the number of lines affected by the operation, which is used +to multiply the amount of padding if the padding spec ends with a `*'. +Finally, OUTFUN is a function (such as `fputchar') that is called to +output each character. When actually called, OUTFUN should expect one +argument, a character. + + The operation of `tputs' is controlled by two global variables, +`ospeed' and `PC'. The value of `ospeed' is supposed to be the +terminal output speed, encoded as in the `ioctl' system call which gets +the speed information. This is needed to compute the number of padding +characters. The value of `PC' is the character used for padding. + + You are responsible for storing suitable values into these variables +before using `tputs'. The value stored into the `PC' variable should be +taken from the `pc' capability in the terminal description (*note Pad +Specs::.). Store zero in `PC' if there is no `pc' capability. + + The argument NLINES requires some thought. Normally, it should be +the number of lines whose contents will be cleared or moved by the +command. For cursor motion commands, or commands that do editing +within one line, use the value 1. For most commands that affect +multiple lines, such as `al' (insert a line) and `cd' (clear from the +cursor to the end of the screen), NLINES should be the screen height +minus the current vertical position (origin 0). For multiple insert +and scroll commands such as `AL' (insert multiple lines), that same +value for NLINES is correct; the number of lines being inserted is not +correct. + + If a "scroll window" feature is used to reduce the number of lines +affected by a command, the value of NLINES should take this into +account. This is because the delay time required depends on how much +work the terminal has to do, and the scroll window feature reduces the +work. *Note Scrolling::. + + Commands such as `ic' and `dc' (insert or delete characters) are +problematical because the padding needed by these commands is +proportional to the number of characters affected, which is the number +of columns from the cursor to the end of the line. It would be nice to +have a way to specify such a dependence, and there is no need for +dependence on vertical position in these commands, so it is an obvious +idea to say that for these commands NLINES should really be the number +of columns affected. However, the definition of termcap clearly says +that NLINES is always the number of lines affected, even in this case, +where it is always 1. It is not easy to change this rule now, because +too many programs and terminal descriptions have been written to follow +it. + + Because NLINES is always 1 for the `ic' and `dc' strings, there is +no reason for them to use `*', but some of them do. These should be +corrected by deleting the `*'. If, some day, such entries have +disappeared, it may be possible to change to a more useful convention +for the NLINES argument for these operations without breaking any +programs. + + +File: termcap.info, Node: Parameters, Prev: Padding, Up: Library + +Filling In Parameters +===================== + + Some terminal control strings require numeric "parameters". For +example, when you move the cursor, you need to say what horizontal and +vertical positions to move it to. The value of the terminal's `cm' +capability, which says how to move the cursor, cannot simply be a +string of characters; it must say how to express the cursor position +numbers and where to put them within the command. + + The specifications of termcap include conventions as to which +string-valued capabilities require parameters, how many parameters, and +what the parameters mean; for example, it defines the `cm' string to +take two parameters, the vertical and horizontal positions, with 0,0 +being the upper left corner. These conventions are described where the +individual commands are documented. + + Termcap also defines a language used within the capability +definition for specifying how and where to encode the parameters for +output. This language uses character sequences starting with `%'. +(This is the same idea as `printf', but the details are different.) +The language for parameter encoding is described in this section. + + A program that is doing display output calls the functions `tparam' +or `tgoto' to encode parameters according to the specifications. These +functions produce a string containing the actual commands to be output +(as well a padding spec which must be processed with `tputs'; *note +Padding::.). + +* Menu: + +* Encode Parameters:: The language for encoding parameters. +* Using Parameters:: Outputting a string command with parameters. + + +File: termcap.info, Node: Encode Parameters, Next: Using Parameters, Up: Parameters + +Describing the Encoding +----------------------- + + A terminal command string that requires parameters contains special +character sequences starting with `%' to say how to encode the +parameters. These sequences control the actions of `tparam' and +`tgoto'. + + The parameters values passed to `tparam' or `tgoto' are considered +to form a vector. A pointer into this vector determines the next +parameter to be processed. Some of the `%'-sequences encode one +parameter and advance the pointer to the next parameter. Other +`%'-sequences alter the pointer or alter the parameter values without +generating output. + + For example, the `cm' string for a standard ANSI terminal is written +as `\E[%i%d;%dH'. (`\E' stands for ESC.) `cm' by convention always +requires two parameters, the vertical and horizontal goal positions, so +this string specifies the encoding of two parameters. Here `%i' +increments the two values supplied, and each `%d' encodes one of the +values in decimal. If the cursor position values 20,58 are encoded +with this string, the result is `\E[21;59H'. + + First, here are the `%'-sequences that generate output. Except for +`%%', each of them encodes one parameter and advances the pointer to +the following parameter. + +`%%' + Output a single `%'. This is the only way to represent a literal + `%' in a terminal command with parameters. `%%' does not use up a + parameter. + +`%d' + As in `printf', output the next parameter in decimal. + +`%2' + Like `%02d' in `printf': output the next parameter in decimal, and + always use at least two digits. + +`%3' + Like `%03d' in `printf': output the next parameter in decimal, and + always use at least three digits. Note that `%4' and so on are + *not* defined. + +`%.' + Output the next parameter as a single character whose ASCII code is + the parameter value. Like `%c' in `printf'. + +`%+CHAR' + Add the next parameter to the character CHAR, and output the + resulting character. For example, `%+ ' represents 0 as a space, + 1 as `!', etc. + + The following `%'-sequences specify alteration of the parameters +(their values, or their order) rather than encoding a parameter for +output. They generate no output; they are used only for their side +effects on the parameters. Also, they do not advance the "next +parameter" pointer except as explicitly stated. Only `%i', `%r' and +`%>' are defined in standard Unix termcap. The others are GNU +extensions. + +`%i' + Increment the next two parameters. This is used for terminals that + expect cursor positions in origin 1. For example, `%i%d,%d' would + output two parameters with `1' for 0, `2' for 1, etc. + +`%r' + Interchange the next two parameters. This is used for terminals + whose cursor positioning command expects the horizontal position + first. + +`%s' + Skip the next parameter. Do not output anything. + +`%b' + Back up one parameter. The last parameter used will become once + again the next parameter to be output, and the next output command + will use it. Using `%b' more than once, you can back up any + number of parameters, and you can refer to each parameter any + number of times. + +`%>C1C2' + Conditionally increment the next parameter. Here C1 and C2 are + characters which stand for their ASCII codes as numbers. If the + next parameter is greater than the ASCII code of C1, the ASCII + code of C2 is added to it. + +`%a OP TYPE POS' + Perform arithmetic on the next parameter, do not use it up, and do + not output anything. Here OP specifies the arithmetic operation, + while TYPE and POS together specify the other operand. + + Spaces are used above to separate the operands for clarity; the + spaces don't appear in the data base, where this sequence is + exactly five characters long. + + The character OP says what kind of arithmetic operation to + perform. It can be any of these characters: + + `=' + assign a value to the next parameter, ignoring its old value. + The new value comes from the other operand. + + `+' + add the other operand to the next parameter. + + `-' + subtract the other operand from the next parameter. + + `*' + multiply the next parameter by the other operand. + + `/' + divide the next parameter by the other operand. + + The "other operand" may be another parameter's value or a constant; + the character TYPE says which. It can be: + + `p' + Use another parameter. The character POS says which + parameter to use. Subtract 64 from its ASCII code to get the + position of the desired parameter relative to this one. Thus, + the character `A' as POS means the parameter after the next + one; the character `?' means the parameter before the next + one. + + `c' + Use a constant value. The character POS specifies the value + of the constant. The 0200 bit is cleared out, so that 0200 + can be used to represent zero. + + The following `%'-sequences are special purpose hacks to compensate +for the weird designs of obscure terminals. They modify the next +parameter or the next two parameters but do not generate output and do +not use up any parameters. `%m' is a GNU extension; the others are +defined in standard Unix termcap. + +`%n' + Exclusive-or the next parameter with 0140, and likewise the + parameter after next. + +`%m' + Complement all the bits of the next parameter and the parameter + after next. + +`%B' + Encode the next parameter in BCD. It alters the value of the + parameter by adding six times the quotient of the parameter by ten. + Here is a C statement that shows how the new value is computed: + + PARM = (PARM / 10) * 16 + PARM % 10; + +`%D' + Transform the next parameter as needed by Delta Data terminals. + This involves subtracting twice the remainder of the parameter by + 16. + + PARM -= 2 * (PARM % 16); + + +File: termcap.info, Node: Using Parameters, Prev: Encode Parameters, Up: Parameters + +Sending Display Commands with Parameters +---------------------------------------- + + The termcap library functions `tparam' and `tgoto' serve as the +analog of `printf' for terminal string parameters. The newer function +`tparam' is a GNU extension, more general but missing from Unix +termcap. The original parameter-encoding function is `tgoto', which is +preferable for cursor motion. + +* Menu: + +* tparam:: The general case, for GNU termcap only. +* tgoto:: The special case of cursor motion. + + +File: termcap.info, Node: tparam, Next: tgoto, Up: Using Parameters + +`tparam' +........ + + The function `tparam' can encode display commands with any number of +parameters and allows you to specify the buffer space. It is the +preferred function for encoding parameters for all but the `cm' +capability. Its ANSI C declaration is as follows: + + char *tparam (char *CTLSTRING, char *BUFFER, int SIZE, int PARM1,...) + + The arguments are a control string CTLSTRING (the value of a terminal +capability, presumably), an output buffer BUFFER and SIZE, and any +number of integer parameters to be encoded. The effect of `tparam' is +to copy the control string into the buffer, encoding parameters +according to the `%' sequences in the control string. + + You describe the output buffer by its address, BUFFER, and its size +in bytes, SIZE. If the buffer is not big enough for the data to be +stored in it, `tparam' calls `malloc' to get a larger buffer. In +either case, `tparam' returns the address of the buffer it ultimately +uses. If the value equals BUFFER, your original buffer was used. +Otherwise, a new buffer was allocated, and you must free it after you +are done with printing the results. If you pass zero for SIZE and +BUFFER, `tparam' always allocates the space with `malloc'. + + All capabilities that require parameters also have the ability to +specify padding, so you should use `tputs' to output the string +produced by `tparam'. *Note Padding::. Here is an example. + + { + char *buf; + char buffer[40]; + + buf = tparam (command, buffer, 40, parm); + tputs (buf, 1, fputchar); + if (buf != buffer) + free (buf); + } + + If a parameter whose value is zero is encoded with `%.'-style +encoding, the result is a null character, which will confuse `tputs'. +This would be a serious problem, but luckily `%.' encoding is used only +by a few old models of terminal, and only for the `cm' capability. To +solve the problem, use `tgoto' rather than `tparam' to encode the `cm' +capability. + + +File: termcap.info, Node: tgoto, Prev: tparam, Up: Using Parameters + +`tgoto' +....... + + The special case of cursor motion is handled by `tgoto'. There are +two reasons why you might choose to use `tgoto': + + * For Unix compatibility, because Unix termcap does not have + `tparam'. + + * For the `cm' capability, since `tgoto' has a special feature to + avoid problems with null characters, tabs and newlines on certain + old terminal types that use `%.' encoding for that capability. + + Here is how `tgoto' might be declared in ANSI C: + + char *tgoto (char *CSTRING, int HPOS, int VPOS) + + There are three arguments, the terminal description's `cm' string and +the two cursor position numbers; `tgoto' computes the parametrized +string in an internal static buffer and returns the address of that +buffer. The next time you use `tgoto' the same buffer will be reused. + + Parameters encoded with `%.' encoding can generate null characters, +tabs or newlines. These might cause trouble: the null character because +`tputs' would think that was the end of the string, the tab because the +kernel or other software might expand it into spaces, and the newline +becaue the kernel might add a carriage-return, or padding characters +normally used for a newline. To prevent such problems, `tgoto' is +careful to avoid these characters. Here is how this works: if the +target cursor position value is such as to cause a problem (that is to +say, zero, nine or ten), `tgoto' increments it by one, then compensates +by appending a string to move the cursor back or up one position. + + The compensation strings to use for moving back or up are found in +global variables named `BC' and `UP'. These are actual external C +variables with upper case names; they are declared `char *'. It is up +to you to store suitable values in them, normally obtained from the +`le' and `up' terminal capabilities in the terminal description with +`tgetstr'. Alternatively, if these two variables are both zero, the +feature of avoiding nulls, tabs and newlines is turned off. + + It is safe to use `tgoto' for commands other than `cm' only if you +have stored zero in `BC' and `UP'. + + Note that `tgoto' reverses the order of its operands: the horizontal +position comes before the vertical position in the arguments to +`tgoto', even though the vertical position comes before the horizontal +in the parameters of the `cm' string. If you use `tgoto' with a +command such as `AL' that takes one parameter, you must pass the +parameter to `tgoto' as the "vertical position". + + +File: termcap.info, Node: Data Base, Next: Capabilities, Prev: Library, Up: Top + +The Format of the Data Base +*************************** + + The termcap data base of terminal descriptions is stored in the file +`/etc/termcap'. It contains terminal descriptions, blank lines, and +comments. + + A terminal description starts with one or more names for the +terminal type. The information in the description is a series of +"capability names" and values. The capability names have standard +meanings (*note Capabilities::.) and their values describe the terminal. + +* Menu: + +* Format:: Overall format of a terminal description. +* Capability Format:: Format of capabilities within a description. +* Naming:: Naming conventions for terminal types. +* Inheriting:: Inheriting part of a description from +a related terminal type. +* Changing:: When changes in the data base take effect. + + +File: termcap.info, Node: Format, Next: Capability Format, Up: Data Base + +Terminal Description Format +=========================== + + Aside from comments (lines starting with `#', which are ignored), +each nonblank line in the termcap data base is a terminal description. +A terminal description is nominally a single line, but it can be split +into multiple lines by inserting the two characters `\ newline'. This +sequence is ignored wherever it appears in a description. + + The preferred way to split the description is between capabilities: +insert the four characters `: \ newline tab' immediately before any +colon. This allows each sub-line to start with some indentation. This +works because, after the `\ newline' are ignored, the result is `: tab +:'; the first colon ends the preceding capability and the second colon +starts the next capability. If you split with `\ newline' alone, you +may not add any indentation after them. + + Here is a real example of a terminal description: + + dw|vt52|DEC vt52:\ + :cr=^M:do=^J:nl=^J:bl=^G:\ + :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\ + :cm=\EY%+ %+ :co#80:li#24:\ + :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\ + :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H: + + Each terminal description begins with several names for the terminal +type. The names are separated by `|' characters, and a colon ends the +last name. The first name should be two characters long; it exists +only for the sake of very old Unix systems and is never used in modern +systems. The last name should be a fully verbose name such as "DEC +vt52" or "Ann Arbor Ambassador with 48 lines". The other names should +include whatever the user ought to be able to specify to get this +terminal type, such as `vt52' or `aaa-48'. *Note Naming::, for +information on how to choose terminal type names. + + After the terminal type names come the terminal capabilities, +separated by colons and with a colon after the last one. Each +capability has a two-letter name, such as `cm' for "cursor motion +string" or `li' for "number of display lines". + + +File: termcap.info, Node: Capability Format, Next: Naming, Prev: Format, Up: Data Base + +Writing the Capabilities +======================== + + There are three kinds of capabilities: flags, numbers, and strings. +Each kind has its own way of being written in the description. Each +defined capability has by convention a particular kind of value; for +example, `li' always has a numeric value and `cm' always a string value. + + A flag capability is thought of as having a boolean value: the value +is true if the capability is present, false if not. When the +capability is present, just write its name between two colons. + + A numeric capability has a value which is a nonnegative number. +Write the capability name, a `#', and the number, between two colons. +For example, `...:li#48:...' is how you specify the `li' capability for +48 lines. + + A string-valued capability has a value which is a sequence of +characters. Usually these are the characters used to perform some +display operation. Write the capability name, a `=', and the +characters of the value, between two colons. For example, +`...:cm=\E[%i%d;%dH:...' is how the cursor motion command for a +standard ANSI terminal would be specified. + + Special characters in the string value can be expressed using +`\'-escape sequences as in C; in addition, `\E' stands for ESC. `^' is +also a kind of escape character; `^' followed by CHAR stands for the +control-equivalent of CHAR. Thus, `^a' stands for the character +control-a, just like `\001'. `\' and `^' themselves can be represented +as `\\' and `\^'. + + To include a colon in the string, you must write `\072'. You might +ask, "Why can't `\:' be used to represent a colon?" The reason is that +the interrogation functions do not count slashes while looking for a +capability. Even if `:ce=ab\:cd:' were interpreted as giving the `ce' +capability the value `ab:cd', it would also appear to define `cd' as a +flag. + + The string value will often contain digits at the front to specify +padding (*note Padding::.) and/or `%'-sequences within to specify how +to encode parameters (*note Parameters::.). Although these things are +not to be output literally to the terminal, they are considered part of +the value of the capability. They are special only when the string +value is processed by `tputs', `tparam' or `tgoto'. By contrast, `\' +and `^' are considered part of the syntax for specifying the characters +in the string. + + Let's look at the VT52 example again: + + dw|vt52|DEC vt52:\ + :cr=^M:do=^J:nl=^J:bl=^G:\ + :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\ + :cm=\EY%+ %+ :co#80:li#24:\ + :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\ + :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H: + + Here we see the numeric-valued capabilities `co' and `li', the flags +`bs' and `pt', and many string-valued capabilities. Most of the +strings start with ESC represented as `\E'. The rest contain control +characters represented using `^'. The meanings of the individual +capabilities are defined elsewhere (*note Capabilities::.). + |