http://invisible-island.net/ncurses/man/


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)(int));
       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.


Initialization

       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)].

       Each initialization routine provides applications with the
       terminal capabilities either directly (via header  defini-
       tions),  or  by special functions.  The header files curs-
       es.h and term.h should be included (in this order) to  get
       the definitions for these strings, numbers, and flags.

       The  terminfo  variables lines and columns are initialized
       by setupterm as follows:

       o   If use_env(FALSE) has been called,  values  for  lines
           and columns specified in terminfo are used.

       o   Otherwise, if the environment variables LINES and COL-
           UMNS exist, their values are used.  If these  environ-
           ment variables do not exist and the program is running
           in a window, the current window size is used.   Other-
           wise,  if  the environment variables do not exist, the
           values for lines and columns specified in the terminfo
           database are used.

       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 reset_shell_mode to restore the tty modes before  ex-
       iting [see curs_kernel(3x)].

       Programs which use cursor addressing should

       o   output enter_ca_mode upon startup and

       o   output exit_ca_mode before exiting.

       Programs which execute shell subprocesses should

       o   call  reset_shell_mode  and output exit_ca_mode before
           the shell is called and

       o   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 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.

            setupterm  determines if the entry is a hardcopy type
            by checking the hc (hardcopy) capability.

       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.

            setupterm determines if the entry is a  generic  type
            by checking the gn (generic) capability.

       -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 was replaced by setupterm.  The call:

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

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


The Terminal State

       The  setupterm  routine  stores  its information about the
       terminal in a TERMINAL structure pointed to by the  global
       variable  cur_term.   If  it  detects an error, or decides
       that the terminal is unsuitable (hardcopy or generic),  it
       discards  this information, making it not available to ap-
       plications.

       If setupterm is called repeatedly for  the  same  terminal
       type,  it  will  reuse the information.  It maintains only
       one copy of a given terminal's capabilities in memory.  If
       it is called for different terminal types, setupterm allo-
       cates new storage for each set of terminal capabilities.

       The set_curterm routine sets 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).  restartterm assumes that the
       windows and the input and output options are the  same  as
       when memory was saved, but the terminal type and baud rate
       may be different.  Accordingly, restartterm saves  various
       tty  state  bits,  calls  setupterm, and then restores the
       bits.


Formatting Output

       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.


Output Functions

       The tputs  routine  applies  padding  information  to  the
       string str and outputs it:

       o   The  str must be a terminfo string variable or the re-
           turn value from tparm, tgetstr, or tgoto.

       o   affcnt is the number of lines affected, or  1  if  not
           applicable.

       o   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).


Terminal Capability Functions

       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 capname  for  each
       capability  is  given in the table column entitled capname
       code in the capabilities section of terminfo(5).

       These routines return special values to denote errors.

       The tigetflag routine returns

       -1     if capname is not a boolean capability, or

       0      if it is canceled or absent from the  terminal  de-
              scription.

       The tigetnum routine returns

       -2     if capname is not a numeric capability, or

       -1     if  it  is canceled or absent from the terminal de-
              scription.

       The tigetstr routine returns

       (char *)-1
              if capname is not a string capability, or

       0      if it is canceled or absent from the  terminal  de-
              scription.


Terminal Capability Names

       These  null-terminated  arrays  contain the short terminfo
       names ("codes"), the termcap names, and the long  terminfo
       names ("fnames") for each of the predefined terminfo vari-
       ables:
              char *boolnames[], *boolcodes[], *boolfnames[]

              char *numnames[], *numcodes[], *numfnames[]

              char *strnames[], *strcodes[], *strfnames[]


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.


PORTABILITY

       X/Open notes that vidattr and vidputs may be macros.

       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.

       If configured to use the terminal-driver,  e.g.,  for  the
       MinGW port,

       o   setupterm  interprets a missing/empty TERM variable as
           the special value "unknown".

       o   setupterm allows explicit use of the the windows  con-
           sole driver by checking if $TERM is set to "#win32con"
           or an abbreviation of that string.

       Older versions of ncurses assumed that the file descriptor
       passed  to setupterm from initscr or newterm uses buffered
       I/O, and would write to the corresponding stream.  In  ad-
       dition  to  the  limitation  that the terminal was left in
       block-buffered mode on exit (like System V curses), it was
       problematic  because  ncurses did not allow a reliable way
       to cleanup on receiving SIGTSTP.  The current version uses
       output  buffers  managed directly by ncurses.  Some of the
       low-level functions described in this manual page write to
       the standard output.  They are not signal-safe.  The high-
       level functions in ncurses use alternate versions of these
       functions using the more reliable buffering scheme.

       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 tiparm 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.

       Other implementions may not declare  the  capability  name
       arrays.  Some provide them without declaring them.  X/Open
       does not specify them.

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


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)