# curs_terminfo

## NAME



           **del_curterm** , **mvcur** , **putp** , **restartterm** , **set_curterm** , **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_**);**
           **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  termi‐
           nal capabilities, such as programming function keys.  For all oth‐
           er  functionality, **curses** routines are more suitable and their use
           is recommended.
    
           None of these functions use (or are aware of) multibyte  character
           strings such as UTF-8:
    
           •   capability names use the POSIX portable character set
    
           •   capability string values have no associated encoding; they are
               strings of 8-bit characters.
    
       **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 variables [listed in **termin‐**
           **fo**(5)].
    
           Applications can use the terminal capabilities either directly
           (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 **se‐**
           **tupterm** 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** ex‐
               ist, their values 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.
    
           Parameterized strings should be passed through **tparm** to instanti‐
           ate 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 exiting [see **curs_kernel**(3X)].
    
           Programs which use cursor addressing should
    
           •   output **enter_ca_mode** upon startup and
    
           •   output **exit_ca_mode** before exiting.
    
           Programs which execute shell subprocesses should
    
           •   call **reset_shell_mode** and output **exit_ca_mode** before the shell
               is called and
    
           •   output **enter_ca_mode** and call **reset_prog_mode** after returning
               from the shell.
    
           The **setupterm** routine reads in the **terminfo** database, initializing
           the **terminfo** structures, but does not set up the output virtual‐
           ization 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 status 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 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 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 applications.
    
           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** allocates 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 refer to invalid memory locations
           until another **setupterm** has been called.
    
           The **restartterm** routine is similar to **setupterm** and **initscr** , ex‐
           cept 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 op‐
           tions 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 parameters _pi_.
           A pointer is returned to the result of _str_ with the parameters ap‐
           plied.  Application developers should keep in mind these quirks of
           the interface:
    
           •   Although **tparm** 's actual parameters may be integers or strings,
               the prototype expects **long**(integer) values.
    
           •   Aside from the **set_attributes**(**sgr**) capability, most terminal
               capabilities require no more than one or two parameters.
    
           •   Padding information is ignored by **tparm** ; it is interpreted by
               **tputs**.
    
           •   The capability string is null-terminated.  Use “\200” where an
               ASCII NUL is needed in the output.
    
           **tiparm** is a newer form of **tparm** which uses _< stdarg.h>_ rather than
           a fixed-parameter list.  Its numeric parameters are integers (int)
           rather than longs.
    
       **Output Functions**
           The **tputs** routine applies padding information (i.e., by interpret‐
           ing marker embedded in the terminfo capability such as “$<5>” as 5
           milliseconds) to the string _str_ and outputs it:
    
           •   The _str_ parameter must be a terminfo string variable or the
               return value from **tparm** , **tiparm** , **tgetstr** , or **tgoto**.
    
               The **tgetstr** and **tgoto** functions are part of the _termcap_ inter‐
               face, which happens to share this function name with the _ter‐_
               _minfo_ interface.
    
           •   _affcnt_ is the number of lines affected, or 1 if not applica‐
               ble.
    
           •   _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 **se‐**
           **tupterm**.
    
           The **vidputs** routine displays the string on the terminal in the
           video attribute mode _attrs_ , which is any combination of the at‐
           tributes 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 vid‐
           puts, respectively.  They use a set of arguments for representing
           the video attributes plus color, i.e.,
    
           •   _attrs_ of type **attr_t** for the attributes and
    
           •   _pair_ of type **short** for the color-pair number.
    
           The **vid_attr** and **vid_puts** routines are designed to use the at‐
           tribute 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 allows _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 ef‐
           fect immediately (rather than at the next refresh).
    
           While **putp** and **mvcur** are low-level functions which do not use the
           high-level curses state, they are declared in **< curses.h> **because
           SystemV did this (see _HISTORY_).
    
       **Terminal Capability Functions**
           The **tigetflag** , **tigetnum** and **tigetstr** routines return the value of
           the capability corresponding to the **terminfo** _capname_ 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 description.
    
           The **tigetnum** routine returns
    
           **-2** if _capname_ is not a numeric capability, or
    
           **-1** if it is canceled or absent from the terminal description.
    
           The **tigetstr** routine returns
    
           **(char *)-1**
                  if _capname_ is not a string capability, or
    
           **0** if it is canceled or absent from the terminal description.
    
       **Terminal Capability Names**
           These null-terminated arrays contain
    
           •   the short terminfo names (“codes”),
    
           •   the **termcap** names (“names”), and
    
           •   the long terminfo names (“fnames”)
    
           for each of the predefined **terminfo** variables:
    
                  **const char *boolnames[]** , ***boolcodes[]** , ***boolfnames[]**
                  **const char *numnames[]** , ***numcodes[]** , ***numfnames[]**
                  **const char *strnames[]** , ***strcodes[]** , ***strfnames[]**
    
       **Releasing Memory**
           Each successful call to **setupterm** allocates memory to hold the
           terminal description.  As a side-effect, it sets **cur_term** to point
           to this memory.  If an application calls
    
                **del_curterm(cur_term);**
    
           the memory will be freed.
    
           The formatting functions **tparm** and **tiparm** extend the storage allo‐
           cated by **setupterm** :
    
           •   the “static” terminfo variables [a-z].  Before ncurses 6.3,
               those were shared by all screens.  With ncurses 6.3, those are
               allocated per screen.  See terminfo(5) for details.
    
           •   to improve performance, ncurses 6.3 caches the result of ana‐
               lyzing terminfo strings for their parameter types.  That is
               stored as a binary tree referenced from the **TERMINAL** struc‐
               ture.
    
           The higher-level **initscr** and **newterm** functions use **setupterm**.
           Normally they do not free this memory, but it is possible to do
           that using the **delscreen**(3X) function.
    


## RETURN VALUE



           Routines that return an integer return **ERR** upon failure and **OK**
           (SVr4 only specifies “an integer value other than **ERR** ”) upon suc‐
           cessful completion, unless otherwise noted in the preceding rou‐
           tine descriptions.
    
           Routines that return pointers always return **NULL** on error.
    
           X/Open defines no error conditions.  In this implementation
    
              **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 **setupterm** re‐
                   turns an error.
    
              **setupterm**
                   returns an error if it cannot allocate enough memory, or
                   create the initial windows (stdscr, curscr, newscr).  Oth‐
                   er 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_.
    
       **Compatibility macros**
           This implementation provides a few macros for compatibility with
           systems before SVr4 (see _HISTORY_).  Those include **crmode** , **fixterm** ,
           **gettmode** , **nocrmode** , **resetterm** , **saveterm** , and **setterm**.
    
           In SVr4, those are found in **< curses.h>**, but except for **setterm** ,
           are likewise macros.  The one function, **setterm** , is mentioned in
           the manual page.  The manual page notes that the **setterm** routine
           was replaced by **setupterm** , stating that the call:
    
                 **setupterm(**_term_**, 1, (int *)0)**
    
           provides the same functionality as **setterm(**_term_**)** , and is not rec‐
           ommended for new programs.  This implementation provides each of
           those symbols as macros for BSD compatibility,
    


## 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 con‐
           sidered 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 addition 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 direct‐
           ly 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.
    
       **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.
    
           •   X/Open Curses uses **const** less effectively than a later design
               might, in some cases applying it needlessly to values are al‐
               ready constant, and in most cases overlooking parameters which
               normally would use **const**.  Using constant parameters for func‐
               tions which do not use **const** may prevent the program from com‐
               piling.  On the other hand, _writable strings_ are an obsoles‐
               cent 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.
    
           •   X/Open Curses prototypes **tparm** with a fixed number of parame‐
               ters, rather than a variable argument list.
    
               This implementation uses a variable argument list, but can be
               configured to use the fixed-parameter list.  Portable applica‐
               tions should provide 9 parameters after 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,
    
           •   **setupterm** interprets a missing/empty TERM variable as the spe‐
               cial value “unknown”.
    
           •   **setupterm** allows explicit use of the the windows console dri‐
               ver by checking if $TERM is set to “#win32con” or an abbrevia‐
               tion of that string.
    
       **Other portability issues**
           In System V Release 4, **set_curterm** has an **int** return type and re‐
           turns **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) returns 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 application should
           touch and refresh the window before resuming normal curses calls.
           Both **ncurses** and System V Release 4 curses implement **mvcur** using
           the SCREEN data allocated in either **initscr** or **newterm**.  So though
           it is documented 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 ordi‐
           nates.  In that case, the old location is unknown.
    


* * *