doc/html/man/curs_termcap.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2022,2023 Thomas E. Dickey                                *
   4   * Copyright 1998-2017,2018 Free Software Foundation, Inc.                  *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: curs_termcap.3x,v 1.76 2023/12/18 00:22:30 tom Exp @
  31   * See &lt;https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/\
  32   *   termlib/termcap.c&gt;.
  33   * See https://www.oreilly.com/openbook/opensources/book/kirkmck.html
  34   * for much BSD release history.
  35   * https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s7/ttycap.c
  36   * https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/man7/ttycap.7
  37   * https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/termlib/
  38   * https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/bin/etc/termcap
  39   * https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/lib/\
  40   *   libtermlib/
  41   * https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/man/man3/\
  42   *   termlib.3
  43   * ...except in the source tree...
  44   * https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
  45   *   libtermlib/makefile
  46   * Observe the `tncktc()`, `tnamatch()`, `tskip()`, and `tdecode()`
  47   * entry points disappearing from termcap.c.
  48   * 2BSD became a branch retaining support for non-virtual memory
  49   * systems (like the PDP-11) whereas most BSD development focused on
  50   * the VAX and other VM-enabled systems starting with 3BSD.
  51   * This man page previously located a termcap.h in 2BSD, but that may
  52   * be confusion arising from its backport to 2.9BSD (and still present
  53   * in surviving sources for 2.11BSD, the "end of the line" for that
  54   * branch's development).
  55   * Observe the copyright notice in
  56   *   https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD/usr/contrib/\
  57   *     jove/Makefile
  58   * --much too late for 2BSD (1979).
  59 -->
  60 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  61 <HTML>
  62 <HEAD>
  63 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  64 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  65 <TITLE>curs_termcap 3x 2023-12-17 ncurses 6.4 Library calls</TITLE>
  66 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  67
  68 </HEAD>
  69 <BODY>
  70 <H1 class="no-header">curs_termcap 3x 2023-12-17 ncurses 6.4 Library calls</H1>
  71 <PRE>
  72 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>                 Library calls                <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
  73
  74
  75
  76
  77 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  78        <STRONG>PC</STRONG>, <STRONG>UP</STRONG>, <STRONG>BC</STRONG>, <STRONG>ospeed</STRONG>, <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>, <STRONG>tgetstr</STRONG>, <STRONG>tgoto</STRONG>, <STRONG>tputs</STRONG> -
  79        <EM>curses</EM> emulation of <EM>termcap</EM>
  80
  81
  82 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  83        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  84        <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>
  85
  86        <STRONG>char</STRONG> <STRONG>PC;</STRONG>
  87        <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>UP;</STRONG>
  88        <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>BC;</STRONG>
  89        <STRONG>short</STRONG> <STRONG>ospeed;</STRONG>
  90
  91        <STRONG>int</STRONG> <STRONG>tgetent(char</STRONG> <STRONG>*</STRONG><EM>bp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>name</EM><STRONG>);</STRONG>
  92        <STRONG>int</STRONG> <STRONG>tgetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>id</EM><STRONG>);</STRONG>
  93        <STRONG>int</STRONG> <STRONG>tgetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>id</EM><STRONG>);</STRONG>
  94        <STRONG>char</STRONG> <STRONG>*tgetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>id</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>**</STRONG><EM>area</EM><STRONG>);</STRONG>
  95        <STRONG>char</STRONG> <STRONG>*tgoto(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>col</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>row</EM><STRONG>);</STRONG>
  96        <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
  97
  98
  99 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 100        <EM>ncurses</EM>  provides  the  foregoing  variables   and   functions   as   a
 101        compatibility layer for programs that use the <EM>termcap</EM> library.  The API
 102        is the same, but behavior is  emulated  using  the  <EM>terminfo</EM>  database.
 103        Thus,  it  can  be  used  only  to  query  the capabilities of terminal
 104        database entries for which a <EM>terminfo</EM> entry has been compiled.
 105
 106
 107 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
 108        <STRONG>tgetent</STRONG> loads the terminal database entry for <EM>name</EM>; see <STRONG><A HREF="term.7.html">term(7)</A></STRONG>.   This
 109        must be done before calling any of the other functions.  It returns:
 110
 111           1   on success,
 112
 113           0   if  there is no such entry (or if the matching entry describes a
 114               generic terminal,  having  too  little  information  for  <EM>curses</EM>
 115               applications to run), and
 116
 117           -1  if the <EM>terminfo</EM> database could not be found.
 118
 119        This implementation differs from those of historical <EM>termcap</EM> libraries.
 120
 121           <STRONG>o</STRONG>   <EM>ncurses</EM>  ignores  the  buffer  pointer  <EM>bp</EM>,  as do other <EM>termcap</EM>
 122               implementations conforming to  portions  of  X/Open  Curses  now
 123               withdrawn.   The  BSD  <EM>termcap</EM> library would store a copy of the
 124               terminal  type  description  in  the  area  referenced  by  this
 125               pointer.   <EM>ncurses</EM> stores terminal type descriptions in compiled
 126               form, which is not the same thing.
 127
 128           <STRONG>o</STRONG>   The meanings of the  return  values  differ.   The  BSD  <EM>termcap</EM>
 129               library  does not check whether the terminal type description is
 130               marked  with  the  <STRONG>gn</STRONG>  (<STRONG>generic</STRONG>)  capability,  nor  whether  the
 131               terminal  type  description  supports  an  addressable cursor, a
 132               property essential for any <EM>curses</EM> implementation to operate.
 133
 134
 135 </PRE><H3><a name="h3-Retrieving-Capability-Values">Retrieving Capability Values</a></H3><PRE>
 136        <STRONG>tgetflag</STRONG> reports the Boolean entry  for  <EM>id</EM>,  or  zero  if  it  is  not
 137        available.
 138
 139        <STRONG>tgetnum</STRONG> obtains the numeric entry for <EM>id</EM>, or -1 if it is not available.
 140
 141        <STRONG>tgetstr</STRONG>  returns  the  string  entry  for  <EM>id</EM>,  or  <STRONG>NULL</STRONG>  if  it is not
 142        available.   Use  <STRONG>tputs</STRONG>  to  output  the  string  returned.   The  <EM>area</EM>
 143        parameter is used as follows.
 144
 145           <STRONG>o</STRONG>   It is assumed to be the address of a pointer to a buffer managed
 146               by the calling application.
 147
 148           <STRONG>o</STRONG>   However, <EM>ncurses</EM> checks to ensure that <EM>area</EM>  is  not  <STRONG>NULL</STRONG>,  and
 149               also  that  the resulting buffer pointer is not <STRONG>NULL</STRONG>.  If either
 150               check fails, <EM>area</EM> is ignored.
 151
 152           <STRONG>o</STRONG>   If the checks succeed, <EM>ncurses</EM> also copies the return  value  to
 153               the  buffer  pointed to by <EM>area</EM>, and the library updates <EM>area</EM> to
 154               point past the null character terminating this value.
 155
 156           <STRONG>o</STRONG>   The return value itself is  an  address  in  the  terminal  type
 157               description loaded into memory.
 158
 159
 160 </PRE><H3><a name="h3-Applying-String-Capabilities">Applying String Capabilities</a></H3><PRE>
 161        String capabilities can be parameterized; see subsection "Parameterized
 162        Strings" in  <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.  <STRONG>tgoto</STRONG> applies its second and third arguments
 163        to  the  parametric  placeholders in the capability stored in the first
 164        argument.
 165
 166        <STRONG>o</STRONG>   The capability may contain padding specifications;  see  subsection
 167            "Delays  and  Padding"  of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.  The output of <STRONG>tgoto</STRONG> should
 168            thus be passed to <STRONG>tputs</STRONG> rather than some other output function such
 169            as <STRONG>printf(3)</STRONG>.
 170
 171        <STRONG>o</STRONG>   While  <STRONG>tgoto</STRONG>  is  assumed  to  be used for the two-parameter cursor
 172            positioning  capability,  <EM>termcap</EM>  applications  also  use  it  for
 173            single-parameter capabilities.
 174
 175            Doing  so  reveals  a  quirk  in <STRONG>tgoto</STRONG>: most hardware terminals use
 176            cursor addressing with <EM>row</EM> first, but the  original  developers  of
 177            the  <EM>termcap</EM>  interface  chose  to  put  the <EM>col</EM> (column) parameter
 178            first.  The <STRONG>tgoto</STRONG> function swaps the order of parameters.  It  does
 179            this  even  for  calls  requiring only a single parameter.  In that
 180            case, the first parameter is merely a placeholder.
 181
 182        <STRONG>o</STRONG>   Normally the <EM>ncurses</EM>  library  is  compiled  without  full  <EM>termcap</EM>
 183            support.  In that case, <STRONG>tgoto</STRONG> uses an internal version of <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>
 184            (a more capable function).
 185
 186            Because it uses <STRONG>tparm</STRONG> internally, <STRONG>tgoto</STRONG> is able to use  some  <EM>term-</EM>
 187            <EM>info</EM>  features, but not all.  In particular, it allows only numeric
 188            parameters; <STRONG>tparm</STRONG> supports string parameters.
 189
 190            However, <STRONG>tparm</STRONG> is not  a  <EM>termcap</EM>  feature,  and  portable  <EM>termcap</EM>
 191            applications should not rely upon its availability.
 192
 193        <STRONG>tputs</STRONG>  is described in <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>.  It can retrieve capabilities
 194        by either <EM>termcap</EM> or <EM>terminfo</EM> name.
 195
 196
 197 </PRE><H3><a name="h3-Global-Variables">Global Variables</a></H3><PRE>
 198        The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the <EM>terminfo</EM>  entry's
 199        data for <STRONG>pad_char</STRONG>, <STRONG>cursor_up</STRONG> and <STRONG>backspace_if_not_bs</STRONG>, respectively.  <STRONG>UP</STRONG>
 200        is not used by <EM>ncurses</EM>.  <STRONG>PC</STRONG> is used by <STRONG><A HREF="curs_util.3x.html">delay_output(3x)</A></STRONG>.  <STRONG>BC</STRONG> is used by
 201        <STRONG>tgoto</STRONG> emulation.  The variable <STRONG>ospeed</STRONG> is set by <EM>ncurses</EM> using a system-
 202        specific encoding to indicate the terminal's data rate.
 203
 204
 205 </PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE>
 206        The <EM>termcap</EM> functions provide  no  means  of  freeing  memory,  because
 207        legacy  <EM>termcap</EM>  implementations used only the buffer areas provided by
 208        the caller via <STRONG>tgetent</STRONG> and <STRONG>tgetstr</STRONG>.  Those buffers are unused in  <EM>term-</EM>
 209        <EM>info</EM>.
 210
 211        By  contrast,  <EM>terminfo</EM>  allocates  memory.   It  uses <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to
 212        obtain the data  used  by  <STRONG>tgetent</STRONG>  and  the  functions  that  retrieve
 213        capability values.  One could use
 214               del_curterm(cur_term);
 215        to  free  this  memory,  but  there  is an additional complication with
 216        <EM>ncurses</EM>.  It uses a fixed-size pool of storage locations, one per value
 217        of the <EM>TERM</EM> environment variable when <STRONG>tgetent</STRONG> is called.  The <STRONG>screen(1)</STRONG>
 218        program relies upon this arrangement to improve its performance.
 219
 220        An application that uses only the <EM>termcap</EM>  functions,  not  the  higher
 221        level  <EM>curses</EM>  API,  could  release  the  memory using <STRONG><A HREF="curs_terminfo.3x.html">del_curterm(3x)</A></STRONG>,
 222        because the pool is freed using other functions; see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>.
 223
 224
 225 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 226        The return values of  <STRONG>tgetent</STRONG>,  <STRONG>tgetflag</STRONG>,  <STRONG>tgetname</STRONG>,  and  <STRONG>tgetstr</STRONG>  are
 227        documented above.
 228
 229        <STRONG>tgoto</STRONG> returns <STRONG>NULL</STRONG> on error.  Error conditions include:
 230
 231        <STRONG>o</STRONG>   uninitialized state (<STRONG>tgetent</STRONG> was not called successfully),
 232
 233        <STRONG>o</STRONG>   <EM>cap</EM> being a null pointer,
 234
 235        <STRONG>o</STRONG>   <EM>cap</EM> referring to a canceled capability,
 236
 237        <STRONG>o</STRONG>   <EM>cap</EM>  being  a  capability  with  string-valued  parameters (a <EM>term-</EM>
 238            <EM>info</EM>-only feature), and
 239
 240        <STRONG>o</STRONG>   <EM>cap</EM> being a capability with more than two parameters.
 241
 242        See <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> regarding <STRONG>tputs</STRONG>.
 243
 244
 245 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 246        <EM>ncurses</EM> compares only the first two characters of the <EM>id</EM>  parameter  of
 247        <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>, and <STRONG>tgetstr</STRONG> to the capability names in the database.
 248
 249
 250 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 251        These  functions  are  no  longer standardized (and the variables never
 252        were); <EM>ncurses</EM> provides them  to  support  legacy  applications.   They
 253        should not be used in new programs.
 254
 255
 256 </PRE><H3><a name="h3-Standards">Standards</a></H3><PRE>
 257        <STRONG>o</STRONG>   X/Open   Curses,   Issue  4,  Version  2  (1996),  describes  these
 258            functions.  However, they are marked "TO BE WITHDRAWN".
 259
 260        <STRONG>o</STRONG>   X/Open Curses, Issue 7 (2009) marked the <EM>termcap</EM>  interface  (along
 261            with <STRONG>vwprintw</STRONG> and <STRONG>vwscanw</STRONG>) as withdrawn.
 262
 263        Neither  X/Open  Curses  nor  the  SVr4 man pages documented the return
 264        values of <STRONG>tgetent</STRONG> correctly, though all three  were  in  fact  returned
 265        ever  since  SVr1.   In  particular,  an  omission in the X/Open Curses
 266        specification has been misinterpreted to mean that <STRONG>tgetent</STRONG>  returns  <STRONG>OK</STRONG>
 267        or  <STRONG>ERR</STRONG>.   Because  the  purpose  of  these  functions  is  to  provide
 268        compatibility with the <EM>termcap</EM> library, that  is  a  defect  in  X/Open
 269        Curses, Issue 4, Version 2 rather than in <EM>ncurses</EM>.
 270
 271    <STRONG>Compatibility</STRONG> <STRONG>with</STRONG> <STRONG>BSD</STRONG> <EM>termcap</EM>
 272        Externally  visible  variables  are  provided  for  support  of certain
 273        <EM>termcap</EM>  applications.   However,  their  correct   usage   is   poorly
 274        documented; for example, it is unclear when reading and writing them is
 275        meaningful.  In particular, some applications are reported  to  declare
 276        and/or modify <STRONG>ospeed</STRONG>.
 277
 278        The  constraint  that only the first two characters of the <EM>id</EM> parameter
 279        are used escapes many application developers.  The BSD <EM>termcap</EM>  library
 280        did  not require a trailing null character on the capability identifier
 281        passed to <STRONG>tgetstr</STRONG>,  <STRONG>tgetnum</STRONG>,  and  <STRONG>tgetflag</STRONG>.   Some  applications  thus
 282        assume  that  the  <EM>termcap</EM> interface does not require the trailing null
 283        character for the capability identifier.
 284
 285        <STRONG>o</STRONG>   <EM>ncurses</EM> disallows matches by the <EM>termcap</EM> interface against extended
 286            capability   names   that  are  longer  than  two  characters;  see
 287            <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>.
 288
 289        The BSD <EM>termcap</EM> function <STRONG>tgetent</STRONG> returns the text of a <EM>termcap</EM> entry in
 290        the  buffer  passed  as an argument.  This library, like other <EM>terminfo</EM>
 291        implementations, does not store terminal type descriptions as text.  It
 292        sets the buffer contents to a null-terminated string.
 293
 294
 295 </PRE><H3><a name="h3-Header-File">Header File</a></H3><PRE>
 296        This  library  includes a <EM>termcap.h</EM> header for compatibility with other
 297        implementations, but the  header  is  rarely  used  because  the  other
 298        implementations are not strictly compatible.
 299
 300
 301 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 302        Bill  Joy  originated  a  forerunner  of <EM>termcap</EM> called "ttycap", dated
 303        September 1977, and released in 1BSD (March 1978).  It used many of the
 304        same  function  names  as the later <EM>termcap</EM>, such as <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>,
 305        <STRONG>tgetnum</STRONG>, and <STRONG>tgetstr</STRONG>.
 306
 307        A clear descendant, the <EM>termlib</EM> library, followed in 2BSD  (May  1979),
 308        adding <STRONG>tgoto</STRONG> and <STRONG>tputs</STRONG>.  The former applied at that time only to cursor
 309        positioning  capabilities,  thus  the  overly  specific  name.   Little
 310        changed  in 3BSD (late 1979) except the addition of test programs and a
 311        <EM>termlib</EM> man page, which documented the API shown in section  "SYNOPSIS"
 312        above.
 313
 314        4BSD  (November 1980) renamed <EM>termlib</EM> to <EM>termcap</EM> and added another test
 315        program.  The library remained much the same though 4.3BSD (June 1986).
 316        4.4BSD-Lite (June 1994) refactored it but left the API unchanged.
 317
 318        Function  prototypes  were  a feature of the forthcoming ANSI C (1989).
 319        Thus the library provided no header file declaring them.  Nevertheless,
 320        the  BSD  sources  included  two  different <EM>termcap.h</EM> header files over
 321        time.
 322
 323        <STRONG>o</STRONG>   One was used internally by <STRONG>jove(1)</STRONG> from 4.3BSD onward.  It delcared
 324            global symbols for the <EM>termcap</EM> variables that it used.
 325
 326        <STRONG>o</STRONG>   The  other appeared in 4.4BSD-Lite Release 2 (June 1995) as part of
 327            <EM>libedit</EM> (also known as the <EM>editline</EM> library).  CSRG source  history
 328            shows that this was added in mid-1992.  The <EM>libedit</EM> header file was
 329            used  internally  as  a  convenience  for  compiling  the  <EM>editline</EM>
 330            library.  It declared function prototypes, but no global variables.
 331            This header file was added to NetBSD's <EM>termcap</EM> library in mid-1994.
 332
 333        Meanwhile, GNU <EM>termcap</EM> began development in 1990.   Its  first  release
 334        (1.0)  in  1991  included  a  <EM>termcap.h</EM>  header.   Its  second (1.1) in
 335        September 1992 modified the  header  to  use  <EM>const</EM>  for  the  function
 336        prototypes  in  the  header where one would expect the parameters to be
 337        read-only.   BSD  <EM>termcap</EM>  did  not.   The  prototype  for  <STRONG>tputs</STRONG>  also
 338        differed,  but  in that instance, it was <EM>libedit</EM> that differed from BSD
 339        <EM>termcap</EM>.
 340
 341        GNU <EM>termcap</EM> 1.3 was bundled  with  <EM>bash</EM>  in  mid-1993  to  support  the
 342        <STRONG>readline(3)</STRONG> library.
 343
 344        <EM>ncurses</EM>  1.8.1 (November 1993) provided a <EM>termcap.h</EM> file.  It reflected
 345        influence  from  GNU  <EM>termcap</EM>  and  <STRONG>emacs(1)</STRONG>  (rather  than   <STRONG>jove(1)</STRONG>),
 346        providing the following interface:
 347
 348        <STRONG>o</STRONG>   global symbols used by <EM>emacs</EM>,
 349
 350        <STRONG>o</STRONG>   <EM>const</EM>-qualified function prototypes, and
 351
 352        <STRONG>o</STRONG>   a prototype for <STRONG>tparam</STRONG>, a GNU <EM>termcap</EM> feature.
 353
 354        Later  (in mid-1996) the <STRONG>tparam</STRONG> function was removed from <EM>ncurses</EM>.  Any
 355        two of the four implementations thus differ, and programs  that  intend
 356        to work with all <EM>termcap</EM> library interfaces must account for that fact.
 357
 358
 359 </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
 360        If  you  call  <STRONG>tgetstr</STRONG>  to  fetch  <STRONG>ca</STRONG> or any other parameterized string
 361        capability, be aware that it is returned in <EM>terminfo</EM> notation, not  the
 362        older  and  not-quite-compatible <EM>termcap</EM> notation.  This does not cause
 363        problems if all you do with it is  call  <STRONG>tgoto</STRONG>  or  <STRONG>tparm</STRONG>,  which  both
 364        expand  <EM>terminfo</EM>-style  strings  as  <EM>terminfo</EM>  does.   (If  <EM>ncurses</EM>  is
 365        configured to support <EM>termcap,</EM> <STRONG>tgoto</STRONG> checks whether the string is <EM>term-</EM>
 366        <EM>info</EM>-style  by  looking  for  "<STRONG>%p</STRONG>"  parameters  or  "<STRONG>&lt;</STRONG>...<STRONG>&gt;</STRONG>" delays, and
 367        invokes a <EM>termcap</EM>-style parser if the string appears not to  use  <EM>term-</EM>
 368        <EM>info</EM> syntax.)
 369
 370        Because  <EM>terminfo</EM>'s  syntax  for padding in string capabilities differs
 371        from <EM>termcap</EM>'s, users can be surprised.
 372
 373        <STRONG>o</STRONG>   <STRONG>tputs("50")</STRONG> in a <EM>terminfo</EM> system transmits "50" rather  than  busy-
 374            waiting for 50 milliseconds.
 375
 376        <STRONG>o</STRONG>   However,  if  <EM>ncurses</EM> is configured to support <EM>termcap</EM>, it may also
 377            have been configured to support BSD-style padding.
 378
 379            In that case, <STRONG>tputs</STRONG> inspects strings  passed  to  it,  looking  for
 380            digits at the beginning of the string.
 381
 382            <STRONG>tputs("50")</STRONG>  in  a <EM>termcap</EM> system may busy-wait for 50 milliseconds
 383            rather than transmitting "50".
 384
 385        <EM>termcap</EM>  has  nothing  analogous  to  <EM>terminfo</EM>'s   <STRONG>sgr</STRONG>   string.    One
 386        consequence  is  that <EM>termcap</EM> applications assume that "<STRONG>me</STRONG>" (equivalent
 387        to <EM>terminfo</EM>'s <STRONG>sgr0</STRONG> capability) does not reset the  alternate  character
 388        set.   <EM>ncurses</EM>  checks  for,  and  modifies  the  data shared with, the
 389        <EM>termcap</EM> interface  to  accommodate  the  latter's  limitation  in  this
 390        respect.
 391
 392
 393 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 394        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
 395
 396        https://invisible-island.net/ncurses/tctest.html
 397
 398
 399
 400 ncurses 6.4                       2023-12-17                  <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
 401 </PRE>
 402 <div class="nav">
 403 <ul>
 404 <li><a href="#h2-NAME">NAME</a></li>
 405 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 406 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 407 <ul>
 408 <li><a href="#h3-Initialization">Initialization</a></li>
 409 <li><a href="#h3-Retrieving-Capability-Values">Retrieving Capability Values</a></li>
 410 <li><a href="#h3-Applying-String-Capabilities">Applying String Capabilities</a></li>
 411 <li><a href="#h3-Global-Variables">Global Variables</a></li>
 412 <li><a href="#h3-Releasing-Memory">Releasing Memory</a></li>
 413 </ul>
 414 </li>
 415 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 416 <li><a href="#h2-NOTES">NOTES</a></li>
 417 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 418 <ul>
 419 <li><a href="#h3-Standards">Standards</a></li>
 420 <li><a href="#h3-Header-File">Header File</a></li>
 421 </ul>
 422 </li>
 423 <li><a href="#h2-HISTORY">HISTORY</a></li>
 424 <li><a href="#h2-BUGS">BUGS</a></li>
 425 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 426 </ul>
 427 </div>
 428 </BODY>
 429 </HTML>