# curs_termcap

## NAME



           **PC** , **UP** , **BC** , **ospeed** , **tgetent** , **tgetflag** , **tgetnum** , **tgetstr** , **tgoto** ,
           **tputs** - **curses** emulation of termcap
    


## SYNOPSIS



           **#include <curses.h>**
           **#include <term.h>**
    
           **extern char PC;**
           **extern char * UP;**
           **extern char * BC;**
           **extern @NCURSES_OSPEED@ ospeed;**
    
           **int tgetent(char ***_bp_**, const char ***_name_**);**
           **int tgetflag(const char ***_id_**);**
           **int tgetnum(const char ***_id_**);**
           **char *tgetstr(const char ***_id_**, char ****_area_**);**
           **char *tgoto(const char ***_cap_**, int** _col_**, int** _row_**);**
           **int tputs(const char ***_str_**, int** _affcnt_**, int (***_putc_**)(int));**
    


## DESCRIPTION



           These  routines are included as a conversion aid for programs that
           use the _termcap_ library.  Their parameters are the same,  but  the
           routines are emulated using the _terminfo_ database.  Thus, they can
           only be used to query the capabilities of entries for which a ter‐
           minfo entry has been compiled.
    
       **Initialization**
           The **tgetent** routine loads the entry for _name_.  It returns:
    
              1  on success,
    
              0  if there is no such entry (or that it is a generic type,
                 having too little information for curses applications to
                 run), and
    
              -1 if the terminfo database could not be found.
    
           This differs from the _termcap_ library in two ways:
    
              •   The emulation ignores the buffer pointer _bp_.  The _termcap_
                  library would store a copy of the terminal description in
                  the area referenced by this pointer.  However, ncurses
                  stores its terminal descriptions in compiled binary form,
                  which is not the same thing.
    
              •   There is a difference in return codes.  The _termcap_ library
                  does not check if the terminal description is marked with
                  the _generic_ capability, or if the terminal description has
                  cursor-addressing.
    
       **Capability Values**
           The **tgetflag** routine gets the boolean entry for _id_ , or zero if it
           is not available.
    
           The **tgetnum** routine gets the numeric entry for _id_ , or -1 if it is
           not available.
    
           The **tgetstr** routine returns the string entry for _id_ , or zero if it
           is not available.  Use **tputs** to output the returned string.  The
           _area_ parameter is used as follows:
    
              •   It is assumed to be the address of a pointer to a buffer
                  managed by the calling application.
    
              •   However, ncurses checks to ensure that **area** is not NULL,
                  and also that the resulting buffer pointer is not NULL.  If
                  either check fails, the _area_ parameter is ignored.
    
              •   If the checks succeed, ncurses also copies the return value
                  to the buffer pointed to by _area_ , and the _area_ value will
                  be updated to point past the null ending this value.
    
              •   The return value itself is an address in the terminal de‐
                  scription which is loaded into memory.
    
           Only the first two characters of the **id** parameter of **tgetflag** ,
           **tgetnum** and **tgetstr** are compared in lookups.
    
       **Formatting Capabilities**
           The **tgoto** routine expands the given capability using the parame‐
           ters.
    
           •   Because the capability may have padding characters, the output
               of **tgoto** should be passed to **tputs** rather than some other out‐
               put function such as printf(3).
    
           •   While **tgoto** is assumed to be used for the two-parameter cursor
               positioning capability, termcap applications also use it for
               single-parameter capabilities.
    
               Doing this shows a quirk in **tgoto** : most hardware terminals use
               cursor addressing with _row_ first, but the original developers
               of the termcap interface chose to put the _column_ parameter
               first.  The **tgoto** function swaps the order of parameters.  It
               does this also for calls requiring only a single parameter.
               In that case, the first parameter is merely a placeholder.
    
           •   Normally the ncurses library is compiled with terminfo sup‐
               port.  In that case, **tgoto** uses **tparm**(3X) (a more capable for‐
               matter).
    
               However, **tparm** is not a _termcap_ feature, and portable _termcap_
               applications should not rely upon its availability.
    
           The **tputs** routine is described on the **curs_terminfo**(3X) manual
           page.  It can retrieve capabilities by either termcap or terminfo
           name.
    
       **Global Variables**
           The variables **PC** , **UP** and **BC** are set by **tgetent** to the terminfo en‐
           try's data for **pad_char** , **cursor_up** and **backspace_if_not_bs** , re‐
           spectively.  **UP** is not used by ncurses.  **PC** is used in the **tde‐**
           **lay_output** function.  **BC** is used in the **tgoto** emulation.  The
           variable **ospeed** is set by ncurses in a system-specific coding to
           reflect the terminal speed.
    
       **Releasing Memory**
           The termcap functions provide no means for freeing memory, because
           legacy termcap implementations used only the buffer areas provided
           by the caller via **tgetent** and **tgetstr**.  Those buffers are unused
           in terminfo.
    
           On the other hand, terminfo allocates memory.  It uses **setupterm**
           to retrieve the data used by **tgetent** and the functions which re‐
           turn capability values such as **tgetstr**.  One could use
    
                **del_curterm(cur_term);**
    
           to free this memory, but there is an additional complication with
           ncurses.  It uses a fixed-size _pool_ of storage locations, one per
           setting of the **TERM** variable when **tgetent** is called.  The
           screen(1) program relies upon this arrangement, to improve its
           performance.
    
           An application which uses only the low-level termcap functions
           could free the memory using **del_curterm** , because the pool is freed
           using other functions (see **curs_memleaks**(3X)).
    


