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 (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.

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