+ improve formatting/style of manpages (patches by Branden Robinson).
+ add ms-vt100-16color, winconsole -TD
+ add rio, rio-direct -TD
+ add mostlike -TD
+ add wezterm, contour -TD
-- sale, use or other dealings in this Software without prior written --
-- authorization. --
-------------------------------------------------------------------------------
--- $Id: NEWS,v 1.4055 2023/12/23 21:00:43 tom Exp $
+-- $Id: NEWS,v 1.4057 2023/12/31 00:17:55 tom Exp $
-------------------------------------------------------------------------------
This is a log of changes that ncurses has gone through since Zeyd started
Changes through 1.9.9e did not credit all contributions;
it is not possible to add this information.
+20231230
+ + improve formatting/style of manpages (patches by Branden Robinson).
+ + add ms-vt100-16color, winconsole -TD
+ + add rio, rio-direct -TD
+ + add mostlike -TD
+ + add wezterm, contour -TD
+
20231223
+ improve formatting/style of manpages (patches by Branden Robinson).
-5:0:10 6.4 20231223
+5:0:10 6.4 20231230
<!--
- $Id: announce.html.in,v 1.105 2023/12/02 21:45:06 tom Exp $
+ $Id: announce.html.in,v 1.106 2023/12/30 21:24:48 tom Exp $
****************************************************************************
* Copyright 2018-2022,2023 Thomas E. Dickey *
* *
</li>
<li>
- <p>The library meets the XSI requirement that every macro
- entry point has a corresponding function which may be linked
- (and will be prototype-checked) if the macro definition is
- disabled with <code>#undef</code>.</p>
+ <p>The library meets the X/Open Curses requirement that every
+ function declared in a header file has a macro equivalent.
+ If the macro definition is disabled with <code>#undef</code>,
+ the function may be linked (and its calls will be checked
+ against the prototype).</p>
</li>
<li>
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: dist.mk,v 1.1585 2023/12/23 11:35:00 tom Exp $
+# $Id: dist.mk,v 1.1586 2023/12/30 11:24:34 tom Exp $
# Makefile for creating ncurses distributions.
#
# This only needs to be used directly as a makefile by developers, but
# These define the major/minor/patch versions of ncurses.
NCURSES_MAJOR = 6
NCURSES_MINOR = 4
-NCURSES_PATCH = 20231223
+NCURSES_PATCH = 20231230
# We don't append the patch to the version, since this only applies to releases
VERSION = $(NCURSES_MAJOR).$(NCURSES_MINOR)
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_color.3x,v 1.95 2023/12/23 20:18:13 tom Exp @
+ * @Id: curs_color.3x,v 1.96 2023/12/30 21:20:01 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<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_color 3x 2023-12-23 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_color 3x 2023-12-30 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_color 3x 2023-12-23 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_color 3x 2023-12-30 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
<STRONG>o</STRONG> window attributes, as from <STRONG><A HREF="curs_attr.3x.html">wattrset(3x)</A></STRONG> or <STRONG><A HREF="curs_attr.3x.html">wattr_set(3x)</A></STRONG>
- <STRONG>o</STRONG> window background character att
tributes, as from <STRONG><A HREF="curs_bkgd.3x.html">wbkgdset(3x)</A></STRONG> or
+ <STRONG>o</STRONG> window background character att
ributes, as from <STRONG><A HREF="curs_bkgd.3x.html">wbkgdset(3x)</A></STRONG> or
<STRONG><A HREF="curs_bkgrnd.3x.html">wbkgrndset(3x)</A></STRONG>
Per-character and window attributes are usually set through a function
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_inwstr.3x,v 1.35 2023/11/25 11:31:49 tom Exp @
+ * @Id: curs_inwstr.3x,v 1.36 2023/12/30 21:32:48 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<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_inwstr 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_inwstr 3x 2023-12-30 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_inwstr 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_inwstr 3x 2023-12-30 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
All routines except <STRONG>winnwstr</STRONG> may be macros.
- Each cell in the window holds a complex character (i.e., base- and
- combining-characters) together with attributes and color. These
- functions store only the wide characters, ignoring attributes and
- color. Use <STRONG>in_wchstr</STRONG> to return the complex characters from a window.
+ Each cell in the window holds a complex character (a spacing character
+ and zero or more non-spacing characters) together with attributes and
+ color. These functions store only the wide characters, ignoring
+ attributes and color. Use <STRONG>in_wchstr</STRONG> to return the complex characters
+ from a window.
Reading a line that overflows the array pointed to by <EM>wstr</EM> with <STRONG>inwstr</STRONG>,
- <STRONG>mvinwstr</STRONG>, <STRONG>mvwinwstr</STRONG> or <STRONG>winwstr</STRONG> causes undefined results. Therefore,
+ <STRONG>mvinwstr</STRONG>, <STRONG>mvwinwstr</STRONG> or <STRONG>winwstr</STRONG> causes undefined results. Therefore,
the use of <STRONG>innwstr</STRONG>, <STRONG>mvinnwstr</STRONG>, <STRONG>mvwinnwstr</STRONG>, or <STRONG>winnwstr</STRONG> is recommended.
</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_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>, <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>,
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,
<STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>, <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>,
<STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-30 <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_scr_dump.3x,v 1.36 2023/12/16 21:10:18 tom Exp @
+ * @Id: curs_scr_dump.3x,v 1.37 2023/12/30 21:34:11 tom Exp @
+ * SVID 4, p. 529
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<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_scr_dump 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_scr_dump 3x 2023-12-30 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_scr_dump 3x 2023-12-16 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_scr_dump 3x 2023-12-30 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+ <EM>curses</EM> provides applications the ability to write the contents of the
+ screen to a file and read them back. To read/write a window (rather
+ than the whole screen) from/to a file, use <STRONG><A HREF="curs_util.3x.html">getwin(3x)</A></STRONG> and <STRONG><A HREF="curs_util.3x.html">putwin(3x)</A></STRONG>,
+ respectively.
+
</PRE><H3><a name="h3-scr_dump">scr_dump</a></H3><PRE>
- The <STRONG>scr_dump</STRONG> routine dumps the current contents of the <EM>virtual</EM> <EM>screen</EM>
- to the file <EM>filename</EM>.
+ <STRONG>scr_dump</STRONG> writes to <EM>filename</EM> the contents of the virtual screen; see
+ <STRONG><A HREF="curs_variables.3x.html">curscr(3x)</A></STRONG>.
</PRE><H3><a name="h3-scr_restore">scr_restore</a></H3><PRE>
- The <STRONG>scr_restore</STRONG> routine sets the <EM>virtual</EM> <EM>screen</EM> to the contents of
- <EM>filename</EM>, which must have been written using <STRONG>scr_dump</STRONG>. The next call
- to <STRONG>doupdate</STRONG> restores the <EM>physical</EM> <EM>screen</EM> to the way it looked in the
- dump file.
+ <STRONG>scr_restore</STRONG> updates the virtual screen to contain the contents of
+ <EM>filename</EM> (if it was validly written with <STRONG>scr_dump</STRONG>). No refresh is
+ performed; after performing any further desired updates, call
+ <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> or similar.
</PRE><H3><a name="h3-scr_init">scr_init</a></H3><PRE>
- The <STRONG>scr_init</STRONG> routine reads in the contents of <EM>filename</EM> and uses them to
- initialize the <STRONG>curses</STRONG> data structures about what the terminal currently
- has on its screen. If the data is determined to be valid, <STRONG>curses</STRONG> bases
- its next update of the screen on this information rather than clearing
- the screen and starting from scratch. <STRONG>scr_init</STRONG> is used after
- <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or a <STRONG>system(3)</STRONG> call to share the screen with another
- process which has done a <STRONG>scr_dump</STRONG> after its <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> call. The data
- is declared invalid
+ <STRONG>scr_init</STRONG> reads <EM>filename,</EM> using it to initialize <EM>curses</EM> data structures
+ describing the state of the terminal screen. If these data are valid,
+ <EM>curses</EM> bases its next update of the screen on this information rather
+ than clearing it and starting from scratch.
+
+ The data fail the validity check
+
+ <STRONG>o</STRONG> if the terminal employs <EM>terminfo</EM> capabilities <STRONG>exit_ca_mode</STRONG> (<STRONG>rmcup</STRONG>)
+ or <STRONG>non_rev_rmcup</STRONG> (<STRONG>nrrmc</STRONG>) are defined, or
- <STRONG>o</STRONG> if the terminfo capabilities <STRONG>rmcup</STRONG> and <STRONG>nrrmc</STRONG> exist, also
+ <STRONG>o</STRONG> if <EM>curses</EM> knows that the terminal has been written to since the
+ preceding <STRONG>scr_dump</STRONG> call.
- <STRONG>o</STRONG> if the terminal has been written to since the preceding <STRONG>scr_dump</STRONG>
- call.
+ <STRONG>scr_init</STRONG> could be used after <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG>system(3)</STRONG> to share the
+ screen with another process that has done a <STRONG>scr_dump</STRONG> after <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG>.
</PRE><H3><a name="h3-scr_set">scr_set</a></H3><PRE>
- The <STRONG>scr_set</STRONG> routine is a combination of <STRONG>scr_restore</STRONG> and <STRONG>scr_init</STRONG>. It
+ The <STRONG>scr_set</STRONG> routine is a combination of <STRONG>scr_restore</STRONG> and <STRONG>scr_init</STRONG>. It
tells the program that the information in <EM>filename</EM> is what is currently
on the screen, and also what the program wants on the screen. This can
be thought of as a screen inheritance function.
- To read (write) a window from (to) a file, use the <STRONG>getwin</STRONG> and <STRONG>putwin</STRONG>
- routines [see <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>].
-
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- These routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
+ These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
- X/Open defines no error conditions. In this implementation, each will
- return an error if the file cannot be opened.
+ X/Open defines no failure conditions. In this implementation, each
+ function fails if it cannot open <EM>filename.</EM>
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- Note that <STRONG>scr_init</STRONG>, <STRONG>scr_set</STRONG>, and <STRONG>scr_restore</STRONG> may be macros.
+ <STRONG>scr_init</STRONG>, <STRONG>scr_set</STRONG>, and <STRONG>scr_restore</STRONG> may be macros.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These functions are described in the XSI Curses standard, Issue 4,
- which adds <EM>const</EM> qualifiers to the arguments.
+ X/Open Curses, Issue 4, describes these functions.
+
+ SVr4 omitted the <EM>const</EM> qualifiers.
- The SVr4 docs merely say under <STRONG>scr_init</STRONG> that the dump data is also
- considered invalid "if the time-stamp of the tty is old" but do not
+ SVr4 documentation describes <STRONG>scr_init</STRONG> such that the dump data is also
+ considered invalid "if the time-stamp of the tty is old" but does not
define "old".
-ncurses 6.4 2023-12-
16 <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_termcap.3x,v 1.80 2023/12/23 20:19:05 tom Exp @
+ * @Id: curs_termcap.3x,v 1.81 2023/12/30 21:27:22 tom Exp @
* See <https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/\
* termlib/termcap.c>.
* See https://www.oreilly.com/openbook/opensources/book/kirkmck.html
<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_termcap 3x 2023-12-23 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_termcap 3x 2023-12-30 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_termcap 3x 2023-12-23 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_termcap 3x 2023-12-30 ncurses 6.4 Library calls</H1>
<PRE>
<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>
program. The library remained much the same though 4.3BSD (June 1986).
4.4BSD-Lite (June 1994) refactored it, leaving the API unchanged.
- Function prototypes were a feature of ANSI C (1989). Thus the library
- itself provided no header file declaring them. Nevertheless, the BSD
- sources included two different <EM>termcap.h</EM> header files over time.
+ Function prototypes were a feature of ANSI C (1989). The library long
+ antedated the standard and thus provided no header file declaring them.
+ Nevertheless, the BSD sources included two different <EM>termcap.h</EM> header
+ files over time.
- <STRONG>o</STRONG> One was used internally by <STRONG>jove(1)</STRONG> from 4.3BSD onward. It delcared
+ <STRONG>o</STRONG> One was used internally by <STRONG>jove(1)</STRONG> from 4.3BSD onward. It declared
global symbols for the <EM>termcap</EM> variables that it used.
- <STRONG>o</STRONG> The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part of
- <EM>libedit</EM> (also known as the <EM>editline</EM> library). CSRG source history
+ <STRONG>o</STRONG> The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part of
+ <EM>libedit</EM> (also known as the <EM>editline</EM> library). CSRG source history
shows that this was added in mid-1992. The <EM>libedit</EM> header file was
used internally as a convenience for compiling the <EM>editline</EM>
library. It declared function prototypes, but no global variables.
This header file was added to NetBSD's <EM>termcap</EM> library in mid-1994.
- Meanwhile, GNU <EM>termcap</EM> began development in 1990. Its first release
- (1.0) in 1991 included a <EM>termcap.h</EM> header. Its second (1.1) in
- September 1992 modified the header to use <EM>const</EM> for the function
- prototypes in the header where one would expect the parameters to be
+ Meanwhile, GNU <EM>termcap</EM> began development in 1990. Its first release
+ (1.0) in 1991 included a <EM>termcap.h</EM> header. Its second (1.1) in
+ September 1992 modified the header to use <EM>const</EM> for the function
+ prototypes in the header where one would expect the parameters to be
read-only. BSD <EM>termcap</EM> did not. The prototype for <STRONG>tputs</STRONG> also
- differed, but in that instance, it was <EM>libedit</EM> that differed from BSD
+ differed, but in that instance, it was <EM>libedit</EM> that differed from BSD
<EM>termcap</EM>.
- GNU <EM>termcap</EM> 1.3 was bundled with <STRONG>bash(1)</STRONG> in mid-1993 to support the
+ GNU <EM>termcap</EM> 1.3 was bundled with <STRONG>bash(1)</STRONG> in mid-1993 to support the
<STRONG>readline(3)</STRONG> library.
- <EM>ncurses</EM> 1.8.1 (November 1993) provided a <EM>termcap.h</EM> file. It reflected
- influence from GNU <EM>termcap</EM> and <STRONG>emacs(1)</STRONG> (rather than <STRONG>jove(1)</STRONG>),
+ <EM>ncurses</EM> 1.8.1 (November 1993) provided a <EM>termcap.h</EM> file. It reflected
+ influence from GNU <EM>termcap</EM> and <STRONG>emacs(1)</STRONG> (rather than <STRONG>jove(1)</STRONG>),
providing the following interface:
<STRONG>o</STRONG> global symbols used by <EM>emacs</EM>,
<STRONG>o</STRONG> a prototype for <STRONG>tparam</STRONG>, a GNU <EM>termcap</EM> feature.
- Later (in mid-1996) the <STRONG>tparam</STRONG> function was removed from <EM>ncurses</EM>. Any
- two of the four implementations thus differ, and programs that intend
+ Later (in mid-1996) the <STRONG>tparam</STRONG> function was removed from <EM>ncurses</EM>. Any
+ two of the four implementations thus differ, and programs that intend
to work with all <EM>termcap</EM> library interfaces must account for that fact.
</PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>column_address</STRONG> (<STRONG>ch</STRONG>) or any other
- parameterized string capability, be aware that it is returned in <EM>term-</EM>
+ parameterized string capability, be aware that it is returned in <EM>term-</EM>
<EM>info</EM> notation, not the older and not-quite-compatible <EM>termcap</EM> notation.
- This does not cause problems if all you do with it is call <STRONG>tgoto</STRONG> or
- <STRONG>tparm</STRONG>, which both expand <EM>terminfo</EM>-style strings as <EM>terminfo</EM> does. (If
- <EM>ncurses</EM> is configured to support <EM>termcap,</EM> <STRONG>tgoto</STRONG> checks whether the
- string is <EM>terminfo</EM>-style by looking for "<STRONG>%p</STRONG>" parameters or "<STRONG><</STRONG>...<STRONG>></STRONG>"
+ This does not cause problems if all you do with it is call <STRONG>tgoto</STRONG> or
+ <STRONG>tparm</STRONG>, which both expand <EM>terminfo</EM>-style strings as <EM>terminfo</EM> does. (If
+ <EM>ncurses</EM> is configured to support <EM>termcap,</EM> <STRONG>tgoto</STRONG> checks whether the
+ string is <EM>terminfo</EM>-style by looking for "<STRONG>%p</STRONG>" parameters or "<STRONG><</STRONG>...<STRONG>></STRONG>"
delays, and invokes a <EM>termcap</EM>-style parser if the string appears not to
use <EM>terminfo</EM> syntax.)
- Because <EM>terminfo</EM>'s syntax for padding in string capabilities differs
+ Because <EM>terminfo</EM>'s syntax for padding in string capabilities differs
from <EM>termcap</EM>'s, users can be surprised.
- <STRONG>o</STRONG> <STRONG>tputs("50")</STRONG> in a <EM>terminfo</EM> system transmits "50" rather than busy-
+ <STRONG>o</STRONG> <STRONG>tputs("50")</STRONG> in a <EM>terminfo</EM> system transmits "50" rather than busy-
waiting for 50 milliseconds.
- <STRONG>o</STRONG> However, if <EM>ncurses</EM> is configured to support <EM>termcap</EM>, it may also
+ <STRONG>o</STRONG> However, if <EM>ncurses</EM> is configured to support <EM>termcap</EM>, it may also
have been configured to support BSD-style padding.
- In that case, <STRONG>tputs</STRONG> inspects strings passed to it, looking for
+ In that case, <STRONG>tputs</STRONG> inspects strings passed to it, looking for
digits at the beginning of the string.
- <STRONG>tputs("50")</STRONG> in a <EM>termcap</EM> system may busy-wait for 50 milliseconds
+ <STRONG>tputs("50")</STRONG> in a <EM>termcap</EM> system may busy-wait for 50 milliseconds
rather than transmitting "50".
<EM>termcap</EM> has nothing analogous to <EM>terminfo</EM>'s <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>)
- capability. One consequence is that <EM>termcap</EM> applications assume that
- "<STRONG>me</STRONG>" (equivalent to <EM>terminfo</EM>'s <STRONG>exit_attribute_mode</STRONG> (<STRONG>sgr0</STRONG>) capability)
- does not reset the alternate character set. <EM>ncurses</EM> checks for, and
+ capability. One consequence is that <EM>termcap</EM> applications assume that
+ "<STRONG>me</STRONG>" (equivalent to <EM>terminfo</EM>'s <STRONG>exit_attribute_mode</STRONG> (<STRONG>sgr0</STRONG>) capability)
+ does not reset the alternate character set. <EM>ncurses</EM> checks for, and
modifies the data shared with, the <EM>termcap</EM> interface to accommodate the
latter's limitation in this respect.
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_terminfo.3x,v 1.124 2023/12/23 17:34:39 tom Exp @
+ * @Id: curs_terminfo.3x,v 1.125 2023/12/30 23:46:56 tom Exp @
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
- * See X/Open Curses Issue 4, Version 2, pp. 227-234.
- * See X/Open Curses Issue 7, pp. 311-318.
* ***************************************************************************
* ***************************************************************************
+ * X/Open Curses Issue 7, p. 161
* ***************************************************************************
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<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-23 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_terminfo 3x 2023-12-30 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-23 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_terminfo 3x 2023-12-30 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>
recommended.
None of these functions use (or are aware of) multibyte character
- strings such as UTF-8:
+ strings such as UTF-8.
- <STRONG>o</STRONG> capability names use the POSIX portable character set
+ <STRONG>o</STRONG> Capability names and codes use the POSIX portable character set.
- <STRONG>o</STRONG> capability string values have no associated encoding; they are
+ <STRONG>o</STRONG> Capability string values have no associated encoding; they are
strings of 8-bit characters.
</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
- Initially, <STRONG>setupterm</STRONG> should be called. The high-level curses functions
+ Initially, <STRONG>setupterm</STRONG> should be called. The high-level <EM>curses</EM> functions
<STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to initialize the low-level set of
- terminal-dependent variables [listed in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>].
+ terminal-dependent variables listed in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>.
Applications can use the terminal capabilities either directly (via
header definitions), or by special functions. The header files
- <STRONG>curses.h</STRONG> and <STRONG>term.h</STRONG> should be included (in this order) to get the
+ <EM>curses.h</EM> and <EM>term.h</EM> should be included (in that order) to get the
definitions for these strings, numbers, and flags.
- The <STRONG>terminfo</STRONG> variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized by <STRONG>setupterm</STRONG>
+ The <EM>terminfo</EM> variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized by <STRONG>setupterm</STRONG>
as follows:
<STRONG>o</STRONG> If <STRONG>use_env(FALSE)</STRONG> has been called, values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG>
- specified in <STRONG>terminfo</STRONG> are used.
+ specified in <EM>terminfo</EM> are used.
<STRONG>o</STRONG> Otherwise, if the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> exist,
their values are used. If these environment variables do not exist
and the program is running in a window, the current window size is
used. Otherwise, if the environment variables do not exist, the
- values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <STRONG>terminfo</STRONG> database are
+ values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <EM>terminfo</EM> database are
used.
Parameterized strings should be passed through <STRONG>tparm</STRONG> to instantiate
- them. All <STRONG>terminfo</STRONG> strings (including the output of <STRONG>tparm</STRONG>) should be
+ them. All <EM>terminfo</EM> strings (including the output of <STRONG>tparm</STRONG>) should be
printed with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>. Call <STRONG>reset_shell_mode</STRONG> to restore the tty
modes before exiting [see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>].
<STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> and call <STRONG>reset_prog_mode</STRONG> after returning from
the shell.
- The <STRONG>setupterm</STRONG> routine reads in the <STRONG>terminfo</STRONG> database, initializing the
- <STRONG>terminfo</STRONG> structures, but does not set up the output virtualization
- structures used by <STRONG>curses</STRONG>. These are its parameters:
+ The <STRONG>setupterm</STRONG> routine reads in the <EM>terminfo</EM> database, initializing the
+ <EM>terminfo</EM> structures, but does not set up the output virtualization
+ structures used by <EM>curses.</EM> These are its parameters:
<EM>term</EM> is the terminal type, a character string. If <EM>term</EM> is null, the
environment variable <EM>TERM</EM> is used.
If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> prints an error message upon
finding an error and exits. Thus, the simplest call is:
- <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>,
+ <STRONG>setupterm((char</STRONG> <STRONG>*)0,</STRONG> <STRONG>1,</STRONG> <STRONG>(int</STRONG> <STRONG>*)0);</STRONG>
- which uses all the defaults and sends the output to <STRONG>stdout</STRONG>.
+ which uses all the defaults and sends the output to <STRONG>stdout</STRONG>.
</PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE>
terminal types, <STRONG>setupterm</STRONG> allocates new storage for each set of
terminal capabilities.
- The <STRONG>set_curterm</STRONG> routine sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes all of the
- <STRONG>terminfo</STRONG> boolean, numeric, and string variables use the values from
- <EM>nterm</EM>. It returns the old value of <STRONG>cur_term</STRONG>.
+ <STRONG>set_curterm</STRONG> sets <STRONG>cur_term</STRONG> to <EM>nterm,</EM> and makes all of the <EM>terminfo</EM>
+ Boolean, numeric, and string variables use the values from <EM>nterm.</EM> It
+ returns the old value of <STRONG>cur_term</STRONG>.
- The <STRONG>del_curterm</STRONG> routine frees the space pointed to by <EM>oterm</EM> and makes
- it available for further use. If <EM>oterm</EM> is the same as <STRONG>cur_term</STRONG>,
- references to any of the <STRONG>terminfo</STRONG> boolean, numeric, and string
+ <STRONG>del_curterm</STRONG> routine frees the space pointed to by <EM>oterm</EM> and makes it
+ available for further use. If <EM>oterm</EM> is the same as <STRONG>cur_term</STRONG>,
+ references to any of the <EM>terminfo</EM> Boolean, numeric, and string
variables thereafter may refer to invalid memory locations until
another <STRONG>setupterm</STRONG> has been called.
<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.
+ <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 <EM>int</EM>s rather than
+ <EM>long</EM>s.
Both <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> assume that the application passes parameters
consistent with the terminal description. Two extensions are provided
The <STRONG>vidattr</STRONG> routine is like the <STRONG>vidputs</STRONG> routine, except that it outputs
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
- attributes plus color, i.e.,
+ <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> correspond to <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG>, respectively.
+ They use multiple parameters to represent the character attributes and
+ color; namely,
- <STRONG>o</STRONG> <EM>attrs</EM> of type <STRONG>attr_t</STRONG> for the attributes and
+ <STRONG>o</STRONG> <EM>attrs,</EM> of type <EM>attr</EM><STRONG>_</STRONG><EM>t,</EM> 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 <EM>short,</EM> 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.
+ Use the attribute constants prefixed with "<STRONG>WA_</STRONG>" with <STRONG>vid_attr</STRONG> and
+ <STRONG>vid_puts</STRONG>.
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
- extension, 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.
+ applications must provide a null pointer for that argument; but see
+ section "EXTENSIONS" below.
- The <STRONG>mvcur</STRONG> routine provides low-level cursor motion. It takes effect
- immediately (rather than at the next refresh). Unlike the other low-
- level output functions, which either write to the standard output or
+ The <STRONG>mvcur</STRONG> routine provides low-level cursor motion. It takes effect
+ immediately (rather than at the next refresh). Unlike the other low-
+ level output functions, which either write to the standard output or
pass an output function parameter, <STRONG>mvcur</STRONG> uses an output file descriptor
derived from the output stream parameter of <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>.
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 System V
- did this (see <EM>HISTORY</EM>).
+ level curses state, they are declared in <EM>curses.h</EM> because System V 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 <EM>terminfo</EM> <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.
The <STRONG>tigetflag</STRONG> routine returns
- <STRONG>-1</STRONG> if <EM>capname</EM> is not a boolean capability, or
+ <STRONG>-1</STRONG> if <EM>capname</EM> is not a Boolean capability, or
<STRONG>0</STRONG> if it is canceled or absent from the terminal description.
</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
+ description. As a side-effect, it sets <STRONG>cur_term</STRONG> to point to this
memory. 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
+ 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 <EM>ncurses</EM> 6.3, those
- were shared by all screens. With <EM>ncurses</EM> 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, <EM>ncurses</EM> 6.3 caches the result of analyzing
- terminfo strings for their parameter types. That is stored as a
+ <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 <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
+ 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
- completion, unless otherwise noted in the preceding routine
- descriptions.
+ X/Open defines no failure conditions. In <EM>ncurses,</EM>
- Routines that return pointers always return <STRONG>NULL</STRONG> on error.
+ <STRONG>del_curterm</STRONG>
+ returns an error if its terminal parameter is null.
- X/Open defines no error conditions. In this implementation
+ <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error-codes.
- <STRONG>del_curterm</STRONG>
- returns an error if its terminal parameter is null.
+ <STRONG>restartterm</STRONG>
+ returns an error if the associated call to <STRONG>setupterm</STRONG> returns an
+ error.
- <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error-codes.
+ <STRONG>setupterm</STRONG>
+ returns an error if it cannot allocate enough memory, or create
+ the initial windows (<STRONG>stdscr</STRONG>, <STRONG>curscr</STRONG>, and <STRONG>newscr</STRONG>) Other error
+ conditions are documented above.
- <STRONG>restartterm</STRONG>
- returns an error if the associated call to <STRONG>setupterm</STRONG> returns an
- error.
+ <STRONG>tparm</STRONG>
+ returns a null if the capability would require unexpected
+ parameters, e.g., too many, too few, or incorrect types (strings
+ where integers are expected, or vice versa).
- <STRONG>setupterm</STRONG>
- returns an error if it cannot allocate enough memory, or create
- the initial windows (stdscr, curscr, newscr). Other error
- conditions are documented above.
-
- <STRONG>tparm</STRONG>
- returns a null if the capability would require unexpected
- parameters, e.g., too many, too few, or incorrect types
- (strings where integers are expected, or vice versa).
-
- <STRONG>tputs</STRONG>
- returns an error if the string parameter is null. It does not
- detect I/O errors: X/Open states that <STRONG>tputs</STRONG> ignores the return
- value of the output function <EM>putc</EM>.
+ <STRONG>tputs</STRONG>
+ returns an error if the string parameter is null. It does not
+ detect I/O errors: X/Open Curses states that <STRONG>tputs</STRONG> ignores the
+ return value of the output function <EM>putc</EM>.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- 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
+ The <STRONG>vid_attr</STRONG> function in <EM>ncurses</EM> 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.
+ parts of the <EM>ncurses</EM> wide-character API were developed, and unlike the
+ other wide-character functions, is also provided in the non-wide-
+ character configuration.
</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 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous
- curses implementation.
+ The functions marked as extensions were designed for <EM>ncurses,</EM> and are
+ not found in SVr4 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous curses
+ implementation.
+
+ <EM>ncurses</EM> allows <EM>opts</EM> to be a pointer to <EM>int,</EM> which overrides the <EM>pair</EM>
+ (<EM>short</EM>) argument.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
likewise macros. The one function, <STRONG>setterm</STRONG>, is mentioned in the manual
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>
+ setupterm(<EM>term</EM>, 1, (int *)0)
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.
Other implementions may not declare the capability name arrays. Some
provide them without declaring them. X/Open does not specify them.
- Extended terminal capability names, e.g., as defined by <STRONG>tic</STRONG> <STRONG>-x</STRONG>, are not
+ Extended terminal capability names, as defined by "<STRONG>tic</STRONG> <STRONG>-x</STRONG>", are not
stored in the arrays described here.
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 <EM>ncurses</EM> did not allow a reliable
- way to cleanup on receiving SIGTSTP.
+ terminal was left in block-buffered mode on exit (like System V
+ <EM>curses</EM>), it was problematic because <EM>ncurses</EM> did not allow a reliable
+ way to cleanup on receiving <STRONG>SIGTSTP</STRONG>.
The current version (ncurses6) uses output buffers managed directly by
- <EM>ncurses</EM>. 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 <EM>ncurses</EM> use alternate versions of these functions
+ level functions in <EM>ncurses</EM> employ alternate versions of these functions
using the more reliable buffering scheme.
</PRE><H3><a name="h3-Function-Prototypes">Function Prototypes</a></H3><PRE>
- The X/Open Curses prototypes are based on the SVr4 curses header
+ The X/Open Curses prototypes are based on the SVr4 <EM>curses</EM> header
declarations, which were defined at the same time the C language was
first standardized in the late 1980s.
- <STRONG>o</STRONG> X/Open Curses uses <STRONG>const</STRONG> less effectively than a later design
+ <STRONG>o</STRONG> X/Open Curses uses <EM>const</EM> less effectively than a later design
might, in some cases applying it needlessly to values are already
constant, and in most cases overlooking parameters which normally
- would use <STRONG>const</STRONG>. Using constant parameters for functions which do
- not use <STRONG>const</STRONG> may prevent the program from compiling. On the other
- hand, <EM>writable</EM> <EM>strings</EM> are an obsolescent feature.
+ would use <EM>const.</EM> Using constant parameters for functions which do
+ not use <EM>const</EM> may prevent the program from compiling. On the other
+ hand, "writable strings" are an obsolescent feature.
As an extension, this implementation can be configured to change
- the function prototypes to use the <STRONG>const</STRONG> keyword. The <EM>ncurses</EM> ABI
+ the function prototypes to use the <EM>const</EM> keyword. The <EM>ncurses</EM> ABI
6 enables this feature by default.
<STRONG>o</STRONG> X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number of parameters,
<STRONG>o</STRONG> Most of the calls to <STRONG>tparm</STRONG> use only one or two parameters. Passing
nine on each call is awkward.
- Using <STRONG>long</STRONG> for the numeric parameter type is a workaround to make
+ Using <EM>long</EM> for the numeric parameter type is a workaround to make
the parameter use the same amount of stack as a pointer. That
approach dates back to the mid-1980s, before C was standardized.
Since then, there is a standard (and pointers are not required to
SVr4 curses uses the special value "dumb".
- The difference between the two is that the former uses the <STRONG>gn</STRONG>
- (<STRONG>generic_type</STRONG>) terminfo capability, while the latter does not. A
+ The difference between the two is that the former uses the <STRONG>gn</STRONG> (-
+ <STRONG>generic_type</STRONG>) terminfo capability, while the latter does not. A
generic terminal is unsuitable for full-screen applications.
<STRONG>o</STRONG> <STRONG>setupterm</STRONG> allows explicit use of the the windows console driver by
</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.
+ In SVr4, <STRONG>set_curterm</STRONG> returns an <EM>int,</EM> <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. We have chosen to
+ implement the X/Open Curses semantics.
- In System V Release 4, the third argument of <STRONG>tputs</STRONG> has the type <STRONG>int</STRONG>
- <STRONG>(*putc)(char)</STRONG>.
+ In SVr4, the third argument of <STRONG>tputs</STRONG> has the type "<STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>".
- At least one implementation of X/Open Curses (Solaris) returns a value
- other than <STRONG>OK</STRONG>/<STRONG>ERR</STRONG> from <STRONG>tputs</STRONG>. That returns the length of the string,
- and does no error-checking.
+ At least one implementation of X/Open Curses (Solaris) returns a value
+ other than <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> from <STRONG>tputs</STRONG>. It instead returns the length of the
+ string, and does no error checking.
+
+ X/Open Curses notes that after calling <STRONG>mvcur</STRONG>, the <EM>curses</EM> state may not
+ match the actual terminal state, and that an application should touch
+ and refresh the window before resuming normal <EM>curses</EM> calls. Both
+ <EM>ncurses</EM> and SVr4 <EM>curses</EM> 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 <EM>terminfo</EM>
+ function, <STRONG>mvcur</STRONG> is really a <EM>curses</EM> function that is not well specified.
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
a terminfo function, <STRONG>mvcur</STRONG> is really a curses function which is not
well specified.
- X/Open states that the old location must be given for <STRONG>mvcur</STRONG>. This
- implementation allows the caller to use -1's for the old ordinates. In
- that case, the old location is unknown.
+ X/Open Curses states that the old location must be given for <STRONG>mvcur</STRONG> to
+ accommodate terminals that lack absolute cursor positioning. <EM>ncurses</EM>
+ allows the caller to use -1 for either or both old coordinates. The -1
+ tells <EM>ncurses</EM> that the old location is unknown, and that it must use
+ only absolute motion (such as <EM>cursor</EM><STRONG>_</STRONG><EM>address</EM>) rather than the least
+ costly combination of absolute and relative motion.
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
- SVr2 introduced the terminfo feature. Its programming manual mentioned
- the following low-level functions.
+ SVr2 (1984) introduced the <EM>terminfo</EM> feature. Its programming manual
+ mentioned the following low-level functions.
<STRONG>Function</STRONG> <STRONG>Description</STRONG>
------------------------------------------------------------------------
<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
- <EM>putchar</EM>.
+ <STRONG>putp</STRONG> use <STRONG>tputs</STRONG> to send characters via <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>savetty</STRONG> store current tty flags
<STRONG>setterm</STRONG> establish terminal with given type
<STRONG>setupterm</STRONG> establish terminal with given type
- <STRONG>tparm</STRONG> instantiate a string expression with parameters
+ <STRONG>tparm</STRONG> interpolate parameters into string capability
<STRONG>tputs</STRONG> apply padding information to a string
- <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>vidattr</STRONG> like <STRONG>vidputs</STRONG>, but output through <EM>putchar</EM>
+ <STRONG>vidputs</STRONG> write string to terminal, applying specified attributes
- The programming manual also mentioned functions provided for <EM>termcap</EM>
+ The programming manual also mentioned functions provided for <EM>termcap</EM>
compatibility (commenting that they "may go away at a later date").
<STRONG>Function</STRONG> <STRONG>Description</STRONG>
------------------------------------------------------------------------
<STRONG>tgetent</STRONG> look up <EM>termcap</EM> entry for given <EM>name</EM>
- <STRONG>tgetflag</STRONG> get boolean entry for given <EM>id</EM>
+ <STRONG>tgetflag</STRONG> get Boolean entry for given <EM>id</EM>
<STRONG>tgetnum</STRONG> get numeric entry for given <EM>id</EM>
<STRONG>tgetstr</STRONG> get string entry for given <EM>id</EM>
<STRONG>tgoto</STRONG> apply parameters to given capability
- <STRONG>tputs</STRONG> apply padding to capability, calling a function to put
- characters
+ <STRONG>tputs</STRONG> write characters via a function parameter, applying padding
- Early terminfo programs obtained capability values from the <EM>TERMINAL</EM>
+ Early <EM>terminfo</EM> programs obtained capability values from the <EM>TERMINAL</EM>
structure initialized by <STRONG>setupterm</STRONG>.
- SVr3 extended terminfo by adding functions to retrieve capability
- values (like the termcap interface), and reusing <STRONG>tgoto</STRONG> and <STRONG>tputs</STRONG>:
+ SVr3 (1987) extended <EM>terminfo</EM> by adding functions to retrieve
+ capability values (like the <EM>termcap</EM> interface), and reusing <STRONG>tgoto</STRONG> and
+ <STRONG>tputs</STRONG>.
<STRONG>Function</STRONG> <STRONG>Description</STRONG>
------------------------------------------------------------------------
-
- <STRONG>tigetflag</STRONG> get boolean entry for given <EM>id</EM>
+ <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>
- SVr3 also replaced several of the SVr2 <EM>terminfo</EM> functions which had no
+ SVr3 also replaced several of the SVr2 <EM>terminfo</EM> functions that had no
counterpart in the <EM>termcap</EM> 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
- handling functions such as <STRONG>vidattr</STRONG> (which used more than the two
- parameters supported by <STRONG>tgoto</STRONG>).
+ 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 to
+ handle capabilities accessed by functions such as <STRONG>vidattr</STRONG> (which used
+ more than the two parameters supported by <STRONG>tgoto</STRONG>).
- SVr3 introduced the functions for switching between terminal
- descriptions, e.g., <STRONG>set_curterm</STRONG>. Some of that was incremental
- improvements to the SVr2 library:
+ SVr3 introduced the functions for switching between terminal
+ descriptions; for example, <STRONG>set_curterm</STRONG>. Some changes reflected
+ incremental improvements to the SVr2 library.
- <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 <EM>TERMINAL</EM> type definition was introduced in SVr3.01, for the
+ <EM>term</EM> 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
+ <STRONG>o</STRONG> Various global variables such as <STRONG>boolnames</STRONG> were mentioned in the
+ programming manual at this point, though the variables had been
provided in SVr2.
- SVr4 added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions.
+ SVr4 (1989) added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions.
- There are other low-level functions declared in the <EM>curses</EM> header files
- on Unix systems, but none were documented. The functions marked
- "obsolete" remained in use by the Unix <STRONG>vi(1)</STRONG> editor.
+ Other low-level functions are declared in the <EM>curses</EM> header files of
+ Unix systems, but none are documented. Those noted as "obsolete" by
+ SVr3 remained in use by System V's <STRONG>vi(1)</STRONG> editor.
</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_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>putc(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(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>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>
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: infocmp.1m,v 1.103 2023/12/23 16:08:25 tom Exp @
+ * @Id: infocmp.1m,v 1.104 2023/12/30 21:36:32 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<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>infocmp 1m 2023-12-23 ncurses 6.4 User commands</TITLE>
+<TITLE>infocmp 1m 2023-12-30 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">infocmp 1m 2023-12-23 ncurses 6.4 User commands</H1>
+<H1 class="no-header">infocmp 1m 2023-12-30 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG> User commands <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>
<STRONG>infocmp</STRONG> can be used to compare a binary <STRONG>terminfo</STRONG> entry with other
terminfo entries, rewrite a <STRONG>terminfo</STRONG> description to take advantage of
the <STRONG>use=</STRONG> terminfo field, or print out a <STRONG>terminfo</STRONG> description from the
- binary file (<STRONG>term</STRONG>) in a variety of formats. In all cases, the boolean
+ binary file (<STRONG>term</STRONG>) in a variety of formats. In all cases, the Boolean
fields will be printed first, followed by the numeric fields, followed
by the string fields.
only one of the terminals, the value returned depends on the type of
the capability:
- <STRONG>o</STRONG> <STRONG>F</STRONG> for missing boolean variables
+ <STRONG>o</STRONG> <STRONG>F</STRONG> for missing Boolean variables
<STRONG>o</STRONG> <STRONG>NULL</STRONG> for missing integer or string variables
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: ncurses.3x,v 1.189 2023/12/23 16:32:37 tom Exp @
+ * @Id: ncurses.3x,v 1.192 2023/12/31 00:46:04 tom Exp @
* X/Open Curses Issue 7 assumes some optimization will be done, but
* does not mandate it in any way.
+ * See X/Open Curses Issue 4, Version 2, pp. 227-234.
+ * See X/Open Curses Issue 7, pp. 311-318.
+ * XXX: What's missing? GBR counts untic(1), and that's all.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<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>ncurses 3x 2023-12-23 ncurses 6.4 Library calls</TITLE>
+<TITLE>ncurses 3x 2023-12-30 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">ncurses 3x 2023-12-23 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">ncurses 3x 2023-12-30 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> Library calls <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
method of updating character screens with reasonable optimization.
This implementation is "new curses" (<EM>ncurses</EM>) and is the approved
replacement for 4.4BSD classic curses, which has been discontinued.
- This describes <EM>ncurses</EM> version 6.4 (patch 20231223).
+ This describes <EM>ncurses</EM> version 6.4 (patch 20231230).
The <EM>ncurses</EM> library emulates the curses library of System V Release 4
Unix ("SVr4"), and XPG4 (X/Open Portability Guide) curses (also known
<STRONG>o</STRONG> "NOTES" describes matters and caveats of which any user of the
<EM>ncurses</EM> API should be aware, such as limitations on the size of an
underlying integral type or the availability of a preprocessor
- macro for a function (which prevents its address from being taken).
- This section also describes implementation details that will be
- significant to the programmer but which are not standardized.
-
- <STRONG>o</STRONG> "EXTENSIONS" presents <EM>ncurses</EM> innovations beyond the X/Open Curses
- standard and/or the SVr4 <EM>curses</EM> implementation. They are termed
- <EM>extensions</EM> to indicate that they cannot be implemented solely by
+ macro exclusive of a function definition (which prevents its
+ address from being taken). This section also describes
+ implementation details that will be significant to the programmer
+ but which are not standardized.
+
+ <STRONG>o</STRONG> "EXTENSIONS" presents <EM>ncurses</EM> innovations beyond the X/Open Curses
+ standard and/or the SVr4 <EM>curses</EM> implementation. They are termed
+ <EM>extensions</EM> to indicate that they cannot be implemented solely by
using the library API, but require access to the library's internal
state.
<STRONG>o</STRONG> "PORTABILITY" discusses matters (beyond the exercise of extensions)
- that should be considered when writing to a <EM>curses</EM> standard, or to
+ that should be considered when writing to a <EM>curses</EM> standard, or to
multiple implementations.
- <STRONG>o</STRONG> "HISTORY" examines points of detail in <EM>ncurses</EM> and other <EM>curses</EM>
+ <STRONG>o</STRONG> "HISTORY" examines points of detail in <EM>ncurses</EM> and other <EM>curses</EM>
implementations over the decades of their development, particularly
where precedent or inertia have frustrated better design (and, in a
few cases, where such inertia has been overcome).
- A program using these routines must be linked with the <STRONG>-lncurses</STRONG>
- option, or (if it has been generated) with the debugging library
- <STRONG>-lncurses_g</STRONG>. (Your system integrator may also have installed these
- libraries under the names <STRONG>-lcurses</STRONG> and <STRONG>-lcurses_g</STRONG>.) The ncurses_g
- library generates trace logs (in a file called "trace" in the current
+ A program using these routines must be linked with the <STRONG>-lncurses</STRONG>
+ option, or (if it has been generated) with the debugging library
+ <STRONG>-lncurses_g</STRONG>. (Your system integrator may also have installed these
+ libraries under the names <STRONG>-lcurses</STRONG> and <STRONG>-lcurses_g</STRONG>.) The ncurses_g
+ library generates trace logs (in a file called "trace" in the current
directory) that describe curses actions. See section "ALTERNATE
CONFIGURATIONS" below.
- The <EM>ncurses</EM> package supports: overall screen, window and pad
- manipulation; output to windows and pads; reading terminal input;
- control over terminal and <STRONG>curses</STRONG> input and output options; environment
- query routines; color manipulation; use of soft label keys; terminfo
+ The <EM>ncurses</EM> package supports: overall screen, window and pad
+ manipulation; output to windows and pads; reading terminal input;
+ control over terminal and <STRONG>curses</STRONG> input and output options; environment
+ query routines; color manipulation; use of soft label keys; terminfo
capabilities; and access to low-level terminal-manipulation routines.
</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
- The library uses the locale which the calling program has initialized.
+ The library uses the locale which the calling program has initialized.
That is normally done with <STRONG>setlocale(3)</STRONG>:
<STRONG>setlocale(LC_ALL,</STRONG> <STRONG>"");</STRONG>
- If the locale is not initialized, the library assumes that characters
- are printable as in ISO-8859-1, to work with certain legacy programs.
- You should initialize the locale and not rely on specific details of
+ If the locale is not initialized, the library assumes that characters
+ are printable as in ISO-8859-1, to work with certain legacy programs.
+ You should initialize the locale and not rely on specific details of
the library when the locale has not been setup.
- The function <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> must be called to initialize the
- library before any of the other routines that deal with windows and
- screens are used. The routine <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> must be called before
+ The function <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> must be called to initialize the
+ library before any of the other routines that deal with windows and
+ screens are used. The routine <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> must be called before
exiting.
- To get character-at-a-time input without echoing (most interactive,
- screen oriented programs want this), the following sequence should be
+ To get character-at-a-time input without echoing (most interactive,
+ screen oriented programs want this), the following sequence should be
used:
<STRONG>initscr();</STRONG> <STRONG>cbreak();</STRONG> <STRONG>noecho();</STRONG>
<STRONG>keypad(stdscr,</STRONG> <STRONG>TRUE);</STRONG>
Before a <STRONG>curses</STRONG> program is run, the tab stops of the terminal should be
- set and its initialization strings, if defined, must be output. This
- can be done by executing the <STRONG>tput</STRONG> <STRONG>init</STRONG> command after the shell
- environment
variable <EM>TERM</EM> has been exported. (The BSD-style <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>
+ set and its initialization strings, if defined, must be output. This
+ can be done by executing the <STRONG>tput</STRONG> <STRONG>init</STRONG> command after the shell
+ environment
variable <EM>TERM</EM> has been exported. (The BSD-style <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>
utility also performs this function.) See subsection "Tabs and
Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
</PRE><H3><a name="h3-Overview">Overview</a></H3><PRE>
- A <EM>curses</EM> library abstracts the terminal screen by representing all or
- part of it as a <EM>WINDOW</EM> data structure. A <EM>window</EM> is a rectangular grid
- of character cells, addressed by row and column coordinates (<EM>y</EM>, <EM>x</EM>),
+ A <EM>curses</EM> library abstracts the terminal screen by representing all or
+ part of it as a <EM>WINDOW</EM> data structure. A <EM>window</EM> is a rectangular grid
+ of character cells, addressed by row and column coordinates (<EM>y</EM>, <EM>x</EM>),
with the upper left corner as (0, 0). A window called <STRONG>stdscr</STRONG>, the same
- size as the terminal screen, is always available. Create others with
+ size as the terminal screen, is always available. Create others with
<STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>.
- A
<EM>curses</EM> library does not manage overlapping windows. (See <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>
- if you desire this.) You can either use <STRONG>stdscr</STRONG> to manage one screen-
+ A
<EM>curses</EM> library does not manage overlapping windows. (See <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>
+ if you desire this.) You can either use <STRONG>stdscr</STRONG> to manage one screen-
filling window, or tile the screen into non-overlapping windows and not
- use <STRONG>stdscr</STRONG> at all. Mixing the two approaches will result in
+ use <STRONG>stdscr</STRONG> at all. Mixing the two approaches will result in
unpredictable, and undesired, effects.
- Functions permit manipulation of a window and the <EM>cursor</EM> identifying
- the cell within it at which the next output operation will occur.
+ Functions permit manipulation of a window and the <EM>cursor</EM> identifying
+ the cell within it at which the next output operation will occur.
Among those, the most basic are <STRONG><A HREF="curs_move.3x.html">move(3x)</A></STRONG> and <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>: these place the
- cursor and write a character to <STRONG>stdscr</STRONG>, respectively. As a rule,
- window-addressing functions feature names prefixed (or infixed, see
+ cursor and write a character to <STRONG>stdscr</STRONG>, respectively. As a rule,
+ window-addressing functions feature names prefixed (or infixed, see
below) with "w"; these allow the user to specify a pointer to a <EM>WINDOW.</EM>
- Counterparts not thus prefixed (or infixed) affect <STRONG>stdscr</STRONG>. Because
- moving the cursor prior to another operation is so common, <EM>curses</EM>
- generally also provides functions with a "mv" prefix as a convenience.
- Thus, the library defines all of <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG>, and <STRONG>mvwaddch</STRONG>.
- When both prefixes are present, the order of arguments is a <EM>WINDOW</EM>
+ Counterparts not thus prefixed (or infixed) affect <STRONG>stdscr</STRONG>. Because
+ moving the cursor prior to another operation is so common, <EM>curses</EM>
+ generally also provides functions with a "mv" prefix as a convenience.
+ Thus, the library defines all of <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG>, and <STRONG>mvwaddch</STRONG>.
+ When both prefixes are present, the order of arguments is a <EM>WINDOW</EM>
pointer first, then a <EM>y</EM> and <EM>x</EM> coordinate pair.
- Updating the terminal screen with every <EM>curses</EM> call can cause
- unpleasant flicker or inefficient use of the communications channel to
- the device. Therefore, after using <EM>curses</EM> functions to accumulate a
- set of desired updates that make sense to present together, call
- <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> to tell the library to make the user's screen look like
- <STRONG>stdscr</STRONG>. <EM>ncurses</EM> <EM>optimizes</EM> its output by computing a minimal number of
- operations to mutate the screen from its state at the previous refresh
- to the new one. Effective optimization demands accurate information
- about the terminal device: the management of such information is the
- province of the <STRONG><A HREF="curs_terminfo.3x.html">terminfo(3x)</A></STRONG> API, a feature of every standard <EM>curses</EM>
+ Updating the terminal screen with every <EM>curses</EM> call can cause
+ unpleasant flicker or inefficient use of the communications channel to
+ the device. Therefore, after using <EM>curses</EM> functions to accumulate a
+ set of desired updates that make sense to present together, call
+ <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> to tell the library to make the user's screen look like
+ <STRONG>stdscr</STRONG>. <EM>ncurses</EM> <EM>optimizes</EM> its output by computing a minimal number of
+ operations to mutate the screen from its state at the previous refresh
+ to the new one. Effective optimization demands accurate information
+ about the terminal device: the management of such information is the
+ province of the <STRONG><A HREF="curs_terminfo.3x.html">terminfo(3x)</A></STRONG> API, a feature of every standard <EM>curses</EM>
implementation.
Special windows called <EM>pads</EM> may also be manipulated. These are windows
- that are not constrained to the size of the terminal screen and whose
+ that are not constrained to the size of the terminal screen and whose
contents need not be completely displayed. See <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>.
- In addition to drawing characters on the screen, rendering attributes
- and colors may be supported, causing the characters to show up in such
- modes as underlined, in reverse video, or in color on terminals that
+ In addition to drawing characters on the screen, rendering attributes
+ and colors may be supported, causing the characters to show up in such
+ modes as underlined, in reverse video, or in color on terminals that
support such display enhancements. See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>.
- <EM>curses</EM> predefines constants for a small set of line-drawing and other
- graphics corresponding to the DEC Alternate Character Set (ACS), a
+ <EM>curses</EM> predefines constants for a small set of line-drawing and other
+ graphics corresponding to the DEC Alternate Character Set (ACS), a
feature of VT100 and other terminals. See <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> and <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.
- <EM>curses</EM> is implemented using the operating system's terminal driver;
- keystroke events are received not as scan codes but as byte sequences.
- Graphical keycaps (alphanumeric and punctuation keys, and the space)
+ <EM>curses</EM> is implemented using the operating system's terminal driver;
+ keystroke events are received not as scan codes but as byte sequences.
+ Graphical keycaps (alphanumeric and punctuation keys, and the space)
appear as-is. Everything else, including the tab, enter/return,
- keypad, arrow, and function keys, appears as a control character or a
- multibyte <EM>escape</EM> <EM>sequence.</EM> <EM>curses</EM> translates these into unique <EM>key</EM>
+ keypad, arrow, and function keys, appears as a control character or a
+ multibyte <EM>escape</EM> <EM>sequence.</EM> <EM>curses</EM> translates these into unique <EM>key</EM>
<EM>codes.</EM> See <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>.
</PRE><H3><a name="h3-Effects-of-GUIs-and-Environment-Variables">Effects of GUIs and Environment Variables</a></H3><PRE>
The selection of an approprate value of <EM>TERM</EM> in the process environment
is essential to correct <EM>curses</EM> and <EM>terminfo</EM> library operation. A well-
- configured
system selects a correct <EM>TERM</EM> value automatically; <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>
+ configured
system selects a correct <EM>TERM</EM> value automatically; <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>
may assist with troubleshooting exotic situations.
- If the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> are set, or if the
- <EM>curses</EM> program is executing in a graphical windowing environment, the
- information obtained thence overrides that obtained by <EM>terminfo</EM>. An
+ If the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> are set, or if the
+ <EM>curses</EM> program is executing in a graphical windowing environment, the
+ information obtained thence overrides that obtained by <EM>terminfo</EM>. An
<EM>ncurses</EM> extension supports resizable terminals; see <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>.
- If the environment variable <EM>TERMINFO</EM> is defined, a <EM>curses</EM> program
- checks first for a terminal type description in the location it
+ If the environment variable <EM>TERMINFO</EM> is defined, a <EM>curses</EM> program
+ checks first for a terminal type description in the location it
identifies. <EM>TERMINFO</EM> is useful for developing experimental type
- descriptions or when write permission to <EM>/usr/share/terminfo</EM> is not
+ descriptions or when write permission to <EM>/usr/share/terminfo</EM> is not
available.
See section "ENVIRONMENT" below.
</PRE><H3><a name="h3-Naming-Conventions">Naming Conventions</a></H3><PRE>
- Many <EM>curses</EM> functions have two or more versions. Those prefixed with
- "w" require a window argument. Four functions prefixed with "p"
- require a pad argument. Those without a prefix generally operate on
+ Many <EM>curses</EM> functions have two or more versions. Those prefixed with
+ "w" require a window argument. Four functions prefixed with "p"
+ require a pad argument. Those without a prefix generally operate on
<STRONG>stdscr</STRONG>.
- In function synopses, <EM>ncurses</EM> man pages apply the following names to
+ In function synopses, <EM>ncurses</EM> man pages apply the following names to
parameters.
<EM>bf</EM> <EM>bool</EM> (<STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>)
</PRE><H3><a name="h3-Wide-and-Non-wide-Character-Configurations">Wide and Non-wide Character Configurations</a></H3><PRE>
- This manual page describes functions that appear in any configuration
- of the library. There are two common configurations; see section
+ This manual page describes functions that appear in any configuration
+ of the library. There are two common configurations; see section
"ALTERNATE CONFIGURATIONS" below.
<EM>ncurses</EM> is the library in its "non-wide" configuration, handling only
- eight-bit characters. It stores a character combined with
- attributes in a <EM>chtype</EM> datum.
+ eight-bit characters. It stores a character combined with
+ attributes in a <EM>chtype</EM> datum, which is often an alias of <EM>int.</EM>
- Attributes alone (with no corresponding character) can be
- stored in variables of <EM>chtype</EM> or <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> type. In either
+ Attributes alone (with no corresponding character) can be
+ stored in variables of <EM>chtype</EM> or <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> type. In either
case, they are represented as an integral bit mask.
Each cell of a <EM>WINDOW</EM> is stored as a <EM>chtype.</EM>
- <EM>ncursesw</EM> is the library in its "wide" configuration, which handles
+ <EM>ncursesw</EM> is the library in its "wide" configuration, which handles
character encodings requiring a larger data type than <EM>char</EM> (a
byte-sized type) can represent. It adds about one third more
calls using additional data types that can store such
<EM>multibyte</EM> characters.
- <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> corresponds to the non-wide configuration's <EM>chtype.</EM>
- It always a structure type, because it stores more
- data than can fit into an integer. A character code
- may be larger than can fit in a C <EM>char,</EM> and moreover
- more than one character may occupy a cell (as with
- accent marks and other diacritics). Each character
- is of type <EM>wchar</EM><STRONG>_</STRONG><EM>t;</EM> a complex character contains one
- spacing character and zero or more non-spacing
- characters (see below). Attributes and color data
- are stored in separate fields of the structure, not
- combined as in <EM>chtype.</EM>
-
- Each cell (row and column) <EM>WINDOW</EM> is stored as a
- <EM>cchar</EM><STRONG>_</STRONG><EM>t.</EM>
+ <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> corresponds to the non-wide configuration's <EM>chtype.</EM>
+ It always a structure type, because it stores more
+ data than fits into an integral type. A character
+ code may not be representable as a <EM>char,</EM> and
+ moreover more than one character may occupy a cell
+ (as with accent marks and other diacritics). Each
+ character is of type <EM>wchar</EM><STRONG>_</STRONG><EM>t;</EM> a complex character
+ contains one spacing character and zero or more non-
+ spacing characters (see below). Attributes and
+ color data are stored in separate fields of the
+ structure, not combined as in <EM>chtype.</EM>
+
+ Each cell of a <EM>WINDOW</EM> is stored as a <EM>cchar</EM><STRONG>_</STRONG><EM>t.</EM>
The <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> functions store and
retrieve the data from a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> structure. The wide library
API of <EM>ncurses</EM> depends on two data types standardized by ISO
C95.
- <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> stores a wide character. Like <EM>chtype,</EM> this may be
- an integer. Depending on the character encoding, a
- wide character may be <EM>spacing,</EM> meaning that it
+ <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> stores a wide character. Like <EM>chtype,</EM> it may be an
+ alias of <EM>int.</EM> Depending on the character encoding,
+ a wide character may be <EM>spacing,</EM> meaning that it
occupies a character cell by itself and typically
- accompanies cursor advancement on input, or
- <EM>combining,</EM> meaning that it occupies the same cell as
- a spacing character, is often regarded as a
- "modifier" of the base glyph with which it combines,
- and typically does not advance the cursor on input.
+ accompanies cursor advancement, or <EM>non-spacing,</EM>
+ meaning that it occupies the same cell as a spacing
+ character, is often regarded as a "modifier" of the
+ base glyph with which it combines, and typically
+ does not advance the cursor.
<EM>wint</EM><STRONG>_</STRONG><EM>t</EM> can store a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> or the constant <STRONG>WEOF</STRONG>,
analogously to the <EM>int</EM>-sized character manipulation
<STRONG><EM>curses</EM></STRONG> Function Name Man Page
---------------------------------------------
COLOR_PAIR <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
- PAIR_NUMBER <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
+
+ PAIR_NUMBER <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
add_wch <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
add_wchnstr <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
add_wchstr <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
erasewchar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
exit_curses <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>*
exit_terminfo <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>*
-
extended_color_content <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>*
extended_pair_content <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>*
+
extended_slk_color <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>*
filter <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
find_pair <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG>*
insertln <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG>
insnstr <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG>
insstr <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG>
-
instr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
intrflush <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
inwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
+
is_cbreak <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>*
is_cleared <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_echo <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>*
mvin_wchnstr <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG>
mvin_wchstr <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG>
mvinch <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>
-
mvinchnstr <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>
mvinchstr <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>
mvinnstr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
mvinnwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
+
mvins_nwstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
mvins_wch <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>
mvins_wstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
nocbreak <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
nodelay <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
noecho <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
-
nofilter <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>*
nonl <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
noqiflush <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
noraw <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
notimeout <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
+
overlay <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG>
overwrite <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG>
pair_content <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
subpad <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
subwin <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
syncok <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
-
term_attrs <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
termattrs <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
termname <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
tgetent <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
tgetflag <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
tgetnum <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
+
tgetstr <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
tgoto <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
tigetflag <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
wbkgrndset <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
wborder <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
wborder_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
-
wchgat <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
wclear <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>
wclrtobot <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>
wcolor_set <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
wcursyncup <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
wdelch <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG>
+
wdeleteln <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG>
wecho_wchar <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
wechochar <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Routines that return an integer return <STRONG>ERR</STRONG> upon failure and an integer
- value other than <STRONG>ERR</STRONG> upon successful completion, unless otherwise noted
- in the routine descriptions.
-
- As a general rule, routines check for null pointers passed as
- parameters, and handle this as an error.
-
- All macros return the value of the <STRONG>w</STRONG> version, except <STRONG>setscrreg</STRONG>,
- <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG>. The return values of
- <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG> are undefined
- (i.e., these should not be used as the right-hand side of assignment
- statements).
+ Unless otherwise noted, functions that return an integer return <STRONG>OK</STRONG> on
+ success and <STRONG>ERR</STRONG> on failure. Functions that return pointers return <STRONG>NULL</STRONG>
+ on failure. Typically, <EM>ncurses</EM> treats a null pointer passed as a
+ function parameter as a failure.
Functions with a "mv" prefix first perform cursor movement using <STRONG>wmove</STRONG>
- and return an error if the position is outside the window, or (for
- "mvw" functions) if the <EM>WINDOW</EM> pointer is null. Most "mv"-prefixed
- functions (except variadic functions such as <STRONG>mvprintw</STRONG>) are provided
- both as macros and functions.
-
- Routines that return pointers return <STRONG>NULL</STRONG> on error.
+ and fail if the position is outside the window, or (for "mvw"
+ functions) if the <EM>WINDOW</EM> pointer is null.
</PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
</PRE><H3><a name="h3-CC-command-character"><EM>CC</EM> command-character</a></H3><PRE>
- When set, change occurrences of the command_character (i.e., the <STRONG>cmdch</STRONG>
- capability) of the loaded terminfo entries to the value of this
- variable. Very few terminfo entries provide this feature.
+ When set, change the <STRONG>command_character</STRONG> (<STRONG>cmdch</STRONG>) capability value of
+ loaded <EM>terminfo</EM> entries to the value of this variable. Very few <EM>term-</EM>
+ <EM>info</EM> entries provide this feature.
Because this name is also used in development environments to represent
the C compiler's name, <EM>ncurses</EM> ignores it if it does not happen to be a
Those functions are described in these pages:
- <STRONG>o</STRONG> <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> - miscellaneous curses extensions
+ <STRONG>o</STRONG> <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> - miscellaneous <EM>curses</EM> extensions
- <STRONG>o</STRONG> <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> - <STRONG>curses</STRONG> input options
+ <STRONG>o</STRONG> <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> - <EM>curses</EM> input options
- <STRONG>o</STRONG> <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> - low-level <STRONG>curses</STRONG> routines
+ <STRONG>o</STRONG> <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> - low-level <EM>curses</EM> routines
- <STRONG>o</STRONG> <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> - <STRONG>curses</STRONG> environment query routines
+ <STRONG>o</STRONG> <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> - <EM>curses</EM> environment query routines
- <STRONG>o</STRONG> <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> - <STRONG>curses</STRONG> emulation of termcap
+ <STRONG>o</STRONG> <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> - <EM>curses</EM> emulation of <EM>termcap</EM>
- <STRONG>o</STRONG> <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> - <STRONG>curses</STRONG> interfaces to terminfo database
+ <STRONG>o</STRONG> <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> - <EM>curses</EM> interface to <EM>terminfo</EM> database
- <STRONG>o</STRONG> <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> - miscellaneous <STRONG>curses</STRONG> utility routines
+ <STRONG>o</STRONG> <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> - miscellaneous <EM>curses</EM> utility routines
--with-trace
The <STRONG>trace</STRONG> function normally resides in the debug library, but it
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- If standard output from a <EM>ncurses</EM> program is re-directed to something
- which is not a tty, screen updates will be directed to standard error.
- This was an undocumented feature of AT&T System V Release 3 curses.
+ X/Open Curses permits most functions it specifies to be made available
+ as macros as well. <EM>ncurses</EM> does so
+
+ <STRONG>o</STRONG> for functions that return values via their parameters,
+
+ <STRONG>o</STRONG> to support obsolete features,
+
+ <STRONG>o</STRONG> to reuse functions (for example, those that move the cursor before
+ another operation), and
- See subsection "Header files" below regarding symbols exposed by
+ <STRONG>o</STRONG> a few special cases.
+
+ If the standard output file descriptor of an <EM>ncurses</EM> program is
+ redirected to something that is not a terminal device, the library
+ writes screen updates to the standard error file descriptor. This was
+ an undocumented feature of SVr3.
+
+ See subsection "Header files" below regarding symbols exposed by
inclusion of <EM>curses.h</EM>.
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
- The <EM>ncurses</EM> library can be compiled with an option (<STRONG>-DUSE_GETCAP</STRONG>) that
- falls back to the old-style /etc/termcap file if the terminal setup
- code cannot find a terminfo entry corresponding to <EM>TERM</EM>. Use of this
- feature is not recommended, as it essentially includes an entire
- termcap compiler in the <EM>ncurses</EM> startup code, at significant cost in
- core and startup cycles.
-
- The <EM>ncurses</EM> library includes facilities for capturing mouse events on
- certain terminals (including xterm). See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual
- page for details.
-
- The <EM>ncurses</EM> library includes facilities for responding to window
- resizing events, e.g., when running in an xterm. See the
- <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> and <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual pages for details. In addition,
- the library may be configured with a <STRONG>SIGWINCH</STRONG> handler.
-
- The <EM>ncurses</EM> library extends the fixed set of function key capabilities
- of terminals by allowing the application designer to define additional
- key sequences at runtime. See the <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>, and
- <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> manual pages for details.
-
- The <EM>ncurses</EM> library can exploit the capabilities of terminals which
- implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
- application to reset the terminal to its original foreground and
- background colors. From the users' perspective, the application is
- able to draw colored text on a background whose color is set
- independently, providing better control over color contrasts. See the
- <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> manual page for details.
-
- The <EM>ncurses</EM> library includes a function for directing application
- output to a printer attached to the terminal device. See the
- <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details.
+ <EM>ncurses</EM> enables an application to capture mouse events on certain
+ terminals, including <EM>xterm;</EM> see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>.
+ <EM>ncurses</EM> provides a means of responding to window resizing events, as
+ when running in a GUI terminal emulator application such as <EM>xterm;</EM> see
+ <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> and <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>.
-</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- The <EM>ncurses</EM> library is intended to be BASE-level conformant with XSI
- Curses. The EXTENDED XSI Curses functionality (including color
- support) is supported.
+ <EM>ncurses</EM> allows an application to query the terminal for the presence of
+ a wide variety of special keys; see <STRONG><A HREF="curs_getch.3x.html">has_key(3x)</A></STRONG>.
- A small number of local differences (that is, individual differences
- between the XSI Curses and <EM>ncurses</EM> calls) are described in <STRONG>PORTABILITY</STRONG>
- sections of the library man pages.
+ <EM>ncurses</EM> extends the fixed set of function key capabilities specified by
+ X/Open Curses by allowing the application programmer to define
+ additional key sequences at runtime; see <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>,
+ <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>, and <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>.
+ <EM>ncurses</EM> can exploit the capabilities of terminals implementing
+ ISO 6429/ECMA-48 SGR 39 and SGR 49 sequences, which allow an
+ application to reset the terminal to its original foreground and
+ background colors. From a user's perspective, the application is able
+ to draw colored text on a background whose color is set independently,
+ providing better control over color contrasts. See <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>.
-</PRE><H3><a name="h3-Error-Checking">Error Checking</a></H3><PRE>
- In many cases, X/Open Curses is vague about error conditions, omitting
- some of the SVr4 documentation.
+ An <EM>ncurses</EM> application can choose to hide the internal details of
+ <EM>WINDOW</EM> structures, instead using accessor functions such as
+ <STRONG><A HREF="curs_opaque.3x.html">is_scrollok(3x)</A></STRONG>.
- Unlike other implementations, this one checks parameters such as
- pointers to <EM>WINDOW</EM> structures to ensure they are not null. The main
- reason for providing this behavior is to guard against programmer
- error. The standard interface does not provide a way for the library
- to tell an application which of several possible errors were detected.
- Relying on this (or some other) extension will adversely affect the
- portability of curses applications.
+ <EM>ncurses</EM> enables an application to direct application output to a
+ printer attached to the terminal device; see <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>.
+
+ <EM>ncurses</EM> offers <STRONG><A HREF="curs_slk.3x.html">slk_attr(3x)</A></STRONG> as a counterpart of <STRONG><A HREF="curs_attr.3x.html">attr_get(3x)</A></STRONG> for soft-
+ label key lines, and <STRONG><A HREF="curs_slk.3x.html">extended_slk_color(3x)</A></STRONG> as a form of <STRONG><A HREF="curs_slk.3x.html">slk_color(3x)</A></STRONG>
+ that can gather color information from them when many colors are
+ supported.
+
+ Some extensions are only available if <EM>ncurses</EM> is compiled to support
+ them; see section "ALTERNATE CONFIGURATIONS" above.
+ <STRONG>o</STRONG> Rudimentary support for multi-threaded applications may be
+ available; see <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>.
-</PRE><H3><a name="h3-Extensions-Versus-Portability">Extensions Versus Portability</a></H3><PRE>
- Most of the extensions provided by <EM>ncurses</EM> have not been standardized.
- Some have been incorporated into other implementations, such as
- PDCurses or NetBSD curses. Here are a few to consider:
+ <STRONG>o</STRONG> Functions that ease the management of multiple screens can be
+ exposed; see <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>.
- <STRONG>o</STRONG> The routine <STRONG>has_key</STRONG> is not part of XPG4, nor is it present in SVr4.
- See the <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> manual page for details.
+ <STRONG>o</STRONG> The compiler option <STRONG>-DUSE_GETCAP</STRONG> causes the library to fall back to
+ reading <EM>/etc/termcap</EM> if the terminal setup code cannot find a <EM>term-</EM>
+ <EM>info</EM> entry corresponding to <EM>TERM.</EM> Use of this feature is not
+ recommended, as it essentially includes an entire <EM>termcap</EM> compiler
+ in the <EM>ncurses</EM> startup code, at a cost in memory usage and
+ application launch latency.
- <STRONG>o</STRONG> The routine <STRONG>slk_attr</STRONG> is not part of XPG4, nor is it present in
- SVr4. See the <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> manual page for details.
+ <EM>PDCurses</EM> and NetBSD <EM>curses</EM> incorporate some <EM>ncurses</EM> extensions.
+ Individual man pages indicate where this is the case.
- <STRONG>o</STRONG> The routines <STRONG>getmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mouseinterval</STRONG>, and
- <STRONG>wenclose</STRONG> relating to mouse interfacing are not part of XPG4, nor
- are they present in SVr4. See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual page for
- details.
- <STRONG>o</STRONG> The routine <STRONG>mcprint</STRONG> was not present in any previous curses
- implementation. See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details.
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+ X/Open Curses defines two levels of conformance, "base" and "enhanced".
+ The latter includes several additional features, such as wide-character
+ and color support. <EM>ncurses</EM> intends base-level conformance with X/Open
+ Curses, and supports nearly all its enhanced features.
- <STRONG>o</STRONG> The routine <STRONG>wresize</STRONG> is not part of XPG4, nor is it present in SVr4.
- See the <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual page for details.
+ Differences between X/Open Curses and <EM>ncurses</EM> are documented in the
+ "PORTABILITY" sections of applicable man pages.
- <STRONG>o</STRONG> The <EM>WINDOW</EM> structure's internal details can be hidden from
- application programs. See <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> for the discussion of
- <STRONG>is_scrollok</STRONG>, etc.
- <STRONG>o</STRONG> This implementation can be configured to provide rudimentary
- support for multi-threaded applications. See <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> for
- details.
+</PRE><H3><a name="h3-Error-Checking">Error Checking</a></H3><PRE>
+ In many cases, X/Open Curses is vague about error conditions, omitting
+ some of the SVr4 documentation.
- <STRONG>o</STRONG> This implementation can also be configured to provide a set of
- functions which improve the ability to manage multiple screens.
- See <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> for details.
+ Unlike other implementations, this one checks parameters such as
+ pointers to <EM>WINDOW</EM> structures to ensure they are not null. The main
+ reason for providing this behavior is to guard against programmer
+ error. The standard interface does not provide a way for the library
+ to tell an application which of several possible errors were detected.
+ Relying on this (or some other) extension will adversely affect the
+ portability of curses applications.
</PRE><H3><a name="h3-Padding-Differences">Padding Differences</a></H3><PRE>
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
<li><a href="#h3-Error-Checking">Error Checking</a></li>
-<li><a href="#h3-Extensions-Versus-Portability">Extensions Versus Portability</a></li>
<li><a href="#h3-Padding-Differences">Padding Differences</a></li>
<li><a href="#h3-Header-Files">Header Files</a></li>
</ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: scr_dump.5,v 1.41 2023/12/23 16:27:25 tom Exp @
+ * @Id: scr_dump.5,v 1.42 2023/12/30 22:06:36 tom Exp @
+ *SH SYNOPSIS
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<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>scr_dump 5 2023-12-23 ncurses 6.4 File formats</TITLE>
+<TITLE>scr_dump 5 2023-12-30 ncurses 6.4 File formats</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">scr_dump 5 2023-12-23 ncurses 6.4 File formats</H1>
+<H1 class="no-header">scr_dump 5 2023-12-30 ncurses 6.4 File formats</H1>
<PRE>
<STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG> File formats <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
scr_dump - <EM>curses</EM> screen dump
-</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
- <STRONG>scr_dump</STRONG>
-
-
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
The curses library provides applications with the ability to write the
contents of a window to an external file using <STRONG>scr_dump</STRONG> or <STRONG>putwin</STRONG>, and
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- There is no standard format for <STRONG>putwin</STRONG>. This section gives a brief
- description of the existing formats.
+ There is no standard format for <EM>curses</EM> screen dumps. A brief survey of
+ the existing implementations follows.
</PRE><H3><a name="h3-X_Open-Curses">X/Open Curses</a></H3><PRE>
- Refer to <EM>X/Open</EM> <EM>Curses,</EM> <EM>Issue</EM> <EM>7</EM> (2009).
-
- X/Open's documentation for <EM>enhanced</EM> <EM>curses</EM> says only:
+ X/Open Curses, Issue 7 specifies little. It says (boldface emphasis
+ added)
- The <STRONG>getwin(</STRONG> <STRONG>)</STRONG> function reads window-related data stored in the file
- by <EM>putwin(</EM> <EM>)</EM>. The function then creates and initializes a new
+ "[t]he <EM>getwin()</EM> function reads window-related data stored in the
+ file by <EM>putwin()</EM>. The function then creates and initializes a new
window using that data.
- The <STRONG>putwin(</STRONG> <STRONG>)</STRONG> function writes all data associated with <EM>win</EM> into the
- <STRONG>stdio(3)</STRONG> stream to which <EM>filep</EM> points, using an <STRONG>unspecified</STRONG> <STRONG>format</STRONG>.
- This information can be retrieved later using <STRONG>getwin(</STRONG> <STRONG>)</STRONG>.
-
- In the mid-1990s when the X/Open Curses document was written, there
- were still systems using older, less capable curses libraries (aside
- from the BSD curses library which was not relevant to X/Open because it
- did not meet the criteria for <EM>base</EM> <EM>curses</EM>). The document explained the
- term "enhanced" as follows:
-
- <STRONG>o</STRONG> Shading is used to identify <EM>X/Open</EM> <EM>Enhanced</EM> <EM>Curses</EM> material,
- relating to interfaces included to provide enhanced capabilities
- for applications originally written to be compiled on systems
- based on the Unix operating system. Therefore, the features
- described may not be present on systems that conform to <STRONG>XPG4</STRONG> <STRONG>or</STRONG>
- <STRONG>to</STRONG> <STRONG>earlier</STRONG> <STRONG>XPG</STRONG> <STRONG>releases</STRONG>. The relevant reference pages may
- provide additional or more specific portability warnings about
- use of the material.
+ The <EM>putwin()</EM> function writes all data associated with <EM>win</EM> into the
+ <EM>stdio</EM> stream to which <EM>filep</EM> points, using an <STRONG>unspecified</STRONG> <STRONG>format</STRONG>.
+ This information can be retrieved later using <EM>getwin()</EM>."
- In the foregoing, emphasis was added to <STRONG>unspecified</STRONG> <STRONG>format</STRONG> and to <STRONG>XPG4</STRONG>
- <STRONG>or</STRONG> <STRONG>to</STRONG> <STRONG>earlier</STRONG> <STRONG>XPG</STRONG> <STRONG>releases</STRONG>, for clarity.
+ In the mid-1990s when the X/Open Curses document was written, there
+ were still System V systems using older, less capable <EM>curses</EM> libraries.
+ BSD <EM>curses</EM> was not relevant to X/Open because it did not meet the
+ criteria for base-level conformance; see <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
-</PRE><H3><a name="h3-
Unix-System-V">Unix System V</a></H3><PRE>
- Unix System V curses identified the file format by writing a "magic
- number" at the beginning of the dump. The <EM>WINDOW</EM> data and the lines of
- text follow, all in binary form.
+</PRE><H3><a name="h3-
System-V">System V</a></H3><PRE>
+ System V <EM>curses</EM> identified the file format by writing a "magic number"
+ at the beginning of the dump. The <EM>WINDOW</EM> data and the lines of text
+ follow, all in binary form.
- The Solaris curses source has these definitions:
+ Solaris <EM>curses</EM> has the following definitions.
/* terminfo magic number */
#define MAGNUM 0432
#define SVR3_DUMP_MAGIC_NUMBER 0434
That is, the feature was likely introduced in SVr2 (1984), and improved
- in SVr3 (1987). The Solaris curses source has no magic number for SVr4
- (1989). Other operating systems (AIX and HP-UX) use a magic number
- which would correspond to this definition:
+ in SVr3 (1987). Solaris <EM>curses</EM> has no magic number for SVr4 (1989).
+ Other System V operating systems (AIX and HP-UX) use a magic number
+ that would correspond to the following.
/* curses screen dump magic number */
#define SVR4_DUMP_MAGIC_NUMBER 0435
- That octal number in bytes is 001, 035. Because most Unix vendors use
- big-endian hardware, the magic number is written with the high-order
- byte first, e.g.,
+ That octal number in bytes is 001, 035. Because most Unix vendors at
+ the time used big-endian hardware, the magic number is written with the
+ high-order byte first.
\001\035
- After the magic number, the <EM>WINDOW</EM> structure and line-data are written
- in binary format. While the magic number used by the Unix systems can
- be seen using <STRONG>od(1)</STRONG>, none of the Unix systems documents the format used
- for screen-dumps.
+ After the magic number, the <EM>WINDOW</EM> structure and line data are written
+ in binary format. While the magic number used by these systems can be
+ observed with <STRONG>od(1)</STRONG>, none of them documents the format used for screen
+ dumps.
- The Unix systems do not use identical formats. While collecting
- information for for this manual page, the <EM>savescreen</EM> test-program
- produced dumps of different size (all on 64-bit hardware, on 40x80
- screens):
+ Nor do they use an identical format, even with the System V family.
+ The <EM>ncurses</EM> <EM>savescreen</EM> test program was used to collect information for
+ this manual page. It produced dumps of different size (all on 64-bit
+ hardware, on 40x80 screens):
<STRONG>o</STRONG> AIX (51817 bytes)
</PRE><H3><a name="h3-Solaris">Solaris</a></H3><PRE>
- As noted above, Solaris curses has no magic number corresponding to
- SVr4 curses. This is odd since Solaris was the first operating system
- to pass the SVr4 guidelines. Solaris has two versions of curses:
+ As noted above, Solaris <EM>curses</EM> has no magic number corresponding to
+ SVr4 <EM>curses.</EM> This is odd, since Solaris was the first operating system
+ to meet the SVr4 guidelines. Solaris furthermore supplies two versions
+ of <EM>curses.</EM>
- <STRONG>o</STRONG> The default curses library uses the SVr3 magic number.
+ <STRONG>o</STRONG> The default <EM>curses</EM> library uses the SVr3 magic number.
- <STRONG>o</STRONG> There is an alternate curses library in <STRONG>/usr/xpg4</STRONG>. This uses a
- textual format with no magic number.
+ <STRONG>o</STRONG> An alternate <EM>curses</EM> library (which we term <EM>xcurses),</EM> available in
+ <EM>/usr/xpg4,</EM> uses a textual format with no magic number.
- According to the copyright notice, the <EM>xpg4</EM> Solaris curses library
- was developed by MKS (Mortice Kern Systems) from 1990 to 1995.
+ According to its copyright notice, this <EM>xcurses</EM> library was
+ developed by MKS (Mortice Kern Systems) from 1990 to 1995.
- Like ncurses6, there is a file-header with parameters. Unlike
- ncurses6, the contents of the window are written piecemeal, with
- coordinates and attributes for each chunk of text rather than
+ Like ncurses6, it includes a header with parameters. Unlike
+ ncurses6, the contents of the window are written piecemeal, with
+ coordinates and attributes for each chunk of text rather than
writing the whole window from top to bottom.
</PRE><H3><a name="h3-PDCurses">PDCurses</a></H3><PRE>
- PDCurses added support for screen dumps in version 2.7 (2005). Like
- Unix System V and ncurses5, it writes the <EM>WINDOW</EM> structure in binary,
- but begins the file with its three-byte identifier "PDC", followed by a
- one-byte version, e.g.,
+ <EM>PDCurses</EM> added support for screen dumps in version 2.7 (2005). Like
+ System V and ncurses5, it writes the <EM>WINDOW</EM> structure in binary, but
+ begins the file with its three-byte identifier "PDC", followed by a
+ single-byte version number.
"PDC\001"
</PRE><H3><a name="h3-NetBSD">NetBSD</a></H3><PRE>
- As of April 2017, NetBSD curses does not support <STRONG>scr_dump</STRONG> and
+ As of April 2017, NetBSD <EM>curses</EM> does not support <STRONG>scr_dump</STRONG> and
<STRONG>scr_restore</STRONG> (or <STRONG>scr_init</STRONG>, <STRONG>scr_set</STRONG>), although it has <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG>.
- Like ncurses5, NetBSD <STRONG>putwin</STRONG> does not identify its dumps with a useful
+ Like ncurses5, NetBSD <STRONG>putwin</STRONG> does not identify its dumps with a useful
magic number. It writes
- <STRONG>o</STRONG> the curses shared library major and minor versions as the first two
- bytes (e.g., 7 and 1),
+ <STRONG>o</STRONG> the <EM>curses</EM> shared library major and minor versions as the first two
+ bytes (for example, 7 and 1),
<STRONG>o</STRONG> followed by a binary dump of the <EM>WINDOW</EM>,
- <STRONG>o</STRONG> some data for wide-characters referenced by the <EM>WINDOW</EM> structure,
+ <STRONG>o</STRONG> some data for wide characters referenced by the <EM>WINDOW</EM> structure,
and
<STRONG>o</STRONG> finally, lines as done by other implementations.
</PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
- Given a simple program which writes text to the screen (and for the
+ Given a simple program which writes text to the screen (and for the
sake of example, limiting the screen-size to 10x20):
#include <curses.h>
<STRONG>o</STRONG> The actual color pair values are not written to the file.
- <STRONG>o</STRONG> All characters are shown in printable form; spaces are "\s" to
+ <STRONG>o</STRONG> All characters are shown in printable form; spaces are "\s" to
ensure they are not overlooked.
- <STRONG>o</STRONG> Attributes are written in escaped curly braces, e.g., "\{BOLD}",
+ <STRONG>o</STRONG> Attributes are written in escaped curly braces, e.g., "\{BOLD}",
and may include a color pair (C1 or C2 in this example).
- <STRONG>o</STRONG> The parameters in the header are written out only if they are
+ <STRONG>o</STRONG> The parameters in the header are written out only if they are
nonzero. When reading back, order does not matter.
Running the same program with Solaris <EM>xpg4</EM> curses gives this dump:
9,19,0,0,
CUR=11,5
- Solaris <STRONG>getwin</STRONG> requires that all parameters are present, and in the
- same order. The <EM>xpg4</EM> curses library does not know about the <STRONG>bce</STRONG> (back
+ Solaris <STRONG>getwin</STRONG> requires that all parameters are present, and in the
+ same order. The <EM>xpg4</EM> curses library does not know about the <STRONG>bce</STRONG> (back
color erase) capability, and does not color the window background.
- On the other hand, the SVr4 curses library does know about the
- background color. However, its screen dumps are in binary. Here is
+ On the other hand, the SVr4 curses library does know about the
+ background color. However, its screen dumps are in binary. Here is
the corresponding dump (using "od -t x1"):
0000000 1c 01 c3 d6 f3 58 05 00 0b 00 0a 00 14 00 00 00
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
-<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-ncurses6">ncurses6</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
<li><a href="#h3-X_Open-Curses">X/Open Curses</a></li>
-<li><a href="#h3-Unix-System-V">Unix System V</a></li>
+<li><a href="#h3-System-V">System V</a></li>
<li><a href="#h3-Solaris">Solaris</a></li>
<li><a href="#h3-PDCurses">PDCurses</a></li>
<li><a href="#h3-NetBSD">NetBSD</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: term.5,v 1.69 2023/12/23 16:08:25 tom Exp @
+ * @Id: term.5,v 1.70 2023/12/30 21:36:32 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<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>term 5 2023-12-23 ncurses 6.4 File formats</TITLE>
+<TITLE>term 5 2023-12-30 ncurses 6.4 File formats</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">term 5 2023-12-23 ncurses 6.4 File formats</H1>
+<H1 class="no-header">term 5 2023-12-30 ncurses 6.4 File formats</H1>
<PRE>
<STRONG><A HREF="term.5.html">term(5)</A></STRONG> File formats <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
b) <EM>terminal</EM> <EM>names</EM>,
- c) <EM>boolean</EM> <EM>flags</EM>,
+ c) <EM>Boolean</EM> <EM>flags</EM>,
d) <EM>numbers</EM>,
(2) the size, in bytes, of the <EM>terminal</EM> <EM>names</EM> section;
- (3) the number of bytes in the <EM>boolean</EM> <EM>flags</EM> section;
+ (3) the number of bytes in the <EM>Boolean</EM> <EM>flags</EM> section;
(4) the number of short integers in the <EM>numbers</EM> section;
(6) the size, in bytes, of the <EM>string</EM> <EM>table</EM>.
- The capabilities in the <EM>boolean</EM> <EM>flags</EM>, <EM>numbers</EM>, and <EM>strings</EM> sections
+ The capabilities in the <EM>Boolean</EM> <EM>flags</EM>, <EM>numbers</EM>, and <EM>strings</EM> sections
are in the same order as the file <term.h>.
Short integers are signed, in the range -32768 to 32767. They are
the corresponding table.
The integer value -1 is represented by two bytes 0377, 0377.
- Absent boolean values are represented by the byte 0 (false).
+ Absent Boolean values are represented by the byte 0 (false).
<STRONG>o</STRONG> If a capability has been canceled from this terminal, tic stores a
-2 in the corresponding table.
The integer value -2 is represented by two bytes 0377, 0376.
- The boolean value -2 is represented by the byte 0376.
+ The Boolean value -2 is represented by the byte 0376.
<STRONG>o</STRONG> Other negative values are illegal.
the terminal, separated by the "|" character. The <EM>terminal</EM> <EM>names</EM>
section is terminated with an ASCII NUL character.
- The <EM>boolean</EM> <EM>flags</EM> section has one byte for each flag. Boolean
+ The <EM>Boolean</EM> <EM>flags</EM> section has one byte for each flag. Boolean
capabilities are either 1 or 0 (true or false) according to whether the
terminal supports the given capability or not.
- Between the <EM>boolean</EM> <EM>flags</EM> section and the <EM>number</EM> section, a null byte
+ Between the <EM>Boolean</EM> <EM>flags</EM> section and the <EM>number</EM> section, a null byte
will be inserted, if necessary, to ensure that the <EM>number</EM> section
begins on an even byte This is a relic of the PDP-11's word-addressed
architecture, originally designed to avoid traps induced by addressing
a word on an odd byte boundary. All short integers are aligned on a
short word boundary.
- The <EM>numbers</EM> section is similar to the <EM>boolean</EM> <EM>flags</EM> section. Each
+ The <EM>numbers</EM> section is similar to the <EM>Boolean</EM> <EM>flags</EM> section. Each
capability takes up two bytes, and is stored as a little-endian short
integer.
The previous section describes the conventional terminfo binary format.
With some minor variations of the offsets (see PORTABILITY), the same
binary format is used in all modern Unix systems. Each system uses a
- predefined set of boolean, number or string capabilities.
+ predefined set of Boolean, number or string capabilities.
The <EM>ncurses</EM> libraries and applications support extended terminfo binary
format, allowing users to define capabilities which are loaded at
First, it reads the extended header (5 short integers):
- (1) count of extended boolean capabilities
+ (1) count of extended Boolean capabilities
(2) count of extended numeric capabilities
The extended string table contains values for string capabilities.
After the end of these values, it contains the names for each of the
- extended capabilities in order, e.g., booleans, then numbers and
+ extended capabilities in order, e.g., Booleans, then numbers and
finally strings.
By storing terminal descriptions in this way, <EM>ncurses</EM> is able to
(resulting in missing entries). The routine <STRONG>setupterm</STRONG> must be prepared
for both possibilities - this is why the numbers and sizes are
included. Also, new capabilities must always be added at the end of
- the lists of boolean, number, and string capabilities.
+ the lists of Boolean, number, and string capabilities.
</PRE><H3><a name="h3-Binary-Format">Binary Format</a></H3><PRE>
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: terminfo.head,v 1.59 2023/12/23 23:44:58 tom Exp @
+ * @Id: terminfo.head,v 1.60 2023/12/30 22:21:45 tom Exp @
* Head of terminfo man page ends here
****************************************************************************
* Copyright 2018-2022,2023 Thomas E. Dickey *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: terminfo.tail,v 1.140 2023/12/23 16:23:35 tom Exp @
+ * @Id: terminfo.tail,v 1.141 2023/12/30 21:36:32 tom Exp @
*.in -2
*.in +2
*.in -2
<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>terminfo 5 2023-12-23 ncurses 6.4 File formats</TITLE>
+<TITLE>terminfo 5 2023-12-30 ncurses 6.4 File formats</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">terminfo 5 2023-12-23 ncurses 6.4 File formats</H1>
+<H1 class="no-header">terminfo 5 2023-12-30 ncurses 6.4 File formats</H1>
<PRE>
<STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> File formats <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
have, by specifying how to perform screen operations, and by specifying
padding requirements and initialization sequences.
- This manual describes <EM>ncurses</EM> version 6.4 (patch 20231223).
+ This manual describes <EM>ncurses</EM> version 6.4 (patch 20231230).
</PRE><H3><a name="h3-terminfo-Entry-Syntax"><EM>terminfo</EM> Entry Syntax</a></H3><PRE>
features.
After the first field (giving the name(s) of the terminal entry), there
- should be one or more <EM>capability</EM> fields. These are boolean, numeric or
+ should be one or more <EM>capability</EM> fields. These are Boolean, numeric or
string names with corresponding values:
<STRONG>o</STRONG> Boolean capabilities are true when present, false when absent.
- There is no explicit value for boolean capabilities.
+ There is no explicit value for Boolean capabilities.
<STRONG>o</STRONG> Numeric capabilities have a "#" following the name, then an
unsigned decimal integer value.
(#<EM>i</EM>) indicates the <EM>i</EM>th parameter.
- These are the boolean capabilities:
+ These are the Boolean capabilities:
<STRONG>Variable</STRONG> <STRONG>Cap-</STRONG> <STRONG>TCap</STRONG> <STRONG>Description</STRONG>
capabilities. The <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> programs provide the <STRONG>-x</STRONG> option for
this purpose. When <STRONG>-x</STRONG> is set, <STRONG>tic</STRONG> treats unknown capabilities as user-
defined. That is, if <STRONG>tic</STRONG> encounters a capability name which it does
- not recognize, it infers its type (boolean, number or string) from the
+ not recognize, it infers its type (Boolean, number or string) from the
syntax and makes an extended table entry for that capability. The
<STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG> function makes this information conditionally
available to applications. The <EM>ncurses</EM> library provides the data
<STRONG>o</STRONG> User-defined capability strings whose name begins with "k" are
treated as function keys.
- <STRONG>o</STRONG> The types (boolean, number, string) determined by <STRONG>tic</STRONG> can be
+ <STRONG>o</STRONG> The types (Boolean, number, string) determined by <STRONG>tic</STRONG> can be
inferred by successful calls on <STRONG>tigetflag</STRONG>, etc.
<STRONG>o</STRONG> If the capability name happens to be two characters, the capability
predefined set of capabilities, in practice it has been limited to the
capabilities defined by terminfo implementations. As a rule, user-
defined capabilities intended for use by termcap applications should be
- limited to booleans and numbers to avoid running past the 1023 byte
+ limited to Booleans and numbers to avoid running past the 1023 byte
limit assumed by termcap implementations and their applications. In
particular, providing extended sets of function keys (past the 60
numbered keys and the handful of special named keys) is best done using
using <STRONG>ri</STRONG> or <STRONG>ind</STRONG> on many terminals without a true insert/delete line,
and is often faster even on terminals with those features.
- The boolean <STRONG>non_dest_scroll_region</STRONG> should be set if each scrolling
+ The Boolean <STRONG>non_dest_scroll_region</STRONG> should be set if each scrolling
window is effectively a view port on a screen-sized canvas. To test
for this capability, create a scrolling region in the middle of the
screen, write something to the bottom line, move the cursor to the top
A command to erase or blank the status line may be specified as <STRONG>dsl</STRONG>.
- The boolean capability <STRONG>eslok</STRONG> specifies that escape sequences, tabs,
+ The Boolean capability <STRONG>eslok</STRONG> specifies that escape sequences, tabs,
etc., work ordinarily in the status line.
The <EM>ncurses</EM> implementation does not yet use any of these capabilities.
color pairs to their default values for the terminal. Some terminals
(including many PC terminal emulators) erase screen areas with the
current background color rather than the power-up default background;
- these should have the boolean capability <STRONG>bce</STRONG>.
+ these should have the Boolean capability <STRONG>bce</STRONG>.
While the curses library works with <EM>color</EM> <EM>pairs</EM> (reflecting the
inability of some devices to set foreground and background colors
indicate that colors can be modified. If so, the <STRONG>initc</STRONG> capability
will take a color number (0 to <STRONG>colors</STRONG> - 1)and three more parameters
which describe the color. These three parameters default to being
- interpreted as RGB (Red, Green, Blue) values. If the boolean
+ interpreted as RGB (Red, Green, Blue) values. If the Boolean
capability <STRONG>hls</STRONG> is present, they are instead as HLS (Hue, Lightness,
Saturation) indices. The ranges are terminal-dependent.
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: tic.1m,v 1.105 2023/12/23 16:08:25 tom Exp @
+ * @Id: tic.1m,v 1.106 2023/12/30 21:36:32 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<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>tic 1m 2023-12-23 ncurses 6.4 User commands</TITLE>
+<TITLE>tic 1m 2023-12-30 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">tic 1m 2023-12-23 ncurses 6.4 User commands</H1>
+<H1 class="no-header">tic 1m 2023-12-30 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG> User commands <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>
<STRONG>-x</STRONG> Treat unknown capabilities as user-defined (see <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>).
That is, if you supply a capability name which <STRONG>tic</STRONG> does not
- recognize, it will infer its type (boolean, number or string) from
+ recognize, it will infer its type (Boolean, number or string) from
the syntax and make an extended table entry for that. User-
defined capability strings whose name begins with "k" are treated
as function keys.
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: tput.1,v 1.96 2023/12/23 20:55:36 tom Exp @
+ * @Id: tput.1,v 1.97 2023/12/31 00:16:41 tom Exp @
* longname was added in October 1989.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<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>tput 1 2023-12-23 ncurses 6.4 User commands</TITLE>
+<TITLE>tput 1 2023-12-30 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">tput 1 2023-12-23 ncurses 6.4 User commands</H1>
+<H1 class="no-header">tput 1 2023-12-30 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> User commands <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
- <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <EM>cap-code</EM> [<EM>parameter</EM> ...]
+ <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] {<EM>cap-code</EM> [<EM>parameter</EM> ...]} ...
<STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] [<STRONG>-x</STRONG>] <STRONG>clear</STRONG>
Otherwise, <STRONG>reset</STRONG> acts identically to <STRONG>init</STRONG>.
<STRONG>longname</STRONG>
- If the terminal database is present and an entry for the user's
+ A terminfo entry begins with one or more names by which an
+ application can refer to the entry, before the list of terminal
+ capabilities. The names are separated by "|" characters.
+ X/Open states that the last name is the "long name" and also
+ that it may include blanks.
+
+ <STRONG>tic</STRONG> warns if the last name does not include blanks, to
+ accommodate old terminfo entries which treated the long name as
+ an optional feature. The long name is often referred to as the
+ description field.
+
+ If the terminal database is present and an entry for the user's
terminal exists (see <STRONG>-T</STRONG> <EM>type</EM> above), <STRONG>tput</STRONG> reports the terminal's
- description (or "long name") to the standard output, without a
- trailing newline. See <STRONG><A HREF="term.5.html">term(5)</A></STRONG>.
+ description (or "long name") to the standard output, without a
+ trailing newline. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
</PRE><H3><a name="h3-Aliases">Aliases</a></H3><PRE>
- <STRONG>tput</STRONG> handles the <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG> commands specially: it allows
+ <STRONG>tput</STRONG> handles the <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG> commands specially: it allows
for the possibility that it is invoked by a link with those names.
- If <STRONG>tput</STRONG> is invoked by a link named <STRONG>reset</STRONG>, this has the same effect as
- <STRONG>tput</STRONG> <STRONG>reset</STRONG>. The <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> utility also treats a link named <STRONG>reset</STRONG>
+ If <STRONG>tput</STRONG> is invoked by a link named <STRONG>reset</STRONG>, this has the same effect as
+ <STRONG>tput</STRONG> <STRONG>reset</STRONG>. The <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> utility also treats a link named <STRONG>reset</STRONG>
specially.
Before <EM>ncurses</EM> 6.1, the two utilities were different from each other:
- <STRONG>o</STRONG> <STRONG>tset</STRONG> utility reset the terminal modes and special characters (not
+ <STRONG>o</STRONG> <STRONG>tset</STRONG> utility reset the terminal modes and special characters (not
done with <STRONG>tput</STRONG>).
- <STRONG>o</STRONG> On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal capabilities for
- resetting the terminal was more limited, i.e., only <STRONG>reset_1string</STRONG>,
- <STRONG>reset_2string</STRONG> and <STRONG>reset_file</STRONG> in contrast to the tab-stops and
+ <STRONG>o</STRONG> On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal capabilities for
+ resetting the terminal was more limited, i.e., only <STRONG>reset_1string</STRONG>,
+ <STRONG>reset_2string</STRONG> and <STRONG>reset_file</STRONG> in contrast to the tab-stops and
margins which are set by this utility.
- <STRONG>o</STRONG> The <STRONG>reset</STRONG> program is usually an alias for <STRONG>tset</STRONG>, because of this
+ <STRONG>o</STRONG> The <STRONG>reset</STRONG> program is usually an alias for <STRONG>tset</STRONG>, because of this
difference with resetting terminal modes and special characters.
- With the changes made for <EM>ncurses</EM> 6.1, the <EM>reset</EM> feature of the two
+ With the changes made for <EM>ncurses</EM> 6.1, the <EM>reset</EM> feature of the two
programs is (mostly) the same. A few differences remain:
- <STRONG>o</STRONG> The <STRONG>tset</STRONG> program waits one second when resetting, in case it
+ <STRONG>o</STRONG> The <STRONG>tset</STRONG> program waits one second when resetting, in case it
happens to be a hardware terminal.
- <STRONG>o</STRONG> The two programs write the terminal initialization strings to
- different streams (i.e., the standard error for <STRONG>tset</STRONG> and the
+ <STRONG>o</STRONG> The two programs write the terminal initialization strings to
+ different streams (i.e., the standard error for <STRONG>tset</STRONG> and the
standard output for <STRONG>tput</STRONG>).
- <STRONG>Note:</STRONG> although these programs write to different streams,
- redirecting their output to a file will capture only part of their
- actions. The changes to the terminal modes are not affected by
+ <STRONG>Note:</STRONG> although these programs write to different streams,
+ redirecting their output to a file will capture only part of their
+ actions. The changes to the terminal modes are not affected by
redirecting the output.
- If <STRONG>tput</STRONG> is invoked by a link named <STRONG>init</STRONG>, this has the same effect as
+ If <STRONG>tput</STRONG> is invoked by a link named <STRONG>init</STRONG>, this has the same effect as
<STRONG>tput</STRONG> <STRONG>init</STRONG>. Again, you are less likely to use that link because another
program named <STRONG>init</STRONG> has a more well-established use.
</PRE><H3><a name="h3-Terminal-Size">Terminal Size</a></H3><PRE>
Besides the special commands (e.g., <STRONG>clear</STRONG>), tput treats certain
- terminfo capabilities specially: <STRONG>lines</STRONG> and <STRONG>cols</STRONG>. tput calls
+ terminfo capabilities specially: <STRONG>lines</STRONG> and <STRONG>cols</STRONG>. tput calls
<STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to obtain the terminal size:
<STRONG>o</STRONG> first, it gets the size from the terminal database (which generally
- is not provided for terminal emulators which do not have a fixed
+ is not provided for terminal emulators which do not have a fixed
window size)
- <STRONG>o</STRONG> then it asks the operating system for the terminal's size (which
+ <STRONG>o</STRONG> then it asks the operating system for the terminal's size (which
generally works, unless connecting via a serial line which does not
support <EM>NAWS</EM>: negotiations about window size).
- <STRONG>o</STRONG> finally, it inspects the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM>
+ <STRONG>o</STRONG> finally, it inspects the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM>
which may override the terminal size.
- If the <STRONG>-T</STRONG> option is given tput ignores the environment variables by
- calling <STRONG>use_tioctl(TRUE)</STRONG>, relying upon the operating system (or
+ If the <STRONG>-T</STRONG> option is given tput ignores the environment variables by
+ calling <STRONG>use_tioctl(TRUE)</STRONG>, relying upon the operating system (or
finally, the terminal database).
</PRE><H2><a name="h2-EXIT-STATUS">EXIT STATUS</a></H2><PRE>
If the <STRONG>-S</STRONG> option is used, <STRONG>tput</STRONG> checks for errors from each line, and if
- any errors are found, will set the exit status to 4 plus the number of
- lines with errors. If no errors are found, the exit status is <STRONG>0</STRONG>. No
- indication of which line failed can be given so exit status <STRONG>1</STRONG> will
- never appear. Exit statuses <STRONG>2</STRONG>, <STRONG>3</STRONG>, and <STRONG>4</STRONG> retain their usual
- interpretation. If the <STRONG>-S</STRONG> option is not used, the exit status depends
+ any errors are found, will set the exit status to 4 plus the number of
+ lines with errors. If no errors are found, the exit status is <STRONG>0</STRONG>. No
+ indication of which line failed can be given so exit status <STRONG>1</STRONG> will
+ never appear. Exit statuses <STRONG>2</STRONG>, <STRONG>3</STRONG>, and <STRONG>4</STRONG> retain their usual
+ interpretation. If the <STRONG>-S</STRONG> option is not used, the exit status depends
on the type of <EM>cap-code</EM>:
<EM>Boolean</EM>
a value of <STRONG>0</STRONG> is set for TRUE and <STRONG>1</STRONG> for FALSE.
- <EM>string</EM> a value of <STRONG>0</STRONG> is set if the <EM>cap-code</EM> is defined for this
- terminal <EM>type</EM> (the value of <EM>cap-code</EM> is returned on standard
- output); a value of <STRONG>1</STRONG> is set if <EM>cap-code</EM> is not defined for
+ <EM>string</EM> a value of <STRONG>0</STRONG> is set if the <EM>cap-code</EM> is defined for this
+ terminal <EM>type</EM> (the value of <EM>cap-code</EM> is returned on standard
+ output); a value of <STRONG>1</STRONG> is set if <EM>cap-code</EM> is not defined for
this terminal <EM>type</EM> (nothing is written to standard output).
<EM>integer</EM>
- a value of <STRONG>0</STRONG> is always set, whether or not <EM>cap-code</EM> is
- defined for this terminal <EM>type</EM>. To determine if <EM>cap-code</EM> is
- defined for this terminal <EM>type</EM>, the user must test the value
- written to standard output. A value of <STRONG>-1</STRONG> means that <EM>cap-</EM>
+ a value of <STRONG>0</STRONG> is always set, whether or not <EM>cap-code</EM> is
+ defined for this terminal <EM>type</EM>. To determine if <EM>cap-code</EM> is
+ defined for this terminal <EM>type</EM>, the user must test the value
+ written to standard output. A value of <STRONG>-1</STRONG> means that <EM>cap-</EM>
<EM>code</EM> is not defined for this terminal <EM>type</EM>.
- <EM>other</EM> <STRONG>reset</STRONG> or <STRONG>init</STRONG> may fail to find their respective files. In
+ <EM>other</EM> <STRONG>reset</STRONG> or <STRONG>init</STRONG> may fail to find their respective files. In
that case, the exit status is set to 4 + <STRONG>errno</STRONG>.
- Any other exit status indicates an error; see section "DIAGNOSTICS"
+ Any other exit status indicates an error; see section "DIAGNOSTICS"
below.
</PRE><H2><a name="h2-DIAGNOSTICS">DIAGNOSTICS</a></H2><PRE>
- <STRONG>tput</STRONG> prints the following error messages and sets the corresponding
+ <STRONG>tput</STRONG> prints the following error messages and sets the corresponding
exit statuses.
exit status error message
------------------------------------------------------------------------
- <STRONG>0</STRONG> (<EM>cap-code</EM> is a numeric variable that is not specified in
- the <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> database for this terminal type, e.g.
+ <STRONG>0</STRONG> (<EM>cap-code</EM> is a numeric variable that is not specified in
+ the <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> database for this terminal type, e.g.
<STRONG>tput</STRONG> <STRONG>-T450</STRONG> <STRONG>lines</STRONG> and <STRONG>tput</STRONG> <STRONG>-Thp2621</STRONG> <STRONG>xmc</STRONG>)
<STRONG>1</STRONG> no error message is printed, see the <STRONG>EXIT</STRONG> <STRONG>STATUS</STRONG> section.
<STRONG>2</STRONG> usage error
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- This implementation of <STRONG>tput</STRONG> differs from AT&T <STRONG>tput</STRONG> in two important
+ This implementation of <STRONG>tput</STRONG> differs from AT&T <STRONG>tput</STRONG> in two important
areas:
- <STRONG>o</STRONG> <STRONG>tput</STRONG> <EM>cap-code</EM> writes to the standard output. That need not be a
- regular terminal. However, the subcommands which manipulate
+ <STRONG>o</STRONG> <STRONG>tput</STRONG> <EM>cap-code</EM> writes to the standard output. That need not be a
+ regular terminal. However, the subcommands which manipulate
terminal modes may not use the standard output.
- The AT&T implementation's <STRONG>init</STRONG> and <STRONG>reset</STRONG> commands use the BSD
- (4.1c) <STRONG>tset</STRONG> source, which manipulates terminal modes. It
- successively tries standard output, standard error, standard input
+ The AT&T implementation's <STRONG>init</STRONG> and <STRONG>reset</STRONG> commands use the BSD
+ (4.1c) <STRONG>tset</STRONG> source, which manipulates terminal modes. It
+ successively tries standard output, standard error, standard input
before falling back to "/dev/tty" and finally just assumes a 1200Bd
terminal. When updating terminal modes, it ignores errors.
- Until changes made after <EM>ncurses</EM> 6.0, <STRONG>tput</STRONG> did not modify terminal
+ Until changes made after <EM>ncurses</EM> 6.0, <STRONG>tput</STRONG> did not modify terminal
modes. <STRONG>tput</STRONG> now uses a similar scheme, using functions shared with
- <STRONG>tset</STRONG> (and ultimately based on the 4.4BSD <STRONG>tset</STRONG>). If it is not able
+ <STRONG>tset</STRONG> (and ultimately based on the 4.4BSD <STRONG>tset</STRONG>). If it is not able
to open a terminal, e.g., when running in <STRONG>cron(1)</STRONG>, <STRONG>tput</STRONG> will return
an error.
- <STRONG>o</STRONG> AT&T <STRONG>tput</STRONG> guesses the type of its <EM>cap-code</EM> operands by seeing if
+ <STRONG>o</STRONG> AT&T <STRONG>tput</STRONG> guesses the type of its <EM>cap-code</EM> operands by seeing if
all of the characters are numeric, or not.
- Most implementations which provide support for <EM>cap-code</EM> operands
- use the <STRONG>tparm</STRONG> function to expand parameters in it. That function
- expects a mixture of numeric and string parameters, requiring <STRONG>tput</STRONG>
+ Most implementations which provide support for <EM>cap-code</EM> operands
+ use the <STRONG>tparm</STRONG> function to expand parameters in it. That function
+ expects a mixture of numeric and string parameters, requiring <STRONG>tput</STRONG>
to know which type to use.
- This implementation uses a table to determine the parameter types
+ This implementation uses a table to determine the parameter types
for the standard <EM>cap-code</EM> operands, and an internal library
function to analyze nonstandard <EM>cap-code</EM> operands.
- Besides providing more reliable operation than AT&T's utility, a
- portability problem is introduced by this analysis: An OpenBSD
- developer adapted the internal library function from <EM>ncurses</EM> to
- port NetBSD's termcap-based <STRONG>tput</STRONG> to terminfo. That had been
- modified to interpret multiple commands on a line. Portable
+ Besides providing more reliable operation than AT&T's utility, a
+ portability problem is introduced by this analysis: An OpenBSD
+ developer adapted the internal library function from <EM>ncurses</EM> to
+ port NetBSD's termcap-based <STRONG>tput</STRONG> to terminfo. That had been
+ modified to interpret multiple commands on a line. Portable
applications should not rely upon this feature; <EM>ncurses</EM> provides it
to support applications written specifically for OpenBSD.
This implementation (unlike others) can accept both <EM>termcap</EM> and
<EM>terminfo</EM> names for the <EM>cap-code</EM> feature, if <EM>termcap</EM> support is compiled
- in. However, the predefined <EM>termcap</EM> and <EM>terminfo</EM> names have two
+ in. However, the predefined <EM>termcap</EM> and <EM>terminfo</EM> names have two
ambiguities in this case (and the <EM>terminfo</EM> name is assumed):
- <STRONG>o</STRONG> The <EM>termcap</EM> name <STRONG>dl</STRONG> corresponds to the <EM>terminfo</EM> name <STRONG>dl1</STRONG> (delete
+ <STRONG>o</STRONG> The <EM>termcap</EM> name <STRONG>dl</STRONG> corresponds to the <EM>terminfo</EM> name <STRONG>dl1</STRONG> (delete
one line).
- The <EM>terminfo</EM> name <STRONG>dl</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>DL</STRONG> (delete a
+ The <EM>terminfo</EM> name <STRONG>dl</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>DL</STRONG> (delete a
given number of lines).
- <STRONG>o</STRONG> The <EM>termcap</EM> name <STRONG>ed</STRONG> corresponds to the <EM>terminfo</EM> name <STRONG>rmdc</STRONG> (end
+ <STRONG>o</STRONG> The <EM>termcap</EM> name <STRONG>ed</STRONG> corresponds to the <EM>terminfo</EM> name <STRONG>rmdc</STRONG> (end
delete mode).
- The <EM>terminfo</EM> name <STRONG>ed</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>cd</STRONG> (clear to
+ The <EM>terminfo</EM> name <STRONG>ed</STRONG> corresponds to the <EM>termcap</EM> name <STRONG>cd</STRONG> (clear to
end of screen).
- The <STRONG>longname</STRONG> and <STRONG>-S</STRONG> options, and the parameter-substitution features
- used in the <STRONG>cup</STRONG> example, were not supported in AT&T/USL <EM>curses</EM> before
+ The <STRONG>longname</STRONG> and <STRONG>-S</STRONG> options, and the parameter-substitution features
+ used in the <STRONG>cup</STRONG> example, were not supported in AT&T/USL <EM>curses</EM> before
SVr4 (1989). Later, 4.3BSD-Reno (1990) added support for <STRONG>longname</STRONG>, and
NetBSD (1994) added support for the parameter-substitution features.
- IEEE Std 1003.1/The Open Group Base Specifications Issue 7
- (POSIX.1-2008) documents only the operands for <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG>.
+ IEEE Std 1003.1/The Open Group Base Specifications Issue 7
+ (POSIX.1-2008) documents only the operands for <STRONG>clear</STRONG>, <STRONG>init</STRONG> and <STRONG>reset</STRONG>.
There are a few interesting observations to make regarding that:
<STRONG>o</STRONG> In this implementation, <STRONG>clear</STRONG> is part of the <EM>cap-code</EM> support. The
- others (<STRONG>init</STRONG> and <STRONG>longname</STRONG>) do not correspond to terminal
+ others (<STRONG>init</STRONG> and <STRONG>longname</STRONG>) do not correspond to terminal
capabilities.
<STRONG>o</STRONG> Other implementations of <STRONG>tput</STRONG> on SVr4-based systems such as
- Solaris, IRIX64 and HP-UX as well as others such as AIX and Tru64
+ Solaris, IRIX64 and HP-UX as well as others such as AIX and Tru64
provide support for <EM>cap-code</EM> operands.
<STRONG>o</STRONG> A few platforms such as FreeBSD recognize termcap names rather than
terminfo capability names in their respective <STRONG>tput</STRONG> commands. Since
- 2010, NetBSD's <STRONG>tput</STRONG> uses terminfo names. Before that, it (like
+ 2010, NetBSD's <STRONG>tput</STRONG> uses terminfo names. Before that, it (like
FreeBSD) recognized termcap names.
- Beginning in 2021, FreeBSD uses the <EM>ncurses</EM> <STRONG>tput</STRONG>, configured for
+ Beginning in 2021, FreeBSD uses the <EM>ncurses</EM> <STRONG>tput</STRONG>, configured for
both terminfo (tested first) and termcap (as a fallback).
Because (apparently) <EM>all</EM> of the certified Unix systems support the full
- set of capability names, the reasoning for documenting only a few may
+ set of capability names, the reasoning for documenting only a few may
not be apparent.
<STRONG>o</STRONG> X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>cap-code</EM> and
the other features used in this implementation.
- <STRONG>o</STRONG> That is, there are two standards for <STRONG>tput</STRONG>: POSIX (a subset) and
- X/Open Curses (the full implementation). POSIX documents a subset
- to avoid the complication of including X/Open Curses and the
+ <STRONG>o</STRONG> That is, there are two standards for <STRONG>tput</STRONG>: POSIX (a subset) and
+ X/Open Curses (the full implementation). POSIX documents a subset
+ to avoid the complication of including X/Open Curses and the
terminal capabilities database.
- <STRONG>o</STRONG> While it is certainly possible to write a <STRONG>tput</STRONG> program without
- using <EM>curses,</EM> no system with a <EM>curses</EM> implementation provides a
+ <STRONG>o</STRONG> While it is certainly possible to write a <STRONG>tput</STRONG> program without
+ using <EM>curses,</EM> no system with a <EM>curses</EM> implementation provides a
<STRONG>tput</STRONG> utility that does not also supply the <EM>cap-code</EM> feature.
X/Open Curses Issue 7 (2009) is the first version to document
utilities. However that part of X/Open Curses does not follow existing
practice (that is, System V <EM>curses</EM> behavior).
- <STRONG>o</STRONG> It assigns exit status 4 to "invalid operand", which may be the
- same as <EM>unknown</EM> <EM>capability</EM>. For instance, the source code for
+ <STRONG>o</STRONG> It assigns exit status 4 to "invalid operand", which may be the
+ same as <EM>unknown</EM> <EM>capability</EM>. For instance, the source code for
Solaris' xcurses uses the term "invalid" in this case.
- <STRONG>o</STRONG> It assigns exit status 255 to a numeric variable that is not
+ <STRONG>o</STRONG> It assigns exit status 255 to a numeric variable that is not
specified in the terminfo database. That likely is a documentation
- error, confusing the <STRONG>-1</STRONG> written to the standard output for an
+ error, confusing the <STRONG>-1</STRONG> written to the standard output for an
absent or cancelled numeric value versus an (unsigned) exit status.
- The various Unix systems (AIX, HP-UX, Solaris) use the same exit
+ The various Unix systems (AIX, HP-UX, Solaris) use the same exit
statuses as <EM>ncurses</EM>.
NetBSD curses documents different exit statuses which do not correspond
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
- The <STRONG>tput</STRONG> command was begun by Bill Joy in 1980. The initial version
+ The <STRONG>tput</STRONG> command was begun by Bill Joy in 1980. The initial version
only cleared the screen.
AT&T System V provided a different <STRONG>tput</STRONG> command:
- <STRONG>o</STRONG> SVr2 provided a rudimentary <STRONG>tput</STRONG> which checked the parameter
- against each predefined capability and returned the corresponding
- value. This version of <STRONG>tput</STRONG> did not use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> for the
+ <STRONG>o</STRONG> SVr2 provided a rudimentary <STRONG>tput</STRONG> which checked the parameter
+ against each predefined capability and returned the corresponding
+ value. This version of <STRONG>tput</STRONG> did not use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> for the
capabilities which are parameterized.
<STRONG>o</STRONG> SVr3 replaced that, a year later, by a more extensive program whose
- <STRONG>init</STRONG> and <STRONG>reset</STRONG> subcommands (more than half the program) were
- incorporated from the <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> written by Eric
+ <STRONG>init</STRONG> and <STRONG>reset</STRONG> subcommands (more than half the program) were
+ incorporated from the <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> written by Eric
Allman.
<STRONG>o</STRONG> SVr4 added color initialization using the <STRONG>orig_colors</STRONG> and <STRONG>orig_pair</STRONG>
capabilities in the <STRONG>init</STRONG> subcommand.
- Keith Bostic replaced the BSD <STRONG>tput</STRONG> command in 1989 with a new
- implementation based on the AT&T System V program <STRONG>tput</STRONG>. Like the AT&T
- program, Bostic's version accepted some parameters named for <EM>terminfo</EM>
- capabilities (<STRONG>clear</STRONG>, <STRONG>init</STRONG>, <STRONG>longname</STRONG> and <STRONG>reset</STRONG>). However (because he
- had only <EM>termcap</EM> available), it accepted <EM>termcap</EM> names for other
- capabilities. Also, Bostic's BSD <STRONG>tput</STRONG> did not modify the terminal I/O
+ Keith Bostic replaced the BSD <STRONG>tput</STRONG> command in 1989 with a new
+ implementation based on the AT&T System V program <STRONG>tput</STRONG>. Like the AT&T
+ program, Bostic's version accepted some parameters named for <EM>terminfo</EM>
+ capabilities (<STRONG>clear</STRONG>, <STRONG>init</STRONG>, <STRONG>longname</STRONG> and <STRONG>reset</STRONG>). However (because he
+ had only <EM>termcap</EM> available), it accepted <EM>termcap</EM> names for other
+ capabilities. Also, Bostic's BSD <STRONG>tput</STRONG> did not modify the terminal I/O
modes as the earlier BSD <STRONG>tset</STRONG> had done.
At the same time, Bostic added a shell script named "clear", which used
<STRONG>tput</STRONG> to clear the screen.
- Both of these appeared in 4.4BSD, becoming the "modern" BSD
+ Both of these appeared in 4.4BSD, becoming the "modern" BSD
implementation of <STRONG>tput</STRONG>.
- This implementation of <STRONG>tput</STRONG> began from a different source than AT&T or
- BSD: Ross Ridge's <EM>mytinfo</EM> package, published on <EM>comp.sources.unix</EM> in
- December 1992. Ridge's program made more sophisticated use of the
- terminal capabilities than the BSD program. Eric Raymond used that
- <STRONG>tput</STRONG> program (and other parts of <EM>mytinfo</EM>) in <EM>ncurses</EM> in June 1995.
- Using the portions dealing with terminal capabilities almost without
- change, Raymond made improvements to the way the command-line
+ This implementation of <STRONG>tput</STRONG> began from a different source than AT&T or
+ BSD: Ross Ridge's <EM>mytinfo</EM> package, published on <EM>comp.sources.unix</EM> in
+ December 1992. Ridge's program made more sophisticated use of the
+ terminal capabilities than the BSD program. Eric Raymond used that
+ <STRONG>tput</STRONG> program (and other parts of <EM>mytinfo</EM>) in <EM>ncurses</EM> in June 1995.
+ Using the portions dealing with terminal capabilities almost without
+ change, Raymond made improvements to the way the command-line
parameters were handled.
</PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
<STRONG>tput</STRONG> <STRONG>init</STRONG>
- Initialize the terminal according to the type of terminal in the
- environment variable <EM>TERM</EM>. This command should be included in
- everyone's .profile after the environment variable <EM>TERM</EM> has been
+ Initialize the terminal according to the type of terminal in the
+ environment variable <EM>TERM</EM>. This command should be included in
+ everyone's .profile after the environment variable <EM>TERM</EM> has been
exported, as illustrated on the <STRONG>profile(5)</STRONG> manual page.
<STRONG>tput</STRONG> <STRONG>-T5620</STRONG> <STRONG>reset</STRONG>
- Reset an AT&T 5620 terminal, overriding the type of terminal in
+ Reset an AT&T 5620 terminal, overriding the type of terminal in
the environment variable <EM>TERM</EM>.
<STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>0</STRONG> <STRONG>0</STRONG>
Send the sequence to move the cursor to row <STRONG>0</STRONG>, column <STRONG>0</STRONG> (the upper
- left corner of the screen, usually known as the "home" cursor
+ left corner of the screen, usually known as the "home" cursor
position).
<STRONG>tput</STRONG> <STRONG>clear</STRONG>
Print the number of columns for the 450 terminal.
<STRONG>bold=`tput</STRONG> <STRONG>smso`</STRONG> <STRONG>offbold=`tput</STRONG> <STRONG>rmso`</STRONG>
- Set the shell variables <STRONG>bold</STRONG>, to begin stand-out mode sequence,
- and <STRONG>offbold</STRONG>, to end standout mode sequence, for the current
+ Set the shell variables <STRONG>bold</STRONG>, to begin stand-out mode sequence,
+ and <STRONG>offbold</STRONG>, to end standout mode sequence, for the current
terminal. This might be followed by a prompt: <STRONG>echo</STRONG> <STRONG>"${bold}Please</STRONG>
<STRONG>type</STRONG> <STRONG>in</STRONG> <STRONG>your</STRONG> <STRONG>name:</STRONG> <STRONG>${offbold}\c"</STRONG>
Send the sequence to move the cursor to row 23, column 4.
<STRONG>tput</STRONG> <STRONG>cup</STRONG>
- Send the terminfo string for cursor-movement, with no parameters
+ Send the terminfo string for cursor-movement, with no parameters
substituted.
<STRONG>tput</STRONG> <STRONG>longname</STRONG>
- Print the long name from the <EM>terminfo</EM> database for the type of
+ Print the long name from the <EM>terminfo</EM> database for the type of
terminal specified in the environment variable <EM>TERM</EM>.
<STRONG>tput</STRONG> <STRONG>-S</STRONG>
clears the screen, moves the cursor to position (10, 10) and turns
on bold (extra bright) mode.
- The same sequence of commands can be combined using the OpenBSD
- feature:
-
- $ <STRONG>tput</STRONG> <STRONG>clear</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG> <STRONG>bold</STRONG>
+ <STRONG>tput</STRONG> <STRONG>clear</STRONG> <STRONG>cup</STRONG> <STRONG>10</STRONG> <STRONG>10</STRONG> <STRONG>bold</STRONG>
+ Perform the same actions as the foregoing "<STRONG>tput</STRONG> <STRONG>-S</STRONG>" example.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: user_caps.5,v 1.43 2023/12/23 16:08:25 tom Exp @
+ * @Id: user_caps.5,v 1.44 2023/12/30 21:36:32 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<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>user_caps 5 2023-12-23 ncurses 6.4 File formats</TITLE>
+<TITLE>user_caps 5 2023-12-30 ncurses 6.4 File formats</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">user_caps 5 2023-12-23 ncurses 6.4 File formats</H1>
+<H1 class="no-header">user_caps 5 2023-12-30 ncurses 6.4 File formats</H1>
<PRE>
<STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> File formats <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>
Single Unix Specification beginning in 1995.
Most of the <EM>extensions</EM> in this fixed repertoire were additions to the
- tables of boolean, numeric and string capabilities. Rather than change
+ tables of Boolean, numeric and string capabilities. Rather than change
the meaning of an existing capability, a new name was added. The
terminfo database uses a binary format; binary compatibility was
ensured by using a header which gave the number of items in the tables
terminfo database may have other extensions, <EM>ncurses</EM> makes explicit
checks for these:
- AX <EM>boolean</EM>, asserts that the terminal interprets SGR 39 and SGR 49
+ AX <EM>Boolean</EM>, asserts that the terminal interprets SGR 39 and SGR 49
by resetting the foreground and background color, respectively,
to the default.
The command "<STRONG>tput</STRONG> <STRONG>clear</STRONG>" does the same thing.
- NQ <EM>boolean</EM>, used to suppress a consistency check in tic for the
+ NQ <EM>Boolean</EM>, used to suppress a consistency check in tic for the
<EM>ncurses</EM> capabilities in user6 through user9 (u6, u7, u8 and u9)
which tell how to query the terminal's cursor position and its
device attributes.
RGB
- <EM>boolean</EM>, <EM>number</EM> <STRONG>or</STRONG> <EM>string</EM>, used to assert that the
+ <EM>Boolean</EM>, <EM>number</EM> <STRONG>or</STRONG> <EM>string</EM>, used to assert that the
<STRONG>set_a_foreground</STRONG> and <STRONG>set_a_background</STRONG> capabilities correspond to
<EM>direct</EM> <EM>colors</EM>, using an RGB (red/green/blue) convention. This
capability allows the <STRONG>color_content</STRONG> function to return
The capability type determines the values which <EM>ncurses</EM> sees:
- <EM>boolean</EM>
+ <EM>Boolean</EM>
implies that the number of bits for red, green and blue are
the same. Using the maximum number of colors, <EM>ncurses</EM> adds
two, divides that sum by three, and assigns the result to red,
<EM>number</EM>
tells <EM>ncurses</EM> what result to add to red, green and blue. If
<EM>ncurses</EM> runs out of bits, blue (and green) lose just as in the
- <EM>boolean</EM> case.
+ <EM>Boolean</EM> case.
<EM>string</EM>
explicitly list the number of bits used for red, green and
-ncurses 6.4 2023-12-
23 <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>
+ncurses 6.4 2023-12-
30 <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>
</PRE>
<div class="nav">
<ul>
# Author: Zeyd M. Ben-Halim <zmbenhal@netcom.com> 1992,1995
# and: Eric S. Raymond <esr@snark.thyrsus.com>
#
-# $Id: Caps,v 1.49 2023/10/14 20:54:32 tom Exp $
+# $Id: Caps,v 1.50 2023/12/30 21:36:32 Branden.Robinson Exp $
#
# This is the master termcap/terminfo capability table.
#
#
# Column 1: terminfo variable name
# Column 2: terminfo capability name
-# Column 3: capability type (boolean, numeric, or string)
+# Column 3: capability type (Boolean, numeric, or string)
# Column 4: termcap capability name
# Column 5: KEY_xxx name, if any, `-' otherwise
# Column 6: value for KEY_xxx name, if any, `-' otherwise
#%indicates the \fIi\fP\uth\d parameter.
#%
#%.PP
-#% These are the boolean capabilities:
+#% These are the Boolean capabilities:
#%
#%.na
#%.TS H
#
# Author: Thomas Dickey
#
-# $Id: Caps.aix4,v 1.21 2023/10/14 21:47:17 tom Exp $
+# $Id: Caps.aix4,v 1.22 2023/12/30 21:36:32 Branden.Robinson Exp $
#
# This is an adaptation of ncurses' termcap/terminfo capability table, which
# is designed to align with AIX 4.x's terminfo.
#
# Column 1: terminfo variable name
# Column 2: terminfo capability name
-# Column 3: capability type (boolean, numeric, or string)
+# Column 3: capability type (Boolean, numeric, or string)
# Column 4: termcap capability name
# Column 5: KEY_xxx name, if any, `-' otherwise
# Column 6: value for KEY_xxx name, if any, `-' otherwise
#%indicates the \fIi\fP\uth\d parameter.
#%
#%.PP
-#% These are the boolean capabilities:
+#% These are the Boolean capabilities:
#%
#%.na
#%.TS H
#
# Author: Thomas Dickey
#
-# $Id: Caps.hpux11,v 1.19 2023/10/14 21:50:28 tom Exp $
+# $Id: Caps.hpux11,v 1.20 2023/12/30 21:36:32 Branden.Robinson Exp $
#
# This is an adaptation of ncurses' termcap/terminfo capability table, which
# is designed to align with HPUX 11.x's terminfo.
#
# Column 1: terminfo variable name
# Column 2: terminfo capability name
-# Column 3: capability type (boolean, numeric, or string)
+# Column 3: capability type (Boolean, numeric, or string)
# Column 4: termcap capability name
# Column 5: KEY_xxx name, if any, `-' otherwise
# Column 6: value for KEY_xxx name, if any, `-' otherwise
#%indicates the \fIi\fP\uth\d parameter.
#%
#%.PP
-#% These are the boolean capabilities:
+#% These are the Boolean capabilities:
#%
#%.na
#%.TS H
tilde_glitch hz bool hz - - YB-GE cannot print ~'s (Hazeltine)
transparent_underline ul bool ul - - YBCGE underline character overstrikes
xon_xoff xon bool xo - - YB--- terminal uses xon/xoff handshaking
-# end booleans for HPUX 9, 10 (non-color curses)
+# end Booleans for HPUX 9, 10 (non-color curses)
needs_xon_xoff nxon bool nx - - ----- padding will not work, xon/xoff required
prtr_silent mc5i bool 5i - - ----- printer will not echo on screen
hard_cursor chts bool HC - - ----- cursor is hard to see
# Author: Thomas Dickey
# and: Ilya Zakharevich
#
-# $Id: Caps.keys,v 1.18 2023/10/14 21:48:29 tom Exp $
+# $Id: Caps.keys,v 1.19 2023/12/30 21:36:32 Branden.Robinson Exp $
#
# This is an adaptation of ncurses' termcap/terminfo capability table, which
# is illustrates an experimental extension to describe alt-, shift- and
#
# Column 1: terminfo variable name
# Column 2: terminfo capability name
-# Column 3: capability type (boolean, numeric, or string)
+# Column 3: capability type (Boolean, numeric, or string)
# Column 4: termcap capability name
# Column 5: KEY_xxx name, if any, `-' otherwise
# Column 6: value for KEY_xxx name, if any, `-' otherwise
#%indicates the \fIi\fP\uth\d parameter.
#%
#%.PP
-#% These are the boolean capabilities:
+#% These are the Boolean capabilities:
#%
#%.na
#%.TS H
#
# Author: Thomas Dickey
#
-# $Id: Caps.osf1r5,v 1.17 2023/10/14 21:48:39 tom Exp $
+# $Id: Caps.osf1r5,v 1.18 2023/12/30 21:36:32 Branden.Robinson Exp $
#
# This is an adaptation of ncurses' termcap/terminfo capability table, which
# is designed to align with OSF/1 version 5 (Tru64) terminfo.
#
# Column 1: terminfo variable name
# Column 2: terminfo capability name
-# Column 3: capability type (boolean, numeric, or string)
+# Column 3: capability type (Boolean, numeric, or string)
# Column 4: termcap capability name
# Column 5: KEY_xxx name, if any, `-' otherwise
# Column 6: value for KEY_xxx name, if any, `-' otherwise
#%indicates the \fIi\fP\uth\d parameter.
#%
#%.PP
-#% These are the boolean capabilities:
+#% These are the Boolean capabilities:
#%
#%.na
#%.TS H
#
# Author: Thomas Dickey
#
-# $Id: Caps.uwin,v 1.16 2023/10/14 21:48:58 tom Exp $
+# $Id: Caps.uwin,v 1.17 2023/12/30 21:36:32 Branden.Robinson Exp $
#
# This is an adaptation of ncurses' termcap/terminfo capability table, which
# is designed to align with U/Win's terminfo.
#
# Column 1: terminfo variable name
# Column 2: terminfo capability name
-# Column 3: capability type (boolean, numeric, or string)
+# Column 3: capability type (Boolean, numeric, or string)
# Column 4: termcap capability name
# Column 5: KEY_xxx name, if any, `-' otherwise
# Column 6: value for KEY_xxx name, if any, `-' otherwise
#%indicates the \fIi\fP\uth\d parameter.
#%
#%.PP
-#% These are the boolean capabilities:
+#% These are the Boolean capabilities:
#%
#%.na
#%.TS H
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_color.3x,v 1.95 2023/12/23 20:18:13 tom Exp $
-.TH curs_color 3X 2023-12-23 "ncurses 6.4" "Library calls"
+.\" $Id: curs_color.3x,v 1.96 2023/12/30 21:20:01 tom Exp $
+.TH curs_color 3X 2023-12-30 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
window attributes,
as from \fB\%wattrset\fP(3X) or \fB\%wattr_set\fP(3X)
.bP
-window background character atttributes,
+window background character attributes,
as from \fB\%wbkgdset\fP(3X) or \fB\%wbkgrndset\fP(3X)
.PP
Per-character and window attributes are usually set through a function
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inwstr.3x,v 1.35 2023/11/25 11:31:49 tom Exp $
-.TH curs_inwstr 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_inwstr.3x,v 1.36 2023/12/30 21:32:48 tom Exp $
+.TH curs_inwstr 3X 2023-12-30 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBwinnwstr\fP
may be macros.
.PP
-Each cell in the window holds a complex character (i.e., base-
-and combining-characters) together with attributes and color.
+Each cell in the window holds a complex character
+(a spacing character and zero or more non-spacing characters)
+together with attributes and color.
These functions store only the wide characters,
ignoring attributes and color.
Use \fBin_wchstr\fP to return the complex characters from a window.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scr_dump.3x,v 1.36 2023/12/16 21:10:18 tom Exp $
-.TH curs_scr_dump 3X 2023-12-16 "ncurses 6.4" "Library calls"
+.\" $Id: curs_scr_dump.3x,v 1.37 2023/12/30 21:34:11 tom Exp $
+.TH curs_scr_dump 3X 2023-12-30 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint scr_set(const char *\fIfilename\fP);
.fi
.SH DESCRIPTION
+.I curses
+provides applications the ability to write the contents of the screen
+to a file and read them back.
+To read/write a window
+(rather than the whole screen)
+from/to a file,
+use \fB\%getwin\fP(3X) and
+\fB\%putwin\fP(3X),
+respectively.
.SS scr_dump
-The \fBscr_dump\fP routine dumps the current contents
-of the \fIvirtual screen\fP
-to the file \fIfilename\fP.
+\fB\%scr_dump\fP writes to
+.I filename
+the contents of the virtual screen;
+see \fB\%curscr\fP(3X).
.SS scr_restore
-The \fBscr_restore\fP routine sets the \fIvirtual screen\fP to the contents
-of \fIfilename\fP, which must have been written using \fBscr_dump\fP.
-The next call to \fBdoupdate\fP restores
-the \fIphysical screen\fP to the way it looked in the dump file.
+\fB\%scr_restore\fP updates the virtual screen to contain the contents
+of
+.I filename
+(if it was validly written with \fB\%scr_dump\fP).
+No refresh is performed;
+after performing any further desired updates,
+call \fB\%doupdate\fP(3X) or similar.
.SS scr_init
-The \fBscr_init\fP routine reads in the contents of \fIfilename\fP and uses
-them to initialize the \fBcurses\fP data structures about what the terminal
-currently has on its screen.
-If the data is determined to be valid,
-\fBcurses\fP bases its next update of the screen on this information rather
-than clearing the screen and starting from scratch.
-\fBscr_init\fP is used
-after \fBinitscr\fP(3X) or a \fBsystem\fP(3) call to share
-the screen with another process which has done a \fBscr_dump\fP after its
-\fBendwin\fP(3X) call.
-The data is declared invalid
+\fB\%scr_init\fP reads
+.I filename,
+using it to initialize
+.I curses
+data structures describing the state of the terminal screen.
+If these data are valid,
+.I curses
+bases its next update of the screen on this information rather than
+clearing it and starting from scratch.
+.PP
+The data fail the validity check
.bP
-if the terminfo capabilities \fBrmcup\fP and \fBnrrmc\fP exist, also
+if the terminal employs
+.I \%term\%info
+capabilities
+.B \%exit_ca_mode
+.RB ( \%rmcup )
+or
+.B \%non_rev_rmcup
+.RB ( \%nrrmc )
+are defined,
+or
.bP
-if the terminal has been written to since the preceding \fBscr_dump\fP call.
+if
+.I curses
+knows that the terminal has been written to since the preceding
+\fB\%scr_dump\fP call.
+.PP
+\fB\%scr_init\fP could be used after \fB\%initscr\fP(3X) or
+\fB\%system\fP(3) to share the screen with another process that has
+done a \fBscr_dump\fP after \fB\%endwin\fP(3X).
.SS scr_set
The \fBscr_set\fP routine is a combination of \fBscr_restore\fP and
\fBscr_init\fP. It tells the program that the information in \fIfilename\fP is
what is currently on the screen, and also what the program wants on the screen.
This can be thought of as a screen inheritance function.
-.PP
-To read (write) a window from (to) a file, use the \fBgetwin\fP and
-\fBputwin\fP routines [see \fBcurs_util\fP(3X)].
.SH RETURN VALUE
-These routines return the integer \fBERR\fP upon failure and \fBOK\fP
-upon success.
+These functions return \fBOK\fP on success and \fBERR\fP on failure.
.PP
-X/Open defines no error conditions.
+X/Open defines no failure conditions.
In this implementation,
-each will return an error if the file cannot be opened.
+each function fails if it cannot open
+.I filename.
.SH NOTES
-Note that \fBscr_init\fP, \fBscr_set\fP, and \fBscr_restore\fP may be macros.
+\fB\%scr_init\fP,
+\fB\%scr_set\fP,
+and
+\fB\%scr_restore\fP may be macros.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4,
-which adds \fI\%const\fP qualifiers to the arguments.
+X/Open Curses, Issue 4, describes these functions.
+.PP
+.\" SVID 4, p. 529
+SVr4 omitted the
+.I \%const
+qualifiers.
.PP
-The SVr4 docs merely say under \fBscr_init\fP that the dump data is also
-considered invalid \*(``if the time-stamp of the tty is old\*('' but do
-not define \*(``old\*(''.
+SVr4 documentation describes \fB\%scr_init\fP such that the dump data is
+also considered invalid \*(``if the time-stamp of the tty is old\*(''
+but does not define \*(``old\*(''.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_initscr\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termcap.3x,v 1.80 2023/12/23 20:19:05 tom Exp $
-.TH curs_termcap 3X 2023-12-23 "ncurses 6.4" "Library calls"
+.\" $Id: curs_termcap.3x,v 1.81 2023/12/30 21:27:22 tom Exp $
+.TH curs_termcap 3X 2023-12-30 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
leaving the API unchanged.
.PP
Function prototypes were a feature of ANSI C (1989).
-Thus the library itself provided no header file declaring them.
+The library long antedated the standard and thus provided no header file
+declaring them.
Nevertheless,
the BSD sources included two different \fI\%termcap.h\fP header files
over time.
.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD/usr/contrib/\
.\" jove/Makefile
.\" --much too late for 2BSD (1979).
-It delcared global symbols for the \fItermcap\fP variables that it used.
+It declared global symbols for the \fItermcap\fP variables that it used.
.bP
The other appeared in 4.4BSD-Lite Release 2
(June 1995)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_terminfo.3x,v 1.124 2023/12/23 17:34:39 tom Exp $
-.TH curs_terminfo 3X 2023-12-23 "ncurses 6.4" "Library calls"
+.\" $Id: curs_terminfo.3x,v 1.125 2023/12/30 23:46:56 tom Exp $
+.TH curs_terminfo 3X 2023-12-30 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB\%vid_puts\fP,
\fB\%vidattr\fP,
\fB\%vidputs\fP \-
-\fIcurses\fR interfaces to \fIterminfo\fR database
+\fIcurses\fR interfaces to \fI\%term\%info\fR database
.SH SYNOPSIS
.nf
\fB#include <curses.h>
.fi
.SH DESCRIPTION
These low-level routines must be called by programs that have to deal
-directly with the \fIterminfo\fP database to handle certain terminal
-capabilities, such as programming function keys.
-For all other
-functionality, \fIcurses\fP routines are more suitable and their use is
-recommended.
+directly with the
+.I \%term\%info
+database to handle certain terminal capabilities,
+such as programming function keys.
+For all other functionality,
+.I curses
+routines are more suitable and their use is recommended.
.PP
-None of these functions use (or are aware of) multibyte character strings
-such as UTF-8:
+None of these functions use
+(or are aware of)
+multibyte character strings such as UTF-8.
.bP
-capability names use the POSIX portable character set
+Capability names and codes use the POSIX portable character set.
.bP
-capability string values have no associated encoding;
+Capability string values have no associated encoding;
they are strings of 8-bit characters.
.SS Initialization
-Initially, \fBsetupterm\fP should be called.
-The high-level curses functions \fBinitscr\fP and
-\fBnewterm\fP call \fBsetupterm\fP to initialize the
-low-level set of terminal-dependent variables
-[listed in \fBterminfo\fP(5)].
+Initially,
+\fB\%setupterm\fP should be called.
+The high-level
+.I curses
+functions \fB\%initscr\fP and \fB\%newterm\fP call \fB\%setupterm\fP to
+initialize the low-level set of terminal-dependent variables
+listed in \fB\%term_variables\fP(3X).
.PP
Applications can use the
-terminal capabilities either directly (via header definitions),
+terminal capabilities either directly
+(via header definitions),
or by special functions.
-The header files \fBcurses.h\fP and \fBterm.h\fP should be included (in this
-order) to get the definitions for these strings, numbers, and flags.
-.PP
-The \fBterminfo\fP variables
-\fBlines\fP and \fBcolumns\fP are initialized by \fBsetupterm\fP as
+The header files
+.I \%curses.h
+and
+.I \%term.h
+should be included
+(in that order)
+to get the definitions for these strings, numbers, and flags.
+.PP
+The
+.I \%term\%info
+variables
+\fBlines\fP and \fBcolumns\fP are initialized by \fB\%setupterm\fP as
follows:
.bP
-If \fBuse_env(FALSE)\fP has been called, values for
-\fBlines\fP and \fBcolumns\fP specified in \fBterminfo\fP are used.
+If \fB\%use_env(FALSE)\fP has been called,
+values for \fBlines\fP and \fBcolumns\fP specified in
+.I \%term\%info
+are used.
.bP
Otherwise,
if the environment variables \fILINES\fP and \fI\%COLUMNS\fP exist,
is used.
Otherwise, if the environment variables do not exist, the
values for \fBlines\fP and \fBcolumns\fP specified in the
-\fBterminfo\fP database are used.
+.I \%term\%info
+database are used.
.PP
Parameterized strings should be passed through \fBtparm\fP to instantiate them.
-All \fBterminfo\fP strings
+All
+.I \%term\%info
+strings
(including the output of \fBtparm\fP)
should be printed
with \fBtputs\fP or \fBputp\fP.
output \fBenter_ca_mode\fP and
call \fBreset_prog_mode\fP after returning from the shell.
.PP
-The \fBsetupterm\fP routine reads in the \fBterminfo\fP database,
-initializing the \fBterminfo\fP structures, but does not set up the
-output virtualization structures used by \fBcurses\fP.
+The \fB\%setupterm\fP routine reads in the
+.I \%term\%info
+database,
+initializing the
+.I \%term\%info
+structures,
+but does not set up the output virtualization structures used by
+.I curses.
These are its parameters:
.RS 3
.TP 5
checking the \fBgn\fP \%(\fBgeneric_type\fP) capability.
.TP 5
.B \-1
-means that the \fIterminfo\fP database could not be found.
+means that the
+.I \%term\%info
+database could not be found.
.RE
.IP
If \fIerrret\fP is
null, \fB\%setupterm\fP prints an error message upon finding an error
and exits.
Thus, the simplest call is:
+.RS
+.IP
+\fBsetupterm((char *)0, 1, (int *)0);\fP
+.RE
.IP
-\fBsetupterm((char *)0, 1, (int *)0);\fP,
-.PP
which uses all the defaults and sends the output to \fBstdout\fP.
.RE
.\" ***************************************************************************
If it is called for different terminal types,
\fBsetupterm\fP allocates new storage for each set of terminal capabilities.
.PP
-The \fBset_curterm\fP routine sets \fBcur_term\fP to
-\fInterm\fP, and makes all of the \fBterminfo\fP boolean, numeric, and
-string variables use the values from \fInterm\fP.
-It returns the old value of \fBcur_term\fP.
-.PP
-The \fBdel_curterm\fP routine frees the space pointed to by
-\fIoterm\fP and makes it available for further use.
-If \fIoterm\fP is
-the same as \fBcur_term\fP, references to any of the \fBterminfo\fP
-boolean, numeric, and string variables thereafter may refer to invalid
-memory locations until another \fBsetupterm\fP has been called.
+\fB\%set_curterm\fP sets \fB\%cur_term\fP to
+.I \%nterm,
+and makes all of the
+.I \%term\%info
+Boolean,
+numeric,
+and string variables use the values from
+.I \%nterm.
+It returns the old value of \fB\%cur_term\fP.
+.PP
+\fB\%del_curterm\fP routine frees the space pointed to by
+.I \%oterm
+and makes it available for further use.
+If
+.I \%oterm
+is
+the same as \fB\%cur_term\fP,
+references to any of the
+.I \%term\%info
+Boolean,
+numeric,
+and string variables thereafter may refer to invalid memory locations
+until another \fB\%setupterm\fP has been called.
.PP
The \fBrestartterm\fP routine is similar to \fBsetupterm\fP and \fBinitscr\fP,
except that it is called after restoring memory to a previous state (for
The capability string is null-terminated.
Use \*(``\e200\*('' where an ASCII NUL is needed in the output.
.PP
-\fBtiparm\fP is a newer form of \fBtparm\fP which uses \fI<stdarg.h>\fP
+\fB\%tiparm\fP is a newer form of \fB\%tparm\fP which uses
+.I \%stdarg.h
rather than a fixed-parameter list.
-Its numeric parameters are integers (int) rather than longs.
+Its numeric parameters are
+.IR int s
+rather than
+.IR long s.
.PP
Both \fBtparm\fP and \fBtiparm\fP assume that the application passes
parameters consistent with the terminal description.
.IP
The \fBtgetstr\fP and \fBtgoto\fP functions are part of the \fItermcap\fP
interface,
-which happens to share this function name with the \fIterminfo\fP interface.
+which happens to share this function name with the
+.I \%term\%info
+interface.
.bP
\fIaffcnt\fP is the number of lines affected, or 1 if
not applicable.
The \fBvidattr\fP routine is like the \fBvidputs\fP routine, except
that it outputs through \fI\%putchar\fP.
.PP
-The \fBvid_attr\fP and \fBvid_puts\fP routines correspond
-to vidattr and vidputs, respectively.
-They use a set of arguments for representing the video attributes plus color,
-i.e.,
-.bP
-\fIattrs\fP of type \fBattr_t\fP for the attributes and
-.bP
-\fIpair\fP of type \fBshort\fP for the color pair number.
-.PP
-The \fBvid_attr\fP and \fBvid_puts\fP routines
-are designed to use the attribute constants with the \fBWA_\fP prefix.
-.PP
-X/Open Curses reserves the \fIopts\fP argument for future use,
-saying that applications must provide a null pointer for that argument.
-As an extension,
-this implementation allows \fIopts\fP to be used as a pointer to \fBint\fP,
-which overrides the \fIpair\fP (\fBshort\fP) argument.
+.B \%vid_attr
+and
+.B \%vid_puts
+correspond to
+.B \%vidattr
+and
+.BR \%vidputs ,
+respectively.
+They use multiple parameters to represent the character attributes and
+color;
+namely,
+.bP
+.I \%attrs,
+of type
+.I \%attr_t,
+for the attributes and
+.bP
+.I pair,
+of type
+.I short,
+for the color pair number.
+.PP
+Use the attribute constants prefixed with
+.RB \*(`` WA_ \*(''
+with
+.B \%vid_attr
+and
+.BR \%vid_puts .
+.PP
+X/Open Curses reserves the
+.I opts
+argument for future use,
+saying that applications must provide a null pointer for that argument;
+but see section \*(``EXTENSIONS\*('' below.
.PP
The \fBmvcur\fP routine provides low-level cursor motion.
It takes effect immediately (rather than at the next refresh).
.PP
While \fBputp\fP and \fBmvcur\fP are low-level functions which
do not use the high-level curses state,
-they are declared in \fB\%<curses.h>\fP because System\ V did this
+they are declared in
+.I \%curses.h
+because System\ V did this
(see \fIHISTORY\fP).
.\" ***************************************************************************
.SS "Terminal Capability Functions"
The \fBtigetflag\fP, \fBtigetnum\fP and \fBtigetstr\fP routines return
-the value of the capability corresponding to the \fBterminfo\fP
+the value of the capability corresponding to the
+.I \%term\%info
\fIcapname\fP passed to them, such as \fBxenl\fP.
The \fIcapname\fP for each capability is given in the table column entitled
-\fIcapname\fP code in the capabilities section of \fBterminfo\fP(5).
+\fIcapname\fP code in the capabilities section of \fB\%terminfo\fP(5).
.PP
These routines return special values to denote errors.
.PP
The \fBtigetflag\fP routine returns
.TP
\fB\-1\fP
-if \fIcapname\fP is not a boolean capability,
+if \fIcapname\fP is not a Boolean capability,
or
.TP
\fB0\fP
.SS "Terminal Capability Names"
These null-terminated arrays contain
.bP
-the short \fIterminfo\fP names (\*(``codes\*(''),
+the short \fI\%term\%info\fP names (\*(``codes\*(''),
.bP
the \fItermcap\fP names (\*(``names\*(''), and
.bP
-the long \fIterminfo\fP names (\*(``fnames\*('')
+the long \fI\%term\%info\fP names (\*(``fnames\*('')
.PP
-for each of the predefined \fIterminfo\fP variables:
+for each of the predefined
+.I \%term\%info
+variables:
.PP
.RS
.nf
the \*(``static\*('' terminfo variables [a-z].
Before \fI\%ncurses\fP 6.3, those were shared by all screens.
With \fI\%ncurses\fP 6.3, those are allocated per screen.
-See \fBterminfo\fP(5) for details.
+See \fB\%terminfo\fP(5) for details.
.bP
to improve performance,
\fI\%ncurses\fP 6.3 caches the result of analyzing terminfo
the \fBdelscreen\fP(3X) function.
.\" ***************************************************************************
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
-(SVr4 only specifies \*(``an integer value other than \fBERR\fP\*('')
-upon successful completion,
-unless otherwise noted in the preceding routine descriptions.
-.PP
-Routines that return pointers always return \fBNULL\fP on error.
-.PP
-X/Open defines no error conditions.
-In this implementation
-.RS 3
+X/Open defines no failure conditions.
+In
+.I \%ncurses,
.TP 5
\fBdel_curterm\fP
returns an error
\fBsetupterm\fP
returns an error
if it cannot allocate enough memory, or
-create the initial windows (stdscr, curscr, newscr).
+create the initial windows
+.RB ( \%stdscr ,
+.BR \%curscr ,
+and
+.BR \%newscr )
Other error conditions are documented above.
.TP 5
\fBtparm\fP
\fBtputs\fP
returns an error if the string parameter is null.
It does not detect I/O errors:
-X/Open states that \fBtputs\fP ignores the return value
+X/Open Curses states that \fBtputs\fP ignores the return value
of the output function \fIputc\fP.
-.RE
.\" ***************************************************************************
.SH NOTES
-.\" See X/Open Curses Issue 4, Version 2, pp. 227-234.
-.\" See X/Open Curses Issue 7, pp. 311-318.
-According to X/Open Curses,
-any of the \fIenhanced curses\fP functions may be implemented as macros.
-The term \*(``enhanced\*('' refers to features not found in SVr4 curses.
-.PP
-\fB\%ncurses\fP uses macros
-.bP
-for functions which return values via their parameters,
-.bP
-to support obsolete features,
-.bP
-to reuse functions,
-e.g., those that move the cursor before another operation, and
-.bP
-a few special cases.
-.PP
-The \fB\%vid_puts\fP function in \fB\%ncurses\fP is a special case.
+The
+.B \%vid_attr
+function in
+.I \%ncurses
+is a special case.
It was originally implemented based on a draft of X/Open Curses,
as a macro,
-before other parts of the \fB\%ncurses\fP wide-character API were developed.
+before other parts of the
+.I \%ncurses
+wide-character API were developed,
+and unlike the other wide-character functions,
+is also provided in the non-wide-character configuration.
.\" ***************************************************************************
.SH EXTENSIONS
The functions marked as extensions were designed for
-\fB\%ncurses\fP(3X),
+.I \%ncurses,
and are not found in SVr4
.IR curses ,
4.4BSD
.IR curses ,
or any other previous curses implementation.
+.PP
+.I \%ncurses
+allows
+.I opts
+to be a pointer to
+.I int,
+which overrides the
+.I pair
+.RI ( short )
+argument.
.\" ***************************************************************************
.SH PORTABILITY
-\fBsetterm\fP is not described by X/Open and must be considered
+\fB\%setterm\fP is not described by X/Open and must be considered
non-portable.
All other functions are as described by X/Open.
.SS "Compatibility Macros"
stating that the call
.RS
.EX
-setupterm(\fIterm\fB, 1, (int *)0)\fP
+setupterm(\fIterm\fP, 1, (int *)0)
.EE
.RE
-provides the same functionality as \fBsetterm(\fIterm\fB)\fR,
+provides the same functionality as \fB\%setterm(\fIterm\fB)\fR,
discouraging the latter for new programs.
.I \%ncurses
implements each of these symbols as macros for BSD
.I curses
compatibility.
.SS "Legacy Data"
-\fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
+\fB\%setupterm\fP copies the terminal name to the array \fB\%ttytype\fP.
This is not part of X/Open Curses, but is assumed by some applications.
.PP
Other implementions may not declare the capability name arrays.
Some provide them without declaring them.
X/Open does not specify them.
.PP
-Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
+Extended terminal capability names,
+as defined by
+.RB \%\*(`` "@TIC@\ \-x" \*('',
are not stored in the arrays described here.
.SS "Output Buffering"
Older versions of \fI\%ncurses\fP assumed that the file descriptor
-passed to \fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses
+passed to \fB\%setupterm\fP from \fB\%initscr\fP or \fB\%newterm\fP 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 \fI\%ncurses\fP
-did not allow a reliable way to cleanup on receiving SIGTSTP.
+In addition to the limitation that the terminal was left in
+block-buffered mode on exit
+(like System\ V
+.IR curses ),
+it was problematic because
+.I \%ncurses
+did not allow a reliable way to cleanup on receiving
+.BR SIGTSTP .
.PP
The current version (ncurses6)
-uses output buffers managed directly by \fI\%ncurses\fP.
+uses output buffers managed directly by
+.I \%ncurses.
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 \fI\%ncurses\fP use
-alternate versions of these functions
-using the more reliable buffering scheme.
+The high-level functions in
+.I \%ncurses
+employ alternate versions of these functions using the more reliable
+buffering scheme.
.SS "Function Prototypes"
-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.
+The X/Open Curses prototypes are based on the SVr4
+.I curses
+header declarations,
+which were defined at the same time the C language was first
+standardized in the late 1980s.
.bP
-X/Open Curses uses \fBconst\fP less effectively than a later design might,
+X/Open Curses uses
+.I \%const
+less effectively than a later design might,
in some cases applying it needlessly to values are already constant,
-and in most cases overlooking parameters which normally would use \fBconst\fP.
-Using constant parameters for functions which do not use \fBconst\fP
+and in most cases overlooking parameters which normally would use
+.I \%const.
+Using constant parameters for functions which do not use
+.I \%const
may prevent the program from compiling.
-On the other hand, \fIwritable strings\fP are an obsolescent feature.
+On the other hand,
+\*(``writable strings\*('' are an obsolescent feature.
.IP
-As an extension, this implementation can be configured to change the
-function prototypes to use the \fBconst\fP keyword.
-The \fI\%ncurses\fP ABI 6 enables this feature by default.
+As an extension,
+this implementation can be configured to change the function prototypes
+to use the
+.I \%const
+keyword.
+The
+.I \%ncurses
+ABI 6 enables this feature by default.
.bP
-X/Open Curses prototypes \fBtparm\fP with a fixed number of parameters,
+X/Open Curses prototypes \fB\%tparm\fP with a fixed number of
+parameters,
rather than a variable argument list.
.IP
This implementation uses a variable argument list, but can be
zeroes are fine for this purpose.
.IP
In response to review comments by Thomas E. Dickey,
-X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009.
+X/Open Curses Issue 7 proposed the \fB\%tiparm\fP function in mid-2009.
.IP
-While \fBtiparm\fP is always provided in \fI\%ncurses\fP,
+While \fB\%tiparm\fP is always provided in \fI\%ncurses\fP,
the older form is only available as a build-time configuration option.
-If not specially configured, \fBtparm\fP is the same as \fBtiparm\fP.
+If not specially configured,
+\fB\%tparm\fP is the same as \fB\%tiparm\fP.
.PP
-Both forms of \fBtparm\fP have drawbacks:
+Both forms of \fB\%tparm\fP have drawbacks:
.bP
-Most of the calls to \fBtparm\fP use only one or two parameters.
+Most of the calls to \fB\%tparm\fP use only one or two parameters.
Passing nine on each call is awkward.
.IP
-Using \fBlong\fP for the numeric parameter type is a workaround
-to make the parameter use the same amount of stack as a pointer.
+Using
+.I long
+for the numeric parameter type is a workaround to make the parameter use
+the same amount of stack as a pointer.
That approach dates back to the mid-1980s, before C was standardized.
Since then, there is a standard
(and pointers are not required to fit in a long).
.bP
Providing the right number of parameters for a variadic function
-such as \fBtiparm\fP can be a problem, in particular for string parameters.
+such as \fB\%tiparm\fP can be a problem,
+in particular for string parameters.
However, only a few terminfo capabilities use string parameters
(e.g., the ones used for programmable function keys).
.IP
The \fI\%ncurses\fP 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 \fBtparm\fP calls.
+places for the \fB\%tparm\fP calls.
.IP
-The \fB@TPUT@\fR(1) program checks its use of these capabilities with a table,
-so that it calls \fBtparm\fP correctly.
+The \fB\%@TPUT@\fR(1) program checks its use of these capabilities with
+a table,
+so that it calls \fB\%tparm\fP correctly.
.SS "Special \fITERM\fP treatment"
If configured to use the terminal-driver,
e.g., for the MinGW port,
.bP
-\fBsetupterm\fP interprets a missing/empty \fITERM\fP variable as the
+\fB\%setupterm\fP interprets a missing/empty \fITERM\fP variable as the
special value \*(``unknown\*(''.
.IP
SVr4 curses uses the
special value \*(``dumb\*(''.
.IP
The difference between the two is that
-the former uses the \fBgn\fP (\fBgeneric_type\fR) terminfo capability,
+the former uses the \fBgn\fP (\fB\%generic_type\fR) terminfo capability,
while the latter does not.
A generic terminal is unsuitable for full-screen applications.
.bP
-\fBsetupterm\fP allows explicit use of the
+\fB\%setupterm\fP allows explicit use of the
the windows console driver by checking if \fB$TERM\fP is set to
\*(``#win32con\*('' or an abbreviation of that string.
.SS "Other Portability Issues"
-In System V Release 4, \fBset_curterm\fP has an \fBint\fP return type and
-returns \fBOK\fP or \fBERR\fP. We have chosen to implement the X/Open Curses
-semantics.
+In SVr4,
+\fB\%set_curterm\fP returns an
+.I int,
+.B OK
+or
+.BR ERR .
+We have chosen to implement the X/Open Curses semantics.
.PP
-In System V Release 4, the third argument of \fBtputs\fP has the type
-\fBint (*putc)(char)\fP.
+In SVr4,
+the third argument of \fB\%tputs\fP has the type
+.RB \*(`` "int (*putc)(char)" \*(''.
.PP
At least one implementation of X/Open Curses (Solaris) returns a value
-other than \fBOK\fP/\fBERR\fP from \fBtputs\fP.
-That returns the length of the string, and does no error-checking.
+other than
+.B OK
+or
+.B ERR
+from \fB\%tputs\fP.
+It instead returns the length of the string,
+and does no error checking.
+.PP
+X/Open Curses notes that after calling \fB\%mvcur\fP,
+the
+.I curses
+state may not match the actual terminal state,
+and that an application should touch and refresh the window before
+resuming normal
+.I curses
+calls.
+Both
+.I \%ncurses
+and SVr4
+.I curses
+implement \fB\%mvcur\fP using the
+.I SCREEN
+data allocated in either \fB\%initscr\fP or \fB\%newterm\fP.
+So though it is documented as a
+.I \%term\%info
+function,
+\fB\%mvcur\fP is really a
+.I curses
+function that is not well specified.
.PP
X/Open notes that after calling \fBmvcur\fP, the curses state may not match the
actual terminal state, and that an application should touch and refresh
So though it is documented as a terminfo function,
\fBmvcur\fP is really a curses function which is not well specified.
.PP
-X/Open states that the old location must be given for \fBmvcur\fP.
-This implementation allows the caller to use \-1's for the old ordinates.
-In that case, the old location is unknown.
+X/Open Curses states that the old location must be given for
+\fB\%mvcur\fP to accommodate terminals that lack absolute cursor
+positioning.
+.\" X/Open Curses Issue 7, p. 161
+.I \%ncurses
+allows the caller to use \-1 for either or both old coordinates.
+The \-1 tells
+.I \%ncurses
+that the old location is unknown,
+and that it must use only absolute motion
+(such as \fI\%cursor_address\fP)
+rather than the least costly combination of absolute and relative motion.
.\" ***************************************************************************
.SH HISTORY
-SVr2 introduced the terminfo feature.
+SVr2 (1984) introduced the
+.I \%term\%info
+feature.
Its programming manual mentioned the following low-level functions.
.PP
.TS
fixterm restore tty to \*(``in curses\*('' state
gettmode establish current tty modes
mvcur low level cursor motion
-putp T{
-utility function that uses \fBtputs\fP to send characters via
-\fI\%putchar\fP.
-T}
+putp use \fBtputs\fP to send characters via \fI\%putchar\fP
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
+tparm interpolate parameters into string capability
tputs apply padding information to a string
-vidattr like \fBvidputs\fP, but outputs through \fIputchar\fP
-vidputs T{
-output a string to put terminal in a specified video attribute mode
-T}
+vidattr like \fBvidputs\fP, but output through \fIputchar\fP
+vidputs write string to terminal, applying specified attributes
.TE
.PP
The programming manual also mentioned
-functions provided for \fItermcap\fP compatibility
+functions provided for
+.I termcap
+compatibility
(commenting that they \*(``may go away at a later date\*('').
.PP
.TS
Function Description
_
tgetent look up \fItermcap\fP entry for given \fIname\fP
-tgetflag get boolean entry for given \fIid\fP
+tgetflag get Boolean entry for given \fIid\fP
tgetnum get numeric entry for given \fIid\fP
tgetstr get string entry for given \fIid\fP
tgoto apply parameters to given capability
-tputs T{
-apply padding to capability, calling a function to put characters
-T}
+tputs write characters via a function parameter, applying padding
.TE
.PP
-Early terminfo programs obtained capability values from the
-\fI\%TERMINAL\fP structure initialized by \fBsetupterm\fP.
+Early
+.I \%term\%info
+programs obtained capability values from the
+.I \%TERMINAL
+structure initialized by \fB\%setupterm\fP.
.PP
-SVr3 extended terminfo by adding functions to retrieve capability values
-(like the termcap interface),
-and reusing \fBtgoto\fP and \fBtputs\fP:
+SVr3 (1987) extended
+.I \%term\%info
+by adding functions to retrieve capability values
+(like the
+.I termcap
+interface),
+and reusing \fB\%tgoto\fP and \fB\%tputs\fP.
.PP
.TS
lB lB
lB lx.
Function Description
_
-tigetflag get boolean entry for given \fIid\fP
+tigetflag get Boolean entry for given \fIid\fP
tigetnum get numeric entry for given \fIid\fP
tigetstr get string entry for given \fIid\fP
.TE
.PP
-SVr3 also replaced several of the SVr2 \fIterminfo\fP functions
-which had no counterpart in the \fItermcap\fP interface,
+SVr3 also replaced several of the SVr2
+.I \%term\%info
+functions that had no counterpart in the
+.I termcap
+interface,
documenting them as obsolete.
.PP
.TS
setterm setupterm
.TE
.PP
-SVr3 kept the \fBmvcur\fP, \fBvidattr\fP and \fBvidputs\fP functions,
-along with \fBputp\fP, \fBtparm\fP and \fBtputs\fP.
+SVr3 kept the \fB\%mvcur\fP,
+\fB\%vidattr\fP,
+and \fB\%vidputs\fP functions,
+along with \fB\%putp\fP,
+\fB\%tparm\fP,
+and \fB\%tputs\fP.
The latter were needed to support padding,
-and handling functions such as \fBvidattr\fP
-(which used more than the two parameters supported by \fBtgoto\fP).
+and to handle capabilities accessed by functions such as \fB\%vidattr\fP
+(which used more than the two parameters supported by \fB\%tgoto\fP).
.PP
SVr3 introduced the functions for switching between terminal
-descriptions, e.g., \fBset_curterm\fP.
-Some of that was incremental improvements to the SVr2 library:
-.bP
-The \fI\%TERMINAL\fP type definition was introduced in SVr3.01,
-for the \fBterm\fP structure provided in SVr2.
-.bP
-The various global variables such as \fBboolnames\fP were mentioned
+descriptions;
+for example,
+\fB\%set_curterm\fP.
+Some changes reflected incremental improvements to the SVr2 library.
+.bP
+The
+.I \%TERMINAL
+type definition was introduced in SVr3.01,
+for the
+.I term
+structure provided in SVr2.
+.bP
+Various global variables such as \fB\%boolnames\fP were mentioned
in the programming manual at this point,
-though the variables were provided in SVr2.
+though the variables had been provided in SVr2.
.PP
-SVr4 added the \fBvid_attr\fP and \fBvid_puts\fP functions.
+SVr4 (1989) added the \fB\%vid_attr\fP and \fB\%vid_puts\fP functions.
.PP
-There are other low-level functions declared in the \fIcurses\fP header files
-on Unix systems,
-but none were documented.
-The functions marked \*(``obsolete\*('' remained in use
-by the Unix \fBvi\fP(1) editor.
+Other low-level functions are declared in the
+.I curses
+header files of Unix systems,
+but none are documented.
+Those noted as \*(``obsolete\*('' by SVr3 remained in use by System\ V's
+\fIvi\fP(1) editor.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_initscr\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: infocmp.1m,v 1.103 2023/12/23 16:08:25 tom Exp $
-.TH @INFOCMP@ 1M 2023-12-23 "ncurses 6.4" "User commands"
+.\" $Id: infocmp.1m,v 1.104 2023/12/30 21:36:32 tom Exp $
+.TH @INFOCMP@ 1M 2023-12-30 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
terminfo entries, rewrite a \fBterminfo\fP description to take advantage of the
\fBuse=\fP terminfo field, or print out a \fBterminfo\fP description from the
binary file (\fBterm\fP) in a variety of formats.
-In all cases, the boolean
+In all cases, the Boolean
fields will be printed first, followed by the numeric fields, followed by the
string fields.
.SS "Default Options"
If a capability is defined for only one of the
terminals, the value returned depends on the type of the capability:
.bP
-\fBF\fP for missing boolean variables
+\fBF\fP for missing Boolean variables
.bP
\fBNULL\fP for missing integer or string variables
.PP
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: man_db.renames.in,v 1.66 2023/12/23 16:14:04 tom Exp $
+# $Id: man_db.renames.in,v 1.67 2023/12/30 21:34:11 tom Exp $
# Manual-page renamings for the man_db program
#
# Files:
derwin.3x derwin.3ncurses
doupdate.3x doupdate.3ncurses
endwin.3x endwin.3ncurses
+extended_slk_color.3x extended_slk_color.3ncurses
filter.3x filter.3ncurses
flushinp.3x flushinp.3ncurses
get_wch.3x get_wch.3ncurses
+getattr.3x getattr.3ncurses
getcchar.3x getcchar.3ncurses
getch.3x getch.3ncurses
+getwin.3x getwin.3ncurses
+has_key.3x has_key.3ncurses
idcok.3x idcok.3ncurses
idlok.3x idlok.3ncurses
immedok.3x immedok.3ncurses
in_wch.3x in_wch.3ncurses
inch.3x inch.3ncurses
initscr.3x initscr.3ncurses
+is_scrollok.3x is_scrollok.3ncurses
+keyname.3x keyname.3ncurses
keypad.3x keypad.3ncurses
leaveok.3x leaveok.3ncurses
longname.3x longname.3ncurses
newwin.3x newwin.3ncurses
nodelay.3x nodelay.3ncurses
notimeout.3x notimeout.3ncurses
+putwin.3x putwin.3ncurses
refresh.3x refresh.3ncurses
reset_shell_mode.3x reset_shell_mode.3ncurses
restartterm.3x restartterm.3ncurses
set_term.3x set_term.3nses
setcchar.3x setcchar.3ncurses
setupterm.3x setupterm.3ncurses
+slk_attr.3x slk_attr.3ncurses
+slk_color.3x slk_color.3ncurses
slk_init.3x slk_init.3ncurses
slk_touch.3x slk_touch.3ncurses
start_color.3x start_color.3ncurses
-# $Id: manhtml.aliases,v 1.30 2023/12/23 21:21:06 tom Exp $
+# $Id: manhtml.aliases,v 1.31 2023/12/31 00:46:44 tom Exp $
#***************************************************************************
# Copyright 2019-2022,2023 Thomas E. Dickey *
# Copyright 2013,2017 Free Software Foundation, Inc. *
add_wch(3X) curs_add_wch(3X)
addch(3X) curs_addch(3X)
assume_default_colors(3X) default_colors(3X)
+attr_get(3X) curs_attr(3X)
attr_on(3X) curs_attr(3X)
attron(3X) curs_attr(3X)
baudrate(3X) curs_termattrs(3X)
delscreen(3X) curs_initscr(3X)
doupdate(3X) curs_refresh(3X)
endwin(3X) curs_initscr(3X)
+extended_slk_color(3X) curs_slk(3X)
filter(3X) curs_util(3X)
flushinp(3X) curs_util(3X)
get_wch(3X) curs_get_wch(3X)
getcchar(3X) curs_getcchar(3X)
getch(3X) curs_getch(3X)
+getwin(3X) curs_util(3X)
+has_key(3X) curs_getch(3X)
immedok(3X) curs_outopts(3X)
in_wch(3X) curs_in_wch(3X)
inch(3X) curs_inch(3X)
mvwin(3X) curs_window(3X)
newterm(3X) curs_initscr(3X)
newwin(3X) curs_window(3X)
+putwin(3X) curs_util(3X)
refresh(3X) curs_refresh(3X)
reset_shell_mode(3X) curs_kernel(3X)
restartterm(3X) curs_terminfo(3X)
set_term(3X) curs_initscr(3X)
setcchar(3X) curs_getcchar(3X)
setupterm(3X) curs_terminfo(3X)
+slk_attr(3X) curs_slk(3X)
+slk_color(3X) curs_slk(3X)
slk_init(3X) curs_slk(3X)
slk_touch(3X) curs_slk(3X)
start_color(3X) curs_color(3X)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: ncurses.3x,v 1.189 2023/12/23 16:32:37 tom Exp $
-.TH ncurses 3X 2023-12-23 "ncurses 6.4" "Library calls"
+.\" $Id: ncurses.3x,v 1.192 2023/12/31 00:46:04 tom Exp $
+.TH ncurses 3X 2023-12-30 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\*(``NOTES\*('' describes matters and caveats of which any user of the
\fI\%ncurses\fP API should be aware,
such as limitations on the size of an underlying integral type or the
-availability of a preprocessor macro for a function
+availability of a preprocessor macro exclusive of a function definition
(which prevents its address from being taken).
This section also describes implementation details that will be
significant to the programmer but which are not standardized.
handling only eight-bit characters.
It stores a character combined with attributes in a
.I \%chtype
-datum.
+datum,
+which is often an alias of
+.I int.
.IP
Attributes alone
(with no corresponding character)
corresponds to the non-wide configuration's
.I \%chtype.
It always a structure type,
-because it stores more data than can fit into an integer.
-A character code may be larger than can fit in a C
+because it stores more data than fits into an integral type.
+A character code may not be representable as a
.I \%char,
and moreover more than one character may occupy a cell
(as with accent marks and other diacritics).
structure,
not combined as in
.I \%chtype.
-.IP
-Each cell
-(row and column)
+.PP
+Each cell of a
.I \%WINDOW
is stored as a
.I \%cchar_t.
stores a wide character.
Like
.I \%chtype,
-this may be an integer.
+it may be an alias of
+.I int.
Depending on the character encoding,
a wide character may be
.I spacing,
meaning that it occupies a character cell by itself and typically
-accompanies cursor advancement on input,
+accompanies cursor advancement,
or
-.I combining,
+.I non-spacing,
meaning that it occupies the same cell as a spacing character,
is often regarded as a \*(``modifier\*('' of the base glyph with which
it combines,
-and typically does not advance the cursor on input.
+and typically does not advance the cursor.
.TP 9
.I \%wint_t
can store a
\f(BIcurses\fP Function Name/Man Page
_
COLOR_PAIR/\fBcurs_color\fP(3X)
-PAIR_NUMBER/\fBcurs_attr\fP(3X)
+PAIR_NUMBER/\fBcurs_color\fP(3X)
add_wch/\fBcurs_add_wch\fP(3X)
add_wchnstr/\fBcurs_add_wchstr\fP(3X)
add_wchstr/\fBcurs_add_wchstr\fP(3X)
\fBcurs_trace\fP(3X) - curses debugging routines
.RE
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fP upon failure and an
-integer value other than \fBERR\fP upon successful completion, unless
-otherwise noted in the routine descriptions.
-.PP
-As a general rule, routines check for null pointers passed as parameters,
-and handle this as an error.
-.PP
-All macros return the value of the \fBw\fP version, except \fBsetscrreg\fP,
-\fBwsetscrreg\fP, \fBgetyx\fP, \fBgetbegyx\fP, and \fBgetmaxyx\fP.
-The return values of
-\fBsetscrreg\fP,
-\fBwsetscrreg\fP,
-\fBgetyx\fP,
-\fBgetbegyx\fP, and
-\fBgetmaxyx\fP are undefined (i.e., these should not be used as the
-right-hand side of assignment statements).
+Unless otherwise noted,
+functions that return an integer return \fBOK\fP on success and
+\fBERR\fP on failure.
+Functions that return pointers return \fBNULL\fP on failure.
+Typically,
+.I \%ncurses
+treats a null pointer passed as a function parameter as a failure.
.PP
Functions with a \*(``mv\*('' prefix first perform cursor movement using
-\fB\%wmove\fP and return an error if the position is outside the window,
+\fB\%wmove\fP and fail if the position is outside the window,
or
(for \*(``mvw\*('' functions)
if the
.I \%WINDOW
pointer is null.
-Most \*(``mv\*(''-prefixed functions
-(except variadic functions such as \fB\%mvprintw\fP)
-are provided both as macros and functions.
-.PP
-Routines that return pointers return \fBNULL\fP on error.
.SH ENVIRONMENT
The following environment symbols are useful for customizing the
runtime behavior of the \fI\%ncurses\fP library.
The most important ones have been already discussed in detail.
.SS \fICC\fP command-character
-When set, change occurrences of the command_character
-(i.e., the \fBcmdch\fP capability)
-of the loaded terminfo entries to the value of this variable.
-Very few terminfo entries provide this feature.
+When set,
+change the
+.B \%command_character
+.RB ( \%cmdch )
+capability value of loaded
+.I \%term\%info
+entries to the value of this variable.
+Very few
+.I \%term\%info
+entries provide this feature.
.PP
Because this name is also used in development environments to represent
the C compiler's name,
Those functions are described in these pages:
.RS
.bP
-\fBcurs_extend\fP(3X) \- miscellaneous curses extensions
+\fB\%curs_extend\fP(3X) \- miscellaneous \fIcurses\fP extensions
.bP
-\fBcurs_inopts\fP(3X) \- \fBcurses\fP input options
+\fB\%curs_inopts\fP(3X) \- \fIcurses\fP input options
.bP
-\fBcurs_kernel\fP(3X) \- low-level \fBcurses\fP routines
+\fB\%curs_kernel\fP(3X) \- low-level \fIcurses\fP routines
.bP
-\fBcurs_termattrs\fP(3X) \- \fBcurses\fP environment query routines
+\fB\%curs_termattrs\fP(3X) \- \fIcurses\fP environment query routines
.bP
-\fBcurs_termcap\fP(3X) \- \fBcurses\fP emulation of termcap
+\fB\%curs_termcap\fP(3X) \- \fIcurses\fP emulation of \fItermcap\fP
.bP
-\fBcurs_terminfo\fP(3X) \- \fBcurses\fP interfaces to terminfo database
+\fB\%curs_terminfo\fP(3X) \- \fIcurses\fP interface to \fIterminfo\fP
+database
.bP
-\fBcurs_util\fP(3X) \- miscellaneous \fBcurses\fP utility routines
+\fB\%curs_util\fP(3X) \- miscellaneous \fIcurses\fP utility routines
.RE
.TP 5
\-\-with\-trace
.I \*d
compiled terminal capability database
.SH NOTES
-If standard output from a \fI\%ncurses\fP program is re-directed to
-something which is not a tty,
-screen updates will be directed to standard error.
-This was an undocumented feature of AT&T System V Release 3 curses.
+X/Open Curses permits most functions it specifies to be made available
+as macros as well.
+.\" See X/Open Curses Issue 4, Version 2, pp. 227-234.
+.\" See X/Open Curses Issue 7, pp. 311-318.
+\fI\%ncurses\fP does so
+.bP
+for functions that return values via their parameters,
+.bP
+to support obsolete features,
+.bP
+to reuse functions
+(for example,
+those that move the cursor before another operation),
+and
+.bP
+a few special cases.
+.PP
+If the standard output file descriptor of an
+.I \%ncurses
+program is redirected to something that is not a terminal device,
+the library writes screen updates to the standard error file descriptor.
+This was an undocumented feature of SVr3.
.PP
See subsection \*(``Header files\*('' below regarding symbols exposed by
inclusion of \fI\%curses.h\fP.
.SH EXTENSIONS
-The \fI\%ncurses\fP library can be compiled with an option
-(\fB\-DUSE_GETCAP\fP)
-that falls back to the old-style /etc/termcap file if the terminal setup code
-cannot find a terminfo entry corresponding to \fITERM\fP.
-Use of this feature is not recommended,
-as it essentially includes an entire termcap compiler in the
-\fI\%ncurses\fP startup code,
-at significant cost in core and startup cycles.
-.PP
-The \fI\%ncurses\fP library includes facilities for capturing mouse
-events on certain terminals
-(including xterm).
-See the \fBcurs_mouse\fP(3X)
-manual page for details.
-.PP
-The \fI\%ncurses\fP library includes facilities for responding to window
-resizing events, e.g., when running in an xterm.
-See the \fBresizeterm\fP(3X)
-and \fBwresize\fP(3X) manual pages for details.
-In addition, the library may be configured with a \fBSIGWINCH\fP handler.
-.PP
-The \fI\%ncurses\fP library extends the fixed set of function key
-capabilities of terminals by allowing the application designer to define
-additional key sequences at runtime.
-See the \fBdefine_key\fP(3X)
-\fBkey_defined\fP(3X),
-and \fBkeyok\fP(3X) manual pages for details.
-.PP
-The \fI\%ncurses\fP library can exploit the capabilities of terminals
-which implement the ISO\-6429 SGR 39 and SGR 49 controls,
+.I \%ncurses
+enables an application to capture mouse events on certain terminals,
+including
+.I \%xterm;
+see \fB\%curs_mouse\fP(3X).
+.PP
+.I \%ncurses
+provides a means of responding to window resizing events,
+as when running in a GUI terminal emulator application such as
+.I \%xterm;
+see \fB\%resizeterm\fP(3X) and \fB\%wresize\fP(3X).
+.PP
+.I \%ncurses
+allows an application to query the terminal for the presence of a wide
+variety of special keys;
+see \fB\%has_key\fP(3X).
+.PP
+.I \%ncurses
+extends the fixed set of function key capabilities specified by X/Open
+Curses by allowing the application programmer to define additional key
+sequences at runtime;
+see
+\fB\%define_key\fP(3X),
+\fB\%key_defined\fP(3X),
+and
+\fB\%keyok\fP(3X).
+.PP
+.I \%ncurses
+can exploit the capabilities of terminals implementing ISO\ 6429/ECMA-48
+SGR\ 39 and SGR\ 49 sequences,
which allow an application to reset the terminal to its original
foreground and background colors.
-From the users' perspective, the application is able to draw colored
-text on a background whose color is set independently, providing better
-control over color contrasts.
-See the \fBdefault_colors\fP(3X) manual page for details.
-.PP
-The \fI\%ncurses\fP library includes a function for directing
-application output to a printer attached to the terminal device.
-See the \fBcurs_print\fP(3X) manual page for details.
+From a user's perspective,
+the application is able to draw colored text on a background whose color
+is set independently,
+providing better control over color contrasts.
+See \fB\%default_colors\fP(3X).
+.PP
+An
+.I \%ncurses
+application can choose to hide the internal details of
+.I \%WINDOW
+structures,
+instead using accessor functions such as
+\fB\%is_scrollok\fP(3X).
+.PP
+.I \%ncurses
+enables an application to direct application output to a printer
+attached to the terminal device;
+see \fB\%curs_print\fP(3X).
+.PP
+.I \%ncurses
+offers \fB\%slk_attr\fP(3X) as a counterpart of \fB\%attr_get\fP(3X) for
+soft-label key lines,
+and \fB\%extended_slk_color\fP(3X) as a form of \fB\%slk_color\fP(3X)
+that can gather color information from them when many colors are
+supported.
+.PP
+Some extensions are only available if
+.I \%ncurses
+is compiled to support them;
+see section \*(``ALTERNATE CONFIGURATIONS\*('' above.
+.bP
+Rudimentary support for multi-threaded applications may be available;
+see \fBcurs_threads\fP(3X).
+.bP
+Functions that ease the management of multiple screens can be exposed;
+see \fBcurs_sp_funcs\fP(3X).
+.bP
+The compiler option
+.B \%\-DUSE_GETCAP
+causes the library to fall back to reading
+.I \%/etc/termcap
+if the terminal setup code cannot find a
+.I \%term\%info
+entry corresponding to
+.I TERM.
+Use of this feature is not recommended,
+as it essentially includes an entire
+.I termcap
+compiler in the
+.I \%ncurses
+startup code,
+at a cost in memory usage and application launch latency.
+.PP
+.I \%PDCurses
+and NetBSD
+.I curses
+incorporate some
+.I \%ncurses
+extensions.
+Individual man pages indicate where this is the case.
.SH PORTABILITY
-The \fI\%ncurses\fP library is intended to be BASE-level conformant with
-XSI Curses.
-The EXTENDED XSI Curses functionality
-(including color support) is supported.
-.PP
-A small number of local differences
-(that is,
-individual differences between the XSI Curses and \fI\%ncurses\fP calls)
-are described in \fBPORTABILITY\fP sections of the library man pages.
+X/Open Curses defines two levels of conformance,
+\*(``base\*('' and \*(``enhanced\*(''.
+The latter includes several additional features,
+such as wide-character and color support.
+.I \%ncurses
+intends base-level conformance with X/Open Curses,
+and supports nearly all its enhanced features.
+.\" XXX: What's missing? GBR counts untic(1), and that's all.
+.PP
+Differences between X/Open Curses and
+.I \%ncurses
+are documented in the \*(``PORTABILITY\*('' sections of applicable man
+pages.
.SS "Error Checking"
In many cases, X/Open Curses is vague about error conditions,
omitting some of the SVr4 documentation.
to tell an application which of several possible errors were detected.
Relying on this (or some other) extension will adversely affect the
portability of curses applications.
-.SS "Extensions Versus Portability"
-Most of the extensions provided by \fI\%ncurses\fP have not been
-standardized.
-Some have been incorporated into other implementations, such as
-PDCurses or NetBSD curses.
-Here are a few to consider:
-.bP
-The routine \fBhas_key\fP is not part of XPG4, nor is it present in SVr4.
-See the \fBcurs_getch\fP(3X) manual page for details.
-.bP
-The routine \fBslk_attr\fP is not part of XPG4, nor is it present in SVr4.
-See the \fBcurs_slk\fP(3X) manual page for details.
-.bP
-The routines \fBgetmouse\fP, \fBmousemask\fP, \fBungetmouse\fP,
-\fBmouseinterval\fP, and \fBwenclose\fP relating to mouse interfacing are not
-part of XPG4, nor are they present in SVr4.
-See the \fBcurs_mouse\fP(3X) manual page for details.
-.bP
-The routine \fBmcprint\fP was not present in any previous curses implementation.
-See the \fBcurs_print\fP(3X) manual page for details.
-.bP
-The routine \fBwresize\fP is not part of XPG4, nor is it present in SVr4.
-See the \fBwresize\fP(3X) manual page for details.
-.bP
-The \fI\%WINDOW\fP structure's internal details can be hidden from application
-programs.
-See \fBcurs_opaque\fP(3X) for the discussion of \fBis_scrollok\fP, etc.
-.bP
-This implementation can be configured to provide rudimentary support
-for multi-threaded applications.
-See \fBcurs_threads\fP(3X) for details.
-.bP
-This implementation can also be configured to provide a set of functions which
-improve the ability to manage multiple screens.
-See \fBcurs_sp_funcs\fP(3X) for details.
.SS "Padding Differences"
In historic curses versions, delays embedded in the capabilities \fBcr\fP,
\fBind\fP, \fBcub1\fP, \fBff\fP and \fBtab\fP activated corresponding delay
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: scr_dump.5,v 1.41 2023/12/23 16:27:25 tom Exp $
-.TH scr_dump 5 2023-12-23 "ncurses 6.4" "File formats"
+.\" $Id: scr_dump.5,v 1.42 2023/12/30 22:06:36 tom Exp $
+.TH scr_dump 5 2023-12-30 "ncurses 6.4" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.SH NAME
scr_dump \-
\fIcurses\fR screen dump
-.SH SYNOPSIS
-.B scr_dump
+.\"SH SYNOPSIS
.SH DESCRIPTION
The curses library provides applications with the ability to write the
contents of a window to an external file using \fBscr_dump\fP or \fBputwin\fP,
This is similar to Unix System\ V,
but does not write a \*(``magic number\*('' to identify the file format.
.SH PORTABILITY
-There is no standard format for \fBputwin\fP.
-This section gives a brief description of the existing formats.
+There is no standard format for
+.I curses
+screen dumps.
+A brief survey of the existing implementations follows.
.SS "X/Open Curses"
-Refer to \fIX/Open Curses, Issue 7\fP (2009).
-.PP
-X/Open's documentation for \fIenhanced curses\fP says only:
+X/Open Curses, Issue 7 specifies little.
+It says
+(boldface emphasis added)
.RS 3
.PP
-The \fBgetwin(\ ) \fPfunction reads window-related data
-stored in the file by \fIputwin(\ )\fP.
-The function
-then creates and initializes a new window using that data.
+\*(``[t]he \fI\%getwin()\fP function reads window-related data stored in
+the file by \fI\%putwin()\fP.
+The function then creates and initializes a new window using that data.
.PP
-The \fBputwin(\ )\fP function writes all data associated
-with \fIwin\fP into the \fI\%stdio\fP(3) stream to which \fIfilep\fP
-points, using an \fBunspecified format\fP.
-This information can be retrieved later using \fBgetwin(\ )\fP.
+The \fI\%putwin()\fP function writes all data associated with \fIwin\fP
+into the \fI\%stdio\fP stream to which \fIfilep\fP points,
+using an \fBunspecified format\fP.
+This information can be retrieved later using \fI\%getwin()\fP.\*(''
.RE
.PP
In the mid-1990s when the X/Open Curses document was written,
-there were still systems using older, less capable curses libraries
-(aside from the BSD curses library which was not relevant to X/Open
-because it did not meet the criteria for \fIbase curses\fP).
-The document explained the term \*(``enhanced\*('' as follows:
-.RS 3
-.bP
-Shading is used to identify \fIX/Open Enhanced Curses\fP material,
-relating to interfaces included to provide enhanced capabilities
-for applications originally written to be compiled on systems
-based on the Unix operating system.
-Therefore, the features described may not be present on systems
-that conform to \fBXPG4 or to earlier XPG releases\fP.
-The relevant reference pages may provide additional
-or more specific portability warnings about use of the material.
-.RE
-.PP
-In the foregoing, emphasis was added to \fBunspecified format\fP
-and to \fBXPG4 or to earlier XPG releases\fP,
-for clarity.
-.SS "Unix System V"
-Unix System\ V curses identified the file format by writing a
-\*(``magic number\*('' at the beginning of the dump.
+there were still System\ V systems using older,
+less capable
+.I curses
+libraries.
+BSD
+.I curses
+was not relevant to X/Open because it did not meet the criteria
+for base-level conformance;
+see \fB\%ncurses\fP(3X).
+.SS "System V"
+System\ V
+.I curses
+identified the file format by writing a \*(``magic number\*('' at the
+beginning of the dump.
The \fI\%WINDOW\fP data and the lines of text follow, all in binary form.
.PP
-The Solaris curses source has these definitions:
+Solaris
+.I curses
+has the following definitions.
.PP
.RS 4
.EX
.PP
That is, the feature was likely introduced in SVr2 (1984),
and improved in SVr3 (1987).
-The Solaris curses source has no magic number for SVr4 (1989).
-Other operating systems (AIX and HP-UX) use a magic number which would
-correspond to this definition:
+Solaris
+.I curses
+has no magic number for SVr4 (1989).
+Other System\ V operating systems
+(AIX and HP-UX)
+use a magic number that would correspond to the following.
.PP
.RS 4
.EX
.RE
.PP
That octal number in bytes is 001, 035.
-Because most Unix vendors use big-endian hardware,
-the magic number is written with the high-order byte first, e.g.,
+Because most Unix vendors at the time used big-endian hardware,
+the magic number is written with the high-order byte first.
.PP
.RS 4
.EX
.EE
.RE
.PP
-After the magic number, the \fI\%WINDOW\fP structure and line-data are
-written in binary format.
-While the magic number used by the Unix systems can be seen using \fBod\fP(1),
-none of the Unix systems documents the format used for screen-dumps.
+After the magic number,
+the \fI\%WINDOW\fP structure and line data are written in binary format.
+While the magic number used by these systems can be observed with
+\fIod\fP(1),
+none of them documents the format used for screen dumps.
.PP
-The Unix systems do not use identical formats.
-While collecting information for for this manual page,
-the \fIsavescreen\fP test-program
-produced dumps of different size
-(all on 64-bit hardware, on 40x80 screens):
+Nor do they use an identical format,
+even with the System\ V family.
+The
+.I \%ncurses
+.I \%savescreen
+test program was used to collect information for this manual page.
+It produced dumps of different size
+(all on 64-bit hardware,
+on 40x80 screens):
.bP
AIX (51817 bytes)
.bP
.bP
\fI\%ncurses\fP5 (12888 bytes)
.SS Solaris
-As noted above, Solaris curses has no magic number corresponding
-to SVr4 curses.
-This is odd since Solaris was the first operating system
-to pass the SVr4 guidelines.
-Solaris has two versions of curses:
+As noted above,
+Solaris
+.I curses
+has no magic number corresponding to SVr4
+.I curses.
+This is odd,
+since Solaris was the first operating system to meet the SVr4
+guidelines.
+Solaris furthermore supplies two versions of
+.I curses.
.bP
-The default curses library uses the SVr3 magic number.
+The default
+.I curses
+library uses the SVr3 magic number.
.bP
-There is an alternate curses library in \fB/usr/xpg4\fP.
-This uses a textual format with no magic number.
+An alternate
+.I curses
+library
+(which we term
+.I \%xcurses),
+available in
+.I /usr/xpg4,
+uses a textual format with no magic number.
.IP
-According to the copyright notice, the \fIxpg4\fP Solaris curses library was
-developed by MKS (Mortice Kern Systems) from 1990 to 1995.
+According to its copyright notice,
+this
+.I \%xcurses
+library was developed by MKS
+(Mortice Kern Systems) from 1990 to 1995.
.IP
-Like ncurses6, there is a file-header with parameters.
-Unlike ncurses6, the contents of the window are written piecemeal,
-with coordinates and attributes for each chunk of text rather
-than writing the whole window from top to bottom.
+Like ncurses6,
+it includes a header with parameters.
+Unlike ncurses6,
+the contents of the window are written piecemeal,
+with coordinates and attributes for each chunk of text rather than
+writing the whole window from top to bottom.
.SS PDCurses
-PDCurses added support for screen dumps in version 2.7 (2005).
-Like Unix System\ V and ncurses5,
+.I \%PDCurses
+added support for screen dumps in version 2.7 (2005).
+Like System\ V and ncurses5,
it writes the \fI\%WINDOW\fP structure in binary,
but begins the file with its three-byte identifier \*(``PDC\*('',
-followed by a one-byte version,
-e.g.,
+followed by a single-byte version number.
.PP
.RS 4
.EX
.EE
.RE
.SS NetBSD
-As of April 2017, NetBSD curses does
-not support \fBscr_dump\fP and \fBscr_restore\fP
-(or \fBscr_init\fP, \fBscr_set\fP),
-although it has \fBputwin\fP and \fBgetwin\fP.
+As of April 2017,
+NetBSD
+.I curses
+does not support \fB\%scr_dump\fP and \fB\%scr_restore\fP
+(or \fB\%scr_init\fP,
+\fB\%scr_set\fP),
+although it has \fB\%putwin\fP and \fB\%getwin\fP.
.PP
-Like ncurses5, NetBSD \fBputwin\fP does not identify its dumps with a
-useful magic number.
+Like ncurses5,
+NetBSD \fB\%putwin\fP does not identify its dumps with a useful magic
+number.
It writes
.bP
-the curses shared library major and minor versions
-as the first two bytes (e.g., 7 and 1),
+the
+.I curses
+shared library major and minor versions as the first two bytes
+(for example,
+7 and 1),
.bP
followed by a binary dump of the \fI\%WINDOW\fP,
.bP
-some data for wide-characters referenced by the \fI\%WINDOW\fP structure, and
+some data for wide characters referenced by the \fI\%WINDOW\fP
+structure,
+and
.bP
-finally, lines as done by other implementations.
+finally,
+lines as done by other implementations.
.SH EXAMPLES
Given a simple program which writes text to the screen
(and for the sake of example, limiting the screen-size to 10x20):
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: term.5,v 1.69 2023/12/23 16:08:25 tom Exp $
-.TH term 5 2023-12-23 "ncurses 6.4" "File formats"
+.\" $Id: term.5,v 1.70 2023/12/30 21:36:32 tom Exp $
+.TH term 5 2023-12-30 "ncurses 6.4" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.TP 3
b) \fIterminal names\fP,
.TP 3
-c) \fIboolean flags\fP,
+c) \fIBoolean flags\fP,
.TP 3
d) \fInumbers\fP,
.TP 3
.TP 5
(2) the size, in bytes, of the \fIterminal names\fP section;
.TP 5
-(3) the number of bytes in the \fIboolean flags\fP section;
+(3) the number of bytes in the \fIBoolean flags\fP section;
.TP 5
(4) the number of short integers in the \fInumbers\fP section;
.TP 5
.RE
.PP
The capabilities in the
-\fIboolean flags\fP,
+\fIBoolean flags\fP,
\fInumbers\fP, and
\fIstrings\fP
sections are in the same order as the file <term.h>.
.IP
The integer value \-1 is represented by two bytes 0377, 0377.
.br
-Absent boolean values are represented by the byte 0 (false).
+Absent Boolean values are represented by the byte 0 (false).
.bP
If a capability has been canceled from this terminal,
@TIC@ stores a \-2 in the corresponding table.
.IP
The integer value \-2 is represented by two bytes 0377, 0376.
.br
-The boolean value \-2 is represented by the byte 0376.
+The Boolean value \-2 is represented by the byte 0376.
.br
.bP
Other negative values are illegal.
The \fIterminal names\fP section is terminated
with an \s-1ASCII NUL\s+1 character.
.PP
-The \fIboolean flags\fP section has one byte for each flag.
+The \fIBoolean flags\fP section has one byte for each flag.
Boolean capabilities are either 1 or 0 (true or false)
according to whether the terminal supports the given capability or not.
.PP
-Between the \fIboolean flags\fP section and the \fInumber\fP section,
+Between the \fIBoolean flags\fP section and the \fInumber\fP section,
a null byte will be inserted, if necessary,
to ensure that the \fInumber\fP section begins on an even byte
This is a relic of the PDP\-11's word-addressed architecture,
by addressing a word on an odd byte boundary.
All short integers are aligned on a short word boundary.
.PP
-The \fInumbers\fP section is similar to the \fIboolean flags\fP section.
+The \fInumbers\fP section is similar to the \fIBoolean flags\fP section.
Each capability takes up two bytes,
and is stored as a little-endian short integer.
.PP
The previous section describes the conventional terminfo binary format.
With some minor variations of the offsets (see PORTABILITY),
the same binary format is used in all modern Unix systems.
-Each system uses a predefined set of boolean, number or string capabilities.
+Each system uses a predefined set of Boolean, number or string capabilities.
.PP
The \fI\%ncurses\fP libraries and applications support
extended terminfo binary format,
.RS 5
.TP 5
(1)
-count of extended boolean capabilities
+count of extended Boolean capabilities
.TP 5
(2)
count of extended numeric capabilities
.PP
The extended string table contains values for string capabilities.
After the end of these values, it contains the names for each of
-the extended capabilities in order, e.g., booleans, then numbers and
+the extended capabilities in order, e.g., Booleans, then numbers and
finally strings.
.PP
By storing terminal descriptions in this way,
must be prepared for both possibilities \-
this is why the numbers and sizes are included.
Also, new capabilities must always be added at the end of the lists
-of boolean, number, and string capabilities.
+of Boolean, number, and string capabilities.
.SS "Binary Format"
X/Open Curses does not specify a format for the terminfo database.
System V curses used a directory-tree of binary files,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: terminfo.head,v 1.59 2023/12/23 23:44:58 tom Exp $
-.TH terminfo 5 2023-12-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
+.\" $Id: terminfo.head,v 1.60 2023/12/30 22:21:45 tom Exp $
+.TH terminfo 5 2023-12-30 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
After the first field (giving the name(s) of the terminal entry),
there should be one or more \fIcapability\fP fields.
-These are boolean, numeric or string names with corresponding values:
+These are Boolean, numeric or string names with corresponding values:
.bP
Boolean capabilities are true when present, false when absent.
-There is no explicit value for boolean capabilities.
+There is no explicit value for Boolean capabilities.
.bP
Numeric capabilities have a \*(``#\*('' following the name,
then an unsigned decimal integer value.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: terminfo.tail,v 1.140 2023/12/23 16:23:35 tom Exp $
+.\" $Id: terminfo.tail,v 1.141 2023/12/30 21:36:32 tom Exp $
.ps +1
.SS "User-Defined Capabilities"
.
\fB@TIC@\fP treats unknown capabilities as user-defined.
That is, if \fB@TIC@\fP encounters a capability name
which it does not recognize,
-it infers its type (boolean, number or string) from the syntax
+it infers its type (Boolean, number or string) from the syntax
and makes an extended table entry for that capability.
The \fBuse_extended_names\fP(3X) function makes this information
conditionally available to applications.
User-defined capability strings whose name begins
with \*(``k\*('' are treated as function keys.
.bP
-The types (boolean, number, string) determined by \fB@TIC@\fP
+The types (Boolean, number, string) determined by \fB@TIC@\fP
can be inferred by successful calls on \fBtigetflag\fP, etc.
.bP
If the capability name happens to be two characters,
terminfo implementations.
As a rule,
user-defined capabilities intended for use by termcap applications should
-be limited to booleans and numbers to avoid running past the 1023 byte
+be limited to Booleans and numbers to avoid running past the 1023 byte
limit assumed by termcap implementations and their applications.
In particular, providing extended sets of function keys (past the 60
numbered keys and the handful of special named keys) is best done using
on many terminals without a true insert/delete line,
and is often faster even on terminals with those features.
.PP
-The boolean \fBnon_dest_scroll_region\fP should be set if each scrolling
+The Boolean \fBnon_dest_scroll_region\fP should be set if each scrolling
window is effectively a view port on a screen-sized canvas.
To test for
this capability, create a scrolling region in the middle of the screen,
.PP
A command to erase or blank the status line may be specified as \fBdsl\fP.
.PP
-The boolean capability \fBeslok\fP specifies that escape sequences, tabs,
+The Boolean capability \fBeslok\fP specifies that escape sequences, tabs,
etc., work ordinarily in the status line.
.PP
The \fI\%ncurses\fP implementation does not yet use any of these
their default values for the terminal.
Some terminals (including many PC
terminal emulators) erase screen areas with the current background color rather
-than the power-up default background; these should have the boolean capability
+than the power-up default background; these should have the Boolean capability
\fBbce\fP.
.PP
While the curses library works with \fIcolor pairs\fP
describe the color.
These three parameters default to being interpreted as RGB
(Red, Green, Blue) values.
-If the boolean capability \fBhls\fP is present,
+If the Boolean capability \fBhls\fP is present,
they are instead as HLS (Hue, Lightness, Saturation) indices.
The ranges are
terminal-dependent.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tic.1m,v 1.105 2023/12/23 16:08:25 tom Exp $
-.TH @TIC@ 1M 2023-12-23 "ncurses 6.4" "User commands"
+.\" $Id: tic.1m,v 1.106 2023/12/30 21:36:32 tom Exp $
+.TH @TIC@ 1M 2023-12-30 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB\-x\fP
Treat unknown capabilities as user-defined (see \fBuser_caps\fP(5)).
That is, if you supply a capability name which \fB@TIC@\fP does not recognize,
-it will infer its type (boolean, number or string) from the syntax and
+it will infer its type (Boolean, number or string) from the syntax and
make an extended table entry for that.
User-defined capability strings
whose name begins with \*(``k\*('' are treated as function keys.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tput.1,v 1.96 2023/12/23 20:55:36 tom Exp $
-.TH @TPUT@ 1 2023-12-23 "ncurses 6.4" "User commands"
+.\" $Id: tput.1,v 1.97 2023/12/31 00:16:41 tom Exp $
+.TH @TPUT@ 1 2023-12-30 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB\%reset\fP \-
initialize a terminal or query \fI\%term\%info\fP database
.SH SYNOPSIS
-\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] \fIcap-code\fP [\fIparameter\fP .\|.\|.]
+\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP]
+{\fIcap-code\fP [\fIparameter\fP .\|.\|.\&]} .\|.\|.
.PP
\fB@TPUT@\fP [\fB\-T\fP \fIterminal-type\fP] [\fB\-x\fP] \fBclear\fP
.PP
Otherwise, \fBreset\fP acts identically to \fBinit\fP.
.TP
.B longname
+A terminfo entry begins with one or more names by which an
+application can refer to the entry,
+before the list of terminal capabilities.
+The names are separated by \*(``|\*('' characters.
+X/Open states that the last name is the \*(``long name\*(''
+and also that it may include blanks.
+.IP
+\fB\%@TIC@\fP warns if the last name does not include blanks,
+to accommodate old terminfo entries which treated
+the long name as an optional feature.
+The long name is often referred to as the description field.
+.IP
If the terminal database is present and an entry for the user's terminal
exists
(see
(or \*(``long name\*('')
to the standard output,
without a trailing newline.
-See \fBterm\fP(5).
+See \fB\%term\%info\fP(5).
.SS Aliases
\fB@TPUT@\fP handles the \fBclear\fP, \fBinit\fP and \fBreset\fP
commands specially:
and turns on bold
(extra bright)
mode.
-.IP
-The same sequence of commands can be combined using the OpenBSD feature:
-.IP
-.EX
-$ \fB@TPUT@ \fBclear\fP \fBcup 10 10\fP \fBbold\fP
-.EE
+.TP 5
+.B @TPUT@ clear cup 10 10 bold
+Perform the same actions as the foregoing
+.RB \%\[lq] @TPUT@
+.BR \-S \[rq]
+example.
.SH SEE ALSO
\fB\%@CLEAR@\fP(1),
\fB\%stty\fP(1),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: user_caps.5,v 1.43 2023/12/23 16:08:25 tom Exp $
-.TH user_caps 5 2023-12-23 "ncurses 6.4" "File formats"
+.\" $Id: user_caps.5,v 1.44 2023/12/30 21:36:32 tom Exp $
+.TH user_caps 5 2023-12-30 "ncurses 6.4" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
and standardized in the Single Unix Specification beginning in 1995.
.PP
Most of the \fIextensions\fP in this fixed repertoire were additions
-to the tables of boolean, numeric and string capabilities.
+to the tables of Boolean, numeric and string capabilities.
Rather than change the meaning of an existing capability, a new name was added.
The terminfo database uses a binary format; binary compatibility was
ensured by using a header which gave the number of items in the
.RS 3
.TP 3
AX
-\fIboolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
+\fIBoolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
by resetting the foreground and background color, respectively, to the default.
.IP
This is a feature recognized by the \fBscreen\fP program as well.
The command \*(``\fBtput clear\fP\*('' does the same thing.
.TP 3
NQ
-\fIboolean\fP,
+\fIBoolean\fP,
used to suppress a consistency check in @TIC@ for the \fI\%ncurses\fP
capabilities
in user6 through user9 (u6, u7, u8 and u9)
and its device attributes.
.TP 3
RGB
-\fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
+\fIBoolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
used to assert that the
\fBset_a_foreground\fP and
\fBset_a_background\fP capabilities correspond to \fIdirect colors\fP,
The capability type determines the values which \fI\%ncurses\fP sees:
.RS 3
.TP 3
-\fIboolean\fP
+\fIBoolean\fP
implies that the number of bits for red, green and blue are the same.
Using the maximum number of colors,
\fI\%ncurses\fP adds two,
\fInumber\fP
tells \fI\%ncurses\fP what result to add to red, green and blue.
If \fI\%ncurses\fP runs out of bits,
-blue (and green) lose just as in the \fIboolean\fP case.
+blue (and green) lose just as in the \fIBoolean\fP case.
.TP 3
\fIstring\fP
explicitly list the number of bits used for red, green and blue components
# Report bugs and new terminal descriptions to
# bug-ncurses@gnu.org
#
-# $Revision: 1.1085 $
-# $Date: 2023/12/16 13:48:44 $
+# $Revision: 1.1092 $
+# $Date: 2023/12/30 18:05:02 $
#
# The original header is preserved below for reference. It is noted that there
# is a "newer" version which differs in some cosmetic details (but actually
ms-vt-utf8|vt-utf8|UTF-8 flavor of VT100+,
use=ms-vt100+,
+# VT-UTF-8 and VT100+ Protocols
+# https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-vuvp/969416c0-ccd6-4a75-a9b3-597d7713845b
+#
+# This Microsoft "protocol" adapted the aixterm 16-color feature from xterm's
+# documentation in 2015, as seen in successive revisions:
+#
+# 2013/07/22 has 8 colors
+# 2015/10/16 has 16 colors using SGR 90-97, 100-107 as well as SGR 24 and 27,
+# adds "informative" reference to xterm's ctlseqs
+#
+# The cnorm/civis definitions added in 2015 are unrelated to any standard.
+ms-vt100-16color|VT-UTF-8 and VT100+,
+ civis=\E[?h, cnorm=\E[?l, rmso=\E[27m, rmul=\E[24m,
+ use=ibm+16color, use=ms-vt100+,
+
+# Based on
+# https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences
+# We use this scheme to map function keys
+# terminfo modifier code keys
+# kf13-kf24 shift 2 F1 to F12
+# kf25-kf36 alt 3 F1 to F12
+# kf37-kf48 control 4 F1 to F12
+# kf49-kf60 ctrl-alt 7 F1 to F12
+#
+# Unclear: smam and rmam implemented?
+# Unclear: rmkx, smkx, rmir, smir - irrelevant?
+#
+# TD:
+# + According to tack, tbc and cbt fail.
+# + The line-drawing (acsc) does not work in telnet or ssh. I added the
+# U8 extension to tell ncurses to use UTF-8 for line-drawing (when the
+# locale uses UTF-8). That won't work for telnet (which uses ASCII),
+# but seems to work for OpenSSH's ssh. I set the codepage to 65001,
+# of course.
+# + Function keys... do not work consistently in telnet and ssh. With
+# telnet, kf1-kf4 are \EOP to \EOS, and kf5-kf12 match the terminfo.
+# But with ssh, it's entirely different (reminds me of rxvt).
+winconsole|Windows 10 new console,
+ am, km, mir, msgr, xenl, AX,
+ ncv@, U8#1,
+ acsc=++\,\,--..00``aaffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxy
+ yzz~~,
+ bel=^G, blink@, cr=\r, ech=\E[%p1%dX, el1=\E[0K, ich1@, ind=\n,
+ invis@, is1=\E[!p, kdch1=\E[3~, kend=\E[4~, kf1=\E[11~,
+ kf10=\E[21~, kf11=\E[23~, kf12=\E[24~, kf13=\E[11;2~,
+ kf14=\E[12;2~, kf15=\E[13;2~, kf16=\E[14;2~,
+ kf17=\E[15;2~, kf18=\E[17;2~, kf19=\E[18;2~, kf2=\E[12~,
+ kf20=\E[19;2~, kf21=\E[20;2~, kf22=\E[21;2~,
+ kf23=\E[24;2~, kf24=\E[25;2~, kf25=\E[11;3~,
+ kf26=\E[12;3~, kf27=\E[13;3~, kf28=\E[14;3~,
+ kf29=\E[15;3~, kf3=\E[13~, kf30=\E[17;3~, kf31=\E[18;3~,
+ kf32=\E[19;3~, kf33=\E[20;3~, kf34=\E[21;3~,
+ kf35=\E[24;3~, kf36=\E[25;3~, kf37=\E[11;4~,
+ kf38=\E[12;4~, kf39=\E[13;4~, kf4=\E[14~, kf40=\E[14;4~,
+ kf41=\E[15;4~, kf42=\E[17;4~, kf43=\E[18;4~,
+ kf44=\E[19;4~, kf45=\E[20;4~, kf46=\E[21;4~,
+ kf47=\E[24;4~, kf48=\E[25;4~, kf49=\E[11;7~, kf5=\E[15~,
+ kf50=\E[12;7~, kf51=\E[13;7~, kf52=\E[14;7~,
+ kf53=\E[15;7~, kf54=\E[17;7~, kf55=\E[18;7~,
+ kf56=\E[19;7~, kf57=\E[20;7~, kf58=\E[21;7~,
+ kf59=\E[24;7~, kf6=\E[17~, kf60=\E[25;7~, kf7=\E[18~,
+ kf8=\E[19~, kf9=\E[20~, khome=\E[1~, kich1=\E[2~,
+ knp=\E[6~, kpp=\E[5~, nel=\r\n, ri=\E[T, rmacs=\E(B, rmir@,
+ rmpch@, rs1=\E[!p,
+ sgr=\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;7%;m%?%p9%t
+ \E(0%e\E(B%;,
+ sgr0=\E[0m\E(B, smacs=\E(0, smir@, smpch@, use=ansi+arrows,
+ use=ansi+csr, use=ansi+cup, use=ansi+erase, use=ansi+idc,
+ use=ansi+idl, use=ecma+index, use=ansi+inittabs,
+ use=ansi+local, use=ecma+sgr, use=ecma+color,
+ use=vt220+cvis,
+
# Windows Terminal (Preview)
# https://github.com/microsoft/terminal
#
%t;7;31%;%?%p3%t;7;34%;m,
smso=\E[7;31m, smul=\E[4;42m, use=xterm+sl, use=xterm-r6,
+# This was mentioned
+# http://unix.stackexchange.com/questions/119/colors-in-man-pages
+# pointing to
+# http://nion.modprobe.de/blog/archives/569-colored-manpages.html
+# (blog posting by Nico Golde, June 24 2007)
+# archive:
+# https://web-beta.archive.org/web/20070921042430/http://nion.modprobe.de/mostlike.txt
+# The comment hints where it started, but there are differences:
+# Reconstructed via infocmp from file: /usr/share/terminfo/x/xterm-pcolor
+mostlike|manpages with color looking like most,
+ OTbs@,
+ bold=\E[1m\E[31m,
+ is2=\E7\E[r\E[m\E[?7h\E[?1;3;4;6l\E[4l\E8\E>, kbs=^H,
+ meml@, memu@, rev=\E[7m\E[34m,
+ rs2=\E7\E[r\E8\E[m\E[?7h\E[?1;3;4;6l\E[4l\E>, sgr@,
+ smso=\E[1;30m\E[47m, smul=\E[32m, TS@, use=xterm-pcolor,
+
# This describes the capabilities of color_xterm, an xterm variant from
# before ECMA-48 color support was folded into the main-line xterm release.
# This entry is straight from color_xterm's maintainer.
use=xterm+sl-twm, use=ecma+italics, use=xterm+pce2,
use=xterm+pcc2, use=xterm+pcf2, use=bracketed+paste,
+# https://github.com/raphamorim/rio
+# derived from alacritty
+rio|fork of alacritty,
+ use=alacritty,
+rio-direct|fork of alacritty,
+ use=alacritty-direct,
+
#### Kitty
# https://github.com/kovidgoyal/kitty
# Project started in 2016/10 (see alacritty), but is a Python script rather
use=xterm+pcfkeys, use=xterm-basic,
use=bracketed+paste,
+######## Miscellaneous
+
+#### WezTerm
+# https://wezfurlong.org/wezterm/
+# https://github.com/wez/wezterm
+#
+# which says:
+# "wezterm is a terminal emulator with support for modern features
+# such as fonts with ligatures, hyperlinks, tabs and multiple windows."
+#
+# wezterm-20230712_072601_f4abf8fd-1.fedora38.x86_64
+# tested with MacOS and Fedora 38/39.
+#
+# General:
+# + written in Rust.
+# + initial screensize is odd, i.e., 81x24
+# provides no visual feedback on resize
+# ignores "resize -s"
+# manual resize and then running resize got off-by-one adjustment
+# + leaves debris (unerased cells) when switching between normal/alternate
+# screens.
+# + sets TERM=xterm-256color
+# tack:
+# + misplaced message in "am" screen
+# + fails xenl (should be false)
+# + cvvis is same as cnorm, block
+# + has blink and dim
+# + in bce test, blue isn't really blue but some pale purple
+# + modified keys mostly work, but its tab control interferes with some
+# + rmm/smm don't work (always uses escape-prefix)
+# wraptest:
+# + poor (doesn't copy anyone, most of the results are wrong)
+# vttest:
+# + DA is VT5xx with sixel, selective erase, user windows, color
+# + DA2 is VT220 version 277
+# + only the VT100 character set works, contrary to DA/DA2.
+# + no NRCS, either
+# + double-sized character work, with some debris
+# + doesn't switch between 80/132 columns.
+# + numeric keypad ANSI application mode escapes don't work.
+# + numeric keypad ANSI mode misses "0", ".", ","
+# + uses PC-style editing keypad \E[H and \E[F for Find and Select
+# + no VT52
+# + DECSED selective erase doesn't work
+# + SRM doesn't work
+# + 8-bit controls don't work
+# + DECNCSM doesn't work
+# + most DECRQSS do not work (DECSCL, DECSTBM, DECSLRM respond)
+# + DECRQM/DECRPM don't work (most reply permanently reset)
+# + DECLRMM responds to DECRPM, but VT420 rectangle tests do not work.
+# Some of the left/right margin tests work with the cursor-movement screen,
+# but DECFI/DECBI do not work. The other cursor-movement tests are buggy.
+# + implements ECMA-48 cursor movement, but not SL/SR or protected area
+# + implements xterm normal, any-event and button-event mouse, none of the rest
+# + reports window size, none of the other window reports
+wezterm|Wez's Terminal Emulator,
+ km@, xenl@,
+ cvvis@, rmkx=\E[?1l, rmm@, smkx=\E[?1h, smm@,
+ use=xterm-256color,
+
+#### Contour
+# https://github.com/contour-terminal/contour
+#
+# "Modern C++ Terminal Emulator"
+# Contour is a modern and actually fast, modal, virtual terminal emulator,
+# for everyday use. It is aiming for power users with a modern feature mindset.
+#
+# That is three occurrences of "modern" too many -TD
+#
+# MacOS
+# - cannot run, because the package is not signed.
+#
+# Fedora rawhide
+# contour-terminal-0.3.12.262-6.fc39.x86_64
+# - dumps core, cannot test
+#
+# Fedora 39
+# contour-terminal-0.4.0.6245-1.fc38.x86_64
+# - starts but doesn't display
+#
+# Fedora 38
+# contour-terminal-0.4.0.6245-1.fc38.x86_64
+# - starts but doesn't display
+# contour-terminal-0.3.12.262-1.fc38.x86_64
+# + testable (see below)
+# + initial screensize 62x23, no visual feedback on resize, no "resize -s"
+#
+# Sets TERM=contour (which is preferable to xterm).
+#
+# tack:
+# + cvvis is same as cnorm, "|"
+# + sitm/ritm don't work
+# + rmm/smm don't work (always uses escape, but terminfo defines km)
+# + initp interchanges red/blue (bug in tack?)
+# + modified F1-F4 are wrong, sending SS3 with modifier numbers
+# + shifted editing-keypad doesn't send anything
+# + meta key doesn't work
+# + status-line works (based on xterm, including window-resizing)
+# + dots don't line up for home test
+#
+# wraptest:
+# + poor 7/25 differences from xterm (perhaps copying iTerm2)
+#
+# vttest:
+# + hangs in menu 1, etc., when it tries to resize
+#
+# infocmp vs xterm-256color
+# + missing XM/xm
+# + rmcup/smcup doesn't use title-stack (but is implemented)
+# + doesn't use SGR mouse (but is implemented)
+# + sgr doesn't define dim, but dim capability is in terminfo (implemented)
+#
+# Developer's terminfo (compiled-in) uses some extensions.
+contour|contour-latest|Contour Terminal Emulator,
+ am, bce, eslok, hs, km, mc5i, mir, msgr, npc, xenl, xvpa,
+ cols#80, it#8, lines#24, pairs#0x7fff,
+ acsc=``aaffggiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~,
+ bel=^G, bold=\E[1m, cbt=\E[Z, clear=\E[H\E[2J, cr=\r,
+ cub=\E[%p1%dD, cub1=^H, cud=\E[%p1%dB, cud1=\n,
+ cuf=\E[%p1%dC, cuf1=\E[C, cuu=\E[%p1%dA, cuu1=\E[A,
+ dim=\E[2m, dsl=\E[$~, ech=\E[%p1%dX, el1=\E[1K,
+ flash=\E[?5h$<100/>\E[?5l, fsl=\E[$}, hpa=\E[%i%p1%dG,
+ ht=^I, hts=\EH, ind=\n, indn=\E[%p1%dS, invis=\E[8m, ka1=,
+ ka3=, kbs=^?, kc1=, kc3=, kcbt=\E[Z, kend=\EOF, khlp=,
+ kmous=\E[M, kund=, oc=\E]104\E\\, op=\E[39;49m, rev=\E[7m,
+ ri=\EM, rin=\E[%p1%dT, rmacs=\E(B, rmam=\E[?7l,
+ rmkx=\E[?1l, rmso=\E[27m, rmul=\E[24m, rs1=\E]\E\\\Ec,
+ sgr=%?%p9%t\E(0%e\E(B%;\E[0%?%p6%t;1%;%?%p2%t;4%;%?%p1%p3%|
+ %t;7%;%?%p4%t;5%;%?%p7%t;8%;m,
+ sgr0=\E(B\E[m, smacs=\E(0, smam=\E[?7h, smkx=\E[?1h,
+ smso=\E[7m, smul=\E[4m, tbc=\E[3g,
+ tsl=\E[2$~\E[1$}\E[H\E[2J, vpa=\E[%i%p1%dd,
+ Cs=\E]12;%p1%s\E\\, E3=\E[3J, Rmol=\E[55m, Se=\E[ q,
+ Smol=\E[53m, Smulx=\E[4:%p1%dm, Ss=\E[%p1%d q,
+ use=ansi+apparrows, use=ansi+cup, use=ansi+csr,
+ use=ansi+erase, use=ansi+idc, use=ansi+idl, use=ansi+rep,
+ use=att610+cvis, use=ecma+italics, use=ecma+strikeout,
+ use=xterm+256color, use=xterm+alt1049, use=xterm+pcc2,
+ use=xterm+pce2, use=xterm+pcf2,
+
+contour-direct|Contour terminal with direct colors,
+ use=xterm+direct, use=contour,
+
######## UNIX VIRTUAL TERMINALS, VIRTUAL CONSOLES, AND TELNET CLIENTS
#
# 2023-12-16
# + used "infocmp -u" to help trim redundant capabilities -TD
#
+# 2023-12-30
+# + add ms-vt100-16color, winconsole -TD
+# + add rio, rio-direct -TD
+# + add mostlike -TD
+# + add wezterm, contour -TD
+#
######## SHANTIH! SHANTIH! SHANTIH!
-ncurses6 (6.4+20231223) unstable; urgency=low
+ncurses6 (6.4+20231230) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 23 Dec 2023 06:35:00 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Fri, 29 Dec 2023 05:35:26 -0500
ncurses6 (5.9+20131005) unstable; urgency=low
-ncurses6 (6.4+20231223) unstable; urgency=low
+ncurses6 (6.4+20231230) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 23 Dec 2023 06:35:00 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Fri, 29 Dec 2023 05:35:26 -0500
ncurses6 (5.9+20131005) unstable; urgency=low
-ncurses6 (6.4+20231223) unstable; urgency=low
+ncurses6 (6.4+20231230) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 23 Dec 2023 06:35:00 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Fri, 29 Dec 2023 05:35:25 -0500
ncurses6 (5.9+20120608) unstable; urgency=low
-; $Id: mingw-ncurses.nsi,v 1.625 2023/12/23 11:35:00 tom Exp $\r
+; $Id: mingw-ncurses.nsi,v 1.626 2023/12/29 10:35:26 tom Exp $\r
\r
; TODO add examples\r
; TODO bump ABI to 6\r
!define VERSION_MAJOR "6"\r
!define VERSION_MINOR "4"\r
!define VERSION_YYYY "2023"\r
-!define VERSION_MMDD "1223"\r
+!define VERSION_MMDD "1230"\r
!define VERSION_PATCH ${VERSION_YYYY}${VERSION_MMDD}\r
\r
!define MY_ABI "5"\r
Summary: shared libraries for terminal handling
Name: mingw32-ncurses6
Version: 6.4
-Release: 20231223
+Release: 20231230
License: X11
Group: Development/Libraries
URL: https://invisible-island.net/ncurses/
Summary: shared libraries for terminal handling
Name: ncurses6
Version: 6.4
-Release: 20231223
+Release: 20231230
License: X11
Group: Development/Libraries
URL: https://invisible-island.net/ncurses/
Summary: Curses library with POSIX thread support.
Name: ncursest6
Version: 6.4
-Release: 20231223
+Release: 20231230
License: X11
Group: Development/Libraries
Source: ncurses-%{version}-%{release}.tgz
projects / ncurses.git / commitdiff