-<!--
+<!--
****************************************************************************
- * Copyright 2018,2020 Thomas E. Dickey *
+ * Copyright 2018-2022,2022 Thomas E. Dickey *
* Copyright 1998-2016,2017 Free Software Foundation, Inc. *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_terminfo.3x,v 1.67 2020/11/07 23:49:07 tom Exp @
+ * @Id: curs_terminfo.3x,v 1.81 2022/02/12 20:05:11 tom Exp @
+ * ***************************************************************************
+ * ***************************************************************************
+ * ***************************************************************************
+ * ***************************************************************************
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>curs_terminfo 3x</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+
</HEAD>
<BODY>
<H1 class="no-header">curs_terminfo 3x</H1>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
- <STRONG>del_curterm</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>setterm</STRONG>, <STRONG>setupterm</STRONG>,
+ <STRONG>del_curterm</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>setupterm</STRONG>,
<STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tparm</STRONG>, <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>,
<STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> - <STRONG>curses</STRONG> interfaces to terminfo database
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
+ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
<STRONG>#include</STRONG> <STRONG><term.h></STRONG>
<STRONG>TERMINAL</STRONG> <STRONG>*cur_term;</STRONG>
<STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strfnames[];</STRONG>
<STRONG>int</STRONG> <STRONG>setupterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
- <STRONG>int</STRONG> <STRONG>setterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG>
<STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>restartterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
which uses all the defaults and sends the output to <STRONG>stdout</STRONG>.
- The <STRONG>setterm</STRONG> routine was replaced by <STRONG>setupterm</STRONG>. The call:
-
- <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
-
- provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>. The <STRONG>setterm</STRONG> routine
- is provided for BSD compatibility, and is not recommended for new pro-
- grams.
-
</PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE>
The <STRONG>setupterm</STRONG> routine stores its information about the terminal in a
<STRONG>o</STRONG> Aside from the <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>) capability, most terminal capa-
bilities require no more than one or two parameters.
+ <STRONG>o</STRONG> Padding information is ignored by <STRONG>tparm</STRONG>; it is interpreted by
+ <STRONG>tputs</STRONG>.
+
+ <STRONG>o</STRONG> The capability string is null-terminated. Use "\200" where an
+ ASCII NUL is needed in the output.
+
<STRONG>tiparm</STRONG> is a newer form of <STRONG>tparm</STRONG> which uses <EM><stdarg.h></EM> rather than a
fixed-parameter list. Its numeric parameters are integers (int) rather
than longs.
</PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE>
- The <STRONG>tputs</STRONG> routine applies padding information to the string <EM>str</EM> and
- outputs it:
+ The <STRONG>tputs</STRONG> routine applies padding information (i.e., by interpreting
+ marker embedded in the terminfo capability such as "$<5>" as 5 mil-
+ liseconds) to the string <EM>str</EM> and outputs it:
- <STRONG>o</STRONG> The <EM>str</EM> parameter must be a terminfo string variable or the return
+ <STRONG>o</STRONG> The <EM>str</EM> parameter must be a terminfo string variable or the return
value from <STRONG>tparm</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>.
- The <STRONG>tgetstr</STRONG> and <STRONG>tgoto</STRONG> functions are part of the <EM>termcap</EM> interface,
- which happens to share this function name with the <EM>terminfo</EM> inter-
+ The <STRONG>tgetstr</STRONG> and <STRONG>tgoto</STRONG> functions are part of the <EM>termcap</EM> interface,
+ which happens to share this function name with the <EM>terminfo</EM> inter-
face.
<STRONG>o</STRONG> <EM>affcnt</EM> is the number of lines affected, or 1 if not applicable.
- <STRONG>o</STRONG> <EM>putc</EM> is a <STRONG>putchar</STRONG>-like routine to which the characters are passed,
+ <STRONG>o</STRONG> <EM>putc</EM> is a <STRONG>putchar</STRONG>-like routine to which the characters are passed,
one at a time.
- The <STRONG>putp</STRONG> routine calls <STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>. The output of <STRONG>putp</STRONG> al-
+ The <STRONG>putp</STRONG> routine calls <STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>. The output of <STRONG>putp</STRONG> al-
ways goes to <STRONG>stdout</STRONG>, rather than the <EM>filedes</EM> specified in <STRONG>setupterm</STRONG>.
- The <STRONG>vidputs</STRONG> routine displays the string on the terminal in the video
+ The <STRONG>vidputs</STRONG> routine displays the string on the terminal in the video
attribute mode <EM>attrs</EM>, which is any combination of the attributes listed
- in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>. The characters are passed to the <STRONG>putchar</STRONG>-like routine
+ in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>. The characters are passed to the <STRONG>putchar</STRONG>-like routine
<EM>putc</EM>.
The <STRONG>vidattr</STRONG> routine is like the <STRONG>vidputs</STRONG> routine, except that it outputs
through <STRONG>putchar</STRONG>.
- The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines correspond to vidattr and vidputs,
- respectively. They use a set of arguments for representing the video
+ The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines correspond to vidattr and vidputs,
+ respectively. They use a set of arguments for representing the video
attributes plus color, i.e.,
<STRONG>o</STRONG> <EM>attrs</EM> of type <STRONG>attr_t</STRONG> for the attributes and
<STRONG>o</STRONG> <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
- The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines are designed to use the attribute
- constants with the <EM>WA</EM><STRONG>_</STRONG> prefix.
+ The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines are designed to use the attribute
+ constants with the <STRONG>WA_</STRONG> prefix.
- X/Open Curses reserves the <EM>opts</EM> argument for future use, saying that
- applications must provide a null pointer for that argument. As an ex-
- tension, this implementation allows <EM>opts</EM> to be used as a pointer to
+ X/Open Curses reserves the <EM>opts</EM> argument for future use, saying that
+ applications must provide a null pointer for that argument. As an ex-
+ tension, this implementation allows <EM>opts</EM> to be used as a pointer to
<STRONG>int</STRONG>, which overrides the <EM>pair</EM> (<STRONG>short</STRONG>) argument.
- The <STRONG>mvcur</STRONG> routine provides low-level cursor motion. It takes effect
+ The <STRONG>mvcur</STRONG> routine provides low-level cursor motion. It takes effect
immediately (rather than at the next refresh).
+ While <STRONG>putp</STRONG> and <STRONG>mvcur</STRONG> are low-level functions which do not use the high-
+ level curses state, they are declared in <STRONG><curses.h></STRONG> because SystemV did
+ this (see <EM>HISTORY</EM>).
+
</PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE>
- The <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines return the value of the
- capability corresponding to the <STRONG>terminfo</STRONG> <EM>capname</EM> passed to them, such
- as <STRONG>xenl</STRONG>. The <EM>capname</EM> for each capability is given in the table column
+ The <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG> and <STRONG>tigetstr</STRONG> routines return the value of the
+ capability corresponding to the <STRONG>terminfo</STRONG> <EM>capname</EM> passed to them, such
+ as <STRONG>xenl</STRONG>. The <EM>capname</EM> for each capability is given in the table column
entitled <EM>capname</EM> code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
These routines return special values to denote errors.
<STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>
+</PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE>
+ Each successful call to <STRONG>setupterm</STRONG> allocates memory to hold the terminal
+ description. As a side-effect, it sets <STRONG>cur_term</STRONG> to point to this memo-
+ ry. If an application calls
+
+ <STRONG>del_curterm(cur_term);</STRONG>
+
+ the memory will be freed.
+
+ The formatting functions <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> extend the storage allocated
+ by <STRONG>setupterm</STRONG>:
+
+ <STRONG>o</STRONG> the "static" terminfo variables [a-z]. Before ncurses 6.3, those
+ were shared by all screens. With ncurses 6.3, those are allocated
+ per screen. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for details.
+
+ <STRONG>o</STRONG> to improve performance, ncurses 6.3 caches the result of analyzing
+ terminfo strings for their parameter types. That is stored as a
+ binary tree referenced from the <STRONG>TERMINAL</STRONG> structure.
+
+ The higher-level <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> functions use <STRONG>setupterm</STRONG>. Normally
+ they do not free this memory, but it is possible to do that using the
+ <STRONG><A HREF="curs_initscr.3x.html">delscreen(3x)</A></STRONG> function.
+
+
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
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 com-
value of the output function <EM>putc</EM>.
+</PRE><H3><a name="h3-Compatibility-macros">Compatibility macros</a></H3><PRE>
+ This implementation provides a few macros for compatibility with sys-
+ tems before SVr4 (see <EM>HISTORY</EM>). Those include <STRONG>crmode</STRONG>, <STRONG>fixterm</STRONG>,
+ <STRONG>gettmode</STRONG>, <STRONG>nocrmode</STRONG>, <STRONG>resetterm</STRONG>, <STRONG>saveterm</STRONG>, and <STRONG>setterm</STRONG>.
+
+ In SVr4, those are found in <STRONG><curses.h></STRONG>, but except for <STRONG>setterm</STRONG>, are
+ likewise macros. The one function, <STRONG>setterm</STRONG>, is mentioned in the manual
+ page. The manual page notes that the <STRONG>setterm</STRONG> routine was replaced by
+ <STRONG>setupterm</STRONG>, stating that the call:
+
+ <STRONG>setupterm(</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0)</STRONG>
+
+ provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>, and is not recommend-
+ ed for new programs. This implementation provides each of those sym-
+ bols as macros for BSD compatibility,
+
+
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
SVr2 introduced the terminfo feature. Its programming manual mentioned
these low-level functions:
fixterm restore tty to "in curses" state
gettmode establish current tty modes
mvcur low level cursor motion
- putp utility function that uses <STRONG>tputs</STRONG> to send char-
+ putp utility function that uses <STRONG>tputs</STRONG> to send char-
acters via <STRONG>putchar</STRONG>.
resetterm set tty modes to "out of curses" state
resetty reset tty flags to stored value
saveterm save current modes as "in curses" state
savetty store current tty flags
setterm establish terminal with given type
-
setupterm establish terminal with given type
tparm instantiate a string expression with parameters
tputs apply padding information to a string
vidattr like <STRONG>vidputs</STRONG>, but outputs through <STRONG>putchar</STRONG>
- vidputs output a string to put terminal in a specified
+ vidputs output a string to put terminal in a specified
video attribute mode
- The programming manual also mentioned functions provided for termcap
+ The programming manual also mentioned functions provided for termcap
compatibility (commenting that they "may go away at a later date"):
<STRONG>Function</STRONG> <STRONG>Description</STRONG>
tputs apply padding to capability, calling
a function to put characters
- Early terminfo programs obtained capability values from the <STRONG>TERMINAL</STRONG>
+ Early terminfo programs obtained capability values from the <STRONG>TERMINAL</STRONG>
structure initialized by <STRONG>setupterm</STRONG>.
- SVr3 extended terminfo by adding functions to retrieve capability val-
+ SVr3 extended terminfo by adding functions to retrieve capability val-
ues (like the termcap interface), and reusing tgoto and tputs:
<STRONG>Function</STRONG> <STRONG>Description</STRONG>
-------------------------------------------
tigetflag get boolean entry for given <EM>id</EM>
+
tigetnum get numeric entry for given <EM>id</EM>
tigetstr get string entry for given <EM>id</EM>
- SVr3 also replaced several of the SVr2 terminfo functions which had no
+ SVr3 also replaced several of the SVr2 terminfo functions which had no
counterpart in the termcap interface, documenting them as obsolete:
<STRONG>Function</STRONG> <STRONG>Replaced</STRONG> <STRONG>by</STRONG>
saveterm def_prog_mode
setterm setupterm
- SVr3 kept the <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> functions, along with <STRONG>putp</STRONG>,
- <STRONG>tparm</STRONG> and <STRONG>tputs</STRONG>. The latter were needed to support padding, and han-
- dling functions such as <STRONG>vidattr</STRONG> (which used more than the two parame-
+ SVr3 kept the <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> functions, along with <STRONG>putp</STRONG>,
+ <STRONG>tparm</STRONG> and <STRONG>tputs</STRONG>. The latter were needed to support padding, and han-
+ dling functions such as <STRONG>vidattr</STRONG> (which used more than the two parame-
ters supported by <STRONG>tgoto</STRONG>).
- SVr3 introduced the functions for switching between terminal descrip-
- tions, e.g., <STRONG>set_curterm</STRONG>. The various global variables such as <STRONG>bool-</STRONG>
- <STRONG>names</STRONG> were mentioned in the programming manual at this point.
+ SVr3 introduced the functions for switching between terminal descrip-
+ tions, e.g., <STRONG>set_curterm</STRONG>. Some of that was incremental improvements to
+ the SVr2 library:
+
+ <STRONG>o</STRONG> The <STRONG>TERMINAL</STRONG> type definition was introduced in SVr3.01, for the
+ <STRONG>term</STRONG> structure provided in SVr2.
+
+ <STRONG>o</STRONG> The various global variables such as <STRONG>boolnames</STRONG> were mentioned in
+ the programming manual at this point, though the variables were
+ provided in SVr2.
SVr4 added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions.
There are other low-level functions declared in the curses header files
on Unix systems, but none were documented. The functions marked "obso-
- lete" remained in use by the Unix <STRONG>vi</STRONG> editor.
+ lete" remained in use by the Unix <STRONG>vi(1)</STRONG> editor.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>,
- <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>,
+ <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG>ter-</STRONG>
+ <STRONG><A HREF="terminfo.5.html">minfo(5)</A></STRONG>
<li><a href="#h3-Output-Functions">Output Functions</a></li>
<li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li>
<li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li>
+<li><a href="#h3-Releasing-Memory">Releasing Memory</a></li>
+</ul>
+</li>
+<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a>
+<ul>
+<li><a href="#h3-Compatibility-macros">Compatibility macros</a></li>
</ul>
</li>
-<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
projects / ncurses.git / blobdiff