-- sale, use or other dealings in this Software without prior written --
-- authorization. --
-------------------------------------------------------------------------------
--- $Id: NEWS,v 1.4047 2023/12/09 22:52:42 tom Exp $
+-- $Id: NEWS,v 1.4053 2023/12/17 23:18:40 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.
+20231217
+ + improve formatting/style of manpages (patches by Branden Robinson).
+ + correct an assignment in infocmp "-u" for detecting if a boolean
+ is unset in a base entry and set in a use'd chunk, i.e., if it was
+ cancelled.
+ + modify infocmp "-u" option to not report cancels for strings which
+ were already cancelled in a use'd chunk.
+ + join two lines in infotocap.3x to eliminate a spurious "description"
+ link in installed manpages (report by Sven Joachim).
+ + fix typo in NEWS (report by Sven Joachim).
+
20231209
+ modify infocmp "-u" option to not report cancels in use'd chunks
which are not mentioned in the top-level terminal description.
+ remove xterm+sm+1006 from tmux (Debian #1057688).
+ used "infocmp -u" to help trim redundant capabilities -TD
+ updated man/edit_man.sh to allow for "\%" markers embedded after
- bold font escapes in manpage cross-references (Debian #1057541).
+ bold font escapes in manpage cross-references (Debian #1057651).
+ reduce compiler-warnings in configure checks
20231202
-5:0:10 6.4 20231209
+5:0:10 6.4 20231217
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: dist.mk,v 1.1582 2023/12/09 11:46:25 tom Exp $
+# $Id: dist.mk,v 1.1584 2023/12/17 23:18:40 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 = 20231209
+NCURSES_PATCH = 20231217
# We don't append the patch to the version, since this only applies to releases
VERSION = $(NCURSES_MAJOR).$(NCURSES_MINOR)
@misc/csort < subst.tmp | uniq > subst.sed
@echo '/<\/TITLE>/a\' >> subst.sed
@echo '<link rel="author" href="mailto:bug-ncurses@gnu.org">\' >> subst.sed
- @rm -f subst.tmp
+ #@rm -f subst.tmp
@for f in man/*.[0-9]* ; do \
m=`basename $$f` ;\
T=`$${EGREP-grep -E} '^.TH' $$f|sed -e 's/^.TH //' -e s'/"//g' -e 's/[ ]\+$$//'` ; \
sed -e 's/"curses.3x.html"/"ncurses.3x.html"/g' \
>> doc/html/man/$$g ;\
done
- @rm -f subst.sed
+ #@rm -f subst.sed
#
# Please note that this target can only be properly built if the build of the
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: MKada_config.in,v 1.31 2023/11/25 19:51:50 tom Exp @
+ * @Id: MKada_config.in,v 1.32 2023/12/16 21:42:53 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>adacursesw6\-config 1 2023-11-25 ncurses 6.4 User commands</TITLE>
+<TITLE>adacursesw6\-config 1 2023-12-16 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">adacursesw6\-config 1 2023-11-25 ncurses 6.4 User commands</H1>
+<H1 class="no-header">adacursesw6\-config 1 2023-12-16 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="adacursesw6-config.1.html">adacursesw6-config(1)</A></STRONG> User commands <STRONG><A HREF="adacursesw6-config.1.html">adacursesw6-config(1)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="adacursesw6-config.1.html">adacursesw6-config(1)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="adacursesw6-config.1.html">adacursesw6-config(1)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: captoinfo.1m,v 1.56 2023/12/02 20:51:25 tom Exp @
+ * @Id: captoinfo.1m,v 1.57 2023/12/16 21:34:23 tom Exp @
* TODO: There are about 40 box drawing code points in CCSID 437;
* were there no XENIX capabilities for the mixed single- and double-
* line intersections?
<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>captoinfo 1m 2023-12-02 ncurses 6.4 User commands</TITLE>
+<TITLE>captoinfo 1m 2023-12-16 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">captoinfo 1m 2023-12-02 ncurses 6.4 User commands</H1>
+<H1 class="no-header">captoinfo 1m 2023-12-16 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG> User commands <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG>
check that it has not mistakenly translated an unknown or mistyped
capability name.
- <STRONG>Name</STRONG>
- <STRONG>Obsolete</STRONG> <STRONG>Standard</STRONG> <STRONG>Origin</STRONG> <EM>t</I<STRONG>t</STRONG><EM>e</I<STRONG>e</STRONG><EM>r</I<STRONG>r</STRONG><EM>m</I<STRONG>m</STRONG><EM>i</I<STRONG>i</STRONG><EM>n</I<STRONG>n</STRONG><EM>f</I<STRONG>f</STRONG><EM>o</I<STRONG>o</STRONG> <STRONG>capability</STRONG>
- ---------------------------------------------------------
- <STRONG>BO</STRONG> <STRONG>mr</STRONG> AT&T <STRONG>enter_reverse_mode</STRONG>
- <STRONG>CI</STRONG> <STRONG>vi</STRONG> AT&T <STRONG>cursor_invisible</STRONG>
- <STRONG>CV</STRONG> <STRONG>ve</STRONG> AT&T <STRONG>cursor_normal</STRONG>
- <STRONG>DS</STRONG> <STRONG>mh</STRONG> AT&T <STRONG>enter_dim_mode</STRONG>
- <STRONG>EE</STRONG> <STRONG>me</STRONG> AT&T <STRONG>exit_attribute_mode</STRONG>
- <STRONG>FE</STRONG> <STRONG>LF</STRONG> AT&T <STRONG>label_on</STRONG>
- <STRONG>FL</STRONG> <STRONG>LO</STRONG> AT&T <STRONG>label_off</STRONG>
- <STRONG>XS</STRONG> <STRONG>mk</STRONG> AT&T <STRONG>enter_secure_mode</STRONG>
- <STRONG>EN</STRONG> <STRONG>@7</STRONG> XENIX <STRONG>key_end</STRONG>
- <STRONG>GE</STRONG> <STRONG>ae</STRONG> XENIX <STRONG>exit_alt_charset_mode</STRONG>
- <STRONG>GS</STRONG> <STRONG>as</STRONG> XENIX <STRONG>enter_alt_charset_mode</STRONG>
- <STRONG>HM</STRONG> <STRONG>kh</STRONG> XENIX <STRONG>key_home</STRONG>
- <STRONG>LD</STRONG> <STRONG>kL</STRONG> XENIX <STRONG>key_dl</STRONG>
- <STRONG>PD</STRONG> <STRONG>kN</STRONG> XENIX <STRONG>key_npage</STRONG>
- <STRONG>PN</STRONG> <STRONG>po</STRONG> XENIX <STRONG>prtr_off</STRONG>
- <STRONG>PS</STRONG> <STRONG>pf</STRONG> XENIX <STRONG>prtr_on</STRONG>
- <STRONG>PU</STRONG> <STRONG>kP</STRONG> XENIX <STRONG>key_ppage</STRONG>
- <STRONG>RT</STRONG> <STRONG>@8</STRONG> XENIX <STRONG>kent</STRONG>
- <STRONG>UP</STRONG> <STRONG>ku</STRONG> XENIX <STRONG>kcuu1</STRONG>
- <STRONG>KA</STRONG> <STRONG>k;</STRONG> Tektronix <STRONG>key_f10</STRONG>
- <STRONG>KB</STRONG> <STRONG>F1</STRONG> Tektronix <STRONG>key_f11</STRONG>
- <STRONG>KC</STRONG> <STRONG>F2</STRONG> Tektronix <STRONG>key_f12</STRONG>
- <STRONG>KD</STRONG> <STRONG>F3</STRONG> Tektronix <STRONG>key_f13</STRONG>
- <STRONG>KE</STRONG> <STRONG>F4</STRONG> Tektronix <STRONG>key_f14</STRONG>
- <STRONG>KF</STRONG> <STRONG>F5</STRONG> Tektronix <STRONG>key_f15</STRONG>
- <STRONG>BC</STRONG> <STRONG>Sb</STRONG> Tektronix <STRONG>set_background</STRONG>
-
- <STRONG>FC</STRONG> <STRONG>Sf</STRONG> Tektronix <STRONG>set_foreground</STRONG>
- <STRONG>HS</STRONG> <STRONG>mh</STRONG> IRIX <STRONG>enter_dim_mode</STRONG>
+ <STRONG>Name</STRONG>
+ <STRONG>Obsolete</STRONG> <STRONG>Standard</STRONG> <STRONG>Origin</STRONG> <STRONG><EM>terminfo</EM></STRONG> <STRONG>capability</STRONG>
+ ---------------------------------------------------------
+ <STRONG>BO</STRONG> <STRONG>mr</STRONG> AT&T <STRONG>enter_reverse_mode</STRONG>
+ <STRONG>CI</STRONG> <STRONG>vi</STRONG> AT&T <STRONG>cursor_invisible</STRONG>
+ <STRONG>CV</STRONG> <STRONG>ve</STRONG> AT&T <STRONG>cursor_normal</STRONG>
+ <STRONG>DS</STRONG> <STRONG>mh</STRONG> AT&T <STRONG>enter_dim_mode</STRONG>
+ <STRONG>EE</STRONG> <STRONG>me</STRONG> AT&T <STRONG>exit_attribute_mode</STRONG>
+ <STRONG>FE</STRONG> <STRONG>LF</STRONG> AT&T <STRONG>label_on</STRONG>
+ <STRONG>FL</STRONG> <STRONG>LO</STRONG> AT&T <STRONG>label_off</STRONG>
+ <STRONG>XS</STRONG> <STRONG>mk</STRONG> AT&T <STRONG>enter_secure_mode</STRONG>
+ <STRONG>EN</STRONG> <STRONG>@7</STRONG> XENIX <STRONG>key_end</STRONG>
+ <STRONG>GE</STRONG> <STRONG>ae</STRONG> XENIX <STRONG>exit_alt_charset_mode</STRONG>
+ <STRONG>GS</STRONG> <STRONG>as</STRONG> XENIX <STRONG>enter_alt_charset_mode</STRONG>
+ <STRONG>HM</STRONG> <STRONG>kh</STRONG> XENIX <STRONG>key_home</STRONG>
+ <STRONG>LD</STRONG> <STRONG>kL</STRONG> XENIX <STRONG>key_dl</STRONG>
+ <STRONG>PD</STRONG> <STRONG>kN</STRONG> XENIX <STRONG>key_npage</STRONG>
+ <STRONG>PN</STRONG> <STRONG>po</STRONG> XENIX <STRONG>prtr_off</STRONG>
+ <STRONG>PS</STRONG> <STRONG>pf</STRONG> XENIX <STRONG>prtr_on</STRONG>
+ <STRONG>PU</STRONG> <STRONG>kP</STRONG> XENIX <STRONG>key_ppage</STRONG>
+ <STRONG>RT</STRONG> <STRONG>@8</STRONG> XENIX <STRONG>kent</STRONG>
+ <STRONG>UP</STRONG> <STRONG>ku</STRONG> XENIX <STRONG>kcuu1</STRONG>
+ <STRONG>KA</STRONG> <STRONG>k;</STRONG> Tektronix <STRONG>key_f10</STRONG>
+ <STRONG>KB</STRONG> <STRONG>F1</STRONG> Tektronix <STRONG>key_f11</STRONG>
+ <STRONG>KC</STRONG> <STRONG>F2</STRONG> Tektronix <STRONG>key_f12</STRONG>
+ <STRONG>KD</STRONG> <STRONG>F3</STRONG> Tektronix <STRONG>key_f13</STRONG>
+ <STRONG>KE</STRONG> <STRONG>F4</STRONG> Tektronix <STRONG>key_f14</STRONG>
+ <STRONG>KF</STRONG> <STRONG>F5</STRONG> Tektronix <STRONG>key_f15</STRONG>
+ <STRONG>BC</STRONG> <STRONG>Sb</STRONG> Tektronix <STRONG>set_background</STRONG>
+
+ <STRONG>FC</STRONG> <STRONG>Sf</STRONG> Tektronix <STRONG>set_foreground</STRONG>
+ <STRONG>HS</STRONG> <STRONG>mh</STRONG> IRIX <STRONG>enter_dim_mode</STRONG>
XENIX <EM>termcap</EM> had a set of extension capabilities, corresponding to box
drawing characters of CCSID ("code page") 437, as follows.
- <EM>t</I<STRONG>t</STRONG><EM>e</I<STRONG>e</STRONG><EM>r</I<STRONG>r</STRONG><EM>m</I<STRONG>m</STRONG><EM>c</I<STRONG>c</STRONG><EM>a</I<STRONG>a</STRONG><EM>p</I<STRONG>p</STRONG> <STRONG>Name</STRONG> <STRONG>Graphic</STRONG>
- -----------------------------------------
- <STRONG>G2</STRONG> upper left corner
- <STRONG>G3</STRONG> lower left corner
- <STRONG>G1</STRONG> upper right corner
- <STRONG>G4</STRONG> lower right corner
- <STRONG>GR</STRONG> tee pointing right
- <STRONG>GL</STRONG> tee pointing left
- <STRONG>GU</STRONG> tee pointing up
- <STRONG>GD</STRONG> tee pointing down
- <STRONG>GH</STRONG> horizontal line
- <STRONG>GV</STRONG> vertical line
- <STRONG>GC</STRONG> intersection
- <STRONG>G6</STRONG> double upper left corner
- <STRONG>G7</STRONG> double lower left corner
- <STRONG>G5</STRONG> double upper right corner
- <STRONG>G8</STRONG> double lower right corner
- <STRONG>Gr</STRONG> double tee pointing right
- <STRONG>Gr</STRONG> double tee pointing left
- <STRONG>Gu</STRONG> double tee pointing up
- <STRONG>Gd</STRONG> double tee pointing down
- <STRONG>Gh</STRONG> double horizontal line
- <STRONG>Gv</STRONG> double vertical line
- <STRONG>Gc</STRONG> double intersection
- <STRONG>GG</STRONG> ACS magic cookie count
+ <STRONG><EM>termcap</EM></STRONG> <STRONG>Name</STRONG> <STRONG>Graphic</STRONG>
+ -----------------------------------------
+ <STRONG>G2</STRONG> upper left corner
+ <STRONG>G3</STRONG> lower left corner
+ <STRONG>G1</STRONG> upper right corner
+ <STRONG>G4</STRONG> lower right corner
+ <STRONG>GR</STRONG> tee pointing right
+ <STRONG>GL</STRONG> tee pointing left
+ <STRONG>GU</STRONG> tee pointing up
+ <STRONG>GD</STRONG> tee pointing down
+ <STRONG>GH</STRONG> horizontal line
+ <STRONG>GV</STRONG> vertical line
+ <STRONG>GC</STRONG> intersection
+ <STRONG>G6</STRONG> double upper left corner
+ <STRONG>G7</STRONG> double lower left corner
+ <STRONG>G5</STRONG> double upper right corner
+ <STRONG>G8</STRONG> double lower right corner
+ <STRONG>Gr</STRONG> double tee pointing right
+ <STRONG>Gr</STRONG> double tee pointing left
+ <STRONG>Gu</STRONG> double tee pointing up
+ <STRONG>Gd</STRONG> double tee pointing down
+ <STRONG>Gh</STRONG> double horizontal line
+ <STRONG>Gv</STRONG> double vertical line
+ <STRONG>Gc</STRONG> double intersection
+ <STRONG>GG</STRONG> ACS magic cookie count
<STRONG>captoinfo</STRONG> composes single-line capabilities into an <STRONG>acsc</STRONG> string, and
discards <STRONG>GG</STRONG> and double-line capabilities with a warning diagnostic.
which is incompatible with the SVr4 format. <STRONG>captoinfo</STRONG> translates the
following AIX extensions.
- <STRONG>IBM</STRONG> <STRONG>XSI</STRONG>
- -------------
- ksel kslt
- kbtab kcbt
- font0 s0ds
- font1 s1ds
- font2 s2ds
- font3 s3ds
+ <STRONG>IBM</STRONG> <STRONG>XSI</STRONG>
+ -------------
+ ksel kslt
+ kbtab kcbt
+ font0 s0ds
+ font1 s1ds
+ font2 s2ds
+ font3 s3ds
Additionally, this program translates the AIX <STRONG>box1</STRONG> capability to an
<STRONG>acsc</STRONG> string.
default <EM>termcap</EM> terminal capability database
-</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- The verbose option is not identical to SVr4's. Under SVr4, instead of
- following the <STRONG>-v</STRONG> with a trace level <EM>n</EM>, you repeat it <EM>n</EM> times.
-
-
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- X/Open Curses, Issue 7 (2009) describes <STRONG>tic</STRONG> briefly, but omits this
- program. SVr4 systems provide <STRONG>captoinfo</STRONG> as a separate application from
- <STRONG>tic</STRONG>.
+ X/Open Curses, Issue 7 (2009) describes <STRONG>tic</STRONG> briefly, but omits this
+ program.
+
+ SVr4 systems provide <STRONG>captoinfo</STRONG> as a separate application from <STRONG>tic</STRONG>. Its
+ <STRONG>-v</STRONG> option does not accept a trace level argument <EM>n;</EM> repeat <STRONG>-v</STRONG> <EM>n</EM> times
+ instead.
NetBSD does not provide this application.
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG>
</PRE>
<div class="nav">
<ul>
</ul>
</li>
<li><a href="#h2-FILES">FILES</a></li>
-<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-AUTHORS">AUTHORS</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: clear.1,v 1.45 2023/12/02 20:49:04 tom Exp @
+ * @Id: clear.1,v 1.46 2023/12/16 20:32:22 tom Exp @
* https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/clear.c
* https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/\
* tput/clear.sh
<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>clear 1 2023-12-02 ncurses 6.4 User commands</TITLE>
+<TITLE>clear 1 2023-12-16 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">clear 1 2023-12-02 ncurses 6.4 User commands</H1>
+<H1 class="no-header">clear 1 2023-12-16 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="clear.1.html">clear(1)</A></STRONG> User commands <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_add_wch.3x,v 1.48 2023/11/25 14:20:05 tom Exp @
+ * @Id: curs_add_wch.3x,v 1.49 2023/12/16 21:19:37 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_add_wch 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_add_wch 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_add_wch 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_add_wch 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
WACS_URCORNER 0x2510 + k upper right-hand corner
WACS_VLINE 0x2502 | x vertical line
- The wide-character configuration of ncurses also defines symbols for
+ The wide-character configuration of <EM>ncurses</EM> also defines symbols for
thick lines (<STRONG>acsc</STRONG> "J" to "V"):
<STRONG>ACS</STRONG> <STRONG>Unicode</STRONG> <STRONG>ASCII</STRONG> <STRONG>acsc</STRONG> <STRONG>Glyph</STRONG>
WACS_D_VLINE 0x2551 | Y double vertical line
Unicode's descriptions for these characters differs slightly from
- ncurses, by introducing the term "light" (along with less important
+ <EM>ncurses</EM>, by introducing the term "light" (along with less important
details). Here are its descriptions for the normal, thick, and double
horizontal lines:
<STRONG>o</STRONG> If <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not enabled, writing a character at the lower
right margin succeeds. However, an error is returned because it is
- not possible to wrap to a new line
+ not possible to wrap to a new line.
<STRONG>o</STRONG> If an error is detected when converting a multibyte character to a
sequence of bytes, or if it is not possible to add all of the
Existing implementations of Unix curses (AIX, HP-UX, Solaris) use only
the <STRONG>acsc</STRONG> character-mapping to provide this feature. As a result, those
implementations can only use single-byte line-drawing characters.
- Ncurses 5.3 (2002) provided a table of Unicode values to solve these
+ <EM>ncurses</EM> 5.3 (2002) provided a table of Unicode values to solve these
problems. NetBSD curses incorporated that table in 2010.
In this implementation, the Unicode values are used instead of the
terminal description's <STRONG>acsc</STRONG> mapping as discussed in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> for the
- environment variable <STRONG>NCURSES_NO_UTF8_ACS</STRONG>. In contrast, for the same
- cases, the line-drawing characters described in <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> will use
- only the ASCII default values.
+ environment variable <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM>. In contrast, for the same
+ cases, the line-drawing characters described in <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG> will use only
+ the ASCII default values.
Having Unicode available does not solve all of the problems with line-
drawing for curses:
<STRONG>o</STRONG> may hold one non-spacing character.
- In the latter case, ncurses adds the non-spacing character to the
+ In the latter case, <EM>ncurses</EM> adds the non-spacing character to the
active (base) spacing character.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_addch.3x,v 1.74 2023/11/25 14:20:05 tom Exp @
+ * @Id: curs_addch.3x,v 1.75 2023/12/16 21:19:37 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_addch 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_addch 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_addch 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_addch 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
<STRONG>o</STRONG> If <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not enabled, writing a character at the lower
right margin succeeds. However, an error is returned because it is
- not possible to wrap to a new line
+ not possible to wrap to a new line.
If <EM>ch</EM> is a tab, newline, carriage return or backspace, the cursor is
moved appropriately within the window:
<STRONG>o</STRONG> If <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not enabled, writing a character at the lower
right margin succeeds. However, an error is returned because it is
- not possible to wrap to a new line
+ not possible to wrap to a new line.
<STRONG>o</STRONG> If an error is detected when converting a multibyte character to a
sequence of bytes, or if it is not possible to add all of the
The <EM>displayed</EM> values for the <STRONG>ACS_</STRONG> and <STRONG>WACS_</STRONG> constants depend on
- <STRONG>o</STRONG> the library configuration, i.e., <STRONG>ncurses</STRONG> versus <STRONG>ncursesw</STRONG>, where the
+ <STRONG>o</STRONG> the library configuration, i.e., <EM>ncurses</EM> versus <EM>ncursesw</EM>, where the
latter is capable of displaying Unicode while the former is not,
and
character information which is packed in a <STRONG>chtype</STRONG> to pass to <STRONG>waddch</STRONG>.
In this implementation, <STRONG>chtype</STRONG> holds an eight-bit character. But
- ncurses allows multibyte characters to be passed in a succession of
+ <EM>ncurses</EM> allows multibyte characters to be passed in a succession of
calls to <STRONG>waddch</STRONG>. The other implementations do not do this; a call to
<STRONG>waddch</STRONG> passes exactly one character which may be rendered as one or
more cells on the screen depending on whether it is printable.
- Depending on the locale settings, ncurses will inspect the byte passed
+ Depending on the locale settings, <EM>ncurses</EM> will inspect the byte passed
in each call to <STRONG>waddch</STRONG>, and check if the latest call will continue a
- multibyte sequence. When a character is <EM>complete</EM>, ncurses displays the
+ multibyte sequence. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the
character and moves to the next position in the screen.
If the calling application interrupts the succession of bytes in a
multibyte character by moving the current location (e.g., using <STRONG>wmove</STRONG>),
- ncurses discards the partially built character, starting over again.
+ <EM>ncurses</EM> discards the partially built character, starting over again.
For portability to other implementations, do not rely upon this
behavior:
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_attr.3x,v 1.91 2023/12/02 21:05:24 tom Exp @
+ * @Id: curs_attr.3x,v 1.92 2023/12/16 21:07:24 tom Exp @
* ---------------------------------------------------------------------------
* ---------------------------------------------------------------------------
* ---------------------------------------------------------------------------
<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_attr 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_attr 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_attr 3x 2023-12-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_attr 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
attr_set(A_BOLD, <EM>pair</EM>, NULL);
However, if the value does not fit, then the <STRONG>COLOR_PAIR</STRONG> macro uses only
- the bits that fit. For example, because in ncurses <STRONG>A_COLOR</STRONG> has eight
+ the bits that fit. For example, because in <EM>ncurses</EM> <STRONG>A_COLOR</STRONG> has eight
(8) bits, then <STRONG>COLOR_PAIR(</STRONG><EM>259</EM><STRONG>)</STRONG> is 4 (i.e., 259 is 4 more than the limit
255).
than <STRONG>attr_t</STRONG>.
There is no corresponding <STRONG>attrget</STRONG> function as such in X/Open Curses,
- although
ncurses provides <STRONG>getattrs</STRONG> (see <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>).
+ although
<EM>ncurses</EM> provides <STRONG>getattrs</STRONG> (see <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>).
</PRE><H3><a name="h3-Change-character-rendition">Change character rendition</a></H3><PRE>
function generalizes this to any window; the <STRONG>mvwchgat</STRONG> function does a
cursor move before acting.
- In these functions, the color <EM>pair</EM> argument is a color-pair index (as
+ In these functions, the color <EM>pair</EM> argument is a color pair index (as
in the first argument of <STRONG>init_pair</STRONG>, see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>).
outside the range 0..COLOR_PAIRS-1.
<STRONG>o</STRONG> does not return an error if either of the parameters of <STRONG>wattr_get</STRONG>
- used for retrieving attribute or color-pair values is <STRONG>NULL</STRONG>.
+ used for retrieving attribute or color pair values is <STRONG>NULL</STRONG>.
Functions with a "mv" prefix first perform a cursor movement using
<STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
Color pair values can only be OR'd with attributes if the pair number
is less than 256. The alternate functions such as <STRONG>color_set</STRONG> can pass a
- color pair value directly. However, ncurses ABI 4 and 5 simply OR this
- value within the alternate functions. You must use ncurses ABI 6 to
+ color pair value directly. However, <EM>ncurses</EM> ABI 4 and 5 simply OR this
+ value within the alternate functions. You must use <EM>ncurses</EM> ABI 6 to
support more than 256 color pairs.
X/Open Curses still (after more than twenty years) documents as
reserved for future use, saying that it should be <STRONG>NULL</STRONG>. This
implementation uses that parameter in ABI 6 for the functions which
- have a color-pair parameter to support <EM>extended</EM> <EM>color</EM> <EM>pairs</EM>:
+ have a color pair parameter to support <EM>extended</EM> <EM>color</EM> <EM>pairs</EM>:
<STRONG>o</STRONG> For functions which modify the color, e.g., <STRONG>wattr_set</STRONG> and <STRONG>wattr_on</STRONG>,
if <EM>opts</EM> is set it is treated as a pointer to <STRONG>int</STRONG>, and used to set
the same because it simplifies copying information between <STRONG>chtype</STRONG>
and <STRONG>cchar_t</STRONG> variables.
- <STRONG>o</STRONG> Because ncurses's <STRONG>attr_t</STRONG> can hold a color pair (in the <STRONG>A_COLOR</STRONG>
+ <STRONG>o</STRONG> Because <EM>ncurses</EM>'s <STRONG>attr_t</STRONG> can hold a color pair (in the <STRONG>A_COLOR</STRONG>
field), a call to <STRONG>wattr_on</STRONG>, <STRONG>wattr_off</STRONG>, or <STRONG>wattr_set</STRONG> may alter the
window's color. If the color pair information in the attribute
parameter is zero, no change is made to the window's color.
Regarding OSF/1 (and Tru64),
- <STRONG>o</STRONG> These used 64-bit hardware. Like ncurses, the OSF/1 curses
+ <STRONG>o</STRONG> These used 64-bit hardware. Like <EM>ncurses</EM>, the OSF/1 curses
interface is not customized for 32-bit and 64-bit versions.
<STRONG>o</STRONG> Unlike other systems which evolved from AT&T code, OSF/1
modification to make the library 8-bit clean for <STRONG>nvi(1)</STRONG>. He moved
<EM>standout</EM> attribute to a structure member.
- The resulting 4.4BSD curses was replaced by ncurses over the next
+ The resulting 4.4BSD curses was replaced by <EM>ncurses</EM> over the next
ten years.
<STRONG>o</STRONG> U/Win is rarely used now.
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_bkgd.3x,v 1.51 2023/12/02 21:02:44 tom Exp @
+ * @Id: curs_bkgd.3x,v 1.54 2023/12/17 23:31:28 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_bkgd 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_bkgd 3x 2023-12-17 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_bkgd 3x 2023-12-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_bkgd 3x 2023-12-17 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
- <STRONG>void</STRONG> <STRONG>bkgdset(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
- <STRONG>void</STRONG> <STRONG>wbkgdset(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
-
<STRONG>int</STRONG> <STRONG>bkgd(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>wbkgd(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
+ <STRONG>void</STRONG> <STRONG>bkgdset(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
+ <STRONG>void</STRONG> <STRONG>wbkgdset(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
+
<STRONG>chtype</STRONG> <STRONG>getbkgd(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+ The <EM>background</EM> of a <EM>curses</EM> window (in the library's non-"wide"
+ configuration) is a <EM>chtype</EM> combining a set of attributes (see
+ <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>) with a character called the <EM>blank</EM> <EM>character.</EM>
-</PRE><H3><a name="h3-bkgdset">bkgdset</a></H3><PRE>
- The <STRONG>bkgdset</STRONG> and <STRONG>wbkgdset</STRONG> routines set the <EM>background</EM> for a window. A
- window's background is a <STRONG>chtype</STRONG> consisting of any combination of
- attributes (i.e., rendition) and a character:
-
- <STRONG>o</STRONG> The attribute part of the background is combined (OR'ed) with all
- non-blank characters that are written into the window with <STRONG>waddch</STRONG>.
-
- <STRONG>o</STRONG> Both the character and attribute parts of the background are
- combined with blank characters that are written into the window.
-
- The background becomes a property of each character and moves with the
- character through any scrolling and insert/delete line/character
- operations.
-
- To the extent possible on a particular terminal, the attribute part of
- the background is displayed as the graphic rendition of the character
- put on the screen.
+ The blank character is a spacing character that populates a window's
+ character cells when their contents are erased without replacement.
+ The background's attributes are combined with all non-blank characters
+ written to the window, as with the <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> and <STRONG><A HREF="curs_insch.3x.html">winsch(3x)</A></STRONG> families
+ of functions.
+ The blank character and attributes of the background combine with
+ characters written to the window as described below. The background
+ becomes a property of the character and moves with it through any
+ scrolling and insert/delete line/character operations.
-</PRE><H3><a name="h3-bkgd">bkgd</a></H3><PRE>
- The <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> functions set the background property of the current
- or specified window and then apply this setting to every character
- position in that window. According to X/Open Curses, it should do
- this:
+ To the extent possible on a given terminal, the attribute part of the
+ background is displayed as the graphic rendition of the character put
+ on the screen.
- <STRONG>o</STRONG> The rendition of every character on the screen is changed to the
- new background rendition.
- <STRONG>o</STRONG> Wherever the former background character appears, it is changed to
- the new background character.
+</PRE><H3><a name="h3-bkgd_-wbkgd">bkgd, wbkgd</a></H3><PRE>
+ <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> set the background property of <STRONG>stdscr</STRONG> or the specified
+ window and then apply this setting to every character cell in that
+ window.
- Neither X/Open Curses nor the SVr4 manual pages give details about the
- way the rendition of characters on the screen is updated when <STRONG>bkgd</STRONG> or
- <STRONG>wbkgd</STRONG> is used to change the background character.
+ <STRONG>o</STRONG> The rendition of every character in the window changes to the new
+ background rendition.
- <EM>ncurses</EM>, like SVr4 <EM>curses</EM>, does not store the background and window
- attribute contributions to each cell separately. It updates the
- rendition by comparing the character, non-color attributes and colors
- contained in the background. For each cell in the window, whether or
- not it is blank:
-
- <STRONG>o</STRONG> The library first compares the <EM>character</EM>, and if it matches the
- current character part of the background, it replaces that with the
+ <STRONG>o</STRONG> Wherever the former background character appears, it changes to the
new background character.
- When <STRONG>bkgdset</STRONG> is used to set the background character, that does not
- update each cell in the window. A subsequent call to <STRONG>bkgd</STRONG> will
- only modify the <EM>character</EM> in cells which match the current
- background character.
+ <EM>ncurses</EM> updates the rendition of each character cell by comparing the
+ character, non-color attributes, and colors. The library applies to
+ following procedure to each cell in the window, whether or not it is
+ blank.
+
+ <STRONG>o</STRONG> <EM>ncurses</EM> first compares the cell's character to the previously
+ specified blank character; if they match, <EM>ncurses</EM> writes the new
+ blank character to the cell.
- <STRONG>o</STRONG> The library then checks if the cell uses color, i.e., its color
- pair value is nonzero. If not, it simply replaces the attributes
- and color pair in the cell with those from the new background
+ <STRONG>o</STRONG> <EM>ncurses</EM> then checks if the cell uses color, that is, its color pair
+ value is nonzero. If not, it simply replaces the attributes and
+ color pair in the cell with those from the new background
character.
- <STRONG>o</STRONG> If the cell uses color, and that matches the color in the current
- background, the library removes attributes which may have come from
- the current background and adds attributes from the new background.
- It finishes by setting the cell to use the color from the new
- background.
+ <STRONG>o</STRONG> If the cell uses color, and its background color matches that of
+ the current window background, <EM>ncurses</EM> removes attributes that may
+ have come from the current background and adds those from the new
+ background. It finishes by setting the cell's background to use
+ the new window background color.
- <STRONG>o</STRONG> If the cell uses color, and that does not match the color in the
- current background, the library updates only the non-color
- attributes, first removing those which may have come from the
- current background, and then adding attributes from the new
+ <STRONG>o</STRONG> If the cell uses color, and its background color does not match
+ that of the current window background, <EM>ncurses</EM> updates only the
+ non-color attributes, first removing those that may have come from
+ the current background, and then adding attributes from the new
background.
- If the background's character value is zero (0), a space is assumed.
+ <EM>ncurses</EM> treats a background character value of zero (0) as a blank
+ character.
+
+ If the terminal does not support color, or if color has not been
+ initialized with <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG>, <EM>ncurses</EM> ignores the new background
+ character's color attribute.
+
- If the terminal does not support color, or if color has not been
- started with <STRONG>start_color</STRONG>, the new background character's color
- attribute will be ignored.
+</PRE><H3><a name="h3-bkgdset_-wbkgdset">bkgdset, wbkgdset</a></H3><PRE>
+ <STRONG>bkgdset</STRONG> and <STRONG>wbkgdset</STRONG> manipulate the background of the applicable
+ window, without updating the character cells as <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> do; only
+ future writes reflect the updated background.
</PRE><H3><a name="h3-getbkgd">getbkgd</a></H3><PRE>
- The <STRONG>getbkgd</STRONG> function returns the given window's current background
- character/attribute pair.
+ <STRONG>getbkgd</STRONG> obtains the given window's background character and attribute
+ combination.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Functions returning an <EM>int</EM> return <STRONG>OK</STRONG> on success. <STRONG>bkgd</STRONG> returns <STRONG>ERR</STRONG> if
- the library has not been initialized. <STRONG>wbkgd</STRONG> and <STRONG>getbkgd</STRONG> return <STRONG>ERR</STRONG> if
- the <EM>WINDOW</EM> pointer argument is null.
+ Functions returning an <EM>int</EM> return <STRONG>OK</STRONG> on success. <STRONG>bkgd</STRONG> returns <STRONG>ERR</STRONG> if
+ the library has not been initialized. <STRONG>wbkgd</STRONG> and <STRONG>getbkgd</STRONG> return <STRONG>ERR</STRONG> if
+ a <EM>WINDOW</EM> pointer argument is null.
- In contrast, the SVr4.0 manual says <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> may return <STRONG>OK</STRONG> "or a
- non-negative integer if <STRONG>immedok</STRONG> is set", which refers to the return
- value from <STRONG>wrefresh</STRONG> (used to implement the immediate repainting). SVr4
- <EM>curses</EM> <STRONG>wrefresh</STRONG> returns the number of characters written to the screen
- during the refresh. <EM>ncurses</EM> does not do that.
+ <STRONG>bkgdset</STRONG> and <STRONG>wbkgdset</STRONG> do not return a value.
+
+ <STRONG>getbkgd</STRONG> returns a window's background character and attribute
+ combination.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
Unusually, there is no <STRONG>wgetbkgd</STRONG> function; <STRONG>getbkgd</STRONG> behaves as one would
expect <STRONG>wgetbkgd</STRONG> to, accepting a <EM>WINDOW</EM> pointer argument.
- Note that <STRONG>bkgdset</STRONG> and <STRONG>bkgd</STRONG> may be macros.
+ <STRONG>bkgd</STRONG> and <STRONG>bkgdset</STRONG> may be available as macros.
X/Open Curses mentions that the character part of the background must
be a single-byte value. <EM>ncurses</EM>, like SVr4 <EM>curses</EM>, checks to ensure
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These functions are described in the XSI Curses standard, Issue 4. It
- specifies that <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> return <STRONG>ERR</STRONG> on failure, but gives no
- failure conditions.
+ X/Open Curses, Issue 4, describes these functions. It specifies that
+ <STRONG>bkgd</STRONG>, <STRONG>wbkgd</STRONG>, and <STRONG>getbkgd</STRONG> return <STRONG>ERR</STRONG> on failure (in the case of the
+ last, this value is cast to <EM>chtype</EM>), but describes no failure
+ conditions.
+
+ The SVr4.0 manual says that <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> may return <STRONG>OK</STRONG> "or a non-
+ negative integer if <STRONG>immedok</STRONG> is set", which refers to the return value
+ from <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, used to implement the immediate repainting. SVr4
+ <EM>curses</EM>'s <STRONG>wrefresh</STRONG> returns the number of characters written to the
+ screen during the refresh. <EM>ncurses</EM> does not do that.
+
+ Neither X/Open Curses nor the SVr4 manual pages detail how the
+ rendition of characters on the screen updates when <STRONG>bkgd</STRONG> or <STRONG>wbkgd</STRONG>
+ changes the background character. <EM>ncurses,</EM> like SVr4 <EM>curses,</EM> does not
+ (in its non-"wide" configuration) store the background and window
+ attribute contributions to each character cell separately.
</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_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
+ <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> describes the corresponding functions in the "wide"
+ configuration of <EM>ncurses.</EM>
+
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>
+ncurses 6.4 2023-12-
17 <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
-<li><a href="#h3-bkgdset">bkgdset</a></li>
-<li><a href="#h3-bkgd">bkgd</a></li>
+<li><a href="#h3-bkgd_-wbkgd">bkgd, wbkgd</a></li>
+<li><a href="#h3-bkgdset_-wbkgdset">bkgdset, wbkgdset</a></li>
<li><a href="#h3-getbkgd">getbkgd</a></li>
</ul>
</li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_bkgrnd.3x,v 1.34 2023/12/02 21:30:00 tom Exp @
+ * @Id: curs_bkgrnd.3x,v 1.35 2023/12/16 23:00:21 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_bkgrnd 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_bkgrnd 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_bkgrnd 3x 2023-12-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_bkgrnd 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+ The <EM>background</EM> of a <EM>curses</EM> window (in the library's "wide"
+ configuration) is a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> combining a set of attributes (see
+ <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>) with a complex character called the <EM>blank</EM> <EM>character.</EM>
-</PRE><H3><a name="h3-bkgrndset">bkgrndset</a></H3><PRE>
- The <STRONG>bkgrndset</STRONG> and <STRONG>wbkgrndset</STRONG> routines manipulate the background of the
- named window. The window background is a <STRONG>cchar_t</STRONG> consisting of any
- combination of attributes (i.e., rendition) and a complex character.
+ The blank character is a spacing character that populates a window's
+ character cells when their contents are erased without replacement.
+ The background's attributes are combined with all non-blank characters
+ written to the window, as with the <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> and <STRONG><A HREF="curs_ins_wch.3x.html">wins_wch(3x)</A></STRONG>
+ families of functions.
- <STRONG>o</STRONG> The attribute part of the background is combined (OR'ed) with all
- non-blank characters that are written into the window with <STRONG>waddch</STRONG>.
+ The blank character and attributes of the background combine with
+ characters written to the window as described below. The background
+ becomes a property of the character and moves with it through any
+ scrolling and insert/delete line/character operations.
- <STRONG>o</STRONG> Both the character and attribute parts of the background are
- combined with the blank characters.
+ To the extent possible on a given terminal, the attribute part of the
+ background is displayed as the graphic rendition of the character put
+ on the screen.
- The background becomes a property of the character and moves with the
- character through any scrolling and insert/delete line/character
- operations.
- To the extent possible on a particular terminal, the attribute part of
- the background is displayed as the graphic rendition of the character
- put on the screen.
+</PRE><H3><a name="h3-bkgrnd_-wbkgrnd">bkgrnd, wbkgrnd</a></H3><PRE>
+ <STRONG>bkgrnd</STRONG> and <STRONG>wbkgrnd</STRONG> set the background property of <STRONG>stdscr</STRONG> or the
+ specified window and then apply this setting to every character cell in
+ that window.
+ <STRONG>o</STRONG> The rendition of every character in the window changes to the new
+ background rendition.
-</PRE><H3><a name="h3-bkgrnd">bkgrnd</a></H3><PRE>
- The <STRONG>bkgrnd</STRONG> and <STRONG>wbkgrnd</STRONG> functions set the background property of the
- current or specified window and then apply this setting to every
- character position in that window:
+ <STRONG>o</STRONG> Wherever the former background character appears, it changes to the
+ new background character.
- <STRONG>o</STRONG> The rendition of every character on the screen is changed to the
- new background rendition.
+ <EM>ncurses</EM> updates the rendition of each character cell by comparing the
+ character, non-color attributes, and colors. The library applies to
+ following procedure to each cell in the window, whether or not it is
+ blank.
- <STRONG>o</STRONG> Wherever the former background character appears, it is changed to
- the new background character.
+ <STRONG>o</STRONG> <EM>ncurses</EM> first compares the cell's character to the previously
+ specified blank character; if they match, <EM>ncurses</EM> writes the new
+ blank character to the cell.
+ <STRONG>o</STRONG> <EM>ncurses</EM> then checks if the cell uses color, that is, its color pair
+ value is nonzero. If not, it simply replaces the attributes and
+ color pair in the cell with those from the new background
+ character.
-</PRE><H3><a name="h3-getbkgrnd">getbkgrnd</a></H3><PRE>
- The <STRONG>getbkgrnd</STRONG> and <STRONG>wgetbkgrnd</STRONG> functions obtain the given or specified
- window's current background character and attribute pair and store it
- via the <EM>wch</EM> pointer.
+ <STRONG>o</STRONG> If the cell uses color, and its background color matches that of
+ the current window background, <EM>ncurses</EM> removes attributes that may
+ have come from the current background and adds those from the new
+ background. It finishes by setting the cell's background to use
+ the new window background color.
+
+ <STRONG>o</STRONG> If the cell uses color, and its background color does not match
+ that of the current window background, <EM>ncurses</EM> updates only the
+ non-color attributes, first removing those that may have come from
+ the current background, and then adding attributes from the new
+ background.
+
+ <EM>ncurses</EM> treats a background character value of zero (0) as a blank
+ character.
+
+ If the terminal does not support color, or if color has not been
+ initialized with <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG>, <EM>ncurses</EM> ignores the new background
+ character's color attribute.
+
+
+</PRE><H3><a name="h3-bkgrndset_-wbkgrndset">bkgrndset, wbkgrndset</a></H3><PRE>
+ <STRONG>bkgrndset</STRONG> and <STRONG>wbkgrndset</STRONG> manipulate the background of the applicable
+ window, without updating the character cells as <STRONG>bkgrnd</STRONG> and <STRONG>wbkgrnd</STRONG> do;
+ only future writes reflect the updated background.
+
+
+</PRE><H3><a name="h3-getbkgrnd_-wgetbkgrnd">getbkgrnd, wgetbkgrnd</a></H3><PRE>
+ The <STRONG>getbkgrnd</STRONG> and <STRONG>wgetbkgrnd</STRONG> functions obtain the background character
+ and attribute pair of <STRONG>stdscr</STRONG> or the specified window and store it via
+ the <EM>wch</EM> pointer.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- The <STRONG>bkgrndset</STRONG> and <STRONG>wbkgrndset</STRONG> routines do not return a value.
+ <STRONG>bkgrndset</STRONG> and <STRONG>wbkgrndset</STRONG> do not return a value.
- Upon successful completion, the other functions return <STRONG>OK</STRONG>. Otherwise,
- they return <STRONG>ERR</STRONG>:
+ The other functions return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success. In
+ <EM>ncurses,</EM> failure occurs if
- <STRONG>o</STRONG> A null <EM>WINDOW</EM> pointer is treated as an error.
+ <STRONG>o</STRONG> a <EM>WINDOW</EM> pointer <EM>win</EM> is null, or
- <STRONG>o</STRONG> A null <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> pointer is treated as an error.
+ <STRONG>o</STRONG> a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> pointer <EM>wch</EM> is null.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
<STRONG>bkgrnd</STRONG>, <STRONG>bkgrndset</STRONG>, and <STRONG>getbkgrnd</STRONG> may be available as macros.
- X/Open Curses does not provide details on how the rendition is changed.
- This implementation follows the approach used in SVr4 curses, which is
- explained in the manual page for <STRONG>wbkgd</STRONG>.
+ Unlike their counterparts in the non-"wide" configuration of <EM>ncurses,</EM>
+ <STRONG>getbkgrnd</STRONG> and <STRONG>wgetbkgrnd</STRONG> supply the background character and attribute
+ in a modifiable <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> parameter, not as the return value.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These functions are described in the XSI Curses standard, Issue 4.
+ X/Open Curses, Issue 4, describes these functions. It specifies no
+ error conditions for them.
+
+ X/Open Curses does not provide details of how the rendition is updated.
+ This implementation follows the approach used in SVr4 <EM>curses.</EM>
</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_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>
+ <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> describes the corresponding functions in the non-"wide"
+ configuration of <EM>ncurses.</EM>
+
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
-<li><a href="#h3-bkgrndset">bkgrndset</a></li>
-<li><a href="#h3-bkgrnd">bkgrnd</a></li>
-<li><a href="#h3-getbkgrnd">getbkgrnd</a></li>
+<li><a href="#h3-bkgrnd_-wbkgrnd">bkgrnd, wbkgrnd</a></li>
+<li><a href="#h3-bkgrndset_-wbkgrndset">bkgrndset, wbkgrndset</a></li>
+<li><a href="#h3-getbkgrnd_-wgetbkgrnd">getbkgrnd, wgetbkgrnd</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_border.3x,v 1.43 2023/11/25 11:31:27 tom Exp @
+ * @Id: curs_border.3x,v 1.44 2023/12/16 21:09:11 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_border 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_border 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_border 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_border 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_clear.3x,v 1.40 2023/11/25 11:31:27 tom Exp @
+ * @Id: curs_clear.3x,v 1.41 2023/12/16 21:09:11 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_clear 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_clear 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_clear 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_clear 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
These functions are described in the XSI Curses standard, Issue 4.
- The SVr4.0 manual says that these functions could return "a non-
- negative integer if <STRONG><A HREF="curs_outopts.3x.html">immedok(3x)</A></STRONG> is set", referring to the return-value
- of <STRONG>wrefresh</STRONG>. In that implementation, <STRONG>wrefresh</STRONG> would return a count of
- the number of characters written to the terminal.
+ The SVr4.0 manual says that these functions could return "or a non-
+ negative integer if <STRONG>immedok</STRONG> is set", referring to the return-value of
+ <STRONG>wrefresh</STRONG>. In that implementation, <STRONG>wrefresh</STRONG> would return a count of the
+ number of characters written to the terminal.
Some historic curses implementations had, as an undocumented feature,
the ability to do the equivalent of <STRONG>clearok(...,</STRONG> <STRONG>1)</STRONG> by saying
- <STRONG>touchwin(stdscr)</STRONG> or <STRONG>clear(stdscr)</STRONG>. This will not work under ncurses.
+ <STRONG>touchwin(stdscr)</STRONG> or <STRONG>clear(stdscr)</STRONG>. This will not work under <EM>ncurses</EM>.
This implementation, and others such as Solaris, sets the current
position to 0,0 after erasing via <STRONG>werase</STRONG> and <STRONG>wclear</STRONG>. That fact is not
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_color.3x,v 1.92 2023/11/25 17:36:51 tom Exp @
+ * @Id: curs_color.3x,v 1.93 2023/12/16 21:07:24 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-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_color 3x 2023-12-16 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-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_color 3x 2023-12-16 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>start_color</STRONG>, <STRONG>has_colors</STRONG>, <STRONG>can_change_color</STRONG>, <STRONG>init_pair</STRONG>, <STRONG>init_color</STRONG>,
<STRONG>init_extended_pair</STRONG>, <STRONG>init_extended_color</STRONG>, <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>,
<STRONG>extended_color_content</STRONG>, <STRONG>extended_pair_content</STRONG>, <STRONG>reset_color_pairs</STRONG>,
- <STRONG>COLOR_PAIR</STRONG>, <STRONG>PAIR_NUMBER</STRONG> - manipulate terminal colors with <EM>curses</EM>
+ <STRONG>COLOR_PAIR</STRONG>, <STRONG>PAIR_NUMBER</STRONG>, <STRONG>COLORS</STRONG>, <STRONG>COLOR_PAIRS</STRONG>, <STRONG>COLOR_BLACK</STRONG>, <STRONG>COLOR_RED</STRONG>,
+ <STRONG>COLOR_GREEN</STRONG>, <STRONG>COLOR_YELLOW</STRONG>, <STRONG>COLOR_BLUE</STRONG>, <STRONG>COLOR_MAGENTA</STRONG>, <STRONG>COLOR_CYAN</STRONG>,
+ <STRONG>COLOR_WHITE</STRONG> - manipulate terminal colors with <EM>curses</EM>
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>void</STRONG> <STRONG>reset_color_pairs(void);</STRONG>
<STRONG>int</STRONG> <STRONG>COLOR_PAIR(int</STRONG> <EM>n</EM><STRONG>);</STRONG>
- <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM><STRONG>);</STRONG>
+ <STRONG>PAIR_NUMBER(int</STRONG> <EM>attr</EM><STRONG>);</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
</PRE><H3><a name="h3-Overview">Overview</a></H3><PRE>
<EM>curses</EM> supports color attributes on terminals with that capability. To
use these routines <STRONG>start_color</STRONG> must be called, usually right after
- <STRONG>initscr</STRONG>. Colors are always used in pairs (referred to as color-pairs).
- A color-pair consists of a foreground color (for characters) and a
+ <STRONG>initscr</STRONG>. Colors are always used in pairs (referred to as color pairs).
+ A color pair consists of a foreground color (for characters) and a
background color (for the blank field on which the characters are
- displayed). A programmer initializes a color-pair with the routine
+ displayed). A programmer initializes a color pair with the routine
<STRONG>init_pair</STRONG>. After it has been initialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>) can be used to
convert the pair to a video attribute.
the programmer can change the colors. The routine <STRONG>color_content</STRONG> allows
a programmer to extract the amounts of red, green, and blue components
in an initialized color. The routine <STRONG>pair_content</STRONG> allows a programmer
- to find out how a given color-pair is currently defined.
+ to find out how a given color pair is currently defined.
</PRE><H3><a name="h3-Color-Rendering">Color Rendering</a></H3><PRE>
routine right after <STRONG>initscr</STRONG>. <STRONG>start_color</STRONG> does this:
<STRONG>o</STRONG> It initializes two global variables, <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG>
- (respectively defining the maximum number of colors and color-pairs
+ (respectively defining the maximum number of colors and color pairs
the terminal can support).
<STRONG>o</STRONG> It initializes the special color pair <STRONG>0</STRONG> to the default foreground
</PRE><H3><a name="h3-init_pair">init_pair</a></H3><PRE>
- The <STRONG>init_pair</STRONG> routine changes the definition of a color-pair. It takes
- three arguments: the number of the color-pair to be changed, the
+ The <STRONG>init_pair</STRONG> routine changes the definition of a color pair. It takes
+ three arguments: the number of the color pair to be changed, the
foreground color number, and the background color number. For portable
applications:
<STRONG>o</STRONG> The second and third arguments must be valid color values.
- If the color-pair was previously initialized, the screen is refreshed
- and all occurrences of that color-pair are changed to the new
+ If the color pair was previously initialized, the screen is refreshed
+ and all occurrences of that color pair are changed to the new
definition.
- As an extension, ncurses allows you to set color pair <STRONG>0</STRONG> via the
+ As an extension, <EM>ncurses</EM> allows you to set color pair <STRONG>0</STRONG> via the
<STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> routine, or to specify the use of default
colors (color number <STRONG>-1</STRONG>) if you first invoke the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>
routine.
</PRE><H3><a name="h3-init_extended_pair">init_extended_pair</a></H3><PRE>
Because <STRONG>init_pair</STRONG> uses signed <STRONG>short</STRONG>s for its parameters, that limits
- color-pairs and color-values to 32767 on modern hardware. The
- extension <STRONG>init_extended_pair</STRONG> uses <STRONG>int</STRONG>s for the color-pair and color-
+ color pairs and color-values to 32767 on modern hardware. The
+ extension <STRONG>init_extended_pair</STRONG> uses <STRONG>int</STRONG>s for the color pair and color-
value, allowing a larger number of colors to be supported.
</PRE><H3><a name="h3-pair_content">pair_content</a></H3><PRE>
The <STRONG>pair_content</STRONG> routine allows programmers to find out what colors a
- given color-pair consists of. It requires three arguments: the color-
+ given color pair consists of. It requires three arguments: the color
pair number, and two addresses of <STRONG>short</STRONG>s for storing the foreground and
the background color numbers.
</PRE><H3><a name="h3-extended_pair_content">extended_pair_content</a></H3><PRE>
Because <STRONG>pair_content</STRONG> uses signed <STRONG>short</STRONG>s for its parameters, that limits
- color-pair and color-values to 32767 on modern hardware. The extension
+ color pair and color-values to 32767 on modern hardware. The extension
<STRONG>extended_pair_content</STRONG> uses <STRONG>int</STRONG>s for the color pair and for returning
the foreground and background colors, allowing a larger number of
colors to be supported.
</PRE><H3><a name="h3-reset_color_pairs">reset_color_pairs</a></H3><PRE>
- The extension <STRONG>reset_color_pairs</STRONG> tells ncurses to discard all of the
- color-pair information which was set with <STRONG>init_pair</STRONG>. It also touches
+ The extension <STRONG>reset_color_pairs</STRONG> tells <EM>ncurses</EM> to discard all of the
+ color pair information which was set with <STRONG>init_pair</STRONG>. It also touches
the current- and standard-screens, allowing an application to switch
color palettes rapidly.
-</PRE><H3><a name="h3-PAIR_NUMBER">PAIR_NUMBER</a></H3><PRE>
- <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM>) extracts the color value from its <EM>attrs</EM> parameter
- and returns it as a color pair number.
+</PRE><H3><a name="h3-COLOR_PAIR">COLOR_PAIR</a></H3><PRE>
+ <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an attribute. Attributes
+ can hold color pairs in the range 0 to 255. If you need a color pair
+ larger than that, you must use functions such as <STRONG>attr_set</STRONG> (which pass
+ the color pair as a separate parameter) rather than the legacy
+ functions such as <STRONG>attrset</STRONG>.
-</PRE><H3><a name="h3-COLOR_PAIR">COLOR_PAIR</a></H3><PRE>
- Its inverse <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an attribute.
- Attributes can hold color pairs in the range 0 to 255. If you need a
- color pair larger than that, you must use functions such as <STRONG>attr_set</STRONG>
- (which pass the color pair as a separate parameter) rather than the
- legacy functions such as <STRONG>attrset</STRONG>.
+</PRE><H3><a name="h3-PAIR_NUMBER">PAIR_NUMBER</a></H3><PRE>
+ <STRONG>PAIR_NUMBER(</STRONG><EM>attr</EM>) extracts the color information from its <EM>attr</EM>
+ parameter and returns it as a color pair number; it is the inverse
+ operation of <STRONG>COLOR_PAIR</STRONG>.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
The routines <STRONG>can_change_color</STRONG> and <STRONG>has_colors</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
- All other routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
- specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ All other routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
+ specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
completion.
- X/Open defines no error conditions. SVr4 does document some error
+ X/Open defines no error conditions. SVr4 does document some error
conditions which apply in general:
<STRONG>o</STRONG> This implementation will return <STRONG>ERR</STRONG> on attempts to use color values
- outside the range <STRONG>0</STRONG> to <STRONG>COLORS</STRONG>-1 (except for the default colors
- extension), or use color pairs outside the range <STRONG>0</STRONG> to
+ outside the range <STRONG>0</STRONG> to <STRONG>COLORS</STRONG>-1 (except for the default colors
+ extension), or use color pairs outside the range <STRONG>0</STRONG> to
<STRONG>COLOR_PAIRS-1</STRONG>.
Color values used in <STRONG>init_color</STRONG> must be in the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.
- An error is returned from all functions if the terminal has not
+ An error is returned from all functions if the terminal has not
been initialized.
- An error is returned from secondary functions such as <STRONG>init_pair</STRONG> if
+ An error is returned from secondary functions such as <STRONG>init_pair</STRONG> if
<STRONG>start_color</STRONG> was not called.
- <STRONG>o</STRONG> SVr4 does much the same, except that it returns <STRONG>ERR</STRONG> from
- <STRONG>pair_content</STRONG> if the pair was not initialized using <STRONG>init_pairs</STRONG> and
- it returns <STRONG>ERR</STRONG> from <STRONG>color_content</STRONG> if the terminal does not support
+ <STRONG>o</STRONG> SVr4 does much the same, except that it returns <STRONG>ERR</STRONG> from
+ <STRONG>pair_content</STRONG> if the pair was not initialized using <STRONG>init_pairs</STRONG> and
+ it returns <STRONG>ERR</STRONG> from <STRONG>color_content</STRONG> if the terminal does not support
changing colors.
This implementation does not return <STRONG>ERR</STRONG> for either case.
<STRONG>init_color</STRONG>
returns an error if the terminal does not support this feature,
- e.g., if the <STRONG>initialize_color</STRONG> capability is absent from the
+ e.g., if the <STRONG>initialize_color</STRONG> capability is absent from the
terminal description.
<STRONG>start_color</STRONG>
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- In the <EM>ncurses</EM> implementation, there is a separate color activation
- flag, color palette, color pairs table, and associated <STRONG>COLORS</STRONG> and
- <STRONG>COLOR_PAIRS</STRONG> counts for each screen; the <STRONG>start_color</STRONG> function only
- affects the current screen. The SVr4/XSI interface is not really
- designed with this in mind, and historical implementations may use a
+ In the <EM>ncurses</EM> implementation, there is a separate color activation
+ flag, color palette, color pairs table, and associated <STRONG>COLORS</STRONG> and
+ <STRONG>COLOR_PAIRS</STRONG> counts for each screen; the <STRONG>start_color</STRONG> function only
+ affects the current screen. The SVr4/XSI interface is not really
+ designed with this in mind, and historical implementations may use a
single shared color palette.
- Setting an implicit background color via a color pair affects only
- character cells that a character write operation explicitly touches.
- To change the background color used when parts of a window are blanked
+ Setting an implicit background color via a color pair affects only
+ character cells that a character write operation explicitly touches.
+ To change the background color used when parts of a window are blanked
by erasing or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
- Several caveats apply on older x86 machines (e.g., i386, i486) with
+ Several caveats apply on older x86 machines (e.g., i386, i486) with
VGA-compatible graphics:
- <STRONG>o</STRONG> COLOR_YELLOW is actually brown. To get yellow, use COLOR_YELLOW
+ <STRONG>o</STRONG> COLOR_YELLOW is actually brown. To get yellow, use COLOR_YELLOW
combined with the <STRONG>A_BOLD</STRONG> attribute.
- <STRONG>o</STRONG> The A_BLINK attribute should in theory cause the background to go
+ <STRONG>o</STRONG> The A_BLINK attribute should in theory cause the background to go
bright. This often fails to work, and even some cards for which it
- mostly works (such as the Paradise and compatibles) do the wrong
- thing when you try to set a bright "yellow" background (you get a
+ mostly works (such as the Paradise and compatibles) do the wrong
+ thing when you try to set a bright "yellow" background (you get a
blinking yellow foreground instead).
<STRONG>o</STRONG> Color RGB values are not settable.
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
- The functions marked as extensions were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and
- are not found in SVr4 curses, 4.4BSD curses, or any other previous
+ The functions marked as extensions were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and
+ are not found in SVr4 curses, 4.4BSD curses, or any other previous
version of curses.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- This implementation satisfies XSI Curses's minimum maximums for <STRONG>COLORS</STRONG>
+ This implementation satisfies XSI Curses's minimum maximums for <STRONG>COLORS</STRONG>
and <STRONG>COLOR_PAIRS</STRONG>.
The <STRONG>init_pair</STRONG> routine accepts negative values of foreground and
- background color to support the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> extension, but
+ background color to support the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> extension, but
only if that routine has been first invoked.
The assumption that <STRONG>COLOR_BLACK</STRONG> is the default background color for all
- terminals
can be modified using the <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG>
+ terminals
can be modified using the <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG>
extension.
- This implementation checks the pointers, e.g., for the values returned
- by <STRONG>color_content</STRONG> and <STRONG>pair_content</STRONG>, and will treat those as optional
+ This implementation checks the pointers, e.g., for the values returned
+ by <STRONG>color_content</STRONG> and <STRONG>pair_content</STRONG>, and will treat those as optional
parameters when null.
- X/Open Curses does not specify a limit for the number of colors and
+ X/Open Curses does not specify a limit for the number of colors and
color pairs which a terminal can support. However, in its use of <STRONG>short</STRONG>
- for the parameters, it carries over SVr4's implementation detail for
+ for the parameters, it carries over SVr4's implementation detail for
the compiled terminfo database, which uses signed 16-bit numbers. This
- implementation provides extended versions of those functions which use
- <STRONG>short</STRONG> parameters, allowing applications to use larger color- and pair-
+ implementation provides extended versions of those functions which use
+ <STRONG>short</STRONG> parameters, allowing applications to use larger color- and pair-
numbers.
- The <STRONG>reset_color_pairs</STRONG> function is an extension of ncurses.
+ The <STRONG>reset_color_pairs</STRONG> function is an extension of <EM>ncurses</EM>.
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
SVr3.2 introduced color support to curses in 1987.
- SVr4 made internal changes, e.g., moving the storage for the color
+ SVr4 made internal changes, e.g., moving the storage for the color
state from <STRONG>SP</STRONG> (the <STRONG>SCREEN</STRONG> structure) to <STRONG>cur_term</STRONG> (the <STRONG>TERMINAL</STRONG>
structure), but provided the same set of library functions.
- SVr4 curses limits the number of color pairs to 64, reserving color
- pair zero (0) as the terminal's initial uncolored state. This limit
- arises because the color pair information is a bitfield in the <STRONG>chtype</STRONG>
+ SVr4 curses limits the number of color pairs to 64, reserving color
+ pair zero (0) as the terminal's initial uncolored state. This limit
+ arises because the color pair information is a bitfield in the <STRONG>chtype</STRONG>
data type (denoted by <STRONG>A_COLOR</STRONG>).
Other implementations of curses had different limits:
changing <STRONG>chtype</STRONG> from 16-bits to 32-bits.
<STRONG>o</STRONG> X/Open Curses (1992-present) added a new structure <STRONG>cchar_t</STRONG> to store
- the character, attributes and color-pair values, allowing increased
- range of color-pairs. Both color-pairs and color-values used a
+ the character, attributes and color pair values, allowing increased
+ range of color pairs. Both color pairs and color-values used a
signed <STRONG>short</STRONG>, limiting values to 15 bits.
- <STRONG>o</STRONG> ncurses (1992-present) uses eight bits for <STRONG>A_COLOR</STRONG> in <STRONG>chtype</STRONG>
+ <STRONG>o</STRONG> <EM>ncurses</EM> (1992-present) uses eight bits for <STRONG>A_COLOR</STRONG> in <STRONG>chtype</STRONG>
values.
- Version 5.3 provided a wide-character interface (2002), but left
- color-pairs as part of the attributes-field.
+ Version 5.3 provided a wide-character interface (2002), but left
+ color pairs as part of the attributes-field.
- Since version 6 (2015), ncurses uses a separate <STRONG>int</STRONG> for color-pairs
- in the <STRONG>cchar_t</STRONG> values. When those color-pair values fit in 8 bits,
- ncurses allows color-pairs to be manipulated via the functions
+ Since version 6 (2015), ncurses uses a separate <STRONG>int</STRONG> for color pairs
+ in the <STRONG>cchar_t</STRONG> values. When those color pair values fit in 8 bits,
+ ncurses allows color pairs to be manipulated via the functions
using <STRONG>chtype</STRONG> values.
- <STRONG>o</STRONG> NetBSD curses used 6 bits from 2000 (when colors were first
- supported) until 2004. At that point, NetBSD changed to use 10
- bits. As of 2021, that size is unchanged. Like ncurses before
- version 6, the NetBSD color-pair information is stored in the
- attributes field of <STRONG>cchar_t</STRONG>, limiting the number of color-pairs by
+ <STRONG>o</STRONG> NetBSD curses used 6 bits from 2000 (when colors were first
+ supported) until 2004. At that point, NetBSD changed to use 10
+ bits. As of 2021, that size is unchanged. Like <EM>ncurses</EM> before
+ version 6, the NetBSD color pair information is stored in the
+ attributes field of <STRONG>cchar_t</STRONG>, limiting the number of color pairs by
the size of the bitfield.
</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_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,
<STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
<STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h3-pair_content">pair_content</a></li>
<li><a href="#h3-extended_pair_content">extended_pair_content</a></li>
<li><a href="#h3-reset_color_pairs">reset_color_pairs</a></li>
-<li><a href="#h3-PAIR_NUMBER">PAIR_NUMBER</a></li>
<li><a href="#h3-COLOR_PAIR">COLOR_PAIR</a></li>
+<li><a href="#h3-PAIR_NUMBER">PAIR_NUMBER</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_delch.3x,v 1.29 2023/10/07 21:19:07 tom Exp @
+ * @Id: curs_delch.3x,v 1.30 2023/12/16 21:09:11 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_delch 3x 2023-10-07 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_delch 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_delch 3x 2023-10-07 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_delch 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG>
-ncurses 6.4 2023-1
0-07 <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_deleteln.3x,v 1.33 2023/11/25 14:08:05 tom Exp @
+ * @Id: curs_deleteln.3x,v 1.34 2023/12/16 21:33:34 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_deleteln 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_deleteln 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_deleteln 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_deleteln 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- All routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
+ These routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
completion.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* authorization. *
****************************************************************************
* Author: Thomas E. Dickey 1999-on
- * @Id: curs_extend.3x,v 1.42 2023/11/25 14:26:30 tom Exp @
+ * @Id: curs_extend.3x,v 1.43 2023/12/16 20:32:22 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_extend 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_extend 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_extend 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_extend 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines are specific to ncurses. They were not supported on
+ These routines are specific to <EM>ncurses</EM>. They were not supported on
Version 7, BSD or System V implementations. It is recommended that any
code depending on them be conditioned using NCURSES_VERSION.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_get_wstr.3x,v 1.41 2023/11/25 14:29:54 tom Exp @
+ * @Id: curs_get_wstr.3x,v 1.42 2023/12/16 20:32:22 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_get_wstr 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_get_wstr 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_get_wstr 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_get_wstr 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
X/Open Curses does not specify what happens if the length <EM>n</EM> is
negative.
- <STRONG>o</STRONG> For analogy with <STRONG>wgetnstr</STRONG>, ncurses 6.2 uses a limit (based on
+ <STRONG>o</STRONG> For analogy with <STRONG>wgetnstr</STRONG>, <EM>ncurses</EM> 6.2 uses a limit (based on
<STRONG>LINE_MAX</STRONG>).
<STRONG>o</STRONG> Some other implementations (such as Solaris xcurses) do the same,
while others (PDCurses) do not allow this.
- <STRONG>o</STRONG> NetBSD 7 curses imitates ncurses 6.1 in this regard, treating a <STRONG>-1</STRONG>
+ <STRONG>o</STRONG> NetBSD 7 curses imitates <EM>ncurses</EM> 6.1 in this regard, treating a <STRONG>-1</STRONG>
as an indefinite number of characters.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_getcchar.3x,v 1.42 2023/11/25 14:30:18 tom Exp @
+ * @Id: curs_getcchar.3x,v 1.43 2023/12/16 21:07:24 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_getcchar 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_getcchar 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_getcchar 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_getcchar 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG>
<STRONG>o</STRONG> Stores the character attributes in the location pointed to by <EM>attrs</EM>
- <STRONG>o</STRONG> Stores the color-pair in the location pointed to by <EM>color</EM><STRONG>_</STRONG><EM>pair</EM>
+ <STRONG>o</STRONG> Stores the color pair in the location pointed to by <EM>color</EM><STRONG>_</STRONG><EM>pair</EM>
<STRONG>o</STRONG> Stores the wide-character string, characters referenced by <EM>wcval</EM>,
into the array pointed to by <EM>wch</EM>.
L'\0' terminated, contain at most one spacing character, which must
be the first.
- Up to <STRONG>CCHARW_MAX</STRONG>-1 nonspacing characters may follow. Additional
- nonspacing characters are ignored.
+ Up to <STRONG>CCHARW_MAX</STRONG>-1 non-spacing characters may follow. Additional
+ non-spacing characters are ignored.
The string may contain a single control character instead. In that
- case, no nonspacing characters are allowed.
+ case, no non-spacing characters are allowed.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
X/Open Curses documents the <EM>opts</EM> argument as reserved for future use,
saying that it must be null. This implementation uses that parameter
- in ABI 6 for the functions which have a color-pair parameter to support
+ in ABI 6 for the functions which have a color pair parameter to support
extended color pairs:
<STRONG>o</STRONG> For functions which modify the color, e.g., <STRONG>setcchar</STRONG>, if <EM>opts</EM> is
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- The <STRONG>CCHARW_MAX</STRONG> symbol is specific to ncurses. X/Open Curses does not
+ The <STRONG>CCHARW_MAX</STRONG> symbol is specific to <EM>ncurses</EM>. X/Open Curses does not
provide details for the layout of the <STRONG>cchar_t</STRONG> structure. It tells what
data are stored in it:
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_getch.3x,v 1.75 2023/10/07 21:19:07 tom Exp @
+ * @Id: curs_getch.3x,v 1.76 2023/12/16 21:01:28 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_getch 3x 2023-10-07 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_getch 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_getch 3x 2023-10-07 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_getch 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
<STRONG>int</STRONG> <STRONG>getch(void);</STRONG>
<STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG>
-
<STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>mvwgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
experience a delay between the time a user presses the escape key and
the escape is returned to the program.
- In <STRONG>ncurses</STRONG>, the timer normally expires after the value in <STRONG>ESCDELAY</STRONG> (see
+ In <EM>ncurses</EM>, the timer normally expires after the value in <STRONG>ESCDELAY</STRONG> (see
<STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>). If <STRONG>notimeout</STRONG> is <STRONG>TRUE</STRONG>, the timer does not expire;
it is an infinite (or very large) value. Because function keys usually
begin with an escape character, the terminal may appear to hang in
KEY_ENTER Enter or send
KEY_SRESET Soft (partial) reset
KEY_RESET Reset or hard reset
-
KEY_PRINT Print or copy
+
KEY_LL Home down or bottom (lower left)
KEY_A1 Upper left of keypad
KEY_A3 Upper right of keypad
<STRONG>o</STRONG> <STRONG>KEY_MOUSE</STRONG> is returned for mouse-events (see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>). This
code relies upon whether or not <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> has been enabled,
- because (e.g., with <STRONG>xterm(1)</STRONG> mouse prototocol) ncurses must read
+ because (e.g., with <STRONG>xterm(1)</STRONG> mouse prototocol) <EM>ncurses</EM> must read
escape sequences, just like a function key.
<STRONG>KEY_ENTER</STRONG> versus control/M, <STRONG>KEY_BACKSPACE</STRONG> versus control/H. Some
curses implementations may differ according to whether they treat these
control keys specially (and ignore the terminfo), or use the terminfo
- definitions. <STRONG>Ncurses</STRONG> uses the terminfo definition. If it says that
+ definitions. <EM>ncurses</EM> uses the terminfo definition. If it says that
<STRONG>KEY_ENTER</STRONG> is control/M, <STRONG>getch</STRONG> will return <STRONG>KEY_ENTER</STRONG> when you press
control/M.
<STRONG>KEY_MOUSE</STRONG> is mentioned in XSI Curses, along with a few related terminfo
capabilities, but no higher-level functions use the feature. The
- implementation in ncurses is an extension.
+ implementation in <EM>ncurses</EM> is an extension.
- <STRONG>KEY_RESIZE</STRONG> is an extension first implemented for ncurses. NetBSD
+ <STRONG>KEY_RESIZE</STRONG> is an extension first implemented for <EM>ncurses</EM>. NetBSD
curses later added this extension.
Programmers concerned about portability should be prepared for either
receipt interrupts <STRONG>getch</STRONG> and causes it to return <STRONG>ERR</STRONG> with <STRONG>errno</STRONG> set to
<STRONG>EINTR</STRONG>.
- The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>. We recommend that any code
+ The <STRONG>has_key</STRONG> function is unique to <EM>ncurses</EM>. We recommend that any code
using it be conditionalized on the <STRONG>NCURSES_VERSION</STRONG> feature macro.
-ncurses 6.4 2023-1
0-07 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_getstr.3x,v 1.51 2023/11/25 14:29:54 tom Exp @
+ * @Id: curs_getstr.3x,v 1.52 2023/12/16 20:32:22 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_getstr 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_getstr 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_getstr 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_getstr 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
"read at most <EM>n</EM>-1 bytes" to allow for the terminating NUL. As of 2018,
some implementations count it, some do not:
- <STRONG>o</STRONG> ncurses 6.1 and PDCurses do not count the NUL in the given limit,
+ <STRONG>o</STRONG> <EM>ncurses</EM> 6.1 and PDCurses do not count the NUL in the given limit,
while
<STRONG>o</STRONG> Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
A comment in NetBSD's source code states that this is specified in
SUSv2.
- <STRONG>o</STRONG> ncurses (before 6.2) assumes no particular limit for the result
+ <STRONG>o</STRONG> <EM>ncurses</EM> (before 6.2) assumes no particular limit for the result
from <STRONG>wgetstr</STRONG>, and treats the <EM>n</EM> parameter of <STRONG>wgetnstr</STRONG> like SVr4
curses.
- <STRONG>o</STRONG> ncurses 6.2 uses <STRONG>LINE_MAX</STRONG>, or a larger (system-dependent) value
+ <STRONG>o</STRONG> <EM>ncurses</EM> 6.2 uses <STRONG>LINE_MAX</STRONG>, or a larger (system-dependent) value
which the <STRONG>sysconf</STRONG> function may provide. If neither <STRONG>LINE_MAX</STRONG> or
- <STRONG>sysconf</STRONG> is available, ncurses uses the POSIX value for <STRONG>LINE_MAX</STRONG> (a
+ <STRONG>sysconf</STRONG> is available, <EM>ncurses</EM> uses the POSIX value for <STRONG>LINE_MAX</STRONG> (a
2048 byte limit). In either case, it reserves a byte for the
terminating NUL.
caller into account when deciding whether to handle echoing within
<STRONG>getnstr</STRONG> or as a side-effect of the <STRONG>getch</STRONG> calls.
- <STRONG>o</STRONG> The original ncurses (as <EM>pcurses</EM> in 1986) set <STRONG>noraw</STRONG> and <STRONG>cbreak</STRONG> when
+ <STRONG>o</STRONG> The original <EM>ncurses</EM> (as <EM>pcurses</EM> in 1986) set <STRONG>noraw</STRONG> and <STRONG>cbreak</STRONG> when
accepting input for <STRONG>getnstr</STRONG>. That may have been done to make
- function- and cursor-keys work; it is not necessary with ncurses.
+ function- and cursor-keys work; it is not necessary with <EM>ncurses</EM>.
- Since 1995, ncurses has provided signal handlers for INTR and QUIT
+ Since 1995, <EM>ncurses</EM> has provided signal handlers for INTR and QUIT
(e.g., <STRONG>^C</STRONG> or <STRONG>^\</STRONG>). With the <STRONG>noraw</STRONG> and <STRONG>cbreak</STRONG> settings, those may
catch a signal and stop the program, where other implementations
allow one to enter those characters in the buffer.
- <STRONG>o</STRONG> Starting in 2021 (ncurses 6.3), <STRONG>getnstr</STRONG> sets <STRONG>raw</STRONG>, rather than <STRONG>noraw</STRONG>
+ <STRONG>o</STRONG> Starting in 2021 (<EM>ncurses</EM> 6.3), <STRONG>getnstr</STRONG> sets <STRONG>raw</STRONG>, rather than <STRONG>noraw</STRONG>
and <STRONG>cbreak</STRONG> for better compatibility with SVr4-curses, e.g.,
allowing one to enter a <STRONG>^C</STRONG> into the buffer.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_getyx.3x,v 1.39 2023/10/21 10:28:36 tom Exp @
+ * @Id: curs_getyx.3x,v 1.40 2023/12/16 21:33:21 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_getyx 3x 2023-10-21 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_getyx 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_getyx 3x 2023-10-21 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_getyx 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- All of these interfaces are macros. A "<STRONG>&</STRONG>" is not necessary before the
+ All of these interfaces are macros. A "&" is not necessary before the
variables <EM>y</EM> and <EM>x</EM>.
-ncurses 6.4 2023-1
0-21 <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_inch.3x,v 1.40 2023/10/07 21:19:07 tom Exp @
+ * @Id: curs_inch.3x,v 1.41 2023/12/16 21:08:16 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_inch 3x 2023-10-07 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_inch 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_inch 3x 2023-10-07 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_inch 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>
</PRE><H3><a name="h3-Attributes">Attributes</a></H3><PRE>
- The following bit-masks may be AND-ed with characters returned by
+ The following bit masks may be AND-ed with characters returned by
<STRONG>winch</STRONG>.
- <STRONG>A_CHARTEXT</STRONG> Bit-mask to extract character
- <STRONG>A_ATTRIBUTES</STRONG> Bit-mask to extract attributes
- <STRONG>A_COLOR</STRONG> Bit-mask to extract color-pair field information
+ <STRONG>A_CHARTEXT</STRONG> Bit mask to extract character
+ <STRONG>A_ATTRIBUTES</STRONG> Bit mask to extract attributes
+ <STRONG>A_COLOR</STRONG> Bit mask to extract color pair field information
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
-ncurses 6.4 2023-1
0-07 <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_initscr.3x,v 1.56 2023/12/03 00:09:54 tom Exp @
+ * @Id: curs_initscr.3x,v 1.59 2023/12/17 23:56:04 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_initscr 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_initscr 3x 2023-12-17 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_initscr 3x 2023-12-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_initscr 3x 2023-12-17 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>
X/Open specifies that portable applications must not call <STRONG>initscr</STRONG> more
than once:
- <STRONG>o</STRONG> The portable way to use <STRONG>initscr</STRONG> is once only, using <STRONG>refresh</STRONG> (see
- <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>) to restore the screen after <STRONG>endwin</STRONG>.
+ <STRONG>o</STRONG> The portable way to use <STRONG>initscr</STRONG> is once only, using <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> to
+ restore the screen after <STRONG>endwin</STRONG>.
<STRONG>o</STRONG> This implementation allows using <STRONG>initscr</STRONG> after <STRONG>endwin</STRONG>.
<STRONG>curscr</STRONG> as well as a work area <STRONG>newscr</STRONG>. SVr4 curses ignores other
windows.
- <STRONG>o</STRONG> Since version 4.0 (1996), ncurses has maintained a list of all
+ <STRONG>o</STRONG> Since version 4.0 (1996), <EM>ncurses</EM> has maintained a list of all
windows for each screen, using that information to delete those
windows when <STRONG>delscreen</STRONG> is called.
- <STRONG>o</STRONG> NetBSD copied this feature of ncurses in 2001. PDCurses follows
+ <STRONG>o</STRONG> NetBSD copied this feature of <EM>ncurses</EM> in 2001. PDCurses follows
the SVr4 model, deleting only the standard <STRONG>WINDOW</STRONG> structures.
-</PRE><H3><a name="h3-High-level-versus-
low-level">High-level versus low-level</a></H3><PRE>
+</PRE><H3><a name="h3-High-level-versus-
Low-level">High-level versus Low-level</a></H3><PRE>
Different implementations may disagree regarding the level of some
functions. For example, <STRONG>SCREEN</STRONG> (returned by <STRONG>newterm</STRONG>) and <STRONG>TERMINAL</STRONG>
(returned by <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>) hold file descriptors for the output
For example
<STRONG>o</STRONG> NetBSD's <STRONG><A HREF="curs_termattrs.3x.html">baudrate(3x)</A></STRONG> function uses the descriptor in <STRONG>TERMINAL</STRONG>.
- <STRONG>ncurses</STRONG> and SVr4 use the descriptor in <STRONG>SCREEN</STRONG>.
+ <EM>ncurses</EM> and SVr4 use the descriptor in <STRONG>SCREEN</STRONG>.
- <STRONG>o</STRONG> NetBSD and <STRONG>ncurses</STRONG> use the descriptor in <STRONG>TERMINAL</STRONG> for terminal I/O
+ <STRONG>o</STRONG> NetBSD and <EM>ncurses</EM> use the descriptor in <STRONG>TERMINAL</STRONG> for terminal I/O
modes, e.g., <STRONG><A HREF="curs_kernel.3x.html">def_shell_mode(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">def_prog_mode(3x)</A></STRONG>. SVr4 curses
uses the descriptor in <STRONG>SCREEN</STRONG>.
-
-</PRE><H3><a name="h3-Unset-TERM-Variable">Unset TERM Variable</a></H3><PRE>
+ <STRONG>Unset</STRONG> <EM>TERM</EM> <STRONG>Variable</STRONG>
If the <EM>TERM</EM> variable is missing or empty, <STRONG>initscr</STRONG> uses the value
"unknown", which normally corresponds to a terminal entry with the
<EM>generic</EM> (<EM>gn</EM>) capability. Generic entries are detected by <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>
<STRONG>SIGTSTP</STRONG>
This handles the <EM>stop</EM> signal, used in job control. When resuming
the process, this implementation discards pending input with
- <STRONG>flushinput</STRONG> (see <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>), and repaints the screen assuming
- that it has been completely altered. It also updates the saved
- terminal modes with <STRONG>def_shell_mode</STRONG> (see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>).
+ <STRONG><A HREF="curs_util.3x.html">flushinp(3x)</A></STRONG>, and repaints the screen assuming that it has been
+ completely altered. It also updates the saved terminal modes with
+ <STRONG><A HREF="curs_kernel.3x.html">def_shell_mode(3x)</A></STRONG>.
<STRONG>SIGWINCH</STRONG>
This handles the window-size changes which were ignored in the
standardization efforts. The handler sets a (signal-safe)
- variable which is later tested in <STRONG>wgetch</STRONG> (see <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>). If
- <STRONG>keypad</STRONG> has been enabled for the corresponding window, <STRONG>wgetch</STRONG>
- returns the key symbol <STRONG>KEY_RESIZE</STRONG>. At the same time, <STRONG>wgetch</STRONG> calls
- <STRONG>resizeterm</STRONG> to adjust the standard screen <STRONG>stdscr</STRONG>, and update other
- data such as <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG>.
+ variable which is later tested in <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>. If <STRONG>keypad</STRONG> has been
+ enabled for the corresponding window, <STRONG>wgetch</STRONG> returns the key
+ symbol <STRONG>KEY_RESIZE</STRONG>. At the same time, <STRONG>wgetch</STRONG> calls <STRONG>resizeterm</STRONG> to
+ adjust the standard screen <STRONG>stdscr</STRONG>, and update other data such as
+ <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG>.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>
+ncurses 6.4 2023-12-
17 <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
<li><a href="#h3-Differences">Differences</a></li>
-<li><a href="#h3-High-level-versus-low-level">High-level versus low-level</a></li>
-<li><a href="#h3-Unset-TERM-Variable">Unset TERM Variable</a></li>
+<li><a href="#h3-High-level-versus-Low-level">High-level versus Low-level</a></li>
<li><a href="#h3-Signal-Handlers">Signal Handlers</a></li>
</ul>
</li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_inopts.3x,v 1.58 2023/11/25 14:30:50 tom Exp @
+ * @Id: curs_inopts.3x,v 1.59 2023/12/16 20:32:22 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_inopts 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_inopts 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_inopts 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_inopts 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_ins_wstr.3x,v 1.29 2023/11/25 11:29:34 tom Exp @
+ * @Id: curs_ins_wstr.3x,v 1.30 2023/12/16 20:36:15 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_ins_wstr 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_ins_wstr 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_ins_wstr 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_ins_wstr 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
All but <STRONG>wins_nwstr</STRONG> may be macros.
- If the first character in the string is a nonspacing character, these
- functions will fail. XSI does not define what will happen if a
- nonspacing character follows a control character.
+ If the first character in the string is a non-spacing character, these
+ functions will fail. XSI does not define what will happen if a non-
+ spacing character follows a control character.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_insch.3x,v 1.33 2023/10/07 21:19:07 tom Exp @
+ * @Id: curs_insch.3x,v 1.34 2023/12/16 21:09:11 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_insch 3x 2023-10-07 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_insch 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_insch 3x 2023-10-07 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_insch 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- All routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG>
- (SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
- completion, unless otherwise noted in the preceding routine
- descriptions.
+ These routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
+ specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ completion.
- Functions with a "mv" prefix first perform a cursor movement using
+ Functions with a "mv" prefix first perform a cursor movement using
<STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
the window pointer is null.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- These routines do not necessarily imply use of a hardware insert
+ These routines do not necessarily imply use of a hardware insert
character feature.
Note that <STRONG>insch</STRONG>, <STRONG>mvinsch</STRONG>, and <STRONG>mvwinsch</STRONG> may be macros.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>
- Comparable functions in the wide-character (ncursesw) library are
+ Comparable functions in the wide-character (ncursesw) library are
described in <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>.
-ncurses 6.4 2023-1
0-07 <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_instr.3x,v 1.43 2023/11/25 17:58:25 tom Exp @
+ * @Id: curs_instr.3x,v 1.44 2023/12/16 20:32:22 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_instr 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_instr 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_instr 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_instr 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
SVr4 does not document whether a length limit includes or excludes the
trailing NUL.
- The ncurses library extends the XSI description by allowing a negative
+ The <EM>ncurses</EM> library extends the XSI description by allowing a negative
value for <EM>n</EM>. In this case, the functions return the string ending at
the right margin.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_kernel.3x,v 1.49 2023/10/14 22:03:52 tom Exp @
+ * @Id: curs_kernel.3x,v 1.50 2023/12/16 20:32:22 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_kernel 3x 2023-10-14 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_kernel 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_kernel 3x 2023-10-14 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_kernel 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
currently incorrect". This implementation gets it right, but it may be
unwise to count on the correctness of the return value anywhere else.
- Both ncurses and SVr4 will call <STRONG>curs_set</STRONG> in <STRONG>endwin</STRONG> if <STRONG>curs_set</STRONG> has been
+ Both <EM>ncurses</EM> and SVr4 will call <STRONG>curs_set</STRONG> in <STRONG>endwin</STRONG> if <STRONG>curs_set</STRONG> has been
called to make the cursor other than normal, i.e., either invisible or
- very visible. There is no way for ncurses to determine the initial
+ very visible. There is no way for <EM>ncurses</EM> to determine the initial
cursor state to restore that.
type int. This is misleading, as they are macros with no documented
semantics for the return value.
- If interrupted, ncurses restarts <STRONG>napms</STRONG>. That, and the limitation to 30
+ If interrupted, <EM>ncurses</EM> restarts <STRONG>napms</STRONG>. That, and the limitation to 30
seconds, are different from other implementations.
-ncurses 6.4 2023-1
0-14 <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_memleaks.3x,v 1.31 2023/11/11 11:46:43 tom Exp @
+ * @Id: curs_memleaks.3x,v 1.32 2023/12/16 20:32:22 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_memleaks 3x 2023-11-11 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_memleaks 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_memleaks 3x 2023-11-11 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_memleaks 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
These functions are used to simplify analysis of memory leaks in the
- ncurses library.
+ <EM>ncurses</EM> library.
Any implementation of curses must not free the memory associated with a
screen, since (even after calling <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG>), it must be available for
use in the next call to <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>. There are also chunks of memory
held for performance reasons. That makes it hard to analyze curses
applications for memory leaks. When using the specially configured
- debugging version of the ncurses library, applications can call
+ debugging version of the <EM>ncurses</EM> library, applications can call
functions which free those chunks of memory, simplifying the process of
memory-leak checking.
not intended for use in the non-debugging library:
<STRONG>_nc_freeall</STRONG>
- This frees (almost) all of the memory allocated by ncurses.
+ This frees (almost) all of the memory allocated by <EM>ncurses</EM>.
<STRONG>_nc_free_and_exit</STRONG>
- This frees the memory allocated by ncurses (like <STRONG>_nc_freeall</STRONG>), and
+ This frees the memory allocated by <EM>ncurses</EM> (like <STRONG>_nc_freeall</STRONG>), and
exits the program. It is preferred over <STRONG>_nc_freeall</STRONG> since some of
that memory may be required to keep the application running.
Simply exiting (with the given exit-code) is safer.
-ncurses 6.4 2023-1
1-11 <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_mouse.3x,v 1.81 2023/10/21 10:29:45 tom Exp @
+ * @Id: curs_mouse.3x,v 1.82 2023/12/16 21:08:16 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_mouse 3x 2023-10-21 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_mouse 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_mouse 3x 2023-10-21 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_mouse 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>
</PRE><H3><a name="h3-wmouse_trafo">wmouse_trafo</a></H3><PRE>
The <STRONG>wmouse_trafo</STRONG> function transforms a given pair of coordinates from
- stdscr-relative coordinates to coordinates relative to the given window
- or vice versa. The resulting stdscr-relative coordinates are not
+ <STRONG>stdscr</STRONG>-relative coordinates to coordinates relative to the given window
+ or vice versa. The resulting <STRONG>stdscr</STRONG>-relative coordinates are not
always identical to window-relative coordinates due to the mechanism to
reserve lines on top or bottom of the screen for other purposes (see
the <STRONG>ripoffline</STRONG> and <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG> calls, for example).
window, <STRONG>FALSE</STRONG> is returned.
<STRONG>o</STRONG> If <EM>to</EM><STRONG>_</STRONG><EM>screen</EM> is <STRONG>FALSE</STRONG>, the pointers <EM>pY,</EM> <EM>pX</EM> must reference window-
- relative coordinates. They are converted to stdscr-relative
+ relative coordinates. They are converted to <STRONG>stdscr</STRONG>-relative
coordinates if the window <EM>win</EM> encloses this point. In this case
the function returns <STRONG>TRUE</STRONG>.
</PRE><H3><a name="h3-mouse_trafo">mouse_trafo</a></H3><PRE>
The <STRONG>mouse_trafo</STRONG> function performs the same translation as <STRONG>wmouse_trafo</STRONG>,
- using stdscr for <EM>win</EM>.
+ using <STRONG>stdscr</STRONG> for <EM>win</EM>.
</PRE><H3><a name="h3-mouseinterval">mouseinterval</a></H3><PRE>
</PRE><H3><a name="h3-has_mouse">has_mouse</a></H3><PRE>
The <STRONG>has_mouse</STRONG> function returns <STRONG>TRUE</STRONG> if the mouse driver has been
- successfully initialized.
+ successfully initialized, and <STRONG>FALSE</STRONG> otherwise.
Note that mouse events will be ignored when input is in cooked mode,
and will cause an error beep when cooked mode is being simulated in a
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- <STRONG>getmouse</STRONG> and <STRONG>ungetmouse</STRONG> return the integer <STRONG>ERR</STRONG> upon failure or <STRONG>OK</STRONG> upon
- successful completion:
+ <STRONG>has_mouse</STRONG>, <STRONG>wenclose</STRONG>, <STRONG>mouse_trafo</STRONG>, and <STRONG>wmouse_trafo</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>
+ as noted above.
- <STRONG>getmouse</STRONG>
- returns an error.
+ <STRONG>getmouse</STRONG> and <STRONG>ungetmouse</STRONG> return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
- <STRONG>o</STRONG> If no mouse driver was initialized, or if the mask parameter is
- zero,
+ <STRONG>getmouse</STRONG> fails if:
- <STRONG>o</STRONG> It returns an error if a mouse event was detected which did not
- match the current <EM>mousemask</EM>.
+ <STRONG>o</STRONG> no mouse driver was initialized,
- <STRONG>o</STRONG> It also returns an error if no more events remain in the queue.
+ <STRONG>o</STRONG> the mask of reportable events is zero,
- <STRONG>ungetmouse</STRONG>
- returns an error if the FIFO is full.
+ <STRONG>o</STRONG> a mouse event was detected that does not match the mask,
+
+ <STRONG>o</STRONG> or if no more events remain in the queue.
+
+ <STRONG>ungetmouse</STRONG> returns an error if the event queue is full.
<STRONG>mousemask</STRONG> returns the mask of reportable events.
was not initialized. In that case, it returns the maximum interval
value (166).
- <STRONG>wenclose</STRONG> and <STRONG>wmouse_trafo</STRONG> are boolean functions returning <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>
- depending on their test result.
+
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+ The feature macro <STRONG>NCURSES_MOUSE_VERSION</STRONG> is provided so the preprocessor
+ can be used to test whether these features are present. If the
+ interface is changed, the value of <STRONG>NCURSES_MOUSE_VERSION</STRONG> will be
+ incremented. These values for <STRONG>NCURSES_MOUSE_VERSION</STRONG> may be specified
+ when configuring <EM>ncurses</EM>:
+
+ 1 has definitions for reserved events. The mask uses 28 bits.
+
+ 2 adds definitions for button 5, removes the definitions for
+ reserved events. The mask uses 29 bits.
+
+ The order of the <STRONG>MEVENT</STRONG> structure members is not guaranteed.
+ Additional fields may be added to the structure in the future.
+
+ Under <EM>ncurses</EM>, these calls are implemented using either xterm's built-
+ in mouse-tracking API or platform-specific drivers including
+
+ <STRONG>o</STRONG> Alessandro Rubini's gpm server
+
+ <STRONG>o</STRONG> FreeBSD sysmouse
+
+ <STRONG>o</STRONG> OS/2 EMX
+
+ If you are using an unsupported configuration, mouse events will not be
+ visible to <EM>ncurses</EM> (and the <STRONG>mousemask</STRONG> function will always return <STRONG>0</STRONG>).
+
+ If the terminfo entry contains a <STRONG>XM</STRONG> string, this is used in the xterm
+ mouse driver to control the way the terminal is initialized for mouse
+ operation. The default, if <STRONG>XM</STRONG> is not found, corresponds to private
+ mode 1000 of xterm:
+
+ \E[?1000%?%p1%{1}%=%th%el%;
+
+ The mouse driver also recognizes a newer xterm private mode 1006, e.g.,
+
+ \E[?1006;1000%?%p1%{1}%=%th%el%;
+
+ The <EM>z</EM> member in the event structure is not presently used. It is
+ intended for use with touch screens (which may be pressure-sensitive)
+ or with 3D-mice/trackballs/power gloves.
+
+ The <STRONG>ALL_MOUSE_EVENTS</STRONG> class does not include <STRONG>REPORT_MOUSE_POSITION</STRONG>.
+ They are distinct. For example, in xterm, wheel/scrolling mice send
+ position reports as a sequence of presses of buttons 4 or 5 without
+ matching button-releases.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These calls were designed for <EM>ncurses</EM>, and are not found in SVr4
+ These calls were designed for <EM>ncurses</EM>, and are not found in SVr4
<EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous version of <EM>curses</EM>.
- SVr4 <EM>curses</EM> had support for the mouse in a variant of <STRONG>xterm(1)</STRONG>. It is
+ SVr4 <EM>curses</EM> had support for the mouse in a variant of <STRONG>xterm(1)</STRONG>. It is
mentioned in a few places, but with no supporting documentation:
- <STRONG>o</STRONG> the "libcurses" manual page lists functions for this feature which
+ <STRONG>o</STRONG> the "libcurses" manual page lists functions for this feature which
are prototyped in <STRONG>curses.h</STRONG>:
extern int mouse_set(long int);
mouse_info minfo Mi Mouse status information
req_mouse_pos reqmp RQ Request mouse position report
- <STRONG>o</STRONG> the interface made assumptions (as does <EM>ncurses</EM>) about the escape
+ <STRONG>o</STRONG> the interface made assumptions (as does <EM>ncurses</EM>) about the escape
sequences sent to and received from the terminal.
- For instance the SVr4 <EM>curses</EM> library used the <STRONG>get_mouse</STRONG> capability
- to tell the terminal which mouse button events it should send,
- passing the mouse-button bit-mask to the terminal. Also, it could
- ask the terminal where the mouse was using the <STRONG>req_mouse_pos</STRONG>
+ For instance the SVr4 <EM>curses</EM> library used the <STRONG>get_mouse</STRONG> capability
+ to tell the terminal which mouse button events it should send,
+ passing the mouse-button bit mask to the terminal. Also, it could
+ ask the terminal where the mouse was using the <STRONG>req_mouse_pos</STRONG>
capability.
- Those features required a terminal which had been modified to work
+ Those features required a terminal which had been modified to work
with <EM>curses</EM>. They were not part of the X Consortium's xterm.
- When developing the xterm mouse support for <EM>ncurses</EM> in September 1995,
- Eric Raymond was uninterested in using the same interface due to its
+ When developing the xterm mouse support for <EM>ncurses</EM> in September 1995,
+ Eric Raymond was uninterested in using the same interface due to its
lack of documentation. Later, in 1998, Mark Hesseling provided support
- in PDCurses 2.3 using the SVr4 interface. PDCurses, however, does not
- use video terminals, making it unnecessary to be concerned about
+ in PDCurses 2.3 using the SVr4 interface. PDCurses, however, does not
+ use video terminals, making it unnecessary to be concerned about
compatibility with the escape sequences.
- The feature macro <STRONG>NCURSES_MOUSE_VERSION</STRONG> is provided so the preprocessor
- can be used to test whether these features are present. If the
- interface is changed, the value of <STRONG>NCURSES_MOUSE_VERSION</STRONG> will be
- incremented. These values for <STRONG>NCURSES_MOUSE_VERSION</STRONG> may be specified
- when configuring <EM>ncurses</EM>:
-
- 1 has definitions for reserved events. The mask uses 28 bits.
-
- 2 adds definitions for button 5, removes the definitions for
- reserved events. The mask uses 29 bits.
-
- The order of the <STRONG>MEVENT</STRONG> structure members is not guaranteed.
- Additional fields may be added to the structure in the future.
-
- Under <EM>ncurses</EM>, these calls are implemented using either xterm's built-
- in mouse-tracking API or platform-specific drivers including
-
- <STRONG>o</STRONG> Alessandro Rubini's gpm server
-
- <STRONG>o</STRONG> FreeBSD sysmouse
-
- <STRONG>o</STRONG> OS/2 EMX
-
- If you are using an unsupported configuration, mouse events will not be
- visible to <EM>ncurses</EM> (and the <STRONG>mousemask</STRONG> function will always return <STRONG>0</STRONG>).
-
- If the terminfo entry contains a <STRONG>XM</STRONG> string, this is used in the xterm
- mouse driver to control the way the terminal is initialized for mouse
- operation. The default, if <STRONG>XM</STRONG> is not found, corresponds to private
- mode 1000 of xterm:
-
- \E[?1000%?%p1%{1}%=%th%el%;
-
- The mouse driver also recognizes a newer xterm private mode 1006, e.g.,
-
- \E[?1006;1000%?%p1%{1}%=%th%el%;
-
- The <EM>z</EM> member in the event structure is not presently used. It is
- intended for use with touch screens (which may be pressure-sensitive)
- or with 3D-mice/trackballs/power gloves.
-
- The <STRONG>ALL_MOUSE_EVENTS</STRONG> class does not include <STRONG>REPORT_MOUSE_POSITION</STRONG>.
- They are distinct. For example, in xterm, wheel/scrolling mice send
- position reports as a sequence of presses of buttons 4 or 5 without
- matching button-releases.
-
</PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
- Mouse events from <EM>xterm</EM> are <EM>not</EM> ignored in cooked mode if they have
- been enabled by <STRONG>mousemask</STRONG>. Instead, the <EM>xterm</EM> mouse report sequence
+ Mouse events from <EM>xterm</EM> are <EM>not</EM> ignored in cooked mode if they have
+ been enabled by <STRONG>mousemask</STRONG>. Instead, the <EM>xterm</EM> mouse report sequence
appears in the string read.
- Mouse event reports from <EM>xterm</EM> are not detected correctly in a window
- with keypad application mode disabled, since they are interpreted as a
- variety of function key. Set the the terminal's <EM>terminfo</EM> capability
- <STRONG>kmous</STRONG> to "\E[M" (the beginning of the response from <EM>xterm</EM> for mouse
- clicks). Other values of <STRONG>kmous</STRONG> are permitted under the same
+ Mouse event reports from <EM>xterm</EM> are not detected correctly in a window
+ with keypad application mode disabled, since they are interpreted as a
+ variety of function key. Set the the terminal's <EM>terminfo</EM> capability
+ <STRONG>kmous</STRONG> to "\E[M" (the beginning of the response from <EM>xterm</EM> for mouse
+ clicks). Other values of <STRONG>kmous</STRONG> are permitted under the same
assumption, that is, the report begins with that sequence.
Because there are no standard response sequences that serve to identify
- terminals supporting the <EM>xterm</EM> mouse protocol, <EM>ncurses</EM> assumes that if
+ terminals supporting the <EM>xterm</EM> mouse protocol, <EM>ncurses</EM> assumes that if
<STRONG>kmous</STRONG> is defined in the terminal description, or if the terminal type's
- primary name or aliases contain the string "xterm", then the terminal
+ primary name or aliases contain the string "xterm", then the terminal
may send mouse events. The <STRONG>kmous</STRONG> capability is checked first, allowing
use of newer <EM>xterm</EM> mouse protocols such as its private mode 1006.
-ncurses 6.4 2023-1
0-21 <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
+<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-BUGS">BUGS</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_move.3x,v 1.32 2023/10/07 21:19:07 tom Exp @
+ * @Id: curs_move.3x,v 1.33 2023/12/16 21:33:08 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_move 3x 2023-10-07 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_move 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_move 3x 2023-10-07 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_move 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- These routines return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 specifies only "an
- integer value other than <STRONG>ERR</STRONG>") upon successful completion.
+ These routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
+ specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ completion.
Specifically, they return an error if the window pointer is null, or if
the position is outside the window.
-ncurses 6.4 2023-1
0-07 <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_opaque.3x,v 1.40 2023/12/02 20:52:50 tom Exp @
+ * @Id: curs_opaque.3x,v 1.41 2023/12/16 20:32:22 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_opaque 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_opaque 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_opaque 3x 2023-12-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_opaque 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_outopts.3x,v 1.52 2023/11/25 14:08:05 tom Exp @
+ * @Id: curs_outopts.3x,v 1.53 2023/12/16 20:32:22 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_outopts 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_outopts 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_outopts 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_outopts 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
These functions are described in the XSI Curses standard, Issue 4.
- From the outset, ncurses used <STRONG>nl</STRONG>/<STRONG>nonl</STRONG> to control the conversion of
+ From the outset, <EM>ncurses</EM> used <STRONG>nl</STRONG>/<STRONG>nonl</STRONG> to control the conversion of
newlines to carriage return/line-feed on output as well as input. XSI
Curses documents only the use of these functions for input. This
difference arose from converting the <EM>pcurses</EM> source (which used <STRONG>ioctl</STRONG>
interface). In the former, both input and output were controlled via a
single option <STRONG>CRMOD</STRONG>, while the latter separates these features.
Because that conversion interferes with output optimization, <STRONG>nl</STRONG>/<STRONG>nonl</STRONG>
- were amended after ncurses 6.2 to eliminate their effect on output.
+ were amended after <EM>ncurses</EM> 6.2 to eliminate their effect on output.
Some historic curses implementations had, as an undocumented feature,
the ability to do the equivalent of <STRONG>clearok(...,</STRONG> <STRONG>1)</STRONG> by saying
- <STRONG>touchwin(stdscr)</STRONG> or <STRONG>clear(stdscr)</STRONG>. This will not work under ncurses.
+ <STRONG>touchwin(stdscr)</STRONG> or <STRONG>clear(stdscr)</STRONG>. This will not work under <EM>ncurses</EM>.
Earlier System V curses implementations specified that with <STRONG>scrollok</STRONG>
enabled, any window modification triggering a scroll also forced a
- physical refresh. XSI Curses does not require this, and <STRONG>ncurses</STRONG> avoids
+ physical refresh. XSI Curses does not require this, and <EM>ncurses</EM> avoids
doing it to perform better vertical-motion optimization at <STRONG>wrefresh</STRONG>
time.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_overlay.3x,v 1.35 2023/11/25 11:29:34 tom Exp @
+ * @Id: curs_overlay.3x,v 1.36 2023/12/16 21:32:51 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_overlay 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_overlay 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_overlay 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_overlay 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(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 <STRONG>OK</STRONG> (SVr4
- only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ These routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
+ specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
completion.
X/Open defines no error conditions. In this implementation, <STRONG>copywin</STRONG>,
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_pad.3x,v 1.49 2023/11/25 14:08:35 tom Exp @
+ * @Id: curs_pad.3x,v 1.50 2023/12/16 21:18:02 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_pad 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_pad 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_pad 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_pad 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
</PRE><H3><a name="h3-newpad">newpad</a></H3><PRE>
- The <STRONG>newpad</STRONG> routine creates and returns a pointer to a new pad data
- structure with the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>.
- A pad is like a window, except that it is not restricted by the screen
- size, and is not necessarily associated with a particular part of the
- screen. Pads can be used when a large window is needed, and only a
- part of the window will be on the screen at one time. Automatic
- refreshes of pads (e.g., from scrolling or echoing of input) do not
- occur.
-
- It is not valid to call <STRONG>wrefresh</STRONG> with a <EM>pad</EM> argument; call <STRONG>prefresh</STRONG> or
- <STRONG>pnoutrefresh</STRONG> instead. They require additional parameters to specify
- the part of the pad to be displayed and the location on the screen to
+ <STRONG>newpad</STRONG> creates and returns a pointer to a new pad data structure with
+ the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>. A pad is like a
+ window, except that it is not restricted by the screen size, and is not
+ necessarily associated with a particular part of the screen. Pads can
+ be used when a large window is needed, and only a part of the window
+ will be on the screen at one time. Automatic refreshes of pads (as
+ from scrolling or echoing of input) do not occur.
+
+ It is not valid to call <STRONG>wrefresh</STRONG> with a <EM>pad</EM> argument; call <STRONG>prefresh</STRONG> or
+ <STRONG>pnoutrefresh</STRONG> instead. They require additional parameters to specify
+ the part of the pad to be displayed and the location on the screen to
be used for the display.
</PRE><H3><a name="h3-subpad">subpad</a></H3><PRE>
- The <STRONG>subpad</STRONG> routine creates and returns a pointer to a subwindow within
- a pad with the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>.
+ The <STRONG>subpad</STRONG> routine creates and returns a pointer to a subwindow within
+ a pad with the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>.
Unlike <STRONG>subwin</STRONG>, which uses screen coordinates, the window is at position
(<EM>begin</EM>_<EM>x</EM><STRONG>,</STRONG> <EM>begin</EM>_<EM>y</EM>) on the pad. The window is made in the middle of the
- window <EM>orig</EM>, so that changes made to one window affect both windows.
- During the use of this routine, it will often be necessary to call
+ window <EM>orig</EM>, so that changes made to one window affect both windows.
+ During the use of this routine, it will often be necessary to call
<STRONG>touchwin</STRONG> or <STRONG>touchline</STRONG> on <EM>orig</EM> before calling <STRONG>prefresh</STRONG>.
</PRE><H3><a name="h3-prefresh_-pnoutrefresh">prefresh, pnoutrefresh</a></H3><PRE>
- The <STRONG>prefresh</STRONG> and <STRONG>pnoutrefresh</STRONG> routines are analogous to <STRONG>wrefresh</STRONG> and
- <STRONG>wnoutrefresh</STRONG> except that they relate to pads instead of windows. The
- additional parameters are needed to indicate what part of the pad and
+ The <STRONG>prefresh</STRONG> and <STRONG>pnoutrefresh</STRONG> routines are analogous to <STRONG>wrefresh</STRONG> and
+ <STRONG>wnoutrefresh</STRONG> except that they relate to pads instead of windows. The
+ additional parameters are needed to indicate what part of the pad and
screen are involved.
- <STRONG>o</STRONG> The <EM>pminrow</EM> and <EM>pmincol</EM> parameters specify the upper left-hand
+ <STRONG>o</STRONG> The <EM>pminrow</EM> and <EM>pmincol</EM> parameters specify the upper left-hand
corner of the rectangle to be displayed in the pad.
- <STRONG>o</STRONG> The <EM>sminrow</EM>, <EM>smincol</EM>, <EM>smaxrow</EM>, and <EM>smaxcol</EM> parameters specify the
+ <STRONG>o</STRONG> The <EM>sminrow</EM>, <EM>smincol</EM>, <EM>smaxrow</EM>, and <EM>smaxcol</EM> parameters specify the
edges of the rectangle to be displayed on the screen.
The lower right-hand corner of the rectangle to be displayed in the pad
is calculated from the screen coordinates, since the rectangles must be
the same size. Both rectangles must be entirely contained within their
- respective structures. Negative values of <EM>pminrow</EM>, <EM>pmincol</EM>, <EM>sminrow</EM>,
+ respective structures. Negative values of <EM>pminrow</EM>, <EM>pmincol</EM>, <EM>sminrow</EM>,
or <EM>smincol</EM> are treated as if they were zero.
</PRE><H3><a name="h3-pechochar">pechochar</a></H3><PRE>
- The <STRONG>pechochar</STRONG> routine is functionally equivalent to a call to <STRONG>addch</STRONG>
- followed by a call to <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>, a call to <STRONG>waddch</STRONG> followed by a call
- to <STRONG>wrefresh</STRONG>, or a call to <STRONG>waddch</STRONG> followed by a call to <STRONG>prefresh</STRONG>. The
- knowledge that only a single character is being output is taken into
- consideration and, for non-control characters, a considerable
+ The <STRONG>pechochar</STRONG> routine is functionally equivalent to a call to <STRONG>addch</STRONG>
+ followed by a call to <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>, a call to <STRONG>waddch</STRONG> followed by a call
+ to <STRONG>wrefresh</STRONG>, or a call to <STRONG>waddch</STRONG> followed by a call to <STRONG>prefresh</STRONG>. The
+ knowledge that only a single character is being output is taken into
+ consideration and, for non-control characters, a considerable
performance gain might be seen by using these routines instead of their
equivalents. In the case of <STRONG>pechochar</STRONG>, the last location of the pad on
the screen is reused for the arguments to <STRONG>prefresh</STRONG>.
</PRE><H3><a name="h3-pecho_wchar">pecho_wchar</a></H3><PRE>
- The <STRONG>pecho_wchar</STRONG> function is the analogous wide-character form of
+ The <STRONG>pecho_wchar</STRONG> function is the analogous wide-character form of
<STRONG>pechochar</STRONG>. It outputs one character to a pad and immediately refreshes
- the pad. It does this by a call to <STRONG>wadd_wch</STRONG> followed by a call to
+ the pad. It does this by a call to <STRONG>wadd_wch</STRONG> followed by a call to
<STRONG>prefresh</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 <STRONG>OK</STRONG> (SVr4
- only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ Functions that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
+ specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
completion.
- Routines that return pointers return <STRONG>NULL</STRONG> on error, and set <STRONG>errno</STRONG> to
+ Functions that return pointers return <STRONG>NULL</STRONG> on error, and set <STRONG>errno</STRONG> to
<STRONG>ENOMEM</STRONG>.
- X/Open does not define any error conditions. In this implementation
+ X/Open Curses does not define any error conditions. In this
+ implementation
<STRONG>prefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>
return an error if the window pointer is null, or if the window
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- Note that <STRONG>pechochar</STRONG> may be a macro.
+ <STRONG>pechochar</STRONG> may be a macro.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
conditions. The behavior of <STRONG>subpad</STRONG> if the parent window is not a pad
is undocumented, and is not checked by the vendor Unix implementations:
- <STRONG>o</STRONG> SVr4 <EM>curses</EM> sets a flag in the <STRONG>WINDOW</STRONG> structure in <STRONG>newpad</STRONG> which
+ <STRONG>o</STRONG> SVr4 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM> structure in <STRONG>newpad</STRONG> which
tells if the window is a <EM>pad</EM>.
However, it uses this information only in <STRONG>waddch</STRONG> (to decide if it
does not check in <STRONG>wrefresh</STRONG> to ensure that the pad is refreshed
properly.
- <STRONG>o</STRONG> Solaris X/Open Curses checks if a window is a pad in <STRONG>wnoutrefresh</STRONG>,
+ <STRONG>o</STRONG> Solaris <EM>xcurses</EM> checks whether a window is a pad in <STRONG>wnoutrefresh</STRONG>,
returning <STRONG>ERR</STRONG> in that case.
However, it only sets the flag for subwindows if the parent window
enough, a comment in the source code states that the lack of a
check was an MKS extension.
- <STRONG>o</STRONG> NetBSD 7 <EM>curses</EM> sets a flag in the <STRONG>WINDOW</STRONG> structure for <STRONG>newpad</STRONG> and
+ <STRONG>o</STRONG> NetBSD 7 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG> and
<STRONG>subpad</STRONG>, using this to help with the distinction between
<STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>.
This implementation
- <STRONG>o</STRONG> sets a flag in the <STRONG>WINDOW</STRONG> structure for <STRONG>newpad</STRONG> and <STRONG>subpad</STRONG>,
+ <STRONG>o</STRONG> sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG> and <STRONG>subpad</STRONG>,
<STRONG>o</STRONG> allows a <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG> call to succeed having a pad parent by
forcing the subwindow to be a pad,
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_print.3x,v 1.34 2023/10/21 10:31:22 tom Exp @
+ * @Id: curs_print.3x,v 1.35 2023/12/16 20:32:22 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_print 3x 2023-10-21 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_print 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_print 3x 2023-10-21 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_print 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>
-ncurses 6.4 2023-1
0-21 <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_printw.3x,v 1.43 2023/11/25 11:31:06 tom Exp @
+ * @Id: curs_printw.3x,v 1.45 2023/12/18 00:03:28 tom Exp @
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+ * libcurses/printw.c
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
+ * varargs.h
+ * either header declares "va_list", but only one can be used
-->
<!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_printw 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_printw 3x 2023-12-17 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_printw 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_printw 3x 2023-12-17 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
<STRONG>printw</STRONG>, <STRONG>wprintw</STRONG>, <STRONG>mvprintw</STRONG>, <STRONG>mvwprintw</STRONG>, <STRONG>vwprintw</STRONG>, <STRONG>vw_printw</STRONG> - write
- formatted output to <EM>curses</EM> windows
+ formatted output to a <EM>curses</EM> window
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>int</STRONG> <STRONG>wprintw(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>fmt</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
<STRONG>int</STRONG> <STRONG>mvprintw(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>fmt</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
<STRONG>int</STRONG> <STRONG>mvwprintw(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>fmt</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
+
<STRONG>int</STRONG> <STRONG>vw_printw(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>fmt</EM><STRONG>,</STRONG> <STRONG>va_list</STRONG> <EM>varglist</EM><STRONG>);</STRONG>
<EM>/*</EM> <EM>obsolete</EM> <EM>*/</EM>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- The <STRONG>printw</STRONG>, <STRONG>wprintw</STRONG>, <STRONG>mvprintw</STRONG> and <STRONG>mvwprintw</STRONG> routines are analogous to
- <STRONG>printf</STRONG> [see <STRONG>printf(3)</STRONG>]. In effect, the string that would be output by
- <STRONG>printf</STRONG> is output instead as though <STRONG>waddstr</STRONG> were used on the given
- window.
+ <STRONG>printw</STRONG>, <STRONG>wprintw</STRONG>, <STRONG>mvprintw</STRONG>, and <STRONG>mvwprintw</STRONG> are analogous to <STRONG>printf(3)</STRONG>.
+ In effect, the string that would be output by <STRONG>printf(3)</STRONG> is instead
+ output as though <STRONG><A HREF="curs_addstr.3x.html">waddstr(3x)</A></STRONG> were used with <EM>win</EM> (or <STRONG>stdscr</STRONG>) as its
+ first argument.
- The <STRONG>vwprintw</STRONG> and <STRONG>vw_printw</STRONG> routines are analogous to <STRONG>vprintf</STRONG> [see
- <STRONG>printf(3)</STRONG>] and perform a <STRONG>wprintw</STRONG> using a variable argument list. The
- third argument is a <STRONG>va_list</STRONG>, a pointer to a list of arguments, as
- defined in <STRONG><stdarg.h></STRONG>.
+ <STRONG>vwprintw</STRONG> and <STRONG>vw_printw</STRONG> are analogous to <STRONG>vprintf(3)</STRONG>, and perform a
+ <STRONG>wprintw</STRONG> using a variable argument list. The third argument is a
+ <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, a pointer to a list of arguments, as defined in <EM>stdarg.h</EM>.
</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.
+ These functions return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
- X/Open defines no error conditions. In this implementation, an error
- may be returned if it cannot allocate enough memory for the buffer used
- to format the results. It will return an error if the window pointer
- is null.
+ In <EM>ncurses,</EM> failure occurs if the library cannot allocate enough memory
+ for the buffer into which the output is formatted, or if the window
+ pointer <EM>win</EM> is null.
Functions with a "mv" prefix first perform a cursor movement using
- <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
- the window pointer is null.
-
+ <STRONG>wmove</STRONG>, and fail if the position is outside the window.
-</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- In this implementation, <STRONG>vw_printw</STRONG> and <STRONG>vwprintw</STRONG> are equivalent, to
- support legacy applications. However, the latter (<STRONG>vwprintw</STRONG>) is
- obsolete:
- <STRONG>o</STRONG> The XSI Curses standard, Issue 4 described these functions. The
- function <STRONG>vwprintw</STRONG> is marked TO BE WITHDRAWN, and is to be replaced
- by a function <STRONG>vw_printw</STRONG> using the <STRONG><stdarg.h></STRONG> interface.
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+ No wide character counterpart functions are defined by the "wide"
+ <EM>ncurses</EM> configuration nor by any standard. To format and write a wide-
+ character string to a <EM>curses</EM> window, consider using <STRONG>swprintf(3)</STRONG> and
+ <STRONG><A HREF="curs_addwstr.3x.html">waddwstr(3x)</A></STRONG> or similar.
- <STRONG>o</STRONG> The Single Unix Specification, Version 2 states that <STRONG>vw_printw</STRONG> is
- preferred to <STRONG>vwprintw</STRONG> since the latter requires including
- <STRONG><varargs.h></STRONG>, which cannot be used in the same file as <STRONG><stdarg.h></STRONG>.
- This implementation uses <STRONG><stdarg.h></STRONG> for both, because that header
- is included in <STRONG><curses.h</STRONG>>.
- <STRONG>o</STRONG> X/Open Curses, Issue 5 (December 2007) marked <STRONG>vwprintw</STRONG> (along with
- <STRONG>vwscanw</STRONG> and the termcap interface) as withdrawn.
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+ X/Open Curses, Issue 4, describes these functions. It specifies no
+ error conditions for them.
+ <EM>ncurses</EM> defines <STRONG>vw_printw</STRONG> and <STRONG>vwprintw</STRONG> identically to support legacy
+ applications. However, the latter is obsolete.
-</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
- While <STRONG>printw</STRONG> was implemented in 4BSD, it was unused until 4.2BSD (which
- used it in games). That early version of curses was before the ANSI C
- standard. It did not use <varargs.h>, though that was available. In
- 1991 (a couple of years after SVr4 was generally available, and after
- the C standard was published), other developers updated the library,
- using <stdarg.h> internally in 4.4BSD curses. Even with this
- improvement, BSD curses did not use function prototypes (or even
- declare functions) in the <curses.h> header until 1992.
+ <STRONG>o</STRONG> X/Open Curses, Issue 4, Version 2 (1996), marked <STRONG>vwprintw</STRONG> as
+ requiring <EM>varargs.h</EM> and "TO BE WITHDRAWN", and specified <STRONG>vw_printw</STRONG>
+ using the <EM>stdarg.h</EM> interface.
- SVr2 documented <STRONG>printw</STRONG>, <STRONG>wprintw</STRONG> tersely as "printf on <EM>stdscr</EM>" and
- tersely as "printf on <EM>win</EM>", respectively.
+ <STRONG>o</STRONG> X/Open Curses, Issue 5, Draft 2 (December 2007) marked <STRONG>vwprintw</STRONG>
+ (along with <STRONG>vwscanw</STRONG> and the termcap interface) as withdrawn. After
+ incorporating review comments, this became X/Open Curses, Issue 7
+ (2009).
- SVr3 added <STRONG>mvprintw</STRONG>, and <STRONG>mvwprintw</STRONG>, with a three-line summary saying
- that they were analogous to <STRONG>printf(3)</STRONG>, explaining that the string which
- would be output from <STRONG>printf(3)</STRONG> would instead be output using <STRONG>waddstr</STRONG> on
- the given window. SVr3 also added <STRONG>vwprintw</STRONG>, saying that the third
- parameter is a <STRONG>va_list</STRONG>, defined in <varargs.h>, and referring the
- reader to the manual pages for <EM>varargs</EM> and <STRONG>vprintf</STRONG> for detailed
- descriptions.
+ <STRONG>o</STRONG> <EM>ncurses</EM> provides <STRONG>vwprintw</STRONG>, but marks it as deprecated.
- SVr4 added no new variations of <STRONG>printw</STRONG>, but provided for using
- <varargs.h> or <stdarg.h> to define the <STRONG>va_list</STRONG> type.
- X/Open Curses added <STRONG>vw_printw</STRONG> to replace <STRONG>vwprintw</STRONG>, stating that its
- <STRONG>va_list</STRONG> definition requires <stdarg.h>.
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+ While <STRONG>printw</STRONG> was implemented in 4BSD (November 1980), it was unused
+ until 4.2BSD (August 1983), which employed it for games. That early
+ version of <EM>curses</EM> preceded the ANSI C standard of 1989. It did not use
+ <EM>varargs.h</EM>, though that had been available since Seventh Edition Unix
+ (1979). In 1991 (a couple of years after SVr4 was generally available,
+ and after the C standard was published), other developers updated the
+ library, using <EM>stdarg.h</EM> internally in 4.4BSD <EM>curses.</EM> Even with this
+ improvement, BSD <EM>curses</EM> did not use function prototypes (nor even
+ declare functions) in <EM>curses.h</EM> until 1992.
+
+ SVr2 (1984) documented <STRONG>printw</STRONG> and <STRONG>wprintw</STRONG> tersely as "printf on <STRONG>stdscr</STRONG>"
+ and "printf on <EM>win</EM>", respectively.
+
+ SVr3 (1987) added <STRONG>mvprintw</STRONG> and <STRONG>mvwprintw</STRONG>, with a three-line summary
+ asserting that they were analogous to <STRONG>printf(3)</STRONG>, explaining that the
+ string that <STRONG>printf(3)</STRONG> would write to the standard output stream would
+ instead be output using <STRONG>waddstr</STRONG> to the given window. SVr3 also
+ implemented <STRONG>vwprintw</STRONG>, describing its third parameter as a <EM>va</EM><STRONG>_</STRONG><EM>list</EM>,
+ defined in <EM>varargs.h</EM>, and referred the reader to the manual pages for
+ <EM>varargs</EM> and <EM>vprintf</EM> for detailed descriptions.
+
+ SVr4 (1989) introduced no new variations of <EM>printw</EM>, but provided for
+ using either <EM>varargs.h</EM> or <EM>stdarg.h</EM> to define the <EM>va</EM><STRONG>_</STRONG><EM>list</EM> type.
+
+ X/Open Curses, Issue 4 (1995), defined <STRONG>vw_printw</STRONG> to replace <STRONG>vwprintw</STRONG>,
+ stating that its <EM>va</EM><STRONG>_</STRONG><EM>list</EM> type is defined in <EM>stdarg.h</EM>.
</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_addstr.3x.html">curs_addstr(3x)</A></STRONG>, <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>, <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>,
- <STRONG>printf(3)</STRONG>, <STRONG>vprintf(3)</STRONG>
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>, <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>, <STRONG>printf(3)</STRONG>, <STRONG>vprintf(3)</STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-17 <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
+<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_refresh.3x,v 1.38 2023/10/07 21:19:07 tom Exp @
+ * @Id: curs_refresh.3x,v 1.39 2023/12/16 21:09:11 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_refresh 3x 2023-10-07 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_refresh 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_refresh 3x 2023-10-07 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_refresh 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(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 <STRONG>OK</STRONG> (SVr4
- only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ These routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
+ specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
completion.
X/Open does not define any error conditions. In this implementation
-ncurses 6.4 2023-1
0-07 <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_scanw.3x,v 1.43 2023/11/25 11:31:06 tom Exp @
+ * @Id: curs_scanw.3x,v 1.44 2023/12/17 22:50:40 tom Exp @
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+ * libcurses/scanw.c
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
+ * varargs.h
+ * either header declares "va_list", but only one can be used
-->
<!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_scanw 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_scanw 3x 2023-12-17 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_scanw 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_scanw 3x 2023-12-17 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- The <STRONG>scanw</STRONG>, <STRONG>wscanw</STRONG> and <STRONG>mvscanw</STRONG> routines are analogous to <STRONG>scanf</STRONG> [see
- <STRONG>scanf(3)</STRONG>]. The effect of these routines is as though <STRONG>wgetstr</STRONG> were
- called on the window, and the resulting line used as input for
- <STRONG>sscanf(3)</STRONG>. Fields which do not map to a variable in the <EM>fmt</EM> field are
- lost.
+ <STRONG>scanw</STRONG>, <STRONG>wscanw</STRONG>, <STRONG>mvscanw</STRONG>, and <STRONG>mvwscanw</STRONG> are analogous to <STRONG>scanf(3)</STRONG>. In
+ effect, they call <STRONG><A HREF="curs_getstr.3x.html">wgetstr(3x)</A></STRONG> with <EM>win</EM> (or <STRONG>stdscr</STRONG>) as its first
+ argument, then attempt conversion of the resulting string with
+ <STRONG>vsscanf(3)</STRONG>. Fields in the string that do not map to a variable in the
+ <EM>fmt</EM> parameter are discarded.
- The <STRONG>vwscanw</STRONG> and <STRONG>vw_scanw</STRONG> routines are analogous to <STRONG>vscanf(3)</STRONG>. They
- perform a <STRONG>wscanw</STRONG> using a variable argument list. The third argument is
- a <STRONG>va_list</STRONG>, a pointer to a list of arguments, as defined in <STRONG><stdarg.h></STRONG>.
+ <STRONG>vwscanw</STRONG> and <STRONG>vw_scanw</STRONG> are analogous to <STRONG>vscanf(3)</STRONG>, and perform a <STRONG>wscanw</STRONG>
+ using a variable argument list. The third argument is a <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, a
+ pointer to a list of arguments, as defined in <EM>stdarg.h</EM>.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- <STRONG>vwscanw</STRONG> returns <STRONG>ERR</STRONG> on failure and an integer equal to the number of
- fields scanned on success.
+ These functions return <STRONG>ERR</STRONG> upon failure and otherwise a count of
+ successful conversions; this quantity may be zero.
- Applications may use the return value from the <STRONG>scanw</STRONG>, <STRONG>wscanw</STRONG>, <STRONG>mvscanw</STRONG>
- and <STRONG>mvwscanw</STRONG> routines to determine the number of fields which were
- mapped in the call.
+ In <EM>ncurses,</EM> failure occurs if <STRONG>vsscanf(3)</STRONG> returns <STRONG>EOF</STRONG>, or if the window
+ pointer <EM>win</EM> is null.
- Functions with a "mv" prefix first perform a cursor movement using
- <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
- the window pointer is null.
+ Functions with a "mv" prefix first perform a cursor movement using
+ <STRONG>wmove</STRONG>, and fail if the position is outside the window.
+
+
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+ No wide character counterpart functions are defined by the "wide"
+ <EM>ncurses</EM> configuration nor by any standard. They are unnecessary: to
+ retrieve and convert a wide-character string from a <EM>curses</EM> terminal
+ keyboard, use these functions with the <STRONG>scanf(3)</STRONG> conversions "%lc" and
+ "%ls" for wide characters and strings, respectively.
+
+ <EM>ncurses</EM> implements <STRONG>vsscanf(3)</STRONG> internally if it is unavailable when the
+ library is configured.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- In this implementation, <STRONG>vw_scanw</STRONG> and <STRONG>vwscanw</STRONG> are equivalent, to support
- legacy applications. However, the latter (<STRONG>vwscanw</STRONG>) is obsolete:
+ X/Open Curses, Issue 4, describes these functions. It specifies no
+ error conditions for them.
- <STRONG>o</STRONG> The XSI Curses standard, Issue 4 described these functions, noting
- that the function <STRONG>vwscanw</STRONG> is marked TO BE WITHDRAWN, and is to be
- replaced by a function <STRONG>vw_scanw</STRONG> using the <STRONG><stdarg.h></STRONG> interface.
+ <EM>ncurses</EM> defines <STRONG>vw_scanw</STRONG> and <STRONG>vwscanw</STRONG> identically to support legacy
+ applications. However, the latter is obsolete.
- <STRONG>o</STRONG> The Single Unix Specification, Version 2 states that <STRONG>vw_scanw</STRONG> is
- preferred to <STRONG>vwscanw</STRONG> since the latter requires including
- <STRONG><varargs.h></STRONG>, which cannot be used in the same file as <STRONG><stdarg.h></STRONG>.
- This implementation uses <STRONG><stdarg.h></STRONG> for both, because that header
- is included in <STRONG><curses.h</STRONG>>.
+ <STRONG>o</STRONG> X/Open Curses, Issue 4, Version 2 (1996), marked <STRONG>vwscanw</STRONG> as
+ requiring <EM>varargs.h</EM> and "TO BE WITHDRAWN", and specified <STRONG>vw_scanw</STRONG>
+ using the <EM>stdarg.h</EM> interface.
- <STRONG>o</STRONG> X/Open Curses, Issue 5 (December 2007) marked <STRONG>vwscanw</STRONG> (along with
- <STRONG>vwprintw</STRONG> and the termcap interface) as withdrawn.
+ <STRONG>o</STRONG> X/Open Curses, Issue 5, Draft 2 (December 2007) marked <STRONG>vwscanw</STRONG>
+ (along with <STRONG>vwscanw</STRONG> and the termcap interface) as withdrawn. After
+ incorporating review comments, this became X/Open Curses, Issue 7
+ (2009).
- Both XSI and The Single Unix Specification, Version 2 state that these
- functions return <STRONG>ERR</STRONG> or <STRONG>OK</STRONG>.
+ <STRONG>o</STRONG> <EM>ncurses</EM> provides <STRONG>vwscanw</STRONG>, but marks it as deprecated.
- <STRONG>o</STRONG> Since the underlying <STRONG>scanf(3)</STRONG> can return the number of items
- scanned, and the SVr4 code was documented to use this feature, this
- is probably an editing error which was introduced in XSI, rather
- than being done intentionally.
+ X/Open Curses Issues 4 and 7 both state that these functions return <STRONG>ERR</STRONG>
+ or <STRONG>OK</STRONG>. This is likely an erratum.
- <STRONG>o</STRONG> This implementation returns the number of items scanned, for
- compatibility with SVr4 curses. As of 2018, NetBSD curses also
- returns the number of items scanned. Both ncurses and NetBSD
- curses call <STRONG>vsscanf</STRONG> to scan the string, which returns <STRONG>EOF</STRONG> on error.
+ <STRONG>o</STRONG> Since the underlying <STRONG>scanf(3)</STRONG> returns the number of successful
+ conversions, and SVr4 <EM>curses</EM> was documented to use this feature,
+ this may have been an editorial solecism introduced by X/Open,
+ rather than an intentional change.
- <STRONG>o</STRONG> Portable applications should only test if the return value is <STRONG>ERR</STRONG>,
- since the <STRONG>OK</STRONG> value (zero) is likely to be misleading.
+ <STRONG>o</STRONG> This implementation retains compatibility with SVr4 <EM>curses.</EM> As of
+ 2018, NetBSD <EM>curses</EM> also returns the number of successful
+ conversions. Both <EM>ncurses</EM> and NetBSD <EM>curses</EM> call <STRONG>vsscanf(3)</STRONG> to
+ scan the string, which returns <STRONG>EOF</STRONG> on error.
- One possible way to get useful results would be to use a "%n"
- conversion at the end of the format string to ensure that something
- was processed.
+ <STRONG>o</STRONG> Portable applications should test only if the return value is <STRONG>ERR</STRONG>,
+ and not compare it to <STRONG>OK</STRONG>, since that value (zero) might be
+ misleading.
+
+ One portable way to get useful results would be to use a "%n"
+ conversion at the end of the format string, and check the value of
+ the corresponding variable to determine how many conversions
+ succeeded.
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
- While <STRONG>scanw</STRONG> was implemented in 4BSD, none of the BSD releases used it
- until 4.4BSD (in a game). That early version of curses was before the
- ANSI C standard. It did not use <varargs.h>, though that was
- available. In 1991 (a couple of years after SVr4 was generally
- available, and after the C standard was published), other developers
- updated the library, using <stdarg.h> internally in 4.4BSD curses.
- Even with this improvement, BSD curses did not use function prototypes
- (or even declare functions) in the <curses.h> header until 1992.
-
- SVr2 documented <STRONG>scanw</STRONG>, <STRONG>wscanw</STRONG> tersely as "scanf through <EM>stdscr</EM>" and
- tersely as "scanf through <EM>win</EM>", respectively.
-
- SVr3 added <STRONG>mvscanw</STRONG>, and <STRONG>mvwscanw</STRONG>, with a three-line summary saying that
- they were analogous to <STRONG>scanf(3)</STRONG>, explaining that the string which would
- be output from <STRONG>scanf(3)</STRONG> would instead be output using <STRONG>waddstr</STRONG> on the
- given window. SVr3 also added <STRONG>vwscanw</STRONG>, saying that the third parameter
- is a <STRONG>va_list</STRONG>, defined in <varargs.h>, and referring the reader to the
- manual pages for <EM>varargs</EM> and <STRONG>vprintf</STRONG> for detailed descriptions.
- (Because the SVr3 documentation does not mention <STRONG>vscanf</STRONG>, that reference
- to <STRONG>vprintf</STRONG> may not be an error).
-
- SVr4 added no new variations of <STRONG>scanw</STRONG>, but provided for using
- <varargs.h> or <stdarg.h> to define the <STRONG>va_list</STRONG> type.
-
- X/Open Curses added <STRONG>vw_scanw</STRONG> to replace <STRONG>vwscanw</STRONG>, stating that its
- <STRONG>va_list</STRONG> definition requires <stdarg.h>.
+ <STRONG>scanw</STRONG> was implemented in 4BSD (November 1980); that early version of
+ <EM>curses</EM> preceded the ANSI C standard of 1989. The function was unused
+ in Berkeley distributions for over ten years, until 4.4BSD, which
+ employed it in a game. The 4BSD <STRONG>scanw</STRONG> did not use <EM>varargs.h</EM>, though
+ that had been available since Seventh Edition Unix (1979). In 1991 (a
+ couple of years after SVr4 was generally available, and after the C
+ standard was published), other developers updated the library, using
+ <EM>stdarg.h</EM> internally in 4.4BSD <EM>curses.</EM> Even with this improvement, BSD
+ <EM>curses</EM> did not use function prototypes (nor even declare functions) in
+ <EM>curses.h</EM> until 1992.
+
+ SVr2 (1984) documented <STRONG>scanw</STRONG> and <STRONG>wscanw</STRONG> tersely as "scanf through
+ <STRONG>stdscr</STRONG>" and "scanf through <EM>win</EM>", respectively.
+
+ SVr3 (1987) added <STRONG>mvscanw</STRONG>, and <STRONG>mvwscanw</STRONG>, stating
+
+ These routines correspond to <STRONG>scanf(3S)</STRONG>, as do their arguments
+ and return values. <STRONG>wgetstr</STRONG>() is called on the window, and the
+ resulting line is used as input for the scan.
+
+ SVr3 also implemented <STRONG>vwscanw</STRONG>, describing its third parameter as a
+ <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, defined in <EM>varargs.h</EM>, and referred the reader to the manual
+ pages for <EM>varargs</EM> and <EM>vprintf</EM> for detailed descriptions. (Because the
+ SVr3 documentation does not mention <EM>vscanf</EM>, the reference to <EM>vprintf</EM>
+ might not be an error).
+
+ SVr4 (1989) introduced no new variations of <EM>scanw</EM>, but provided for
+ using either <EM>varargs.h</EM> or <EM>stdarg.h</EM> to define the <EM>va</EM><STRONG>_</STRONG><EM>list</EM> type.
+
+ X/Open Curses, Issue 4 (1995), defined <EM>vw</EM><STRONG>_</STRONG><EM>scanw</EM> to replace <EM>vwscanw</EM>,
+ stating that its <EM>va</EM><STRONG>_</STRONG><EM>list</EM> type is defined in <EM>stdarg.h</EM>.
</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_getstr.3x.html">curs_getstr(3x)</A></STRONG>, <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>, <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>,
- <STRONG>scanf(3)</STRONG>
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>, <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>, <STRONG>scanf(3)</STRONG>, <STRONG>vscanf(3)</STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-17 <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
+<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_scr_dump.3x,v 1.35 2023/11/25 11:29:34 tom Exp @
+ * @Id: curs_scr_dump.3x,v 1.36 2023/12/16 21:10:18 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_scr_dump 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_scr_dump 3x 2023-12-16 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-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_scr_dump 3x 2023-12-16 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-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- All routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
+ These routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
X/Open defines no error conditions. In this implementation, each will
return an error if the file cannot be opened.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <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_scroll.3x,v 1.35 2023/10/07 21:19:07 tom Exp @
+ * @Id: curs_scroll.3x,v 1.36 2023/12/16 22:52:35 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_scroll 3x 2023-10-07 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_scroll 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_scroll 3x 2023-10-07 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_scroll 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- The <STRONG>scroll</STRONG> routine scrolls the window up one line. This involves
- moving the lines in the window data structure. As an optimization, if
- the scrolling region of the window is the entire screen, the <EM>physical</EM>
- <EM>screen</EM> may be scrolled at the same time.
+ <STRONG>scroll</STRONG> scrolls the given window up one line. That is, every visible
+ line we might number <EM>i</EM> becomes line <EM>i</EM>-1. The text of the top line in
+ the window disappears and the bottom line is populated with blank
+ characters; see <STRONG><A HREF="curs_bkgd.3x.html">bkgd(3x)</A></STRONG> or <STRONG><A HREF="curs_bkgrnd.3x.html">bkgrnd(3x)</A></STRONG>. As an optimization, if the
+ scrolling region of the window is the entire screen, the physical
+ screen may be scrolled at the same time; see <STRONG><A HREF="curs_variables.3x.html">curscr(3x)</A></STRONG>.
- For positive <EM>n</EM>, the <STRONG>scrl</STRONG> and <STRONG>wscrl</STRONG> routines scroll the window up <EM>n</EM>
- lines (line <EM>i</EM>+<EM>n</EM> becomes <EM>i</EM>); otherwise scroll the window down <EM>n</EM> lines.
- This involves moving the lines in the window character image structure.
- The current cursor position is not changed.
+ <STRONG>scrl</STRONG> and <STRONG>wscrl</STRONG> scroll <STRONG>stdscr</STRONG> or the specified window up or down
+ depending on the sign of <EM>n.</EM>
- For these functions to work, scrolling must be enabled via
- <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>.
+ <STRONG>o</STRONG> For positive <EM>n,</EM> line <EM>i</EM>+<EM>n</EM> becomes <EM>i</EM> (scrolling up);
+ <STRONG>o</STRONG> for negative <EM>n,</EM> line <EM>i</EM>-<EM>n</EM> becomes <EM>i</EM> (scrolling down).
+
+ The cursor does not move. These functions perform no operation unless
+ scrolling is enabled for the window via <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>.
-</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- These routines return <STRONG>ERR</STRONG> upon failure, and <STRONG>OK</STRONG> (SVr4 only specifies "an
- integer value other than <STRONG>ERR</STRONG>") upon successful completion.
- X/Open defines no error conditions.
+</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
+ These functions return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success.
- This implementation returns an error if the window pointer is null, or
- if scrolling is not enabled in the window, e.g., with <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>.
+ <EM>ncurses</EM> returns <STRONG>ERR</STRONG> if scrolling is not enabled in the window, for
+ example with <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>, or if the <EM>WINDOW</EM> pointer is null.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- Note that <STRONG>scrl</STRONG> and <STRONG>scroll</STRONG> may be macros.
-
- The SVr4 documentation says that the optimization of physically
- scrolling immediately if the scroll region is the entire screen "is"
- performed, not "may be" performed. This implementation deliberately
- does not guarantee that this will occur, to leave open the possibility
- of smarter optimization of multiple scroll actions on the next update.
+ Unusually, there is no <STRONG>wscroll</STRONG> function; <STRONG>scroll</STRONG> behaves as one would
+ expect <STRONG>wscroll</STRONG> to, accepting a <EM>WINDOW</EM> pointer argument.
- Neither the SVr4 nor the XSI documentation specify whether the current
- attribute or current color-pair of blanks generated by the scroll
- function is zeroed. Under this implementation it is.
+ <STRONG>scrl</STRONG> and <STRONG>scroll</STRONG> may be implemented as macros.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- The XSI Curses standard, Issue 4 describes these functions.
+ X/Open Curses, Issue 4, describes these functions. It defines no error
+ conditions.
+
+ SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>" as a successful
+ return value.
+
+ SVr4 indicates that the optimization of physically scrolling
+ immediately if the scroll region is the entire screen "is" performed,
+ not "may be" performed. <EM>ncurses</EM> deliberately does not guarantee that
+ this will occur, to leave open the possibility of smarter optimization
+ of multiple scroll actions on the next update.
+
+ Neither SVr4 <EM>curses</EM> nor X/Open Curses specify whether the current
+ attribute or current color pair of blanks generated by the scroll
+ function are zeroed. <EM>ncurses</EM> does so.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.4 2023-1
0-07 <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_slk.3x,v 1.66 2023/11/25 14:31:07 tom Exp @
+ * @Id: curs_slk.3x,v 1.67 2023/12/16 21:18:45 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_slk 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_slk 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_slk 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_slk 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
<STRONG>int</STRONG> <STRONG>slk_init(int</STRONG> <EM>fmt</EM><STRONG>);</STRONG>
- <STRONG>int</STRONG> <STRONG>slk_set(int</STRONG> <EM>labnum</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>label</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fmt</EM><STRONG>);</STRONG>
- <STRONG>int</STRONG> <STRONG>slk_wset(int</STRONG> <EM>labnum</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>label</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fmt</EM><STRONG>);</STRONG>
+ <STRONG>int</STRONG> <STRONG>slk_set(int</STRONG> <EM>labnum</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>label</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>align</EM><STRONG>);</STRONG>
+ <STRONG>int</STRONG> <STRONG>slk_wset(int</STRONG> <EM>labnum</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>label</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>align</EM><STRONG>);</STRONG>
<STRONG>char</STRONG> <STRONG>*slk_label(int</STRONG> <EM>labnum</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>slk_attron(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>slk_attroff(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>slk_attrset(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
- <STRONG>int</STRONG> <STRONG>slk_attr_on(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void*</STRONG> <EM>opts</EM><STRONG>);</STRONG>
- <STRONG>int</STRONG> <STRONG>slk_attr_off(const</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <EM>opts</EM><STRONG>);</STRONG>
- <STRONG>int</STRONG> <STRONG>slk_attr_set(const</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void*</STRONG> <EM>opts</EM><STRONG>);</STRONG>
+ <STRONG>int</STRONG> <STRONG>slk_attr_on(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
+ <STRONG>int</STRONG> <STRONG>slk_attr_off(const</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
+ <STRONG>int</STRONG> <STRONG>slk_attr_set(const</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void*</STRONG><EM>opts</EM><STRONG>);</STRONG>
<EM>/*</EM> <EM>extension</EM> <EM>*/</EM>
<STRONG>attr_t</STRONG> <STRONG>slk_attr(void);</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- The <STRONG>slk</STRONG>* functions manipulate the set of soft function-key labels that
- exist on many terminals. For those terminals that do not have soft
- labels, <EM>curses</EM> takes over the bottom line of <STRONG>stdscr</STRONG>, reducing the size
- of <STRONG>stdscr</STRONG> and the variable <STRONG>LINES</STRONG>. <EM>curses</EM> standardizes on eight labels
- of up to eight characters each. In addition to this, the <EM>ncurses</EM>
- implementation supports a mode where it simulates 12 labels of up to
- five characters each. This is useful for PC-like enduser devices.
- <EM>ncurses</EM> simulates this mode by taking over up to two lines at the
- bottom of the screen; it does not try to use any hardware support for
- this mode.
+ These functions manipulate the soft function key labels that some
+ hardware terminals support. For those terminals that do not have soft
+ labels, <EM>curses</EM> takes over the bottom line of <STRONG>stdscr</STRONG>, reducing its
+ vertical size and the value of <STRONG>LINES</STRONG> by one. By default, <EM>curses</EM> uses
+ eight labels of up to eight characters each.
+
+ <EM>ncurses</EM> furthermore supports a mode comprising twelve labels of up to
+ five characters each, following a convention associated with the IBM
+ PC/AT keyboard. <EM>ncurses</EM> simulates this mode by taking over up to two
+ lines at the bottom of the screen; it does not try to use any hardware
+ support for this mode.
</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
- The <STRONG>slk_init</STRONG> routine must be called before <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> is
- called. If <STRONG>initscr</STRONG> eventually uses a line from <STRONG>stdscr</STRONG> to emulate the
- soft labels, then <EM>fmt</EM> determines how the labels are arranged on the
- screen:
+ <STRONG>slk_init</STRONG> must be called before <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. If <STRONG>initscr</STRONG>
+ eventually uses a line from <STRONG>stdscr</STRONG> to emulate the soft labels, then <EM>fmt</EM>
+ determines how the labels are arranged on the screen.
- <STRONG>0</STRONG> indicates a 3-2-3 arrangement of the labels.
+ <STRONG>0</STRONG> indicates a 3-2-3 arrangement of the labels.
- <STRONG>1</STRONG> indicates a 4-4 arrangement
+ <STRONG>1</STRONG> indicates a 4-4 arrangement
- <STRONG>2</STRONG> indicates the PC-like 4-4-4 mode.
+ <STRONG>2</STRONG> indicates the PC-like 4-4-4 mode.
- <STRONG>3</STRONG> is again the PC-like 4-4-4 mode, but in addition an index line is
- generated, helping the user to identify the key numbers easily.
+ <STRONG>3</STRONG> is again the PC-like 4-4-4 mode, but in addition an index line is
+ generated, helping the user to associate each label with its
+ numbered function key. <STRONG>LINES</STRONG> and the vertical size of <STRONG>stdscr</STRONG> are
+ further reduced.
</PRE><H3><a name="h3-Labels">Labels</a></H3><PRE>
- The <STRONG>slk_set</STRONG> routine (and the <STRONG>slk_wset</STRONG> routine for the wide-character
- library) has three parameters:
+ Populate the labels with normal strings (<STRONG>slk_set</STRONG>) or wide-character
+ strings (<STRONG>slk_wset</STRONG>). Each function takes three parameters.
- <EM>labnum</EM>
- is the label number, from <STRONG>1</STRONG> to <STRONG>8</STRONG> (12 if <EM>fmt</EM> in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or
+ <EM>labnum</EM> is the label number, from <STRONG>1</STRONG> to <STRONG>8</STRONG> (12 if <EM>fmt</EM> in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or
<STRONG>3</STRONG>);
- <EM>label</EM>
- is be the string to put on the label, up to eight (five if <EM>fmt</EM>
- in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>) characters in length. A null string or
+ <EM>label</EM> is be the string to put on the label, up to eight (five if <EM>fmt</EM>
+ in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>) characters in length. A empty string or
a null pointer sets up a blank label.
- <EM>fmt</EM> is either <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, indicating whether the label is to be
- left-justified, centered, or right-justified, respectively,
- within the label.
+ <EM>align</EM> is <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, aligning <EM>label</EM> to the left, center, or right,
+ respectively, within the 8 (5) character cells housing it.
- The <STRONG>slk_label</STRONG> routine returns the current label for label number
- <EM>labnum</EM>, with leading and trailing blanks stripped.
+ <STRONG>slk_label</STRONG> obtains the string assigned to label number <EM>labnum</EM>, with any
+ leading and trailing blanks stripped.
-</PRE><H3><a name="h3-Screen-
updates">Screen updates</a></H3><PRE>
- The <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> routines correspond to the <STRONG>wrefresh</STRONG>
- and <STRONG>wnoutrefresh</STRONG> routines.
+</PRE><H3><a name="h3-Screen-
Updates">Screen Updates</a></H3><PRE>
+ <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> affect the soft key label lines as
+ <STRONG>wrefresh</STRONG> and <STRONG>wnoutrefresh</STRONG> do the <EM>curses</EM> window.
The <STRONG>slk_clear</STRONG> routine clears the soft labels from the screen.
- The <STRONG>slk_restore</STRONG> routine restores the soft labels to the screen after a
+ The <STRONG>slk_restore</STRONG> routine restores the soft labels to the screen after a
<STRONG>slk_clear</STRONG> has been performed.
- The <STRONG>slk_touch</STRONG> routine forces all the soft labels to be output the next
+ The <STRONG>slk_touch</STRONG> routine forces all the soft labels to be output the next
time a <STRONG>slk_noutrefresh</STRONG> is performed.
-</PRE><H3><a name="h3-Video-
attributes">Video attributes</a></H3><PRE>
- The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG> and <STRONG>slk_attr</STRONG> routines
- correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG> and <STRONG>attr_get</STRONG>, respectively.
- They have an effect only if soft labels are simulated on the bottom
- line of the screen. The default highlight for soft keys is A_STANDOUT
- (as in System V <EM>curses</EM>, which does not document this fact).
+</PRE><H3><a name="h3-Video-
Attributes">Video Attributes</a></H3><PRE>
+ The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attr</STRONG> routines
+ correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attr_get</STRONG>, respectively.
+ They have an effect only if soft labels are simulated on the bottom
+ line of the screen. The default highlight for soft key labels is
+ <STRONG>A_STANDOUT</STRONG> (as in System V <EM>curses</EM>, which does not document this fact).
</PRE><H3><a name="h3-Colors">Colors</a></H3><PRE>
- The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>. It has an effect only
+ The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>. It has an effect only
if soft labels are simulated on the bottom line of the screen.
- Because <STRONG>slk_color</STRONG> accepts only <STRONG>short</STRONG> (signed 16-bit integer) values,
- this implementation provides <STRONG>extended_slk_color</STRONG> which accepts an
- integer value, e.g., 32-bits.
+ Because <STRONG>slk_color</STRONG> accepts only <EM>short</EM> (signed 16-bit integer) values,
+ this implementation provides <STRONG>extended_slk_color</STRONG>, which accepts an <EM>int</EM>
+ value of at least 32 bits.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- These routines return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 specifies only "an
- integer value other than <STRONG>ERR</STRONG>") upon successful completion.
+ Routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
+ specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ completion.
+
+ X/Open Curses defines no error conditions.
- X/Open defines no error conditions. In this implementation
+ In this implementation
<STRONG>slk_attr</STRONG>
returns the attribute used for the soft keys.
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
- X/Open <EM>curses</EM> documents the <EM>opts</EM> argument as reserved for future use,
+ X/Open Curses documents the <EM>opts</EM> argument as reserved for future use,
saying that it must be null. This implementation uses that parameter
- in ABI 6 for the functions which have a color-pair parameter to support
+ in ABI 6 for the functions which have a color pair parameter to support
extended color pairs.
- For functions which modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM> is
- set it is treated as a pointer to <STRONG>int</STRONG>, and used to set the color
- pair instead of the <STRONG>short</STRONG> pair parameter.
+ For functions which modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM> is
+ set it is treated as a pointer to <EM>int</EM>, and used to set the color pair
+ instead of the <EM>short</EM> pair parameter.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- The XSI <EM>curses</EM> standard, Issue 4, described the soft-key functions,
- with some differences from SVr4 <EM>curses</EM>:
+ X/Open Curses, Issue 4, describes these functions, with some
+ differences from SVr4 <EM>curses</EM>:
- <STRONG>o</STRONG> It added functions like the SVr4 attribute-manipulation functions
- <STRONG>slk_attron</STRONG>, <STRONG>slk_attroff</STRONG>, <STRONG>slk_attrset</STRONG>, but which use <STRONG>attr_t</STRONG>
- parameters (rather than <STRONG>chtype</STRONG>), along with a reserved <EM>opts</EM>
+ <STRONG>o</STRONG> X/Open added functions like the SVr4 attribute-manipulation
+ functions <STRONG>slk_attron</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attrset</STRONG>, but which use
+ <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> parameters (rather than <EM>chtype</EM>), along with a reserved <EM>opts</EM>
parameter.
Two of these new functions (unlike the SVr4 functions) have no
provision for color: <STRONG>slk_attr_on</STRONG> and <STRONG>slk_attr_off</STRONG>.
- The third function (<STRONG>slk_attr_set</STRONG>) has a color-pair parameter.
+ The third function (<STRONG>slk_attr_set</STRONG>) has a color pair parameter.
- <STRONG>o</STRONG> It added <STRONG>const</STRONG> qualifiers to parameters (unnecessarily), and
+ <STRONG>o</STRONG> It added <EM>const</EM> qualifiers to parameters (unnecessarily), and
<STRONG>o</STRONG> It added <STRONG>slk_color</STRONG>.
The function <STRONG>slk_attr</STRONG> was added by <EM>ncurses</EM> in 1996.
- X/Open <EM>curses</EM> does not specify a limit for the number of colors and
- color pairs which a terminal can support. However, in its use of <STRONG>short</STRONG>
+ X/Open Curses does not specify a limit for the number of colors and
+ color pairs which a terminal can support. However, in its use of <EM>short</EM>
for the parameters, it carries over SVr4's implementation detail for
the compiled terminfo database, which uses signed 16-bit numbers. This
implementation provides extended versions of those functions which use
- <STRONG>int</STRONG> parameters, allowing applications to use larger color- and pair-
+ <EM>int</EM> parameters, allowing applications to use larger color- and pair-
numbers.
<STRONG>slk_attrset</STRONG>
<STRONG>slk_start</STRONG>
- X/Open <EM>curses</EM> added these:
+ X/Open Curses added these:
<STRONG>slk_attr_off</STRONG>
<STRONG>slk_attr_on</STRONG>
<STRONG>slk_attr_set</STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<ul>
<li><a href="#h3-Initialization">Initialization</a></li>
<li><a href="#h3-Labels">Labels</a></li>
-<li><a href="#h3-Screen-updates">Screen updates</a></li>
-<li><a href="#h3-Video-attributes">Video attributes</a></li>
+<li><a href="#h3-Screen-Updates">Screen Updates</a></li>
+<li><a href="#h3-Video-Attributes">Video Attributes</a></li>
<li><a href="#h3-Colors">Colors</a></li>
</ul>
</li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_sp_funcs.3x,v 1.44 2023/11/25 15:48:03 tom Exp @
+ * @Id: curs_sp_funcs.3x,v 1.45 2023/12/16 20:32:22 tom Exp @
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
<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_sp_funcs 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_sp_funcs 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_sp_funcs 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_sp_funcs 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
This implementation can be configured to provide a set of functions
which improve the ability to manage multiple screens. This feature can
- be added to any of the configurations supported by ncurses; it adds new
+ be added to any of the configurations supported by <EM>ncurses</EM>; it adds new
entrypoints without changing the meaning of any of the existing ones.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines are specific to ncurses. They were not supported on
+ These routines are specific to <EM>ncurses</EM>. They were not supported on
Version 7, BSD or System V implementations. It is recommended that any
- code depending on ncurses extensions be conditioned using
+ code depending on <EM>ncurses</EM> extensions be conditioned using
<EM>NCURSES</EM><STRONG>_</STRONG><EM>SP</EM><STRONG>_</STRONG><EM>FUNCS</EM>.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(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.74 2023/12/02 20:49:04 tom Exp @
+ * @Id: curs_termcap.3x,v 1.76 2023/12/18 00:22:30 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
+ * for much BSD release history.
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s7/ttycap.c
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/man7/ttycap.7
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/termlib/
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/bin/etc/termcap
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/lib/\
+ * libtermlib/
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/man/man3/\
+ * termlib.3
+ * ...except in the source tree...
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+ * libtermlib/makefile
+ * Observe the `tncktc()`, `tnamatch()`, `tskip()`, and `tdecode()`
+ * entry points disappearing from termcap.c.
+ * 2BSD became a branch retaining support for non-virtual memory
+ * systems (like the PDP-11) whereas most BSD development focused on
+ * the VAX and other VM-enabled systems starting with 3BSD.
+ * This man page previously located a termcap.h in 2BSD, but that may
+ * be confusion arising from its backport to 2.9BSD (and still present
+ * in surviving sources for 2.11BSD, the "end of the line" for that
+ * branch's development).
+ * Observe the copyright notice in
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD/usr/contrib/\
+ * jove/Makefile
+ * --much too late for 2BSD (1979).
-->
<!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_termcap 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_termcap 3x 2023-12-17 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-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_termcap 3x 2023-12-17 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>
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
<STRONG>#include</STRONG> <STRONG><term.h></STRONG>
- <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>PC;</STRONG>
- <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>UP;</STRONG>
- <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>BC;</STRONG>
- <STRONG>extern</STRONG> <STRONG>short</STRONG> <STRONG>ospeed;</STRONG>
+ <STRONG>char</STRONG> <STRONG>PC;</STRONG>
+ <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>UP;</STRONG>
+ <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>BC;</STRONG>
+ <STRONG>short</STRONG> <STRONG>ospeed;</STRONG>
<STRONG>int</STRONG> <STRONG>tgetent(char</STRONG> <STRONG>*</STRONG><EM>bp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>name</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>tgetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>id</EM><STRONG>);</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- These routines are included as a conversion aid for programs that use
- the <EM>termcap</EM> library. Their parameters are the same, but the routines
- are emulated using the <EM>terminfo</EM> database. Thus, they can only be used
- to query the capabilities of entries for which a terminfo entry has
- been compiled.
+ <EM>ncurses</EM> provides the foregoing variables and functions as a
+ compatibility layer for programs that use the <EM>termcap</EM> library. The API
+ is the same, but behavior is emulated using the <EM>terminfo</EM> database.
+ Thus, it can be used only to query the capabilities of terminal
+ database entries for which a <EM>terminfo</EM> entry has been compiled.
</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
- The <STRONG>tgetent</STRONG> routine loads the entry for <EM>name</EM>. It returns:
+ <STRONG>tgetent</STRONG> loads the terminal database entry for <EM>name</EM>; see <STRONG><A HREF="term.7.html">term(7)</A></STRONG>. This
+ must be done before calling any of the other functions. It returns:
- 1 on success,
+ 1 on success,
- 0 if there is no such entry (or that it is a generic type, having
- too little information for curses applications to run), and
+ 0 if there is no such entry (or if the matching entry describes a
+ generic terminal, having too little information for <EM>curses</EM>
+ applications to run), and
- -1 if the terminfo database could not be found.
+ -1 if the <EM>terminfo</EM> database could not be found.
- This differs from the <EM>termcap</EM> library in two ways:
+ This implementation differs from those of historical <EM>termcap</EM> libraries.
- <STRONG>o</STRONG> The emulation ignores the buffer pointer <EM>bp</EM>. The <EM>termcap</EM>
- library would store a copy of the terminal description in the
- area referenced by this pointer. However, ncurses stores its
- terminal descriptions in compiled binary form, which is not the
- same thing.
+ <STRONG>o</STRONG> <EM>ncurses</EM> ignores the buffer pointer <EM>bp</EM>, as do other <EM>termcap</EM>
+ implementations conforming to portions of X/Open Curses now
+ withdrawn. The BSD <EM>termcap</EM> library would store a copy of the
+ terminal type description in the area referenced by this
+ pointer. <EM>ncurses</EM> stores terminal type descriptions in compiled
+ form, which is not the same thing.
- <STRONG>o</STRONG> There is a difference in return codes. The <EM>termcap</EM> library does
- not check if the terminal description is marked with the <EM>generic</EM>
- capability, or if the terminal description has cursor-
- addressing.
+ <STRONG>o</STRONG> The meanings of the return values differ. The BSD <EM>termcap</EM>
+ library does not check whether the terminal type description is
+ marked with the <STRONG>gn</STRONG> (<STRONG>generic</STRONG>) capability, nor whether the
+ terminal type description supports an addressable cursor, a
+ property essential for any <EM>curses</EM> implementation to operate.
-</PRE><H3><a name="h3-Capability-Values">Capability Values</a></H3><PRE>
- The <STRONG>tgetflag</STRONG> routine gets the boolean entry for <EM>id</EM>, or zero if it is
- not available.
-
- The <STRONG>tgetnum</STRONG> routine gets the numeric entry for <EM>id</EM>, or -1 if it is not
+</PRE><H3><a name="h3-Retrieving-Capability-Values">Retrieving Capability Values</a></H3><PRE>
+ <STRONG>tgetflag</STRONG> reports the Boolean entry for <EM>id</EM>, or zero if it is not
available.
- The <STRONG>tgetstr</STRONG> routine returns the string entry for <EM>id</EM>, or zero if it is
- not available. Use <STRONG>tputs</STRONG> to output the returned string. The <EM>area</EM>
- parameter is used as follows:
+ <STRONG>tgetnum</STRONG> obtains the numeric entry for <EM>id</EM>, or -1 if it is not available.
+
+ <STRONG>tgetstr</STRONG> returns the string entry for <EM>id</EM>, or <STRONG>NULL</STRONG> if it is not
+ available. Use <STRONG>tputs</STRONG> to output the string returned. The <EM>area</EM>
+ parameter is used as follows.
<STRONG>o</STRONG> It is assumed to be the address of a pointer to a buffer managed
by the calling application.
- <STRONG>o</STRONG> However, ncurses checks to ensure that <STRONG>area</STRONG> is not NULL, and
- also that the resulting buffer pointer is not NULL. If either
- check fails, the <EM>area</EM> parameter is ignored.
+ <STRONG>o</STRONG> However, <EM>ncurses</EM> checks to ensure that <EM>area</EM> is not <STRONG>NULL</STRONG>, and
+ also that the resulting buffer pointer is not <STRONG>NULL</STRONG>. If either
+ check fails, <EM>area</EM> is ignored.
- <STRONG>o</STRONG> If the checks succeed, ncurses also copies the return value to
- the buffer pointed to by <EM>area</EM>, and the <EM>area</EM> value will be
- updated to point past the null ending this value.
+ <STRONG>o</STRONG> If the checks succeed, <EM>ncurses</EM> also copies the return value to
+ the buffer pointed to by <EM>area</EM>, and the library updates <EM>area</EM> to
+ point past the null character terminating this value.
- <STRONG>o</STRONG> The return value itself is an address in the terminal
- description which is loaded into memory.
+ <STRONG>o</STRONG> The return value itself is an address in the terminal type
+ description loaded into memory.
- Only the first two characters of the <STRONG>id</STRONG> parameter of <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>
- and <STRONG>tgetstr</STRONG> are compared in lookups.
+</PRE><H3><a name="h3-Applying-String-Capabilities">Applying String Capabilities</a></H3><PRE>
+ String capabilities can be parameterized; see subsection "Parameterized
+ Strings" in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. <STRONG>tgoto</STRONG> applies its second and third arguments
+ to the parametric placeholders in the capability stored in the first
+ argument.
-</PRE><H3><a name="h3-Formatting-Capabilities">Formatting Capabilities</a></H3><PRE>
- The <STRONG>tgoto</STRONG> routine expands the given capability using the parameters.
-
- <STRONG>o</STRONG> Because the capability may have padding characters, the output of
- <STRONG>tgoto</STRONG> should be passed to <STRONG>tputs</STRONG> rather than some other output
- function such as <STRONG>printf(3)</STRONG>.
+ <STRONG>o</STRONG> The capability may contain padding specifications; see subsection
+ "Delays and Padding" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. The output of <STRONG>tgoto</STRONG> should
+ thus be passed to <STRONG>tputs</STRONG> rather than some other output function such
+ as <STRONG>printf(3)</STRONG>.
<STRONG>o</STRONG> While <STRONG>tgoto</STRONG> is assumed to be used for the two-parameter cursor
- positioning capability, termcap applications also use it for
+ positioning capability, <EM>termcap</EM> applications also use it for
single-parameter capabilities.
- Doing this shows a quirk in <STRONG>tgoto</STRONG>: most hardware terminals use
+ Doing so reveals a quirk in <STRONG>tgoto</STRONG>: most hardware terminals use
cursor addressing with <EM>row</EM> first, but the original developers of
- the termcap interface chose to put the <EM>column</EM> parameter first. The
- <STRONG>tgoto</STRONG> function swaps the order of parameters. It does this also
- for calls requiring only a single parameter. In that case, the
- first parameter is merely a placeholder.
+ the <EM>termcap</EM> interface chose to put the <EM>col</EM> (column) parameter
+ first. The <STRONG>tgoto</STRONG> function swaps the order of parameters. It does
+ this even for calls requiring only a single parameter. In that
+ case, the first parameter is merely a placeholder.
- <STRONG>o</STRONG> Normally the ncurses library is compiled with terminfo support. In
- that case, <STRONG>tgoto</STRONG> uses an internal version of <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> (a more
- capable formatter).
+ <STRONG>o</STRONG> Normally the <EM>ncurses</EM> library is compiled without full <EM>termcap</EM>
+ support. In that case, <STRONG>tgoto</STRONG> uses an internal version of <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>
+ (a more capable function).
- With terminfo support, <STRONG>tgoto</STRONG> is able to use some of the terminfo
- features, but not all. In particular, it allows only numeric
+ Because it uses <STRONG>tparm</STRONG> internally, <STRONG>tgoto</STRONG> is able to use some <EM>term-</EM>
+ <EM>info</EM> features, but not all. In particular, it allows only numeric
parameters; <STRONG>tparm</STRONG> supports string parameters.
However, <STRONG>tparm</STRONG> is not a <EM>termcap</EM> feature, and portable <EM>termcap</EM>
applications should not rely upon its availability.
- The <STRONG>tputs</STRONG> routine is described on the <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> manual page.
- It can retrieve capabilities by either termcap or terminfo name.
+ <STRONG>tputs</STRONG> is described in <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>. It can retrieve capabilities
+ by either <EM>termcap</EM> or <EM>terminfo</EM> name.
</PRE><H3><a name="h3-Global-Variables">Global Variables</a></H3><PRE>
- The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the terminfo entry's
+ The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the <EM>terminfo</EM> entry's
data for <STRONG>pad_char</STRONG>, <STRONG>cursor_up</STRONG> and <STRONG>backspace_if_not_bs</STRONG>, respectively. <STRONG>UP</STRONG>
- is not used by ncurses. <STRONG>PC</STRONG> is used in the <STRONG>tdelay_output</STRONG> function. <STRONG>BC</STRONG>
- is used in the <STRONG>tgoto</STRONG> emulation. The variable <STRONG>ospeed</STRONG> is set by ncurses
- in a system-specific coding to reflect the terminal speed.
+ is not used by <EM>ncurses</EM>. <STRONG>PC</STRONG> is used by <STRONG><A HREF="curs_util.3x.html">delay_output(3x)</A></STRONG>. <STRONG>BC</STRONG> is used by
+ <STRONG>tgoto</STRONG> emulation. The variable <STRONG>ospeed</STRONG> is set by <EM>ncurses</EM> using a system-
+ specific encoding to indicate the terminal's data rate.
</PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE>
- The termcap functions provide no means for freeing memory, because
- legacy termcap implementations used only the buffer areas provided by
- the caller via <STRONG>tgetent</STRONG> and <STRONG>tgetstr</STRONG>. Those buffers are unused in
- terminfo.
+ The <EM>termcap</EM> functions provide no means of freeing memory, because
+ legacy <EM>termcap</EM> implementations used only the buffer areas provided by
+ the caller via <STRONG>tgetent</STRONG> and <STRONG>tgetstr</STRONG>. Those buffers are unused in <EM>term-</EM>
+ <EM>info</EM>.
+
+ By contrast, <EM>terminfo</EM> allocates memory. It uses <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to
+ obtain the data used by <STRONG>tgetent</STRONG> and the functions that retrieve
+ capability values. One could use
+ del_curterm(cur_term);
+ to free this memory, but there is an additional complication with
+ <EM>ncurses</EM>. It uses a fixed-size pool of storage locations, one per value
+ of the <EM>TERM</EM> environment variable when <STRONG>tgetent</STRONG> is called. The <STRONG>screen(1)</STRONG>
+ program relies upon this arrangement to improve its performance.
- On the other hand, terminfo allocates memory. It uses <STRONG>setupterm</STRONG> to
- retrieve the data used by <STRONG>tgetent</STRONG> and the functions which return
- capability values such as <STRONG>tgetstr</STRONG>. One could use
+ An application that uses only the <EM>termcap</EM> functions, not the higher
+ level <EM>curses</EM> API, could release the memory using <STRONG><A HREF="curs_terminfo.3x.html">del_curterm(3x)</A></STRONG>,
+ because the pool is freed using other functions; see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>.
- <STRONG>del_curterm(cur_term);</STRONG>
+</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
+ The return values of <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>, <STRONG>tgetname</STRONG>, and <STRONG>tgetstr</STRONG> are
+ documented above.
- to free this memory, but there is an additional complication with
- ncurses. It uses a fixed-size <EM>pool</EM> of storage locations, one per
- setting of the <EM>TERM</EM> variable when <STRONG>tgetent</STRONG> is called. The <STRONG>screen(1)</STRONG>
- program relies upon this arrangement, to improve its performance.
+ <STRONG>tgoto</STRONG> returns <STRONG>NULL</STRONG> on error. Error conditions include:
- An application which uses only the low-level termcap functions could
- free the memory using <STRONG>del_curterm</STRONG>, because the pool is freed using
- other functions (see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>).
+ <STRONG>o</STRONG> uninitialized state (<STRONG>tgetent</STRONG> was not called successfully),
+ <STRONG>o</STRONG> <EM>cap</EM> being a null pointer,
-</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Except where explicitly noted, routines that return an integer return
- <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 only specifies "an integer value other
- than <STRONG>ERR</STRONG>") upon successful completion.
+ <STRONG>o</STRONG> <EM>cap</EM> referring to a canceled capability,
- Routines that return pointers return <STRONG>NULL</STRONG> on error.
+ <STRONG>o</STRONG> <EM>cap</EM> being a capability with string-valued parameters (a <EM>term-</EM>
+ <EM>info</EM>-only feature), and
- A few special cases apply:
+ <STRONG>o</STRONG> <EM>cap</EM> being a capability with more than two parameters.
- <STRONG>o</STRONG> If the terminal database has not been initialized, these return an
- error.
+ See <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> regarding <STRONG>tputs</STRONG>.
- <STRONG>o</STRONG> The calls with a string parameter (<STRONG>tgoto</STRONG>, <STRONG>tputs</STRONG>) check if the
- string is null, or cancelled. Those return an error.
- <STRONG>o</STRONG> A call to <STRONG>tgoto</STRONG> using a capability with string parameters is an
- error.
-
- <STRONG>o</STRONG> A call to <STRONG>tgoto</STRONG> using a capability with more than two parameters is
- an error.
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+ <EM>ncurses</EM> compares only the first two characters of the <EM>id</EM> parameter of
+ <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>, and <STRONG>tgetstr</STRONG> to the capability names in the database.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+ These functions are no longer standardized (and the variables never
+ were); <EM>ncurses</EM> provides them to support legacy applications. They
+ should not be used in new programs.
-</PRE><H3><a name="h3-Standards">Standards</a></H3><PRE>
- These functions are provided for supporting legacy applications, and
- should not be used in new programs:
- <STRONG>o</STRONG> The XSI Curses standard, Issue 4 describes these functions.
- However, they are marked TO BE WITHDRAWN and may be removed in
- future versions.
+</PRE><H3><a name="h3-Standards">Standards</a></H3><PRE>
+ <STRONG>o</STRONG> X/Open Curses, Issue 4, Version 2 (1996), describes these
+ functions. However, they are marked "TO BE WITHDRAWN".
- <STRONG>o</STRONG> X/Open Curses, Issue 5 (December 2007) marked the termcap interface
- (along with <STRONG>vwprintw</STRONG> and <STRONG>vwscanw</STRONG>) as withdrawn.
+ <STRONG>o</STRONG> X/Open Curses, Issue 7 (2009) marked the <EM>termcap</EM> interface (along
+ with <STRONG>vwprintw</STRONG> and <STRONG>vwscanw</STRONG>) as withdrawn.
- Neither the XSI Curses standard nor the SVr4 man pages documented the
- return values of <STRONG>tgetent</STRONG> correctly, though all three were in fact
- returned ever since SVr1. In particular, an omission in the XSI Curses
- documentation has been misinterpreted to mean that <STRONG>tgetent</STRONG> returns <STRONG>OK</STRONG>
+ Neither X/Open Curses nor the SVr4 man pages documented the return
+ values of <STRONG>tgetent</STRONG> correctly, though all three were in fact returned
+ ever since SVr1. In particular, an omission in the X/Open Curses
+ specification has been misinterpreted to mean that <STRONG>tgetent</STRONG> returns <STRONG>OK</STRONG>
or <STRONG>ERR</STRONG>. Because the purpose of these functions is to provide
- compatibility with the <EM>termcap</EM> library, that is a defect in XCurses,
- Issue 4, Version 2 rather than in ncurses.
-
-
-</PRE><H3><a name="h3-Compatibility-with-BSD-Termcap">Compatibility with BSD Termcap</a></H3><PRE>
- External variables are provided for support of certain termcap
- applications. However, termcap applications' use of those variables is
- poorly documented, e.g., not distinguishing between input and output.
- In particular, some applications are reported to declare and/or modify
- <STRONG>ospeed</STRONG>.
-
- The comment that only the first two characters of the <STRONG>id</STRONG> parameter are
- used escapes many application developers. The original BSD 4.2 termcap
- library (and historical relics thereof) did not require a trailing null
- NUL on the parameter name passed to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetflag</STRONG>.
- Some applications assume that the termcap interface does not require
- the trailing NUL for the parameter name. Taking into account these
- issues:
-
- <STRONG>o</STRONG> As a special case, <STRONG>tgetflag</STRONG> matched against a single-character
- identifier provided that was at the end of the terminal
- description. You should not rely upon this behavior in portable
- programs. This implementation disallows matches against single-
- character capability names.
-
- <STRONG>o</STRONG> This implementation disallows matches by the termcap interface
- against extended capability names which are longer than two
- characters.
-
- The BSD termcap function <STRONG>tgetent</STRONG> returns the text of a termcap entry in
- the buffer passed as an argument. This library (like other terminfo
- implementations) does not store terminal descriptions as text. It sets
- the buffer contents to a null-terminated string.
-
-
-</PRE><H3><a name="h3-Other-Compatibility">Other Compatibility</a></H3><PRE>
- This library includes a termcap.h header, for compatibility with other
- implementations. But the header is rarely used because the other
+ compatibility with the <EM>termcap</EM> library, that is a defect in X/Open
+ Curses, Issue 4, Version 2 rather than in <EM>ncurses</EM>.
+
+ <STRONG>Compatibility</STRONG> <STRONG>with</STRONG> <STRONG>BSD</STRONG> <EM>termcap</EM>
+ Externally visible variables are provided for support of certain
+ <EM>termcap</EM> applications. However, their correct usage is poorly
+ documented; for example, it is unclear when reading and writing them is
+ meaningful. In particular, some applications are reported to declare
+ and/or modify <STRONG>ospeed</STRONG>.
+
+ The constraint that only the first two characters of the <EM>id</EM> parameter
+ are used escapes many application developers. The BSD <EM>termcap</EM> library
+ did not require a trailing null character on the capability identifier
+ passed to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG>, and <STRONG>tgetflag</STRONG>. Some applications thus
+ assume that the <EM>termcap</EM> interface does not require the trailing null
+ character for the capability identifier.
+
+ <STRONG>o</STRONG> <EM>ncurses</EM> disallows matches by the <EM>termcap</EM> interface against extended
+ capability names that are longer than two characters; see
+ <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>.
+
+ The BSD <EM>termcap</EM> function <STRONG>tgetent</STRONG> returns the text of a <EM>termcap</EM> entry in
+ the buffer passed as an argument. This library, like other <EM>terminfo</EM>
+ implementations, does not store terminal type descriptions as text. It
+ sets the buffer contents to a null-terminated string.
+
+
+</PRE><H3><a name="h3-Header-File">Header File</a></H3><PRE>
+ This library includes a <EM>termcap.h</EM> header for compatibility with other
+ implementations, but the header is rarely used because the other
implementations are not strictly compatible.
- The original BSD termcap (through 4.3BSD) had no header file which gave
- function prototypes, because that was a feature of ANSI C. BSD termcap
- was written several years before C was standardized. However, there
- were two different termcap.h header files in the BSD sources:
- <STRONG>o</STRONG> One was used internally by the <STRONG>jove</STRONG> editor in 2BSD through 4.4BSD.
- It defined global symbols for the termcap variables which it used.
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+ Bill Joy originated a forerunner of <EM>termcap</EM> called "ttycap", dated
+ September 1977, and released in 1BSD (March 1978). It used many of the
+ same function names as the later <EM>termcap</EM>, such as <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>,
+ <STRONG>tgetnum</STRONG>, and <STRONG>tgetstr</STRONG>.
+
+ A clear descendant, the <EM>termlib</EM> library, followed in 2BSD (May 1979),
+ adding <STRONG>tgoto</STRONG> and <STRONG>tputs</STRONG>. The former applied at that time only to cursor
+ positioning capabilities, thus the overly specific name. Little
+ changed in 3BSD (late 1979) except the addition of test programs and a
+ <EM>termlib</EM> man page, which documented the API shown in section "SYNOPSIS"
+ above.
+
+ 4BSD (November 1980) renamed <EM>termlib</EM> to <EM>termcap</EM> and added another test
+ program. The library remained much the same though 4.3BSD (June 1986).
+ 4.4BSD-Lite (June 1994) refactored it but left the API unchanged.
+
+ Function prototypes were a feature of the forthcoming ANSI C (1989).
+ Thus the library provided no header file declaring them. Nevertheless,
+ the BSD sources included two different <EM>termcap.h</EM> header files over
+ time.
- <STRONG>o</STRONG> The other appeared in 4.4BSD Lite Release 2 (mid-1993) as part of
- <EM>libedit</EM> (also known as the <EM>editline</EM> library). The 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.
+ <STRONG>o</STRONG> One was used internally by <STRONG>jove(1)</STRONG> from 4.3BSD onward. It delcared
+ global symbols for the <EM>termcap</EM> variables that it used.
- The header file from <EM>libedit</EM> was added to NetBSD's termcap library in
- mid-1994.
+ <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 termcap was under development, starting in 1990. The
- first release (termcap 1.0) in 1991 included a termcap.h header. The
- second release (termcap 1.1) in September 1992 modified the header to
- use <STRONG>const</STRONG> for the function prototypes in the header where one would
- expect the parameters to be read-only. This was a difference versus
- the original BSD termcap. The prototype for <STRONG>tputs</STRONG> also differed, but
- in that instance, it was <EM>libedit</EM> which differed from BSD termcap.
+ 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
+ <EM>termcap</EM>.
- A copy of GNU termcap 1.3 was bundled with <EM>bash</EM> in mid-1993, to support
- the <STRONG>readline(3)</STRONG> library.
+ GNU <EM>termcap</EM> 1.3 was bundled with <EM>bash</EM> in mid-1993 to support the
+ <STRONG>readline(3)</STRONG> library.
- A termcap.h file was provided in ncurses 1.8.1 (November 1993). That
- reflected influence by <STRONG>emacs(1)</STRONG> (rather than <STRONG>jove(1)</STRONG>) and GNU termcap:
+ <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> it provided declarations for a few global symbols used by <STRONG>emacs</STRONG>
+ <STRONG>o</STRONG> global symbols used by <EM>emacs</EM>,
- <STRONG>o</STRONG> it provided function prototypes (using <STRONG>const</STRONG>).
+ <STRONG>o</STRONG> <EM>const</EM>-qualified function prototypes, and
- <STRONG>o</STRONG> a prototype for <STRONG>tparam</STRONG> (a GNU termcap feature) was provided.
+ <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 ncurses. As a
- result, there are differences between any of the four implementations,
- which must be taken into account by programs which can work with all
- termcap library interfaces.
+ 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>ca</STRONG> or any other parameterized string
- capability, be aware that it is returned in <EM>terminfo</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. (The <STRONG>tgoto</STRONG> function,
- if configured to support <EM>termcap,</EM> checks if the string is indeed
- <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
+ If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>ca</STRONG> or any other parameterized string
+ capability, be aware that it is returned in <EM>terminfo</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>term-</EM>
+ <EM>info</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>term-</EM>
+ <EM>info</EM> syntax.)
+
+ 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>sgr</STRONG> string. One
- consequence is that <EM>termcap</EM> applications assume that <STRONG>me</STRONG> (equivalent to
- <EM>terminfo</EM>'s <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.
+ <EM>termcap</EM> has nothing analogous to <EM>terminfo</EM>'s <STRONG>sgr</STRONG> string. One
+ consequence is that <EM>termcap</EM> applications assume that "<STRONG>me</STRONG>" (equivalent
+ to <EM>terminfo</EM>'s <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.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="ncurses.3x.html">curses(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>
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG>
<A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
https://invisible-island.net/ncurses/tctest.html
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
+ncurses 6.4 2023-12-
17 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-Initialization">Initialization</a></li>
-<li><a href="#h3-Capability-Values">Capability Values</a></li>
-<li><a href="#h3-Formatting-Capabilities">Formatting Capabilities</a></li>
+<li><a href="#h3-Retrieving-Capability-Values">Retrieving Capability Values</a></li>
+<li><a href="#h3-Applying-String-Capabilities">Applying String Capabilities</a></li>
<li><a href="#h3-Global-Variables">Global Variables</a></li>
<li><a href="#h3-Releasing-Memory">Releasing Memory</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
+<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
<li><a href="#h3-Standards">Standards</a></li>
-<li><a href="#h3-Compatibility-with-BSD-Termcap">Compatibility with BSD Termcap</a></li>
-<li><a href="#h3-Other-Compatibility">Other Compatibility</a></li>
+<li><a href="#h3-Header-File">Header File</a></li>
</ul>
</li>
+<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-BUGS">BUGS</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_terminfo.3x,v 1.122 2023/12/03 00:10:20 tom Exp @
+ * @Id: curs_terminfo.3x,v 1.123 2023/12/16 21:11:53 tom Exp @
* ***************************************************************************
* ***************************************************************************
* ***************************************************************************
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
-<TITLE>curs_terminfo 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_terminfo 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_terminfo 3x 2023-12-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_terminfo 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
<STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>restartterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
- <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
- <EM>or</EM>
- <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>long</STRONG> <EM>p1</EM> <EM>...</EM> <STRONG>long</STRONG> <EM>p9</EM><STRONG>);</STRONG>
+ <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG>
+ <EM>/*</EM> <EM>or</EM> <EM>*/</EM>
+ <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>long</STRONG> <EM>p1</EM> ... <STRONG>long</STRONG> <EM>p9</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
<STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
<STRONG>char</STRONG> <STRONG>*tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG>
- <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
+ <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG>
<EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
<STRONG>char</STRONG> <STRONG>*tiparm_s(int</STRONG> <EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
<STRONG>o</STRONG> <EM>attrs</EM> of type <STRONG>attr_t</STRONG> for the attributes and
- <STRONG>o</STRONG> <EM>pair</EM> of type <STRONG>short</STRONG> for the color-pair number.
+ <STRONG>o</STRONG> <EM>pair</EM> of type <STRONG>short</STRONG> for the color pair number.
The <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> routines are designed to use the attribute
constants with the <STRONG>WA_</STRONG> prefix.
The formatting functions <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> extend the storage allocated
by <STRONG>setupterm</STRONG>:
- <STRONG>o</STRONG> the "static" terminfo variables [a-z]. Before ncurses 6.3, those
- were shared by all screens. With ncurses 6.3, those are allocated
+ <STRONG>o</STRONG> the "static" terminfo variables [a-z]. Before <EM>ncurses</EM> 6.3, those
+ were shared by all screens. With <EM>ncurses</EM> 6.3, those are allocated
per screen. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for details.
- <STRONG>o</STRONG> to improve performance, ncurses 6.3 caches the result of analyzing
+ <STRONG>o</STRONG> to improve performance, <EM>ncurses</EM> 6.3 caches the result of analyzing
terminfo strings for their parameter types. That is stored as a
binary tree referenced from the <STRONG>TERMINAL</STRONG> structure.
non-portable. All other functions are as described by X/Open.
-</PRE><H3><a name="h3-Compatibility-
macros">Compatibility macros</a></H3><PRE>
+</PRE><H3><a name="h3-Compatibility-
Macros">Compatibility Macros</a></H3><PRE>
This implementation provides a few macros for compatibility with
systems before SVr4 (see <EM>HISTORY</EM>). Those include <STRONG>crmode</STRONG>, <STRONG>fixterm</STRONG>,
<STRONG>gettmode</STRONG>, <STRONG>nocrmode</STRONG>, <STRONG>resetterm</STRONG>, <STRONG>saveterm</STRONG>, and <STRONG>setterm</STRONG>.
those symbols as macros for BSD compatibility.
-</PRE><H3><a name="h3-Legacy-
data">Legacy data</a></H3><PRE>
+</PRE><H3><a name="h3-Legacy-
Data">Legacy Data</a></H3><PRE>
<STRONG>setupterm</STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>. This is not
part of X/Open Curses, but is assumed by some applications.
stored in the arrays described here.
-</PRE><H3><a name="h3-Output-
buffering">Output buffering</a></H3><PRE>
- Older versions of <STRONG>ncurses</STRONG> assumed that the file descriptor passed to
+</PRE><H3><a name="h3-Output-
Buffering">Output Buffering</a></H3><PRE>
+ Older versions of <EM>ncurses</EM> assumed that the file descriptor passed to
<STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered I/O, and would write to
the corresponding stream. In addition to the limitation that the
terminal was left in block-buffered mode on exit (like System V
- curses), it was problematic because <STRONG>ncurses</STRONG> did not allow a reliable
+ curses), it was problematic because <EM>ncurses</EM> did not allow a reliable
way to cleanup on receiving SIGTSTP.
The current version (ncurses6) uses output buffers managed directly by
- <STRONG>ncurses</STRONG>. Some of the low-level functions described in this manual page
+ <EM>ncurses</EM>. Some of the low-level functions described in this manual page
write to the standard output. They are not signal-safe. The high-
- level functions in <STRONG>ncurses</STRONG> use alternate versions of these functions
+ level functions in <EM>ncurses</EM> use alternate versions of these functions
using the more reliable buffering scheme.
-</PRE><H3><a name="h3-Function-
prototypes">Function prototypes</a></H3><PRE>
+</PRE><H3><a name="h3-Function-
Prototypes">Function Prototypes</a></H3><PRE>
The X/Open Curses prototypes are based on the SVr4 curses header
declarations, which were defined at the same time the C language was
first standardized in the late 1980s.
In response to review comments by Thomas E. Dickey, X/Open Curses
Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009.
- While <STRONG>tiparm</STRONG> is always provided in ncurses, the older form is only
+ While <STRONG>tiparm</STRONG> is always provided in <EM>ncurses</EM>, the older form is only
available as a build-time configuration option. If not specially
configured, <STRONG>tparm</STRONG> is the same as <STRONG>tiparm</STRONG>.
parameters. However, only a few terminfo capabilities use string
parameters (e.g., the ones used for programmable function keys).
- The ncurses library checks usage of these capabilities, and returns
+ The <EM>ncurses</EM> library checks usage of these capabilities, and returns
an error if the capability mishandles string parameters. But it
cannot check if a calling program provides strings in the right
places for the <STRONG>tparm</STRONG> calls.
The <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> program checks its use of these capabilities with a
table, so that it calls <STRONG>tparm</STRONG> correctly.
-
-</PRE><H3><a name="h3-Special-TERM-treatment">Special TERM treatment</a></H3><PRE>
+ <STRONG>Special</STRONG> <EM>TERM</EM> <STRONG>treatment</STRONG>
If configured to use the terminal-driver, e.g., for the MinGW port,
<STRONG>o</STRONG> <STRONG>setupterm</STRONG> interprets a missing/empty <EM>TERM</EM> variable as the special
string.
-</PRE><H3><a name="h3-Other-
portability-issues">Other portability issues</a></H3><PRE>
+</PRE><H3><a name="h3-Other-
Portability-Issues">Other Portability Issues</a></H3><PRE>
In System V Release 4, <STRONG>set_curterm</STRONG> has an <STRONG>int</STRONG> return type and returns
<STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. We have chosen to implement the X/Open Curses semantics.
X/Open notes that after calling <STRONG>mvcur</STRONG>, the curses state may not match
the actual terminal state, and that an application should touch and
- refresh the window before resuming normal curses calls. Both <STRONG>ncurses</STRONG>
+ refresh the window before resuming normal curses calls. Both <EM>ncurses</EM>
and System V Release 4 curses implement <STRONG>mvcur</STRONG> using the SCREEN data
allocated in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. So though it is documented as
a terminfo function, <STRONG>mvcur</STRONG> is really a curses function which is not
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
-<li><a href="#h3-Compatibility-macros">Compatibility macros</a></li>
-<li><a href="#h3-Legacy-data">Legacy data</a></li>
-<li><a href="#h3-Output-buffering">Output buffering</a></li>
-<li><a href="#h3-Function-prototypes">Function prototypes</a></li>
-<li><a href="#h3-Special-TERM-treatment">Special TERM treatment</a></li>
-<li><a href="#h3-Other-portability-issues">Other portability issues</a></li>
+<li><a href="#h3-Compatibility-Macros">Compatibility Macros</a></li>
+<li><a href="#h3-Legacy-Data">Legacy Data</a></li>
+<li><a href="#h3-Output-Buffering">Output Buffering</a></li>
+<li><a href="#h3-Function-Prototypes">Function Prototypes</a></li>
+<li><a href="#h3-Other-Portability-Issues">Other Portability Issues</a></li>
</ul>
</li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_threads.3x,v 1.49 2023/11/25 14:09:12 tom Exp @
+ * @Id: curs_threads.3x,v 1.50 2023/12/16 20:32:22 tom Exp @
* ***************************************************************************
* ***************************************************************************
-->
<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_threads 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_threads 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_threads 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_threads 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_trace.3x,v 1.40 2023/10/07 21:19:07 tom Exp @
+ * @Id: curs_trace.3x,v 1.41 2023/12/16 20:50:14 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_trace 3x 2023-10-07 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_trace 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_trace 3x 2023-10-07 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_trace 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- The <EM>curses</EM> <EM>trace</EM> routines are used for debugging the ncurses libraries,
- as well as applications which use the ncurses libraries. Some
+ The <EM>curses</EM> <EM>trace</EM> routines are used for debugging the <EM>ncurses</EM> libraries,
+ as well as applications which use the <EM>ncurses</EM> libraries. Some
limitations apply:
<STRONG>o</STRONG> Aside from <STRONG>curses_trace</STRONG>, the other functions are normally available
parameter updates the trace mask, and returns the previous trace
mask.
- When the trace mask is nonzero, ncurses creates the file "trace" in
+ When the trace mask is nonzero, <EM>ncurses</EM> creates the file "trace" in
the current directory for output. If the file already exists, no
tracing is done.
</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
- These functions check the <STRONG>NCURSES_TRACE</STRONG> environment variable, to set
+ These functions check the <EM>NCURSES</EM><STRONG>_</STRONG><EM>TRACE</EM> environment variable, to set
the tracing feature as if <STRONG>curses_trace</STRONG> was called:
filter, initscr, new_prescr, newterm, nofilter, restartterm,
Because the command-line utilities may call initialization functions
such as <STRONG>setupterm</STRONG>, <STRONG>tgetent</STRONG> or <STRONG>use_extended_names</STRONG>, some of their
- debugging output may be directed to the <EM>trace</EM> file if the <STRONG>NCURSES_TRACE</STRONG>
+ debugging output may be directed to the <EM>trace</EM> file if the <EM>NCURSES</EM><STRONG>_</STRONG><EM>TRACE</EM>
environment variable is set:
<STRONG>o</STRONG> messages produced in the utility are written to the standard error.
<STRONG>o</STRONG> messages produced by the underlying library are written to <EM>trace</EM>.
- If ncurses is built without tracing, none of the latter are produced,
+ If <EM>ncurses</EM> is built without tracing, none of the latter are produced,
and fewer diagnostics are provided by the command-line utilities.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
These functions are not part of the XSI interface. Some other curses
implementations are known to have similar features, but they are not
- compatible with ncurses:
+ compatible with <EM>ncurses</EM>:
<STRONG>o</STRONG> SVr4 provided <STRONG>traceon</STRONG> and <STRONG>traceoff</STRONG>, to control whether debugging
information was written to the "trace" file. While the functions
a debug-library is built.
PDCurses has a short description of these functions, with a note
- that they are not present in X/Open Curses, ncurses or NetBSD. It
+ that they are not present in X/Open Curses, <EM>ncurses</EM> or NetBSD. It
does not mention SVr4, but the functions' inclusion in a header
file section labeled "Quasi-standard" hints at the origin.
<STRONG>o</STRONG> NetBSD does not provide functions for enabling/disabling traces.
- It uses environment variables <STRONG>CURSES_TRACE_MASK</STRONG> and
- <STRONG>CURSES_TRACE_FILE</STRONG> to determine what is traced, and where the
+ It uses environment variables <EM>CURSES</EM><STRONG>_</STRONG><EM>TRACE</EM><STRONG>_</STRONG><EM>MASK</EM> and
+ <EM>CURSES</EM><STRONG>_</STRONG><EM>TRACE</EM><STRONG>_</STRONG><EM>FILE</EM> to determine what is traced, and where the
results are written. This is available only when a debug-library
is built.
The NetBSD tracing feature is undocumented.
- A few ncurses functions are not provided when symbol versioning is
+ A few <EM>ncurses</EM> functions are not provided when symbol versioning is
used:
_nc_tracebits, _tracedump, _tracemouse
-ncurses 6.4 2023-1
0-07 <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_util.3x,v 1.90 2023/12/02 21:10:36 tom Exp @
+ * @Id: curs_util.3x,v 1.91 2023/12/16 20:32:22 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_util 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_util 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_util 3x 2023-12-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_util 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
<STRONG>o</STRONG> Then it asks for the screen size via operating system calls. If
successful, it overrides the values from the terminal database.
- <STRONG>o</STRONG> Finally (unless <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG> parameter), <STRONG>ncurses</STRONG>
+ <STRONG>o</STRONG> Finally (unless <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG> parameter), <EM>ncurses</EM>
examines the <EM>LINES</EM> or <EM>COLUMNS</EM> environment variables, using a value
in those to override the results from the operating system or
terminal database.
- <STRONG>Ncurses</STRONG> also updates the screen size in response to <STRONG>SIGWINCH</STRONG>,
- unless overridden by the <EM>LINES</EM> or <EM>COLUMNS</EM> environment variables,
+ <EM>curses</EM> also updates the screen size in response to <STRONG>SIGWINCH</STRONG>, unless
+ overridden by the <EM>LINES</EM> or <EM>COLUMNS</EM> environment variables,
</PRE><H3><a name="h3-use_tioctl">use_tioctl</a></H3><PRE>
The <STRONG>use_tioctl</STRONG> routine, if used, should be called before <STRONG>initscr</STRONG> or
<STRONG>newterm</STRONG> are called (because those compute the screen size). After
- <STRONG>use_tioctl</STRONG> is called with <STRONG>TRUE</STRONG> as an argument, <STRONG>ncurses</STRONG> modifies the
+ <STRONG>use_tioctl</STRONG> is called with <STRONG>TRUE</STRONG> as an argument, <EM>ncurses</EM> modifies the
last step in its computation of screen size as follows:
<STRONG>o</STRONG> checks if the <EM>LINES</EM> and <EM>COLUMNS</EM> environment variables are set to a
number greater than zero.
- <STRONG>o</STRONG> for each, <STRONG>ncurses</STRONG> updates the corresponding environment variable
+ <STRONG>o</STRONG> for each, <EM>ncurses</EM> updates the corresponding environment variable
with the value that it has obtained via operating system call or
from the terminal database.
- <STRONG>o</STRONG> <STRONG>ncurses</STRONG> re-fetches the value of the environment variables so that
+ <STRONG>o</STRONG> <EM>ncurses</EM> re-fetches the value of the environment variables so that
it is still the environment variables which set the screen size.
The <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> routines combine as follows.
<STRONG>o</STRONG> the data written is a copy of the <STRONG>WINDOW</STRONG> structure, and its
associated character cells. The format differs between the wide-
- character (<STRONG>ncursesw</STRONG>) and non-wide (<STRONG>ncurses</STRONG>) libraries. You can
+ character (<EM>ncursesw</EM>) and non-wide (<EM>ncurses</EM>) libraries. You can
transfer data between the two, however.
<STRONG>o</STRONG> the retrieved window is always created as a top-level window (or
</PRE><H3><a name="h3-nofilter_use_tioctl">nofilter/use_tioctl</a></H3><PRE>
- The <STRONG>nofilter</STRONG> and <STRONG>use_tioctl</STRONG> routines are specific to <STRONG>ncurses</STRONG>. They
+ The <STRONG>nofilter</STRONG> and <STRONG>use_tioctl</STRONG> routines are specific to <EM>ncurses</EM>. They
were not supported on Version 7, BSD or System V implementations. It
- is recommended that any code depending on <STRONG>ncurses</STRONG> extensions be
+ is recommended that any code depending on <EM>ncurses</EM> extensions be
conditioned using <STRONG>NCURSES_VERSION</STRONG>.
<STRONG>o</STRONG> Most implementations simply dump the binary <STRONG>WINDOW</STRONG> structure to the
file. These include SVr4 curses, NetBSD and PDCurses, as well as
- older <STRONG>ncurses</STRONG> versions. This implementation (as well as the X/Open
+ older <EM>ncurses</EM> versions. This implementation (as well as the X/Open
variant of Solaris curses, dated 1995) uses textual dumps.
The implementations which use binary dumps use block-I/O (the
before initializing curses), this implementation returns strings
"M-^@", "M-^A", etc.
- X/Open Curses documents <STRONG>unctrl</STRONG> as declared in <STRONG><unctrl.h></STRONG>, which <STRONG>ncurses</STRONG>
- does. However, <STRONG>ncurses</STRONG>' <STRONG><curses.h></STRONG> includes <STRONG><unctrl.h></STRONG>, matching the
+ X/Open Curses documents <STRONG>unctrl</STRONG> as declared in <STRONG><unctrl.h></STRONG>, which <EM>ncurses</EM>
+ does. However, <EM>ncurses</EM>' <STRONG><curses.h></STRONG> includes <STRONG><unctrl.h></STRONG>, matching the
behavior of SVr4 curses. Other implementations may not do that.
</PRE><H3><a name="h3-use_env_use_tioctl">use_env/use_tioctl</a></H3><PRE>
- If <STRONG>ncurses</STRONG> is configured to provide the sp-functions extension, the
+ If <EM>ncurses</EM> is configured to provide the sp-functions extension, the
state of <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> may be updated before creating each
<EM>screen</EM> rather than once only (<STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>). This feature of
<STRONG>use_env</STRONG> is not provided by other implementations of curses.
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_variables.3x,v 1.34 2023/11/25 14:32:36 tom Exp @
+ * @Id: curs_variables.3x,v 1.35 2023/12/16 21:05:52 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_variables 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_variables 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_variables 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_variables 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
<STRONG>int</STRONG> <STRONG>COLOR_PAIRS;</STRONG>
<STRONG>int</STRONG> <STRONG>COLORS;</STRONG>
<STRONG>int</STRONG> <STRONG>COLS;</STRONG>
- <STRONG>int</STRONG> <STRONG>ESCDELAY;</STRONG>
<STRONG>int</STRONG> <STRONG>LINES;</STRONG>
- <STRONG>int</STRONG> <STRONG>TABSIZE;</STRONG>
<STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>curscr;</STRONG>
- <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>newscr;</STRONG>
<STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>stdscr;</STRONG>
+ <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
+ <STRONG>int</STRONG> <STRONG>ESCDELAY;</STRONG>
+ <STRONG>int</STRONG> <STRONG>TABSIZE;</STRONG>
+ <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>newscr;</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
library.
-</PRE><H3><a name="h3-bool_-TRUE_-FALSE">
bool, TRUE, FALSE</a></H3><PRE>
+</PRE><H3><a name="h3-bool_-TRUE_-FALSE">
<EM>bool,</EM> TRUE, FALSE</a></H3><PRE>
X/Open Issue 4 <EM>curses</EM> (1996) preceded the ISO C99 and ISO C++98
standards, each of which also defined a Boolean data type. The <EM>curses</EM>
library requires an integral type <EM>bool</EM> and constants <STRONG>TRUE</STRONG> and <STRONG>FALSE</STRONG> to
values indicating failure and success, respectively.
-</PRE><H3><a name="h3-chtype">
chtype</a></H3><PRE>
+</PRE><H3><a name="h3-chtype">
<EM>chtype</EM></a></H3><PRE>
The <EM>chtype</EM> integral type combines a ("narrow", 8-bit) character with
attributes encoding the character's <EM>rendition</EM>, such as the styling of
its typeface and/or foreground and background colors. See, for
example, <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">attron(3x)</A></STRONG>, and <STRONG><A HREF="curs_inch.3x.html">inch(3x)</A></STRONG>.
-</PRE><H3><a name="h3-cchar_t_-attr_t">
cchar_t, attr_t</a></H3><PRE>
+</PRE><H3><a name="h3-cchar_t_-attr_t">
<EM>cchar_t,</EM> attr_t</a></H3><PRE>
<EM>chtype</EM> is too small for the standard C library's wide-character type,
<EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>. <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> is a type that can accommodate an <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> and enough
wide characters to store what Unicode terms a <EM>grapheme</EM> <EM>cluster</EM> (a
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_window.3x,v 1.43 2023/11/25 14:17:29 tom Exp @
+ * @Id: curs_window.3x,v 1.44 2023/12/16 20:32:22 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_window 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_window 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_window 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_window 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
X/Open curses does not even make that check, and will delete a
parent window which still has subwindows.
- <STRONG>o</STRONG> Since release 4.0 (1996), ncurses maintains a list of windows for
+ <STRONG>o</STRONG> Since release 4.0 (1996), <EM>ncurses</EM> maintains a list of windows for
each screen, to ensure that a window has no subwindows before
allowing deletion.
- <STRONG>o</STRONG> NetBSD copied this feature of ncurses in 2003.
+ <STRONG>o</STRONG> NetBSD copied this feature of <EM>ncurses</EM> in 2003.
PDCurses follows the scheme used in Solaris X/Open curses.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* authorization. *
****************************************************************************
* Author: Thomas E. Dickey 1997,1999,2000,2005
- * @Id: default_colors.3x,v 1.47 2023/11/25 14:26:30 tom Exp @
+ * @Id: default_colors.3x,v 1.48 2023/12/16 20:32:22 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>default_colors 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>default_colors 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">default_colors 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">default_colors 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> Library calls <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
<EM>use</EM><STRONG>_</STRONG><EM>default</EM><STRONG>_</STRONG><EM>colors();</EM>
<EM>assume</EM><STRONG>_</STRONG><EM>default</EM><STRONG>_</STRONG><EM>colors(-1,-1);</EM>
- These are ncurses extensions. For other curses implementations, color
- number -1 does not mean anything, just as for ncurses before a
+ These are <EM>ncurses</EM> extensions. For other curses implementations, color
+ number -1 does not mean anything, just as for <EM>ncurses</EM> before a
successful call of <STRONG>use_default_colors</STRONG> or <STRONG>assume_default_colors</STRONG>.
Other curses implementations do not allow an application to modify
color pair 0. They assume that the background is COLOR_BLACK, but do
not ensure that the color pair 0 is painted to match the assumption.
If your application does not use either <STRONG>use_default_colors</STRONG> or
- <STRONG>assume_default_colors</STRONG> ncurses will paint a white foreground (text) with
+ <STRONG>assume_default_colors</STRONG> <EM>ncurses</EM> will paint a white foreground (text) with
black background for color pair 0.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines are specific to ncurses. They were not supported on
+ These routines are specific to <EM>ncurses</EM>. They were not supported on
Version 7, BSD or System V implementations. It is recommended that any
code depending on them be conditioned using NCURSES_VERSION.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* authorization. *
****************************************************************************
* Author: Thomas E. Dickey 1997
- * @Id: define_key.3x,v 1.39 2023/11/25 14:26:30 tom Exp @
+ * @Id: define_key.3x,v 1.40 2023/12/16 20:32:22 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>define_key 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>define_key 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">define_key 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">define_key 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> Library calls <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: form.3x,v 1.50 2023/11/25 13:59:44 tom Exp @
+ * @Id: form.3x,v 1.51 2023/12/16 20:32:22 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>form 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>form 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">form 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">form 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> Library calls <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>
</PRE><H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE>
The following table lists each <STRONG>form</STRONG> routine and the name of the manual
- page on which it is described. Routines flagged with "*" are ncurses-
- specific, not present in SVr4.
+ page on which it is described. Routines flagged with "*" are
+ <EM>ncurses</EM>-specific, not present in SVr4.
<STRONG>curses</STRONG> Routine Name Manual Page Name
--------------------------------------------------
It is not part of X/Open Curses.
- Aside from ncurses, there are few implementations:
+ Aside from <EM>ncurses</EM>, there are few implementations:
<STRONG>o</STRONG> systems based on SVr4 source code, e.g., Solaris.
<STRONG>o</STRONG> NetBSD curses.
A few functions in this implementation are extensions added for
- ncurses, but not provided by other implementations, e.g.,
+ <EM>ncurses</EM>, but not provided by other implementations, e.g.,
<STRONG>form_driver_w</STRONG>, <STRONG>unfocus_current_field</STRONG>.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
- Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric S.
+ Juergen Pfeifer. Manual pages and adaptation for <EM>ncurses</EM> by Eric S.
Raymond.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: form_field_buffer.3x,v 1.42 2023/11/25 13:58:47 tom Exp @
+ * @Id: form_field_buffer.3x,v 1.43 2023/12/16 20:32:22 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>form_field_buffer 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>form_field_buffer 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">form_field_buffer 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">form_field_buffer 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG>
These routines emulate the System V forms library. They were not
supported on Version 7 or BSD versions.
- The <STRONG>set_max_field</STRONG> function checks for an ncurses extension
+ The <STRONG>set_max_field</STRONG> function checks for an <EM>ncurses</EM> extension
<STRONG>O_INPUT_FIELD</STRONG> which allows a dynamic field to shrink if the new limit
is smaller than the current field size.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: form_field_validation.3x,v 1.50 2023/11/25 13:58:47 tom Exp @
+ * @Id: form_field_validation.3x,v 1.51 2023/12/16 20:32:22 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>form_field_validation 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>form_field_validation 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">form_field_validation 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">form_field_validation 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG>
where <EM>a</EM>, <EM>b</EM>, <EM>c</EM>, and <EM>d</EM> are numbers in the range 0 to 255. Trailing
blanks in the buffer are ignored. The address itself is not validated.
- This is an ncurses extension; this field type may not be available in
+ This is an <EM>ncurses</EM> extension; this field type may not be available in
other curses implementations.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: form_page.3x,v 1.34 2023/11/25 13:58:47 tom Exp @
+ * @Id: form_page.3x,v 1.35 2023/12/16 20:32:22 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>form_page 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>form_page 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">form_page 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">form_page 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="form_page.3x.html">form_page(3x)</A></STRONG> Library calls <STRONG><A HREF="form_page.3x.html">form_page(3x)</A></STRONG>
These routines emulate the System V forms library. They were not
supported on Version 7 or BSD versions.
- The <STRONG>unfocus_current_field</STRONG> function is an ncurses extension.
+ The <STRONG>unfocus_current_field</STRONG> function is an <EM>ncurses</EM> extension.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="form_page.3x.html">form_page(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="form_page.3x.html">form_page(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: form_requestname.3x,v 1.32 2023/11/25 13:58:47 tom Exp @
+ * @Id: form_requestname.3x,v 1.33 2023/12/16 20:32:22 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>form_requestname 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>form_requestname 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">form_requestname 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">form_requestname 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="form_requestname.3x.html">form_requestname(3x)</A></STRONG> Library calls <STRONG><A HREF="form_requestname.3x.html">form_requestname(3x)</A></STRONG>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines are specific to ncurses. They were not supported on
+ These routines are specific to <EM>ncurses</EM>. They were not supported on
Version 7, BSD or System V implementations. It is recommended that any
code depending on them be conditioned using NCURSES_VERSION.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="form_requestname.3x.html">form_requestname(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="form_requestname.3x.html">form_requestname(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.101 2023/12/02 20:49:04 tom Exp @
+ * @Id: infocmp.1m,v 1.102 2023/12/16 20:32:22 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-02 ncurses 6.4 User commands</TITLE>
+<TITLE>infocmp 1m 2023-12-16 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-02 ncurses 6.4 User commands</H1>
+<H1 class="no-header">infocmp 1m 2023-12-16 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>
that were not needed.
<STRONG>Changing</STRONG> <STRONG>Databases</STRONG> <STRONG>[-A</STRONG> <EM>directory</EM>] [-B <EM>directory</EM>]
- Like other <STRONG>ncurses</STRONG> utilities, <STRONG>infocmp</STRONG> looks for the terminal
+ Like other <EM>ncurses</EM> utilities, <STRONG>infocmp</STRONG> looks for the terminal
descriptions in several places. You can use the <EM>TERMINFO</EM> and
<EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variables to override the compiled-in default
list of places to search. See <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, as well as the <EM>Fetching</EM>
according to the type and the name of the corresponding terminal
entry.
- Before ncurses 5.0, the split between the <STRONG>-e</STRONG> and <STRONG>-E</STRONG> options was
+ Before <EM>ncurses</EM> 5.0, the split between the <STRONG>-e</STRONG> and <STRONG>-E</STRONG> options was
not needed; but support for extended names required making the
arrays of terminal capabilities separate from the TERMTYPE
structure.
contents of two source files, since it excludes the inferences
that <STRONG>infocmp</STRONG> makes to fill in missing data.
- <STRONG>-V</STRONG> reports the version of ncurses which was used in this program, and
+ <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> which was used in this program, and
exits.
<STRONG>-v</STRONG> <EM>n</EM> prints out tracing information on standard error as the program
runs.
The optional parameter <EM>n</EM> is a number from 1 to 10, inclusive,
- indicating the desired level of detail of information. If ncurses
+ indicating the desired level of detail of information. If <EM>ncurses</EM>
is built without tracing support, the optional parameter is
ignored.
(AT&T) wrote the first <STRONG>infocmp</STRONG> in early 1984, for System V Release 3.
Eric Raymond used the AT&T documentation in 1995 to provide an
- equivalent <STRONG>infocmp</STRONG> for ncurses. In addition, he added a few new
+ equivalent <STRONG>infocmp</STRONG> for <EM>ncurses</EM>. In addition, he added a few new
features such as:
<STRONG>o</STRONG> the <STRONG>-e</STRONG> option, to support <EM>fallback</EM> (compiled-in) terminal
For a complete list, see the <EM>EXTENSIONS</EM> section.
In 2010, Roy Marples provided an <STRONG>infocmp</STRONG> program for NetBSD. It is
- less capable than the SVr4 or ncurses versions (e.g., it lacks the
+ less capable than the SVr4 or <EM>ncurses</EM> versions (e.g., it lacks the
sorting options documented in X/Open), but does include the <STRONG>-x</STRONG> option
- adapted from ncurses.
+ adapted from <EM>ncurses</EM>.
</PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>
+ncurses 6.4 2023-12-
16 <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: infotocap.1m,v 1.37 2023/11/25 14:32:36 tom Exp @
+ * @Id: infotocap.1m,v 1.39 2023/12/10 14:12:43 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>infotocap 1m 2023-11-25 ncurses 6.4 User commands</TITLE>
+<TITLE>infotocap 1m 2023-12-10 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">infotocap 1m 2023-11-25 ncurses 6.4 User commands</H1>
+<H1 class="no-header">infotocap 1m 2023-12-10 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG> User commands <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>
+ncurses 6.4 2023-1
2-10 <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* authorization. *
****************************************************************************
* Author: Thomas E. Dickey 2003
- * @Id: key_defined.3x,v 1.31 2023/11/25 14:26:30 tom Exp @
+ * @Id: key_defined.3x,v 1.32 2023/12/16 20:32:22 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>key_defined 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>key_defined 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">key_defined 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">key_defined 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> Library calls <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* authorization. *
****************************************************************************
* Author: Thomas E. Dickey 1999
- * @Id: keybound.3x,v 1.33 2023/11/25 14:26:30 tom Exp @
+ * @Id: keybound.3x,v 1.34 2023/12/16 20:32:22 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>keybound 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>keybound 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">keybound 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">keybound 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG> Library calls <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* authorization. *
****************************************************************************
* Author: Thomas E. Dickey 1997
- * @Id: keyok.3x,v 1.37 2023/11/25 14:26:30 tom Exp @
+ * @Id: keyok.3x,v 1.38 2023/12/16 20:32:22 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>keyok 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>keyok 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">keyok 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">keyok 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> Library calls <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* authorization. *
****************************************************************************
* Author: Thomas E. Dickey
- * @Id: legacy_coding.3x,v 1.23 2023/11/25 14:26:30 tom Exp @
+ * @Id: legacy_coding.3x,v 1.24 2023/12/16 20:32:22 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>legacy_coding 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>legacy_coding 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">legacy_coding 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">legacy_coding 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG> Library calls <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- This routine is specific to ncurses. It was not supported on Version
+ This routine is specific to <EM>ncurses</EM>. It was not supported on Version
7, BSD or System V implementations. It is recommended that any code
- depending on ncurses extensions be conditioned using NCURSES_VERSION.
+ depending on <EM>ncurses</EM> extensions be conditioned using NCURSES_VERSION.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: menu.3x,v 1.41 2023/11/25 13:59:44 tom Exp @
+ * @Id: menu.3x,v 1.42 2023/12/16 20:32:22 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>menu 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>menu 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">menu 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">menu 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> Library calls <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG>
It is not part of X/Open Curses.
- Aside from ncurses, there are few implementations:
+ Aside from <EM>ncurses</EM>, there are few implementations:
<STRONG>o</STRONG> systems based on SVr4 source code, e.g., Solaris.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
- Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric S.
+ Juergen Pfeifer. Manual pages and adaptation for <EM>ncurses</EM> by Eric S.
Raymond.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: menu_driver.3x,v 1.43 2023/11/25 13:58:47 tom Exp @
+ * @Id: menu_driver.3x,v 1.44 2023/12/16 20:32:22 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>menu_driver 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>menu_driver 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">menu_driver 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">menu_driver 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
These routines emulate the System V menu library. They were not
supported on Version 7 or BSD versions. The support for mouse events
- is ncurses specific.
+ is <EM>ncurses</EM> specific.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: menu_requestname.3x,v 1.30 2023/11/25 13:58:47 tom Exp @
+ * @Id: menu_requestname.3x,v 1.31 2023/12/16 20:32:22 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>menu_requestname 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>menu_requestname 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">menu_requestname 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">menu_requestname 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines are specific to ncurses. They were not supported on
+ These routines are specific to <EM>ncurses</EM>. They were not supported on
Version 7, BSD or System V implementations. It is recommended that any
code depending on them be conditioned using NCURSES_VERSION.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: menu_spacing.3x,v 1.34 2023/11/25 13:58:47 tom Exp @
+ * @Id: menu_spacing.3x,v 1.35 2023/12/16 20:32:22 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>menu_spacing 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>menu_spacing 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">menu_spacing 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">menu_spacing 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines are specific to ncurses. They were not supported on
+ These routines are specific to <EM>ncurses</EM>. They were not supported on
Version 7, BSD or System V implementations. It is recommended that any
code depending on them be conditioned using NCURSES_VERSION.
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: ncurses.3x,v 1.185 2023/12/03 00:14:35 tom Exp @
+ * @Id: ncurses.3x,v 1.187 2023/12/17 23:44:14 tom Exp @
+ * X/Open Curses Issue 7 assumes some optimization will be done, but
+ * does not mandate it in any way.
-->
<!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-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>ncurses 3x 2023-12-17 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-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">ncurses 3x 2023-12-17 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>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- The <STRONG>ncurses</STRONG> library routines give the user a terminal-independent
+ The <EM>ncurses</EM> library routines give the user a terminal-independent
method of updating character screens with reasonable optimization.
- This implementation is "new curses" (ncurses) and is the approved
+ This implementation is "new curses" (<EM>ncurses</EM>) and is the approved
replacement for 4.4BSD classic curses, which has been discontinued.
- This describes <STRONG>ncurses</STRONG> version 6.4 (patch 20231202).
+ This describes <EM>ncurses</EM> version 6.4 (patch 20231217).
- The <STRONG>ncurses</STRONG> library emulates the curses library of System V Release 4
+ 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
as XSI curses). XSI stands for X/Open System Interfaces Extension.
- The <STRONG>ncurses</STRONG> library is freely redistributable in source form.
+ The <EM>ncurses</EM> library is freely redistributable in source form.
<EM>ncurses</EM> man pages employ several sections to clarify matters of usage
and interoperability with other <EM>curses</EM> implementations.
directory) that describe curses actions. See also the section on
<STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>.
- The <STRONG>ncurses</STRONG> package supports: overall screen, window and pad
+ 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
Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
-</PRE><H3><a name="h3-Datatypes">Datatypes</a></H3><PRE>
- The <STRONG>ncurses</STRONG> library permits manipulation of data structures, called
- <EM>windows</EM>, which can be thought of as two-dimensional arrays of
- characters representing all or part of a CRT screen. A default window
- called <STRONG>stdscr</STRONG>, which is the size of the terminal screen, is supplied.
- Others may be created with <STRONG>newwin</STRONG>.
-
- Note that <STRONG>curses</STRONG> does not handle overlapping windows, that's done by
- the <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG> library. This means that you can either use <STRONG>stdscr</STRONG> or
- divide the screen into tiled windows and not using <STRONG>stdscr</STRONG> at all.
- Mixing the two will result in unpredictable, and undesired, effects.
-
- Windows are referred to by variables declared as <STRONG>WINDOW</STRONG> <STRONG>*</STRONG>. These data
- structures are manipulated with routines described here and elsewhere
- in the <STRONG>ncurses</STRONG> manual pages. Among those, the most basic routines are
- <STRONG>move</STRONG> and <STRONG>addch</STRONG>. More general versions of these routines are included
- with names beginning with <STRONG>w</STRONG>, allowing the user to specify a window.
- The routines not beginning with <STRONG>w</STRONG> affect <STRONG>stdscr</STRONG>.
-
- After using routines to manipulate a window, <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> is called,
- telling <STRONG>curses</STRONG> to make the user's CRT screen look like <STRONG>stdscr</STRONG>. The
- characters in a window are actually of type <STRONG>chtype</STRONG>, (character and
- attribute data) so that other information about the character may also
- be stored with each character.
+</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>),
+ 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
+ <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-
+ 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
+ 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.
+ 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
+ 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>
+ 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>
+ implementation.
Special windows called <EM>pads</EM> may also be manipulated. These are windows
- which are not constrained to the size of the screen and whose contents
- need not be completely displayed. See <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> for more
- information.
-
- In addition to drawing characters on the screen, video 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. Line drawing characters may be
- specified to be output. On input, <STRONG>curses</STRONG> is also able to translate
- arrow and function keys that transmit escape sequences into single
- values. The video attributes, line drawing characters, and input
- values use names, defined in <STRONG><curses.h></STRONG>, such as <STRONG>A_REVERSE</STRONG>, <STRONG>ACS_HLINE</STRONG>,
- and <STRONG>KEY_LEFT</STRONG>.
-
-
-</PRE><H3><a name="h3-Environment-variables">Environment variables</a></H3><PRE>
- If the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> are set, or if the
- program is executing in a window environment, line and column
- information in the environment will override information read by
- <EM>terminfo</EM>. This would affect a program running in an AT&T 630 layer,
- for example, where the size of a screen is changeable (see
- <STRONG>ENVIRONMENT</STRONG>).
-
- If the environment variable <EM>TERMINFO</EM> is defined, any program using
- <STRONG>curses</STRONG> checks for a local terminal definition before checking in the
- standard place. For example, if <EM>TERM</EM> is set to <STRONG>att4424</STRONG>, then the
- compiled terminal definition is found in
-
- <STRONG>/usr/share/terminfo/a/att4424</STRONG>.
-
- (The <STRONG>a</STRONG> is copied from the first letter of <STRONG>att4424</STRONG> to avoid creation of
- huge directories.) However, if <EM>TERMINFO</EM> is set to <STRONG>$HOME/myterms</STRONG>,
- <STRONG>curses</STRONG> first checks
-
- <STRONG>$HOME/myterms/a/att4424</STRONG>,
-
- and if that fails, it then checks
-
- <STRONG>/usr/share/terminfo/a/att4424</STRONG>.
-
- This is useful for developing experimental definitions or when write
- permission in <STRONG>/usr/share/terminfo</STRONG> is not available.
-
- The integer variables <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG> are defined in <STRONG><curses.h></STRONG> and will
- be filled in by <STRONG>initscr</STRONG> with the size of the screen. The constants
- <STRONG>TRUE</STRONG> and <STRONG>FALSE</STRONG> have the values <STRONG>1</STRONG> and <STRONG>0</STRONG>, respectively.
-
- The <STRONG>curses</STRONG> routines also define the <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> variable <STRONG>curscr</STRONG> which is
- used for certain low-level operations like clearing and redrawing a
- screen containing garbage. The <STRONG>curscr</STRONG> can be used in only a few
- routines.
-
-
-</PRE><H3><a name="h3-Routine-and-Argument-Names">Routine and Argument Names</a></H3><PRE>
- Many <STRONG>curses</STRONG> routines have two or more versions. The routines prefixed
- with <EM>w</EM> require a window argument. The routines prefixed with <EM>p</EM> require
- a pad argument. Those without a prefix generally use <STRONG>stdscr</STRONG>.
-
- The routines prefixed with <STRONG>mv</STRONG> require a <EM>y</EM> and <EM>x</EM> coordinate to move to
- before performing the appropriate action. The <STRONG>mv</STRONG> routines imply a call
- to <STRONG>move</STRONG> before the call to the other routine. The coordinate <EM>y</EM> always
- refers to the row (of the window), and <EM>x</EM> always refers to the column.
- The upper left-hand corner is always (0,0), not (1,1).
-
- The routines prefixed with <STRONG>mvw</STRONG> take both a window argument and <EM>x</EM> and <EM>y</EM>
- coordinates. The window argument is always specified before the
- coordinates.
-
- In each case, <EM>win</EM> is the window affected, and <EM>pad</EM> is the pad affected;
- <EM>win</EM> and <EM>pad</EM> are always pointers to type <STRONG>WINDOW</STRONG>.
-
- Option setting routines require a Boolean flag <EM>bf</EM> with the value <STRONG>TRUE</STRONG>
- or <STRONG>FALSE</STRONG>; <EM>bf</EM> is always of type <STRONG>bool</STRONG>. Most of the data types used in
- the library routines, such as <STRONG>WINDOW</STRONG>, <STRONG>SCREEN</STRONG>, <STRONG>bool</STRONG>, and <STRONG>chtype</STRONG> are
- defined in <STRONG><curses.h></STRONG>. Types used for the terminfo routines such as
- <STRONG>TERMINAL</STRONG> are defined in <STRONG><term.h></STRONG>.
-
- This manual page describes functions which may appear in any
- configuration of the library. There are two common configurations of
- the library:
-
- <EM>ncurses</EM>
- the "normal" library, which handles 8-bit characters. The
- normal (8-bit) library stores characters combined with
- attributes in <STRONG>chtype</STRONG> data.
-
- Attributes alone (no corresponding character) may be stored in
- <STRONG>chtype</STRONG> or the equivalent <STRONG>attr_t</STRONG> data. In either case, the data
- is stored in something like an integer.
-
- Each cell (row and column) in a <STRONG>WINDOW</STRONG> is stored as a <STRONG>chtype</STRONG>.
-
- <EM>ncursesw</EM>
- the so-called "wide" library, which handles multibyte
- characters (see the section on <STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>). The
- "wide" library includes all of the calls from the "normal"
- library. It adds about one third more calls using data types
- which store multibyte characters:
-
- <STRONG>cchar_t</STRONG>
- corresponds to <STRONG>chtype</STRONG>. However it is a structure, because
- more data is stored than can fit into an integer. The
- characters are large enough to require a full integer
- value - and there may be more than one character per cell.
- The video attributes and color are stored in separate
- fields of the structure.
-
- Each cell (row and column) in a <STRONG>WINDOW</STRONG> is stored as a
- <STRONG>cchar_t</STRONG>.
-
- 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 <STRONG>cchar_t</STRONG> structure.
-
- <STRONG>wchar_t</STRONG>
- stores a "wide" character. Like <STRONG>chtype</STRONG>, this may be an
- integer.
-
- <STRONG>wint_t</STRONG>
- stores a <STRONG>wchar_t</STRONG> or <STRONG>WEOF</STRONG> - not the same, though both may
- have the same size.
-
- The "wide" library provides new functions which are analogous
- to functions in the "normal" library. There is a naming
- convention which relates many of the normal/wide variants: a
- "_w" is inserted into the name. For example, <STRONG>waddch</STRONG> becomes
- <STRONG>wadd_wch</STRONG>.
-
-
-</PRE><H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE>
- The following table lists the <STRONG>curses</STRONG> routines provided in the "normal"
- and "wide" libraries and the names of the manual pages on which they
- are described. Routines flagged with "*" are ncurses-specific, not
- described by XPG4 or present in SVr4.
-
- <STRONG>curses</STRONG> Routine Name Manual Page Name
+ 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
+ support such display enhancements. See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>.
+
+ <EM>curses</EM> predefines symbols for a small set of line graphics characters,
+ corresponding to the VT100 line drawing set. 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 not received 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>
+ <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>
+ 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
+ <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
+ identifies. <EM>TERMINFO</EM> is useful for developing experimental type
+ 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
+ <STRONG>stdscr</STRONG>.
+
+ 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>)
+ <EM>win</EM> pointer to <EM>WINDOW</EM>
+ <EM>pad</EM> pointer to <EM>WINDOW</EM> that is a pad
+
+
+</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
+ "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.
+
+ 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
+ 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>
+
+ 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
+ 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.
+
+ <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
+ functions of ISO C and their constant <STRONG>EOF</STRONG>.
+
+ The wide library provides additional functions that
+ complement those in the non-wide library where the size of
+ the underlying character type is significant. A somewhat
+ regular naming convention relates many of the wide variants
+ to their non-wide counterparts; where a non-wide function
+ name contains "ch" or "str", prefix it with "_w" to obtain
+ the wide counterpart. For example, <STRONG>waddch</STRONG> becomes <STRONG>wadd_wch</STRONG>.
+
+ This convention is inapplicable to some non-wide function
+ names, so other transformations are used for the wide
+ configuration: in the window background management functions,
+ "bkgd" becomes "bkgrnd"; the window border-drawing and
+ -clearing functions are suffixed with "_set".
+
+
+</PRE><H3><a name="h3-Function-Name-Index">Function Name Index</a></H3><PRE>
+ The following table lists the <EM>curses</EM> functions provided in the non-wide
+ and wide APIs and the corresponding man pages that describe them.
+ Those flagged with "*" are <EM>ncurses</EM>-specific, neither described by
+ X/Open Curses nor present in SVr4.
+
+ <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>
addchnstr <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>
addchstr <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>
addnstr <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>
-
addnwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>
addstr <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>
addwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(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>*
flushinp <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
free_pair <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG>*
get_wch <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
-
get_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
getattrs <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
getbegx <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(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_idcok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_idlok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_immedok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
-
is_keypad <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_leaveok <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>*
is_linetouched <STRONG><A HREF="curs_touch.3x.html">curs_touch(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>
mvins_wstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
mvinsch <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG>
mvinsnstr <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG>
-
mvinsstr <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG>
mvinstr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
mvinwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(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>
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>
pecho_wchar <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
-
pechochar <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
pnoutrefresh <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
prefresh <STRONG><A HREF="curs_pad.3x.html">curs_pad(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>
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>
-
tigetnum <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
tigetstr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
timeout <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(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>
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>
wenclose <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>*
werase <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>
(i.e., these should not be used as the right-hand side of assignment
statements).
- Functions with a "mv" prefix first perform a cursor movement using
- <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
- the window pointer is null. Most "mv"-prefixed functions (except
- variadic functions such as <STRONG>mvprintw</STRONG>) are provided both as macros and
- functions.
+ 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.
</PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
The following environment symbols are useful for customizing the
- runtime behavior of the <STRONG>ncurses</STRONG> library. The most important ones have
+ runtime behavior of the <EM>ncurses</EM> library. The most important ones have
been already discussed in detail.
variable. Very few terminfo entries provide this feature.
Because this name is also used in development environments to represent
- the C compiler's name, <STRONG>ncurses</STRONG> ignores it if it does not happen to be a
+ the C compiler's name, <EM>ncurses</EM> ignores it if it does not happen to be a
single character.
</PRE><H3><a name="h3-BAUDRATE"><EM>BAUDRATE</EM></a></H3><PRE>
The debugging library checks this environment variable when the
application has redirected output to a file. The variable's numeric
- value is used for the baudrate. If no value is found, <STRONG>ncurses</STRONG> uses
+ value is used for the baudrate. If no value is found, <EM>ncurses</EM> uses
9600. This allows testers to construct repeatable test-cases that take
into account costs that depend on baudrate.
Specify the width of the screen in characters. Applications running in
a windowing environment usually are able to obtain the width of the
window in which they are executing. If neither the <EM>COLUMNS</EM> value nor
- the terminal's screen size is available, <STRONG>ncurses</STRONG> uses the size which
+ the terminal's screen size is available, <EM>ncurses</EM> uses the size which
may be specified in the terminfo database (i.e., the <STRONG>cols</STRONG> capability).
It is important that your application use a correct size for the
</PRE><H3><a name="h3-ESCDELAY"><EM>ESCDELAY</EM></a></H3><PRE>
- Specifies the total time, in milliseconds, for which ncurses will await
+ Specifies the total time, in milliseconds, for which <EM>ncurses</EM> will await
a character sequence, e.g., a function key. The default value, 1000
milliseconds, is enough for most uses. However, it is made a variable
to accommodate unusual applications.
</PRE><H3><a name="h3-HOME"><EM>HOME</EM></a></H3><PRE>
- Tells <STRONG>ncurses</STRONG> where your home directory is. That is where it may read
+ Tells <EM>ncurses</EM> where your home directory is. That is where it may read
and write auxiliary terminal descriptions:
$HOME/.termcap
This variable lets you customize the mouse. The variable must be three
numeric digits 1-3 in any order, e.g., 123 or 321. If it is not
- specified, <STRONG>ncurses</STRONG> uses 132.
+ specified, <EM>ncurses</EM> uses 132.
</PRE><H3><a name="h3-NCURSES_ASSUMED_COLORS"><EM>NCURSES_ASSUMED_COLORS</EM></a></H3><PRE>
are white-on-black (see <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>). You may set the
foreground and background color values with this environment variable
by proving a 2-element list: foreground,background. For example, to
- tell ncurses to not assume anything about the colors, set this to
+ tell <EM>ncurses</EM> to not assume anything about the colors, set this to
"-1,-1". To make it green-on-black, set it to "2,0". Any positive
value from zero to the terminfo <STRONG>max_colors</STRONG> value is allowed.
</PRE><H3><a name="h3-NCURSES_CONSOLE2"><EM>NCURSES_CONSOLE2</EM></a></H3><PRE>
- This applies only to the MinGW port of ncurses.
+ This applies only to the MinGW port of <EM>ncurses</EM>.
The <STRONG>Console2</STRONG> program's handling of the Microsoft Console API call
<STRONG>CreateConsoleScreenBuffer</STRONG> is defective. Applications which use this
</PRE><H3><a name="h3-NCURSES_GPM_TERMS"><EM>NCURSES_GPM_TERMS</EM></a></H3><PRE>
- This applies only to ncurses configured to use the GPM interface.
+ This applies only to <EM>ncurses</EM> configured to use the GPM interface.
If present, the environment variable is a list of one or more terminal
names against which the <EM>TERM</EM> environment variable is matched. Setting
it to an empty value disables the GPM interface; using the built-in
support for xterm, etc.
- If the environment variable is absent, ncurses will attempt to open GPM
+ If the environment variable is absent, <EM>ncurses</EM> will attempt to open GPM
if <EM>TERM</EM> contains "linux".
</PRE><H3><a name="h3-NCURSES_NO_HARD_TABS"><EM>NCURSES_NO_HARD_TABS</EM></a></H3><PRE>
- <STRONG>Ncurses</STRONG> may use tabs as part of the cursor movement optimization. In
- some cases, your terminal driver may not handle these properly. Set
- this environment variable to disable the feature. You can also adjust
- your <STRONG>stty(1)</STRONG> settings to avoid the problem.
+ <EM>ncurses</EM> may use tabs as part of cursor movement optimization. In some
+ cases, your terminal driver may not handle these properly. Set this
+ environment variable to any value to disable the feature. You can also
+ adjust your <STRONG>stty(1)</STRONG> settings to avoid the problem.
</PRE><H3><a name="h3-NCURSES_NO_MAGIC_COOKIE"><EM>NCURSES_NO_MAGIC_COOKIE</EM></a></H3><PRE>
Some terminals use a magic-cookie feature which requires special
handling to make highlighting and other video attributes display
properly. You can suppress the highlighting entirely for these
- terminals by setting this environment variable.
+ terminals by setting this environment variable to any value.
</PRE><H3><a name="h3-NCURSES_NO_PADDING"><EM>NCURSES_NO_PADDING</EM></a></H3><PRE>
<STRONG>o</STRONG> continued though 5.9 patch 20130126
- <STRONG>ncurses</STRONG> enabled buffered output during terminal initialization. This
+ <EM>ncurses</EM> enabled buffered output during terminal initialization. This
was done (as in SVr4 curses) for performance reasons. For testing
- purposes, both of <STRONG>ncurses</STRONG> and certain applications, this feature was
+ purposes, both of <EM>ncurses</EM> and certain applications, this feature was
made optional. Setting the <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>SETBUF</EM> variable disabled output
buffering, leaving the output in the original (usually line buffered)
mode.
- In the current implementation, ncurses performs its own buffering and
+ In the current implementation, <EM>ncurses</EM> performs its own buffering and
does not require this workaround. It does not modify the buffering of
the standard output.
The reason for the change was to make the behavior for interrupts and
other signals more robust. One drawback is that certain
- nonconventional programs would mix ordinary stdio calls with ncurses
- calls and (usually) work. This is no longer possible since ncurses is
+ nonconventional programs would mix ordinary stdio calls with <EM>ncurses</EM>
+ calls and (usually) work. This is no longer possible since <EM>ncurses</EM> is
not using the buffered standard output but its own output (to the same
file descriptor). As a special case, the low-level calls such as <STRONG>putp</STRONG>
still use the standard output. But high-level curses calls do not.
</PRE><H3><a name="h3-NCURSES_NO_UTF8_ACS"><EM>NCURSES_NO_UTF8_ACS</EM></a></H3><PRE>
- During initialization, the <STRONG>ncurses</STRONG> library checks for special cases
+ During initialization, the <EM>ncurses</EM> library checks for special cases
where VT100 line-drawing (and the corresponding alternate character set
capabilities) described in the terminfo are known to be missing.
Specifically, when running in a UTF-8 locale, the Linux console
- emulator and the GNU screen program ignore these. Ncurses checks the
- <EM>TERM</EM> environment variable for these. For other special cases, you
- should set this environment variable. Doing this tells ncurses to use
- Unicode values which correspond to the VT100 line-drawing glyphs. That
- works for the special cases cited, and is likely to work for terminal
- emulators.
+ emulator and the GNU screen program ignore these. <EM>ncurses</EM> <EM>checks</EM> <EM>the</EM>
+ <EM>TERM</EM> <EM>environment</EM> <EM>variable</EM> <EM>for</EM> <EM>these.</EM> <EM>For</EM> <EM>other</EM> <EM>special</EM> <EM>cases,</EM> <EM>you</EM>
+ <EM>should</EM> <EM>set</EM> <EM>this</EM> <EM>environment</EM> <EM>variable.</EM> <EM>Doing</EM> <EM>this</EM> <EM>tells</EM> <EM>ncurses</EM> <EM>to</EM> <EM>use</EM>
+ <EM>Unicode</EM> <EM>values</EM> <EM>which</EM> <EM>correspond</EM> <EM>to</EM> <EM>the</EM> <EM>VT100</EM> <EM>line-drawing</EM> <EM>glyphs.</EM> <EM>That</EM>
+ <EM>works</EM> <EM>for</EM> <EM>the</EM> <EM>special</EM> <EM>cases</EM> <EM>cited,</EM> <EM>and</EM> <EM>is</EM> <EM>likely</EM> <EM>to</EM> <EM>work</EM> <EM>for</EM> <EM>terminal</EM>
+ <EM>emulators.</EM>
When setting this variable, you should set it to a nonzero value.
Setting it to zero (or to a nonnumber) disables the special check for
"linux" and "screen".
- As an alternative to the environment variable, ncurses checks for an
+ As an alternative to the environment variable, <EM>ncurses</EM> checks for an
extended terminfo capability <STRONG>U8</STRONG>. This is a numeric capability which
can be compiled using <STRONG>tic</STRONG> <STRONG>-x</STRONG>. For example
U8#1, use=xterm,
The name "U8" is chosen to be two characters, to permit it to be used
- by applications that use ncurses' termcap interface.
+ by applications that use <EM>ncurses</EM>' termcap interface.
</PRE><H3><a name="h3-NCURSES_TRACE"><EM>NCURSES_TRACE</EM></a></H3><PRE>
- During initialization, the <STRONG>ncurses</STRONG> debugging library checks the
+ During initialization, the <EM>ncurses</EM> debugging library checks the
<EM>NCURSES</EM><STRONG>_</STRONG><EM>TRACE</EM> environment variable. If it is defined, to a numeric
- value, <STRONG>ncurses</STRONG> calls the <STRONG>trace</STRONG> function, using that value as the
+ value, <EM>ncurses</EM> calls the <STRONG>trace</STRONG> function, using that value as the
argument.
The argument values, which are defined in <STRONG>curses.h</STRONG>, provide several
</PRE><H3><a name="h3-TERMCAP"><EM>TERMCAP</EM></a></H3><PRE>
- If the <STRONG>ncurses</STRONG> library has been configured with <EM>termcap</EM> support,
- <STRONG>ncurses</STRONG> will check for a terminal's description in termcap form if it
+ If the <EM>ncurses</EM> library has been configured with <EM>termcap</EM> support,
+ <EM>ncurses</EM> will check for a terminal's description in termcap form if it
is not available in the terminfo database.
The <EM>TERMCAP</EM> environment variable contains either a terminal description
(with newlines stripped out), or a file name telling where the
information denoted by the <EM>TERM</EM> environment variable exists. In either
- case, setting it directs <STRONG>ncurses</STRONG> to ignore the usual place for this
+ case, setting it directs <EM>ncurses</EM> to ignore the usual place for this
information, e.g., /etc/termcap.
</PRE><H3><a name="h3-TERMINFO"><EM>TERMINFO</EM></a></H3><PRE>
- <STRONG>ncurses</STRONG> can be configured to read from multiple terminal databases.
+ <EM>ncurses</EM> can be configured to read from multiple terminal databases.
The <EM>TERMINFO</EM> variable overrides the location for the default terminal
database. Terminal descriptions (in terminal format) are stored in
terminal databases:
and the <EM>TERMINFO</EM> variable is used by <EM>curses</EM> applications on those
systems to override the default location of the terminal database.
- <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built to use hashed databases, then each entry in
+ <STRONG>o</STRONG> If <EM>ncurses</EM> is built to use hashed databases, then each entry in
this list may be the path of a hashed database file, e.g.,
/usr/share/terminfo.db
existence of the directory tree, reading it directly rather than
using the terminfo library calls.
- <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built with a support for reading termcap files
+ <STRONG>o</STRONG> If <EM>ncurses</EM> is built with a support for reading termcap files
directly, then an entry in this list may be the path of a termcap
file.
- <STRONG>o</STRONG> If the <EM>TERMINFO</EM> variable begins with "hex:" or "b64:", <STRONG>ncurses</STRONG> uses
+ <STRONG>o</STRONG> If the <EM>TERMINFO</EM> variable begins with "hex:" or "b64:", <EM>ncurses</EM> uses
the remainder of that variable as a compiled terminal description.
You might produce the base64 format using <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>:
of the default terminal database. The complete list of database
locations in order follows:
- <STRONG>o</STRONG> the last terminal database to which <STRONG>ncurses</STRONG> wrote, if any, is
+ <STRONG>o</STRONG> the last terminal database to which <EM>ncurses</EM> wrote, if any, is
searched first
<STRONG>o</STRONG> the location specified by the <EM>TERMINFO</EM> environment variable
<STRONG>o</STRONG> locations listed in the <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variable
<STRONG>o</STRONG> one or more locations whose names are configured and compiled
- into the ncurses library, i.e.,
+ into the <EM>ncurses</EM> library, i.e.,
<STRONG>o</STRONG> /usr/share/terminfo (corresponding to the <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM>
variable)
(i.e., ":") on Unix, semicolons on OS/2 EMX.
There is no corresponding feature in System V terminfo; it is an
- extension developed for <STRONG>ncurses</STRONG>.
+ extension developed for <EM>ncurses</EM>.
</PRE><H3><a name="h3-TERMPATH"><EM>TERMPATH</EM></a></H3><PRE>
- If <EM>TERMCAP</EM> does not hold a file name then <STRONG>ncurses</STRONG> checks the <EM>TERMPATH</EM>
+ If <EM>TERMCAP</EM> does not hold a file name then <EM>ncurses</EM> checks the <EM>TERMPATH</EM>
environment variable. This is a list of filenames separated by spaces
or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
- If the <EM>TERMPATH</EM> environment variable is not set, <STRONG>ncurses</STRONG> looks in the
+ If the <EM>TERMPATH</EM> environment variable is not set, <EM>ncurses</EM> looks in the
files
/etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
</PRE><H2><a name="h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></H2><PRE>
Several different configurations are possible, depending on the
- configure script options used when building <STRONG>ncurses</STRONG>. There are a few
+ configure script options used when building <EM>ncurses</EM>. There are a few
main options whose effects are visible to the applications developer
- using <STRONG>ncurses</STRONG>:
+ using <EM>ncurses</EM>:
--disable-overwrite
- The standard include for <STRONG>ncurses</STRONG> is as noted in <STRONG>SYNOPSIS</STRONG>:
+ The standard include for <EM>ncurses</EM> is as noted in <STRONG>SYNOPSIS</STRONG>:
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
- This option is used to avoid filename conflicts when <STRONG>ncurses</STRONG> is
- not the main implementation of curses of the computer. If <STRONG>ncurses</STRONG>
+ This option is used to avoid filename conflicts when <EM>ncurses</EM> is
+ not the main implementation of curses of the computer. If <EM>ncurses</EM>
is installed disabling overwrite, it puts its headers in a
subdirectory, e.g.,
than <STRONG>curses.h</STRONG> may require a specific value for <STRONG>_XOPEN_SOURCE</STRONG>
(or a system-specific symbol).
- The <STRONG>curses.h</STRONG> file which is installed for the wide-character
- library is designed to be compatible with the normal library's
- header. Only the size of the <STRONG>WINDOW</STRONG> structure differs, and very
- few applications require more than a pointer to <STRONG>WINDOW</STRONG>s.
+ The <EM>curses.h</EM> header file installed for the wide-character library
+ is designed to be compatible with the non-wide library's header.
+ Only the size of the <EM>WINDOW</EM> structure differs; few applications
+ require more than pointers to <EM>WINDOW</EM>s.
If the headers are installed allowing overwrite, the wide-
character library's headers should be installed last, to allow
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- If standard output from a <STRONG>ncurses</STRONG> program is re-directed to something
+ 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.
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
- The <STRONG>ncurses</STRONG> library can be compiled with an option (<STRONG>-DUSE_GETCAP</STRONG>) that
+ 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 <STRONG>ncurses</STRONG> startup code, at significant cost in
+ termcap compiler in the <EM>ncurses</EM> startup code, at significant cost in
core and startup cycles.
- The <STRONG>ncurses</STRONG> library includes facilities for capturing mouse events on
+ 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 <STRONG>ncurses</STRONG> library includes facilities for responding to window
+ 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 <STRONG>ncurses</STRONG> library extends the fixed set of function key capabilities
+ 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 <STRONG>ncurses</STRONG> library can exploit the capabilities of terminals which
+ 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
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 <STRONG>ncurses</STRONG> library includes a function for directing application
+ 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.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- The <STRONG>ncurses</STRONG> library is intended to be BASE-level conformant with XSI
+ 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.
A small number of local differences (that is, individual differences
- between the XSI Curses and <STRONG>ncurses</STRONG> calls) are described in <STRONG>PORTABILITY</STRONG>
+ between the XSI Curses and <EM>ncurses</EM> calls) are described in <STRONG>PORTABILITY</STRONG>
sections of the library man pages.
</PRE><H3><a name="h3-Extensions-versus-portability">Extensions versus portability</a></H3><PRE>
- Most of the extensions provided by ncurses have not been standardized.
+ 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:
<stdio.h>.
BSD curses included <curses.h> and <unctrl.h> from an internal
- header "curses.ext" ("ext" was a short name for <EM>externs</EM>).
+ header file <EM>curses.ext</EM> ("ext" abbreviated "externs").
BSD curses used <stdio.h> internally (for <STRONG>printw</STRONG> and <STRONG>scanw</STRONG>), but
nothing in <curses.h> itself relied upon <stdio.h>.
<STRONG>o</STRONG> X/Open Curses is inconsistent with respect to SVr4 regarding
<unctrl.h>.
- As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, ncurses includes <unctrl.h> from
+ As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <EM>ncurses</EM> includes <unctrl.h> from
<curses.h> (like SVr4).
<STRONG>o</STRONG> X/Open's comments about <term.h> and <termios.h> may refer to HP-UX
and AIX:
HP-UX curses includes <term.h> from <curses.h> to declare <STRONG>setupterm</STRONG>
- in curses.h, but ncurses (and Solaris curses) do not.
+ in curses.h, but <EM>ncurses</EM> (and Solaris curses) do not.
- AIX curses includes <term.h> and <termios.h>. Again, ncurses (and
+ AIX curses includes <term.h> and <termios.h>. Again, <EM>ncurses</EM> (and
Solaris curses) do not.
<STRONG>o</STRONG> X/Open says that <curses.h> <EM>may</EM> include <term.h>, but there is no
old versions of AIX curses required including <curses.h> before
including <term.h>.
- Because ncurses header files include the headers needed to define
- datatypes used in the headers, ncurses header files can be included
+ Because <EM>ncurses</EM> header files include the headers needed to define
+ datatypes used in the headers, <EM>ncurses</EM> header files can be included
in any order. But for portability, you should include <curses.h>
before <term.h>.
file does not necessarily make all symbols in it visible (there are
ifdef's to consider).
- For instance, in ncurses <wchar.h> <EM>may</EM> be included if the proper
- symbol is defined, and if ncurses is configured for wide-character
+ For instance, in <EM>ncurses</EM> <wchar.h> <EM>may</EM> be included if the proper
+ symbol is defined, and if <EM>ncurses</EM> is configured for wide-character
support. If the header is included, its symbols may be made
visible. That depends on the value used for <STRONG>_XOPEN_SOURCE</STRONG> feature
test macro.
None of the X/Open Curses implementations require an application to
include <stdarg.h> before <curses.h> because they either have
- allowed for a special type, or (like ncurses) include <stdarg.h>
+ allowed for a special type, or (like <EM>ncurses</EM>) include <stdarg.h>
directly to provide a portable interface.
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
+ncurses 6.4 2023-12-
17 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-Initialization">Initialization</a></li>
-<li><a href="#h3-Datatypes">Datatypes</a></li>
-<li><a href="#h3-Environment-variables">Environment variables</a></li>
-<li><a href="#h3-Routine-and-Argument-Names">Routine and Argument Names</a></li>
-<li><a href="#h3-Routine-Name-Index">Routine Name Index</a></li>
+<li><a href="#h3-Overview">Overview</a></li>
+<li><a href="#h3-Effects-of-GUIs-and-Environment-Variables">Effects of GUIs and Environment Variables</a></li>
+<li><a href="#h3-Naming-Conventions">Naming Conventions</a></li>
+<li><a href="#h3-Wide-and-Non-wide-Character-Configurations">Wide and Non-wide Character Configurations</a></li>
+<li><a href="#h3-Function-Name-Index">Function Name Index</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: MKncu_config.in,v 1.19 2023/12/02 21:37:31 tom Exp @
+ * @Id: MKncu_config.in,v 1.20 2023/12/16 21:43:05 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>ncursesw6-config 1 2023-12-02 ncurses 6.4 User commands</TITLE>
+<TITLE>ncursesw6-config 1 2023-12-16 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">ncursesw6-config 1 2023-12-02 ncurses 6.4 User commands</H1>
+<H1 class="no-header">ncursesw6-config 1 2023-12-16 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="ncursesw6-config.1.html">ncursesw6-config(1)</A></STRONG> User commands <STRONG><A HREF="ncursesw6-config.1.html">ncursesw6-config(1)</A></STRONG>
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="ncursesw6-config.1.html">ncursesw6-config(1)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="ncursesw6-config.1.html">ncursesw6-config(1)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* authorization. *
****************************************************************************
* Author: Thomas E. Dickey
- * @Id: new_pair.3x,v 1.43 2023/11/25 14:26:30 tom Exp @
+ * @Id: new_pair.3x,v 1.44 2023/12/16 20:32:22 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>new_pair 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>new_pair 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">new_pair 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">new_pair 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG> Library calls <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: panel.3x,v 1.59 2023/11/25 14:08:47 tom Exp @
+ * @Id: panel.3x,v 1.60 2023/12/16 21:24:43 tom Exp @
* ---------
* ---------
* ---------
<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>panel 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>panel 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">panel 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">panel 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG> Library calls <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* authorization. *
****************************************************************************
* Author: Thomas E. Dickey 1996-on
- * @Id: resizeterm.3x,v 1.53 2023/12/02 20:49:04 tom Exp @
+ * @Id: resizeterm.3x,v 1.54 2023/12/16 20:32:22 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>resizeterm 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
+<TITLE>resizeterm 3x 2023-12-16 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">resizeterm 3x 2023-12-02 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">resizeterm 3x 2023-12-16 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> Library calls <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: scr_dump.5,v 1.39 2023/11/25 14:21:48 tom Exp @
+ * @Id: scr_dump.5,v 1.40 2023/12/16 21:07:24 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>scr_dump 5 2023-11-25 ncurses 6.4 File formats</TITLE>
+<TITLE>scr_dump 5 2023-12-16 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-11-25 ncurses 6.4 File formats</H1>
+<H1 class="no-header">scr_dump 5 2023-12-16 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>
</PRE><H3><a name="h3-ncurses5-_legacy_">ncurses5 (legacy)</a></H3><PRE>
- The screen-dump feature was added to ncurses in June 1995. While there
+ The screen-dump feature was added to <EM>ncurses</EM> in June 1995. While there
were fixes and improvements in succeeding years, the basic scheme was
unchanged:
<STRONG>o</STRONG> Solaris 10 (13273 bytes)
- <STRONG>o</STRONG> ncurses5 (12888 bytes)
+ <STRONG>o</STRONG> <EM>ncurses</EM>5 (12888 bytes)
</PRE><H3><a name="h3-Solaris">Solaris</a></H3><PRE>
ensure they are not overlooked.
<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).
+ 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
nonzero. When reading back, order does not matter.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
Thomas E. Dickey
- extended screen-dump format for ncurses 6.0 (2015)
+ extended screen-dump format for <EM>ncurses</EM> 6.0 (2015)
Eric S. Raymond
- screen dump feature in ncurses 1.9.2d (1995)
+ screen dump feature in <EM>ncurses</EM> 1.9.2d (1995)
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: tabs.1,v 1.50 2023/11/25 14:32:36 tom Exp @
+ * @Id: tabs.1,v 1.51 2023/12/17 00:13:57 tom Exp @
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=PWB1/sys/source/s2/\
+ * tabs.c
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/src/cmd/tabs.c
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
+ * tabs.c
+ * https://minnie.tuhs.org/cgi-bin/utree.pl?file=SysVR4/cmd/tabs/tabs.c
+ * https://pubs.opengroup.org/onlinepubs/009604499/utilities/tabs.html
-->
<!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>tabs 1 2023-11-25 ncurses 6.4 User commands</TITLE>
+<TITLE>tabs 1 2023-12-16 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">tabs 1 2023-11-25 ncurses 6.4 User commands</H1>
+<H1 class="no-header">tabs 1 2023-12-16 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG> User commands <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>
<STRONG>-n</STRONG> This option tells <STRONG>tabs</STRONG> to check the options and run any debugging
option, but not to modify the terminal settings.
- <STRONG>-V</STRONG> reports the version of ncurses which was used in this program, and
+ <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> which was used in this program, and
exits.
The <STRONG>tabs</STRONG> program processes a single list of tab stops. The last option
The <STRONG>-d</STRONG> (debug) and <STRONG>-n</STRONG> (no-op) options are extensions not provided by
other implementations.
- A <STRONG>tabs</STRONG> utility appeared in PWB/Unix 1.0 (1977). There was a reduced
- version of the <STRONG>tabs</STRONG> utility in Unix 7th edition and in 3BSD (1979).
- The latter supported a single "-n" option (to cause the first tab stop
- to be set on the left margin). That option is not documented by POSIX.
- The PWB/Unix <STRONG>tabs</STRONG> utility, which was included in System III (1980),
- used built-in tables rather than the terminal database, to support a
- half-dozen hardcopy terminal (printer) types. It also had built-in
- logic to support the left-margin, as well as a feature for copying the
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+ A <STRONG>tabs</STRONG> utility appeared in PWB/Unix 1.0 (1977). A reduced version
+ shipped in Seventh Edition Unix (early 1979) and in 3BSD (later the
+ same year); it supported a "-n" option to set the first tab stop at the
+ left margin. That option is not documented by POSIX.
+
+ The PWB/Unix <STRONG>tabs</STRONG> utility returned in System III (1980), and used
+ built-in tables rather than the terminal database, to support a half-
+ dozen hardcopy terminal (printer) types. It also had built-in logic to
+ support setting the left margin, as well as a feature for copying the
tab settings from a file.
- Later versions of Unix, e.g., SVr4, added support for the terminal
- database, but kept the tables to support the printers. In an earlier
- development effort, the tab-stop initialization provided by <STRONG>tset</STRONG> (1982)
- and incorporated into <STRONG>tput</STRONG> uses the terminal database,
-
- The <STRONG>+m</STRONG> option was documented in the Base Specifications Issue 5
- (Unix98, 1997), and omitted in Issue 6 (Unix03, 2004) without
- documenting the rationale, though an introductory comment <EM>"and</EM>
- <EM>optionally</EM> <EM>adjusts</EM> <EM>the</EM> <EM>margin"</EM> remains, overlooked in the removal. The
- documented <STRONG>tabs</STRONG> utility in Issues 6 and later has no mechanism for
- setting margins. The <STRONG>+m</STRONG> option in this implementation differs from the
- feature in SVr4 by using terminal capabilities rather than built-in
- tables.
-
- POSIX documents no limits on the number of tab stops. Documentation
- for other implementations states that there is a limit on the number of
- tab stops (e.g., 20 in PWB/Unix's <STRONG>tabs</STRONG> utility). While some terminals
- may not accept an arbitrary number of tab stops, this implementation
- will attempt to set tab stops up to the right margin of the screen, if
- the given list happens to be that long.
-
- The <EM>Rationale</EM> section of the POSIX documentation goes into some detail
- about the ways the committee considered redesigning the <STRONG>tabs</STRONG> and <STRONG>tput</STRONG>
- utilities, without proposing an improved solution. It comments that
-
- no known historical version of tabs supports the capability of
+ Versions of the program in later releases of AT&T Unix, such as SVr4,
+ added support for the terminal database, but retained the tables to
+ support the printers. In an earlier development effort, the tab stop
+ initialization provided by <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> (1982), and incorporated into
+ <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> uses the terminal database,
+
+ The <STRONG>+m</STRONG> option was documented in the POSIX Base Specifications Issue 5
+ (Unix98, 1997), then omitted in Issue 6 (Unix03, 2004) without express
+ motivation, though an introductory comment <EM>"and</EM> <EM>optionally</EM> <EM>adjusts</EM> <EM>the</EM>
+ <EM>margin"</EM> remains, overlooked in the removal. The <STRONG>tabs</STRONG> utility
+ documented in Issues 6 and later has no mechanism for setting margins.
+ The <STRONG>+m</STRONG> option in <EM>ncurses</EM> <STRONG>tabs</STRONG> differs from the SVr4 feature by using
+ terminal capabilities rather than built-in tables.
+
+ POSIX documents no limit on the number of tab stops. Other
+ implementations impose one; the limit is 20 in PWB/Unix's <STRONG>tabs</STRONG> utility.
+ While some terminals may not accept an arbitrary number of tab stops,
+ <EM>ncurses</EM> <STRONG>tabs</STRONG> attempts to set tab stops up to the right margin if the
+ list thereof is sufficiently long.
+
+ The "Rationale" section of the Issue 6 <STRONG>tabs</STRONG> reference page details how
+ the committee considered redesigning the <STRONG>tabs</STRONG> and <STRONG>tput</STRONG> utilities,
+ without settling on an improved solution. It claims that
+
+ no known historical version of tabs supports the capability of
setting arbitrary tab stops.
- However, the <EM>Explicit</EM> <EM>Lists</EM> described in this manual page were
- implemented in PWB/Unix. Those provide the capability of setting
- abitrary tab stops.
+ Nevertheless, the feature described in subsection "Explicit Lists"
+ above was implemented in PWB/Unix, and permits the setting of abitrary
+ tab stops.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>
</PRE>
<div class="nav">
<ul>
</li>
<li><a href="#h2-FILES">FILES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
+<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: term.5,v 1.67 2023/12/02 20:49:04 tom Exp @
+ * @Id: term.5,v 1.68 2023/12/16 20:32:22 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-02 ncurses 6.4 File formats</TITLE>
+<TITLE>term 5 2023-12-16 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-02 ncurses 6.4 File formats</H1>
+<H1 class="no-header">term 5 2023-12-16 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>
</PRE><H3><a name="h3-STORAGE-LOCATION">STORAGE LOCATION</a></H3><PRE>
Compiled terminfo descriptions are placed under the directory
<STRONG>/usr/share/terminfo</STRONG>. Two configurations are supported (when building
- the <STRONG>ncurses</STRONG> libraries):
+ the <EM>ncurses</EM> libraries):
<STRONG>directory</STRONG> <STRONG>tree</STRONG>
A two-level scheme is used to avoid a linear search of a huge Unix
with the terminfo's primary name as a key, and records containing
only aliases pointing to the primary name.
- If built to write hashed databases, <STRONG>ncurses</STRONG> can still read
+ If built to write hashed databases, <EM>ncurses</EM> can still read
terminfo databases organized as a directory tree, but cannot write
entries into the directory tree. It can write (or rewrite)
entries in the hashed database.
- <STRONG>ncurses</STRONG> distinguishes the two cases in the <EM>TERMINFO</EM> and
+ <EM>ncurses</EM> distinguishes the two cases in the <EM>TERMINFO</EM> and
<EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variable by assuming a directory tree
for entries that correspond to an existing directory, and hashed
database otherwise.
binary format is used in all modern Unix systems. Each system uses a
predefined set of boolean, number or string capabilities.
- The <STRONG>ncurses</STRONG> libraries and applications support extended terminfo binary
+ The <EM>ncurses</EM> libraries and applications support extended terminfo binary
format, allowing users to define capabilities which are loaded at
runtime. This extension is made possible by using the fact that the
other implementations stop reading the terminfo data when they have
- reached the end of the size given in the header. <STRONG>ncurses</STRONG> checks the
+ reached the end of the size given in the header. <EM>ncurses</EM> checks the
size, and if it exceeds that due to the predefined data, continues to
parse according to its own scheme.
The count- and size-values for the extended string table include the
extended capability <EM>names</EM> as well as extended capability <EM>values</EM>.
- Using the counts and sizes, <STRONG>ncurses</STRONG> allocates arrays and reads data for
+ Using the counts and sizes, <EM>ncurses</EM> allocates arrays and reads data for
the extended capabilities in the same order as the header information.
The extended string table contains values for string capabilities.
extended capabilities in order, e.g., booleans, then numbers and
finally strings.
- By storing terminal descriptions in this way, <STRONG>ncurses</STRONG> is able to
+ By storing terminal descriptions in this way, <EM>ncurses</EM> is able to
provide a database useful with legacy applications, as well as
providing data for applications which need more than the predefined
- capabilities. See <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> for an overview of the way <STRONG>ncurses</STRONG> uses
+ capabilities. See <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> for an overview of the way <EM>ncurses</EM> uses
this extended information.
Applications which manipulate terminal data can use the definitions
</PRE><H3><a name="h3-EXTENDED-NUMBER-FORMAT">EXTENDED NUMBER FORMAT</a></H3><PRE>
- On occasion, 16-bit signed integers are not large enough. With <STRONG>ncurses</STRONG>
+ On occasion, 16-bit signed integers are not large enough. With <EM>ncurses</EM>
6.1, a new format was introduced by making a few changes to the legacy
format:
This implementation is by default compatible with the binary terminfo
format used by Solaris curses, except in a few less-used details where
it was found that the latter did not match X/Open Curses. The format
- used by the other Unix versions can be matched by building ncurses with
+ used by the other Unix versions can be matched by building <EM>ncurses</EM> with
different configuration options.
</PRE><H3><a name="h3-Mixed-case-terminal-names">Mixed-case terminal names</a></H3><PRE>
A small number of terminal descriptions use uppercase characters in
their names. If the underlying filesystem ignores the difference
- between uppercase and lowercase, <STRONG>ncurses</STRONG> represents the "first
+ between uppercase and lowercase, <EM>ncurses</EM> represents the "first
character" of the terminal name used as the intermediate level of a
directory tree in (two-character) hexadecimal form.
</PRE><H3><a name="h3-Limits">Limits</a></H3><PRE>
- <STRONG>ncurses</STRONG> stores compiled terminal descriptions in three related formats,
+ <EM>ncurses</EM> stores compiled terminal descriptions in three related formats,
described in the sections
<STRONG>o</STRONG> <STRONG>LEGACY</STRONG> <STRONG>STORAGE</STRONG> <STRONG>FORMAT</STRONG>, and
The legacy storage format and the extended number format differ by the
types of numeric capability which they can store (i.e., 16-bit versus
- 32-bit integers). The extended storage format introduced by ncurses
+ 32-bit integers). The extended storage format introduced by <EM>ncurses</EM>
5.0 adds data to either of these formats.
Some limitations apply:
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
Thomas E. Dickey
- extended terminfo format for ncurses 5.0
- hashed database support for ncurses 5.6
- extended number support for ncurses 6.1
+ extended terminfo format for <EM>ncurses</EM> 5.0
+ hashed database support for <EM>ncurses</EM> 5.6
+ extended number support for <EM>ncurses</EM> 6.1
Eric S. Raymond
documented legacy terminfo format, e.g., from <EM>pcurses</EM>.
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
+ncurses 6.4 2023-12-
16 <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.55 2023/11/25 19:52:56 tom Exp @
+ * @Id: terminfo.head,v 1.57 2023/12/18 01:15:58 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.137 2023/12/03 00:17:23 tom Exp @
+ * @Id: terminfo.tail,v 1.139 2023/12/17 22:56:21 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-11-25 ncurses 6.4 File formats</TITLE>
+<TITLE>terminfo 5 2023-12-17 ncurses 6.4 File formats</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">terminfo 5 2023-11-25 ncurses 6.4 File formats</H1>
+<H1 class="no-header">terminfo 5 2023-12-17 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 <STRONG>ncurses</STRONG> version 6.4 (patch 20231202).
+ This manual describes <EM>ncurses</EM> version 6.4 (patch 20231217).
</PRE><H3><a name="h3-Terminfo-Entry-Syntax">Terminfo Entry Syntax</a></H3><PRE>
which are awkward or impossible to represent by reusing the predefined
capabilities.
- <STRONG>ncurses</STRONG> addresses this limitation by allowing user-defined
+ <EM>ncurses</EM> addresses this limitation by allowing user-defined
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
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 ncurses library provides the data
+ available to applications. The <EM>ncurses</EM> library provides the data
leaving most of the behavior to applications:
<STRONG>o</STRONG> User-defined capability strings whose name begins with "k" are
numbered keys and the handful of special named keys) is best done using
the longer names available using terminfo.
- The ncurses library uses a few of these user-defined capabilities, as
+ The <EM>ncurses</EM> library uses a few of these user-defined capabilities, as
described in <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>. Other user-defined capabilities (including
function keys) are described in the terminal database, in the section
on <EM>NCURSES</EM> <EM>USER-DEFINABLE</EM> <EM>CAPABILITIES</EM>
<STRONG>o</STRONG> Both <STRONG>\E</STRONG> and <STRONG>\e</STRONG> map to an ESCAPE character,
- <STRONG>o</STRONG> <STRONG>^</STRONG><EM>x</I<STRONG>x</STRONG> maps to a control-<EM>x</EM> for any appropriate <EM>x</EM>, and
+ <STRONG>o</STRONG> <STRONG>^</STRONG><STRONG><EM>x</EM></STRONG> maps to a control-<EM>x</EM> for any appropriate <EM>x</EM>, and
<STRONG>o</STRONG> the sequences
</PRE><H3><a name="h3-Fetching-Compiled-Descriptions">Fetching Compiled Descriptions</a></H3><PRE>
- Terminal descriptions in <STRONG>ncurses</STRONG> are stored in terminal databases.
+ Terminal descriptions in <EM>ncurses</EM> are stored in terminal databases.
These databases, which are found by their pathname, may be configured
either as directory trees or hashed databases (see <STRONG><A HREF="term.5.html">term(5)</A></STRONG>),
The library uses a compiled-in list of pathnames, which can be
overridden by environment variables. Before starting to search,
- <STRONG>ncurses</STRONG> checks the search list, eliminating duplicates and pathnames
- where no terminal database is found. The <STRONG>ncurses</STRONG> library reads the
+ <EM>ncurses</EM> checks the search list, eliminating duplicates and pathnames
+ where no terminal database is found. The <EM>ncurses</EM> library reads the
first description which passes its consistency checks.
<STRONG>o</STRONG> The environment variable <STRONG>TERMINFO</STRONG> is checked first, for a terminal
database containing the terminal description.
- <STRONG>o</STRONG> Next, <STRONG>ncurses</STRONG> looks in <EM>$HOME/.terminfo</EM> for a compiled description.
+ <STRONG>o</STRONG> Next, <EM>ncurses</EM> looks in <EM>$HOME/.terminfo</EM> for a compiled description.
This is an optional feature which may be omitted entirely from the
library, or limited to prevent accidental use by privileged
applications.
- <STRONG>o</STRONG> Next, if the environment variable <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> is set, <STRONG>ncurses</STRONG>
+ <STRONG>o</STRONG> Next, if the environment variable <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> is set, <EM>ncurses</EM>
interprets the contents of that variable as a list of colon-
separated pathnames of terminal databases to be searched.
colon, or contains adjacent colons) is interpreted as the system
location <EM>/usr/share/terminfo</EM>.
- <STRONG>o</STRONG> Finally, <STRONG>ncurses</STRONG> searches these compiled-in locations:
+ <STRONG>o</STRONG> Finally, <EM>ncurses</EM> searches these compiled-in locations:
<STRONG>o</STRONG> a list of directories (/usr/share/terminfo), and
The <STRONG>TERMINFO</STRONG> variable can contain a terminal description instead of the
pathname of a terminal database. If this variable begins with "hex:"
- or "b64:" then <STRONG>ncurses</STRONG> reads a terminal description from hexadecimal-
+ or "b64:" then <EM>ncurses</EM> reads a terminal description from hexadecimal-
or base64-encoded data, and if that description matches the name
sought, will use that. This encoded data can be set using the "-Q"
option of <STRONG>tic</STRONG> or <STRONG>infocmp</STRONG>.
- The preceding addresses the usual configuration of <STRONG>ncurses</STRONG>, which uses
+ The preceding addresses the usual configuration of <EM>ncurses</EM>, which uses
terminal descriptions prepared in <EM>terminfo</EM> format. While <EM>termcap</EM> is
- less expressive, <STRONG>ncurses</STRONG> can also be configured to read <EM>termcap</EM>
+ less expressive, <EM>ncurses</EM> can also be configured to read <EM>termcap</EM>
descriptions. In that configuration, it checks the <EM>TERMCAP</EM> and
<EM>TERMPATH</EM> variables (for content and search path, respectively) after
the system terminal database.
<EM>static</EM> variables. They are the same. Like SVr4 curses, XPG4
curses does not initialize these explicitly.
- <STRONG>o</STRONG> Before version 6.3, ncurses stores both <EM>dynamic</EM> and <EM>static</EM>
+ <STRONG>o</STRONG> Before version 6.3, <EM>ncurses</EM> stores both <EM>dynamic</EM> and <EM>static</EM>
variables in persistent storage, initialized to zeros.
- <STRONG>o</STRONG> Beginning with version 6.3, ncurses stores <EM>static</EM> and <EM>dynamic</EM>
+ <STRONG>o</STRONG> Beginning with version 6.3, <EM>ncurses</EM> stores <EM>static</EM> and <EM>dynamic</EM>
variables in the same manner as SVr4.
- <STRONG>o</STRONG> Unlike other implementations, ncurses zeros dynamic
+ <STRONG>o</STRONG> Unlike other implementations, <EM>ncurses</EM> zeros dynamic
variables before the first <STRONG>%g</STRONG> or <STRONG>%P</STRONG> operator.
- <STRONG>o</STRONG> Like SVr2, the scope of dynamic variables in ncurses is
+ <STRONG>o</STRONG> Like SVr2, the scope of dynamic variables in <EM>ncurses</EM> is
within the current call to <STRONG>tparm</STRONG>. Use static variables if
persistent storage is needed.
available.)
-</PRE><H3><a name="h3-Insert_
delete-line-and-vertical-motions">Insert/delete line and vertical motions</a></H3><PRE>
+</PRE><H3><a name="h3-Insert_
Delete-Line-and-Vertical-Motions">Insert/Delete Line and Vertical Motions</a></H3><PRE>
If the terminal can open a new blank line before the line where the
cursor is, this should be given as <STRONG>il1</STRONG>; this is done only from the
first position of a line. The cursor must then appear on the newly
The boolean capability <STRONG>eslok</STRONG> specifies that escape sequences, tabs,
etc., work ordinarily in the status line.
- The <STRONG>ncurses</STRONG> implementation does not yet use any of these capabilities.
+ The <EM>ncurses</EM> implementation does not yet use any of these capabilities.
They are documented here in case they ever become important.
<STRONG>o</STRONG> Tektronix-like terminals have a predefined set of <EM>N</EM> colors (where <EM>N</EM>
is usually 8), and can set character-cell foreground and background
- characters independently, mixing them into <EM>N</EM> * <EM>N</EM> color-pairs.
+ characters independently, mixing them into <EM>N</EM> * <EM>N</EM> color pairs.
<STRONG>o</STRONG> On HP-like terminals, the user must set each color pair up
separately (foreground and background are not independently
- settable). Up to <EM>M</EM> color-pairs may be set up from 2*<EM>M</EM> different
+ settable). Up to <EM>M</EM> color pairs may be set up from 2*<EM>M</EM> different
colors. ANSI-compatible terminals are Tektronix-like.
Some basic color capabilities are independent of the color method. The
numeric capabilities <STRONG>colors</STRONG> and <STRONG>pairs</STRONG> specify the maximum numbers of
- colors and color-pairs that can be displayed simultaneously. The <STRONG>op</STRONG>
+ colors and color pairs that can be displayed simultaneously. The <STRONG>op</STRONG>
(original pair) string resets foreground and background colors to their
default values for the terminal. The <STRONG>oc</STRONG> string resets all colors or
- color-pairs to their default values for the terminal. Some terminals
+ 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>.
The <STRONG>setaf</STRONG>/<STRONG>setab</STRONG> and <STRONG>setf</STRONG>/<STRONG>setb</STRONG> capabilities take a single numeric
argument each. Argument values 0-7 of <STRONG>setaf</STRONG>/<STRONG>setab</STRONG> are portably defined
as follows (the middle column is the symbolic #define available in the
- header for the <STRONG>curses</STRONG> or <STRONG>ncurses</STRONG> libraries). The terminal hardware is
+ header for the <STRONG>curses</STRONG> or <EM>ncurses</EM> libraries). The terminal hardware is
free to map these as it likes, but the RGB values indicate normal
locations in color space.
It is important to not confuse the two sets of color capabilities;
otherwise red/blue will be interchanged on the display.
- On an HP-like terminal, use <STRONG>scp</STRONG> with a color-pair number parameter to
+ On an HP-like terminal, use <STRONG>scp</STRONG> with a color pair number parameter to
set which color pair is current.
Some terminals allow the <EM>color</EM> <EM>values</EM> to be modified:
Saturation) indices. The ranges are terminal-dependent.
<STRONG>o</STRONG> On an HP-like terminal, <STRONG>initp</STRONG> may give a capability for changing a
- color-pair value. It will take seven parameters; a color-pair
+ color pair value. It will take seven parameters; a color pair
number (0 to <STRONG>max_pairs</STRONG> - 1), and two triples describing first
background and then foreground colors. These parameters must be
(Red, Green, Blue) or (Hue, Lightness, Saturation) depending on
<STRONG>hls</STRONG>.
On some color terminals, colors collide with highlights. You can
- register these collisions with the <STRONG>ncv</STRONG> capability. This is a bit-mask
+ register these collisions with the <STRONG>ncv</STRONG> capability. This is a bit mask
of attributes not to be used when colors are enabled. The
correspondence with the attributes understood by <STRONG>curses</STRONG> is as follows:
with the foreground color blue and is not available in color mode.
These should have an <STRONG>ncv</STRONG> capability of 2.
- SVr4 curses does nothing with <STRONG>ncv</STRONG>, ncurses recognizes it and optimizes
+ SVr4 curses does nothing with <STRONG>ncv</STRONG>, <EM>ncurses</EM> recognizes it and optimizes
the output in favor of colors.
If the terminal requires other than a null (zero) character as a pad,
then this can be given as pad. Only the first character of the pad
string is used. If the terminal does not have a pad character, specify
- npc. Note that ncurses implements the termcap-compatible <STRONG>PC</STRONG> variable;
+ npc. Note that <EM>ncurses</EM> implements the termcap-compatible <STRONG>PC</STRONG> variable;
though the application may set this value to something other than a
- null, ncurses will test <STRONG>npc</STRONG> first and use napms if the terminal has no
+ null, <EM>ncurses</EM> will test <STRONG>npc</STRONG> first and use napms if the terminal has no
pad character.
If the terminal can move up or down half a line, this can be indicated
while an <STRONG>mc5p</STRONG> is in effect.
-</PRE><H3><a name="h3-Glitches-and-Brain
damage">Glitches and Braindamage</a></H3><PRE>
+</PRE><H3><a name="h3-Glitches-and-Brain
-Damage">Glitches and Brain Damage</a></H3><PRE>
Hazeltine terminals, which do not allow "~" characters to be displayed
should indicate <STRONG>hz</STRONG>.
teleray_glitch. This glitch is also taken to mean that it is not
possible to position the cursor on top of a "magic cookie", that to
erase standout mode it is instead necessary to use delete and insert
- line. The ncurses implementation ignores this glitch.
+ line. The <EM>ncurses</EM> implementation ignores this glitch.
The Beehive Superbee, which is unable to correctly transmit the escape
or control/C characters, has <STRONG>xsb</STRONG>, indicating that the f1 key is used
terminal types and users whose <EM>TERM</EM> variable does not have a termcap
entry.
- When in -C (translate to termcap) mode, the <STRONG>ncurses</STRONG> implementation of
+ When in -C (translate to termcap) mode, the <EM>ncurses</EM> implementation of
<STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG> issues warning messages when the pre-tc length of a termcap
translation is too long. The -c (check) option also checks resolved
(after tc expansion) lengths.
-</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- Do not count on compiled (binary) <EM>terminfo</EM> entries being portable
- between commercial Unix systems. At least two implementations of
- <EM>terminfo</EM> (those of HP-UX and AIX) diverged from those of other System V
- Unices after SVr1, adding extension capabilities to the string table
- that (in the binary format) collide with subsequent System V and XSI
- Curses extensions.
+</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
+ <EM>/usr/share/terminfo</EM>
+ compiled terminal description database directory
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
- Searching for terminal descriptions in <EM>$HOME/.terminfo</EM> and
+ Searching for terminal descriptions in <EM>$HOME/.terminfo</EM> and
<EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> is not supported by older implementations.
- Some SVr4 <STRONG>curses</STRONG> implementations, and all previous to SVr4, do not
+ Some SVr4 <STRONG>curses</STRONG> implementations, and all previous to SVr4, do not
interpret the %A and %O operators in parameter strings.
- SVr4/XPG4 do not specify whether <STRONG>msgr</STRONG> licenses movement while in an
- alternate-character-set mode (such modes may, among other things, map
- CR and NL to characters that do not trigger local motions). The
- <STRONG>ncurses</STRONG> implementation ignores <STRONG>msgr</STRONG> in <STRONG>ALTCHARSET</STRONG> mode. This raises
+ SVr4/XPG4 do not specify whether <STRONG>msgr</STRONG> licenses movement while in an
+ alternate-character-set mode (such modes may, among other things, map
+ CR and NL to characters that do not trigger local motions). The
+ <EM>ncurses</EM> implementation ignores <STRONG>msgr</STRONG> in <STRONG>ALTCHARSET</STRONG> mode. This raises
the possibility that an XPG4 implementation making the opposite
- interpretation may need terminfo entries made for <STRONG>ncurses</STRONG> to have <STRONG>msgr</STRONG>
+ interpretation may need terminfo entries made for <EM>ncurses</EM> to have <STRONG>msgr</STRONG>
turned off.
- The <STRONG>ncurses</STRONG> library handles insert-character and insert-character modes
- in a slightly non-standard way to get better update efficiency. See
+ The <EM>ncurses</EM> library handles insert-character and insert-character modes
+ in a slightly non-standard way to get better update efficiency. See
the <STRONG>Insert/Delete</STRONG> <STRONG>Character</STRONG> subsection above.
- The parameter substitutions for <STRONG>set_clock</STRONG> and <STRONG>display_clock</STRONG> are not
- documented in SVr4 or the XSI Curses standard. They are deduced from
+ The parameter substitutions for <STRONG>set_clock</STRONG> and <STRONG>display_clock</STRONG> are not
+ documented in SVr4 or the XSI Curses standard. They are deduced from
the documentation for the AT&T 505 terminal.
- Be careful assigning the <STRONG>kmous</STRONG> capability. The <STRONG>ncurses</STRONG> library wants
- to interpret it as <STRONG>KEY_MOUSE</STRONG>, for use by terminals and emulators like
- xterm that can return mouse-tracking information in the keyboard-input
+ Be careful assigning the <STRONG>kmous</STRONG> capability. The <EM>ncurses</EM> library wants
+ to interpret it as <STRONG>KEY_MOUSE</STRONG>, for use by terminals and emulators like
+ xterm that can return mouse-tracking information in the keyboard-input
stream.
- X/Open Curses does not mention italics. Portable applications must
- assume that numeric capabilities are signed 16-bit values. This
- includes the <EM>no</EM><STRONG>_</STRONG><EM>color</EM><STRONG>_</STRONG><EM>video</EM> (<STRONG>ncv</STRONG>) capability. The 32768 mask value
- used for italics with <STRONG>ncv</STRONG> can be confused with an absent or cancelled
- <STRONG>ncv</STRONG>. If italics should work with colors, then the <STRONG>ncv</STRONG> value must be
+ X/Open Curses does not mention italics. Portable applications must
+ assume that numeric capabilities are signed 16-bit values. This
+ includes the <EM>no</EM><STRONG>_</STRONG><EM>color</EM><STRONG>_</STRONG><EM>video</EM> (<STRONG>ncv</STRONG>) capability. The 32768 mask value
+ used for italics with <STRONG>ncv</STRONG> can be confused with an absent or cancelled
+ <STRONG>ncv</STRONG>. If italics should work with colors, then the <STRONG>ncv</STRONG> value must be
specified, even if it is zero.
- Different commercial ports of <EM>terminfo</EM> and <EM>curses</EM> support different
- subsets of XSI Curses and (in some cases) different extensions. Here
- is a summary, accurate as of October 1995, after which the commercial
+ Different commercial ports of <EM>terminfo</EM> and <EM>curses</EM> support different
+ subsets of XSI Curses and (in some cases) different extensions. Here
+ is a summary, accurate as of October 1995, after which the commercial
Unix market contracted and lost diversity.
<STRONG>o</STRONG> SVr4, Solaris, and <EM>ncurses</EM> support all SVr4 capabilities.
- <STRONG>o</STRONG> IRIX supports the SVr4 set and adds one undocumented extended
+ <STRONG>o</STRONG> IRIX supports the SVr4 set and adds one undocumented extended
string capability (<STRONG>set_pglen</STRONG>).
- <STRONG>o</STRONG> SVr1 and Ultrix support a restricted subset of <EM>terminfo</EM>
- capabilities. The Booleans end with <STRONG>xon_xoff</STRONG>; the numerics with
+ <STRONG>o</STRONG> SVr1 and Ultrix support a restricted subset of <EM>terminfo</EM>
+ capabilities. The Booleans end with <STRONG>xon_xoff</STRONG>; the numerics with
<STRONG>width_status_line</STRONG>; and the strings with <STRONG>prtr_non</STRONG>.
- <STRONG>o</STRONG> HP/UX supports the SVr1 subset, plus the SVr[234] numerics
- <STRONG>num_labels</STRONG>, <STRONG>label_height</STRONG>, <STRONG>label_width</STRONG>, plus function keys 11
- through 63, plus <STRONG>plab_norm</STRONG>, <STRONG>label_on</STRONG>, and <STRONG>label_off</STRONG>, plus a number
+ <STRONG>o</STRONG> HP/UX supports the SVr1 subset, plus the SVr[234] numerics
+ <STRONG>num_labels</STRONG>, <STRONG>label_height</STRONG>, <STRONG>label_width</STRONG>, plus function keys 11
+ through 63, plus <STRONG>plab_norm</STRONG>, <STRONG>label_on</STRONG>, and <STRONG>label_off</STRONG>, plus a number
of incompatible string table extensions.
- <STRONG>o</STRONG> AIX supports the SVr1 subset, plus function keys 11 through 63,
+ <STRONG>o</STRONG> AIX supports the SVr1 subset, plus function keys 11 through 63,
plus a number of incompatible string table extensions.
<STRONG>o</STRONG> OSF/1 supports both the SVr4 set and the AIX extensions.
-</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
- <EM>/usr/share/terminfo</EM>
- compiled terminal description database directory
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+ Do not count on compiled (binary) <EM>terminfo</EM> entries being portable
+ between commercial Unix systems. At least two implementations of
+ <EM>terminfo</EM> (those of HP-UX and AIX) diverged from those of other System V
+ Unices after SVr1, adding extension capabilities to the string table
+ that (in the binary format) collide with subsequent System V and XSI
+ Curses extensions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
+ncurses 6.4 2023-1
2-17 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h3-Cursor-Motions">Cursor Motions</a></li>
<li><a href="#h3-Margins">Margins</a></li>
<li><a href="#h3-Area-Clears">Area Clears</a></li>
-<li><a href="#h3-Insert_delete-line-and-vertical-motions">Insert/delete line and vertical motions</a></li>
+<li><a href="#h3-Insert_Delete-Line-and-Vertical-Motions">Insert/Delete Line and Vertical Motions</a></li>
<li><a href="#h3-Insert_Delete-Character">Insert/Delete Character</a></li>
<li><a href="#h3-Highlighting_-Underlining_-and-Visible-Bells">Highlighting, Underlining, and Visible Bells</a></li>
<li><a href="#h3-Keypad-and-Function-Keys">Keypad and Function Keys</a></li>
<li><a href="#h3-Line-Graphics">Line Graphics</a></li>
<li><a href="#h3-Color-Handling">Color Handling</a></li>
<li><a href="#h3-Miscellaneous">Miscellaneous</a></li>
-<li><a href="#h3-Glitches-and-Braindamage">Glitches and Braindamage</a></li>
+<li><a href="#h3-Glitches-and-Brain-Damage">Glitches and Brain Damage</a></li>
<li><a href="#h3-Pitfalls-of-Long-Entries">Pitfalls of Long Entries</a></li>
</ul>
</li>
-<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
-<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
<li><a href="#h2-FILES">FILES</a></li>
+<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-AUTHORS">AUTHORS</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: tic.1m,v 1.103 2023/12/02 20:50:53 tom Exp @
+ * @Id: tic.1m,v 1.104 2023/12/16 20:33:11 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-02 ncurses 6.4 User commands</TITLE>
+<TITLE>tic 1m 2023-12-16 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-02 ncurses 6.4 User commands</H1>
+<H1 class="no-header">tic 1m 2023-12-16 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>-I</STRONG> Force source translation to terminfo format.
- <STRONG>-K</STRONG> Suppress some longstanding ncurses extensions to termcap format,
+ <STRONG>-K</STRONG> Suppress some longstanding <EM>ncurses</EM> extensions to termcap format,
e.g., "\s" for space.
<STRONG>-L</STRONG> Force source translation to terminfo format using the long C
file. Normally, it infers data which is commonly missing in older
terminfo data, or in termcaps.
- <STRONG>-V</STRONG> reports the version of ncurses which was used in this program, and
+ <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> which was used in this program, and
exits.
<STRONG>-v</STRONG><EM>n</EM> specifies that (verbose) output be written to standard error trace
The optional parameter <EM>n</EM> is a number from 1 to 9, inclusive,
indicating the desired level of detail of information.
- <STRONG>o</STRONG> If ncurses is built without tracing support, the optional
+ <STRONG>o</STRONG> If <EM>ncurses</EM> is built without tracing support, the optional
parameter is ignored.
<STRONG>o</STRONG> If <EM>n</EM> is omitted, the default level is 1.
<STRONG>-0</STRONG> <STRONG>-1</STRONG> <STRONG>-C</STRONG> <STRONG>-G</STRONG> <STRONG>-I</STRONG> <STRONG>-N</STRONG> <STRONG>-R</STRONG> <STRONG>-T</STRONG> <STRONG>-V</STRONG> <STRONG>-a</STRONG> <STRONG>-e</STRONG> <STRONG>-f</STRONG> <STRONG>-g</STRONG> <STRONG>-o</STRONG> <STRONG>-r</STRONG> <STRONG>-s</STRONG> <STRONG>-t</STRONG> <STRONG>-x</STRONG>
- <STRONG>o</STRONG> The NetBSD <STRONG>tic</STRONG> supports a few of the ncurses options
+ <STRONG>o</STRONG> The NetBSD <STRONG>tic</STRONG> supports a few of the <EM>ncurses</EM> options
<STRONG>-a</STRONG> <STRONG>-o</STRONG> <STRONG>-x</STRONG>
Shortly after Issue 7 was released, Tru64 was discontinued. As of
2019, the surviving implementations of <STRONG>tic</STRONG> are SVr4 (AIX, HP-UX and
- Solaris), ncurses and NetBSD curses. The SVr4 <STRONG>tic</STRONG> programs all support
+ Solaris), <EM>ncurses</EM> and NetBSD curses. The SVr4 <STRONG>tic</STRONG> programs all support
the <STRONG>-v</STRONG> option. The NetBSD <STRONG>tic</STRONG> program follows X/Open's documentation,
omitting the <STRONG>-v</STRONG> option.
Release 4, the table of capabilities grew from 180 (<EM>pcurses</EM>) to 464
(Solaris).
- In early development of ncurses (1993), Zeyd Ben-Halim used the table
+ In early development of <EM>ncurses</EM> (1993), Zeyd Ben-Halim used the table
from <EM>mytinfo</EM> to extend the <EM>pcurses</EM> table to 469 capabilities (456
matched SVr4, 8 were only in SVr4, 13 were not in SVr4). Of those 13,
11 were ultimately discarded (perhaps to match the draft of X/Open
Curses). The exceptions were <STRONG>memory_lock_above</STRONG> and <STRONG>memory_unlock</STRONG> (see
<STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>).
- Eric Raymond incorporated parts of <EM>mytinfo</EM> into ncurses to implement
+ Eric Raymond incorporated parts of <EM>mytinfo</EM> into <EM>ncurses</EM> to implement
the termcap-to-terminfo source conversion, and extended that to begin
development of the corresponding terminfo-to-termcap source conversion,
Thomas Dickey completed that development over the course of several
capabilities.
In 2010, Roy Marples provided a <STRONG>tic</STRONG> program and terminfo library for
- NetBSD. That implementation adapts several features from ncurses,
+ NetBSD. That implementation adapts several features from <EM>ncurses</EM>,
including <STRONG>tic</STRONG>'s <STRONG>-x</STRONG> option.
The <STRONG>-c</STRONG> option tells <STRONG>tic</STRONG> to check for problems in the terminfo source
<STRONG>o</STRONG> <EM>pcurses</EM> had 8 warnings
- <STRONG>o</STRONG> ncurses in 1996 had 16 warnings
+ <STRONG>o</STRONG> <EM>ncurses</EM> in 1996 had 16 warnings
<STRONG>o</STRONG> Solaris (SVr4) curses has 28 warnings
<STRONG>o</STRONG> NetBSD tic in 2019 has 19 warnings.
- <STRONG>o</STRONG> ncurses in 2019 has 96 warnings
+ <STRONG>o</STRONG> <EM>ncurses</EM> in 2019 has 96 warnings
- The checking done in ncurses' <STRONG>tic</STRONG> helps with the conversion to termcap,
+ The checking done in <EM>ncurses</EM>' <STRONG>tic</STRONG> helps with the conversion to termcap,
as well as pointing out errors and inconsistencies. It is also used to
ensure consistency with the user-defined capabilities. There are 527
- distinct capabilities in ncurses' terminal database; 128 of those are
+ distinct capabilities in <EM>ncurses</EM>' terminal database; 128 of those are
user-defined.
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>
+ncurses 6.4 2023-12-
16 <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: toe.1m,v 1.58 2023/12/02 20:49:04 tom Exp @
+ * @Id: toe.1m,v 1.59 2023/12/16 21:01:59 tom Exp @
* toe -a | grep -E '^(xterm|vt)'
* The next row overruns the line length on DWB nroff (65n).
* toe -as | grep -E '(^-+>|:.(xterm|vt))'
<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>toe 1m 2023-12-02 ncurses 6.4 User commands</TITLE>
+<TITLE>toe 1m 2023-12-16 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">toe 1m 2023-12-02 ncurses 6.4 User commands</H1>
+<H1 class="no-header">toe 1m 2023-12-16 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG> User commands <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
<STRONG>toe</STRONG> reports to the standard output stream the (primary) names and
descriptions of the terminal types available to the <EM>terminfo</EM> library.
- Each <EM>directory</EM> operand is scanned; if none are given, <STRONG>toe</STRONG> scans the the
- default <EM>terminfo</EM> directory.
+ Each <EM>directory</EM> is scanned; if none are given, <STRONG>toe</STRONG> scans the default
+ <EM>terminfo</EM> directory.
</PRE><H2><a name="h2-OPTIONS">OPTIONS</a></H2><PRE>
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="toe.1m.html">toe(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.91 2023/12/02 20:49:04 tom Exp @
+ * @Id: tput.1,v 1.92 2023/12/16 20:32:22 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>tput 1 2023-12-02 ncurses 6.4 User commands</TITLE>
+<TITLE>tput 1 2023-12-16 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-02 ncurses 6.4 User commands</H1>
+<H1 class="no-header">tput 1 2023-12-16 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>
variable <EM>TERM</EM>. If <STRONG>-T</STRONG> is specified, then the shell variables
<EM>LINES</EM> and <EM>COLUMNS</EM> will also be ignored.
- <STRONG>-V</STRONG> reports the version of ncurses which was used in this program,
+ <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> which was used in this program,
and exits.
<STRONG>-x</STRONG> prevents <STRONG>tput</STRONG> from attempting to clear the scrollback buffer.
<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 ncurses 6.1, the two utilities were different from each other:
+ 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
done with <STRONG>tput</STRONG>).
<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 ncurses 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
before falling back to "/dev/tty" and finally just assumes a 1200Bd
terminal. When updating terminal modes, it ignores errors.
- Until changes made after ncurses 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
to open a terminal, e.g., when running in <STRONG>cron(1)</STRONG>, <STRONG>tput</STRONG> will return
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 ncurses to
+ 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; ncurses provides it
+ 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
2010, NetBSD's <STRONG>tput</STRONG> uses terminfo names. Before that, it (like
FreeBSD) recognized termcap names.
- Beginning in 2021, FreeBSD uses the ncurses <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
absent or cancelled numeric value versus an (unsigned) exit code.
The various Unix systems (AIX, HP-UX, Solaris) use the same exit-codes
- as ncurses.
+ as <EM>ncurses</EM>.
NetBSD curses documents different exit codes which do not correspond to
- either ncurses or X/Open.
+ either <EM>ncurses</EM> or X/Open.
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
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 ncurses in June 1995.
+ <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.
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
+ncurses 6.4 2023-12-
16 <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: tset.1,v 1.77 2023/12/02 20:52:24 tom Exp @
+ * @Id: tset.1,v 1.78 2023/12/16 20:32:22 tom Exp @
* https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s6/reset.c
* https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
* reset.c
<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>tset 1 2023-12-02 ncurses 6.4 User commands</TITLE>
+<TITLE>tset 1 2023-12-16 ncurses 6.4 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">tset 1 2023-12-02 ncurses 6.4 User commands</H1>
+<H1 class="no-header">tset 1 2023-12-16 ncurses 6.4 User commands</H1>
<PRE>
<STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> User commands <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>
variable <EM>TERM</EM> to the standard output; see subsection "Setting the
Environment".
- <STRONG>-V</STRONG> reports the version of ncurses which was used in this program, and
+ <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> which was used in this program, and
exits.
<STRONG>-w</STRONG> Resize the window to match the size deduced via <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>.
few exceptions we shall consider now.
A few options are different because the <EM>TERMCAP</EM> variable is no longer
- supported under terminfo-based <STRONG>ncurses</STRONG>:
+ supported under terminfo-based <EM>ncurses</EM>:
<STRONG>o</STRONG> The <STRONG>-S</STRONG> option of BSD <STRONG>tset</STRONG> no longer works; it prints an error
message to the standard error and dies.
to set the window size if <STRONG>tset</STRONG> is not able to obtain the window
size from the operating system.
- <STRONG>o</STRONG> In ncurses, <STRONG>tset</STRONG> obtains the window size using <STRONG>setupterm</STRONG>, which may
+ <STRONG>o</STRONG> In <EM>ncurses</EM>, <STRONG>tset</STRONG> obtains the window size using <STRONG>setupterm</STRONG>, which may
be from the operating system, the <EM>LINES</EM> and <EM>COLUMNS</EM> environment
variables or the terminal description.
-ncurses 6.4 2023-12-
02 <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>
+ncurses 6.4 2023-12-
16 <STRONG><A HREF="tset.1.html">tset(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.41 2023/10/07 21:19:07 tom Exp @
+ * @Id: user_caps.5,v 1.42 2023/12/16 20:32:22 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-10-07 ncurses 6.4 File formats</TITLE>
+<TITLE>user_caps 5 2023-12-16 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-10-07 ncurses 6.4 File formats</H1>
+<H1 class="no-header">user_caps 5 2023-12-16 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>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
</PRE><H3><a name="h3-Background">Background</a></H3><PRE>
- Before ncurses 5.0, terminfo databases used a <EM>fixed</EM> <EM>repertoire</EM> of
+ Before <EM>ncurses</EM> 5.0, terminfo databases used a <EM>fixed</EM> <EM>repertoire</EM> of
terminal capabilities designed for the SVr2 terminal database in 1984,
and extended in stages through SVr4 (1989), and standardized in the
Single Unix Specification beginning in 1995.
needed, while others were added (out of order) to comply with
X/Open Curses.
- While ncurses' repertoire of predefined capabilities is closest to
+ While <EM>ncurses</EM>' repertoire of predefined capabilities is closest to
Solaris, Solaris's terminfo database has a few differences from the
- list published by X/Open Curses. For example, ncurses can be
+ list published by X/Open Curses. For example, <EM>ncurses</EM> can be
configured with tables which match the terminal databases for AIX,
HP-UX or OSF/1, rather than the default Solaris-like configuration.
- <STRONG>o</STRONG> In SVr4 curses and ncurses, the terminal database is defined at
+ <STRONG>o</STRONG> In SVr4 curses and <EM>ncurses</EM>, the terminal database is defined at
compile-time using a text file which lists the different terminal
capabilities.
In principle, the text-file can be extended, but doing this
requires recompiling and reinstalling the library. The text-file
- used in ncurses for terminal capabilities includes details for
+ used in <EM>ncurses</EM> for terminal capabilities includes details for
various systems past the documented X/Open Curses features. For
- example, ncurses supports these capabilities in each configuration:
+ example, <EM>ncurses</EM> supports these capabilities in each configuration:
memory_lock
(meml) lock memory above cursor
Although termcap's extensibility was rarely used (it was never the
<EM>speaker</EM> who had actually used the feature), the criticism had a point.
- ncurses 5.0 provided a way to detect nonstandard capabilities,
+ <EM>ncurses</EM> 5.0 provided a way to detect nonstandard capabilities,
determine their type and optionally store and retrieve them in a way
which did not interfere with other applications. These are referred to
as <EM>user-defined</EM> <EM>capabilities</EM> because no modifications to the toolset's
predefined capability names are needed.
- The ncurses utilities <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> have a command-line option "-x"
+ The <EM>ncurses</EM> utilities <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> have a command-line option "-x"
to control whether the nonstandard capabilities are stored or
retrieved. A library function <STRONG>use_extended_names</STRONG> is provided for the
same purpose.
user-defined capability if the capability name is not one of the
predefined names.
- Because ncurses provides a termcap library interface, these user-
+ Because <EM>ncurses</EM> provides a termcap library interface, these user-
defined capabilities may be visible to termcap applications:
<STRONG>o</STRONG> The termcap interface (like all implementations of termcap)
predefined function-key names, to which a series of keys can be
assigned, that is insufficient for more than a dozen keys
multiplied by more than a couple of modifier combinations. The
- ncurses database uses a convention based on <STRONG>xterm(1)</STRONG> to provide
+ <EM>ncurses</EM> database uses a convention based on <STRONG>xterm(1)</STRONG> to provide
extended special-key names.
Fitting that into termcap's limitation of 2-character names would
</PRE><H3><a name="h3-Recognized-capabilities">Recognized capabilities</a></H3><PRE>
- The ncurses library uses the user-definable capabilities. While the
- terminfo database may have other extensions, ncurses makes explicit
+ The <EM>ncurses</EM> library uses the user-definable capabilities. While the
+ 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
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
- ncurses capabilities in user6 through user9 (u6, u7, u8 and u9)
+ <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.
appropriate values without requiring the application to
initialize colors using <STRONG>init_color</STRONG>.
- The capability type determines the values which ncurses sees:
+ The capability type determines the values which <EM>ncurses</EM> sees:
<EM>boolean</EM>
implies that the number of bits for red, green and blue are
- the same. Using the maximum number of colors, ncurses adds
+ the same. Using the maximum number of colors, <EM>ncurses</EM> adds
two, divides that sum by three, and assigns the result to red,
green and blue in that order.
comparison to red.
<EM>number</EM>
- tells ncurses what result to add to red, green and blue. If
- ncurses runs out of bits, blue (and green) lose just as in the
+ 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>string</EM>
could define <STRONG>RGB#1</STRONG> to represent the standard eight ANSI colors,
i.e., one bit per color.
- U8 <EM>number</EM>, asserts that ncurses must use Unicode values for line-
+ U8 <EM>number</EM>, asserts that <EM>ncurses</EM> must use Unicode values for line-
drawing characters, and that it should ignore the alternate
character set capabilities when the locale uses UTF-8 encoding.
For more information, see the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG>
Set this capability to a nonzero value to enable it.
- XM <EM>string</EM>, override ncurses's built-in string which enables/disables
+ XM <EM>string</EM>, override <EM>ncurses</EM>'s built-in string which enables/disables
<STRONG>xterm(1)</STRONG> mouse mode.
- ncurses sends a character sequence to the terminal to initialize
+ <EM>ncurses</EM> sends a character sequence to the terminal to initialize
mouse mode, and when the user clicks the mouse buttons or (in
certain modes) moves the mouse, handles the characters sent back
by the terminal to tell it what was done with the mouse.
The mouse protocol is enabled when the <EM>mask</EM> passed in the
- <STRONG>mousemask</STRONG> function is nonzero. By default, ncurses handles the
+ <STRONG>mousemask</STRONG> function is nonzero. By default, <EM>ncurses</EM> handles the
responses for the X11 xterm mouse protocol. It also knows about
the <EM>SGR</EM> <EM>1006</EM> xterm mouse protocol, but must to be told to look
for this specifically. It will not be able to guess which mode
The <STRONG>XM</STRONG> capability has a single parameter. If nonzero, the mouse
protocol should be enabled. If zero, the mouse protocol should
- be disabled. ncurses inspects this capability if it is present,
+ be disabled. <EM>ncurses</EM> inspects this capability if it is present,
to see whether the 1006 protocol is used. If so, it expects the
responses to use the <EM>SGR</EM> <EM>1006</EM> xterm mouse protocol.
Since 1999, <STRONG>xterm(1)</STRONG> has supported <EM>shift</EM>, <EM>control</EM>, <EM>alt</EM>, and <EM>meta</EM>
modifiers which produce distinct special-key strings. In a terminal
- description, ncurses has no special knowledge of the modifiers used.
+ description, <EM>ncurses</EM> has no special knowledge of the modifiers used.
Applications can use the <EM>naming</EM> <EM>convention</EM> established for <STRONG>xterm</STRONG> to
find these special keys in the terminal description.
Starting with the curses convention that <EM>key</EM> <EM>names</EM> begin with "k" and
- that shifted special keys are an uppercase name, ncurses' terminal
+ that shifted special keys are an uppercase name, <EM>ncurses</EM>' terminal
database defines these names to which a suffix is added:
<STRONG>Name</STRONG> <STRONG>Description</STRONG>
16 Meta + Ctrl + Alt + Shift
None of these are predefined; terminal descriptions can refer to <EM>names</EM>
- which ncurses will allocate at runtime to <EM>key-codes</EM>. To use these keys
- in an ncurses program, an application could do this:
+ which <EM>ncurses</EM> will allocate at runtime to <EM>key-codes</EM>. To use these keys
+ in an <EM>ncurses</EM> program, an application could do this:
<STRONG>o</STRONG> using a list of extended key <EM>names</EM>, ask <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> for their
values, and
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
Thomas E. Dickey
- beginning with ncurses 5.0 (1999)
+ beginning with <EM>ncurses</EM> 5.0 (1999)
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.4 2023-1
0-07 <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>
+ncurses 6.4 2023-1
2-16 <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>
</PRE>
<div class="nav">
<ul>
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: MKada_config.in,v 1.31 2023/11/25 19:51:50 tom Exp $
-.TH adacurses@USE_CFG_SUFFIX@\-config 1 2023-11-25 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.\" $Id: MKada_config.in,v 1.32 2023/12/16 21:42:53 tom Exp $
+.TH adacurses@USE_CFG_SUFFIX@\-config 1 2023-12-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.ds C adacurses@USE_CFG_SUFFIX@\-config
.ie \n(.g \{\
.ds `` \(lq
.SH DESCRIPTION
This program development aid simplifies the process of configuring
applications to use the \fI@ADA_LIBNAME@\fP library binding to
-\fIncurses\fP.
+\fI\%ncurses\fP.
.SH OPTIONS
.TP 11 \" "--version" + 2n
\fB\-\-cflags\fP
reports the GNAT libraries needed to link with \fI@ADA_LIBNAME@\fP.
.TP
\fB\-\-version\fP
-reports the release and patch date information of the \fIncurses\fP
+reports the release and patch date information of the \fI\%ncurses\fP
libraries used to configure and build \fI@ADA_LIBNAME@\fP and exits
successfully.
.TP
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: MKncu_config.in,v 1.19 2023/12/02 21:37:31 tom Exp $
-.TH @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config 1 2023-12-02 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.\" $Id: MKncu_config.in,v 1.20 2023/12/16 21:43:05 tom Exp $
+.TH @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config 1 2023-12-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.SH NAME
\fB\%@LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config\fP \-
-configuration helper for \fIncurses\fR libraries
+configuration helper for \fI\%ncurses\fP libraries
.SH SYNOPSIS
.B @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config
.I option
.B "@LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config \-\-help"
.SH DESCRIPTION
This program development aid simplifies the process of configuring
-applications against a particular set of \fIncurses\fP libraries.
+applications against a particular set of \fI\%ncurses\fP libraries.
.SH OPTIONS
.TP 18 \" "--mouse-version" + 2n + adjustment for PDF
\fB\-\-prefix\fP
-reports the package prefix of \fIncurses\fP.
+reports the package prefix of \fI\%ncurses\fP.
.TP
\fB\-\-exec\-prefix\fP
-reports the executable prefix of \fIncurses\fP.
+reports the executable prefix of \fI\%ncurses\fP.
.TP
\fB\-\-cflags\fP
-reports the C compiler flags needed to compile with \fIncurses\fP.
+reports the C compiler flags needed to compile with \fI\%ncurses\fP.
.TP
\fB\-\-libs\fP
-reports the libraries needed to link with \fIncurses\fP.
+reports the libraries needed to link with \fI\%ncurses\fP.
.TP
\fB\-\-version\fP
-reports the release and patch date information of \fIncurses\fP and
+reports the release and patch date information of \fI\%ncurses\fP and
exits successfully.
.TP
\fB\-\-abi\-version\fP
-reports the ABI version of \fIncurses\fP.
+reports the ABI version of \fI\%ncurses\fP.
.TP
\fB\-\-mouse\-version\fP
-reports the mouse\-interface version of \fIncurses\fP.
+reports the mouse\-interface version of \fI\%ncurses\fP.
.TP
\fB\-\-bindir\fP
-reports the directory containing \fIncurses\fP programs.
+reports the directory containing \fI\%ncurses\fP programs.
.TP
\fB\-\-datadir\fP
-reports the directory containing \fIncurses\fP data.
+reports the directory containing \fI\%ncurses\fP data.
.TP
\fB\-\-includedir\fP
-reports the directory containing \fIncurses\fP header files.
+reports the directory containing \fI\%ncurses\fP header files.
.TP
\fB\-\-libdir\fP
-reports the directory containing \fIncurses\fP libraries.
+reports the directory containing \fI\%ncurses\fP libraries.
.TP
\fB\-\-mandir\fP
-reports the directory containing \fIncurses\fP man pages.
+reports the directory containing \fI\%ncurses\fP man pages.
.TP
\fB\-\-terminfo\fP
reports the \fI\%TERMINFO\fP \fIterminfo\fP database path,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: captoinfo.1m,v 1.56 2023/12/02 20:51:25 tom Exp $
-.TH @CAPTOINFO@ 1M 2023-12-02 "ncurses 6.4" "User commands"
+.\" $Id: captoinfo.1m,v 1.57 2023/12/16 21:34:23 tom Exp $
+.TH @CAPTOINFO@ 1M 2023-12-16 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
-.ds ' \(aq
.\}
.el \{\
.ie t .ds `` ``
.el .ds `` ""
.ie t .ds '' ''
.el .ds '' ""
-.ie t .ds ' \(aq
-.el .ds ' '
.\}
.
.ds d /etc/termcap
.SH NAME
\fB\%@CAPTOINFO@\fP \-
-convert a \fItermcap\fR description into a \fIterminfo\fR description
+convert a \fItermcap\fP description into a \fI\%term\%info\fP description
.SH SYNOPSIS
.B @CAPTOINFO@
.RI [ tic-option ]
\fB\%@CAPTOINFO@\fP translates terminal descriptions.
It looks in each given text \fIfile\fP for \fI\%termcap\fP entries and,
for each one found,
-writes an equivalent \fI\%terminfo\fP description to the standard output
-stream.
-\fI\%termcap\fP \fBtc\fP capabilities translate to \fI\%terminfo\fP
+writes an equivalent \fI\%\%term\%info\fP description to the standard
+output stream.
+\fI\%termcap\fP \fBtc\fP capabilities translate to \fI\%\%term\%info\fP
\*(``\fBuse\fP\*('' capabilities.
.PP
If no \fIfile\fPs are specified,
\fB\%@CAPTOINFO@\fP translates some obsolete,
nonstandard capabilities into standard
(SVr4/XSI Curses)
-\fI\%terminfo\fP capabilities.
+\fI\%\%term\%info\fP capabilities.
It issues a diagnostic to the standard error stream for each,
inviting the user to check that it has not mistakenly translated an
unknown or mistyped capability name.
.PP
.TS
+center;
Cb S
Cb Cb Cb Cb
Cb Cb C Lb.
as follows.
.PP
.TS
+center;
cb cb
cb l .
\f(BItermcap\fP Name Graphic
and discards \fBGG\fP and double-line capabilities with a warning
diagnostic.
.PP
-IBM's AIX has a \fI\%terminfo\fP facility descended from SVr1
-\fI\%terminfo\fP,
+IBM's AIX has a \fI\%\%term\%info\fP facility descended from SVr1
+\fI\%\%term\%info\fP,
but which is incompatible with the SVr4 format.
\fB\%@CAPTOINFO@\fP translates the following AIX extensions.
.PP
.TS
+center;
cb cb
l l .
IBM XSI
this program translates the AIX \fBbox1\fP capability to an \fBacsc\fP
string.
.PP
-The HP-UX \fI\%terminfo\fP library supports two nonstandard
-\fI\%terminfo\fP capabilities,
+The HP-UX \fI\%\%term\%info\fP library supports two nonstandard
+\fI\%\%term\%info\fP capabilities,
\fBmeml\fP (memory lock) and \fBmemu\fP (memory unlock).
\fB\%@CAPTOINFO@\fP discards these with a warning message.
.SH FILES
.TP
.I \*d
default \fI\%termcap\fP terminal capability database
-.SH NOTES
-The verbose option is not identical to SVr4's.
-Under SVr4,
-instead of following the \fB\-v\fP with a trace level \fIn\fP,
-you repeat it \fIn\fP times.
.SH PORTABILITY
X/Open Curses,
Issue 7 (2009) describes \fBtic\fP briefly,
but omits this program.
+.PP
SVr4 systems provide \fB\%captoinfo\fP as a separate application from
\fBtic\fP.
+Its
+.B \-v
+option does not accept a trace level argument
+.I n;
+repeat
+.B \-v
+.I n
+times instead.
.PP
NetBSD does not provide this application.
.SH AUTHORS
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: clear.1,v 1.45 2023/12/02 20:49:04 tom Exp $
-.TH @CLEAR@ 1 2023-12-02 "ncurses 6.4" "User commands"
+.\" $Id: clear.1,v 1.46 2023/12/16 20:32:22 tom Exp $
+.TH @CLEAR@ 1 2023-12-16 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
The capabilities to clear the screen and scrollback buffer are named
\*(``clear\*('' and \*(``E3\*('', respectively.
The latter is a \fIuser-defined capability\fP,
-applying an extension mechanism introduced in \fIncurses\fP 5.0 (1999).
+applying an extension mechanism introduced in \fI\%ncurses\fP 5.0
+(1999).
.SH OPTIONS
\fB\%@CLEAR@\fP recognizes the following options.
.TP 9 \" "-T type" + 2n
\fI\%COLUMNS\fP as well.
.TP
.B \-V
-reports the version of \fIncurses\fP associated with this program and
+reports the version of \fI\%ncurses\fP associated with this program and
exits with a successful status.
.TP
.B \-x
The remainder of the script in each case is a copyright notice.
.PP
In 1995,
-\fIncurses\fP's \fBclear\fP began by adapting BSD's original \fBclear\fP
-command to use \fIterminfo\fP.
+\fI\%ncurses\fP's \fBclear\fP began by adapting BSD's original
+\fBclear\fP command to use \fIterminfo\fP.
The \fBE3\fP extension came later.
.bP
In June 1999, \fIxterm\fP provided an extension to the standard control
.bP
Subsequently,
more terminal developers adopted the feature.
-The next relevant step was to change the \fIncurses\fP \fBclear\fP
+The next relevant step was to change the \fI\%ncurses\fP \fBclear\fP
program in 2013 to incorporate this extension.
.bP
In 2013,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wch.3x,v 1.48 2023/11/25 14:20:05 tom Exp $
-.TH curs_add_wch 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_add_wch.3x,v 1.49 2023/12/16 21:19:37 tom Exp $
+.TH curs_add_wch 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
function is functionally equivalent to a call to
\fBadd_wch\fP
followed by a call to
-\fBrefresh\fP(3X).
+\fB\%refresh\fP(3X).
Similarly, the
\fBwecho_wchar\fP
is functionally equivalent to a call to
for non-control characters, a considerable performance gain might be seen
by using the *\fBecho\fP* functions instead of their equivalents.
.SS Line Graphics
-Like \fBaddch\fP(3X),
+Like \fB\%addch\fP(3X),
\fBaddch_wch\fP accepts symbols which make it simple to draw lines and other
frequently used special characters.
These symbols correspond to the same VT100 line-drawing set as
-\fBaddch\fP(3X).
+\fB\%addch\fP(3X).
.PP
.TS
l l l l l
WACS_VLINE 0x2502 | x vertical line
.TE
.PP
-The wide-character configuration of ncurses also defines symbols
+The wide-character configuration of \fI\%ncurses\fP also defines symbols
for thick lines (\fBacsc\fP \*(``J\*('' to \*(``V\*(''):
.PP
.TS
WACS_D_VLINE 0x2551 | Y double vertical line
.TE
.PP
-Unicode's descriptions for these characters differs slightly from ncurses,
+Unicode's descriptions for these characters differs slightly from
+\fI\%ncurses\fP,
by introducing the term \*(``light\*('' (along with less important details).
Here are its descriptions for the normal, thick, and double horizontal lines:
.bP
.PP
The latter may be due to different causes:
.bP
-If \fBscrollok\fP(3X) is not enabled,
+If \fB\%scrollok\fP(3X) is not enabled,
writing a character at the lower right margin succeeds.
-However, an error is returned because
-it is not possible to wrap to a new line
+However,
+an error is returned because it is not possible to wrap to a new line.
.bP
If an error is detected when converting a multibyte character to a sequence
of bytes,
use only the \fBacsc\fP character-mapping to provide this feature.
As a result, those implementations can only use single-byte line-drawing
characters.
-Ncurses 5.3 (2002) provided a table of Unicode values to solve these problems.
+\fI\%ncurses\fP 5.3 (2002) provided a table of Unicode values to solve
+these problems.
NetBSD curses incorporated that table in 2010.
.PP
In this implementation, the Unicode values are used instead of the
-terminal description's \fBacsc\fP mapping as discussed in ncurses(3X)
-for the environment variable \fBNCURSES_NO_UTF8_ACS\fP.
+terminal description's \fBacsc\fP mapping as discussed in
+\fB\%ncurses\fP(3X) for the environment variable
+\fINCURSES_NO_UTF8_ACS\fP.
In contrast, for the same cases, the line-drawing characters
-described in \fBcurs_addch\fP(3X) will use only the ASCII default values.
+described in \fB\%addch\fP(3X) will use only the ASCII default values.
.PP
Having Unicode available does not solve all of the problems with
line-drawing for curses:
or a non-spacing character.
.PP
This implementation assumes that \fIwch\fP is constructed using
-\fBsetcchar\fP(3X), and in turn that the result
+\fB\%setcchar\fP(3X), and in turn that the result
.bP
contains at most one spacing character in the beginning of its list of wide
characters,
.bP
may hold one non-spacing character.
.PP
-In the latter case, ncurses adds the non-spacing character to the active
+In the latter case,
+\fI\%ncurses\fP adds the non-spacing character to the active
(base) spacing character.
.SH SEE ALSO
\fB\%curses\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addch.3x,v 1.74 2023/11/25 14:20:05 tom Exp $
-.TH curs_addch 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_addch.3x,v 1.75 2023/12/16 21:19:37 tom Exp $
+.TH curs_addch 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
The cursor automatically wraps to the beginning of the next line.
.bP
At the bottom of the current scrolling region,
-and if \fBscrollok\fP(3X) is enabled,
+and if \fB\%scrollok\fP(3X) is enabled,
the scrolling region is scrolled up one line.
.bP
-If \fBscrollok\fP(3X) is not enabled,
+If \fB\%scrollok\fP(3X) is not enabled,
writing a character at the lower right margin succeeds.
-However, an error is returned because
-it is not possible to wrap to a new line
+However,
+an error is returned because it is not possible to wrap to a new line.
.PP
If \fIch\fP is a tab, newline, carriage return or backspace,
the cursor is moved appropriately within the window:
.PP
If \fIch\fP is any other nonprintable character,
it is drawn in printable form,
-using the same convention as \fBunctrl\fR(3X):
+using the same convention as \fB\%unctrl\fP(3X):
.bP
Control characters are displayed in the \fB^\fIX\fR notation.
.bP
Values above 128 are either meta characters
(if the screen has not been initialized,
-or if \fBmeta\fP(3X) has been called with a \fBTRUE\fP E parameter),
+or if \fB\%meta\fP(3X) has been called with a \fBTRUE\fP E parameter),
shown in the \fBM\-\fIX\fR notation, or are displayed as themselves.
In the latter case, the values may not be printable;
this follows the X/Open specification.
Video attributes can be combined with a character argument passed to
\fBaddch\fP or related functions by logical-ORing them into the character.
(Thus, text, including attributes, can be copied from one place to another
-using \fBinch\fP(3X) and \fBaddch\fP.) See the \fBcurs_attr\fP(3X) page for
-values of predefined video attribute constants that can be usefully OR'ed
-into characters.
+using \fB\%inch\fP(3X) and \fBaddch\fP.)
+See the \fB\%curs_attr\fP(3X) page for values of predefined video
+attribute constants that can be usefully OR'ed into characters.
.SS Echoing characters
The \fBechochar\fP and \fBwechochar\fP routines are equivalent to a call to
-\fBaddch\fP followed by a call to \fBrefresh\fP(3X), or a call to \fBwaddch\fP
+\fBaddch\fP followed by a call to \fB\%refresh\fP(3X), or a call to \fBwaddch\fP
followed by a call to \fBwrefresh\fP.
The knowledge that only a single
character is being output is used and, for non-control characters, a
If it is not possible to add a complete character,
an error is returned:
.bP
-If \fBscrollok\fP(3X) is not enabled,
+If \fB\%scrollok\fP(3X) is not enabled,
writing a character at the lower right margin succeeds.
-However, an error is returned because
-it is not possible to wrap to a new line
+However,
+an error is returned because it is not possible to wrap to a new line.
.bP
If an error is detected when converting a multibyte character to a sequence
of bytes,
include \fBacsc\fP strings in which their key characters (pryz{|}) are
embedded, and a second-hand list of their character descriptions has come
to light.
-The ACS-prefixed names for them were invented for \fBncurses\fP(3X).
+The ACS-prefixed names for them were invented for \fB\%ncurses\fP(3X).
.LP
The \fIdisplayed\fP values for the \fBACS_\fP and \fBWACS_\fP constants
depend on
.bP
-the library configuration, i.e., \fBncurses\fP versus \fBncursesw\fP,
+the library configuration,
+i.e.,
+\fI\%ncurses\fP versus \fI\%ncursesw\fP,
where the latter is capable of displaying Unicode while the former is not, and
.bP
whether the \fIlocale\fP uses UTF-8 encoding.
.LP
In certain cases, the terminal is unable to display line-drawing characters
-except by using UTF-8 (see the discussion of \fBNCURSES_NO_UTF8_ACS\fP in
-ncurses(3X)).
+except by using UTF-8
+(see the discussion of \fB\%NCURSES_NO_UTF8_ACS\fP in
+\fB\%ncurses\fP(3X)).
.SS Character Set
X/Open Curses assumes that the parameter passed to \fBwaddch\fP contains
a single character.
-As discussed in \fBcurs_attr\fP(3X), that character may have been
+As discussed in \fB\%curs_attr\fP(3X), that character may have been
more than eight bits in an SVr3 or SVr4 implementation,
but in the X/Open Curses model, the details are not given.
The important distinction between SVr4 curses and X/Open Curses is
to pass to \fBwaddch\fP.
.PP
In this implementation, \fBchtype\fP holds an eight-bit character.
-But ncurses allows multibyte characters to be passed in a succession
-of calls to \fBwaddch\fP.
+But \fI\%ncurses\fP allows multibyte characters to be passed in a
+succession of calls to \fBwaddch\fP.
The other implementations do not do this;
a call to \fBwaddch\fP passes exactly one character
which may be rendered as one or more cells on the screen
depending on whether it is printable.
.PP
Depending on the locale settings,
-ncurses will inspect the byte passed in each call to \fBwaddch\fP,
+\fI\%ncurses\fP will inspect the byte passed in each call to \fBwaddch\fP,
and check if the latest call will continue a multibyte sequence.
When a character is \fIcomplete\fP,
-ncurses displays the character and moves to the next position in the screen.
+\fI\%ncurses\fP displays the character and moves to the next position in the screen.
.PP
If the calling application interrupts the succession of bytes in
a multibyte character by moving the current location (e.g., using \fBwmove\fP),
-ncurses discards the partially built character,
+\fI\%ncurses\fP discards the partially built character,
starting over again.
.PP
For portability to other implementations,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_attr.3x,v 1.91 2023/12/02 21:05:24 tom Exp $
-.TH curs_attr 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_attr.3x,v 1.92 2023/12/16 21:07:24 tom Exp $
+.TH curs_attr 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
However, if the value does not fit, then the \fBCOLOR_PAIR\fP macro
uses only the bits that fit.
-For example, because in ncurses \fBA_COLOR\fP has eight (8) bits,
+For example,
+because in \fI\%ncurses\fP \fBA_COLOR\fP has eight (8) bits,
then \fBCOLOR_PAIR(\fI259\fB)\fR is 4
(i.e., 259 is 4 more than the limit 255).
.PP
\fBattr_\fP* functions, except that they take arguments of type \fBint\fP
rather than \fBattr_t\fP.
.PP
-There is no corresponding \fBattrget\fP function as such in X/Open Curses,
-although ncurses provides \fBgetattrs\fP (see curs_legacy(3X)).
+There is no corresponding \fB\%attrget\fP function as such
+in X/Open Curses,
+although \fI\%ncurses\fP provides \fB\%getattrs\fP
+(see \fB\%curs_legacy\fP(3X)).
.\" ---------------------------------------------------------------------------
.SS Change character rendition
The routine \fBchgat\fP changes the attributes of a given number of characters
the \fBmvwchgat\fP function does a cursor move before acting.
.PP
In these functions,
-the color \fIpair\fP argument is a color-pair index
+the color \fIpair\fP argument is a color pair index
(as in the first argument of \fBinit_pair\fP, see \fBcurs_color\fP(3X)).
.\" ---------------------------------------------------------------------------
.SS Change window color
for \fBwcolor_set\fP is outside the range 0..COLOR_PAIRS\-1.
.bP
does not return an error if either of the parameters of \fBwattr_get\fP
-used for retrieving attribute or color-pair values is \fBNULL\fP.
+used for retrieving attribute or color pair values is \fBNULL\fP.
.PP
Functions with a \*(``mv\*('' prefix first perform a cursor movement using
\fBwmove\fP, and return an error if the position is outside the window,
number is less than 256.
The alternate functions such as \fBcolor_set\fP can pass a color pair
value directly.
-However, ncurses ABI 4 and 5 simply OR this value
+However, \fI\%ncurses\fP ABI 4 and 5 simply OR this value
within the alternate functions.
-You must use ncurses ABI 6 to support more than 256 color pairs.
+You must use \fI\%ncurses\fP ABI 6 to support more than 256 color pairs.
.\" ---------------------------------------------------------------------------
.SH EXTENSIONS
This implementation provides the \fBA_ITALIC\fP attribute for terminals
which X/Open Curses still (after more than twenty years) documents
as reserved for future use, saying that it should be \fBNULL\fP.
This implementation uses that parameter in ABI 6 for the functions which
-have a color-pair parameter to support \fIextended color pairs\fP:
+have a color pair parameter to support \fIextended color pairs\fP:
.bP
For functions which modify the color, e.g.,
\fBwattr_set\fP and \fBwattr_on\fP,
the same because it simplifies copying information between
\fBchtype\fP and \fBcchar_t\fP variables.
.bP
-Because ncurses's \fBattr_t\fP can hold a color pair
+Because \fI\%ncurses\fP's \fBattr_t\fP can hold a color pair
(in the \fBA_COLOR\fP field),
a call to
\fBwattr_on\fP,
Regarding OSF/1 (and Tru64),
.bP
These used 64-bit hardware.
-Like ncurses, the OSF/1 curses interface is not customized for 32-bit
-and 64-bit versions.
+Like \fI\%ncurses\fP,
+the OSF/1 curses interface is not customized for 32-bit and 64-bit
+versions.
.bP
Unlike other systems which evolved from AT&T code,
OSF/1 provided a new implementation for X/Open curses.
modification to make the library 8-bit clean for \fBnvi\fP(1).
He moved \fIstandout\fP attribute to a structure member.
.IP
-The resulting 4.4BSD curses was replaced by ncurses over the next ten years.
+The resulting 4.4BSD curses was replaced by \fI\%ncurses\fP over the
+next ten years.
.bP
U/Win is rarely used now.
.\" ---------------------------------------------------------------------------
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_bkgd.3x,v 1.51 2023/12/02 21:02:44 tom Exp $
-.TH curs_bkgd 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_bkgd.3x,v 1.54 2023/12/17 23:31:28 tom Exp $
+.TH curs_bkgd 3X 2023-12-17 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.nf
\fB#include <curses.h>
.PP
-\fBvoid bkgdset(chtype \fIch\fP);
-\fBvoid wbkgdset(WINDOW *\fIwin\fP, chtype \fIch\fP);
-.PP
\fBint bkgd(chtype \fIch\fP);
\fBint wbkgd(WINDOW *\fIwin\fP, chtype \fIch\fP);
.PP
+\fBvoid bkgdset(chtype \fIch\fP);
+\fBvoid wbkgdset(WINDOW *\fIwin\fP, chtype \fIch\fP);
+.PP
\fBchtype getbkgd(WINDOW *\fIwin\fP);
.fi
.SH DESCRIPTION
-.SS bkgdset
-The \fBbkgdset\fP and \fBwbkgdset\fP routines
-set the \fIbackground\fP for a window.
-A window's background is a \fBchtype\fP consisting of
-any combination of attributes (i.e., rendition) and a character:
-.bP
-The attribute part of the background is combined (OR'ed) with all non-blank
-characters that are written into the window with \fBwaddch\fP.
-.bP
-Both the character and attribute parts of the background are combined with
-blank characters that are written into the window.
-.PP
-The background becomes a property of each
-character and moves with the character through any scrolling and
-insert/delete line/character operations.
-.PP
-To the extent possible on a particular terminal,
-the attribute part of the background is displayed
-as the graphic rendition of the character put on the screen.
-.SS bkgd
-The \fBbkgd\fP and \fBwbkgd\fP functions
-set the background property of the current or specified window
-and then apply this setting to every character position in that window.
-According to X/Open Curses, it should do this:
+The
+.I background
+of a
+.I curses
+window
+(in the library's non-\*(``wide\*('' configuration)
+is a
+.I \%chtype
+combining a set of attributes
+(see \fB\%curs_attr\fP(3X))
+with a character called the
+.I "blank character."
+.PP
+The blank character is a spacing character that populates a window's
+character cells when their contents are erased without replacement.
+The background's attributes are combined with all non-blank characters
+written to the window,
+as with the \fB\%waddch\fP(3X) and \fB\%winsch\fP(3X) families of
+functions.
+.PP
+The blank character and attributes of the background combine with
+characters written to the window as described below.
+The background becomes a property of the character and moves with it
+through any scrolling and insert/delete line/character operations.
+.PP
+To the extent possible on a given terminal,
+the attribute part of the background is displayed as the graphic
+rendition of the character put on the screen.
+.SS "bkgd, wbkgd"
+\fB\%bkgd\fP and \fB\%wbkgd\fP set the background property of
+\fB\%stdscr\fP or the specified window and then apply this setting to
+every character cell in that window.
.bP
-The rendition of every character on the screen is changed to
-the new background rendition.
+The rendition of every character in the window changes to the new
+background rendition.
.bP
-Wherever the former background character
-appears, it is changed to the new background character.
+Wherever the former background character appears,
+it changes to the new background character.
.PP
-Neither X/Open Curses nor the SVr4 manual pages give details about
-the way the rendition of characters on the screen is updated when
-\fBbkgd\fP or \fBwbkgd\fP is used to change the background character.
-.PP
-\fI\%ncurses\fP,
-like SVr4 \fIcurses\fP,
-does not store the background and window attribute contributions to each
-cell separately.
-It updates the rendition by comparing the character,
-non-color attributes and colors contained in the background.
-For each cell in the window, whether or not it is blank:
+.I \%ncurses
+updates the rendition of each character cell by comparing the character,
+non-color attributes,
+and colors.
+The library applies to following procedure to each cell in the window,
+whether or not it is blank.
.bP
-The library first compares the \fIcharacter\fP,
-and if it matches the current character part of the background,
-it replaces that with the new background character.
-.IP
-When \fBbkgdset\fP is used to set the background character,
-that does not update each cell in the window.
-A subsequent call to \fBbkgd\fP will only modify the \fIcharacter\fP in
-cells which match the current background character.
+.I \%ncurses
+first compares the cell's character to the previously specified blank
+character;
+if they match,
+.I \%ncurses
+writes the new blank character to the cell.
.bP
-The library then checks if the cell uses color,
-i.e., its color pair value is nonzero.
-If not, it simply replaces the attributes and color pair in the
-cell with those from the new background character.
+.I \%ncurses
+then checks if the cell uses color,
+that is,
+its color pair value is nonzero.
+If not,
+it simply replaces the attributes and color pair in the cell with those
+from the new background character.
.bP
If the cell uses color,
-and that matches the color in the current background,
-the library removes attributes
-which may have come from the current background
-and adds attributes from the new background.
-It finishes by setting the cell
-to use the color from the new background.
+and its background color matches that of the current window background,
+.I \%ncurses
+removes attributes that may have come from the current background and
+adds those from the new background.
+It finishes by setting the cell's background to use the new window
+background color.
.bP
If the cell uses color,
-and that does not match the color in the current background,
-the library updates only the non-color attributes,
-first removing those which may have come from the current background,
+and its background color does not match that of the current window
+background,
+.I \%ncurses
+updates only the non-color attributes,
+first removing those that may have come from the current background,
and then adding attributes from the new background.
.PP
-If the background's character value is zero (0), a space is assumed.
+.I \%ncurses
+treats a background character value of zero (0) as a blank character.
.PP
If the terminal does not support color,
-or if color has not been started with \fBstart_color\fP,
-the new background character's color attribute will be ignored.
+or if color has not been initialized with \fB\%start_color\fP(3X),
+.I \%ncurses
+ignores the new background character's color attribute.
+.SS "bkgdset, wbkgdset"
+\fB\%bkgdset\fP and \fB\%wbkgdset\fP manipulate the background of
+the applicable window,
+without updating the character cells as \fB\%bkgd\fP and
+\fB\%wbkgd\fP do;
+only future writes reflect the updated background.
.SS getbkgd
-The \fBgetbkgd\fP function returns the given window's current background
-character/attribute pair.
+\fB\%getbkgd\fP obtains the given window's background character and
+attribute combination.
.SH RETURN VALUE
Functions returning an \fIint\fP return \fBOK\fP on success.
\fB\%bkgd\fP returns \fBERR\fP if the library has not been initialized.
-\fB\%wbkgd\fP and \fB\%getbkgd\fP return \fBERR\fP if the \fI\%WINDOW\fP
+\fB\%wbkgd\fP and \fB\%getbkgd\fP return \fBERR\fP if a \fI\%WINDOW\fP
pointer argument is null.
.PP
-In contrast,
-the SVr4.0 manual says \fB\%bkgd\fP and \fB\%wbkgd\fP may return
-\fBOK\fP
-\*(``or a non-negative integer if \fB\%immedok\fP is set\*('',
-which refers to the return value from \fB\%wrefresh\fP
-(used to implement the immediate repainting).
-SVr4 \fIcurses\fP \fB\%wrefresh\fP returns the number of characters
-written to the screen during the refresh.
-\fI\%ncurses\fP does not do that.
+\fB\%bkgdset\fP and \fBwbkgdset\fP do not return a value.
+.PP
+\fB\%getbkgd\fP returns a window's background character and attribute
+combination.
.SH NOTES
Unusually,
there is no \fB\%wgetbkgd\fP function;
\fB\%getbkgd\fP behaves as one would expect \fB\%wgetbkgd\fP to,
accepting a \fI\%WINDOW\fP pointer argument.
.PP
-Note that \fBbkgdset\fP and \fBbkgd\fP may be macros.
+\fB\%bkgd\fP and \fB\%bkgdset\fP may be available as macros.
.PP
X/Open Curses mentions that the character part of the background must
be a single-byte value.
checks to ensure that,
and will reuse the old background character if the check fails.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
-It specifies that \fBbkgd\fP and \fBwbkgd\fP return \fBERR\fP on
-failure,
-but gives no failure conditions.
+X/Open Curses, Issue 4, describes these functions.
+It specifies that
+\fB\%bkgd\fP,
+\fB\%wbkgd\fP,
+and
+\fB\%getbkgd\fP
+return \fBERR\fP on failure
+(in the case of the last,
+this value is cast to
+.IR \%chtype ),
+but describes no failure conditions.
+.PP
+The SVr4.0 manual says that \fB\%bkgd\fP and \fB\%wbkgd\fP may return
+\fBOK\fP
+\*(``or a non-negative integer if \fB\%immedok\fP is set\*('',
+which refers to the return value from \fB\%wrefresh\fP(3X),
+used to implement the immediate repainting.
+SVr4 \fIcurses\fP's \fB\%wrefresh\fP returns the number of characters
+written to the screen during the refresh.
+\fI\%ncurses\fP does not do that.
+.PP
+Neither X/Open Curses nor the SVr4 manual pages detail how the rendition
+of characters on the screen updates when \fB\%bkgd\fP or \fB\%wbkgd\fP
+changes the background character.
+.I \%ncurses,
+like SVr4
+.I curses,
+does not
+(in its non-\*(``wide\*('' configuration)
+store the background and window attribute contributions to each
+character cell separately.
.SH SEE ALSO
+\fB\%curs_bkgrnd\fP(3X) describes the corresponding functions in the
+\*(``wide\*('' configuration of
+.I \%ncurses.
+.PP
\fB\%curses\fP(3X),
\fB\%curs_addch\fP(3X),
-\fB\%curs_attr\fP(3X),
-\fB\%curs_outopts\fP(3X)
+\fB\%curs_attr\fP(3X)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_bkgrnd.3x,v 1.34 2023/12/02 21:30:00 tom Exp $
-.TH curs_bkgrnd 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_bkgrnd.3x,v 1.35 2023/12/16 23:00:21 tom Exp $
+.TH curs_bkgrnd 3X 2023-12-16 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
\fBint wgetbkgrnd(WINDOW *\fIwin\fP, cchar_t *\fIwch\fP);
.fi
.SH DESCRIPTION
-.SS bkgrndset
-The \fBbkgrndset\fP and \fBwbkgrndset\fP routines manipulate the
-background of the named window.
-The window background is a \fBcchar_t\fP consisting of
-any combination of attributes (i.e., rendition) and a complex character.
+The
+.I background
+of a
+.I curses
+window
+(in the library's \*(``wide\*('' configuration)
+is a
+.I \%cchar_t
+combining a set of attributes
+(see \fB\%curs_attr\fP(3X))
+with a complex character called the
+.I "blank character."
+.PP
+The blank character is a spacing character that populates a window's
+character cells when their contents are erased without replacement.
+The background's attributes are combined with all non-blank characters
+written to the window,
+as with the \fB\%wadd_wch\fP(3X) and \fB\%wins_wch\fP(3X) families of
+functions.
+.PP
+The blank character and attributes of the background combine with
+characters written to the window as described below.
+The background becomes a property of the character and moves with it
+through any scrolling and insert/delete line/character operations.
+.PP
+To the extent possible on a given terminal,
+the attribute part of the background is displayed as the graphic
+rendition of the character put on the screen.
+.SS "bkgrnd, wbkgrnd"
+\fB\%bkgrnd\fP and \fB\%wbkgrnd\fP set the background property of
+\fB\%stdscr\fP or the specified window and then apply this setting to
+every character cell in that window.
.bP
-The attribute part of the background is combined (OR'ed) with all non-blank
-characters that are written into the window with \fBwaddch\fP.
+The rendition of every character in the window changes to the new
+background rendition.
.bP
-Both
-the character and attribute parts of the background are combined with
-the blank characters.
+Wherever the former background character appears,
+it changes to the new background character.
.PP
-The background becomes a property of the
-character and moves with the character through any scrolling and
-insert/delete line/character operations.
-.PP
-To the extent possible on a
-particular terminal, the attribute part of the background is displayed
-as the graphic rendition of the character put on the screen.
-.SS bkgrnd
-The \fBbkgrnd\fP and \fBwbkgrnd\fP functions
-set the background property of the current or specified window
-and then apply this setting to every character position in that window:
+.I \%ncurses
+updates the rendition of each character cell by comparing the character,
+non-color attributes,
+and colors.
+The library applies to following procedure to each cell in the window,
+whether or not it is blank.
+.bP
+.I \%ncurses
+first compares the cell's character to the previously specified blank
+character;
+if they match,
+.I \%ncurses
+writes the new blank character to the cell.
+.bP
+.I \%ncurses
+then checks if the cell uses color,
+that is,
+its color pair value is nonzero.
+If not,
+it simply replaces the attributes and color pair in the cell with those
+from the new background character.
.bP
-The rendition of every character on the screen is changed to
-the new background rendition.
+If the cell uses color,
+and its background color matches that of the current window background,
+.I \%ncurses
+removes attributes that may have come from the current background and
+adds those from the new background.
+It finishes by setting the cell's background to use the new window
+background color.
.bP
-Wherever the former background character
-appears, it is changed to the new background character.
-.SS getbkgrnd
-The \fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP functions obtain the given
-or specified window's current background character and attribute pair
-and store it via the
+If the cell uses color,
+and its background color does not match that of the current window
+background,
+.I \%ncurses
+updates only the non-color attributes,
+first removing those that may have come from the current background,
+and then adding attributes from the new background.
+.PP
+.I \%ncurses
+treats a background character value of zero (0) as a blank character.
+.PP
+If the terminal does not support color,
+or if color has not been initialized with \fB\%start_color\fP(3X),
+.I \%ncurses
+ignores the new background character's color attribute.
+.SS "bkgrndset, wbkgrndset"
+\fB\%bkgrndset\fP and \fB\%wbkgrndset\fP manipulate the background of
+the applicable window,
+without updating the character cells as \fB\%bkgrnd\fP and
+\fB\%wbkgrnd\fP do;
+only future writes reflect the updated background.
+.SS "getbkgrnd, wgetbkgrnd"
+The \fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP functions obtain the
+background character and attribute pair of \fB\%stdscr\fP or the
+specified window and store it via the
.I wch
pointer.
.SH RETURN VALUE
-The \fBbkgrndset\fP and \fBwbkgrndset\fP routines do not return a value.
+\fBbkgrndset\fP and \fBwbkgrndset\fP do not return a value.
.PP
-Upon successful completion, the other functions return \fBOK\fP.
-Otherwise, they return \fBERR\fP:
+The other functions return
+.B ERR
+upon failure and
+.B OK
+upon success.
+In
+.I \%ncurses,
+failure occurs if
.bP
-A null \fI\%WINDOW\fP pointer is treated as an error.
+a
+.I \%WINDOW
+pointer
+.I win
+is null, or
.bP
-A null \fI\%cchar_t\fP pointer is treated as an error.
+a
+.I \%cchar_t
+pointer
+.I wch
+is null.
.SH NOTES
\fB\%bkgrnd\fP,
\fB\%bkgrndset\fP, and
\fB\%getbkgrnd\fP
may be available as macros.
.PP
-X/Open Curses does not provide details on how the rendition is changed.
-This implementation follows the approach used in SVr4 curses,
-which is explained in the manual page for \fBwbkgd\fP.
+Unlike their counterparts in the non-\*(``wide\*('' configuration of
+.I \%ncurses,
+\fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP supply the background character
+and attribute in a modifiable
+.I \%cchar_t
+parameter,
+not as the return value.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+X/Open Curses, Issue 4, describes these functions.
+It specifies no error conditions for them.
+.PP
+X/Open Curses does not provide details of how the rendition is updated.
+This implementation follows the approach used in SVr4
+.I curses.
.SH SEE ALSO
+\fB\%curs_bkgd\fP(3X) describes the corresponding functions in the
+non-\*(``wide\*('' configuration of
+.I \%ncurses.
+.PP
\fB\%curses\fP(3X),
-\fB\%curs_bkgd\fP(3X)
+\fB\%curs_add_wch\fP(3X),
+\fB\%curs_attr\fP(3X)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_border.3x,v 1.43 2023/11/25 11:31:27 tom Exp $
-.TH curs_border 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_border.3x,v 1.44 2023/12/16 21:09:11 tom Exp $
+.TH curs_border 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
long, or as many as fit into the window.
.SH RETURN VALUE
All routines return the integer \fBOK\fP.
-The SVr4.0 manual says "or a
-non-negative integer if \fBimmedok\fP is set", but this appears to be an error.
+The SVr4.0 manual says
+\*(``or a non-negative integer if \fB\%immedok\fP is set\*('',
+but this appears to be an error.
.PP
X/Open does not define any error conditions.
This implementation returns an error
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_clear.3x,v 1.40 2023/11/25 11:31:27 tom Exp $
-.TH curs_clear 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_clear.3x,v 1.41 2023/12/16 21:09:11 tom Exp $
+.TH curs_clear 3X 2023-12-16 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
.SH PORTABILITY
These functions are described in the XSI Curses standard, Issue 4.
.PP
-The SVr4.0 manual says that these functions could
-return "a non-negative integer if \fBimmedok\fP(3X) is set",
+The SVr4.0 manual says that these functions could return
+\*(``or a non-negative integer if \fB\%immedok\fP is set\*('',
referring to the return-value of \fBwrefresh\fP.
In that implementation, \fBwrefresh\fP would return a count of
the number of characters written to the terminal.
ability to do the equivalent of \fBclearok(..., 1)\fP by saying
\fBtouchwin(stdscr)\fP or \fBclear(stdscr)\fP.
This will not work under
-ncurses.
+\fI\%ncurses\fP.
.PP
This implementation, and others such as Solaris,
sets the current position to 0,0 after erasing
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_color.3x,v 1.92 2023/11/25 17:36:51 tom Exp $
-.TH curs_color 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_color.3x,v 1.93 2023/12/16 21:07:24 tom Exp $
+.TH curs_color 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB\%extended_pair_content\fP,
\fB\%reset_color_pairs\fP,
\fB\%COLOR_PAIR\fP,
-\fB\%PAIR_NUMBER\fP \-
+\fB\%PAIR_NUMBER\fP,
+\fB\%COLORS\fP,
+\fB\%COLOR_PAIRS\fP,
+\fB\%COLOR_BLACK\fP,
+\fB\%COLOR_RED\fP,
+\fB\%COLOR_GREEN\fP,
+\fB\%COLOR_YELLOW\fP,
+\fB\%COLOR_BLUE\fP,
+\fB\%COLOR_MAGENTA\fP,
+\fB\%COLOR_CYAN\fP,
+\fB\%COLOR_WHITE\fP \-
manipulate terminal colors with \fIcurses\fR
.SH SYNOPSIS
.nf
\fBvoid reset_color_pairs(void);
.PP
\fBint COLOR_PAIR(int \fIn\fP);
-\fBPAIR_NUMBER(\fIattrs\fP);
+\fBPAIR_NUMBER(int \fIattr\fP);
.fi
.SH DESCRIPTION
.SS Overview
\fIcurses\fP supports color attributes on terminals with that capability.
To use these routines \fB\%start_color\fP must be called, usually right after
\fB\%initscr\fP.
-Colors are always used in pairs (referred to as color-pairs).
-A color-pair consists of a foreground color (for characters) and a background
+Colors are always used in pairs (referred to as color pairs).
+A color pair consists of a foreground color (for characters) and a background
color (for the blank field on which the characters are displayed).
-A programmer initializes a color-pair with the routine \fB\%init_pair\fP.
+A programmer initializes a color pair with the routine \fB\%init_pair\fP.
After it has been initialized, \fB\%COLOR_PAIR\fP(\fIn\fP)
can be used to convert the pair to a video attribute.
.PP
programmer to extract the amounts of red, green, and blue components in an
initialized color.
The routine \fB\%pair_content\fP allows a programmer to find
-out how a given color-pair is currently defined.
+out how a given color pair is currently defined.
.SS Color Rendering
The \fIcurses\fP library combines these inputs to produce the
actual foreground and background colors shown on the screen:
.bP
It initializes two global variables, \fB\%COLORS\fP and
\fB\%COLOR_PAIRS\fP (respectively defining the maximum number of colors
-and color-pairs the terminal can support).
+and color pairs the terminal can support).
.bP
It initializes the special color pair \fB\%0\fP to the default foreground
and background colors.
other, it returns \fBFALSE\fP.
This routine facilitates writing terminal-independent programs.
.SS init_pair
-The \fB\%init_pair\fP routine changes the definition of a color-pair.
+The \fB\%init_pair\fP routine changes the definition of a color pair.
It takes three arguments:
-the number of the color-pair to be changed, the foreground
+the number of the color pair to be changed, the foreground
color number, and the background color number.
For portable applications:
.bP
.bP
The second and third arguments must be valid color values.
.PP
-If the color-pair was previously initialized,
-the screen is refreshed and all occurrences of that color-pair
+If the color pair was previously initialized,
+the screen is refreshed and all occurrences of that color pair
are changed to the new definition.
.PP
-As an extension, ncurses allows you to set color pair \fB0\fP via
-the \fB\%assume_default_colors\fP(3X) routine, or to specify the use of
+As an extension,
+\fI\%ncurses\fP allows you to set color pair \fB0\fP via the
+\fB\%assume_default_colors\fP(3X) routine, or to specify the use of
default colors (color number \fB\-1\fP) if you first invoke the
\fB\%use_default_colors\fP(3X) routine.
.SS init_extended_pair
Because \fB\%init_pair\fP uses signed \fBshort\fPs for its parameters,
-that limits color-pairs and color-values
+that limits color pairs and color-values
to 32767 on modern hardware.
The extension \fB\%init_extended_pair\fP uses \fBint\fPs
-for the color-pair and color-value,
+for the color pair and color-value,
allowing a larger number of colors to be supported.
.SS init_color
The \fB\%init_color\fP routine changes the definition of a color.
allowing a larger number of colors to be supported.
.SS pair_content
The \fB\%pair_content\fP routine allows programmers to find out what colors a
-given color-pair consists of.
-It requires three arguments: the color-pair
+given color pair consists of.
+It requires three arguments: the color pair
number, and two addresses of \fBshort\fRs for storing the foreground and the
background color numbers.
.bP
range \fB0\fP through \fB\%COLORS\fP, inclusive.
.SS extended_pair_content
Because \fB\%pair_content\fP uses signed \fBshort\fPs for its parameters,
-that limits color-pair and color-values to 32767 on modern hardware.
+that limits color pair and color-values to 32767 on modern hardware.
The extension \fB\%extended_pair_content\fP uses \fBint\fPs
for the color pair and
for returning the foreground and background colors,
allowing a larger number of colors to be supported.
.SS reset_color_pairs
-The extension \fB\%reset_color_pairs\fP tells ncurses to discard all
-of the color-pair information which was set with \fB\%init_pair\fP.
+The extension \fB\%reset_color_pairs\fP tells \fI\%ncurses\fP to discard
+all of the color pair information which was set with \fB\%init_pair\fP.
It also touches the current- and standard-screens, allowing an application to
switch color palettes rapidly.
-.SS PAIR_NUMBER
-\fB\%PAIR_NUMBER(\fIattrs\fR) extracts the color
-value from its \fIattrs\fP parameter and returns it as a color pair number.
.SS COLOR_PAIR
-Its inverse \fB\%COLOR_PAIR(\fIn\fB)\fR converts a color pair number
-to an attribute.
+\fB\%COLOR_PAIR(\fIn\fB)\fR converts a color pair number to an
+attribute.
Attributes can hold color pairs in the range 0 to 255.
-If you need a color pair larger than that, you must use functions
-such as \fB\%attr_set\fP (which pass the color pair as a separate parameter)
+If you need a color pair larger than that,
+you must use functions such as \fB\%attr_set\fP
+(which pass the color pair as a separate parameter)
rather than the legacy functions such as \fB\%attrset\fP.
+.SS PAIR_NUMBER
+\fB\%PAIR_NUMBER(\fIattr\fR) extracts the color information from its
+\fIattr\fP parameter and returns it as a color pair number;
+it is the inverse operation of \fB\%COLOR_PAIR\fP.
.SH RETURN VALUE
The routines \fB\%can_change_color\fP and \fB\%has_colors\fP return \fBTRUE\fP
or \fBFALSE\fP.
returns an error if the color table cannot be allocated.
.RE
.SH NOTES
-In the \fIncurses\fP implementation, there is a separate color activation flag,
+In the \fI\%ncurses\fP implementation,
+there is a separate color activation flag,
color palette, color pairs table,
and associated \fB\%COLORS\fP and \fB\%COLOR_PAIRS\fP counts
for each screen; the \fB\%start_color\fP function only affects the current
.bP
Color RGB values are not settable.
.SH EXTENSIONS
-The functions marked as extensions were designed for \fBncurses\fP(3X),
+The functions marked as extensions were designed for
+\fB\%ncurses\fP(3X),
and are not found in SVr4 curses, 4.4BSD curses,
or any other previous version of curses.
.SH PORTABILITY
which use \fBshort\fP parameters,
allowing applications to use larger color- and pair-numbers.
.PP
-The \fB\%reset_color_pairs\fP function is an extension of ncurses.
+The \fB\%reset_color_pairs\fP function is an extension of
+\fI\%ncurses\fP.
.SH HISTORY
SVr3.2 introduced color support to curses in 1987.
.PP
.bP
X/Open Curses (1992-present)
added a new structure \fB\%cchar_t\fP to store the character,
-attributes and color-pair values, allowing increased range of color-pairs.
-Both color-pairs and color-values used a signed \fBshort\fP,
+attributes and color pair values, allowing increased range of color pairs.
+Both color pairs and color-values used a signed \fBshort\fP,
limiting values to 15 bits.
.bP
-ncurses (1992-present) uses eight bits
+\fI\%ncurses\fP (1992-present) uses eight bits
for \fB\%A_COLOR\fP in \fB\%chtype\fP values.
.IP
Version 5.3 provided a wide-character interface (2002),
-but left color-pairs as part of the attributes-field.
+but left color pairs as part of the attributes-field.
.IP
Since version 6 (2015),
-ncurses uses a separate \fBint\fP for color-pairs in the \fB\%cchar_t\fP values.
-When those color-pair values fit in 8 bits,
-ncurses allows color-pairs to be manipulated
+ncurses uses a separate \fBint\fP for color pairs in the \fB\%cchar_t\fP values.
+When those color pair values fit in 8 bits,
+ncurses allows color pairs to be manipulated
via the functions using \fB\%chtype\fP values.
.bP
NetBSD curses used 6 bits from
2000 (when colors were first supported) until 2004.
At that point, NetBSD changed to use 10 bits.
As of 2021, that size is unchanged.
-Like ncurses before version 6,
-the NetBSD color-pair information is stored in
-the attributes field of \fB\%cchar_t\fP, limiting the number of color-pairs
+Like \fI\%ncurses\fP before version 6,
+the NetBSD color pair information is stored in
+the attributes field of \fB\%cchar_t\fP, limiting the number of color pairs
by the size of the bitfield.
.SH SEE ALSO
\fB\%curses\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_delch.3x,v 1.29 2023/10/07 21:19:07 tom Exp $
-.TH curs_delch 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_delch.3x,v 1.30 2023/12/16 21:09:11 tom Exp $
+.TH curs_delch 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
(This does not
imply use of the hardware delete character feature.)
.SH RETURN VALUE
-All routines return the integer \fBERR\fP upon failure and an \fBOK\fP (SVr4
-specifies only "an integer value other than \fBERR\fP") upon successful
-completion.
+All routines return the integer \fBERR\fP upon failure and an \fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
Functions with a \*(``mv\*('' prefix first perform a cursor movement using
\fBwmove\fP, and return an error if the position is outside the window,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_deleteln.3x,v 1.33 2023/11/25 14:08:05 tom Exp $
-.TH curs_deleteln 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_deleteln.3x,v 1.34 2023/12/16 21:33:34 tom Exp $
+.TH curs_deleteln 3X 2023-12-16 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.SH NAME
\fB\%deleteln\fP,
\fB\%wdeleteln\fP,
The \fBinsertln\fP and \fBwinsertln\fP routines insert a blank line above the
current line and the bottom line is lost.
.SH RETURN VALUE
-All routines return the integer \fBERR\fP upon failure and an \fBOK\fP (SVr4
-specifies only "an integer value other than \fBERR\fP") upon successful
-completion.
+These routines return the integer \fBERR\fP upon failure and an \fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
X/Open defines no error conditions.
In this implementation,
.\"
.\" Author: Thomas E. Dickey 1999-on
.\"
-.\" $Id: curs_extend.3x,v 1.42 2023/11/25 14:26:30 tom Exp $
-.TH curs_extend 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_extend.3x,v 1.43 2023/12/16 20:32:22 tom Exp $
+.TH curs_extend 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBuse_extended_names\fP returns the previous state, allowing you to
save this and restore it.
.SH PORTABILITY
-These routines are specific to ncurses.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on
Version 7, BSD or System V implementations.
It is recommended that
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_get_wstr.3x,v 1.41 2023/11/25 14:29:54 tom Exp $
-.TH curs_get_wstr 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_get_wstr.3x,v 1.42 2023/12/16 20:32:22 tom Exp $
+.TH curs_get_wstr 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
X/Open Curses does not specify what happens if the length \fIn\fP is negative.
.bP
For analogy with \fBwgetnstr\fP,
-ncurses 6.2 uses a limit (based on \fBLINE_MAX\fP).
+\fI\%ncurses\fP 6.2 uses a limit (based on \fBLINE_MAX\fP).
.bP
Some other implementations (such as Solaris xcurses) do the same,
while others (PDCurses) do not allow this.
.bP
-NetBSD 7 curses imitates ncurses 6.1 in this regard,
+NetBSD 7 curses imitates \fI\%ncurses\fP 6.1 in this regard,
treating a \fB\-1\fP as an indefinite number of characters.
.SH SEE ALSO
\fB\%curses\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getcchar.3x,v 1.42 2023/11/25 14:30:18 tom Exp $
-.TH curs_getcchar 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_getcchar.3x,v 1.43 2023/12/16 21:07:24 tom Exp $
+.TH curs_getcchar 3X 2023-12-16 "ncurses 6.4" "Library calls"
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
.bP
Stores the character attributes in the location pointed to by \fIattrs\fP
.bP
-Stores the color-pair in the location pointed to by \fIcolor_pair\fP
+Stores the color pair in the location pointed to by \fIcolor_pair\fP
.bP
Stores the wide-character string,
characters referenced by \fIwcval\fP, into the array pointed to by \fIwch\fP.
contain at most one spacing character,
which must be the first.
.IP
-Up to \fBCCHARW_MAX\fP\-1 nonspacing characters may follow.
-Additional nonspacing characters are ignored.
+Up to \fBCCHARW_MAX\fP\-1 non-spacing characters may follow.
+Additional non-spacing characters are ignored.
.IP
The string may contain a single control character instead.
-In that case, no nonspacing characters are allowed.
+In that case, no non-spacing characters are allowed.
.SH RETURN VALUE
When \fIwch\fP is a null pointer,
\fBgetcchar\fP returns the number of wide characters referenced by
X/Open Curses documents the \fIopts\fP argument as reserved for future use,
saying that it must be null.
This implementation
-uses that parameter in ABI 6 for the functions which have a color-pair
+uses that parameter in ABI 6 for the functions which have a color pair
parameter to support extended color pairs:
.bP
For functions which modify the color, e.g., \fBsetcchar\fP,
and used to retrieve the color pair as an \fBint\fP value,
in addition retrieving it via the standard pointer to \fBshort\fP parameter.
.SH PORTABILITY
-The \fBCCHARW_MAX\fP symbol is specific to ncurses.
+The \fBCCHARW_MAX\fP symbol is specific to \fI\%ncurses\fP.
X/Open Curses does not provide details for the layout of the \fBcchar_t\fP
structure.
It tells what data are stored in it:
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getch.3x,v 1.75 2023/10/07 21:19:07 tom Exp $
-.TH curs_getch 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_getch.3x,v 1.76 2023/12/16 21:01:28 tom Exp $
+.TH curs_getch 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
.B int getch(void);
.B int wgetch(WINDOW *\fIwin\fP);
-.PP
.B int mvgetch(int \fIy\fP, int \fIx\fP);
.B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
.PP
For this reason, many terminals experience a delay between the time
a user presses the escape key and the escape is returned to the program.
.PP
-In \fBncurses\fP, the timer normally expires after
+In \fI\%ncurses\fP, the timer normally expires after
the value in \fBESCDELAY\fP (see \fBcurs_variables\fP(3X)).
If \fBnotimeout\fP is \fBTRUE\fP, the timer does not expire;
it is an infinite (or very large) value.
.B KEY_MOUSE
is returned for mouse-events (see \fBcurs_mouse\fP(3X)).
This code relies upon whether or not \fBkeypad\fP(3X) has been enabled,
-because (e.g., with \fBxterm\fP(1) mouse prototocol) ncurses must
-read escape sequences,
+because
+(e.g.,
+with \fBxterm\fP(1) mouse prototocol)
+\fI\%ncurses\fP must read escape sequences,
just like a function key.
.SS Testing key-codes
The \fBhas_key\fP routine takes a key-code value from the above list, and
Some curses implementations may differ according to whether they
treat these control keys specially (and ignore the terminfo), or
use the terminfo definitions.
-\fBNcurses\fP uses the terminfo definition.
+\fI\%ncurses\fP uses the terminfo definition.
If it says that \fBKEY_ENTER\fP is control/M,
\fBgetch\fP will return \fBKEY_ENTER\fP
when you press control/M.
.PP
\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related
terminfo capabilities, but no higher-level functions use the feature.
-The implementation in ncurses is an extension.
+The implementation in \fI\%ncurses\fP is an extension.
.PP
-\fBKEY_RESIZE\fP is an extension first implemented for ncurses.
+\fBKEY_RESIZE\fP is an extension first implemented for \fI\%ncurses\fP.
NetBSD curses later added this extension.
.PP
Programmers concerned about portability should be prepared for either of two
interrupts \fBgetch\fP and causes it to return \fBERR\fP with \fBerrno\fP set to
\fBEINTR\fP.
.PP
-The \fBhas_key\fP function is unique to \fBncurses\fP.
+The \fBhas_key\fP function is unique to \fI\%ncurses\fP.
We recommend that
any code using it be conditionalized on the \fBNCURSES_VERSION\fP feature macro.
.SH SEE ALSO
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getstr.3x,v 1.51 2023/11/25 14:29:54 tom Exp $
-.TH curs_getstr 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_getstr.3x,v 1.52 2023/12/16 20:32:22 tom Exp $
+.TH curs_getstr 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
to allow for the terminating NUL.
As of 2018, some implementations count it, some do not:
.bP
-ncurses 6.1 and PDCurses do not count the NUL in the given limit, while
+\fI\%ncurses\fP 6.1 and PDCurses do not count the NUL in the given limit, while
.bP
Solaris SVr4 and NetBSD curses count the NUL as part of the limit.
.bP
.IP
A comment in NetBSD's source code states that this is specified in SUSv2.
.bP
-ncurses (before 6.2) assumes no particular limit for the result
+\fI\%ncurses\fP (before 6.2) assumes no particular limit for the result
from \fBwgetstr\fP, and treats the \fIn\fP parameter of \fBwgetnstr\fP
like SVr4 curses.
.bP
-ncurses 6.2 uses \fBLINE_MAX\fP,
+\fI\%ncurses\fP 6.2 uses \fBLINE_MAX\fP,
or a larger (system-dependent) value
which the \fBsysconf\fP function may provide.
If neither \fBLINE_MAX\fP or \fBsysconf\fP is available,
-ncurses uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit).
+\fI\%ncurses\fP uses the POSIX value for \fBLINE_MAX\fP (a 2048 byte limit).
In either case, it reserves a byte for the terminating NUL.
.PP
Although \fBgetnstr\fP is equivalent to a series of calls to \fBgetch\fP,
mode set by the caller into account when deciding whether to handle
echoing within \fBgetnstr\fP or as a side-effect of the \fBgetch\fP calls.
.bP
-The original ncurses (as \fIpcurses\fP in 1986) set \fBnoraw\fP and \fBcbreak\fP
-when accepting input for \fBgetnstr\fP.
+The original \fI\%ncurses\fP
+(as \fIpcurses\fP in 1986)
+set \fBnoraw\fP and \fBcbreak\fP when accepting input for \fBgetnstr\fP.
That may have been done to make function- and cursor-keys work;
-it is not necessary with ncurses.
+it is not necessary with \fI\%ncurses\fP.
.IP
-Since 1995, ncurses has provided signal handlers for INTR and QUIT
+Since 1995,
+\fI\%ncurses\fP has provided signal handlers for INTR and QUIT
(e.g., \fB^C\fP or \fB^\e\fP).
With the \fBnoraw\fP and \fBcbreak\fP settings,
those may catch a signal and stop the program,
where other implementations allow one to enter those characters in the buffer.
.bP
-Starting in 2021 (ncurses 6.3), \fBgetnstr\fP sets \fBraw\fP,
+Starting in 2021
+(\fI\%ncurses\fP 6.3),
+\fBgetnstr\fP sets \fBraw\fP,
rather than \fBnoraw\fP and \fBcbreak\fP for better compatibility with
SVr4-curses, e.g., allowing one to enter a \fB^C\fP into the buffer.
.SH SEE ALSO
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getyx.3x,v 1.39 2023/10/21 10:28:36 tom Exp $
-.TH curs_getyx 3X 2023-10-21 "ncurses 6.4" "Library calls"
+.\" $Id: curs_getyx.3x,v 1.40 2023/12/16 21:33:21 tom Exp $
+.TH curs_getyx 3X 2023-12-16 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.SH NAME
\fB\%getyx\fP,
\fB\%getparyx\fP,
they should not be used as the right-hand side of assignment statements).
.SH NOTES
All of these interfaces are macros.
-A "\fB&\fP" is not necessary before the variables \fIy\fP and \fIx\fP.
+A \*(``&\*('' is not necessary before the variables \fIy\fP and \fIx\fP.
.SH PORTABILITY
The
\fB\%getyx\fP,
the data stored in like-named members may not have like-values in
different implementations.
For example, the \fB\%WINDOW._maxx\fP and \fB\%WINDOW._maxy\fP values
-in \fIncurses\fP have
+in \fI\%ncurses\fP have
(at least since release 1.8.1)
differed by one from some other implementations.
The difference is hidden by means of the macro \fB\%getmaxyx\fP.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inch.3x,v 1.40 2023/10/07 21:19:07 tom Exp $
-.TH curs_inch 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_inch.3x,v 1.41 2023/12/16 21:08:16 tom Exp $
+.TH curs_inch 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
extract the character or attributes alone.
.
.SS Attributes
-The following bit-masks may be AND-ed with characters returned by \fBwinch\fP.
+The following bit masks may be AND-ed with characters returned by \fBwinch\fP.
.PP
.TS
l l .
-\fBA_CHARTEXT\fP Bit-mask to extract character
-\fBA_ATTRIBUTES\fP Bit-mask to extract attributes
-\fBA_COLOR\fP Bit-mask to extract color-pair field information
+\fBA_CHARTEXT\fP Bit mask to extract character
+\fBA_ATTRIBUTES\fP Bit mask to extract attributes
+\fBA_COLOR\fP Bit mask to extract color pair field information
.TE
.SH RETURN VALUE
Functions with a \*(``mv\*('' prefix first perform a cursor movement using
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_initscr.3x,v 1.56 2023/12/03 00:09:54 tom Exp $
-.TH curs_initscr 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_initscr.3x,v 1.59 2023/12/17 23:56:04 tom Exp $
+.TH curs_initscr 3X 2023-12-17 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
call \fBinitscr\fP more than once:
.bP
The portable way to use \fBinitscr\fP is once only,
-using \fBrefresh\fP (see curs_refresh(3X))
+using \fB\%refresh\fP(3X)
to restore the screen after \fBendwin\fP.
.bP
This implementation allows using \fBinitscr\fP after \fBendwin\fP.
\fBstdscr\fP and \fBcurscr\fP as well as a work area \fBnewscr\fP.
SVr4 curses ignores other windows.
.bP
-Since version 4.0 (1996), ncurses has maintained a list of all windows
-for each screen,
+Since version 4.0 (1996),
+\fI\%ncurses\fP has maintained a list of all windows for each screen,
using that information to delete those windows when \fBdelscreen\fP is called.
.bP
-NetBSD copied this feature of ncurses in 2001.
+NetBSD copied this feature of \fI\%ncurses\fP in 2001.
PDCurses follows the SVr4 model,
deleting only the standard \fBWINDOW\fP structures.
-.SS High-level versus low-level
+.SS "High-level versus Low-level"
Different implementations may disagree regarding the level of some functions.
For example, \fBSCREEN\fP (returned by \fBnewterm\fP) and
\fBTERMINAL\fP (returned by \fBsetupterm\fP(3X)) hold file descriptors for
For example
.bP
NetBSD's \fBbaudrate\fP(3X) function uses the descriptor in \fBTERMINAL\fP.
-\fBncurses\fP and SVr4 use the descriptor in \fBSCREEN\fP.
+\fI\%ncurses\fP and SVr4 use the descriptor in \fBSCREEN\fP.
.bP
-NetBSD and \fBncurses\fP use the descriptor
+NetBSD and \fI\%ncurses\fP use the descriptor
in \fBTERMINAL\fP
for terminal I/O modes,
e.g.,
\fBdef_shell_mode\fP(3X),
\fBdef_prog_mode\fP(3X).
SVr4 curses uses the descriptor in \fBSCREEN\fP.
-.SS Unset TERM Variable
+.SS "Unset \fITERM\fP Variable"
If the \fITERM\fP variable is missing or empty, \fBinitscr\fP uses the
value \*(``unknown\*('',
which normally corresponds to a terminal entry with the \fIgeneric\fP
Generic entries are detected by \fBsetupterm\fP(3X)
and cannot be used for full-screen operation.
Other implementations may handle a missing/empty \fITERM\fP variable differently.
-.SS Signal Handlers
+.SS "Signal Handlers"
Quoting from X/Open Curses Issue 7, section 3.1.1:
.RS 5
.PP
.B SIGTSTP
This handles the \fIstop\fP signal, used in job control.
When resuming the process, this implementation discards pending
-input with \fBflushinput\fP (see curs_util(3X)), and repaints the screen
+input with \fB\%flushinp\fP(3X), and repaints the screen
assuming that it has been completely altered.
-It also updates the saved terminal modes with \fBdef_shell_mode\fP
-(see \fBcurs_kernel\fP(3X)).
+It also updates the saved terminal modes with
+\fB\%def_shell_mode\fP(3X).
.TP 5
.B SIGWINCH
This handles the window-size changes which were ignored in
the standardization efforts.
The handler sets a (signal-safe) variable
-which is later tested in \fBwgetch\fP (see curs_getch(3X)).
+which is later tested in \fB\%wgetch\fP(3X).
If \fBkeypad\fP has been enabled for the corresponding window,
\fBwgetch\fP returns the key symbol \fBKEY_RESIZE\fP.
At the same time, \fBwgetch\fP calls \fBresizeterm\fP to adjust the
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inopts.3x,v 1.58 2023/11/25 14:30:50 tom Exp $
-.TH curs_inopts 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_inopts.3x,v 1.59 2023/12/16 20:32:22 tom Exp $
+.TH curs_inopts 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint is_raw(void);
.fi
.SH DESCRIPTION
-The \fIncurses\fP library provides several functions which let an application
-change the way input from the terminal is handled.
+The \fI\%ncurses\fP library provides several functions which let an
+application change the way input from the terminal is handled.
Some are global, applying to all windows.
Others apply only to a specific window.
Window-specific settings are not automatically applied to new or derived
\-1
if the \fIcurses\fP library was not initialized.
.PP
-These routines are specific to \fIncurses\fP.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on Version 7, BSD or System V implementations.
-It is recommended that any code depending on \fIncurses\fP extensions
+It is recommended that any code depending on \fI\%ncurses\fP extensions
be conditioned using NCURSES_VERSION.
.SH PORTABILITY
Except as noted in the section on extensions,
these functions are described in the XSI Curses standard, Issue 4.
.PP
-The \fIncurses\fP library obeys the XPG4 standard
+The \fI\%ncurses\fP library obeys the XPG4 standard
and the historical practice of the
AT&T \fIcurses\fP implementations,
in that the echo bit is cleared when \fIcurses\fP
system will not alter.
.PP
When \fB\%keypad\fP is first enabled,
-\fIncurses\fP loads the key-definitions for the current terminal description.
+\fI\%ncurses\fP loads the key-definitions for the current terminal
+description.
If the terminal description includes extended string capabilities,
e.g., from using the \fB\-x\fP option of \fB@TIC@\fP,
-then \fIncurses\fP also defines keys for the capabilities whose names
+then \fI\%ncurses\fP also defines keys for the capabilities whose names
begin with \*(``k\*(''.
The corresponding keycodes are generated and (depending on previous
loads of terminal descriptions) may differ from one execution of a
the strings are loaded.
If more than one key definition has the same string value,
then \fB\%wgetch\fP can return only one keycode.
-Most \fIcurses\fP implementations (including \fIncurses\fP)
+Most \fIcurses\fP implementations (including \fI\%ncurses\fP)
load key definitions in the order
defined by the array of string capability names.
The last key to be loaded determines the keycode which will be returned.
-In \fIncurses\fP, you may also have extended capabilities interpreted as
-key definitions.
+In \fI\%ncurses\fP,
+you may also have extended capabilities interpreted as key definitions.
These are loaded after the predefined keys,
and if a capability's value is the same as a previously-loaded
key definition,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_ins_wstr.3x,v 1.29 2023/11/25 11:29:34 tom Exp $
-.TH curs_ins_wstr 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_ins_wstr.3x,v 1.30 2023/12/16 20:36:15 tom Exp $
+.TH curs_ins_wstr 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.SH NOTES
All but \fBwins_nwstr\fP may be macros.
.PP
-If the first character in the string is a nonspacing character, these
+If the first character in the string is a non-spacing character, these
functions will fail.
-XSI does not define what will happen if a nonspacing character follows
+XSI does not define what will happen if a non-spacing character follows
a control character.
.SH PORTABILITY
These functions are described in the XSI Curses standard, Issue 4,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_insch.3x,v 1.33 2023/10/07 21:19:07 tom Exp $
-.TH curs_insch 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_insch.3x,v 1.34 2023/12/16 21:09:11 tom Exp $
+.TH curs_insch 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
right, with the possibility of the rightmost character on the line being lost.
The insertion operation does not change the cursor position.
.SH RETURN VALUE
-All routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
-(SVr4 specifies only "an integer value other than \fBERR\fP")
-upon successful completion,
-unless otherwise noted in the preceding routine descriptions.
+These routines return the integer \fBERR\fP upon failure and an \fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
Functions with a \*(``mv\*('' prefix first perform a cursor movement using
\fBwmove\fP, and return an error if the position is outside the window,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_instr.3x,v 1.43 2023/11/25 17:58:25 tom Exp $
-.TH curs_instr 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_instr.3x,v 1.44 2023/12/16 20:32:22 tom Exp $
+.TH curs_instr 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
SVr4 does not
document whether a length limit includes or excludes the trailing NUL.
.PP
-The ncurses library extends the XSI description by allowing a negative
-value for \fIn\fP.
+The \fI\%ncurses\fP library extends the XSI description by allowing a
+negative value for \fIn\fP.
In this case, the functions return the string ending at the right margin.
.SH SEE ALSO
\fB\%curses\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_kernel.3x,v 1.49 2023/10/14 22:03:52 tom Exp $
-.TH curs_kernel 3X 2023-10-14 "ncurses 6.4" "Library calls"
+.\" $Id: curs_kernel.3x,v 1.50 2023/12/16 20:32:22 tom Exp $
+.TH curs_kernel 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
This implementation gets it right, but it may be unwise to count
on the correctness of the return value anywhere else.
.PP
-Both ncurses and SVr4 will call \fBcurs_set\fP in \fBendwin\fP
+Both \fI\%ncurses\fP and SVr4 will call \fBcurs_set\fP in \fBendwin\fP
if \fBcurs_set\fP
has been called to make the cursor other than normal, i.e., either
invisible or very visible.
-There is no way for ncurses to determine the initial cursor state to
-restore that.
+There is no way for \fI\%ncurses\fP to determine the initial cursor
+state to restore that.
.SH PORTABILITY
The \fIvirtual screen\fP functions \fBsetsyx\fP and \fBgetsyx\fP
are not described in the XSI Curses standard, Issue 4.
This is misleading, as they are macros with no documented semantics
for the return value.
.PP
-If interrupted, ncurses restarts \fBnapms\fP.
+If interrupted, \fI\%ncurses\fP restarts \fBnapms\fP.
That, and the limitation to 30 seconds,
are different from other implementations.
.SH SEE ALSO
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_memleaks.3x,v 1.31 2023/11/11 11:46:43 tom Exp $
-.TH curs_memleaks 3X 2023-11-11 "ncurses 6.4" "Library calls"
+.\" $Id: curs_memleaks.3x,v 1.32 2023/12/16 20:32:22 tom Exp $
+.TH curs_memleaks 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBvoid _nc_free_tinfo(int \fIcode\fP);
.fi
.SH DESCRIPTION
-These functions are used to simplify analysis of memory leaks in the ncurses
-library.
+These functions are used to simplify analysis of memory leaks in the
+\fI\%ncurses\fP library.
.PP
Any implementation of curses must not free the memory associated with
a screen, since (even after calling \fB\%endwin\fP(3X)), it must be available
for use in the next call to \fB\%refresh\fP(3X).
There are also chunks of memory held for performance reasons.
That makes it hard to analyze curses applications for memory leaks.
-When using the specially configured debugging version of the ncurses library,
+When using the specially configured debugging version of the
+\fI\%ncurses\fP library,
applications can call functions which free those chunks of memory,
simplifying the process of memory-leak checking.
.PP
because they are not intended for use in the non-debugging library:
.TP 5
\fB\%_nc_freeall\fP
-This frees (almost) all of the memory allocated by ncurses.
+This frees (almost) all of the memory allocated by \fI\%ncurses\fP.
.TP 5
\fB\%_nc_free_and_exit\fP
-This frees the memory allocated by ncurses (like \fB\%_nc_freeall\fP),
+This frees the memory allocated by \fI\%ncurses\fP
+(like \fB\%_nc_freeall\fP),
and exits the program.
It is preferred over \fB\%_nc_freeall\fP since some of that memory
may be required to keep the application running.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_mouse.3x,v 1.81 2023/10/21 10:29:45 tom Exp $
-.TH curs_mouse 3X 2023-10-21 "ncurses 6.4" "Library calls"
+.\" $Id: curs_mouse.3x,v 1.82 2023/12/16 21:08:16 tom Exp $
+.TH curs_mouse 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
the screen windows enclose the location of a mouse event.
.SS wmouse_trafo
The \fB\%wmouse_trafo\fP function transforms a given pair of coordinates
-from stdscr-relative coordinates
+from \fB\%stdscr\fP-relative coordinates
to coordinates relative to the given window or vice versa.
-The resulting stdscr-relative coordinates are not always identical
-to window-relative coordinates due to the mechanism to reserve lines on top
-or bottom of the screen for other purposes
+The resulting \fB\%stdscr\fP-relative coordinates are not always
+identical to window-relative coordinates due to the mechanism to reserve
+lines on top or bottom of the screen for other purposes
(see the \fB\%ripoffline\fP and \fB\%slk_init\fP(3X) calls, for example).
.bP
If the parameter \fIto_screen\fP is \fBTRUE\fP, the pointers
If \fIto_screen\fP is
\fBFALSE\fP, the pointers \fIpY, pX\fP must reference window-relative
coordinates.
-They are converted to stdscr-relative coordinates if the
+They are converted to \fB\%stdscr\fP-relative coordinates if the
window \fIwin\fP encloses this point.
In this case the function returns \fBTRUE\fP.
.bP
.SS mouse_trafo
The \fB\%mouse_trafo\fP function performs the same translation
as \fB\%wmouse_trafo\fP,
-using stdscr for \fIwin\fP.
+using \fB\%stdscr\fP for \fIwin\fP.
.SS mouseinterval
The \fB\%mouseinterval\fP function sets the maximum time (in thousands of a
second) that can elapse between press and release events for them to
Use \fB\%mouseinterval(\-1)\fP to obtain the interval without altering it.
The default is one sixth of a second.
.SS has_mouse
-The \fB\%has_mouse\fP function returns \fBTRUE\fP if the mouse driver has been
-successfully initialized.
+The \fB\%has_mouse\fP function returns \fBTRUE\fP if the mouse driver
+has been successfully initialized,
+and \fBFALSE\fP otherwise.
.PP
Note that mouse events will be ignored when input is in cooked mode, and will
cause an error beep when cooked mode is being simulated in a window by a
function such as \fB\%getstr\fP that expects a linefeed for input-loop
termination.
.SH RETURN VALUE
+\fB\%has_mouse\fP,
+\fB\%wenclose\fP,
+\fB\%mouse_trafo\fP,
+and
+\fB\%wmouse_trafo\fP
+return \fBTRUE\fP or \fBFALSE\fP as noted above.
+.PP
\fB\%getmouse\fP and \fB\%ungetmouse\fP
-return the integer \fBERR\fP upon failure or \fBOK\fP
-upon successful completion:
-.RS 3
-.TP 5
-\fB\%getmouse\fP
-returns an error.
+return \fBERR\fP upon failure and \fBOK\fP upon success.
+.PP
+\fB\%getmouse\fP fails if:
.bP
-If no mouse driver was initialized, or
-if the mask parameter is zero,
+no mouse driver was initialized,
.bP
-It returns an error if a mouse event was detected which did not match the
-current \fImousemask\fP.
+the mask of reportable events is zero,
.bP
-It also returns an error if no more events remain in the queue.
-.TP 5
-\fB\%ungetmouse\fP
-returns an error if the FIFO is full.
-.RE
+a mouse event was detected that does not match the mask,
+.bP
+or if no more events remain in the queue.
+.PP
+\fB\%ungetmouse\fP returns an error if the event queue is full.
.PP
\fB\%mousemask\fP
returns the mask of reportable events.
returns the previous interval value, unless
the terminal was not initialized.
In that case, it returns the maximum interval value (166).
-.PP
-\fB\%wenclose\fP and \fB\%wmouse_trafo\fP
-are boolean functions returning \fBTRUE\fP or \fBFALSE\fP depending
-on their test result.
-.SH PORTABILITY
-These calls were designed for \fIncurses\fP, and are not found in SVr4
-\fIcurses\fP, 4.4BSD \fIcurses\fP, or any other previous version of \fIcurses\fP.
-.PP
-SVr4 \fIcurses\fP had support for the mouse in a variant of \fBxterm\fP(1).
-It is mentioned in a few places, but with no supporting documentation:
-.bP
-the \*(``libcurses\*('' manual page lists functions for this feature
-which are prototyped in \fBcurses.h\fP:
-.PP
-.RS 8
-.EX
-extern int mouse_set(long int);
-extern int mouse_on(long int);
-extern int mouse_off(long int);
-extern int request_mouse_pos(void);
-extern int map_button(unsigned long);
-extern void wmouse_position(WINDOW *, int *, int *);
-extern unsigned long getmouse(void), getbmap(void);
-.EE
-.RE
-.bP
-the \*(``terminfo\*('' manual page lists capabilities for the feature
-.PP
-.RS 8
-.EX
-buttons btns BT Number of buttons on the mouse
-get_mouse getm Gm Curses should get button events
-key_mouse kmous Km 0631, Mouse event has occurred
-mouse_info minfo Mi Mouse status information
-req_mouse_pos reqmp RQ Request mouse position report
-.EE
-.RE
-.bP
-the interface made assumptions (as does \fIncurses\fP)
-about the escape sequences
-sent to and received from the terminal.
-.IP
-For instance
-the SVr4 \fIcurses\fP library used the \fB\%get_mouse\fP capability to tell the
-terminal which mouse button events it should send,
-passing the mouse-button bit-mask to the terminal.
-Also, it could ask the terminal
-where the mouse was using the \fB\%req_mouse_pos\fP capability.
-.IP
-Those features required a terminal which had been modified
-to work with \fIcurses\fP.
-They were not part of the X Consortium's xterm.
-.PP
-When developing the xterm mouse support for \fIncurses\fP in September 1995,
-Eric Raymond was uninterested in using the same interface due to its
-lack of documentation.
-Later, in 1998, Mark Hesseling provided support in
-PDCurses 2.3 using the SVr4 interface.
-PDCurses, however, does not use video terminals,
-making it unnecessary to be concerned about compatibility with the
-escape sequences.
-.PP
+.SH NOTES
The feature macro \fB\%NCURSES_MOUSE_VERSION\fP is provided so the preprocessor
can be used to test whether these features are present.
If the interface is changed, the value of \fB\%NCURSES_MOUSE_VERSION\fP will be
incremented.
These values for \fB\%NCURSES_MOUSE_VERSION\fP may be
-specified when configuring \fIncurses\fP:
+specified when configuring \fI\%ncurses\fP:
.RS 3
.TP 3
1
The order of the \fB\%MEVENT\fP structure members is not guaranteed.
Additional fields may be added to the structure in the future.
.PP
-Under \fIncurses\fP, these calls are implemented using either
+Under \fI\%ncurses\fP, these calls are implemented using either
xterm's built-in mouse-tracking API or
platform-specific drivers including
.RS 3
.PP
If you are using an unsupported configuration,
mouse events will not be visible to
-\fIncurses\fP (and the \fB\%mousemask\fP function will always
+\fI\%ncurses\fP (and the \fB\%mousemask\fP function will always
return \fB0\fP).
.PP
If the terminfo entry contains a \fBXM\fP string,
For example, in xterm,
wheel/scrolling mice send position reports as a sequence of
presses of buttons 4 or 5 without matching button-releases.
+.SH PORTABILITY
+These calls were designed for \fI\%ncurses\fP,
+and are not found in SVr4 \fIcurses\fP,
+4.4BSD \fIcurses\fP, or any other previous version of \fIcurses\fP.
+.PP
+SVr4 \fIcurses\fP had support for the mouse in a variant of \fBxterm\fP(1).
+It is mentioned in a few places, but with no supporting documentation:
+.bP
+the \*(``libcurses\*('' manual page lists functions for this feature
+which are prototyped in \fBcurses.h\fP:
+.PP
+.RS 8
+.EX
+extern int mouse_set(long int);
+extern int mouse_on(long int);
+extern int mouse_off(long int);
+extern int request_mouse_pos(void);
+extern int map_button(unsigned long);
+extern void wmouse_position(WINDOW *, int *, int *);
+extern unsigned long getmouse(void), getbmap(void);
+.EE
+.RE
+.bP
+the \*(``terminfo\*('' manual page lists capabilities for the feature
+.PP
+.RS 8
+.EX
+buttons btns BT Number of buttons on the mouse
+get_mouse getm Gm Curses should get button events
+key_mouse kmous Km 0631, Mouse event has occurred
+mouse_info minfo Mi Mouse status information
+req_mouse_pos reqmp RQ Request mouse position report
+.EE
+.RE
+.bP
+the interface made assumptions (as does \fI\%ncurses\fP)
+about the escape sequences
+sent to and received from the terminal.
+.IP
+For instance
+the SVr4 \fIcurses\fP library used the \fB\%get_mouse\fP capability to tell the
+terminal which mouse button events it should send,
+passing the mouse-button bit mask to the terminal.
+Also, it could ask the terminal
+where the mouse was using the \fB\%req_mouse_pos\fP capability.
+.IP
+Those features required a terminal which had been modified
+to work with \fIcurses\fP.
+They were not part of the X Consortium's xterm.
+.PP
+When developing the xterm mouse support for \fI\%ncurses\fP in September
+1995,
+Eric Raymond was uninterested in using the same interface due to its
+lack of documentation.
+Later, in 1998, Mark Hesseling provided support in
+PDCurses 2.3 using the SVr4 interface.
+PDCurses, however, does not use video terminals,
+making it unnecessary to be concerned about compatibility with the
+escape sequences.
.SH BUGS
Mouse events from \fI\%xterm\fP are \fInot\fP ignored in cooked mode if
they have been enabled by \fB\%mousemask\fP.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_move.3x,v 1.32 2023/10/07 21:19:07 tom Exp $
-.TH curs_move 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_move.3x,v 1.33 2023/12/16 21:33:08 tom Exp $
+.TH curs_move 3X 2023-12-16 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.SH NAME
\fB\%move\fP,
\fB\%wmove\fP \-
The position specified is relative to the upper
left-hand corner of the window, which is (0,0).
.SH RETURN VALUE
-These routines return \fBERR\fP upon failure and \fBOK\fP (SVr4
-specifies only "an integer value other than \fBERR\fP") upon successful
-completion.
+These routines return the integer \fBERR\fP upon failure and an \fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
Specifically, they return an error
if the window pointer is null, or
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_opaque.3x,v 1.40 2023/12/02 20:52:50 tom Exp $
-.TH curs_opaque 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_opaque.3x,v 1.41 2023/12/16 20:32:22 tom Exp $
+.TH curs_opaque 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint wgetscrreg(const WINDOW *\fIwin\fP, int *\fItop\fP, int *\fIbottom\fP);
.fi
.SH DESCRIPTION
-\fIncurses\fP provides functions returning properties of a
+\fI\%ncurses\fP provides functions returning properties of a
\fI\%WINDOW\fP structure,
allowing it to be \*(``opaque\*('' if
the application defines the \fB\%NCURSES_OPAQUE\fP preprocessor symbol.
.SH RETURN VALUE
These functions return \fBTRUE\fP or \fBFALSE\fP except as noted.
.SH NOTES
-\fIncurses\fP provides both a C function and a preprocessor macro for
+\fI\%ncurses\fP provides both a C function and a preprocessor macro for
each function documented in this page.
.SH PORTABILITY
-These routines are specific to \fIncurses\fP.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on Version 7, BSD or System V implementations.
-It is recommended that any code depending on \fIncurses\fP extensions
+It is recommended that any code depending on \fI\%ncurses\fP extensions
be conditioned using \fB\%NCURSES_VERSION\fP.
.SH SEE ALSO
\fB\%curses\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_outopts.3x,v 1.52 2023/11/25 14:08:05 tom Exp $
-.TH curs_outopts 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_outopts.3x,v 1.53 2023/12/16 20:32:22 tom Exp $
+.TH curs_outopts 3X 2023-12-16 "ncurses 6.4" "Library calls"
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
.SH PORTABILITY
These functions are described in the XSI Curses standard, Issue 4.
.PP
-From the outset, ncurses used \fBnl\fP/\fBnonl\fP to control the conversion
-of newlines to carriage return/line-feed on output as well as input.
+From the outset,
+\fI\%ncurses\fP used \fBnl\fP/\fBnonl\fP to control the conversion of
+newlines to carriage return/line-feed on output as well as input.
XSI Curses documents only the use of these functions for input.
This difference arose from converting the \fIpcurses\fP source
(which used \fBioctl\fP calls with the \fBsgttyb\fP structure)
option \fBCRMOD\fP,
while the latter separates these features.
Because that conversion interferes with output optimization,
-\fBnl\fP/\fBnonl\fP were amended after ncurses 6.2
+\fBnl\fP/\fBnonl\fP were amended after \fI\%ncurses\fP 6.2
to eliminate their effect on output.
.PP
Some historic curses implementations had, as an undocumented feature, the
ability to do the equivalent of \fBclearok(..., 1)\fP by saying
\fBtouchwin(stdscr)\fP or \fBclear(stdscr)\fP.
-This will not work under ncurses.
+This will not work under \fI\%ncurses\fP.
.PP
Earlier System V curses implementations specified that with \fBscrollok\fP
enabled, any window modification triggering a scroll also forced a physical
refresh.
-XSI Curses does not require this, and \fBncurses\fP avoids doing
+XSI Curses does not require this, and \fI\%ncurses\fP avoids doing
it to perform better vertical-motion optimization at \fBwrefresh\fP
time.
.PP
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_overlay.3x,v 1.35 2023/11/25 11:29:34 tom Exp $
-.TH curs_overlay 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_overlay.3x,v 1.36 2023/12/16 21:32:51 tom Exp $
+.TH curs_overlay 3X 2023-12-16 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.SH NAME
\fB\%overlay\fP,
\fB\%overwrite\fP,
then copying is non-destructive,
as in \fBoverlay\fP.
.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.
+These routines return the integer \fBERR\fP upon failure and an \fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
X/Open defines no error conditions.
In this implementation,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_pad.3x,v 1.49 2023/11/25 14:08:35 tom Exp $
-.TH curs_pad 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_pad.3x,v 1.50 2023/12/16 21:18:02 tom Exp $
+.TH curs_pad 3X 2023-12-16 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
.fi
.SH DESCRIPTION
.SS newpad
-The \fB\%newpad\fP routine creates and returns a pointer to a new pad data
-structure with the given number of lines, \fInlines\fP, and columns,
+\fB\%newpad\fP creates and returns a pointer to a new pad data structure
+with the given number of lines,
+\fInlines\fP,
+and columns,
\fIncols\fP.
-A pad is like a window, except that it is not restricted by the
-screen size, and is not necessarily associated with a particular part of the
-screen.
-Pads can be used when a large window is needed, and only a part of the
-window will be on the screen at one time.
+A pad is like a window,
+except that it is not restricted by the screen size,
+and is not necessarily associated with a particular part of the screen.
+Pads can be used when a large window is needed,
+and only a part of the window will be on the screen at one time.
Automatic refreshes of pads
-(e.g., from scrolling or echoing of input) do not occur.
+(as from scrolling or echoing of input)
+do not occur.
.PP
It is not valid to call \fB\%wrefresh\fP with a \fIpad\fP argument;
call \fB\%prefresh\fP or \fB\%pnoutrefresh\fP instead.
It does this by a call to \fB\%wadd_wch\fP followed by a call
to \fB\%prefresh\fP.
.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.
+Functions that return an integer return \fBERR\fP upon failure and
+\fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
-Routines that return pointers return \fBNULL\fP on error, and set \fB\%errno\fP
-to \fB\%ENOMEM\fP.
+Functions that return pointers return \fBNULL\fP on error,
+and set \fB\%errno\fP to \fB\%ENOMEM\fP.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not define any error conditions.
In this implementation
.RS 3
.TP 5
to \fB\%wecho_wchar\fP returns an error.
.RE
.SH NOTES
-Note that \fB\%pechochar\fP may be a macro.
+\fB\%pechochar\fP may be a macro.
.SH PORTABILITY
BSD \fIcurses\fP has no \fIpad\fP feature.
.PP
a pad is undocumented,
and is not checked by the vendor Unix implementations:
.bP
-SVr4 \fIcurses\fP sets a flag in the \fB\%WINDOW\fP structure in \fB\%newpad\fP
-which tells if the window is a \fIpad\fP.
+SVr4 \fIcurses\fP sets a flag in the \fI\%WINDOW\fP structure in
+\fB\%newpad\fP which tells if the window is a \fIpad\fP.
.IP
However, it uses this information only in
\fB\%waddch\fP (to decide if it should call \fB\%wrefresh\fP) and
and does not check in \fB\%wrefresh\fP to ensure that the pad
is refreshed properly.
.bP
-Solaris X/Open Curses checks if a window is a pad in \fB\%wnoutrefresh\fP,
+Solaris \fI\%xcurses\fP checks whether a window is a pad in
+\fB\%wnoutrefresh\fP,
returning \fBERR\fP in that case.
.IP
-However, it only sets the flag for subwindows if the parent window is a pad.
+However,
+it only sets the flag for subwindows if the parent window is a pad.
Its \fB\%newpad\fP function does not set this information.
Consequently, the check will never fail.
.IP
states that the lack of a check was an MKS extension.
.bP
NetBSD 7 \fIcurses\fP
-sets a flag in the \fB\%WINDOW\fP structure
+sets a flag in the \fI\%WINDOW\fP structure
for \fB\%newpad\fP and \fB\%subpad\fP,
using this to help with the distinction between \fB\%wnoutrefresh\fP
and \fB\%pnoutrefresh\fP.
.PP
This implementation
.bP
-sets a flag in the \fB\%WINDOW\fP structure
+sets a flag in the \fI\%WINDOW\fP structure
for \fB\%newpad\fP and \fB\%subpad\fP,
.bP
allows a \fB\%subwin\fP or \fB\%derwin\fP call to succeed having a pad parent by
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_print.3x,v 1.34 2023/10/21 10:31:22 tom Exp $
-.TH curs_print 3X 2023-10-21 "ncurses 6.4" "Library calls"
+.\" $Id: curs_print.3x,v 1.35 2023/12/16 20:32:22 tom Exp $
+.TH curs_print 3X 2023-12-16 "ncurses 6.4" "Library calls"
.SH NAME
\fB\%mcprint\fP \-
write binary data to printer using \fIterminfo\fR capabilities
When \fB\%mcprint\fP succeeds, it returns the number of characters actually
sent to the printer.
.SH PORTABILITY
-The \fB\%mcprint\fP call was designed for \fIncurses\fP, and is not found
-in SVr4 \fIcurses\fP, 4.4BSD \fIcurses\fP,
+The \fB\%mcprint\fP call was designed for \fI\%ncurses\fP,
+and is not found in SVr4 \fIcurses\fP,
+4.4BSD \fIcurses\fP,
or any other previous version of \fIcurses\fP.
-It is recommended that any code depending on \fIncurses\fP extensions
+It is recommended that any code depending on \fI\%ncurses\fP extensions
be conditioned using \fB\%NCURSES_VERSION\fP.
.SH BUGS
Padding in the
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_printw.3x,v 1.43 2023/11/25 11:31:06 tom Exp $
-.TH curs_printw 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_printw.3x,v 1.45 2023/12/18 00:03:28 tom Exp $
+.TH curs_printw 3X 2023-12-17 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB\%mvwprintw\fP,
\fB\%vwprintw\fP,
\fB\%vw_printw\fP \-
-write formatted output to \fIcurses\fR windows
+write formatted output to a \fIcurses\fR window
.SH SYNOPSIS
.nf
\fB#include <curses.h>
\fBint wprintw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, ...);
\fBint mvprintw(int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...);
\fBint mvwprintw(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...);
+.PP
\fBint vw_printw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
.PP
\fI/* obsolete */\fP
\fBint vwprintw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
.fi
.SH DESCRIPTION
-The \fBprintw\fP, \fBwprintw\fP, \fBmvprintw\fP and \fBmvwprintw\fP
-routines are analogous to \fBprintf\fP [see \fBprintf\fP(3)].
-In
-effect, the string that would be output by \fBprintf\fP is output
-instead as though \fBwaddstr\fP were used on the given window.
+\fB\%printw\fP,
+\fB\%wprintw\fP,
+\fB\%mvprintw\fP,
+and
+\fB\%mvwprintw\fP
+are analogous to \fI\%printf\fP(3).
+In effect,
+the string that would be output by \fI\%printf\fP(3) is instead output
+as though \fB\%waddstr\fP(3X) were used with
+.I win
+(or
+.BR \%stdscr )
+as its first argument.
.PP
-The \fBvwprintw\fP and \fBvw_printw\fP routines are analogous
-to \fBvprintf\fP [see \fBprintf\fP(3)]
-and perform a \fBwprintw\fP using a variable argument list.
-The third argument is a \fBva_list\fP, a pointer to a
-list of arguments, as defined in \fB<stdarg.h>\fP.
+\fB\%vwprintw\fP
+and
+\fB\%vw_printw\fP are analogous to \fI\%vprintf\fP(3),
+and perform a \fB\%wprintw\fP using a variable argument list.
+The third argument is a \fI\%va_list\fP,
+a pointer to a list of arguments,
+as defined in \fI\%stdarg.h\fP.
.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.
+These functions return
+.B ERR
+upon failure and
+.B OK
+upon success.
.PP
-X/Open defines no error conditions.
-In this implementation,
-an error may be returned if it cannot allocate enough memory for the
-buffer used to format the results.
-It will return an error if the window pointer is null.
+In
+.I \%ncurses,
+failure occurs if the library cannot allocate enough memory for the
+buffer into which the output is formatted,
+or if the window pointer
+.I win
+is null.
.PP
-Functions with a \*(``mv\*('' prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions with a \*(``mv\*('' prefix first perform a cursor movement
+using \fB\%wmove\fP,
+and fail if the position is outside the window.
+.SH NOTES
+No wide character counterpart functions are defined by the
+\*(``wide\*(''
+.I \%ncurses
+configuration nor by any standard.
+To format and write a wide-character string to a
+.I curses
+window,
+consider using \fI\%swprintf\fP(3) and \fB\%waddwstr\fP(3X) or similar.
.SH PORTABILITY
-In this implementation, \fBvw_printw\fP and \fBvwprintw\fP are equivalent,
-to support legacy applications.
-However, the latter (\fBvwprintw\fP) is obsolete:
-.bP
-The XSI Curses standard, Issue 4 described these functions.
-The function
-\fBvwprintw\fP is marked TO BE WITHDRAWN, and is to be replaced by a function
-\fBvw_printw\fP using the \fB<stdarg.h>\fP interface.
+X/Open Curses, Issue 4, describes these functions.
+It specifies no error conditions for them.
+.PP
+.I \%ncurses
+defines \fB\%vw_printw\fP and \fB\%vwprintw\fP identically to support
+legacy applications.
+However,
+the latter is obsolete.
.bP
-The Single Unix Specification, Version 2 states that
-\fBvw_printw\fP is preferred to \fBvwprintw\fP since the latter requires
-including \fB<varargs.h>\fP, which
-cannot be used in the same file as \fB<stdarg.h>\fP.
-This implementation uses \fB<stdarg.h>\fP for both,
-because that header is included in \fB<curses.h\fP>.
+X/Open Curses, Issue 4, Version 2 (1996),
+marked \fB\%vwprintw\fP as requiring \fI\%varargs.h\fP and
+\*(``TO BE WITHDRAWN\*('',
+and specified \fB\%vw_printw\fP using the \fI\%stdarg.h\fP interface.
.bP
-X/Open Curses, Issue 5 (December 2007) marked \fBvwprintw\fP (along with
+X/Open Curses, Issue 5, Draft 2
+(December 2007) marked \fBvwprintw\fP (along with
\fBvwscanw\fP and the termcap interface) as withdrawn.
+After incorporating review comments,
+this became
+X/Open Curses, Issue 7 (2009).
+.bP
+.I \%ncurses
+provides \fB\%vwprintw\fP,
+but marks it as deprecated.
.SH HISTORY
-While \fBprintw\fP was implemented in 4BSD,
-it was unused until 4.2BSD (which used it in games).
-That early version of curses was before the ANSI C standard.
-It did not use <varargs.h>, though that was available.
-In 1991 (a couple of years after SVr4 was generally available,
+While \fB\%printw\fP was implemented in 4BSD
+(November 1980),
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+.\" libcurses/printw.c
+it was unused until 4.2BSD
+(August 1983),
+which employed it for games.
+That early version of
+.I curses
+preceded the ANSI C standard of 1989.
+It did not use \fI\%varargs.h\fP,
+though that had been available since Seventh Edition Unix (1979).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
+.\" varargs.h
+In 1991
+(a couple of years after SVr4 was generally available,
and after the C standard was published),
other developers updated the library,
-using <stdarg.h> internally in 4.4BSD curses.
+using \fI\%stdarg.h\fP internally in 4.4BSD
+.I curses.
Even with this improvement,
-BSD curses did not use function prototypes (or even declare
-functions) in the <curses.h> header until 1992.
+BSD
+.I curses
+did not use function prototypes
+(nor even declare functions)
+in \fI\%curses.h\fP until 1992.
.PP
-SVr2 documented
-\fBprintw\fP,
-\fBwprintw\fP
-tersely as \*(``printf on \fIstdscr\fP\*('' and
-tersely as \*(``printf on \fIwin\fP\*('', respectively.
+SVr2 (1984) documented \fB\%printw\fP and \fB\%wprintw\fP tersely as
+\*(``printf on \fB\%stdscr\fP\*('' and
+\*(``printf on \fIwin\fP\*('',
+respectively.
.PP
-SVr3 added
-\fBmvprintw\fP, and
-\fBmvwprintw\fP, with a three-line summary saying that they were analogous
-to \fBprintf\fP(3),
-explaining that the string which would be output from \fBprintf\fP(3) would
-instead be output using \fBwaddstr\fP on the given window.
-SVr3 also added \fBvwprintw\fP, saying that the third parameter
-is a \fBva_list\fP, defined in <varargs.h>,
-and referring the reader to the manual pages for \fIvarargs\fP and
-\fBvprintf\fP for detailed descriptions.
+SVr3 (1987) added \fB\%mvprintw\fP and \fB\%mvwprintw\fP,
+with a three-line summary asserting that they were analogous to
+\fI\%printf\fP(3),
+explaining that the string that \fI\%printf\fP(3) would write to the
+standard output stream would instead be output using \fB\%waddstr\fP to
+the given window.
+SVr3 also implemented \fB\%vwprintw\fP,
+describing its third parameter as a \fI\%va_list\fP,
+defined in \fI\%varargs.h\fP,
+and referred the reader to the manual pages for \fI\%varargs\fP and
+\fI\%vprintf\fP for detailed descriptions.
.PP
-SVr4 added no new variations of \fBprintw\fP,
-but provided for using <varargs.h> or <stdarg.h> to define the \fBva_list\fP
-type.
+SVr4 (1989) introduced no new variations of \fI\%printw\fP,
+but provided for using either \fI\%varargs.h\fP or \fI\%stdarg.h\fP to
+define the \fI\%va_list\fP type.
+.\" either header declares "va_list", but only one can be used
.PP
-X/Open Curses added \fBvw_printw\fP to replace \fBvwprintw\fP,
-stating that its \fBva_list\fP definition requires <stdarg.h>.
+X/Open Curses, Issue 4 (1995),
+defined \fB\%vw_printw\fP to replace \fB\%vwprintw\fP,
+stating that its \fI\%va_list\fP type is defined in \fI\%stdarg.h\fP.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_addstr\fP(3X),
\fB\%curs_scanw\fP(3X),
-\fB\%curs_termcap\fP(3X),
\fB\%printf\fP(3),
\fB\%vprintf\fP(3)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_refresh.3x,v 1.38 2023/10/07 21:19:07 tom Exp $
-.TH curs_refresh 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_refresh.3x,v 1.39 2023/12/16 21:09:11 tom Exp $
+.TH curs_refresh 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
It touches the indicated lines (marking them changed).
The routine \fBredrawwin\fP touches the entire window.
.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.
+These routines return the integer \fBERR\fP upon failure and \fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
X/Open does not define any error conditions.
In this implementation
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scanw.3x,v 1.43 2023/11/25 11:31:06 tom Exp $
-.TH curs_scanw 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_scanw.3x,v 1.44 2023/12/17 22:50:40 tom Exp $
+.TH curs_scanw 3X 2023-12-17 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint vwscanw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
.fi
.SH DESCRIPTION
-The \fBscanw\fP, \fBwscanw\fP and \fBmvscanw\fP routines are analogous to
-\fBscanf\fP [see \fBscanf\fP(3)].
-The effect of these routines is as though
-\fBwgetstr\fP were called on the window, and the resulting line used as input
-for \fBsscanf\fP(3).
-Fields which do not map to a variable in the \fIfmt\fP
-field are lost.
+\fB\%scanw\fP,
+\fB\%wscanw\fP,
+\fB\%mvscanw\fP,
+and
+\fB\%mvwscanw\fP
+are analogous to \fI\%scanf\fP(3).
+In effect,
+they call \fB\%wgetstr\fP(3X) with
+.I win
+(or
+.BR \%stdscr )
+as its first argument,
+then attempt conversion of the resulting string with \fI\%vsscanf\fP(3).
+Fields in the string that do not map to a variable in the \fIfmt\fP
+parameter are discarded.
.PP
-The \fBvwscanw\fP and \fBvw_scanw\fP routines are analogous to \fBvscanf\fP(3).
-They perform a \fBwscanw\fP using a variable argument list.
-The third argument is a \fBva_list\fP,
-a pointer to a list of arguments, as defined in \fB<stdarg.h>\fP.
+\fB\%vwscanw\fP
+and
+\fB\%vw_scanw\fP are analogous to \fI\%vscanf\fP(3),
+and perform a \fB\%wscanw\fP using a variable argument list.
+The third argument is a \fI\%va_list\fP,
+a pointer to a list of arguments,
+as defined in \fI\%stdarg.h\fP.
.SH RETURN VALUE
-\fBvwscanw\fP returns \fBERR\fP on failure and an integer equal to the
-number of fields scanned on success.
+These functions return
+.B ERR
+upon failure and otherwise a count of successful conversions;
+this quantity may be zero.
+.PP
+In
+.I \%ncurses,
+failure occurs if \fI\%vsscanf\fP(3) returns
+\fBEOF\fP,
+or if the window pointer
+.I win
+is null.
.PP
-Applications may use the return value from the \fBscanw\fP, \fBwscanw\fP,
-\fBmvscanw\fP and \fBmvwscanw\fP routines to determine the number of fields
-which were mapped in the call.
+Functions with a \*(``mv\*('' prefix first perform a cursor movement
+using \fB\%wmove\fP,
+and fail if the position is outside the window.
+.SH NOTES
+No wide character counterpart functions are defined by the
+\*(``wide\*(''
+.I \%ncurses
+configuration nor by any standard.
+They are unnecessary:
+to retrieve and convert a wide-character string from a
+.I curses
+terminal keyboard,
+use these functions with the \fI\%scanf\fP(3) conversions \*(``%lc\*(''
+and \*(``%ls\*('' for wide characters and strings,
+respectively.
.PP
-Functions with a \*(``mv\*('' prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+.I \%ncurses
+implements \fI\%vsscanf\fP(3) internally if it is unavailable when the
+library is configured.
.SH PORTABILITY
-In this implementation, \fBvw_scanw\fP and \fBvwscanw\fP are equivalent,
-to support legacy applications.
-However, the latter (\fBvwscanw\fP) is obsolete:
+X/Open Curses, Issue 4, describes these functions.
+It specifies no error conditions for them.
+.PP
+.I \%ncurses
+defines \fB\%vw_scanw\fP and \fB\%vwscanw\fP identically to support
+legacy applications.
+However,
+the latter is obsolete.
.bP
-The XSI Curses standard, Issue 4 described these functions,
-noting that the function
-\fBvwscanw\fP is marked TO BE WITHDRAWN, and is to be replaced by a function
-\fBvw_scanw\fP using the \fB<stdarg.h>\fP interface.
+X/Open Curses, Issue 4, Version 2 (1996),
+marked \fB\%vwscanw\fP as requiring \fI\%varargs.h\fP and
+\*(``TO BE WITHDRAWN\*('',
+and specified \fB\%vw_scanw\fP using the \fI\%stdarg.h\fP interface.
.bP
-The Single Unix Specification, Version 2 states that
-\fBvw_scanw\fP is preferred to \fBvwscanw\fP since the latter requires
-including \fB<varargs.h>\fP, which
-cannot be used in the same file as \fB<stdarg.h>\fP.
-This implementation uses \fB<stdarg.h>\fP for both, because that header
-is included in \fB<curses.h\fP>.
+X/Open Curses, Issue 5, Draft 2
+(December 2007) marked \fB\%vwscanw\fP (along with
+\fB\%vwscanw\fP and the termcap interface) as withdrawn.
+After incorporating review comments,
+this became
+X/Open Curses, Issue 7 (2009).
.bP
-X/Open Curses, Issue 5 (December 2007) marked \fBvwscanw\fP (along with
-\fBvwprintw\fP and the termcap interface) as withdrawn.
-.LP
-Both XSI and The Single Unix Specification, Version 2 state that these
-functions return \fBERR\fP or \fBOK\fP.
+.I \%ncurses
+provides \fB\%vwscanw\fP,
+but marks it as deprecated.
+.PP
+X/Open Curses Issues 4 and 7 both state that these functions return
+\fBERR\fP or \fBOK\fP.
+This is likely an erratum.
.bP
-Since the underlying \fBscanf\fP(3) can return the number of items scanned,
-and the SVr4 code was documented to use this feature,
-this is probably an editing error which was introduced in XSI,
-rather than being done intentionally.
+Since the underlying \fI\%scanf\fP(3) returns the number of successful
+conversions,
+and SVr4
+.I curses
+was documented to use this feature,
+this may have been an editorial solecism introduced by X/Open,
+rather than an intentional change.
.bP
-This implementation returns the number of items scanned,
-for compatibility with SVr4 curses.
-As of 2018, NetBSD curses also returns the number of items scanned.
-Both ncurses and NetBSD curses call \fBvsscanf\fP to scan the string,
+This implementation retains compatibility with SVr4
+.I curses.
+As of 2018,
+NetBSD
+.I curses
+also returns the number of successful conversions.
+Both
+.I \%ncurses\fP
+and NetBSD
+.I curses
+call \fI\%vsscanf\fP(3) to scan the string,
which returns \fBEOF\fP on error.
.bP
-Portable applications should only test if the return value is \fBERR\fP,
-since the \fBOK\fP value (zero) is likely to be misleading.
+Portable applications should test only if the return value is \fBERR\fP,
+and not compare it to \fBOK\fP,
+since that value (zero) might be misleading.
.IP
-One possible way to get useful results would be to use a "%n" conversion
-at the end of the format string to ensure that something was processed.
+One portable way to get useful results would be to use a \*(``%n\*(''
+conversion at the end of the format string,
+and check the value of the corresponding variable to determine how many
+conversions succeeded.
.SH HISTORY
-While \fBscanw\fP was implemented in 4BSD,
-none of the BSD releases used it until 4.4BSD (in a game).
-That early version of curses was before the ANSI C standard.
-It did not use <varargs.h>, though that was available.
-In 1991 (a couple of years after SVr4 was generally available,
+\fB\%scanw\fP was implemented in 4BSD
+(November 1980);
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+.\" libcurses/scanw.c
+that early version of
+.I curses
+preceded the ANSI C standard of 1989.
+The function was unused in Berkeley distributions for over ten years,
+until 4.4BSD,
+which employed it in a game.
+The 4BSD \fB\%scanw\fP did not use \fI\%varargs.h\fP,
+though that had been available since Seventh Edition Unix (1979).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
+.\" varargs.h
+In 1991
+(a couple of years after SVr4 was generally available,
and after the C standard was published),
other developers updated the library,
-using <stdarg.h> internally in 4.4BSD curses.
+using \fI\%stdarg.h\fP internally in 4.4BSD
+.I curses.
Even with this improvement,
-BSD curses did not use function prototypes (or even declare
-functions) in the <curses.h> header until 1992.
+BSD
+.I curses
+did not use function prototypes
+(nor even declare functions)
+in \fI\%curses.h\fP until 1992.
+.PP
+SVr2 (1984) documented \fB\%scanw\fP and \fB\%wscanw\fP tersely as
+\*(``scanf through \fB\%stdscr\fP\*('' and
+\*(``scanf through \fIwin\fP\*('',
+respectively.
+.PP
+SVr3 (1987) added
+\fB\%mvscanw\fP, and
+\fB\%mvwscanw\fP, stating
+.RS
.PP
-SVr2 documented
-\fBscanw\fP,
-\fBwscanw\fP
-tersely as \*(``scanf through \fIstdscr\fP\*('' and
-tersely as \*(``scanf through \fIwin\fP\*('', respectively.
+These routines correspond to \fIscanf\fP(3S),
+as do their arguments and return values.
+\fB\%wgetstr\fP() is called on the window,
+and the resulting line is used as input for the scan.
+.RE
.PP
-SVr3 added
-\fBmvscanw\fP, and
-\fBmvwscanw\fP, with a three-line summary saying that they were analogous
-to \fBscanf\fP(3),
-explaining that the string which would be output from \fBscanf\fP(3) would
-instead be output using \fBwaddstr\fP on the given window.
-SVr3 also added \fBvwscanw\fP, saying that the third parameter
-is a \fBva_list\fP, defined in <varargs.h>,
-and referring the reader to the manual pages for \fIvarargs\fP and
-\fBvprintf\fP for detailed descriptions.
-(Because the SVr3 documentation does not mention \fBvscanf\fP,
-that reference to \fBvprintf\fP may not be an error).
+SVr3 also implemented \fB\%vwscanw\fP,
+describing its third parameter as a \fI\%va_list\fP,
+defined in \fI\%varargs.h\fP,
+and referred the reader to the manual pages for \fI\%varargs\fP and
+\fI\%vprintf\fP for detailed descriptions.
+(Because the SVr3 documentation does not mention \fI\%vscanf\fP,
+the reference to \fI\%vprintf\fP might not be an error).
.PP
-SVr4 added no new variations of \fBscanw\fP,
-but provided for using <varargs.h> or <stdarg.h> to define the \fBva_list\fP
-type.
+SVr4 (1989) introduced no new variations of \fI\%scanw\fP,
+but provided for using either \fI\%varargs.h\fP or \fI\%stdarg.h\fP to
+define the \fI\%va_list\fP type.
+.\" either header declares "va_list", but only one can be used
.PP
-X/Open Curses added \fBvw_scanw\fP to replace \fBvwscanw\fP,
-stating that its \fBva_list\fP definition requires <stdarg.h>.
+X/Open Curses, Issue 4 (1995),
+defined \fI\%vw_scanw\fP to replace \fI\%vwscanw\fP,
+stating that its \fI\%va_list\fP type is defined in \fI\%stdarg.h\fP.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_getstr\fP(3X),
\fB\%curs_printw\fP(3X),
-\fB\%curs_termcap\fP(3X),
-\fB\%scanf\fP(3)
+\fB\%scanf\fP(3),
+\fB\%vscanf\fP(3)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scr_dump.3x,v 1.35 2023/11/25 11:29:34 tom Exp $
-.TH curs_scr_dump 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $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"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
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
-All routines return the integer \fBERR\fP upon failure and \fBOK\fP
+These routines return the integer \fBERR\fP upon failure and \fBOK\fP
upon success.
.PP
X/Open defines no error conditions.
which adds \fI\%const\fP qualifiers to the arguments.
.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\*(''.
+considered invalid \*(``if the time-stamp of the tty is old\*('' but do
+not define \*(``old\*(''.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_initscr\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_scroll.3x,v 1.35 2023/10/07 21:19:07 tom Exp $
-.TH curs_scroll 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_scroll.3x,v 1.36 2023/12/16 22:52:35 tom Exp $
+.TH curs_scroll 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.ie t .ds '' ''
.el .ds '' ""
.\}
+.
+.de bP
+.ie n .IP \(bu 4
+.el .IP \(bu 2
+..
.SH NAME
\fB\%scroll\fP,
\fB\%scrl\fP,
\fBint wscrl(WINDOW *\fIwin\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
-The \fBscroll\fP routine scrolls the window up one line.
-This involves moving
-the lines in the window data structure.
-As an optimization, if the scrolling
-region of the window is the entire screen,
-the \fIphysical screen\fP may be scrolled at the same time.
+\fBscroll\fP scrolls the given window up one line.
+That is,
+every visible line we might number
+.I i
+becomes line
+.IR i \-1.
+The text of the top line in the window disappears and the bottom line
+is populated with blank characters;
+see \fB\%bkgd\fP(3X) or \fB\%bkgrnd\fP(3X).
+As an optimization,
+if the scrolling region of the window is the entire screen,
+the physical screen may be scrolled at the same time;
+see \fB\%curscr\fP(3X).
.PP
-For positive \fIn\fP, the \fBscrl\fP and \fBwscrl\fP routines scroll the
-window up \fIn\fP lines (line \fIi\fP+\fIn\fP becomes \fIi\fP); otherwise
-scroll the window down \fIn\fP lines.
-This involves moving the lines in the
-window character image structure.
-The current cursor position is not changed.
+\fB\%scrl\fP and \fB\%wscrl\fP scroll
+.B \%stdscr
+or the specified window up or down depending on the sign of
+.I n.
+.bP
+For positive
+.I n,
+line \fIi\fP+\fIn\fP becomes \fIi\fP (scrolling up);
+.bP
+for negative
+.I n,
+line \fIi\fP-\fIn\fP becomes \fIi\fP (scrolling down).
.PP
-For these functions to work, scrolling must be enabled via \fBscrollok\fP(3X).
-.SH RETURN VALUE
-These routines return \fBERR\fP upon failure, and \fBOK\fP (SVr4 only specifies
-"an integer value other than \fBERR\fP") upon successful completion.
+The cursor does not move.
+These functions perform no operation unless scrolling is enabled for the
+window via \fB\%scrollok\fP(3X).
+.SH "RETURN VALUE"
+These functions return
+.B ERR
+upon failure and
+.B OK
+upon success.
.PP
-X/Open defines no error conditions.
-.PP
-This implementation returns an error
-if the window pointer is null, or
-if scrolling is not enabled in the window, e.g., with \fBscrollok\fP(3X).
+.I \%ncurses
+returns \fBERR\fP if scrolling is not enabled in the window,
+for example with \fB\%scrollok\fP(3X),
+or if the
+.I \%WINDOW
+pointer is null.
.SH NOTES
-Note that \fBscrl\fP and \fBscroll\fP may be macros.
+Unusually,
+there is no \fB\%wscroll\fP function;
+\fBscroll\fP behaves as one would expect \fB\%wscroll\fP to,
+accepting a \fI\%WINDOW\fP pointer argument.
+.PP
+\fB\%scrl\fP and \fB\%scroll\fP may be implemented as macros.
+.SH PORTABILITY
+X/Open Curses, Issue 4, describes these functions.
+It defines no error conditions.
.PP
-The SVr4 documentation says that the optimization of physically scrolling
-immediately if the scroll region is the entire screen \*(``is\*('' performed,
+SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('' as a successful return
+value.
+.PP
+SVr4 indicates that the optimization of physically scrolling immediately
+if the scroll region is the entire screen \*(``is\*('' performed,
not \*(``may be\*('' performed.
-This implementation deliberately does not guarantee
-that this will occur, to leave open the possibility of smarter
-optimization of multiple scroll actions on the next update.
+.I \%ncurses
+deliberately does not guarantee that this will occur,
+to leave open the possibility of smarter optimization of multiple scroll
+actions on the next update.
.PP
-Neither the SVr4 nor the XSI documentation specify whether the current
-attribute or
-current color-pair of blanks generated by the scroll function is zeroed.
-Under this implementation it is.
-.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.
+Neither SVr4
+.I curses
+nor X/Open Curses specify whether the current attribute or current color
+pair of blanks generated by the scroll function are zeroed.
+.I \%ncurses
+does so.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_outopts\fP(3X)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_slk.3x,v 1.66 2023/11/25 14:31:07 tom Exp $
-.TH curs_slk 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_slk.3x,v 1.67 2023/12/16 21:18:45 tom Exp $
+.TH curs_slk 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
\fBint slk_init(int \fIfmt\fP);
.PP
-\fBint slk_set(int \fIlabnum\fP, const char *\fIlabel\fP, int \fIfmt\fP);
-\fBint slk_wset(int \fIlabnum\fP, const wchar_t *\fIlabel\fP, int \fIfmt\fP);
+\fBint slk_set(int \fIlabnum\fP, const char *\fIlabel\fP, int \fIalign\fP);
+\fBint slk_wset(int \fIlabnum\fP, const wchar_t *\fIlabel\fP, int \fIalign\fP);
.PP
\fBchar *slk_label(int \fIlabnum\fP);
.PP
\fBint slk_attron(const chtype \fIattrs\fP);
\fBint slk_attroff(const chtype \fIattrs\fP);
\fBint slk_attrset(const chtype \fIattrs\fP);
-\fBint slk_attr_on(attr_t \fIattrs\fP, void* \fIopts\fP);
-\fBint slk_attr_off(const attr_t \fIattrs\fP, void * \fIopts\fP);
-\fBint slk_attr_set(const attr_t \fIattrs\fP, short \fIpair\fP, void* \fIopts\fP);
+\fBint slk_attr_on(attr_t \fIattrs\fP, void *\fIopts\fP);
+\fBint slk_attr_off(const attr_t \fIattrs\fP, void *\fIopts\fP);
+\fBint slk_attr_set(const attr_t \fIattrs\fP, short \fIpair\fP, void*\fIopts\fP);
\fI/* extension */
\fBattr_t slk_attr(void);
.PP
\fBint extended_slk_color(int \fIpair\fP);
.fi
.SH DESCRIPTION
-The \fBslk\fP* functions manipulate the set
-of soft function-key labels that exist on many terminals.
+These functions manipulate the soft function key labels that some
+hardware terminals support.
For those terminals that do not have soft labels,
-\fIcurses\fP takes over the bottom line of \fB\%stdscr\fP, reducing the size of
-\fB\%stdscr\fP and the variable \fBLINES\fP.
-\fIcurses\fP standardizes on eight
-labels of up to eight characters each.
-In addition to this, the \fIncurses\fP
-implementation supports a mode where it simulates 12 labels of up to five
-characters each.
-This is useful for PC-like enduser devices.
-\fIncurses\fP simulates this mode by taking over up to two lines at
+\fIcurses\fP takes over the bottom line of \fB\%stdscr\fP,
+reducing its vertical size and the value of \fBLINES\fP by one.
+By default,
+\fIcurses\fP uses eight labels of up to eight characters each.
+.PP
+\fI\%ncurses\fP
+furthermore supports a mode comprising twelve labels of up to five
+characters each,
+following a convention associated with the IBM PC/AT keyboard.
+\fI\%ncurses\fP simulates this mode by taking over up to two lines at
the bottom of the screen;
it does not try to use any hardware support for this
mode.
.SS Initialization
-The \fB\%slk_init\fP routine must be called
-before \fB\%initscr\fP or \fB\%newterm\fP
-is called.
+\fB\%slk_init\fP must be called before \fB\%initscr\fP or
+\fB\%newterm\fP.
If \fB\%initscr\fP eventually uses a line from \fB\%stdscr\fP to
emulate the soft labels,
-then \fIfmt\fP determines how the labels are arranged on the screen:
-.RS 3
+then \fIfmt\fP determines how the labels are arranged on the screen.
.TP 3
.B 0
indicates a 3\-2\-3 arrangement of
.TP 3
.B 3
is again the PC-like 4\-4\-4 mode,
-but in addition an index line is generated, helping the user to
-identify the key numbers easily.
-.RE
+but in addition an index line is generated,
+helping the user to associate each label with its numbered function key.
+\fBLINES\fP and the vertical size of \fB\%stdscr\fP are further reduced.
.SS Labels
-The \fB\%slk_set\fP routine
-(and the \fB\%slk_wset\fP routine for the wide-character library)
-has three parameters:
-.RS 3
-.TP 5
+Populate the labels with normal strings
+(\fB\%slk_set\fP)
+or wide-character strings
+(\fB\%slk_wset\fP).
+Each function takes three parameters.
+.TP 8 \" "labnum" + 2n
.I labnum
is the label number, from \fB1\fP to \fB8\fP
(12 if \fIfmt\fP in \fB\%slk_init\fP is \fB2\fP or \fB3\fP);
up to eight
(five if \fIfmt\fP in \fB\%slk_init\fP is \fB2\fP or \fB3\fP)
characters in length.
-A null string or a null pointer sets up a blank label.
+A empty string or a null pointer sets up a blank label.
.TP
-.I fmt
-is either
-\fB0\fP, \fB1\fP, or \fB2\fP, indicating whether the label is to be
-left-justified, centered, or right-justified, respectively, within the
-label.
-.RE
+.I align
+is
+.BR 0 ,
+.BR 1 ,
+or
+.BR 2 ,
+aligning
+.I label
+to the left,
+center,
+or right,
+respectively,
+within the 8 (5) character cells housing it.
.PP
-The \fB\%slk_label\fP routine returns the current label for label number
-\fIlabnum\fP, with leading and trailing blanks stripped.
-.SS Screen updates
-The \fB\%slk_refresh\fP and \fB\%slk_noutrefresh\fP routines correspond to
-the \fB\%wrefresh\fP and \fB\%wnoutrefresh\fP routines.
+\fB\%slk_label\fP obtains the string assigned to label number
+\fIlabnum\fP,
+with any leading and trailing blanks stripped.
+.SS "Screen Updates"
+\fB\%slk_refresh\fP and \fB\%slk_noutrefresh\fP affect the soft key
+label lines as \fB\%wrefresh\fP and \fB\%wnoutrefresh\fP do the
+.I curses
+window.
.PP
The \fB\%slk_clear\fP routine clears the soft labels from the screen.
.PP
.PP
The \fB\%slk_touch\fP routine forces all the soft labels to be output
the next time a \fB\%slk_noutrefresh\fP is performed.
-.SS Video attributes
+.SS "Video Attributes"
The
-\fB\%slk_attron\fP, \fB\%slk_attrset\fP, \fB\%slk_attroff\fP and \fB\%slk_attr\fP
+\fB\%slk_attron\fP,
+\fB\%slk_attrset\fP,
+\fB\%slk_attroff\fP,
+and
+\fB\%slk_attr\fP
routines correspond to
-\fB\%attron\fP, \fB\%attrset\fP, \fB\%attroff\fP and \fB\%attr_get\fP, respectively.
-They have an effect only if soft labels are simulated on the bottom line of
-the screen.
-The default highlight for soft keys is A_STANDOUT (as in
-System V \fIcurses\fP, which does not document this fact).
+\fB\%attron\fP,
+\fB\%attrset\fP,
+\fB\%attroff\fP,
+and
+\fB\%attr_get\fP,
+respectively.
+They have an effect only if soft labels are simulated on the bottom line
+of the screen.
+The default highlight for soft key labels is \fB\%A_STANDOUT\fP
+(as in System\ V \fIcurses\fP,
+which does not document this fact).
.SS Colors
The \fB\%slk_color\fP routine corresponds to \fB\%color_set\fP.
It has an effect only
if soft labels are simulated on the bottom line of the screen.
.PP
Because \fB\%slk_color\fP accepts
-only \fBshort\fP (signed 16-bit integer) values,
+only \fIshort\fP
+(signed 16-bit integer)
+values,
this implementation provides
-\fB\%extended_slk_color\fP which accepts an integer value, e.g., 32-bits.
-.
+\fB\%extended_slk_color\fP,
+which accepts an \fIint\fP value of at least 32 bits.
.SH RETURN VALUE
-These routines return \fBERR\fP upon failure
-and \fBOK\fP (SVr4 specifies only "an integer value other than \fBERR\fP")
+Routines that return an integer return \fBERR\fP upon failure and
+\fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
upon successful completion.
.PP
-X/Open defines no error conditions.
+X/Open Curses defines no error conditions.
+.PP
In this implementation
.RS 3
.TP 5
Most applications would use \fB\%slk_noutrefresh\fP because a
\fB\%wrefresh\fP is likely to follow soon.
.SH EXTENSIONS
-X/Open \fIcurses\fP documents the \fIopts\fP argument
+X/Open Curses documents the \fIopts\fP argument
as reserved for future use,
saying that it must be null.
This implementation
-uses that parameter in ABI 6 for the functions which have a color-pair
+uses that parameter in ABI 6 for the functions which have a color pair
parameter to support extended color pairs.
.PP
-For functions which modify the color, e.g., \fB\%slk_attr_set\fP,
-if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
-and used to set the color pair instead of the \fBshort\fP pair parameter.
+For functions which modify the color,
+e.g.,
+\fB\%slk_attr_set\fP,
+if \fIopts\fP is set it is treated as a pointer to \fIint\fP,
+and used to set the color pair instead of the \fIshort\fP pair
+parameter.
.SH PORTABILITY
-The XSI \fIcurses\fP standard, Issue 4, described the soft-key functions,
+X/Open Curses, Issue 4, describes these functions,
with some differences from SVr4 \fIcurses\fP:
.bP
-It added functions like the SVr4
-attribute-manipulation functions \fB\%slk_attron\fP,
-\fB\%slk_attroff\fP, \fB\%slk_attrset\fP,
-but which use \fBattr_t\fP parameters (rather than \fB\%chtype\fP),
+X/Open added functions like the SVr4 attribute-manipulation functions
+\fB\%slk_attron\fP,
+\fB\%slk_attroff\fP,
+and
+\fB\%slk_attrset\fP,
+but which use \fI\%attr_t\fP parameters
+(rather than \fI\%chtype\fP),
along with a reserved \fIopts\fP parameter.
.IP
-Two of these new functions (unlike the SVr4 functions) have no provision
-for color: \fB\%slk_attr_on\fP and \fB\%slk_attr_off\fP.
+Two of these new functions
+(unlike the SVr4 functions)
+have no provision for color:
+\fB\%slk_attr_on\fP and \fB\%slk_attr_off\fP.
.IP
-The third function \%(\fBslk_attr_set\fP) has a color-pair parameter.
+The third function \%(\fBslk_attr_set\fP) has a color pair parameter.
.bP
-It added \fBconst\fP qualifiers to parameters (unnecessarily), and
+It added \fIconst\fP qualifiers to parameters (unnecessarily),
+and
.bP
It added \fB\%slk_color\fP.
.PP
If there are more than 16 elements, \fB\%slk_start\fP returns an error.
.bP
The format codes \fB2\fP and \fB3\fP for \fB\%slk_init\fP
-were added by \fIncurses\fP in 1996.
+were added by \fI\%ncurses\fP in 1996.
PDCurses 2.4 added this feature in 2001.
.PP
-The function \fB\%slk_attr\fP was added by \fIncurses\fP in 1996.
+The function \fB\%slk_attr\fP was added by \fI\%ncurses\fP in 1996.
.PP
-X/Open \fIcurses\fP does not specify a limit for the number of colors and
+X/Open Curses does not specify a limit for the number of colors and
color pairs which a terminal can support.
-However, in its use of \fBshort\fP for the parameters,
+However, in its use of \fIshort\fP for the parameters,
it carries over SVr4's implementation detail for the compiled
terminfo database, which uses signed 16-bit numbers.
This implementation provides extended versions of those functions
-which use \fBint\fP parameters,
+which use \fIint\fP parameters,
allowing applications to use larger color- and pair-numbers.
.SH HISTORY
SVr3 introduced these functions:
\fBslk_attrset\fP
\fBslk_start\fP
.PP
-X/Open \fIcurses\fP added these:
+X/Open Curses added these:
\fBslk_attr_off\fP
\fBslk_attr_on\fP
\fBslk_attr_set\fP
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_sp_funcs.3x,v 1.44 2023/11/25 15:48:03 tom Exp $
-.TH curs_sp_funcs 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_sp_funcs.3x,v 1.45 2023/12/16 20:32:22 tom Exp $
+.TH curs_sp_funcs 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.SH DESCRIPTION
This implementation can be configured to provide a set of functions which
improve the ability to manage multiple screens.
-This feature can be added to any of the configurations supported by ncurses;
+This feature can be added to any of the configurations supported by
+\fI\%ncurses\fP;
it adds new entrypoints
without changing the meaning of any of the existing ones.
.\" ***************************************************************************
This is a function-pointer type used for the cases where a function passes
characters to the output stream, e.g., \fBvidputs\fP(3X).
.SH PORTABILITY
-These routines are specific to ncurses.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on Version 7, BSD or System V implementations.
-It is recommended that any code depending on ncurses extensions
+It is recommended that any code depending on \fI\%ncurses\fP extensions
be conditioned using \fINCURSES_SP_FUNCS\fP.
.SH SEE ALSO
\fB\%curses\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termcap.3x,v 1.74 2023/12/02 20:49:04 tom Exp $
-.TH curs_termcap 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_termcap.3x,v 1.76 2023/12/18 00:22:30 tom Exp $
+.TH curs_termcap 3X 2023-12-17 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB#include <curses.h>
\fB#include <term.h>
.PP
-\fBextern char PC;
-\fBextern char * UP;
-\fBextern char * BC;
-\fBextern @NCURSES_OSPEED@ ospeed;
+\fBchar PC;
+\fBchar * UP;
+\fBchar * BC;
+\fB@NCURSES_OSPEED@ ospeed;
.PP
\fBint tgetent(char *\fIbp\fP, const char *\fIname\fP);
\fBint tgetflag(const char *\fIid\fP);
\fBint tputs(const char *\fIstr\fP, int \fIaffcnt\fP, int (*\fIputc\fP)(int));
.fi
.SH DESCRIPTION
-These routines are included as a conversion aid for programs that use
-the \fItermcap\fP library.
-Their parameters are the same, but the
-routines are emulated using the \fIterminfo\fP database.
-Thus, they
-can only be used to query the capabilities of entries for which a
-terminfo entry has been compiled.
+.I \%ncurses
+provides the foregoing variables and functions as a compatibility layer
+for programs that use the \fItermcap\fP library.
+The API is the same,
+but behavior is emulated using the \fI\%term\%info\fP database.
+Thus,
+it can be used only to query the capabilities of terminal database
+entries for which a \fI\%term\%info\fP entry has been compiled.
.SS Initialization
-The \fBtgetent\fP routine loads the entry for \fIname\fP.
+\fB\%tgetent\fP loads the terminal database entry for \fIname\fP;
+see \fBterm\fP(7).
+This must be done before calling any of the other functions.
It returns:
.RS 3
-.TP 3
+.TP 4
1
on success,
-.TP 3
+.TP 4
0
if there is no such entry
-(or that it is a generic type, having too little information for curses
-applications to run), and
-.TP 3
+(or if the matching entry describes a generic terminal,
+having too little information for
+.I curses
+applications to run),
+and
+.TP 4
\-1
-if the terminfo database could not be found.
+if the \fI\%term\%info\fP database could not be found.
.RE
.PP
-This differs from the \fItermcap\fP library in two ways:
+This implementation differs from those of historical \fItermcap\fP
+libraries.
.RS 3
.bP
-The emulation ignores the buffer pointer \fIbp\fP.
-The \fItermcap\fP library would store a copy of the terminal
+.I \%ncurses
+ignores the buffer pointer \fIbp\fP,
+as do other \fItermcap\fP implementations conforming to portions of
+X/Open Curses now withdrawn.
+The BSD \fItermcap\fP library would store a copy of the terminal type
description in the area referenced by this pointer.
-However, ncurses stores its terminal descriptions in compiled
-binary form, which is not the same thing.
+\fI\%ncurses\fP stores terminal type descriptions in compiled form,
+which is not the same thing.
.bP
-There is a difference in return codes.
-The \fItermcap\fP library does not check if the terminal
-description is marked with the \fIgeneric\fP capability,
-or if the terminal description has cursor-addressing.
+The meanings of the return values differ.
+The BSD \fItermcap\fP library does not check whether the terminal type
+description is marked with the
+.B gn
+.RB ( \%generic )
+capability,
+nor whether the terminal type description supports an addressable
+cursor,
+a property essential for any \fIcurses\fP implementation to operate.
.RE
-.SS Capability Values
-The \fBtgetflag\fP routine gets the boolean entry for \fIid\fP,
+.SS "Retrieving Capability Values"
+\fB\%tgetflag\fP reports the Boolean entry for \fIid\fP,
or zero if it is not available.
.PP
-The \fBtgetnum\fP routine gets the numeric entry for \fIid\fP,
+\fB\%tgetnum\fP obtains the numeric entry for \fIid\fP,
or \-1 if it is not available.
.PP
-The \fBtgetstr\fP routine returns the string entry for \fIid\fP,
-or zero if it is not available.
-Use \fBtputs\fP to output the returned string.
-The \fIarea\fP parameter is used as follows:
+\fB\%tgetstr\fP returns the string entry for \fIid\fP,
+or
+.B NULL
+if it is not available.
+Use \fB\%tputs\fP to output the string returned.
+The
+.I area
+parameter is used as follows.
.RS 3
.bP
It is assumed to be the address of a pointer to a buffer managed by the
calling application.
.bP
-However, ncurses checks to ensure that \fBarea\fP is not NULL,
-and also that the resulting buffer pointer is not NULL.
-If either check fails, the \fIarea\fP parameter is ignored.
+However,
+\fI\%ncurses\fP checks to ensure that
+.I area
+is not
+.BR NULL ,
+and also that the resulting buffer pointer is not
+.BR NULL .
+If either check fails,
+.I area
+is ignored.
.bP
-If the checks succeed, ncurses also copies the return value to
-the buffer pointed to by \fIarea\fP,
-and the \fIarea\fP value will be updated to point past the null ending
-this value.
+If the checks succeed,
+\fI\%ncurses\fP also copies the return value to the buffer pointed to by
+\fIarea\fP,
+and the library updates
+.I area
+to point past the null character terminating this value.
.bP
-The return value itself is an address in the terminal description which
-is loaded into memory.
+The return value itself is an address in the terminal type description
+loaded into memory.
.RE
-.PP
-Only the first two characters of the \fBid\fP parameter of
-\fBtgetflag\fP,
-\fBtgetnum\fP and
-\fBtgetstr\fP are compared in lookups.
-.SS Formatting Capabilities
-The \fBtgoto\fP routine expands the given capability using the parameters.
+.SS "Applying String Capabilities"
+String capabilities can be parameterized;
+see subsection \*(``Parameterized Strings\*('' in \fB\%terminfo\fP(5).
+\fB\%tgoto\fP applies its second and third arguments to the parametric
+placeholders in the capability stored in the first argument.
.bP
-Because the capability may have padding characters,
-the output of \fBtgoto\fP should be passed to \fBtputs\fP
-rather than some other output function such as \fBprintf\fP(3).
+The capability may contain padding specifications;
+see subsection \*(``Delays and Padding\*('' of \fB\%terminfo\fP(5).
+The output of \fB\%tgoto\fP should thus be passed to \fB\%tputs\fP
+rather than some other output function such as \fI\%printf\fP(3).
.bP
-While \fBtgoto\fP is assumed to be used for the two-parameter
+While \fB\%tgoto\fP is assumed to be used for the two-parameter
cursor positioning capability,
-termcap applications also use it for single-parameter capabilities.
+\fItermcap\fP applications also use it for single-parameter
+capabilities.
.IP
-Doing this shows a quirk in \fBtgoto\fP: most hardware
-terminals use cursor addressing with \fIrow\fP first,
-but the original developers of the termcap interface chose to
-put the \fIcolumn\fP parameter first.
-The \fBtgoto\fP function swaps the order of parameters.
-It does this also for calls requiring only a single parameter.
-In that case, the first parameter is merely a placeholder.
+Doing so reveals a quirk in \fB\%tgoto\fP:
+most hardware terminals use cursor addressing with \fIrow\fP first,
+but the original developers of the \fItermcap\fP interface chose to
+put the \fIcol\fP (column) parameter first.
+The \fB\%tgoto\fP function swaps the order of parameters.
+It does this even for calls requiring only a single parameter.
+In that case,
+the first parameter is merely a placeholder.
.bP
-Normally the ncurses library is compiled with terminfo support.
-In that case, \fBtgoto\fP uses an internal version of
-\fBtparm\fP(3X) (a more capable formatter).
+Normally the \fI\%ncurses\fP library is compiled without
+full \fI\%term\%cap\fP support.
+In that case,
+\fB\%tgoto\fP uses an internal version of \fB\%tparm\fP(3X)
+(a more capable function).
.IP
-With terminfo support, \fBtgoto\fP is able to use some of the terminfo
-features, but not all.
-In particular, it allows only numeric parameters;
-\fBtparm\fP supports string parameters.
+Because it uses \fB\%tparm\fP internally,
+\fB\%tgoto\fP is able to use some \fI\%term\%info\fP features,
+but not all.
+In particular,
+it allows only numeric parameters;
+\fB\%tparm\fP supports string parameters.
.IP
-However, \fBtparm\fP is not a \fItermcap\fP feature,
-and portable \fItermcap\fP applications should not rely upon its availability.
+However,
+\fB\%tparm\fP is not a \fItermcap\fP feature,
+and portable \fItermcap\fP applications should not rely upon its
+availability.
.PP
-The \fBtputs\fP routine is described on the \fBcurs_terminfo\fP(3X) manual
-page.
-It can retrieve capabilities by either termcap or terminfo name.
-.SS Global Variables
+\fB\%tputs\fP is described in \fB\%curs_terminfo\fP(3X).
+It can retrieve capabilities by either \fItermcap\fP or
+\fI\%term\%info\fP name.
+.SS "Global Variables"
The variables
\fBPC\fP,
\fBUP\fP and
\fBBC\fP
-are set by \fBtgetent\fP to the terminfo entry's data for
-\fBpad_char\fP,
-\fBcursor_up\fP and
-\fBbackspace_if_not_bs\fP,
+are set by \fB\%tgetent\fP to the \fI\%term\%info\fP entry's data for
+\fB\%pad_char\fP,
+\fB\%cursor_up\fP and
+\fB\%backspace_if_not_bs\fP,
respectively.
-\fBUP\fP is not used by ncurses.
-\fBPC\fP is used in the \fBtdelay_output\fP function.
-\fBBC\fP is used in the \fBtgoto\fP emulation.
-The variable \fBospeed\fP is set by ncurses in a system-specific coding
-to reflect the terminal speed.
-.SS Releasing Memory
-The termcap functions provide no means for freeing memory,
-because legacy termcap implementations used only the buffer
-areas provided by the caller via \fBtgetent\fP and \fBtgetstr\fP.
-Those buffers are unused in terminfo.
+\fBUP\fP is not used by \fI\%ncurses\fP.
+\fBPC\fP is used by \fB\%delay_output\fP(3X).
+\fBBC\fP is used by \fB\%tgoto\fP emulation.
+The variable \fB\%ospeed\fP is set by \fI\%ncurses\fP using a
+system-specific encoding to indicate the terminal's data rate.
+.SS "Releasing Memory"
+The \fItermcap\fP functions provide no means of freeing memory,
+because legacy \fItermcap\fP implementations used only the buffer
+areas provided by the caller via \fB\%tgetent\fP and \fB\%tgetstr\fP.
+Those buffers are unused in \fI\%term\%info\fP.
.PP
-On the other hand, terminfo allocates memory.
-It uses \fBsetupterm\fP to retrieve the data used by \fBtgetent\fP
-and the functions which return capability values such as \fBtgetstr\fP.
+By contrast,
+\fI\%term\%info\fP allocates memory.
+It uses \fB\%setupterm\fP(3X) to obtain the data used by \fB\%tgetent\fP
+and the functions that retrieve capability values.
One could use
-.sp
- \fBdel_curterm(cur_term);\fP
-.sp
-.PP
-to free this memory, but there is an additional complication with ncurses.
-It uses a fixed-size \fIpool\fP of storage locations,
-one per setting of the \fITERM\fP variable when \fBtgetent\fP is called.
-The \fBscreen\fP(1) program relies upon this arrangement,
-to improve its performance.
-.PP
-An application which uses only the low-level termcap functions could
-free the memory using \fBdel_curterm\fP,
-because the pool is freed using other functions
-(see \fBcurs_memleaks\fP(3X)).
-.
-.SH RETURN VALUE
-Except where explicitly noted,
-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.
+.RS
+.EX
+del_curterm(cur_term);
+.EE
+.RE
+to free this memory,
+but there is an additional complication with \fI\%ncurses\fP.
+It uses a fixed-size pool of storage locations,
+one per value of the \fITERM\fP environment variable when
+\fB\%tgetent\fP is called.
+The \fBscreen\fP(1) program relies upon this arrangement to improve its
+performance.
.PP
-Routines that return pointers return \fBNULL\fP on error.
+An application that uses only the \fItermcap\fP functions,
+not the higher level
+.I \%curses
+API,
+could release the memory using \fB\%del_curterm\fP(3X),
+because the pool is freed using other functions;
+see \fB\%curs_memleaks\fP(3X).
+.SH "RETURN VALUE"
+The return values of
+\fB\%tgetent\fP,
+\fB\%tgetflag\fP,
+\fB\%tgetname\fP,
+and
+\fB\%tgetstr\fP
+are documented above.
.PP
-A few special cases apply:
+\fB\%tgoto\fP returns
+.B NULL
+on error.
+Error conditions include:
+.bP
+uninitialized state
+(\fB\%tgetent\fP was not called successfully),
.bP
-If the terminal database has not been initialized,
-these return an error.
+.I cap
+being a null pointer,
.bP
-The calls with a string parameter (\fBtgoto\fP, \fBtputs\fP)
-check if the string is null, or cancelled.
-Those return an error.
+.I cap
+referring to a canceled capability,
.bP
-A call to \fBtgoto\fP using a capability with string parameters is an error.
+.I cap
+being a capability with string-valued parameters
+(a \fI\%term\%info\fP-only feature),
+and
.bP
-A call to \fBtgoto\fP using a capability with more than two parameters
-is an error.
+.I cap
+being a capability with more than two parameters.
+.PP
+See \fB\%curs_terminfo\fP(3X) regarding \fB\%tputs\fP.
+.SH NOTES
+\fI\%ncurses\fP compares only the first two characters of the \fIid\fP
+parameter of
+\fB\%tgetflag\fP,
+\fB\%tgetnum\fP,
+and
+\fB\%tgetstr\fP to the capability names in the database.
.SH PORTABILITY
+These functions are no longer standardized
+(and the variables never were);
+\fI\%ncurses\fP provides them to support legacy applications.
+They should not be used in new programs.
.SS Standards
-These functions are provided for supporting legacy applications,
-and should not be used in new programs:
.bP
-The XSI Curses standard, Issue 4 describes these functions.
-However, they
-are marked TO BE WITHDRAWN and may be removed in future versions.
+X/Open Curses, Issue 4, Version 2 (1996),
+describes these functions.
+However,
+they are marked
+\*(``TO BE WITHDRAWN\*(''.
.bP
-X/Open Curses, Issue 5 (December 2007) marked the termcap interface
-(along with \fBvwprintw\fP and \fBvwscanw\fP) as withdrawn.
+X/Open Curses, Issue 7 (2009) marked the \fItermcap\fP interface
+(along with \fB\%vwprintw\fP and \fB\%vwscanw\fP) as withdrawn.
.PP
-Neither the XSI Curses standard nor the SVr4 man pages documented the return
-values of \fBtgetent\fP correctly, though all three were in fact returned ever
-since SVr1.
-In particular, an omission in the XSI Curses documentation has been
-misinterpreted to mean that \fBtgetent\fP returns \fBOK\fP or \fBERR\fP.
+Neither X/Open Curses nor the SVr4 man pages documented the return
+values of \fB\%tgetent\fP correctly,
+though all three were in fact returned ever since SVr1.
+In particular,
+an omission in the X/Open Curses specification has been misinterpreted
+to mean that \fB\%tgetent\fP returns \fBOK\fP or \fBERR\fP.
Because the purpose of these functions is to provide compatibility with
-the \fItermcap\fP library, that is a defect in XCurses, Issue 4, Version 2
-rather than in ncurses.
-.SS Compatibility with BSD Termcap
-External variables are provided for support of certain termcap applications.
-However, termcap applications' use of those variables is poorly documented,
-e.g., not distinguishing between input and output.
-In particular, some applications are reported to declare and/or
-modify \fBospeed\fP.
+the \fItermcap\fP library,
+that is a defect in X/Open Curses, Issue 4, Version 2
+rather than in \fI\%ncurses\fP.
+.SS "Compatibility with BSD \fItermcap\fP"
+Externally visible variables are provided for support of certain
+\fItermcap\fP applications.
+However,
+their correct usage is poorly documented;
+for example,
+it is unclear when reading and writing them is meaningful.
+In particular,
+some applications are reported to declare and/or modify \fB\%ospeed\fP.
.PP
-The comment that only the first two characters of the \fBid\fP parameter
-are used escapes many application developers.
-The original BSD 4.2 termcap library (and historical relics thereof)
-did not require a trailing null NUL on the parameter name passed
-to \fBtgetstr\fP, \fBtgetnum\fP and \fBtgetflag\fP.
-Some applications assume that the termcap interface does not require
-the trailing NUL for the parameter name.
-Taking into account these issues:
-.bP
-As a special case,
-\fBtgetflag\fP matched against a single-character identifier
-provided that was at the end of the terminal description.
-You should not rely upon this behavior in portable programs.
-This implementation disallows matches against single-character capability names.
+The constraint that only the first two characters of the \fIid\fP
+parameter are used escapes many application developers.
+The BSD \fItermcap\fP library did not require a trailing null character
+on the capability identifier passed to \fB\%tgetstr\fP,
+\fB\%tgetnum\fP,
+and
+\fB\%tgetflag\fP.
+.\" See <https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/\
+.\" termlib/termcap.c>.
+Some applications thus assume that the \fItermcap\fP interface does not
+require the trailing null character for the capability identifier.
.bP
-This implementation disallows matches by the termcap interface against
-extended capability names which are longer than two characters.
+.I \%ncurses
+disallows matches by the \fItermcap\fP interface against extended
+capability names that are longer than two characters;
+see \fB\%user_caps\fP(5).
.PP
-The BSD termcap function \fBtgetent\fP returns the text of a termcap
-entry in the buffer passed as an argument.
-This library (like other terminfo implementations) does not store
-terminal descriptions as text.
+The BSD \fItermcap\fP function \fB\%tgetent\fP returns the text of a
+\fItermcap\fP entry in the buffer passed as an argument.
+This library,
+like other \fI\%term\%info\fP implementations,
+does not store terminal type descriptions as text.
It sets the buffer contents to a null-terminated string.
-.SS Other Compatibility
-This library includes a termcap.h header,
-for compatibility with other implementations.
-But the header is rarely used because the other implementations
-are not strictly compatible.
+.SS "Header File"
+This library includes a \fI\%termcap.h\fP header for compatibility with
+other implementations,
+but the header is rarely used because the other implementations are not
+strictly compatible.
+.SH HISTORY
+.\" See https://www.oreilly.com/openbook/opensources/book/kirkmck.html
+.\" for much BSD release history.
+Bill Joy originated a forerunner of \fItermcap\fP called
+\*(``ttycap\*('',
+dated September 1977,
+and released in 1BSD
+(March 1978).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/s7/ttycap.c
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=1BSD/man7/ttycap.7
+It used many of the same function names as the later \fItermcap\fP,
+such as
+\fB\%tgetent\fP,
+\fB\%tgetflag\fP,
+\fB\%tgetnum\fP,
+and
+\fB\%tgetstr\fP.
+.PP
+A clear descendant,
+the \fItermlib\fP library,
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/src/termlib/
+followed in 2BSD
+(May 1979),
+adding \fB\%tgoto\fP and \fB\%tputs\fP.
+The former applied at that time only to cursor positioning capabilities,
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=2BSD/bin/etc/termcap
+thus the overly specific name.
+Little changed in 3BSD
+(late 1979)
+except the addition of test programs and a \fI\%termlib\fP man page,
+which documented the API shown in section \*(``SYNOPSIS\*('' above.
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/lib/\
+.\" libtermlib/
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/man/man3/\
+.\" termlib.3
+.PP
+4BSD
+(November 1980)
+renamed \fItermlib\fP to \fItermcap\fP
+.\" ...except in the source tree...
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
+.\" libtermlib/makefile
+and added another test program.
+The library remained much the same though 4.3BSD
+(June 1986).
+4.4BSD-Lite
+(June 1994)
+refactored it
+.\" Observe the `tncktc()`, `tnamatch()`, `tskip()`, and `tdecode()`
+.\" entry points disappearing from termcap.c.
+but left the API unchanged.
.PP
-The original BSD termcap (through 4.3BSD) had no header file which
-gave function prototypes, because that was a feature of ANSI C.
-BSD termcap was written several years before C was standardized.
-However, there were two different termcap.h header files in the BSD
-sources:
+Function prototypes were a feature of the forthcoming ANSI C (1989).
+Thus the library provided no header file declaring them.
+Nevertheless,
+the BSD sources included two different \fI\%termcap.h\fP header files
+over time.
.bP
-One was used internally by the \fBjove\fP editor in 2BSD through 4.4BSD.
-It defined global symbols for the termcap variables which it used.
+One was used internally by \fBjove\fP(1) from 4.3BSD onward.
+.\" 2BSD became a branch retaining support for non-virtual memory
+.\" systems (like the PDP-11) whereas most BSD development focused on
+.\" the VAX and other VM-enabled systems starting with 3BSD.
+.\"
+.\" This man page previously located a termcap.h in 2BSD, but that may
+.\" be confusion arising from its backport to 2.9BSD (and still present
+.\" in surviving sources for 2.11BSD, the "end of the line" for that
+.\" branch's development).
+.\"
+.\" Observe the copyright notice in
+.\" 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.
.bP
-The other appeared in 4.4BSD Lite Release 2 (mid-1993)
-as part of \fIlibedit\fP (also known as the \fIeditline\fP library).
-The CSRG source history shows that this was added in mid-1992.
-The \fIlibedit\fP header file was used internally,
-as a convenience for compiling the \fIeditline\fP library.
-It declared function prototypes, but no global variables.
-.PP
-The header file from \fIlibedit\fP was added to NetBSD's termcap
-library in mid-1994.
+The other appeared in 4.4BSD-Lite Release 2
+(June 1995)
+as part of \fIlibedit\fP
+(also known as the \fI\%edit\%line\fP library).
+CSRG source history shows that this was added in mid-1992.
+The \fIlibedit\fP header file was used internally as a convenience for
+compiling the \fI\%edit\%line\fP library.
+It declared function prototypes,
+but no global variables.
+This header file was added to NetBSD's \fItermcap\fP library in
+mid-1994.
.PP
-Meanwhile, GNU termcap was under development, starting in 1990.
-The first release (termcap 1.0) in 1991 included a termcap.h header.
-The second release (termcap 1.1) in September 1992 modified the
-header to use \fBconst\fP for the function prototypes in the header
-where one would expect the parameters to be read-only.
-This was a difference versus the original BSD termcap.
-The prototype for \fBtputs\fP also differed,
-but in that instance, it was \fIlibedit\fP which differed from BSD termcap.
+Meanwhile,
+GNU \fItermcap\fP began development in 1990.
+Its first release (1.0) in 1991 included a \fI\%termcap.h\fP header.
+Its second (1.1) in September 1992 modified the header to use
+\fIconst\fP for the function prototypes in the header where one would
+expect the parameters to be read-only.
+BSD \fItermcap\fP did not.
+The prototype for \fB\%tputs\fP also differed,
+but in that instance,
+it was \fIlibedit\fP that differed from BSD \fItermcap\fP.
.PP
-A copy of GNU termcap 1.3 was bundled with \fIbash\fP in mid-1993,
-to support the \fBreadline\fP(3) library.
+GNU \fItermcap\fP 1.3 was bundled with \fIbash\fP in mid-1993 to support
+the \fBreadline\fP(3) library.
.PP
-A termcap.h file was provided in ncurses 1.8.1 (November 1993).
-That reflected influence by \fBemacs\fP(1) (rather than \fBjove\fP(1))
-and GNU termcap:
+\fI\%ncurses\fP 1.8.1
+(November 1993)
+provided a \fI\%termcap.h\fP file.
+It reflected influence from GNU \fItermcap\fP and \fBemacs\fP(1)
+(rather than \fBjove\fP(1)),
+providing the following interface:
.bP
-it provided declarations for a few global symbols used by \fBemacs\fP
+global symbols used by \fIemacs\fP,
.bP
-it provided function prototypes (using \fBconst\fP).
+\fIconst\fP-qualified function prototypes,
+and
.bP
-a prototype for \fBtparam\fP (a GNU termcap feature) was provided.
+a prototype for \fBtparam\fP,
+a GNU \fItermcap\fP feature.
.PP
-Later (in mid-1996) the \fBtparam\fP function was removed from ncurses.
-As a result, there are differences between any of the four implementations,
-which must be taken into account by programs which can work with all
-termcap library interfaces.
+Later
+(in mid-1996)
+the \fB\%tparam\fP function was removed from \fI\%ncurses\fP.
+Any two of the four implementations thus differ,
+and programs that intend to work with all \fItermcap\fP library
+interfaces must account for that fact.
.SH BUGS
If you call \fB\%tgetstr\fP to fetch \fB\%ca\fP or any other
parameterized string capability,
-be aware that it is returned in \fI\%terminfo\fP notation,
-not the older and not-quite-compatible \fI\%termcap\fP notation.
+be aware that it is returned in \fI\%term\%info\fP notation,
+not the older and not-quite-compatible \fItermcap\fP notation.
This does not cause problems if all you do with it is call \fB\%tgoto\fP
-or \fB\%tparm\fP, which both expand
-\fI\%terminfo\fP-style strings as \fI\%terminfo\fP does.
-(The \fB\%tgoto\fP function,
-if configured to support \fI\%termcap,\fP
-checks if the string is indeed \fI\%terminfo\fP-style by looking for
-\*(``\fB%p\fP\*('' parameters or \*(``\fB<\fP.\|.\|.\fB>\fP\*('' delays,
-and invokes a \fI\%termcap\fP-style parser if the string appears not to
-use \fI\%terminfo\fP syntax.)
+or \fB\%tparm\fP,
+which both expand \fI\%term\%info\fP-style strings as \fI\%term\%info\fP
+does.
+(If
+.I \%ncurses
+is configured to support \fItermcap,\fP
+\fB\%tgoto\fP checks whether the string is \fI\%term\%info\fP-style by
+looking for \*(``\fB%p\fP\*('' parameters or
+\*(``\fB<\fP.\|.\|.\fB>\fP\*('' delays,
+and invokes a \fItermcap\fP-style parser if the string appears not to
+use \fI\%term\%info\fP syntax.)
.PP
-Because \fI\%terminfo\fP's syntax for padding in string capabilities
-differs from \fI\%termcap\fP's,
+Because \fI\%term\%info\fP's syntax for padding in string capabilities
+differs from \fItermcap\fP's,
users can be surprised.
.IP \(bu 4
-\fB\%tputs("50")\fP in a \fI\%terminfo\fP system transmits \*(``50\*(''
-rather than busy-waiting for 50 milliseconds.
+\fB\%tputs("50")\fP in a \fI\%term\%info\fP system transmits
+\*(``50\*('' rather than busy-waiting for 50 milliseconds.
.IP \(bu 4
However,
-if \fI\%ncurses\fP is configured to support \fI\%termcap\fP,
+if \fI\%ncurses\fP is configured to support \fItermcap\fP,
it may also have been configured to support BSD-style padding.
.IP
In that case,
\fB\%tputs\fP inspects strings passed to it,
looking for digits at the beginning of the string.
.IP
-\fB\%tputs("50")\fP in a \fI\%termcap\fP system may busy-wait for 50
+\fB\%tputs("50")\fP in a \fItermcap\fP system may busy-wait for 50
milliseconds rather than transmitting \*(``50\*(''.
.PP
-\fI\%termcap\fP has nothing analogous to \fI\%terminfo\fP's \fBsgr\fP
+\fItermcap\fP has nothing analogous to \fI\%term\%info\fP's \fBsgr\fP
string.
-One consequence is that \fI\%termcap\fP applications assume that
-\fBme\fP
-(equivalent to \fI\%terminfo\fP's \fBsgr0\fP capability)
+One consequence is that \fItermcap\fP applications assume that
+.RB \*(`` me \*(''
+(equivalent to \fI\%term\%info\fP's \fBsgr0\fP capability)
does not reset the alternate character set.
\fI\%ncurses\fP checks for,
and modifies the data shared with,
-the \fI\%termcap\fP interface to accommodate the latter's limitation in
+the \fItermcap\fP interface to accommodate the latter's limitation in
this respect.
-.SH SEE ALSO
+.SH "SEE ALSO"
\fB\%curses\fP(3X),
+\fB\%curs_terminfo\fP(3X),
\fB\%putc\fP(3),
\fB\%term_variables\fP(3X),
\fB\%terminfo\fP(5)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_terminfo.3x,v 1.122 2023/12/03 00:10:20 tom Exp $
-.TH curs_terminfo 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_terminfo.3x,v 1.123 2023/12/16 21:11:53 tom Exp $
+.TH curs_terminfo 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint del_curterm(TERMINAL *\fIoterm\fP);
\fBint restartterm(const char *\fIterm\fP, int \fIfiledes\fP, int *\fIerrret\fP);
.PP
-\fBchar *tparm(const char *\fIstr\fP, ...);
- \fIor
-\fBchar *tparm(const char *\fIstr\fP, long \fIp1 ... \fPlong \fIp9\fP);
+\fBchar *tparm(const char *\fIstr\fP, \fR.\|.\|.\fP);
+ \fI/* or */
+\fBchar *tparm(const char *\fIstr\fP, long \fIp1\fP \fR.\|.\|.\fP \fBlong\fP \fIp9\fP);
.PP
\fBint tputs(const char *\fIstr\fP, int \fIaffcnt\fP, int (*\fIputc\fP)(int));
\fBint putp(const char *\fIstr\fP);
\fBint tigetnum(const char *\fIcapname\fP);
\fBchar *tigetstr(const char *\fIcapname\fP);
.PP
-\fBchar *tiparm(const char *\fIstr\fP, ...);
+\fBchar *tiparm(const char *\fIstr\fP, \fR.\|.\|.\fP);
.PP
\fI/* extensions */
\fBchar *tiparm_s(int \fIexpected\fP, int \fImask\fP, const char *\fIstr\fP, ...);
which uses all the defaults and sends the output to \fBstdout\fP.
.RE
.\" ***************************************************************************
-.SS The Terminal State
+.SS "The Terminal State"
The \fBsetupterm\fP routine stores its information about the terminal
in a \fBTERMINAL\fP structure pointed to by the global variable \fBcur_term\fP.
If it detects an error,
Accordingly, \fBrestartterm\fP saves various tty state bits,
calls \fBsetupterm\fP, and then restores the bits.
.\" ***************************************************************************
-.SS Formatting Output
+.SS "Formatting Output"
The \fBtparm\fP routine instantiates the string \fIstr\fP with
parameters \fIpi\fP. A pointer is returned to the result of \fIstr\fP
with the parameters applied.
The extension \fBtiscan_s\fP allows the application
to inspect a formatting capability to see what the curses library would assume.
.\" ***************************************************************************
-.SS Output Functions
+.SS "Output Functions"
String capabilities can contain padding information,
a time delay
(accommodating performance limitations of hardware terminals)
.bP
\fIattrs\fP of type \fBattr_t\fP for the attributes and
.bP
-\fIpair\fP of type \fBshort\fP for the color-pair number.
+\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.
they are declared in \fB\%<curses.h>\fP because System\ V did this
(see \fIHISTORY\fP).
.\" ***************************************************************************
-.SS Terminal Capability Functions
+.SS "Terminal Capability Functions"
The \fBtigetflag\fP, \fBtigetnum\fP and \fBtigetstr\fP routines return
the value of the capability corresponding to the \fBterminfo\fP
\fIcapname\fP passed to them, such as \fBxenl\fP.
\fB0\fP
if it is canceled or absent from the terminal description.
.\" ***************************************************************************
-.SS Terminal Capability Names
+.SS "Terminal Capability Names"
These null-terminated arrays contain
.bP
the short \fIterminfo\fP names (\*(``codes\*(''),
.fi
.RE
.\" ***************************************************************************
-.SS Releasing Memory
+.SS "Releasing Memory"
Each successful call to \fBsetupterm\fP allocates memory to hold the terminal
description.
As a side-effect, it sets \fBcur_term\fP to point to this memory.
allocated by \fBsetupterm\fP:
.bP
the \*(``static\*('' terminfo variables [a-z].
-Before ncurses 6.3, those were shared by all screens.
-With ncurses 6.3, those are allocated per screen.
+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.
.bP
-to improve performance, ncurses 6.3 caches the result of analyzing terminfo
+to improve performance,
+\fI\%ncurses\fP 6.3 caches the result of analyzing terminfo
strings for their parameter types.
That is stored as a binary tree referenced from the \fBTERMINAL\fP structure.
.PP
X/Open notes that \fBvidattr\fP and \fBvidputs\fP may be macros.
.\" ***************************************************************************
.SH EXTENSIONS
-The functions marked as extensions were designed for \fBncurses\fP(3X),
+The functions marked as extensions were designed for
+\fB\%ncurses\fP(3X),
and are not found in SVr4 curses, 4.4BSD curses,
or any other previous version of curses.
.\" ***************************************************************************
The function \fBsetterm\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
+.SS "Compatibility Macros"
This implementation provides a few macros for compatibility with systems
before SVr4 (see \fIHISTORY\fP).
Those include
and is not recommended for new programs.
This implementation provides each of those symbols
as macros for BSD compatibility.
-.SS Legacy data
+.SS "Legacy Data"
\fBsetupterm\fP copies the terminal name to the array \fBttytype\fP.
This is not part of X/Open Curses, but is assumed by some applications.
.PP
.PP
Extended terminal capability names, e.g., as defined by \fB@TIC@\ \-x\fP,
are not stored in the arrays described here.
-.SS Output buffering
-Older versions of \fBncurses\fP assumed that the file descriptor passed to
-\fBsetupterm\fP from \fBinitscr\fP or \fBnewterm\fP uses buffered I/O,
+.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
+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 \fBncurses\fP
+it was problematic because \fI\%ncurses\fP
did not allow a reliable way to cleanup on receiving SIGTSTP.
.PP
The current version (ncurses6)
-uses output buffers managed directly by \fBncurses\fP.
+uses output buffers managed directly by \fI\%ncurses\fP.
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 \fBncurses\fP use
+The high-level functions in \fI\%ncurses\fP use
alternate versions of these functions
using the more reliable buffering scheme.
-.SS Function prototypes
+.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.
.IP
As an extension, this implementation can be configured to change the
function prototypes to use the \fBconst\fP keyword.
-The \fIncurses\fP ABI 6 enables this feature by default.
+The \fI\%ncurses\fP ABI 6 enables this feature by default.
.bP
X/Open Curses prototypes \fBtparm\fP with a fixed number of parameters,
rather than a variable argument list.
In response to review comments by Thomas E. Dickey,
X/Open Curses Issue 7 proposed the \fBtiparm\fP function in mid-2009.
.IP
-While \fBtiparm\fP is always provided in ncurses,
+While \fBtiparm\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.
.PP
However, only a few terminfo capabilities use string parameters
(e.g., the ones used for programmable function keys).
.IP
-The ncurses library checks usage of these capabilities,
+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.
.IP
The \fB@TPUT@\fR(1) program checks its use of these capabilities with a table,
so that it calls \fBtparm\fP correctly.
-.SS Special TERM treatment
+.SS "Special \fITERM\fP treatment"
If configured to use the terminal-driver,
e.g., for the MinGW port,
.bP
\fBsetupterm\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
+.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.
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
the window before resuming normal curses calls.
-Both \fBncurses\fP and System V Release 4 curses implement \fBmvcur\fP using
-the SCREEN data allocated in either \fBinitscr\fP or \fBnewterm\fP.
+Both \fI\%ncurses\fP and System V Release 4 curses implement \fBmvcur\fP
+using the SCREEN data allocated in either \fBinitscr\fP or
+\fBnewterm\fP.
So though it is documented as a terminfo function,
\fBmvcur\fP is really a curses function which is not well specified.
.PP
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_threads.3x,v 1.49 2023/11/25 14:09:12 tom Exp $
-.TH curs_threads 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_threads.3x,v 1.50 2023/12/16 20:32:22 tom Exp $
+.TH curs_threads 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint use_window(WINDOW *\fIwin\fP, NCURSES_WINDOW_CB \fIfunc\fP, void *\fIdata\fP);
.fi
.SH DESCRIPTION
-The \fIncurses\fP library can be configured to support multi-threaded
+The \fI\%ncurses\fP library can be configured to support multi-threaded
applications in a rudimentary way.
Such configuration produces a different set of libraries,
named \fIlibncursest\fP,
for example,
-since doing so alters \fIncurses\fP's application binary interface
+since doing so alters \fI\%ncurses\fP's application binary interface
(ABI).
.PP
Instead of modifying the programming interface (API) to make
-\fIncurses\fP functions expect an additional argument specifying a
+\fI\%ncurses\fP functions expect an additional argument specifying a
thread,
the library adds functions,
usable in any configuration,
needed to prevent concurrent access to variables shared by multiple
threads of execution.
.PP
-\fIncurses\fP threading support requires the use of functions to access
-members of the \fI\%WINDOW\fP structure (see \fBcurs_opaque\fP(3X)).
+\fI\%ncurses\fP threading support requires the use of functions to
+access members of the \fI\%WINDOW\fP structure (see
+\fBcurs_opaque\fP(3X)).
It further makes functions of the common global variables
\fB\%COLORS\fP,
\fB\%COLOR_PAIRS\fP,
and return the value from the user-supplied function to the application.
.\" ***************************************************************************
.SS Usage
-All \fIncurses\fP library functions assume that the locale is not
+All \fI\%ncurses\fP library functions assume that the locale is not
altered during operation.
In addition,
they use data that is maintained within a hierarchy of scopes.
reentrant data associated with \*(``pure\*('' functions that alter no
shared variables
.PP
-The following table lists the scope of each symbol in the \fIncurses\fP
-library when configured to support multi-threaded applications.
+The following table lists the scope of each symbol in the
+\fI\%ncurses\fP library when configured to support multi-threaded
+applications.
.PP
.TS
center tab(/);
\fB\%use_screen\fP and \fB\%use_window\fP return the \fIint\fP returned
by the user-supplied function they are called with.
.SH NOTES
-\fIncurses\fP provides both a C function and a preprocessor macro for
+\fI\%ncurses\fP provides both a C function and a preprocessor macro for
each function documented in this page.
.SH PORTABILITY
-These routines are specific to \fIncurses\fP.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on Version 7, BSD or System V implementations.
-It is recommended that any code depending on \fIncurses\fP extensions
+It is recommended that any code depending on \fI\%ncurses\fP extensions
be conditioned using \fB\%NCURSES_VERSION\fP.
.SH SEE ALSO
\fB\%curses\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_trace.3x,v 1.40 2023/10/07 21:19:07 tom Exp $
-.TH curs_trace 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_trace.3x,v 1.41 2023/12/16 20:50:14 tom Exp $
+.TH curs_trace 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBvoid trace(const unsigned int \fIparam\fP);
.fi
.SH DESCRIPTION
-The \fIcurses trace\fP routines are used for debugging the ncurses libraries,
-as well as applications which use the ncurses libraries.
+The \fIcurses trace\fP routines are used for debugging the
+\fI\%ncurses\fP libraries,
+as well as applications which use the \fI\%ncurses\fP libraries.
Some limitations apply:
.bP
Aside from \fBcurses_trace\fP,
and returns the previous trace mask.
.IP
When the trace mask is nonzero,
-ncurses creates the file \*(``trace\*('' in the current directory for output.
+\fI\%ncurses\fP creates the file \*(``trace\*('' in the current directory for output.
If the file already exists, no tracing is done.
.bP
If tracing is not available, \fBcurses_trace\fP returns zero (0).
Some features overlap.
The specific names are used as a guideline.
.SS Initialization
-These functions check the \fBNCURSES_TRACE\fP environment variable,
+These functions check the \fI\%NCURSES_TRACE\fP environment variable,
to set the tracing feature as if \fBcurses_trace\fP was called:
.RS 4
.PP
Because the command-line utilities may call initialization functions
such as \fBsetupterm\fP, \fBtgetent\fP or \fBuse_extended_names\fP,
some of their debugging output may be directed to the \fItrace\fP file
-if the \fBNCURSES_TRACE\fP environment variable is set:
+if the \fI\%NCURSES_TRACE\fP environment variable is set:
.bP
messages produced in the utility are written to the standard error.
.bP
messages produced by the underlying library are written to \fItrace\fP.
.PP
-If ncurses is built without tracing, none of the latter are produced,
+If \fI\%ncurses\fP is built without tracing,
+none of the latter are produced,
and fewer diagnostics are provided by the command-line utilities.
.SH RETURN VALUE
Routines which return a value are designed to be used as parameters
These functions are not part of the XSI interface.
Some other curses implementations are known to
have similar features,
-but they are not compatible with ncurses:
+but they are not compatible with \fI\%ncurses\fP:
.bP
SVr4 provided \fBtraceon\fP and \fBtraceoff\fP,
to control whether debugging information was written
.IP
PDCurses has a short description of these functions,
with a note that they are not present in X/Open Curses,
-ncurses or NetBSD.
+\fI\%ncurses\fP or NetBSD.
It does not mention SVr4,
but the functions' inclusion in a header file section
labeled \*(``Quasi-standard\*('' hints at the origin.
.bP
NetBSD does not provide functions for enabling/disabling traces.
It uses environment variables
-\fBCURSES_TRACE_MASK\fP and
-\fBCURSES_TRACE_FILE\fP to determine what is traced,
+\fI\%CURSES_TRACE_MASK\fP and
+\fI\%CURSES_TRACE_FILE\fP to determine what is traced,
and where the results are written.
This is available only when a debug-library is built.
.IP
The NetBSD tracing feature is undocumented.
.PP
-A few ncurses functions are not provided when symbol versioning is used:
+A few \fI\%ncurses\fP functions are not provided when symbol versioning
+is used:
.RS 4
.PP
_nc_tracebits,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_util.3x,v 1.90 2023/12/02 21:10:36 tom Exp $
-.TH curs_util 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_util.3x,v 1.91 2023/12/16 20:32:22 tom Exp $
+.TH curs_util 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
should be called before \fBinitscr\fP or
\fBnewterm\fP are called
(because those compute the screen size).
-It modifies the way \fIncurses\fP treats environment variables
+It modifies the way \fI\%ncurses\fP treats environment variables
when determining the screen size.
.bP
-Normally \fIncurses\fP looks first at the terminal database for the screen size.
+Normally \fI\%ncurses\fP looks first at the terminal database for the
+screen size.
.IP
If \fBuse_env\fP was called with \fBFALSE\fP for parameter,
it stops here unless
it overrides the values from the terminal database.
.bP
Finally (unless \fBuse_env\fP was called with \fBFALSE\fP parameter),
-\fBncurses\fP examines the \fILINES\fP or \fI\%COLUMNS\fP environment
+\fI\%ncurses\fP examines the \fILINES\fP or \fI\%COLUMNS\fP environment
variables,
using a value in those to override the results
from the operating system or terminal database.
.IP
-\fBNcurses\fP also updates the screen size in response to \fBSIGWINCH\fP,
+\fI\%curses\fP also updates the screen size in response to
+\fBSIGWINCH\fP,
unless overridden by the \fILINES\fP or \fI\%COLUMNS\fP environment
variables,
.SS use_tioctl
should be called before \fBinitscr\fP or \fBnewterm\fP are called
(because those compute the screen size).
After \fBuse_tioctl\fP is called with \fBTRUE\fP as an argument,
-\fBncurses\fP modifies the last step in its computation
+\fI\%ncurses\fP modifies the last step in its computation
of screen size as follows:
.bP
checks if the \fILINES\fP and \fI\%COLUMNS\fP environment variables
are set to a number greater than zero.
.bP
-for each, \fBncurses\fP updates the corresponding environment variable
+for each, \fI\%ncurses\fP updates the corresponding environment variable
with the value that it has obtained via operating system call
or from the terminal database.
.bP
-\fBncurses\fP re-fetches the value of the environment variables so that
-it is still the environment variables which set the screen size.
+\fI\%ncurses\fP re-fetches the value of the environment variables so
+that it is still the environment variables which set the screen size.
.PP
The \fB\%use_env\fP and \fB\%use_tioctl\fP routines combine as follows.
.IP
_
TRUE FALSE T{
This is the default behavior.
-\fIncurses\fP uses operating system calls
+\fI\%ncurses\fP uses operating system calls
unless overridden by \fILINES\fP or \fI\%COLUMNS\fP environment
variables;
default.
T}
TRUE TRUE T{
-\fIncurses\fP updates \fILINES\fP and \fI\%COLUMNS\fP based on operating
-system calls.
+\fI\%ncurses\fP updates \fILINES\fP and \fI\%COLUMNS\fP based on
+operating system calls.
T}
FALSE TRUE T{
-\fIncurses\fP ignores \fILINES\fP and \fI\%COLUMNS\fP,
+\fI\%ncurses\fP ignores \fILINES\fP and \fI\%COLUMNS\fP,
using operating system calls to obtain size.
T}
.TE
.bP
the data written is a copy of the \fBWINDOW\fP structure,
and its associated character cells.
-The format differs between the wide-character (\fBncursesw\fP) and
-non-wide (\fBncurses\fP) libraries.
+The format differs between the wide-character (\fI\%ncursesw\fP) and
+non-wide (\fI\%ncurses\fP) libraries.
You can transfer data between the two, however.
.bP
the retrieved window is always created as a top-level window (or pad),
The \fBdelay_output\fP routine inserts an \fIms\fP millisecond pause
in output.
Employ this function judiciously when terminal output uses padding,
-because \fIncurses\fP transmits null characters
+because \fI\%ncurses\fP transmits null characters
(consuming CPU and I/O resources)
instead of sleeping and requesting resumption from the operating system.
Padding is used unless:
the environment variable \fB\%NCURSES_NO_PADDING\fP is set.
.PP
If padding is not in use,
-\fIncurses\fP uses \fBnapms\fP to perform the delay.
+\fI\%ncurses\fP uses \fBnapms\fP to perform the delay.
If the value of \fIms\fP exceeds 30,000
(thirty seconds),
it is capped at that value.
The \fBuse_extended_names\fP(3X) function controls whether this data is
loaded when the terminal description is read by the library.
.SS nofilter/use_tioctl
-The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to \fBncurses\fP.
+The \fBnofilter\fP and \fBuse_tioctl\fP routines are specific to
+\fI\%ncurses\fP.
They were not supported on Version 7, BSD or System V implementations.
-It is recommended that any code depending on \fBncurses\fP extensions
+It is recommended that any code depending on \fI\%ncurses\fP extensions
be conditioned using \fBNCURSES_VERSION\fP.
.SS putwin/getwin file-format
The \fBputwin\fP and \fBgetwin\fP functions have several issues with
.bP
Most implementations simply dump the binary \fBWINDOW\fP structure to the file.
These include SVr4 curses, NetBSD and PDCurses,
-as well as older \fBncurses\fP versions.
+as well as older \fI\%ncurses\fP versions.
This implementation
(as well as the X/Open variant of Solaris curses, dated 1995)
uses textual dumps.
this implementation returns strings \*(``M\-^@\*('', \*(``M\-^A\*('', etc.
.PP
X/Open Curses documents \fBunctrl\fP as declared in \fB<unctrl.h>\fP,
-which \fBncurses\fP does.
-However, \fBncurses\fP' \fB<curses.h>\fP includes \fB<unctrl.h>\fP,
+which \fI\%ncurses\fP does.
+However, \fI\%ncurses\fP' \fB<curses.h>\fP includes \fB<unctrl.h>\fP,
matching the behavior of SVr4 curses.
Other implementations may not do that.
.SS use_env/use_tioctl
-If \fBncurses\fP is configured to provide the sp-functions extension,
+If \fI\%ncurses\fP is configured to provide the sp-functions extension,
the state of \fBuse_env\fP and \fBuse_tioctl\fP may be updated before
creating each \fIscreen\fP rather than once only
(\fBcurs_sp_funcs\fP(3X)).
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_variables.3x,v 1.34 2023/11/25 14:32:36 tom Exp $
-.TH curs_variables 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_variables.3x,v 1.35 2023/12/16 21:05:52 tom Exp $
+.TH curs_variables 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint COLOR_PAIRS;
\fBint COLORS;
\fBint COLS;
-\fBint ESCDELAY;
\fBint LINES;
-\fBint TABSIZE;
\fBWINDOW * curscr;
-\fBWINDOW * newscr;
\fBWINDOW * stdscr;
+\fI/* extensions */
+\fBint ESCDELAY;
+\fBint TABSIZE;
+\fBWINDOW * newscr;
.fi
.SH DESCRIPTION
This page summarizes data types,
and variables provided by the \fIcurses\fP library.
Locate further discussion in \fB\%curses\fP(3X).
.PP
-Depending on \fIncurses\fP's build-time configuration,
+Depending on \fI\%ncurses\fP's build-time configuration,
the variables may instead be
macros (see \fB\%curs_threads\fP(3X) and \fB\%curs_opaque\fP(3X))
that provide read-only access to the library's state.
In either case,
applications should treat them as read-only to avoid
confusing the library.
-.SS bool, TRUE, FALSE
+.SS \fIbool\fP, TRUE, FALSE
X/Open Issue 4 \fIcurses\fP (1996) preceded the ISO C99 and ISO C++98
standards,
each of which also defined a Boolean data type.
\fIcurses\fP and \fIterminfo\fP routines frequently return these
constant integral values indicating failure and success,
respectively.
-.SS chtype
+.SS \fIchtype\fP
The \fI\%chtype\fP integral type combines a
(\*(``narrow\*('',
8-bit)
\fB\%attron\fP(3X),
and
\fB\%inch\fP(3X).
-.SS cchar_t, attr_t
+.SS \fIcchar_t\fP, \fIattr_t\fP
\fI\%chtype\fP is too small for the standard C library's wide-character
type,
\fIwchar_t\fP.
\fB\%curs_refresh\fP(3X) and
\fB\%curs_outopts\fP(3X).
.SS newscr
-\fIncurses\fP collects pending updates to the terminal screen in a
+\fI\%ncurses\fP collects pending updates to the terminal screen in a
\fI\%WINDOW\fP structure named \fB\%newscr\fP.
.PP
This object is referred to as the \*(``virtual screen\*('' in the
Either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) initializes
\fIcurses\fP.
.PP
-If \fIncurses\fP is configured to provide separate \fIcurses\fP and
+If \fI\%ncurses\fP is configured to provide separate \fIcurses\fP and
\fIterminfo\fP libraries,
most of these variables reside in the \fIcurses\fP library.
.SH PORTABILITY
the virtual screen with \fB\%addch\fP(3X) and
the physical screen with \fB\%mvcur\fP(3X).
.bP
-\fIncurses\fP uses the value of \fB\%TABSIZE\fP only to update the
+\fI\%ncurses\fP uses the value of \fB\%TABSIZE\fP only to update the
virtual screen.
It uses the terminal description's \*(``\fBit\fP\*(''
(\fB\%init_tabs\fP) capability for computing hardware tabs
For instance,
NetBSD \fIcurses\fP allows \fB\%TABSIZE\fP to be set through an
environment variable.
-\fIncurses\fP does not.
+\fI\%ncurses\fP does not.
.IP
NetBSD \fIcurses\fP does not support hardware tabs;
it uses the \fB\%init_tabs\fP capability and the \fB\%TABSIZE\fP
The default value for AIX's \fB\%ESCDELAY\fP equals 0.1 seconds.
.bP
AIX also enforces a limit of 10,000 seconds for \fB\%ESCDELAY\fP;
-\fIncurses\fP does not enforce any upper limit.
+\fI\%ncurses\fP does not enforce any upper limit.
.PP
-\fIncurses\fP has long used \fB\%ESCDELAY\fP with units of milliseconds,
+\fI\%ncurses\fP has long used \fB\%ESCDELAY\fP with units of
+milliseconds,
making it impossible to be completely compatible with AIX.
Consequently,
most users have decided either to override the value,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_window.3x,v 1.43 2023/11/25 14:17:29 tom Exp $
-.TH curs_window 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: curs_window.3x,v 1.44 2023/12/16 20:32:22 tom Exp $
+.TH curs_window 3X 2023-12-16 "ncurses 6.4" "Library calls"
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
Solaris X/Open curses does not even make that check,
and will delete a parent window which still has subwindows.
.bP
-Since release 4.0 (1996), ncurses maintains a list of windows for each screen,
+Since release 4.0 (1996),
+\fI\%ncurses\fP maintains a list of windows for each screen,
to ensure that a window has no subwindows before allowing deletion.
.bP
-NetBSD copied this feature of ncurses in 2003.
+NetBSD copied this feature of \fI\%ncurses\fP in 2003.
.br
PDCurses follows the scheme used in Solaris X/Open curses.
.SH BUGS
.\"
.\" Author: Thomas E. Dickey 1997,1999,2000,2005
.\"
-.\" $Id: default_colors.3x,v 1.47 2023/11/25 14:26:30 tom Exp $
-.TH default_colors 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: default_colors.3x,v 1.48 2023/12/16 20:32:22 tom Exp $
+.TH default_colors 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.I assume_default_colors(\-1,\-1);
.RE
.PP
-These are ncurses extensions.
+These are \fI\%ncurses\fP extensions.
For other curses implementations, color
-number \-1 does not mean anything, just as for ncurses before a
+number \-1 does not mean anything, just as for \fI\%ncurses\fP before a
successful call of \fBuse_default_colors\fP or \fBassume_default_colors\fP.
.PP
Other curses implementations do not allow an application to modify color pair 0.
.B use_default_colors
or
.B assume_default_colors
-ncurses will paint a white foreground (text) with black background
+\fI\%ncurses\fP will paint a white foreground (text) with black background
for color pair 0.
.SH RETURN VALUE
These functions return the integer \fBERR\fP upon failure
environment variables and other configuration to bypass curses'
notion of the terminal's default colors, setting specific values.
.SH PORTABILITY
-These routines are specific to ncurses.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on
Version 7, BSD or System V implementations.
It is recommended that
.\"
.\" Author: Thomas E. Dickey 1997
.\"
-.\" $Id: define_key.3x,v 1.39 2023/11/25 14:26:30 tom Exp $
-.TH define_key 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: define_key.3x,v 1.40 2023/12/16 20:32:22 tom Exp $
+.TH define_key 3X 2023-12-16 "ncurses 6.4" "Library calls"
.SH NAME
\fB\%define_key\fP \-
define a \fIcurses\fR keycode
.SH DESCRIPTION
This is an extension to the \fIcurses\fP library.
It permits an application to define keycodes with their corresponding control
-strings, so that the \fIncurses\fP library will interpret them just as it would
+strings,
+so that the \fI\%ncurses\fP library will interpret them just as it would
the predefined codes in the terminfo database.
.PP
If \fIdefinition\fP is \fBNULL\fP,
data to store the definition.
If no error is detected, \fBOK\fP is returned.
.SH PORTABILITY
-These routines are specific to \fIncurses\fP.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on
Version 7, BSD or System V implementations.
It is recommended that
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form.3x,v 1.50 2023/11/25 13:59:44 tom Exp $
-.TH form 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: form.3x,v 1.51 2023/12/16 20:32:22 tom Exp $
+.TH form 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
The following table lists each \fBform\fP routine and the name of
the manual page on which it is described.
Routines flagged with \*(``*\*(''
-are ncurses-specific, not present in SVr4.
+are \fI\%ncurses\fP-specific, not present in SVr4.
.PP
.TS
l l
.PP
It is not part of X/Open Curses.
.PP
-Aside from ncurses, there are few implementations:
+Aside from \fI\%ncurses\fP, there are few implementations:
.bP
systems based on SVr4 source code, e.g., Solaris.
.bP
NetBSD curses.
.PP
-A few functions in this implementation are extensions added for ncurses,
+A few functions in this implementation are extensions added for
+\fI\%ncurses\fP,
but not provided by other implementations, e.g.,
\fBform_driver_w\fP,
\fBunfocus_current_field\fP.
.SH AUTHORS
Juergen Pfeifer.
-Manual pages and adaptation for ncurses by Eric
+Manual pages and adaptation for \fI\%ncurses\fP by Eric
S. Raymond.
.SH SEE ALSO
\fBcurses\fP(3X) and related pages whose names begin \*(``form_\*('' for
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_buffer.3x,v 1.42 2023/11/25 13:58:47 tom Exp $
-.TH form_field_buffer 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: form_field_buffer.3x,v 1.43 2023/12/16 20:32:22 tom Exp $
+.TH form_field_buffer 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
They were not supported on
Version 7 or BSD versions.
.PP
-The \fBset_max_field\fP function checks for an ncurses extension
+The \fBset_max_field\fP function checks for an \fI\%ncurses\fP extension
\fBO_INPUT_FIELD\fP which allows a dynamic field to shrink if the new
limit is smaller than the current field size.
.SH AUTHORS
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_field_validation.3x,v 1.50 2023/11/25 13:58:47 tom Exp $
-.TH form_field_validation 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: form_field_validation.3x,v 1.51 2023/12/16 20:32:22 tom Exp $
+.TH form_field_validation 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
Trailing blanks in the buffer are ignored.
The address itself is not validated.
.PP
-This is an ncurses extension;
+This is an \fI\%ncurses\fP extension;
this field type may not be available in other curses implementations.
.SH RETURN VALUE
The functions \fBfield_type\fP and \fBfield_arg\fP return \fBNULL\fP on error.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_page.3x,v 1.34 2023/11/25 13:58:47 tom Exp $
-.TH form_page 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: form_page.3x,v 1.35 2023/12/16 20:32:22 tom Exp $
+.TH form_page 3X 2023-12-16 "ncurses 6.4" "Library calls"
.SH NAME
\fBform_page\fP \-
set and get form page number
They were not supported on
Version 7 or BSD versions.
.PP
-The \fBunfocus_current_field\fP function is an ncurses extension.
+The \fBunfocus_current_field\fP function is an \fI\%ncurses\fP
+extension.
.SH AUTHORS
Juergen Pfeifer.
Manual pages and adaptation for new curses by Eric S. Raymond.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: form_requestname.3x,v 1.32 2023/11/25 13:58:47 tom Exp $
-.TH form_requestname 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: form_requestname.3x,v 1.33 2023/12/16 20:32:22 tom Exp $
+.TH form_requestname 3X 2023-12-16 "ncurses 6.4" "Library calls"
.SH NAME
\fBform_request_by_name\fP,
\fBform_request_name\fP \-
\fBform_request_by_name\fP returns \fBE_NO_MATCH\fP on error.
It does not set \fBerrno\fP.
.SH PORTABILITY
-These routines are specific to ncurses.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on
Version 7, BSD or System V implementations.
It is recommended that
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: infocmp.1m,v 1.101 2023/12/02 20:49:04 tom Exp $
-.TH @INFOCMP@ 1M 2023-12-02 "ncurses 6.4" "User commands"
+.\" $Id: infocmp.1m,v 1.102 2023/12/16 20:32:22 tom Exp $
+.TH @INFOCMP@ 1M 2023-12-16 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB@INFOCMP@\fP will flag any other \fIterminal-type use=\fP fields that
were not needed.
.SS Changing Databases [\-A \fIdirectory\fR] [\-B \fIdirectory\fR]
-Like other \fBncurses\fP utilities,
+Like other \fI\%ncurses\fP utilities,
\fB@INFOCMP@\fP looks for the terminal descriptions in several places.
You can use the \fI\%TERMINFO\fP and \fI\%TERMINFO_DIRS\fP environment
variables to override the compiled-in default list of places to search.
The tables are all declared static, and are named according to the type
and the name of the corresponding terminal entry.
.sp
-Before ncurses 5.0, the split between the \fB\-e\fP and \fB\-E\fP
-options was not needed; but support for extended names required making
-the arrays of terminal capabilities separate from the TERMTYPE structure.
+Before \fI\%ncurses\fP 5.0,
+the split between the \fB\-e\fP and \fB\-E\fP options was not needed;
+but support for extended names required making the arrays of terminal
+capabilities separate from the TERMTYPE structure.
.TP 5
\fB\-e\fP
Dump the capabilities of the given terminal as a C initializer for a
data.
.TP 5
\fB\-V\fP
-reports the version of ncurses which was used in this program, and exits.
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
.TP 5
\fB\-v\fP \fIn\fP
prints out tracing information on standard error as the program runs.
.IP
The optional parameter \fIn\fP is a number from 1 to 10, inclusive,
indicating the desired level of detail of information.
-If ncurses is built without tracing support, the optional parameter is ignored.
+If \fI\%ncurses\fP is built without tracing support,
+the optional parameter is ignored.
.TP
\fB\-W\fP
By itself, the \fB\-w\fP option will not force long strings to be wrapped.
for System V Release 3.
.PP
Eric Raymond used the AT&T documentation in 1995 to provide an equivalent
-\fB@INFOCMP@\fP for ncurses.
+\fB@INFOCMP@\fP for \fI\%ncurses\fP.
In addition, he added a few new features such as:
.bP
the \fB\-e\fP option, to support \fIfallback\fP
For a complete list, see the \fIEXTENSIONS\fP section.
.PP
In 2010, Roy Marples provided an \fBinfocmp\fP program for NetBSD.
-It is less capable than the SVr4 or ncurses versions
+It is less capable than the SVr4 or \fI\%ncurses\fP versions
(e.g., it lacks the sorting options documented in X/Open),
-but does include the \fB\-x\fP option adapted from ncurses.
+but does include the \fB\-x\fP option adapted from \fI\%ncurses\fP.
.SH BUGS
The \fB\-F\fP option of \fB\%@INFOCMP@\fP(1M) should be a
\fB\%@TOE@\fP(1M) mode.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: infotocap.1m,v 1.37 2023/11/25 14:32:36 tom Exp $
-.TH @INFOTOCAP@ 1M 2023-11-25 "ncurses 6.4" "User commands"
+.\" $Id: infotocap.1m,v 1.39 2023/12/10 14:12:43 tom Exp $
+.TH @INFOTOCAP@ 1M 2023-12-10 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.ds d @TERMINFO@
.SH NAME
\fB\%@INFOTOCAP@\fP \-
-convert a \fI\%terminfo\fR description into a \fI\%termcap\fR
-description
+convert a \fI\%terminfo\fR description into a \fI\%termcap\fR description
.SH SYNOPSIS
.B @INFOTOCAP@
.RI [ tic-option ]
.\"
.\" Author: Thomas E. Dickey 2003
.\"
-.\" $Id: key_defined.3x,v 1.31 2023/11/25 14:26:30 tom Exp $
-.TH key_defined 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: key_defined.3x,v 1.32 2023/12/16 20:32:22 tom Exp $
+.TH key_defined 3X 2023-12-16 "ncurses 6.4" "Library calls"
.SH NAME
\fB\%key_defined\fP \-
test whether a \fIcurses\fR keycode is defined
If the string conflicts with longer strings
which are bound to keys, \-1 is returned.
.SH PORTABILITY
-This routine is specific to \fIncurses\fP.
+This routine is specific to \fI\%ncurses\fP.
It was not supported on
Version 7, BSD or System V implementations.
It is recommended that
.\"
.\" Author: Thomas E. Dickey 1999
.\"
-.\" $Id: keybound.3x,v 1.33 2023/11/25 14:26:30 tom Exp $
-.TH keybound 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: keybound.3x,v 1.34 2023/12/16 20:32:22 tom Exp $
+.TH keybound 3X 2023-12-16 "ncurses 6.4" "Library calls"
.SH NAME
\fB\%keybound\fP \-
get definition of \fIcurses\fR keycode
When successful,
the function returns a string which must be freed by the caller.
.SH PORTABILITY
-This routine is specific to \fIncurses\fP.
+This routine is specific to \fI\%ncurses\fP.
It was not supported on
Version 7, BSD or System V implementations.
It is recommended that
.\"
.\" Author: Thomas E. Dickey 1997
.\"
-.\" $Id: keyok.3x,v 1.37 2023/11/25 14:26:30 tom Exp $
-.TH keyok 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: keyok.3x,v 1.38 2023/12/16 20:32:22 tom Exp $
+.TH keyok 3X 2023-12-16 "ncurses 6.4" "Library calls"
.SH NAME
\fB\%keyok\fP \-
enable or disable a \fIcurses\fR keycode
and vice versa.
Otherwise, the function returns \fBOK\fP.
.SH PORTABILITY
-This routine is specific to \fIncurses\fP.
+This routine is specific to \fI\%ncurses\fP.
It was not supported on
Version 7, BSD or System V implementations.
It is recommended that
.\"
.\" Author: Thomas E. Dickey
.\"
-.\" $Id: legacy_coding.3x,v 1.23 2023/11/25 14:26:30 tom Exp $
-.TH legacy_coding 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: legacy_coding.3x,v 1.24 2023/12/16 20:32:22 tom Exp $
+.TH legacy_coding 3X 2023-12-16 "ncurses 6.4" "Library calls"
.SH NAME
\fB\%use_legacy_coding\fP \-
override \fIcurses\fR locale encoding checks
the function returns \fBERR\fP.
Otherwise, it returns the previous level: \fB0\fP, \fB1\fP or \fB2\fP.
.SH PORTABILITY
-This routine is specific to ncurses.
+This routine is specific to \fI\%ncurses\fP.
It was not supported on Version 7, BSD or System V implementations.
-It is recommended that any code depending on ncurses extensions
+It is recommended that any code depending on \fI\%ncurses\fP extensions
be conditioned using NCURSES_VERSION.
.SH AUTHORS
Thomas Dickey (to support lynx's font-switching feature).
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: man_db.renames.in,v 1.61 2023/11/25 14:32:36 tom Exp $
+# $Id: man_db.renames.in,v 1.63 2023/12/17 23:52:59 tom Exp $
# Manual-page renamings for the man_db program
#
# Files:
user_caps.5 user_caps.5
wresize.3x wresize.3ncurses
#
+# Supplementary topics in the foregoing pages:
+add_wch.3x add_wch.3ncurses
+addch.3x addch.3ncurses
+assume_default_colors.3x assume_default_colors.3ncurses
+attr_on.3x attr_on.3ncurses
+attron.3x attron.3ncurses
+baudrate.3x baudrate.3ncurses
+bkgd.3x bkgd.3ncurses
+bkgrnd.3x bkgrnd.3ncurses
+clearok.3x clearok.3ncurses
+curs_set.3x curs_set.3ncurses
+curscr.3x curscr.3ncurses
+def_prog_mode.3x def_prog_mode.3ncurses
+def_shell_mode.3x def_shell_mode.3ncurses
+del_curterm.3x del_curterm.3ncurses
+delay_output.3x delay_output.3ncurses
+delscreen.3x delscreen.3ncurses
+derwin.3x derwin.3ncurses
+doupdate.3x doupdate.3ncurses
+endwin.3x endwin.3ncurses
+filter.3x filter.3ncurses
+flushinp.3x flushinp.3ncurses
+get_wch.3x get_wch.3ncurses
+getcchar.3x getcchar.3ncurses
+getch.3x getch.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
+keypad.3x keypad.3ncurses
+leaveok.3x leaveok.3ncurses
+longname.3x longname.3ncurses
+meta.3x meta.3ncurses
+move.3x move.3ncurses
+mvcur.3x mvcur.3ncurses
+mvwin.3x mvwin.3nwinses
+newpad.3x newpad.3ncurses
+newterm.3x newterm.3ncurses
+newwin.3x newwin.3ncurses
+nodelay.3x nodelay.3ncurses
+notimeout.3x notimeout.3ncurses
+refresh.3x refresh.3ncurses
+reset_shell_mode.3x reset_shell_mode.3ncurses
+restartterm.3x restartterm.3ncurses
+scrollok.3x scrollok.3ncurses
+set_curterm.3x set_curterm.3ncurses
+set_term.3x set_term.3nses
+setcchar.3x setcchar.3ncurses
+setupterm.3x setupterm.3ncurses
+slk_init.3x slk_init.3ncurses
+slk_touch.3x slk_touch.3ncurses
+start_color.3x start_color.3ncurses
+subwin.3x subwin.3ncurses
+syncok.3x syncok.3ncurses
+terminfo.3x terminfo.3ncurses
+tigetstr.3x tigetstr.3ncurses
+tparm.3x tparm.3ncurses
+tputs.3x tputs.3ncurses
+unctrl.3x unctrl.3ncurses
+use_default_colors.3x use_default_colors.3ncurses
+use_env.3x use_env.3ncurses
+use_extended_names.3x use_extended_names.3ncurses
+use_legacy_coding.3x use_legacy_coding.3ncurses
+vidputs.3x vidputs.3ncurses
+wadd_wch.3x wadd_wch.3ncurses
+waddch.3x waddch.3ncurses
+waddstr.3x waddstr.3ncurses
+waddwstr.3x waddwstr.3ncurses
+wbkgdset.3x wbkgdset.3ncurses
+wget_wch.3x wget_wch.3ncurses
+wgetch.3x wgetch.3ncurses
+wgetstr.3x wgetstr.3ncurses
+wins_wch.3x wins_wch.3ncurses
+winsch.3x winsch.3ncurses
+wmove.3x wmove.3ncurses
+wnoutrefresh.3x wnoutrefresh.3ncurses
+wrefresh.3x wrefresh.3ncurses
+wsetscrreg.3x wsetscrreg.3ncurses
+wtimeout.3x wtimeout.3ncurses
+#
# Other:
getty.1 getty.8
scanf.3 scanf.3
-# $Id: manhtml.aliases,v 1.28 2023/11/19 00:14:00 tom Exp $
+# $Id: manhtml.aliases,v 1.29 2023/12/18 00:27:56 tom Exp $
#***************************************************************************
# Copyright 2019-2022,2023 Thomas E. Dickey *
# Copyright 2013,2017 Free Software Foundation, Inc. *
attr_on(3X) curs_attr(3X)
attron(3X) curs_attr(3X)
baudrate(3X) curs_termattrs(3X)
+bkgd(3X) curs_bkgd(3X)
+bkgrnd(3X) curs_bkgrnd(3X)
clearok(3X) curs_outopts(3X)
curs_set(3X) curs_kernel(3X)
+curscr(3X) curs_variables(3X)
def_prog_mode(3X) curs_kernel(3X)
def_shell_mode(3X) curs_kernel(3X)
+del_curterm(3X) curs_terminfo(3X)
delay_output(3X) curs_util(3X)
delscreen(3X) curs_initscr(3X)
doupdate(3X) curs_refresh(3X)
endwin(3X) curs_initscr(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)
keypad(3X) curs_inopts(3X)
longname(3X) curs_termattrs(3X)
meta(3X) curs_inopts(3X)
+move(3X) curs_move(3X)
mvcur(3X) curs_terminfo(3X)
mvwin(3X) curs_window(3X)
newterm(3X) curs_initscr(3X)
setupterm(3X) curs_terminfo(3X)
slk_init(3X) curs_slk(3X)
slk_touch(3X) curs_slk(3X)
+start_color(3X) curs_color(3X)
+terminfo(3X) curs_terminfo(3X)
tic(1) tic(1M)
tigetstr(3X) curs_terminfo(3X)
tparm(3X) curs_terminfo(3X)
vidputs(3X) curs_terminfo(3X)
wadd_wch(3X) curs_add_wch(3X)
waddch(3X) curs_addch(3X)
+waddstr(3X) curs_addstr(3X)
+waddwstr(3X) curs_addwstr(3X)
wbkgdset(3X) curs_bkgd(3X)
wget_wch(3X) curs_get_wch(3X)
wgetch(3X) curs_getch(3X)
+wgetstr(3X) curs_getstr(3X)
wins_wch(3X) curs_ins_wch(3X)
winsch(3X) curs_insch(3X)
wmove(3X) curs_move(3X)
-# $Id: manhtml.externs,v 1.15 2021/12/26 00:02:52 tom Exp $
+# $Id: manhtml.externs,v 1.18 2023/12/18 00:35:38 tom Exp $
# Items in this list will not be linked by man2html
#***************************************************************************
-# Copyright 2019-2020,2021 Thomas E. Dickey *
+# Copyright 2019-2021,2023 Thomas E. Dickey *
# Copyright 2013,2017 Free Software Foundation, Inc. *
# *
# Permission is hereby granted, free of charge, to any person obtaining a *
# sale, use or other dealings in this Software without prior written *
# authorization. *
#***************************************************************************
-ADACURSES(1)
COLOR_PAIR(1)
COLOR_PAIR(2)
-COLOR_PAIR(3)
atoi(3)
conflict(1)
cron(1)
screen(1)
setlocale(3)
sh(1)
+scanf(3)
+scanf(3S)
sscanf(3)
stdio(3)
stty(1)
system(3)
+swprintf(3)
termios(3)
tmux(1)
tty(4)
vi(1)
vprintf(3)
vscanf(3)
+vsscanf(3)
wcwidth(3)
write(2)
xterm(1)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu.3x,v 1.41 2023/11/25 13:59:44 tom Exp $
-.TH menu 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: menu.3x,v 1.42 2023/12/16 20:32:22 tom Exp $
+.TH menu 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
It is not part of X/Open Curses.
.PP
-Aside from ncurses, there are few implementations:
+Aside from \fI\%ncurses\fP, there are few implementations:
.bP
systems based on SVr4 source code, e.g., Solaris.
.bP
NetBSD curses.
.SH AUTHORS
Juergen Pfeifer.
-Manual pages and adaptation for ncurses by Eric S. Raymond.
+Manual pages and adaptation for \fI\%ncurses\fP by Eric S. Raymond.
.SH SEE ALSO
\fB\%curses\fP(3X) and related pages whose names begin \*(``menu_\*(''
for detailed descriptions of the entry points.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_driver.3x,v 1.43 2023/11/25 13:58:47 tom Exp $
-.TH menu_driver 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: menu_driver.3x,v 1.44 2023/12/16 20:32:22 tom Exp $
+.TH menu_driver 3X 2023-12-16 "ncurses 6.4" "Library calls"
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
These routines emulate the System V menu library.
They were not supported on
Version 7 or BSD versions.
-The support for mouse events is ncurses specific.
+The support for mouse events is \fI\%ncurses\fP specific.
.SH AUTHORS
Juergen Pfeifer.
Manual pages and adaptation for new curses by Eric S. Raymond.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_requestname.3x,v 1.30 2023/11/25 13:58:47 tom Exp $
-.TH menu_requestname 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: menu_requestname.3x,v 1.31 2023/12/16 20:32:22 tom Exp $
+.TH menu_requestname 3X 2023-12-16 "ncurses 6.4" "Library calls"
.SH NAME
\fBmenu_request_by_name\fP,
\fBmenu_request_name\fP \-
\fBmenu_request_by_name\fP returns \fBE_NO_MATCH\fP on error.
It does not set \fBerrno\fP.
.SH PORTABILITY
-These routines are specific to ncurses.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on
Version 7, BSD or System V implementations.
It is recommended that
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: menu_spacing.3x,v 1.34 2023/11/25 13:58:47 tom Exp $
-.TH menu_spacing 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: menu_spacing.3x,v 1.35 2023/12/16 20:32:22 tom Exp $
+.TH menu_spacing 3X 2023-12-16 "ncurses 6.4" "Library calls"
.SH NAME
\fBset_menu_spacing\fP,
\fBmenu_spacing\fP \-
\fBE_POSTED\fP if the menu is posted, or \fBE_BAD_ARGUMENT\fP if one of the
spacing values is out of range.
.SH PORTABILITY
-These routines are specific to ncurses.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on
Version 7, BSD or System V implementations.
It is recommended that
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: ncurses.3x,v 1.185 2023/12/03 00:14:35 tom Exp $
-.TH ncurses 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: ncurses.3x,v 1.187 2023/12/17 23:44:14 tom Exp $
+.TH ncurses 3X 2023-12-17 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.ie t .ds '' ''
.el .ds '' ""
.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
\fB#include <curses.h>
.fi
.SH DESCRIPTION
-The \fBncurses\fP library routines give the user a terminal-independent method
-of updating character screens with reasonable optimization.
-This implementation is \*(``new curses\*('' (ncurses) and
+The \fI\%ncurses\fP library routines give the user a
+terminal-independent method of updating character screens with
+reasonable optimization.
+This implementation is \*(``new curses\*('' (\fI\%ncurses\fP) and
is the approved replacement for
4.4BSD classic curses, which has been discontinued.
-This describes \fBncurses\fP
+This describes \fI\%ncurses\fP
version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.PP
-The \fBncurses\fP library emulates the curses library of
+The \fI\%ncurses\fP library emulates the curses library of
System V Release 4 Unix (\*(``SVr4\*(''),
and XPG4 (X/Open Portability Guide) curses (also known as XSI curses).
XSI stands for X/Open System Interfaces Extension.
-The \fBncurses\fP library is freely redistributable in source form.
+The \fI\%ncurses\fP library is freely redistributable in source form.
.PP
\fI\%ncurses\fP man pages employ several sections to clarify matters of
usage and interoperability with other \fIcurses\fP implementations.
that describe curses actions.
See also the section on \fBALTERNATE CONFIGURATIONS\fP.
.PP
-The \fBncurses\fP package supports: overall screen, window and pad
+The \fI\%ncurses\fP package supports: overall screen, window and pad
manipulation; output to windows and pads; reading terminal input; control over
terminal and \fBcurses\fP input and output options; environment query
routines; color manipulation; use of soft label keys; terminfo capabilities;
after the shell environment variable \fITERM\fP has been exported.
(The BSD-style \fB\%@TSET@\fP(1) utility also performs this function.)
See subsection \*(``Tabs and Initialization\*('' of \fBterminfo\fP(5).
-.SS Datatypes
-The \fBncurses\fP library permits manipulation of data structures,
-called \fIwindows\fP, which can be thought of as two-dimensional
-arrays of characters representing all or part of a CRT screen.
-A default window called \fBstdscr\fP, which is the size of the terminal
-screen, is supplied.
-Others may be created with \fBnewwin\fP.
-.PP
-Note that \fBcurses\fP does not handle overlapping windows, that's done by
-the \fBpanel\fP(3X) library.
-This means that you can either use
-\fBstdscr\fP or divide the screen into tiled windows and not using
-\fBstdscr\fP at all.
-Mixing the two will result in unpredictable, and undesired, effects.
-.PP
-Windows are referred to by variables declared as \fBWINDOW *\fP.
-These data structures are manipulated with routines described here and
-elsewhere in the \fBncurses\fP manual pages.
-Among those, the most basic
-routines are \fBmove\fP and \fBaddch\fP.
-More general versions of
-these routines are included with names beginning with \fBw\fP,
-allowing the user to specify a window.
-The routines not beginning
-with \fBw\fP affect \fBstdscr\fP.
-.PP
-After using routines to manipulate a window, \fBrefresh\fP(3X) is called,
-telling \fBcurses\fP to make the user's CRT screen look like
-\fBstdscr\fP.
-The characters in a window are actually of type
-\fBchtype\fP, (character and attribute data) so that other information
-about the character may also be stored with each character.
+.SS Overview
+A
+.I curses
+library abstracts the terminal screen by representing all or part of it
+as a
+.I \%WINDOW
+data structure.
+A
+.I window
+is a rectangular grid of character cells,
+addressed by row and column coordinates
+.RI ( y ,
+.IR x ),
+with the upper left corner as (0, 0).
+A window called \fB\%stdscr\fP,
+the same size as the terminal screen,
+is always available.
+Create others with \fB\%newwin\fP(3X).
+.PP
+A
+.I curses
+library does not manage overlapping windows.
+(See \fBpanel\fP(3X) if you desire this.)
+You can either use \fB\%stdscr\fP to manage one screen-filling window,
+or tile the screen into non-overlapping windows and not use
+\fB\%stdscr\fP at all.
+Mixing the two approaches will result in unpredictable,
+and undesired,
+effects.
+.PP
+Functions permit manipulation of a window and the
+.I cursor
+identifying the cell within it at which the next output operation will
+occur.
+Among those,
+the most basic are \fBmove\fP(3X) and \fB\%addch\fP(3X):
+these place the cursor and write a character to
+.BR \%stdscr ,
+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
+.I \%WINDOW.
+Counterparts not thus prefixed
+(or infixed)
+affect \fB\%stdscr\fP.
+Because moving the cursor prior to another operation is so common,
+.I curses
+generally also provides functions with a \*(``mv\*('' prefix as a
+convenience.
+Thus,
+the library defines all of
+\fB\%addch\fP,
+\fB\%waddch\fP,
+\fB\%mvaddch\fP,
+and
+\fB\%mvwaddch\fP.
+When both prefixes are present,
+the order of arguments is a
+.I \%WINDOW
+pointer first,
+then a
+.I y
+and
+.I x
+coordinate pair.
+.PP
+Updating the terminal screen with every
+.I curses
+call can cause unpleasant flicker or inefficient use of the
+communications channel to the device.
+Therefore,
+after using
+.I curses
+functions to accumulate a set of desired updates that make sense to
+present together,
+call \fB\%refresh\fP(3X) to tell the library to make the user's screen
+look like \fBstdscr\fP.
+.I \%ncurses
+.\" X/Open Curses Issue 7 assumes some optimization will be done, but
+.\" does not mandate it in any way.
+.I optimizes
+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
+\fB\%terminfo\fP(3X) API,
+a feature of every standard
+.I curses
+implementation.
.PP
Special windows called \fIpads\fP may also be manipulated.
-These are windows
-which are not constrained to the size of the screen and whose contents need not
-be completely displayed.
-See \fBcurs_pad\fP(3X) for more information.
-.PP
-In addition to drawing characters on the screen, video 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.
-Line drawing characters may be specified to be output.
-On input, \fBcurses\fP is also able to translate arrow and function keys that
-transmit escape sequences into single values.
-The video attributes, line
-drawing characters, and input values use names, defined in \fB<curses.h>\fP,
-such as \fBA_REVERSE\fP, \fBACS_HLINE\fP, and \fBKEY_LEFT\fP.
-.SS Environment variables
+These are windows that are not constrained to the size of the terminal
+screen and whose contents need not be completely displayed.
+See \fB\%curs_pad\fP(3X).
+.PP
+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 \fB\%curs_attr\fP(3X).
+.PP
+.I curses
+predefines symbols for a small set of line graphics characters,
+corresponding to the VT100 line drawing set.
+See
+\fB\%waddch\fP(3X) and
+\fB\%wadd_wch\fP(3X).
+.PP
+.I curses
+is implemented using the operating system's terminal driver;
+keystroke events are not received 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
+.I "escape sequence."
+.I curses
+translates these into unique
+.I "key codes."
+See \fB\%getch\fP(3X).
+.SS "Effects of GUIs and Environment Variables"
+The selection of an approprate value of
+.I TERM
+in the process environment is essential to correct
+.I curses
+and
+.I \%term\%info
+library operation.
+A well-configured system selects a correct
+.I TERM
+value automatically;
+\fB\%tset\fP(1) may assist with troubleshooting exotic situations.
+.PP
If the environment variables \fILINES\fP and \fI\%COLUMNS\fP are set,
or if the
-program is executing in a window environment, line and column information in
-the environment will override information read by \fIterminfo\fP.
-This would affect a program running in an AT&T 630 layer,
-for example, where the size of a
-screen is changeable (see \fBENVIRONMENT\fP).
+.I curses
+program is executing in a graphical windowing environment,
+the information obtained thence overrides that obtained by
+.IR \%term\%info .
+An
+.I \%ncurses
+extension supports resizable terminals;
+see \fB\%wresize\fP(3X).
.PP
If the environment variable \fI\%TERMINFO\fP is defined,
-any program using
-\fBcurses\fP checks for a local terminal definition before checking in the
-standard place.
-For example, if \fITERM\fP is set to \fBatt4424\fP, then the
-compiled terminal definition is found in
-.PP
-.RS 4
-.EX
-\fB\*d/a/att4424\fP.
-.EE
-.RE
+a
+.I curses
+program checks first for a terminal type description in the location it
+identifies.
+.I \%TERMINFO
+is useful for developing experimental type descriptions or when write
+permission to \fI\*d\fP is not available.
+.PP
+See section \*(``ENVIRONMENT\*('' below.
+.SS "Naming Conventions"
+Many
+.I curses
+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 \fB\%stdscr\fP.
+.PP
+In function synopses,
+.I \%ncurses
+man pages apply the following names to parameters.
.PP
-(The \fBa\fP is copied from the first letter of \fBatt4424\fP to avoid
-creation of huge directories.)
-However,
-if \fI\%TERMINFO\fP is set to
-\fB$HOME/myterms\fP, \fBcurses\fP first checks
-.PP
-.RS 4
-.EX
-\fB$HOME/myterms/a/att4424\fP,
-.EE
-.RE
-.PP
-and if that fails, it then checks
-.PP
-.RS 4
-.EX
-\fB\*d/a/att4424\fP.
-.EE
-.RE
-.PP
-This is useful for developing experimental definitions or when write
-permission in \fB\*d\fP is not available.
-.PP
-The integer variables \fBLINES\fP and \fBCOLS\fP are defined in
-\fB<curses.h>\fP and will be filled in by \fBinitscr\fP with the size of the
-screen.
-The constants \fBTRUE\fP and \fBFALSE\fP have the values \fB1\fP and
-\fB0\fP, respectively.
-.PP
-The \fBcurses\fP routines also define the \fBWINDOW *\fP variable \fBcurscr\fP
-which is used for certain low-level operations like clearing and redrawing a
-screen containing garbage.
-The \fBcurscr\fP can be used in only a few routines.
-.\"
-.SS Routine and Argument Names
-Many \fBcurses\fP routines have two or more versions.
-The routines prefixed with \fIw\fP require a window argument.
-The routines prefixed with \fIp\fP require a pad argument.
-Those without a prefix generally use \fBstdscr\fP.
-.PP
-The routines prefixed with \fBmv\fP require a \fIy\fP and \fIx\fP
-coordinate to move to before performing the appropriate action.
-The \fBmv\fP routines imply a call to \fBmove\fP before the call to the
-other routine.
-The coordinate \fIy\fP always refers to the row (of
-the window), and \fIx\fP always refers to the column.
-The upper left-hand corner is always (0,0), not (1,1).
-.PP
-The routines prefixed with \fBmvw\fP take both a window argument and
-\fIx\fP and \fIy\fP coordinates.
-The window argument is always specified before the coordinates.
-.PP
-In each case, \fIwin\fP is the window affected, and \fIpad\fP is the
-pad affected; \fIwin\fP and \fIpad\fP are always pointers to type
-\fBWINDOW\fP.
-.PP
-Option setting routines require a Boolean flag \fIbf\fP with the value
-\fBTRUE\fP or \fBFALSE\fP; \fIbf\fP is always of type \fBbool\fP.
-Most of the data types used in the library routines,
-such as \fBWINDOW\fP, \fBSCREEN\fP, \fBbool\fP, and \fBchtype\fP
-are defined in \fB<curses.h>\fP.
-Types used for the terminfo routines such as
-\fBTERMINAL\fP are defined in \fB<term.h>\fP.
-.PP
-This manual page describes functions which may appear in any configuration
+.TS
+center;
+Li L.
+bf \fIbool\fP (\fBTRUE\fP or \fBFALSE\fP)
+win pointer to \fIWINDOW\fP
+pad pointer to \fIWINDOW\fP that is a pad
+.TE
+.SS "Wide and Non-wide Character Configurations"
+This manual page describes functions that appear in any configuration
of the library.
-There are two common configurations of the library:
-.RS 3
-.TP 5
-.I ncurses
-the \*(``normal\*('' library, which handles 8-bit characters.
-The normal (8-bit) library stores characters combined with attributes
-in \fBchtype\fP data.
+There are two common configurations;
+see section \*(``ALTERNATE CONFIGURATIONS\*('' below.
+.TP 10 \" "ncursesw" + 2n
+.I \%ncurses
+is the library in its \*(``non-wide\*('' configuration,
+handling only eight-bit characters.
+It stores a character combined with attributes in a
+.I \%chtype
+datum.
.IP
-Attributes alone (no corresponding character) may be stored in \fBchtype\fP
-or the equivalent \fBattr_t\fP data.
-In either case, the data is stored in something like an integer.
+Attributes alone
+(with no corresponding character)
+can be stored in variables of
+.I \%chtype
+or
+.I \%attr_t
+type.
+In either case,
+they are represented as an integral bit mask.
.IP
-Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBchtype\fP.
-.TP 5
-.I ncursesw
-the so-called \*(``wide\*('' library, which handles multibyte characters
-(see the section on \fBALTERNATE CONFIGURATIONS\fP).
-The \*(``wide\*('' library includes all of the calls
-from the \*(``normal\*('' library.
-It adds about one third more calls using data types which store
-multibyte characters:
-.RS 5
-.TP 5
-.B cchar_t
-corresponds to \fBchtype\fP.
-However it is a structure, because more data is stored than can fit into
-an integer.
-The characters are large enough to require a full integer value \- and there
-may be more than one character per cell.
-The video attributes and color are stored in separate fields of the structure.
+Each cell of a
+.I \%WINDOW
+is stored as a
+.I \%chtype.
+.TP 10
+.I \%ncursesw
+is the library in its \*(``wide\*('' configuration,
+which handles character encodings requiring a larger data type than
+.I \%char
+(a byte-sized type)
+can represent.
+It adds about one third more calls using additional data types that
+can store such
+.I multibyte
+characters.
+.RS 10 \" same as foregoing tag width
+.TP 9 \" "cchar_t" + 2n
+.I \%cchar_t
+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
+.I \%char,
+and moreover more than one character may occupy a cell
+(as with accent marks and other diacritics).
+Each character is of type
+.I \%wchar_t;
+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
+.I \%chtype.
.IP
-Each cell (row and column) in a \fBWINDOW\fP is stored as a \fBcchar_t\fP.
-.IP
-The \fBsetcchar\fP(3X) and \fBgetcchar\fP(3X)
-functions store and retrieve the data from
-a \fBcchar_t\fP structure.
-.TP 5
-.B wchar_t
-stores a \*(``wide\*('' character.
-Like \fBchtype\fP, this may be an integer.
-.TP 5
-.B wint_t
-stores a \fBwchar_t\fP or \fBWEOF\fP \- not the same, though both may have
-the same size.
+Each cell
+(row and column)
+.I \%WINDOW
+is stored as a
+.I \%cchar_t.
+.PP
+The \fB\%setcchar\fP(3X) and \fB\%getcchar\fP(3X)
+functions store and retrieve the data from a
+.I \%cchar_t
+structure.
+The wide library API of
+.I \%ncurses
+depends on two data types standardized by ISO C95.
+.TP 9
+.I \%wchar_t
+stores a wide character.
+Like
+.I \%chtype,
+this may be an integer.
+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,
+or
+.I combining,
+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.
+.TP 9
+.I \%wint_t
+can store a
+.I \%wchar_t
+or the constant
+.BR \%WEOF ,
+analogously to the
+.IR int -sized
+character manipulation functions of ISO C and their constant
+.BR \%EOF .
.RE
.IP
-The \*(``wide\*('' library provides new functions which are analogous to
-functions in the \*(``normal\*('' library.
-There is a naming convention which relates many of the normal/wide variants:
-a \*(``_w\*('' is inserted into the name.
-For example, \fBwaddch\fP becomes \fBwadd_wch\fP.
-.RE
+The wide library provides additional functions that complement those in
+the non-wide library where the size of the underlying character type is
+significant.
+A somewhat regular naming convention relates many of the wide variants
+to their non-wide counterparts;
+where a non-wide function name contains \*(``ch\*('' or \*(``str\*('',
+prefix it with \*(``_w\*('' to obtain the wide counterpart.
+For example,
+\fB\%waddch\fP becomes \fB\%wadd_wch\fP.
+.IP
+This convention is inapplicable to some non-wide function names,
+so other transformations are used for the wide configuration:
+in the window background management functions,
+\*(``bkgd\*('' becomes \*(``bkgrnd\*('';
+the window border-drawing and -clearing functions are suffixed with
+\*(``_set\*(''.
.\"
-.SS Routine Name Index
-The following table lists the \fBcurses\fP routines provided in
-the \*(``normal\*('' and \*(``wide\*('' libraries and the names of
-the manual pages on which they are described.
-Routines flagged with \*(``*\*(''
-are ncurses-specific, not described by XPG4 or present in SVr4.
+.SS "Function Name Index"
+The following table lists the
+.I curses
+functions provided in the non-wide and wide APIs and the corresponding
+man pages that describe them.
+Those flagged with \*(``*\*(''
+are
+.IR \%ncurses -specific,
+neither described by X/Open Curses nor present in SVr4.
.PP
.TS
center tab(/);
-l l
l l .
-\fBcurses\fP Routine Name/Manual Page Name
-=
+\f(BIcurses\fP Function Name/Man Page
+_
COLOR_PAIR/\fBcurs_color\fP(3X)
PAIR_NUMBER/\fBcurs_attr\fP(3X)
add_wch/\fBcurs_add_wch\fP(3X)
\fBgetmaxyx\fP are undefined (i.e., these should not be used as the
right-hand side of assignment statements).
.PP
-Functions with a \*(``mv\*('' prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions with a \*(``mv\*('' prefix first perform cursor movement using
+\fB\%wmove\fP and return an error 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 \fBmvprintw\fP)
+(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 \fBncurses\fP library.
+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
Very few terminfo entries provide this feature.
.PP
Because this name is also used in development environments to represent
-the C compiler's name, \fBncurses\fP ignores it if it does not happen to
-be a single character.
+the C compiler's name,
+\fI\%ncurses\fP ignores it if it does not happen to be a single
+character.
.SS \fIBAUDRATE\fP
The debugging library checks this environment variable when the application
has redirected output to a file.
The variable's numeric value is used for the baudrate.
-If no value is found, \fBncurses\fP uses 9600.
+If no value is found, \fI\%ncurses\fP uses 9600.
This allows testers to construct repeatable test-cases
that take into account costs that depend on baudrate.
.SS \fICOLUMNS\fP
Applications running in a windowing environment usually are able to
obtain the width of the window in which they are executing.
If neither the \fI\%COLUMNS\fP value nor the terminal's screen size is available,
-\fBncurses\fP uses the size which may be specified in the terminfo database
+\fI\%ncurses\fP uses the size which may be specified in the terminfo
+database
(i.e., the \fBcols\fP capability).
.PP
It is important that your application use a correct size for the screen.
\fILINES\fP to match the screen size obtained from system calls or the
terminal database.
.SS \fIESCDELAY\fP
-Specifies the total time, in milliseconds, for which ncurses will
-await a character sequence, e.g., a function key.
+Specifies the total time,
+in milliseconds,
+for which \fI\%ncurses\fP will await a character sequence,
+e.g.,
+a function key.
The default value, 1000 milliseconds, is enough for most uses.
However, it is made a variable to accommodate unusual applications.
.PP
but setting the environment variable rather than the global variable
does not create problems when compiling an application.
.SS \fIHOME\fP
-Tells \fBncurses\fP where your home directory is.
+Tells \fI\%ncurses\fP where your home directory is.
That is where it may read and write auxiliary terminal descriptions:
.PP
.RS 4
.PP
This variable lets you customize the mouse.
The variable must be three numeric digits 1\-3 in any order, e.g., 123 or 321.
-If it is not specified, \fBncurses\fP uses 132.
+If it is not specified, \fI\%ncurses\fP uses 132.
.SS \fINCURSES_ASSUMED_COLORS\fP
Override the compiled-in assumption that the
terminal's default colors are white-on-black
(see \fBdefault_colors\fP(3X)).
You may set the foreground and background color values with this environment
variable by proving a 2-element list: foreground,background.
-For example, to tell ncurses to not assume anything
+For example, to tell \fI\%ncurses\fP to not assume anything
about the colors, set this to "\-1,\-1".
To make it green-on-black, set it to "2,0".
Any positive value from zero to the terminfo \fBmax_colors\fP value is allowed.
.SS \fINCURSES_CONSOLE2\fP
-This applies only to the MinGW port of ncurses.
+This applies only to the MinGW port of \fI\%ncurses\fP.
.PP
The \fBConsole2\fP program's handling of the Microsoft Console API call
\fBCreateConsoleScreenBuffer\fP is defective.
explicitly saving and restoring the original screen contents.
Setting the environment variable \fBNCGDB\fP has the same effect.
.SS \fINCURSES_GPM_TERMS\fP
-This applies only to ncurses configured to use the GPM interface.
+This applies only to \fI\%ncurses\fP configured to use the GPM
+interface.
.PP
If present,
the environment variable is a list of one or more terminal names
using the built-in support for xterm, etc.
.PP
If the environment variable is absent,
-ncurses will attempt to open GPM if \fITERM\fP contains \*(``linux\*(''.
+\fI\%ncurses\fP will attempt to open GPM if \fITERM\fP contains
+\*(``linux\*(''.
.SS \fINCURSES_NO_HARD_TABS\fP
-\fBNcurses\fP may use tabs as part of the cursor movement optimization.
+\fI\%ncurses\fP may use tabs as part of cursor movement optimization.
In some cases,
your terminal driver may not handle these properly.
-Set this environment variable to disable the feature.
+Set this environment variable to any value to disable the feature.
You can also adjust your \fBstty\fP(1) settings to avoid the problem.
.SS \fINCURSES_NO_MAGIC_COOKIE\fP
Some terminals use a magic-cookie feature which requires special handling
to make highlighting and other video attributes display properly.
You can suppress the highlighting entirely for these terminals by
-setting this environment variable.
+setting this environment variable to any value.
.SS \fINCURSES_NO_PADDING\fP
Most of the terminal descriptions in the terminfo database are written
for real \*(``hardware\*('' terminals.
though 5.9 patch 20130126
.RE
.PP
-\fBncurses\fP enabled buffered output during terminal initialization.
+\fI\%ncurses\fP enabled buffered output during terminal initialization.
This was done (as in SVr4 curses) for performance reasons.
-For testing purposes, both of \fBncurses\fP and certain applications,
+For testing purposes, both of \fI\%ncurses\fP and certain applications,
this feature was made optional.
Setting the \fI\%NCURSES_NO_SETBUF\fP variable
disabled output buffering, leaving the output in the original (usually
line buffered) mode.
.PP
In the current implementation,
-ncurses performs its own buffering and does not require this workaround.
+\fI\%ncurses\fP performs its own buffering and does not require this
+workaround.
It does not modify the buffering of the standard output.
.PP
The reason for the change was to make the behavior for interrupts and
other signals more robust.
One drawback is that certain nonconventional programs would mix
-ordinary stdio calls with ncurses calls and (usually) work.
-This is no longer possible since ncurses is not using
+ordinary stdio calls with \fI\%ncurses\fP calls and (usually) work.
+This is no longer possible since \fI\%ncurses\fP is not using
the buffered standard output but its own output (to the same file descriptor).
As a special case, the low-level calls such as \fBputp\fP still use the
standard output.
But high-level curses calls do not.
.SS \fINCURSES_NO_UTF8_ACS\fP
-During initialization, the \fBncurses\fP library
+During initialization, the \fI\%ncurses\fP library
checks for special cases where VT100 line-drawing (and the corresponding
alternate character set capabilities) described in the terminfo are known
to be missing.
Specifically, when running in a UTF\-8 locale,
the Linux console emulator and the GNU screen program ignore these.
-Ncurses checks the \fITERM\fP environment variable for these.
+\fI\%ncurses checks the \fITERM\fP environment variable for these.
For other special cases, you should set this environment variable.
-Doing this tells ncurses to use Unicode values which correspond to
-the VT100 line-drawing glyphs.
+Doing this tells \fI\%ncurses\fP to use Unicode values which correspond
+to the VT100 line-drawing glyphs.
That works for the special cases cited,
and is likely to work for terminal emulators.
.PP
disables the special check for \*(``linux\*('' and \*(``screen\*(''.
.PP
As an alternative to the environment variable,
-ncurses checks for an extended terminfo capability \fBU8\fP.
+\fI\%ncurses\fP checks for an extended terminfo capability \fBU8\fP.
This is a numeric capability which can be compiled using \fB@TIC@\ \-x\fP.
For example
.PP
.RE
.PP
The name \*(``U8\*('' is chosen to be two characters,
-to permit it to be used by applications that use ncurses'
+to permit it to be used by applications that use \fI\%ncurses\fP'
termcap interface.
.SS \fINCURSES_TRACE\fP
-During initialization, the \fBncurses\fP debugging library
+During initialization, the \fI\%ncurses\fP debugging library
checks the \fI\%NCURSES_TRACE\fP environment variable.
-If it is defined, to a numeric value, \fBncurses\fP calls the \fBtrace\fP
-function, using that value as the argument.
+If it is defined,
+to a numeric value,
+\fI\%ncurses\fP calls the \fBtrace\fP function,
+using that value as the argument.
.PP
The argument values, which are defined in \fBcurses.h\fP, provide several
types of information.
specify \fITERM\fP as a parameter or configuration value do
not change their behavior to match that setting.
.SS \fITERMCAP\fP
-If the \fBncurses\fP library has been configured with \fItermcap\fP
-support, \fBncurses\fP will check for a terminal's description in
+If the \fI\%ncurses\fP library has been configured with \fItermcap\fP
+support, \fI\%ncurses\fP will check for a terminal's description in
termcap form if it is not available in the terminfo database.
.PP
The \fI\%TERMCAP\fP environment variable contains
either a terminal description (with newlines stripped out),
or a file name telling where the information denoted by
the \fITERM\fP environment variable exists.
-In either case, setting it directs \fBncurses\fP to ignore
+In either case, setting it directs \fI\%ncurses\fP to ignore
the usual place for this information, e.g., /etc/termcap.
.SS \fITERMINFO\fP
-\fBncurses\fP can be configured to read from multiple terminal databases.
+\fI\%ncurses\fP can be configured to read from multiple terminal
+databases.
The \fI\%TERMINFO\fP variable overrides the location for
the default terminal database.
Terminal descriptions (in terminal format) are stored in terminal databases:
on those
systems to override the default location of the terminal database.
.IP \(bu 4
-If \fBncurses\fP is built to use hashed databases,
+If \fI\%ncurses\fP is built to use hashed databases,
then each entry in this list may be the path of a hashed database file, e.g.,
.RS 4
.PP
rather than using the terminfo library calls.
.RE
.bP
-If \fBncurses\fP is built with a support for reading termcap files
+If \fI\%ncurses\fP is built with a support for reading termcap files
directly, then an entry in this list may be the path of a termcap file.
.IP \(bu 4
If the \fI\%TERMINFO\fP variable begins with
\*(``hex:\*('' or \*(``b64:\*('',
-\fBncurses\fP uses the remainder of that variable as a compiled terminal
-description.
+\fI\%ncurses\fP uses the remainder of that variable as a compiled
+terminal description.
You might produce the base64 format using \fBinfocmp\fP(1M):
.RS 4
.PP
The complete list of database locations in order follows:
.RS 3
.bP
-the last terminal database to which \fBncurses\fP wrote,
+the last terminal database to which \fI\%ncurses\fP wrote,
if any, is searched first
.bP
the location specified by the \fI\%TERMINFO\fP environment variable
locations listed in the \fI\%TERMINFO_DIRS\fP environment variable
.bP
one or more locations whose names are configured and compiled into the
-ncurses library, i.e.,
+\fI\%ncurses\fP library, i.e.,
.RS 3
.bP
@TERMINFO_DIRS@ (corresponding to the \fI\%TERMINFO_DIRS\fP variable)
The list is separated by colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
.PP
There is no corresponding feature in System V terminfo;
-it is an extension developed for \fBncurses\fP.
+it is an extension developed for \fI\%ncurses\fP.
.SS \fITERMPATH\fP
-If \fI\%TERMCAP\fP does not hold a file name then \fBncurses\fP checks
+If \fI\%TERMCAP\fP does not hold a file name then \fI\%ncurses\fP checks
the \fI\%TERMPATH\fP environment variable.
This is a list of filenames separated by spaces or colons (i.e., ":") on Unix,
semicolons on OS/2 EMX.
.PP
If the \fI\%TERMPATH\fP environment variable is not set,
-\fBncurses\fP looks in the files
+\fI\%ncurses\fP looks in the files
.PP
.RS 4
.EX
.RE
.SH ALTERNATE CONFIGURATIONS
Several different configurations are possible,
-depending on the configure script options used when building \fBncurses\fP.
+depending on the configure script options used when building
+\fI\%ncurses\fP.
There are a few main options whose effects are visible to the applications
-developer using \fBncurses\fP:
+developer using \fI\%ncurses\fP:
.TP 5
\-\-disable\-overwrite
-The standard include for \fBncurses\fP is as noted in \fBSYNOPSIS\fP:
+The standard include for \fI\%ncurses\fP is as noted in \fBSYNOPSIS\fP:
.RS 5
.PP
.RS 4
.EE
.RE
.PP
-This option is used to avoid filename conflicts when \fBncurses\fP
+This option is used to avoid filename conflicts when \fI\%ncurses\fP
is not the main implementation of curses of the computer.
-If \fBncurses\fP is installed disabling overwrite, it puts its headers in
-a subdirectory, e.g.,
+If \fI\%ncurses\fP is installed disabling overwrite,
+it puts its headers in a subdirectory,
+e.g.,
.PP
.RS 4
.EX
may require a specific value for \fB_XOPEN_SOURCE\fP
(or a system-specific symbol).
.PP
-The \fBcurses.h\fP file which is installed for the wide-character
-library is designed to be compatible with the normal library's header.
-Only the size of the \fBWINDOW\fP structure differs, and very few
-applications require more than a pointer to \fBWINDOW\fPs.
+The \fI\%curses.h\fP header file installed for the wide-character
+library is designed to be compatible with the non-wide library's header.
+Only the size of the \fI\%WINDOW\fP structure differs;
+few applications require more than pointers to \fI\%WINDOW\fPs.
.PP
If the headers are installed allowing overwrite,
the wide-character library's headers should be installed last,
.I \*d
compiled terminal capability database
.SH NOTES
-If standard output from a \fBncurses\fP program is re-directed to something
-which is not a tty, screen updates will be directed to standard error.
+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.
.PP
See subsection \*(``Header files\*('' below regarding symbols exposed by
inclusion of \fI\%curses.h\fP.
.SH EXTENSIONS
-The \fBncurses\fP library can be compiled with an option (\fB\-DUSE_GETCAP\fP)
+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 \fBncurses\fP startup code, at significant cost in core and startup cycles.
-.PP
-The \fBncurses\fP library includes facilities for capturing mouse events on
-certain terminals (including xterm).
+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 \fBncurses\fP library includes facilities for responding to window
+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 \fBncurses\fP library extends the fixed set of function key capabilities
-of terminals by allowing the application designer to define additional
-key sequences at runtime.
+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 \fBncurses\fP 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.
+The \fI\%ncurses\fP 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 \fBdefault_colors\fP(3X) manual page for details.
.PP
-The \fBncurses\fP library includes a function for directing application output
-to a printer attached to the terminal device.
+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.
.SH PORTABILITY
-The \fBncurses\fP library is intended to be BASE-level conformant with XSI
-Curses.
+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 \fBncurses\fP calls) are described in \fBPORTABILITY\fP
-sections of the library man pages.
+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.
.SS Error checking
In many cases, X/Open Curses is vague about error conditions,
omitting some of the SVr4 documentation.
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 ncurses have not been standardized.
+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:
Starting with BSD curses, all implementations have included <stdio.h>.
.IP
BSD curses included <curses.h> and <unctrl.h> from an internal header
-"curses.ext" ("ext" was a short name for \fIexterns\fP).
+file
+.I \%curses.ext
+(\*(``ext\*('' abbreviated \*(``externs\*('').
.IP
BSD curses used <stdio.h> internally (for \fBprintw\fP and \fBscanw\fP),
but nothing in <curses.h> itself relied upon <stdio.h>.
.bP
X/Open Curses is inconsistent with respect to SVr4 regarding <unctrl.h>.
.IP
-As noted in \fBcurs_util\fP(3X), ncurses includes <unctrl.h> from
-<curses.h> (like SVr4).
+As noted in \fBcurs_util\fP(3X),
+\fI\%ncurses\fP includes <unctrl.h> from <curses.h>
+(like SVr4).
.bP
X/Open's comments about <term.h> and <termios.h> may refer to HP-UX and AIX:
.IP
HP-UX curses includes <term.h> from <curses.h>
to declare \fBsetupterm\fP in curses.h,
-but ncurses (and Solaris curses) do not.
+but \fI\%ncurses\fP (and Solaris curses) do not.
.IP
AIX curses includes <term.h> and <termios.h>.
-Again, ncurses (and Solaris curses) do not.
+Again, \fI\%ncurses\fP (and Solaris curses) do not.
.bP
X/Open says that <curses.h> \fImay\fP include <term.h>,
but there is no requirement that it do that.
Very old versions of AIX curses required including <curses.h>
before including <term.h>.
.IP
-Because ncurses header files include the headers needed to
+Because \fI\%ncurses\fP header files include the headers needed to
define datatypes used in the headers,
-ncurses header files can be included in any order.
+\fI\%ncurses\fP header files can be included in any order.
But for portability, you should include <curses.h> before <term.h>.
.bP
X/Open Curses says \fI"may make visible"\fP
because including a header file does not necessarily make all symbols
in it visible (there are ifdef's to consider).
.IP
-For instance, in ncurses <wchar.h> \fImay\fP be included if
-the proper symbol is defined, and if ncurses is configured for
+For instance, in \fI\%ncurses\fP <wchar.h> \fImay\fP be included if
+the proper symbol is defined, and if \fI\%ncurses\fP is configured for
wide-character support.
If the header is included, its symbols may be made visible.
That depends on the value used for \fB_XOPEN_SOURCE\fP
.IP
None of the X/Open Curses implementations require an application
to include <stdarg.h> before <curses.h> because they either
-have allowed for a special type, or (like ncurses) include <stdarg.h>
-directly to provide a portable interface.
+have allowed for a special type,
+or
+(like \fI\%ncurses\fP)
+include <stdarg.h> directly to provide a portable interface.
.SH AUTHORS
Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
Based on \fIpcurses\fP by Pavel Curtis.
.\"
.\" Author: Thomas E. Dickey
.\"
-.\" $Id: new_pair.3x,v 1.43 2023/11/25 14:26:30 tom Exp $
-.TH new_pair 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: new_pair.3x,v 1.44 2023/12/16 20:32:22 tom Exp $
+.TH new_pair 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
The size of the table is determined by the terminfo \fBpairs\fP capability.
The table is shared with \fBinit_pair\fP;
in fact \fBalloc_pair\fP calls \fBinit_pair\fP after
-updating the \fIncurses\fP library's fast index
+updating the \fI\%ncurses\fP library's fast index
to the colors versus color pairs.
.SS find_pair
The \fBfind_pair\fP function accepts parameters for
Likewise, \fBfree_pair\fP returns \fBOK\fP unless it encounters an
error updating the fast index or if no such color pair is in use.
.SH PORTABILITY
-These routines are specific to \fIncurses\fP.
+These routines are specific to \fI\%ncurses\fP.
They were not supported on
Version 7, BSD or System V implementations.
It is recommended that
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: panel.3x,v 1.59 2023/11/25 14:08:47 tom Exp $
-.TH panel 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.\" $Id: panel.3x,v 1.60 2023/12/16 21:24:43 tom Exp $
+.TH panel 3X 2023-12-16 "ncurses 6.4" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
..
.SH NAME
panel \-
-panel stack extension for \fI\%curses\fP
+panel stack extension for \fIcurses\fP
.SH SYNOPSIS
.nf
\fB#include <panel.h>
Panels are \fBcurses\fP(3X) windows with the added property of
depth.
Panel functions allow the use of stacked windows and ensure that the
-proper portions of each window and the \fI\%curses\fP \fB\%stdscr\fP
+proper portions of each window and the \fIcurses\fP \fB\%stdscr\fP
window are hidden or displayed when panels are added,
moved,
modified,
and show panels.
You can relocate a panel to any desired position in the stack.
.PP
-Panel routines are a functional layer added to \fI\%curses\fP,
-make only high-level \fI\%curses\fP calls,
-and work anywhere \fI\%curses\fP does.
+Panel routines are a functional layer added to \fIcurses\fP,
+make only high-level \fIcurses\fP calls,
+and work anywhere \fIcurses\fP does.
.SH FUNCTIONS
.\" ---------
.SS bottom_panel
such as Solaris,
provide this library.
.bP
-\fIncurses\fP (since version 0.6 in 1993)
+\fI\%ncurses\fP (since version 0.6 in 1993)
and \fIPDCurses\fP (since version 2.2 in 1995)
provide a panel library whose common ancestor
is a public domain implementation by Warren Tucker
.\"
.\" Author: Thomas E. Dickey 1996-on
.\"
-.\" $Id: resizeterm.3x,v 1.53 2023/12/02 20:49:04 tom Exp $
-.TH resizeterm 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: resizeterm.3x,v 1.54 2023/12/16 20:32:22 tom Exp $
+.TH resizeterm 3X 2023-12-16 "ncurses 6.4" "Library calls"
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
.fi
.SH DESCRIPTION
This is an extension to the \fIcurses\fP library.
-It provides callers with a hook into the \fIncurses\fP data to resize windows,
+It provides callers with a hook into the \fI\%ncurses\fP data to resize
+windows,
primarily for use by programs running in an X Window terminal (e.g., xterm)
when the terminal's screen size is changed by the user:
.bP
The added cells should match the current attributes of the windows.
.PP
If the calling program has not set up a handler for \fB\%SIGWINCH\fP
-when it initializes \fIncurses\fP
+when it initializes \fI\%ncurses\fP
(e.g., using \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X)),
-then \fIncurses\fP sets a handler for \fB\%SIGWINCH\fP which notifies
+then \fI\%ncurses\fP sets a handler for \fB\%SIGWINCH\fP which notifies
the library when a window-size event has occurred.
The library checks for this notification
.bP
The function \fB\%resizeterm\fP resizes the standard and current windows
(i.e., \fB\%stdscr\fP and \fB\%curscr\fP)
to the specified dimensions, and adjusts other bookkeeping data used by
-the \fIncurses\fP library that record the window dimensions
+the \fI\%ncurses\fP library that record the window dimensions
such as the \fB\%LINES\fP and \fB\%COLS\fP variables.
.SS resize_term
Most of the work for \fB\%resizeterm\fP is
context where \fB\%malloc\fP or \fB\%realloc\fP may have been interrupted,
since it uses those functions.
.PP
-If \fIncurses\fP is configured to supply its own \fB\%SIGWINCH\fP handler,
+If \fI\%ncurses\fP is configured to supply its own \fB\%SIGWINCH\fP
+handler,
.bP
on receipt of a \fB\%SIGWINCH\fP, the handler sets a flag
.bP
.IP
Calling \fB\%resizeterm\fP or \fB\%resize_term\fP
directly from a signal handler is unsafe.
-This indirect method is used to provide a safe way to resize the \fIncurses\fP
-data structures.
+This indirect method is used to provide a safe way to resize the
+\fI\%ncurses\fP data structures.
.PP
If the environment variables \fILINES\fP or \fI\%COLUMNS\fP are set,
this overrides the library's use of the window size obtained from
.PP
Doing that clears the screen and is visually distracting.
.PP
-This extension of \fIncurses\fP was introduced in mid-1995.
+This extension of \fI\%ncurses\fP was introduced in mid-1995.
It was adopted in NetBSD \fIcurses\fP (2001) and PDCurses (2003).
.SH AUTHORS
Thomas Dickey (from an equivalent function written in 1988 for BSD \fIcurses\fP)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: scr_dump.5,v 1.39 2023/11/25 14:21:48 tom Exp $
-.TH scr_dump 5 2023-11-25 "ncurses 6.4" "File formats"
+.\" $Id: scr_dump.5,v 1.40 2023/12/16 21:07:24 tom Exp $
+.TH scr_dump 5 2023-12-16 "ncurses 6.4" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.bP
The ncurses6 \fBgetwin\fP reads the legacy screen dumps from ncurses5.
.SS ncurses5 (legacy)
-The screen-dump feature was added to ncurses in June 1995.
+The screen-dump feature was added to \fI\%ncurses\fP in June 1995.
While there were fixes and improvements in succeeding years,
the basic scheme was unchanged:
.bP
.bP
Solaris 10 (13273 bytes)
.bP
-ncurses5 (12888 bytes)
+\fI\%ncurses\fP5 (12888 bytes)
.SS Solaris
As noted above, Solaris curses has no magic number corresponding
to SVr4 curses.
ensure they are not overlooked.
.bP
Attributes are written in escaped curly braces, e.g., \*(``\e{BOLD}\*('',
-and may include a color-pair (C1 or C2 in this example).
+and may include a color pair (C1 or C2 in this example).
.bP
The parameters in the header are written out only if they are nonzero.
When reading back, order does not matter.
.SH AUTHORS
Thomas E. Dickey
.br
-extended screen-dump format for ncurses 6.0 (2015)
+extended screen-dump format for \fI\%ncurses\fP 6.0 (2015)
.sp
Eric S. Raymond
.br
-screen dump feature in ncurses 1.9.2d (1995)
+screen dump feature in \fI\%ncurses\fP 1.9.2d (1995)
.SH SEE ALSO
\fB\%curs_scr_dump\fP(3X),
\fB\%curs_util\fP(3X)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tabs.1,v 1.50 2023/11/25 14:32:36 tom Exp $
-.TH @TABS@ 1 2023-11-25 "ncurses 6.4" "User commands"
+.\" $Id: tabs.1,v 1.51 2023/12/17 00:13:57 tom Exp $
+.TH @TABS@ 1 2023-12-16 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
option, but not to modify the terminal settings.
.TP
\fB\-V\fP
-reports the version of ncurses which was used in this program, and exits.
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
.PP
The \fB@TABS@\fP program processes a single list of tab stops.
The last option to be processed which defines a list is the one that
.PP
The \fB\-d\fP (debug) and \fB\-n\fP (no-op) options are extensions not provided
by other implementations.
-.PP
+.SH HISTORY
A \fBtabs\fP utility appeared in PWB/Unix 1.0 (1977).
-There was a reduced version of the \fBtabs\fP utility
-in Unix 7th edition and in 3BSD (1979).
-The latter supported a single \*(``\-n\*('' option
-(to cause the first tab stop to be set on the left margin).
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=PWB1/sys/source/s2/\
+.\" tabs.c
+A reduced version shipped in Seventh Edition Unix
+(early 1979)
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/src/cmd/tabs.c
+and in 3BSD
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=3BSD/usr/src/cmd/\
+.\" tabs.c
+(later the same year);
+it supported a \*(``\-n\*('' option to set the first tab stop at the
+left margin.
That option is not documented by POSIX.
.PP
-The PWB/Unix \fBtabs\fP utility, which was included in System III (1980),
-used built-in tables rather than the terminal database,
+The PWB/Unix \fBtabs\fP utility returned in System III (1980),
+and used built-in tables rather than the terminal database,
to support a half-dozen hardcopy terminal (printer) types.
-It also had built-in logic to support the left-margin,
+It also had built-in logic to support setting the left margin,
as well as a feature for copying the tab settings from a file.
.PP
-Later versions of Unix, e.g., SVr4,
+Versions of the program in later releases of AT&T Unix,
+such as SVr4,
+.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=SysVR4/cmd/tabs/tabs.c
added support for the terminal database,
-but kept the tables to support the printers.
+but retained the tables to support the printers.
In an earlier development effort,
-the tab-stop initialization provided by \fBtset\fP (1982)
-and incorporated into \fBtput\fP uses the terminal database,
+the tab stop initialization provided by \fBtset\fP(1) (1982),
+and incorporated into \fBtput\fP(1) uses the terminal database,
.PP
-The \fB+m\fP option was documented
-in the Base Specifications Issue 5 (Unix98, 1997),
-and omitted in Issue 6 (Unix03, 2004) without documenting the rationale,
+The \fB+m\fP option was documented in the POSIX
+Base Specifications Issue 5
+(Unix98, 1997),
+then omitted in Issue 6
+(Unix03, 2004)
+without express motivation,
though an introductory comment
\fI\*(``and optionally adjusts the margin\*(''\fP remains,
overlooked in the removal.
-The documented \fBtabs\fP utility in Issues 6 and later has no mechanism
+The \fBtabs\fP utility documented in Issues 6 and later has no mechanism
for setting margins.
-The \fB+m\fP option in this implementation differs from the feature
-in SVr4 by using terminal capabilities rather than built-in tables.
+The \fB+m\fP option in
+.I \%ncurses
+\fBtabs\fP differs from the SVr4 feature by using terminal capabilities
+rather than built-in tables.
.PP
-POSIX documents no limits on the number of tab stops.
-Documentation for other implementations states that there is a limit on the
-number of tab stops
-(e.g., 20 in PWB/Unix's \fBtabs\fP utility).
-While some terminals may not accept an arbitrary number
-of tab stops, this implementation will attempt to set tab stops up to the
-right margin of the screen, if the given list happens to be that long.
+POSIX documents no limit on the number of tab stops.
+Other implementations impose one;
+the limit is 20 in PWB/Unix's \fBtabs\fP utility.
+While some terminals may not accept an arbitrary number of tab stops,
+.I \%ncurses
+\fBtabs\fP attempts to set tab stops up to the right margin if the list
+thereof is sufficiently long.
.PP
-The \fIRationale\fP section of the POSIX documentation goes into some
-detail about the ways the committee considered redesigning the
-\fBtabs\fP and \fBtput\fP utilities,
-without proposing an improved solution.
-It comments that
+The \*(``Rationale\*('' section of the Issue 6 \fBtabs\fP reference page
+.\" https://pubs.opengroup.org/onlinepubs/009604499/utilities/tabs.html
+details how the committee considered redesigning the \fBtabs\fP and
+\fBtput\fP utilities,
+without settling on an improved solution.
+It claims that
.RS 5
.PP
no known historical version of tabs supports the capability of setting
arbitrary tab stops.
.RE
.PP
-However, the \fIExplicit Lists\fP described in this manual page
-were implemented in PWB/Unix.
-Those provide the capability of setting abitrary tab stops.
+Nevertheless,
+the feature described in subsection \*(``Explicit Lists\*('' above was
+implemented in PWB/Unix,
+and permits the setting of abitrary tab stops.
.SH SEE ALSO
\fB\%@INFOCMP@\fP(1M),
\fB\%@TSET@\fP(1),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: term.5,v 1.67 2023/12/02 20:49:04 tom Exp $
-.TH term 5 2023-12-02 "ncurses 6.4" "File formats"
+.\" $Id: term.5,v 1.68 2023/12/16 20:32:22 tom Exp $
+.TH term 5 2023-12-16 "ncurses 6.4" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.SH DESCRIPTION
.SS STORAGE LOCATION
Compiled terminfo descriptions are placed under the directory \fB\*d\fP.
-Two configurations are supported (when building the \fBncurses\fP libraries):
+Two configurations are supported
+(when building the \fI\%ncurses\fP libraries):
.TP 5
.B directory tree
A two-level scheme is used to avoid a linear search
and records containing only aliases pointing to the primary name.
.IP
If built to write hashed databases,
-\fBncurses\fP can still read terminfo databases organized as a directory tree,
+\fI\%ncurses\fP can still read terminfo databases organized as a
+directory tree,
but cannot write entries into the directory tree.
It can write (or rewrite) entries in the hashed database.
.IP
-\fBncurses\fP distinguishes the two cases in the \fI\%TERMINFO\fP and
+\fI\%ncurses\fP distinguishes the two cases in the \fI\%TERMINFO\fP and
\fI\%TERMINFO_DIRS\fP environment variable by assuming a directory tree
for entries that correspond to an existing directory,
and hashed database otherwise.
the same binary format is used in all modern Unix systems.
Each system uses a predefined set of boolean, number or string capabilities.
.PP
-The \fBncurses\fP libraries and applications support
+The \fI\%ncurses\fP libraries and applications support
extended terminfo binary format,
allowing users to define capabilities which are loaded at runtime.
This
extension is made possible by using the fact that the other implementations
stop reading the terminfo data when they have reached the end of the size given
in the header.
-\fBncurses\fP checks the size,
+\fI\%ncurses\fP checks the size,
and if it exceeds that due to the predefined data,
continues to parse according to its own scheme.
.PP
include the extended capability \fInames\fP as well as
extended capability \fIvalues\fP.
.PP
-Using the counts and sizes, \fBncurses\fP allocates arrays and reads data
-for the extended capabilities in the same order as the header information.
+Using the counts and sizes,
+\fI\%ncurses\fP allocates arrays and reads data for the extended
+capabilities in the same order as the header information.
.PP
The extended string table contains values for string capabilities.
After the end of these values, it contains the names for each of
finally strings.
.PP
By storing terminal descriptions in this way,
-\fBncurses\fP is able to provide a database useful with legacy applications,
+\fI\%ncurses\fP is able to provide a database useful with legacy
+applications,
as well as providing data for applications which need more than the
predefined capabilities.
See \fBuser_caps\fP(5) for an overview
-of the way \fBncurses\fP uses this extended information.
+of the way \fI\%ncurses\fP uses this extended information.
.PP
Applications which manipulate terminal data can use the definitions
described in \fBterm_variables\fP(3X) which associate the long capability
.
.SS EXTENDED NUMBER FORMAT
On occasion, 16-bit signed integers are not large enough.
-With \fBncurses\fP 6.1, a new format was introduced by making a few changes
+With \fI\%ncurses\fP 6.1,
+a new format was introduced by making a few changes
to the legacy format:
.bP
a different magic number (octal 01036)
except in a few less-used details
where it was found that the latter did not match X/Open Curses.
The format used by the other Unix versions
-can be matched by building ncurses
+can be matched by building \fI\%ncurses\fP
with different configuration options.
.SS Magic codes
The magic number in a binary terminfo file is the first 16-bits (two bytes).
their names.
If the underlying filesystem ignores the difference between
uppercase and lowercase,
-\fBncurses\fP represents the \*(``first character\*(''
+\fI\%ncurses\fP represents the \*(``first character\*(''
of the terminal name used as
the intermediate level of a directory tree in (two-character) hexadecimal form.
.SS Limits
-\fBncurses\fP stores compiled terminal descriptions
+\fI\%ncurses\fP stores compiled terminal descriptions
in three related formats,
described in the sections
.bP
The legacy storage format and the extended number format differ by
the types of numeric capability which they can store
(i.e., 16-bit versus 32-bit integers).
-The extended storage format introduced by ncurses 5.0 adds data to
-either of these formats.
+The extended storage format introduced by \fI\%ncurses\fP 5.0 adds data
+to either of these formats.
.PP
Some limitations apply:
.bP
.SH AUTHORS
Thomas E. Dickey
.br
-extended terminfo format for ncurses 5.0
+extended terminfo format for \fI\%ncurses\fP 5.0
.br
-hashed database support for ncurses 5.6
+hashed database support for \fI\%ncurses\fP 5.6
.br
-extended number support for ncurses 6.1
+extended number support for \fI\%ncurses\fP 6.1
.sp
Eric S. Raymond
.br
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: terminfo.head,v 1.55 2023/11/25 19:52:56 tom Exp $
-.TH terminfo 5 2023-11-25 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
+.\" $Id: terminfo.head,v 1.57 2023/12/18 01:15:58 tom Exp $
+.TH terminfo 5 2023-12-17 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
have, by specifying how to perform screen operations, and by
specifying padding requirements and initialization sequences.
.PP
-This manual describes \fBncurses\fP
+This manual describes \fI\%ncurses\fP
version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
.SS Terminfo Entry Syntax
Entries in
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: terminfo.tail,v 1.137 2023/12/03 00:17:23 tom Exp $
+.\" $Id: terminfo.tail,v 1.139 2023/12/17 22:56:21 tom Exp $
.ps +1
-.SS User-Defined Capabilities
+.SS "User-Defined Capabilities"
.
The preceding section listed the \fIpredefined\fP capabilities.
They deal with some special features for terminals no longer
are awkward or impossible to represent by reusing the predefined
capabilities.
.PP
-\fBncurses\fP addresses this limitation by allowing user-defined capabilities.
+\fI\%ncurses\fP addresses this limitation by allowing user-defined
+capabilities.
The \fB@TIC@\fP and \fB@INFOCMP@\fP programs provide
the \fB\-x\fP option for this purpose.
When \fB\-x\fP is set,
and makes an extended table entry for that capability.
The \fBuse_extended_names\fP(3X) function makes this information
conditionally available to applications.
-The ncurses library provides the data leaving most of the behavior
-to applications:
+The \fI\%ncurses\fP library provides the data leaving most of the
+behavior to applications:
.bP
User-defined capability strings whose name begins
with \*(``k\*('' are treated as function keys.
numbered keys and the handful of special named keys) is best done using
the longer names available using terminfo.
.PP
-The ncurses library uses a few of these user-defined capabilities,
+The \fI\%ncurses\fP library uses a few of these user-defined
+capabilities,
as described in \fBuser_caps\fR(5).
Other user-defined capabilities (including function keys) are
described in the terminal database, in the section on
.I "NCURSES USER-DEFINABLE CAPABILITIES"
.
-.SS A Sample Entry
+.SS "A Sample Entry"
.
The following entry, describing an ANSI-standard terminal, is representative
of what a \fBterminfo\fP entry for a modern terminal typically looks like.
string
capabilities, which give a sequence which can be used to perform particular
terminal operations.
-.SS Types of Capabilities
+.SS "Types of Capabilities"
All capabilities have names.
For instance, the fact that
ANSI-standard terminals have
in the example above.
.br
.ne 5
-.SS Fetching Compiled Descriptions
-Terminal descriptions in \fBncurses\fP are stored in terminal databases.
+.SS "Fetching Compiled Descriptions"
+Terminal descriptions in \fI\%ncurses\fP are stored in terminal
+databases.
These databases, which are found by their pathname,
may be configured either as directory trees or hashed databases
(see \fBterm\fR(5)),
The library uses a compiled-in list of pathnames,
which can be overridden by environment variables.
Before starting to search,
-\fBncurses\fP checks the search list,
+\fI\%ncurses\fP checks the search list,
eliminating duplicates and pathnames where no terminal database is found.
-The \fBncurses\fP library reads the first description
+The \fI\%ncurses\fP library reads the first description
which passes its consistency checks.
.bP
The environment variable \fBTERMINFO\fR is checked first, for
a terminal database containing the terminal description.
.bP
Next,
-\fBncurses\fP looks in \fI$HOME/.terminfo\fP
+\fI\%ncurses\fP looks in \fI$HOME/.terminfo\fP
for a compiled description.
.IP
This is an optional feature which may be omitted entirely from
.bP
Next,
if the environment variable \fI\%TERMINFO_DIRS\fP is set,
-\fBncurses\fP interprets the contents of that variable
+\fI\%ncurses\fP interprets the contents of that variable
as a list of colon-separated pathnames of terminal databases to be searched.
.IP
An empty pathname (i.e., if the variable begins or ends
with a colon, or contains adjacent colons)
is interpreted as the system location \fI\*d\fP.
.bP
-Finally, \fBncurses\fP searches these compiled-in locations:
+Finally, \fI\%ncurses\fP searches these compiled-in locations:
.RS
.bP
a list of directories (@TERMINFO_DIRS@), and
The \fBTERMINFO\fP variable can contain a terminal description instead
of the pathname of a terminal database.
If this variable begins with \*(``hex:\*('' or \*(``b64:\*(''
-then \fBncurses\fP reads a terminal description from
+then \fI\%ncurses\fP reads a terminal description from
hexadecimal- or base64-encoded data,
and if that description matches the name sought, will use that.
This encoded data can be set using the \*(``\-Q\*('' option of
\fB@TIC@\fR or \fB@INFOCMP@\fR.
.PP
-The preceding addresses the usual configuration of \fBncurses\fP,
+The preceding addresses the usual configuration of \fI\%ncurses\fP,
which uses terminal descriptions prepared in \fIterminfo\fP format.
While \fItermcap\fP is less expressive,
-\fBncurses\fP can also be configured to read \fItermcap\fP descriptions.
+\fI\%ncurses\fP can also be configured to read \fItermcap\fP
+descriptions.
In that configuration,
it checks the \fI\%TERMCAP\fP and \fI\%TERMPATH\fP variables
(for content and search path,
respectively)
after the system terminal database.
-.SS Preparing Descriptions
+.SS "Preparing Descriptions"
We now outline how to prepare descriptions of terminals.
The most effective way to prepare a terminal description is by imitating
the description of a similar terminal in
key several times quickly.
If the terminal messes up, more padding is usually needed.
A similar test can be used for insert character.
-.SS Basic Capabilities
+.SS "Basic Capabilities"
The number of columns on each line for the terminal is given by the
\fBcols\fP numeric capability.
If the terminal is a \s-1CRT\s0, then the
ind=\*^J, lines#24,\s+1
.\".in +2
.EE
-.SS Parameterized Strings
+.SS "Parameterized Strings"
Cursor addressing and other strings requiring parameters
in the terminal are described by a
parameterized string capability,
They are the same.
Like SVr4 curses, XPG4 curses does not initialize these explicitly.
.bP
-Before version 6.3, ncurses stores both \fIdynamic\fP and \fIstatic\fP
+Before version 6.3,
+\fI\%ncurses\fP stores both \fIdynamic\fP and \fIstatic\fP
variables in persistent storage, initialized to zeros.
.bP
-Beginning with version 6.3, ncurses stores \fIstatic\fP and \fIdynamic\fP
+Beginning with version 6.3,
+\fI\%ncurses\fP stores \fIstatic\fP and \fIdynamic\fP
variables in the same manner as SVr4.
.RS
.bP
-Unlike other implementations, ncurses zeros dynamic variables
+Unlike other implementations, \fI\%ncurses\fP zeros dynamic variables
before the first \fB%g\fP or \fB%P\fP operator.
.bP
Like SVr2,
-the scope of dynamic variables in ncurses
+the scope of dynamic variables in \fI\%ncurses\fP
is within the current call to
\fBtparm\fP.
Use static variables if persistent storage is needed.
in place of the two previous values) and outputs that value as a character.
Then the same is done for the second parameter.
More complex arithmetic is possible using the stack.
-.SS Cursor Motions
+.SS "Cursor Motions"
If the terminal has a fast way to home the cursor
(to very upper left corner of screen) then this can be given as
\fBhome\fP; similarly a fast way of getting to the lower left-hand corner
The \fBmgc\fP string capability should be defined.
Applications such as \fBtabs\fP(1) rely upon this to reset all margins.
.\"
-.SS Area Clears
+.SS "Area Clears"
If the terminal can clear from the current position to the end of the
line, leaving the cursor where it is, this should be given as \fBel\fP.
If the terminal can clear from the beginning of the line to the current
.B ed
is not available.)
.\"
-.SS Insert/delete line and vertical motions
+.SS "Insert/Delete Line and Vertical Motions"
If the terminal can open a new blank line before the line where the cursor
is, this should be given as \fBil1\fP; this is done only from the first
position of a line.
.B rc
(save and restore cursor) commands may be useful for ensuring that
your synthesized insert/delete string does not move the cursor.
-(Note that the \fBncurses\fP(3X) library does this synthesis
+(Note that the \fB\%ncurses\fP(3X) library does this synthesis
automatically, so you need not compose insert/delete strings for
an entry with \fBcsr\fP).
.PP
These indicate
that deleting a line or scrolling may bring non-blank lines up from below
or that scrolling back with \fBri\fP may bring down non-blank lines.
-.SS Insert/Delete Character
+.SS "Insert/Delete Character"
There are two basic kinds of intelligent terminals with respect to
insert/delete character which can be described using
.I terminfo.
specify the capability \fBos\fP.
If overstrikes are erasable with a blank,
then this should be indicated by giving \fBeo\fP.
-.SS Keypad and Function Keys
+.SS "Keypad and Function Keys"
If the terminal has a keypad that transmits codes when the keys are pressed,
this information can be given.
Note that it is not possible to handle
give them in \fBsmln\fP and \fBrmln\fP.
\fBsmln\fP is normally output after one or more pln
sequences to make sure that the change becomes visible.
-.SS Tabs and Initialization
+.SS "Tabs and Initialization"
A few capabilities are used only for tabs:
.bP
If the terminal has hardware tabs, the command to advance to the next
\fBhts\fP (\fBset_tab\fP) capabilities directly
only when the \fBit\fP (\fBinit_tabs\fP) capability
is set to a value other than \fIeight\fP.
-.SS Delays and Padding
+.SS "Delays and Padding"
Many older and slower terminals do not support either XON/XOFF or DTR
handshaking, including hard copy terminals and some very archaic CRTs
(including, for example, DEC VT100s).
Only the first character of the
.B pad
string is used.
-.SS Status Lines
+.SS "Status Lines"
Some terminals have an extra \*(``status line\*('' which is not normally used by
software (and thus not counted in the terminal's \fBlines\fP capability).
.PP
The boolean capability \fBeslok\fP specifies that escape sequences, tabs,
etc., work ordinarily in the status line.
.PP
-The \fBncurses\fP implementation does not yet use any of these capabilities.
+The \fI\%ncurses\fP implementation does not yet use any of these
+capabilities.
They are documented here in case they ever become important.
-.SS Line Graphics
+.SS "Line Graphics"
Many terminals have alternate character sets useful for forms-drawing.
Terminfo and \fBcurses\fP have built-in support
for most of the drawing characters
as the corresponding graphic.
Then read off the VT100/your terminal
character pairs right to left in sequence; these become the ACSC string.
-.SS Color Handling
+.SS "Color Handling"
The curses library functions \fBinit_pair\fP and \fBinit_color\fP
manipulate the \fIcolor pairs\fP and \fIcolor values\fP discussed in this
section
(where \fIN\fP is usually 8),
and can set
character-cell foreground and background characters independently, mixing them
-into \fIN\fP\ *\ \fIN\fP color-pairs.
+into \fIN\fP\ *\ \fIN\fP color pairs.
.bP
On HP-like terminals, the user must set each color
pair up separately (foreground and background are not independently settable).
-Up to \fIM\fP color-pairs may be set up from 2*\fIM\fP different colors.
+Up to \fIM\fP color pairs may be set up from 2*\fIM\fP different colors.
ANSI-compatible terminals are Tektronix-like.
.PP
Some basic color capabilities are independent of the color method.
The numeric
capabilities \fBcolors\fP and \fBpairs\fP specify the maximum numbers of colors
-and color-pairs that can be displayed simultaneously.
+and color pairs that can be displayed simultaneously.
The \fBop\fP (original
pair) string resets foreground and background colors to their default values
for the terminal.
-The \fBoc\fP string resets all colors or color-pairs to
+The \fBoc\fP string resets all colors or 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
single numeric argument each.
Argument values 0-7 of \fBsetaf\fP/\fBsetab\fP are portably defined as
follows (the middle column is the symbolic #define available in the header for
-the \fBcurses\fP or \fBncurses\fP libraries).
+the \fBcurses\fP or \fI\%ncurses\fP libraries).
The terminal hardware is free to
map these as it likes, but the RGB values indicate normal locations in color
space.
It is important to not confuse the two sets of color capabilities;
otherwise red/blue will be interchanged on the display.
.PP
-On an HP-like terminal, use \fBscp\fP with a color-pair number parameter to set
+On an HP-like terminal, use \fBscp\fP with a color pair number parameter to set
which color pair is current.
.PP
Some terminals allow the \fIcolor values\fP to be modified:
terminal-dependent.
.bP
On an HP-like terminal, \fBinitp\fP may give a capability for changing a
-color-pair value.
-It will take seven parameters; a color-pair number (0 to
+color pair value.
+It will take seven parameters; a color pair number (0 to
\fBmax_pairs\fP \- 1), and two triples describing first background and then
foreground colors.
These parameters must be (Red, Green, Blue) or
On some color terminals, colors collide with highlights.
You can register
these collisions with the \fBncv\fP capability.
-This is a bit-mask of
+This is a bit mask of
attributes not to be used when colors are enabled.
The correspondence with the
attributes understood by \fBcurses\fP is as follows:
These should have
an \fBncv\fP capability of 2.
.PP
-SVr4 curses does nothing with \fBncv\fP, ncurses recognizes it and optimizes
+SVr4 curses does nothing with \fBncv\fP,
+\fI\%ncurses\fP recognizes it and optimizes
the output in favor of colors.
.SS Miscellaneous
If the terminal requires other than a null (zero) character as a pad, then this
can be given as pad.
Only the first character of the pad string is used.
If the terminal does not have a pad character, specify npc.
-Note that ncurses implements the termcap-compatible \fBPC\fP variable;
+Note that \fI\%ncurses\fP implements the termcap-compatible \fBPC\fP
+variable;
though the application may set this value to something other than
-a null, ncurses will test \fBnpc\fP first and use napms if the terminal
+a null,
+\fI\%ncurses\fP will test \fBnpc\fP first and use napms if the terminal
has no pad character.
.PP
If the terminal can move up or down half a line,
is transparently passed to the printer while an
.B mc5p
is in effect.
-.SS Glitches and Braindamage
+.SS "Glitches and Brain Damage"
Hazeltine terminals,
which do not allow \*(``\*~\*('' characters to be displayed should
indicate \fBhz\fP.
the cursor on top of a \*(``magic cookie\*('',
that to erase standout mode it is instead necessary to use
delete and insert line.
-The ncurses implementation ignores this glitch.
+The \fI\%ncurses\fP implementation ignores this glitch.
.PP
The Beehive Superbee, which is unable to correctly transmit the escape
or control/C characters, has
.PP
Other specific terminal problems may be corrected by adding more
capabilities of the form \fBx\fIx\fR.
-.SS Pitfalls of Long Entries
+.SS "Pitfalls of Long Entries"
Long terminfo entries are unlikely to be a problem; to date, no entry has even
approached terminfo's 4096-byte string-table maximum.
Unfortunately, the termcap
terminal types and users whose \fITERM\fP variable does not have a termcap
entry.
.PP
-When in \-C (translate to termcap) mode, the \fBncurses\fP implementation of
+When in \-C (translate to termcap) mode,
+the \fI\%ncurses\fP implementation of
\fB@TIC@\fP(1M) issues warning messages when the pre-tc length of a termcap
translation is too long.
The \-c (check) option also checks resolved (after tc
expansion) lengths.
-.SH PORTABILITY
-Do not count on compiled (binary) \fI\%terminfo\fP entries being
-portable between commercial Unix systems.
-At least two implementations of \fI\%terminfo\fP
-(those of HP-UX and AIX)
-diverged from those of other System V Unices after SVr1,
-adding extension capabilities to the string table that
-(in the binary format)
-collide with subsequent System V and XSI Curses extensions.
+.SH FILES
+.TP
+.I \*d
+compiled terminal description database directory
.SH EXTENSIONS
Searching for terminal descriptions in
\fI$HOME/.terminfo\fP and \fI\%TERMINFO_DIRS\fP
SVr4/XPG4 do not specify whether \fBmsgr\fP licenses movement while in
an alternate-character-set mode (such modes may, among other things, map
CR and NL to characters that do not trigger local motions).
-The \fBncurses\fP implementation ignores \fBmsgr\fP in \fBALTCHARSET\fP
-mode.
+The \fI\%ncurses\fP implementation ignores \fBmsgr\fP in
+\fBALTCHARSET\fP mode.
This raises the possibility that an XPG4
implementation making the opposite interpretation may need terminfo
-entries made for \fBncurses\fP to have \fBmsgr\fP turned off.
+entries made for \fI\%ncurses\fP to have \fBmsgr\fP turned off.
.PP
-The \fBncurses\fP library handles insert-character and insert-character modes
-in a slightly non-standard way to get better update efficiency.
+The \fI\%ncurses\fP library handles insert-character and
+insert-character modes in a slightly non-standard way to get better
+update efficiency.
See
the \fBInsert/Delete Character\fP subsection above.
.PP
documentation for the AT&T 505 terminal.
.PP
Be careful assigning the \fBkmous\fP capability.
-The \fBncurses\fP library wants to interpret it as \fBKEY_MOUSE\fP,
+The \fI\%ncurses\fP library wants to interpret it as \fBKEY_MOUSE\fP,
for use by terminals and emulators like xterm
that can return mouse-tracking information in the keyboard-input stream.
.PP
plus a number of incompatible string table extensions.
.bP
OSF/1 supports both the SVr4 set and the AIX extensions.
-.SH FILES
-.TP
-.I \*d
-compiled terminal description database directory
+.SH PORTABILITY
+Do not count on compiled (binary) \fI\%terminfo\fP entries being
+portable between commercial Unix systems.
+At least two implementations of \fI\%terminfo\fP
+(those of HP-UX and AIX)
+diverged from those of other System V Unices after SVr1,
+adding extension capabilities to the string table that
+(in the binary format)
+collide with subsequent System V and XSI Curses extensions.
.SH AUTHORS
Zeyd M. Ben-Halim, Eric S. Raymond, Thomas E. Dickey.
Based on \fIpcurses\fP by Pavel Curtis.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tic.1m,v 1.103 2023/12/02 20:50:53 tom Exp $
-.TH @TIC@ 1M 2023-12-02 "ncurses 6.4" "User commands"
+.\" $Id: tic.1m,v 1.104 2023/12/16 20:33:11 tom Exp $
+.TH @TIC@ 1M 2023-12-16 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
The \fB@TIC@\fP command translates a \fBterminfo\fP file from source
format into compiled format.
The compiled format is necessary for use with
-the library routines in \fBncurses\fP(3X).
+the library routines in \fB\%ncurses\fP(3X).
.PP
As described in \fBterm\fP(5), the database may be either a directory
tree (one file per terminal entry) or a hashed database (one record per entry).
Force source translation to terminfo format.
.TP
\fB\-K\fP
-Suppress some longstanding ncurses extensions to termcap format,
+Suppress some longstanding \fI\%ncurses\fP extensions to termcap format,
e.g., "\es" for space.
.TP
\fB\-L\fP
or in termcaps.
.TP
\fB\-V\fP
-reports the version of ncurses which was used in this program, and exits.
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
.TP
\fB\-v\fIn\fR
specifies that (verbose) output be written to standard error trace
indicating the desired level of detail of information.
.RS
.bP
-If ncurses is built without tracing support, the optional parameter is ignored.
+If \fI\%ncurses\fP is built without tracing support,
+the optional parameter is ignored.
.bP
If \fIn\fP is omitted, the default level is 1.
.bP
\fB\-x\fP
.RE
.bP
-The NetBSD \fBtic\fP supports a few of the ncurses options
+The NetBSD \fBtic\fP supports a few of the \fI\%ncurses\fP options
.sp
.RS
\fB\-a\fP
Shortly after Issue 7 was released, Tru64 was discontinued.
As of 2019, the surviving implementations of \fBtic\fP
are SVr4 (AIX, HP-UX and Solaris),
-ncurses
+\fI\%ncurses\fP
and NetBSD curses.
The SVr4 \fBtic\fP programs all support the \fB\-v\fP option.
The NetBSD \fBtic\fP program follows X/Open's documentation,
continued with System V Release 4,
the table of capabilities grew from 180 (\fIpcurses\fP) to 464 (Solaris).
.PP
-In early development of ncurses (1993),
+In early development of \fI\%ncurses\fP (1993),
Zeyd Ben-Halim used the table from \fImytinfo\fP to
extend the \fIpcurses\fP table to 469 capabilities
(456 matched SVr4, 8 were only in SVr4, 13 were not in SVr4).
\fB\%memory_lock_above\fP and
\fB\%memory_unlock\fP (see \fB\%user_caps\fP(5)).
.PP
-Eric Raymond incorporated parts of \fImytinfo\fP into ncurses
+Eric Raymond incorporated parts of \fImytinfo\fP into \fI\%ncurses\fP
to implement the termcap-to-terminfo source conversion,
and extended that to begin development of
the corresponding terminfo-to-termcap source conversion,
.PP
In 2010, Roy Marples provided a \fBtic\fP program
and terminfo library for NetBSD.
-That implementation adapts several features from ncurses,
+That implementation adapts several features from \fI\%ncurses\fP,
including \fB@TIC@\fP's \fB\-x\fP option.
.PP
The \fB\-c\fP option tells \fB@TIC@\fP to check for problems in the
.bP
\fIpcurses\fP had 8 warnings
.bP
-ncurses in 1996 had 16 warnings
+\fI\%ncurses\fP in 1996 had 16 warnings
.bP
Solaris (SVr4) curses has 28 warnings
.bP
NetBSD tic in 2019 has 19 warnings.
.bP
-ncurses in 2019 has 96 warnings
+\fI\%ncurses\fP in 2019 has 96 warnings
.PP
-The checking done in ncurses' \fB@TIC@\fP helps with the conversion to
-termcap, as well as pointing out errors and inconsistencies.
+The checking done in \fI\%ncurses\fP' \fB@TIC@\fP helps with the
+conversion to termcap,
+as well as pointing out errors and inconsistencies.
It is also used to ensure consistency with the user-defined capabilities.
-There are 527 distinct capabilities in ncurses' terminal database;
+There are 527 distinct capabilities in \fI\%ncurses\fP' terminal
+database;
128 of those are user-defined.
.SH AUTHORS
Eric S. Raymond <esr@snark.thyrsus.com>
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: toe.1m,v 1.58 2023/12/02 20:49:04 tom Exp $
-.TH @TOE@ 1M 2023-12-02 "ncurses 6.4" "User commands"
+.\" $Id: toe.1m,v 1.59 2023/12/16 21:01:59 tom Exp $
+.TH @TOE@ 1M 2023-12-16 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB\%@TOE@\fP reports to the standard output stream the (primary) names
and descriptions of the terminal types available to the \fIterminfo\fP
library.
-Each \fIdirectory\fP operand is scanned;
+Each \fIdirectory\fP is scanned;
if none are given,
-\fB\%@TOE@\fP scans the the default \fIterminfo\fP directory.
+\fB\%@TOE@\fP scans the default \fIterminfo\fP directory.
.SH OPTIONS
The \fB\-h\fP option can be helpful to observe where \fB\%@TOE@\fP is
looking for terminal descriptions.
.IP
The optional parameter \fIn\fP is an integer between 1 and 10 inclusive,
interpreted as for \fB\%@TIC@\fP(1M).
-If \fIncurses\fP is built without tracing support,
+If \fI\%ncurses\fP is built without tracing support,
\fIn\fP is ignored.
.TP
\fB\-V\fP
-reports the version of \fIncurses\fP associated
+reports the version of \fI\%ncurses\fP associated
with this program and exits with a successful status.
.SH FILES
.TP
There is no applicable X/Open or POSIX standard for it.
.PP
It replaces a \fB\-T\fP option that was briefly supported by
-the \fIncurses\fP \fB\%infocmp\fP utility in 1995.
+the \fI\%ncurses\fP \fB\%infocmp\fP utility in 1995.
.PP
The \fB\-a\fP and \fB\-s\fP options were added in 2006 and 2011,
respectively.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tput.1,v 1.91 2023/12/02 20:49:04 tom Exp $
-.TH @TPUT@ 1 2023-12-02 "ncurses 6.4" "User commands"
+.\" $Id: tput.1,v 1.92 2023/12/16 20:32:22 tom Exp $
+.TH @TPUT@ 1 2023-12-16 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
variables \fILINES\fP and \fI\%COLUMNS\fP will also be ignored.
.TP
\fB\-V\fP
-reports the version of ncurses which was used in this program, and exits.
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
.TP
.B \-x
prevents \fB\%@TPUT@\fP from attempting to clear the scrollback buffer.
same effect as \fB@TPUT@ reset\fP.
The \fB@TSET@\fP(1) utility also treats a link named \fBreset\fP specially.
.PP
-Before ncurses 6.1, the two utilities were different from each other:
+Before \fI\%ncurses\fP 6.1,
+the two utilities were different from each other:
.bP
\fB@TSET@\fP utility reset the terminal modes and special characters
(not done with \fB@TPUT@\fP).
The \fBreset\fP program is usually an alias for \fB@TSET@\fP,
because of this difference with resetting terminal modes and special characters.
.PP
-With the changes made for ncurses 6.1, the \fIreset\fP feature of the
-two programs is (mostly) the same.
+With the changes made for \fI\%ncurses\fP 6.1,
+the \fIreset\fP feature of the two programs is (mostly) the same.
A few differences remain:
.bP
The \fB@TSET@\fP program waits one second when resetting,
a 1200Bd terminal.
When updating terminal modes, it ignores errors.
.IP
-Until changes made after ncurses 6.0,
+Until changes made after \fI\%ncurses\fP 6.0,
\fB@TPUT@\fP did not modify terminal modes.
\fB@TPUT@\fP now uses a similar scheme,
using functions shared with \fB@TSET@\fP
.IP
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 ncurses
-to port NetBSD's termcap-based \fBtput\fP to terminfo.
+An OpenBSD developer adapted the internal library function from
+\fI\%ncurses\fP to port NetBSD's termcap-based \fBtput\fP to terminfo.
That had been modified to interpret multiple commands on a line.
Portable applications should not rely upon this feature;
-ncurses provides it to support applications written
+\fI\%ncurses\fP provides it to support applications written
specifically for OpenBSD.
.PP
This implementation (unlike others) can accept both \fItermcap\fP
Since 2010, NetBSD's \fBtput\fP uses terminfo names.
Before that, it (like FreeBSD) recognized termcap names.
.IP
-Beginning in 2021, FreeBSD uses the ncurses \fBtput\fP,
+Beginning in 2021, FreeBSD uses the \fI\%ncurses\fP \fBtput\fP,
configured for both terminfo (tested first) and termcap (as a fallback).
.PP
Because (apparently) \fIall\fP of the certified Unix systems
or cancelled numeric value versus an (unsigned) exit code.
.PP
The various Unix systems (AIX, HP-UX, Solaris) use the same exit-codes
-as ncurses.
+as \fI\%ncurses\fP.
.PP
NetBSD curses documents different exit codes which do not correspond
-to either ncurses or X/Open.
+to either \fI\%ncurses\fP or X/Open.
.SH HISTORY
The \fBtput\fP command was begun by Bill Joy in 1980.
The initial version only cleared the screen.
Ridge's program made more sophisticated use of the terminal capabilities
than the BSD program.
Eric Raymond used that \fBtput\fP program
-(and other parts of \fImytinfo\fP) in ncurses in June 1995.
+(and other parts of \fImytinfo\fP) in \fI\%ncurses\fP in June 1995.
Using the portions dealing with terminal capabilities
almost without change,
Raymond made improvements to the way the command-line parameters
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tset.1,v 1.77 2023/12/02 20:52:24 tom Exp $
-.TH @TSET@ 1 2023-12-02 "ncurses 6.4" "User commands"
+.\" $Id: tset.1,v 1.78 2023/12/16 20:32:22 tom Exp $
+.TH @TSET@ 1 2023-12-16 "ncurses 6.4" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
see subsection \*(``Setting the Environment\*(''.
.TP
.B \-V
-reports the version of ncurses which was used in this program, and exits.
+reports the version of \fI\%ncurses\fP which was used in this program,
+and exits.
.TP
.B \-w
Resize the window to match the size deduced via \fBsetupterm\fP(3X).
.PP
A few options are different
because the \fI\%TERMCAP\fP variable
-is no longer supported under terminfo-based \fBncurses\fP:
+is no longer supported under terminfo-based \fI\%ncurses\fP:
.bP
The \fB\-S\fP option of BSD \fBtset\fP no longer works;
it prints an error message to the standard error and dies.
to set the window size if \fBtset\fP is not able to obtain the window
size from the operating system.
.bP
-In ncurses, \fB@TSET@\fP obtains the window size using
+In \fI\%ncurses\fP, \fB@TSET@\fP obtains the window size using
\fBsetupterm\fP, which may be from
the operating system,
the \fILINES\fP and \fICOLUMNS\fP environment variables or
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: user_caps.5,v 1.41 2023/10/07 21:19:07 tom Exp $
-.TH user_caps 5 2023-10-07 "ncurses 6.4" "File formats"
+.\" $Id: user_caps.5,v 1.42 2023/12/16 20:32:22 tom Exp $
+.TH user_caps 5 2023-12-16 "ncurses 6.4" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.B @TIC@ \-x
.SH DESCRIPTION
.SS Background
-Before ncurses 5.0,
+Before \fI\%ncurses\fP 5.0,
terminfo databases used a \fIfixed repertoire\fP of terminal
capabilities designed for the SVr2 terminal database in 1984,
and extended in stages through SVr4 (1989),
the position in the tables differs because some features were added as needed,
while others were added (out of order) to comply with X/Open Curses.
.IP
-While ncurses' repertoire of predefined capabilities is closest to Solaris,
+While \fI\%ncurses\fP' repertoire of predefined capabilities is closest
+to Solaris,
Solaris's terminfo database has a few differences from
the list published by X/Open Curses.
-For example, ncurses can be configured with tables which match the
-terminal databases for AIX, HP-UX or OSF/1,
+For example,
+\fI\%ncurses\fP can be configured with tables which match the terminal
+databases for AIX, HP-UX or OSF/1,
rather than the default Solaris-like configuration.
.bP
-In SVr4 curses and ncurses,
+In SVr4 curses and \fI\%ncurses\fP,
the terminal database is defined at compile-time using a text file
which lists the different terminal capabilities.
.IP
In principle, the text-file can be extended,
but doing this requires recompiling and reinstalling the library.
-The text-file used in ncurses for terminal capabilities includes
+The text-file used in \fI\%ncurses\fP for terminal capabilities includes
details for various systems past the documented X/Open Curses features.
-For example, ncurses supports these capabilities in each configuration:
+For example, \fI\%ncurses\fP supports these capabilities in each configuration:
.RS 8
.TP 5
memory_lock
Although termcap's extensibility was rarely used
(it was never the \fIspeaker\fP who had actually used the feature),
the criticism had a point.
-ncurses 5.0 provided a way to detect nonstandard capabilities,
+\fI\%ncurses\fP 5.0 provided a way to detect nonstandard capabilities,
determine their
type and optionally store and retrieve them in a way which did not interfere
with other applications.
These are referred to as \fIuser-defined capabilities\fP because no
modifications to the toolset's predefined capability names are needed.
.PP
-The ncurses utilities \fB@TIC@\fP and \fB@INFOCMP@\fP have a command-line
-option \*(``\-x\*('' to control whether the nonstandard capabilities
-are stored or retrieved.
+The \fI\%ncurses\fP utilities \fB@TIC@\fP and \fB@INFOCMP@\fP have a
+command-line option \*(``\-x\*('' to control whether the nonstandard
+capabilities are stored or retrieved.
A library function \fBuse_extended_names\fP
is provided for the same purpose.
.PP
\fB@TIC@\fP will store a user-defined capability if the capability name is not
one of the predefined names.
.PP
-Because ncurses provides a termcap library interface,
+Because \fI\%ncurses\fP provides a termcap library interface,
these user-defined capabilities may be visible to termcap applications:
.bP
The termcap interface (like all implementations of termcap)
to which a series of keys can be assigned,
that is insufficient for more than a dozen keys multiplied by more than
a couple of modifier combinations.
-The ncurses database uses a convention based on \fBxterm\fP(1) to
-provide extended special-key names.
+The \fI\%ncurses\fP database uses a convention based on \fBxterm\fP(1)
+to provide extended special-key names.
.IP
Fitting that into termcap's limitation of 2-character names
would be pointless.
These extended keys are available only with terminfo.
.SS Recognized capabilities
-The ncurses library uses the user-definable capabilities.
+The \fI\%ncurses\fP library uses the user-definable capabilities.
While the terminfo database may have other extensions,
-ncurses makes explicit checks for these:
+\fI\%ncurses\fP makes explicit checks for these:
.RS 3
.TP 3
AX
.TP 3
NQ
\fIboolean\fP,
-used to suppress a consistency check in @TIC@ for the ncurses capabilities
+used to suppress a consistency check in @TIC@ for the \fI\%ncurses\fP
+capabilities
in user6 through user9 (u6, u7, u8 and u9)
which tell how to query the terminal's cursor position
and its device attributes.
return appropriate values without requiring the application
to initialize colors using \fBinit_color\fP.
.IP
-The capability type determines the values which ncurses sees:
+The capability type determines the values which \fI\%ncurses\fP sees:
.RS 3
.TP 3
\fIboolean\fP
implies that the number of bits for red, green and blue are the same.
Using the maximum number of colors,
-ncurses adds two, divides that sum by three, and assigns the result
-to red, green and blue in that order.
+\fI\%ncurses\fP adds two,
+divides that sum by three,
+and assigns the result to red,
+green and blue in that order.
.IP
If the number of bits needed for the number of colors is not a multiple
of three, the blue (and green) components lose in comparison to red.
.TP 3
\fInumber\fP
-tells ncurses what result to add to red, green and blue.
-If ncurses runs out of bits,
+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.
.TP 3
\fIstring\fP
.TP 3
U8
\fInumber\fP,
-asserts that ncurses must use Unicode values for line-drawing characters,
+asserts that \fI\%ncurses\fP must use Unicode values for line-drawing
+characters,
and that it should ignore the alternate character set capabilities
when the locale uses UTF-8 encoding.
For more information, see the discussion of
-\fBNCURSES_NO_UTF8_ACS\fP in \fBncurses\fP(3X).
+\fBNCURSES_NO_UTF8_ACS\fP in \fB\%ncurses\fP(3X).
.IP
Set this capability to a nonzero value to enable it.
.TP 3
XM
\fIstring\fP,
-override ncurses's built-in string which
+override \fI\%ncurses\fP's built-in string which
enables/disables \fBxterm\fP(1) mouse mode.
.IP
-ncurses sends a character sequence to the terminal to initialize mouse mode,
+\fI\%ncurses\fP sends a character sequence to the terminal to initialize mouse mode,
and when the user clicks the mouse buttons or (in certain modes) moves the
mouse, handles the characters sent back by the terminal to tell it what
was done with the mouse.
.IP
The mouse protocol is enabled when
the \fImask\fP passed in the \fBmousemask\fP function is nonzero.
-By default, ncurses handles the responses for the X11 xterm mouse protocol.
+By default,
+\fI\%ncurses\fP handles the responses for the X11 xterm mouse protocol.
It also knows about the \fISGR 1006\fP xterm mouse protocol,
but must to be told to look for this specifically.
It will not be able to guess which mode is used,
The \fBXM\fP capability has a single parameter.
If nonzero, the mouse protocol should be enabled.
If zero, the mouse protocol should be disabled.
-ncurses inspects this capability if it is present,
+\fI\%ncurses\fP inspects this capability if it is present,
to see whether the 1006 protocol is used.
If so, it expects the responses to use the \fISGR 1006\fP xterm mouse protocol.
.IP
Since 1999, \fBxterm\fP(1) has supported
\fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce
distinct special-key strings.
-In a terminal description, ncurses has no special knowledge of the
-modifiers used.
+In a terminal description,
+\fI\%ncurses\fP has no special knowledge of the modifiers used.
Applications can use the \fInaming convention\fP established for \fBxterm\fP
to find these special keys in the terminal description.
.PP
Starting with the curses convention that \fIkey names\fP begin with \*(``k\*(''
and that shifted special keys are an uppercase name,
-ncurses' terminal database defines these names to which a suffix is added:
+\fI\%ncurses\fP' terminal database defines these names to which a suffix
+is added:
.PP
.RS 5
.TS
.RE
.PP
None of these are predefined; terminal descriptions can refer to \fInames\fP
-which ncurses will allocate at runtime to \fIkey-codes\fP.
-To use these keys in an ncurses program, an application could do this:
+which \fI\%ncurses\fP will allocate at runtime to \fIkey-codes\fP.
+To use these keys in an \fI\%ncurses\fP program,
+an application could do this:
.bP
using a list of extended key \fInames\fP,
ask \fBtigetstr\fP(3X) for their values, and
.SH AUTHORS
Thomas E. Dickey
.br
-beginning with ncurses 5.0 (1999)
+beginning with \fI\%ncurses\fP 5.0 (1999)
.\"
.SH SEE ALSO
\fB\%@INFOCMP@\fP(1M),
# Report bugs and new terminal descriptions to
# bug-ncurses@gnu.org
#
-# $Revision: 1.1083 $
-# $Date: 2023/12/09 18:07:12 $
+# $Revision: 1.1085 $
+# $Date: 2023/12/16 13:48:44 $
#
# 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
kich1=\E[2z, knp=\E[222z, kpp=\E[216z, kund=\E[195z,
use=xterm+nofkeys, use=xterm+nopcfkeys,
xterms-sun|small (80x24) xterm with sunFunctionKeys true,
- cols#80, lines#24, use=xterm-sun,
+ use=xterm-sun,
#### GNOME (VTE)
# this describes the alpha-version of GNOME terminal shipped with Redhat 6.0
sun-48|Sun 48-line window,
cols#80, lines#48, use=sun,
sun-34|Sun 34-line window,
- cols#80, lines#34, use=sun,
+ use=sun,
sun-24|Sun 24-line window,
cols#80, lines#24, use=sun,
sun-17|Sun 17-line window,
blink=\EG2, invis=\EG1, rev=\EG4, rmso=\EG0, rmul=\EG0,
sgr=\E%%\E(%?%p5%p8%|%t\E)%;%?%p9%t\E$%;\EG%{48}%?%p7%t%{1}
%+%;%?%p4%t%{2}%+%;%?%p3%p1%|%t%{4}%+%;%?%p2%t%{8}%+%;%c,
- sgr0=\EG0\E%%\E(, smso=\EG4, smul=\EG8, use=ndr9500,
+ smso=\EG4, smul=\EG8, use=ndr9500,
ndr9500-25-mc|NDR 500 with 25 lines and magic cookies,
lines#25, use=ndr9500-mc,
use=minitel12-80,
minitel12-80|minitel 12 (80cols),
- G0,
civis=\E[<1h, cnorm=\E[<1l, is2=\E[12h, u6=\E[%i%d;%dH,
u7=\E[6n,
.acsc=ffggj+k+l+m+n+ovq-swt+u+v+w+xx}}\,m+k.l-j0
.enacs=\E)3, .rmacs=^O, .rs3=\E[?4l, .scs=\E(%p1%c,
.smacs=^N,
C0=ffggj+k+l+m+n+ovq-swt+u+v+w+xx}}\,m+k.l-j0\177,
- E0=^O, S0=\E)3\016,
+ S0=\E)3\016,
XC=B%\E(B\,\243\E(3}\,\247\E(R[\,\257\E(3v\,\260\E(3f\,\261
\E(3g\,\267\E(3~\,\274\E(3O\,\275\E(3P\,\276\E(3Q\,\300A
\,\301A\,\302A\,\303A\,\304A\,\305A\,\306E\,\307C\,\310E
# + remove xterm+sm+1006 from tmux (Debian #1057688).
# + used "infocmp -u" to help trim redundant capabilities -TD
#
+# 2023-12-16
+# + used "infocmp -u" to help trim redundant capabilities -TD
+#
######## SHANTIH! SHANTIH! SHANTIH!
-ncurses6 (6.4+20231209) unstable; urgency=low
+ncurses6 (6.4+20231217) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sun, 03 Dec 2023 19:13:10 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sun, 17 Dec 2023 18:18:40 -0500
ncurses6 (5.9+20131005) unstable; urgency=low
-ncurses6 (6.4+20231209) unstable; urgency=low
+ncurses6 (6.4+20231217) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sun, 03 Dec 2023 19:13:10 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sun, 17 Dec 2023 18:18:40 -0500
ncurses6 (5.9+20131005) unstable; urgency=low
-ncurses6 (6.4+20231209) unstable; urgency=low
+ncurses6 (6.4+20231217) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sun, 03 Dec 2023 19:13:10 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sun, 17 Dec 2023 18:18:40 -0500
ncurses6 (5.9+20120608) unstable; urgency=low
-; $Id: mingw-ncurses.nsi,v 1.622 2023/12/04 00:13:44 tom Exp $\r
+; $Id: mingw-ncurses.nsi,v 1.624 2023/12/17 23:18:40 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 "1209"\r
+!define VERSION_MMDD "1217"\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: 20231209
+Release: 20231217
License: X11
Group: Development/Libraries
URL: https://invisible-island.net/ncurses/
Summary: shared libraries for terminal handling
Name: ncurses6
Version: 6.4
-Release: 20231209
+Release: 20231217
License: X11
Group: Development/Libraries
URL: https://invisible-island.net/ncurses/
Summary: Curses library with POSIX thread support.
Name: ncursest6
Version: 6.4
-Release: 20231209
+Release: 20231217
License: X11
Group: Development/Libraries
Source: ncurses-%{version}-%{release}.tgz
#include <dump_entry.h>
-MODULE_ID("$Id: infocmp.c,v 1.161 2023/12/09 19:56:10 tom Exp $")
+MODULE_ID("$Id: infocmp.c,v 1.163 2023/12/16 17:27:47 tom Exp $")
#define MAX_STRING 1024 /* maximum formatted string */
return (_nc_capcmp(s, t));
}
+/*
+ * Predicate function to use for "use=" decompilation.
+ *
+ * Return value is used in fmt_entry:
+ * FAIL show nothing for this capability.
+ * FALSE show cancel for booleans (a compromise)
+ * TRUE show capability
+ *
+ * The only difference between FALSE/TRUE returns is in the treatment of
+ * booleans.
+ */
static int
use_predicate(unsigned type, PredIdx idx)
-/* predicate function to use for use decompilation */
{
int result = FAIL;
ENTRY *ep;
if (idx < NUM_BOOLEANS(&(entries[0].tterm))) {
for (ep = &entries[1]; ep < entries + termcount; ep++) {
if (idx < NUM_BOOLEANS(&(ep->tterm))
- && ep->tterm.Booleans[idx] == TRUE) {
- is_set = entries[0].tterm.Booleans[idx];
+ && (is_set = ep->tterm.Booleans[idx])) {
break;
}
}
if (usestr == CANCELLED_STRING && termstr == ABSENT_STRING)
result = (FAIL);
+ else if (usestr == CANCELLED_STRING && termstr == CANCELLED_STRING)
+ result = (TRUE);
else if (usestr == ABSENT_STRING && termstr == ABSENT_STRING)
result = (FAIL);
else if (!usestr || !termstr || capcmp(idx, usestr, termstr))
projects / ncurses.git / commitdiff