NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

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

     int
     tgetent(char *bp, char *name);

     int
     tgetnum(char *id);

     int
     tgetflag(char *id);

     char *
     tgetstr(char *id, char **area);

     char *
     tgoto(char *cm, destcol, destline);

     void
     tputs(register char *cp, int affcnt, int (*outc)());

DESCRIPTION    [Toc]    [Back]

     These functions extract and use capabilities from a terminal
capability
     data base, usually /usr/share/misc/termcap,  the  format  of
which is described
  in  termcap(5).  This version of these routines has
been deprecated
 in favor of the emulation provided by  termcap(3).   This
library is
     provided  solely  for old applications that require behavior
that is not
     emulated.

     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().  As an extension tgetent() can be
passed NULL
     for the bp argument, in which case an internal  buffer  will
be used.  If
     repeated  calls  to  tgetent() are made with a NULL bp argument, some memory
     will be leaked on each call subsequent to  the  first.   The
tgetent() function
  returns -1 if none of the termcap database 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
/usr/share/misc/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 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
     /usr/share/misc/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 capability
  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 variables
     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 controlI
  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 external variable
     PC should contain a pad character to be used  (from  the  pc
capability) if
     a null (^@) is inappropriate.

FILES    [Toc]    [Back]

     /usr/lib/libotermcap.a   -l lotermcap library
     /usr/share/misc/termcap     standard   terminal   capability
database
     $HOME/.termcap           user's terminal capability database

SEE ALSO    [Toc]    [Back]

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

HISTORY    [Toc]    [Back]

     The tgetent functions appeared in 4.0BSD.

OpenBSD      3.6                        December     11,     1993