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>

       TERMINAL *cur_term;

       const char * const boolnames[];
       const char * const boolcodes[];
       const char * const boolfnames[];
       const char * const numnames[];
       const char * const numcodes[];
       const char * const numfnames[];
       const char * const strnames[];
       const char * const strcodes[];
       const char * const strfnames[];

       int setupterm(const char *term, int filedes, int *errret);
       int setterm(const char *term);
       TERMINAL *set_curterm(TERMINAL *nterm);
       int del_curterm(TERMINAL *oterm);
       int restartterm(const char *term, int filedes, int *errret);

       char *tparm(const 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(const char *capname);
       int tigetnum(const char *capname);
       char *tigetstr(const 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.   The  high-level
       curses  functions  initscr  and  newterm call setupterm to
       initialize the low-level set of  terminal-dependent  vari-
       ables [listed in terminfo(5)].

       Applications  can use the terminal capabilities either di-
       rectly (via header definitions), or by special  functions.
       The  header  files  curses.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.  These
       are its parameters:

          term is the terminal type, a character string.  If term
               is null, the environment variable TERM is used.

          filedes
               is the file descriptor used for all output.

          errret
               points to an optional location where an error sta-
               tus can be returned to the caller.  If  errret  is
               not  null,  then  setupterm  returns OK or ERR and
               stores a status value in the integer pointed to by
               errret.  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 hard-
                    copy type by checking the hc (hardcopy) capa-
                    bility.

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

                    setupterm determines if the entry is a gener-
                    ic type by checking the gn (generic) capabil-
                    ity.

               -1   means that the terminfo database could not be
                    found.

               If  errret is null, setupterm prints an error mes-
               sage 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 stdout.

       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.   Application  developers should
       keep in mind these quirks of the interface:

       o   Although tparm's actual parameters may be integers  or
           strings, the prototype expects long (integer) values.

       o   Aside  from  the set_attributes (sgr) capability, most
           terminal capabilities require no more than one or  two
           parameters.

       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).  The output
       of putp always goes to stdout,  rather  than  the  filedes
       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.,

       o   attrs of type attr_t for the attributes and

       o   pair of type short for the color-pair number.

       The vid_attr and vid_puts routines are designed to use the
       attribute constants with the WA_ prefix.

       X/Open Curses reserves the opts argument for  future  use,
       saying  that  applications must provide a null pointer for
       that argument.  As an extension, this  implementation  al-
       lows  opts to be used as a pointer to int, which overrides
       the pair (short) 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

       o   the short terminfo names ("codes"),

       o   the termcap names ("names", and

       o   the long terminfo names ("fnames")

       for each of the predefined terminfo variables:

              const   char  *boolnames[],  *boolcodes[],  *boolf-
              names[]
              const char *numnames[], *numcodes[], *numfnames[]
              const 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 mem-
               ory,   or  create  the  initial  windows  (stdscr,
               curscr, newscr).  Other error conditions are docu-
               mented 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 func-
               tion putc.


PORTABILITY


Legacy functions

       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.


Legacy data

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

       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.


Output buffering

       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 (ncurses6) uses output buffers managed
       directly by ncurses.  Some of the low-level functions  de-
       scribed  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.


Function prototypes

       The X/Open Curses prototypes are based on the SVr4  curses
       header  declarations,  which were defined at the same time
       the C language was first standardized in the late 1980s.

       o   X/Open Curses uses const less effectively than a later
           design  might, in some cases applying it needlessly to
           values are already constant, and in most  cases  over-
           looking  parameters  which  normally  would use const.
           Using constant parameters for functions which  do  not
           use  const may prevent the program from compiling.  On
           the other hand, writable strings  are  an  obsolescent
           feature.

           As an extension, this implementation can be configured
           to change the function prototypes  to  use  the  const
           keyword.   The  ncurses  ABI 6 enables this feature by
           default.

       o   X/Open Curses prototypes tparm with a fixed number  of
           parameters, rather than a variable argument list.

           This implementation uses a variable argument list, but
           can be configured to  use  the  fixed-parameter  list.
           Portable  applications should provide 9 parameters af-
           ter the format; zeroes are fine for this purpose.

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


Special TERM treatment

       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.


Other portability issues

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


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)