X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=a825da78b50cb364a6413361a9bdc4b6e855cd4e;hp=0490529778fa0486c0d9d32a0fef90d2a9e39a38;hb=ca276baf720e3a44721b9e18955d3f546955c6c8;hpb=a8987e73ec254703634802b4f7ee30d3a485524d
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html
index 04905297..a825da78 100644
--- a/doc/html/man/ncurses.3x.html
+++ b/doc/html/man/ncurses.3x.html
@@ -2,7 +2,7 @@
@@ -41,7 +41,7 @@
-ncurses(3x) ncurses(3x)
+ncurses(3x) ncurses(3x)
@@ -62,15 +62,23 @@
independent method of updating character screens with rea-
sonable optimization. This implementation is ``new
curses'' (ncurses) and is the approved replacement for
- 4.4BSD classic curses, which has been discontinued.
-
- 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 BUGS sections below and
- described in detail in the EXTENSIONS and BUGS sections of
- individual man pages.
+ 4.4BSD classic curses, which has been discontinued. This
+ 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
@@ -78,21 +86,22 @@
may also have installed these libraries under the names
-lcurses and -lcurses_g.) The ncurses_g library generates
trace logs (in a file called 'trace' in the current direc-
- tory) that describe curses actions.
+ tory) that describe curses actions. See also the section
+ on ALTERNATE CONFIGURATIONS.
- The ncurses package supports: overall screen, window and
+ The ncurses package supports: overall screen, window and
pad manipulation; output to windows and pads; reading ter-
- minal input; control over terminal and curses input and
- output options; environment query routines; color manipu-
+ minal input; control over terminal and curses input and
+ output options; environment query routines; color manipu-
lation; use of soft label keys; terminfo capabilities; and
access to low-level terminal-manipulation routines.
To initialize the routines, the routine initscr or newterm
- must be called before any of the other routines that deal
- with windows and screens are used. The routine endwin
+ must be called before any of the other routines that deal
+ with windows and screens are used. The routine endwin
must be called before exiting. To get character-at-a-time
- input without echoing (most interactive, screen oriented
- programs want this), the following sequence should be
+ input without echoing (most interactive, screen oriented
+ programs want this), the following sequence should be
used:
initscr(); cbreak(); noecho();
@@ -103,74 +112,74 @@
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
- defined, must be output. This can be done by executing
+ 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
+ TERM has been exported. tset(1) is usually responsible
for doing this. [See terminfo(5) for further details.]
- The ncurses library permits manipulation of data struc-
- tures, called windows, which can be thought of as two-
- dimensional arrays of characters representing all or part
+ The ncurses library permits manipulation of data struc-
+ tures, called windows, which can be thought of as two-
+ dimensional arrays of characters representing all or part
of a CRT screen. A default window called stdscr, which is
- the size of the terminal screen, is supplied. Others may
+ the size of the terminal screen, is supplied. Others may
be created with newwin.
- Note that curses does not handle overlapping windows,
- that's done by the panel(3x) library. This means that you
+ Note that curses does not handle overlapping windows,
+ 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 *.
- These data structures are manipulated with routines
- described here and elsewhere in the ncurses manual pages.
- Among which the most basic routines are move and addch.
- More general versions of these routines are included with
- names beginning with w, allowing the user to specify a
- window. The routines not beginning with w affect stdscr.)
-
- After using routines to manipulate a window, refresh is
- called, telling curses to make the user's CRT screen look
- like stdscr. The characters in a window are actually of
- type chtype, (character and attribute data) so that other
- information about the character may also be stored with
+ These data structures are manipulated with routines
+ described here and elsewhere in the ncurses manual pages.
+ Among those, the most basic routines are move and addch.
+ More general versions of these routines are included with
+ names beginning with w, allowing the user to specify a
+ window. The routines not beginning with w affect stdscr.
+
+ After using routines to manipulate a window, refresh is
+ called, telling curses to make the user's CRT screen look
+ like stdscr. The characters in a window are actually of
+ type chtype, (character and attribute data) so that other
+ information about the character may also be stored with
each character.
- Special windows called pads may also be manipulated.
+ Special windows called pads may also be manipulated.
These are windows which are not constrained to the size of
- the screen and whose contents need not be completely dis-
+ the screen and whose contents need not be completely dis-
played. See curs_pad(3x) for more information.
- In addition to drawing characters on the screen, video
- attributes and colors may be supported, causing the char-
- acters to show up in such modes as underlined, in reverse
- video, or in color on terminals that support such display
+ In addition to drawing characters on the screen, video
+ attributes and colors may be supported, causing the char-
+ acters to show up in such modes as underlined, in reverse
+ video, or in color on terminals that support such display
enhancements. Line drawing characters may be specified to
- be output. On input, curses is also able to translate
- arrow and function keys that transmit escape sequences
- into single values. The video attributes, line drawing
- characters, and input values use names, defined in
+ be output. On input, curses is also able to translate
+ arrow and function keys that transmit escape sequences
+ into single values. The video attributes, line drawing
+ characters, and input values use names, defined in
<curses.h>, such as A_REVERSE, ACS_HLINE, and KEY_LEFT.
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
- running in an AT&T 630 layer, for example, where the size
+ if the program is executing in a window environment, line
+ and column information in the environment will override
+ 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).
- If the environment variable TERMINFO is defined, any pro-
- gram using curses checks for a local terminal definition
- before checking in the standard place. For example, if
+ If the environment variable TERMINFO is defined, any pro-
+ gram using curses checks for a local terminal definition
+ before checking in the standard place. For example, if
TERM is set to att4424, then the compiled terminal defini-
tion is found in
/usr/share/terminfo/a/att4424.
(The a is copied from the first letter of att4424 to avoid
- creation of huge directories.) However, if TERMINFO is
+ creation of huge directories.) However, if TERMINFO is
set to $HOME/myterms, curses first checks
$HOME/myterms/a/att4424,
@@ -179,54 +188,111 @@
/usr/share/terminfo/a/att4424.
- This is useful for developing experimental definitions or
+ This is useful for developing experimental definitions or
when write permission in /usr/share/terminfo is not avail-
able.
- The integer variables LINES and COLS are defined in
- <curses.h> and will be filled in by initscr with the size
+ The integer variables LINES and COLS are defined in
+ <curses.h> and will be filled in by initscr with the size
of the screen. The constants TRUE and FALSE have the val-
ues 1 and 0, respectively.
- The curses routines also define the WINDOW * variable
+ The curses routines also define the WINDOW * variable
curscr which is used for certain low-level operations like
- clearing and redrawing a screen containing garbage. The
+ clearing and redrawing a screen containing garbage. The
curscr can be used in only a few routines.
Routine and Argument Names
- Many curses routines have two or more versions. The rou-
+ Many curses routines have two or more versions. The rou-
tines prefixed with w require a window argument. The rou-
tines prefixed with p require a pad argument. Those with-
out a prefix generally use stdscr.
The routines prefixed with mv require a y and x coordinate
- to move to before performing the appropriate action. The
- mv routines imply a call to move before the call to the
- other routine. The coordinate y always refers to the row
- (of the window), and x always refers to the column. The
+ to move to before performing the appropriate action. The
+ mv routines imply a call to move before the call to the
+ other routine. The coordinate y always refers to the row
+ (of the window), and x always refers to the column. The
upper left-hand corner is always (0,0), not (1,1).
The routines prefixed with mvw take both a window argument
- and x and y coordinates. The window argument is always
+ and x and y coordinates. The window argument is always
specified before the coordinates.
- In each case, win is the window affected, and pad is the
+ In each case, win is the window affected, and pad is the
pad affected; win and pad are always pointers to type WIN-
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
- of the manual page on which it is described. Routines
- flagged with `*' are ncurses-specific, not described by
+ of the manual page on which it is 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)
@@ -305,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)
@@ -352,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 +463,6 @@
mvadd_wchstr curs_add_wchstr(3x)
mvaddch curs_addch(3x)
mvaddchnstr curs_addchstr(3x)
-
mvaddchstr curs_addchstr(3x)
mvaddnstr curs_addstr(3x)
mvaddnwstr curs_addwstr(3x)
@@ -422,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 +529,6 @@
mvwinchnstr curs_inchstr(3x)
mvwinchstr curs_inchstr(3x)
mvwinnstr curs_instr(3x)
-
mvwinnwstr curs_inwstr(3x)
mvwins_nwstr curs_ins_wstr(3x)
mvwins_wch curs_ins_wch(3x)
@@ -464,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)
@@ -487,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 +596,6 @@
slk_attr_on curs_slk(3x)
slk_attr_set curs_slk(3x)
slk_attroff curs_slk(3x)
-
slk_attron curs_slk(3x)
slk_attrset curs_slk(3x)
slk_clear curs_slk(3x)
@@ -553,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 +663,6 @@
waddstr curs_addstr(3x)
waddwstr curs_addwstr(3x)
wattr_get curs_attr(3x)
-
wattr_off curs_attr(3x)
wattr_on curs_attr(3x)
wattr_set curs_attr(3x)
@@ -618,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 +729,6 @@
wstandout curs_attr(3x)
wsyncdown curs_window(3x)
wsyncup curs_window(3x)
-
wtimeout curs_inopts(3x)
wtouchln curs_touch(3x)
wunctrl curs_util(3x)
@@ -650,14 +738,14 @@
RETURN VALUE
- Routines that return an integer return ERR upon failure
- and an integer value other than ERR upon successful com-
- pletion, unless otherwise noted in the routine descrip-
+ Routines that return an integer return ERR upon failure
+ and an integer value other than ERR upon successful com-
+ pletion, unless otherwise noted in the routine descrip-
tions.
- All macros return the value of the w version, except
+ All macros return the value of the w version, except
setscrreg, wsetscrreg, getyx, getbegyx, and getmaxyx. The
- return values of setscrreg, wsetscrreg, getyx, getbegyx,
+ return values of setscrreg, wsetscrreg, getyx, getbegyx,
and getmaxyx are undefined (i.e., these should not be used
as the right-hand side of assignment statements).
@@ -671,66 +759,78 @@
important ones have been already discussed in detail.
BAUDRATE
- The debugging library checks this environment symbol
+ The debugging library checks this environment symbol
when the application has redirected output to a file.
- The symbol's numeric value is used for the baudrate.
+ The symbol's numeric value is used for the baudrate.
If no value is found, ncurses uses 9600. This allows
- testers to construct repeatable test-cases that take
+ testers to construct repeatable test-cases that take
into account costs that depend on baudrate.
CC When set, change occurrences of the command_character
- (i.e., the cmdch capability) of the loaded terminfo
- entries to the value of this symbol. Very few ter-
+ (i.e., the cmdch capability) of the loaded terminfo
+ entries to the value of this symbol. Very few ter-
minfo entries provide this feature.
COLUMNS
Specify the width of the screen in characters.
- Applications running in a windowing environment usu-
- ally are able to obtain the width of the window in
- which they are executing. If neither the $COLUMNS
- value nor the terminal's screen size is available,
- ncurses uses the size which may be specified in the
+ Applications running in a windowing environment usu-
+ ally are able to obtain the width of the window in
+ which they are executing. If neither the COLUMNS
+ value nor the terminal's screen size is available,
+ ncurses uses the size which may be specified in the
terminfo database (i.e., the cols capability).
- It is important that your application use a correct
- size for the screen. However, this is not always
- possible because your application may be running on a
- host which does not honor NAWS (Negotiations About
- Window Size), or because you are temporarily running
- as another user.
-
- Either COLUMNS or LINES symbols may be specified
- independently. This is mainly useful to circumvent
- legacy misfeatures of terminal descriptions, e.g.,
+ It is important that your application use a correct
+ size for the screen. This is not always possible
+ because your application may be running on a host
+ which does not honor NAWS (Negotiations About Window
+ Size), or because you are temporarily running as
+ another user. However, setting COLUMNS and/or LINES
+ overrides the library's use of the screen size
+ obtained from the operating system.
+
+ Either COLUMNS or LINES symbols may be specified
+ independently. This is mainly useful to circumvent
+ legacy misfeatures of terminal descriptions, e.g.,
xterm which commonly specifies a 65 line screen. For
- best results, lines and cols should not be specified
+ best results, lines and cols should not be specified
in a terminal description for terminals which are run
as emulations.
- Use the use_env function to disable this feature.
+ Use the use_env function to disable all use of exter-
+ nal environment (including system calls) to determine
+ the screen size.
ESCDELAY
- Specifies the total time, in milliseconds, for which
- ncurses will await a character sequence, e.g., a
- function key. The default value, 1000 milliseconds,
+ Specifies the total time, in milliseconds, for which
+ ncurses will await a character sequence, e.g., a
+ function key. The default value, 1000 milliseconds,
is enough for most uses. However, it is made a vari-
able to accommodate unusual applications.
The most common instance where you may wish to change
- this value is to work with slow hosts, e.g., running
- on a network. If the host cannot read characters
- rapidly enough, it will have the same effect as if
- the terminal did not send characters rapidly enough.
+ this value is to work with slow hosts, e.g., running
+ on a network. If the host cannot read characters
+ rapidly enough, it will have the same effect as if
+ the terminal did not send characters rapidly enough.
The library will still see a timeout.
- Note that xterm mouse events are built up from char-
- acter sequences received from the xterm. If your
+ Note that xterm mouse events are built up from char-
+ acter sequences received from the xterm. If your
application makes heavy use of multiple-clicking, you
- may wish to lengthen this default value because the
- timeout applies to the composed multi-click event as
+ may wish to lengthen this default value because the
+ timeout applies to the composed multi-click event as
well as the individual clicks.
- HOME Tells ncurses where your home directory is. That is
+ In addition to the environment variable, this imple-
+ mentation provides a global variable with the same
+ name. Portable applications should not rely upon the
+ presence of ESCDELAY in either form, but setting the
+ environment variable rather than the global variable
+ does not create problems when compiling an applica-
+ tion.
+
+ HOME Tells ncurses where your home directory is. That is
where it may read and write auxiliary terminal
descriptions:
@@ -738,12 +838,12 @@
$HOME/.terminfo
LINES
- Like COLUMNS, specify the height of the screen in
- characters. See COLUMNS for a detailed description.
+ Like COLUMNS, specify the height of the screen in
+ characters. See COLUMNS for a detailed description.
MOUSE_BUTTONS_123
This applies only to the OS/2 EMX port. It specifies
- the order of buttons on the mouse. OS/2 numbers a
+ the order of buttons on the mouse. OS/2 numbers a
3-button mouse inconsistently from other platforms:
1 = left
@@ -751,59 +851,92 @@
3 = middle.
This symbol lets you customize the mouse. The symbol
- must be three numeric digits 1-3 in any order, e.g.,
- 123 or 321. If it is not specified, ncurses uses
+ must be three numeric digits 1-3 in any order, e.g.,
+ 123 or 321. If it is not specified, ncurses uses
132.
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: fore-
- ground,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.
+ Override the compiled-in assumption that the termi-
+ nal's default colors are white-on-black (see
+ 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
+ optimization. In some cases, your terminal driver
+ may not handle these properly. Set this environment
+ variable to disable the feature. You can also adjust
+ your stty settings to avoid the problem.
+
+ NCURSES_NO_MAGIC_COOKIES
+ Some terminals use a magic-cookie feature which
+ requires special handling to make highlighting and
+ other video attributes display properly. You can
+ suppress the highlighting entirely for these termi-
+ nals by setting this environment variable.
NCURSES_NO_PADDING
- Most of the terminal descriptions in the terminfo
- database are written for real "hardware" terminals.
- Many people use terminal emulators which run in a
- windowing environment and use curses-based applica-
- tions. Terminal emulators can duplicate all of the
+ Most of the terminal descriptions in the terminfo
+ database are written for real "hardware" terminals.
+ Many people use terminal emulators which run in a
+ windowing environment and use curses-based applica-
+ tions. Terminal emulators can duplicate all of the
important aspects of a hardware terminal, but they do
- not have the same limitations. The chief limitation
- of a hardware terminal from the standpoint of your
- application is the management of dataflow, i.e.,
- timing. Unless a hardware terminal is interfaced
- into a terminal concentrator (which does flow con-
- trol), it (or your application) must manage dataflow,
- preventing overruns. The cheapest solution (no hard-
- ware cost) is for your program to do this by pausing
- after operations that the terminal does slowly, such
- as clearing the display.
-
- As a result, many terminal descriptions (including
- the vt100) have delay times embedded. You may wish
- to use these descriptions, but not want to pay the
+ not have the same limitations. The chief limitation
+ of a hardware terminal from the standpoint of your
+ application is the management of dataflow, i.e., tim-
+ ing. Unless a hardware terminal is interfaced into a
+ terminal concentrator (which does flow control), it
+ (or your application) must manage dataflow, prevent-
+ ing overruns. The cheapest solution (no hardware
+ cost) is for your program to do this by pausing after
+ operations that the terminal does slowly, such as
+ clearing the display.
+
+ As a result, many terminal descriptions (including
+ the vt100) have delay times embedded. You may wish
+ to use these descriptions, but not want to pay the
performance penalty.
- Set the NCURSES_NO_PADDING symbol to disable all but
- mandatory padding. Mandatory padding is used as a
+ Set the NCURSES_NO_PADDING symbol to disable all but
+ mandatory padding. Mandatory padding is used as a
part of special control sequences such as flash.
NCURSES_NO_SETBUF
- Normally ncurses enables buffered output during ter-
- minal initialization. This is done (as in SVr4
- curses) for performance reasons. For testing pur-
+ Normally ncurses enables buffered output during ter-
+ minal initialization. This is done (as in SVr4
+ curses) for performance reasons. For testing pur-
poses, both of ncurses and certain applications, this
feature is made optional. Setting the
NCURSES_NO_SETBUF variable disables output buffering,
- leaving the output in the original (usually line
+ leaving the output in the original (usually line
buffered) mode.
+ NCURSES_NO_UTF8_ACS
+ During initialization, the ncurses library checks for
+ special cases where VT100 line-drawing (and the cor-
+ responding alternate character set capabilities)
+ described in the terminfo are known to be missing.
+ Specifically, when running in a UTF-8 locale, the
+ Linux console emulator and the GNU screen program
+ ignore these. Ncurses checks the TERM environment
+ variable for these. For other special cases, you
+ should set this environment variable. Doing this
+ tells ncurses to use Unicode values which correspond
+ to the VT100 line-drawing glyphs. That works for the
+ special cases cited, and is likely to work for termi-
+ nal emulators.
+
+ When setting this variable, you should set it to a
+ nonzero value. Setting it to zero (or to a nonnum-
+ ber) disables the special check for Linux and screen.
+
NCURSES_TRACE
During initialization, the ncurses debugging library
checks the NCURSES_TRACE symbol. If it is defined,
@@ -873,6 +1006,77 @@
$TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
+
+ALTERNATE CONFIGURATIONS
+ Several different configurations are possible, depending
+ on the configure script options used when building
+ ncurses. There are a few main options whose effects are
+ visible to the applications developer using ncurses:
+
+ --disable-overwrite
+ The standard include for ncurses is as noted in SYN-
+ OPSIS:
+
+ #include <curses.h>
+
+ This option is used to avoid filename conflicts when
+ ncurses is not the main implementation of curses of
+ the computer. If ncurses is installed disabling
+ overwrite, it puts its headers in a subdirectory,
+ e.g.,
+
+ #include <ncurses/curses.h>
+
+ It also omits a symbolic link which would allow you
+ to use -lcurses to build executables.
+
+ --enable-widec
+ The configure script renames the library and (if the
+ --disable-overwrite option is used) puts the header
+ files in a different subdirectory. All of the
+ library names have a "w" appended to them, i.e.,
+ instead of
+
+ -lncurses
+
+ you link with
+
+ -lncursesw
+
+ You must also define _XOPEN_SOURCE_EXTENDED when com-
+ piling for the wide-character library to use the
+ 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
+ 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
+ the same set of headers.
+
+ --with-shared
+
+ --with-normal
+
+ --with-debug
+
+ --with-profile
+ The shared and normal (static) library names differ
+ 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
+ library, but it is sometimes useful to configure this
+ in the shared library. Configure scripts should
+ check for the function's existence rather than assum-
+ ing it is always in the debug library.
+
+
FILES
/usr/share/tabset
@@ -898,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
@@ -914,57 +1118,66 @@
ual pages for details.
The ncurses library can exploit the capabilities of termi-
- nals 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 indepen-
- dently, providing better control over color contrasts.
- 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
+ nals which implement the ISO-6429 SGR 39 and SGR 49 con-
+ 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
+ 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
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 pre-
- sent 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.
@@ -985,7 +1198,7 @@
- ncurses(3x)
+ ncurses(3x)