* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_terminfo.3x,v 1.122 2023/12/03 00:10:20 tom Exp @
+ * @Id: curs_terminfo.3x,v 1.124 2023/12/23 17:34:39 tom Exp @
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
+ * See X/Open Curses Issue 4, Version 2, pp. 227-234.
+ * See X/Open Curses Issue 7, pp. 311-318.
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
-<TITLE>curs_terminfo 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_terminfo 3x 2023-12-23 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_terminfo 3x 2023-12-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_terminfo 3x 2023-12-23 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></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>
- <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
- <EM>or</EM>
- <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>long</STRONG> <EM>p1</EM> <EM>...</EM> <STRONG>long</STRONG> <EM>p9</EM><STRONG>);</STRONG>
+ <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG>
+ <EM>/*</EM> <EM>or</EM> <EM>*/</EM>
+ <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>long</STRONG> <EM>p1</EM> ... <STRONG>long</STRONG> <EM>p9</EM><STRONG>);</STRONG>
<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>
<STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
<STRONG>char</STRONG> <STRONG>*tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
- <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
+ <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG>
<EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
<STRONG>char</STRONG> <STRONG>*tiparm_s(int</STRONG> <EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
<STRONG>int</STRONG> <STRONG>tiscan_s(int</STRONG> <STRONG>*</STRONG><EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
+ <EM>/*</EM> <EM>deprecated</EM> <EM>*/</EM>
+ <STRONG>int</STRONG> <STRONG>setterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG>
+
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
These low-level routines must be called by programs that have to deal
</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>TERMINAL</STRONG> structure pointed to by the global variable <STRONG>cur_term</STRONG>. If it
+ <EM>TERMINAL</EM> structure pointed to by the global variable <STRONG>cur_term</STRONG>. If it
detects an error, or decides that the terminal is unsuitable (hardcopy
or generic), it discards this information, making it not available to
applications.
<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 <EM>putchar</EM>-like function to which the characters are passed,
one at a time.
If <STRONG>tputs</STRONG> processes a time-delay, it uses the <STRONG><A HREF="curs_util.3x.html">delay_output(3x)</A></STRONG>
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 <EM>putchar</EM>-like function
<EM>putc</EM>.
The <STRONG>vidattr</STRONG> routine is like the <STRONG>vidputs</STRONG> routine, except that it outputs
- through <STRONG>putchar</STRONG>.
+ through <EM>putchar</EM>.
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
<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.
+ <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 <STRONG>WA_</STRONG> prefix.
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
+ <STRONG>o</STRONG> the "static" terminfo variables [a-z]. Before <EM>ncurses</EM> 6.3, those
+ were shared by all screens. With <EM>ncurses</EM> 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
+ <STRONG>o</STRONG> to improve performance, <EM>ncurses</EM> 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.
+ binary tree referenced from the <EM>TERMINAL</EM> 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
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- X/Open notes that <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG> may be macros.
+ According to X/Open Curses, any of the <EM>enhanced</EM> <EM>curses</EM> functions may be
+ implemented as macros. The term "enhanced" refers to features not
+ found in SVr4 curses.
+
+ <STRONG>ncurses</STRONG> uses macros
+
+ <STRONG>o</STRONG> for functions which return values via their parameters,
+
+ <STRONG>o</STRONG> to support obsolete features,
+
+ <STRONG>o</STRONG> to reuse functions, e.g., those that move the cursor before another
+ operation, and
+
+ <STRONG>o</STRONG> a few special cases.
+
+ The <STRONG>vid_puts</STRONG> function in <STRONG>ncurses</STRONG> is a special case. It was originally
+ implemented based on a draft of X/Open Curses, as a macro, before other
+ parts of the <STRONG>ncurses</STRONG> wide-character API were developed.
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
- The functions marked as extensions were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and
- are not found in SVr4 curses, 4.4BSD curses, or any other previous
- version of curses.
+ The functions marked as extensions were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and
+ are not found in SVr4 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous
+ curses implementation.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- The function <STRONG>setterm</STRONG> is not described by X/Open and must be considered
- non-portable. All other functions are as described by X/Open.
+ <STRONG>setterm</STRONG> is not described by X/Open and must be considered non-portable.
+ All other functions are as described by X/Open.
-</PRE><H3><a name="h3-Compatibility-macros">Compatibility macros</a></H3><PRE>
- This implementation provides a few macros for compatibility with
- systems 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>.
+</PRE><H3><a name="h3-Compatibility-Macros">Compatibility Macros</a></H3><PRE>
+ This implementation provides a few macros for compatibility with
+ systems before SVr4 (see section "HISTORY" below). They include
+ <STRONG>Bcrmode</STRONG>, <STRONG>Bfixterm</STRONG>, <STRONG>Bgettmode</STRONG>, <STRONG>Bnocrmode</STRONG>, <STRONG>Bresetterm</STRONG>, <STRONG>Bsaveterm</STRONG>, and
+ <STRONG>Bsetterm</STRONG>.
- In SVr4, those are found in <STRONG><curses.h></STRONG>, but except for <STRONG>setterm</STRONG>, are
+ In SVr4, these are found in <EM>curses.h</EM>, 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
- recommended for new programs. This implementation provides each of
- those symbols as macros for BSD compatibility.
+ page. It further notes that <STRONG>setterm</STRONG> was replaced by <STRONG>setupterm</STRONG>, stating
+ that the call
+ setupterm(<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>, discouraging the
+ latter for new programs. <EM>ncurses</EM> implements each of these symbols as
+ macros for BSD <EM>curses</EM> compatibility.
-</PRE><H3><a name="h3-Legacy-
data">Legacy data</a></H3><PRE>
+</PRE><H3><a name="h3-Legacy-
Data">Legacy Data</a></H3><PRE>
<STRONG>setupterm</STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>. This is not
part of X/Open Curses, but is assumed by some applications.
stored in the arrays described here.
-</PRE><H3><a name="h3-Output-
buffering">Output buffering</a></H3><PRE>
- Older versions of <STRONG>ncurses</STRONG> assumed that the file descriptor passed to
+</PRE><H3><a name="h3-Output-
Buffering">Output Buffering</a></H3><PRE>
+ Older versions of <EM>ncurses</EM> assumed that the file descriptor passed to
<STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered I/O, and would write to
the corresponding stream. In addition to the limitation that the
terminal was left in block-buffered mode on exit (like System V
- curses), it was problematic because <STRONG>ncurses</STRONG> did not allow a reliable
+ curses), it was problematic because <EM>ncurses</EM> did not allow a reliable
way to cleanup on receiving SIGTSTP.
The current version (ncurses6) uses output buffers managed directly by
- <STRONG>ncurses</STRONG>. Some of the low-level functions described in this manual page
+ <EM>ncurses</EM>. Some of the low-level functions described in this manual page
write to the standard output. They are not signal-safe. The high-
- level functions in <STRONG>ncurses</STRONG> use alternate versions of these functions
+ level functions in <EM>ncurses</EM> use alternate versions of these functions
using the more reliable buffering scheme.
-</PRE><H3><a name="h3-Function-
prototypes">Function prototypes</a></H3><PRE>
+</PRE><H3><a name="h3-Function-
Prototypes">Function Prototypes</a></H3><PRE>
The X/Open Curses prototypes are based on the SVr4 curses header
declarations, which were defined at the same time the C language was
first standardized in the late 1980s.
In response to review comments by Thomas E. Dickey, X/Open Curses
Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009.
- While <STRONG>tiparm</STRONG> is always provided in ncurses, the older form is only
+ While <STRONG>tiparm</STRONG> is always provided in <EM>ncurses</EM>, the older form is only
available as a build-time configuration option. If not specially
configured, <STRONG>tparm</STRONG> is the same as <STRONG>tiparm</STRONG>.
parameters. However, only a few terminfo capabilities use string
parameters (e.g., the ones used for programmable function keys).
- The ncurses library checks usage of these capabilities, and returns
+ The <EM>ncurses</EM> library checks usage of these capabilities, and returns
an error if the capability mishandles string parameters. But it
cannot check if a calling program provides strings in the right
places for the <STRONG>tparm</STRONG> calls.
The <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> program checks its use of these capabilities with a
table, so that it calls <STRONG>tparm</STRONG> correctly.
-
-</PRE><H3><a name="h3-Special-TERM-treatment">Special TERM treatment</a></H3><PRE>
+ <STRONG>Special</STRONG> <EM>TERM</EM> <STRONG>treatment</STRONG>
If configured to use the terminal-driver, e.g., for the MinGW port,
<STRONG>o</STRONG> <STRONG>setupterm</STRONG> interprets a missing/empty <EM>TERM</EM> variable as the special
string.
-</PRE><H3><a name="h3-Other-
portability-issues">Other portability issues</a></H3><PRE>
+</PRE><H3><a name="h3-Other-
Portability-Issues">Other Portability Issues</a></H3><PRE>
In System V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type and returns
<STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. We have chosen to implement the X/Open Curses semantics.
X/Open notes that after calling <STRONG>mvcur</STRONG>, the curses state may not match
the actual terminal state, and that an application should touch and
- refresh the window before resuming normal curses calls. Both <STRONG>ncurses</STRONG>
- and System V Release 4 curses implement <STRONG>mvcur</STRONG> using the SCREEN data
+ refresh the window before resuming normal curses calls. Both <EM>ncurses</EM>
+ and System V Release 4 curses implement <STRONG>mvcur</STRONG> using the <EM>SCREEN</EM> data
allocated in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. So though it is documented as
a terminfo function, <STRONG>mvcur</STRONG> is really a curses function which is not
well specified.
<STRONG>fixterm</STRONG> restore tty to "in curses" state
<STRONG>gettmode</STRONG> establish current tty modes
<STRONG>mvcur</STRONG> low level cursor motion
-
<STRONG>putp</STRONG> utility function that uses <STRONG>tputs</STRONG> to send characters via
- <STRONG>putchar</STRONG>.
+ <EM>putchar</EM>.
<STRONG>resetterm</STRONG> set tty modes to "out of curses" state
<STRONG>resetty</STRONG> reset tty flags to stored value
<STRONG>saveterm</STRONG> save current modes as "in curses" state
<STRONG>setupterm</STRONG> establish terminal with given type
<STRONG>tparm</STRONG> instantiate a string expression with parameters
<STRONG>tputs</STRONG> apply padding information to a string
- <STRONG>vidattr</STRONG> like <STRONG>vidputs</STRONG>, but outputs through <STRONG>putchar</STRONG>
+ <STRONG>vidattr</STRONG> like <STRONG>vidputs</STRONG>, but outputs through <EM>putchar</EM>
<STRONG>vidputs</STRONG> output a string to put terminal in a specified video
attribute mode
<STRONG>tputs</STRONG> 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 <EM>TERMINAL</EM>
structure initialized by <STRONG>setupterm</STRONG>.
SVr3 extended terminfo by adding functions to retrieve capability
<STRONG>Function</STRONG> <STRONG>Description</STRONG>
------------------------------------------------------------------------
+
<STRONG>tigetflag</STRONG> get boolean entry for given <EM>id</EM>
<STRONG>tigetnum</STRONG> get numeric entry for given <EM>id</EM>
<STRONG>tigetstr</STRONG> get string entry for given <EM>id</EM>
descriptions, 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>o</STRONG> The <EM>TERMINAL</EM> 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
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
+ncurses 6.4 2023-12-
23 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
-<li><a href="#h3-Compatibility-macros">Compatibility macros</a></li>
-<li><a href="#h3-Legacy-data">Legacy data</a></li>
-<li><a href="#h3-Output-buffering">Output buffering</a></li>
-<li><a href="#h3-Function-prototypes">Function prototypes</a></li>
-<li><a href="#h3-Special-TERM-treatment">Special TERM treatment</a></li>
-<li><a href="#h3-Other-portability-issues">Other portability issues</a></li>
+<li><a href="#h3-Compatibility-Macros">Compatibility Macros</a></li>
+<li><a href="#h3-Legacy-Data">Legacy Data</a></li>
+<li><a href="#h3-Output-Buffering">Output Buffering</a></li>
+<li><a href="#h3-Function-Prototypes">Function Prototypes</a></li>
+<li><a href="#h3-Other-Portability-Issues">Other Portability Issues</a></li>
</ul>
</li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
projects / ncurses.git / blobdiff