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