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.80 2023/12/23 20:19:05 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 (such as 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-23 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-23 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
 130               includes the <STRONG>generic</STRONG> (<STRONG>gn</STRONG>) capability, nor whether  the  terminal
 131               type  description  supports  an  addressable  cursor, a property
 132               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 its  parameters.   It
 179            does  this  even  for  calls requiring only a single parameter.  In
 180            that 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> code.
 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 terminal name parameter given to <STRONG>tgetent</STRONG>.  The <STRONG>screen(1)</STRONG> program
 218        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, marking them as "TO BE WITHDRAWN".
 259
 260        <STRONG>o</STRONG>   X/Open Curses, Issue 7 (2009) marks 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 shown here were  in  fact
 265        returned  ever  since  SVr1.   In particular, an omission in the X/Open
 266        Curses specification has  been  misinterpreted  to  mean  that  <STRONG>tgetent</STRONG>
 267        returns  <STRONG>OK</STRONG>  or  <STRONG>ERR</STRONG>.   Because  the  purpose  of these functions is to
 268        provide compatibility with the <EM>termcap</EM> library, that  is  a  defect  in
 269        X/Open 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, leaving the API unchanged.
 317
 318        Function  prototypes were a feature of ANSI C (1989).  Thus the library
 319        itself provided no header file declaring them.  Nevertheless,  the  BSD
 320        sources included two different <EM>termcap.h</EM> header files over time.
 321
 322        <STRONG>o</STRONG>   One was used internally by <STRONG>jove(1)</STRONG> from 4.3BSD onward.  It delcared
 323            global symbols for the <EM>termcap</EM> variables that it used.
 324
 325        <STRONG>o</STRONG>   The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part  of
 326            <EM>libedit</EM>  (also known as the <EM>editline</EM> library).  CSRG source history
 327            shows that this was added in mid-1992.  The <EM>libedit</EM> header file was
 328            used  internally  as  a  convenience  for  compiling  the  <EM>editline</EM>
 329            library.  It declared function prototypes, but no global variables.
 330            This header file was added to NetBSD's <EM>termcap</EM> library in mid-1994.
 331
 332        Meanwhile,  GNU  <EM>termcap</EM>  began development in 1990.  Its first release
 333        (1.0) in 1991  included  a  <EM>termcap.h</EM>  header.   Its  second  (1.1)  in
 334        September  1992  modified  the  header  to  use  <EM>const</EM> for the function
 335        prototypes in the header where one would expect the  parameters  to  be
 336        read-only.   BSD  <EM>termcap</EM>  did  not.   The  prototype  for  <STRONG>tputs</STRONG>  also
 337        differed, but in that instance, it was <EM>libedit</EM> that differed  from  BSD
 338        <EM>termcap</EM>.
 339
 340        GNU  <EM>termcap</EM>  1.3  was  bundled with <STRONG>bash(1)</STRONG> in mid-1993 to support the
 341        <STRONG>readline(3)</STRONG> library.
 342
 343        <EM>ncurses</EM> 1.8.1 (November 1993) provided a <EM>termcap.h</EM> file.  It  reflected
 344        influence   from  GNU  <EM>termcap</EM>  and  <STRONG>emacs(1)</STRONG>  (rather  than  <STRONG>jove(1)</STRONG>),
 345        providing the following interface:
 346
 347        <STRONG>o</STRONG>   global symbols used by <EM>emacs</EM>,
 348
 349        <STRONG>o</STRONG>   <EM>const</EM>-qualified function prototypes, and
 350
 351        <STRONG>o</STRONG>   a prototype for <STRONG>tparam</STRONG>, a GNU <EM>termcap</EM> feature.
 352
 353        Later (in mid-1996) the <STRONG>tparam</STRONG> function was removed from <EM>ncurses</EM>.   Any
 354        two  of  the four implementations thus differ, and programs that intend
 355        to work with all <EM>termcap</EM> library interfaces must account for that fact.
 356
 357
 358 </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
 359        If  you  call  <STRONG>tgetstr</STRONG>  to  fetch  <STRONG>column_address</STRONG>  (<STRONG>ch</STRONG>)  or  any  other
 360        parameterized  string capability, be aware that it is returned in <EM>term-</EM>
 361        <EM>info</EM> notation, not the older and not-quite-compatible <EM>termcap</EM> notation.
 362        This  does  not  cause  problems if all you do with it is call <STRONG>tgoto</STRONG> or
 363        <STRONG>tparm</STRONG>, which both expand <EM>terminfo</EM>-style strings as <EM>terminfo</EM> does.   (If
 364        <EM>ncurses</EM>  is  configured  to  support  <EM>termcap,</EM> <STRONG>tgoto</STRONG> checks whether the
 365        string is <EM>terminfo</EM>-style by looking  for  "<STRONG>%p</STRONG>"  parameters  or  "<STRONG>&lt;</STRONG>...<STRONG>&gt;</STRONG>"
 366        delays, and invokes a <EM>termcap</EM>-style parser if the string appears not to
 367        use <EM>terminfo</EM> syntax.)
 368
 369        Because <EM>terminfo</EM>'s syntax for padding in  string  capabilities  differs
 370        from <EM>termcap</EM>'s, users can be surprised.
 371
 372        <STRONG>o</STRONG>   <STRONG>tputs("50")</STRONG>  in  a <EM>terminfo</EM> system transmits "50" rather than busy-
 373            waiting for 50 milliseconds.
 374
 375        <STRONG>o</STRONG>   However, if <EM>ncurses</EM> is configured to support <EM>termcap</EM>, it  may  also
 376            have been configured to support BSD-style padding.
 377
 378            In  that  case,  <STRONG>tputs</STRONG>  inspects  strings passed to it, looking for
 379            digits at the beginning of the string.
 380
 381            <STRONG>tputs("50")</STRONG> in a <EM>termcap</EM> system may busy-wait for  50  milliseconds
 382            rather than transmitting "50".
 383
 384        <EM>termcap</EM>  has  nothing  analogous  to  <EM>terminfo</EM>'s  <STRONG>set_attributes</STRONG>  (<STRONG>sgr</STRONG>)
 385        capability.  One consequence is that <EM>termcap</EM> applications  assume  that
 386        "<STRONG>me</STRONG>"  (equivalent  to <EM>terminfo</EM>'s <STRONG>exit_attribute_mode</STRONG> (<STRONG>sgr0</STRONG>) capability)
 387        does not reset the alternate character set.  <EM>ncurses</EM>  checks  for,  and
 388        modifies the data shared with, the <EM>termcap</EM> interface to accommodate the
 389        latter's limitation in this respect.
 390
 391
 392 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 393        <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>
 394
 395        https://invisible-island.net/ncurses/tctest.html
 396
 397
 398
 399 ncurses 6.4                       2023-12-23                  <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
 400 </PRE>
 401 <div class="nav">
 402 <ul>
 403 <li><a href="#h2-NAME">NAME</a></li>
 404 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 405 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 406 <ul>
 407 <li><a href="#h3-Initialization">Initialization</a></li>
 408 <li><a href="#h3-Retrieving-Capability-Values">Retrieving Capability Values</a></li>
 409 <li><a href="#h3-Applying-String-Capabilities">Applying String Capabilities</a></li>
 410 <li><a href="#h3-Global-Variables">Global Variables</a></li>
 411 <li><a href="#h3-Releasing-Memory">Releasing Memory</a></li>
 412 </ul>
 413 </li>
 414 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 415 <li><a href="#h2-NOTES">NOTES</a></li>
 416 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
 417 <ul>
 418 <li><a href="#h3-Standards">Standards</a></li>
 419 <li><a href="#h3-Header-File">Header File</a></li>
 420 </ul>
 421 </li>
 422 <li><a href="#h2-HISTORY">HISTORY</a></li>
 423 <li><a href="#h2-BUGS">BUGS</a></li>
 424 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 425 </ul>
 426 </div>
 427 </BODY>
 428 </HTML>