# curs_termcap 3x 2025-02-01 ncurses 6.5 Library calls

    curs_termcap(3x)                 Library calls                curs_termcap(3x)

## NAME

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

## SYNOPSIS

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

           char PC;
           char * UP;
           char * BC;
           short ospeed;

           int tgetent(char * bp, const char * name);
           int tgetflag(const char * id);
           int tgetnum(const char * id);
           char * tgetstr(const char * id, char ** sbuf);
           char * tgoto(const char * cap, int col, int row);
           int tputs(const char * str, int affcnt, int (* putc)(int));

## DESCRIPTION

           ncurses  provides  the  foregoing  variables   and   functions   as   a
           compatibility layer for programs that use the termcap library.  The API
           is the same, but behavior is  emulated  using  the  terminfo  database.
           Thus,  it  can  be  used  only  to  query  the capabilities of terminal
           database entries for which a terminfo entry has been compiled.

### Initialization

           tgetent loads the terminal database entry for name; see term(7).   This
           must be done before calling any of the other functions.  It returns

              1    on success,

              0    if there is no such entry (or if the matching entry describes a
                   generic terminal, having  too  little  information  for  curses
                   applications to run), and

              -1   if the terminfo database could not be found.

           This implementation differs from those of historical termcap libraries.

           o   ncurses  ignores  the  buffer  pointer  bp,  as  do  other  termcap
               implementations  conforming  to  portions  of  X/Open  Curses   now
               withdrawn.   The  BSD  termcap  library  would  store a copy of the
               terminal type description in the buffer referenced by this pointer.
               terminfo  stores terminal type descriptions in compiled form, which
               is not the same thing.

           o   The meanings of the return values differ.  The BSD termcap  library
               does  not  check whether the terminal type description includes the
               generic (gn) capability, nor whether the terminal type  description
               supports an addressable cursor, a property essential for any curses
               implementation to operate.

### Retrieving Capability Values

           tgetflag reports the Boolean entry  for  id,  or  zero  if  it  is  not
           available.

           tgetnum obtains the numeric entry for id, or -1 if it is not available.

           tgetstr  returns  the  string  entry  for  id,  or  NULL  if  it is not
           available.   Use  tputs  to  output  the  string  returned.   The  sbuf
           parameter is used as follows.

           o   It is assumed to be the address of a pointer to a buffer managed by
               the calling application.

           o   However, ncurses checks to ensure that sbuf is not NULL,  and  that
               the  pointer  obtained  by dereferencing sbuf is also not NULL.  If
               either check fails, ncurses ignores sbuf.

           o   If the checks succeed, ncurses also copies the return value to  the
               buffer  pointed  to  by sbuf, and the library updates sbuf to point
               past the null character terminating this value.

           o   The return  value  itself  is  an  address  in  the  terminal  type
               description loaded into memory.

### Applying String Capabilities

           String capabilities can be parameterized; see subsection "Parameterized
           Strings" in  terminfo(5).  tgoto applies its second and third arguments
           to  the  parametric  placeholders in the capability stored in the first
           argument.

           o   The capability may contain padding specifications;  see  subsection
               "Delays  and  Padding"  of terminfo(5).  The output of tgoto should
               thus be passed to tputs rather than some other output function such
               as printf(3).

           o   While  tgoto  is  assumed  to  be used for the two-parameter cursor
               positioning  capability,  termcap  applications  also  use  it  for
               single-parameter capabilities.

               Doing  so  reveals  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 col (column) parameter
               first.  The tgoto function swaps the order of its  parameters.   It
               does  this  even  for  calls requiring only a single parameter.  In
               that case, the first parameter is merely a placeholder.

           o   Normally the ncurses  library  is  compiled  without  full  termcap
               support.  In that case, tgoto uses an internal version of tparm(3x)
               (a more capable function).

               Because it uses tparm internally, tgoto is able to use  some  term-
               info  features, but not all.  In particular, it allows only numeric
               parameters; tparm supports string parameters.

               However, tparm is not  a  termcap  feature,  and  portable  termcap
               applications should not rely upon its availability.

           tputs  is described in curs_terminfo(3x).  It can retrieve capabilities
           by either termcap or terminfo code.

