+ improve formatting/style of manpages (patches by Branden Robinson).
+ limit value from ESCDELAY environment variable to 30 seconds, like
other delay limits.
+ limit values from LINES and COLUMNS environment variables to 512
(report by Miroslav Lichvar).
-- sale, use or other dealings in this Software without prior written --
-- authorization. --
-------------------------------------------------------------------------------
--- $Id: NEWS,v 1.4117 2024/05/04 18:43:01 tom Exp $
+-- $Id: NEWS,v 1.4119 2024/05/11 21:38:14 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.
+20240511
+ + improve formatting/style of manpages (patches by Branden Robinson).
+ + limit value from ESCDELAY environment variable to 30 seconds, like
+ other delay limits.
+ + limit values from LINES and COLUMNS environment variables to 512
+ (report by Miroslav Lichvar).
+
20240504
+ update ncurses/wcwidth.c, for MinGW ports, from xterm.
+ trim obsolete comment about tack from INSTALL.
-5:0:10 6.5 20240504
+5:0:10 6.5 20240511
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: dist.mk,v 1.1611 2024/05/04 10:21:09 tom Exp $
+# $Id: dist.mk,v 1.1612 2024/05/11 10:20:08 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 = 5
-NCURSES_PATCH = 20240504
+NCURSES_PATCH = 20240511
# We don't append the patch to the version, since this only applies to releases
VERSION = $(NCURSES_MAJOR).$(NCURSES_MINOR)
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_add_wch.3x,v 1.62 2024/04/20 21:20:07 tom Exp @
+ * @Id: curs_add_wch.3x,v 1.63 2024/05/11 21:31: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_add_wch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_add_wch 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_add_wch 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_add_wch 3x 2024-05-11 ncurses 6.5 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>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
<STRONG>add_wch</STRONG>, <STRONG>wadd_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, <STRONG>echo_wchar</STRONG>, <STRONG>wecho_wchar</STRONG> - add
- a <EM>curses</EM> complex character to a window and advance the cursor
+ a <EM>curses</EM> complex character to a window, possibly advancing the cursor
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
-</PRE><H3><a name="h3-add_wch">add_wch</a></H3><PRE>
- The <STRONG>add_wch</STRONG>, <STRONG>wadd_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, and <STRONG>mvwadd_wch</STRONG> functions put the
- complex character <EM>wch</EM> into the given window at its current position,
- which is then advanced. These functions perform wrapping and special-
- character processing as follows:
-
- <STRONG>o</STRONG> If <EM>wch</EM> refers to a spacing character, then any previous character
- at that location is removed. A new character specified by <EM>wch</EM> is
- placed at that location with rendition specified by <EM>wch</EM>. The
- cursor then advances after this spacing character, to prepare for
- writing the next character on the screen.
-
- The newly added spacing character is the base of the active complex
- character. Subsequent non-spacing characters can be combined with
- this base until another spacing character is written to the screen,
- or the cursor is moved, e.g., using <STRONG>wmove</STRONG>.
-
- <STRONG>o</STRONG> If <EM>wch</EM> refers to a non-spacing character, it is appended to the
- active complex character, retaining the previous characters at that
- location. The rendition specified by <EM>wch</EM> is ignored.
-
- The cursor is not advanced after adding a non-spacing character.
- Subsequent calls to add non-spacing characters will update the same
- position.
+</PRE><H3><a name="h3-wadd_wch">wadd_wch</a></H3><PRE>
+ <STRONG>wadd_wch</STRONG> writes the complex character <EM>wch</EM> to the window <EM>win</EM>, then may
+ advance the cursor position, analogously to the standard C library's
+ <STRONG>putwchar(3)</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function.
+
+ Much behavior depends on whether the wide characters in <EM>wch</EM> are spacing
+ or non-spacing; see subsection "Complex Characters" below.
+
+ <STRONG>o</STRONG> If <EM>wch</EM> contains a spacing character, then any character at the
+ cursor is first removed. The complex character <EM>wch</EM>, with its
+ attributes and color pair identifier, becomes the <EM>base</EM> of the
+ <EM>active</EM> <EM>complex</EM> <EM>character</EM>.
+
+ <STRONG>o</STRONG> If <EM>wch</EM> contains only non-spacing characters, they are combined with
+ the active complex character. <EM>curses</EM> ignores its attributes and
+ color pair identifier, and does not advance the cursor.
+
+ Further non-spacing characters added with <STRONG>wadd_wch</STRONG> are not written at
+ the new cursor position but combine with the active complex character
+ until another spacing character is written to the window or the cursor
+ is moved.
+
+ If advancement occurs at the right margin,
+
+ <STRONG>o</STRONG> the cursor automatically wraps to the beginning of the next line,
+ then,
+
+ <STRONG>o</STRONG> if it was at the bottom of the scrolling region, and if
+ <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is enabled for <EM>win</EM>, the scrolling region scrolls up
+ one line.
- <STRONG>o</STRONG> If the character part of <EM>wch</EM> is a tab, newline, backspace or other
- control character, the window is updated and the cursor moves as if
- <STRONG>addch</STRONG> were called.
+ If <EM>wch</EM> is a backspace, carriage return, line feed, or tab, the cursor
+ moves appropriately within the window.
+ <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin
+ of a window, it does nothing.
-</PRE><H3><a name="h3-echo_wchar">echo_wchar</a></H3><PRE>
- The <STRONG>echo_wchar</STRONG> function is functionally equivalent to a call to <STRONG>add_wch</STRONG>
- followed by a call to <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>. Similarly, the <STRONG>wecho_wchar</STRONG> is
- functionally equivalent to a call to <STRONG>wadd_wch</STRONG> followed by a call to
- <STRONG>wrefresh</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 the *<STRONG>echo</STRONG>*
- functions instead of their equivalents.
+ <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the current
+ line of the window.
+ <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then advances as if from the right
+ margin.
-</PRE><H3><a name="h3-Line-Graphics">Line Graphics</a></H3><PRE>
- Like <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>, <STRONG>addch_wch</STRONG> 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 <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>.
+ <STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next
+ line); these are placed at every eighth column by default. Alter
+ the tab interval with the <STRONG>TABSIZE</STRONG> extension; see
+ <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
- <STRONG>Unicode</STRONG> <STRONG>ASCII</STRONG> <STRONG>acsc</STRONG>
+ If <EM>wch</EM> is any other nonprintable character, it is drawn in printable
+ form using the same convention as <STRONG><A HREF="curs_util.3x.html">wunctrl(3x)</A></STRONG>.
+ Calling <STRONG><A HREF="curs_in_wch.3x.html">win_wch(3x)</A></STRONG> on the location of a nonprintable character does
+ not return the character itself, but its <STRONG><A HREF="curs_util.3x.html">wunctrl(3x)</A></STRONG> representation.
- <STRONG>ACS</STRONG> <STRONG>Name</STRONG> <STRONG>Default</STRONG> <STRONG>Default</STRONG> <STRONG>Char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
+
+</PRE><H3><a name="h3-wecho_wchar">wecho_wchar</a></H3><PRE>
+ <STRONG>echo_wchar</STRONG> and <STRONG>wecho_wchar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>add_wch</STRONG>
+ followed by (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> interprets these functions as a hint
+ that only a single (complex) character is being output; for non-control
+ characters, a considerable performance gain may be enjoyed by employing
+ them.
+
+
+</PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE>
+ <EM>curses</EM> defines macros starting with <STRONG>WACS_</STRONG> that can be used with
+ <STRONG>wadd_wch</STRONG> to write line-drawing and other special characters to the
+ screen. <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default
+ listed below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> capability does
+ not define a terminal-specific replacement for it, or if the terminal
+ and locale configuration requires Unicode to access these characters
+ but the library is unable to use Unicode. The "acsc char" column
+ corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>)
+ string capability, and the characters in it may appear on the screen if
+ the terminal type's database entry incorrectly advertises ACS support.
+ The name "ACS" originates in the Alternate Character Set feature of the
+ DEC VT100 terminal.
+
+ <STRONG>Unicode</STRONG> <STRONG>ACS</STRONG> <STRONG>acsc</STRONG>
+ <STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
------------------------------------------------------------------------
<STRONG>WACS_BLOCK</STRONG> 0x25ae # 0 solid square block
<STRONG>WACS_BOARD</STRONG> 0x2592 # h board of squares
<STRONG>WACS_D_LTEE</STRONG> 0x2560 + F double tee pointing right
<STRONG>WACS_D_PLUS</STRONG> 0x256c + E double large plus
<STRONG>WACS_D_RTEE</STRONG> 0x2563 + G double tee pointing left
-
<STRONG>WACS_D_TTEE</STRONG> 0x2566 + I double tee pointing down
<STRONG>WACS_D_ULCORNER</STRONG> 0x2554 + C double upper left corner
<STRONG>WACS_D_URCORNER</STRONG> 0x2557 + B double upper right corner
</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> on success.
+ These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. In <EM>ncurses</EM>,
+ <STRONG>wadd_wch</STRONG> returns <STRONG>ERR</STRONG> if
- X/Open Curses does not specify any error conditions. This
- implementation returns an error
+ <STRONG>o</STRONG> <EM>win</EM> is <STRONG>NULL</STRONG>,
- <STRONG>o</STRONG> if the window pointer is null or
+ <STRONG>o</STRONG> wrapping to a new line is impossible because <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> has not
+ been called on <EM>win</EM> when writing to its bottom right location is
+ attempted, or
- <STRONG>o</STRONG> if it is not possible to add a complete character in the window.
+ <STRONG>o</STRONG> it is not possible to add a complete character at the cursor
+ position.
- The latter may be due to different causes:
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
- <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.
- <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
- resulting bytes in the window, an error is returned.
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+ <STRONG>add_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, and <STRONG>echo_wchar</STRONG> may be implemented as
+ macros.
- Functions prefixed with "mv" first perform cursor movement and fail if
- the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
+</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
-</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- Note that <STRONG>add_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, and <STRONG>echo_wchar</STRONG> may be macros.
+</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
+ The <STRONG>TABSIZE</STRONG> variable is implemented in SVr4 and other versions of
+ <EM>curses</EM>, but is not specified by X/Open Curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These functions are described in X/Open Curses, Issue 4. The defaults
- specified for line-drawing characters apply in the POSIX locale.
+ These functions are described in X/Open Curses, Issue 4. It specifies
+ no error conditions for them.
+ SVr4 <EM>curses</EM> describes a successful return value only as "an integer
+ value other than <STRONG>ERR</STRONG>".
-</PRE><H3><a name="h3-WACS-Symbols">WACS Symbols</a></H3><PRE>
- X/Open Curses makes it clear that the WACS_ symbols should be defined
- as a pointer to <STRONG>cchar_t</STRONG> data, e.g., in the discussion of <STRONG>border_set</STRONG>. A
- few implementations are problematic:
+ The defaults specified for forms-drawing characters apply in the POSIX
+ locale. X/Open Curses makes it clear that the WACS_ symbols should be
+ defined as a pointer to <STRONG>cchar_t</STRONG> data, e.g., in the discussion of
+ <STRONG>border_set</STRONG>. A few implementations are problematic:
<STRONG>o</STRONG> NetBSD curses defines the symbols as a <STRONG>wchar_t</STRONG> within a <STRONG>cchar_t</STRONG>.
- <STRONG>o</STRONG> HP-UX curses equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
- <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters. The
- misdefined symbols are the arrows and other symbols which are not
+ <STRONG>o</STRONG> HP-UX curses equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
+ <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters. The
+ misdefined symbols are the arrows and other symbols which are not
used for line-drawing.
- X/Open Curses does not specify symbols for thick- or double-lines.
+ X/Open Curses does not specify symbols for thick- or double-lines.
SVr4 curses implementations defined their line-drawing symbols in terms
- of intermediate symbols. This implementation extends those symbols,
+ of intermediate symbols. This implementation extends those symbols,
providing new definitions which are not in the SVr4 implementations.
- Not all Unicode-capable terminals provide support for VT100-style
- alternate character sets (i.e., the <STRONG>acsc</STRONG> capability), with their
- corresponding line-drawing characters. X/Open Curses did not address
- the aspect of integrating Unicode with line-drawing characters.
- Existing implementations of Unix curses (AIX, HP-UX, Solaris) use only
+ Not all Unicode-capable terminals provide support for VT100-style
+ alternate character sets (i.e., the <STRONG>acsc</STRONG> capability), with their
+ corresponding line-drawing characters. X/Open Curses did not address
+ the aspect of integrating Unicode with line-drawing characters.
+ 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.
- <EM>ncurses</EM> 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
+ 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 <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM>. In contrast, for the same
+ 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-
+ Having Unicode available does not solve all of the problems with line-
drawing for curses:
- <STRONG>o</STRONG> The closest Unicode equivalents to the VT100 graphics <EM>S1</EM>, <EM>S3</EM>, <EM>S7</EM>
- and <EM>S9</EM> frequently are not displayed at the regular intervals which
+ <STRONG>o</STRONG> The closest Unicode equivalents to the VT100 graphics <EM>S1</EM>, <EM>S3</EM>, <EM>S7</EM>
+ and <EM>S9</EM> frequently are not displayed at the regular intervals which
the terminal used.
- <STRONG>o</STRONG> The <EM>lantern</EM> is a special case. It originated with the AT&T 4410
- terminal in the early 1980s. There is no accessible documentation
+ <STRONG>o</STRONG> The <EM>lantern</EM> is a special case. It originated with the AT&T 4410
+ terminal in the early 1980s. There is no accessible documentation
depicting the lantern symbol on the AT&T terminal.
Lacking documentation, most readers assume that a <EM>storm</EM> <EM>lantern</EM> was
intended. But there are several possibilities, all with problems.
- Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and
- U+1F3EE. Those were not available in 2002, and are irrelevant
- since they lie outside the BMP and as a result are not generally
+ Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and
+ U+1F3EE. Those were not available in 2002, and are irrelevant
+ since they lie outside the BMP and as a result are not generally
available in terminals. They are not storm lanterns, in any case.
Most <EM>storm</EM> <EM>lanterns</EM> have a tapering glass chimney (to guard against
tipping); some have a wire grid protecting the chimney.
- For the tapering appearance, U+2603 was adequate. In use on a
+ For the tapering appearance, U+2603 was adequate. In use on a
terminal, no one can tell what the image represents. Unicode calls
it a snowman.
Others have suggested these alternatives: <section> U+00A7 (section
- mark), <Theta> U+0398 (theta), <Phi> U+03A6 (phi), <delta> U+03B4
+ mark), <Theta> U+0398 (theta), <Phi> U+03A6 (phi), <delta> U+03B4
(delta), U+2327 (x in a rectangle), U+256C (forms double vertical
and horizontal), and U+2612 (ballot box with x).
</PRE><H3><a name="h3-Complex-Characters">Complex Characters</a></H3><PRE>
- The complex character type <STRONG>cchar_t</STRONG> can store more than one wide
- character (<STRONG>wchar_t</STRONG>). The X/Open Curses description does not mention
- this possibility, describing only the cases where <EM>wch</EM> is a spacing
- character or a non-spacing character.
+ The complex character type <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> can store more than one wide
+ character (<EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>). X/Open Curses does not mention this possibility,
+ specifying behavior only where <EM>wch</EM> is a single character, either
+ spacing or non-spacing.
- This implementation assumes that <EM>wch</EM> is constructed using <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG>,
- and in turn that the result
+ <EM>ncurses</EM> assumes that <EM>wch</EM> is constructed using <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG>, and in turn
+ that the result
- <STRONG>o</STRONG> contains at most one spacing character in the beginning of its list
- of wide characters, and zero or more non-spacing characters or
+ <STRONG>o</STRONG> contains at most one spacing character at the beginning of its list
+ of wide characters, and zero or more non-spacing characters, or
- <STRONG>o</STRONG> may hold one non-spacing character.
+ <STRONG>o</STRONG> holds one non-spacing character.
- In the latter case, <EM>ncurses</EM> adds the non-spacing character to the
- active (base) spacing character.
-
-
-</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
- The <STRONG>TABSIZE</STRONG> variable is implemented in SVr4 and other versions of
- <EM>curses</EM>, but is not specified by X/Open Curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).
+ In the latter case, <EM>ncurses</EM> adds the non-spacing character to the
+ active complex character.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(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-add_wch">add_wch</a></li>
-<li><a href="#h3-echo_wchar">echo_wchar</a></li>
-<li><a href="#h3-Line-Graphics">Line Graphics</a></li>
+<li><a href="#h3-wadd_wch">wadd_wch</a></li>
+<li><a href="#h3-wecho_wchar">wecho_wchar</a></li>
+<li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</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-EXTENSIONS">EXTENSIONS</a>
+<ul>
+<li><a href="#h3-TABSIZE">TABSIZE</a></li>
+</ul>
+</li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
-<li><a href="#h3-WACS-Symbols">WACS Symbols</a></li>
<li><a href="#h3-Complex-Characters">Complex Characters</a></li>
-<li><a href="#h3-TABSIZE">TABSIZE</a></li>
</ul>
</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_add_wchstr.3x,v 1.39 2024/04/20 21:20:07 tom Exp @
+ * @Id: curs_add_wchstr.3x,v 1.40 2024/05/11 20:39: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>curs_add_wchstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_add_wchstr 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_add_wchstr 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_add_wchstr 3x 2024-05-11 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- These functions copy the (null-terminated) array of complex characters
- <EM>wchstr</EM> into the window image structure starting at the current cursor
- position.
+ <STRONG>wadd_wchstr</STRONG> copies the string of complex characters <EM>wchstr</EM> to the
+ window <EM>win</EM>. A null complex character terminates the string. If a
+ complex character does completely fit at the end of the line, <EM>curses</EM>
+ fills the remaining columns with the window background; see <STRONG><A HREF="curs_bkgrnd.3x.html">bkgrnd(3x)</A></STRONG>.
+ <STRONG>wadd_wchnstr</STRONG> does the same, but copies at most <EM>n</EM> characters, or as many
+ as possible if <EM>n</EM> is <STRONG>-1</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these
+ functions.
- The four functions with <EM>n</EM> as the last argument copy at most <EM>n</EM> elements,
- but no more than will fit on the line. If <STRONG>n</STRONG>=<STRONG>-1</STRONG> then the whole array is
- copied, to the maximum number of characters that will fit on the line.
+ Because these functions do not call <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> internally, they are
+ faster than <STRONG><A HREF="curs_addwstr.3x.html">waddwstr(3x)</A></STRONG> and <STRONG><A HREF="curs_addwstr.3x.html">waddnwstr(3x)</A></STRONG>. On the other hand, they
- The window cursor is <EM>not</EM> advanced. These functions are faster than
- <STRONG>waddnstr</STRONG>. On the other hand:
+ <STRONG>o</STRONG> do not treat the backspace, carriage return, or line feed
+ characters specially;
- <STRONG>o</STRONG> they do not perform checking (such as for the newline, backspace,
- or carriage return characters),
+ <STRONG>o</STRONG> do not represent unprintable characters with <STRONG><A HREF="curs_util.3x.html">wunctrl(3x)</A></STRONG>;
- <STRONG>o</STRONG> they do not advance the current cursor position,
+ <STRONG>o</STRONG> do not update the cursor position to follow the last character
+ written;
- <STRONG>o</STRONG> they do not expand other control characters to ^-escapes, and
-
- <STRONG>o</STRONG> they truncate the string if it crosses the right margin, rather
- than wrapping it around to the new line.
-
- These functions end successfully on encountering a null <STRONG>cchar_t</STRONG>, or
- when they have filled the current line. If a complex character cannot
- completely fit at the end of the current line, the remaining columns
- are filled with the background character and rendition.
+ <STRONG>o</STRONG> truncate the string at the window's right margin, rather than
+ wrapping it to the next line and potentially scrolling.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- All functions return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success.
+ These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
- X/Open Curses does not specify any error conditions. This
- implementation returns an error
+ X/Open Curses does not specify any error conditions. <EM>ncurses</EM> returns
+ <STRONG>ERR</STRONG> if
- <STRONG>o</STRONG> if the <EM>win</EM> parameter is null or
+ <STRONG>o</STRONG> <EM>win</EM> is <STRONG>NULL</STRONG> or
- <STRONG>o</STRONG> if the <EM>wchstr</EM> parameter is null.
+ <STRONG>o</STRONG> <EM>wchstr</EM> is <STRONG>NULL</STRONG>.
Functions prefixed with "mv" first perform cursor movement and fail if
the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- All functions except <STRONG>wadd_wchnstr</STRONG> may be macros.
+ All of these functions except <STRONG>wadd_wchnstr</STRONG> may be implemented as
+ macros.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These functions are described in X/Open Curses, Issue 4.
+ X/Open Curses, Issue 4 describes these functions.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(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.85 2024/04/20 19:03:47 tom Exp @
+ * @Id: curs_addch.3x,v 1.86 2024/05/11 20:39: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>curs_addch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_addch 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_addch 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_addch 3x 2024-05-11 ncurses 6.5 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>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
-</PRE><H3><a name="h3-
Adding-Characters">Adding Characters</a></H3><PRE>
- <STRONG>waddch</STRONG> puts the character <EM>ch</EM> at the cursor position of window <EM>win</EM>, then
- advances the cursor position, analogously to the standard C library's
+</PRE><H3><a name="h3-
waddch">waddch</a></H3><PRE>
+ <STRONG>waddch</STRONG> writes the <EM>curses</EM> character <EM>ch</EM> to the window <EM>win</EM>, then advances
+ the cursor position, analogously to the standard C library's
<STRONG>putchar(3)</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function.
If advancement occurs at the right margin,
- <STRONG>o</STRONG> the cursor automatically wraps to the beginning of the next line;
- and
+ <STRONG>o</STRONG> the cursor automatically wraps to the beginning of the next line,
+ then,
- <STRONG>o</STRONG> at the bottom of the current scrolling region, and if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>
- is enabled for <EM>win</EM>, the scrolling region scrolls up one line.
+ <STRONG>o</STRONG> if it was at the bottom of the scrolling region, and if
+ <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is enabled for <EM>win</EM>, the scrolling region scrolls up
+ one line.
- If <EM>ch</EM> is a backspace, carriage return, line feed, or tab, the cursor
+ If <EM>ch</EM> is a backspace, carriage return, line feed, or tab, the cursor
moves appropriately within the window.
- <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin
+ <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin
of a window, it does nothing.
- <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the current
+ <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the current
line of the window.
- <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then moves the cursor to the left
- margin on the next line of the window, and if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is
- enabled for <EM>win</EM>, scrolls the window if the cursor was already on
- the last line.
+ <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then advances as if from the right
+ margin.
- <STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next
- line); these are placed at every eighth column by default. Alter
- the tab interval with the <STRONG>TABSIZE</STRONG> extension; see
+ <STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next
+ line); these are placed at every eighth column by default. Alter
+ the tab interval with the <STRONG>TABSIZE</STRONG> extension; see
<STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
- If <EM>ch</EM> is any other nonprintable character, it is drawn in printable
- form
, using the same convention as <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>.
+ If <EM>ch</EM> is any other nonprintable character, it is drawn in printable
+ form using the same convention as <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>.
- Calling <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> on the location of a nonprintable character does not
+ Calling <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> on the location of a nonprintable character does not
return the character itself, but its <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> representation.
- <EM>ch</EM> may contain rendering and/or color attributes, and others can be
- combined with the parameter by logically "or"ing with it. (A character
- with its attributes can be copied from place to place using <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG>
- and <STRONG>waddch</STRONG>.) See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> for values of predefined video
- attribute constants that can be usefully "or"ed with characters.
+ The object or expression <EM>ch</EM> may contain attributes and/or a color pair
+ identifier. (A character with its attributes can be copied from place
+ to place using <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> and <STRONG>waddch</STRONG>.) See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> for values of
+ predefined video attribute constants that can be usefully "or"ed with
+ characters.
-</PRE><H3><a name="h3-
Echoing-Characters">Echoing Characters</a></H3><PRE>
- <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by
- (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> interprets these functions as a hint that only a
+</PRE><H3><a name="h3-
wechochar">wechochar</a></H3><PRE>
+ <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by
+ (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> interprets these functions as a hint that only a
single character is being output; for non-control characters, a
considerable performance gain may be enjoyed by employing them.
</PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE>
- <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG>
- to write line-drawing and other special characters to the screen.
- <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default listed
- below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> capability does not
- define a terminal-specific replacement for it, or if the terminal and
- locale configuration requires Unicode to access these characters but
+ <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG>
+ to write line-drawing and other special characters to the screen.
+ <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default listed
+ below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> capability does not
+ define a terminal-specific replacement for it, or if the terminal and
+ locale configuration requires Unicode to access these characters but
the library is unable to use Unicode. The "acsc char" column
- corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> string
- capability, and the characters in it may appear on the screen if the
- terminal's database entry incorrectly advertises ACS support. The name
- "ACS" originates in the Alternate Character Set feature of the DEC
- VT100 terminal.
+ corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>)
+ string capability, and the characters in it may appear on the screen if
+ the terminal type's database entry incorrectly advertises ACS support.
+ The name "ACS" originates in the Alternate Character Set feature of the
+ DEC VT100 terminal.
<STRONG>ACS</STRONG> <STRONG>acsc</STRONG>
<STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
- In <EM>ncurses</EM>, <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG> if it is not possible to add a complete
- character at the cursor position, as when conversion of a multibyte
- character to a byte sequence fails, or at least one of the resulting
- bytes cannot be added to the window. See section "PORTABILITY" below
- regarding the use of <STRONG>waddch</STRONG> with multibyte characters.
+ In <EM>ncurses</EM>, <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG> if
- <STRONG>waddch</STRONG> can successfully write a character at the bottom right location
- of the window. However, <EM>ncurses</EM> returns <STRONG>ERR</STRONG> if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not
- enabled in that event, because it is not possible to wrap to a new
- line.
+ <STRONG>o</STRONG> <EM>win</EM> is <STRONG>NULL</STRONG>,
+
+ <STRONG>o</STRONG> wrapping to a new line is impossible because <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> has not
+ been called on <EM>win</EM> when a write to its bottom right location is
+ attempted, or
+
+ <STRONG>o</STRONG> it is not possible to add a complete character at the cursor
+ position.
+
+ The last may be due to different causes:
+
+ <STRONG>o</STRONG> conversion of a multibyte character to a byte sequence can fail, or
+
+ <STRONG>o</STRONG> at least one of the bytes resulting from conversion from a
+ multibyte sequence cannot be added to the window. See section
+ "PORTABILITY" below regarding the use of <STRONG>waddch</STRONG> with multibyte
+ characters.
Functions prefixed with "mv" first perform cursor movement and fail if
the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
<STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be implemented as macros.
+</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
+
+</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
+ SVr4 and other versions of <EM>curses</EM> implement the <STRONG>TABSIZE</STRONG> variable, but
+ X/Open Curses does not specify it; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
+
+
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- X/Open Curses, Issue 4 describes these functions. It specifies no
+ X/Open Curses, Issue 4 describes these functions. It specifies no
error conditions for them.
- SVr4 <EM>curses</EM> describes a successful return value only as "an integer
+ SVr4 <EM>curses</EM> describes a successful return value only as "an integer
value other than <STRONG>ERR</STRONG>".
- The defaults specified for forms-drawing characters apply in the POSIX
+ The defaults specified for forms-drawing characters apply in the POSIX
locale.
Some implementations are problematic.
- <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, define the ACS symbols as constants;
+ <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, defines the ACS symbols as constants;
others define them as elements of an array.
- This implementation uses an array, <STRONG>acs_map</STRONG>, as did SVr4 <EM>curses</EM>.
+ This implementation uses an array, <STRONG>acs_map</STRONG>, as did SVr4 <EM>curses</EM>.
NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG>
for compatibility.
- <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
- <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters (see
- <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and
+ <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <STRONG>ACS_</STRONG> symbols to the analogous
+ <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters (see
+ <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and
others that are not used for line drawing.
- <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for
- the <STRONG>ACS_LANTERN</STRONG> symbol, equating its "VT100+ Character" to "I"
- (capital I), while the header files for SVr4 <EM>curses</EM> and other
+ <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for
+ the <STRONG>ACS_LANTERN</STRONG> symbol, equating its "VT100+ Character" to "I"
+ (capital I), while the header files for SVr4 <EM>curses</EM> and other
implementations use "i" (small i).
- None of the terminal descriptions on Unix platforms use uppercase
- I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>,
- apparently based on the X/Open documentation around 1995). On the
- other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator)
+ None of the terminal descriptions on Unix platforms use uppercase
+ I, except for Solaris (in its <EM>terminfo</EM> entry for <STRONG>screen(1)</STRONG>,
+ apparently based on the X/Open documentation around 1995). On the
+ other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator)
description uses lowercase i.
- Some ACS symbols (<STRONG>ACS_S3</STRONG>, <STRONG>ACS_S7</STRONG>, <STRONG>ACS_LEQUAL</STRONG>, <STRONG>ACS_GEQUAL</STRONG>, <STRONG>ACS_PI</STRONG>,
- <STRONG>ACS_NEQUAL</STRONG>, and <STRONG>ACS_STERLING</STRONG>) were not documented in any publicly
- released System V. However, many publicly available <EM>terminfo</EM> entries
- include <STRONG>acsc</STRONG> strings in which their key characters <STRONG>(</STRONG>pryz{|}<STRONG>)</STRONG> are
- embedded, and a second-hand list of their character descriptions has
- come to light. The <EM>ncurses</EM> developers invented ACS-prefixed names for
+ Some ACS symbols (<STRONG>ACS_S3</STRONG>, <STRONG>ACS_S7</STRONG>, <STRONG>ACS_LEQUAL</STRONG>, <STRONG>ACS_GEQUAL</STRONG>, <STRONG>ACS_PI</STRONG>,
+ <STRONG>ACS_NEQUAL</STRONG>, and <STRONG>ACS_STERLING</STRONG>) were not documented in any publicly
+ released System V. However, many publicly available <EM>terminfo</EM> entries
+ include <STRONG>acsc</STRONG> capabilities in which their key characters (<STRONG>pryz{|}</STRONG>) are
+ embedded, and a second-hand list of their character descriptions has
+ come to light. The <EM>ncurses</EM> developers invented ACS-prefixed names for
them.
The <EM>displayed</EM> values of <STRONG>ACS_</STRONG> constants depend on
<STRONG>o</STRONG> the <EM>ncurses</EM> ABI--for example, wide-character versus non-wide-
- character configurations (the former is capable of displaying
+ character configurations (the former is capable of displaying
Unicode while the latter is not), and
<STRONG>o</STRONG> whether the locale uses UTF-8 encoding.
- In certain cases, the terminal is unable to display forms-drawing
- characters <EM>except</EM> by using UTF-8; see the discussion of the
- <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM> environment variable in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>).
+ In certain cases, the terminal is unable to display forms-drawing
+ characters <EM>except</EM> by using UTF-8; see the discussion of the
+ <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM> environment variable in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
</PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE>
- X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a
- single character. As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, that character may
- have been more than eight bits wide in an SVr3 or SVr4 implementation,
- but in the X/Open Curses model, the details are not given. The
- important distinction between SVr4 <EM>curses</EM> and X/Open Curses is that the
- latter separates non-character information (attributes and color) from
- the character code, which SVr4 packs into a <EM>chtype</EM> for passage to
- <STRONG>waddch</STRONG>.
-
- In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character. But the library
- allows a multibyte character to be passed in a succession of calls to
- <STRONG>waddch</STRONG>. Other implementations do not; a <STRONG>waddch</STRONG> call transmits exactly
- one character, which may be rendered in one or more screen locations
- depending on whether it is printable.
-
- Depending on the locale settings, <EM>ncurses</EM> inspects the byte passed in
- each <STRONG>waddch</STRONG> call, and checks whether the latest call continues a
- multibyte sequence. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the
- character and advances the cursor.
-
- If the calling application interrupts the succession of bytes in a
- multibyte character sequence by changing the current location--for
+ X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a
+ single character. That character may have been more than eight bits
+ wide in an SVr3 or SVr4 implementation, but X/Open Curses leaves the
+ width of a non-wide character code unspecified. The standard further
+ does not specify the internal structure of a <EM>chtype</EM>, though the use of
+ bit operations to combine the character code with attributes and a
+ color pair identifier into a <EM>chtype</EM> for passage to <STRONG>waddch</STRONG> is common. A
+ portable application uses only the macros discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> to
+ manipulate a <EM>chtype</EM>.
+
+ In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character, but the library allows
+ a multibyte character to be passed in a succession of calls to <STRONG>waddch</STRONG>.
+ Other implementations do not; a <STRONG>waddch</STRONG> call transmits exactly one
+ character, which may be rendered in one or more screen locations
+ depending on whether it is printable (see <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>). Depending on
+ the locale, <EM>ncurses</EM> inspects the byte passed in each <STRONG>waddch</STRONG> call and
+ checks whether the latest call continues a multibyte sequence. When a
+ character is <EM>complete</EM>, <EM>ncurses</EM> displays the character and advances the
+ cursor. If the calling application interrupts the succession of bytes
+ in a multibyte character sequence by changing the current location--for
example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG>--<EM>ncurses</EM> discards the incomplete character.
- For portability to other implementations, do not rely upon this
- behavior. Check whether a character can be represented as a single
- byte in the current locale.
+ For portability to other implementations, do not rely upon the
+ foregoing behavior. Check whether a character can be represented as a
+ single byte in the current locale.
<STRONG>o</STRONG> If it can, call either <STRONG>waddch</STRONG> or <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.
<STRONG>o</STRONG> If it cannot, use only <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.
-</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
- SVr4 and other versions of <EM>curses</EM> implement the <STRONG>TABSIZE</STRONG> variable, but
- X/Open Curses does not specify it (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>).
-
-
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library
in its wide-character configuration (<EM>ncursesw</EM>).
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="curs_addch.3x.html">curs_addch(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-Adding-Characters">Adding Characters</a></li>
-<li><a href="#h3-Echoing-Characters">Echoing Characters</a></li>
+<li><a href="#h3-waddch">waddch</a></li>
+<li><a href="#h3-wechochar">wechochar</a></li>
<li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</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-EXTENSIONS">EXTENSIONS</a>
+<ul>
+<li><a href="#h3-TABSIZE">TABSIZE</a></li>
+</ul>
+</li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
<li><a href="#h3-ACS-Symbols">ACS Symbols</a></li>
<li><a href="#h3-Character-Set">Character Set</a></li>
-<li><a href="#h3-TABSIZE">TABSIZE</a></li>
</ul>
</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_addchstr.3x,v 1.45 2024/04/20 21:20:07 tom Exp @
+ * @Id: curs_addchstr.3x,v 1.46 2024/05/11 20:39: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>curs_addchstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_addchstr 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_addchstr 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_addchstr 3x 2024-05-11 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- These functions copy the (null-terminated) <EM>chstr</EM> array into the window
- image structure starting at the current cursor position.
+ <STRONG>waddchstr</STRONG> copies the string of <EM>curses</EM> characters <EM>chstr</EM> to the window
+ <EM>win</EM>. A null <EM>curses</EM> character terminates the string. <STRONG>waddchnstr</STRONG> does
+ the same, but copies at most <EM>n</EM> characters, or as many as possible if <EM>n</EM>
+ is <STRONG>-1</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions.
- The four functions with <EM>n</EM> as the last argument copy at most <EM>n</EM> elements,
- but no more than will fit on the line. If <STRONG>n</STRONG>=<STRONG>-1</STRONG> then the whole array is
- copied, to the maximum number of characters that will fit on the line.
+ Because these functions do not call <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> internally, they are
+ faster than <STRONG><A HREF="curs_addstr.3x.html">waddstr(3x)</A></STRONG> and <STRONG><A HREF="curs_addstr.3x.html">waddnstr(3x)</A></STRONG>. On the other hand, they
- The window cursor is <EM>not</EM> advanced. These functions are faster than
- <STRONG>waddnstr</STRONG>. On the other hand:
+ <STRONG>o</STRONG> do not treat the backspace, carriage return, or line feed
+ characters specially;
- <STRONG>o</STRONG> they do not perform checking (such as for the newline, backspace,
- or carriage return characters),
+ <STRONG>o</STRONG> do not represent unprintable characters with <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>;
- <STRONG>o</STRONG> they do not advance the current cursor position,
+ <STRONG>o</STRONG> do not update the cursor position to follow the last character
+ written;
- <STRONG>o</STRONG> they do not expand other control characters to ^-escapes, and
-
- <STRONG>o</STRONG> they truncate the string if it crosses the right margin, rather
- than wrapping it around to the new line.
+ <STRONG>o</STRONG> truncate the string at the window's right margin, rather than
+ wrapping it to the next line and potentially scrolling.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- All functions return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success.
+ These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
- X/Open Curses does not specify any error conditions. This
- implementation returns an error
+ X/Open Curses does not specify any error conditions. <EM>ncurses</EM> returns
+ <STRONG>ERR</STRONG> if
- <STRONG>o</STRONG> if the <EM>win</EM> parameter is null or
+ <STRONG>o</STRONG> <EM>win</EM> is <STRONG>NULL</STRONG> or
- <STRONG>o</STRONG> if the <EM>wchstr</EM> parameter is null.
+ <STRONG>o</STRONG> <EM>chstr</EM> is <STRONG>NULL</STRONG>.
- Functions prefixed with "mv" first perform cursor movement and fail if
+ Functions prefixed with "mv" first perform cursor movement and fail if
the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- All functions except <STRONG>waddchnstr</STRONG> may be macros.
+ All of these functions except <STRONG>waddchnstr</STRONG> may be implemented as macros.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These functions are described in X/Open Curses, Issue 4.
+ X/Open Curses, Issue 4 describes these functions.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(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.105 2024/04/27 17:54:42 tom Exp @
+ * @Id: curs_attr.3x,v 1.106 2024/05/11 20:39: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>curs_attr 3x 2024-04-27 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_attr 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_attr 3x 2024-04-27 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_attr 3x 2024-05-11 ncurses 6.5 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>
<STRONG>A_CHARTEXT</STRONG> Bit-mask to extract a character
<STRONG>A_COLOR</STRONG> Bit-mask to extract a color (legacy routines)
+ You can thus use <STRONG>A_CHARTEXT</STRONG> to extract the character from a <EM>chtype</EM>,
+ <STRONG>A_ATTRIBUTES</STRONG> to obtain its rendering attributes, and <STRONG>A_COLOR</STRONG> to find
+ the color pair it uses.
+
These video attributes are supported by <STRONG>attr_on</STRONG> and related functions
(which also support the attributes recognized by <STRONG>attron</STRONG>, etc.):
<STRONG>WA_BLINK</STRONG> Blinking
<STRONG>WA_DIM</STRONG> Half bright
<STRONG>WA_BOLD</STRONG> Extra bright or bold
-
<STRONG>WA_ALTCHARSET</STRONG> Alternate character set
X/Open Curses does not assign values to these symbols, nor does it
-ncurses 6.5 2024-0
4-27 <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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_delch.3x,v 1.34 2024/04/20 19:24:14 tom Exp @
+ * @Id: curs_delch.3x,v 1.35 2024/05/11 20:39: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>curs_delch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_delch 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_delch 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_delch 3x 2024-05-11 ncurses 6.5 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>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- <STRONG>wdelch</STRONG> deletes the character at the cursor position in <EM>win</EM>.
- <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function.
-
- <STRONG>wdelch</STRONG> moves all characters to the right of the cursor on the same line
- to the left one position and replaces the contents of the rightmost
- position on the line with the window's blank character; see <STRONG><A HREF="curs_bkgd.3x.html">bkgd(3x)</A></STRONG>
- (wide-character API users may consult <STRONG><A HREF="curs_bkgrnd.3x.html">bkgrnd(3x)</A></STRONG> instead). The cursor
- position does not change (after moving to (<EM>y</EM>, <EM>x</EM>), if specified).
+ <STRONG>wdelch</STRONG> deletes the character at the cursor position in <EM>win</EM>. It moves
+ all characters to the right of the cursor on the same line to the left
+ one position and replaces the contents of the rightmost position on the
+ line with the window's blank character; see <STRONG><A HREF="curs_bkgd.3x.html">bkgd(3x)</A></STRONG> (wide-character
+ API users: <STRONG><A HREF="curs_bkgrnd.3x.html">bkgrnd(3x)</A></STRONG>). The cursor position does not change (after
+ moving to (<EM>y</EM>, <EM>x</EM>), if specified). <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of
+ this function.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
Functions taking a <EM>WINDOW</EM> pointer argument fail if the pointer is <STRONG>NULL</STRONG>.
- Functions prefixed with "mv" first perform cursor movement and fail if
+ Functions prefixed with "mv" first perform cursor movement and fail if
the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
<STRONG>delch</STRONG>, <STRONG>mvdelch</STRONG>, and <STRONG>mvwdelch</STRONG> may be implemented as macros.
- A terminal's <STRONG>delete_character</STRONG> (<STRONG>dch1</STRONG>) capability is not necessarily
+ A terminal's <STRONG>delete_character</STRONG> (<STRONG>dch1</STRONG>) capability is not necessarily
employed.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- X/Open Curses, Issue 4 describes these functions.
+ X/Open Curses, Issue 4 describes these functions. It specifies no
+ error conditions for them.
SVr4 <EM>curses</EM> describes a successful return value only as "an integer
value other than <STRONG>ERR</STRONG>".
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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_get_wch.3x,v 1.40 2024/04/20 19:23:03 tom Exp @
+ * @Id: curs_get_wch.3x,v 1.41 2024/05/11 20:39: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>curs_get_wch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_get_wch 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_get_wch 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_get_wch 3x 2024-05-11 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
</PRE><H3><a name="h3-Reading-Characters">Reading Characters</a></H3><PRE>
- <STRONG>wget_wch</STRONG> gathers a key stroke <EM>wch</EM> from the terminal keyboard associated
- with a <EM>curses</EM> window <EM>win</EM>, returning <STRONG>OK</STRONG> if a wide character is read,
+ <STRONG>wget_wch</STRONG> gathers a key event from the terminal keyboard associated with
+ a <EM>curses</EM> window <EM>win</EM>, returning <STRONG>OK</STRONG> if a wide character is read,
<STRONG>KEY_CODE_YES</STRONG> if a function key is read, and <STRONG>ERR</STRONG> if no key event is
available. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function.
When input is pending, <STRONG>wget_wch</STRONG> stores an integer identifying the key
- stroke in <EM>wch</EM>; for alphanumeric and punctuation keys, this value
+ event in <EM>wch</EM>; for alphanumeric and punctuation keys, this value
corresponds to the character encoding used by the terminal. Use of the
- control key as a modifier often results in a distinct code. The
- behavior of other keys depends on whether <EM>win</EM> is in keypad mode; see
- subsections "Keypad Mode" and "Predefined Key Codes" in <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>.
-
- If no input is pending, then if the no-delay flag is set in the window
- (see <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits
- until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> has been called, this
- happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called,
- it occurs when the next newline is read. If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been
- called, <EM>curses</EM> waits until a character is typed or the specified delay
+ control key as a modifier, by holding it down while pressing and
+ releasing another key, often results in a distinct code. The behavior
+ of other keys depends on whether <EM>win</EM> is in keypad mode; see subsections
+ "Keypad Mode" and "Predefined Key Codes" in <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>.
+
+ If no input is pending, then if the no-delay flag is set in the window
+ (see <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits
+ until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> has been called, this
+ happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called,
+ it occurs when the next newline is read. If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been
+ called, <EM>curses</EM> waits until input is available or the specified delay
elapses.
If <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> has been called, and the window is not a pad, <EM>curses</EM> writes
<EM>wch</EM> to the window (at the cursor position) per the following rules.
- <STRONG>o</STRONG> If <EM>wch</EM> matches the terminal's erase character, the cursor moves
- leftward one position and the new position is erased as if
- <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG> were called. When the window's
- keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are
+ <STRONG>o</STRONG> If <EM>wch</EM> matches the terminal's erase character, the cursor moves
+ leftward one position and the new position is erased as if
+ <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG> were called. When the window's
+ keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are
handled the same way.
<STRONG>o</STRONG> <EM>curses</EM> writes any other <EM>wch</EM> to the window, as with <STRONG><A HREF="curs_add_wch.3x.html">wecho_wchar(3x)</A></STRONG>.
- <STRONG>o</STRONG> If the window has been moved or modified since the last call to
- <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG>.
+ <STRONG>o</STRONG> If the window <EM>win</EM> has been moved or modified since the last call to
+ <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG> on it.
- If <EM>wch</EM> is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> stores
- the the character code for newline (line feed) in <EM>wch</EM> instead.
+ If <EM>wch</EM> is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> stores
+ the the character code for line feed in <EM>wch</EM> instead.
</PRE><H3><a name="h3-Ungetting-Characters">Ungetting Characters</a></H3><PRE>
- <STRONG>unget_wch</STRONG> places <EM>wch</EM> into the input queue to be returned by the next
- call to <STRONG>wget_wch</STRONG>. A single input queue serves all windows.
+ <STRONG>unget_wch</STRONG> places <EM>wch</EM> into the input queue to be returned by the next
+ call to <STRONG>wget_wch</STRONG>. A single input queue serves all windows associated
+ with the terminal.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
input character in an additional <EM>wch</EM> parameter instead of the return
value.
- Unlike <STRONG>ungetch</STRONG>, <STRONG>unget_wch</STRONG> cannot distinguish function key codes
- <STRONG>wget_wch</STRONG> from conventional character codes. An application can
- overcome this limitation by pushing function key codes with <STRONG>ungetch</STRONG> and
- subsequently checking the return value of <STRONG>wget_wch</STRONG> for a match with
- <STRONG>KEY_CODE_YES</STRONG>.
+ Unlike <STRONG>ungetch</STRONG>, <STRONG>unget_wch</STRONG> cannot distinguish function key codes from
+ conventional character codes. An application can overcome this
+ limitation by pushing function key codes with <STRONG>ungetch</STRONG> and subsequently
+ checking the return value of <STRONG>wget_wch</STRONG> for a match with <STRONG>KEY_CODE_YES</STRONG>.
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
Applications employing <EM>ncurses</EM> extensions should condition their use on
the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.
- X/Open Curses, Issue 4 describes these functions. It specifies no
+ X/Open Curses, Issue 4 describes these functions. It specifies no
error conditions for them.
- See the "PORTABILITY" section of <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> regarding the interaction
+ See the "PORTABILITY" section of <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> regarding the interaction
of <STRONG>wget_wch</STRONG> with signal handlers.
<STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in
its non-wide-character configuration.
- <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_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>,
+ <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_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>,
<STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(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.87 2024/04/20 19:18:18 tom Exp @
+ * @Id: curs_getch.3x,v 1.88 2024/05/11 20:39: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>curs_getch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_getch 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_getch 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_getch 3x 2024-05-11 ncurses 6.5 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>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
</PRE><H3><a name="h3-Reading-Characters">Reading Characters</a></H3><PRE>
- <STRONG>wgetch</STRONG> gathers a key stroke from the terminal keyboard associated with
- a <EM>curses</EM> window <EM>win</EM>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this
+ <STRONG>wgetch</STRONG> gathers a key event from the terminal keyboard associated with a
+ <EM>curses</EM> window <EM>win</EM>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this
function.
When input is pending, <STRONG>wgetch</STRONG> returns an integer identifying the key
- stroke; for alphanumeric and punctuation keys, this value corresponds
- to the character encoding used by the terminal. Use of the control key
- as a modifier often results in a distinct code. The behavior of other
- keys depends on whether <EM>win</EM> is in keypad mode; see subsection "Keypad
- Mode" below.
-
- If no input is pending, then if the no-delay flag is set in the window
- (see <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits
- until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> has been called, this
- happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called,
- it occurs when the next newline is read. If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been
- called, <EM>curses</EM> waits until a character is typed or the specified delay
+ event; for alphanumeric and punctuation keys, this value corresponds to
+ the character encoding used by the terminal. Use of the control key as
+ a modifier, by holding it down while pressing and releasing another
+ key, often results in a distinct code. The behavior of other keys
+ depends on whether <EM>win</EM> is in keypad mode; see subsection "Keypad Mode"
+ below.
+
+ If no input is pending, then if the no-delay flag is set in the window
+ (see <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits
+ until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> has been called, this
+ happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called,
+ it occurs when the next newline is read. If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been
+ called, <EM>curses</EM> waits until input is available or the specified delay
elapses.
If <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> has been called, and the window is not a pad, <EM>curses</EM> writes
the returned character <EM>c</EM> to the window (at the cursor position) per the
following rules.
- <STRONG>o</STRONG> If <EM>c</EM> matches the terminal's erase character, the cursor moves
- leftward one position and the new position is erased as if
- <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG> were called. When the window's
- keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are
+ <STRONG>o</STRONG> If <EM>c</EM> matches the terminal's erase character, the cursor moves
+ leftward one position and the new position is erased as if
+ <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG> were called. When the window's
+ keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are
handled the same way.
<STRONG>o</STRONG> <EM>curses</EM> writes any other <EM>c</EM> to the window, as with <STRONG><A HREF="curs_addch.3x.html">wechochar(3x)</A></STRONG>.
- <STRONG>o</STRONG> If the window has been moved or modified since the last call to
- <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG>.
+ <STRONG>o</STRONG> If the window <EM>win</EM> has been moved or modified since the last call to
+ <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG> on it.
- If <EM>c</EM> is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> returns
+ If <EM>c</EM> is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> returns
the character code for line feed instead.
</PRE><H3><a name="h3-Keypad-Mode">Keypad Mode</a></H3><PRE>
- To <EM>curses</EM>, key strokes not from the alphabetic section of the keyboard
+ To <EM>curses</EM>, key strokes not from the alphabetic section of the keyboard
(those corresponding to the ECMA-6 character set--see
- <STRONG>ascii(7)</STRONG>--optionally modified by either the control or shift keys) are
+ <STRONG>ascii(7)</STRONG>--optionally modified by either the control or shift keys) are
treated as <EM>function</EM> keys. (In <EM>curses</EM>, the term "function key" includes
- but is not limited to keycaps engraved with "F1", "PF1", and so on.)
- If the window is in keypad mode, these produce a numeric code
- corresponding to the <STRONG>KEY_</STRONG> symbols listed in subsection "Predefined Key
- Codes" below; otherwise, they transmit a sequence of codes typically
- starting with the escape character, and which must be collected with
+ but is not limited to keycaps engraved with "F1", "PF1", and so on.)
+ If the window is in keypad mode, these produce a numeric code
+ corresponding to the <STRONG>KEY_</STRONG> symbols listed in subsection "Predefined Key
+ Codes" below; otherwise, they transmit a sequence of codes typically
+ starting with the escape character, and which must be collected with
multiple <STRONG>wgetch</STRONG> calls.
- <STRONG>o</STRONG> The <EM>curses.h</EM> header file declares many <EM>predefined</EM> <EM>function</EM> <EM>keys</EM>
- whose names begin with <STRONG>KEY_</STRONG>; these object-like macros have values
+ <STRONG>o</STRONG> The <EM>curses.h</EM> header file declares many <EM>predefined</EM> <EM>function</EM> <EM>keys</EM>
+ whose names begin with <STRONG>KEY_</STRONG>; these object-like macros have values
outside the range of eight-bit character codes.
- <STRONG>o</STRONG> In <EM>ncurses</EM>, <EM>user-defined</EM> <EM>function</EM> <EM>keys</EM> are configured with
- <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>; they have no names, but are also expected to have
+ <STRONG>o</STRONG> In <EM>ncurses</EM>, <EM>user-defined</EM> <EM>function</EM> <EM>keys</EM> are configured with
+ <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>; they have no names, but are also expected to have
values outside the range of eight-bit codes.
- A variable intended to hold a function key code must thus be of type
+ A variable intended to hold a function key code must thus be of type
<EM>short</EM> or larger.
- Most terminals one encounters follow the ECMA-48 standard insofar as
- their function keys produce character sequences prefixed with the
- escape character ESC. This fact implies that <EM>curses</EM> cannot know
- whether the terminal has sent an ESC key stroke or the beginning of a
- function key's character sequence without waiting to see if, and how
- soon, further input arrives. When <EM>curses</EM> reads such an ambiguous
- character, it sets a timer. If the remainder of the sequence does not
- arrive within the designated time, <STRONG>wgetch</STRONG> returns the prefix character;
- otherwise, it returns the function key code corresponding to the unique
- sequence defined by the terminal. Consequently, a user of a <EM>curses</EM>
- application may experience a delay after pressing ESC while <EM>curses</EM>
- disambiguates the input; see section "EXTENSIONS" below. If the window
- is in "no time-out" mode, the timer does not expire; it is an infinite
- (or very large) value. See <STRONG><A HREF="notimeout.3x.html">notimeout(3x)</A></STRONG>. Because function key
- sequences usually begin with an escape character, the terminal may
- appear to hang in no time-out mode after the user has pressed ESC.
- Generally, further typing "awakens" <EM>curses</EM>.
+ Most terminals one encounters follow the ECMA-48 standard insofar as
+ their function keys produce character sequences prefixed with the
+ escape character ESC. This fact implies that <EM>curses</EM> cannot distinguish
+ a user's press of the escape key (assuming it sends ESC) from the
+ beginning of a function key's character sequence without waiting to see
+ if, and how soon, further input arrives. When <EM>curses</EM> reads such an
+ ambiguous character, it sets a timer. If the remainder of the sequence
+ does not arrive within the designated time, <STRONG>wgetch</STRONG> returns the prefix
+ character; otherwise, it returns the function key code corresponding to
+ the unique sequence defined by the terminal. Consequently, a user of a
+ <EM>curses</EM> application may experience a delay after they escape key is
+ pressed while <EM>curses</EM> disambiguates the input; see section "EXTENSIONS"
+ below. If the window is in "no time-out" mode, the timer does not
+ expire; it is an infinite (or very large) value. See <STRONG><A HREF="notimeout.3x.html">notimeout(3x)</A></STRONG>.
+ Because function key sequences usually begin with ESC, the terminal may
+ appear to hang in no time-out mode after the user presses the escape
+ key. Generally, further typing "awakens" <EM>curses</EM>.
</PRE><H3><a name="h3-Ungetting-Characters">Ungetting Characters</a></H3><PRE>
- <STRONG>ungetch</STRONG> places <EM>c</EM> into the input queue to be returned by the next call
- to <STRONG>wgetch</STRONG>. A single input queue serves all windows.
+ <STRONG>ungetch</STRONG> places <EM>c</EM> into the input queue to be returned by the next call
+ to <STRONG>wgetch</STRONG>. A single input queue serves all windows associated with the
+ terminal.
</PRE><H3><a name="h3-Predefined-Key-Codes">Predefined Key Codes</a></H3><PRE>
<STRONG>KEY_RIGHT</STRONG>
<STRONG>KEY_HOME</STRONG> Home key (upward+left arrow)
<STRONG>KEY_BACKSPACE</STRONG> Backspace
+
<STRONG>KEY_F0</STRONG> Function keys; space for 64 keys is reserved
<STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> Function key <EM>n</EM> where 0 <= <EM>n</EM> <= 63
-
<STRONG>KEY_DL</STRONG> Delete line
<STRONG>KEY_IL</STRONG> Insert line
<STRONG>KEY_DC</STRONG> Delete character
<STRONG>KEY_SCREATE</STRONG> Shifted create key
<STRONG>KEY_SDC</STRONG> Shifted delete character key
<STRONG>KEY_SDL</STRONG> Shifted delete line key
+
<STRONG>KEY_SEND</STRONG> Shifted end key
<STRONG>KEY_SEOL</STRONG> Shifted clear line key
-
<STRONG>KEY_SEXIT</STRONG> Shifted exit key
<STRONG>KEY_SFIND</STRONG> Shifted find key
<STRONG>KEY_SHELP</STRONG> Shifted help key
<EM>curses</EM> distinguishes the Enter keys in the alphabetic and numeric
keypad sections of a keyboard because (most) terminals do. <STRONG>KEY_ENTER</STRONG>
refers to the key on the numeric keypad and, like other function keys,
- and is reliably recognized only if the window's keypad mode is enabled.
+ is reliably recognized only if the window's keypad mode is enabled.
<STRONG>o</STRONG> The <EM>terminfo</EM> <STRONG>key_enter</STRONG> (<STRONG>kent</STRONG>) capability describes the character
(sequence) sent by the Enter key of a terminal's numeric (or
function key character sequence from a series of key strokes beginning
with ESC typed by the user; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
- <STRONG>has_key</STRONG> was designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and is not found in SVr4 <EM>curses</EM>,
- 4.4BSD <EM>curses</EM>, or any other previous curses implementation.
+ <STRONG>has_key</STRONG> was designed for <EM>ncurses</EM>, and is not found in SVr4 <EM>curses</EM>,
+ 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> implementation.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
The behavior of <STRONG>wgetch</STRONG> in the presence of signal handlers is
unspecified in the SVr4 documentation and X/Open Curses. In historical
<EM>curses</EM> implementations, it varied depending on whether the operating
- system's dispatch of a signal to a handler interrupting a <STRONG>read(2)</STRONG> call
+ system's dispatch of a signal to a handler interrupted a <STRONG>read(2)</STRONG> call
in progress, and also (in some implementations) whether an input
- timeout or non-blocking mode has been set. Programmers concerned about
+ timeout or non-blocking mode had been set. Programmers concerned about
portability should be prepared for either of two cases: (a) signal
receipt does not interrupt <STRONG>wgetch</STRONG>; or (b) signal receipt interrupts
<STRONG>wgetch</STRONG> and causes it to return <STRONG>ERR</STRONG> with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>.
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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.58 2024/04/20 19:18:18 tom Exp @
+ * @Id: curs_getstr.3x,v 1.59 2024/05/11 20:39: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>curs_getstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_getstr 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_getstr 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_getstr 3x 2024-05-11 ncurses 6.5 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>
documented in SVr4.
X/Open Curses, Issue 5 (2007) stated that these functions "read at most
- <EM>n</EM> bytes" but did not state whether the terminating NUL is counted in
+ <EM>n</EM> bytes" but did not state whether the terminating NUL counted toward
that limit. X/Open Curses, Issue 7 (2009) changed that to say they
"read at most <EM>n</EM>-1 bytes" to allow for the terminating NUL. As of 2018,
some implementations count it, some do not:
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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.44 2024/04/20 21:20:07 tom Exp @
+ * @Id: curs_getyx.3x,v 1.45 2024/05/11 20:39: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>curs_getyx 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_getyx 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_getyx 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_getyx 3x 2024-05-11 ncurses 6.5 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>
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
<STRONG>void</STRONG> <STRONG>getyx(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>void</STRONG> <STRONG>getparyx(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>void</STRONG> <STRONG>getbegyx(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>void</STRONG> <STRONG>getmaxyx(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>void</STRONG> <STRONG>getparyx(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>
+
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- The <STRONG>getyx</STRONG> macro places the current cursor position of the given window
- in the two integer variables <EM>y</EM> and <EM>x</EM>.
-
- If <EM>win</EM> is a subwindow, the <STRONG>getparyx</STRONG> macro places the beginning
- coordinates of the subwindow relative to the parent window into two
- integer variables <EM>y</EM> and <EM>x</EM>. Otherwise, <STRONG>-1</STRONG> is placed into <EM>y</EM> and <EM>x</EM>.
+ These macros obtain the cursor position and bounds information of a
+ <EM>curses</EM> window <EM>win</EM>. <STRONG>getyx</STRONG> stores <EM>win</EM>'s cursor position in the variables
+ <EM>y</EM> and <EM>x</EM>. <STRONG>getmaxyx</STRONG> stores <EM>win</EM>'s maximum valid row and column numbers in
+ <EM>y</EM> and <EM>x</EM>, respectively. <STRONG>getbegyx</STRONG> similarly stores the position of <EM>win</EM>'s
+ origin relative to that of the screen (for <STRONG>stdscr</STRONG>, these coordinates
+ are always <STRONG>0</STRONG>).
- Like <STRONG>getyx</STRONG>, the <STRONG>getbegyx</STRONG> and <STRONG>getmaxyx</STRONG> macros store the current
- beginning coordinates and size of the specified window.
+ If <EM>win</EM> is a subwindow (see <STRONG><A HREF="subwin.3x.html">subwin(3x)</A></STRONG>), the <STRONG>getparyx</STRONG> macro places the
+ coordinates of its origin relative to its parent window into <EM>y</EM> and <EM>x</EM>,
+ and <STRONG>-1</STRONG> into both if it is not.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- The return values of these macros are undefined (i.e., they should not
- be used as the right-hand side of assignment statements).
+ No return values are defined for macros. Do not use them as the right-
+ hand side of assignment statements.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- All of these interfaces are macros. A "&" is not necessary before the
- variables <EM>y</EM> and <EM>x</EM>.
+ All of these interfaces are implemented as macros. An "&" operator is
+ not necessary before the variables <EM>y</EM> and <EM>x</EM>.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- The <STRONG>getyx</STRONG>, <STRONG>getparyx</STRONG>, <STRONG>getbegyx</STRONG> and <STRONG>getmaxyx</STRONG> macros are described in
- X/Open Curses, Issue 4.
+ These macros are described in X/Open Curses, Issue 4.
- This implementation also provides functions <STRONG>getbegx</STRONG>, <STRONG>getbegy</STRONG>, <STRONG>getcurx</STRONG>,
- <STRONG>getcury</STRONG>, <STRONG>getmaxx</STRONG>, <STRONG>getmaxy</STRONG>, <STRONG>getparx</STRONG> and <STRONG>getpary</STRONG> for compatibility with
-
older versions of <EM>curses</EM>; see <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>.
+ <EM>ncurses</EM> also provides functions <STRONG>getbegx</STRONG>, <STRONG>getbegy</STRONG>, <STRONG>getcurx</STRONG>, <STRONG>getcury</STRONG>,
+ <STRONG>getmaxx</STRONG>, <STRONG>getmaxy</STRONG>, <STRONG>getparx</STRONG>, and <STRONG>getpary</STRONG> for compatibility with older
+ versions of <EM>curses</EM>; see <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>.
- Although X/Open Curses does not address this, many implementations
- provide members of the <STRONG>WINDOW</STRONG> structure containing values corresponding
- to these macros. For best portability, do not rely on using the data
- in <STRONG>WINDOW</STRONG>, since some implementations make <STRONG>WINDOW</STRONG> opaque (do not allow
- direct use of its members).
+ Although X/Open Curses does not address the issue, many implementations
+ expose members of the <EM>WINDOW</EM> structure containing values corresponding
+ to these macros. Do not rely on their availability; some
+ implementations make <EM>WINDOW</EM> opaque (that is, they do not allow direct
+ access to its members).
Besides the problem of opaque structures, the data stored in like-named
- members may not have like-values in different implementations. For
- example, the <STRONG>WINDOW._maxx</STRONG> and <STRONG>WINDOW._maxy</STRONG> values in <EM>ncurses</EM> have (at
- least since release 1.8.1) differed by one from some other
- implementations. The difference is hidden by means of the macro
- <STRONG>getmaxyx</STRONG>.
+ members may not have values of the same meaning different
+ implementations. For example, the values of <STRONG>WINDOW._maxx</STRONG> and
+ <STRONG>WINDOW._maxy</STRONG> in <EM>ncurses</EM> have long differed by one from some other
+ implementations. The <STRONG>getmaxyx</STRONG> macro hides this difference.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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.51 2024/04/20 21:20:07 tom Exp @
+ * @Id: curs_inch.3x,v 1.52 2024/05/11 20:39: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>curs_inch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_inch 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_inch 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_inch 3x 2024-05-11 ncurses 6.5 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>
<STRONG>chtype</STRONG> <STRONG>inch(void);</STRONG>
<STRONG>chtype</STRONG> <STRONG>winch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG>
-
<STRONG>chtype</STRONG> <STRONG>mvinch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG>
<STRONG>chtype</STRONG> <STRONG>mvwinch(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>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- These routines return the character, of type <STRONG>chtype</STRONG>, at the current
- position in the named window. If any attributes are set for that
- position, their values are OR'ed into the value returned. Constants
- defined in <STRONG><curses.h></STRONG> can be used with the <STRONG>&</STRONG> (logical AND) operator to
- extract the character or attributes alone.
-
-
-</PRE><H3><a name="h3-Attributes">Attributes</a></H3><PRE>
- The following bit masks may be AND-ed with characters returned by
- <STRONG>winch</STRONG>.
-
- <STRONG>Name</STRONG> <STRONG>Description</STRONG>
- ------------------------------------------------------------------------
- <STRONG>A_CHARTEXT</STRONG> Extract character
- <STRONG>A_ATTRIBUTES</STRONG> Extract attributes
- <STRONG>A_COLOR</STRONG> Extract color pair information
+ <STRONG>winch</STRONG> returns the <EM>curses</EM> character, including rendering attributes and
+ color pair identifier, at the cursor position in the window <EM>win</EM>.
+ Subsection "Video Attributes" of <STRONG><A HREF="curs_attr.3x.html">attron(3x)</A></STRONG> explains how to extract
+ these data from a <EM>chtype</EM>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this
+ function.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Functions prefixed with "mv" first perform cursor movement and fail if
+ Functions prefixed with "mv" first perform cursor movement and fail if
the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
- The <STRONG>winch</STRONG> function does not return an error if the window contains
- characters larger than 8-bits (255). Only the low-order 8 bits of the
- character are used by <STRONG>winch</STRONG>.
+ These functions do not return an error if the window comprises cells of
+ <EM>curses</EM> complex characters (that is, they contain characters with codes
+ wider than eight bits, or greater than 255 as an unsigned decimal
+ integer). They instead extract only the low-order eight bits of
+ character data in the cell.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- Note that all of these routines may be macros.
+ <STRONG>inch</STRONG>, <STRONG>mvinch</STRONG>, and <STRONG>mvwinch</STRONG> may be implemented as macros.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These functions are described in X/Open Curses, Issue 4.
+ X/Open Curses, Issue 4 describes these functions. It specifies no
+ error conditions for them.
- Very old systems (before standardization) provide a different function
- with the same name:
- <STRONG>o</STRONG> The <STRONG>winch</STRONG> function was part of the original BSD curses library,
- which stored a 7-bit character combined with the <EM>standout</EM>
- attribute.
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+ <STRONG>winch</STRONG> was implemented in the original 4BSD <EM>curses</EM> library (November
+ 1980). It returned only the character code (as an integer) with the
+ "standout" attribute bit (the only one it supported) cleared. Because
+ 7-bit ASCII was the only character encoding supported, 4BSD's <STRONG>winch</STRONG>
+ returned a <EM>char</EM> type.
- In BSD curses, <STRONG>winch</STRONG> returned only the character (as an integer)
- with the <EM>standout</EM> attribute removed.
+ System V <EM>curses</EM> (1983) permitted several rendering attributes to be
+ combined with a character in a window. Reflecting this improvement,
+ <STRONG>winch</STRONG> returned an <EM>int</EM> in SVr3.2 (1988) and switched to <EM>chtype</EM> in SVr4
+ (1989).
- <STRONG>o</STRONG> System V curses added support for several video attributes which
- could be combined with characters in the window.
-
- Reflecting this improvement, the function was altered to return the
- character combined with all video attributes in a <STRONG>chtype</STRONG> value.
-
- X/Open Curses does not specify the size and layout of attributes, color
- and character values in <STRONG>chtype</STRONG>; it is implementation-dependent. This
- implementation uses 8 bits for character values. An application using
- more bits, e.g., a Unicode value, should use the wide-character
- equivalents to these functions.
+ X/Open Curses does not specify the sizes of the character code or color
+ pair identifier, nor the quantity of rendering attribute bits, in
+ <EM>chtype</EM>; these are implementation-dependent. <EM>ncurses</EM> uses eight bits
+ for the character code. An application requiring a wider character
+ type, for instance to handle Unicode, should use the wide-character
+ counterparts of these functions.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
-<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
-<ul>
-<li><a href="#h3-Attributes">Attributes</a></li>
-</ul>
-</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>
</ul>
</div>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_mouse.3x,v 1.98 2024/04/20 19:02:07 tom Exp @
+ * @Id: curs_mouse.3x,v 1.99 2024/05/11 20:39: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>curs_mouse 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_mouse 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_mouse 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_mouse 3x 2024-05-11 ncurses 6.5 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>
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 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.
+ An <EM>ncurses</EM> window must enable <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> to correctly receive mouse
+ event reports from <EM>xterm</EM> since they are encoded like function keys.
+ Set 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
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(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.64 2024/04/20 21:24:19 tom Exp @
+ * @Id: curs_outopts.3x,v 1.65 2024/05/11 20:39: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>curs_outopts 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_outopts 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_outopts 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_outopts 3x 2024-05-11 ncurses 6.5 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-NAME">NAME</a></H2><PRE>
- <STRONG>clearok</STRONG>, <STRONG>idlok</STRONG>, <STRONG>idcok</STRONG>, <STRONG>immedok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>,
- <STRONG>scrollok</STRONG> - set <EM>curses</EM> output options
+ <STRONG>clearok</STRONG>, <STRONG>idcok</STRONG>, <STRONG>idlok</STRONG>, <STRONG>immedok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>scrollok</STRONG>, <STRONG>setscrreg</STRONG>,
+ <STRONG>wsetscrreg</STRONG> - set <EM>curses</EM> output options
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
<STRONG>int</STRONG> <STRONG>clearok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
- <STRONG>int</STRONG> <STRONG>idlok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>void</STRONG> <STRONG>idcok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
+ <STRONG>int</STRONG> <STRONG>idlok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>void</STRONG> <STRONG>immedok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>leaveok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>scrollok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
repainted from scratch.
+</PRE><H3><a name="h3-idcok">idcok</a></H3><PRE>
+ If <STRONG>idcok</STRONG> is called with <STRONG>FALSE</STRONG> as second argument, <STRONG>curses</STRONG> no longer
+ considers using the hardware insert/delete character feature of
+ terminals so equipped. Use of character insert/delete is enabled by
+ default. Calling <STRONG>idcok</STRONG> with <STRONG>TRUE</STRONG> as second argument re-enables use of
+ character insertion and deletion.
+
+
</PRE><H3><a name="h3-idlok">idlok</a></H3><PRE>
If <STRONG>idlok</STRONG> is called with <STRONG>TRUE</STRONG> as second argument, <STRONG>curses</STRONG> considers using
the hardware insert/delete line feature of terminals so equipped.
changed portions of all lines.
-</PRE><H3><a name="h3-idcok">idcok</a></H3><PRE>
- If <STRONG>idcok</STRONG> is called with <STRONG>FALSE</STRONG> as second argument, <STRONG>curses</STRONG> no longer
- considers using the hardware insert/delete character feature of
- terminals so equipped. Use of character insert/delete is enabled by
- default. Calling <STRONG>idcok</STRONG> with <STRONG>TRUE</STRONG> as second argument re-enables use of
- character insertion and deletion.
-
-
</PRE><H3><a name="h3-immedok">immedok</a></H3><PRE>
If <STRONG>immedok</STRONG> is called with <STRONG>TRUE</STRONG> as second argument, any change in the
window image, such as the ones caused by <STRONG>waddch,</STRONG> <STRONG>wclrtobot,</STRONG> <STRONG>wscrl</STRONG>,
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-clearok">clearok</a></li>
-<li><a href="#h3-idlok">idlok</a></li>
<li><a href="#h3-idcok">idcok</a></li>
+<li><a href="#h3-idlok">idlok</a></li>
<li><a href="#h3-immedok">immedok</a></li>
<li><a href="#h3-leaveok">leaveok</a></li>
<li><a href="#h3-scrollok">scrollok</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_sp_funcs.3x,v 1.50 2024/04/20 18:56:31 tom Exp @
+ * @Id: curs_sp_funcs.3x,v 1.51 2024/05/11 20:39: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>curs_sp_funcs 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_sp_funcs 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_sp_funcs 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_sp_funcs 3x 2024-05-11 ncurses 6.5 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>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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_termattrs.3x,v 1.41 2024/04/20 21:20:07 tom Exp @
+ * @Id: curs_termattrs.3x,v 1.42 2024/05/11 20:39: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>curs_termattrs 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_termattrs 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_termattrs 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_termattrs 3x 2024-05-11 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
<STRONG>baudrate</STRONG>, <STRONG>erasechar</STRONG>, <STRONG>erasewchar</STRONG>, <STRONG>has_ic</STRONG>, <STRONG>has_il</STRONG>, <STRONG>killchar</STRONG>, <STRONG>killwchar</STRONG>,
- <STRONG>longname</STRONG>, <STRONG>term_attrs</STRONG>, <STRONG>termattrs</STRONG>, <STRONG>termname</STRONG> - <EM>curses</EM> environment query
- routines
+ <STRONG>longname</STRONG>, <STRONG>term_attrs</STRONG>, <STRONG>termattrs</STRONG>, <STRONG>termname</STRONG> - get and set terminal
+ attributes with <EM>curses</EM>
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(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.101 2024/04/20 21:20:07 tom Exp @
+ * @Id: curs_util.3x,v 1.102 2024/05/11 20:39: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>curs_util 3x 2024-04-20 ncurses 6.5 Library calls</TITLE>
+<TITLE>curs_util 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_util 3x 2024-04-20 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">curs_util 3x 2024-05-11 ncurses 6.5 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>void</STRONG> <STRONG>filter(void);</STRONG>
- <STRONG>void</STRONG> <STRONG>use_env(bool</STRONG> <EM>f</EM><STRONG>);</STRONG>
+ <STRONG>void</STRONG> <STRONG>use_env(bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
<STRONG>int</STRONG> <STRONG>putwin(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG><EM>filep</EM><STRONG>);</STRONG>
<STRONG>WINDOW</STRONG> <STRONG>*getwin(FILE</STRONG> <STRONG>*</STRONG><EM>filep</EM><STRONG>);</STRONG>
<EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
<STRONG>void</STRONG> <STRONG>nofilter(void);</STRONG>
- <STRONG>void</STRONG> <STRONG>use_tioctl(bool</STRONG> <EM>f</EM><STRONG>);</STRONG>
+ <STRONG>void</STRONG> <STRONG>use_tioctl(bool</STRONG> <EM>bf</EM><STRONG>);</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
<STRONG>use_env</STRONG> <STRONG>use_tioctl</STRONG> <STRONG>Summary</STRONG>
-----------------------------------------------------------------
- <STRONG>TRUE</STRONG> <STRONG>FALSE</STRONG> This is the default behavior. <EM>ncurses</EM>
- uses operating system calls unless
- overridden by <EM>LINES</EM> or <EM>COLUMNS</EM>
+ <STRONG>TRUE</STRONG> <STRONG>FALSE</STRONG> <EM>ncurses</EM> uses operating system calls
+ unless overridden by <EM>LINES</EM> or <EM>COLUMNS</EM>
environment variables; default.
- <STRONG>TRUE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> updates <EM>LINES</EM> and <EM>COLUMNS</EM> based
+ <STRONG>TRUE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> updates <EM>LINES</EM> and <EM>COLUMNS</EM> based
on operating system calls.
- <STRONG>FALSE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> ignores <EM>LINES</EM> and <EM>COLUMNS</EM>, using
+ <STRONG>FALSE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> ignores <EM>LINES</EM> and <EM>COLUMNS</EM>, using
operating system calls to obtain size.
</PRE><H3><a name="h3-putwin_getwin">putwin, getwin</a></H3><PRE>
- The <STRONG>putwin</STRONG> routine writes all data associated with window (or pad) <EM>win</EM>
- into the file to which <EM>filep</EM> points. This information can be later
+ The <STRONG>putwin</STRONG> routine writes all data associated with window (or pad) <EM>win</EM>
+ into the file to which <EM>filep</EM> points. This information can be later
retrieved using the <STRONG>getwin</STRONG> function.
- The <STRONG>getwin</STRONG> routine reads window related data stored in the file by
- <STRONG>putwin</STRONG>. The routine then creates and initializes a new window using
- that data. It returns a pointer to the new window. There are a few
+ The <STRONG>getwin</STRONG> routine reads window related data stored in the file by
+ <STRONG>putwin</STRONG>. The routine then creates and initializes a new window using
+ that data. It returns a pointer to the new window. There are a few
caveats:
- <STRONG>o</STRONG> the data written is a copy of the <EM>WINDOW</EM> structure, and its
- associated character cells. The format differs between the wide-
- character (<EM>ncursesw</EM>) and non-wide (<EM>ncurses</EM>) libraries. You can
+ <STRONG>o</STRONG> the data written is a copy of the <EM>WINDOW</EM> structure, and its
+ associated character cells. The format differs between the wide-
+ 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
+ <STRONG>o</STRONG> the retrieved window is always created as a top-level window (or
pad), rather than a subwindow.
- <STRONG>o</STRONG> the window's character cells contain the color pair <EM>value</EM>, but not
- the actual color <EM>numbers</EM>. If cells in the retrieved window use
- color pairs which have not been created in the application using
+ <STRONG>o</STRONG> the window's character cells contain the color pair <EM>value</EM>, but not
+ the actual color <EM>numbers</EM>. If cells in the retrieved window use
+ color pairs which have not been created in the application using
<STRONG>init_pair</STRONG>, they will not be colored when the window is refreshed.
</PRE><H3><a name="h3-delay_output">delay_output</a></H3><PRE>
- The <STRONG>delay_output</STRONG> routine inserts an <EM>ms</EM> millisecond pause in output.
- Employ this function judiciously when terminal output uses padding,
- because <EM>ncurses</EM> transmits null characters (consuming CPU and I/O
- resources) instead of sleeping and requesting resumption from the
+ The <STRONG>delay_output</STRONG> routine inserts an <EM>ms</EM> millisecond pause in output.
+ Employ this function judiciously when terminal output uses padding,
+ because <EM>ncurses</EM> transmits null characters (consuming CPU and I/O
+ resources) instead of sleeping and requesting resumption from the
operating system. Padding is used unless:
<STRONG>o</STRONG> the terminal description has <STRONG>npc</STRONG> (<STRONG>no_pad_char</STRONG>) capability, or
<STRONG>o</STRONG> the environment variable <STRONG>NCURSES_NO_PADDING</STRONG> is set.
- If padding is not in use, <EM>ncurses</EM> uses <STRONG>napms</STRONG> to perform the delay. If
- the value of <EM>ms</EM> exceeds 30,000 (thirty seconds), it is capped at that
+ If padding is not in use, <EM>ncurses</EM> uses <STRONG>napms</STRONG> to perform the delay. If
+ the value of <EM>ms</EM> exceeds 30,000 (thirty seconds), it is capped at that
value.
</PRE><H3><a name="h3-flushinp">flushinp</a></H3><PRE>
- The <STRONG>flushinp</STRONG> routine throws away any typeahead that has been typed by
+ The <STRONG>flushinp</STRONG> routine throws away any typeahead that has been typed by
the user and has not yet been read by the program.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Except for <STRONG>flushinp</STRONG>, 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>")
+ Except for <STRONG>flushinp</STRONG>, 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.
Routines that return pointers return <STRONG>NULL</STRONG> on error.
- X/Open Curses does not specify any error conditions. In this
+ X/Open Curses does not specify any error conditions. In this
implementation
<STRONG>flushinp</STRONG>
returns an error if the terminal was not initialized.
<STRONG>putwin</STRONG>
- returns an error if the associated <STRONG>fwrite</STRONG> calls return an
+ returns an error if the associated <STRONG>fwrite</STRONG> calls return an
error.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
</PRE><H3><a name="h3-filter">filter</a></H3><PRE>
- The SVr4 documentation describes the action of <STRONG>filter</STRONG> only in the
- vaguest terms. The description here is adapted from X/Open Curses
+ The SVr4 documentation describes the action of <STRONG>filter</STRONG> only in the
+ vaguest terms. The description here is adapted from X/Open Curses
(which erroneously fails to describe the disabling of <STRONG>cuu</STRONG>).
</PRE><H3><a name="h3-delay_output-padding">delay_output padding</a></H3><PRE>
- The limitation to 30 seconds and the use of <STRONG>napms</STRONG> differ from other
+ The limitation to 30 seconds and the use of <STRONG>napms</STRONG> differ from other
implementations.
<STRONG>o</STRONG> SVr4 curses does not delay if no padding character is available.
- <STRONG>o</STRONG> NetBSD curses uses <STRONG>napms</STRONG> when no padding character is available,
- but does not take timing into account when using the padding
+ <STRONG>o</STRONG> NetBSD curses uses <STRONG>napms</STRONG> when no padding character is available,
+ but does not take timing into account when using the padding
character.
Neither limits the delay.
</PRE><H3><a name="h3-keyname">keyname</a></H3><PRE>
- The <STRONG>keyname</STRONG> function may return the names of user-defined string
- capabilities which are defined in the terminfo entry via the <STRONG>-x</STRONG> option
+ The <STRONG>keyname</STRONG> function may return the names of user-defined string
+ capabilities which are defined in the terminfo entry via the <STRONG>-x</STRONG> option
of <STRONG>tic</STRONG>. This implementation automatically assigns at run-time keycodes
- to user-defined strings which begin with "k". The keycodes start at
+ to user-defined strings which begin with "k". The keycodes start at
KEY_MAX, but are not guaranteed to be the same value for different runs
- because user-defined codes are merged from all terminal descriptions
- which have been loaded. The <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG> function controls
- whether this data is loaded when the terminal description is read by
+ because user-defined codes are merged from all terminal descriptions
+ which have been loaded. The <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG> function controls
+ whether this data is loaded when the terminal description is read by
the library.
</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 <EM>ncurses</EM>. They
- were not supported on Version 7, BSD or System V implementations. It
- is recommended that any code depending on <EM>ncurses</EM> extensions be
+ 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 <EM>ncurses</EM> extensions be
conditioned using <STRONG>NCURSES_VERSION</STRONG>.
</PRE><H3><a name="h3-putwin_getwin-file-format">putwin/getwin file-format</a></H3><PRE>
The <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG> functions have several issues with portability:
- <STRONG>o</STRONG> The files written and read by these functions use an
- implementation-specific format. Although the format is an obvious
+ <STRONG>o</STRONG> The files written and read by these functions use an
+ implementation-specific format. Although the format is an obvious
target for standardization, it has been overlooked.
- Interestingly enough, according to the copyright dates in Solaris
- source, the functions (along with <STRONG>scr_init</STRONG>, etc.) originated with
+ Interestingly enough, according to the copyright dates in Solaris
+ source, the functions (along with <STRONG>scr_init</STRONG>, etc.) originated with
the University of California, Berkeley (in 1982) and were later (in
- 1988) incorporated into SVr4. Oddly, there are no such functions
+ 1988) incorporated into SVr4. Oddly, there are no such functions
in the 4.3BSD curses sources.
<STRONG>o</STRONG> Most implementations simply dump the binary <EM>WINDOW</EM> structure to the
- file. These include SVr4 curses, NetBSD and PDCurses, as well as
+ file. These include SVr4 curses, NetBSD and PDCurses, as well as
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
- <STRONG>fwrite</STRONG> and <STRONG>fread</STRONG> functions). Those that use textual dumps use
+ The implementations which use binary dumps use block-I/O (the
+ <STRONG>fwrite</STRONG> and <STRONG>fread</STRONG> functions). Those that use textual dumps use
buffered-I/O. A few applications may happen to write extra data in
- the file using these functions. Doing that can run into problems
- mixing block- and buffered-I/O. This implementation reduces the
- problem on writes by flushing the output. However, reading from a
+ the file using these functions. Doing that can run into problems
+ mixing block- and buffered-I/O. This implementation reduces the
+ problem on writes by flushing the output. However, reading from a
file written using mixed schemes may not be successful.
</PRE><H3><a name="h3-unctrl_wunctrl">unctrl, wunctrl</a></H3><PRE>
- X/Open Curses, Issue 4 describes these functions. It states that
+ X/Open Curses, Issue 4 describes these functions. It states that
<STRONG>unctrl</STRONG> and <STRONG>wunctrl</STRONG> will return a null pointer if unsuccessful, but does
- not define any error conditions. This implementation checks for three
+ not define any error conditions. This implementation checks for three
cases:
- <STRONG>o</STRONG> the parameter is a 7-bit US-ASCII code. This is the case that
+ <STRONG>o</STRONG> the parameter is a 7-bit US-ASCII code. This is the case that
X/Open Curses documented.
<STRONG>o</STRONG> the parameter is in the range 128-159, i.e., a C1 control code. If
- <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> has been called with a <STRONG>2</STRONG> parameter, <STRONG>unctrl</STRONG>
- returns the parameter, i.e., a one-character string with the
- parameter as the first character. Otherwise, it returns "~@",
+ <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> has been called with a <STRONG>2</STRONG> parameter, <STRONG>unctrl</STRONG>
+ returns the parameter, i.e., a one-character string with the
+ parameter as the first character. Otherwise, it returns "~@",
"~A", etc., analogous to "^@", "^A", C0 controls.
X/Open Curses does not document whether <STRONG>unctrl</STRONG> can be called before
pointer.
The strings returned by <STRONG>unctrl</STRONG> in this implementation are determined at
- compile time, showing C1 controls from the upper-128 codes with a "~"
- prefix rather than "^". Other implementations have different
- conventions. For example, they may show both sets of control
- characters with "^", and strip the parameter to 7 bits. Or they may
- ignore C1 controls and treat all of the upper-128 codes as printable.
- This implementation uses 8 bits but does not modify the string to
- reflect locale. The <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> function allows the caller
+ compile time, showing C1 controls from the upper-128 codes with a "~"
+ prefix rather than "^". Other implementations have different
+ conventions. For example, they may show both sets of control
+ characters with "^", and strip the parameter to 7 bits. Or they may
+ ignore C1 controls and treat all of the upper-128 codes as printable.
+ This implementation uses 8 bits but does not modify the string to
+ reflect locale. The <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> function allows the caller
to change the output of <STRONG>unctrl</STRONG>.
- Likewise, the <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> function allows the caller to change the output
- of <STRONG>keyname</STRONG>, i.e., it determines whether to use the "M-" prefix for
- "meta" keys (codes in the range 128 to 255). Both
- <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> and <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> succeed only after curses is
- initialized. X/Open Curses does not document the treatment of codes
+ Likewise, the <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> function allows the caller to change the output
+ of <STRONG>keyname</STRONG>, i.e., it determines whether to use the "M-" prefix for
+ "meta" keys (codes in the range 128 to 255). Both
+ <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> and <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> succeed only after curses is
+ initialized. X/Open Curses does not document the treatment of codes
128 to 159. When treating them as "meta" keys (or if <STRONG>keyname</STRONG> is called
- before initializing curses), this implementation returns strings
+ 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 <EM>ncurses</EM>
- does. However, <EM>ncurses</EM>' <STRONG><curses.h></STRONG> includes <STRONG><unctrl.h></STRONG>, matching the
+ 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 <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
+ 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.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,
<STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,
<STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,
<STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>, <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
<STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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: infocmp.1m,v 1.109 2024/03/16 15:35:01 tom Exp @
+ * @Id: infocmp.1m,v 1.110 2024/05/11 20:39: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>infocmp 1m 2024-03-16 ncurses 6.5 User commands</TITLE>
+<TITLE>infocmp 1m 2024-05-11 ncurses 6.5 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">infocmp 1m 2024-03-16 ncurses 6.5 User commands</H1>
+<H1 class="no-header">infocmp 1m 2024-05-11 ncurses 6.5 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>
-ncurses 6.5 2024-0
3-16 <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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.41 2024/03/16 15:35:01 tom Exp @
+ * @Id: infotocap.1m,v 1.42 2024/05/11 20:39: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>infotocap 1m 2024-03-16 ncurses 6.5 User commands</TITLE>
+<TITLE>infotocap 1m 2024-05-11 ncurses 6.5 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">infotocap 1m 2024-03-16 ncurses 6.5 User commands</H1>
+<H1 class="no-header">infotocap 1m 2024-05-11 ncurses 6.5 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.5 2024-0
3-16 <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: ncurses.3x,v 1.214 2024/04/27 17:55:43 tom Exp @
+ * @Id: ncurses.3x,v 1.215 2024/05/11 20:39: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>ncurses 3x 2024-04-27 ncurses 6.5 Library calls</TITLE>
+<TITLE>ncurses 3x 2024-05-11 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">ncurses 3x 2024-04-27 ncurses 6.5 Library calls</H1>
+<H1 class="no-header">ncurses 3x 2024-05-11 ncurses 6.5 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>
terminals with output optimized to minimize screen updates. <EM>ncurses</EM>
replaces the <EM>curses</EM> libraries from System V Release 4 Unix ("SVr4") and
4.4BSD Unix, the development of which ceased in the 1990s. This
- document describes <EM>ncurses</EM> version 6.5 (patch 20240427).
+ document describes <EM>ncurses</EM> version 6.5 (patch 20240511).
<EM>ncurses</EM> permits control of the terminal screen's contents; abstraction
- and subdivision thereof with <EM>windows</EM> and <EM>pads</EM>; the reading of terminal
- input; control of terminal input and output options; environment query
- routines; color manipulation; the definition and use of <EM>soft</EM> <EM>label</EM>
- keys; <EM>terminfo</EM> capability access; a <EM>termcap</EM> compatibility interface;
- and an abstraction of the system's API for manipulating the terminal
- (such as <STRONG>termios(3)</STRONG>).
-
- <EM>ncurses</EM> implements the standard interface described by X/Open Curses
- Issue 7. In many behavioral details not standardized by X/Open,
- <EM>ncurses</EM> emulates the <EM>curses</EM> library of SVr4 and provides numerous
- useful extensions.
+ and subdivision thereof with <EM>windows</EM> and <EM>pads</EM>; acquisition of keyboard
+ and mouse events; control of terminal input and output options;
+ selection of color and rendering attributes (such as bold or
+ underline); the definition and use of <EM>soft</EM> <EM>label</EM> keys; access to the
+ <EM>terminfo</EM> terminal capability database; a <EM>termcap</EM> compatibility
+ interface; and an abstraction of the system's API for manipulating the
+ terminal (such as <STRONG>termios(3)</STRONG>).
+
+ <EM>ncurses</EM> implements the interface described by X/Open Curses Issue 7.
+ In many behavioral details not standardized by X/Open, <EM>ncurses</EM> emulates
+ the <EM>curses</EM> library of SVr4 and provides numerous useful extensions.
<EM>ncurses</EM> man pages employ several sections to clarify matters of usage
and interoperability with other <EM>curses</EM> implementations.
cursor and write a character to <STRONG>stdscr</STRONG>, respectively.
Frequent changes to the terminal screen can cause unpleasant flicker or
- inefficient use of the communication channel to the device, so the
- library does not generally update it automatically. Therefore, after
+ inefficient use of the communication channel to the device, so as a
+ rule the library does not update it automatically. 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>. The library <EM>optimizes</EM> its output
- by computing a minimal number of operations to mutate the screen from
+ by computing a minimal volume of operations to mutate the screen from
its state at the previous refresh to the new one. Effective
optimization demands accurate information about the terminal device:
the management of such information is the province of the <STRONG><A HREF="curs_terminfo.3x.html">terminfo(3x)</A></STRONG>
API, a feature of every standard <EM>curses</EM> implementation.
- Special windows called <EM>pads</EM> may also be manipulated. These are windows
- that are not constrained to the size of the terminal screen and whose
-
contents need not be completely displayed. See <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>.
+ Special windows called <EM>pads</EM> may also be manipulated. These are not
+ constrained to the size of the terminal screen and their 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>.
+ Many terminals support configuration of character cell foreground and
+ background colors as well as rendering <EM>attributes</EM> <EM>,</EM> which cause
+ characters to show up in such modes as boldfaced, underlined, or in
+
reverse video. See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>.
<EM>curses</EM> predefines constants for a small set of forms-drawing graphics
corresponding to the DEC Alternate Character Set (ACS), a feature of
- VT100 and other terminals. See <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG>.
+ VT100 and other terminals. See <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>.
- <EM>curses</EM> is implemented using the operating system's terminal driver;
- keystroke events are received not as scan codes but as byte sequences.
- Graphical keycaps (alphanumeric and punctuation keys, and the space)
- 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>.
+ <EM>curses</EM> is implemented using the operating system's terminal driver; key
+ events are received not as scan codes but as byte sequences. Graphical
+ keycaps (alphanumeric and punctuation keys, and the space) appear as-
+ is. Everything else, including the tab, enter/return, keypad, arrow,
+ and function keys, appears as a control character or a multibyte <EM>escape</EM>
+ <EM>sequence.</EM> <EM>curses</EM> translates the latter into unique <EM>key</EM> <EM>codes.</EM> See
+ <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>.
<EM>ncurses</EM> provides reimplementations of the SVr4 <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, and
- <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> libraries to ease construction of user interfaces with <EM>curses</EM>.
+ <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> libraries; they permit overlapping windows and ease
+ construction of user interfaces with <EM>curses</EM>.
</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
- The selection of an appropriate value of <EM>TERM</EM> in the process
+ The selection of an appropriate 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
+ 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 you change the terminal type, export the <EM>TERM</EM> environment variable
- in the shell, then run <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> or the "<STRONG>tput</STRONG> <STRONG>init</STRONG>" command. See
-
subsection "Tabs and Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
+ If you change the terminal type, export the shell's <EM>TERM</EM> variable, then
+ run <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> or the "<STRONG>tput</STRONG> <STRONG>init</STRONG>" command. See subsection "Tabs and
+ Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
- If the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> are set, or if the
- <EM>curses</EM> program is executing in a graphical windowing environment, the
- information obtained thence overrides that obtained by <EM>terminfo</EM>. An
+ If the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> are set, or if the
+ <EM>curses</EM> program is executing in a graphical windowing environment, the
+ information obtained thence overrides that obtained by <EM>terminfo</EM>. An
<EM>ncurses</EM> extension supports resizable terminals; see <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>.
- If the environment variable <EM>TERMINFO</EM> is defined, a <EM>curses</EM> program
- checks first for a terminal type description in the location it
- identifies. <EM>TERMINFO</EM> is useful for developing experimental type
- descriptions or when write permission to <EM>/usr/share/terminfo</EM> is not
- available.
+ 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 type descriptions or
+ when write permission to <EM>/usr/share/terminfo</EM> is not available.
See section "ENVIRONMENT" below.
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>bf</EM> a <EM>bool</EM> (<STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>)
<EM>c</EM> a <EM>char</EM> or <EM>int</EM>
<EM>ch</EM> a <EM>chtype</EM>
<EM>wc</EM> a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> or <EM>wint</EM><STRONG>_</STRONG><EM>t</EM>
</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.
+ This man page primarily surveys 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, which is often an alias of <EM>int</EM>.
+ attributes and a color pair in a <EM>chtype</EM> datum, which is often
+ an alias of <EM>int</EM>. A string of <EM>curses</EM> characters is similar to
+ a C <EM>char</EM> string; a <EM>chtype</EM> string ends with an integral <STRONG>0</STRONG>, the
+ null <EM>curses</EM> character.
- 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.
+ Attributes and a color pair selection (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 accessed via an integral bit
+ mask.
Each cell of a <EM>WINDOW</EM> is stored as a <EM>chtype</EM>.
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>.
+ more non-spacing characters (see below). A string
+ of complex characters ends with a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> whose
+ <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> member is the null wide character.
+ Attributes and a color pair selection are stored in
+ separate fields of the structure, not combined into
+ an integer as in <EM>chtype</EM>.
Each cell of a <EM>WINDOW</EM> is stored as a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>.
- <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> store and retrieve <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>
- data. The wide library API of <EM>ncurses</EM> depends on two data
+ <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> store and retrieve <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>
+ data. 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>, it may be an
- alias of <EM>int</EM>. Depending on the character encoding,
- a wide character may be <EM>spacing</EM>, meaning that it
- occupies a character cell by itself and typically
- accompanies cursor advancement, or <EM>non-spacing</EM>,
- meaning that it occupies the same cell as a spacing
- character, is often regarded as a "modifier" of the
- base glyph with which it combines, and typically
+ <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> stores a wide character. Like <EM>chtype</EM>, it may be an
+ alias of <EM>int</EM>. Depending on the character encoding,
+ a wide character may be <EM>spacing</EM>, meaning that it
+ occupies a character cell by itself and typically
+ accompanies cursor advancement, or <EM>non-spacing</EM>,
+ meaning that it occupies the same cell as a spacing
+ character, is often regarded as a "modifier" of the
+ base glyph with which it combines, and typically
does not advance the cursor.
- <EM>wint</EM><STRONG>_</STRONG><EM>t</EM> can store a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> or the constant <STRONG>WEOF</STRONG>,
- analogously to the <EM>int</EM>-sized character manipulation
+ <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 its 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>.
- (Exceptions that add only "w" comprise <STRONG>addwstr</STRONG>, <STRONG>inwstr</STRONG>, and
+ 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>.
+ (Exceptions that add only "w" comprise <STRONG>addwstr</STRONG>, <STRONG>inwstr</STRONG>, and
their variants.)
- This convention is inapplicable to some non-wide function
+ This convention is inapplicable to some non-wide function
names, so other transformations are used for the wide
configuration: the window background management function
- "bkgd" becomes "bkgrnd"; the window border-drawing and
- -clearing functions are suffixed with "_set"; and character
- attribute manipulation functions like "attron" become
+ "bkgd" becomes "bkgrnd"; the window border-drawing and
+ -clearing functions are suffixed with "_set"; and character
+ attribute manipulation functions like "attron" become
"attr_on".
</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
+ 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
delch <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG>
deleteln <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG>
delscreen <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>
+
delwin <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
derwin <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
doupdate <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
dupwin <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
echo <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
-
echo_wchar <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
echochar <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
endwin <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>
inchstr <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>
init_color <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
init_extended_color <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>*
+
init_extended_pair <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>*
init_pair <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
initscr <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>
innstr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
-
innwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
ins_nwstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
ins_wch <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>
mvcur <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
mvdelch <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG>
mvderwin <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
+
mvget_wch <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
mvget_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
mvgetch <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
-
mvgetn_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
mvgetnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
mvgetstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
mvwinstr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
mvwinwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
mvwprintw <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>
+
mvwscanw <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>
mvwvline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
-
mvwvline_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
napms <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
newpad <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
slk_color <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
slk_init <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
slk_label <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
- slk_noutrefresh <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
+ slk_noutrefresh <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
slk_refresh <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
slk_restore <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
slk_set <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
wscanw <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>
wscrl <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
wsetscrreg <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
-
wstandend <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
+
wstandout <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
wsyncdown <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
wsyncup <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
wvline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
wvline_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
- <EM>ncurses</EM>'s <EM>screen-pointer</EM> <EM>extension</EM> adds additional functions
- corresponding to many of the above, each with an "_sp" suffix; see
+ <EM>ncurses</EM>'s <EM>screen-pointer</EM> <EM>extension</EM> adds additional functions
+ corresponding to many of the above, each with an "_sp" suffix; see
<STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>.
- The availability of some extensions is configurable when <EM>ncurses</EM> is
- compiled; see sections "ALTERNATE CONFIGURATIONS" and "EXTENSIONS"
+ The availability of some extensions is configurable when <EM>ncurses</EM> is
+ compiled; see sections "ALTERNATE CONFIGURATIONS" and "EXTENSIONS"
below.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Unless otherwise noted, functions that return an integer return <STRONG>OK</STRONG> on
- success and <STRONG>ERR</STRONG> on failure. Functions that return pointers return <STRONG>NULL</STRONG>
- on failure. Typically, <EM>ncurses</EM> treats a null pointer passed as a
- function parameter as a failure. Functions prefixed with "mv" first
- perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the
- window boundaries.
+ Unless otherwise noted, functions that return integers return the
+ constants <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
+ Functions that return pointers return <STRONG>NULL</STRONG> on failure. Typically,
+ <EM>ncurses</EM> treats a null pointer passed as a function parameter as a
+ failure. Functions prefixed with "mv" first perform cursor movement
+ and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.
</PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
- The following symbols from the process environment customize the
- runtime behavior of <EM>ncurses</EM> applications. The library may be
- configured to disregard the variables <EM>TERMINFO</EM>, <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM>,
- <EM>TERMPATH</EM>, and <EM>HOME</EM>, if the user is the superuser (root), or the
+ The following symbols from the process environment customize the
+ runtime behavior of <EM>ncurses</EM> applications. The library may be
+ configured to disregard the variables <EM>TERMINFO</EM>, <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM>,
+ <EM>TERMPATH</EM>, and <EM>HOME</EM>, if the user is the superuser (root), or the
application uses <STRONG>setuid(2)</STRONG> or <STRONG>setgid(2)</STRONG>.
</PRE><H3><a name="h3-BAUDRATE"><EM>BAUDRATE</EM></a></H3><PRE>
- The debugging library checks this variable when the application has
- redirected output to a file. Its integral value is used for the baud
- rate. If that value is absent or invalid, <EM>ncurses</EM> uses 9600. This
- feature allows testers to construct repeatable test cases that take
+ The debugging library checks this variable when the application has
+ redirected output to a file. Its integral value is used for the baud
+ rate. If that value is absent or invalid, <EM>ncurses</EM> uses 9600. This
+ feature allows developers to construct repeatable test cases that take
into account optimization decisions that depend on baud rate.
</PRE><H3><a name="h3-CC-_command-character_"><EM>CC</EM> (command character)</a></H3><PRE>
- When set, the <STRONG>command_character</STRONG> (<STRONG>cmdch</STRONG>) capability value of loaded
+ When set, the <STRONG>command_character</STRONG> (<STRONG>cmdch</STRONG>) capability value of loaded
<EM>terminfo</EM> entries changes to the value of this variable. Very few <EM>term-</EM>
<EM>info</EM> entries provide this feature.
Because this name is also used in development environments to represent
- the C compiler's name, <EM>ncurses</EM> ignores its value if it is not one
+ the C compiler's name, <EM>ncurses</EM> ignores its value if it is not one
character in length.
</PRE><H3><a name="h3-COLUMNS"><EM>COLUMNS</EM></a></H3><PRE>
This variable specifies the width of the screen in characters.
- Applications running in a windowing environment usually are able to
+ Applications running in a windowing environment usually are able to
obtain the width of the window in which they are executing. If <EM>COLUMNS</EM>
is not defined and the terminal's screen size is not available from the
- terminal driver, <EM>ncurses</EM> uses the size specified by the <STRONG>columns</STRONG> (<STRONG>cols</STRONG>)
- capability of the terminal type's entry in the <EM>terminfo</EM> database, if
+ terminal driver, <EM>ncurses</EM> uses the size specified by the <STRONG>columns</STRONG> (<STRONG>cols</STRONG>)
+ capability of the terminal type's entry in the <EM>terminfo</EM> database, if
any.
- It is important that your application use the correct screen size.
- Automatic detection thereof is not always possible because an
- application may be running on a host that does not honor NAWS
- (Negotiations About Window Size) or as a different user ID than the
- owner of the terminal device file. Setting <EM>COLUMNS</EM> and/or <EM>LINES</EM>
- overrides the library's use of the screen size obtained from the
+ It is important that your application use the correct screen size.
+ Automatic detection thereof is not always possible because an
+ application may be running on a host that does not honor NAWS
+ (Negotiations About Window Size) or as a different user ID than the
+ owner of the terminal device file. Setting <EM>COLUMNS</EM> and/or <EM>LINES</EM>
+ overrides the library's use of the screen size obtained from the
operating system.
- The <EM>COLUMNS</EM> and <EM>LINES</EM> variables may be specified independently. This
- property is useful to circumvent misfeatures of legacy terminal type
- descriptions; <STRONG>xterm(1)</STRONG> descriptions specifying 65 lines were once
- notorious. For best results, avoid specifying <STRONG>cols</STRONG> and <STRONG>lines</STRONG>
+ The <EM>COLUMNS</EM> and <EM>LINES</EM> variables may be specified independently. This
+ property is useful to circumvent misfeatures of legacy terminal type
+ descriptions; <STRONG>xterm(1)</STRONG> descriptions specifying 65 lines were once
+ notorious. For best results, avoid specifying <STRONG>cols</STRONG> and <STRONG>lines</STRONG>
capability codes in <EM>terminfo</EM> descriptions of terminal emulators.
- <STRONG><A HREF="curs_util.3x.html">use_env(3x)</A></STRONG> can disable use of the process environment in determining
- the screen size. <STRONG><A HREF="curs_util.3x.html">use_tioctl(3x)</A></STRONG> can update <EM>COLUMNS</EM> and <EM>LINES</EM> to match
+ <STRONG><A HREF="curs_util.3x.html">use_env(3x)</A></STRONG> can disable use of the process environment in determining
+ the screen size. <STRONG><A HREF="curs_util.3x.html">use_tioctl(3x)</A></STRONG> can update <EM>COLUMNS</EM> and <EM>LINES</EM> to match
the screen size obtained from system calls or the terminal database.
</PRE><H3><a name="h3-ESCDELAY"><EM>ESCDELAY</EM></a></H3><PRE>
- For <EM>curses</EM> to distinguish the ESC character resulting from a user's
- press of the "Escape" key on the input device from one beginning an
+ For <EM>curses</EM> to distinguish the ESC character resulting from a user's
+ press of the "Escape" key on the input device from one beginning an
<EM>escape</EM> <EM>sequence</EM> (as commonly produced by function keys), it waits after
- receiving the escape character to see if further characters are
- available on the input stream within a short interval. A global
- variable <STRONG>ESCDELAY</STRONG> stores this interval in milliseconds. The default
+ receiving the escape character to see if further characters are
+ available on the input stream within a short interval. A global
+ variable <STRONG>ESCDELAY</STRONG> stores this interval in milliseconds. The default
value of 1000 (one second) is adequate for most uses. This environment
variable overrides it.
- The most common instance where you may wish to change this value is to
+ The most common instance where you may wish to change this value is to
work with a remote host over a slow communication channel. If the host
- running a <EM>curses</EM> application does not receive the characters of an
- escape sequence in a timely manner, the library can interpret them as
+ running a <EM>curses</EM> application does not receive the characters of an
+ escape sequence in a timely manner, the library can interpret them as
multiple key stroke events.
<STRONG>xterm(1)</STRONG> mouse events are a form of escape sequence; therefore, if your
- application makes heavy use of multiple-clicking, you may wish to
- lengthen the default value because the delay applies to the composite
+ application makes heavy use of multiple-clicking, you may wish to
+ lengthen the default value because the delay applies to the composite
multi-click event as well as the individual clicks.
- Portable applications should not rely upon the presence of <STRONG>ESCDELAY</STRONG> in
- either form, but setting the environment variable rather than the
+ Portable applications should not rely upon the presence of <STRONG>ESCDELAY</STRONG> in
+ either form, but setting the environment variable rather than the
global variable does not create problems when compiling an application.
- If <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> is disabled for the <EM>curses</EM> window receiving input, a
+ If <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> is disabled for the <EM>curses</EM> window receiving input, a
program must disambiguate escape sequences itself.
</PRE><H3><a name="h3-HOME"><EM>HOME</EM></a></H3><PRE>
- <EM>ncurses</EM> may read and write auxiliary terminal descriptions in <EM>.termcap</EM>
+ <EM>ncurses</EM> may read and write auxiliary terminal descriptions in <EM>.termcap</EM>
and <EM>.terminfo</EM> files in the user's home directory.
</PRE><H3><a name="h3-LINES"><EM>LINES</EM></a></H3><PRE>
- This counterpart to <EM>COLUMNS</EM> specifies the height of the screen in
- characters. The corresponding <EM>terminfo</EM> capability and code is <STRONG>lines</STRONG>.
+ This counterpart to <EM>COLUMNS</EM> specifies the height of the screen in
+ characters. The corresponding <EM>terminfo</EM> capability and code is <STRONG>lines</STRONG>.
See the description of the <EM>COLUMNS</EM> variable above.
</PRE><H3><a name="h3-MOUSE_BUTTONS_123"><EM>MOUSE_BUTTONS_123</EM></a></H3><PRE>
- (OS/2 EMX port only) OS/2 numbers a three-button mouse inconsistently
- with other platforms, such that 1 is the left button, 2 the right, and
- 3 the middle. This variable customizes the mouse button numbering.
- Its value must be three digits 1-3 in any order. By default, <EM>ncurses</EM>
+ (OS/2 EMX port only) OS/2 numbers a three-button mouse inconsistently
+ with other platforms, such that 1 is the left button, 2 the right, and
+ 3 the middle. This variable customizes the mouse button numbering.
+ Its value must be three digits 1-3 in any order. By default, <EM>ncurses</EM>
assumes a numbering of "132".
</PRE><H3><a name="h3-NCURSES_ASSUMED_COLORS"><EM>NCURSES_ASSUMED_COLORS</EM></a></H3><PRE>
- If set, this variable overrides the <EM>ncurses</EM> library's compiled-in
- assumption that the terminal's default colors are white on black; see
- <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>. Set the foreground and background color values
- with this environment variable by assigning it two integer values
+ If set, this variable overrides the <EM>ncurses</EM> library's compiled-in
+ assumption that the terminal's default colors are white on black; see
+ <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>. Set the foreground and background color values
+ with this environment variable by assigning it two integer values
separated by a comma, indicating foregound and background color
numbers, respectively.
- For example, to tell <EM>ncurses</EM> not to assume anything about the colors,
- use a value of "-1,-1". To make the default color scheme green on
- black, use "2,0". <EM>ncurses</EM> accepts integral values from -1 up to the
+ For example, to tell <EM>ncurses</EM> not to assume anything about the colors,
+ use a value of "-1,-1". To make the default color scheme green on
+ black, use "2,0". <EM>ncurses</EM> accepts integral values from -1 up to the
value of the <EM>terminfo</EM> <STRONG>max_colors</STRONG> (<STRONG>colors</STRONG>) capability.
</PRE><H3><a name="h3-NCURSES_CONSOLE2"><EM>NCURSES_CONSOLE2</EM></a></H3><PRE>
- (MinGW port only) The <EM>Console2</EM> program defectively handles the
- Microsoft Console API call <EM>CreateConsoleScreenBuffer</EM>. Applications
- that use it will hang. However, it is possible to simulate the action
- of this call by mapping coordinates, explicitly saving and restoring
- the original screen contents. Setting the environment variable <EM>NCGDB</EM>
+ (MinGW port only) The <EM>Console2</EM> program defectively handles the
+ Microsoft Console API call <EM>CreateConsoleScreenBuffer</EM>. Applications
+ that use it will hang. However, it is possible to simulate the action
+ of this call by mapping coordinates, explicitly saving and restoring
+ the original screen contents. Setting the environment variable <EM>NCGDB</EM>
has the same effect.
</PRE><H3><a name="h3-NCURSES_GPM_TERMS"><EM>NCURSES_GPM_TERMS</EM></a></H3><PRE>
- (Linux only) When <EM>ncurses</EM> is configured to use the GPM interface, this
- variable may list one or more terminal names against which the <EM>TERM</EM>
- variable (see below) is matched. An empty value disables the GPM
- interface, using <EM>ncurses</EM>'s built-in support for <STRONG>xterm(1)</STRONG> mouse
+ (Linux only) When <EM>ncurses</EM> is configured to use the GPM interface, this
+ variable may list one or more terminal type names against which the
+ <EM>TERM</EM> variable (see below) is matched. An empty value disables the GPM
+ interface, using <EM>ncurses</EM>'s built-in support for <STRONG>xterm(1)</STRONG> mouse
protocols instead. If the variable is absent, <EM>ncurses</EM> attempts 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>
- <EM>ncurses</EM> may use tab characters in cursor movement optimization. In
- some cases, your terminal driver may not handle them properly. Set
+ <EM>ncurses</EM> may use tab characters in cursor movement optimization. In
+ some cases, your terminal driver may not handle them 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>
- Many terminals store video attributes as a property of a character
- cell, as <EM>curses</EM> does. Historically, some recorded changes in video
- attributes as data that logically <EM>occupies</EM> character cells on the
- display, switching attributes on or off, similarly to tags in a markup
- language; these are termed "magic cookies", and must be subsequently
- overprinted. If the <EM>terminfo</EM> entry for your terminal type does not
+ Many terminals store video attributes as a property of a character
+ cell, as <EM>curses</EM> does. Historically, some recorded changes in video
+ attributes as data that logically <EM>occupies</EM> character cells on the
+ display, switching attributes on or off, similarly to tags in a markup
+ language; these are termed "magic cookies", and must be subsequently
+ overprinted. If the <EM>terminfo</EM> entry for your terminal type does not
adequately describe its handling of magic cookies, set this variable to
any value to instruct <EM>ncurses</EM> to disable attributes entirely.
</PRE><H3><a name="h3-NCURSES_NO_PADDING"><EM>NCURSES_NO_PADDING</EM></a></H3><PRE>
Most terminal type descriptions in the <EM>terminfo</EM> database detail
- hardware devices. Many people use <EM>curses</EM>-based applications in
- terminal emulator programs that run in a windowing environment. These
- programs can duplicate all of the important features of a hardware
- terminal, but often lack their limitations. Chief among these absent
+ hardware devices. Many people use <EM>curses</EM>-based applications in
+ terminal emulator programs that run in a windowing environment. These
+ programs can duplicate all of the important features of a hardware
+ terminal, but often lack their limitations. Chief among these absent
drawbacks is the problem of data flow management; that is, limiting the
- speed of communication to what the hardware could handle. Unless a
- hardware terminal is interfaced into a terminal concentrator (which
- does flow control), an application must manage flow control itself to
- prevent overruns and data loss.
-
- A solution that comes at no hardware cost is for an application to
- pause after directing a terminal to execute an operation that it
- performs slowly, such as clearing the display. Many terminal type
- descriptions, including that for the VT100, embed delay specifications
- in capabilities. You may wish to use these terminal descriptions
- without paying the performance penalty. Set <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>PADDING</EM> to any
- value to disable all but mandatory padding. Mandatory padding is used
+ speed of communication to what the hardware could handle. Unless a
+ hardware terminal is interfaced into a terminal concentrator (which
+ does flow control), an application must manage flow itself to prevent
+ overruns and data loss.
+
+ A solution that comes at no hardware cost is for an application to
+ pause after directing a terminal to execute an operation that it
+ performs slowly, such as clearing the display. Many terminal type
+ descriptions, including that for the VT100, embed delay specifications
+ in capabilities. You may wish to use these terminal descriptions
+ without paying the performance penalty. Set <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>PADDING</EM> to any
+ value to disable all but mandatory padding. Mandatory padding is used
by such terminal capabilities as <STRONG>flash_screen</STRONG> (<STRONG>flash</STRONG>).
</PRE><H3><a name="h3-NCURSES_NO_SETBUF"><EM>NCURSES_NO_SETBUF</EM></a></H3><PRE>
- (Obsolete) Prior to internal changes developed in <EM>ncurses</EM> 5.9 (patches
- 20120825 through 20130126), the library used <STRONG>setbuf(3)</STRONG> to enable fully
- buffered output when initializing the terminal. This was done, as in
- SVr4 <EM>curses</EM>, to increase performance. For testing purposes, both of
- <EM>ncurses</EM> and of certain applications, this feature was made optional.
- Setting this variable disabled output buffering, leaving the output
+ (Obsolete) Prior to internal changes developed in <EM>ncurses</EM> 5.9 (patches
+ 20120825 through 20130126), the library used <STRONG>setbuf(3)</STRONG> to enable fully
+ buffered output when initializing the terminal. This was done, as in
+ SVr4 <EM>curses</EM>, to increase performance. For testing purposes, both of
+ <EM>ncurses</EM> and of certain applications, this feature was made optional.
+ Setting this variable disabled output buffering, leaving the output
stream in the original (usually line-buffered) mode.
- Nowadays, <EM>ncurses</EM> performs its own buffering and does not require this
- workaround; it does not modify the buffering of the standard output
- stream. This approach makes signal handling, as for interrupts, more
- robust. A drawback is that certain unconventional programs mixed
- <STRONG>stdio(3)</STRONG> calls with <EM>ncurses</EM> calls and (usually) got the behavior they
- expected. This is no longer the case; <EM>ncurses</EM> does not write to the
+ Nowadays, <EM>ncurses</EM> performs its own buffering and does not require this
+ workaround; it does not modify the buffering of the standard output
+ stream. This approach makes signal handling, as for interrupts, more
+ robust. A drawback is that certain unconventional programs mixed
+ <STRONG>stdio(3)</STRONG> calls with <EM>ncurses</EM> calls and (usually) got the behavior they
+ expected. This is no longer the case; <EM>ncurses</EM> does not write to the
standard output file descriptor through a <EM>stdio</EM>-buffered stream.
- As a special case, low-level API calls such as <STRONG><A HREF="curs_terminfo.3x.html">putp(3x)</A></STRONG> still use the
- standard output stream. High-level <EM>curses</EM> calls such as <STRONG><A HREF="curs_printw.3x.html">printw(3x)</A></STRONG> do
+ As a special case, low-level API calls such as <STRONG><A HREF="curs_terminfo.3x.html">putp(3x)</A></STRONG> still use the
+ standard output stream. High-level <EM>curses</EM> calls such as <STRONG><A HREF="curs_printw.3x.html">printw(3x)</A></STRONG> do
not.
</PRE><H3><a name="h3-NCURSES_NO_UTF8_ACS"><EM>NCURSES_NO_UTF8_ACS</EM></a></H3><PRE>
- At initialization, <EM>ncurses</EM> inspects the <EM>TERM</EM> environment variable for
- special cases where VT100 forms-drawing characters (and the
- corresponding alternate character set <EM>terminfo</EM> capabilities) are known
+ At initialization, <EM>ncurses</EM> inspects the <EM>TERM</EM> environment variable for
+ special cases where VT100 forms-drawing characters (and the
+ corresponding alternate character set <EM>terminfo</EM> capabilities) are known
to be unsupported by terminal types that otherwise claim VT100
compatibility. Specifically, when running in a UTF-8 locale, the Linux
- virtual console device and the GNU <STRONG>screen(1)</STRONG> program ignore them. Set
+ virtual console device and the GNU <STRONG>screen(1)</STRONG> program ignore them. Set
this variable to a nonzero value to instruct <EM>ncurses</EM> that the
terminal's ACS support is broken; the library then outputs Unicode code
points that correspond to the forms-drawing characters. Set it to zero
(or a non-integer) to disable the special check for terminal type names
- matching "linux" or "screen", directing <EM>ncurses</EM> to assume that the ACS
+ matching "linux" or "screen", directing <EM>ncurses</EM> to assume that the ACS
feature works if the terminal type description advertises it.
- As an alternative to use of this variable, <EM>ncurses</EM> checks for an
+ As an alternative to use of this variable, <EM>ncurses</EM> checks for an
extended <EM>terminfo</EM> numeric capability <STRONG>U8</STRONG> that can be compiled using "<STRONG>tic</STRONG>
<STRONG>-x</STRONG>". Examples follow.
xterm-utf8|xterm relying on UTF-8 line-graphics,
U8#1, use=xterm,
- The two-character name "U8" was chosen to permit its use via <EM>ncurses</EM>'s
+ The two-character name "U8" was chosen to permit its use via <EM>ncurses</EM>'s
<EM>termcap</EM> interface.
</PRE><H3><a name="h3-NCURSES_TRACE"><EM>NCURSES_TRACE</EM></a></H3><PRE>
- At initialization, <EM>ncurses</EM> (in its debugging configuration) checks for
- this variable's presence. If defined with an integral value, the
+ At initialization, <EM>ncurses</EM> (in its debugging configuration) checks for
+ this variable's presence. If defined with an integral value, the
library calls <STRONG><A HREF="curs_trace.3x.html">curses_trace(3x)</A></STRONG> with that value as the argument.
</PRE><H3><a name="h3-TERM"><EM>TERM</EM></a></H3><PRE>
- The <EM>TERM</EM> variable denotes the terminal type. Each is distinct, though
- many are similar. It is commonly set by terminal emulators to help
- applications find a workable terminal description. Some choose a
- popular approximation such as "ansi", "vt100", or "xterm" rather than
- an exact fit to their capabilities. Not infrequently, an application
- will have problems with that approach; for example, a key stroke may
- not operate correctly, or produce no effect but seeming garbage
+ The <EM>TERM</EM> variable denotes the terminal type. Each is distinct, though
+ many are similar. It is commonly set by terminal emulators to help
+ applications find a workable terminal description. Some choose a
+ popular approximation such as "ansi", "vt100", or "xterm" rather than
+ an exact fit to their capabilities. Not infrequently, an application
+ will have problems with that approach; for example, a key stroke may
+ not operate correctly, or produce no effect but seeming garbage
characters on the screen.
- Setting <EM>TERM</EM> has no effect on hardware operation; it affects the way
- applications communicate with the terminal. Likewise, as a general
- rule (<STRONG>xterm(1)</STRONG> being a rare exception), terminal emulators that allow
+ Setting <EM>TERM</EM> has no effect on hardware operation; it affects the way
+ applications communicate with the terminal. Likewise, as a general
+ rule (<STRONG>xterm(1)</STRONG> being a rare exception), terminal emulators that allow
you to specify <EM>TERM</EM> as a parameter or configuration value do not change
their behavior to match that setting.
</PRE><H3><a name="h3-TERMCAP"><EM>TERMCAP</EM></a></H3><PRE>
If <EM>ncurses</EM> is configured with <EM>termcap</EM> support, it checks for a terminal
- type description in <EM>termcap</EM> format if one in <EM>terminfo</EM> format is not
- available. Setting this variable directs <EM>ncurses</EM> to ignore the usual
- <EM>termcap</EM> database location, <EM>/etc/termcap</EM>; see <EM>TERMPATH</EM> below. <EM>TERMCAP</EM>
- should contain either a terminal description (with newlines stripped
- out), or a file name indicating where the information required by the
+ type description in <EM>termcap</EM> format if one in <EM>terminfo</EM> format is not
+ available. Setting this variable directs <EM>ncurses</EM> to ignore the usual
+ <EM>termcap</EM> database location, <EM>/etc/termcap</EM>; see <EM>TERMPATH</EM> below. <EM>TERMCAP</EM>
+ should contain either a terminal description (with newlines stripped
+ out), or a file name indicating where the information required by the
<EM>TERM</EM> environment variable is stored.
</PRE><H3><a name="h3-TERMINFO"><EM>TERMINFO</EM></a></H3><PRE>
- <EM>ncurses</EM> can be configured to read terminal type description databases
- in various locations using different formats. This variable overrides
+ <EM>ncurses</EM> can be configured to read terminal type description databases
+ in various locations using different formats. This variable overrides
the default location.
- <STRONG>o</STRONG> Descriptions in <EM>terminfo</EM> format are normally stored in a directory
- tree using subdirectories named by the common first letters of the
+ <STRONG>o</STRONG> Descriptions in <EM>terminfo</EM> format are normally stored in a directory
+ tree using subdirectories named by the common first letters of the
terminal types named therein. This is the scheme used in System V.
<STRONG>o</STRONG> If <EM>ncurses</EM> is configured to use hashed databases, then <EM>TERMINFO</EM> may
- name its location, such as <EM>/usr/share/terminfo.db</EM>, rather than
+ name its location, such as <EM>/usr/share/terminfo.db</EM>, rather than
<EM>/usr/share/terminfo/</EM>.
- The hashed database uses less disk space and is a little faster than
+ The hashed database uses less disk space and is a little faster than
the directory tree. However, some applications assume the existence of
the directory tree, and read it directly rather than using the <EM>terminfo</EM>
API.
- <STRONG>o</STRONG> If <EM>ncurses</EM> is configured with <EM>termcap</EM> support, this variable may
+ <STRONG>o</STRONG> If <EM>ncurses</EM> is configured with <EM>termcap</EM> support, this variable may
contain the location of a <EM>termcap</EM> file.
<STRONG>o</STRONG> If the value of <EM>TERMINFO</EM> begins with "hex:" or "b64:", <EM>ncurses</EM> uses
TERMINFO=$(infocmp -0 -Q2 -q)
export TERMINFO
- The compiled description is used only if it corresponds to the
+ The compiled description is used only if it corresponds to the
terminal type identified by <EM>TERM</EM>.
- Setting <EM>TERMINFO</EM> is the simplest, but not the only, way to direct
+ Setting <EM>TERMINFO</EM> is the simplest, but not the only, way to direct
<EM>ncurses</EM> to a terminal database. The search path is as follows.
<STRONG>o</STRONG> the last terminal database to which the running <EM>ncurses</EM> application
<STRONG>o</STRONG> location(s) configured and compiled into <EM>ncurses</EM>
- <STRONG>o</STRONG> <EM>/usr/share/terminfo</EM>
+ <STRONG>o</STRONG> <EM>/usr/share/terminfo</EM>
</PRE><H3><a name="h3-TERMINFO_DIRS"><EM>TERMINFO_DIRS</EM></a></H3><PRE>
- This variable specifies a list of locations, akin to <EM>PATH</EM>, in which
- <EM>ncurses</EM> searches for the terminal type descriptions described by
- <EM>TERMINFO</EM> above. The list items are separated by colons on Unix and
- semicolons on OS/2 EMX. System V <EM>terminfo</EM> lacks a corresponding
+ This variable specifies a list of locations, akin to <EM>PATH</EM>, in which
+ <EM>ncurses</EM> searches for the terminal type descriptions described by
+ <EM>TERMINFO</EM> above. The list items are separated by colons on Unix and
+ semicolons on OS/2 EMX. System V <EM>terminfo</EM> lacks a corresponding
feature; <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> is an <EM>ncurses</EM> extension.
</PRE><H3><a name="h3-TERMPATH"><EM>TERMPATH</EM></a></H3><PRE>
If <EM>TERMCAP</EM> does not hold a terminal type description or file name, then
- <EM>ncurses</EM> checks the contents of <EM>TERMPATH</EM>, a list of locations, akin to
+ <EM>ncurses</EM> checks the contents of <EM>TERMPATH</EM>, a list of locations, akin to
<EM>PATH</EM>, in which it searches for <EM>termcap</EM> terminal type descriptions. The
list items are separated by colons on Unix and semicolons on OS/2 EMX.
</PRE><H2><a name="h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></H2><PRE>
- Many different <EM>ncurses</EM> configurations are possible, determined by the
- options given to the <EM>configure</EM> script when building the library. Run
- the script with the <STRONG>--help</STRONG> option to peruse them all. A few are of
+ Many different <EM>ncurses</EM> configurations are possible, determined by the
+ options given to the <EM>configure</EM> script when building the library. Run
+ the script with the <STRONG>--help</STRONG> option to peruse them all. A few are of
particular significance to the application developer employing <EM>ncurses</EM>.
<STRONG>--disable-overwrite</STRONG>
- The standard include for <EM>ncurses</EM> is as noted in <STRONG>SYNOPSIS</STRONG>:
+ The standard C preprocessor inclusion for the <EM>curses</EM> library is as
+ follows.
<STRONG>#include</STRONG> <STRONG><curses.h></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.,
+ This option is used to avoid file name conflicts between <EM>ncurses</EM>
+ and an existing <EM>curses</EM> installation on the system. If <EM>ncurses</EM> is
+ installed disabling overwrite, it puts its header files in a
+ subdirectory. Here is an example.
<STRONG>#include</STRONG> <STRONG><ncurses/curses.h></STRONG>
- It also omits a symbolic link which would allow you to use
- <STRONG>-lcurses</STRONG> to build executables.
+ Installation also omits a symbolic link that would cause the
+ compiler's <STRONG>-lcurses</STRONG> option to link object files with <EM>ncurses</EM>
+ instead of the system <EM>curses</EM> library.
+
+ The directory used by this configuration of <EM>ncurses</EM> is shown in
+ section "SYNOPSIS" above.
<STRONG>--enable-widec</STRONG>
The configure script renames the library and (if the
<STRONG>o</STRONG> to reuse functions (for example, those that move the cursor before
another operation), and
- <STRONG>o</STRONG> a few special cases.
+ <STRONG>o</STRONG> in a few special cases.
If the standard output file descriptor of an <EM>ncurses</EM> program is
redirected to something that is not a terminal device, the library
An <EM>ncurses</EM> application can eschew knowledge of <EM>WINDOW</EM> structure
internals, instead using accessor functions such as <STRONG><A HREF="curs_opaque.3x.html">is_scrollok(3x)</A></STRONG>.
- <EM>ncurses</EM> enables an application to direct application output to a
-
printer attached to the terminal device; see <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>.
+ <EM>ncurses</EM> enables an application to direct its output to a printer
+ attached to the terminal device; see <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>.
<EM>ncurses</EM> offers <STRONG><A HREF="curs_slk.3x.html">slk_attr(3x)</A></STRONG> as a counterpart of <STRONG><A HREF="curs_attr.3x.html">attr_get(3x)</A></STRONG> for soft-
label key lines, and <STRONG><A HREF="curs_slk.3x.html">extended_slk_color(3x)</A></STRONG> as a form of <STRONG><A HREF="curs_slk.3x.html">slk_color(3x)</A></STRONG>
<STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>'s behavior; see <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG>. <EM>ncurses</EM> is compiled
to support them; section "ALTERNATE CONFIGURATIONS" describes how.
- <STRONG>o</STRONG> Rudimentary support for multi-threaded applications may be
- available; see <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>.
+ <EM>ncurses</EM> permits modification of <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>'s behavior; see
+ <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG>.
+
+ Rudimentary support for multi-threaded applications may be available;
+ see <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>.
- <STRONG>o</STRONG> Functions that ease the management of multiple screens can be
-
exposed; see <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>.
+ Functions that ease the management of multiple screens can be exposed;
+ see <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>.
- <STRONG>o</STRONG> To aid applications to debug their memory usage, <EM>ncurses</EM> optionally
- offers functions to more aggressively free memory it dynamically
-
allocates itself; see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>.
+ To aid applications to debug their memory usage, <EM>ncurses</EM> optionally
+ offers functions to more aggressively free memory it dynamically
+ allocates itself; see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>.
- <STRONG>o</STRONG> The library facilitates auditing and troubleshooting of its
-
behavior; see <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>.
+ The library facilitates auditing and troubleshooting of its behavior;
+ see <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>.
- <STRONG>o</STRONG> The compiler option <STRONG>-DUSE_GETCAP</STRONG> causes the library to fall back to
- reading <EM>/etc/termcap</EM> if the terminal setup code cannot find a <EM>term-</EM>
- <EM>info</EM> entry corresponding to <EM>TERM</EM>. Use of this feature is not
- recommended, as it essentially includes an entire <EM>termcap</EM> compiler
- in the <EM>ncurses</EM> startup code, at a cost in memory usage and
- application launch latency.
+ Compiling <EM>ncurses</EM> with the option <STRONG>-DUSE_GETCAP</STRONG> causes it to fall back
+ to reading <EM>/etc/termcap</EM> if the terminal setup code cannot find a <EM>term-</EM>
+ <EM>info</EM> entry corresponding to <EM>TERM</EM>. Use of this feature is not
+ recommended, as it essentially includes an entire <EM>termcap</EM> compiler in
+ the <EM>ncurses</EM> startup code, at a cost in memory usage and application
+ launch latency.
- <EM>PDCurses</EM> and NetBSD <EM>curses</EM> incorporate some <EM>ncurses</EM> extensions.
+ <EM>PDCurses</EM> and NetBSD <EM>curses</EM> incorporate some <EM>ncurses</EM> extensions.
Individual man pages indicate where this is the case.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
X/Open Curses defines two levels of conformance, "base" and "enhanced".
The latter includes several additional features, such as wide-character
- and color support. <EM>ncurses</EM> intends base-level conformance with X/Open
- Curses, and supports all features of its enhanced level except the
+ and color support. <EM>ncurses</EM> intends base-level conformance with X/Open
+ Curses, and supports all features of its enhanced level except the
<STRONG>untic</STRONG> utility.
- Differences between X/Open Curses and <EM>ncurses</EM> are documented in the
+ Differences between X/Open Curses and <EM>ncurses</EM> are documented in the
"PORTABILITY" sections of applicable man pages.
</PRE><H3><a name="h3-Error-Checking">Error Checking</a></H3><PRE>
- In many cases, X/Open Curses is vague about error conditions, omitting
+ In many cases, X/Open Curses is vague about error conditions, omitting
some of the SVr4 documentation.
- Unlike other implementations, <EM>ncurses</EM> checks pointer parameters, such
- as those to <EM>WINDOW</EM> structures, to ensure that they are not null. This
- is done primarily to guard against programmer error. The standard
+ Unlike other implementations, <EM>ncurses</EM> checks pointer parameters, such
+ as those to <EM>WINDOW</EM> structures, to ensure that they are not null. This
+ is done primarily to guard against programmer error. The standard
interface does not provide a way for the library to tell an application
- which of several possible errors occurred. Relying on this (or some
- other) extension adversely affects the portability of <EM>curses</EM>
- applications.
+ which of several possible errors occurred. An application that relies
+ on <EM>ncurses</EM> to check its function parameters for validity limits its
+ portability and robustness.
</PRE><H3><a name="h3-Padding-Differences">Padding Differences</a></H3><PRE>
- In historical <EM>curses</EM> implementations, delays embedded in the <EM>terminfo</EM>
- capabilities <STRONG>carriage_return</STRONG> (<STRONG>cr</STRONG>), <STRONG>scroll_forward</STRONG> (<STRONG>ind</STRONG>), <STRONG>cursor_left</STRONG>
+ In historical <EM>curses</EM> implementations, delays embedded in the <EM>terminfo</EM>
+ capabilities <STRONG>carriage_return</STRONG> (<STRONG>cr</STRONG>), <STRONG>scroll_forward</STRONG> (<STRONG>ind</STRONG>), <STRONG>cursor_left</STRONG>
(<STRONG>cub1</STRONG>), <STRONG>form_feed</STRONG> (<STRONG>ff</STRONG>), and <STRONG>tab</STRONG> (<STRONG>ht</STRONG>) activated corresponding delay bits
- in the Unix terminal driver. <EM>ncurses</EM> performs all padding by sending
- NUL bytes to the device. This method is slightly more expensive, but
- narrows the interface to the Unix kernel significantly and
+ in the Unix terminal driver. <EM>ncurses</EM> performs all padding by sending
+ NUL bytes to the device. This method is slightly more expensive, but
+ narrows the interface to the Unix kernel significantly and
correspondingly increases the package's portability.
</PRE><H3><a name="h3-Header-Files">Header Files</a></H3><PRE>
- The header file <EM>curses.h</EM> itself includes the header files <EM>stdio.h</EM> and
+ The header file <EM>curses.h</EM> itself includes the header files <EM>stdio.h</EM> and
<EM>unctrl.h</EM>.
X/Open Curses has more to say,
- The inclusion of <EM>curses.h</EM> may make visible all symbols from the
+ The inclusion of <EM>curses.h</EM> may make visible all symbols from the
headers <EM>stdio.h</EM>, <EM>term.h</EM>, <EM>termios.h</EM>, and <EM>wchar.h</EM>.
but does not finish the story. A more complete account follows.
- <STRONG>o</STRONG> Starting with 4BSD <EM>curses</EM> (1980) all implementations have provided
+ <STRONG>o</STRONG> Starting with 4BSD <EM>curses</EM> (1980) all implementations have provided
a <EM>curses.h</EM> file.
- BSD <EM>curses</EM> code included <EM>curses.h</EM> and <EM>unctrl.h</EM> from an internal
+ BSD <EM>curses</EM> code included <EM>curses.h</EM> and <EM>unctrl.h</EM> from an internal
header file <EM>curses.ext</EM>, where "ext" abbreviated "externs".
- The implementations of <EM>printw</EM> and <EM>scanw</EM> used undocumented internal
- functions of the standard I/O library (<STRONG>_</STRONG><EM>doprnt</EM> and <STRONG>_</STRONG><EM>doscan</EM>), but
+ The implementations of <EM>printw</EM> and <EM>scanw</EM> used undocumented internal
+ functions of the standard I/O library (<STRONG>_</STRONG><EM>doprnt</EM> and <STRONG>_</STRONG><EM>doscan</EM>), but
nothing in <EM>curses.h</EM> itself relied upon <EM>stdio.h</EM>.
- <STRONG>o</STRONG> SVr2 <EM>curses</EM> added <EM>newterm</EM>, which relies upon <EM>stdio.h</EM> because its
+ <STRONG>o</STRONG> SVr2 <EM>curses</EM> added <EM>newterm</EM>, which relies upon <EM>stdio.h</EM> because its
function prototype employs the <EM>FILE</EM> type.
SVr4 <EM>curses</EM> added <EM>putwin</EM> and <EM>getwin</EM>, which also use <EM>stdio.h</EM>.
X/Open Curses specifies all three of these functions.
- SVr4 <EM>curses</EM> and X/Open Curses do not require the developer to
- include <EM>stdio.h</EM> before <EM>curses.h</EM>. Both document use of <EM>curses</EM> as
+ SVr4 <EM>curses</EM> and X/Open Curses do not require the developer to
+ include <EM>stdio.h</EM> before <EM>curses.h</EM>. Both document use of <EM>curses</EM> as
requiring only <EM>curses.h</EM>.
As a result, standard <EM>curses.h</EM> always includes <EM>stdio.h</EM>.
- <STRONG>o</STRONG> X/Open Curses and SVr4 <EM>curses</EM> are inconsistent with respect to
+ <STRONG>o</STRONG> X/Open Curses and SVr4 <EM>curses</EM> are inconsistent with respect to
<EM>unctrl.h</EM>.
- As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <EM>ncurses</EM> includes <EM>unctrl.h</EM> from <EM>curses.h</EM>
+ As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <EM>ncurses</EM> includes <EM>unctrl.h</EM> from <EM>curses.h</EM>
(as SVr4 does).
- <STRONG>o</STRONG> X/Open Curses's comments about <EM>term.h</EM> and <EM>termios.h</EM> may refer to
+ <STRONG>o</STRONG> X/Open Curses's comments about <EM>term.h</EM> and <EM>termios.h</EM> may refer to
HP-UX and AIX.
- HP-UX <EM>curses</EM> includes <EM>term.h</EM> from <EM>curses.h</EM> to declare <EM>setupterm</EM> in
+ HP-UX <EM>curses</EM> includes <EM>term.h</EM> from <EM>curses.h</EM> to declare <EM>setupterm</EM> in
<EM>curses.h</EM>, but <EM>ncurses</EM> and Solaris <EM>curses</EM> do not.
- AIX <EM>curses</EM> includes <EM>term.h</EM> and termios.h<EM>.</EM> Again, <EM>ncurses</EM> and
+ AIX <EM>curses</EM> includes <EM>term.h</EM> and <EM>termios.h</EM>. Again, <EM>ncurses</EM> and
Solaris <EM>curses</EM> do not.
- <STRONG>o</STRONG> X/Open Curses says that <EM>curses.h</EM> <STRONG>may</STRONG> include <EM>term.h</EM>, but does not
+ <STRONG>o</STRONG> X/Open Curses says that <EM>curses.h</EM> <STRONG>may</STRONG> include <EM>term.h</EM>, but does not
require it to do so.
- Some programs use functions declared in both <EM>curses.h</EM> and <EM>term.h</EM>,
- and must include both header files in the same module. Very old
- versions of AIX <EM>curses</EM> required inclusion of <EM>curses.h</EM> before
+ Some programs use functions declared in both <EM>curses.h</EM> and <EM>term.h</EM>,
+ and must include both header files in the same module. Very old
+ versions of AIX <EM>curses</EM> required inclusion of <EM>curses.h</EM> before
<EM>term.h</EM>.
- The header files supplied by <EM>ncurses</EM> include the standard library
- headers required for its declarations, so <EM>ncurses</EM>'s own header
- files can be included in any order. But for portability, you
+ The header files supplied by <EM>ncurses</EM> include the standard library
+ headers required for its declarations, so <EM>ncurses</EM>'s own header
+ files can be included in any order. But for portability, you
should include <EM>curses.h</EM> before <EM>term.h</EM>.
- <STRONG>o</STRONG> X/Open Curses says "may make visible" because including a header
- file does not necessarily make visible all of the symbols in it
+ <STRONG>o</STRONG> X/Open Curses says "may make visible" because including a header
+ file does not necessarily make visible all of the symbols in it
(consider <STRONG>#ifdef</STRONG> and similar).
- For instance, <EM>ncurses</EM>'s <EM>curses.h</EM> <STRONG>may</STRONG> include <EM>wchar.h</EM> if the proper
- symbol is defined, and if <EM>ncurses</EM> is configured for wide-character
- support. If <EM>wchar.h</EM> is included, its symbols <STRONG>may</STRONG> be made visible
+ For instance, <EM>ncurses</EM>'s <EM>curses.h</EM> <STRONG>may</STRONG> include <EM>wchar.h</EM> if the proper
+ symbol is defined, and if <EM>ncurses</EM> is configured for wide-character
+ support. If <EM>wchar.h</EM> is included, its symbols <STRONG>may</STRONG> be made visible
depending on the value of the <STRONG>_XOPEN_SOURCE</STRONG> feature test macro.
<STRONG>o</STRONG> X/Open Curses mandates an application's inclusion of one standard C
- library header in a special case: <EM>stdarg.h</EM> before <EM>curses.h</EM> to
- prototype the functions <EM>vw</EM><STRONG>_</STRONG><EM>printw</EM> and <EM>vw</EM><STRONG>_</STRONG><EM>scanw</EM> (as well as the
- obsolete <EM>vwprintw</EM> and <EM>vwscanw</EM>). Each of these takes a variadic
+ library header in a special case: <EM>stdarg.h</EM> before <EM>curses.h</EM> to
+ prototype the functions <EM>vw</EM><STRONG>_</STRONG><EM>printw</EM> and <EM>vw</EM><STRONG>_</STRONG><EM>scanw</EM> (as well as the
+ obsolete <EM>vwprintw</EM> and <EM>vwscanw</EM>). Each of these takes a variadic
argument list, a <EM>va</EM><STRONG>_</STRONG><EM>list</EM> parameter, like that of <STRONG>printf(3)</STRONG>.
- SVr3 <EM>curses</EM> introduced the two obsolete functions, and X/Open
- Curses the others. In between, SVr4 <EM>curses</EM> provided for the
- possibility that an application might include either <EM>varargs.h</EM> or
- <EM>stdarg.h</EM>. These represented contrasting approaches to handling
- variadic argument lists. The older interface, <EM>varargs.h</EM>, used a
- pointer to <EM>char</EM> for variadic functions' <EM>va</EM><STRONG>_</STRONG><EM>list</EM> parameter. Later,
- the list acquired its own standard data type, <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, defined in
- <EM>stdarg.h</EM>, empowering the compiler to check the types of a function
- call's actual parameters against the formal ones declared in its
+ SVr3 <EM>curses</EM> introduced the two obsolete functions, and X/Open
+ Curses the others. In between, SVr4 <EM>curses</EM> provided for the
+ possibility that an application might include either <EM>varargs.h</EM> or
+ <EM>stdarg.h</EM>. These represented contrasting approaches to handling
+ variadic argument lists. The older interface, <EM>varargs.h</EM>, used a
+ pointer to <EM>char</EM> for variadic functions' <EM>va</EM><STRONG>_</STRONG><EM>list</EM> parameter. Later,
+ the list acquired its own standard data type, <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, defined in
+ <EM>stdarg.h</EM>, empowering the compiler to check the types of a function
+ call's actual parameters against the formal ones declared in its
prototype.
- No conforming implementations of X/Open Curses require an
+ No conforming implementations of X/Open Curses require an
application to include <EM>stdarg.h</EM> before <EM>curses.h</EM> because they either
- have allowed for a special type, or, like <EM>ncurses</EM>, they include
+ have allowed for a special type, or, like <EM>ncurses</EM>, they include
<EM>stdarg.h</EM> themselves to provide a portable interface.
-ncurses 6.5 2024-0
4-27 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: MKncu_config.in,v 1.24 2024/04/20 21:13:38 tom Exp @
+ * @Id: MKncu_config.in,v 1.25 2024/05/11 20:39: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>ncursesw6-config 1 2024-04-20 ncurses 6.5 User commands</TITLE>
+<TITLE>ncursesw6\-config 1 2024-05-11 ncurses 6.5 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">ncursesw6-config 1 2024-04-20 ncurses 6.5 User commands</H1>
+<H1 class="no-header">ncursesw6\-config 1 2024-05-11 ncurses 6.5 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.5 2024-0
4-20 <STRONG><A HREF="ncursesw6-config.1.html">ncursesw6-config(1)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="ncursesw6-config.1.html">ncursesw6-config(1)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: term.5,v 1.77 2024/04/20 21:24:19 tom Exp @
+ * @Id: term.5,v 1.78 2024/05/11 20:39: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>term 5 2024-04-20 ncurses 6.5 File formats</TITLE>
+<TITLE>term 5 2024-05-11 ncurses 6.5 File formats</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">term 5 2024-04-20 ncurses 6.5 File formats</H1>
+<H1 class="no-header">term 5 2024-05-11 ncurses 6.5 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>
term - compiled <EM>terminfo</EM> terminal description
-</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
- <STRONG>term</STRONG>
-
-
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+ <STRONG><A HREF="tic.1m.html">tic(1)</A></STRONG> compiles a <EM>terminfo</EM> terminal type description, and <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>
+ reads it. A compiled description may be stored in a file or in a
+ database of, potentially, many such descriptions. Further, a compiled
+ description may be in one of two formats: one similar to that used by
+ System V, and a newer, extensible format employed exclusively by
+ <EM>ncurses</EM>.
+
</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 <EM>ncurses</EM> libraries):
+ Compiled <EM>terminfo</EM> <EM>descriptions</EM> <EM>are</EM> <EM>placed</EM> under the directory
+ <EM>/usr/share/terminfo</EM>. One of two configurations is selected when
+ building 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
- system directory: <STRONG>/usr/share/terminfo/c/name</STRONG> where <EM>name</EM> is the
+ system directory: <EM>/usr/share/terminfo/</EM>c<EM>/</EM>name where <EM>name</EM> is the
name of the terminal, and <EM>c</EM> is the first character of <EM>name</EM>. Thus,
- <EM>act4</EM> can be found in the file <STRONG>/usr/share/terminfo/a/act4</STRONG>.
- Synonyms for the same terminal are implemented by multiple links
- to the same compiled file.
+ the compiled description of terminal type "act4" is found in the
+ file <EM>/usr/share/terminfo/a/act4</EM>. Synonyms for the same terminal
+ are implemented by multiple links to the same compiled file.
<STRONG>hashed</STRONG> <STRONG>database</STRONG>
- Using Berkeley database, two types of records are stored: the
- terminfo data in the same format as stored in a directory tree
- 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, <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)
+ Using the Berkeley database API, two types of records are stored:
+ the <EM>terminfo</EM> data in the same format as that stored in a directory
+ tree with the terminal's primary type name as a key, and records
+ containing only aliases pointing to the primary name.
+
+ If built to write hashed databases, <EM>ncurses</EM> can still read <EM>term-</EM>
+ <EM>info</EM> databases organized as a directory tree, but cannot write
+ entries into the directory tree. It can write (or rewrite)
entries in the hashed database.
- <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
+ <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 a hashed
database otherwise.
</PRE><H3><a name="h3-Legacy-Storage-Format">Legacy Storage Format</a></H3><PRE>
The format has been chosen so that it will be the same on all hardware.
- An 8 or more bit byte is assumed, but no assumptions about byte
- ordering or sign extension are made.
+ A byte of at least eight bits' width is assumed, but no assumptions
+ about bit ordering or sign extension are made.
- The compiled file is created with the <STRONG>tic</STRONG> program, and read by the
- routine <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>. The file is divided into six parts:
+ The file is divided into six parts:
- a) <EM>header</EM>,
+ (a) <EM>header</EM>,
- b) <EM>terminal</EM> <EM>names</EM>,
+ (b) <EM>terminal</EM> <EM>names</EM>,
- c) <EM>Boolean</EM> <EM>flags</EM>,
+ (c) <EM>Boolean</EM> <EM>flags</EM>,
- d) <EM>numbers</EM>,
+ (d) <EM>numbers</EM>,
- e) <EM>strings</EM>, and
+ (e) <EM>strings</EM>, and
- f) <EM>string</EM> <EM>table</EM>.
+ (f) a <EM>string</EM> <EM>table</EM>.
The <EM>header</EM> section begins the file. This section contains six short
integers in the format described below. These integers are
- (1) the <EM>magic</EM> <EM>number</EM> (octal 0432);
+ (1) the <EM>magic</EM> <EM>number</EM>
+ (octal 0432);
- (2) the size, in bytes, of the <EM>terminal</EM> <EM>names</EM> section;
+ (2) the size,
+ in bytes, of the <EM>terminal</EM> <EM>names</EM> section;
(3) the number of bytes in the <EM>Boolean</EM> <EM>flags</EM> section;
(4) the number of short integers in the <EM>numbers</EM> section;
- (5) the number of offsets (short integers) in the <EM>strings</EM> section;
+ (5) the number of offsets
+ (short integers) in the <EM>strings</EM> section;
- (6) the size, in bytes, of the <EM>string</EM> <EM>table</EM>.
+ (6) the size,
+ in bytes, of the <EM>string</EM> <EM>table</EM>.
The capabilities in the <EM>Boolean</EM> <EM>flags</EM>, <EM>numbers</EM>, and <EM>strings</EM> sections
- are in the same order as the file <term.h>.
+ are in the same order as in the header file <EM>term.h</EM>.
- Short integers are signed, in the range -32768 to 32767. They are
- stored as two 8-bit bytes. The first byte contains the least
- significant 8 bits of the value, and the second byte contains the most
- significant 8 bits. (Thus, the value represented is 256*second+first.)
- This format corresponds to the hardware of the VAX and PDP-11 (that is,
- little-endian machines). Machines where this does not correspond to
- the hardware must read the integers as two bytes and compute the
- little-endian value.
+ Short integers are signed, in the range -32768 to 32767, and stored in
+ little-endian format.
Numbers in a terminal description, whether they are entries in the
<EM>numbers</EM> or <EM>strings</EM> table, are positive integers. Boolean flags are
treated as positive one-byte integers. In each case, those positive
- integers represent a terminal capability. The terminal compiler tic
+ integers represent a terminal capability. The terminal compiler <EM>tic</EM>
uses negative integers to handle the cases where a capability is not
available:
- <STRONG>o</STRONG> If a capability is absent from this terminal, tic stores a -1 in
+ <STRONG>o</STRONG> If a capability is absent from this terminal, <EM>tic</EM> stores a -1 in
the corresponding table.
The integer value -1 is represented by two bytes 0377, 0377.
Absent Boolean values are represented by the byte 0 (false).
- <STRONG>o</STRONG> If a capability has been canceled from this terminal, tic stores a
+ <STRONG>o</STRONG> If a capability has been canceled from this terminal, <EM>tic</EM> stores a
-2 in the corresponding table.
The integer value -2 is represented by two bytes 0377, 0376.
<STRONG>o</STRONG> Other negative values are illegal.
The <EM>terminal</EM> <EM>names</EM> section comes after the <EM>header</EM>. It contains the
- first line of the terminfo description, listing the various names for
+ first line of the <EM>terminfo</EM> description, listing the various names for
the terminal, separated by the "|" character. The <EM>terminal</EM> <EM>names</EM>
section is terminated with an ASCII NUL character.
string capabilities referenced in the <EM>strings</EM> section. Each string is
null-terminated. Special characters in ^X or \c notation are stored in
their interpreted form, not the printing representation. Padding
- information $<nn> and parameter information %x are stored intact in
+ information <STRONG>$<</STRONG><EM>nn</EM><STRONG>></STRONG> and parameter information <STRONG>%x</STRONG> are stored intact in
uninterpreted form.
</PRE><H3><a name="h3-Extended-Storage-Format">Extended Storage Format</a></H3><PRE>
- The previous section describes the conventional terminfo binary format.
+ The previous section describes the conventional <EM>terminfo</EM> binary format.
With some minor variations of the offsets (see PORTABILITY), the same
binary format is used in all modern Unix systems. Each system uses a
predefined set of Boolean, number or string capabilities.
- The <EM>ncurses</EM> libraries and applications support extended terminfo binary
- format, allowing users to define capabilities which are loaded at
+ The <EM>ncurses</EM> libraries and applications support extended <EM>terminfo</EM> binary
+ format, allowing users to define capabilities that 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. <EM>ncurses</EM> checks the
- size, and if it exceeds that due to the predefined data, continues to
- parse according to its own scheme.
+ other implementations stop reading the <EM>terminfo</EM> data when they reach
+ 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.
First, it reads the extended header (5 short integers):
The extended string table contains values for string capabilities.
After the end of these values, it contains the names for each of the
- extended capabilities in order, e.g., Booleans, then numbers and
- finally strings.
+ extended capabilities in order: Boolean, numeric, and string.
- By storing terminal descriptions in this way, <EM>ncurses</EM> 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 <EM>ncurses</EM> uses
- this extended information.
+ providing data for applications that require more information about a
+ terminal type than was anticipated by X/Open Curses. 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
- described in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> which associate the long capability
- names with members of a <STRONG>TERMTYPE</STRONG> structure.
+ Applications that manipulate terminal data can use the definitions
+ described in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> associating the long capability names
+ with members of a <EM>TERMTYPE</EM> structure.
</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 <EM>ncurses</EM>
- 6.1, a new format was introduced by making a few changes to the legacy
- format:
+ On occasion, 16-bit signed integers are not large enough. <EM>ncurses</EM> 6.1
+ introduced a new format by making a few changes to the legacy format:
<STRONG>o</STRONG> a different magic number (octal 01036)
to signed 32-bit integers.
To maintain compatibility, the library presents the same data
- structures to direct users of the <STRONG>TERMTYPE</STRONG> structure as in previous
+ structures to direct users of the <EM>TERMTYPE</EM> structure as in previous
formats. However, that cannot provide callers with the extended
numbers. The library uses a similar but hidden data structure
- <STRONG>TERMTYPE2</STRONG> to provide data for the terminfo functions.
+ <EM>TERMTYPE2</EM> to provide data for the <EM>terminfo</EM> functions.
</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
</PRE><H3><a name="h3-Binary-Format">Binary Format</a></H3><PRE>
- X/Open Curses does not specify a format for the terminfo database.
- System V curses used a directory-tree of binary files, one per terminal
+ X/Open Curses does not specify a format for the <EM>terminfo</EM> database.
+ System V <EM>curses</EM> used a directory-tree of binary files, one per terminal
description.
- Despite the consistent use of little-endian for numbers and the
- otherwise self-describing format, it is not wise to count on
- portability of binary terminfo entries between commercial Unix
- versions. The problem is that there are at least three versions of
- terminfo (under HP-UX, AIX, and OSF/1) which diverged from System V
- terminfo after SVr1, and have added extension capabilities to the
- string table that (in the binary format) collide with System V and
- X/Open Curses extensions. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for detailed discussion of
- terminfo source compatibility issues.
-
- This implementation is by default compatible with the binary terminfo
- format used by Solaris curses, except in a few less-used details where
+ Despite the consistent use of little-endian numbers and the otherwise
+ self-describing format, it is not wise to count on portability of
+ binary <EM>terminfo</EM> entries between commercial Unix versions. The problem
+ is that there are at least three versions of <EM>terminfo</EM> (under HP-UX,
+ AIX, and OSF/1) each of which diverged from System V <EM>terminfo</EM> after
+ SVr1, and added extension capabilities to the string table that (in the
+ binary format) collide with System V and X/Open Curses extensions. See
+ <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for detailed discussion of <EM>terminfo</EM> source compatibility
+ issues.
+
+ This implementation is by default compatible with the binary <EM>terminfo</EM>
+ format used by Solaris <EM>curses</EM>, 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 <EM>ncurses</EM> with
different configuration options.
</PRE><H3><a name="h3-Magic-Codes">Magic Codes</a></H3><PRE>
- The magic number in a binary terminfo file is the first 16-bits (two
+ The magic number in a binary <EM>terminfo</EM> file is the first 16 bits (two
bytes). Besides making it more reliable for the library to check that
- a file is terminfo, utilities such as <STRONG>file(1)</STRONG> also use that to tell
+ a file is <EM>terminfo</EM>, utilities such as <STRONG>file(1)</STRONG> also use that to tell
what the file-format is. System V defined more than one magic number,
with 0433, 0435 as screen-dumps (see <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>). This implementation
uses 01036 as a continuation of that sequence, but with a different
high-order byte to avoid confusion.
<STRONG>The</STRONG> <EM>TERMTYPE</EM> <STRONG>Structure</STRONG>
- Direct access to the <STRONG>TERMTYPE</STRONG> structure is provided for legacy
- applications. Portable applications should use the <STRONG>tigetflag</STRONG> and
- related functions described in <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> for reading terminal
- capabilities.
+ Direct access to the <EM>TERMTYPE</EM> structure is provided for legacy
+ applications. Portable applications should use <STRONG><A HREF="curs_terminfo.3x.html">tigetflag(3x)</A></STRONG> and
+ related functions to read terminal capabilities.
</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, <EM>ncurses</EM> represents the "first
- character" of the terminal name used as the intermediate level of a
+ A small number of terminal descriptions use uppercase characters in
+ their names. If the underlying file system ignores the difference
+ 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>
<EM>ncurses</EM> stores compiled terminal descriptions in three related formats,
- described in the sections
+ described in the subsections
- <STRONG>o</STRONG> <STRONG>LEGACY</STRONG> <STRONG>STORAGE</STRONG> <STRONG>FORMAT</STRONG>, and
+ <STRONG>o</STRONG> <STRONG>Legacy</STRONG> <STRONG>Storage</STRONG> <STRONG>Format</STRONG>, and
- <STRONG>o</STRONG> <STRONG>EXTENDED</STRONG> <STRONG>STORAGE</STRONG> <STRONG>FORMAT</STRONG>, and
+ <STRONG>o</STRONG> <STRONG>Extended</STRONG> <STRONG>Storage</STRONG> <STRONG>Format</STRONG>, and
- <STRONG>o</STRONG> <STRONG>EXTENDED</STRONG> <STRONG>NUMBER</STRONG> <STRONG>FORMAT</STRONG>.
+ <STRONG>o</STRONG> <STRONG>Extended</STRONG> <STRONG>Number</STRONG> <STRONG>Format</STRONG>.
- 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 <EM>ncurses</EM>
- 5.0 adds data to either of these formats.
+ The legacy storage format and the extended number format differ by the
+ types of numeric capability that they can store (for example, 16-
+ versus 32-bit integers). The extended storage format introduced by
+ <EM>ncurses</EM> 5.0 adds data to either of these formats.
Some limitations apply:
- <STRONG>o</STRONG> total compiled entries cannot exceed 4096 bytes in the legacy
+ <STRONG>o</STRONG> total compiled entries cannot exceed 4096 bytes in the legacy
format.
- <STRONG>o</STRONG> total compiled entries cannot exceed 32768 bytes in the extended
+ <STRONG>o</STRONG> total compiled entries cannot exceed 32768 bytes in the extended
format.
<STRONG>o</STRONG> the name field cannot exceed 128 bytes.
- Compiled entries are limited to 32768 bytes because offsets into the
- <EM>strings</EM> <EM>table</EM> use two-byte integers. The legacy format could have
- supported 32768-byte entries, but was limited to a virtual memory
+ Compiled entries are limited to 32768 bytes because offsets into the
+ <EM>strings</EM> <EM>table</EM> use two-byte integers. The legacy format could have
+ supported 32768-byte entries, but was limited to a virtual memory
page's 4096 bytes.
</PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE>
- As an example, here is a description for the Lear-Siegler ADM-3, a
- popular though rather stupid early terminal:
+ Here is a <EM>terminfo</EM> description of the Lear-Siegler ADM-3, a popular
+ though rather stupid early terminal.
adm3a|lsi adm3a,
am,
cuf1=^L, cup=\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,
home=^^, ind=^J,
- and a hexadecimal dump of the compiled terminal description:
+ A hexadecimal dump of its compiled terminal description (in legacy
+ format) follows.
0000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3
0010 61 7c 6c 73 69 20 61 64 6d 33 61 00 00 01 50 00 a|lsi ad m3a...P.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
Thomas E. Dickey
- extended terminfo format for <EM>ncurses</EM> 5.0
+ extended <EM>terminfo</EM> 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>.
+ documented legacy <EM>terminfo</EM> format (that used by <EM>pcurses</EM>).
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="term.5.html">term(5)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
-<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-Storage-Location">Storage Location</a></li>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: term.7,v 1.48 2024/03/16 15:35:01 tom Exp @
+ * @Id: term.7,v 1.49 2024/05/11 20:39: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>term 7 2024-03-16 ncurses 6.5 Miscellaneous</TITLE>
+<TITLE>term 7 2024-05-11 ncurses 6.5 Miscellaneous</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">term 7 2024-03-16 ncurses 6.5 Miscellaneous</H1>
+<H1 class="no-header">term 7 2024-05-11 ncurses 6.5 Miscellaneous</H1>
<PRE>
<STRONG><A HREF="term.7.html">term(7)</A></STRONG> Miscellaneous <STRONG><A HREF="term.7.html">term(7)</A></STRONG>
-ncurses 6.5 2024-0
3-16 <STRONG><A HREF="term.7.html">term(7)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="term.7.html">term(7)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: terminfo.head,v 1.65 2024/04/20 21:14:00 tom Exp @
+ * @Id: terminfo.head,v 1.66 2024/05/11 20:39: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>terminfo 5 2024-04-20 ncurses 6.5 File formats</TITLE>
+<TITLE>terminfo 5 2024-05-11 ncurses 6.5 File formats</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">terminfo 5 2024-04-20 ncurses 6.5 File formats</H1>
+<H1 class="no-header">terminfo 5 2024-05-11 ncurses 6.5 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 document describes <EM>ncurses</EM> version 6.5 (patch 20240427).
+ This document describes <EM>ncurses</EM> version 6.5 (patch 20240511).
</PRE><H3><a name="h3-terminfo-Entry-Syntax"><EM>terminfo</EM> Entry Syntax</a></H3><PRE>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
</PRE>
<div class="nav">
<ul>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: tic.1m,v 1.110 2024/04/27 17:57:06 tom Exp @
+ * @Id: tic.1m,v 1.111 2024/05/11 20:39: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>tic 1m 2024-04-27 ncurses 6.5 User commands</TITLE>
+<TITLE>tic 1m 2024-05-11 ncurses 6.5 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">tic 1m 2024-04-27 ncurses 6.5 User commands</H1>
+<H1 class="no-header">tic 1m 2024-05-11 ncurses 6.5 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>
-ncurses 6.5 2024-0
4-27 <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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.68 2024/04/20 18:59:26 tom Exp @
+ * @Id: toe.1m,v 1.69 2024/05/11 20:39: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>toe 1m 2024-04-20 ncurses 6.5 User commands</TITLE>
+<TITLE>toe 1m 2024-05-11 ncurses 6.5 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">toe 1m 2024-04-20 ncurses 6.5 User commands</H1>
+<H1 class="no-header">toe 1m 2024-05-11 ncurses 6.5 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>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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.113 2024/04/20 19:58:50 tom Exp @
+ * @Id: tput.1,v 1.114 2024/05/11 20:39: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>tput 1 2024-04-20 ncurses 6.5 User commands</TITLE>
+<TITLE>tput 1 2024-05-11 ncurses 6.5 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">tput 1 2024-04-20 ncurses 6.5 User commands</H1>
+<H1 class="no-header">tput 1 2024-05-11 ncurses 6.5 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>
-ncurses 6.5 2024-0
4-20 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <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.85 2024/04/27 17:57:47 tom Exp @
+ * @Id: tset.1,v 1.86 2024/05/11 20:39: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>tset 1 2024-04-27 ncurses 6.5 User commands</TITLE>
+<TITLE>tset 1 2024-05-11 ncurses 6.5 User commands</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">tset 1 2024-04-27 ncurses 6.5 User commands</H1>
+<H1 class="no-header">tset 1 2024-05-11 ncurses 6.5 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>
-ncurses 6.5 2024-0
4-27 <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>
+ncurses 6.5 2024-0
5-11 <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>
</PRE>
<div class="nav">
<ul>
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: MKncu_config.in,v 1.24 2024/04/20 21:13:38 tom Exp $
-.TH @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config 1 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.\" $Id: MKncu_config.in,v 1.25 2024/05/11 20:39:53 tom Exp $
+.TH @LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@\-config 1 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.SH NAME
\fB\%@LIB_NAME@@DFT_ARG_SUFFIX@@cf_cv_abi_version@-config\fP \-
configuration helper for \fI\%ncurses\fP libraries
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wch.3x,v 1.62 2024/04/20 21:20:07 tom Exp $
-.TH curs_add_wch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_add_wch.3x,v 1.63 2024/05/11 21:31:45 tom Exp $
+.TH curs_add_wch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB\%mvwadd_wch\fP,
\fB\%echo_wchar\fP,
\fB\%wecho_wchar\fP \-
-add a \fIcurses\fR complex character to a window and advance the cursor
+add a \fIcurses\fR complex character to a window, possibly advancing the cursor
.SH SYNOPSIS
.nf
\fB#include <curses.h>
\fBint wecho_wchar(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP);
.fi
.SH DESCRIPTION
-.SS add_wch
-The
-\fBadd_wch\fP,
-\fBwadd_wch\fP,
-\fBmvadd_wch\fP, and
-\fBmvwadd_wch\fP
-functions put the complex character \fIwch\fP into the given
-window at its current position,
-which is then advanced.
-These functions perform
-wrapping and special-character processing as follows:
+.SS wadd_wch
+.B \%wadd_wch
+writes the complex character
+.I wch
+to the window
+.IR win ","
+then may advance the cursor position,
+analogously to the standard C library's \fI\%putwchar\fP(3).
+\fB\%ncurses\fP(3X) describes the variants of this function.
+.PP
+Much behavior depends on whether the wide characters in
+.I wch
+are spacing or non-spacing;
+see subsection \*(``Complex Characters\*('' below.
.bP
-If \fIwch\fP refers to a spacing character,
-then any previous character at that location is removed.
-A new character specified by \fIwch\fP is
-placed at that location with rendition specified by \fIwch\fP.
-The cursor then advances after this spacing character,
-to prepare for writing the next character on the screen.
-.IP
-The newly added spacing character is the base of the active complex character.
-Subsequent non-spacing characters can be combined with this base
-until another spacing character is written to the screen,
-or the cursor is moved, e.g., using \fBwmove\fP.
+If
+.I wch
+contains a spacing character,
+then any character at the cursor is first removed.
+The complex character
+.IR wch ","
+with its attributes and color pair identifier,
+becomes the
+.I base
+of the
+.IR "active complex character" "."
.bP
-If \fIwch\fP refers to a non-spacing character,
-it is appended to the active complex character,
-retaining the previous characters at that location.
-The rendition specified by \fIwch\fP is ignored.
-.IP
-The cursor is not advanced after adding a non-spacing character.
-Subsequent calls to add non-spacing characters will update the same position.
+If
+.I wch
+contains only non-spacing characters,
+.\" XXX: see wadd_wch_literal (the beginning of the array may be nonspacing)
+they are combined with the active complex character.
+.I curses
+ignores its attributes and color pair identifier,
+and does not advance the cursor.
+.PP
+Further non-spacing characters added with
+.B \%wadd_wch
+are not written at the new cursor position but combine with the active
+complex character until another spacing character is written to the
+window or the cursor is moved.
+.PP
+If advancement occurs at the right margin,
+.bP
+the cursor automatically wraps to the beginning of the next line,
+then,
+.bP
+if it was at the bottom of the scrolling region,
+and if \fB\%scrollok\fP(3X) is enabled for
+.IR win ,
+the scrolling region scrolls up one line.
+.PP
+If
+.I wch
+is a
+backspace,
+carriage return,
+line feed,
+or
+tab,
+the cursor moves appropriately within the window.
.bP
-If the character part of \fIwch\fP is
-a tab, newline, backspace or other control character,
-the window is updated and the cursor moves as if \fBaddch\fP were called.
-.SS echo_wchar
-The \fBecho_wchar\fP
-function is functionally equivalent to a call to
-\fBadd_wch\fP
-followed by a call to
-\fB\%refresh\fP(3X).
-Similarly, the
-\fBwecho_wchar\fP
-is functionally equivalent to a call to
-\fBwadd_wch\fP
-followed by a call to
-\fBwrefresh\fP.
-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 the *\fBecho\fP* functions instead of their equivalents.
-.SS "Line Graphics"
-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
-\fB\%addch\fP(3X).
+Backspace moves the cursor one character left;
+at the left margin of a window,
+it does nothing.
+.bP
+Carriage return moves the cursor to the left margin on the current line
+of the window.
+.bP
+Line feed does a \fB\%clrtoeol\fP(3X),
+then advances as if from the right margin.
+.bP
+Tab advances the cursor to the next tab stop
+(possibly on the next line);
+these are placed at every eighth column by default.
+Alter the tab interval with the
+.B \%TABSIZE
+extension;
+see \fB\%curs_variables\fP(3X).
+.PP
+If
+.I wch
+is any other nonprintable character,
+it is drawn in printable form using the same convention as
+\fB\%wunctrl\fP(3X).
+.PP
+Calling \fB\%win_wch\fP(3X) on the location of a nonprintable character
+does not return the character itself,
+but its \fB\%wunctrl\fP(3X) representation.
+.SS wecho_wchar
+.B \%echo_wchar
+and
+.B \%wecho_wchar
+are equivalent to calling
+.RB \%( w ) add_wch
+followed by
+.RB \%( w ) refresh .
+.I curses
+interprets these functions as a hint that only a single (complex)
+character is being output;
+for non-control characters,
+a considerable performance gain may be enjoyed by employing them.
+.\" TODO: Combine the following with the "Line Drawing" subsection of
+.\" terminfo(5) and replace this with a cross reference there.
+.SS "Forms-Drawing Characters"
+.I curses
+defines macros starting with
+.B \%WACS_
+that can be used with
+.B \%wadd_wch
+to write line-drawing and other special characters to the screen.
+.I \%ncurses
+terms these
+.I "forms-drawing characters."
+The ACS default listed below is used if the
+.B \%acs_chars
+.RB ( \%acsc )
+.I \%term\%info
+capability does not define a terminal-specific replacement for it,
+or if the terminal and locale configuration requires Unicode to access
+these characters but the library is unable to use Unicode.
+The \*(``acsc char\*('' column corresponds to how the characters are
+specified in the
+.B \%acs_chars
+.RB ( \%acsc )
+string capability,
+and the characters in it may appear on the screen if the terminal type's
+database entry incorrectly advertises ACS support.
+The name \*(``ACS\*('' originates in the Alternate Character Set feature
+of the DEC VT100 terminal.
.PP
.TS
Lb Lb Lb Lb Lb
Lb Lb Lb Lb Lb
Lb L L L Lx.
-\& Unicode ASCII acsc \&
-ACS Name Default Default Char Glyph Name
+\& Unicode ACS acsc \&
+Symbol Default Default char Glyph Name
_
WACS_BLOCK 0x25ae # 0 T{
solid square block
.bP
U+2550 BOX DRAWINGS DOUBLE HORIZONTAL
.SH RETURN VALUE
-All routines return the integer \fBERR\fP upon failure and \fBOK\fP on success.
-.PP
-X/Open Curses does not specify any error conditions.
-This implementation returns an error
-.bP
-if the window pointer is null or
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
+In
+.IR \%ncurses ,
+.B \%wadd_wch
+returns
+.B ERR
+if
.bP
-if it is not possible to add a complete character in the window.
-.PP
-The latter may be due to different causes:
+.I win
+is
+.BR NULL ","
.bP
-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.
+wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
+not been called on
+.I win
+when writing to its bottom right location is attempted,
+or
.bP
-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 resulting bytes in the window,
-an error is returned.
+it is not possible to add a complete character at the cursor position.
.PP
Functions prefixed with \*(``mv\*('' first perform cursor movement and
fail if the position
.IR x )
is outside the window boundaries.
.SH NOTES
-Note that
-\fBadd_wch\fP,
-\fBmvadd_wch\fP,
-\fBmvwadd_wch\fP, and
-\fBecho_wchar\fP
-may be macros.
+.BR add_wch ","
+.BR mvadd_wch ","
+.BR mvwadd_wch ","
+and
+.B echo_wchar
+may be implemented as macros.
+.SH EXTENSIONS
+.SS TABSIZE
+The
+.B TABSIZE
+variable is implemented in SVr4 and other versions of
+.IR curses ,
+but is not specified by X/Open Curses
+(see \fBcurs_variables\fP(3X)).
.SH PORTABILITY
These functions are described in X/Open Curses, Issue 4.
-The defaults specified for line-drawing characters apply in the POSIX locale.
-.SS "WACS Symbols"
+It specifies no error conditions for them.
+.PP
+SVr4
+.I curses
+describes a successful return value only as
+\*(``an integer value other than
+.BR ERR \*(''.
+.PP
+The defaults specified for forms-drawing characters apply in the POSIX
+locale.
X/Open Curses makes it clear that the WACS_ symbols should be defined as
a pointer to \fBcchar_t\fP data, e.g., in the discussion of \fBborder_set\fP.
A few implementations are problematic:
\[u256C] U+256C (forms double vertical and horizontal), and
\[u2612] U+2612 (ballot box with x).
.SS "Complex Characters"
-The complex character type \fBcchar_t\fR
-can store more than one wide character (\fBwchar_t\fR).
-The X/Open Curses description does not mention this possibility,
-describing only the cases where \fIwch\fP is a spacing character
-or a non-spacing character.
+The complex character type
+.I \%cchar_t
+can store more than one wide character
+.RI ( \%wchar_t ).
+X/Open Curses does not mention this possibility,
+specifying behavior only where
+.I wch
+is a single character,
+either spacing or non-spacing.
.PP
-This implementation assumes that \fIwch\fP is constructed using
-\fB\%setcchar\fP(3X), and in turn that the result
+.I \%ncurses
+assumes that
+.I wch
+is constructed using \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,
-and zero or more non-spacing characters
+contains at most one spacing character at the beginning of its list of
+wide characters,
+and zero or more non-spacing characters,
or
.bP
-may hold one non-spacing character.
+holds one non-spacing character.
.PP
In the latter case,
-\fI\%ncurses\fP adds the non-spacing character to the active
-(base) spacing character.
-.SS TABSIZE
-The
-.B TABSIZE
-variable is implemented in SVr4 and other versions of
-.IR curses ,
-but is not specified by X/Open Curses
-(see \fBcurs_variables\fP(3X)).
+.I \%ncurses
+adds the non-spacing character to the active complex character.
.SH SEE ALSO
\fB\%curs_addch\fP(3X) describes comparable functions of the
.I \%ncurses
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_add_wchstr.3x,v 1.39 2024/04/20 21:20:07 tom Exp $
-.TH curs_add_wchstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_add_wchstr.3x,v 1.40 2024/05/11 20:39:53 tom Exp $
+.TH curs_add_wchstr 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint mvwadd_wchnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const cchar_t *\fIwchstr\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
-These functions copy the (null-terminated)
-array of complex characters \fIwchstr\fP
-into the window image structure
-starting at the current cursor position.
+.B \%wadd_wchstr
+copies the string of complex characters
+.I \%wchstr
+to the window
+.IR win "."
+A null complex character terminates the string.
+If a complex character does completely fit at the end of the line,
+.I curses
+fills the remaining columns with the window background;
+see \fB\%bkgrnd\fP(3X).
+.B \%wadd_wchnstr
+does the same,
+but copies at most
+.I n
+characters,
+or as many as possible if
+.I n
+is
+.BR \-1 "."
+\fB\%ncurses\fP(3X) describes the variants of these functions.
.PP
-The four functions with \fIn\fP as the last
-argument copy at most \fIn\fP elements,
-but no more than will fit on the line.
-If \fBn\fP=\fB\-1\fP then the whole array is copied,
-to the maximum number of characters that will fit on the line.
-.PP
-The window cursor is \fInot\fP advanced.
-These functions are faster than \fBwaddnstr\fP.
-On the other hand:
+Because these functions do not call \fB\%wadd_wch\fP(3X) internally,
+they are faster than \fB\%waddwstr\fP(3X) and \fB\%waddnwstr\fP(3X).
+On the other hand,
+they
.bP
-they do not perform checking
-(such as for the newline, backspace, or carriage return characters),
+do not treat the backspace,
+carriage return,
+or line feed characters specially;
.bP
-they do not advance the current cursor position,
+do not represent unprintable characters with \fB\%wunctrl\fP(3X);
.bP
-they do not expand other control characters to ^-escapes, and
+do not update the cursor position to follow the last character written;
.bP
-they truncate the string if it crosses the right margin,
-rather than wrapping it around to the new line.
-.PP
-These functions end successfully
-on encountering a null \fBcchar_t\fP, or
-when they have filled the current line.
-If a complex character cannot completely fit at the end of the current line,
-the remaining columns are filled with the background character and rendition.
+truncate the string at the window's right margin,
+rather than wrapping it to the next line and potentially scrolling.
.SH RETURN VALUE
-All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
.PP
X/Open Curses does not specify any error conditions.
-This implementation returns an error
+.I \%ncurses
+returns
+.B ERR
+if
.bP
-if the \fIwin\fP parameter is null or
+.I win
+is
+.B NULL
+or
.bP
-if the \fIwchstr\fP parameter is null.
+.I wchstr
+is
+.BR NULL "."
.PP
Functions prefixed with \*(``mv\*('' first perform cursor movement and
fail if the position
.IR x )
is outside the window boundaries.
.SH NOTES
-All functions except \fBwadd_wchnstr\fP may be macros.
+All of these functions except
+.B \%wadd_wchnstr
+may be implemented as macros.
.SH PORTABILITY
-These functions are described in X/Open Curses, Issue 4.
+X/Open Curses,
+Issue 4 describes these functions.
.SH SEE ALSO
\fB\%curs_addchstr\fP(3X) describes comparable functions of the
.I \%ncurses
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addch.3x,v 1.85 2024/04/20 19:03:47 tom Exp $
-.TH curs_addch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_addch.3x,v 1.86 2024/05/11 20:39:53 tom Exp $
+.TH curs_addch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint wechochar(WINDOW *\fIwin\fP, const chtype \fIch\fP);
.fi
.SH DESCRIPTION
-.SS "Adding Characters"
+.SS waddch
.B \%waddch
-puts the character
+writes the
+.I curses
+character
.I ch
-at the cursor position of window
-.IR win ,
+to the window
+.IR win ","
then advances the cursor position,
analogously to the standard C library's \fI\%putchar\fP(3).
\fB\%ncurses\fP(3X) describes the variants of this function.
.PP
If advancement occurs at the right margin,
.bP
-the cursor automatically wraps to the beginning of the next line;
-and
+the cursor automatically wraps to the beginning of the next line,
+then,
.bP
-at the bottom of the current scrolling region,
+if it was at the bottom of the scrolling region,
and if \fB\%scrollok\fP(3X) is enabled for
.IR win ,
the scrolling region scrolls up one line.
of the window.
.bP
Line feed does a \fB\%clrtoeol\fP(3X),
-then moves the cursor to the left margin on the next line of the window,
-and if \fB\%scrollok\fP(3X) is enabled for
-.IR win ,
-scrolls the window if the cursor was already on the last line.
+then advances as if from the right margin.
.bP
Tab advances the cursor to the next tab stop
(possibly on the next line);
If
.I ch
is any other nonprintable character,
-it is drawn in printable form,
-using the same convention as \fB\%unctrl\fP(3X).
+it is drawn in printable form using the same convention as
+\fB\%unctrl\fP(3X).
.PP
Calling \fB\%winch\fP(3X) on the location of a nonprintable character
does not return the character itself,
but its \fB\%unctrl\fP(3X) representation.
.PP
+The object or expression
.I ch
-may contain rendering and/or color attributes,
-and others can be combined with the parameter
-by logically \*(``or\*(''ing with it.
+may contain attributes and/or a color pair identifier.
(A character with its attributes can be copied from place to place
using \fB\%winch\fP(3X) and
.BR \%waddch .)
See \fB\%curs_attr\fP(3X) for values of predefined video attribute
constants that can be usefully \*(``or\*(''ed with characters.
-.SS "Echoing Characters"
+.SS wechochar
.B \%echochar
and
.B \%wechochar
The \*(``acsc char\*('' column corresponds to how the characters are
specified in the
.B \%acs_chars
+.RB ( \%acsc )
string capability,
-and the characters in it may appear on the screen if the terminal's
+and the characters in it may appear on the screen if the terminal type's
database entry incorrectly advertises ACS support.
The name \*(``ACS\*('' originates in the Alternate Character Set feature
of the DEC VT100 terminal.
.B \%waddch
returns
.B ERR
-if it is not possible to add a complete character at the cursor
-position,
-as when conversion of a multibyte character to a byte sequence fails,
-or at least one of the resulting bytes cannot be added to the window.
+if
+.bP
+.I win
+is
+.BR NULL ","
+.bP
+wrapping to a new line is impossible because \fB\%scrollok\fP(3X) has
+not been called on
+.I win
+when a write to its bottom right location is attempted,
+or
+.bP
+it is not possible to add a complete character at the cursor position.
+.PP
+The last may be due to different causes:
+.bP
+conversion of a multibyte character to a byte sequence can fail,
+or
+.bP
+at least one of the bytes resulting from conversion from a multibyte
+sequence cannot be added to the window.
See section \*(``PORTABILITY\*('' below regarding the use of
.B \%waddch
with multibyte characters.
.PP
-.B \%waddch
-can successfully write a character at the bottom right location of the
-window.
-However,
-.I \%ncurses
-returns
-.B ERR
-if \fB\%scrollok\fP(3X) is not enabled in that event,
-because it is not possible to wrap to a new line.
-.PP
Functions prefixed with \*(``mv\*('' first perform cursor movement and
fail if the position
.RI ( y ,
.IR x )
is outside the window boundaries.
.SH NOTES
-.BR \%addch ,
-.BR \%mvaddch ,
-.BR \%mvwaddch ,
+.BR \%addch ","
+.BR \%mvaddch ","
+.BR \%mvwaddch ","
and
.B \%echochar
may be implemented as macros.
+.SH EXTENSIONS
+.SS TABSIZE
+SVr4 and other versions of
+.I curses
+implement the
+.B \%TABSIZE
+variable,
+but X/Open Curses does not specify it;
+see \fB\%curs_variables\fP(3X).
.SH PORTABILITY
X/Open Curses,
Issue 4 describes these functions.
Solaris
.IR curses ,
for example,
-define the ACS symbols as constants;
+defines the ACS symbols as constants;
others define them as elements of an array.
.IP
This implementation uses an array,
.I \%term\%info
entries include
.B \%acsc
-strings in which their key characters
-.BR ( pryz{|} )
+capabilities in which their key characters
+.RB ( pryz{|} )
are embedded,
and a second-hand list of their character descriptions has come to
light.
by using UTF-8;
see the discussion of the
.I \%NCURSES_NO_UTF8_ACS
-environment variable in \fB\%ncurses\fP(3X)).
+environment variable in \fB\%ncurses\fP(3X).
.SS "Character Set"
X/Open Curses assumes that the parameter passed to
.B \%waddch
contains a single character.
-As discussed in \fB\%curs_attr\fP(3X),
-that character may have been more than eight bits wide in an SVr3 or
+That character may have been more than eight bits wide in an SVr3 or
SVr4 implementation,
-but in the X/Open Curses model,
-the details are not given.
-The important distinction between SVr4
-.I curses
-and X/Open Curses is that the latter separates non-character information
-(attributes and color)
-from the character code,
-which SVr4 packs into a
+but X/Open Curses leaves the width of a non-wide character code
+unspecified.
+The standard further does not specify the internal structure of a
+.IR chtype ","
+though the use of bit operations to combine the character code with
+attributes and a color pair identifier into a
.I \%chtype
for passage to
-.BR \%waddch .
+.B \%waddch
+is common.
+A portable application uses only the macros discussed in
+\fB\%curs_attr\fP(3X) to manipulate a
+.IR \%chtype "."
.PP
In
.IR \%ncurses ,
.I \%chtype
-holds an eight-bit character.
-But the library allows a multibyte character to be passed in a
+holds an eight-bit character,
+but the library allows a multibyte character to be passed in a
succession of calls to
-.BR \%waddch .
+.BR \%waddch "."
Other implementations do not;
a
.B \%waddch
call transmits exactly one character,
which may be rendered in one or more screen locations depending on
-whether it is printable.
-.PP
-Depending on the locale settings,
+whether it is printable
+(see \fB\%unctrl\fP(3X)).
+Depending on the locale,
.I \%ncurses
inspects the byte passed in each
.B \%waddch
-call,
-and checks whether the latest call continues a multibyte sequence.
+call and checks whether the latest call continues a multibyte sequence.
When a character is
-.IR complete ,
+.IR complete ","
.I \%ncurses
displays the character and advances the cursor.
-.PP
If the calling application interrupts the succession of bytes in
a multibyte character sequence by changing the current location\(emfor
example,
discards the incomplete character.
.PP
For portability to other implementations,
-do not rely upon this behavior.
+do not rely upon the foregoing behavior.
Check whether a character can be represented as a single byte in the
current locale.
.bP
If it cannot,
use only
\fB\%wadd_wch\fP(3X).
-.SS TABSIZE
-SVr4 and other versions of
-.I curses
-implement the
-.B \%TABSIZE
-variable,
-but X/Open Curses does not specify it
-(see \fB\%curs_variables\fP(3X)).
.SH SEE ALSO
\fB\%curs_add_wch\fP(3X) describes comparable functions of the
.I \%ncurses
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_addchstr.3x,v 1.45 2024/04/20 21:20:07 tom Exp $
-.TH curs_addchstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_addchstr.3x,v 1.46 2024/05/11 20:39:53 tom Exp $
+.TH curs_addchstr 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fBint mvwaddchnstr(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const chtype *\fIchstr\fP, int \fIn\fP);
.fi
.SH DESCRIPTION
-These functions copy the (null-terminated)
-\fIchstr\fP array
-into the window image structure
-starting at the current cursor position.
+.B \%waddchstr
+copies the string of
+.I curses
+characters
+.I \%chstr
+to the window
+.IR win "."
+A null
+.I curses
+character terminates the string.
+.B \%waddchnstr
+does the same,
+but copies at most
+.I n
+characters,
+or as many as possible if
+.I n
+is
+.BR \-1 "."
+\fB\%ncurses\fP(3X) describes the variants of these functions.
.PP
-The four functions with \fIn\fP as the last
-argument copy at most \fIn\fP elements,
-but no more than will fit on the line.
-If \fBn\fP=\fB\-1\fP then the whole array is copied,
-to the maximum number of characters that will fit on the line.
-.PP
-The window cursor is \fInot\fP advanced.
-These functions are faster than \fBwaddnstr\fP.
-On the other hand:
+Because these functions do not call \fB\%waddch\fP(3X) internally,
+they are faster than \fB\%waddstr\fP(3X) and \fB\%waddnstr\fP(3X).
+On the other hand,
+they
.bP
-they do not perform checking
-(such as for the newline, backspace, or carriage return characters),
+do not treat the backspace,
+carriage return,
+or line feed characters specially;
.bP
-they do not advance the current cursor position,
+do not represent unprintable characters with \fB\%unctrl\fP(3X);
.bP
-they do not expand other control characters to ^-escapes, and
+do not update the cursor position to follow the last character written;
.bP
-they truncate the string if it crosses the right margin,
-rather than wrapping it around to the new line.
+truncate the string at the window's right margin,
+rather than wrapping it to the next line and potentially scrolling.
.SH RETURN VALUE
-All functions return the integer \fBERR\fP upon failure and \fBOK\fP on success.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
.PP
X/Open Curses does not specify any error conditions.
-This implementation returns an error
+.I \%ncurses
+returns
+.B ERR
+if
.bP
-if the \fIwin\fP parameter is null or
+.I win
+is
+.B NULL
+or
.bP
-if the \fIwchstr\fP parameter is null.
+.I chstr
+is
+.BR NULL "."
.PP
Functions prefixed with \*(``mv\*('' first perform cursor movement and
fail if the position
.IR x )
is outside the window boundaries.
.SH NOTES
-All functions except \fBwaddchnstr\fP may be macros.
+All of these functions except
+.B \%waddchnstr
+may be implemented as macros.
.SH PORTABILITY
-These functions are described in X/Open Curses, Issue 4.
+X/Open Curses,
+Issue 4 describes these functions.
.SH SEE ALSO
\fB\%curs_add_wchstr\fP(3X) describes comparable functions of the
.I \%ncurses
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_attr.3x,v 1.105 2024/04/27 17:54:42 tom Exp $
-.TH curs_attr 3X 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_attr.3x,v 1.106 2024/05/11 20:39:53 tom Exp $
+.TH curs_attr 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.TE
.RE
.PP
+You can thus use
+.B \%A_CHARTEXT
+to extract the character from a
+.IR chtype ","
+.B \%A_ATTRIBUTES
+to obtain its rendering attributes,
+and
+.B \%A_COLOR
+to find the color pair it uses.
+.PP
These video attributes are supported by \fBattr_on\fP and related functions
(which also support the attributes recognized by \fBattron\fP, etc.):
.PP
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_delch.3x,v 1.34 2024/04/20 19:24:14 tom Exp $
-.TH curs_delch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_delch.3x,v 1.35 2024/05/11 20:39:53 tom Exp $
+.TH curs_delch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.B \%wdelch
deletes the character at the cursor position in
.IR win .
-\fB\%ncurses\fP(3X) describes the variants of this function.
-.PP
-.B \%wdelch
-moves all characters to the right of the cursor on the same line to the
-left one position and replaces the contents of the rightmost position on
-the line with the window's blank character;
+It moves all characters to the right of the cursor on the same line to
+the left one position and replaces the contents of the rightmost
+position on the line with the window's blank character;
see \fB\%bkgd\fP(3X)
-(wide-character API users may consult \fB\%bkgrnd\fP(3X) instead).
+(wide-character API users: \fB\%bkgrnd\fP(3X)).
The cursor position does not change
(after moving to
.RI ( y ,
.IR x ),
if specified).
+\fB\%ncurses\fP(3X) describes the variants of this function.
.SH RETURN VALUE
These functions return
.B OK
.SH PORTABILITY
X/Open Curses,
Issue 4 describes these functions.
+It specifies no error conditions for them.
.PP
SVr4
.I curses
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_get_wch.3x,v 1.40 2024/04/20 19:23:03 tom Exp $
-.TH curs_get_wch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_get_wch.3x,v 1.41 2024/05/11 20:39:53 tom Exp $
+.TH curs_get_wch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.SH DESCRIPTION
.SS "Reading Characters"
.B \%wget_wch
-gathers a key stroke
-.I wch
-from the terminal keyboard associated with a
+gathers a key event from the terminal keyboard associated with a
.I curses
window
-.IR win ,
+.IR win ","
returning
.B OK
if a wide character is read,
When input is pending,
.B \%wget_wch
stores an integer
-identifying the key stroke in
-.IR wch ;
+identifying the key event in
+.IR wch ";"
for alphanumeric and punctuation keys,
this value corresponds to the character encoding used by the terminal.
-Use of the control key as a modifier often results in a distinct code.
+Use of the control key as a modifier,
+by holding it down while pressing and releasing another key,
+often results in a distinct code.
The behavior of other keys depends on whether
.I win
is in keypad mode;
then if the no-delay flag is set in the window
(see \fB\%nodelay\fP(3X)),
the function returns
-.BR ERR ;
+.BR ERR ";"
otherwise,
.I curses
waits until the terminal has input.
If \fB\%halfdelay\fP(3X)
has been called,
.I curses
-waits until a character is typed or the specified delay elapses.
+waits until input is available or the specified delay elapses.
.PP
If \fB\%echo\fP(3X) has been called,
and the window is not a pad,
to the window,
as with \fB\%wecho_wchar\fP(3X).
.bP
-If the window has been moved or modified since the last call to
+If the window
+.I win
+has been moved or modified since the last call to
\fB\%wrefresh\fP(3X),
.I curses
calls
-.BR \%wrefresh .
+.B \%wrefresh
+on it.
.PP
If
.I wch
is a carriage return and \fBnl\fP(3X) has been called,
.B \%wgetch
-stores the the character code for newline
-(line feed)
-in
+stores the the character code for line feed in
.I wch
instead.
.SS "Ungetting Characters"
places
.I wch
into the input queue to be returned by the next call to
-.BR \%wget_wch .
-A single input queue serves all windows.
+.BR \%wget_wch "."
+A single input queue serves all windows associated with the terminal.
.SH RETURN VALUE
.B \%wget_wch
returns
the
.I \%WINDOW
pointer is
-.BR NULL ,
+.BR NULL ","
or
.bP
its timeout expires without any data arriving,
in which case
.B \%errno
is set to
-.BR \%EINTR .
+.BR \%EINTR "."
.PP
Functions prefixed with \*(``mv\*('' first perform cursor movement and
fail if the position
.RI ( y ,
-.IR x )
+.IR x ")"
is outside the window boundaries.
.PP
.B \%unget_wch
parameter instead of the return value.
.PP
Unlike
-.BR \%ungetch ,
+.BR \%ungetch ","
.B \%unget_wch
-cannot distinguish function key codes
-.B \%wget_wch
-from conventional character codes.
+cannot distinguish function key codes from conventional character codes.
An application can overcome this limitation by pushing function key
codes with
.B \%ungetch
and subsequently checking the return value of
.B \%wget_wch
for a match with
-.BR \%KEY_CODE_YES .
+.BR \%KEY_CODE_YES "."
.SH EXTENSIONS
See the \*(``EXTENSIONS\*('' section of \fB\%wgetch\fP(3X).
.SH PORTABILITY
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getch.3x,v 1.87 2024/04/20 19:18:18 tom Exp $
-.TH curs_getch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_getch.3x,v 1.88 2024/05/11 20:39:53 tom Exp $
+.TH curs_getch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.SH DESCRIPTION
.SS "Reading Characters"
.B \%wgetch
-gathers a key stroke from the terminal keyboard associated with a
+gathers a key event from the terminal keyboard associated with a
.I curses
window
-.IR win .
+.IR win "."
\fB\%ncurses\fP(3X) describes the variants of this function.
.PP
When input is pending,
.B \%wgetch
-returns an integer identifying the key stroke;
+returns an integer identifying the key event;
for alphanumeric and punctuation keys,
this value corresponds to the character encoding used by the terminal.
-Use of the control key as a modifier often results in a distinct code.
+Use of the control key as a modifier,
+by holding it down while pressing and releasing another key,
+often results in a distinct code.
The behavior of other keys depends on whether
.I win
is in keypad mode;
then if the no-delay flag is set in the window
(see \fB\%nodelay\fP(3X)),
the function returns
-.BR ERR ;
+.BR ERR ";"
otherwise,
.I curses
waits until the terminal has input.
If \fB\%halfdelay\fP(3X)
has been called,
.I curses
-waits until a character is typed or the specified delay elapses.
+waits until input is available or the specified delay elapses.
.PP
If \fB\%echo\fP(3X) has been called,
and the window is not a pad,
to the window,
as with \fB\%wechochar\fP(3X).
.bP
-If the window has been moved or modified since the last call to
+If the window
+.I win
+has been moved or modified since the last call to
\fB\%wrefresh\fP(3X),
.I curses
calls
-.BR \%wrefresh .
+.B \%wrefresh
+on it.
.PP
If
.I c
returns the character code for line feed instead.
.SS "Keypad Mode"
To
-.IR curses ,
+.IR curses ","
key strokes not from the alphabetic section of the keyboard
(those corresponding to the ECMA-6 character set\(emsee
\fIascii\fP(7)\(emoptionally modified by either the control or shift
.I function
keys.
(In
-.IR curses ,
+.IR curses ","
the term \*(``function key\*('' includes but is not limited to keycaps
engraved with \*(``F1\*('',
\*(``PF1\*('',
header file declares many
.I "predefined function keys"
whose names begin with
-.BR KEY_ ;
+.BR KEY_ ";"
these object-like macros have values outside the range of eight-bit
character codes.
.bP
In
-.IR \%ncurses ,
+.IR \%ncurses ","
.I "user-defined function keys"
are configured with \fB\%define_key\fP(3X);
they have no names,
escape character ESC.
This fact implies that
.I curses
-cannot know whether the terminal has sent an ESC key stroke or the
-beginning of a function key's character sequence without waiting to see
-if,
+cannot distinguish a user's press of the escape key
+(assuming it sends ESC)
+from the beginning of a function key's character sequence without
+waiting to see if,
and how soon,
further input arrives.
When
Consequently,
a user of a
.I curses
-application may experience a delay after pressing ESC while
+application may experience a delay after they escape key is pressed
+while
.I curses
disambiguates the input;
see section \*(``EXTENSIONS\*('' below.
(or very large)
value.
See \fB\%notimeout\fP(3X).
-Because function key sequences usually begin with an escape character,
-the terminal may appear to hang in no time-out mode after the user has
-pressed ESC.
+Because function key sequences usually begin with ESC,
+the terminal may appear to hang in no time-out mode after the user
+presses the escape key.
Generally,
further typing \*(``awakens\*(''
-.IR curses .
+.IR curses "."
.SS "Ungetting Characters"
.B \%ungetch
places
.I c
into the input queue to be returned by the next call to
-.BR \%wgetch .
-A single input queue serves all windows.
+.BR \%wgetch "."
+A single input queue serves all windows associated with the terminal.
.SS "Predefined Key Codes"
The header file
.I \%curses.h
defines the following function key codes.
.bP
Except for the special case of
-.BR \%KEY_RESIZE ,
+.BR \%KEY_RESIZE ","
a window's keypad mode must be enabled for
.B \%wgetch
to read these codes from it.
.bP
.B \%wgetch
returns
-.BR \%KEY_RESIZE ,
+.BR \%KEY_RESIZE ","
even if the window's keypad mode is disabled,
when
.I \%ncurses
as with a function key.
.SS "Testing Key Codes"
In
-.IR \%ncurses ,
+.IR \%ncurses ","
.B \%has_key
returns a Boolean value indicating whether the terminal type recognizes
its parameter as a key code value.
\fB\%define_key\fP(3X) and \fB\%key_defined\fP(3X).
.SH RETURN VALUE
Except for
-.BR \%has_key ,
+.BR \%has_key ","
these functions return
.B OK
on success and
Functions taking a
.I \%WINDOW
pointer argument fail if the pointer is
-.BR NULL .
+.BR NULL "."
.PP
Functions prefixed with \*(``mv\*('' first perform cursor movement and
fail if the position
.RI ( y ,
-.IR x )
+.IR x ")"
is outside the window boundaries.
.PP
.B \%wgetch
in which case
.B \%errno
is set to
-.BR \%EINTR .
+.BR \%EINTR "."
.PP
.B \%ungetch
fails if there is no more room in the input queue.
returns
.B TRUE
or
-.BR FALSE .
+.BR FALSE "."
.SH NOTES
.I curses
discourages assignment of the ESC key to a discrete function by the
for example,
.B \%KEY_ENTER
may be the same as
-.BR \*^M ,
+.BR \*^M ","
.\" as with att630 or pccon+keys
and
.B \%KEY_BACKSPACE
.B \*^H
.\" as with att505 or vt52-basic
or
-.BR \*^? .
+.BR \*^? "."
.\" as with pccon+keys or vt320
Consult the terminal's
.I \%term\%info
.I curses
implementations,
including
-.IR \%ncurses ,
+.IR \%ncurses ","
honor the
.I \%term\%info
key definitions;
.B \%KEY_ENTER
refers to the key on the numeric keypad and,
like other function keys,
-and is reliably recognized only if the window's keypad mode is enabled.
+is reliably recognized only if the window's keypad mode is enabled.
.bP
The
.I \%term\%info
A
.I curses
application can expect such a keyboard to transmit key codes
-.BR \%KEY_UP ,
-.BR \%KEY_DOWN ,
-.BR \%KEY_LEFT ,
-.BR \%KEY_RIGHT ,
-.BR \%KEY_HOME ,
-.BR \%KEY_END ,
+.BR \%KEY_UP ","
+.BR \%KEY_DOWN ","
+.BR \%KEY_LEFT ","
+.BR \%KEY_RIGHT ","
+.BR \%KEY_HOME ","
+.BR \%KEY_END ","
.B \%KEY_PPAGE
(Page Up),
.B \%KEY_NPAGE
.I n
\(<= 12.
.PP
-.BR \%getch ,
-.BR \%mvgetch ,
+.BR \%getch ","
+.BR \%mvgetch ","
and
.B \%mvwgetch
may be implemented as macros.
.SH EXTENSIONS
In
-.IR \%ncurses ,
+.IR \%ncurses ","
when a window's \*(``no time-out\*('' mode is
.I not
set,
see
\fB\%curs_variables\fP(3X).
.PP
-\fB\%has_key\fP was designed for \fB\%ncurses\fP(3X),
+\fB\%has_key\fP was designed for
+.IR \%ncurses ","
and is not found in SVr4
-.IR curses ,
+.IR curses ","
4.4BSD
-.IR curses ,
-or any other previous curses implementation.
+.IR curses ","
+or any other previous
+.I curses
+implementation.
.SH PORTABILITY
Applications employing
.I \%ncurses
.I curses
implementations,
it varied depending on whether the operating system's dispatch of a
-signal to a handler interrupting a \fIread\fP(2) call in progress,
+signal to a handler interrupted a \fIread\fP(2) call in progress,
and also
(in some implementations)
-whether an input timeout or non-blocking mode has been set.
+whether an input timeout or non-blocking mode had been set.
Programmers concerned about portability should be prepared for either of
two cases:
(a) signal receipt does not interrupt
-.BR \%wgetch ;
+.BR \%wgetch ";"
or
(b) signal receipt interrupts
.B \%wgetch
with
.B \%errno
set to
-.BR \%EINTR .
+.BR \%EINTR "."
.PP
.B \%KEY_MOUSE
is mentioned in X/Open Curses,
and
.B \%has_key
are extensions first implemented for
-.IR \%ncurses .
+.IR \%ncurses "."
By 2022,
.I \%PDCurses
.\" https://web.archive.org/web/20220117232009/https://pdcurses.org/docs/MANUAL.html
.I curses
.\" https://web.archive.org/web/20200923185647/https://man.netbsd.org/curses_input.3
had added them along with
-.BR \%KEY_MOUSE .
+.BR \%KEY_MOUSE "."
.SH SEE ALSO
\fB\%curs_get_wch\fP(3X) describes comparable functions of the
.I \%ncurses
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getstr.3x,v 1.58 2024/04/20 19:18:18 tom Exp $
-.TH curs_getstr 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_getstr.3x,v 1.59 2024/05/11 20:39:53 tom Exp $
+.TH curs_getstr 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
X/Open Curses, Issue 5 (2007) stated that these functions
\*(``read at most \fIn\fP bytes\*(''
-but did not state whether the terminating NUL is counted in that limit.
+but did not state whether the terminating NUL counted toward that limit.
X/Open Curses, Issue 7 (2009) changed that to say they
\*(``read at most \fIn\fP\-1 bytes\*(''
to allow for the terminating NUL.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_getyx.3x,v 1.44 2024/04/20 21:20:07 tom Exp $
-.TH curs_getyx 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_getyx.3x,v 1.45 2024/05/11 20:39:53 tom Exp $
+.TH curs_getyx 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
\fB#include <curses.h>
.PP
\fBvoid getyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
-\fBvoid getparyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
\fBvoid getbegyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
\fBvoid getmaxyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
+.PP
+\fBvoid getparyx(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
.fi
.SH DESCRIPTION
-The \fB\%getyx\fP macro places the current cursor position
-of the given window in the two integer variables \fIy\fP and \fIx\fP.
-.PP
-If \fIwin\fP is a subwindow, the \fB\%getparyx\fP macro places the beginning
-coordinates of the subwindow relative to the parent window into two integer
-variables \fIy\fP and \fIx\fP.
-Otherwise, \fB\-1\fP is placed into \fIy\fP and \fIx\fP.
+These macros obtain the cursor position and bounds information of a
+.I curses
+window
+.IR win "."
+.B \%getyx
+stores
+.IR win "'s"
+cursor position in the variables
+.I y
+and
+.IR x "."
+.B \%getmaxyx
+stores
+.IR win "'s"
+maximum valid row and column numbers in
+.I y
+and
+.IR x ","
+respectively.
+.B \%getbegyx
+similarly stores the position of
+.IR win "'s"
+origin relative to that of the screen
+(for
+.BR stdscr ","
+these coordinates are always
+.BR 0 ")."
.PP
-Like \fB\%getyx\fP, the \fB\%getbegyx\fP and \fB\%getmaxyx\fP macros store
-the current beginning coordinates and size of the specified window.
+If
+.I win
+is a subwindow
+(see \fB\%subwin\fP(3X)),
+the
+.B \%getparyx
+macro places the coordinates of its origin relative to its parent window
+into
+.I y
+and
+.IR x ","
+and
+.B \-1
+into both if it is not.
.SH RETURN VALUE
-The return values of these macros are undefined (i.e.,
-they should not be used as the right-hand side of assignment statements).
+No return values are defined for macros.
+Do not use them as the right-hand side of assignment statements.
.SH NOTES
-All of these interfaces are macros.
-A \*(``&\*('' is not necessary before the variables \fIy\fP and \fIx\fP.
+All of these interfaces are implemented as macros.
+An \*(``&\*('' operator is not necessary before the variables
+.I y
+and
+.IR x "."
.SH PORTABILITY
-The
-\fB\%getyx\fP,
-\fB\%getparyx\fP,
-\fB\%getbegyx\fP and
-\fB\%getmaxyx\fP
-macros are described in X/Open Curses, Issue 4.
+These macros are described in X/Open Curses,
+Issue 4.
.PP
-This implementation also provides functions
-\fB\%getbegx\fP,
-\fB\%getbegy\fP,
-\fB\%getcurx\fP,
-\fB\%getcury\fP,
-\fB\%getmaxx\fP,
-\fB\%getmaxy\fP,
-\fB\%getparx\fP and
-\fB\%getpary\fP
-for compatibility with older versions of \fIcurses\fP;
+.I \%ncurses
+also provides functions
+.BR \%getbegx ","
+.BR \%getbegy ","
+.BR \%getcurx ","
+.BR \%getcury ","
+.BR \%getmaxx ","
+.BR \%getmaxy ","
+.BR \%getparx ","
+and
+.B \%getpary
+for compatibility with older versions of
+.IR curses ";"
see \fB\%curs_legacy\fP(3X).
.PP
-Although X/Open Curses does not address this,
-many implementations provide members of the \fB\%WINDOW\fP structure
-containing values corresponding to these macros.
-For best portability, do not rely on using the data in \fB\%WINDOW\fP,
-since some implementations make \fB\%WINDOW\fP opaque (do not allow
-direct use of its members).
+Although X/Open Curses does not address the issue,
+many implementations expose members of the
+.I \%WINDOW
+structure containing values corresponding to these macros.
+Do not rely on their availability;
+some implementations make
+.I \%WINDOW
+opaque
+(that is,
+they do not allow direct access to its members).
.PP
Besides the problem of opaque structures,
-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 \fI\%ncurses\fP have
-(at least since release 1.8.1)
+the data stored in like-named members may not have values of the same
+meaning different implementations.
+For example,
+the values of
+.B \%WINDOW._maxx
+and
+.B \%WINDOW._maxy
+in
+.I \%ncurses
+have long
+.\" (at least since its initial release, 1.8.1)
differed by one from some other implementations.
-The difference is hidden by means of the macro \fB\%getmaxyx\fP.
+The
+.B \%getmaxyx
+macro hides this difference.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_legacy\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_inch.3x,v 1.51 2024/04/20 21:20:07 tom Exp $
-.TH curs_inch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_inch.3x,v 1.52 2024/05/11 20:39:53 tom Exp $
+.TH curs_inch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
\fBchtype inch(void);
\fBchtype winch(WINDOW *\fIwin\fP);
-.PP
\fBchtype mvinch(int \fIy\fP, int \fIx\fP);
\fBchtype mvwinch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
.fi
.SH DESCRIPTION
-These routines return the character, of type \fBchtype\fP, at the current
-position in the named window.
-If any attributes are set for that position,
-their values are OR'ed into the value returned.
-Constants defined in
-\fB<curses.h>\fP can be used with the \fB&\fP (logical AND) operator to
-extract the character or attributes alone.
-.
-.SS Attributes
-The following bit masks may be AND-ed with characters returned by \fBwinch\fP.
-.PP
-.TS
-Lb Lb
-Lb Lx.
-Name Description
-_
-A_CHARTEXT Extract character
-A_ATTRIBUTES Extract attributes
-A_COLOR Extract color pair information
-.TE
+.B \%winch
+returns the
+.I curses
+character,
+including rendering attributes and color pair identifier,
+at the cursor position in the window
+.IR win "."
+Subsection \*(``Video Attributes\*('' of \fB\%attron\fP(3X) explains
+how to extract these data from a
+.IR chtype "."
+\fB\%ncurses\fP(3X) describes the variants of this function.
.SH RETURN VALUE
Functions prefixed with \*(``mv\*('' first perform cursor movement and
fail if the position
.IR x )
is outside the window boundaries.
.PP
-The \fBwinch\fP function does not return an error if the window contains
-characters larger than 8-bits (255).
-Only the low-order 8 bits of the character are used by \fBwinch\fP.
+These functions do not return an error if the window comprises cells of
+.I curses
+complex characters
+(that is,
+they contain characters with codes wider than eight bits,
+or greater than 255 as an unsigned decimal integer).
+They instead extract only the low-order eight bits of character data
+in the cell.
.SH NOTES
-Note that all of these routines may be macros.
+.BR \%inch ,
+.BR \%mvinch ,
+and
+.B \%mvwinch
+may be implemented as macros.
.SH PORTABILITY
-These functions are described in X/Open Curses, Issue 4.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.SH HISTORY
+.B \%winch
+was implemented in the original 4BSD
+.I curses
+library
+(November 1980).
+It returned only the character code
+(as an integer)
+with the \*(``standout\*(`` attribute bit
+(the only one it supported)
+cleared.
+Because 7-bit ASCII was the only character encoding supported,
+4BSD's
+.B \%winch
+returned a
+.I char
+type.
+.\" Through macros, it directly accessed a `char` structure member.
.PP
-Very old systems (before standardization) provide a different function
-with the same name:
-.bP
-The \fBwinch\fP function was part of the original BSD curses library,
-which stored a 7-bit character combined with the \fIstandout\fP attribute.
-.IP
-In BSD curses, \fBwinch\fP returned only the character (as an integer)
-with the \fIstandout\fP attribute removed.
-.bP
-System V curses added support for several video attributes which
-could be combined with characters in the window.
-.IP
-Reflecting this improvement, the function was altered to return the
-character combined with all video attributes in a \fBchtype\fP value.
+System\ V
+.I curses
+(1983) permitted several rendering attributes to be combined with a
+character in a window.
+Reflecting this improvement,
+.B \%winch
+.\" XXX: possibly returned a `short` in SVr1 through SVr3 --GBR
+returned an
+.I int
+in SVr3.2 (1988)
+and switched to
+.I chtype
+in SVr4 (1989).
.PP
-X/Open Curses does not specify
-the size and layout of attributes, color and character values in
-\fBchtype\fP; it is implementation-dependent.
-This implementation uses 8 bits for character values.
-An application using more bits, e.g., a Unicode value,
-should use the wide-character equivalents to these functions.
+X/Open Curses does not specify the sizes of the character code or
+color pair identifier,
+nor the quantity of rendering attribute bits,
+in
+.IR chtype ";"
+these are implementation-dependent.
+.I \%ncurses
+uses eight bits for the character code.
+An application requiring a wider character type,
+for instance to handle Unicode,
+should use the wide-character counterparts of these functions.
.SH SEE ALSO
\fB\%curs_in_wch\fP(3X) describes comparable functions of the
.I \%ncurses
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_mouse.3x,v 1.98 2024/04/20 19:02:07 tom Exp $
-.TH curs_mouse 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_mouse.3x,v 1.99 2024/05/11 20:39:53 tom Exp $
+.TH curs_mouse 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.I \%xterm
mouse report sequence appears in the string read.
.PP
-Mouse event reports from
+An
+.I \%ncurses
+window must enable \fB\%keypad\fP(3X) to correctly receive mouse event
+reports from
.I \%xterm
-are not detected correctly in a window with keypad application mode
-disabled,
-since they are interpreted as a variety of function key.
+since they are encoded like function keys.
Set the terminal's
.I \%term\%info
capability \fB\%kmous\fP to \*(``\eE[M\*(''
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_outopts.3x,v 1.64 2024/04/20 21:24:19 tom Exp $
-.TH curs_outopts 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_outopts.3x,v 1.65 2024/05/11 20:39:53 tom Exp $
+.TH curs_outopts 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
.SH NAME
\fB\%clearok\fP,
-\fB\%idlok\fP,
\fB\%idcok\fP,
+\fB\%idlok\fP,
\fB\%immedok\fP,
\fB\%leaveok\fP,
+\fB\%scrollok\fP,
\fB\%setscrreg\fP,
-\fB\%wsetscrreg\fP,
-\fB\%scrollok\fP \-
+\fB\%wsetscrreg\fP \-
set \fIcurses\fR output options
.SH SYNOPSIS
.nf
\fB#include <curses.h>
.PP
\fBint clearok(WINDOW *\fIwin\fP, bool \fIbf\fP);
-\fBint idlok(WINDOW *\fIwin\fP, bool \fIbf\fP);
\fBvoid idcok(WINDOW *\fIwin\fP, bool \fIbf\fP);
+\fBint idlok(WINDOW *\fIwin\fP, bool \fIbf\fP);
\fBvoid immedok(WINDOW *\fIwin\fP, bool \fIbf\fP);
\fBint leaveok(WINDOW *\fIwin\fP, bool \fIbf\fP);
\fBint scrollok(WINDOW *\fIwin\fP, bool \fIbf\fP);
the \fIwin\fP argument to \fBclearok\fP is the global variable \fBcurscr\fP,
the next call to \fBwrefresh\fP with any window causes the screen to be cleared
and repainted from scratch.
+.SS idcok
+If \fBidcok\fP is called with \fBFALSE\fP as second argument, \fBcurses\fP
+no longer considers using the hardware insert/delete character feature of
+terminals so equipped.
+Use of character insert/delete is enabled by default.
+Calling \fBidcok\fP with \fBTRUE\fP as second argument re-enables use
+of character insertion and deletion.
.SS idlok
If \fBidlok\fP is called with \fBTRUE\fP as second argument, \fBcurses\fP
considers using the hardware insert/delete line feature of terminals so
when used in applications where it is not really needed.
If insert/delete line
cannot be used, \fBcurses\fP redraws the changed portions of all lines.
-.SS idcok
-If \fBidcok\fP is called with \fBFALSE\fP as second argument, \fBcurses\fP
-no longer considers using the hardware insert/delete character feature of
-terminals so equipped.
-Use of character insert/delete is enabled by default.
-Calling \fBidcok\fP with \fBTRUE\fP as second argument re-enables use
-of character insertion and deletion.
.SS immedok
If \fBimmedok\fP is called with \fBTRUE\fP as second argument,
any change in the window image,
If enabled, (\fIbf\fP is \fBTRUE\fP), the window is scrolled up one line
(Note that to get the physical scrolling effect on the terminal, it is
also necessary to call \fBidlok\fP).
-.SS "setscrreg, wsetscrreg"
+.SS "setscrreg, wsetscrreg"
The \fBsetscrreg\fP and \fBwsetscrreg\fP routines allow the application
programmer to set a software scrolling region in a window.
The \fItop\fP and
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_sp_funcs.3x,v 1.50 2024/04/20 18:56:31 tom Exp $
-.TH curs_sp_funcs 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_sp_funcs.3x,v 1.51 2024/05/11 20:39:53 tom Exp $
+.TH curs_sp_funcs 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_termattrs.3x,v 1.41 2024/04/20 21:20:07 tom Exp $
-.TH curs_termattrs 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_termattrs.3x,v 1.42 2024/05/11 20:39:53 tom Exp $
+.TH curs_termattrs 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.SH NAME
\fB\%baudrate\fP,
\fB\%erasechar\fP,
\fB\%term_attrs\fP,
\fB\%termattrs\fP,
\fB\%termname\fP \-
-\fIcurses\fR environment query routines
+get and set terminal attributes with \fIcurses\fP
.SH SYNOPSIS
.nf
\fB#include <curses.h>
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_util.3x,v 1.101 2024/04/20 21:20:07 tom Exp $
-.TH curs_util 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_util.3x,v 1.102 2024/05/11 20:39:53 tom Exp $
+.TH curs_util 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
\fBvoid filter(void);
.PP
-\fBvoid use_env(bool \fIf\fP);
+\fBvoid use_env(bool \fIbf\fP);
.PP
\fBint putwin(WINDOW *\fIwin\fP, FILE *\fIfilep\fP);
\fBWINDOW *getwin(FILE *\fIfilep\fP);
.PP
\fI/* extensions */
\fBvoid nofilter(void);
-\fBvoid use_tioctl(bool \fIf\fP);
+\fBvoid use_tioctl(bool \fIbf\fP);
.fi
.SH DESCRIPTION
.SS unctrl
use_env use_tioctl Summary
_
TRUE FALSE T{
-This is the default behavior.
\fI\%ncurses\fP uses operating system calls
unless overridden by \fILINES\fP or \fI\%COLUMNS\fP environment
variables;
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: infocmp.1m,v 1.109 2024/03/16 15:35:01 tom Exp $
-.TH @INFOCMP@ 1M 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.\" $Id: infocmp.1m,v 1.110 2024/05/11 20:39:53 tom Exp $
+.TH @INFOCMP@ 1M 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.el .IP \(bu 2
..
.
-.ds d @TERMINFO@
.SH NAME
\fB@INFOCMP@\fP \-
compare or print out \fIterminfo\fP descriptions
using the \fB\-x\fP option of \fB@TIC@\fP.
.SH FILES
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal description database
.SH EXTENSIONS
The
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: infotocap.1m,v 1.41 2024/03/16 15:35:01 tom Exp $
-.TH @INFOTOCAP@ 1M 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.\" $Id: infotocap.1m,v 1.42 2024/05/11 20:39:53 tom Exp $
+.TH @INFOTOCAP@ 1M 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.el .ds '' ""
.\}
.
-.ds d @TERMINFO@
.SH NAME
\fB\%@INFOTOCAP@\fP \-
convert a \fI\%terminfo\fR description into a \fI\%termcap\fR description
with this program and exits with a successful status.
.SH FILES
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal description database
.SH PORTABILITY
None of X/Open Curses,
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: man_db.renames.in,v 1.73 2024/04/13 23:39:11 tom Exp $
+# $Id: man_db.renames.in,v 1.74 2024/05/11 20:30:32 tom Exp $
# Manual-page renamings for the man_db program
#
# Files:
subwin.3x subwin.3ncurses
syncok.3x syncok.3ncurses
terminfo.3x terminfo.3ncurses
+tigetflag.3x tigetflag.3ncurses
tigetstr.3x tigetstr.3ncurses
touchline.3x touchline.3ncurses
touchwin.3x touchwin.3ncurses
vidputs.3x vidputs.3ncurses
wadd_wch.3x wadd_wch.3ncurses
waddch.3x waddch.3ncurses
+waddnstr.3x waddnstr.3ncurses
+waddnwstr.3x waddnwstr.3ncurses
waddstr.3x waddstr.3ncurses
waddwstr.3x waddwstr.3ncurses
wattr_set.3x wattr_set.3ncurses
wrefresh.3x wrefresh.3ncurses
wsetscrreg.3x wsetscrreg.3ncurses
wtimeout.3x wtimeout.3ncurses
+wunctrl.3x wunctrl.3ncurses
#
# Other:
getty.8 getty.8
-# $Id: manhtml.aliases,v 1.35 2024/04/14 00:36:21 tom Exp $
+# $Id: manhtml.aliases,v 1.36 2024/05/11 21:52:17 tom Exp $
#***************************************************************************
# Copyright 2019-2023,2024 Thomas E. Dickey *
# Copyright 2013,2017 Free Software Foundation, Inc. *
start_color(3X) curs_color(3X)
terminfo(3X) curs_terminfo(3X)
tic(1) tic(1M)
+tigetflag(3X) curs_terminfo(3X)
tigetstr(3X) curs_terminfo(3X)
touchline(3X) curs_touch(3X)
touchwin(3X) curs_touch(3X)
vidputs(3X) curs_terminfo(3X)
wadd_wch(3X) curs_add_wch(3X)
waddch(3X) curs_addch(3X)
+waddnstr(3X) curs_addstr(3X)
+waddnwstr(3X) curs_addwstr(3X)
waddstr(3X) curs_addstr(3X)
waddwstr(3X) curs_addwstr(3X)
wattr_set(3X) curs_attr(3X)
wget_wch(3X) curs_get_wch(3X)
wgetch(3X) curs_getch(3X)
wgetstr(3X) curs_getstr(3X)
+win_wch(3X) curs_in_wch(3X)
winch(3X) curs_inch(3X)
wins_wch(3X) curs_ins_wch(3X)
winsch(3X) curs_insch(3X)
wnoutrefresh(3X) curs_refresh(3X)
wrefresh(3X) curs_refresh(3X)
wsetscrreg(3X) curs_outopts(3X)
+wunctrl(3X) curs_util(3X)
-# $Id: manhtml.externs,v 1.25 2024/04/20 19:26:05 tom Exp $
+# $Id: manhtml.externs,v 1.26 2024/05/11 20:35:15 tom Exp $
# Items in this list will not be linked by man2html
#***************************************************************************
# Copyright 2019-2023,2024 Thomas E. Dickey *
profile(5)
putc(3)
putchar(3)
+putwchar(3)
putwc(3)
read(2)
readline(3)
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: ncurses.3x,v 1.214 2024/04/27 17:55:43 tom Exp $
-.TH ncurses 3X 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: ncurses.3x,v 1.215 2024/05/11 20:39:53 tom Exp $
+.TH ncurses 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
. TP
..
.
-.ds d @TERMINFO@
.SH NAME
\fB\%ncurses\fP \-
character-cell terminal interface with optimized output
.I windows
and
.IR pads ;
-the reading of terminal input;
+acquisition of keyboard and mouse events;
control of terminal input and output options;
-environment query routines;
-color manipulation;
+selection of color and rendering attributes
+(such as bold or underline);
the definition and use of
.I "soft label"
keys;
+access to the
.I \%term\%info
-capability access;
+terminal capability database;
a
.I termcap
compatibility interface;
(such as \fI\%termios\fP(3)).
.PP
.I \%ncurses
-implements the standard interface described by
-X/Open Curses Issue\ 7.
+implements the interface described by X/Open Curses Issue\ 7.
In many behavioral details not standardized by X/Open,
.I \%ncurses
emulates the
.PP
Frequent changes to the terminal screen can cause unpleasant flicker or
inefficient use of the communication channel to the device,
-so the library does not generally update it automatically.
+so as a rule the library does not update it automatically.
Therefore,
after using
.I curses
.\" 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
+its output by computing a minimal volume 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:
Special windows called
.I pads
may also be manipulated.
-These are windows that are not constrained to the size of the terminal
-screen and whose contents need not be completely displayed.
+These are not constrained to the size of the terminal screen and their
+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.
+Many terminals support configuration of character cell foreground and
+background colors as well as rendering
+.I attributes ,
+which cause characters to show up in such modes as
+boldfaced,
+underlined,
+or in reverse video.
See \fB\%curs_attr\fP(3X).
.PP
.I curses
predefines constants for a small set of forms-drawing graphics
corresponding to the DEC Alternate Character Set (ACS),
a feature of VT100 and other terminals.
-See \fB\%waddch\fP(3X).
+See \fB\%addch\fP(3X).
.PP
.I curses
is implemented using the operating system's terminal driver;
-keystroke events are received not as scan codes but as byte sequences.
+key events are received not as scan codes but as byte sequences.
Graphical keycaps
(alphanumeric and punctuation keys,
and the space)
appears as a control character or a multibyte
.I "escape sequence."
.I curses
-translates these into unique
+translates the latter into unique
.I "key codes."
See \fB\%getch\fP(3X).
.PP
.I \%ncurses
provides reimplementations of the SVr4 \fBpanel\fP(3X), \fBform\fP(3X),
-and \fBmenu\fP(3X) libraries to ease construction of user interfaces
+and \fBmenu\fP(3X) libraries;
+they permit overlapping windows and ease construction of user interfaces
with
.IR curses .
.SS "Initialization"
\fB\%tset\fP(1) may assist with troubleshooting exotic situations.
.PP
If you change the terminal type,
-export the
+export the shell's
.I TERM
-environment variable in the shell,
+variable,
then run \fB\%tset\fP(1) or the
.RB \*(`` "@TPUT@ init" \*(''
command.
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
-.I \%\*d
+is useful for developing type descriptions or when write permission to
+.I \%@TERMINFO@
is not available.
.PP
See section \*(``ENVIRONMENT\*('' below.
.TS
center;
Li L.
-bf \fIbool\fP (\fBTRUE\fP or \fBFALSE\fP)
+bf a \fIbool\fP (\fBTRUE\fP or \fBFALSE\fP)
c a \fIchar\fP or \fIint\fP
ch a \fIchtype\fP
wc a \fIwchar_t\fP or \fIwint_t\fP
pad pointer to a \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.
+This man page primarily surveys functions that appear in any
+configuration of the library.
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
+It stores a character combined with attributes and a color pair in a
.I \%chtype
datum,
which is often an alias of
.IR int .
+A string of
+.I curses
+characters is similar to a C
+.I char
+string;
+a
+.I chtype
+string ends with an integral
+.BR 0 ","
+the null
+.I curses
+character.
.IP
-Attributes alone
+Attributes and a color pair selection
(with no corresponding character)
can be stored in variables of
.I \%chtype
.I \%attr_t
type.
In either case,
-they are represented as an integral bit mask.
+they are accessed via an integral bit mask.
.IP
Each cell of a
.I \%WINDOW
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
+A string of complex characters ends with a
+.I \%cchar_t
+whose
+.I \%wchar_t
+member is the null wide character.
+Attributes and a color pair selection are stored in separate fields of
+the structure,
+not combined into an integer as in
.IR \%chtype .
.PP
Each cell of a
below.
.SH RETURN VALUE
Unless otherwise noted,
-functions that return an integer return
+functions that return integers return the constants
.B OK
on success and
.B ERR
-on failure.
+on failure;
+see \fB\%curs_variables\fP(3X).
Functions that return pointers return
.B NULL
on failure.
If that value is absent or invalid,
.I \%ncurses
uses 9600.
-This feature allows testers to construct repeatable test cases
+This feature allows developers to construct repeatable test cases
that take into account optimization decisions that depend on baud rate.
.SS "\fICC\fP (command character)"
When set,
When
.I \%ncurses
is configured to use the GPM interface,
-this variable may list one or more terminal names
+this variable may list one or more terminal type names
against which the
.I TERM
variable
An empty value disables the GPM interface,
using
.IR \%ncurses 's
-built-in support for \fIxterm\fP(1) mouse protocols instead.
+built-in support for \fI\%xterm\fP(1) mouse protocols instead.
If the variable is absent,
.I \%ncurses
attempts to open GPM if
limiting the speed of communication to what the hardware could handle.
Unless a hardware terminal is interfaced into a terminal concentrator
(which does flow control),
-an application must manage flow control itself to prevent overruns and
-data loss.
+an application must manage flow itself to prevent overruns and data
+loss.
.PP
A solution that comes at no hardware cost is for an application to pause
after directing a terminal to execute an operation that it performs
.bP
location(s) configured and compiled into
.I \%ncurses
-.RS 3
+.RS
.if !'\*(td'' \{\
.bP
.I \%@TERMINFO_DIRS@
.IR \%ncurses .
.TP 5
.B \-\-disable\-overwrite
-The standard include for \fI\%ncurses\fP is as noted in \fBSYNOPSIS\fP:
+The standard C preprocessor inclusion for the
+.I curses
+library is as follows.
.RS 5
.PP
.RS 4
.EX
-\fB#include <curses.h>\fP
+.\" The dummy character prevents undesired rewriting of the next line on
+.\" installation of the man page.
+\fB#\&include <curses.h>\fP
.EE
.RE
.PP
-This option is used to avoid filename conflicts when \fI\%ncurses\fP
-is not the main implementation of curses of the computer.
-If \fI\%ncurses\fP is installed disabling overwrite,
-it puts its headers in a subdirectory,
-e.g.,
+This option is used to avoid file name conflicts between
+.I \%ncurses
+and an existing
+.I curses
+installation on the system.
+If
+.I \%ncurses
+is installed disabling overwrite,
+it puts its header files in a subdirectory.
+Here is an example.
.PP
.RS 4
.EX
-\fB#include <ncurses/curses.h>\fP
+.\" The dummy character prevents undesired rewriting of the next line on
+.\" installation of the man page.
+\fB#\&include <ncurses/curses.h>\fP
.EE
.RE
.PP
-It also omits a symbolic link which would allow you to use \fB\-lcurses\fP
-to build executables.
+Installation also omits a symbolic link that would cause the compiler's
+.B \-lcurses
+option to link object files with
+.I \%ncurses
+instead of the system
+.I curses
+library.
+.PP
+The directory used by this configuration of
+.I \%ncurses
+is shown in section \*(``SYNOPSIS\*('' above.
.RE
.TP 5
.B \-\-enable\-widec
.I @DATADIR@/tabset
tab stop initialization database
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal capability database
.SH NOTES
X/Open Curses permits most functions it specifies to be made available
those that move the cursor before another operation),
and
.bP
-a few special cases.
+in a few special cases.
.PP
If the standard output file descriptor of an
.I \%ncurses
\fB\%is_scrollok\fP(3X).
.PP
.I \%ncurses
-enables an application to direct application output to a printer
-attached to the terminal device;
+enables an application to direct its output to a printer attached to the
+terminal device;
see \fB\%curs_print\fP(3X).
.PP
.I \%ncurses
.I \%ncurses
is compiled to support them;
section \*(``ALTERNATE CONFIGURATIONS\*('' describes how.
-.bP
+.PP
+.I \%ncurses
+permits modification of \fB\%unctrl\fP(3X)'s behavior;
+see \fB\%use_legacy_coding\fP(3X).
+.PP
Rudimentary support for multi-threaded applications may be available;
see \fBcurs_threads\fP(3X).
-.bP
+.PP
Functions that ease the management of multiple screens can be exposed;
see \fBcurs_sp_funcs\fP(3X).
-.bP
+.PP
To aid applications to debug their memory usage,
-.I ncurses
+.I \%ncurses
optionally offers functions to more aggressively free memory it
dynamically allocates itself;
see \fBcurs_memleaks\fP(3X).
-.bP
+.PP
The library facilitates auditing and troubleshooting of its behavior;
see \fBcurs_trace\fP(3X).
-.bP
-The compiler option
+.PP
+Compiling
+.I \%ncurses
+with the option
.B \%\-DUSE_GETCAP
-causes the library to fall back to reading
+causes it to fall back to reading
.I \%/etc/termcap
if the terminal setup code cannot find a
.I \%term\%info
This is done primarily to guard against programmer error.
The standard interface does not provide a way for the library
to tell an application which of several possible errors occurred.
-Relying on this
-(or some other)
-extension adversely affects the portability of
-.I curses
-applications.
+An application that relies on
+.I \%ncurses
+to check its function parameters for validity limits its portability and
+robustness.
.SS "Padding Differences"
In historical
.I curses
includes
.I \%term.h
and
-.IR \% termios.h .
+.IR \%termios.h .
Again,
.I \%ncurses
and Solaris
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: term.5,v 1.77 2024/04/20 21:24:19 tom Exp $
-.TH term 5 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
+.\" $Id: term.5,v 1.78 2024/05/11 20:39:53 tom Exp $
+.TH term 5 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.el .IP \(bu 2
..
.
-.ds d @TERMINFO@
.SH NAME
term \-
-compiled \fIterminfo\fR terminal description
-.SH SYNOPSIS
-.B term
+compiled \fI\%term\%info\fP terminal description
.SH DESCRIPTION
+\fB\%@TIC@\fP(1) compiles a
+.I \%term\%info
+terminal type description,
+and \fB\%setupterm\fP(3X) reads it.
+A compiled description may be stored in a file or in a database of,
+potentially,
+many such descriptions.
+Further,
+a compiled description may be in one of two formats:
+one similar to that used by System\ V,
+and a newer,
+extensible format employed exclusively by
+.IR \%ncurses .
.SS "Storage Location"
-Compiled terminfo descriptions are placed under the directory \fB\*d\fP.
-Two configurations are supported
-(when building the \fI\%ncurses\fP libraries):
+Compiled
+.I \%term\%info descriptions are placed
+under the directory
+.IR \%@TERMINFO@ .
+One of two configurations is selected
+when building the
+.I \%ncurses
+libraries.
.TP 5
.B directory tree
A two-level scheme is used to avoid a linear search
-of a huge Unix system directory: \fB\*d/c/name\fP where
+of a huge Unix system directory:
+.IR \%@TERMINFO@/ c / name
+where
.I name
-is the name of the terminal, and
+is the name of the terminal,
+and
.I c
is the first character of
.IR name .
Thus,
-.I act4
-can be found in the file \fB\*d/a/act4\fP.
+the compiled description of terminal type \*(``act4\*(''
+is found in the file
+.IR \%@TERMINFO@/a/act4 .
Synonyms for the same terminal are implemented by multiple
links to the same compiled file.
.TP 5
.B hashed database
-Using Berkeley database, two types of records are stored:
-the terminfo data in the same format as stored in a directory tree with
-the terminfo's primary name as a key,
+Using the Berkeley database API,
+two types of records are stored:
+the
+.I \%term\%info
+data in the same format as that stored in a directory tree with
+the terminal's primary type name as a key,
and records containing only aliases pointing to the primary name.
.IP
If built to write hashed databases,
-\fI\%ncurses\fP can still read terminfo databases organized as a
+.I \%ncurses
+can still read
+.I \%term\%info
+databases organized as a
directory tree,
but cannot write entries into the directory tree.
-It can write (or rewrite) entries in the hashed database.
+It can write
+(or rewrite)
+entries in the hashed database.
.IP
-\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.
+.I \%ncurses
+distinguishes the two cases in the
+.I \%TERMINFO
+and
+.I \%TERMINFO_DIRS
+environment variable by assuming a directory tree for entries that
+correspond to an existing directory,
+and a hashed database otherwise.
.SS "Legacy Storage Format"
The format has been chosen so that it will be the same on all hardware.
-An 8 or more bit byte is assumed, but no assumptions about byte ordering
+A byte of at least eight bits' width is assumed,
+but no assumptions about bit ordering
or sign extension are made.
.PP
-The compiled file is created with the \fB@TIC@\fP program,
-and read by the routine \fBsetupterm\fP(3X).
The file is divided into six parts:
.RS 5
-.TP 3
-a) \fIheader\fP,
-.TP 3
-b) \fIterminal names\fP,
-.TP 3
-c) \fIBoolean flags\fP,
-.TP 3
-d) \fInumbers\fP,
-.TP 3
-e) \fIstrings\fP, and
-.TP 3
-f) \fIstring table\fP.
+.IP (a) 4
+.IR header ,
+.IP (b)
+.IR "terminal names" ,
+.IP (c)
+.IR "Boolean flags" ,
+.IP (d)
+.IR numbers ,
+.IP (e)
+.IR strings ,
+and
+.IP (f)
+a
+.IR "string table" .
.RE
.PP
The \fIheader\fP section begins the file.
These integers are
.RS 5
.TP 5
-(1) the \fImagic number\fP (octal 0432);
+(1) the \fImagic number\fP
+(octal 0432);
.TP 5
-(2) the size, in bytes, of the \fIterminal names\fP section;
+(2) the size,
+in bytes,
+of the \fIterminal names\fP section;
.TP 5
(3) the number of bytes in the \fIBoolean flags\fP section;
.TP 5
(4) the number of short integers in the \fInumbers\fP section;
.TP 5
-(5) the number of offsets (short integers) in the \fIstrings\fP section;
+(5) the number of offsets
+(short integers)
+in the \fIstrings\fP section;
.TP 5
-(6) the size, in bytes, of the \fIstring table\fP.
+(6) the size,
+in bytes,
+of the \fIstring table\fP.
.RE
.PP
The capabilities in the
\fIBoolean flags\fP,
-\fInumbers\fP, and
+\fInumbers\fP,
+and
\fIstrings\fP
-sections are in the same order as the file <term.h>.
+sections are in the same order as in the header file
+.IR term.h .
.PP
-Short integers are signed, in the range \-32768 to 32767.
-They are stored as two 8-bit bytes.
-The first byte contains the least significant 8 bits of the value,
-and the second byte contains the most significant 8 bits.
-(Thus, the value represented is 256*second+first.)
-This format corresponds to the hardware of the \s-1VAX\s+1
-and \s-1PDP\s+1-11 (that is, little-endian machines).
-Machines where this does not correspond to the hardware must read the
-integers as two bytes and compute the little-endian value.
+Short integers are signed,
+in the range \-32768 to 32767,
+and stored in little-endian format.
.PP
Numbers in a terminal description,
whether they are entries in the \fInumbers\fP or \fIstrings\fP table,
are positive integers.
Boolean flags are treated as positive one-byte integers.
-In each case, those positive integers represent a terminal capability.
-The terminal compiler @TIC@ uses negative integers to handle the cases where
-a capability is not available:
+In each case,
+those positive integers represent a terminal capability.
+The terminal compiler
+.I \%@TIC@
+uses negative integers to handle the cases where a capability is not
+available:
.bP
If a capability is absent from this terminal,
-@TIC@ stores a \-1 in the corresponding table.
+.I \%@TIC@
+stores a \-1 in the corresponding table.
.IP
-The integer value \-1 is represented by two bytes 0377, 0377.
+The integer value \-1 is represented by two bytes 0377,
+0377.
.br
Absent Boolean values are represented by the byte 0 (false).
.bP
If a capability has been canceled from this terminal,
-@TIC@ stores a \-2 in the corresponding table.
+.I \%@TIC@
+stores a \-2 in the corresponding table.
.IP
-The integer value \-2 is represented by two bytes 0377, 0376.
+The integer value \-2 is represented by two bytes 0377,
+0376.
.br
The Boolean value \-2 is represented by the byte 0376.
.br
Other negative values are illegal.
.PP
The \fIterminal names\fP section comes after the \fIheader\fP.
-It contains the first line of the terminfo description,
+It contains the first line of the
+.I \%term\%info
+description,
listing the various names for the terminal,
separated by the \*(``|\*('' character.
The \fIterminal names\fP section is terminated
with an \s-1ASCII NUL\s+1 character.
.PP
The \fIBoolean flags\fP section has one byte for each flag.
-Boolean capabilities are either 1 or 0 (true or false)
+Boolean capabilities are either 1 or 0
+(true or false)
according to whether the terminal supports the given capability or not.
.PP
Between the \fIBoolean flags\fP section and the \fInumber\fP section,
-a null byte will be inserted, if necessary,
+a null byte will be inserted,
+if necessary,
to ensure that the \fInumber\fP section begins on an even byte
This is a relic of the PDP\-11's word-addressed architecture,
originally designed to avoid traps induced
the \fIstrings\fP section.
Each string is null-terminated.
Special characters in \*^X or \ec notation are stored in their
-interpreted form, not the printing representation.
-Padding information $<nn> and parameter information %x are
-stored intact in uninterpreted form.
+interpreted form,
+not the printing representation.
+Padding information
+.BI $< nn >
+and parameter information
+.B %x
+are stored intact in uninterpreted form.
.SS "Extended Storage Format"
-The previous section describes the conventional terminfo binary format.
-With some minor variations of the offsets (see PORTABILITY),
+The previous section describes the conventional
+.I \%term\%info
+binary format.
+With some minor variations of the offsets
+(see PORTABILITY),
the same binary format is used in all modern Unix systems.
-Each system uses a predefined set of Boolean, number or string capabilities.
+Each system uses a predefined set of Boolean,
+number or string capabilities.
.PP
-The \fI\%ncurses\fP libraries and applications support
-extended terminfo binary format,
-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.
-\fI\%ncurses\fP checks the size,
+The
+.I \%ncurses
+libraries and applications support extended
+.I \%term\%info
+binary format,
+allowing users to define capabilities that are loaded at runtime.
+This extension is made possible by using the fact that the other
+implementations stop reading the
+.I \%term\%info
+data when they reach the end of the size given in the header.
+.I \%ncurses
+checks the size,
and if it exceeds that due to the predefined data,
continues to parse according to its own scheme.
.PP
-First, it reads the extended header (5 short integers):
+First,
+it reads the extended header
+(5 short integers):
.RS 5
.TP 5
(1)
extended capability \fIvalues\fP.
.PP
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.
+.I \%ncurses
+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
-the extended capabilities in order, e.g., Booleans, then numbers and
-finally strings.
+After the end of these values,
+it contains the names for each of
+the extended capabilities in order:
+Boolean,
+numeric,
+and string.
.PP
By storing terminal descriptions in this way,
-\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 \fI\%ncurses\fP uses this extended information.
+.I \%ncurses
+is able to provide a database useful with legacy applications,
+as well as providing data for applications that require more information
+about a terminal type than was anticipated
+by X/Open Curses.
+See \fB\%user_caps\fP(5) for an overview of the way
+.I \%ncurses
+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
-names with members of a \fBTERMTYPE\fP structure.
+Applications that manipulate terminal data can use the definitions
+described in \fB\%term_variables\fP(3X) associating the long capability
+names with members of a
+.I \%TERMTYPE
+structure.
.
.SS "Extended Number Format"
-On occasion, 16-bit signed integers are not large enough.
-With \fI\%ncurses\fP 6.1,
-a new format was introduced by making a few changes
-to the legacy format:
+On occasion,
+16-bit signed integers are not large enough.
+.I \%ncurses
+6.1 introduced a new format
+by making a few changes to the legacy format:
.bP
-a different magic number (octal 01036)
+a different magic number
+(octal 01036)
.bP
changing the type for the \fInumber\fP array from signed 16-bit integers
to signed 32-bit integers.
.PP
-To maintain compatibility, the library presents the same data structures
-to direct users of the \fBTERMTYPE\fP structure as in previous formats.
-However, that cannot provide callers with the extended numbers.
-The library uses a similar but hidden data structure \fBTERMTYPE2\fP
-to provide data for the terminfo functions.
+To maintain compatibility,
+the library presents the same data structures
+to direct users of the
+.I \%TERMTYPE
+structure as in previous formats.
+However,
+that cannot provide callers with the extended numbers.
+The library uses a similar but hidden data structure
+.I \%TERMTYPE2
+to provide data for the
+.I \%term\%info
+functions.
.SH FILES
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal description database
.SH PORTABILITY
.SS setupterm
.B setupterm
must be prepared for both possibilities \-
this is why the numbers and sizes are included.
-Also, new capabilities must always be added at the end of the lists
-of Boolean, number, and string capabilities.
+Also,
+new capabilities must always be added at the end of the lists
+of Boolean,
+number,
+and string capabilities.
.SS "Binary Format"
-X/Open Curses does not specify a format for the terminfo database.
-System V curses used a directory-tree of binary files,
+X/Open Curses does not specify a format for the
+.I \%term\%info
+database.
+System\ V
+.I curses
+used a directory-tree of binary files,
one per terminal description.
.PP
-Despite the consistent use of little-endian for numbers and the otherwise
-self-describing format, it is not wise to count on portability of binary
-terminfo entries between commercial Unix versions.
-The problem is that there
-are at least three versions of terminfo (under HP\-UX, AIX, and OSF/1) which
-diverged from System V terminfo after SVr1, and have added extension
-capabilities to the string table that (in the binary format) collide with
-System V and X/Open Curses extensions.
-See \fBterminfo\fP(5) for detailed
-discussion of terminfo source compatibility issues.
+Despite the consistent use of little-endian numbers and the otherwise
+self-describing format,
+it is not wise to count on portability of binary
+.I \%term\%info
+entries between commercial Unix versions.
+The problem is that there are at least three versions of
+.I \%term\%info
+(under HP\-UX,
+AIX,
+and OSF/1)
+each of which diverged from System\ V
+.I \%term\%info
+after SVr1,
+and added extension capabilities to the string table that
+(in the binary format)
+collide with System\ V and X/Open Curses extensions.
+See \fB\%terminfo\fP(5) for detailed
+discussion of
+.I \%term\%info
+source compatibility issues.
.PP
This implementation is by default compatible with the binary
-terminfo format used by Solaris curses,
+.I \%term\%info
+format used by Solaris
+.IR 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 \fI\%ncurses\fP
+can be matched by building
+.I \%ncurses
with different configuration options.
.SS "Magic Codes"
-The magic number in a binary terminfo file is the first 16-bits (two bytes).
-Besides making it more reliable for the library to check that a file
-is terminfo,
-utilities such as \fBfile\fP(1) also use that to tell what the file-format is.
-System V defined more than one magic number,
-with 0433, 0435 as screen-dumps (see \fBscr_dump\fP(5)).
+The magic number in a binary
+.I \%term\%info
+file is the first 16 bits
+(two bytes).
+Besides making it more reliable for the library to check that a file is
+.IR \%term\%info ,
+utilities such as \fIfile\fP(1) also use that to tell what the
+file-format is.
+System\ V defined more than one magic number,
+with 0433,
+0435 as screen-dumps
+(see \fB\%scr_dump\fP(5)).
This implementation uses 01036 as a continuation of that sequence,
but with a different high-order byte to avoid confusion.
.SS "The \fITERMTYPE\fP Structure"
-Direct access to the \fBTERMTYPE\fP structure is provided for legacy
-applications.
-Portable applications should use the \fBtigetflag\fP and related functions
-described in \fBcurs_terminfo\fP(3X) for reading terminal capabilities.
+Direct access to the
+.I \%TERMTYPE
+structure is provided for legacy applications.
+Portable applications should use \fB\%tigetflag\fP(3X) and related
+functions to read terminal capabilities.
.SS "Mixed-case Terminal Names"
A small number of terminal descriptions use uppercase characters in
their names.
-If the underlying filesystem ignores the difference between
+If the underlying file system ignores the difference between
uppercase and lowercase,
-\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.
+.I \%ncurses
+represents the \*(``first character\*('' of the terminal name used as
+the intermediate level of a directory tree in (two-character)
+hexadecimal form.
.SS Limits
-\fI\%ncurses\fP stores compiled terminal descriptions
-in three related formats,
-described in the sections
+.I \%ncurses
+stores compiled terminal descriptions in three related formats,
+described in the subsections
.bP
-\fBLEGACY STORAGE FORMAT\fP, and
+.BR "Legacy Storage Format" ,
+and
.bP
-\fBEXTENDED STORAGE FORMAT\fP, and
+.BR "Extended Storage Format" ,
+and
.bP
-\fBEXTENDED NUMBER FORMAT\fP.
+.BR "Extended Number Format" .
.PP
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 \fI\%ncurses\fP 5.0 adds data
-to either of these formats.
+the types of numeric capability that they can store
+(for example,
+16- versus 32-bit integers).
+The extended storage format introduced by
+.I \%ncurses
+5.0 adds data to either of these formats.
.PP
Some limitations apply:
.bP
The legacy format could have supported 32768-byte entries,
but was limited to a virtual memory page's 4096 bytes.
.SH EXAMPLES
-As an example, here is a description for the Lear-Siegler
-ADM\-3, a popular though rather stupid early terminal:
+Here is a
+.I \%term\%info
+description of the Lear-Siegler ADM-3,
+a popular though rather stupid early terminal.
.PP
.EX
adm3a|lsi adm3a,
home=\*^\*^, ind=\*^J,
.EE
.PP
-and a hexadecimal dump of the compiled terminal description:
+A hexadecimal dump of its compiled terminal description
+(in legacy format)
+follows.
.PP
.if t .in +4n
.ft \*(CW
.SH AUTHORS
Thomas E. Dickey
.br
-extended terminfo format for \fI\%ncurses\fP 5.0
+extended
+.I \%term\%info
+format for
+.I \%ncurses
+5.0
.br
-hashed database support for \fI\%ncurses\fP 5.6
+hashed database support for
+.I \%ncurses
+5.6
.br
-extended number support for \fI\%ncurses\fP 6.1
+extended number support for
+.I \%ncurses
+6.1
.sp
Eric S. Raymond
.br
-documented legacy terminfo format, e.g., from \fIpcurses\fP.
+documented legacy
+.I \%term\%info
+format
+(that used by
+.IR \%pcurses ).
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_terminfo\fP(3X),
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: term.7,v 1.48 2024/03/16 15:35:01 tom Exp $
-.TH term 7 2024-03-16 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" Miscellaneous
+.\" $Id: term.7,v 1.49 2024/05/11 20:39:53 tom Exp $
+.TH term 7 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" Miscellaneous
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.el .ds '' ""
.\}
.
-.ds d @TERMINFO@
.SH NAME
term \-
conventions for naming terminal types
which you wish to override the system default type for your line.
.PP
Terminal type descriptions are stored as files of capability data underneath
-\*d.
+@TERMINFO@.
To browse a list of all terminal names recognized by the system, do
.sp
@TOE@ | more
@INFOCMP@ \fIentry_name\fP
.sp
where \fIentry_name\fP is the name of the type you wish to examine (and the
-name of its capability file the subdirectory of \*d named for its first
+name of its capability file the subdirectory of @TERMINFO@ named for its first
letter).
This command dumps a capability file in the text format described by
\fBterminfo\fP(5).
on the \fITERM\fP environment variable when no \-T option is specified.
.SH FILES
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal description database
.TP
.I /etc/inittab
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: terminfo.head,v 1.65 2024/04/20 21:14:00 tom Exp $
-.TH terminfo 5 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
+.\" $Id: terminfo.head,v 1.66 2024/05/11 20:39:53 tom Exp $
+.TH terminfo 5 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.el .IP \(bu 2
..
.
-.ds d @TERMINFO@
.SH NAME
\fB\%terminfo\fP \-
terminal capability database
.SH SYNOPSIS
-\*d/*/*
+@TERMINFO@/*/*
.SH DESCRIPTION
.I Terminfo
is a database describing terminals,
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: terminfo.tail,v 1.148 2024/04/20 21:24:19 tom Exp $
+.\" $Id: terminfo.tail,v 1.149 2024/05/11 20:28:54 tom Exp $
.ps +1
.SS "User-Defined Capabilities"
.
.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.
+is interpreted as the system location \fI@TERMINFO@\fP.
.bP
Finally, \fI\%ncurses\fP searches these compiled-in locations:
.RS
.bP
a list of directories (@TERMINFO_DIRS@), and
.bP
-the system terminfo directory, \fI\*d\fP
+the system terminfo directory, \fI@TERMINFO@\fP
.RE
.PP
The \fBTERMINFO\fP variable can contain a terminal description instead
expansion) lengths.
.SH FILES
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal description database directory
.SH EXTENSIONS
Searching for terminal descriptions in
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tic.1m,v 1.110 2024/04/27 17:57:06 tom Exp $
-.TH @TIC@ 1M 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.\" $Id: tic.1m,v 1.111 2024/05/11 20:39:53 tom Exp $
+.TH @TIC@ 1M 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.el .IP \(bu 2
..
.
-.ds d @TERMINFO@
.SH NAME
\fB\%@TIC@\fP \-
compile terminal descriptions for \fIterminfo\fR or \fItermcap\fR
For a directory, this would be the \*(``terminfo\*('' leaf,
versus a "terminfo.db" file.
.PP
-The results are normally placed in the system terminfo database \fB\*d\fP.
+The results are normally placed
+in the system terminfo database \fB@TERMINFO@\fP.
The compiled terminal description can be placed
in a different terminfo database.
There are two ways to achieve this:
or by setting the variable \fI\%TERMINFO\fP
in your shell environment to a valid database location.
.bP
-Secondly, if \fB@TIC@\fP cannot write in \fI\*d\fP
+Secondly, if \fB@TIC@\fP cannot write in \fI@TERMINFO@\fP
or the location specified using your \fI\%TERMINFO\fP variable,
it looks for the directory \fI$HOME/.terminfo\fP
(or hashed database \fI$HOME/.terminfo.db)\fP;
.bP
a compiled-in list of directories (@TERMINFO_DIRS@), and
.bP
-the system terminfo database (\fI\*d\fP).
+the system terminfo database (\fI@TERMINFO@\fP).
.PP
The \fIFetching Compiled Descriptions\fP section in the \fBterminfo\fR(5)
manual goes into further detail.
.PP
When a \fBuse\fP=\fIentry\fP\-\fIname\fP field is discovered in a
terminal entry currently being compiled, \fB@TIC@\fP reads in the binary
-from \fB\*d\fP to complete the entry.
+from \fB@TERMINFO@\fP to complete the entry.
(Entries created from
\fIfile\fP will be used first.
\fB@TIC@\fP duplicates the capabilities in
and a warning message will be printed.
.SH FILES
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal description database
.SH NOTES
There is some evidence that historic \fB@TIC@\fP implementations treated
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: toe.1m,v 1.68 2024/04/20 18:59:26 tom Exp $
-.TH @TOE@ 1M 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.\" $Id: toe.1m,v 1.69 2024/05/11 20:39:53 tom Exp $
+.TH @TOE@ 1M 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.ds d @TERMINFO@
.SH NAME
\fB\%@TOE@\fP \-
list table of entries of \fIterminfo\fR terminal types
with this program and exits with a successful status.
.SH FILES
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal description database
.SH PORTABILITY
\fB\%@TOE@\fP is not provided by other implementations.
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tput.1,v 1.113 2024/04/20 19:58:50 tom Exp $
-.TH @TPUT@ 1 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.\" $Id: tput.1,v 1.114 2024/05/11 20:39:53 tom Exp $
+.TH @TPUT@ 1 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.ds d @TERMINFO@
.SH NAME
\fB\%@TPUT@\fP \-
initialize a terminal, exercise its capabilities, or query \fI\%term\%info\fP database
.I @DATADIR@/tabset
tab stop initialization database
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal description database
.SH PORTABILITY
Over time
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: tset.1,v 1.85 2024/04/27 17:57:47 tom Exp $
-.TH @TSET@ 1 2024-04-27 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
+.\" $Id: tset.1,v 1.86 2024/05/11 20:39:53 tom Exp $
+.TH @TSET@ 1 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "User commands"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.el .IP \(bu 2
..
.
-.ds d @TERMINFO@
.SH NAME
\fB\%@TSET@\fP,
\fB\%@RESET@\fP \-
.I /etc/ttys
system port name to terminal type mapping database (BSD versions only).
.TP
-.I \*d
+.I @TERMINFO@
compiled terminal description database directory
.SH PORTABILITY
Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7
/****************************************************************************
- * Copyright 2018-2020,2022 Thomas E. Dickey *
+ * Copyright 2018-2022,2024 Thomas E. Dickey *
* Copyright 1998-2016,2017 Free Software Foundation, Inc. *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
#include <tic.h>
-MODULE_ID("$Id: lib_newterm.c,v 1.104 2022/07/09 18:58:58 tom Exp $")
+MODULE_ID("$Id: lib_newterm.c,v 1.105 2024/05/11 19:06:59 tom Exp $")
#ifdef USE_TERM_DRIVER
#define NumLabels InfoOf(SP_PARM).numlabels
/* allow user to set maximum escape delay from the environment */
if ((value = _nc_getenv_num("ESCDELAY")) >= 0) {
+ value = Min(value, MAX_DELAY_MSECS);
#if NCURSES_EXT_FUNCS
NCURSES_SP_NAME(set_escdelay) (NCURSES_SP_ARGx value);
#else
****************************************************************************/
/*
- * $Id: curses.priv.h,v 1.688 2024/05/04 18:30:25 tom Exp $
+ * $Id: curses.priv.h,v 1.689 2024/05/11 19:05:45 tom Exp $
*
* curses.priv.h
*
*/
#define MAX_DELAY_MSECS 30000
+/*
+ * Limit screen dimensions read from environment variables.
+ */
+#define MAX_ENV_LINES 512
+#define MAX_ENV_COLUMNS 512
+
/*
* When converting from terminfo to termcap, check for cases where we can trim
* octal escapes down to 2-character form. It is useful for terminfo format
#include <locale.h>
#endif
-MODULE_ID("$Id: lib_setup.c,v 1.240 2024/04/20 17:04:05 tom Exp $")
+MODULE_ID("$Id: lib_setup.c,v 1.241 2024/05/11 19:07:34 tom Exp $")
/****************************************************************************
*
* variable.
*/
if ((value = _nc_getenv_num("LINES")) > 0) {
- *linep = value;
+ *linep = Min(value, MAX_ENV_LINES);
T(("screen size: environment LINES = %d", *linep));
}
if ((value = _nc_getenv_num("COLUMNS")) > 0) {
- *colp = value;
+ *colp = Min(value, MAX_ENV_COLUMNS);
T(("screen size: environment COLUMNS = %d", *colp));
}
/****************************************************************************
- * Copyright 2018-2022,2023 Thomas E. Dickey *
+ * Copyright 2018-2023,2024 Thomas E. Dickey *
* Copyright 2008-2016,2017 Free Software Foundation, Inc. *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
# endif
#endif
-MODULE_ID("$Id: tinfo_driver.c,v 1.74 2023/09/16 10:44:33 tom Exp $")
+MODULE_ID("$Id: tinfo_driver.c,v 1.75 2024/05/11 19:20:44 tom Exp $")
/*
* SCO defines TIOCGSIZE and the corresponding struct. Other systems (SunOS,
* variable.
*/
if ((value = _nc_getenv_num("LINES")) > 0) {
- *linep = value;
+ *linep = Min(value, MAX_ENV_LINES);
T(("screen size: environment LINES = %d", *linep));
}
if ((value = _nc_getenv_num("COLUMNS")) > 0) {
- *colp = value;
+ *colp = Min(value, MAX_ENV_COLUMNS);
T(("screen size: environment COLUMNS = %d", *colp));
}
}
-ncurses6 (6.5+20240504) unstable; urgency=low
+ncurses6 (6.5+20240511) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 04 May 2024 06:21:09 -0400
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 11 May 2024 06:20:08 -0400
ncurses6 (5.9+20131005) unstable; urgency=low
-ncurses6 (6.5+20240504) unstable; urgency=low
+ncurses6 (6.5+20240511) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 04 May 2024 06:21:09 -0400
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 11 May 2024 06:20:08 -0400
ncurses6 (5.9+20131005) unstable; urgency=low
-ncurses6 (6.5+20240504) unstable; urgency=low
+ncurses6 (6.5+20240511) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 04 May 2024 06:21:09 -0400
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 11 May 2024 06:20:08 -0400
ncurses6 (5.9+20120608) unstable; urgency=low
-; $Id: mingw-ncurses.nsi,v 1.646 2024/05/04 10:21:09 tom Exp $\r
+; $Id: mingw-ncurses.nsi,v 1.647 2024/05/11 10:20:08 tom Exp $\r
\r
; TODO add examples\r
; TODO bump ABI to 6\r
!define VERSION_MAJOR "6"\r
!define VERSION_MINOR "5"\r
!define VERSION_YYYY "2024"\r
-!define VERSION_MMDD "0504"\r
+!define VERSION_MMDD "0511"\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.5
-Release: 20240504
+Release: 20240511
License: X11
Group: Development/Libraries
URL: https://invisible-island.net/ncurses/
Summary: shared libraries for terminal handling
Name: ncurses6
Version: 6.5
-Release: 20240504
+Release: 20240511
License: X11
Group: Development/Libraries
URL: https://invisible-island.net/ncurses/
Summary: Curses library with POSIX thread support.
Name: ncursest6
Version: 6.5
-Release: 20240504
+Release: 20240511
License: X11
Group: Development/Libraries
Source: ncurses-%{version}-%{release}.tgz
projects / ncurses.git / commitdiff