Contents | < Browse | Browse >
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'. Capabilities , for definitions of all
the standard capability names.
Once you have found the proper terminal description with `tgetent'
(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);
}
Padding , for information on the variable `PC'.
Using Parameters , for information on `UP' and `BC'.