X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=a825da78b50cb364a6413361a9bdc4b6e855cd4e;hp=c42513ab55f8ede63c33eaff164ccd50268a5634;hb=ca276baf720e3a44721b9e18955d3f546955c6c8;hpb=027ae42953e3186daed8f3882da73de48291b606
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html
index c42513ab..a825da78 100644
--- a/doc/html/man/ncurses.3x.html
+++ b/doc/html/man/ncurses.3x.html
@@ -2,7 +2,7 @@
@@ -63,16 +63,22 @@
sonable 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 5.5 (patch 20061209).
-
- The ncurses routines emulate the curses(3x) library of
- System V Release 4 UNIX, and the XPG4 curses standard (XSI
- curses) but the ncurses library is freely redistributable
- in source form. Differences from the SVr4 curses are sum-
- marized under the EXTENSIONS and PORTABILITY sections
- below and described in detail in the respective EXTEN-
- SIONS, PORTABILITY and BUGS sections of individual man
- pages.
+ describes ncurses version 5.6 (patch 20080621).
+
+ The ncurses library emulates the curses(3x) 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.
A program using these routines must be linked with the
-lncurses option, or (if it has been generated) with the
@@ -106,8 +112,8 @@
intrflush(stdscr, FALSE);
keypad(stdscr, TRUE);
- Before a curses program is run, the tab stops of the ter-
- minal should be set and its initialization strings, if
+ Before a curses 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 tput init command after the shell environment variable
TERM has been exported. tset(1) is usually responsible
@@ -121,9 +127,9 @@
be created with newwin.
Note that curses does not handle overlapping windows,
- that's done by the panel(3x) library. This means that you
+ that's done by the panel(3x) library. This means that you
can either use stdscr or divide the screen into tiled win-
- dows and not using stdscr at all. Mixing the two will
+ dows and not using stdscr at all. Mixing the two will
result in unpredictable, and undesired, effects.
Windows are referred to by variables declared as WINDOW *.
@@ -160,7 +166,7 @@
If the environment variables LINES and COLUMNS are set, or
if the program is executing in a window environment, line
and column information in the environment will override
- information read by terminfo. This would effect a program
+ information read by terminfo. This would affect a program
running in an AT&T 630 layer, for example, where the size
of a screen is changeable (see ENVIRONMENT).
@@ -218,11 +224,67 @@
DOW.
Option setting routines require a Boolean flag bf with the
- value TRUE or FALSE; bf is always of type bool. The vari-
- ables ch and attrs below are always of type chtype. The
- types WINDOW, SCREEN, bool, and chtype are defined in
- <curses.h>. The type TERMINAL is defined in <term.h>.
- All other arguments are integers.
+ value TRUE or FALSE; bf is always of type bool. Most of
+ the data types used in the library routines, such as WIN-
+ DOW, SCREEN, bool, and chtype are defined in <curses.h>.
+ Types used for the terminfo routines such as TERMINAL are
+ defined in <term.h>.
+
+ This manual page describes functions which may appear in
+ any configuration of the library. There are two common
+ configurations of the library:
+
+ ncurses
+ the "normal" library, which handles 8-bit
+ characters. The normal (8-bit) library stores
+ characters combined with attributes in chtype
+ data.
+
+ Attributes alone (no corresponding character)
+ may be stored in chtype or the equivalent
+ attr_t data. In either case, the data is
+ stored in something like an integer.
+
+ Each cell (row and column) in a WINDOW is
+ stored as a chtype.
+
+ ncursesw
+ the so-called "wide" library, which handles
+ multibyte characters (See the section on
+ ALTERNATE CONFIGURATIONS). 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 charac-
+ ters:
+
+ cchar_t
+ corresponds to chtype. However it is a
+ structure, because more data is stored
+ than can fit into an integer. The char-
+ acters 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 sepa-
+ rate fields of the structure.
+
+ Each cell (row and column) in a WINDOW is
+ stored as a cchar_t.
+
+ wchar_t
+ stores a "wide" character. Like chtype,
+ this may be an integer.
+
+ wint_t
+ stores a wchar_t or WEOF - not the same,
+ though both may have the same size.
+
+ The "wide" library provides new functions
+ which are analogous to functions in the "nor-
+ mal" library. There is a naming convention
+ which relates many of the normal/wide vari-
+ ants: a "_w" is inserted into the name. For
+ example, waddch becomes wadd_wch.
+
Routine Name Index
The following table lists each curses routine and the name
@@ -244,11 +306,11 @@
_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)
addch curs_addch(3x)
+
addchnstr curs_addchstr(3x)
addchstr curs_addchstr(3x)
addnstr curs_addstr(3x)
@@ -309,16 +371,25 @@
flushinp curs_util(3x)
get_wch curs_get_wch(3x)
get_wstr curs_get_wstr(3x)
+ getattrs curs_attr(3x)
+ getbegx curs_legacy(3x)*
+ getbegy curs_legacy(3x)*
getbegyx curs_getyx(3x)
-
getbkgd curs_bkgd(3x)
+
getbkgrnd curs_bkgrnd(3x)
getcchar curs_getcchar(3x)
getch curs_getch(3x)
+ getcurx curs_legacy(3x)*
+ getcury curs_legacy(3x)*
+ getmaxx curs_legacy(3x)*
+ getmaxy curs_legacy(3x)*
getmaxyx curs_getyx(3x)
getmouse curs_mouse(3x)*
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)
getsyx curs_kernel(3x)
@@ -356,10 +427,22 @@
instr curs_instr(3x)
intrflush curs_inopts(3x)
inwstr curs_inwstr(3x)
+ is_cleared curs_opaque(3x)*
+ 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)
+ is_nodelay curs_opaque(3x)*
+ is_notimeout curs_opaque(3x)*
+ is_scrollok curs_opaque(3x)*
+ is_syncok curs_opaque(3x)*
+ is_term_resized resizeterm(3x)*
is_wintouched curs_touch(3x)
isendwin curs_initscr(3x)
key_defined key_defined(3x)*
+
key_name curs_util(3x)
keybound keybound(3x)*
keyname curs_util(3x)
@@ -376,7 +459,6 @@
mousemask curs_mouse(3x)*
move curs_move(3x)
mvadd_wch curs_add_wch(3x)
-
mvadd_wchnstr curs_add_wchstr(3x)
mvadd_wchstr curs_add_wchstr(3x)
mvaddch curs_addch(3x)
@@ -426,6 +508,7 @@
mvwaddchstr curs_addchstr(3x)
mvwaddnstr curs_addstr(3x)
mvwaddnwstr curs_addwstr(3x)
+
mvwaddstr curs_addstr(3x)
mvwaddwstr curs_addwstr(3x)
mvwchgat curs_attr(3x)
@@ -442,7 +525,6 @@
mvwin_wch curs_in_wch(3x)
mvwin_wchnstr curs_in_wchstr(3x)
mvwin_wchstr curs_in_wchstr(3x)
-
mvwinch curs_inch(3x)
mvwinchnstr curs_inchstr(3x)
mvwinchstr curs_inchstr(3x)
@@ -468,6 +550,7 @@
nocbreak curs_inopts(3x)
nodelay curs_inopts(3x)
noecho curs_inopts(3x)
+ nofilter curs_util(3x)*
nonl curs_outopts(3x)
noqiflush curs_inopts(3x)
noraw curs_inopts(3x)
@@ -491,6 +574,7 @@
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)
@@ -508,7 +592,6 @@
setterm curs_terminfo(3x)
setupterm curs_terminfo(3x)
slk_attr curs_slk(3x)*
-
slk_attr_off curs_slk(3x)
slk_attr_on curs_slk(3x)
slk_attr_set curs_slk(3x)
@@ -557,6 +640,8 @@
use_default_colors default_colors(3x)*
use_env curs_util(3x)
use_extended_names curs_extend(3x)*
+
+ use_legacy_coding legacy_coding(3x)*
vid_attr curs_terminfo(3x)
vid_puts curs_terminfo(3x)
vidattr curs_terminfo(3x)
@@ -574,7 +659,6 @@
waddchnstr curs_addchstr(3x)
waddchstr curs_addchstr(3x)
waddnstr curs_addstr(3x)
-
waddnwstr curs_addwstr(3x)
waddstr curs_addstr(3x)
waddwstr curs_addwstr(3x)
@@ -622,6 +706,7 @@
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)
@@ -640,7 +725,6 @@
wscanw curs_scanw(3x)
wscrl curs_scroll(3x)
wsetscrreg curs_outopts(3x)
-
wstandend curs_attr(3x)
wstandout curs_attr(3x)
wsyncdown curs_window(3x)
@@ -774,14 +858,14 @@
NCURSES_ASSUMED_COLORS
Override the compiled-in assumption that the termi-
nal's default colors are white-on-black (see
- assume_default_colors(3x)). You may set the fore-
- ground and background color values with this environ-
- ment 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 max_col-
- ors value is allowed.
+ default_colors(3x)). You may set the foreground and
+ background color values with this environment vari-
+ able by proving a 2-element list: foreground,back-
+ ground. 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 posi-
+ tive value from zero to the terminfo max_colors value
+ is allowed.
NCURSES_NO_HARD_TABS
Ncurses may use tabs as part of the cursor movement
@@ -909,12 +993,12 @@
TERMPATH
If TERMCAP does not hold a file name then ncurses
- checks the TERMPATH symbol. This is a list of
- filenames separated by spaces or colons (i.e., ":")
- on Unix, semicolons on OS/2 EMX. If the TERMPATH
- symbol is not set, ncurses looks in the files
- /etc/termcap, /usr/share/misc/termcap and
- $HOME/.termcap, in that order.
+ checks the TERMPATH symbol. This is a list of file-
+ names separated by spaces or colons (i.e., ":") on
+ Unix, semicolons on OS/2 EMX. If the TERMPATH symbol
+ is not set, ncurses looks in the files /etc/termcap,
+ /usr/share/misc/termcap and $HOME/.termcap, in that
+ order.
The library may be configured to disregard the following
variables when the current user is the superuser (root),
@@ -964,9 +1048,9 @@
extended (wide-character) functions. The curses.h
file which is installed for the wide-character
library is designed to be compatible with the normal
- library's header. Only the size of the WINDOW struc-
- ture differs, and very few applications require more
- than a pointer to WINDOWs. If the headers are
+ library's header. Only the size of the WINDOW
+ structure differs, and very few applications require
+ more than a pointer to WINDOWs. 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
@@ -980,10 +1064,10 @@
--with-profile
The shared and normal (static) library names differ
- by their suffixes, e.g., libncurses.so and
- libncurses.a. The debug and profiling libraries add
- a "_g" and a "_p" to the root names respectively,
- e.g., libncurses_g.a and libncurses_p.a.
+ by their suffixes, e.g., libncurses.so and libn-
+ curses.a. The debug and profiling libraries add a
+ "_g" and a "_p" to the root names respectively, e.g.,
+ libncurses_g.a and libncurses_p.a.
--with-trace
The trace function normally resides in the debug
@@ -1018,7 +1102,7 @@
in core and startup cycles.
The ncurses library includes facilities for capturing
- mouse events on certain terminals (including xterm). See
+ mouse events on certain terminals (including xterm). See
the curs_mouse(3x) manual page for details.
The ncurses library includes facilities for responding to
@@ -1038,53 +1122,62 @@
trols, 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 col-
- ored text on a background whose color is set indepen-
- dently, providing better control over color contrasts.
- See the default_colors(3x) manual page for details.
+ ored text on a background whose color is set
+ independently, providing better control over color con-
+ trasts. See the default_colors(3x) manual page for
+ details.
- The ncurses library includes a function for directing
- application output to a printer attached to the terminal
+ 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.
PORTABILITY
- The ncurses library is intended to be BASE-level confor-
- mant with the XSI Curses standard. The EXTENDED XSI
- Curses functionality (including color support) is sup-
- ported.
+ The ncurses library is intended to be BASE-level confor-
+ mant with XSI Curses. The EXTENDED XSI Curses functional-
+ ity (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 sections of the library man
pages.
- The routine has_key is not part of XPG4, nor is it present
- in SVr4. See the curs_getch(3x) manual page for details.
+ This implementation also contains several extensions:
- The routine slk_attr is not part of XPG4, nor is it
- present in SVr4. See the curs_slk(3x) manual page for
- details.
+ The routine has_key is not part of XPG4, nor is it
+ present in SVr4. See the curs_getch(3x) manual page
+ for details.
- The routines getmouse, mousemask, ungetmouse, mouseinter-
- val, 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.
+ The routine slk_attr is not part of XPG4, nor is it
+ present in SVr4. See the curs_slk(3x) manual page
+ for details.
- The routine mcprint was not present in any previous curses
- implementation. See the curs_print(3x) manual page for
- details.
+ The routines getmouse, mousemask, ungetmouse, mou-
+ seinterval, and wenclose relating to mouse interfac-
+ ing are not part of XPG4, nor are they present in
+ SVr4. See the curs_mouse(3x) manual page for
+ details.
+
+ The routine mcprint was not present in any previous
+ curses implementation. See the curs_print(3x) manual
+ page for details.
+
+ The routine wresize is not part of XPG4, nor is it
+ present in SVr4. See the wresize(3x) manual page for
+ details.
- The routine wresize is not part of XPG4, nor is it present
- in SVr4. See the wresize(3x) manual page for details.
+ The WINDOW structure's internal details can be hidden
+ from application programs. See curs_opaque(3x) for
+ the discussion of is_scrollok, etc.
In historic curses versions, delays embedded in the capa-
bilities cr, ind, cub1, ff and tab activated corresponding
delay bits in the UNIX tty driver. In this implementa-
- tion, all padding is done by NUL sends. This method is
- slightly more expensive, but narrows the interface to the
- UNIX kernel significantly and increases the package's
- portability correspondingly.
+ tion, 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 portability correspondingly.