## RETURN VALUE



           Except where explicitly noted, routines that return an integer re‐
           turn **ERR** upon failure and **OK**(SVr4 only specifies "an integer val‐
           ue other than **ERR** ") upon successful completion.
    
           Routines that return pointers return **NULL** on error.
    


## BUGS



           If you call **tgetstr** to fetch **ca** or any other parameterized string,
           be aware that it will be returned in terminfo notation, not the
           older and not-quite-compatible termcap notation.  This will not
           cause problems if all you do with it is call **tgoto** or **tparm** , which
           both expand terminfo-style strings as terminfo.  (The **tgoto** func‐
           tion, if configured to support termcap, will check if the string
           is indeed terminfo-style by looking for "%p" parameters or "$<..>"
           delays, and invoke a termcap-style parser if the string does not
           appear to be terminfo).
    
           Because terminfo conventions for representing padding in string
           capabilities differ from termcap's, users can be surprised:
    
           •   **tputs("50")** in a terminfo system will put out a literal “50”
               rather than busy-waiting for 50 milliseconds.
    
           •   However, if ncurses is configured to support termcap, it may
               also have been configured to support the BSD-style padding.
    
               In that case, **tputs** inspects strings passed to it, looking for
               digits at the beginning of the string.
    
               **tputs("50")** in a termcap system may wait for 50 milliseconds
               rather than put out a literal “50”
    
           Note that termcap has nothing analogous to terminfo's **sgr** string.
           One consequence of this is that termcap applications assume **me**
           (terminfo **sgr0**) does not reset the alternate character set.  This
           implementation checks for, and modifies the data shown to the
           termcap interface to accommodate termcap's limitation in this re‐
           spect.
    


## PORTABILITY



       **Standards**
           These functions are provided for supporting legacy applications,
           and should not be used in new programs:
    
           •   The XSI Curses standard, Issue 4 describes these functions.
               However, they are marked TO BE WITHDRAWN and may be removed in
               future versions.
    
           •   X/Open Curses, Issue 5 (December 2007) marked the termcap in‐
               terface (along with **vwprintw** and **vwscanw**) as withdrawn.
    
           Neither the XSI Curses standard nor the SVr4 man pages documented
           the return values of **tgetent** correctly, though all three were in
           fact returned ever since SVr1.  In particular, an omission in the
           XSI Curses documentation has been misinterpreted to mean that **tge‐**
           **tent** returns **OK** or **ERR**.  Because the purpose of these functions is
           to provide compatibility with the _termcap_ library, that is a de‐
           fect in XCurses, Issue 4, Version 2 rather than in ncurses.
    
       **Compatibility with BSD Termcap**
           External variables are provided for support of certain termcap ap‐
           plications.  However, termcap applications' use of those variables
           is poorly documented, e.g., not distinguishing between input and
           output.  In particular, some applications are reported to declare
           and/or modify **ospeed**.
    
           The comment that only the first two characters of the **id** parameter
           are used escapes many application developers.  The original BSD
           4.2 termcap library (and historical relics thereof) did not re‐
           quire a trailing null NUL on the parameter name passed to **tgetstr** ,
           **tgetnum** and **tgetflag**.  Some applications assume that the termcap
           interface does not require the trailing NUL for the parameter
           name.  Taking into account these issues:
    
           •   As a special case, **tgetflag** matched against a single-character
               identifier provided that was at the end of the terminal de‐
               scription.  You should not rely upon this behavior in portable
               programs.  This implementation disallows matches against sin‐
               gle-character capability names.
    
           •   This implementation disallows matches by the termcap interface
               against extended capability names which are longer than two
               characters.
    
           The BSD termcap function **tgetent** returns the text of a termcap en‐
           try in the buffer passed as an argument.  This library (like other
           terminfo implementations) does not store terminal descriptions as
           text.  It sets the buffer contents to a null-terminated string.
    
       **Other Compatibility**
           This library includes a termcap.h header, for compatibility with
           other implementations.  But the header is rarely used because the
           other implementations are not strictly compatible.
    
           The original BSD termcap (through 4.3BSD) had no header file which
           gave function prototypes, because that was a feature of ANSI C.
           BSD termcap was written several years before C was standardized.
           However, there were two different termcap.h header files in the
           BSD sources:
    
           •   One was used internally by the **jove** editor in 2BSD through
               4.4BSD.  It defined global symbols for the termcap variables
               which it used.
    
           •   The other appeared in 4.4BSD Lite Release 2 (mid-1993) as part
               of _libedit_ (also known as the _editline_ library).  The CSRG
               source history shows that this was added in mid-1992.  The
               _libedit_ header file was used internally, as a convenience for
               compiling the _editline_ library.  It declared function proto‐
               types, but no global variables.
    
           The header file from _libedit_ was added to NetBSD's termcap library
           in mid-1994.
    
           Meanwhile, GNU termcap was under development, starting in 1990.
           The first release (termcap 1.0) in 1991 included a termcap.h head‐
           er.  The second release (termcap 1.1) in September 1992 modified
           the header to use **const** for the function prototypes in the header
           where one would expect the parameters to be read-only.  This was a
           difference versus the original BSD termcap.  The prototype for
           **tputs** also differed, but in that instance, it was _libedit_ which
           differed from BSD termcap.
    
           A copy of GNU termcap 1.3 was bundled with _bash_ in mid-1993, to
           support the readline(3) library.
    
           A termcap.h file was provided in ncurses 1.8.1 (November 1993).
           That reflected influence by **emacs**(1) (rather than **jove**(1)) and GNU
           termcap:
    
           •   it provided declarations for a few global symbols used by
               **emacs**
    
           •   it provided function prototypes (using **const**).
    
           •   a prototype for **tparam**(a GNU termcap feature) was provided.
    
           Later (in mid-1996) the **tparam** function was removed from ncurses.
           As a result, there are differences between any of the four imple‐
           mentations, which must be taken into account by programs which can
           work with all termcap library interfaces.
    


* * *