X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=e3424758997795e29f4b7b609a7ecab78e0cb0cb;hp=2f792e7e85056a3e8885ff378f1105f9d009374c;hb=14d46fadc442db9df4567357cda396235418120e;hpb=8890c8f28a1db5995ef17f52a7d8c0b9cf574210
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html
index 2f792e7e..e3424758 100644
--- a/doc/html/man/ncurses.3x.html
+++ b/doc/html/man/ncurses.3x.html
@@ -1,7 +1,8 @@
@@ -59,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.1 (patch 20191207).
+ 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
@@ -112,7 +113,6 @@
Most programs would additionally use the sequence:
- nonl();
intrflush(stdscr, FALSE);
keypad(stdscr, TRUE);
@@ -258,7 +258,7 @@
Each cell (row and column) in a WINDOW is stored as a
cchar_t.
- The setcchar(3x) and getcchar(3x) functions store and
+ The setcchar(3x) and getcchar(3x) functions store and
retrieve the data from a cchar_t structure.
wchar_t
@@ -277,25 +277,15 @@
- The following table lists each curses routine and the name of the man-
- ual page on which it is described. Routines flagged with "*" are
- ncurses-specific, not described by XPG4 or present in SVr4.
+ The following table lists the curses 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.
curses Routine Name Manual Page Name
---------------------------------------------
COLOR_PAIR curs_color(3x)
PAIR_NUMBER curs_attr(3x)
- _nc_free_and_exit curs_memleaks(3x)*
- _nc_freeall curs_memleaks(3x)*
- _nc_tracebits curs_trace(3x)*
- _traceattr curs_trace(3x)*
- _traceattr2 curs_trace(3x)*
- _tracechar curs_trace(3x)*
- _tracechtype curs_trace(3x)*
- _tracechtype2 curs_trace(3x)*
- _tracedump curs_trace(3x)*
- _tracef curs_trace(3x)*
- _tracemouse curs_trace(3x)*
add_wch curs_add_wch(3x)
add_wchnstr curs_add_wchstr(3x)
add_wchstr curs_add_wchstr(3x)
@@ -312,7 +302,6 @@
attr_off curs_attr(3x)
attr_on curs_attr(3x)
attr_set curs_attr(3x)
-
attroff curs_attr(3x)
attron curs_attr(3x)
attrset curs_attr(3x)
@@ -324,6 +313,7 @@
bkgrndset curs_bkgrnd(3x)
border curs_border(3x)
border_set curs_border_set(3x)
+
box curs_border(3x)
box_set curs_border_set(3x)
can_change_color curs_color(3x)
@@ -337,6 +327,7 @@
color_set curs_attr(3x)
copywin curs_overlay(3x)
curs_set curs_kernel(3x)
+ curses_trace curs_trace(3x)*
curses_version curs_extend(3x)*
def_prog_mode curs_kernel(3x)
def_shell_mode curs_kernel(3x)
@@ -357,6 +348,8 @@
erase curs_clear(3x)
erasechar curs_termattrs(3x)
erasewchar curs_termattrs(3x)
+ exit_curses curs_memleaks(3x)*
+ exit_terminfo curs_memleaks(3x)*
extended_color_content curs_color(3x)*
extended_pair_content curs_color(3x)*
extended_slk_color curs_slk(3x)*
@@ -378,7 +371,6 @@
getcurx curs_legacy(3x)*
getcury curs_legacy(3x)*
getmaxx curs_legacy(3x)*
-
getmaxy curs_legacy(3x)*
getmaxyx curs_getyx(3x)
getmouse curs_mouse(3x)*
@@ -387,6 +379,7 @@
getparx curs_legacy(3x)*
getpary curs_legacy(3x)*
getparyx curs_getyx(3x)
+
getstr curs_getstr(3x)
getsyx curs_kernel(3x)
getwin curs_util(3x)
@@ -396,6 +389,7 @@
has_ic curs_termattrs(3x)
has_il curs_termattrs(3x)
has_key curs_getch(3x)*
+ has_mouse curs_mouse(3x)*
hline curs_border(3x)
hline_set curs_border_set(3x)
idcok curs_outopts(3x)
@@ -444,7 +438,6 @@
key_defined key_defined(3x)*
key_name curs_util(3x)
keybound keybound(3x)*
-
keyname curs_util(3x)
keyok keyok(3x)*
keypad curs_inopts(3x)
@@ -452,6 +445,7 @@
killwchar curs_termattrs(3x)
leaveok curs_outopts(3x)
longname curs_termattrs(3x)
+
mcprint curs_print(3x)*
meta curs_inopts(3x)
mouse_trafo curs_mouse(3x)*
@@ -510,7 +504,6 @@
mvwaddnwstr curs_addwstr(3x)
mvwaddstr curs_addstr(3x)
mvwaddwstr curs_addwstr(3x)
-
mvwchgat curs_attr(3x)
mvwdelch curs_delch(3x)
mvwget_wch curs_get_wch(3x)
@@ -518,6 +511,7 @@
mvwgetch curs_getch(3x)
mvwgetn_wstr curs_get_wstr(3x)
mvwgetnstr curs_getstr(3x)
+
mvwgetstr curs_getstr(3x)
mvwhline curs_border(3x)
mvwhline_set curs_border_set(3x)
@@ -551,13 +545,14 @@
nodelay curs_inopts(3x)
noecho curs_inopts(3x)
nofilter curs_util(3x)*
- nonl curs_outopts(3x)
+ nonl curs_inopts(3x)
noqiflush curs_inopts(3x)
noraw curs_inopts(3x)
notimeout curs_inopts(3x)
overlay curs_overlay(3x)
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)
@@ -568,6 +563,7 @@
raw curs_inopts(3x)
redrawwin curs_refresh(3x)
refresh curs_refresh(3x)
+ reset_color_pairs curs_color(3x)*
reset_prog_mode curs_kernel(3x)
reset_shell_mode curs_kernel(3x)
resetty curs_kernel(3x)
@@ -576,12 +572,12 @@
restartterm curs_terminfo(3x)
ripoffline curs_kernel(3x)
savetty curs_kernel(3x)
-
scanw curs_scanw(3x)
scr_dump curs_scr_dump(3x)
scr_init curs_scr_dump(3x)
scr_restore curs_scr_dump(3x)
scr_set curs_scr_dump(3x)
+
scrl curs_scroll(3x)
scroll curs_scroll(3x)
scrollok curs_outopts(3x)
@@ -608,6 +604,7 @@
slk_restore curs_slk(3x)
slk_set curs_slk(3x)
slk_touch curs_slk(3x)
+ slk_wset curs_slk(3x)*
standend curs_attr(3x)
standout curs_attr(3x)
start_color curs_color(3x)
@@ -642,11 +639,11 @@
use_default_colors default_colors(3x)*
use_env curs_util(3x)
use_extended_names curs_extend(3x)*
-
use_legacy_coding legacy_coding(3x)*
use_tioctl curs_util(3x)*
vid_attr curs_terminfo(3x)
vid_puts curs_terminfo(3x)
+
vidattr curs_terminfo(3x)
vidputs curs_terminfo(3x)
vline curs_border(3x)
@@ -708,11 +705,11 @@
winch curs_inch(3x)
winchnstr curs_inchstr(3x)
winchstr curs_inchstr(3x)
-
winnstr curs_instr(3x)
winnwstr curs_inwstr(3x)
wins_nwstr curs_ins_wstr(3x)
wins_wch curs_ins_wch(3x)
+
wins_wstr curs_ins_wstr(3x)
winsch curs_insch(3x)
winsdelln curs_deleteln(3x)
@@ -741,6 +738,17 @@
wvline curs_border(3x)
wvline_set curs_border_set(3x)
+ Depending on the configuration, additional sets of functions may be
+ available:
+
+ curs_memleaks(3x) - curses memory-leak checking
+
+ curs_sp_funcs(3x) - curses screen-pointer extension
+
+ curs_threads(3x) - curses thread support
+
+ curs_trace(3x) - curses debugging routines
+
Routines that return an integer return ERR upon failure and an integer
@@ -756,6 +764,12 @@
(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
+ wmove, 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 mvprintw) are provided both as macros and func-
+ tions.
+
Routines that return pointers return NULL on error.
@@ -1212,70 +1226,99 @@
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
+ 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
@@ -1284,7 +1327,11 @@
this (or some other) extension will adversely affect the portability of
curses applications.
- This implementation also contains several extensions:
+
+
+ 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.
@@ -1315,6 +1362,8 @@
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
tty driver. In this implementation, all padding is done by sending NUL
@@ -1323,10 +1372,98 @@
portability correspondingly.
-
+
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
+ 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
+ <stdio.h>.
+
+ 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
+ nothing in <curses.h> itself relied upon <stdio.h>.
+
+ 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
+ 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-
+ trl.h>.
+
+ 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
+ and AIX:
+
+ 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
+ Solaris curses) do not.
+
+ 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
+ including <term.h>.
+
+ 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>
+ before <term.h>.
+
+ 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-
+ 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-
+ 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
+ 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-
+ 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>
+ 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.
@@ -1383,7 +1520,14 @@
FILES
SEE ALSO
EXTENSIONS
-PORTABILITY
+PORTABILITY
+
+
NOTES
AUTHORS