+</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
+ The <STRONG>tgetent</STRONG> routine loads the entry for <EM>name</EM>. It returns:
+
+ 1 on success,
+
+ 0 if there is no such entry (or that it is a generic type, having
+ too little information for curses applications to run), and
+
+ -1 if the terminfo database could not be found.
+
+ This differs from the <EM>termcap</EM> library in two ways:
+
+ <STRONG>o</STRONG> The emulation ignores the buffer pointer <EM>bp</EM>. The <EM>termcap</EM> li-
+ brary would store a copy of the terminal description in the area
+ referenced by this pointer. However, ncurses stores its termi-
+ nal descriptions in compiled binary form, which is not the same
+ thing.
+
+ <STRONG>o</STRONG> There is a difference in return codes. The <EM>termcap</EM> library does
+ not check if the terminal description is marked with the <EM>generic</EM>
+ capability, or if the terminal description has cursor-address-
+ ing.
+
+
+</PRE><H3><a name="h3-Capability-Values">Capability Values</a></H3><PRE>
+ The <STRONG>tgetflag</STRONG> routine gets the boolean entry for <EM>id</EM>, or zero if it is
+ not available.
+
+ The <STRONG>tgetnum</STRONG> routine gets the numeric entry for <EM>id</EM>, or -1 if it is not
+ available.
+
+ The <STRONG>tgetstr</STRONG> routine returns the string entry for <EM>id</EM>, or zero if it is
+ not available. Use <STRONG>tputs</STRONG> to output the returned string. The <EM>area</EM> pa-
+ rameter is used as follows:
+
+ <STRONG>o</STRONG> It is assumed to be the address of a pointer to a buffer managed
+ by the calling application.
+
+ <STRONG>o</STRONG> However, ncurses checks to ensure that <STRONG>area</STRONG> is not NULL, and al-
+ so that the resulting buffer pointer is not NULL. If either
+ check fails, the <EM>area</EM> parameter is ignored.
+
+ <STRONG>o</STRONG> If the checks succeed, ncurses also copies the return value to
+ the buffer pointed to by <EM>area</EM>, and the <EM>area</EM> value will be updat-
+ ed to point past the null ending this value.
+
+ <STRONG>o</STRONG> The return value itself is an address in the terminal descrip-
+ tion which is loaded into memory.
+
+ Only the first two characters of the <STRONG>id</STRONG> parameter of <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>
+ and <STRONG>tgetstr</STRONG> are compared in lookups.
+
+
+</PRE><H3><a name="h3-Formatting-Capabilities">Formatting Capabilities</a></H3><PRE>
+ The <STRONG>tgoto</STRONG> routine expands the given capability using the parameters.
+
+ <STRONG>o</STRONG> Because the capability may have padding characters, the output of
+ <STRONG>tgoto</STRONG> should be passed to <STRONG>tputs</STRONG> rather than some other output func-
+ tion such as <STRONG>printf(3)</STRONG>.
+
+ <STRONG>o</STRONG> While <STRONG>tgoto</STRONG> is assumed to be used for the two-parameter cursor po-
+ sitioning capability, termcap applications also use it for single-
+ parameter capabilities.
+
+ Doing this shows a quirk in <STRONG>tgoto</STRONG>: most hardware terminals use cur-
+ sor addressing with <EM>row</EM> first, but the original developers of the
+ termcap interface chose to put the <EM>column</EM> parameter first. The
+ <STRONG>tgoto</STRONG> function swaps the order of parameters. It does this also
+ for calls requiring only a single parameter. In that case, the
+ first parameter is merely a placeholder.
+
+ <STRONG>o</STRONG> Normally the ncurses library is compiled with terminfo support. In
+ that case, <STRONG>tgoto</STRONG> uses <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> (a more capable formatter).
+
+ However, <STRONG>tparm</STRONG> is not a <EM>termcap</EM> feature, and portable <EM>termcap</EM> ap-
+ plications should not rely upon its availability.
+
+ The <STRONG>tputs</STRONG> routine is described on the <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> manual page.
+ It can retrieve capabilities by either termcap or terminfo name.
+
+
+</PRE><H3><a name="h3-Global-Variables">Global Variables</a></H3><PRE>
+ The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the terminfo entry's
+ data for <STRONG>pad_char</STRONG>, <STRONG>cursor_up</STRONG> and <STRONG>backspace_if_not_bs</STRONG>, respectively. <STRONG>UP</STRONG>
+ is not used by ncurses. <STRONG>PC</STRONG> is used in the <STRONG>tdelay_output</STRONG> function. <STRONG>BC</STRONG>
+ is used in the <STRONG>tgoto</STRONG> emulation. The variable <STRONG>ospeed</STRONG> is set by ncurses
+ in a system-specific coding to reflect the terminal speed.
+
+
+</PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE>
+ The termcap functions provide no means for freeing memory, because
+ legacy termcap implementations used only the buffer areas provided by
+ the caller via <STRONG>tgetent</STRONG> and <STRONG>tgetstr</STRONG>. Those buffers are unused in ter-
+ minfo.
+
+ On the other hand, terminfo allocates memory. It uses <STRONG>setupterm</STRONG> to re-
+ trieve the data used by <STRONG>tgetent</STRONG> and the functions which return capabil-
+ ity values such as <STRONG>tgetstr</STRONG>. One could use
+
+ <STRONG>del_curterm(cur_term);</STRONG>
+
+
+ to free this memory, but there is an additional complication with
+ ncurses. It uses a fixed-size <EM>pool</EM> of storage locations, one per set-
+ ting of the <STRONG>TERM</STRONG> variable when <STRONG>tgetent</STRONG> is called. The <STRONG>screen(1)</STRONG> pro-
+ gram relies upon this arrangement, to improve its performance.
+
+ An application which uses only the low-level termcap functions could
+ free the memory using <STRONG>del_curterm</STRONG>, because the pool is freed using oth-
+ er functions (see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>).
+
+
+</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
+ Except where explicitly noted, routines that return an integer return
+ <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 only specifies "an integer value other
+ than <STRONG>ERR</STRONG>") upon successful completion.