-- sale, use or other dealings in this Software without prior written --
-- authorization. --
-------------------------------------------------------------------------------
--- $Id: NEWS,v 1.3605 2020/12/12 20:00:21 tom Exp $
+-- $Id: NEWS,v 1.3608 2020/12/19 23:57:59 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.
+20201219
+ + suppress hyphenation in generated html for manpages, to address
+ regression in upgrade of groff 1.22.2 to 1.22.3.
+ + fix inconsistent sort-order in see-also sections of manpages (report
+ by Chris Bennett).
+
20201212
+ improve manual pages for form field-types.
-5:0:10 6.2 20201212
+5:0:10 6.2 20201219
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: dist.mk,v 1.1389 2020/12/12 11:43:33 tom Exp $
+# $Id: dist.mk,v 1.1391 2020/12/19 23:48:33 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 = 2
-NCURSES_PATCH = 20201212
+NCURSES_PATCH = 20201219
# We don't append the patch to the version, since this only applies to releases
VERSION = $(NCURSES_MAJOR).$(NCURSES_MINOR)
# If that conflicts with the --without-manpage-renames, you can install those
# in a different location using the --with-install-prefix option of the
# configure script.
-MANPROG = tbl | nroff -mandoc -rLL=78n -rLT=78n -Tascii
+MANPROG = tbl | nroff -mandoc -rHY=0 -rLL=78n -rLT=78n -Tascii
manhtml:
@for f in doc/html/man/*.html; do \
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>
- This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201212).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201219).
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
<STRONG>captoinfo</STRONG> looks in each given text <EM>file</EM> for <STRONG>termcap</STRONG> descriptions. For
- each one found, an equivalent <STRONG>terminfo</STRONG> description is written to stan-
- dard output. Termcap <STRONG>tc</STRONG> capabilities are translated directly to ter-
- minfo <STRONG>use</STRONG> capabilities.
+ each one found, an equivalent <STRONG>terminfo</STRONG> description is written to
+ standard output. Termcap <STRONG>tc</STRONG> capabilities are translated directly to
+ terminfo <STRONG>use</STRONG> capabilities.
If no <EM>file</EM> is given, then the environment variable <STRONG>TERMCAP</STRONG> is used for
the filename or entry. If <STRONG>TERMCAP</STRONG> is a full pathname to a file, only
the terminal whose name is specified in the environment variable <STRONG>TERM</STRONG>
is extracted from that file. If the environment variable <STRONG>TERMCAP</STRONG> is
- not set, then the file <STRONG>/usr/local/ncurses/lib/terminfo</STRONG> is read.
+ not set, then the file <STRONG>/usr/share/terminfo</STRONG> is read.
<STRONG>-v</STRONG> print out tracing information on standard error as the program
runs.
</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
- /usr/local/ncurses/lib/terminfo
- Compiled terminal description database.
+ /usr/share/terminfo Compiled terminal description database.
</PRE><H2><a name="h2-TRANSLATIONS-FROM-NONSTANDARD-CAPABILITIES">TRANSLATIONS FROM NONSTANDARD CAPABILITIES</a></H2><PRE>
PD kN XENIX key_npage
PN po XENIX prtr_off
PS pf XENIX prtr_on
-
PU kP XENIX key_ppage
+
RT @8 XENIX kent
UP ku XENIX kcuu1
KA k; Tek key_f10
Gc intersection
GG acs magic cookie count
- If the single-line capabilities occur in an entry, they will automati-
- cally be composed into an <STRONG>acsc</STRONG> string. The double-line capabilities
- and <STRONG>GG</STRONG> are discarded with a warning message.
+ If the single-line capabilities occur in an entry, they will
+ automatically be composed into an <STRONG>acsc</STRONG> string. The double-line
+ capabilities and <STRONG>GG</STRONG> are discarded with a warning message.
IBM's AIX has a terminfo facility descended from SVr1 terminfo but
incompatible with the SVr4 format. The following AIX extensions are
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
- This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201212).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201219).
</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
</PRE><H2><a name="h2-OPTIONS">OPTIONS</a></H2><PRE>
<STRONG>-T</STRONG> <EM>type</EM>
- indicates the <EM>type</EM> of terminal. Normally this option is unneces-
- sary, because the default is taken from the environment variable
- <STRONG>TERM</STRONG>. If <STRONG>-T</STRONG> is specified, then the shell variables <STRONG>LINES</STRONG> and <STRONG>COL-</STRONG>
- <STRONG>UMNS</STRONG> will also be ignored.
+ indicates the <EM>type</EM> of terminal. Normally this option is
+ unnecessary, because the default is taken from the environment
+ variable <STRONG>TERM</STRONG>. If <STRONG>-T</STRONG> is specified, then the shell variables <STRONG>LINES</STRONG>
+ and <STRONG>COLUMNS</STRONG> will also be ignored.
<STRONG>-V</STRONG> reports the version of ncurses which was used in this program, and
exits. The options are as follows:
/usr/bin/tput ${1:+-T$1} clear 2> /dev/null
exit
- In 1989, when Keith Bostic revised the BSD <STRONG>tput</STRONG> command to make it sim-
- ilar to the AT&T <STRONG>tput</STRONG>, he added a shell script for the <STRONG>clear</STRONG> command:
+ In 1989, when Keith Bostic revised the BSD <STRONG>tput</STRONG> command to make it
+ similar to the AT&T <STRONG>tput</STRONG>, he added a shell script for the <STRONG>clear</STRONG>
+ command:
exec tput clear
The remainder of the script in each case is a copyright notice.
- The ncurses <STRONG>clear</STRONG> command began in 1995 by adapting the original BSD
+ The ncurses <STRONG>clear</STRONG> command began in 1995 by adapting the original BSD
<STRONG>clear</STRONG> command (with terminfo, of course).
The <STRONG>E3</STRONG> extension came later:
- <STRONG>o</STRONG> In June 1999, xterm provided an extension to the standard control
- sequence for clearing the screen. Rather than clearing just the
+ <STRONG>o</STRONG> In June 1999, xterm provided an extension to the standard control
+ sequence for clearing the screen. Rather than clearing just the
visible part of the screen using
printf '\033[2J'
printf '\033[<STRONG>3</STRONG>J'
- This is documented in <EM>XTerm</EM> <EM>Control</EM> <EM>Sequences</EM> as a feature origi-
- nating with xterm.
+ This is documented in <EM>XTerm</EM> <EM>Control</EM> <EM>Sequences</EM> as a feature
+ originating with xterm.
<STRONG>o</STRONG> A few other terminal developers adopted the feature, e.g., PuTTY in
2006.
- <STRONG>o</STRONG> In April 2011, a Red Hat developer submitted a patch to the Linux
- kernel, modifying its console driver to do the same thing. The
- Linux change, part of the 3.0 release, did not mention xterm,
+ <STRONG>o</STRONG> In April 2011, a Red Hat developer submitted a patch to the Linux
+ kernel, modifying its console driver to do the same thing. The
+ Linux change, part of the 3.0 release, did not mention xterm,
although it was cited in the Red Hat bug report (#683733) which led
to the change.
- <STRONG>o</STRONG> Again, a few other terminal developers adopted the feature. But
+ <STRONG>o</STRONG> Again, a few other terminal developers adopted the feature. But
the next relevant step was a change to the <STRONG>clear</STRONG> program in 2013 to
incorporate this extension.
- <STRONG>o</STRONG> In 2013, the <STRONG>E3</STRONG> extension was overlooked in <STRONG>tput</STRONG> with the "clear"
- parameter. That was addressed in 2016 by reorganizing <STRONG>tput</STRONG> to
+ <STRONG>o</STRONG> In 2013, the <STRONG>E3</STRONG> extension was overlooked in <STRONG>tput</STRONG> with the "clear"
+ parameter. That was addressed in 2016 by reorganizing <STRONG>tput</STRONG> to
share its logic with <STRONG>clear</STRONG> and <STRONG>tset</STRONG>.
Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7
(POSIX.1-2008) nor X/Open Curses Issue 7 documents tset or reset.
- The latter documents <STRONG>tput</STRONG>, which could be used to replace this utility
- either via a shell script or by an alias (such as a symbolic link) to
+ The latter documents <STRONG>tput</STRONG>, which could be used to replace this utility
+ either via a shell script or by an alias (such as a symbolic link) to
run <STRONG>tput</STRONG> as <STRONG>clear</STRONG>.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
- This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201212).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201219).
</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 com-
- plex character <EM>wch</EM> into the given window at its current position, which
- is then advanced. These functions perform wrapping and special-charac-
- ter processing as follows:
+ 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 cur-
- sor then advances to the next spacing character on the screen.
+ placed at that location with rendition specified by <EM>wch</EM>. The
+ cursor then advances to the next spacing character on the screen.
<STRONG>o</STRONG> If <EM>wch</EM> refers to a non-spacing character, all previous characters
at that location are preserved. The non-spacing characters of <EM>wch</EM>
- are added to the spacing complex character, and the rendition spec-
- ified by <EM>wch</EM> is ignored.
+ are added to the spacing complex character, and the rendition
+ specified by <EM>wch</EM> is ignored.
<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
</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 func-
- tionally equivalent to a call to <STRONG>wadd_wch</STRONG> followed by a call to <STRONG>wre-</STRONG>
- <STRONG>fresh</STRONG>. The knowledge that only a single character is being output is
- taken into consideration and, for non-control characters, a consider-
- able performance gain might be seen by using the *<STRONG>echo</STRONG>* functions
- instead of their equivalents.
+ 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.
</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 cor-
- respond to the same VT100 line-drawing set as <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>.
+ 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>ACS</STRONG> <STRONG>Unicode</STRONG> <STRONG>ASCII</STRONG> <STRONG>acsc</STRONG> <STRONG>Glyph</STRONG>
<STRONG>Name</STRONG> <STRONG>Default</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Name</STRONG>
<STRONG>o</STRONG> NetBSD curses defines the symbols as a <STRONG>wchar_t</STRONG> within a <STRONG>cchar_t</STRONG>.
<STRONG>o</STRONG> HPUX curses equates some of the <EM>ACS</EM><STRONG>_</STRONG> symbols to the analogous <EM>WACS</EM><STRONG>_</STRONG>
- symbols as if the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters. The misde-
- fined symbols are the arrows and other symbols which are not used
- for line-drawing.
+ symbols as if the <EM>ACS</EM><STRONG>_</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 define symbols for thick- or double-lines. SVr4
curses implementations defined their line-drawing symbols in terms of
- intermediate symbols. This implementation extends those symbols, pro-
- viding new definitions which are not in the SVr4 implementations.
+ 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 corre-
- sponding line-drawing characters. X/Open Curses did not address the
- aspect of integrating Unicode with line-drawing characters. Existing
- implementations of Unix curses (AIX, HPUX, Solaris) use only the <STRONG>acsc</STRONG>
- character-mapping to provide this feature. As a result, those imple-
- mentations can only use single-byte line-drawing characters. Ncurses
- 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 ter-
- minal description's <STRONG>acsc</STRONG> mapping as discussed in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> for the
+ 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, HPUX, Solaris) use only
+ the <STRONG>acsc</STRONG> character-mapping to provide this feature. As a result, those
+ implementations can only use single-byte line-drawing characters.
+ Ncurses 5.3 (2002) provided a table of Unicode values to solve these
+ problems. NetBSD curses incorporated that table in 2010.
+
+ In this implementation, the Unicode values are used instead of the
+ terminal description's <STRONG>acsc</STRONG> mapping as discussed in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> for the
environment variable <STRONG>NCURSES_NO_UTF8_ACS</STRONG>. In contrast, for the same
cases, the line-drawing characters described in <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> will use
only the ASCII default values.
terminal, no one can tell what the image represents. Unicode calls
it a snowman.
- Others have suggested these alternatives: S U+00A7 (section mark),
- <STRONG>O</STRONG> U+0398 (theta), <STRONG>O</STRONG> U+03A6 (phi), d U+03B4 (delta), U+2327 (x in a
- rectangle), U+256C (forms double vertical and horizontal), and
- U+2612 (ballot box with x).
+ Others have suggested these alternatives: <section> U+00A7 (section
+ 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><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG>curs_out-</STRONG>
- <STRONG><A HREF="curs_outopts.3x.html">opts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG>putwc(3)</STRONG>
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>,
+ <STRONG><A HREF="curs_outopts.3x.html">
curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG>putwc(3)</STRONG>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_add_wchstr.3x,v 1.14 2020/10/17 23:11:38 tom Exp @
+ * @Id: curs_add_wchstr.3x,v 1.15 2020/12/19 21:39:06 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>.
Comparable functions in the narrow-character (ncurses) library are de-
scribed in <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>.
Video attributes can be combined with a character argument passed to
<STRONG>addch</STRONG> or related functions by logical-ORing them into the character.
(Thus, text, including attributes, can be copied from one place to
- another using <STRONG><A HREF="curs_inch.3x.html">inch(3x)</A></STRONG> and <STRONG>addch</STRONG>.) See the <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> page for val-
- ues of predefined video attribute constants that can be usefully OR'ed
- into characters.
+ another using <STRONG><A HREF="curs_inch.3x.html">inch(3x)</A></STRONG> and <STRONG>addch</STRONG>.) See the <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> page for
+ values of predefined video attribute constants that can be usefully
+ OR'ed into characters.
</PRE><H3><a name="h3-Echoing-characters">Echoing characters</a></H3><PRE>
The <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> routines are equivalent to a call to <STRONG>addch</STRONG>
followed by a call to <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>, or a call to <STRONG>waddch</STRONG> followed by a
call to <STRONG>wrefresh</STRONG>. The knowledge that only a single character is being
- output is used and, for non-control characters, a considerable perfor-
- mance gain may be seen by using these routines instead of their equiva-
- lents.
+ output is used and, for non-control characters, a considerable
+ performance gain may be seen by using these routines instead of their
+ equivalents.
</PRE><H3><a name="h3-Line-Graphics">Line Graphics</a></H3><PRE>
The following variables may be used to add line drawing characters to
the screen with routines of the <STRONG>addch</STRONG> family. The default character
listed below is used if the <STRONG>acsc</STRONG> capability does not define a terminal-
- specific replacement for it, or if the terminal and locale configura-
- tion requires Unicode but the library is unable to use Unicode.
+ specific replacement for it, or if the terminal and locale
+ configuration requires Unicode but the library is unable to use
+ Unicode.
The names are taken from VT100 nomenclature.
</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 (the
- SVr4 manuals specify only "an integer value other than <STRONG>ERR</STRONG>") upon suc-
- cessful completion, unless otherwise noted in the preceding routine
+ SVr4 manuals specify only "an integer value other than <STRONG>ERR</STRONG>") upon
+ successful completion, unless otherwise noted in the preceding routine
descriptions.
- Functions with a "mv" prefix first perform a cursor movement using
+ Functions with a "mv" prefix first perform a cursor movement using
<STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
the window pointer is null.
- If it is not possible to add a complete character, an error is
+ If it is not possible to add a complete character, an error is
returned:
- <STRONG>o</STRONG> If <STRONG>scrollok</STRONG> is not enabled, writing a character at the lower right
- margin succeeds. However, an error is returned because it is not
+ <STRONG>o</STRONG> If <STRONG>scrollok</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
+ <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-PORTABILITY">PORTABILITY</a></H2><PRE>
- All these functions are described in the XSI Curses standard, Issue 4.
- The defaults specified for forms-drawing characters apply in the POSIX
+ All these functions are described in the XSI Curses standard, Issue 4.
+ The defaults specified for forms-drawing characters apply in the POSIX
locale.
</PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE>
X/Open Curses states that the <EM>ACS</EM><STRONG>_</STRONG> definitions are <STRONG>char</STRONG> constants. For
- the wide-character implementation (see <STRONG>curs_add_wch</STRONG>), there are analo-
- gous <EM>WACS</EM><STRONG>_</STRONG> definitions which are <STRONG>cchar_t</STRONG> constants. Some implementa-
- tions are problematic:
+ the wide-character implementation (see <STRONG>curs_add_wch</STRONG>), there are
+ analogous <EM>WACS</EM><STRONG>_</STRONG> definitions which are <STRONG>cchar_t</STRONG> constants. Some
+ implementations are problematic:
- <STRONG>o</STRONG> Some implementations define the ACS symbols to a constant (such as
+ <STRONG>o</STRONG> Some implementations define the ACS symbols to a constant (such as
Solaris), while others define those to entries in an array.
- This implementation uses an array <STRONG>acs_map</STRONG>, as done in SVr4 curses.
+ This implementation uses an array <STRONG>acs_map</STRONG>, as done in SVr4 curses.
NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG>
for compatibility.
<STRONG>o</STRONG> HPUX curses equates some of the <EM>ACS</EM><STRONG>_</STRONG> symbols to the analogous <EM>WACS</EM><STRONG>_</STRONG>
- symbols as if the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters. The misde-
- fined symbols are the arrows and other symbols which are not used
- for line-drawing.
+ symbols as if the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters. The
+ misdefined symbols are the arrows and other symbols which are not
+ used for line-drawing.
- <STRONG>o</STRONG> X/Open Curses (issues 2 through 7) has a typographical error for
- the ACS_LANTERN symbol, equating its "VT100+ Character" to <STRONG>I</STRONG> (capi-
- tal I), while the header files for SVr4 curses and the various
+ <STRONG>o</STRONG> X/Open Curses (issues 2 through 7) has a typographical error for
+ the ACS_LANTERN symbol, equating its "VT100+ Character" to <STRONG>I</STRONG>
+ (capital I), while the header files for SVr4 curses and the various
implementations use <STRONG>i</STRONG> (lowercase).
- None of the terminal descriptions on Unix platforms use uppercase-
- I, except for Solaris (i.e., <EM>screen</EM>'s terminal description, appar-
- ently based on the X/Open documentation around 1995). On the other
- hand, the terminal description <EM>gs6300</EM> (AT&T PC6300 with EMOTS Ter-
- minal Emulator) uses lowercase-i.
-
- Some ACS symbols (ACS_S3, ACS_S7, ACS_LEQUAL, ACS_GEQUAL, ACS_PI,
- ACS_NEQUAL, ACS_STERLING) were not documented in any publicly released
- System V. However, many publicly available terminfos include <STRONG>acsc</STRONG>
- strings in which their key characters (pryz{|}) are embedded, and a
- second-hand list of their character descriptions has come to light.
+ None of the terminal descriptions on Unix platforms use uppercase-
+ I, except for Solaris (i.e., <EM>screen</EM>'s terminal description,
+ apparently based on the X/Open documentation around 1995). On the
+ other hand, the terminal description <EM>gs6300</EM> (AT&T PC6300 with EMOTS
+ Terminal Emulator) uses lowercase-i.
+
+ Some ACS symbols (ACS_S3, ACS_S7, ACS_LEQUAL, ACS_GEQUAL, ACS_PI,
+ ACS_NEQUAL, ACS_STERLING) were not documented in any publicly released
+ System V. However, many publicly available terminfos include <STRONG>acsc</STRONG>
+ strings in which their key characters (pryz{|}) are embedded, and a
+ second-hand list of their character descriptions has come to light.
The ACS-prefixed names for them were invented for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
The <EM>displayed</EM> values for the <EM>ACS</EM><STRONG>_</STRONG> and <EM>WACS</EM><STRONG>_</STRONG> constants depend on
<STRONG>o</STRONG> the library configuration, i.e., <STRONG>ncurses</STRONG> versus <STRONG>ncursesw</STRONG>, where the
- latter is capable of displaying Unicode while the former is not,
+ latter is capable of displaying Unicode while the former is not,
and
<STRONG>o</STRONG> whether the <EM>locale</EM> uses UTF-8 encoding.
- In certain cases, the terminal is unable to display line-drawing char-
- acters except by using UTF-8 (see the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG>
- in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>).
+ In certain cases, the terminal is unable to display line-drawing
+ characters except by using UTF-8 (see the discussion of
+
<STRONG>NCURSES_NO_UTF8_ACS</STRONG> 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 in an SVr3 or SVr4 implementation, but
- in the X/Open Curses model, the details are not given. The important
- distinction between SVr4 curses and X/Open Curses is that the non-char-
- acter information (attributes and color) was separated from the charac-
- ter information which is packed in a <STRONG>chtype</STRONG> to pass to <STRONG>waddch</STRONG>.
-
- In this implementation, <STRONG>chtype</STRONG> holds an eight-bit character. But
- ncurses allows multibyte characters to be passed in a succession of
- calls to <STRONG>waddch</STRONG>. The other implementations do not do this; a call to
- <STRONG>waddch</STRONG> passes exactly one character which may be rendered as one or
+ 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 in an SVr3 or SVr4 implementation, but
+ in the X/Open Curses model, the details are not given. The important
+ distinction between SVr4 curses and X/Open Curses is that the non-
+ character information (attributes and color) was separated from the
+ character information which is packed in a <STRONG>chtype</STRONG> to pass to <STRONG>waddch</STRONG>.
+
+ In this implementation, <STRONG>chtype</STRONG> holds an eight-bit character. But
+ ncurses allows multibyte characters to be passed in a succession of
+ calls to <STRONG>waddch</STRONG>. The other implementations do not do this; a call to
+ <STRONG>waddch</STRONG> passes exactly one character which may be rendered as one or
more cells on the screen depending on whether it is printable.
- Depending on the locale settings, ncurses will inspect the byte passed
- in each call to <STRONG>waddch</STRONG>, and check if the latest call will continue a
+ Depending on the locale settings, ncurses will inspect the byte passed
+ in each call to <STRONG>waddch</STRONG>, and check if the latest call will continue a
multibyte sequence. When a character is <EM>complete</EM>, ncurses displays the
character and moves to the next position in the screen.
- If the calling application interrupts the succession of bytes in a
+ If the calling application interrupts the succession of bytes in a
multibyte character by moving the current location (e.g., using <STRONG>wmove</STRONG>),
ncurses discards the partially built character, starting over again.
- For portability to other implementations, do not rely upon this behav-
- ior:
+ For portability to other implementations, do not rely upon this
+ behavior:
- <STRONG>o</STRONG> check if a character can be represented as a single byte in the
+ <STRONG>o</STRONG> check if a character can be represented as a single byte in the
current locale before attempting call <STRONG>waddch</STRONG>, and
<STRONG>o</STRONG> call <STRONG>wadd_wch</STRONG> for characters which cannot be handled by <STRONG>waddch</STRONG>.
</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
- The <STRONG>TABSIZE</STRONG> variable is implemented in SVr4 and other versions of
- curses, but is not part of X/Open curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> for
+ The <STRONG>TABSIZE</STRONG> variable is implemented in SVr4 and other versions of
+ curses, but is not part of X/Open curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> for
more details).
If <EM>ch</EM> is a carriage return, the cursor is moved to the beginning of the
- current row of the window. This is true of other implementations, but
+ current row of the window. This is true of other implementations, but
is not documented.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG>curs_out-</STRONG>
- <STRONG><A HREF="curs_outopts.3x.html">opts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>.
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>,
+ <STRONG><A HREF="curs_outopts.3x.html">
curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>.
- Comparable functions in the wide-character (ncursesw) library are
+ Comparable functions in the wide-character (ncursesw) library are
described in <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>.
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_addchstr.3x,v 1.21 2020/10/18 00:35:20 tom Exp @
+ * @Id: curs_addchstr.3x,v 1.22 2020/12/19 21:39:20 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>.
Comparable functions in the wide-character (ncursesw) library are de-
scribed in <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>.
have the <STRONG>enter_italics_mode</STRONG> (<STRONG>sitm</STRONG>) and <STRONG>exit_italics_mode</STRONG> (<STRONG>ritm</STRONG>) capa-
bilities. Italics are not mentioned in X/Open Curses. Unlike the oth-
er video attributes, <STRONG>A_ITALIC</STRONG> is unrelated to the <STRONG>set_attributes</STRONG> capa-
- bilities. This implementation makes the assumption that <STRONG>exit_at-</STRONG>
- <STRONG>tribute_mode</STRONG> may also reset italics.
+ bilities. This implementation makes the assumption that <STRONG>exit_attri-</STRONG>
+ <STRONG>bute_mode</STRONG> may also reset italics.
Each of the functions added by XSI Curses has a parameter <EM>opts</EM>, which
X/Open Curses still (after more than twenty years) documents as re-
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
The <STRONG>beep</STRONG> and <STRONG>flash</STRONG> routines are used to alert the terminal user. The
- routine <STRONG>beep</STRONG> sounds an audible alarm on the terminal, if possible; oth-
- erwise it flashes the screen (visible bell). The routine <STRONG>flash</STRONG> flashes
- the screen, and if that is not possible, sounds the alert. If neither
- alert is possible, nothing happens. Nearly all terminals have an audi-
- ble alert (bell or beep), but only some can flash the screen.
+ routine <STRONG>beep</STRONG> sounds an audible alarm on the terminal, if possible;
+ otherwise it flashes the screen (visible bell). The routine <STRONG>flash</STRONG>
+ flashes the screen, and if that is not possible, sounds the alert. If
+ neither alert is possible, nothing happens. Nearly all terminals have
+ an audible alert (bell or beep), but only some can flash the screen.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
- SVr4's beep and flash routines always returned <STRONG>OK</STRONG>, so it was not possi-
- ble to tell when the beep or flash failed.
+ SVr4's beep and flash routines always returned <STRONG>OK</STRONG>, so it was not
+ possible to tell when the beep or flash failed.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
</PRE><H3><a name="h3-bkgdset">bkgdset</a></H3><PRE>
The <STRONG>bkgdset</STRONG> and <STRONG>wbkgdset</STRONG> routines manipulate the background of the
- named window. The window background is a <STRONG>chtype</STRONG> consisting of any com-
- bination of attributes (i.e., rendition) and a character. The
+ named window. The window background is a <STRONG>chtype</STRONG> consisting of any
+ combination of attributes (i.e., rendition) and a character. The
attribute part of the background is combined (OR'ed) with all non-blank
characters that are written into the window with <STRONG>waddch</STRONG>. Both the
character and attribute parts of the background are combined with the
This implementation, like SVr4 curses, does not store the background
and window attribute contributions to each cell separately. It updates
- the rendition by comparing the character, non-color attributes and col-
- ors contained in the background. For each cell in the window, whether
- or not it is blank:
+ the rendition by comparing the character, non-color attributes and
+ colors contained in the background. For each cell in the window,
+ whether or not it is blank:
<STRONG>o</STRONG> The library first compares the <EM>character</EM>, and if it matches the
current character part of the background, it replaces that with the
<STRONG>o</STRONG> The library then checks if the cell uses color, i.e., its color
pair value is nonzero. If not, it simply replaces the attributes
- and color pair in the cell with those from the new background char-
- acter.
+ and color pair in the cell with those from the new background
+ character.
<STRONG>o</STRONG> If the cell uses color, and that matches the color in the current
background, the library removes attributes which may have come from
the current background and adds attributes from the new background.
- It finishes by setting the cell to use the color from the new back-
- ground.
+ It finishes by setting the cell to use the color from the new
+ background.
<STRONG>o</STRONG> If the cell uses color, and that does not match the color in the
current background, the library updates only the non-color
- attributes, first removing those which may have come from the cur-
- rent background, and then adding attributes from the new back-
- ground.
+ attributes, first removing those which may have come from the
+ current background, and then adding attributes from the new
+ background.
If the background's character value is zero, a space is assumed.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
These functions are described in the XSI Curses standard, Issue 4. It
- specifies that <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> return <STRONG>ERR</STRONG> on failure, but gives no fail-
- ure conditions.
+ specifies that <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> return <STRONG>ERR</STRONG> on failure, but gives no
+ failure conditions.
The routines <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> return the integer <STRONG>OK</STRONG>, unless the library
has not been initialized.
The attribute part of the background is combined (OR'ed) with all non-
blank characters that are written into the window with <STRONG>waddch</STRONG>. Both
the character and attribute parts of the background are combined with
- the blank characters. The background becomes a property of the charac-
- ter and moves with the character through any scrolling and
+ the blank characters. The background becomes a property of the
+ character and moves with the character through any scrolling and
insert/delete line/character operations.
To the extent possible on a particular terminal, the attribute part of
</PRE><H3><a name="h3-bkgrnd">bkgrnd</a></H3><PRE>
The <STRONG>bkgrnd</STRONG> and <STRONG>wbkgrnd</STRONG> functions set the background property of the
- current or specified window and then apply this setting to every char-
- acter position in that window:
+ current or specified window and then apply this setting to every
+ character position in that window:
<STRONG>o</STRONG> The rendition of every character on the screen is changed to the
new background rendition.
<STRONG>o</STRONG> If the parameter passed to <STRONG>waddch</STRONG> is <EM>not</EM> <EM>blank</EM>, or it does not use
the special color pair 0, <STRONG>curses</STRONG> prefers the color pair from the
- parameter, if it is nonzero. Otherwise, it tries the window at-
- tribute next, and finally the background character.
+ parameter, if it is nonzero. Otherwise, it tries the window attri-
+ bute next, and finally the background character.
Some <STRONG>curses</STRONG> functions such as <STRONG>wprintw</STRONG> call <STRONG>waddch</STRONG>. Those do not com-
bine its parameter with a color pair. Consequently those calls use on-
These routines delete the character under the cursor; all characters to
the right of the cursor on the same line are moved to the left one
position and the last character on the line is filled with a blank.
- The cursor position does not change (after moving to <EM>y</EM>, <EM>x</EM>, if speci-
- fied). (This does not imply use of the hardware delete character fea-
- ture.)
+ The cursor position does not change (after moving to <EM>y</EM>, <EM>x</EM>, if
+ specified). (This does not imply use of the hardware delete character
+ feature.)
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- All routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4 speci-
- fies only "an integer value other than <STRONG>ERR</STRONG>") upon successful comple-
- tion.
+ All routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
+ specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ completion.
Functions with a "mv" prefix first perform a cursor movement using
<STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
the cursor), and move the remaining lines up. The bottom <EM>n</EM> lines are
cleared. The current cursor position remains the same.
- The <STRONG>insertln</STRONG> and <STRONG>winsertln</STRONG> routines insert a blank line above the cur-
- rent line and the bottom line is lost.
+ The <STRONG>insertln</STRONG> and <STRONG>winsertln</STRONG> routines insert a blank line above the
+ current line and the bottom line is lost.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- All routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4 speci-
- fies only "an integer value other than <STRONG>ERR</STRONG>") upon successful comple-
- tion.
+ All routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
+ specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ completion.
X/Open defines no error conditions. In this implementation, if the
window parameter is null, an error is returned.
These routines do not require a hardware line delete or insert feature
in the terminal. In fact, they will not use hardware line
- delete/insert unless <STRONG>idlok(...,</STRONG> <STRONG>TRUE)</STRONG> has been set on the current win-
- dow.
+ delete/insert unless <STRONG>idlok(...,</STRONG> <STRONG>TRUE)</STRONG> has been set on the current
+ window.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
</PRE><H3><a name="h3-use_extended_names">use_extended_names</a></H3><PRE>
- The <STRONG>use_extended_names</STRONG> function controls whether the calling applica-
- tion is able to use user-defined or nonstandard names which may be com-
- piled into the terminfo description, i.e., via the terminfo or termcap
- interfaces. Normally these names are available for use, since the
- essential decision is made by using the <STRONG>-x</STRONG> option of <STRONG>tic</STRONG> to compile
+ The <STRONG>use_extended_names</STRONG> function controls whether the calling
+ application is able to use user-defined or nonstandard names which may
+ be compiled into the terminfo description, i.e., via the terminfo or
+ termcap interfaces. Normally these names are available for use, since
+ the essential decision is made by using the <STRONG>-x</STRONG> option of <STRONG>tic</STRONG> to compile
extended terminal definitions. However you can disable this feature to
ensure compatibility with other implementations of curses.
</PRE><H3><a name="h3-getcchar">getcchar</a></H3><PRE>
The <STRONG>getcchar</STRONG> function gets a wide-character string and rendition from a
- <STRONG>cchar_t</STRONG> argument. When <EM>wch</EM> is not a null pointer, the <STRONG>getcchar</STRONG> func-
- tion does the following:
+ <STRONG>cchar_t</STRONG> argument. When <EM>wch</EM> is not a null pointer, the <STRONG>getcchar</STRONG>
+ function does the following:
<STRONG>o</STRONG> Extracts information from a <STRONG>cchar_t</STRONG> value <EM>wcval</EM>
<STRONG>o</STRONG> For functions which retrieve the color, e.g., <STRONG>getcchar</STRONG>, if <EM>opts</EM> is
set it is treated as a pointer to <STRONG>int</STRONG>, and used to retrieve the
- color pair as an <STRONG>int</STRONG> value, in addition retrieving it via the stan-
- dard pointer to <STRONG>short</STRONG> parameter.
+ color pair as an <STRONG>int</STRONG> value, in addition retrieving it via the
+ standard pointer to <STRONG>short</STRONG> parameter.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- When <EM>wch</EM> is a null pointer, <STRONG>getcchar</STRONG> returns the number of wide charac-
- ters referenced by <EM>wcval</EM>, including one for a trailing null.
+ When <EM>wch</EM> is a null pointer, <STRONG>getcchar</STRONG> returns the number of wide
+ characters referenced by <EM>wcval</EM>, including one for a trailing null.
When <EM>wch</EM> is not a null pointer, <STRONG>getcchar</STRONG> returns <STRONG>OK</STRONG> upon successful
completion, and <STRONG>ERR</STRONG> otherwise.
of spacing and non-spacing characters (<STRONG>CCHARW_MAX</STRONG>). That was probably
due to a misreading of the AIX 4 header files, because the X/Open
Curses document was not generally available at that time. Later (in
- 2002), this detail was overlooked when beginning to implement the func-
- tions using the structure.
+ 2002), this detail was overlooked when beginning to implement the
+ functions using the structure.
In practice, even four non-spacing characters may seem enough. X/Open
Curses documents possible uses for non-spacing characters, including
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_getch.3x,v 1.56 2020/10/17 23:18:32 tom Exp @
+ * @Id: curs_getch.3x,v 1.57 2020/12/19 21:38:20 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
</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_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(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>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>.
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>, <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, <STRONG>curs_out-</STRONG>
+ <STRONG><A HREF="curs_
outopts.3x.html">opts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>.
Comparable functions in the wide-character (ncursesw) library are de-
scribed in <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>.
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 coordi-
- nates 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>.
+ 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>.
- Like <STRONG>getyx</STRONG>, the <STRONG>getbegyx</STRONG> and <STRONG>getmaxyx</STRONG> macros store the current begin-
- ning coordinates and size of the specified window.
+ Like <STRONG>getyx</STRONG>, the <STRONG>getbegyx</STRONG> and <STRONG>getmaxyx</STRONG> macros store the current
+ beginning coordinates and size of the specified window.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
<STRONG>getcury</STRONG>, <STRONG>getmaxx</STRONG>, <STRONG>getmaxy</STRONG>, <STRONG>getparx</STRONG> and <STRONG>getpary</STRONG> for compatibility with
older versions of curses.
- Although X/Open Curses does not address this, many implementations pro-
- vide members of the WINDOW structure containing values corresponding to
- these macros. For best portability, do not rely on using the data in
- WINDOW, since some implementations make WINDOW opaque (do not allow
+ Although X/Open Curses does not address this, many implementations
+ provide members of the WINDOW structure containing values corresponding
+ to these macros. For best portability, do not rely on using the data
+ in WINDOW, since some implementations make WINDOW opaque (do not allow
direct use of 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 WINDOW._maxx and WINDOW._maxy values in ncurses have (at
- least since release 1.8.1) differed by one from some other implementa-
- tions. The difference is hidden by means of the macro <STRONG>getmaxyx</STRONG>.
+ 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>.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
No errors are defined in the XSI Curses standard. This implementation
- checks for null pointers, returns <STRONG>ERR</STRONG> in that case. Also, the <EM>mv</EM> rou-
- tines check for error moving the cursor, returning <STRONG>ERR</STRONG> in that case.
+ checks for null pointers, returns <STRONG>ERR</STRONG> in that case. Also, the <EM>mv</EM>
+ routines check for error moving the cursor, returning <STRONG>ERR</STRONG> in that case.
Otherwise they return <STRONG>OK</STRONG>.
Functions with a "mv" prefix first perform a cursor movement using
</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 posi-
- tion, their values are OR'ed into the value returned. Constants
+ 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.
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 equiva-
- lents to these functions.
+ more bits, e.g., a Unicode value, should use the wide-character
+ equivalents to these functions.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
gives an overview of the WINDOW and <STRONG>chtype</STRONG> data types.
<STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
- goes into more detail, pointing out portability problems and con-
- straints on the use of <STRONG>chtype</STRONG> for returning window information.
+ goes into more detail, pointing out portability problems and
+ constraints on the use of <STRONG>chtype</STRONG> for returning window information.
<STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG>
describes comparable functions for the wide-character (ncursesw)
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
All routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG>
(SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
- completion, unless otherwise noted in the preceding routine descrip-
- tions.
+ completion, unless otherwise noted in the preceding routine
+ descriptions.
Functions with a "mv" prefix first perform a cursor movement using
<STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- These routines do not necessarily imply use of a hardware insert char-
- acter feature.
+ These routines do not necessarily imply use of a hardware insert
+ character feature.
Note that <STRONG>insch</STRONG>, <STRONG>mvinsch</STRONG>, and <STRONG>mvwinsch</STRONG> may be macros.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
All routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG>
(SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
- completion, unless otherwise noted in the preceding routine descrip-
- tions.
+ completion, unless otherwise noted in the preceding routine
+ descriptions.
X/Open defines no error conditions. In this implementation, if the
window parameter is null or the str parameter is null, an error is
These functions are described in the XSI Curses standard, Issue 4,
which adds const qualifiers to the arguments.
- The Single Unix Specification, Version 2 states that <STRONG>insnstr</STRONG> and <STRONG>win-</STRONG>
- <STRONG>snstr</STRONG> perform wrapping. This is probably an error, since it makes this
- group of functions inconsistent. Also, no implementation of curses
- documents this inconsistency.
+ The Single Unix Specification, Version 2 states that <STRONG>insnstr</STRONG> and
+ <STRONG>winsnstr</STRONG> perform wrapping. This is probably an error, since it makes
+ this group of functions inconsistent. Also, no implementation of
+ curses documents this inconsistency.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
These routines return a string of characters in <EM>str</EM>, extracted starting
at the current cursor position in the named window. Attributes are
stripped from the characters. The four functions with <EM>n</EM> as the last
- argument return a leading substring at most <EM>n</EM> characters long (exclu-
- sive of the trailing NUL).
+ argument return a leading substring at most <EM>n</EM> characters long
+ (exclusive of the trailing NUL).
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- All of the functions return <STRONG>ERR</STRONG> upon failure, or the number of charac-
- ters actually read into the string.
+ All of the functions return <STRONG>ERR</STRONG> upon failure, or the number of
+ characters actually read into the string.
X/Open Curses defines no error conditions. In this implementation:
These routines return a string of <STRONG>wchar_t</STRONG> wide characters in <EM>wstr</EM>,
extracted starting at the current cursor position in the named window.
- The four functions with <EM>n</EM> as the last argument return a leading sub-
- string at most <EM>n</EM> characters long (exclusive of the trailing NUL).
+ The four functions with <EM>n</EM> as the last argument return a leading
+ substring at most <EM>n</EM> characters long (exclusive of the trailing NUL).
Transfer stops at the end of the current line, or when <EM>n</EM> characters
have been stored at the location referenced by <EM>wstr</EM>.
- If the size <EM>n</EM> is not large enough to store a complete complex charac-
- ter, an error is generated.
+ If the size <EM>n</EM> is not large enough to store a complete complex
+ character, an error is generated.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
All routines except <STRONG>winnwstr</STRONG> may be macros.
- Each cell in the window holds a complex character (i.e., base- and com-
- bining-characters) together with attributes and color. These functions
- store only the wide characters, ignoring attributes and color. Use
- <STRONG>in_wchstr</STRONG> to return the complex characters from a window.
+ Each cell in the window holds a complex character (i.e., base- and
+ combining-characters) together with attributes and color. These
+ functions store only the wide characters, ignoring attributes and
+ color. Use <STRONG>in_wchstr</STRONG> to return the complex characters from a window.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- These legacy functions are simpler to use than the X/Open Curses func-
- tions:
+ These legacy functions are simpler to use than the X/Open Curses
+ functions:
<STRONG>o</STRONG> The <STRONG>getattrs</STRONG> function returns the same attribute data as <STRONG>wattr_get</STRONG>.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Except as noted, these functions return an integer, or <STRONG>ERR</STRONG> if the win-
- dow parameter is null.
+ Except as noted, these functions return an integer, or <STRONG>ERR</STRONG> if the
+ window parameter is null.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These functions were supported on Version 7, BSD or System V implemen-
- tations. None of those implementations checked the window parameter.
+ These functions were supported on Version 7, BSD or System V
+ implementations. None of those implementations checked the window
+ parameter.
- The <STRONG>getattrs</STRONG> function and macro are defined to return a (signed) inte-
- ger for compatibility with those implementations although an unsigned
- type would have been more appropriate.
+ The <STRONG>getattrs</STRONG> function and macro are defined to return a (signed)
+ integer for compatibility with those implementations although an
+ unsigned type would have been more appropriate.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
printer or to know how much buffering it has. Your application is
responsible for keeping the rate of writes to the printer below its
continuous throughput rate (typically about half of its nominal cps
- rating). Dot-matrix printers and 6-page-per-minute lasers can typi-
- cally handle 80cps, so a good conservative rule of thumb is to sleep
- for a second after shipping each 80-character line.
+ rating). Dot-matrix printers and 6-page-per-minute lasers can
+ typically handle 80cps, so a good conservative rule of thumb is to
+ sleep for a second after shipping each 80-character line.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
The <STRONG>mcprint</STRONG> function returns <STRONG>ERR</STRONG> if the write operation aborted for
- some reason. In this case, <STRONG>errno</STRONG> will contain either an error associ-
- ated with <STRONG>write(2)</STRONG> or one of the following:
+ some reason. In this case, <STRONG>errno</STRONG> will contain either an error
+ associated with <STRONG>write(2)</STRONG> or one of the following:
ENODEV
Capabilities for printer redirection do not exist.
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
While <STRONG>scanw</STRONG> was implemented in 4BSD, none of the BSD releases used it
until 4.4BSD (in a game). That early version of curses was before the
- ANSI C standard. It did not use <varargs.h>, though that was avail-
- able. In 1991 (a couple of years after SVr4 was generally available,
- and after the C standard was published), other developers updated the
- library, using <stdarg.h> internally in 4.4BSD curses. Even with this
- improvement, BSD curses did not use function prototypes (or even
- declare functions) in the <curses.h> header until 1992.
+ ANSI C standard. It did not use <varargs.h>, though that was
+ available. In 1991 (a couple of years after SVr4 was generally
+ available, and after the C standard was published), other developers
+ updated the library, using <stdarg.h> internally in 4.4BSD curses.
+ Even with this improvement, BSD curses did not use function prototypes
+ (or even declare functions) in the <curses.h> header until 1992.
SVr2 documented <STRONG>scanw</STRONG>, <STRONG>wscanw</STRONG> tersely as "scanf through <EM>stdscr</EM>" and
tersely as "scanf through <EM>win</EM>", respectively.
is probably an editing error which was introduced in XSI, rather
than being done intentionally.
- <STRONG>o</STRONG> This implementation returns the number of items scanned, for com-
- patibility with SVr4 curses. As of 2018, NetBSD curses also
+ <STRONG>o</STRONG> This implementation returns the number of items scanned, for
+ compatibility with SVr4 curses. As of 2018, NetBSD curses also
returns the number of items scanned. Both ncurses and NetBSD
curses call <STRONG>vsscanf</STRONG> to scan the string, which returns <STRONG>EOF</STRONG> on error.
<STRONG>o</STRONG> Portable applications should only test if the return value is <STRONG>ERR</STRONG>,
since the <STRONG>OK</STRONG> value (zero) is likely to be misleading.
- One possible way to get useful results would be to use a "%n" con-
- version at the end of the format string to ensure that something
+ One possible way to get useful results would be to use a "%n"
+ conversion at the end of the format string to ensure that something
was processed.
</PRE><H3><a name="h3-erasechar_-erasewchar">erasechar, erasewchar</a></H3><PRE>
The <STRONG>erasechar</STRONG> routine returns the user's current erase character.
- The <STRONG>erasewchar</STRONG> routine stores the current erase character in the loca-
- tion referenced by <EM>ch</EM>. If no erase character has been defined, the
+ The <STRONG>erasewchar</STRONG> routine stores the current erase character in the
+ location referenced by <EM>ch</EM>. If no erase character has been defined, the
routine fails and the location referenced by <EM>ch</EM> is not changed.
</PRE><H3><a name="h3-termattrs_-term_attrs">termattrs, term_attrs</a></H3><PRE>
- If a given terminal does not support a video attribute that an applica-
- tion program is trying to use, <STRONG>curses</STRONG> may substitute a different video
- attribute for it. The <STRONG>termattrs</STRONG> and <STRONG>term_attrs</STRONG> functions return a log-
- ical <STRONG>OR</STRONG> of all video attributes supported by the terminal using <EM>A</EM><STRONG>_</STRONG> and
- <EM>WA</EM><STRONG>_</STRONG> constants respectively. This information is useful when a <STRONG>curses</STRONG>
- program needs complete control over the appearance of the screen.
+ If a given terminal does not support a video attribute that an
+ application program is trying to use, <STRONG>curses</STRONG> may substitute a different
+ video attribute for it. The <STRONG>termattrs</STRONG> and <STRONG>term_attrs</STRONG> functions return
+ a logical <STRONG>OR</STRONG> of all video attributes supported by the terminal using <EM>A</EM><STRONG>_</STRONG>
+ and <EM>WA</EM><STRONG>_</STRONG> constants respectively. This information is useful when a
+ <STRONG>curses</STRONG> program needs complete control over the appearance of the
+ screen.
</PRE><H3><a name="h3-termname">termname</a></H3><PRE>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
<STRONG>longname</STRONG> and <STRONG>termname</STRONG> return <STRONG>NULL</STRONG> on error.
- Routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
- only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful com-
- pletion.
+ Routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
+ only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ completion.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
The XSI Curses standard, Issue 4 describes these functions. It changes
- the return type of <STRONG>termattrs</STRONG> to the new type <STRONG>attr_t</STRONG>. Most versions of
+ the return type of <STRONG>termattrs</STRONG> to the new type <STRONG>attr_t</STRONG>. Most versions of
curses truncate the result returned by <STRONG>termname</STRONG> to 14 characters.
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_termcap.3x,v 1.46 2020/11/07 23:39:47 tom Exp @
+ * @Id: curs_termcap.3x,v 1.47 2020/12/19 21:47:36 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
</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="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>.
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
https://invisible-island.net/ncurses/tctest.html
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_util.3x,v 1.59 2020/10/24 09:15:57 tom Exp @
+ * @Id: curs_util.3x,v 1.60 2020/12/19 22:44:46 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(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>curs_vari-</STRONG>
- <STRONG><A HREF="curs_variables.3x.html">ables(3x)</A></STRONG>, <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(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>legacy_cod-</STRONG>
+ <STRONG><A HREF="legacy_coding.3x.html">ing(3x)</A></STRONG>.
* authorization. *
****************************************************************************
* Author: Thomas E. Dickey 1997,1999,2000,2005
- * @Id: default_colors.3x,v 1.30 2020/10/24 09:52:16 tom Exp @
+ * @Id: default_colors.3x,v 1.31 2020/12/19 21:38:37 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
- <STRONG>use_default_colors</STRONG>, <STRONG>assume_default_colors</STRONG> - use terminal's default col-
- ors
+ <STRONG>use_default_colors</STRONG>, <STRONG>assume_default_colors</STRONG> - use terminal's default
+ colors
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- The <STRONG>use_default_colors</STRONG> and <STRONG>assume_default_colors</STRONG> functions are exten-
- sions to the curses library. They are used with terminals that support
- ISO 6429 color, or equivalent. These terminals allow the application
- to reset color to an unspecified default value (e.g., with SGR 39 or
- SGR 49).
+ The <STRONG>use_default_colors</STRONG> and <STRONG>assume_default_colors</STRONG> functions are
+ extensions to the curses library. They are used with terminals that
+ support ISO 6429 color, or equivalent. These terminals allow the
+ application to reset color to an unspecified default value (e.g., with
+ SGR 39 or SGR 49).
Applications that paint a colored background over the whole screen do
not take advantage of SGR 39 and SGR 49. Some applications are
text. For example, there are several implementations of the <STRONG>ls</STRONG> program
which use colors to denote different file types or permissions. These
"color ls" programs do not necessarily modify the background color,
- typically using only the <STRONG>setaf</STRONG> terminfo capability to set the fore-
- ground color. Full-screen applications that use default colors can
+ typically using only the <STRONG>setaf</STRONG> terminfo capability to set the
+ foreground color. Full-screen applications that use default colors can
achieve similar visual effects.
The first function, <STRONG>use_default_colors</STRONG> tells the curses library to
default background and init_pair(x,-1,COLOR_BLUE) will initialize pair
x as default foreground on blue.
- The other, <STRONG>assume_default_colors</STRONG> is a refinement which tells which col-
- ors to paint for color pair 0. This function recognizes a special
+ The other, <STRONG>assume_default_colors</STRONG> is a refinement which tells which
+ colors to paint for color pair 0. This function recognizes a special
color number -1, which denotes the default terminal color.
The following are equivalent:
<EM>assume</EM><STRONG>_</STRONG><EM>default</EM><STRONG>_</STRONG><EM>colors(-1,-1);</EM>
These are ncurses extensions. For other curses implementations, color
- number -1 does not mean anything, just as for ncurses before a success-
- ful call of <STRONG>use_default_colors</STRONG> or <STRONG>assume_default_colors</STRONG>.
+ number -1 does not mean anything, just as for ncurses before a
+ successful call of <STRONG>use_default_colors</STRONG> or <STRONG>assume_default_colors</STRONG>.
Other curses implementations do not allow an application to modify
color pair 0. They assume that the background is COLOR_BLACK, but do
ls" programs. Attempting to manage the background color of the screen
for this application would give unsatisfactory results for a variety of
reasons. This extension was devised after noting that color xterm (and
- similar programs) provides a background color which does not necessar-
- ily correspond to any of the ANSI colors. While a special terminfo
- entry could be constructed using nine colors, there was no mechanism
- provided within curses to account for the related <STRONG>orig_pair</STRONG> and
- <STRONG>back_color_erase</STRONG> capabilities.
+ similar programs) provides a background color which does not
+ necessarily correspond to any of the ANSI colors. While a special
+ terminfo entry could be constructed using nine colors, there was no
+ mechanism provided within curses to account for the related <STRONG>orig_pair</STRONG>
+ and <STRONG>back_color_erase</STRONG> capabilities.
- The <STRONG>assume_default_colors</STRONG> function was added to solve a different prob-
- lem: support for applications which would use environment variables and
- other configuration to bypass curses' notion of the terminal's default
- colors, setting specific values.
+ The <STRONG>assume_default_colors</STRONG> function was added to solve a different
+ problem: support for applications which would use environment variables
+ and other configuration to bypass curses' notion of the terminal's
+ default colors, setting specific values.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>, <STRONG>ded(1)</STRONG>.
+ <STRONG>ded(1)</STRONG>, <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>.
</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- The keycode must be greater than zero, and the string non-null, other-
- wise <STRONG>ERR</STRONG> is returned. <STRONG>ERR</STRONG> may also be returned if there is insuffi-
- cient memory to allocate the data to store the definition. If no error
- is detected, <STRONG>OK</STRONG> is returned.
+ The keycode must be greater than zero, and the string non-null,
+ otherwise <STRONG>ERR</STRONG> is returned. <STRONG>ERR</STRONG> may also be returned if there is
+ insufficient memory to allocate the data to store the definition. If
+ no error is detected, <STRONG>OK</STRONG> is returned.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
The <STRONG>form</STRONG> library provides terminal-independent facilities for composing
form screens on character-cell terminals. The library includes: field
routines, which create and modify form fields; and form routines, which
- group fields into forms, display forms on the screen, and handle inter-
- action with the user.
+ group fields into forms, display forms on the screen, and handle
+ interaction with the user.
The <STRONG>form</STRONG> library uses the <STRONG>curses</STRONG> libraries. To use the <STRONG>form</STRONG> library,
link with the options <STRONG>-lform</STRONG> <STRONG>-lcurses</STRONG>.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
Routines that return pointers return <STRONG>NULL</STRONG> on error, and set <STRONG>errno</STRONG> to
- the corresponding error-code returned by functions returning an inte-
- ger. Routines that return an integer return one of the following error
- codes:
+ the corresponding error-code returned by functions returning an
+ integer. Routines that return an integer return one of the following
+ error codes:
<STRONG>E_OK</STRONG> The routine succeeded.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
The menu facility was documented in SVr4.2 in <EM>Character</EM> <EM>User</EM> <EM>Interface</EM>
<EM>Programming</EM> <EM>(UNIX</EM> <EM>SVR4.2)</EM>.
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed
descriptions of the entry points.
- This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201212).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201219).
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: form_driver.3x,v 1.34 2020/10/17 23:28:04 tom Exp @
+ * @Id: form_driver.3x,v 1.35 2020/12/19 21:34:15 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
and character codes returned by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>.
<STRONG>o</STRONG> The input is a printable character. Printable characters (which
- must be positive, less than 256) are checked according to the pro-
- gram's locale settings.
+ must be positive, less than 256) are checked according to the
+ program's locale settings.
<STRONG>o</STRONG> The input is the KEY_MOUSE special key associated with an mouse
event.
</PRE><H3><a name="h3-form_driver_w">form_driver_w</a></H3><PRE>
- This extension simplifies the use of the forms library using wide char-
- acters. The input is either a key code (a request) or a wide character
- returned by <STRONG><A HREF="curs_get_wch.3x.html">get_wch(3x)</A></STRONG>. The type must be passed as well, to enable
- the library to determine whether the parameter is a wide character or a
- request.
+ This extension simplifies the use of the forms library using wide
+ characters. The input is either a key code (a request) or a wide
+ character returned by <STRONG><A HREF="curs_get_wch.3x.html">get_wch(3x)</A></STRONG>. The type must be passed as well, to
+ enable the library to determine whether the parameter is a wide
+ character or a request.
</PRE><H3><a name="h3-Form-driver-requests">Form-driver requests</a></H3><PRE>
that field and <STRONG>E_UNKNOWN_COMMAND</STRONG> is returned. This return value
makes sense, because a double click usually means that an field-
specific action should be returned. It is exactly the purpose
- of this return value to signal that an application specific com-
- mand should be executed.
+ of this return value to signal that an application specific
+ command should be executed.
<STRONG>o</STRONG> If a translation into a request was done, <STRONG>form_driver</STRONG> returns
the result of this request.
</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="form.3x.html">form(3x)</A></STRONG>, <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG>, <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG>,
- <STRONG><A HREF="form_field
type.3x.html">form_fieldtype(3x)</A></STRONG>, <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>.
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG>, <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG>,
+ <STRONG><A HREF="form_field
_validation.3x.html">form_field_validation(3x)</A></STRONG>, <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
The function <STRONG>field_count</STRONG> returns the count of fields in <EM>form</EM>.
- The function <STRONG>move_field</STRONG> moves the given field (which must be discon-
- nected) to a specified location on the screen.
+ The function <STRONG>move_field</STRONG> moves the given field (which must be
+ disconnected) to a specified location on the screen.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
The function <STRONG>field_count</STRONG> returns <STRONG>ERR</STRONG> if the <EM>form</EM> parameter is <STRONG>NULL</STRONG>.
- The functions <STRONG>set_form_fields</STRONG> and <STRONG>move_field</STRONG> return one of the follow-
- ing codes on error:
+ The functions <STRONG>set_form_fields</STRONG> and <STRONG>move_field</STRONG> return one of the
+ following codes on error:
<STRONG>E_OK</STRONG> The routine succeeded.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
The SVr4 forms library documentation specifies the <STRONG>field_count</STRONG> error
value as -1 (which is the value of <STRONG>ERR</STRONG>).
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
The function <STRONG>set_field_fore</STRONG> sets the foreground attribute of <EM>field</EM>.
This is the highlight used to display the field contents. The function
- <STRONG>field_fore</STRONG> returns the foreground attribute. The default is <STRONG>A_STAND-</STRONG>
- <STRONG>OUT</STRONG>.
+ <STRONG>field_fore</STRONG> returns the foreground attribute. The default is
+ <STRONG>A_STANDOUT</STRONG>.
The function <STRONG>set_field_back</STRONG> sets the background attribute of <EM>form</EM>. This
is the highlight used to display the extent fields in the form. The
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
<STRONG>o</STRONG> Buffer 0 is the displayed value of the field.
<STRONG>o</STRONG> Other numbered buffers may be allocated by applications through
- the <STRONG>nbuf</STRONG> argument of (see <STRONG><A HREF="form_field_new.3x.html">form_field_new(3x)</A></STRONG>) but are not manip-
- ulated by the forms library.
+ the <STRONG>nbuf</STRONG> argument of (see <STRONG><A HREF="form_field_new.3x.html">form_field_new(3x)</A></STRONG>) but are not
+ manipulated by the forms library.
The function <STRONG>field_buffer</STRONG> returns a pointer to the contents of the
given numbered buffer:
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- The <STRONG>field_buffer</STRONG> function returns NULL on error. It sets <STRONG>errno</STRONG> accord-
- ing to their success:
+ The <STRONG>field_buffer</STRONG> function returns NULL on error. It sets <STRONG>errno</STRONG>
+ according to their success:
<STRONG>E_OK</STRONG> The routine succeeded.
The header file <STRONG><form.h></STRONG> automatically includes the header file
When configured for wide characters, <STRONG>field_buffer</STRONG> returns a pointer to
- temporary storage (allocated and freed by the library). The applica-
- tion should not attempt to modify the data. It will be freed on the
- next call to <STRONG>field_buffer</STRONG> to return the same buffer. <STRONG><curses.h></STRONG>.
+ temporary storage (allocated and freed by the library). The
+ application should not attempt to modify the data. It will be freed on
+ the next call to <STRONG>field_buffer</STRONG> to return the same buffer. <STRONG><curses.h></STRONG>.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
The <STRONG>set_max_field</STRONG> function checks for an ncurses extension
<STRONG>O_INPUT_FIELD</STRONG> which allows a dynamic field to shrink if the new limit
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
A null (zero pointer) is accepted for any of the return values, to
ignore that value. Not all implementations allow this, e.g., Solaris
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- The function <STRONG>field_just</STRONG> returns one of: NO_JUSTIFICATION, JUS-
- TIFY_RIGHT, JUSTIFY_LEFT, or JUSTIFY_CENTER.
+ The function <STRONG>field_just</STRONG> returns one of: NO_JUSTIFICATION,
+ JUSTIFY_RIGHT, JUSTIFY_LEFT, or JUSTIFY_CENTER.
The function <STRONG>set_field_just</STRONG> returns one of the following:
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
It may be unwise to count on the set of attributes copied by <STRONG>dup_field</STRONG>
being portable; the System V forms library documents are not very
discarded.
O_EDGE_INSERT_STAY
- When inserting into a field up to the boundary position, option-
- ally delay the scrolling, so that the last inserted character
- remains visible, but advance the cursor to reflect the insertion.
- This allows the form library to display the inserted character in
- one-character fields as well as allowing the library to maintain
- consistent state.
+ When inserting into a field up to the boundary position,
+ optionally delay the scrolling, so that the last inserted
+ character remains visible, but advance the cursor to reflect the
+ insertion. This allows the form library to display the inserted
+ character in one-character fields as well as allowing the library
+ to maintain consistent state.
O_INPUT_FIELD
The <STRONG>set_max_field</STRONG> function checks for this extension, which allows
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- Every form field has a field that can be used to hold application-spe-
- cific data (that is, the form-driver code leaves it alone). These
+ Every form field has a field that can be used to hold application-
+ specific data (that is, the form-driver code leaves it alone). These
functions get and set that field.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
The user pointer is a void pointer. We chose not to leave it as a char
pointer for SVr4 compatibility.
lives in automatic variables on the stack.
TYPE_INTEGER
- Integer data, parsable to an integer by <STRONG>atoi(3)</STRONG>. Required parame-
- ters:
+ Integer data, parsable to an integer by <STRONG>atoi(3)</STRONG>. Required
+ parameters:
<STRONG>o</STRONG> a third <STRONG>int</STRONG> argument controlling the precision,
<STRONG>o</STRONG> a fourth <STRONG>long</STRONG> argument constraining minimum value,
<STRONG>o</STRONG> a fifth <STRONG>long</STRONG> constraining maximum value. If the maximum value
- is less than or equal to the minimum value, the range is sim-
- ply ignored.
+ is less than or equal to the minimum value, the range is
+ simply ignored.
On return, the field buffer is formatted according to the <STRONG>printf</STRONG>
- format specification ".*ld", where the "*" is replaced by the pre-
- cision argument.
+ format specification ".*ld", where the "*" is replaced by the
+ precision argument.
For details of the precision handling see <STRONG>printf(3)</STRONG>.
TYPE_NUMERIC
- Numeric data (may have a decimal-point part). Required parame-
- ters:
+ Numeric data (may have a decimal-point part). Required
+ parameters:
<STRONG>o</STRONG> a third <STRONG>int</STRONG> argument controlling the precision,
or equal to the minimum value, the range is simply ignored.
On return, the field buffer is formatted according to the <STRONG>printf</STRONG>
- format specification ".*f", where the "*" is replaced by the pre-
- cision argument.
+ format specification ".*f", where the "*" is replaced by the
+ precision argument.
For details of the precision handling see <STRONG>printf(3)</STRONG>.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- The functions <STRONG>field_type</STRONG> and <STRONG>field_arg</STRONG> return <STRONG>NULL</STRONG> on error. The func-
- tion <STRONG>set_field_type</STRONG> returns one of the following:
+ The functions <STRONG>field_type</STRONG> and <STRONG>field_arg</STRONG> return <STRONG>NULL</STRONG> on error. The
+ function <STRONG>set_field_type</STRONG> returns one of the following:
<STRONG>E_OK</STRONG> The routine succeeded.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
validation. Its parameters are function pointers:
<EM>field</EM><STRONG>_</STRONG><EM>check</EM>
- This function checks the validity of an entered data string when-
- ever the user attempts to leave a field. It has two arguments:
+ This function checks the validity of an entered data string
+ whenever the user attempts to leave a field. It has two
+ arguments:
- <STRONG>o</STRONG> The (FIELD *) argument is passed in so the validation predi-
- cate can see the field's buffer, sizes and other attributes.
+ <STRONG>o</STRONG> The (FIELD *) argument is passed in so the validation
+ predicate can see the field's buffer, sizes and other
+ attributes.
<STRONG>o</STRONG> The second argument is an argument-block structure, about
which more below.
</PRE><H3><a name="h3-free_fieldtype">free_fieldtype</a></H3><PRE>
- The <STRONG>free_fieldtype</STRONG> function frees the space allocated for a given vali-
- dation type by <STRONG>new_fieldtype</STRONG>.
+ The <STRONG>free_fieldtype</STRONG> function frees the space allocated for a given
+ validation type by <STRONG>new_fieldtype</STRONG>.
</PRE><H3><a name="h3-set_fieldtype_arg">set_fieldtype_arg</a></H3><PRE>
the forms user with a way to move through the set.
The <STRONG>set_fieldtype_choice</STRONG> function allows forms programmers to define
- successor and predecessor functions for the field type. These func-
- tions take the field pointer and an argument-block structure as argu-
- ments.
+ successor and predecessor functions for the field type. These
+ functions take the field pointer and an argument-block structure as
+ arguments.
</PRE><H3><a name="h3-link_fieldtype">link_fieldtype</a></H3><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
The <STRONG>unfocus_current_field</STRONG> function is an ncurses extension.
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
- <STRONG>post_form</STRONG>, <STRONG>unpost_form</STRONG> - write or erase forms from associated subwin-
- dows
+ <STRONG>post_form</STRONG>, <STRONG>unpost_form</STRONG> - write or erase forms from associated
+ subwindows
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- <STRONG>form_request_name</STRONG> returns <STRONG>NULL</STRONG> on error and sets <STRONG>errno</STRONG> to <STRONG>E_BAD_ARGU-</STRONG>
- <STRONG>MENT</STRONG>.
+ <STRONG>form_request_name</STRONG> returns <STRONG>NULL</STRONG> on error and sets <STRONG>errno</STRONG> to
+ <STRONG>E_BAD_ARGUMENT</STRONG>.
<STRONG>form_request_by_name</STRONG> returns <STRONG>E_NO_MATCH</STRONG> on error. It does not set
<STRONG>errno</STRONG>.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
The user pointer is a void pointer. We chose not to leave it as a char
pointer for SVr4 compatibility.
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
Every form has an associated pair of <STRONG>curses</STRONG> windows. The form window
- displays any title and border associated with the window; the form sub-
- window displays the items of the form that are currently available for
- selection.
+ displays any title and border associated with the window; the form
+ subwindow displays the items of the form that are currently available
+ for selection.
- The first four functions get and set those windows. It is not neces-
- sary to set either window; by default, the driver code uses <STRONG>stdscr</STRONG> for
- both.
+ The first four functions get and set those windows. It is not
+ necessary to set either window; by default, the driver code uses <STRONG>stdscr</STRONG>
+ for both.
In the <STRONG>set_</STRONG> functions, window argument of <STRONG>NULL</STRONG> is treated as though it
were <STRONG>stsdcr</STRONG>. A form argument of <STRONG>NULL</STRONG> is treated as a request to change
the system default form window or subwindow.
- The function <STRONG>scale_form</STRONG> returns the minimum size required for the sub-
- window of <EM>form</EM>.
+ The function <STRONG>scale_form</STRONG> returns the minimum size required for the
+ subwindow of <EM>form</EM>.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V forms library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V forms library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- <STRONG>infocmp</STRONG> can be used to compare a binary <STRONG>terminfo</STRONG> entry with other ter-
- minfo entries, rewrite a <STRONG>terminfo</STRONG> description to take advantage of the
- <STRONG>use=</STRONG> terminfo field, or print out a <STRONG>terminfo</STRONG> description from the
+ <STRONG>infocmp</STRONG> can be used to compare a binary <STRONG>terminfo</STRONG> entry with other
+ terminfo entries, rewrite a <STRONG>terminfo</STRONG> description to take advantage of
+ the <STRONG>use=</STRONG> terminfo field, or print out a <STRONG>terminfo</STRONG> description from the
binary file (<STRONG>term</STRONG>) in a variety of formats. In all cases, the boolean
fields will be printed first, followed by the numeric fields, followed
by the string fields.
<STRONG>infocmp</STRONG> compares the <STRONG>terminfo</STRONG> description of the first terminal
<EM>termname</EM> with each of the descriptions given by the entries for the
other terminal's <EM>termnames</EM>. If a capability is defined for only one of
- the terminals, the value returned depends on the type of the capabil-
- ity:
+ the terminals, the value returned depends on the type of the
+ capability:
<STRONG>o</STRONG> <STRONG>F</STRONG> for missing boolean variables
<STRONG>-c</STRONG> produces a list of each capability that is <EM>common</EM> between two or
more entries. Missing capabilities are ignored. Each item in the
- list shows "=" after the capability name, followed by the capabil-
- ity value.
+ list shows "=" after the capability name, followed by the
+ capability value.
- The <STRONG>-u</STRONG> option provides a related output, showing the first termi-
- nal description rewritten to use the second as a building block
- via the "use=" clause.
+ The <STRONG>-u</STRONG> option provides a related output, showing the first
+ terminal description rewritten to use the second as a building
+ block via the "use=" clause.
<STRONG>-n</STRONG> produces a list of each capability that is in <EM>none</EM> of the given
entries. Each item in the list shows "!" before the capability
</PRE><H3><a name="h3-Source-Listing-Options-_-I_-_-L_-_-C_-_-r_">Source Listing Options [-I] [-L] [-C] [-r]</a></H3><PRE>
- The <STRONG>-I</STRONG>, <STRONG>-L</STRONG>, and <STRONG>-C</STRONG> options will produce a source listing for each ter-
- minal named.
+ The <STRONG>-I</STRONG>, <STRONG>-L</STRONG>, and <STRONG>-C</STRONG> options will produce a source listing for each
+ terminal named.
<STRONG>-I</STRONG> use the <STRONG>terminfo</STRONG> names
<STRONG>-L</STRONG> use the long C variable name listed in <<STRONG>term.h</STRONG>>
excess whitespace (use the <STRONG>-0</STRONG> option for that).
All padding information for strings will be collected together and
- placed at the beginning of the string where <STRONG>termcap</STRONG> expects it. Manda-
- tory padding (padding information with a trailing "/") will become
+ placed at the beginning of the string where <STRONG>termcap</STRONG> expects it.
+ Mandatory padding (padding information with a trailing "/") will become
optional.
All <STRONG>termcap</STRONG> variables no longer supported by <STRONG>terminfo</STRONG>, but which are
- derivable from other <STRONG>terminfo</STRONG> variables, will be output. Not all <STRONG>ter-</STRONG>
- <STRONG>minfo</STRONG> capabilities will be translated; only those variables which were
- part of <STRONG>termcap</STRONG> will normally be output. Specifying the <STRONG>-r</STRONG> option will
- take off this restriction, allowing all capabilities to be output in
- <EM>termcap</EM> form. Normally you would use both the <STRONG>-C</STRONG> and <STRONG>-r</STRONG> options. The
- actual format used incorporates some improvements for escaped charac-
- ters from terminfo format. For a stricter BSD-compatible translation,
- use the <STRONG>-K</STRONG> option rather than <STRONG>-C</STRONG>.
-
- Note that because padding is collected to the beginning of the capabil-
- ity, not all capabilities are output. Mandatory padding is not sup-
- ported. Because <STRONG>termcap</STRONG> strings are not as flexible, it is not always
- possible to convert a <STRONG>terminfo</STRONG> string capability into an equivalent
- <STRONG>termcap</STRONG> format. A subsequent conversion of the <STRONG>termcap</STRONG> file back into
- <STRONG>terminfo</STRONG> format will not necessarily reproduce the original <STRONG>terminfo</STRONG>
- source.
+ derivable from other <STRONG>terminfo</STRONG> variables, will be output. Not all
+ <STRONG>terminfo</STRONG> capabilities will be translated; only those variables which
+ were part of <STRONG>termcap</STRONG> will normally be output. Specifying the <STRONG>-r</STRONG> option
+ will take off this restriction, allowing all capabilities to be output
+ in <EM>termcap</EM> form. Normally you would use both the <STRONG>-C</STRONG> and <STRONG>-r</STRONG> options.
+ The actual format used incorporates some improvements for escaped
+ characters from terminfo format. For a stricter BSD-compatible
+ translation, use the <STRONG>-K</STRONG> option rather than <STRONG>-C</STRONG>.
+
+ Note that because padding is collected to the beginning of the
+ capability, not all capabilities are output. Mandatory padding is not
+ supported. Because <STRONG>termcap</STRONG> strings are not as flexible, it is not
+ always possible to convert a <STRONG>terminfo</STRONG> string capability into an
+ equivalent <STRONG>termcap</STRONG> format. A subsequent conversion of the <STRONG>termcap</STRONG> file
+ back into <STRONG>terminfo</STRONG> format will not necessarily reproduce the original
+ <STRONG>terminfo</STRONG> source.
Some common <STRONG>terminfo</STRONG> parameter sequences, their <STRONG>termcap</STRONG> equivalents,
and some terminal types which commonly have such sequences, are:
</PRE><H3><a name="h3-Use_-Option-_-u_">Use= Option [-u]</a></H3><PRE>
- The <STRONG>-u</STRONG> option produces a <STRONG>terminfo</STRONG> source description of the first ter-
- minal <EM>termname</EM> which is relative to the sum of the descriptions given
- by the entries for the other terminals <EM>termnames</EM>. It does this by ana-
- lyzing the differences between the first <EM>termname</EM> and the other
+ The <STRONG>-u</STRONG> option produces a <STRONG>terminfo</STRONG> source description of the first
+ terminal <EM>termname</EM> which is relative to the sum of the descriptions
+ given by the entries for the other terminals <EM>termnames</EM>. It does this
+ by analyzing the differences between the first <EM>termname</EM> and the other
<EM>termnames</EM> and producing a description with <STRONG>use=</STRONG> fields for the other
terminals. In this manner, it is possible to retrofit generic terminfo
entries into a terminal's description. Or, if two similar terminals
the first of the other <EM>termname</EM> entries that has this capability gives
a different value for the capability than that in the first <EM>termname</EM>.
- The order of the other <EM>termname</EM> entries is significant. Since the ter-
- minfo compiler <STRONG>tic</STRONG> does a left-to-right scan of the capabilities, spec-
- ifying two <STRONG>use=</STRONG> entries that contain differing entries for the same
+ The order of the other <EM>termname</EM> entries is significant. Since the
+ terminfo compiler <STRONG>tic</STRONG> does a left-to-right scan of the capabilities,
+ specifying two <STRONG>use=</STRONG> entries that contain differing entries for the same
capabilities will produce different results depending on the order that
the entries are given in. <STRONG>infocmp</STRONG> will flag any such inconsistencies
between the other <EM>termname</EM> entries as they are found.
were not needed.
<STRONG>Changing</STRONG> <STRONG>Databases</STRONG> <STRONG>[-A</STRONG> <EM>directory</EM>] [-B <EM>directory</EM>]
- Like other <STRONG>ncurses</STRONG> utilities, <STRONG>infocmp</STRONG> looks for the terminal descrip-
- tions in several places. You can use the <STRONG>TERMINFO</STRONG> and <STRONG>TERMINFO_DIRS</STRONG>
- environment variables to override the compiled-in default list of
- places to search (see <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> for details).
+ Like other <STRONG>ncurses</STRONG> utilities, <STRONG>infocmp</STRONG> looks for the terminal
+ descriptions in several places. You can use the <STRONG>TERMINFO</STRONG> and
+ <STRONG>TERMINFO_DIRS</STRONG> environment variables to override the compiled-in default
+
list of places to search (see <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> for details).
You can also use the options <STRONG>-A</STRONG> and <STRONG>-B</STRONG> to override the list of places
to search when comparing terminal descriptions:
<STRONG>o</STRONG> The <STRONG>-B</STRONG> option sets the location for the other <EM>termnames</EM>.
- Using these options, it is possible to compare descriptions for a ter-
- minal with the same name located in two different databases. For
+ Using these options, it is possible to compare descriptions for a
+ terminal with the same name located in two different databases. For
instance, you can use this feature for comparing descriptions for the
same terminal created by different people.
and exit.
<STRONG>-E</STRONG> Dump the capabilities of the given terminal as tables, needed in
- the C initializer for a TERMTYPE structure (the terminal capabil-
- ity structure in the <STRONG><term.h></STRONG>). This option is useful for prepar-
- ing versions of the curses library hardwired for a given terminal
- type. The tables are all declared static, and are named according
- to the type and the name of the corresponding terminal entry.
-
- Before ncurses 5.0, the split between the <STRONG>-e</STRONG> and <STRONG>-E</STRONG> options was
- not needed; but support for extended names required making the
- arrays of terminal capabilities separate from the TERMTYPE struc-
- ture.
+ the C initializer for a TERMTYPE structure (the terminal
+ capability structure in the <STRONG><term.h></STRONG>). This option is useful for
+ preparing versions of the curses library hardwired for a given
+ terminal type. The tables are all declared static, and are named
+ according to the type and the name of the corresponding terminal
+ entry.
+
+ Before ncurses 5.0, the split between the <STRONG>-e</STRONG> and <STRONG>-E</STRONG> options was
+ not needed; but support for extended names required making the
+ arrays of terminal capabilities separate from the TERMTYPE
+ structure.
<STRONG>-e</STRONG> Dump the capabilities of the given terminal as a C initializer for
- a TERMTYPE structure (the terminal capability structure in the
- <STRONG><term.h></STRONG>). This option is useful for preparing versions of the
+ a TERMTYPE structure (the terminal capability structure in the
+ <STRONG><term.h></STRONG>). This option is useful for preparing versions of the
curses library hardwired for a given terminal type.
<STRONG>-F</STRONG> compare terminfo files. This assumes that two following arguments
- are filenames. The files are searched for pairwise matches
- between entries, with two entries considered to match if any of
- their names do. The report printed to standard output lists
- entries with no matches in the other file, and entries with more
- than one match. For entries with exactly one match it includes a
- difference report. Normally, to reduce the volume of the report,
- use references are not resolved before looking for differences,
+ are filenames. The files are searched for pairwise matches
+ between entries, with two entries considered to match if any of
+ their names do. The report printed to standard output lists
+ entries with no matches in the other file, and entries with more
+ than one match. For entries with exactly one match it includes a
+ difference report. Normally, to reduce the volume of the report,
+ use references are not resolved before looking for differences,
but resolution can be forced by also specifying <STRONG>-r</STRONG>.
- <STRONG>-f</STRONG> Display complex terminfo strings which contain if/then/else/endif
+ <STRONG>-f</STRONG> Display complex terminfo strings which contain if/then/else/endif
expressions indented for readability.
- <STRONG>-G</STRONG> Display constant literals in decimal form rather than their char-
- acter equivalents.
+ <STRONG>-G</STRONG> Display constant literals in decimal form rather than their
+ character equivalents.
- <STRONG>-g</STRONG> Display constant character literals in quoted form rather than
+ <STRONG>-g</STRONG> Display constant character literals in quoted form rather than
their decimal equivalents.
- <STRONG>-i</STRONG> Analyze the initialization (<STRONG>is1</STRONG>, <STRONG>is2</STRONG>, <STRONG>is3</STRONG>), and reset (<STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>,
- <STRONG>rs3</STRONG>), strings in the entry, as well as those used for start-
- ing/stopping cursor-positioning mode (<STRONG>smcup</STRONG>, <STRONG>rmcup</STRONG>) as well as
- starting/stopping keymap mode (<STRONG>smkx</STRONG>, <STRONG>rmkx</STRONG>).
+ <STRONG>-i</STRONG> Analyze the initialization (<STRONG>is1</STRONG>, <STRONG>is2</STRONG>, <STRONG>is3</STRONG>), and reset (<STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>,
+ <STRONG>rs3</STRONG>), strings in the entry, as well as those used for
+ starting/stopping cursor-positioning mode (<STRONG>smcup</STRONG>, <STRONG>rmcup</STRONG>) as well
+ as starting/stopping keymap mode (<STRONG>smkx</STRONG>, <STRONG>rmkx</STRONG>).
- For each string, the code tries to analyze it into actions in
- terms of the other capabilities in the entry, certain X3.64/ISO
+ For each string, the code tries to analyze it into actions in
+ terms of the other capabilities in the entry, certain X3.64/ISO
6429/ECMA-48 capabilities, and certain DEC VT-series private modes
- (the set of recognized special sequences has been selected for
- completeness over the existing terminfo database). Each report
- line consists of the capability name, followed by a colon and
- space, followed by a printable expansion of the capability string
- with sections matching recognized actions translated into
+ (the set of recognized special sequences has been selected for
+ completeness over the existing terminfo database). Each report
+ line consists of the capability name, followed by a colon and
+ space, followed by a printable expansion of the capability string
+ with sections matching recognized actions translated into
{}-bracketed descriptions.
Here is a list of the DEC/ANSI special sequences recognized:
DECSTR soft reset (VT320)
S7C1T 7-bit controls (VT220)
-----------------------------------------
- ISO DEC G0 enable DEC graphics for G0
+ ISO DEC G0 enable DEC graphics for G0
ISO UK G0 enable UK chars for G0
ISO US G0 enable US chars for G0
ISO DEC G1 enable DEC graphics for G1
DEC[+-]AWM wraparound mode
DEC[+-]ARM auto-repeat mode
- It also recognizes a SGR action corresponding to ANSI/ISO
- 6429/ECMA Set Graphics Rendition, with the values NORMAL, BOLD,
- UNDERLINE, BLINK, and REVERSE. All but NORMAL may be prefixed
+ It also recognizes a SGR action corresponding to ANSI/ISO
+ 6429/ECMA Set Graphics Rendition, with the values NORMAL, BOLD,
+ UNDERLINE, BLINK, and REVERSE. All but NORMAL may be prefixed
with
<STRONG>o</STRONG> "+" (turn on) or
<STRONG>o</STRONG> "-" (turn off).
- An SGR0 designates an empty highlight sequence (equivalent to
+ An SGR0 designates an empty highlight sequence (equivalent to
{SGR:NORMAL}).
<STRONG>-l</STRONG> Set output format to terminfo.
<STRONG>-p</STRONG> Ignore padding specifications when comparing strings.
- <STRONG>-Q</STRONG> <EM>n</EM> Rather than show source in terminfo (text) format, print the com-
- piled (binary) format in hexadecimal or base64 form, depending on
- the option's value:
+ <STRONG>-Q</STRONG> <EM>n</EM> Rather than show source in terminfo (text) format, print the
+ compiled (binary) format in hexadecimal or base64 form, depending
+ on the option's value:
1 hexadecimal
3 hexadecimal and base64
- For example, this prints the compiled terminfo value as a string
+ For example, this prints the compiled terminfo value as a string
which could be assigned to the <STRONG>TERMINFO</STRONG> environment variable:
infocmp -0 -q -Q2
<STRONG>-q</STRONG> This makes the output a little shorter:
- <STRONG>o</STRONG> Make the comparison listing shorter by omitting subheadings,
+ <STRONG>o</STRONG> Make the comparison listing shorter by omitting subheadings,
and using "-" for absent capabilities, "@" for canceled rather
than "NULL".
- <STRONG>o</STRONG> However, show differences between absent and cancelled capa-
- bilities.
+ <STRONG>o</STRONG> However, show differences between absent and cancelled
+ capabilities.
<STRONG>o</STRONG> Omit the "Reconstructed from" comment for source listings.
<STRONG>-R</STRONG><EM>subset</EM>
- Restrict output to a given subset. This option is for use with
- archaic versions of terminfo like those on SVr1, Ultrix, or HP/UX
- that do not support the full set of SVR4/XSI Curses terminfo; and
- variants such as AIX that have their own extensions incompatible
+ Restrict output to a given subset. This option is for use with
+ archaic versions of terminfo like those on SVr1, Ultrix, or HP/UX
+ that do not support the full set of SVR4/XSI Curses terminfo; and
+ variants such as AIX that have their own extensions incompatible
with SVr4/XSI.
- <STRONG>o</STRONG> Available terminfo subsets are "SVr1", "Ultrix", "HP", and
+ <STRONG>o</STRONG> Available terminfo subsets are "SVr1", "Ultrix", "HP", and
"AIX"; see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for details.
- <STRONG>o</STRONG> You can also choose the subset "BSD" which selects only capa-
- bilities with termcap equivalents recognized by 4.4BSD. The
- <STRONG>-C</STRONG> option sets the "BSD" subset as a side-effect.
+ <STRONG>o</STRONG> You can also choose the subset "BSD" which selects only
+ capabilities with termcap equivalents recognized by 4.4BSD.
+ The <STRONG>-C</STRONG> option sets the "BSD" subset as a side-effect.
- <STRONG>o</STRONG> If you select any other value for <STRONG>-R</STRONG>, it is the same as no
- subset, i.e., all capabilities are used. The <STRONG>-I</STRONG> option like-
- wise selects no subset as a side-effect.
+ <STRONG>o</STRONG> If you select any other value for <STRONG>-R</STRONG>, it is the same as no
+ subset, i.e., all capabilities are used. The <STRONG>-I</STRONG> option
+ likewise selects no subset as a side-effect.
<STRONG>-s</STRONG> <EM>[d|i|l|c]</EM>
- The <STRONG>-s</STRONG> option sorts the fields within each type according to the
+ The <STRONG>-s</STRONG> option sorts the fields within each type according to the
argument below:
- <STRONG>d</STRONG> leave fields in the order that they are stored in the <EM>ter-</EM>
- <EM>minfo</EM> database.
+ <STRONG>d</STRONG> leave fields in the order that they are stored in the
+ <EM>terminfo</EM> database.
<STRONG>i</STRONG> sort by <EM>terminfo</EM> name.
<STRONG>c</STRONG> sort by the <EM>termcap</EM> name.
- If the <STRONG>-s</STRONG> option is not given, the fields printed out will be
- sorted alphabetically by the <STRONG>terminfo</STRONG> name within each type,
- except in the case of the <STRONG>-C</STRONG> or the <STRONG>-L</STRONG> options, which cause the
- sorting to be done by the <STRONG>termcap</STRONG> name or the long C variable
+ If the <STRONG>-s</STRONG> option is not given, the fields printed out will be
+ sorted alphabetically by the <STRONG>terminfo</STRONG> name within each type,
+ except in the case of the <STRONG>-C</STRONG> or the <STRONG>-L</STRONG> options, which cause the
+ sorting to be done by the <STRONG>termcap</STRONG> name or the long C variable
name, respectively.
- <STRONG>-T</STRONG> eliminates size-restrictions on the generated text. This is
+ <STRONG>-T</STRONG> eliminates size-restrictions on the generated text. This is
mainly useful for testing and analysis, since the compiled
- descriptions are limited (e.g., 1023 for termcap, 4096 for ter-
- minfo).
+ descriptions are limited (e.g., 1023 for termcap, 4096 for
+ terminfo).
- <STRONG>-t</STRONG> tells <STRONG>tic</STRONG> to discard commented-out capabilities. Normally when
- translating from terminfo to termcap, untranslatable capabilities
+ <STRONG>-t</STRONG> tells <STRONG>tic</STRONG> to discard commented-out capabilities. Normally when
+ translating from terminfo to termcap, untranslatable capabilities
are commented-out.
- <STRONG>-U</STRONG> tells <STRONG>infocmp</STRONG> to not post-process the data after parsing the
- source file. This feature helps when comparing the actual con-
- tents of two source files, since it excludes the inferences that
- <STRONG>infocmp</STRONG> makes to fill in missing data.
+ <STRONG>-U</STRONG> tells <STRONG>infocmp</STRONG> to not post-process the data after parsing the
+ source file. This feature helps when comparing the actual
+ contents of two source files, since it excludes the inferences
+ that <STRONG>infocmp</STRONG> makes to fill in missing data.
<STRONG>-V</STRONG> reports the version of ncurses which was used in this program, and
exits.
- <STRONG>-v</STRONG> <EM>n</EM> prints out tracing information on standard error as the program
+ <STRONG>-v</STRONG> <EM>n</EM> prints out tracing information on standard error as the program
runs.
- The optional parameter <EM>n</EM> is a number from 1 to 10, inclusive,
+ The optional parameter <EM>n</EM> is a number from 1 to 10, inclusive,
indicating the desired level of detail of information. If ncurses
- is built without tracing support, the optional parameter is
+ is built without tracing support, the optional parameter is
ignored.
- <STRONG>-W</STRONG> By itself, the <STRONG>-w</STRONG> option will not force long strings to be
+ <STRONG>-W</STRONG> By itself, the <STRONG>-w</STRONG> option will not force long strings to be
wrapped. Use the <STRONG>-W</STRONG> option to do this.
<STRONG>-w</STRONG> <EM>width</EM>
changes the output to <EM>width</EM> characters.
<STRONG>-x</STRONG> print information for user-defined capabilities (see <STRONG>user_caps(5)</STRONG>.
- These are extensions to the terminfo repertoire which can be
+ These are extensions to the terminfo repertoire which can be
loaded using the <STRONG>-x</STRONG> option of <STRONG>tic</STRONG>.
</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
- /usr/local/ncurses/lib/terminfo
- Compiled terminal description database.
+ /usr/share/terminfo Compiled terminal description database.
</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
- Although System V Release 2 provided a terminfo library, it had no doc-
- umented tool for decompiling the terminal descriptions. Tony Hansen
+ Although System V Release 2 provided a terminfo library, it had no
+ documented tool for decompiling the terminal descriptions. Tony Hansen
(AT&T) wrote the first <STRONG>infocmp</STRONG> in early 1984, for System V Release 3.
- Eric Raymond used the AT&T documentation in 1995 to provide an equiva-
- lent <STRONG>infocmp</STRONG> for ncurses. In addition, he added a few new features
- such as:
+ Eric Raymond used the AT&T documentation in 1995 to provide an
+ equivalent <STRONG>infocmp</STRONG> for ncurses. In addition, he added a few new
+ features such as:
- <STRONG>o</STRONG> the <STRONG>-e</STRONG> option, to support <EM>fallback</EM> (compiled-in) terminal descrip-
- tions
+ <STRONG>o</STRONG> the <STRONG>-e</STRONG> option, to support <EM>fallback</EM> (compiled-in) terminal
+ descriptions
<STRONG>o</STRONG> the <STRONG>-i</STRONG> option, to help with analysis
- Later, Thomas Dickey added the <STRONG>-x</STRONG> (user-defined capabilities) option,
- and the <STRONG>-E</STRONG> option to support fallback entries with user-defined capa-
- bilities.
+ Later, Thomas Dickey added the <STRONG>-x</STRONG> (user-defined capabilities) option,
+ and the <STRONG>-E</STRONG> option to support fallback entries with user-defined
+ capabilities.
For a complete list, see the <EM>EXTENSIONS</EM> section.
- In 2010, Roy Marples provided an <STRONG>infocmp</STRONG> program for NetBSD. It is
- less capable than the SVr4 or ncurses versions (e.g., it lacks the
- sorting options documented in X/Open), but does include the <STRONG>-x</STRONG> option
+ In 2010, Roy Marples provided an <STRONG>infocmp</STRONG> program for NetBSD. It is
+ less capable than the SVr4 or ncurses versions (e.g., it lacks the
+ sorting options documented in X/Open), but does include the <STRONG>-x</STRONG> option
adapted from ncurses.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- X/Open Curses, Issue 7 (2009) provides a description of <STRONG>infocmp</STRONG>. It
+ X/Open Curses, Issue 7 (2009) provides a description of <STRONG>infocmp</STRONG>. It
does not mention the options used for converting to termcap format.
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
- The <STRONG>-0</STRONG>, <STRONG>-1</STRONG>, <STRONG>-E</STRONG>, <STRONG>-F</STRONG>, <STRONG>-G</STRONG>, <STRONG>-Q</STRONG>, <STRONG>-R</STRONG>, <STRONG>-T</STRONG>, <STRONG>-V</STRONG>, <STRONG>-a</STRONG>, <STRONG>-e</STRONG>, <STRONG>-f</STRONG>, <STRONG>-g</STRONG>, <STRONG>-i</STRONG>, <STRONG>-l</STRONG>, <STRONG>-p</STRONG>, <STRONG>-q</STRONG>
+ The <STRONG>-0</STRONG>, <STRONG>-1</STRONG>, <STRONG>-E</STRONG>, <STRONG>-F</STRONG>, <STRONG>-G</STRONG>, <STRONG>-Q</STRONG>, <STRONG>-R</STRONG>, <STRONG>-T</STRONG>, <STRONG>-V</STRONG>, <STRONG>-a</STRONG>, <STRONG>-e</STRONG>, <STRONG>-f</STRONG>, <STRONG>-g</STRONG>, <STRONG>-i</STRONG>, <STRONG>-l</STRONG>, <STRONG>-p</STRONG>, <STRONG>-q</STRONG>
and <STRONG>-t</STRONG> options are not supported in SVr4 curses.
- SVr4 infocmp does not distinguish between absent and cancelled capabil-
- ities. Also, it shows missing integer capabilities as <STRONG>-1</STRONG> (the internal
- value used to represent missing integers). This implementation shows
- those as "NULL", for consistency with missing strings.
+ SVr4 infocmp does not distinguish between absent and cancelled
+ capabilities. Also, it shows missing integer capabilities as <STRONG>-1</STRONG> (the
+ internal value used to represent missing integers). This
+ implementation shows those as "NULL", for consistency with missing
+ strings.
The <STRONG>-r</STRONG> option's notion of "termcap" capabilities is System V Release
4's. Actual BSD curses versions will have a more restricted set. To
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG>, <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG>ter-</STRONG>
- <STRONG><A HREF="terminfo.5.html">minfo(5)</A></STRONG>. <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>.
+ <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG>, <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,
+ <STRONG><A HREF="terminfo.5.html">
terminfo(5)</A></STRONG>. <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>.
https://invisible-island.net/ncurses/tctest.html
- This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201212).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201219).
</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: infotocap.1m,v 1.16 2020/02/02 23:34:34 tom Exp @
+ * @Id: infotocap.1m,v 1.17 2020/12/19 21:49:52 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
- /usr/local/ncurses/lib/terminfo
- Compiled terminal description database.
+ /usr/share/terminfo Compiled terminal description database.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="
ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
+ <STRONG><A HREF="
infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
- This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201212).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201219).
</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
The <EM>keycode</EM> parameter must be greater than zero, else NULL is returned.
If it does not correspond to a defined key, then NULL is returned. The
<EM>count</EM> parameter is used to allow the application to iterate through
- multiple definitions, counting from zero. When successful, the func-
- tion returns a string which must be freed by the caller.
+ multiple definitions, counting from zero. When successful, the
+ function returns a string which must be freed by the caller.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
The <EM>level</EM> parameter controls the result:
- 0 the library functions normally, rendering nonprinting char-
- acters as described in <STRONG>unctrl</STRONG>.
+ 0 the library functions normally, rendering nonprinting
+ characters as described in <STRONG>unctrl</STRONG>.
1 the library ignores <STRONG>isprintf</STRONG> for codes in the range
160-255.
The <STRONG>menu</STRONG> library provides terminal-independent facilities for composing
menu systems on character-cell terminals. The library includes: item
routines, which create and modify menu items; and menu routines, which
- group items into menus, display menus on the screen, and handle inter-
- action with the user.
+ group items into menus, display menus on the screen, and handle
+ interaction with the user.
The <STRONG>menu</STRONG> library uses the <STRONG>curses</STRONG> libraries, and a curses initialization
- routine such as <STRONG>initscr</STRONG> must be called before using any of these func-
- tions. To use the <STRONG>menu</STRONG> library, link with the options <STRONG>-lmenu</STRONG> <STRONG>-lcurses</STRONG>.
+ routine such as <STRONG>initscr</STRONG> must be called before using any of these
+ functions. To use the <STRONG>menu</STRONG> library, link with the options <STRONG>-lmenu</STRONG>
+ <STRONG>-lcurses</STRONG>.
</PRE><H3><a name="h3-Current-Default-Values-for-Item-Attributes">Current Default Values for Item Attributes</a></H3><PRE>
- The <STRONG>menu</STRONG> library maintains a default value for item attributes. You
- can get or set this default by calling the appropriate <STRONG>get_</STRONG> or <STRONG>set_</STRONG>
- routine with a <STRONG>NULL</STRONG> item pointer. Changing this default with a <STRONG>set_</STRONG>
- function affects future item creations, but does not change the render-
- ing of items already created.
+ The <STRONG>menu</STRONG> library maintains a default value for item attributes. You
+ can get or set this default by calling the appropriate <STRONG>get_</STRONG> or <STRONG>set_</STRONG>
+ routine with a <STRONG>NULL</STRONG> item pointer. Changing this default with a <STRONG>set_</STRONG>
+ function affects future item creations, but does not change the
+ rendering of items already created.
</PRE><H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE>
- The following table lists each <STRONG>menu</STRONG> routine and the name of the manual
+ The following table lists each <STRONG>menu</STRONG> routine and the name of the manual
page on which it is described.
<STRONG>curses</STRONG> Routine Name Manual Page Name
menu_pattern <STRONG><A HREF="menu_pattern.3x.html">menu_pattern(3x)</A></STRONG>
menu_request_by_name <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG>
menu_request_name <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG>
- menu_spacing <STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG>
+ menu_spacing <STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG>
menu_sub <STRONG><A HREF="menu_win.3x.html">menu_win(3x)</A></STRONG>
menu_term <STRONG><A HREF="menu_hook.3x.html">menu_hook(3x)</A></STRONG>
menu_userptr <STRONG><A HREF="menu_userptr.3x.html">menu_userptr(3x)</A></STRONG>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Routines that return pointers return <STRONG>NULL</STRONG> on error. Routines that
+ Routines that return pointers return <STRONG>NULL</STRONG> on error. Routines that
return an integer return one of the following error codes:
<STRONG>E_OK</STRONG> The routine succeeded.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- The header file <STRONG><menu.h></STRONG> automatically includes the header files
+ The header file <STRONG><menu.h></STRONG> automatically includes the header files
<STRONG><curses.h></STRONG> and <STRONG><eti.h></STRONG>.
In your library list, libmenu.a should be before libncurses.a; that is,
- you should say "-lmenu -lncurses", not the other way around (which
+ you should say "-lmenu -lncurses", not the other way around (which
would give a link-error when using static libraries).
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
- The menu facility was documented in SVr4.2 in <EM>Character</EM> <EM>User</EM> <EM>Interface</EM>
+ The menu facility was documented in SVr4.2 in <EM>Character</EM> <EM>User</EM> <EM>Interface</EM>
<EM>Programming</EM> <EM>(UNIX</EM> <EM>SVR4.2)</EM>.
It is not part of X/Open Curses.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
- Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric S.
+ Juergen Pfeifer. Manual pages and adaptation for ncurses by Eric S.
Raymond.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "menu_" for detailed
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "menu_" for detailed
descriptions of the entry points.
- This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201212).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201219).
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
<STRONG>menu_back</STRONG>, <STRONG>menu_fore</STRONG>, <STRONG>menu_grey</STRONG>, <STRONG>menu_pad</STRONG>, <STRONG>set_menu_back</STRONG>,
- <STRONG>set_menu_fore</STRONG>, <STRONG>set_menu_grey</STRONG>, <STRONG>set_menu_pad</STRONG> - color and attribute con-
- trol for menus
+ <STRONG>set_menu_fore</STRONG>, <STRONG>set_menu_grey</STRONG>, <STRONG>set_menu_pad</STRONG> - color and attribute
+ control for menus
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- The function <STRONG>pos_menu_cursor</STRONG> restores the cursor to the current posi-
- tion associated with the menu's selected item. This is useful after
- <STRONG>curses</STRONG> routines have been called to do screen-painting in response to a
- menu select.
+ The function <STRONG>pos_menu_cursor</STRONG> restores the cursor to the current
+ position associated with the menu's selected item. This is useful
+ after <STRONG>curses</STRONG> routines have been called to do screen-painting in
+ response to a menu select.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: menu_driver.3x,v 1.27 2020/10/17 23:42:13 tom Exp @
+ * @Id: menu_driver.3x,v 1.28 2020/12/19 21:33:37 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
and character codes returned by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>.
<STRONG>o</STRONG> The input is a printable character. Printable characters (which
- must be positive, less than 256) are checked according to the pro-
- gram's locale settings.
+ must be positive, less than 256) are checked according to the
+ program's locale settings.
<STRONG>o</STRONG> The input is the KEY_MOUSE special key associated with an mouse
event.
</PRE><H3><a name="h3-APPLICATION-DEFINED-COMMANDS">APPLICATION-DEFINED COMMANDS</a></H3><PRE>
If the second argument is neither printable nor one of the above pre-
- defined menu requests or KEY_MOUSE, the drive assumes it is an applica-
- tion-specific command and returns <STRONG>E_UNKNOWN_COMMAND</STRONG>. Application-
- defined commands should be defined relative to <STRONG>MAX_COMMAND</STRONG>, the maximum
- value of these pre-defined requests.
+ defined menu requests or KEY_MOUSE, the drive assumes it is an
+ application-specific command and returns <STRONG>E_UNKNOWN_COMMAND</STRONG>.
+ Application-defined commands should be defined relative to <STRONG>MAX_COMMAND</STRONG>,
+ the maximum value of these pre-defined requests.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>.
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG>.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions. The support for mouse events is
- ncurses specific.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions. The support for mouse events
+ is ncurses specific.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
The function <STRONG>set_menu_format</STRONG> sets the maximum display size of the given
menu. If this size is too small to display all menu items, the menu
- will be made scrollable. If this size is larger than the menus subwin-
- dow and the subwindow is too small to display all menu items, <STRONG>post_menu</STRONG>
- will fail.
+ will be made scrollable. If this size is larger than the menus
+ subwindow and the subwindow is too small to display all menu items,
+ <STRONG>post_menu</STRONG> will fail.
The default format is 16 rows, 1 column. Calling <STRONG>set_menu_format</STRONG> with
a null menu pointer will change this default. A zero row or column
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
The SVr4 menu library documentation specifies the <STRONG>item_count</STRONG> error
value as -1 (which is the value of <STRONG>ERR</STRONG>).
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
other end of the menu.
O_MOUSE_MENU
- If user clicks with the mouse and it does not fall on the cur-
- rently active menu, push <STRONG>KEY_MOUSE</STRONG> and the <STRONG>MEVENT</STRONG> data back on the
- queue to allow processing in another part of the calling program.
+ If user clicks with the mouse and it does not fall on the
+ currently active menu, push <STRONG>KEY_MOUSE</STRONG> and the <STRONG>MEVENT</STRONG> data back on
+ the queue to allow processing in another part of the calling
+ program.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
- <STRONG>post_menu</STRONG>, <STRONG>unpost_menu</STRONG> - write or erase menus from associated subwin-
- dows
+ <STRONG>post_menu</STRONG>, <STRONG>unpost_menu</STRONG> - write or erase menus from associated
+ subwindows
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- <STRONG>menu_request_name</STRONG> returns <STRONG>NULL</STRONG> on error and sets <STRONG>errno</STRONG> to <STRONG>E_BAD_ARGU-</STRONG>
- <STRONG>MENT</STRONG>.
+ <STRONG>menu_request_name</STRONG> returns <STRONG>NULL</STRONG> on error and sets <STRONG>errno</STRONG> to
+ <STRONG>E_BAD_ARGUMENT</STRONG>.
<STRONG>menu_request_by_name</STRONG> returns <STRONG>E_NO_MATCH</STRONG> on error. It does not set
<STRONG>errno</STRONG>.
<STRONG>spc_rows</STRONG> parameter controls the number of rows that are used for an
item. It must not be larger than 3. The menu system inserts the blank
lines between item rows, these lines will contain the pad character in
- the appropriate positions. The <STRONG>spc_columns</STRONG> parameter controls the num-
- ber of blanks between columns of items. It must not be larger than
+ the appropriate positions. The <STRONG>spc_columns</STRONG> parameter controls the
+ number of blanks between columns of items. It must not be larger than
<STRONG>TABSIZE</STRONG>. A value of 0 for all the spacing values resets them to the
default, which is 1 for all of them.
The function <STRONG>menu_spacing</STRONG> passes back the spacing info for the menu.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
The user pointer is a void pointer. We chose not to leave it as a char
pointer for SVr4 compatibility.
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
Every menu has an associated pair of <STRONG>curses</STRONG> windows. The menu window
- displays any title and border associated with the window; the menu sub-
- window displays the items of the menu that are currently available for
- selection.
+ displays any title and border associated with the window; the menu
+ subwindow displays the items of the menu that are currently available
+ for selection.
- The first four functions get and set those windows. It is not neces-
- sary to set either window; by default, the driver code uses <STRONG>stdscr</STRONG> for
- both.
+ The first four functions get and set those windows. It is not
+ necessary to set either window; by default, the driver code uses <STRONG>stdscr</STRONG>
+ for both.
In the <STRONG>set_</STRONG> functions, window argument of <STRONG>NULL</STRONG> is treated as though it
were <STRONG>stsdcr</STRONG>. A menu argument of <STRONG>NULL</STRONG> is treated as a request to change
the system default menu window or subwindow.
- The function <STRONG>scale_menu</STRONG> returns the minimum size required for the sub-
- window of <EM>menu</EM>.
+ The function <STRONG>scale_menu</STRONG> returns the minimum size required for the
+ subwindow of <EM>menu</EM>.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
The SVr4 menu library documentation specifies the <STRONG>top_row</STRONG> and
<STRONG>index_item</STRONG> error value as -1 (which is the value of <STRONG>ERR</STRONG>).
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- Every menu item has a field that can be used to hold application-spe-
- cific data (that is, the menu-driver code leaves it alone). These
+ Every menu item has a field that can be used to hold application-
+ specific data (that is, the menu-driver code leaves it alone). These
functions get and set that field.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
The user pointer is a void pointer. We chose not to leave it as a char
pointer for SVr4 compatibility.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- These routines emulate the System V menu library. They were not sup-
- ported on Version 7 or BSD versions.
+ These routines emulate the System V menu library. They were not
+ supported on Version 7 or BSD versions.
</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>
method of updating character screens with reasonable optimization.
This implementation is "new curses" (ncurses) and is the approved
replacement for 4.4BSD classic curses, which has been discontinued.
- This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201212).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201219).
The <STRONG>ncurses</STRONG> library emulates the curses library of System V Release 4
UNIX, and XPG4 (X/Open Portability Guide) curses (also known as XSI
curses). XSI stands for X/Open System Interfaces Extension. The
<STRONG>ncurses</STRONG> library is freely redistributable in source form. Differences
- from the SVr4 curses are summarized under the <STRONG>EXTENSIONS</STRONG> and <STRONG>PORTABIL-</STRONG>
- <STRONG>ITY</STRONG> sections below and described in detail in the respective <STRONG>EXTEN-</STRONG>
- <STRONG>SIONS</STRONG>, <STRONG>PORTABILITY</STRONG> and <STRONG>BUGS</STRONG> sections of individual man pages.
+ from the SVr4 curses are summarized under the <STRONG>EXTENSIONS</STRONG> and
+ <STRONG>PORTABILITY</STRONG> sections below and described in detail in the respective
+ <STRONG>EXTENSIONS</STRONG>, <STRONG>PORTABILITY</STRONG> and <STRONG>BUGS</STRONG> sections of individual man pages.
- The <STRONG>ncurses</STRONG> library also provides many useful extensions, i.e., fea-
- tures which cannot be implemented by a simple add-on library but which
- require access to the internals of the library.
+ The <STRONG>ncurses</STRONG> library also provides many useful extensions, i.e.,
+ features which cannot be implemented by a simple add-on library but
+ which require access to the internals of the library.
A program using these routines must be linked with the <STRONG>-lncurses</STRONG>
option, or (if it has been generated) with the debugging library
directory) that describe curses actions. See also the section on
<STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>.
- The <STRONG>ncurses</STRONG> package supports: overall screen, window and pad manipula-
- tion; output to windows and pads; reading terminal input; control over
- terminal and <STRONG>curses</STRONG> input and output options; environment query rou-
- tines; color manipulation; use of soft label keys; terminfo capabili-
- ties; and access to low-level terminal-manipulation routines.
+ The <STRONG>ncurses</STRONG> package supports: overall screen, window and pad
+ manipulation; output to windows and pads; reading terminal input;
+ control over terminal and <STRONG>curses</STRONG> input and output options; environment
+ query routines; color manipulation; use of soft label keys; terminfo
+ capabilities; and access to low-level terminal-manipulation routines.
</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
The function <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> must be called to initialize the
library before any of the other routines that deal with windows and
- screens are used. The routine <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> must be called before exit-
- ing.
+ screens are used. The routine <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> must be called before
+ exiting.
To get character-at-a-time input without echoing (most interactive,
screen oriented programs want this), the following sequence should be
Before a <STRONG>curses</STRONG> program is run, the tab stops of the terminal should be
set and its initialization strings, if defined, must be output. This
- can be done by executing the <STRONG>tput</STRONG> <STRONG>init</STRONG> command after the shell environ-
- ment variable <STRONG>TERM</STRONG> has been exported. <STRONG>tset(1)</STRONG> is usually responsible
- for doing this. [See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for further details.]
+ can be done by executing the <STRONG>tput</STRONG> <STRONG>init</STRONG> command after the shell
+ environment variable <STRONG>TERM</STRONG> has been exported. <STRONG>tset(1)</STRONG> is usually
+
responsible for doing this. [See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for further details.]
</PRE><H3><a name="h3-Datatypes">Datatypes</a></H3><PRE>
The <STRONG>ncurses</STRONG> library permits manipulation of data structures, called
- <EM>windows</EM>, which can be thought of as two-dimensional arrays of charac-
- ters representing all or part of a CRT screen. A default window called
- <STRONG>stdscr</STRONG>, which is the size of the terminal screen, is supplied. Others
- may be created with <STRONG>newwin</STRONG>.
+ <EM>windows</EM>, which can be thought of as two-dimensional arrays of
+ characters representing all or part of a CRT screen. A default window
+ called <STRONG>stdscr</STRONG>, which is the size of the terminal screen, is supplied.
+ Others may be created with <STRONG>newwin</STRONG>.
Note that <STRONG>curses</STRONG> does not handle overlapping windows, that's done by
the <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG> library. This means that you can either use <STRONG>stdscr</STRONG> or
- divide the screen into tiled windows and not using <STRONG>stdscr</STRONG> at all. Mix-
- ing the two will result in unpredictable, and undesired, effects.
+ divide the screen into tiled windows and not using <STRONG>stdscr</STRONG> at all.
+ Mixing the two will result in unpredictable, and undesired, effects.
Windows are referred to by variables declared as <STRONG>WINDOW</STRONG> <STRONG>*</STRONG>. These data
structures are manipulated with routines described here and elsewhere
Special windows called <EM>pads</EM> may also be manipulated. These are windows
which are not constrained to the size of the screen and whose contents
- need not be completely displayed. See <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> for more informa-
- tion.
+ need not be completely displayed. See <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> for more
+ information.
In addition to drawing characters on the screen, video attributes and
colors may be supported, causing the characters to show up in such
modes as underlined, in reverse video, or in color on terminals that
support such display enhancements. Line drawing characters may be
specified to be output. On input, <STRONG>curses</STRONG> is also able to translate
- arrow and function keys that transmit escape sequences into single val-
- ues. The video attributes, line drawing characters, and input values
- use names, defined in <STRONG><curses.h></STRONG>, such as <STRONG>A_REVERSE</STRONG>, <STRONG>ACS_HLINE</STRONG>, and
- <STRONG>KEY_LEFT</STRONG>.
+ arrow and function keys that transmit escape sequences into single
+ values. The video attributes, line drawing characters, and input
+ values use names, defined in <STRONG><curses.h></STRONG>, such as <STRONG>A_REVERSE</STRONG>, <STRONG>ACS_HLINE</STRONG>,
+ and <STRONG>KEY_LEFT</STRONG>.
</PRE><H3><a name="h3-Environment-variables">Environment variables</a></H3><PRE>
- If the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> are set, or if the pro-
- gram is executing in a window environment, line and column information
- in the environment will override information read by <EM>terminfo</EM>. This
- would affect a program running in an AT&T 630 layer, for example, where
- the size of a screen is changeable (see <STRONG>ENVIRONMENT</STRONG>).
-
- If the environment variable <STRONG>TERMINFO</STRONG> is defined, any program using
- <STRONG>curses</STRONG> checks for a local terminal definition before checking in the
- standard place. For example, if <STRONG>TERM</STRONG> is set to <STRONG>att4424</STRONG>, then the com-
- piled terminal definition is found in
-
- <STRONG>/usr/local/ncurses/lib/terminfo/a/att4424</STRONG>.
-
- (The <STRONG>a</STRONG> is copied from the first letter of <STRONG>att4424</STRONG> to avoid creation of
- huge directories.) However, if <STRONG>TERMINFO</STRONG> is set to <STRONG>$HOME/myterms</STRONG>,
+ If the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> are set, or if the
+ program is executing in a window environment, line and column
+ information in the environment will override information read by
+ <EM>terminfo</EM>. This would affect a program running in an AT&T 630 layer,
+ for example, where the size of a screen is changeable (see
+ <STRONG>ENVIRONMENT</STRONG>).
+
+ If the environment variable <STRONG>TERMINFO</STRONG> is defined, any program using
+ <STRONG>curses</STRONG> checks for a local terminal definition before checking in the
+ standard place. For example, if <STRONG>TERM</STRONG> is set to <STRONG>att4424</STRONG>, then the
+ compiled terminal definition is found in
+
+ <STRONG>/usr/share/terminfo/a/att4424</STRONG>.
+
+ (The <STRONG>a</STRONG> is copied from the first letter of <STRONG>att4424</STRONG> to avoid creation of
+ huge directories.) However, if <STRONG>TERMINFO</STRONG> is set to <STRONG>$HOME/myterms</STRONG>,
<STRONG>curses</STRONG> first checks
<STRONG>$HOME/myterms/a/att4424</STRONG>,
and if that fails, it then checks
- <STRONG>/usr/local/ncurses/lib/terminfo/a/att4424</STRONG>.
+ <STRONG>/usr/share/terminfo/a/att4424</STRONG>.
- This is useful for developing experimental definitions or when write
- permission in <STRONG>/usr/local/ncurses/lib/terminfo</STRONG> is not available.
+ This is useful for developing experimental definitions or when write
+ permission in <STRONG>/usr/share/terminfo</STRONG> is not available.
The integer variables <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG> are defined in <STRONG><curses.h></STRONG> and will
- be filled in by <STRONG>initscr</STRONG> with the size of the screen. The constants
+ be filled in by <STRONG>initscr</STRONG> with the size of the screen. The constants
<STRONG>TRUE</STRONG> and <STRONG>FALSE</STRONG> have the values <STRONG>1</STRONG> and <STRONG>0</STRONG>, respectively.
- The <STRONG>curses</STRONG> routines also define the <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> variable <STRONG>curscr</STRONG> which is
- used for certain low-level operations like clearing and redrawing a
- screen containing garbage. The <STRONG>curscr</STRONG> can be used in only a few rou-
- tines.
+ The <STRONG>curses</STRONG> routines also define the <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> variable <STRONG>curscr</STRONG> which is
+ used for certain low-level operations like clearing and redrawing a
+ screen containing garbage. The <STRONG>curscr</STRONG> can be used in only a few
+ routines.
</PRE><H3><a name="h3-Routine-and-Argument-Names">Routine and Argument Names</a></H3><PRE>
- Many <STRONG>curses</STRONG> routines have two or more versions. The routines prefixed
+ Many <STRONG>curses</STRONG> routines have two or more versions. The routines prefixed
with <STRONG>w</STRONG> require a window argument. The routines prefixed with <STRONG>p</STRONG> require
a pad argument. Those without a prefix generally use <STRONG>stdscr</STRONG>.
- The routines prefixed with <STRONG>mv</STRONG> require a <EM>y</EM> and <EM>x</EM> coordinate to move to
+ The routines prefixed with <STRONG>mv</STRONG> require a <EM>y</EM> and <EM>x</EM> coordinate to move to
before performing the appropriate action. The <STRONG>mv</STRONG> routines imply a call
- to <STRONG>move</STRONG> before the call to the other routine. The coordinate <EM>y</EM> always
- refers to the row (of the window), and <EM>x</EM> always refers to the column.
+ to <STRONG>move</STRONG> before the call to the other routine. The coordinate <EM>y</EM> always
+ refers to the row (of the window), and <EM>x</EM> always refers to the column.
The upper left-hand corner is always (0,0), not (1,1).
- The routines prefixed with <STRONG>mvw</STRONG> take both a window argument and <EM>x</EM> and <EM>y</EM>
- coordinates. The window argument is always specified before the coor-
- dinates.
+ The routines prefixed with <STRONG>mvw</STRONG> take both a window argument and <EM>x</EM> and <EM>y</EM>
+ coordinates. The window argument is always specified before the
+ coordinates.
- In each case, <EM>win</EM> is the window affected, and <EM>pad</EM> is the pad affected;
+ In each case, <EM>win</EM> is the window affected, and <EM>pad</EM> is the pad affected;
<EM>win</EM> and <EM>pad</EM> are always pointers to type <STRONG>WINDOW</STRONG>.
- Option setting routines require a Boolean flag <EM>bf</EM> with the value <STRONG>TRUE</STRONG>
- or <STRONG>FALSE</STRONG>; <EM>bf</EM> is always of type <STRONG>bool</STRONG>. Most of the data types used in
- the library routines, such as <STRONG>WINDOW</STRONG>, <STRONG>SCREEN</STRONG>, <STRONG>bool</STRONG>, and <STRONG>chtype</STRONG> are
- defined in <STRONG><curses.h></STRONG>. Types used for the terminfo routines such as
+ Option setting routines require a Boolean flag <EM>bf</EM> with the value <STRONG>TRUE</STRONG>
+ or <STRONG>FALSE</STRONG>; <EM>bf</EM> is always of type <STRONG>bool</STRONG>. Most of the data types used in
+ the library routines, such as <STRONG>WINDOW</STRONG>, <STRONG>SCREEN</STRONG>, <STRONG>bool</STRONG>, and <STRONG>chtype</STRONG> are
+ defined in <STRONG><curses.h></STRONG>. Types used for the terminfo routines such as
<STRONG>TERMINAL</STRONG> are defined in <STRONG><term.h></STRONG>.
- This manual page describes functions which may appear in any configura-
- tion of the library. There are two common configurations of the
- library:
+ This manual page describes functions which may appear in any
+ configuration of the library. There are two common configurations of
+ the library:
<EM>ncurses</EM>
- the "normal" library, which handles 8-bit characters. The nor-
- mal (8-bit) library stores characters combined with attributes
- in <STRONG>chtype</STRONG> data.
+ the "normal" library, which handles 8-bit characters. The
+ normal (8-bit) library stores characters combined with
+ attributes in <STRONG>chtype</STRONG> data.
- Attributes alone (no corresponding character) may be stored in
+ Attributes alone (no corresponding character) may be stored in
<STRONG>chtype</STRONG> or the equivalent <STRONG>attr_t</STRONG> data. In either case, the data
is stored in something like an integer.
Each cell (row and column) in a <STRONG>WINDOW</STRONG> is stored as a <STRONG>chtype</STRONG>.
<EM>ncursesw</EM>
- the so-called "wide" library, which handles multibyte charac-
- ters (see the section on <STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>). The "wide"
- library includes all of the calls from the "normal" library.
- It adds about one third more calls using data types which store
- multibyte characters:
+ the so-called "wide" library, which handles multibyte
+ characters (see the section on <STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>). The
+ "wide" library includes all of the calls from the "normal"
+ library. It adds about one third more calls using data types
+ which store multibyte characters:
<STRONG>cchar_t</STRONG>
corresponds to <STRONG>chtype</STRONG>. However it is a structure, because
- more data is stored than can fit into an integer. The
- characters are large enough to require a full integer
+ more data is stored than can fit into an integer. The
+ characters are large enough to require a full integer
value - and there may be more than one character per cell.
- The video attributes and color are stored in separate
+ The video attributes and color are stored in separate
fields of the structure.
- Each cell (row and column) in a <STRONG>WINDOW</STRONG> is stored as a
+ Each cell (row and column) in a <STRONG>WINDOW</STRONG> is stored as a
<STRONG>cchar_t</STRONG>.
- The <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> functions store and
+ The <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> functions store and
retrieve the data from a <STRONG>cchar_t</STRONG> structure.
<STRONG>wchar_t</STRONG>
- stores a "wide" character. Like <STRONG>chtype</STRONG>, this may be an
+ stores a "wide" character. Like <STRONG>chtype</STRONG>, this may be an
integer.
<STRONG>wint_t</STRONG>
- stores a <STRONG>wchar_t</STRONG> or <STRONG>WEOF</STRONG> - not the same, though both may
+ stores a <STRONG>wchar_t</STRONG> or <STRONG>WEOF</STRONG> - not the same, though both may
have the same size.
- The "wide" library provides new functions which are analogous
- to functions in the "normal" library. There is a naming con-
- vention which relates many of the normal/wide variants: a "_w"
- is inserted into the name. For example, <STRONG>waddch</STRONG> becomes
+ The "wide" library provides new functions which are analogous
+ to functions in the "normal" library. There is a naming
+ convention which relates many of the normal/wide variants: a
+ "_w" is inserted into the name. For example, <STRONG>waddch</STRONG> becomes
<STRONG>wadd_wch</STRONG>.
</PRE><H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE>
- The following table lists the <STRONG>curses</STRONG> routines provided in the "normal"
- and "wide" libraries and the names of the manual pages on which they
- are described. Routines flagged with "*" are ncurses-specific, not
+ The following table lists the <STRONG>curses</STRONG> routines provided in the "normal"
+ and "wide" libraries and the names of the manual pages on which they
+ are described. Routines flagged with "*" are ncurses-specific, not
described by XPG4 or present in SVr4.
<STRONG>curses</STRONG> Routine Name Manual Page Name
bkgrnd <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
bkgrndset <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
border <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
- border_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
+ border_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
box <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
box_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
can_change_color <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
getnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
getparx <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
getpary <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
- getparyx <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
+ getparyx <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
getstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
getsyx <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
getwin <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
killchar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
killwchar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
leaveok <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
- longname <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
+ longname <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
mcprint <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>*
meta <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
mouse_trafo <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>*
mvwget_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
mvwgetch <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
mvwgetn_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
- mvwgetnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
+ mvwgetnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
mvwgetstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
mvwhline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
mvwhline_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
scr_dump <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
scr_init <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
scr_restore <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
- scr_set <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
+ scr_set <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
scrl <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
scroll <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
scrollok <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
use_legacy_coding <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>*
use_tioctl <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>*
vid_attr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
- vid_puts <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
+ vid_puts <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
vidattr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
vidputs <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
vline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
winnstr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
winnwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
wins_nwstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
- wins_wch <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>
+ wins_wch <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>
wins_wstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
winsch <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG>
winsdelln <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(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>
- Depending on the configuration, additional sets of functions may be
+ Depending on the configuration, additional sets of functions may be
available:
<STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG> - curses memory-leak checking
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- Routines that return an integer return <STRONG>ERR</STRONG> upon failure and an integer
+ Routines that return an integer return <STRONG>ERR</STRONG> upon failure and an integer
value other than <STRONG>ERR</STRONG> upon successful completion, unless otherwise noted
in the routine descriptions.
- As a general rule, routines check for null pointers passed as parame-
- ters, and handle this as an error.
+ As a general rule, routines check for null pointers passed as
+ parameters, and handle this as an error.
- All macros return the value of the <STRONG>w</STRONG> version, except <STRONG>setscrreg</STRONG>,
- <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG>. The return values of
- <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG> are undefined
- (i.e., these should not be used as the right-hand side of assignment
+ All macros return the value of the <STRONG>w</STRONG> version, except <STRONG>setscrreg</STRONG>,
+ <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG>. The return values of
+ <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, <STRONG>getyx</STRONG>, <STRONG>getbegyx</STRONG>, and <STRONG>getmaxyx</STRONG> are undefined
+ (i.e., these should not be used as the right-hand side of assignment
statements).
- Functions with a "mv" prefix first perform a cursor movement using
+ Functions with a "mv" prefix first perform a cursor movement using
<STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
- the window pointer is null. Most "mv"-prefixed functions (except vari-
- adic functions such as <STRONG>mvprintw</STRONG>) are provided both as macros and func-
- tions.
+ the window pointer is null. Most "mv"-prefixed functions (except
+ variadic functions such as <STRONG>mvprintw</STRONG>) are provided both as macros and
+ functions.
Routines that return pointers return <STRONG>NULL</STRONG> on error.
</PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE>
- The following environment symbols are useful for customizing the run-
- time behavior of the <STRONG>ncurses</STRONG> library. The most important ones have
+ The following environment symbols are useful for customizing the
+ runtime behavior of the <STRONG>ncurses</STRONG> library. The most important ones have
been already discussed in detail.
</PRE><H3><a name="h3-CC-command-character">CC command-character</a></H3><PRE>
- When set, change occurrences of the command_character (i.e., the <STRONG>cmdch</STRONG>
- capability) of the loaded terminfo entries to the value of this vari-
- able. Very few terminfo entries provide this feature.
+ When set, change occurrences of the command_character (i.e., the <STRONG>cmdch</STRONG>
+ capability) of the loaded terminfo entries to the value of this
+ variable. Very few terminfo entries provide this feature.
Because this name is also used in development environments to represent
the C compiler's name, <STRONG>ncurses</STRONG> ignores it if it does not happen to be a
</PRE><H3><a name="h3-BAUDRATE">BAUDRATE</a></H3><PRE>
- The debugging library checks this environment variable when the appli-
- cation has redirected output to a file. The variable's numeric value
- is used for the baudrate. If no value is found, <STRONG>ncurses</STRONG> uses 9600.
- This allows testers to construct repeatable test-cases that take into
- account costs that depend on baudrate.
+ The debugging library checks this environment variable when the
+ application has redirected output to a file. The variable's numeric
+ value is used for the baudrate. If no value is found, <STRONG>ncurses</STRONG> uses
+ 9600. This allows testers to construct repeatable test-cases that take
+ into account costs that depend on baudrate.
</PRE><H3><a name="h3-COLUMNS">COLUMNS</a></H3><PRE>
Specify the width of the screen in characters. Applications running in
- a windowing environment usually are able to obtain the width of the
- window in which they are executing. If neither the <STRONG>COLUMNS</STRONG> value nor
- the terminal's screen size is available, <STRONG>ncurses</STRONG> uses the size which
+ a windowing environment usually are able to obtain the width of the
+ window in which they are executing. If neither the <STRONG>COLUMNS</STRONG> value nor
+ the terminal's screen size is available, <STRONG>ncurses</STRONG> uses the size which
may be specified in the terminfo database (i.e., the <STRONG>cols</STRONG> capability).
- It is important that your application use a correct size for the
- screen. This is not always possible because your application may be
- running on a host which does not honor NAWS (Negotiations About Window
- Size), or because you are temporarily running as another user. How-
- ever, setting <STRONG>COLUMNS</STRONG> and/or <STRONG>LINES</STRONG> overrides the library's use of the
- screen size obtained from the operating system.
+ It is important that your application use a correct size for the
+ screen. This is not always possible because your application may be
+ running on a host which does not honor NAWS (Negotiations About Window
+ Size), or because you are temporarily running as another user.
+ However, setting <STRONG>COLUMNS</STRONG> and/or <STRONG>LINES</STRONG> overrides the library's use of
+ the screen size obtained from the operating system.
- Either <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> symbols may be specified independently. This
- is mainly useful to circumvent legacy misfeatures of terminal descrip-
- tions, e.g., xterm which commonly specifies a 65 line screen. For best
- results, <STRONG>lines</STRONG> and <STRONG>cols</STRONG> should not be specified in a terminal descrip-
- tion for terminals which are run as emulations.
+ Either <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> symbols may be specified independently. This
+ is mainly useful to circumvent legacy misfeatures of terminal
+ descriptions, e.g., xterm which commonly specifies a 65 line screen.
+ For best results, <STRONG>lines</STRONG> and <STRONG>cols</STRONG> should not be specified in a terminal
+ description for terminals which are run as emulations.
- Use the <STRONG>use_env</STRONG> function to disable all use of external environment
+ Use the <STRONG>use_env</STRONG> function to disable all use of external environment
(but not including system calls) to determine the screen size. Use the
<STRONG>use_tioctl</STRONG> function to update <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> to match the screen size
obtained from system calls or the terminal database.
</PRE><H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
Specifies the total time, in milliseconds, for which ncurses will await
- a character sequence, e.g., a function key. The default value, 1000
- milliseconds, is enough for most uses. However, it is made a variable
+ a character sequence, e.g., a function key. The default value, 1000
+ milliseconds, is enough for most uses. However, it is made a variable
to accommodate unusual applications.
- The most common instance where you may wish to change this value is to
- work with slow hosts, e.g., running on a network. If the host cannot
- read characters rapidly enough, it will have the same effect as if the
- terminal did not send characters rapidly enough. The library will
+ The most common instance where you may wish to change this value is to
+ work with slow hosts, e.g., running on a network. If the host cannot
+ read characters rapidly enough, it will have the same effect as if the
+ terminal did not send characters rapidly enough. The library will
still see a timeout.
- Note that xterm mouse events are built up from character sequences
- received from the xterm. If your application makes heavy use of multi-
- ple-clicking, you may wish to lengthen this default value because the
- timeout applies to the composed multi-click event as well as the indi-
- vidual clicks.
+ Note that xterm mouse events are built up from character sequences
+ received from the xterm. If your application makes heavy use of
+ multiple-clicking, you may wish to lengthen this default value because
+ the timeout applies to the composed multi-click event as well as the
+ individual clicks.
In addition to the environment variable, this implementation provides a
- global variable with the same name. Portable applications should not
- rely upon the presence of ESCDELAY in either form, but setting the
- environment variable rather than the global variable does not create
+ global variable with the same name. Portable applications should not
+ rely upon the presence of ESCDELAY in either form, but setting the
+ environment variable rather than the global variable does not create
problems when compiling an application.
</PRE><H3><a name="h3-HOME">HOME</a></H3><PRE>
- Tells <STRONG>ncurses</STRONG> where your home directory is. That is where it may read
+ Tells <STRONG>ncurses</STRONG> where your home directory is. That is where it may read
and write auxiliary terminal descriptions:
$HOME/.termcap
</PRE><H3><a name="h3-LINES">LINES</a></H3><PRE>
- Like COLUMNS, specify the height of the screen in characters. See COL-
- UMNS for a detailed description.
+ Like COLUMNS, specify the height of the screen in characters. See
+ COLUMNS for a detailed description.
</PRE><H3><a name="h3-MOUSE_BUTTONS_123">MOUSE_BUTTONS_123</a></H3><PRE>
- This applies only to the OS/2 EMX port. It specifies the order of but-
- tons on the mouse. OS/2 numbers a 3-button mouse inconsistently from
- other platforms:
+ This applies only to the OS/2 EMX port. It specifies the order of
+ buttons on the mouse. OS/2 numbers a 3-button mouse inconsistently
+ from other platforms:
1 = left
2 = right
3 = middle.
This variable lets you customize the mouse. The variable must be three
- numeric digits 1-3 in any order, e.g., 123 or 321. If it is not speci-
- fied, <STRONG>ncurses</STRONG> uses 132.
+ numeric digits 1-3 in any order, e.g., 123 or 321. If it is not
+ specified, <STRONG>ncurses</STRONG> uses 132.
</PRE><H3><a name="h3-NCURSES_ASSUMED_COLORS">NCURSES_ASSUMED_COLORS</a></H3><PRE>
- Override the 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>). You may set the fore-
- ground and background color values with this environment variable by
- proving a 2-element list: foreground,background. For example, to tell
- ncurses to not assume anything about the colors, set this to "-1,-1".
- To make it green-on-black, set it to "2,0". Any positive value from
- zero to the terminfo <STRONG>max_colors</STRONG> value is allowed.
+ Override the 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>). You may set the
+ foreground and background color values with this environment variable
+ by proving a 2-element list: foreground,background. For example, to
+ tell ncurses to not assume anything about the colors, set this to
+ "-1,-1". To make it green-on-black, set it to "2,0". Any positive
+ value from zero to the terminfo <STRONG>max_colors</STRONG> value is allowed.
</PRE><H3><a name="h3-NCURSES_CONSOLE2">NCURSES_CONSOLE2</a></H3><PRE>
This applies only to the MinGW port of ncurses.
- The <STRONG>Console2</STRONG> program's handling of the Microsoft Console API call <STRONG>Cre-</STRONG>
- <STRONG>ateConsoleScreenBuffer</STRONG> is defective. Applications which use this 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 <STRONG>NCGDB</STRONG> has the same
+ The <STRONG>Console2</STRONG> program's handling of the Microsoft Console API call
+ <STRONG>CreateConsoleScreenBuffer</STRONG> is defective. Applications which use this
+ 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 <STRONG>NCGDB</STRONG> has the same
effect.
</PRE><H3><a name="h3-NCURSES_GPM_TERMS">NCURSES_GPM_TERMS</a></H3><PRE>
This applies only to ncurses configured to use the GPM interface.
- If present, the environment variable is a list of one or more terminal
- names against which the <STRONG>TERM</STRONG> environment variable is matched. Setting
- it to an empty value disables the GPM interface; using the built-in
+ If present, the environment variable is a list of one or more terminal
+ names against which the <STRONG>TERM</STRONG> environment variable is matched. Setting
+ it to an empty value disables the GPM interface; using the built-in
support for xterm, etc.
If the environment variable is absent, ncurses will attempt to open GPM
</PRE><H3><a name="h3-NCURSES_NO_HARD_TABS">NCURSES_NO_HARD_TABS</a></H3><PRE>
- <STRONG>Ncurses</STRONG> may use tabs as part of the cursor movement optimization. In
- some cases, your terminal driver may not handle these properly. Set
- this environment variable to disable the feature. You can also adjust
+ <STRONG>Ncurses</STRONG> may use tabs as part of the cursor movement optimization. In
+ some cases, your terminal driver may not handle these properly. Set
+ this environment variable to disable the feature. You can also adjust
your <STRONG>stty</STRONG> settings to avoid the problem.
</PRE><H3><a name="h3-NCURSES_NO_MAGIC_COOKIE">NCURSES_NO_MAGIC_COOKIE</a></H3><PRE>
- Some terminals use a magic-cookie feature which requires special han-
- dling to make highlighting and other video attributes display properly.
- You can suppress the highlighting entirely for these terminals by set-
- ting this environment variable.
+ Some terminals use a magic-cookie feature which requires special
+ handling to make highlighting and other video attributes display
+ properly. You can suppress the highlighting entirely for these
+ terminals by setting this environment variable.
</PRE><H3><a name="h3-NCURSES_NO_PADDING">NCURSES_NO_PADDING</a></H3><PRE>
- Most of the terminal descriptions in the terminfo database are written
- for real "hardware" terminals. Many people use terminal emulators
+ Most of the terminal descriptions in the terminfo database are written
+ for real "hardware" terminals. Many people use terminal emulators
which run in a windowing environment and use curses-based applications.
- Terminal emulators can duplicate all of the important aspects of a
- hardware terminal, but they do not have the same limitations. The
- chief limitation of a hardware terminal from the standpoint of your
- application is the management of dataflow, i.e., timing. Unless a
- hardware terminal is interfaced into a terminal concentrator (which
- does flow control), it (or your application) must manage dataflow, pre-
- venting overruns. The cheapest solution (no hardware cost) is for your
- program to do this by pausing after operations that the terminal does
- slowly, such as clearing the display.
-
- As a result, many terminal descriptions (including the vt100) have
- delay times embedded. You may wish to use these descriptions, but not
+ Terminal emulators can duplicate all of the important aspects of a
+ hardware terminal, but they do not have the same limitations. The
+ chief limitation of a hardware terminal from the standpoint of your
+ application is the management of dataflow, i.e., timing. Unless a
+ hardware terminal is interfaced into a terminal concentrator (which
+ does flow control), it (or your application) must manage dataflow,
+ preventing overruns. The cheapest solution (no hardware cost) is for
+ your program to do this by pausing after operations that the terminal
+ does slowly, such as clearing the display.
+
+ As a result, many terminal descriptions (including the vt100) have
+ delay times embedded. You may wish to use these descriptions, but not
want to pay the performance penalty.
- Set the NCURSES_NO_PADDING environment variable to disable all but
- mandatory padding. Mandatory padding is used as a part of special con-
- trol sequences such as <EM>flash</EM>.
+ Set the NCURSES_NO_PADDING environment variable to disable all but
+ mandatory padding. Mandatory padding is used as a part of special
+ control sequences such as <EM>flash</EM>.
</PRE><H3><a name="h3-NCURSES_NO_SETBUF">NCURSES_NO_SETBUF</a></H3><PRE>
<STRONG>o</STRONG> continued though 5.9 patch 20130126
- <STRONG>ncurses</STRONG> enabled buffered output during terminal initialization. This
- was done (as in SVr4 curses) for performance reasons. For testing pur-
- poses, both of <STRONG>ncurses</STRONG> and certain applications, this feature was made
- optional. Setting the NCURSES_NO_SETBUF variable disabled output
- buffering, leaving the output in the original (usually line buffered)
+ <STRONG>ncurses</STRONG> enabled buffered output during terminal initialization. This
+ was done (as in SVr4 curses) for performance reasons. For testing
+ purposes, both of <STRONG>ncurses</STRONG> and certain applications, this feature was
+ made optional. Setting the NCURSES_NO_SETBUF variable disabled output
+ buffering, leaving the output in the original (usually line buffered)
mode.
- In the current implementation, ncurses performs its own buffering and
- does not require this workaround. It does not modify the buffering of
+ In the current implementation, ncurses performs its own buffering and
+ does not require this workaround. It does not modify the buffering of
the standard output.
- The reason for the change was to make the behavior for interrupts and
- other signals more robust. One drawback is that certain nonconven-
- tional programs would mix ordinary stdio calls with ncurses calls and
- (usually) work. This is no longer possible since ncurses is not using
- the buffered standard output but its own output (to the same file
- descriptor). As a special case, the low-level calls such as <STRONG>putp</STRONG> still
- use the standard output. But high-level curses calls do not.
+ The reason for the change was to make the behavior for interrupts and
+ other signals more robust. One drawback is that certain
+ nonconventional programs would mix ordinary stdio calls with ncurses
+ calls and (usually) work. This is no longer possible since ncurses is
+ not using the buffered standard output but its own output (to the same
+ file descriptor). As a special case, the low-level calls such as <STRONG>putp</STRONG>
+ still use the standard output. But high-level curses calls do not.
</PRE><H3><a name="h3-NCURSES_NO_UTF8_ACS">NCURSES_NO_UTF8_ACS</a></H3><PRE>
- During initialization, the <STRONG>ncurses</STRONG> library checks for special cases
+ During initialization, the <STRONG>ncurses</STRONG> library checks for special cases
where VT100 line-drawing (and the corresponding alternate character set
- capabilities) described in the terminfo are known to be missing.
- Specifically, when running in a UTF-8 locale, the Linux console emula-
- tor and the GNU screen program ignore these. Ncurses checks the <STRONG>TERM</STRONG>
- environment variable for these. For other special cases, you should
- set this environment variable. Doing this tells ncurses to use Unicode
- values which correspond to the VT100 line-drawing glyphs. That works
- for the special cases cited, and is likely to work for terminal emula-
- tors.
-
- When setting this variable, you should set it to a nonzero value. Set-
- ting it to zero (or to a nonnumber) disables the special check for
+ capabilities) described in the terminfo are known to be missing.
+ Specifically, when running in a UTF-8 locale, the Linux console
+ emulator and the GNU screen program ignore these. Ncurses checks the
+ <STRONG>TERM</STRONG> environment variable for these. For other special cases, you
+ should set this environment variable. Doing this tells ncurses to use
+ Unicode values which correspond to the VT100 line-drawing glyphs. That
+ works for the special cases cited, and is likely to work for terminal
+ emulators.
+
+ When setting this variable, you should set it to a nonzero value.
+ Setting it to zero (or to a nonnumber) disables the special check for
"linux" and "screen".
- As an alternative to the environment variable, ncurses checks for an
- extended terminfo capability <STRONG>U8</STRONG>. This is a numeric capability which
+ As an alternative to the environment variable, ncurses checks for an
+ extended terminfo capability <STRONG>U8</STRONG>. This is a numeric capability which
can be compiled using <STRONG>tic</STRONG> <STRONG>-x</STRONG>. For example
# linux console, if patched to provide working
xterm-utf8|xterm relying on UTF-8 line-graphics,
U8#1, use=xterm,
- The name "U8" is chosen to be two characters, to permit it to be used
+ The name "U8" is chosen to be two characters, to permit it to be used
by applications that use ncurses' termcap interface.
</PRE><H3><a name="h3-NCURSES_TRACE">NCURSES_TRACE</a></H3><PRE>
- During initialization, the <STRONG>ncurses</STRONG> debugging library checks the
- NCURSES_TRACE environment variable. If it is defined, to a numeric
- value, <STRONG>ncurses</STRONG> calls the <STRONG>trace</STRONG> function, using that value as the argu-
- ment.
+ During initialization, the <STRONG>ncurses</STRONG> debugging library checks the
+ NCURSES_TRACE environment variable. If it is defined, to a numeric
+ value, <STRONG>ncurses</STRONG> calls the <STRONG>trace</STRONG> function, using that value as the
+ argument.
- The argument values, which are defined in <STRONG>curses.h</STRONG>, provide several
- types of information. When running with traces enabled, your applica-
- tion will write the file <STRONG>trace</STRONG> to the current directory.
+ The argument values, which are defined in <STRONG>curses.h</STRONG>, provide several
+ types of information. When running with traces enabled, your
+ application will write the file <STRONG>trace</STRONG> to the current directory.
See <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> for more information.
</PRE><H3><a name="h3-TERM">TERM</a></H3><PRE>
- Denotes your terminal type. Each terminal type is distinct, though
+ Denotes your terminal type. Each terminal type is distinct, though
many are similar.
- <STRONG>TERM</STRONG> is commonly set by terminal emulators to help applications find a
- workable terminal description. Some of those choose a popular approxi-
- mation, e.g., "ansi", "vt100", "xterm" rather than an exact fit. Not
- infrequently, your application will have problems with that approach,
- e.g., incorrect function-key definitions.
-
- If you set <STRONG>TERM</STRONG> in your environment, it has no effect on the operation
- of the terminal emulator. It only affects the way applications work
- within the terminal. Likewise, as a general rule (<STRONG>xterm</STRONG> being a rare
- exception), terminal emulators which allow you to specify <STRONG>TERM</STRONG> as a
- parameter or configuration value do not change their behavior to match
+ <STRONG>TERM</STRONG> is commonly set by terminal emulators to help applications find a
+ workable terminal description. Some of those choose a popular
+ approximation, e.g., "ansi", "vt100", "xterm" rather than an exact fit.
+ Not infrequently, your application will have problems with that
+ approach, e.g., incorrect function-key definitions.
+
+ If you set <STRONG>TERM</STRONG> in your environment, it has no effect on the operation
+ of the terminal emulator. It only affects the way applications work
+ within the terminal. Likewise, as a general rule (<STRONG>xterm</STRONG> being a rare
+ exception), terminal emulators which allow you to specify <STRONG>TERM</STRONG> as a
+ parameter or configuration value do not change their behavior to match
that setting.
</PRE><H3><a name="h3-TERMCAP">TERMCAP</a></H3><PRE>
- If the <STRONG>ncurses</STRONG> library has been configured with <EM>termcap</EM> support,
- <STRONG>ncurses</STRONG> will check for a terminal's description in termcap form if it
+ If the <STRONG>ncurses</STRONG> library has been configured with <EM>termcap</EM> support,
+ <STRONG>ncurses</STRONG> will check for a terminal's description in termcap form if it
is not available in the terminfo database.
The <STRONG>TERMCAP</STRONG> environment variable contains either a terminal description
- (with newlines stripped out), or a file name telling where the informa-
- tion denoted by the <STRONG>TERM</STRONG> environment variable exists. In either case,
- setting it directs <STRONG>ncurses</STRONG> to ignore the usual place for this informa-
- tion, e.g., /etc/termcap.
+ (with newlines stripped out), or a file name telling where the
+ information denoted by the <STRONG>TERM</STRONG> environment variable exists. In either
+ case, setting it directs <STRONG>ncurses</STRONG> to ignore the usual place for this
+ information, e.g., /etc/termcap.
</PRE><H3><a name="h3-TERMINFO">TERMINFO</a></H3><PRE>
- <STRONG>ncurses</STRONG> can be configured to read from multiple terminal databases.
- The <STRONG>TERMINFO</STRONG> variable overrides the location for the default terminal
- database. Terminal descriptions (in terminal format) are stored in
+ <STRONG>ncurses</STRONG> can be configured to read from multiple terminal databases.
+ The <STRONG>TERMINFO</STRONG> variable overrides the location for the default terminal
+ database. Terminal descriptions (in terminal format) are stored in
terminal databases:
<STRONG>o</STRONG> Normally these are stored in a directory tree, using subdirectories
named by the first letter of the terminal names therein.
This is the scheme used in System V, which legacy Unix systems use,
- and the <STRONG>TERMINFO</STRONG> variable is used by <EM>curses</EM> applications on those
+ and the <STRONG>TERMINFO</STRONG> variable is used by <EM>curses</EM> applications on those
systems to override the default location of the terminal database.
- <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built to use hashed databases, then each entry in
+ <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built to use hashed databases, then each entry in
this list may be the path of a hashed database file, e.g.,
/usr/share/terminfo.db
/usr/share/terminfo/
- 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, reading it directly rather 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, reading it directly rather than
using the terminfo library calls.
- <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built with a support for reading termcap files
- directly, then an entry in this list may be the path of a termcap
+ <STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built with a support for reading termcap files
+ directly, then an entry in this list may be the path of a termcap
file.
<STRONG>o</STRONG> If the <STRONG>TERMINFO</STRONG> variable begins with "hex:" or "b64:", <STRONG>ncurses</STRONG> uses
- the remainder of that variable as a compiled terminal description.
+ the remainder of that variable as a compiled terminal description.
You might produce the base64 format using <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>:
TERMINFO="$(infocmp -0 -Q2 -q)"
export TERMINFO
- The compiled description is used if it corresponds to the terminal
+ The compiled description is used if it corresponds to the terminal
identified by the <STRONG>TERM</STRONG> variable.
- Setting <STRONG>TERMINFO</STRONG> is the simplest, but not the only way to set location
- of the default terminal database. The complete list of database loca-
- tions in order follows:
+ Setting <STRONG>TERMINFO</STRONG> is the simplest, but not the only way to set location
+ of the default terminal database. The complete list of database
+ locations in order follows:
- <STRONG>o</STRONG> the last terminal database to which <STRONG>ncurses</STRONG> wrote, if any, is
+ <STRONG>o</STRONG> the last terminal database to which <STRONG>ncurses</STRONG> wrote, if any, is
searched first
<STRONG>o</STRONG> the location specified by the TERMINFO environment variable
<STRONG>o</STRONG> locations listed in the TERMINFO_DIRS environment variable
- <STRONG>o</STRONG> one or more locations whose names are configured and compiled
+ <STRONG>o</STRONG> one or more locations whose names are configured and compiled
into the ncurses library, i.e.,
- <STRONG>o</STRONG> /usr/local/ncurses/share/terminfo:/usr/share/terminfo (corre-
- sponding to the TERMINFO_DIRS variable)
+ <STRONG>o</STRONG> no default value (corresponding to the TERMINFO_DIRS
+ variable)
- <STRONG>o</STRONG> /usr/local/ncurses/lib/terminfo (corresponding to the TER-
- MINFO variable)
+ <STRONG>o</STRONG> /usr/share/terminfo (corresponding to the TERMINFO variable)
</PRE><H3><a name="h3-TERMINFO_DIRS">TERMINFO_DIRS</a></H3><PRE>
section on the <STRONG>TERMINFO</STRONG> variable. The list is separated by colons
(i.e., ":") on Unix, semicolons on OS/2 EMX.
- There is no corresponding feature in System V terminfo; it is an exten-
- sion developed for <STRONG>ncurses</STRONG>.
+ There is no corresponding feature in System V terminfo; it is an
+ extension developed for <STRONG>ncurses</STRONG>.
</PRE><H3><a name="h3-TERMPATH">TERMPATH</a></H3><PRE>
</PRE><H2><a name="h2-ALTERNATE-CONFIGURATIONS">ALTERNATE CONFIGURATIONS</a></H2><PRE>
- Several different configurations are possible, depending on the config-
- ure script options used when building <STRONG>ncurses</STRONG>. There are a few main
- options whose effects are visible to the applications developer using
- <STRONG>ncurses</STRONG>:
+ Several different configurations are possible, depending on the
+ configure script options used when building <STRONG>ncurses</STRONG>. There are a few
+ main options whose effects are visible to the applications developer
+ using <STRONG>ncurses</STRONG>:
--disable-overwrite
The standard include for <STRONG>ncurses</STRONG> is as noted in <STRONG>SYNOPSIS</STRONG>:
This option is used to avoid filename conflicts when <STRONG>ncurses</STRONG> is
not the main implementation of curses of the computer. If <STRONG>ncurses</STRONG>
- is installed disabling overwrite, it puts its headers in a subdi-
- rectory, e.g.,
+ is installed disabling overwrite, it puts its headers in a
+ subdirectory, e.g.,
<STRONG>#include</STRONG> <STRONG><ncurses/curses.h></STRONG>
<STRONG>-lcurses</STRONG> to build executables.
--enable-widec
- The configure script renames the library and (if the <STRONG>--dis-</STRONG>
- <STRONG>able-overwrite</STRONG> option is used) puts the header files in a differ-
- ent subdirectory. All of the library names have a "w" appended to
- them, i.e., instead of
+ The configure script renames the library and (if the
+ <STRONG>--disable-overwrite</STRONG> option is used) puts the header files in a
+ different subdirectory. All of the library names have a "w"
+ appended to them, i.e., instead of
<STRONG>-lncurses</STRONG>
header. Only the size of the <STRONG>WINDOW</STRONG> structure differs, and very
few applications require more than a pointer to <STRONG>WINDOW</STRONG>s.
- If the headers are installed allowing overwrite, the wide-charac-
- ter library's headers should be installed last, to allow applica-
- tions to be built using either library from the same set of head-
- ers.
+ If the headers are installed allowing overwrite, the wide-
+ character library's headers should be installed last, to allow
+ applications to be built using either library from the same set of
+ headers.
--with-pthread
The configure script renames the library. All of the library
--with-debug
--with-profile
- The shared and normal (static) library names differ by their suf-
- fixes, e.g., <STRONG>libncurses.so</STRONG> and <STRONG>libncurses.a</STRONG>. The debug and pro-
- filing libraries add a "_g" and a "_p" to the root names respec-
- tively, e.g., <STRONG>libncurses_g.a</STRONG> and <STRONG>libncurses_p.a</STRONG>.
+ The shared and normal (static) library names differ by their
+ suffixes, e.g., <STRONG>libncurses.so</STRONG> and <STRONG>libncurses.a</STRONG>. The debug and
+ profiling libraries add a "_g" and a "_p" to the root names
+ respectively, e.g., <STRONG>libncurses_g.a</STRONG> and <STRONG>libncurses_p.a</STRONG>.
--with-termlib
Low-level functions which do not depend upon whether the library
--with-trace
The <STRONG>trace</STRONG> function normally resides in the debug library, but it
- is sometimes useful to configure this in the shared library. Con-
- figure scripts should check for the function's existence rather
+ is sometimes useful to configure this in the shared library.
+ Configure scripts should check for the function's existence rather
than assuming it is always in the debug library.
</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
/usr/share/tabset
- directory containing initialization files for the terminal capa-
- bility database /usr/local/ncurses/lib/terminfo terminal capabil-
- ity database
+ directory containing initialization files for the terminal
+ capability database /usr/share/terminfo terminal capability
+ database
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
The <STRONG>ncurses</STRONG> library can be compiled with an option (<STRONG>-DUSE_GETCAP</STRONG>) that
falls back to the old-style /etc/termcap file if the terminal setup
code cannot find a terminfo entry corresponding to <STRONG>TERM</STRONG>. Use of this
- feature is not recommended, as it essentially includes an entire term-
- cap compiler in the <STRONG>ncurses</STRONG> startup code, at significant cost in core
- and startup cycles.
+ feature is not recommended, as it essentially includes an entire
+ termcap compiler in the <STRONG>ncurses</STRONG> startup code, at significant cost in
+ core and startup cycles.
The <STRONG>ncurses</STRONG> library includes facilities for capturing mouse events on
certain terminals (including xterm). See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual
page for details.
- The <STRONG>ncurses</STRONG> library includes facilities for responding to window resiz-
- ing events, e.g., when running in an xterm. See the <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> and
- <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual pages for details. In addition, the library may be
- configured with a <STRONG>SIGWINCH</STRONG> handler.
+ The <STRONG>ncurses</STRONG> library includes facilities for responding to window
+ resizing events, e.g., when running in an xterm. See the
+ <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> and <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual pages for details. In addition,
+ the library may be configured with a <STRONG>SIGWINCH</STRONG> handler.
The <STRONG>ncurses</STRONG> library extends the fixed set of function key capabilities
of terminals by allowing the application designer to define additional
The <STRONG>ncurses</STRONG> library can exploit the capabilities of terminals which
implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
- application to reset the terminal to its original foreground and back-
- ground colors. From the users' perspective, the application is able to
- draw colored text on a background whose color is set independently,
- providing better control over color contrasts. See the <STRONG>default_col-</STRONG>
- <STRONG><A HREF="default_colors.3x.html">ors(3x)</A></STRONG> manual page for details.
-
- The <STRONG>ncurses</STRONG> library includes a function for directing application out-
- put to a printer attached to the terminal device. See the
+ application to reset the terminal to its original foreground and
+ background colors. From the users' perspective, the application is
+ able to draw colored text on a background whose color is set
+ independently, providing better control over color contrasts. See the
+ <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> manual page for details.
+
+ The <STRONG>ncurses</STRONG> library includes a function for directing application
+ output to a printer attached to the terminal device. See the
<STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
The <STRONG>ncurses</STRONG> library is intended to be BASE-level conformant with XSI
- Curses. The EXTENDED XSI Curses functionality (including color sup-
- port) is supported.
+ Curses. The EXTENDED XSI Curses functionality (including color
+ support) is supported.
A small number of local differences (that is, individual differences
between the XSI Curses and <STRONG>ncurses</STRONG> calls) are described in <STRONG>PORTABILITY</STRONG>
In many cases, X/Open Curses is vague about error conditions, omitting
some of the SVr4 documentation.
- Unlike other implementations, this one checks parameters such as point-
- ers to WINDOW structures to ensure they are not null. The main reason
- for providing this behavior is to guard against programmer error. The
- standard interface does not provide a way for the library to tell an
- application which of several possible errors were detected. Relying on
- this (or some other) extension will adversely affect the portability of
- curses applications.
+ Unlike other implementations, this one checks parameters such as
+ pointers to WINDOW structures to ensure they are not null. The main
+ reason for providing this behavior is to guard against programmer
+ error. The standard interface does not provide a way for the library
+ to tell an application which of several possible errors were detected.
+ Relying on this (or some other) extension will adversely affect the
+ portability of curses applications.
</PRE><H3><a name="h3-Extensions-versus-portability">Extensions versus portability</a></H3><PRE>
are they present in SVr4. See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual page for
details.
- <STRONG>o</STRONG> The routine <STRONG>mcprint</STRONG> was not present in any previous curses imple-
- mentation. See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details.
+ <STRONG>o</STRONG> The routine <STRONG>mcprint</STRONG> was not present in any previous curses
+
implementation. See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details.
<STRONG>o</STRONG> The routine <STRONG>wresize</STRONG> is not part of XPG4, nor is it present in SVr4.
See the <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> manual page for details.
- <STRONG>o</STRONG> The WINDOW structure's internal details can be hidden from applica-
- tion programs. See <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> for the discussion of <STRONG>is_scrol-</STRONG>
- <STRONG>lok</STRONG>, etc.
+ <STRONG>o</STRONG> The WINDOW structure's internal details can be hidden from
+ application programs. See <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> for the discussion of
+ <STRONG>is_scrollok</STRONG>, etc.
- <STRONG>o</STRONG> This implementation can be configured to provide rudimentary sup-
-
port for multi-threaded applications. See <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> for
+ <STRONG>o</STRONG> This implementation can be configured to provide rudimentary
+
support for multi-threaded applications. See <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> for
details.
<STRONG>o</STRONG> This implementation can also be configured to provide a set of
In historic curses versions, delays embedded in the capabilities <STRONG>cr</STRONG>,
<STRONG>ind</STRONG>, <STRONG>cub1</STRONG>, <STRONG>ff</STRONG> and <STRONG>tab</STRONG> activated corresponding delay bits in the UNIX
tty driver. In this implementation, all padding is done by sending NUL
- bytes. This method is slightly more expensive, but narrows the inter-
- face to the UNIX kernel significantly and increases the package's
+ bytes. This method is slightly more expensive, but narrows the
+ interface to the UNIX kernel significantly and increases the package's
portability correspondingly.
As a result, standard <curses.h> will always include <stdio.h>.
- <STRONG>o</STRONG> X/Open Curses is inconsistent with respect to SVr4 regarding <unc-
- trl.h>.
+ <STRONG>o</STRONG> X/Open Curses is inconsistent with respect to SVr4 regarding
+ <unctrl.h>.
As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, ncurses includes <unctrl.h> from
<curses.h> (like SVr4).
For instance, in ncurses <wchar.h> <EM>may</EM> be included if the proper
symbol is defined, and if ncurses is configured for wide-character
- support. If the header is included, its symbols may be made visi-
- ble. That depends on the value used for <STRONG>_XOPEN_SOURCE</STRONG> feature test
- macro.
+ support. If the header is included, its symbols may be made
+ visible. That depends on the value used for <STRONG>_XOPEN_SOURCE</STRONG> feature
+ test macro.
<STRONG>o</STRONG> X/Open Curses documents one required header, in a special case:
<stdarg.h> before <curses.h> to prototype the <STRONG>vw_printw</STRONG> and
- <STRONG>vw_scanw</STRONG> functions (as well as the obsolete the <STRONG>vwprintw</STRONG> and <STRONG>vws-</STRONG>
- <STRONG>canw</STRONG> functions). Each of those uses a <STRONG>va_list</STRONG> parameter.
+ <STRONG>vw_scanw</STRONG> functions (as well as the obsolete the <STRONG>vwprintw</STRONG> and
+ <STRONG>vwscanw</STRONG> functions). Each of those uses a <STRONG>va_list</STRONG> parameter.
The two obsolete functions were introduced in SVr3. The other
functions were introduced in X/Open Curses. In between, SVr4
<STRONG>--terminfo</STRONG>
echos the $TERMINFO terminfo database path, e.g.,
- /usr/local/ncurses/lib/terminfo
+ /usr/share/terminfo
<STRONG>--terminfo-dirs</STRONG>
echos the $TERMINFO_DIRS directory list, e.g.,
- /usr/local/ncurses/share/terminfo:/usr/share/terminfo
+ /usr/share/terminfo
<STRONG>--termpath</STRONG>
- echos the $TERMPATH termcap list, if support for termcap is con-
- figured.
+ echos the $TERMPATH termcap list, if support for termcap is
+ configured.
<STRONG>--help</STRONG> prints this message
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>
- This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201212).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201219).
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
These functions are an extension to the curses library. They permit an
- application to dynamically allocate a color pair using the fore-
- ground/background colors rather than assign a fixed color pair number,
- and return an unused pair to the pool.
+ application to dynamically allocate a color pair using the
+ foreground/background colors rather than assign a fixed color pair
+ number, and return an unused pair to the pool.
The number of colors may be related to the number of possible color
pairs for a given terminal, or it may not:
- <STRONG>o</STRONG> While almost all terminals allow setting the color <EM>attributes</EM> inde-
- pendently, it is unlikely that your terminal allows you to modify
- the attributes of a given character cell without rewriting it.
- That is, the foreground and background colors are applied as a
+ <STRONG>o</STRONG> While almost all terminals allow setting the color <EM>attributes</EM>
+ independently, it is unlikely that your terminal allows you to
+ modify the attributes of a given character cell without rewriting
+ it. That is, the foreground and background colors are applied as a
pair.
- <STRONG>o</STRONG> Color pairs are the curses library's way of managing a color pal-
- ette on a terminal. If the library does not keep track of the <EM>com-</EM>
- <EM>binations</EM> of colors which are displayed, it will be inefficient.
+ <STRONG>o</STRONG> Color pairs are the curses library's way of managing a color
+ palette on a terminal. If the library does not keep track of the
+ <EM>combinations</EM> of colors which are displayed, it will be inefficient.
- <STRONG>o</STRONG> For simple terminal emulators with only a few dozen color combina-
- tions, it is convenient to use the maximum number of combinations
- as the limit on color pairs:
+ <STRONG>o</STRONG> For simple terminal emulators with only a few dozen color
+ combinations, it is convenient to use the maximum number of
+ combinations as the limit on color pairs:
<STRONG>COLORS</STRONG> <EM>*</EM> <STRONG>COLORS</STRONG>
a predefined color scheme.
Beyond that lies in the realm of programs using the foreground and
- background colors for "ASCII art" (or some other non-textual appli-
- cation).
+ background colors for "ASCII art" (or some other non-textual
+ application).
Also beyond those few dozen pairs, the required size for a table to
represent the combinations grows rapidly with an increasing number
</PRE><H3><a name="h3-alloc_pair">alloc_pair</a></H3><PRE>
- The <STRONG>alloc_pair</STRONG> function accepts parameters for foreground and back-
- ground color, and checks if that color combination is already associ-
- ated with a color pair.
+ The <STRONG>alloc_pair</STRONG> function accepts parameters for foreground and
+ background color, and checks if that color combination is already
+ associated with a color pair.
<STRONG>o</STRONG> If the combination already exists, <STRONG>alloc_pair</STRONG> returns the existing
pair.
<STRONG>o</STRONG> If the combination does not exist, <STRONG>alloc_pair</STRONG> allocates a new color
pair and returns that.
- <STRONG>o</STRONG> If the table fills up, <STRONG>alloc_pair</STRONG> discards the least-recently allo-
- cated entry using <STRONG>free_pair</STRONG> and allocates a new color pair.
+ <STRONG>o</STRONG> If the table fills up, <STRONG>alloc_pair</STRONG> discards the least-recently
+ allocated entry using <STRONG>free_pair</STRONG> and allocates a new color pair.
All of the color pairs are allocated from a table of possible color
- pairs. The size of the table is determined by the terminfo <EM>pairs</EM> capa-
- bility. The table is shared with <STRONG>init_pair</STRONG>; in fact <STRONG>alloc_pair</STRONG> calls
- <STRONG>init_pair</STRONG> after updating the ncurses library's fast index to the colors
- versus color pairs.
+ pairs. The size of the table is determined by the terminfo <EM>pairs</EM>
+ capability. The table is shared with <STRONG>init_pair</STRONG>; in fact <STRONG>alloc_pair</STRONG>
+ calls <STRONG>init_pair</STRONG> after updating the ncurses library's fast index to the
+ colors versus color pairs.
</PRE><H3><a name="h3-find_pair">find_pair</a></H3><PRE>
The <STRONG>find_pair</STRONG> function accepts parameters for foreground and background
color, and checks if that color combination is already associated with
- a color pair, returning the pair number if it has been allocated. Oth-
- erwise it returns -1.
+ a color pair, returning the pair number if it has been allocated.
+ Otherwise it returns -1.
</PRE><H3><a name="h3-free_pair">free_pair</a></H3><PRE>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
Panels are <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> windows with the added feature of depth. Panel
- functions allow the use of stacked windows and ensure the proper por-
- tions of each window and the curses <STRONG>stdscr</STRONG> window are hidden or dis-
- played when panels are added, moved, modified or removed. The set of
- currently visible panels is the stack of panels. The <STRONG>stdscr</STRONG> window is
- beneath all panels, and is not considered part of the stack.
+ functions allow the use of stacked windows and ensure the proper
+ portions of each window and the curses <STRONG>stdscr</STRONG> window are hidden or
+ displayed when panels are added, moved, modified or removed. The set
+ of currently visible panels is the stack of panels. The <STRONG>stdscr</STRONG> window
+ is beneath all panels, and is not considered part of the stack.
A window is associated with every panel. The panel routines enable you
to create, move, hide, and show panels, as well as position a panel at
</PRE><H3><a name="h3-del_panel">del_panel</a></H3><PRE>
- <STRONG>del_panel(</STRONG><EM>pan</EM><STRONG>)</STRONG> removes the given panel <EM>pan</EM> from the stack and deallo-
- cates the <STRONG>PANEL</STRONG> structure (but not its associated window).
+ <STRONG>del_panel(</STRONG><EM>pan</EM><STRONG>)</STRONG> removes the given panel <EM>pan</EM> from the stack and
+ deallocates the <STRONG>PANEL</STRONG> structure (but not its associated window).
</PRE><H3><a name="h3-ground_panel">ground_panel</a></H3><PRE>
</PRE><H2><a name="h2-DIAGNOSTICS">DIAGNOSTICS</a></H2><PRE>
Each routine that returns a pointer returns <STRONG>NULL</STRONG> if an error occurs.
- Each routine that returns an int value returns <STRONG>OK</STRONG> if it executes suc-
- cessfully and <STRONG>ERR</STRONG> if not.
+ Each routine that returns an int value returns <STRONG>OK</STRONG> if it executes
+ successfully and <STRONG>ERR</STRONG> if not.
Except as noted, the <EM>pan</EM> and <EM>window</EM> parameters must be non-null. If
those are null, an error is returned.
Reasonable care has been taken to ensure compatibility with the
native panel facility introduced in System V (inspection of the SVr4
manual pages suggests the programming interface is unchanged). The
- <STRONG>PANEL</STRONG> data structures are merely similar. The programmer is cau-
- tioned not to directly use <STRONG>PANEL</STRONG> fields.
+ <STRONG>PANEL</STRONG> data structures are merely similar. The programmer is
+ cautioned not to directly use <STRONG>PANEL</STRONG> fields.
- The functions <STRONG>show_panel</STRONG> and <STRONG>top_panel</STRONG> are identical in this implemen-
- tation, and work equally well with displayed or hidden panels. In the
- native System V implementation, <STRONG>show_panel</STRONG> is intended for making a
- hidden panel visible (at the top of the stack) and <STRONG>top_panel</STRONG> is
- intended for making an already-visible panel move to the top of the
- stack. You are cautioned to use the correct function to ensure compat-
- ibility with native panel libraries.
+ The functions <STRONG>show_panel</STRONG> and <STRONG>top_panel</STRONG> are identical in this
+ implementation, and work equally well with displayed or hidden panels.
+ In the native System V implementation, <STRONG>show_panel</STRONG> is intended for
+ making a hidden panel visible (at the top of the stack) and <STRONG>top_panel</STRONG>
+ is intended for making an already-visible panel move to the top of the
+ stack. You are cautioned to use the correct function to ensure
+ compatibility with native panel libraries.
</PRE><H2><a name="h2-NOTE">NOTE</a></H2><PRE>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
- This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201212).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20201219).
</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
- Originally written by Warren Tucker <wht@n4hgf.mt-park.ga.us>, primar-
- ily to assist in porting <EM>u386mon</EM> to systems without a native panels
- library.
+ Originally written by Warren Tucker <wht@n4hgf.mt-park.ga.us>,
+ primarily to assist in porting <EM>u386mon</EM> to systems without a native
+ panels library.
Repackaged for ncurses by Zeyd ben-Halim.
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
This is an extension to the curses library. It provides callers with a
- hook into the <STRONG>ncurses</STRONG> data to resize windows, primarily for use by pro-
- grams running in an X Window terminal (e.g., xterm).
+ hook into the <STRONG>ncurses</STRONG> data to resize windows, primarily for use by
+ programs running in an X Window terminal (e.g., xterm).
</PRE><H3><a name="h3-resizeterm">resizeterm</a></H3><PRE>
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
Except as noted, these functions return the integer <STRONG>ERR</STRONG> upon failure
and <STRONG>OK</STRONG> on success. They will fail if either of the dimensions are less
- than or equal to zero, or if an error occurs while (re)allocating mem-
- ory for the windows.
+ than or equal to zero, or if an error occurs while (re)allocating
+ memory for the windows.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- While these functions are intended to be used to support a signal han-
- dler (i.e., for <STRONG>SIGWINCH</STRONG>), care should be taken to avoid invoking them
- in a context where <STRONG>malloc</STRONG> or <STRONG>realloc</STRONG> may have been interrupted, since
- it uses those functions.
+ While these functions are intended to be used to support a signal
+ handler (i.e., for <STRONG>SIGWINCH</STRONG>), care should be taken to avoid invoking
+ them in a context where <STRONG>malloc</STRONG> or <STRONG>realloc</STRONG> may have been interrupted,
+ since it uses those functions.
If ncurses is configured to supply its own <STRONG>SIGWINCH</STRONG> handler,
resize the ncurses data structures.
If the environment variables <STRONG>LINES</STRONG> or <STRONG>COLUMNS</STRONG> are set, this overrides
- the library's use of the window size obtained from the operating sys-
- tem. Thus, even if a <STRONG>SIGWINCH</STRONG> is received, no screen size change may
- be recorded.
+ the library's use of the window size obtained from the operating
+ system. Thus, even if a <STRONG>SIGWINCH</STRONG> is received, no screen size change
+ may be recorded.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
read it back using <STRONG>scr_restore</STRONG> or <STRONG>getwin</STRONG>.
The <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG> functions do the work; while <STRONG>scr_dump</STRONG> and
- <STRONG>scr_restore</STRONG> conveniently save and restore the whole screen, i.e., <STRONG>std-</STRONG>
- <STRONG>scr</STRONG>.
+ <STRONG>scr_restore</STRONG> conveniently save and restore the whole screen, i.e.,
+ <STRONG>stdscr</STRONG>.
</PRE><H3><a name="h3-ncurses6">ncurses6</a></H3><PRE>
allowing applications (such as <STRONG>file(1)</STRONG>) to recognize curses dump
files.
- Because ncurses6 uses a new format, that requires a new magic num-
- ber was unused by other applications. This 16-bit number was
+ Because ncurses6 uses a new format, that requires a new magic
+ number was unused by other applications. This 16-bit number was
unused:
0x8888 (octal "\210\210")
0x88888888 (octal "\210\210\210\210")
- This is the pattern submitted to the maintainers of the <STRONG>file</STRONG> pro-
- gram:
+ This is the pattern submitted to the maintainers of the <STRONG>file</STRONG>
+ program:
#
# ncurses5 (and before) did not use a magic number,
<STRONG>o</STRONG> The screen dumps are written in textual form, so that internal data
sizes are not directly related to the dump-format, and enabling the
- library to read dumps from either narrow- or wide-character- con-
- figurations.
+ library to read dumps from either narrow- or wide-character-
+ configurations.
The <EM>narrow</EM> library configuration holds characters and video
attributes in a 32-bit <STRONG>chtype</STRONG>, while the <EM>wide-character</EM> library
stores this information in the <STRONG>cchar_t</STRONG> structure, which is much
larger than 32-bits.
- <STRONG>o</STRONG> It is possible to read a screen dump into a terminal with a differ-
- ent screen-size, because the library truncates or fills the screen
- as necessary.
+ <STRONG>o</STRONG> It is possible to read a screen dump into a terminal with a
+ different screen-size, because the library truncates or fills the
+ screen as necessary.
<STRONG>o</STRONG> The ncurses6 <STRONG>getwin</STRONG> reads the legacy screen dumps from ncurses5.
X/Open's documentation for <EM>enhanced</EM> <EM>curses</EM> says only:
The <EM>getwin(</EM> <EM>)</EM> function reads window-related data stored in the file
- by <EM>putwin(</EM> <EM>)</EM>. The function then creates and initializes a new win-
- dow using that data.
+ by <EM>putwin(</EM> <EM>)</EM>. The function then creates and initializes a new
+ window using that data.
The <EM>putwin(</EM> <EM>)</EM> function writes all data associated with <EM>win</EM> into the
<EM>stdio</EM> stream to which <EM>filep</EM> points, using an <STRONG>unspecified</STRONG> <STRONG>format</STRONG>.
projects / ncurses.git / commitdiff