X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=692ea2a960388c7c2943696221103c13ddc553a7;hb=5925150381bb42a4d8c7116d62c348a7b84309f3;hp=630a7805e350b27968122bd3086ce665768dfd14;hpb=cb4427a16794d98049b4d790b810d62217501f9f;p=ncurses.git
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html
index 630a7805..692ea2a9 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 20190316).
+ This describes ncurses version 6.2 (patch 20201212).
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);
@@ -176,7 +176,7 @@
standard place. For example, if TERM is set to att4424, then the com-
piled terminal definition is found in
- /usr/share/terminfo/a/att4424.
+ /usr/local/ncurses/lib/terminfo/a/att4424.
(The a is copied from the first letter of att4424 to avoid creation of
huge directories.) However, if TERMINFO is set to $HOME/myterms,
@@ -186,10 +186,10 @@
and if that fails, it then checks
- /usr/share/terminfo/a/att4424.
+ /usr/local/ncurses/lib/terminfo/a/att4424.
This is useful for developing experimental definitions or when write
- permission in /usr/share/terminfo is not available.
+ permission in /usr/local/ncurses/lib/terminfo is not available.
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
@@ -258,41 +258,34 @@
Each cell (row and column) in a WINDOW is stored as a
cchar_t.
+ The setcchar(3x) and getcchar(3x) functions store and
+ retrieve the data from a cchar_t structure.
+
wchar_t
- stores a "wide" character. Like chtype, this may be an
+ 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
+ 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 "normal" library. There is a naming con-
- vention which relates many of the normal/wide variants: a "_w"
+ The "wide" library provides new functions which are analogous
+ to functions in the "normal" library. There is a naming con-
+ vention which relates many of the normal/wide variants: a "_w"
is inserted into the name. For example, waddch becomes
wadd_wch.
- 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 +305,6 @@
attroff curs_attr(3x)
attron curs_attr(3x)
attrset curs_attr(3x)
-
baudrate curs_termattrs(3x)
beep curs_beep(3x)
bkgd curs_bkgd(3x)
@@ -321,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)
@@ -334,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)
@@ -354,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,12 +374,12 @@
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)
getwin curs_util(3x)
@@ -393,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,11 +441,11 @@
keyname curs_util(3x)
keyok keyok(3x)*
keypad curs_inopts(3x)
-
killchar curs_termattrs(3x)
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,11 +507,11 @@
mvwchgat curs_attr(3x)
mvwdelch curs_delch(3x)
mvwget_wch curs_get_wch(3x)
-
mvwget_wstr curs_get_wstr(3x)
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)
@@ -548,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)
@@ -565,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,9 +575,9 @@
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)
@@ -605,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,8 +642,8 @@
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,8 +708,8 @@
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)
@@ -738,33 +738,50 @@
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
+ Routines that return an integer return ERR upon failure and an integer
value other than ERR upon successful completion, unless otherwise noted
in the routine descriptions.
- As a general rule, routines check for null pointers passed as parame-
+ As a general rule, routines check for null pointers passed as parame-
ters, and handle this as an error.
- All macros return the value of the w version, except setscrreg,
- wsetscrreg, getyx, getbegyx, and getmaxyx. The 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
+ All macros return the value of the w version, except setscrreg,
+ wsetscrreg, getyx, getbegyx, and getmaxyx. The 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).
+ 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.
- The following environment symbols are useful for customizing the run-
- time behavior of the ncurses library. The most important ones have
+ The following environment symbols are useful for customizing the run-
+ time behavior of the ncurses library. The most important ones have
been already discussed in detail.
- When set, change occurrences of the command_character (i.e., the cmdch
- capability) of the loaded terminfo entries to the value of this vari-
+ When set, change occurrences of the command_character (i.e., the cmdch
+ capability) of the loaded terminfo entries to the value of this vari-
able. Very few terminfo entries provide this feature.
Because this name is also used in development environments to represent
@@ -773,34 +790,34 @@
- The debugging library checks this environment variable when the appli-
- cation has redirected output to a file. The variable'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 into
+ The debugging library checks this environment variable when the appli-
+ cation has redirected output to a file. The variable'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 into
account costs that depend on baudrate.
Specify the width of the screen in characters. Applications running in
- a windowing environment usually 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
+ a windowing environment usually 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. 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. How-
- ever, setting COLUMNS and/or LINES overrides the library's use of the
+ 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. How-
+ ever, 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 descrip-
+ Either COLUMNS or LINES symbols may be specified independently. This
+ is mainly useful to circumvent legacy misfeatures of terminal descrip-
tions, e.g., xterm which commonly specifies a 65 line screen. For best
- results, lines and cols should not be specified in a terminal descrip-
+ results, lines and cols should not be specified in a terminal descrip-
tion for terminals which are run as emulations.
- Use the use_env function to disable all use of external environment
+ Use the use_env function to disable all use of external environment
(but not including system calls) to determine the screen size. Use the
use_tioctl function to update COLUMNS or LINES to match the screen size
obtained from system calls or the terminal database.
@@ -808,31 +825,31 @@
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 variable
+ a character sequence, e.g., a function key. The default value, 1000
+ milliseconds, is enough for most uses. However, it is made a variable
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. The library will
+ 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. The library will
still see a timeout.
- Note that xterm mouse events are built up from character sequences
+ Note that xterm mouse events are built up from character sequences
received from the xterm. If your application makes heavy use of multi-
- ple-clicking, you may wish to lengthen this default value because the
- timeout applies to the composed multi-click event as well as the indi-
+ ple-clicking, you may wish to lengthen this default value because the
+ timeout applies to the composed multi-click event as well as the indi-
vidual clicks.
In addition to the environment variable, this implementation 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
+ 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 application.
- Tells ncurses where your home directory is. That is where it may read
+ Tells ncurses where your home directory is. That is where it may read
and write auxiliary terminal descriptions:
$HOME/.termcap
@@ -846,7 +863,7 @@
This applies only to the OS/2 EMX port. It specifies the order of but-
- tons on the mouse. OS/2 numbers a 3-button mouse inconsistently from
+ tons on the mouse. OS/2 numbers a 3-button mouse inconsistently from
other platforms:
1 = left
@@ -859,32 +876,32 @@
- Override the compiled-in assumption that the terminal's default colors
- are white-on-black (see default_colors(3x)). You may set the fore-
- ground and background color values with this environment 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
+ Override the compiled-in assumption that the terminal's default colors
+ are white-on-black (see default_colors(3x)). You may set the fore-
+ ground and background color values with this environment 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_colors value is allowed.
This applies only to the MinGW port of ncurses.
- The Console2 program's handling of the Microsoft Console API call Cre-
- ateConsoleScreenBuffer is defective. Applications which use this will
- hang. However, it is possible to simulate the action of this call by
- mapping coordinates, explicitly saving and restoring the original
- screen contents. Setting the environment variable NCGDB has the same
+ The Console2 program's handling of the Microsoft Console API call Cre-
+ ateConsoleScreenBuffer is defective. Applications which use this will
+ hang. However, it is possible to simulate the action of this call by
+ mapping coordinates, explicitly saving and restoring the original
+ screen contents. Setting the environment variable NCGDB has the same
effect.
This applies only to ncurses configured to use the GPM interface.
- If present, the environment variable is a list of one or more terminal
- names against which the TERM environment variable is matched. Setting
- it to an empty value disables the GPM interface; using the built-in
+ If present, the environment variable is a list of one or more terminal
+ names against which the TERM environment variable is matched. Setting
+ it to an empty value disables the GPM interface; using the built-in
support for xterm, etc.
If the environment variable is absent, ncurses will attempt to open GPM
@@ -892,38 +909,38 @@
- 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
+ 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.
- Some terminals use a magic-cookie feature which requires special han-
+ Some terminals use a magic-cookie feature which requires special han-
dling to make highlighting and other video attributes display properly.
- You can suppress the highlighting entirely for these terminals by set-
+ You can suppress the highlighting entirely for these terminals by set-
ting this environment variable.
- Most of the terminal descriptions in the terminfo database are written
- for real "hardware" terminals. Many people use terminal emulators
+ 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 applications.
- 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
+ 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 control), it (or your application) must manage dataflow, pre-
venting overruns. The cheapest solution (no hardware cost) is for your
- program to do this by pausing after operations that the terminal does
+ 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
+ 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 environment variable to disable all but
+ Set the NCURSES_NO_PADDING environment variable to disable all but
mandatory padding. Mandatory padding is used as a part of special con-
trol sequences such as flash.
@@ -935,44 +952,44 @@
o continued though 5.9 patch 20130126
- ncurses enabled buffered output during terminal initialization. This
+ ncurses enabled buffered output during terminal initialization. This
was done (as in SVr4 curses) for performance reasons. For testing pur-
- poses, both of ncurses and certain applications, this feature was made
+ poses, both of ncurses and certain applications, this feature was made
optional. Setting the NCURSES_NO_SETBUF variable disabled output
- buffering, leaving the output in the original (usually line buffered)
+ buffering, leaving the output in the original (usually line buffered)
mode.
- In the current implementation, ncurses performs its own buffering and
- does not require this workaround. It does not modify the buffering of
+ In the current implementation, ncurses performs its own buffering and
+ does not require this workaround. It does not modify the buffering of
the standard output.
- The reason for the change was to make the behavior for interrupts and
- other signals more robust. One drawback is that certain nonconven-
- tional programs would mix ordinary stdio calls with ncurses calls and
- (usually) work. This is no longer possible since ncurses is not using
- the buffered standard output but its own output (to the same file
+ The reason for the change was to make the behavior for interrupts and
+ other signals more robust. One drawback is that certain nonconven-
+ tional programs would mix ordinary stdio calls with ncurses calls and
+ (usually) work. This is no longer possible since ncurses is not using
+ the buffered standard output but its own output (to the same file
descriptor). As a special case, the low-level calls such as putp still
use the standard output. But high-level curses calls do not.
- During initialization, the ncurses library checks for special cases
+ During initialization, the ncurses library checks for special cases
where VT100 line-drawing (and the corresponding alternate character set
- capabilities) described in the terminfo are known to be missing.
- Specifically, when running in a UTF-8 locale, the Linux console emula-
- tor and the GNU screen program ignore these. Ncurses checks the TERM
- environment variable for these. For other special cases, you should
+ capabilities) described in the terminfo are known to be missing.
+ Specifically, when running in a UTF-8 locale, the Linux console emula-
+ tor 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 terminal emula-
+ values which correspond to the VT100 line-drawing glyphs. That works
+ for the special cases cited, and is likely to work for terminal emula-
tors.
When setting this variable, you should set it to a nonzero value. Set-
- ting it to zero (or to a nonnumber) disables the special check for
+ ting it to zero (or to a nonnumber) disables the special check for
"linux" and "screen".
- As an alternative to the environment variable, ncurses checks for an
- extended terminfo capability U8. This is a numeric capability which
+ As an alternative to the environment variable, ncurses checks for an
+ extended terminfo capability U8. This is a numeric capability which
can be compiled using tic -x. For example
# linux console, if patched to provide working
@@ -984,67 +1001,67 @@
xterm-utf8|xterm relying on UTF-8 line-graphics,
U8#1, use=xterm,
- The name "U8" is chosen to be two characters, to permit it to be used
+ The name "U8" is chosen to be two characters, to permit it to be used
by applications that use ncurses' termcap interface.
- During initialization, the ncurses debugging library checks the
- NCURSES_TRACE environment variable. If it is defined, to a numeric
- value, ncurses calls the trace function, using that value as the argu-
+ During initialization, the ncurses debugging library checks the
+ NCURSES_TRACE environment variable. If it is defined, to a numeric
+ value, ncurses calls the trace function, using that value as the argu-
ment.
- The argument values, which are defined in curses.h, provide several
- types of information. When running with traces enabled, your applica-
+ The argument values, which are defined in curses.h, provide several
+ types of information. When running with traces enabled, your applica-
tion will write the file trace to the current directory.
See curs_trace(3x) for more information.
- Denotes your terminal type. Each terminal type is distinct, though
+ Denotes your terminal type. Each terminal type is distinct, though
many are similar.
- TERM is commonly set by terminal emulators to help applications find a
+ TERM is commonly set by terminal emulators to help applications find a
workable terminal description. Some of those choose a popular approxi-
- mation, e.g., "ansi", "vt100", "xterm" rather than an exact fit. Not
- infrequently, your application will have problems with that approach,
+ mation, e.g., "ansi", "vt100", "xterm" rather than an exact fit. Not
+ infrequently, your application will have problems with that approach,
e.g., incorrect function-key definitions.
- If you set TERM in your environment, it has no effect on the operation
- of the terminal emulator. It only affects the way applications work
- within the terminal. Likewise, as a general rule (xterm being a rare
- exception), terminal emulators which allow you to specify TERM as a
- parameter or configuration value do not change their behavior to match
+ If you set TERM in your environment, it has no effect on the operation
+ of the terminal emulator. It only affects the way applications work
+ within the terminal. Likewise, as a general rule (xterm being a rare
+ exception), terminal emulators which allow you to specify TERM as a
+ parameter or configuration value do not change their behavior to match
that setting.
- If the ncurses library has been configured with termcap support,
- ncurses will check for a terminal's description in termcap form if it
+ If the ncurses library has been configured with termcap support,
+ ncurses will check for a terminal's description in termcap form if it
is not available in the terminfo database.
The TERMCAP environment variable contains either a terminal description
(with newlines stripped out), or a file name telling where the informa-
- tion denoted by the TERM environment variable exists. In either case,
- setting it directs ncurses to ignore the usual place for this informa-
+ tion denoted by the TERM environment variable exists. In either case,
+ setting it directs ncurses to ignore the usual place for this informa-
tion, e.g., /etc/termcap.
- ncurses can be configured to read from multiple terminal databases.
- The TERMINFO variable overrides the location for the default terminal
- database. Terminal descriptions (in terminal format) are stored in
+ ncurses can be configured to read from multiple terminal databases.
+ The TERMINFO variable overrides the location for the default terminal
+ database. Terminal descriptions (in terminal format) are stored in
terminal databases:
o Normally these are stored in a directory tree, using subdirectories
named by the first letter of the terminal names therein.
This is the scheme used in System V, which legacy Unix systems use,
- and the TERMINFO variable is used by curses applications on those
+ and the TERMINFO variable is used by curses applications on those
systems to override the default location of the terminal database.
- o If ncurses is built to use hashed databases, then each entry in
+ o If ncurses is built to use hashed databases, then each entry in
this list may be the path of a hashed database file, e.g.,
/usr/share/terminfo.db
@@ -1053,30 +1070,30 @@
/usr/share/terminfo/
- The hashed database uses less disk-space and is a little faster
- than the directory tree. However, some applications assume the
- existence of the directory tree, reading it directly rather than
+ The hashed database uses less disk-space and is a little faster
+ than the directory tree. However, some applications assume the
+ existence of the directory tree, reading it directly rather than
using the terminfo library calls.
- o If ncurses is built with a support for reading termcap files
- directly, then an entry in this list may be the path of a termcap
+ o If ncurses is built with a support for reading termcap files
+ directly, then an entry in this list may be the path of a termcap
file.
o If the TERMINFO variable begins with "hex:" or "b64:", ncurses uses
- the remainder of that variable as a compiled terminal description.
+ the remainder of that variable as a compiled terminal description.
You might produce the base64 format using infocmp(1m):
TERMINFO="$(infocmp -0 -Q2 -q)"
export TERMINFO
- The compiled description is used if it corresponds to the terminal
+ The compiled description is used if it corresponds to the terminal
identified by the TERM variable.
- Setting TERMINFO is the simplest, but not the only way to set location
- of the default terminal database. The complete list of database loca-
+ Setting TERMINFO is the simplest, but not the only way to set location
+ of the default terminal database. The complete list of database loca-
tions in order follows:
- o the last terminal database to which ncurses wrote, if any, is
+ o the last terminal database to which ncurses wrote, if any, is
searched first
o the location specified by the TERMINFO environment variable
@@ -1085,13 +1102,14 @@
o locations listed in the TERMINFO_DIRS environment variable
- o one or more locations whose names are configured and compiled
+ o one or more locations whose names are configured and compiled
into the ncurses library, i.e.,
o /usr/local/ncurses/share/terminfo:/usr/share/terminfo (corre-
sponding to the TERMINFO_DIRS variable)
- o /usr/share/terminfo (corresponding to the TERMINFO variable)
+ o /usr/local/ncurses/lib/terminfo (corresponding to the TER-
+ MINFO variable)
@@ -1209,17 +1227,42 @@
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-
- bility database /usr/share/terminfo terminal capability database
+ directory containing initialization files for the terminal capa-
+ bility database /usr/local/ncurses/lib/terminfo terminal capabil-
+ ity database
@@ -1273,28 +1316,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.
@@ -1304,28 +1356,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.
@@ -1380,7 +1522,14 @@
FILES
SEE ALSO
EXTENSIONS
-PORTABILITY
+PORTABILITY
+
+
NOTES
AUTHORS