Contents | < Browse | Browse >
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 
(Interrogate).

   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'.  In
this case the returned value on success is the address of the storage,
cast to `int'.  But normally there is no need for you to look at the
address.  Do not free the storage yourself.

   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.  Data Base , for information on the format of a
terminal description.