]> ncurses.scripts.mit.edu Git - ncurses.git/blob - doc/html/man/curs_termcap.3x.html
32699b3c48124e988b2c43782276f74236236c0f
[ncurses.git] / 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.57 2023/04/08 21:43:01 tom Exp @
31 -->
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
33 <HTML>
34 <HEAD>
35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
37 <TITLE>curs_termcap 3x</TITLE>
38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
39
40 </HEAD>
41 <BODY>
42 <H1 class="no-header">curs_termcap 3x</H1>
43 <PRE>
44 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>                                              <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
45
46
47
48
49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
50        <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> -
51        <STRONG>curses</STRONG> emulation of termcap
52
53
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
56        <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>
57
58        <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>PC;</STRONG>
59        <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>UP;</STRONG>
60        <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>BC;</STRONG>
61        <STRONG>extern</STRONG> <STRONG>short</STRONG> <STRONG>ospeed;</STRONG>
62
63        <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>
64        <STRONG>int</STRONG> <STRONG>tgetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>id</EM><STRONG>);</STRONG>
65        <STRONG>int</STRONG> <STRONG>tgetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>id</EM><STRONG>);</STRONG>
66        <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>
67        <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>
68        <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>
69
70
71 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
72        These routines are included as a conversion aid for programs  that  use
73        the  <EM>termcap</EM>  library.  Their parameters are the same, but the routines
74        are emulated using the <EM>terminfo</EM> database.  Thus, they can only be  used
75        to  query  the  capabilities  of entries for which a terminfo entry has
76        been compiled.
77
78
79 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
80        The <STRONG>tgetent</STRONG> routine loads the entry for <EM>name</EM>.  It returns:
81
82           1  on success,
83
84           0  if there is no such entry (or that it is a generic  type,  having
85              too little information for curses applications to run), and
86
87           -1 if the terminfo database could not be found.
88
89        This differs from the <EM>termcap</EM> library in two ways:
90
91           <STRONG>o</STRONG>   The  emulation  ignores  the buffer pointer <EM>bp</EM>.  The <EM>termcap</EM> li-
92               brary would store a copy of the terminal description in the area
93               referenced  by this pointer.  However, ncurses stores its termi-
94               nal descriptions in compiled binary form, which is not the  same
95               thing.
96
97           <STRONG>o</STRONG>   There is a difference in return codes.  The <EM>termcap</EM> library does
98               not check if the terminal description is marked with the <EM>generic</EM>
99               capability,  or  if the terminal description has cursor-address-
100               ing.
101
102
103 </PRE><H3><a name="h3-Capability-Values">Capability Values</a></H3><PRE>
104        The <STRONG>tgetflag</STRONG> routine gets the boolean entry for <EM>id</EM>, or zero  if  it  is
105        not available.
106
107        The  <STRONG>tgetnum</STRONG>  routine gets the numeric entry for <EM>id</EM>, or -1 if it is not
108        available.
109
110        The <STRONG>tgetstr</STRONG> routine returns the string entry for <EM>id</EM>, or zero if  it  is
111        not  available.  Use <STRONG>tputs</STRONG> to output the returned string.  The <EM>area</EM> pa-
112        rameter is used as follows:
113
114           <STRONG>o</STRONG>   It is assumed to be the address of a pointer to a buffer managed
115               by the calling application.
116
117           <STRONG>o</STRONG>   However, ncurses checks to ensure that <STRONG>area</STRONG> is not NULL, and al-
118               so that the resulting buffer pointer is  not  NULL.   If  either
119               check fails, the <EM>area</EM> parameter is ignored.
120
121           <STRONG>o</STRONG>   If  the  checks succeed, ncurses also copies the return value to
122               the buffer pointed to by <EM>area</EM>, and the <EM>area</EM> value will be updat-
123               ed to point past the null ending this value.
124
125           <STRONG>o</STRONG>   The  return  value itself is an address in the terminal descrip-
126               tion which is loaded into memory.
127
128        Only the first two characters of the <STRONG>id</STRONG> parameter of <STRONG>tgetflag</STRONG>,  <STRONG>tgetnum</STRONG>
129        and <STRONG>tgetstr</STRONG> are compared in lookups.
130
131
132 </PRE><H3><a name="h3-Formatting-Capabilities">Formatting Capabilities</a></H3><PRE>
133        The <STRONG>tgoto</STRONG> routine expands the given capability using the parameters.
134
135        <STRONG>o</STRONG>   Because  the  capability may have padding characters, the output of
136            <STRONG>tgoto</STRONG> should be passed to <STRONG>tputs</STRONG> rather than some other output func-
137            tion such as <STRONG>printf(3)</STRONG>.
138
139        <STRONG>o</STRONG>   While  <STRONG>tgoto</STRONG> is assumed to be used for the two-parameter cursor po-
140            sitioning capability, termcap applications also use it for  single-
141            parameter capabilities.
142
143            Doing this shows a quirk in <STRONG>tgoto</STRONG>: most hardware terminals use cur-
144            sor addressing with <EM>row</EM> first, but the original developers  of  the
145            termcap  interface  chose  to  put the <EM>column</EM> parameter first.  The
146            <STRONG>tgoto</STRONG> function swaps the order of parameters.  It  does  this  also
147            for  calls  requiring  only  a single parameter.  In that case, the
148            first parameter is merely a placeholder.
149
150        <STRONG>o</STRONG>   Normally the ncurses library is compiled with terminfo support.  In
151            that  case, <STRONG>tgoto</STRONG> uses an internal version of <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> (a more ca-
152            pable formatter).
153
154            With terminfo support, <STRONG>tgoto</STRONG> is able to use some  of  the  terminfo
155            features,  but  not all.  In particular, it allows only numeric pa-
156            rameters; <STRONG>tparm</STRONG> supports string parameters.
157
158            However, <STRONG>tparm</STRONG> is not a <EM>termcap</EM> feature, and portable  <EM>termcap</EM>  ap-
159            plications should not rely upon its availability.
160
161        The  <STRONG>tputs</STRONG>  routine  is described on the <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> manual page.
162        It can retrieve capabilities by either termcap or terminfo name.
163
164
165 </PRE><H3><a name="h3-Global-Variables">Global Variables</a></H3><PRE>
166        The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the terminfo  entry's
167        data for <STRONG>pad_char</STRONG>, <STRONG>cursor_up</STRONG> and <STRONG>backspace_if_not_bs</STRONG>, respectively.  <STRONG>UP</STRONG>
168        is not used by ncurses.  <STRONG>PC</STRONG> is used in the <STRONG>tdelay_output</STRONG> function.   <STRONG>BC</STRONG>
169        is  used in the <STRONG>tgoto</STRONG> emulation.  The variable <STRONG>ospeed</STRONG> is set by ncurses
170        in a system-specific coding to reflect the terminal speed.
171
172
173 </PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE>
174        The termcap functions provide no  means  for  freeing  memory,  because
175        legacy  termcap  implementations used only the buffer areas provided by
176        the caller via <STRONG>tgetent</STRONG> and <STRONG>tgetstr</STRONG>.  Those buffers are unused  in  ter-
177        minfo.
178
179        On the other hand, terminfo allocates memory.  It uses <STRONG>setupterm</STRONG> to re-
180        trieve the data used by <STRONG>tgetent</STRONG> and the functions which return capabil-
181        ity values such as <STRONG>tgetstr</STRONG>.  One could use
182
183             <STRONG>del_curterm(cur_term);</STRONG>
184
185
186        to  free  this  memory,  but  there  is an additional complication with
187        ncurses.  It uses a fixed-size <EM>pool</EM> of storage locations, one per  set-
188        ting  of  the <STRONG>TERM</STRONG> variable when <STRONG>tgetent</STRONG> is called.  The <STRONG>screen(1)</STRONG> pro-
189        gram relies upon this arrangement, to improve its performance.
190
191        An application which uses only the low-level  termcap  functions  could
192        free the memory using <STRONG>del_curterm</STRONG>, because the pool is freed using oth-
193        er functions (see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>).
194
195
196 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
197        Except where explicitly noted, routines that return an  integer  return
198        <STRONG>ERR</STRONG>  upon  failure  and <STRONG>OK</STRONG> (SVr4 only specifies "an integer value other
199        than <STRONG>ERR</STRONG>") upon successful completion.
200
201        Routines that return pointers return <STRONG>NULL</STRONG> on error.
202
203        A few special cases apply:
204
205        <STRONG>o</STRONG>   If the terminal database has not been initialized, these return  an
206            error.
207
208        <STRONG>o</STRONG>   The  calls  with  a  string  parameter  (<STRONG>tgoto</STRONG>, <STRONG>tputs</STRONG>) check if the
209            string is null, or cancelled.  Those return an error.
210
211        <STRONG>o</STRONG>   A call to <STRONG>tgoto</STRONG> using a capability with string parameters is an er-
212            ror.
213
214        <STRONG>o</STRONG>   A call to <STRONG>tgoto</STRONG> using a capability with no parameters, or more than
215            two is an error.
216
217
218 </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
219        If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>ca</STRONG> or any other parameterized  string,  be
220        aware  that it will be returned in terminfo notation, not the older and
221        not-quite-compatible termcap notation.  This will not cause problems if
222        all  you do with it is call <STRONG>tgoto</STRONG> or <STRONG>tparm</STRONG>, which both expand terminfo-
223        style strings as terminfo.  (The <STRONG>tgoto</STRONG> function, if configured to  sup-
224        port  termcap,  will  check  if  the string is indeed terminfo-style by
225        looking for "%p" parameters or "$&lt;..&gt;" delays, and  invoke  a  termcap-
226        style parser if the string does not appear to be terminfo).
227
228        Because  terminfo  conventions for representing padding in string capa-
229        bilities differ from termcap's, users can be surprised:
230
231        <STRONG>o</STRONG>   <STRONG>tputs("50")</STRONG> in a terminfo system will put out a literal "50" rather
232            than busy-waiting for 50 milliseconds.
233
234        <STRONG>o</STRONG>   However,  if  ncurses is configured to support termcap, it may also
235            have been configured to support the BSD-style padding.
236
237            In that case, <STRONG>tputs</STRONG> inspects strings passed to it, looking for dig-
238            its at the beginning of the string.
239
240            <STRONG>tputs("50")</STRONG> in a termcap system may wait for 50 milliseconds rather
241            than put out a literal "50"
242
243        Note that termcap has nothing analogous to terminfo's <STRONG>sgr</STRONG> string.   One
244        consequence  of  this  is that termcap applications assume <STRONG>me</STRONG> (terminfo
245        <STRONG>sgr0</STRONG>) does not reset the alternate character set.  This  implementation
246        checks for, and modifies the data shown to the termcap interface to ac-
247        commodate termcap's limitation in this respect.
248
249
250 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
251
252 </PRE><H3><a name="h3-Standards">Standards</a></H3><PRE>
253        These functions are provided for supporting  legacy  applications,  and
254        should not be used in new programs:
255
256        <STRONG>o</STRONG>   The XSI Curses standard, Issue 4 describes these functions.  Howev-
257            er, they are marked TO BE WITHDRAWN and may be  removed  in  future
258            versions.
259
260        <STRONG>o</STRONG>   X/Open Curses, Issue 5 (December 2007) marked the termcap interface
261            (along with <STRONG>vwprintw</STRONG> and <STRONG>vwscanw</STRONG>) as withdrawn.
262
263        Neither the XSI Curses standard nor the SVr4 man pages  documented  the
264        return  values  of <STRONG>tgetent</STRONG> correctly, though all three were in fact re-
265        turned ever since SVr1.  In particular, an omission in the  XSI  Curses
266        documentation  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  compati-
268        bility  with the <EM>termcap</EM> library, that is a defect in XCurses, Issue 4,
269        Version 2 rather than in ncurses.
270
271
272 </PRE><H3><a name="h3-Compatibility-with-BSD-Termcap">Compatibility with BSD Termcap</a></H3><PRE>
273        External variables are provided for support of certain termcap applica-
274        tions.  However, termcap applications' use of those variables is poorly
275        documented, e.g., not distinguishing between input and output.  In par-
276        ticular,  some  applications  are reported to declare and/or modify <STRONG>os-</STRONG>
277        <STRONG>peed</STRONG>.
278
279        The comment that only the first two characters of the <STRONG>id</STRONG> parameter  are
280        used escapes many application developers.  The original BSD 4.2 termcap
281        library (and historical relics thereof) did not require a trailing null
282        NUL  on  the  parameter  name  passed to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetflag</STRONG>.
283        Some applications assume that the termcap interface  does  not  require
284        the trailing NUL for the parameter name.  Taking into account these is-
285        sues:
286
287        <STRONG>o</STRONG>   As a special case,  <STRONG>tgetflag</STRONG>  matched  against  a  single-character
288            identifier  provided  that  was at the end of the terminal descrip-
289            tion.  You should not rely upon this behavior in portable programs.
290            This  implementation disallows matches against single-character ca-
291            pability names.
292
293        <STRONG>o</STRONG>   This implementation disallows  matches  by  the  termcap  interface
294            against extended capability names which are longer than two charac-
295            ters.
296
297        The BSD termcap function <STRONG>tgetent</STRONG> returns the text of a termcap entry in
298        the  buffer  passed  as an argument.  This library (like other terminfo
299        implementations) does not store terminal descriptions as text.  It sets
300        the buffer contents to a null-terminated string.
301
302
303 </PRE><H3><a name="h3-Other-Compatibility">Other Compatibility</a></H3><PRE>
304        This  library includes a termcap.h header, for compatibility with other
305        implementations.  But the header is rarely used because the  other  im-
306        plementations are not strictly compatible.
307
308        The original BSD termcap (through 4.3BSD) had no header file which gave
309        function prototypes, because that was a feature of ANSI C.  BSD termcap
310        was  written  several  years before C was standardized.  However, there
311        were two different termcap.h header files in the BSD sources:
312
313        <STRONG>o</STRONG>   One was used internally by the <STRONG>jove</STRONG> editor in 2BSD through  4.4BSD.
314            It defined global symbols for the termcap variables which it used.
315
316        <STRONG>o</STRONG>   The  other  appeared in 4.4BSD Lite Release 2 (mid-1993) as part of
317            <EM>libedit</EM> (also known as the <EM>editline</EM> library).  The CSRG source his-
318            tory  shows  that  this  was added in mid-1992.  The <EM>libedit</EM> header
319            file was used internally, as a convenience for compiling the  <EM>edit-</EM>
320            <EM>line</EM> library.  It declared function prototypes, but no global vari-
321            ables.
322
323        The header file from <EM>libedit</EM> was added to NetBSD's termcap  library  in
324        mid-1994.
325
326        Meanwhile,  GNU  termcap  was under development, starting in 1990.  The
327        first release (termcap 1.0) in 1991 included a termcap.h  header.   The
328        second  release  (termcap 1.1) in September 1992 modified the header to
329        use <STRONG>const</STRONG> for the function prototypes in the header where one would ex-
330        pect  the parameters to be read-only.  This was a difference versus the
331        original BSD termcap.  The prototype for <STRONG>tputs</STRONG> also  differed,  but  in
332        that instance, it was <EM>libedit</EM> which differed from BSD termcap.
333
334        A copy of GNU termcap 1.3 was bundled with <EM>bash</EM> in mid-1993, to support
335        the <STRONG>readline(3)</STRONG> library.
336
337        A termcap.h file was provided in ncurses 1.8.1 (November  1993).   That
338        reflected influence by <STRONG>emacs(1)</STRONG> (rather than <STRONG>jove(1)</STRONG>) and GNU termcap:
339
340        <STRONG>o</STRONG>   it provided declarations for a few global symbols used by <STRONG>emacs</STRONG>
341
342        <STRONG>o</STRONG>   it provided function prototypes (using <STRONG>const</STRONG>).
343
344        <STRONG>o</STRONG>   a prototype for <STRONG>tparam</STRONG> (a GNU termcap feature) was provided.
345
346        Later (in mid-1996) the <STRONG>tparam</STRONG> function was removed from ncurses.  As a
347        result, there are differences between any of the four  implementations,
348        which  must  be  taken into account by programs which can work with all
349        termcap library interfaces.
350
351
352 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
353        <STRONG><A HREF="ncurses.3x.html">curses(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>.
354
355        https://invisible-island.net/ncurses/tctest.html
356
357
358
359                                                               <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
360 </PRE>
361 <div class="nav">
362 <ul>
363 <li><a href="#h2-NAME">NAME</a></li>
364 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
365 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
366 <ul>
367 <li><a href="#h3-Initialization">Initialization</a></li>
368 <li><a href="#h3-Capability-Values">Capability Values</a></li>
369 <li><a href="#h3-Formatting-Capabilities">Formatting Capabilities</a></li>
370 <li><a href="#h3-Global-Variables">Global Variables</a></li>
371 <li><a href="#h3-Releasing-Memory">Releasing Memory</a></li>
372 </ul>
373 </li>
374 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
375 <li><a href="#h2-BUGS">BUGS</a></li>
376 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
377 <ul>
378 <li><a href="#h3-Standards">Standards</a></li>
379 <li><a href="#h3-Compatibility-with-BSD-Termcap">Compatibility with BSD Termcap</a></li>
380 <li><a href="#h3-Other-Compatibility">Other Compatibility</a></li>
381 </ul>
382 </li>
383 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
384 </ul>
385 </div>
386 </BODY>
387 </HTML>