# curs_terminfo 3x

    curs_terminfo(3x)                                     curs_terminfo(3x)

## NAME

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

## SYNOPSIS

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

           int setupterm(char *term, int fildes, int *errret);
           int setterm(char *term);
           TERMINAL *set_curterm(TERMINAL *nterm);
           int del_curterm(TERMINAL *oterm);
           int restartterm(char *term, int fildes, int *errret);
           char *tparm(char *str, ...);
           int tputs(const char *str, int affcnt, int (*putc)(int));
           int putp(const char *str);
           int vidputs(chtype attrs, int (*putc)(int));
           int vidattr(chtype attrs);
           int vid_puts(attr_t attrs, short pair, void *opts, int (*putc)(char));
           int vid_attr(attr_t attrs, short pair, void *opts);
           int mvcur(int oldrow, int oldcol, int newrow, int newcol);
           int tigetflag(char *capname);
           int tigetnum(char *capname);
           char *tigetstr(char *capname);
           char *tiparm(const char *str, ...);

## 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  se-
           tupterm  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 values are used.  If these en-
                  vironment 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  speci-
                  fied 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
           strings  [including the output of tparm] should be printed
           with tputs or putp.  Call the reset_shell_mode to  restore
           the  tty modes before exiting [see curs_kernel(3x)].  Pro-
           grams  which  use  cursor  addressing  should  output  en-
           ter_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  re-
           set_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 er-
           rret.   A  return value of OK combined with status of 1 in
           errret is normal.  If ERR is returned, examine errret:

                  1    means that the terminal is hardcopy, cannot be
                       used for curses applications.

                  0    means that the terminal could not be found, or
                       that it is a generic type, having  too  little
                       information for curses applications to run.

                  -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 re-
           fer 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
           to  a  previous  state (for example, when reloading a game
           saved as a core image dump).  It assumes that the  windows
           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,
           calls 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.

           tiparm is a newer form  of  tparm  which  uses  <stdarg.h>
           rather  than  a fixed-parameter list.  Its numeric parame-
           ters are integers (int) rather than longs.

           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  vid_attr  and vid_puts routines correspond to vidattr
           and vidputs, respectively.  They use a  set  of  arguments
           for  representing  the  video attributes plus color, i.e.,
           one of type attr_t for the attributes and one of short for
           the color_pair number.  The vid_attr and vid_puts routines
           are designed to use the attribute constants with  the  WA_
           prefix.   The  opts  argument  is reserved for future use.
           Currently, applications must provide a  null  pointer  for
           that argument.

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

           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, or 0 if it is canceled or absent
           from the terminal description.

           The  tigetnum  routine  returns the value -2 if capname is
           not a numeric capability, or -1 if it is canceled  or  ab-
           sent from the terminal description.

           The  tigetstr routine returns the value (char *)-1 if cap-
           name is not a string capability, or 0 if it is canceled or
           absent from the terminal description.

           The capname for each capability is given in the table col-
           umn entitled capname code in the capabilities  section  of
           terminfo(5).

                  char *boolnames[], *boolcodes[], *boolfnames[]

                  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.

           X/Open defines no error conditions.  In  this  implementa-
           tion

                  del_curterm
                       returns  an error if its terminal parameter is
                       null.

                  putp calls tputs, returning the same error-codes.

                  restartterm
                       returns an error if the associated call to se-
                       tupterm returns an error.

                  setupterm
                       returns  an error if it cannot allocate enough
                       memory, or create the initial windows (stdscr,
                       curscr,  newscr).   Other error conditions are
                       documented above.

                  tputs
                       returns an error if the  string  parameter  is
                       null.   It  does not detect I/O errors: X/Open
                       states that tputs ignores the return value  of
                       the output function putc.

## 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 by X/Open  and  must
           be  considered  non-portable.   All other functions are as
           described by X/Open.

           setupterm copies the terminal name to the  array  ttytype.
           This  is not part of X/Open Curses, but is assumed by some
           applications.

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

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

           At least one implementation of X/Open Curses (Solaris) re-
           turns a value other than OK/ERR from tputs.  That  returns
           the length of the string, and does no error-checking.

           X/Open  Curses prototypes tparm with a fixed number of pa-
           rameters, rather than a variable argument list.  This  im-
           plementation  uses  a  variable  argument list, but can be
           configured to use the fixed-parameter list.  Portable  ap-
           plications  should  provide 9 parameters after the format;
           zeroes are fine for this purpose.

           In response to comments by Thomas E. Dickey, X/Open Curses
           Issue 7 proposed the tiparam function in mid-2009.

           X/Open  notes  that  after calling mvcur, the curses state
           may not match the actual terminal state, and that  an  ap-
           plication  should  touch and refresh the window before re-
           suming normal curses calls.  Both ncurses and System V Re-
           lease 4 curses implement mvcur using the SCREEN data allo-
           cated in either initscr or newterm.  So though it is docu-
           mented  as  a  terminfo function, mvcur is really a curses
           function which is not well specified.

           X/Open states that the old  location  must  be  given  for
           mvcur.   This implementation allows the caller to use -1's
           for the old ordinates.  In that case, the old location  is
           unknown.

           Extended  terminal  capability  names, e.g., as defined by
           tic -x, are not stored in the  arrays  described  in  this
           section.

## SEE ALSO

           curses(3x),  curs_initscr(3x), curs_kernel(3x), curs_term-
           cap(3x), curs_variables(3x), term_variables(3x),  putc(3),
           terminfo(5)

                                                          curs_terminfo(3x)