The termcap library is the application programmer's interface to the termcap data base. It contains functions for the following purposes:
tgetent).
tgetnum, tgetflag, tgetstr).
tputs).
tparam,
tgoto).
To use the termcap library in a program, you need two kinds of preparation:
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.
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 (see section Interrogating the Terminal Description).
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. See section The Format of the Data Base, for information on the
format of a 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'. See section Definitions of the Terminal Capabilities, for definitions of all the standard capability names.
Once you have found the proper terminal description with tgetent
(see section Finding a Terminal Description: tgetent), 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
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
tgetflag to get a boolean value. If the capability
name is present in the terminal description, tgetflag
returns 1; otherwise, it returns 0.
tgetstr
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:
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.
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);
}
See section Padding, for information on the variable PC. See section Sending Display Commands with Parameters, for information on UP and BC.
Before starting to output commands to a terminal using termcap, an application program should do two things:
PC and ospeed for
padding (see section Performing Padding with tputs) and UP and BC for
cursor motion (see section tgoto).
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.
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.
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.
There are several common manifestations of insufficient padding.
Although any obscure command on an obscure terminal might lack padding, in practice problems arise most often from the clearing commands `cl' and `cd' (see section Clearing Parts of the Screen), the scrolling commands `sf' and `sr' (see section Scrolling), and the line insert/delete commands `al' and `dl' (see section Insert/Delete 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; see section When Changes in the Data Base Take Effect.) 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.
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. See section Performing Padding with tputs.
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. See section Padding Capabilities.
tputs
Use the termcap function tputs to output a string containing an
optional padding spec of the form described above (see section Specifying Padding in a Terminal Description). 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 (see section Padding Capabilities). 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. See section 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.
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;
see section Padding).
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.
printf, output the next parameter in decimal.
printf: output the next parameter in
decimal, and always use at least two digits.
printf: output the next parameter in
decimal, and always use at least three digits. Note that `%4'
and so on are not defined.
printf.
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.
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.
parm = (parm / 10) * 16 + parm % 10;
parm -= 2 * (parm % 16);
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.
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. See section 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.
tgoto
The special case of cursor motion is handled by tgoto. There
are two reasons why you might choose to use tgoto:
tparam.
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".
Go to the first, previous, next, last section, table of contents.