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


curs_termcap 3x 2023-12-30 ncurses 6.4 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 **area);
       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  area  referenced  by  this
              pointer.   ncurses 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  area
       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 area  is  not  NULL,  and
              also  that  the resulting buffer pointer is not NULL.  If either
              check fails, area is ignored.

          o   If the checks succeed, ncurses also copies the return  value  to
              the  buffer  pointed to by area, and the library updates area 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

       The variables PC, UP and BC are set by tgetent to the terminfo  entry's
       data for pad_char, cursor_up and backspace_if_not_bs, respectively.  UP
       is not used by ncurses.  PC is used by delay_output(3x).  BC is used by
       tgoto emulation.  The variable ospeed is set by ncurses using a system-
       specific encoding to indicate the terminal's data rate.


Releasing Memory

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

       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); ncurses provides them  to  support  legacy  applications.   They
       should not be used in new programs.


Standards

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

       o   X/Open Curses, Issue 7 (2009) marks the  termcap  interface  (along
           with vwprintw and vwscanw) as withdrawn.

       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
       Externally  visible  variables  are  provided  for  support  of 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 used escapes many application developers.  The BSD termcap  library
       did  not require a trailing null character on 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.

       o   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 for compatibility with other
       implementations, but the  header  is  rarely  used  because  the  other
       implementations are not strictly compatible.


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 though 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.
           This header file was added to NetBSD's termcap library in mid-1994.

       Meanwhile, GNU termcap began development in 1990.   Its  first  release
       (1.0)  in  1991  included  a  termcap.h  header.   Its  second (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.   BSD  termcap  did  not.   The  prototype  for  tputs  also
       differed,  but  in that instance, it was libedit that differed from BSD
       termcap.

       GNU termcap 1.3 was bundled with bash(1) in  mid-1993  to  support  the
       readline(3) library.

       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.


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 expand terminfo-style strings 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

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

       https://invisible-island.net/ncurses/tctest.html



ncurses 6.4                       2023-12-30                  curs_termcap(3x)