### Global Variables

           tgetent sets the variables PC, UP, and BC to the terminfo entry's  data
           for  pad_char  (pad), cursor_up (cuu1), and backspace_if_not_bs (OTbs),
           respectively.    ncurses   does    not    employ    cuu1    internally.
           delay_output(3x)  uses  pad,  while  tgoto  emulation uses the obsolete
           termcap capability bs,  represented  in  ncurses  terminfo  as  "OTbs".
           ncurses  assigns  the variable ospeed a system-specific value to encode
           the terminal's data rate.

### Releasing Memory

           The termcap functions provide  no  means  of  freeing  memory,  because
           legacy  termcap  implementations  used only the storage provided by the
           caller via tgetent and tgetstr.  Those buffers are unused in terminfo.

           By contrast, terminfo  allocates  memory.   It  uses  setupterm(3x)  to
           obtain  the  data  used  by  tgetent  and  the  functions that retrieve
           capability values.  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 value
           of the terminal name parameter given to tgetent.  The screen(1) program
           relies upon this arrangement to improve its performance.

           An  application  that  uses only the termcap functions, not the higher-
           level curses API,  could  release  the  memory  using  del_curterm(3x),
           because the pool is freed using other functions; see curs_memleaks(3x).

## RETURN VALUE

           The  return  values  of  tgetent,  tgetflag,  tgetname, and tgetstr are
           documented above.

           tgoto returns NULL on error.  Error conditions include:

           o   uninitialized state (tgetent was not called successfully),

           o   cap being a null pointer,

           o   cap referring to a canceled capability,

           o   cap being a  capability  with  string-valued  parameters  (a  term-
               info-only feature), and

           o   cap being a capability with more than two parameters.

           See curs_terminfo(3x) regarding tputs.

## NOTES

           ncurses  compares  only the first two characters of the id parameter of
           tgetflag, tgetnum, and tgetstr to the capability names in the database.

## PORTABILITY

           These functions are no longer standardized  (and  the  variables  never
           were);  see  section "HISTORY" below.  ncurses provides them to support
           legacy applications; they should not be used in new programs.

           SVr4 describes a successful return value  only  as  "an  integer  value
           other than ERR".

           Neither  X/Open  Curses  nor  the  SVr4 man pages documented the return
           values of tgetent correctly, though all three shown here were  in  fact
           returned  ever  since  SVr1.   In particular, an omission in the X/Open
           Curses specification has  been  misinterpreted  to  mean  that  tgetent
           returns  OK  or  ERR.   Because  the  purpose  of these functions is to
           provide compatibility with the termcap library, that  is  a  defect  in
           X/Open Curses Issue 4 Version 2 rather than in ncurses.

       Compatibility with BSD termcap
           ncurses  provides  externally  visible  variables  to  support  certain
           termcap  applications.   However,  their  correct   usage   is   poorly
           documented; for example, it is unclear when reading and writing them is
           meaningful.  In particular, some applications are reported  to  declare
           and/or modify ospeed.

           The  constraint  that only the first two characters of the id parameter
           are looked  up  in  the  terminal  database  escapes  many  application
           developers.   The  BSD  termcap library did not require a trailing null
           character after the capability identifier passed to  tgetstr,  tgetnum,
           and tgetflag.  Some applications thus assume that the termcap interface
           does not  require  the  trailing  null  character  for  the  capability
           identifier.

           ncurses  disallows  matches  by  the termcap interface against extended
           capability names that are longer than two characters; see user_caps(5).

           The BSD termcap function tgetent returns the text of a termcap entry in
           the  buffer  passed  as an argument.  This library, like other terminfo
           implementations, does not store terminal type descriptions as text.  It
           sets the buffer contents to a null-terminated string.

### Header File

           This  library  includes  a termcap.h header file for compatibility with
           other  implementations,  but  it  is  rarely  used  because  the  other
           implementations are not mutually compatible; see below.

