X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=bda5c0ccd28e723041dc734a06c8b08fdb972581;hp=b1f5bad6408d9b1827f99c607d6fff2f06535ab3;hb=c0f109a299a82a33c16bd7af942a12ce9aefaaf0;hpb=b793748293cd1a764b1a858455399ad899b5a8a1
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html
index b1f5bad6..bda5c0cc 100644
--- a/doc/html/man/ncurses.3x.html
+++ b/doc/html/man/ncurses.3x.html
@@ -1,7 +1,8 @@
-
+
ncurses 3x
-
+
@@ -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.0 (patch 20170520).
+ This describes ncurses version 6.2 (patch 20200314).
The ncurses library emulates the curses library of System V Release 4
UNIX, and XPG4 (X/Open Portability Guide) curses (also known as XSI
@@ -92,7 +93,7 @@
The library uses the locale which the calling program has initialized.
That is normally done with setlocale:
- setlocale(LC_ALL,"");
+ setlocale(LC_ALL,"");
If the locale is not initialized, the library assumes that characters
are printable as in ISO-8859-1, to work with certain legacy programs.
@@ -108,13 +109,13 @@
screen oriented programs want this), the following sequence should be
used:
- initscr();cbreak();noecho();
+ initscr();cbreak();noecho();
Most programs would additionally use the sequence:
- nonl();
- intrflush(stdscr,FALSE);
- keypad(stdscr,TRUE);
+ nonl();
+ intrflush(stdscr,FALSE);
+ keypad(stdscr,TRUE);
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
@@ -176,17 +177,17 @@
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/share/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,
curses first checks
- $HOME/myterms/a/att4424,
+ $HOME/myterms/a/att4424,
and if that fails, it then checks
- /usr/share/terminfo/a/att4424.
+ /usr/share/terminfo/a/att4424.
This is useful for developing experimental definitions or when write
permission in /usr/share/terminfo is not available.
@@ -258,24 +259,27 @@
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.
- 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).
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 +777,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,35 +812,35 @@
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
- $HOME/.terminfo
+ $HOME/.termcap
+ $HOME/.terminfo
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
- 2 = right
- 3 = middle.
+ 1 = left
+ 2 = right
+ 3 = middle.
This variable lets you customize the mouse. The variable must be three
numeric digits 1-3 in any order, e.g., 123 or 321. If it is not speci-
@@ -859,32 +863,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 +896,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 +939,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,99 +988,99 @@
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
+ /usr/share/terminfo.db
rather than
- /usr/share/terminfo/
+ /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
+ 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,7 +1089,7 @@
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-
@@ -1095,9 +1099,9 @@
- Specifies a list of locations to search for terminal descriptions.
- Each location in the list is a terminal database as described in the
- section on the TERMINFO variable. The list is separated by colons
+ Specifies a list of locations to search for terminal descriptions.
+ Each location in the list is a terminal database as described in the
+ section on the TERMINFO variable. The list is separated by colons
(i.e., ":") on Unix, semicolons on OS/2 EMX.
There is no corresponding feature in System V terminfo; it is an exten-
@@ -1105,66 +1109,87 @@
- If TERMCAP does not hold a file name then ncurses checks the TERMPATH
- environment variable. This is a list of filenames separated by spaces
+ If TERMCAP does not hold a file name then ncurses checks the TERMPATH
+ environment variable. This is a list of filenames separated by spaces
or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
- If the TERMPATH environment variable is not set, ncurses looks in the
+ If the TERMPATH environment variable is not set, ncurses looks in the
files
- /etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
+ /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), or if the application uses
+ the current user is the superuser (root), or if the application uses
setuid or setgid permissions:
- $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
+ $TERMINFO, $TERMINFO_DIRS, $TERMPATH, as well as $HOME.
Several different configurations are possible, depending on the config-
- ure script options used when building ncurses. There are a few main
- options whose effects are visible to the applications developer using
+ ure 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 SYNOPSIS:
- #include<curses.h>
+ #include<curses.h>
- This option is used to avoid filename conflicts when ncurses is
+ 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 subdi-
+ is installed disabling overwrite, it puts its headers in a subdi-
rectory, e.g.,
- #include<ncurses/curses.h>
+ #include<ncurses/curses.h>
- It also omits a symbolic link which would allow you to use
+ 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 --dis-
- able-overwrite option is used) puts the header files in a differ-
+ The configure script renames the library and (if the --dis-
+ able-overwrite option is used) puts the header files in a differ-
ent subdirectory. All of the library names have a "w" appended to
them, i.e., instead of
- -lncurses
+ -lncurses
you link with
- -lncursesw
+ -lncursesw
+
+ You must also enable the wide-character features in the header
+ file when compiling for the wide-character library to use the
+ extended (wide-character) functions. The symbol which enables
+ these features has changed since XSI Curses, Issue 4:
+
+ o Originally, the wide-character feature required the symbol
+ _XOPEN_SOURCE_EXTENDED but that was only valid for XPG4
+ (1996).
+
+ o Later, that was deemed conflicting with _XOPEN_SOURCE defined
+ to 500.
- You must also define _XOPEN_SOURCE_EXTENDED when compiling for the
- wide-character library to use the extended (wide-character) func-
- tions. The curses.h file which is installed for the wide-charac-
- ter library is designed to be compatible with the normal library's
+ o As of mid-2018, none of the features in this implementation
+ require a _XOPEN_SOURCE feature greater than 600. However,
+ X/Open Curses, Issue 7 (2009) recommends defining it to 700.
+
+ o Alternatively, you can enable the feature by defining
+ NCURSES_WIDECHAR with the caveat that some other header file
+ than curses.h may require a specific value for _XOPEN_SOURCE
+ (or a system-specific symbol).
+
+ 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.
+ few applications require more than a pointer to WINDOWs.
+
+ If the headers are installed allowing overwrite, the wide-charac-
+ ter library's headers should be installed last, to allow applica-
+ tions to be built using either library from the same set of head-
+ ers.
--with-pthread
The configure script renames the library. All of the library
@@ -1205,6 +1230,7 @@
terminfo(5) and related pages whose names begin "curs_" for detailed
routine descriptions.
curs_variables(3x)
+ user_caps(5) for user-defined capabilities
@@ -1222,7 +1248,7 @@
The ncurses library includes facilities for responding to window resiz-
ing events, e.g., when running in an xterm. See the resizeterm(3x) and
wresize(3x) manual pages for details. In addition, the library may be
- configured with a SIGWINCH handler.
+ configured with a SIGWINCH handler.
The ncurses library extends the fixed set of function key capabilities
of terminals by allowing the application designer to define additional
@@ -1251,28 +1277,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.
@@ -1282,28 +1317,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
<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 "maymakevisible" 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.
@@ -1358,7 +1483,14 @@