2 ****************************************************************************
3 * Copyright 2018-2023,2024 Thomas E. Dickey *
4 * Copyright 1998-2017,2018 Free Software Foundation, Inc. *
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: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
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. *
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 *
29 ****************************************************************************
30 * @Id: curs_termcap.3x,v 1.85 2024/04/20 19:13:12 tom Exp @
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
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 2024-04-20 ncurses 6.5 Library calls</TITLE>
38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
42 <H1 class="no-header">curs_termcap 3x 2024-04-20 ncurses 6.5 Library calls</H1>
44 <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>
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 <EM>curses</EM> emulation of <EM>termcap</EM>
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>char</STRONG> <STRONG>PC;</STRONG>
59 <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>UP;</STRONG>
60 <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>BC;</STRONG>
61 <STRONG>short</STRONG> <STRONG>ospeed;</STRONG>
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>
71 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
72 <EM>ncurses</EM> provides the foregoing variables and functions as a
73 compatibility layer for programs that use the <EM>termcap</EM> library. The API
74 is the same, but behavior is emulated using the <EM>terminfo</EM> database.
75 Thus, it can be used only to query the capabilities of terminal
76 database entries for which a <EM>terminfo</EM> entry has been compiled.
79 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
80 <STRONG>tgetent</STRONG> loads the terminal database entry for <EM>name</EM>; see <STRONG><A HREF="term.7.html">term(7)</A></STRONG>. This
81 must be done before calling any of the other functions. It returns
85 0 if there is no such entry (or if the matching entry describes a
86 generic terminal, having too little information for <EM>curses</EM>
87 applications to run), and
89 -1 if the <EM>terminfo</EM> database could not be found.
91 This implementation differs from those of historical <EM>termcap</EM> libraries.
93 <STRONG>o</STRONG> <EM>ncurses</EM> ignores the buffer pointer <EM>bp</EM>, as do other <EM>termcap</EM>
94 implementations conforming to portions of X/Open Curses now
95 withdrawn. The BSD <EM>termcap</EM> library would store a copy of the
96 terminal type description in the area referenced by this
97 pointer. <EM>terminfo</EM> stores terminal type descriptions in compiled
98 form, which is not the same thing.
100 <STRONG>o</STRONG> The meanings of the return values differ. The BSD <EM>termcap</EM>
101 library does not check whether the terminal type description
102 includes the <STRONG>generic</STRONG> (<STRONG>gn</STRONG>) capability, nor whether the terminal
103 type description supports an addressable cursor, a property
104 essential for any <EM>curses</EM> implementation to operate.
107 </PRE><H3><a name="h3-Retrieving-Capability-Values">Retrieving Capability Values</a></H3><PRE>
108 <STRONG>tgetflag</STRONG> reports the Boolean entry for <EM>id</EM>, or zero if it is not
111 <STRONG>tgetnum</STRONG> obtains the numeric entry for <EM>id</EM>, or -1 if it is not available.
113 <STRONG>tgetstr</STRONG> returns the string entry for <EM>id</EM>, or <STRONG>NULL</STRONG> if it is not
114 available. Use <STRONG>tputs</STRONG> to output the string returned. The <EM>area</EM>
115 parameter is used as follows.
117 <STRONG>o</STRONG> It is assumed to be the address of a pointer to a buffer managed
118 by the calling application.
120 <STRONG>o</STRONG> However, <EM>ncurses</EM> checks to ensure that <EM>area</EM> is not <STRONG>NULL</STRONG>, and
121 also that the resulting buffer pointer is not <STRONG>NULL</STRONG>. If either
122 check fails, <EM>area</EM> is ignored.
124 <STRONG>o</STRONG> If the checks succeed, <EM>ncurses</EM> also copies the return value to
125 the buffer pointed to by <EM>area</EM>, and the library updates <EM>area</EM> to
126 point past the null character terminating this value.
128 <STRONG>o</STRONG> The return value itself is an address in the terminal type
129 description loaded into memory.
132 </PRE><H3><a name="h3-Applying-String-Capabilities">Applying String Capabilities</a></H3><PRE>
133 String capabilities can be parameterized; see subsection "Parameterized
134 Strings" in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. <STRONG>tgoto</STRONG> applies its second and third arguments
135 to the parametric placeholders in the capability stored in the first
138 <STRONG>o</STRONG> The capability may contain padding specifications; see subsection
139 "Delays and Padding" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. The output of <STRONG>tgoto</STRONG> should
140 thus be passed to <STRONG>tputs</STRONG> rather than some other output function such
141 as <STRONG>printf(3)</STRONG>.
143 <STRONG>o</STRONG> While <STRONG>tgoto</STRONG> is assumed to be used for the two-parameter cursor
144 positioning capability, <EM>termcap</EM> applications also use it for
145 single-parameter capabilities.
147 Doing so reveals a quirk in <STRONG>tgoto</STRONG>: most hardware terminals use
148 cursor addressing with <EM>row</EM> first, but the original developers of
149 the <EM>termcap</EM> interface chose to put the <EM>col</EM> (column) parameter
150 first. The <STRONG>tgoto</STRONG> function swaps the order of its parameters. It
151 does this even for calls requiring only a single parameter. In
152 that case, the first parameter is merely a placeholder.
154 <STRONG>o</STRONG> Normally the <EM>ncurses</EM> library is compiled without full <EM>termcap</EM>
155 support. In that case, <STRONG>tgoto</STRONG> uses an internal version of <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>
156 (a more capable function).
158 Because it uses <STRONG>tparm</STRONG> internally, <STRONG>tgoto</STRONG> is able to use some <EM>term-</EM>
159 <EM>info</EM> features, but not all. In particular, it allows only numeric
160 parameters; <STRONG>tparm</STRONG> supports string parameters.
162 However, <STRONG>tparm</STRONG> is not a <EM>termcap</EM> feature, and portable <EM>termcap</EM>
163 applications should not rely upon its availability.
165 <STRONG>tputs</STRONG> is described in <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>. It can retrieve capabilities
166 by either <EM>termcap</EM> or <EM>terminfo</EM> code.
169 </PRE><H3><a name="h3-Global-Variables">Global Variables</a></H3><PRE>
170 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
171 data for <STRONG>pad_char</STRONG>, <STRONG>cursor_up</STRONG> and <STRONG>backspace_if_not_bs</STRONG>, respectively. <STRONG>UP</STRONG>
172 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
173 <STRONG>tgoto</STRONG> emulation. The variable <STRONG>ospeed</STRONG> is set by <EM>ncurses</EM> using a system-
174 specific encoding to indicate the terminal's data rate.
177 </PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE>
178 The <EM>termcap</EM> functions provide no means of freeing memory, because
179 legacy <EM>termcap</EM> implementations used only the buffer areas provided by
180 the caller via <STRONG>tgetent</STRONG> and <STRONG>tgetstr</STRONG>. Those buffers are unused in <EM>term-</EM>
183 By contrast, <EM>terminfo</EM> allocates memory. It uses <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to
184 obtain the data used by <STRONG>tgetent</STRONG> and the functions that retrieve
185 capability values. One could use
186 del_curterm(cur_term);
187 to free this memory, but there is an additional complication with
188 <EM>ncurses</EM>. It uses a fixed-size pool of storage locations, one per value
189 of the terminal name parameter given to <STRONG>tgetent</STRONG>. The <STRONG>screen(1)</STRONG> program
190 relies upon this arrangement to improve its performance.
192 An application that uses only the <EM>termcap</EM> functions, not the higher
193 level <EM>curses</EM> API, could release the memory using <STRONG><A HREF="curs_terminfo.3x.html">del_curterm(3x)</A></STRONG>,
194 because the pool is freed using other functions; see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>.
197 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
198 The return values of <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>, <STRONG>tgetname</STRONG>, and <STRONG>tgetstr</STRONG> are
201 <STRONG>tgoto</STRONG> returns <STRONG>NULL</STRONG> on error. Error conditions include:
203 <STRONG>o</STRONG> uninitialized state (<STRONG>tgetent</STRONG> was not called successfully),
205 <STRONG>o</STRONG> <EM>cap</EM> being a null pointer,
207 <STRONG>o</STRONG> <EM>cap</EM> referring to a canceled capability,
209 <STRONG>o</STRONG> <EM>cap</EM> being a capability with string-valued parameters (a <EM>term-</EM>
210 <EM>info</EM>-only feature), and
212 <STRONG>o</STRONG> <EM>cap</EM> being a capability with more than two parameters.
214 See <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> regarding <STRONG>tputs</STRONG>.
217 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
218 <EM>ncurses</EM> compares only the first two characters of the <EM>id</EM> parameter of
219 <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>, and <STRONG>tgetstr</STRONG> to the capability names in the database.
222 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
223 These functions are no longer standardized (and the variables never
224 were); <EM>ncurses</EM> provides them to support legacy applications. They
225 should not be used in new programs.
228 </PRE><H3><a name="h3-Standards">Standards</a></H3><PRE>
229 <STRONG>o</STRONG> X/Open Curses, Issue 4, Version 2 (1996), describes these
230 functions, marking them as "TO BE WITHDRAWN".
232 <STRONG>o</STRONG> X/Open Curses, Issue 7 (2009) marks the <EM>termcap</EM> interface (along
233 with <STRONG>vwprintw</STRONG> and <STRONG>vwscanw</STRONG>) as withdrawn.
235 Neither X/Open Curses nor the SVr4 man pages documented the return
236 values of <STRONG>tgetent</STRONG> correctly, though all three shown here were in fact
237 returned ever since SVr1. In particular, an omission in the X/Open
238 Curses specification has been misinterpreted to mean that <STRONG>tgetent</STRONG>
239 returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. Because the purpose of these functions is to
240 provide compatibility with the <EM>termcap</EM> library, that is a defect in
241 X/Open Curses, Issue 4, Version 2 rather than in <EM>ncurses</EM>.
243 <STRONG>Compatibility</STRONG> <STRONG>with</STRONG> <STRONG>BSD</STRONG> <EM>termcap</EM>
244 Externally visible variables are provided for support of certain
245 <EM>termcap</EM> applications. However, their correct usage is poorly
246 documented; for example, it is unclear when reading and writing them is
247 meaningful. In particular, some applications are reported to declare
248 and/or modify <STRONG>ospeed</STRONG>.
250 The constraint that only the first two characters of the <EM>id</EM> parameter
251 are used escapes many application developers. The BSD <EM>termcap</EM> library
252 did not require a trailing null character on the capability identifier
253 passed to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG>, and <STRONG>tgetflag</STRONG>. Some applications thus
254 assume that the <EM>termcap</EM> interface does not require the trailing null
255 character for the capability identifier.
257 <STRONG>o</STRONG> <EM>ncurses</EM> disallows matches by the <EM>termcap</EM> interface against extended
258 capability names that are longer than two characters; see
259 <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>.
261 The BSD <EM>termcap</EM> function <STRONG>tgetent</STRONG> returns the text of a <EM>termcap</EM> entry in
262 the buffer passed as an argument. This library, like other <EM>terminfo</EM>
263 implementations, does not store terminal type descriptions as text. It
264 sets the buffer contents to a null-terminated string.
267 </PRE><H3><a name="h3-Header-File">Header File</a></H3><PRE>
268 This library includes a <EM>termcap.h</EM> header for compatibility with other
269 implementations, but the header is rarely used because the other
270 implementations are not strictly compatible.
273 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
274 Bill Joy originated a forerunner of <EM>termcap</EM> called "ttycap", dated
275 September 1977, and released in 1BSD (March 1978). It used many of the
276 same function names as the later <EM>termcap</EM>, such as <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>,
277 <STRONG>tgetnum</STRONG>, and <STRONG>tgetstr</STRONG>.
279 A clear descendant, the <EM>termlib</EM> library, followed in 2BSD (May 1979),
280 adding <STRONG>tgoto</STRONG> and <STRONG>tputs</STRONG>. The former applied at that time only to cursor
281 positioning capabilities, thus the overly specific name. Little
282 changed in 3BSD (late 1979) except the addition of test programs and a
283 <EM>termlib</EM> man page, which documented the API shown in section "SYNOPSIS"
286 4BSD (November 1980) renamed <EM>termlib</EM> to <EM>termcap</EM> and added another test
287 program. The library remained much the same though 4.3BSD (June 1986).
288 4.4BSD-Lite (June 1994) refactored it, leaving the API unchanged.
290 Function prototypes were a feature of ANSI C (1989). The library long
291 antedated the standard and thus provided no header file declaring them.
292 Nevertheless, the BSD sources included two different <EM>termcap.h</EM> header
295 <STRONG>o</STRONG> One was used internally by <STRONG>jove(1)</STRONG> from 4.3BSD onward. It declared
296 global symbols for the <EM>termcap</EM> variables that it used.
298 <STRONG>o</STRONG> The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part of
299 <EM>libedit</EM> (also known as the <EM>editline</EM> library). CSRG source history
300 shows that this was added in mid-1992. The <EM>libedit</EM> header file was
301 used internally as a convenience for compiling the <EM>editline</EM>
302 library. It declared function prototypes, but no global variables.
303 This header file was added to NetBSD's <EM>termcap</EM> library in mid-1994.
305 Meanwhile, GNU <EM>termcap</EM> began development in 1990. Its first release
306 (1.0) in 1991 included a <EM>termcap.h</EM> header. Its second (1.1) in
307 September 1992 modified the header to use <EM>const</EM> for the function
308 prototypes in the header where one would expect the parameters to be
309 read-only. BSD <EM>termcap</EM> did not. The prototype for <STRONG>tputs</STRONG> also
310 differed, but in that instance, it was <EM>libedit</EM> that differed from BSD
313 GNU <EM>termcap</EM> 1.3 was bundled with <STRONG>bash(1)</STRONG> in mid-1993 to support the
314 <STRONG>readline(3)</STRONG> library.
316 <EM>ncurses</EM> 1.8.1 (November 1993) provided a <EM>termcap.h</EM> file. It reflected
317 influence from GNU <EM>termcap</EM> and <STRONG>emacs(1)</STRONG> (rather than <STRONG>jove(1)</STRONG>),
318 providing the following interface:
320 <STRONG>o</STRONG> global symbols used by <EM>emacs</EM>,
322 <STRONG>o</STRONG> <EM>const</EM>-qualified function prototypes, and
324 <STRONG>o</STRONG> a prototype for <STRONG>tparam</STRONG>, a GNU <EM>termcap</EM> feature.
326 Later (in mid-1996) the <STRONG>tparam</STRONG> function was removed from <EM>ncurses</EM>. Any
327 two of the four implementations thus differ, and programs that intend
328 to work with all <EM>termcap</EM> library interfaces must account for that fact.
331 </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
332 If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>column_address</STRONG> (<STRONG>ch</STRONG>) or any other
333 parameterized string capability, be aware that it is returned in <EM>term-</EM>
334 <EM>info</EM> notation, not the older and not-quite-compatible <EM>termcap</EM> notation.
335 This does not cause problems if all you do with it is call <STRONG>tgoto</STRONG> or
336 <STRONG>tparm</STRONG>, which both parametrically expand <EM>terminfo</EM>-style string
337 capabilities as <EM>terminfo</EM> does. (If <EM>ncurses</EM> is configured to support
338 <EM>termcap,</EM> <STRONG>tgoto</STRONG> checks whether the string is <EM>terminfo</EM>-style by looking
339 for "<STRONG>%p</STRONG>" parameters or "<STRONG><</STRONG>...<STRONG>></STRONG>" delays, and invokes a <EM>termcap</EM>-style
340 parser if the string appears not to use <EM>terminfo</EM> syntax.)
342 Because <EM>terminfo</EM>'s syntax for padding in string capabilities differs
343 from <EM>termcap</EM>'s, users can be surprised.
345 <STRONG>o</STRONG> <STRONG>tputs("50")</STRONG> in a <EM>terminfo</EM> system transmits "50" rather than busy-
346 waiting for 50 milliseconds.
348 <STRONG>o</STRONG> However, if <EM>ncurses</EM> is configured to support <EM>termcap</EM>, it may also
349 have been configured to support BSD-style padding.
351 In that case, <STRONG>tputs</STRONG> inspects strings passed to it, looking for
352 digits at the beginning of the string.
354 <STRONG>tputs("50")</STRONG> in a <EM>termcap</EM> system may busy-wait for 50 milliseconds
355 rather than transmitting "50".
357 <EM>termcap</EM> has nothing analogous to <EM>terminfo</EM>'s <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>)
358 capability. One consequence is that <EM>termcap</EM> applications assume that
359 "<STRONG>me</STRONG>" (equivalent to <EM>terminfo</EM>'s <STRONG>exit_attribute_mode</STRONG> (<STRONG>sgr0</STRONG>) capability)
360 does not reset the alternate character set. <EM>ncurses</EM> checks for, and
361 modifies the data shared with, the <EM>termcap</EM> interface to accommodate the
362 latter's limitation in this respect.
365 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
366 <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>
368 https://invisible-island.net/ncurses/tctest.html
372 ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
376 <li><a href="#h2-NAME">NAME</a></li>
377 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
378 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
380 <li><a href="#h3-Initialization">Initialization</a></li>
381 <li><a href="#h3-Retrieving-Capability-Values">Retrieving Capability Values</a></li>
382 <li><a href="#h3-Applying-String-Capabilities">Applying String Capabilities</a></li>
383 <li><a href="#h3-Global-Variables">Global Variables</a></li>
384 <li><a href="#h3-Releasing-Memory">Releasing Memory</a></li>
387 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
388 <li><a href="#h2-NOTES">NOTES</a></li>
389 <li><a href="#h2-PORTABILITY">PORTABILITY</a>
391 <li><a href="#h3-Standards">Standards</a></li>
392 <li><a href="#h3-Header-File">Header File</a></li>
395 <li><a href="#h2-HISTORY">HISTORY</a></li>
396 <li><a href="#h2-BUGS">BUGS</a></li>
397 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>