## HISTORY

           Bill  Joy  originated  a  forerunner  of termcap called "ttycap", dated
           September 1977, and released in 1BSD (March 1978).  It used many of the
           same  function  names  as the later termcap, such as tgetent, tgetflag,
           tgetnum, and tgetstr.

           A clear descendant, the termlib library, followed in 2BSD  (May  1979),
           adding tgoto and tputs.  The former applied at that time only to cursor
           positioning  capabilities,  thus  the  overly  specific  name.   Little
           changed  in 3BSD (late 1979) except the addition of test programs and a
           termlib man page, which documented the API shown in section  "SYNOPSIS"
           above.

           4BSD  (November 1980) renamed termlib to termcap and added another test
           program.  The library remained  much  the  same  through  4.3BSD  (June
           1986).    4.4BSD-Lite  (June  1994)  refactored  it,  leaving  the  API
           unchanged.

           Function prototypes were a feature of ANSI C (1989).  The library  long
           antedated the standard and thus provided no header file declaring them.
           Nevertheless, the BSD sources included two different  termcap.h  header
           files over time.

           o   One was used internally by jove(1) from 4.3BSD onward.  It declared
               global symbols for the termcap variables that it used.

           o   The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part  of
               libedit  (also known as the editline library).  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 prototypes, but no global variables.
               NetBSD's termcap library added this header file in mid-1994.

           Meanwhile,  GNU  termcap  began development in 1990.  Its first release
           (1.0) in 1991 included a  termcap.h  header  file.   Its  second  (1.1)
           release  in  September  1992  modified  the  file  to use const for the
           function prototypes in the header where one would expect parameters  to
           be  read-only.   BSD  termcap  did  not.   The prototype for tputs also
           differed, but in that instance, it was libedit that differed  from  BSD
           termcap.

           GNU  bash(1)  has bundled GNU termcap 1.3 since mid-1993 to support its
           readline(3) library, and continues to use it if configured to do so.

           ncurses 1.8.1 (November 1993) provided a termcap.h file.  It  reflected
           influence   from  GNU  termcap  and  emacs(1)  (rather  than  jove(1)),
           providing the following interface:

           o   global symbols used by emacs,

           o   const-qualified function prototypes, and

           o   a prototype for tparam, a GNU termcap feature.

           Later (in mid-1996) the tparam function was removed from ncurses.   Any
           two  of  the four implementations thus differ, and programs that intend
           to work with all termcap library interfaces must account for that fact.

           X/Open Curses Issue 4, Version 2  (1996),  describes  these  functions,
           marking them as "TO BE WITHDRAWN".

           X/Open Curses Issue 7 (2009) withdrew the termcap interface (along with
           the vwprintw and vwscanw functions).

## BUGS

           If  you  call  tgetstr  to  fetch  column_address  (ch)  or  any  other
           parameterized  string capability, be aware that it is returned in term-
           info notation, not the older and not-quite-compatible termcap notation.
           This  does  not  cause  problems if all you do with it is call tgoto or
           tparm,  which  both   parametrically   expand   terminfo-style   string
           capabilities  as  terminfo  does.  (If ncurses is configured to support
           termcap, tgoto checks whether the string is terminfo-style  by  looking
           for  "%p"  parameters  or  "<...>"  delays, and invokes a termcap-style
           parser if the string appears not to use terminfo syntax.)

           Because terminfo's syntax for padding in  string  capabilities  differs
           from termcap's, users can be surprised.

           o   tputs("50")  in  a terminfo system transmits "50" rather than busy-
               waiting for 50 milliseconds.

           o   However, if ncurses is configured to support termcap, it  may  also
               have been configured to support 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 busy-wait for  50  milliseconds
               rather than transmitting "50".

           termcap  has  nothing  analogous  to  terminfo's  set_attributes  (sgr)
           capability.  One consequence is that termcap applications  assume  that
           "me"  (equivalent  to terminfo's exit_attribute_mode (sgr0) capability)
           does not reset the alternate character set.  ncurses  checks  for,  and
           modifies the data shared with, the termcap interface to accommodate the
           latter's limitation in this respect.

## SEE ALSO

           TCTEST -- A Termcap Test Utility <https://invisible-island.net/ncurses/
           tctest.html>

           curses(3x), curs_terminfo(3x), putc(3), term_variables(3x), terminfo(5)

    ncurses 6.5                       2025-02-01                  curs_termcap(3x)