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=e3424758997795e29f4b7b609a7ecab78e0cb0cb;hp=5cccabb6fc7bd62a3882d605bf424c5924887ece;hb=14d46fadc442db9df4567357cda396235418120e;hpb=d1cc319afccb0d472465718a748664e7cef00840
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html
index 5cccabb6..e3424758 100644
--- a/doc/html/man/ncurses.3x.html
+++ b/doc/html/man/ncurses.3x.html
@@ -28,7 +28,7 @@
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: ncurses.3x,v 1.149 2020/10/03 20:15:52 tom Exp @
+ * @Id: ncurses.3x,v 1.150 2020/11/07 23:48:27 tom Exp @
-->
@@ -60,7 +60,7 @@
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.2 (patch 20201031).
+ This describes ncurses version 6.2 (patch 20201107).
The ncurses library emulates the curses library of System V Release 4
UNIX, and XPG4 (X/Open Portability Guide) curses (also known as XSI
@@ -1226,101 +1226,125 @@
filing libraries add a "_g" and a "_p" to the root names respec-
tively, e.g., libncurses_g.a and libncurses_p.a.
+ --with-termlib
+ Low-level functions which do not depend upon whether the library
+ supports wide-characters, are provided in the tinfo library.
+
+ By doing this, it is possible to share the tinfo library between
+ wide/normal configurations as well as reduce the size of the
+ library when only low-level functions are needed.
+
+ Those functions are described in these pages:
+
+ o curs_extend(3x) - miscellaneous curses extensions
+
+ o curs_inopts(3x) - curses input options
+
+ o curs_kernel(3x) - low-level curses routines
+
+ o curs_termattrs(3x) - curses environment query routines
+
+ o curs_termcap(3x) - curses emulation of termcap
+
+ o curs_terminfo(3x) - curses interfaces to terminfo database
+
+ o curs_util(3x) - miscellaneous curses utility routines
+
--with-trace
- The trace function normally resides in the debug library, but it
+ The trace 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
+ figure scripts should check for the function's existence rather
than assuming it is always in the debug library.
/usr/share/tabset
- directory containing initialization files for the terminal capa-
+ directory containing initialization files for the terminal capa-
bility database /usr/share/terminfo terminal capability database
- 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
- 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 term-
- cap compiler in the ncurses startup code, at significant cost in core
+ 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 term-
+ cap 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 resiz-
ing 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
+ 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 back-
+ 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 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 default_col-
+ draw colored text on a background whose color is set independently,
+ providing better control over color contrasts. See the default_col-
ors(3x) manual page for details.
- The ncurses library includes a function for directing application out-
- put to a printer attached to the terminal device. See the
+ The ncurses library includes a function for directing application out-
+ put 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 sup-
+ The ncurses library is intended to be BASE-level conformant with XSI
+ Curses. The EXTENDED XSI Curses functionality (including color sup-
port) 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 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
+ 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.
- 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 imple-
+ o The routine mcprint was not present in any previous curses imple-
mentation. See the curs_print(3x) manual page for details.
o The routine wresize is not part of XPG4, nor is it present in SVr4.
@@ -1330,61 +1354,61 @@
tion programs. See curs_opaque(3x) for the discussion of is_scrol-
lok, etc.
- o This implementation can be configured to provide rudimentary sup-
- port for multi-threaded applications. See curs_threads(3x) for
+ o This implementation can be configured to provide rudimentary sup-
+ port 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 inter-
- face to the UNIX kernel significantly and increases the package's
+ bytes. This method is slightly more expensive, but narrows the inter-
+ face to the UNIX kernel significantly and increases the package's
portability correspondingly.
- The header file <curses.h> automatically includes the header files
+ The header file <curses.h> automatically 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 <unc-
+ o X/Open Curses is inconsistent with respect to SVr4 regarding <unc-
trl.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
@@ -1393,55 +1417,55 @@
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 "may make visible" because including a header
+ o X/Open Curses says "may make visible" 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 visi-
+ 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 visi-
ble. 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 vws-
+ 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 vws-
canw 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.
+ 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.