TERMCAP(3)                     Library Routines                     TERMCAP(3)

NAME

       tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs, tparm, _set_ospeed -
       terminal independent operation routines

SYNOPSIS

       #include <termcap.h>

       char PC;
       char *BC;
       char *UP;
       short ospeed;

       int tgetent (char *bp, const char *name);
       int tgetnum (const char *id);
       int tgetflag (const char *id);
       char *tgetstr (const char *id, char **area);
       char *tgoto (const char *cm, int destcol, int destline);
       int tputs (const char *cp, int affcnt, int (*outc)(int));
       char *tparm (const char *cp, ...);
       void _set_ospeed (long speed);

DESCRIPTION

       These functions extract and use capabilities from a terminal capability
       data  base,  usually  /etc/termcap, the format of which is described in
       termcap(5).  These are low level routines; see curses(3) for  a  higher
       level package.

       The tgetent function extracts the entry for terminal name into the buf‐
       fer at bp.  The bp argument should be a character buffer of  size  1024
       and must be retained through all subsequent calls to tgetnum, tgetflag,
       and tgetstr.  The tgetent function returns -1 if none  of  the  termcap
       data  base files could be opened, 0 if the terminal name given does not
       have an entry, and 1 if all goes well.  It will look in the environment
       for  a TERMCAP variable.  If found, and the value does not begin with a
       slash, and the terminal type name is the same as the environment string
       TERM, the TERMCAP string is used instead of reading a termcap file.  If
       it does begin with a slash, the string is used as a path  name  of  the
       termcap  file  to  search.   If TERMCAP does not begin with a slash and
       name is different from TERM, tgetent searches the files  $HOME/.termcap
       and  /etc/termcap,  in  that  order,  unless  the  environment variable
       TERMPATH exists, in which case it specifies a list  of  file  pathnames
       (separated  by spaces or colons) to be searched instead.  Whenever mul‐
       tiple files are searched and a tc field occurs in the requested  entry,
       the  entry  it  names must be found in the same file or one of the suc‐
       ceeding files.  This can speed up entry into programs  that  call  tge����
       tent,  as  well as help debug new terminal descriptions or make one for
       your terminal if you can't write the file /etc/termcap.

       The tgetnum function gets the numeric value of capability id, returning
       -1  if it is not given for the terminal.  The tgetflag function returns
       1 if the specified capability is present in the terminal's entry, 0  if
       it  is not.  The tgetstr function returns the string value of the capa‐
       bility id, places it in the buffer  at  area,  and  advances  the  area
       pointer.   It  decodes  the  abbreviations  for this field described in
       termcap(5), except for cursor addressing and padding information.   The
       tgetstr function returns NULL if the capability was not found.

       The  tgoto  function returns a cursor addressing string decoded from cm
       to go to column destcol in line destline.  It uses the  external  vari‐
       ables  UP  (from  the up capability) and BC (if bc is given rather than
       bs) if necessary to avoid placing \n , ^D or ^@ in the returned string.
       (Programs which call tgoto should be sure to turn off the XTABS bit(s),
       since tgoto may now output a tab.  Note  that  programs  using  termcap
       should  in  general turn off XTABS anyway since some terminals use con‐
       trol-I for other functions, such as nondestructive space.)  If a %  se‐
       quence is given which is not understood, then tgoto returns OOPS.

       The  tputs  function  decodes  the  leading  padding information of the
       string cp, affcnt gives the number of lines affected by the  operation,
       or  1 if this is not applicable, outc is a routine which is called with
       each character in turn.  The external variable  ospeed  should  contain
       the  output  speed of the terminal as encoded by stty(3).  The _set_os����
       peed functions converts any (not exactly matched only) numeric speed to
       stty(3)  encoded  speed and set ospeed variable.  The external variable
       PC should contain a pad character to be used (from the  pc  capability)
       if a null ^@ is inappropriate.

       The tparm function instantiates the string cp with given parameters.  A
       pointer is returned which points to the result of cp with  the  parame‐
       ters  applied.   If a % sequence is given which is not understood, then
       tparm returns OOPS.

FILES

              /usr/lib/libtermcap
                     The ltermcap library (also known as ltermlib).

              /etc/termcap
                     standard terminal capability data base

              $HOME/termcap
                     user's terminal capability data base

SEE ALSO

       ex(1), curses(3), termcap(5)

HISTORY

       The termcap functions appeared in 4.0BSD.



GNO                             September 1997                      TERMCAP(3)