X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;fp=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=7f7059d4fb400804c88f332bd9a1e50def47563d;hp=e401bdc0a7dcaa19fe1034b131a5ab245a4303c8;hb=084e3b44fc1c904d5ab941da55f47a237cb15766;hpb=89d66edde5b9525fff1f4343470231344d1ff2c6
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html
index e401bdc0..7f7059d4 100644
--- a/doc/html/man/ncurses.3x.html
+++ b/doc/html/man/ncurses.3x.html
@@ -28,19 +28,19 @@
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: ncurses.3x,v 1.179 2023/10/14 19:29:06 tom Exp @
+ * @Id: ncurses.3x,v 1.181 2023/11/25 14:32:36 tom Exp @
-->
-ncurses 3x 2023-10-14 ncurses 6.4 Library calls
+ncurses 3x 2023-11-25 ncurses 6.4 Library calls
-
ncurses 3x 2023-10-14 ncurses 6.4 Library calls
+
ncurses 3x 2023-11-25 ncurses 6.4 Library calls
ncurses(3x) Library calls ncurses(3x)
@@ -60,19 +60,37 @@
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 ncurses version 6.4 (patch 20231118).
+ This describes ncurses version 6.4 (patch 20231125).
The ncurses 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
- ncurses library is freely redistributable in source form. Differences
- from the SVr4 curses are summarized under the EXTENSIONS and
- PORTABILITY sections below and described in detail in the respective
- EXTENSIONS, PORTABILITY and BUGS sections of individual man pages.
-
- The ncurses 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.
+ Unix ("SVr4"), and XPG4 (X/Open Portability Guide) curses (also known
+ as XSI curses). XSI stands for X/Open System Interfaces Extension.
+ The ncurses library is freely redistributable in source form.
+
+ ncurses man pages employ several sections to clarify matters of usage
+ and interoperability with other curses implementations.
+
+ o "NOTES" describes matters and caveats of which any user of the
+ ncurses API should be aware, such as limitations on the size of an
+ underlying integral type or the availability of a preprocessor
+ macro for a function (which prevents its address from being taken).
+ This section also describes implementation details that will be
+ significant to the programmer but which are not standardized.
+
+ o "EXTENSIONS" presents ncurses innovations beyond the X/Open Curses
+ standard and/or the SVr4 curses implementation. They are termed
+ extensions to indicate that they cannot be implemented solely by
+ using the library API, but require access to the library's internal
+ state.
+
+ o "PORTABILITY" discusses matters (beyond the exercise of extensions)
+ that should be considered when writing to a curses standard, or to
+ multiple implementations.
+
+ o "HISTORY" examines points of detail in ncurses and other curses
+ implementations over the decades of their development, particularly
+ where precedent or inertia have frustrated better design (and, in a
+ few cases, where such inertia has been overcome).
A program using these routines must be linked with the -lncurses
option, or (if it has been generated) with the debugging library
@@ -295,6 +313,7 @@
addchnstr curs_addchstr(3x)
addchstr curs_addchstr(3x)
addnstr curs_addstr(3x)
+
addnwstr curs_addwstr(3x)
addstr curs_addstr(3x)
addwstr curs_addwstr(3x)
@@ -313,7 +332,6 @@
bkgdset curs_bkgd(3x)
bkgrnd curs_bkgrnd(3x)
bkgrndset curs_bkgrnd(3x)
-
border curs_border(3x)
border_set curs_border_set(3x)
box curs_border(3x)
@@ -361,6 +379,7 @@
flushinp curs_util(3x)
free_pair new_pair(3x)*
get_wch curs_get_wch(3x)
+
get_wstr curs_get_wstr(3x)
getattrs curs_attr(3x)
getbegx curs_legacy(3x)*
@@ -379,7 +398,6 @@
getn_wstr curs_get_wstr(3x)
getnstr curs_getstr(3x)
getparx curs_legacy(3x)*
-
getpary curs_legacy(3x)*
getparyx curs_getyx(3x)
getstr curs_getstr(3x)
@@ -427,6 +445,7 @@
is_idcok curs_opaque(3x)*
is_idlok curs_opaque(3x)*
is_immedok curs_opaque(3x)*
+
is_keypad curs_opaque(3x)*
is_leaveok curs_opaque(3x)*
is_linetouched curs_touch(3x)
@@ -445,7 +464,6 @@
key_name curs_util(3x)
keybound keybound(3x)*
keyname curs_util(3x)
-
keyok keyok(3x)*
keypad curs_inopts(3x)
killchar curs_termattrs(3x)
@@ -493,6 +511,7 @@
mvins_wstr curs_ins_wstr(3x)
mvinsch curs_insch(3x)
mvinsnstr curs_insstr(3x)
+
mvinsstr curs_insstr(3x)
mvinstr curs_instr(3x)
mvinwstr curs_inwstr(3x)
@@ -511,7 +530,6 @@
mvwaddstr curs_addstr(3x)
mvwaddwstr curs_addwstr(3x)
mvwchgat curs_attr(3x)
-
mvwdelch curs_delch(3x)
mvwget_wch curs_get_wch(3x)
mvwget_wstr curs_get_wstr(3x)
@@ -559,6 +577,7 @@
overwrite curs_overlay(3x)
pair_content curs_color(3x)
pecho_wchar curs_pad(3x)
+
pechochar curs_pad(3x)
pnoutrefresh curs_pad(3x)
prefresh curs_pad(3x)
@@ -577,7 +596,6 @@
resizeterm resizeterm(3x)*
restartterm curs_terminfo(3x)
ripoffline curs_kernel(3x)
-
savetty curs_kernel(3x)
scanw curs_scanw(3x)
scr_dump curs_scr_dump(3x)
@@ -625,6 +643,7 @@
tgetstr curs_termcap(3x)
tgoto curs_termcap(3x)
tigetflag curs_terminfo(3x)
+
tigetnum curs_terminfo(3x)
tigetstr curs_terminfo(3x)
timeout curs_inopts(3x)
@@ -643,7 +662,6 @@
ungetch curs_getch(3x)
ungetmouse curs_mouse(3x)*
untouchwin curs_touch(3x)
-
use_default_colors default_colors(3x)*
use_env curs_util(3x)
use_extended_names curs_extend(3x)*
@@ -691,6 +709,7 @@
wdelch curs_delch(3x)
wdeleteln curs_deleteln(3x)
wecho_wchar curs_add_wch(3x)
+
wechochar curs_addch(3x)
wenclose curs_mouse(3x)*
werase curs_clear(3x)
@@ -709,7 +728,6 @@
win_wch curs_in_wch(3x)
win_wchnstr curs_in_wchstr(3x)
win_wchstr curs_in_wchstr(3x)
-
winch curs_inch(3x)
winchnstr curs_inchstr(3x)
winchstr curs_inchstr(3x)
@@ -1272,78 +1290,87 @@
compiled terminal capability database
+
+ If standard output from a ncurses program is re-directed to something
+ which is not a tty, screen updates will be directed to standard error.
+ This was an undocumented feature of AT&T System V Release 3 curses.
+
+ See subsection "Header files" below regarding symbols exposed by
+ inclusion of curses.h.
+
+
- The ncurses library can be compiled with an option (-DUSE_GETCAP) that
- falls back to the old-style /etc/termcap file if the terminal setup
- code cannot find a terminfo entry corresponding to TERM. Use of this
- feature is not recommended, as it essentially includes an entire
- termcap compiler in the ncurses startup code, at significant cost in
+ The ncurses library can be compiled with an option (-DUSE_GETCAP) that
+ falls back to the old-style /etc/termcap file if the terminal setup
+ code cannot find a terminfo entry corresponding to TERM. Use of this
+ feature is not recommended, as it essentially includes an entire
+ termcap compiler in the ncurses startup code, at significant cost in
core and startup cycles.
- The ncurses library includes facilities for capturing mouse events on
- certain terminals (including xterm). See the curs_mouse(3x) manual
+ The ncurses library includes facilities for capturing mouse events on
+ certain terminals (including xterm). See the curs_mouse(3x) manual
page for details.
- The ncurses library includes facilities for responding to window
- resizing events, e.g., when running in an xterm. See the
- resizeterm(3x) and wresize(3x) manual pages for details. In addition,
+ The ncurses library includes facilities for responding to window
+ resizing events, e.g., when running in an xterm. See the
+ resizeterm(3x) and wresize(3x) manual pages for details. In addition,
the library may be configured with a SIGWINCH handler.
- The ncurses library extends the fixed set of function key capabilities
- of terminals by allowing the application designer to define additional
- key sequences at runtime. See the define_key(3x)key_defined(3x), and
+ The ncurses library extends the fixed set of function key capabilities
+ of terminals by allowing the application designer to define additional
+ key sequences at runtime. See the define_key(3x)key_defined(3x), and
keyok(3x) manual pages for details.
- The ncurses library can exploit the capabilities of terminals which
- implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
- application to reset the terminal to its original foreground and
- background colors. From the users' perspective, the application is
+ The ncurses library can exploit the capabilities of terminals which
+ implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
+ application to reset the terminal to its original foreground and
+ background colors. From the users' perspective, the application is
able to draw colored text on a background whose color is set
- independently, providing better control over color contrasts. See the
+ independently, providing better control over color contrasts. See the
default_colors(3x) manual page for details.
- The ncurses library includes a function for directing application
+ The ncurses library includes a function for directing application
output to a printer attached to the terminal device. See the
curs_print(3x) manual page for details.
- The ncurses library is intended to be BASE-level conformant with XSI
- Curses. The EXTENDED XSI Curses functionality (including color
+ The ncurses library is intended to be BASE-level conformant with XSI
+ Curses. The EXTENDED XSI Curses functionality (including color
support) is supported.
- A small number of local differences (that is, individual differences
- between the XSI Curses and ncurses calls) are described in PORTABILITY
+ A small number of local differences (that is, individual differences
+ between the XSI Curses and ncurses calls) are described in PORTABILITY
sections of the library man pages.
- In many cases, X/Open Curses is vague about error conditions, omitting
+ In many cases, X/Open Curses is vague about error conditions, omitting
some of the SVr4 documentation.
- Unlike other implementations, 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
+ 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.
- Most of the extensions provided by ncurses have not been standardized.
+ Most of the extensions provided by ncurses have not been standardized.
Some have been incorporated into other implementations, such as
PDCurses or NetBSD curses. Here are a few to consider:
o The routine has_key is not part of XPG4, nor is it present in SVr4.
See the curs_getch(3x) manual page for details.
- o The routine slk_attr is not part of XPG4, nor is it present in
+ o The routine slk_attr is not part of XPG4, nor is it present in
SVr4. See the curs_slk(3x) manual page for details.
- o The routines getmouse, mousemask, ungetmouse, mouseinterval, and
- wenclose relating to mouse interfacing are not part of XPG4, nor
- are they present in SVr4. See the curs_mouse(3x) manual page for
+ o The routines getmouse, mousemask, ungetmouse, mouseinterval, and
+ wenclose relating to mouse interfacing are not part of XPG4, nor
+ are they present in SVr4. See the curs_mouse(3x) manual page for
details.
o The routine mcprint was not present in any previous curses
@@ -1352,65 +1379,65 @@
o The routine wresize is not part of XPG4, nor is it present in SVr4.
See the wresize(3x) manual page for details.
- o The WINDOW structure's internal details can be hidden from
- application programs. See curs_opaque(3x) for the discussion of
+ o The WINDOW structure's internal details can be hidden from
+ application programs. See curs_opaque(3x) for the discussion of
is_scrollok, etc.
o This implementation can be configured to provide rudimentary
- support for multi-threaded applications. See curs_threads(3x) for
+ support for multi-threaded applications. See curs_threads(3x) for
details.
- o This implementation can also be configured to provide a set of
- functions which improve the ability to manage multiple screens.
+ o This implementation can also be configured to provide a set of
+ functions which improve the ability to manage multiple screens.
See curs_sp_funcs(3x) for details.
- In historic curses versions, delays embedded in the capabilities cr,
- ind, cub1, ff and tab activated corresponding delay bits in the UNIX
+ In historic curses versions, delays embedded in the capabilities cr,
+ ind, cub1, ff and tab 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
- interface 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.
- The header file <curses.h> automatically includes the header files
- <stdio.h> and <unctrl.h>.
+ The header file curses.h itself includes the header files stdio.h and
+ unctrl.h.
X/Open Curses has more to say, but does not finish the story:
- The inclusion of <curses.h> may make visible all symbols from the
+ The inclusion of <curses.h> may make visible all symbols from the
headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
Here is a more complete story:
- o Starting with BSD curses, all implementations have included
+ o Starting with BSD curses, all implementations have included
<stdio.h>.
- BSD curses included <curses.h> and <unctrl.h> from an internal
+ BSD curses included <curses.h> and <unctrl.h> from an internal
header "curses.ext" ("ext" was a short name for externs).
- BSD curses used <stdio.h> internally (for printw and scanw), but
+ BSD curses used <stdio.h> internally (for printw and scanw), but
nothing in <curses.h> itself relied upon <stdio.h>.
- o SVr2 curses added newterm(3x), which relies upon <stdio.h>. That
+ o SVr2 curses added newterm(3x), which relies upon <stdio.h>. That
is, the function prototype uses FILE.
SVr4 curses added putwin and getwin, which also use <stdio.h>.
X/Open Curses documents all three of these functions.
- SVr4 curses and X/Open Curses do not require the developer to
+ SVr4 curses and X/Open Curses do not require the developer to
include <stdio.h> before including <curses.h>. Both document
curses showing <curses.h> as the only required header.
As a result, standard <curses.h> will always include <stdio.h>.
- o X/Open Curses is inconsistent with respect to SVr4 regarding
+ o X/Open Curses is inconsistent with respect to SVr4 regarding
<unctrl.h>.
- As noted in curs_util(3x), ncurses includes <unctrl.h> from
+ As noted in curs_util(3x), ncurses includes <unctrl.h> from
<curses.h> (like SVr4).
o X/Open's comments about <term.h> and <termios.h> may refer to HP-UX
@@ -1419,72 +1446,66 @@
HP-UX curses includes <term.h> from <curses.h> to declare setupterm
in curses.h, but ncurses (and Solaris curses) do not.
- AIX curses includes <term.h> and <termios.h>. Again, ncurses (and
+ AIX curses includes <term.h> and <termios.h>. Again, ncurses (and
Solaris curses) do not.
- o X/Open says that <curses.h> may include <term.h>, but there is no
+ o X/Open says that <curses.h> may include <term.h>, but there is no
requirement that it do that.
Some programs use functions declared in both <curses.h> and
- <term.h>, and must include both headers in the same module. Very
- old versions of AIX curses required including <curses.h> before
+ <term.h>, and must include both headers in the same module. Very
+ old versions of AIX curses required including <curses.h> before
including <term.h>.
- Because ncurses header files include the headers needed to define
+ Because ncurses header files include the headers needed to define
datatypes used in the headers, ncurses header files can be included
- in any order. But for portability, you should include <curses.h>
+ in any order. But for portability, you should include <curses.h>
before <term.h>.
- o X/Open Curses says "maymakevisible" because including a header
+ o X/Open Curses says "maymakevisible" because including a header
file does not necessarily make all symbols in it visible (there are
ifdef's to consider).
- For instance, in ncurses <wchar.h> may 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
- visible. That depends on the value used for _XOPEN_SOURCE feature
+ For instance, in ncurses <wchar.h> may 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
+ visible. That depends on the value used for _XOPEN_SOURCE feature
test macro.
- o X/Open Curses documents one required header, in a special case:
- <stdarg.h> before <curses.h> to prototype the vw_printw and
- vw_scanw functions (as well as the obsolete the vwprintw and
+ o X/Open Curses documents one required header, in a special case:
+ <stdarg.h> before <curses.h> to prototype the vw_printw and
+ vw_scanw functions (as well as the obsolete the vwprintw and
vwscanw functions). Each of those uses a va_list parameter.
- The two obsolete functions were introduced in SVr3. The other
- functions were introduced in X/Open Curses. In between, SVr4
- curses provided for the possibility that an application might
+ The two obsolete functions were introduced in SVr3. The other
+ functions were introduced in X/Open Curses. In between, SVr4
+ curses provided for the possibility that an application might
include either <varargs.h> or <stdarg.h>. Initially, that was done
- by using void* for the va_list parameter. Later, a special type
- (defined in <stdio.h>) was introduced, to allow for compiler type-
+ by using void* for the va_list parameter. Later, a special type
+ (defined in <stdio.h>) was introduced, to allow for compiler type-
checking. That special type is always available, because <stdio.h>
is always included by <curses.h>.
None of the X/Open Curses implementations require an application to
- include <stdarg.h> before <curses.h> because they either have
- allowed for a special type, or (like ncurses) include <stdarg.h>
+ include <stdarg.h> before <curses.h> because they either have
+ allowed for a special type, or (like ncurses) include <stdarg.h>
directly to provide a portable interface.
-
- If standard output from a ncurses program is re-directed to something
- which is not a tty, screen updates will be directed to standard error.
- This was an undocumented feature of AT&T System V Release 3 curses.
-
-
- terminfo(5) and related pages whose names begin "curs_" for detailed
+ terminfo(5) and related pages whose names begin "curs_" for detailed
routine descriptions.
curs_variables(3x)user_caps(5) for user-defined capabilities
-ncurses 6.4 2023-10-14 ncurses(3x)
+ncurses 6.4 2023-11-25 ncurses(3x)