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
       buffer 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 envi-
       ronment  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 envi-
       ronment variable TERMPATH exists, in which case it specifies a list  of
       file  pathnames (separated by spaces or colons) to be searched instead.
       Whenever multiple 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 succeeding files.  This can speed  up  entry  into  programs
       that  call  tgetent, 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  %
       sequence 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_ospeed 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)

Man(1) output converted with man2html