- The XSI Curses standard, Issue 4 describes these func-
- tions. However, they are marked TO BE WITHDRAWN and may
- be removed in future versions.
-
- Neither the XSI Curses standard nor the SVr4 man pages
- documented the return values of <STRONG>tgetent</STRONG> correctly, though
- all three were in fact returned ever since SVr1. In par-
- ticular, an omission in the XSI Curses documentation has
- been misinterpreted to mean that <STRONG>tgetent</STRONG> returns <STRONG>OK</STRONG> or
- <STRONG>ERR</STRONG>. Because the purpose of these functions is to provide
- compatibility with the <EM>termcap</EM> library, that is a defect
- in XCurses, Issue 4, Version 2 rather than in ncurses.
-
- External variables are provided for support of certain
- termcap applications. However, termcap applications' use
- of those variables is poorly documented, e.g., not distin-
- guishing between input and output. In particular, some
- applications are reported to declare and/or modify <STRONG>ospeed</STRONG>.
-
- The comment that only the first two characters of the <STRONG>id</STRONG>
- parameter are used escapes many application developers.
- The original BSD 4.2 termcap library (and historical
- relics thereof) did not require a trailing null NUL on the
- parameter name passed to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetflag</STRONG>.
- Some applications assume that the termcap interface does
- not require the trailing NUL for the parameter name. Tak-
- ing into account these issues:
-
- <STRONG>o</STRONG> As a special case, <STRONG>tgetflag</STRONG> matched against a single-
- character identifier provided that was at the end of
- the terminal description. You should not rely upon
- this behavior in portable programs. This implementa-
- tion disallows matches against single-character capa-
- bility names.
-
- <STRONG>o</STRONG> This implementation disallows matches by the termcap
- interface against extended capability names which are
- longer than two characters.
+ These functions are no longer standardized (and the variables never
+ were); <EM>ncurses</EM> provides them to support legacy applications. They
+ should not be used in new programs.
+
+
+</PRE><H3><a name="h3-Standards">Standards</a></H3><PRE>
+ <STRONG>o</STRONG> X/Open Curses, Issue 4, Version 2 (1996), describes these
+ functions, marking them as "TO BE WITHDRAWN".
+
+ <STRONG>o</STRONG> X/Open Curses, Issue 7 (2009) marks the <EM>termcap</EM> interface (along
+ with <STRONG>vwprintw</STRONG> and <STRONG>vwscanw</STRONG>) as withdrawn.
+
+ Neither X/Open Curses nor the SVr4 man pages documented the return
+ values of <STRONG>tgetent</STRONG> 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 <STRONG>tgetent</STRONG>
+ returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. Because the purpose of these functions is to
+ provide compatibility with the <EM>termcap</EM> library, that is a defect in
+ X/Open Curses, Issue 4, Version 2 rather than in <EM>ncurses</EM>.
+
+ <STRONG>Compatibility</STRONG> <STRONG>with</STRONG> <STRONG>BSD</STRONG> <EM>termcap</EM>
+ Externally visible variables are provided for support of certain
+ <EM>termcap</EM> 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 <STRONG>ospeed</STRONG>.
+
+ The constraint that only the first two characters of the <EM>id</EM> parameter
+ are used escapes many application developers. The BSD <EM>termcap</EM> library
+ did not require a trailing null character on the capability identifier
+ passed to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG>, and <STRONG>tgetflag</STRONG>. Some applications thus
+ assume that the <EM>termcap</EM> interface does not require the trailing null
+ character for the capability identifier.
+
+ <STRONG>o</STRONG> <EM>ncurses</EM> disallows matches by the <EM>termcap</EM> interface against extended
+ capability names that are longer than two characters; see
+ <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>.
+
+ The BSD <EM>termcap</EM> function <STRONG>tgetent</STRONG> returns the text of a <EM>termcap</EM> entry in
+ the buffer passed as an argument. This library, like other <EM>terminfo</EM>
+ implementations, does not store terminal type descriptions as text. It
+ sets the buffer contents to a null-terminated string.
+
+
+</PRE><H3><a name="h3-Header-File">Header File</a></H3><PRE>
+ This library includes a <EM>termcap.h</EM> header for compatibility with other
+ implementations, but the header is rarely used because the other
+ implementations are not strictly compatible.
+
+
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+ Bill Joy originated a forerunner of <EM>termcap</EM> called "ttycap", dated
+ September 1977, and released in 1BSD (March 1978). It used many of the
+ same function names as the later <EM>termcap</EM>, such as <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>,
+ <STRONG>tgetnum</STRONG>, and <STRONG>tgetstr</STRONG>.
+
+ A clear descendant, the <EM>termlib</EM> library, followed in 2BSD (May 1979),
+ adding <STRONG>tgoto</STRONG> and <STRONG>tputs</STRONG>. 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
+ <EM>termlib</EM> man page, which documented the API shown in section "SYNOPSIS"
+ above.
+
+ 4BSD (November 1980) renamed <EM>termlib</EM> to <EM>termcap</EM> 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 <EM>termcap.h</EM> header
+ files over time.
+
+ <STRONG>o</STRONG> One was used internally by <STRONG>jove(1)</STRONG> from 4.3BSD onward. It declared
+ global symbols for the <EM>termcap</EM> variables that it used.
+
+ <STRONG>o</STRONG> The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part of
+ <EM>libedit</EM> (also known as the <EM>editline</EM> library). CSRG source history
+ shows that this was added in mid-1992. The <EM>libedit</EM> header file was
+ used internally as a convenience for compiling the <EM>editline</EM>
+ library. It declared function prototypes, but no global variables.
+ This header file was added to NetBSD's <EM>termcap</EM> library in mid-1994.
+
+ Meanwhile, GNU <EM>termcap</EM> began development in 1990. Its first release
+ (1.0) in 1991 included a <EM>termcap.h</EM> header. Its second (1.1) in
+ September 1992 modified the header to use <EM>const</EM> for the function
+ prototypes in the header where one would expect the parameters to be
+ read-only. BSD <EM>termcap</EM> did not. The prototype for <STRONG>tputs</STRONG> also
+ differed, but in that instance, it was <EM>libedit</EM> that differed from BSD
+ <EM>termcap</EM>.
+
+ GNU <EM>termcap</EM> 1.3 was bundled with <STRONG>bash(1)</STRONG> in mid-1993 to support the
+ <STRONG>readline(3)</STRONG> library.
+
+ <EM>ncurses</EM> 1.8.1 (November 1993) provided a <EM>termcap.h</EM> file. It reflected
+ influence from GNU <EM>termcap</EM> and <STRONG>emacs(1)</STRONG> (rather than <STRONG>jove(1)</STRONG>),
+ providing the following interface:
+
+ <STRONG>o</STRONG> global symbols used by <EM>emacs</EM>,
+
+ <STRONG>o</STRONG> <EM>const</EM>-qualified function prototypes, and
+
+ <STRONG>o</STRONG> a prototype for <STRONG>tparam</STRONG>, a GNU <EM>termcap</EM> feature.
+
+ Later (in mid-1996) the <STRONG>tparam</STRONG> function was removed from <EM>ncurses</EM>. Any
+ two of the four implementations thus differ, and programs that intend
+ to work with all <EM>termcap</EM> library interfaces must account for that fact.
+
+
+</PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
+ If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>column_address</STRONG> (<STRONG>ch</STRONG>) or any other
+ parameterized string capability, be aware that it is returned in <EM>term-</EM>
+ <EM>info</EM> notation, not the older and not-quite-compatible <EM>termcap</EM> notation.
+ This does not cause problems if all you do with it is call <STRONG>tgoto</STRONG> or
+ <STRONG>tparm</STRONG>, which both parametrically expand <EM>terminfo</EM>-style string
+ capabilities as <EM>terminfo</EM> does. (If <EM>ncurses</EM> is configured to support
+ <EM>termcap,</EM> <STRONG>tgoto</STRONG> checks whether the string is <EM>terminfo</EM>-style by looking
+ for "<STRONG>%p</STRONG>" parameters or "<STRONG><</STRONG>...<STRONG>></STRONG>" delays, and invokes a <EM>termcap</EM>-style
+ parser if the string appears not to use <EM>terminfo</EM> syntax.)
+
+ Because <EM>terminfo</EM>'s syntax for padding in string capabilities differs
+ from <EM>termcap</EM>'s, users can be surprised.
+
+ <STRONG>o</STRONG> <STRONG>tputs("50")</STRONG> in a <EM>terminfo</EM> system transmits "50" rather than busy-
+ waiting for 50 milliseconds.
+
+ <STRONG>o</STRONG> However, if <EM>ncurses</EM> is configured to support <EM>termcap</EM>, it may also
+ have been configured to support BSD-style padding.
+
+ In that case, <STRONG>tputs</STRONG> inspects strings passed to it, looking for
+ digits at the beginning of the string.
+
+ <STRONG>tputs("50")</STRONG> in a <EM>termcap</EM> system may busy-wait for 50 milliseconds
+ rather than transmitting "50".
+
+ <EM>termcap</EM> has nothing analogous to <EM>terminfo</EM>'s <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>)
+ capability. One consequence is that <EM>termcap</EM> applications assume that
+ "<STRONG>me</STRONG>" (equivalent to <EM>terminfo</EM>'s <STRONG>exit_attribute_mode</STRONG> (<STRONG>sgr0</STRONG>) capability)
+ does not reset the alternate character set. <EM>ncurses</EM> checks for, and
+ modifies the data shared with, the <EM>termcap</EM> interface to accommodate the
+ latter's limitation in this respect.