Go to the first, previous, next, last section, table of contents.


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'. 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
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:

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.


Go to the first, previous, next, last section, table of contents.