X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=1fc62427ff9a92a29aa4d492f21e384d66d0396c;hp=80cfdda7678daafbfade64624636a57c71fe03cd;hb=349761f30e7fc0b4bf2718f7fc3da34e09ea6735;hpb=02f1dee48fe8af6ce054388fba739aa4f975004e
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html
index 80cfdda7..1fc62427 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 20191214).
+ This describes ncurses version 6.2 (patch 20201003).
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.
@@ -1276,28 +1290,37 @@
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
- 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.
- 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.
- 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.
@@ -1307,28 +1330,118 @@
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>.
- 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.
+ 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 +1496,14 @@
FILES
SEE ALSO
EXTENSIONS
-PORTABILITY
+PORTABILITY
+
+
NOTES
AUTHORS