2 ****************************************************************************
3 * Copyright (c) 1998-2013,2015 Free Software Foundation, Inc. *
5 * Permission is hereby granted, free of charge, to any person obtaining a *
6 * copy of this software and associated documentation files (the *
7 * "Software"), to deal in the Software without restriction, including *
8 * without limitation the rights to use, copy, modify, merge, publish, *
9 * distribute, distribute with modifications, sublicense, and/or sell *
10 * copies of the Software, and to permit persons to whom the Software is *
11 * furnished to do so, subject to the following conditions: *
13 * The above copyright notice and this permission notice shall be included *
14 * in all copies or substantial portions of the Software. *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 * Except as contained in this notice, the name(s) of the above copyright *
25 * holders shall not be used in advertising or otherwise to promote the *
26 * sale, use or other dealings in this Software without prior written *
28 ****************************************************************************
29 * @Id: curs_termcap.3x,v 1.31 2015/04/26 00:49:10 tom Exp @
31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
36 <TITLE>curs_termcap 3x</TITLE>
37 <link rev=made href="mailto:bug-ncurses@gnu.org">
38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
41 <H1 class="no-header">curs_termcap 3x</H1>
43 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
48 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
49 <STRONG>PC</STRONG>, <STRONG>UP</STRONG>, <STRONG>BC</STRONG>, <STRONG>ospeed</STRONG>, <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>, <STRONG>tgetstr</STRONG>,
50 <STRONG>tgoto</STRONG>, <STRONG>tputs</STRONG> - direct <STRONG>curses</STRONG> interface to the terminfo
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
56 <STRONG>#include</STRONG> <STRONG><term.h></STRONG>
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>
63 <STRONG>int</STRONG> <STRONG>tgetent(char</STRONG> <STRONG>*bp,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*name);</STRONG>
64 <STRONG>int</STRONG> <STRONG>tgetflag(char</STRONG> <STRONG>*id);</STRONG>
65 <STRONG>int</STRONG> <STRONG>tgetnum(char</STRONG> <STRONG>*id);</STRONG>
66 <STRONG>char</STRONG> <STRONG>*tgetstr(char</STRONG> <STRONG>*id,</STRONG> <STRONG>char</STRONG> <STRONG>**area);</STRONG>
67 <STRONG>char</STRONG> <STRONG>*tgoto(const</STRONG> <STRONG>char</STRONG> <STRONG>*cap,</STRONG> <STRONG>int</STRONG> <STRONG>col,</STRONG> <STRONG>int</STRONG> <STRONG>row);</STRONG>
68 <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*str,</STRONG> <STRONG>int</STRONG> <STRONG>affcnt,</STRONG> <STRONG>int</STRONG> <STRONG>(*putc)(int));</STRONG>
71 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
72 These routines are included as a conversion aid for pro-
73 grams that use the <EM>termcap</EM> library. Their parameters are
74 the same and the routines are emulated using the <EM>terminfo</EM>
75 database. Thus, they can only be used to query the capa-
76 bilities of entries for which a terminfo entry has been
80 </PRE><H3><a name="h3-INITIALIZATION">INITIALIZATION</a></H3><PRE>
81 The <STRONG>tgetent</STRONG> routine loads the entry for <EM>name</EM>. It returns:
85 0 if there is no such entry (or that it is a generic
86 type, having too little information for curses ap-
87 plications to run), and
89 -1 if the terminfo database could not be found.
91 This differs from the <EM>termcap</EM> library in two ways:
93 <STRONG>o</STRONG> The emulation ignores the buffer pointer <EM>bp</EM>. The
94 <EM>termcap</EM> library would store a copy of the terminal
95 description in the area referenced by this pointer.
96 However, ncurses stores its terminal descriptions
97 in compiled binary form, which is not the same
100 <STRONG>o</STRONG> There is a difference in return codes. The <EM>termcap</EM>
101 library does not check if the terminal description
102 is marked with the <EM>generic</EM> capability, or if the
103 terminal description has cursor-addressing.
106 </PRE><H3><a name="h3-CAPABILITY-VALUES">CAPABILITY VALUES</a></H3><PRE>
107 The <STRONG>tgetflag</STRONG> routine gets the boolean entry for <EM>id</EM>, or ze-
108 ro if it is not available.
110 The <STRONG>tgetnum</STRONG> routine gets the numeric entry for <EM>id</EM>, or -1
111 if it is not available.
113 The <STRONG>tgetstr</STRONG> routine returns the string entry for <EM>id</EM>, or
114 zero if it is not available. Use <STRONG>tputs</STRONG> to output the re-
115 turned string. The <EM>area</EM> parameter is used as follows:
117 <STRONG>o</STRONG> It is assumed to be the address of a pointer to a
118 buffer managed by the calling application.
120 <STRONG>o</STRONG> However, ncurses checks to ensure that <STRONG>area</STRONG> is not
121 NULL, and also that the resulting buffer pointer is
122 not NULL. If either check fails, the <EM>area</EM> parame-
125 <STRONG>o</STRONG> If the checks succeed, ncurses also copies the re-
126 turn value to the buffer pointed to by <EM>area</EM>, and
127 the <EM>area</EM> value will be updated to point past the
128 null ending this value.
130 <STRONG>o</STRONG> The return value itself is an address in the termi-
131 nal description which is loaded into memory.
133 Only the first two characters of the <STRONG>id</STRONG> parameter of <STRONG>tget-</STRONG>
134 <STRONG>flag</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetstr</STRONG> are compared in lookups.
137 </PRE><H3><a name="h3-FORMATTING-CAPABILITIES">FORMATTING CAPABILITIES</a></H3><PRE>
138 The <STRONG>tgoto</STRONG> routine instantiates the parameters into the
139 given capability. The output from this routine is to be
140 passed to <STRONG>tputs</STRONG>.
142 The <STRONG>tputs</STRONG> routine is described on the <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
143 manual page. It can retrieve capabilities by either term-
144 cap or terminfo name.
147 </PRE><H3><a name="h3-GLOBAL-VARIABLES">GLOBAL VARIABLES</a></H3><PRE>
148 The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the ter-
149 minfo entry's data for <STRONG>pad_char</STRONG>, <STRONG>cursor_up</STRONG> and
150 <STRONG>backspace_if_not_bs</STRONG>, respectively. <STRONG>UP</STRONG> is not used by
151 ncurses. <STRONG>PC</STRONG> is used in the <STRONG>tdelay_output</STRONG> function. <STRONG>BC</STRONG> is
152 used in the <STRONG>tgoto</STRONG> emulation. The variable <STRONG>ospeed</STRONG> is set
153 by ncurses in a system-specific coding to reflect the ter-
157 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
158 Except where explicitly noted, routines that return an in-
159 teger return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 only specifies
160 "an integer value other than <STRONG>ERR</STRONG>") upon successful comple-
163 Routines that return pointers return <STRONG>NULL</STRONG> on error.
166 </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
167 If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>ca</STRONG> or any other parameterized
168 string, be aware that it will be returned in terminfo no-
169 tation, not the older and not-quite-compatible termcap no-
170 tation. This will not cause problems if all you do with
171 it is call <STRONG>tgoto</STRONG> or <STRONG>tparm</STRONG>, which both expand terminfo-
172 style strings as terminfo. (The <STRONG>tgoto</STRONG> function, if con-
173 figured to support termcap, will check if the string is
174 indeed terminfo-style by looking for "%p" parameters or
175 "$<..>" delays, and invoke a termcap-style parser if the
176 string does not appear to be terminfo).
178 Because terminfo conventions for representing padding in
179 string capabilities differ from termcap's, <STRONG>tputs("50");</STRONG>
180 will put out a literal "50" rather than busy-waiting for
181 50 milliseconds. Cope with it.
183 Note that termcap has nothing analogous to terminfo's <STRONG>sgr</STRONG>
184 string. One consequence of this is that termcap applica-
185 tions assume me (terminfo <STRONG>sgr0</STRONG>) does not reset the alter-
186 nate character set. This implementation checks for, and
187 modifies the data shown to the termcap interface to accom-
188 modate termcap's limitation in this respect.
191 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
192 The XSI Curses standard, Issue 4 describes these func-
193 tions. However, they are marked TO BE WITHDRAWN and may
194 be removed in future versions.
196 Neither the XSI Curses standard nor the SVr4 man pages
197 documented the return values of <STRONG>tgetent</STRONG> correctly, though
198 all three were in fact returned ever since SVr1. In par-
199 ticular, an omission in the XSI Curses documentation has
200 been misinterpreted to mean that <STRONG>tgetent</STRONG> returns <STRONG>OK</STRONG> or
201 <STRONG>ERR</STRONG>. Because the purpose of these functions is to provide
202 compatibility with the <EM>termcap</EM> library, that is a defect
203 in XCurses, Issue 4, Version 2 rather than in ncurses.
205 External variables are provided for support of certain
206 termcap applications. However, termcap applications' use
207 of those variables is poorly documented, e.g., not distin-
208 guishing between input and output. In particular, some
209 applications are reported to declare and/or modify <STRONG>ospeed</STRONG>.
211 The comment that only the first two characters of the <STRONG>id</STRONG>
212 parameter are used escapes many application developers.
213 The original BSD 4.2 termcap library (and historical
214 relics thereof) did not require a trailing null NUL on the
215 parameter name passed to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetflag</STRONG>.
216 Some applications assume that the termcap interface does
217 not require the trailing NUL for the parameter name. Tak-
218 ing into account these issues:
220 <STRONG>o</STRONG> As a special case, <STRONG>tgetflag</STRONG> matched against a single-
221 character identifier provided that was at the end of
222 the terminal description. You should not rely upon
223 this behavior in portable programs. This implementa-
224 tion disallows matches against single-character capa-
227 <STRONG>o</STRONG> This implementation disallows matches by the termcap
228 interface against extended capability names which are
229 longer than two characters.
232 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
233 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>.
235 http://invisible-island.net/ncurses/tctest.html
239 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
243 <li><a href="#h2-NAME">NAME</a></li>
244 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
245 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
247 <li><a href="#h3-INITIALIZATION">INITIALIZATION</a></li>
248 <li><a href="#h3-CAPABILITY-VALUES">CAPABILITY VALUES</a></li>
249 <li><a href="#h3-FORMATTING-CAPABILITIES">FORMATTING CAPABILITIES</a></li>
250 <li><a href="#h3-GLOBAL-VARIABLES">GLOBAL VARIABLES</a></li>
253 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
254 <li><a href="#h2-BUGS">BUGS</a></li>
255 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
256 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>