2 ****************************************************************************
3 * Copyright (c) 1998-2015,2016 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.32 2016/03/19 22:52:25 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 expands the given capability using the
141 <STRONG>o</STRONG> Because the capability may have padding characters,
142 the output of <STRONG>tgoto</STRONG> should be passed to <STRONG>tputs</STRONG> rather
143 than some other output function such as <STRONG>printf</STRONG>.
145 <STRONG>o</STRONG> While <STRONG>tgoto</STRONG> is assumed to be used for the two-parame-
146 ter cursor positioning capability, termcap applica-
147 tions also use it for single-parameter capabilities.
149 Doing this shows a quirk in <STRONG>tgoto</STRONG>: most hardware ter-
150 minals use cursor addressing with <EM>row</EM> first, but the
151 original developers of the termcap interface chose to
152 put the <EM>column</EM> parameter first. The <STRONG>tgoto</STRONG> function
153 swaps the order of parameters. It does this also for
154 calls requiring only a single parameter. In that
155 case, the first parameter is merely a placeholder.
157 <STRONG>o</STRONG> Normally the ncurses library is compiled with terminfo
158 support. In that case, <STRONG>tgoto</STRONG> uses <STRONG>tparm</STRONG> (a more capa-
161 The <STRONG>tputs</STRONG> routine is described on the <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
162 manual page. It can retrieve capabilities by either term-
163 cap or terminfo name.
166 </PRE><H3><a name="h3-GLOBAL-VARIABLES">GLOBAL VARIABLES</a></H3><PRE>
167 The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the ter-
168 minfo entry's data for <STRONG>pad_char</STRONG>, <STRONG>cursor_up</STRONG> and
169 <STRONG>backspace_if_not_bs</STRONG>, respectively. <STRONG>UP</STRONG> is not used by
170 ncurses. <STRONG>PC</STRONG> is used in the <STRONG>tdelay_output</STRONG> function. <STRONG>BC</STRONG> is
171 used in the <STRONG>tgoto</STRONG> emulation. The variable <STRONG>ospeed</STRONG> is set
172 by ncurses in a system-specific coding to reflect the ter-
176 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
177 Except where explicitly noted, routines that return an in-
178 teger return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 only specifies
179 "an integer value other than <STRONG>ERR</STRONG>") upon successful comple-
182 Routines that return pointers return <STRONG>NULL</STRONG> on error.
185 </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
186 If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>ca</STRONG> or any other parameterized
187 string, be aware that it will be returned in terminfo no-
188 tation, not the older and not-quite-compatible termcap no-
189 tation. This will not cause problems if all you do with
190 it is call <STRONG>tgoto</STRONG> or <STRONG>tparm</STRONG>, which both expand terminfo-
191 style strings as terminfo. (The <STRONG>tgoto</STRONG> function, if con-
192 figured to support termcap, will check if the string is
193 indeed terminfo-style by looking for "%p" parameters or
194 "$<..>" delays, and invoke a termcap-style parser if the
195 string does not appear to be terminfo).
197 Because terminfo conventions for representing padding in
198 string capabilities differ from termcap's, <STRONG>tputs("50");</STRONG>
199 will put out a literal "50" rather than busy-waiting for
200 50 milliseconds. Cope with it.
202 Note that termcap has nothing analogous to terminfo's <STRONG>sgr</STRONG>
203 string. One consequence of this is that termcap applica-
204 tions assume me (terminfo <STRONG>sgr0</STRONG>) does not reset the alter-
205 nate character set. This implementation checks for, and
206 modifies the data shown to the termcap interface to accom-
207 modate termcap's limitation in this respect.
210 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
211 The XSI Curses standard, Issue 4 describes these func-
212 tions. However, they are marked TO BE WITHDRAWN and may
213 be removed in future versions.
215 Neither the XSI Curses standard nor the SVr4 man pages
216 documented the return values of <STRONG>tgetent</STRONG> correctly, though
217 all three were in fact returned ever since SVr1. In par-
218 ticular, an omission in the XSI Curses documentation has
219 been misinterpreted to mean that <STRONG>tgetent</STRONG> returns <STRONG>OK</STRONG> or
220 <STRONG>ERR</STRONG>. Because the purpose of these functions is to provide
221 compatibility with the <EM>termcap</EM> library, that is a defect
222 in XCurses, Issue 4, Version 2 rather than in ncurses.
224 External variables are provided for support of certain
225 termcap applications. However, termcap applications' use
226 of those variables is poorly documented, e.g., not distin-
227 guishing between input and output. In particular, some
228 applications are reported to declare and/or modify <STRONG>ospeed</STRONG>.
230 The comment that only the first two characters of the <STRONG>id</STRONG>
231 parameter are used escapes many application developers.
232 The original BSD 4.2 termcap library (and historical
233 relics thereof) did not require a trailing null NUL on the
234 parameter name passed to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetflag</STRONG>.
235 Some applications assume that the termcap interface does
236 not require the trailing NUL for the parameter name. Tak-
237 ing into account these issues:
239 <STRONG>o</STRONG> As a special case, <STRONG>tgetflag</STRONG> matched against a single-
240 character identifier provided that was at the end of
241 the terminal description. You should not rely upon
242 this behavior in portable programs. This implementa-
243 tion disallows matches against single-character capa-
246 <STRONG>o</STRONG> This implementation disallows matches by the termcap
247 interface against extended capability names which are
248 longer than two characters.
251 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
252 <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>.
254 http://invisible-island.net/ncurses/tctest.html
258 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
262 <li><a href="#h2-NAME">NAME</a></li>
263 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
264 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
266 <li><a href="#h3-INITIALIZATION">INITIALIZATION</a></li>
267 <li><a href="#h3-CAPABILITY-VALUES">CAPABILITY VALUES</a></li>
268 <li><a href="#h3-FORMATTING-CAPABILITIES">FORMATTING CAPABILITIES</a></li>
269 <li><a href="#h3-GLOBAL-VARIABLES">GLOBAL VARIABLES</a></li>
272 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
273 <li><a href="#h2-BUGS">BUGS</a></li>
274 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
275 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>