           setupterm, setterm, set_curterm, del_curterm, restartterm,
           tparm, tputs, putp, vidputs,  vidattr,  mvcur,  tigetflag,
           tigetnum,   tigetstr   -  curses  interfaces  to  terminfo
           database

## SYNOPSIS

           #include <curses.h>
           #include <term.h>

           int setupterm(const char *term, int fildes, int *errret);
           int setterm(const char *term);
           TERMINAL *set_curterm(TERMINAL *nterm);
           int del_curterm(TERMINAL *oterm);
           int  restartterm(const  char  *term,   int   fildes,   int
           *errret);
           char *tparm(const char *str, ...);
           char  *tparam(const  char  *str,  char  *buffer, int size,
           ...);
           int tputs(const char *str, int affcnt, int (*putc)(int));
           int putp(const char *str);
           int vidputs(chtype attrs, int (*putc)(char));
           int vidattr(chtype attrs);
           int mvcur(int oldrow, int oldcol, int newrow, int newcol);
           int tigetflag(const char *capname);
           int tigetnum(const char *capname);
           char *tigetstr(const char *capname);

## DESCRIPTION

           These  low-level  routines must be called by programs that
           have to deal directly with the terminfo database to handle
           certain  terminal  capabilities, such as programming func-
           tion keys.  For all other functionality,  curses  routines
           are more suitable and their use is recommended.

           Initially,   setupterm   should   be  called.   Note  that
           setupterm is automatically called by initscr and  newterm.
           This  defines  the  set  of  terminal-dependent  variables
           [listed in terminfo(5)].  The terminfo variables lines and
           columns  are  initialized  by  setupterm  as  follows:  If
           use_env(FALSE) has  been  called,  values  for  lines  and
           columns specified in terminfo are used.  Otherwise, if the
           environment variables LINES and COLUMNS exist, their  val-
           ues are used.  If these environment variables do not exist
           and the program is running in a window, the current window
           size  is used.  Otherwise, if the environment variables do
           not exist, the values for lines and columns  specified  in
           the terminfo database are used.

           The  header  files  curses.h and term.h should be included
           (in this order) to get the definitions for these  strings,
           numbers,  and  flags.   Parameterized  strings  should  be
           passed through tparm to instantiate  them.   All  terminfo
           the  tty modes before exiting [see curs_kernel(3X)].  Pro-
           grams  which   use   cursor   addressing   should   output
           enter_ca_mode  upon startup and should output exit_ca_mode
           before exiting.  Programs desiring  shell  escapes  should
           call

           reset_shell_mode  and output exit_ca_mode before the shell
           is  called  and  should  output  enter_ca_mode  and   call
           reset_prog_mode after returning from the shell.

           The setupterm routine reads in the terminfo database, ini-
           tializing the terminfo structures, but does not set up the
           output virtualization structures used by curses.  The ter-
           minal type is the character string term; if term is  null,
           the  environment  variable TERM is used.  All output is to
           file descriptor fildes which is  initialized  for  output.
           If  errret  is  not null, then setupterm returns OK or ERR
           and stores a status value in the  integer  pointed  to  by
           errret.   A  status of 1 in errret is normal, 0 means that
           the terminal could not be found, and  -1  means  that  the
           terminfo  database could not be found.  If errret is null,
           setupterm prints an error message upon  finding  an  error
           and exits.  Thus, the simplest call is:

                 setupterm((char *)0, 1, (int *)0);,

           which  uses  all the defaults and sends the output to std-
           out.

           The setterm routine is being replaced by  setupterm.   The
           call:

                 setupterm(term, 1, (int *)0)

           provides  the  same  functionality  as setterm(term).  The
           setterm routine is included here  for  BSD  compatibility,
           and is not recommended for new programs.

           The  set_curterm  routine  sets  the  variable cur_term to
           nterm, and makes all of the terminfo boolean, numeric, and
           string  variables  use  the values from nterm.  It returns
           the old value of cur_term.

           The del_curterm routine frees  the  space  pointed  to  by
           oterm and makes it available for further use.  If oterm is
           the same as cur_term, references to any  of  the  terminfo
           boolean,  numeric,  and  string  variables  thereafter may
           refer to invalid memory locations until another  setupterm
           has been called.

           The  restartterm  routine  is  similar  to  setupterm  and
           initscr, except that it is called after  restoring  memory
           and the input and output options are the same as when mem-
           ory was saved, but the terminal type and baud rate may  be
           different.   Accordingly, it saves various tty state bits,
           does a setupterm, and then restores the bits.

           The tparm routine instantiates the string str with parame-
           ters  pi.  A pointer is returned to the result of str with
           the parameters applied.

           The tparam routine is included for compatibility with  the
           GNU  termcap  implementation.  It works like tparm but you
           specify a buffer and buffer size to  be  filled  with  the
           expanded string.

           The  tputs  routine  applies  padding  information  to the
           string str and outputs it.  The str  must  be  a  terminfo
           string  variable  or the return value from tparm, tgetstr,
           or tgoto.  affcnt is the number of lines affected, or 1 if
           not  applicable.   putc is a putchar-like routine to which
           the characters are passed, one at a time.

           The putp routine calls tputs(str, 1, putchar).  Note  that
           the  output  of  putp  always  goes  to stdout, not to the
           fildes specified in setupterm.

           The vidputs routine displays the string on the terminal in
           the  video  attribute mode attrs, which is any combination
           of the attributes listed in  curses(3X).   The  characters
           are passed to the putchar-like routine putc.

           The  vidattr  routine  is like the vidputs routine, except
           that it outputs through putchar.

           The mvcur routine provides low-level  cursor  motion.   It
           takes   effect   immediately  (rather  than  at  the  next
           refresh).

           The tigetflag, tigetnum and tigetstr routines  return  the
           value of the capability corresponding to the terminfo cap-
           name passed to them, such as xenl.

           The tigetflag routine returns the value -1 if  capname  is
           not a boolean capability.

           The  tigetnum  routine  returns the value -2 if capname is
           not a numeric capability.

           The tigetstr routine returns the value (char *)-1 if  cap-
           name is not a string capability.

           The capname for each capability is given in the table col-
           umn entitled capname code in the capabilities  section  of

           char *numnames, *numcodes, *numfnames

           char *strnames, *strcodes, *strfnames

           These  null-terminated  arrays  contain  the capnames, the
           termcap codes, and the full C names, for each of the  ter-
           minfo variables.

## RETURN VALUE

           Routines  that  return  an integer return ERR upon failure
           and OK (SVr4 only specifies "an integer value  other  than
           ERR")  upon  successful completion, unless otherwise noted
           in the preceding routine descriptions.

           Routines that return pointers always return NULL on error.

## NOTES

           The  setupterm routine should be used in place of setterm.
           It may be useful when you want to test for terminal  capa-
           bilities  without  committing to the allocation of storage
           involved in initscr.

           Note that vidattr and vidputs may be macros.

## PORTABILITY

           The function setterm is not described in  the  XSI  Curses
           standard  and  must be considered non-portable.  All other
           functions are as described in the XSI curses standard.

           In System V Release 4, set_curterm has an int return  type
           and  returns  OK  or ERR.  We have chosen to implement the
           XSI Curses semantics.

           In System V Release 4, the third argument of tputs has the
           type int (*putc)(char).

           The XSI Curses standard prototypes tparm with a fixed num-
           ber of parameters, rather than a variable argument list.

## SEE ALSO

           curses(3X), curs_initscr(3X), curs_kernel(3X),  curs_term-
           cap(3X), putc(3S), terminfo(5)