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:

• 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);
}

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.