X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fncurses.3x.html;h=26f8865c7650363a193ceaffae6507a07d553187;hp=d92016cedbaa32b36e3101732d1a61a877449158;hb=51a395aaa20e4aa687310bb8cb1616ccf8e8fd0d;hpb=0485620c03e69b1b58a6b12e5e45c98415fc7575
diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html
index d92016ce..26f8865c 100644
--- a/doc/html/man/ncurses.3x.html
+++ b/doc/html/man/ncurses.3x.html
@@ -1,7 +1,7 @@
-
+
ncurses 3x
-
+
@@ -59,7 +59,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 20170819).
+ This describes ncurses version 6.1 (patch 20190615).
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 +92,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 +108,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,20 +176,20 @@
standard place. For example, if TERM is set to att4424, then the com-
piled terminal definition is found in
- /usr/local/ncurses/lib/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/local/ncurses/lib/terminfo/a/att4424.
+ /usr/share/terminfo/a/att4424.
This is useful for developing experimental definitions or when write
- permission in /usr/local/ncurses/lib/terminfo is not available.
+ permission in /usr/share/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
@@ -640,7 +640,7 @@
use_env curs_util(3x)
use_extended_names curs_extend(3x)*
use_legacy_coding legacy_coding(3x)*
- use_tioctl curs_util(3x)
+ use_tioctl curs_util(3x)*
vid_attr curs_terminfo(3x)
vid_puts curs_terminfo(3x)
@@ -835,8 +835,8 @@
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
@@ -849,9 +849,9 @@
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-
@@ -1047,11 +1047,11 @@
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
@@ -1066,8 +1066,8 @@
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
identified by the TERM variable.
@@ -1091,14 +1091,13 @@
o /usr/local/ncurses/share/terminfo:/usr/share/terminfo (corre-
sponding to the TERMINFO_DIRS variable)
- o /usr/local/ncurses/lib/terminfo (corresponding to the TER-
- MINFO variable)
+ o /usr/share/terminfo (corresponding to the TERMINFO variable)
- 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-
@@ -1106,66 +1105,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 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
+ 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.
+
+ 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
@@ -1199,65 +1219,64 @@
- terminfo(5) and related pages whose names begin "curs_" for detailed
+ terminfo(5) and related pages whose names begin "curs_" for detailed
routine descriptions.
curs_variables(3x)user_caps(5) for user-defined capabilities
- The ncurses library can be compiled with an option (-DUSE_GETCAP) that
- falls back to the old-style /etc/termcap file if the terminal setup
- code cannot find a terminfo entry corresponding to TERM. Use of this
- feature is not recommended, as it essentially includes an entire term-
- cap compiler in the ncurses startup code, at significant cost in core
+ The ncurses library can be compiled with an option (-DUSE_GETCAP) that
+ falls back to the old-style /etc/termcap file if the terminal setup
+ code cannot find a terminfo entry corresponding to TERM. Use of this
+ feature is not recommended, as it essentially includes an entire term-
+ cap compiler in the ncurses startup code, at significant cost in core
and startup cycles.
- The ncurses library includes facilities for capturing mouse events on
- certain terminals (including xterm). See the curs_mouse(3x) manual
+ The ncurses library includes facilities for capturing mouse events on
+ certain terminals (including xterm). See the curs_mouse(3x) manual
page for details.
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
+ wresize(3x) manual pages for details. In addition, the library may be
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
- key sequences at runtime. See the define_key(3x)key_defined(3x), and
+ The ncurses library extends the fixed set of function key capabilities
+ of terminals by allowing the application designer to define additional
+ key sequences at runtime. See the define_key(3x)key_defined(3x), and
keyok(3x) manual pages for details.
- The ncurses library can exploit the capabilities of terminals which
- implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
- application to reset the terminal to its original foreground and back-
+ The ncurses library can exploit the capabilities of terminals which
+ implement the ISO-6429 SGR 39 and SGR 49 controls, which allow an
+ application to reset the terminal to its original foreground and back-
ground colors. From the users' perspective, the application is able to
- draw colored text on a background whose color is set independently,
- providing better control over color contrasts. See the default_col-
+ draw colored text on a background whose color is set independently,
+ providing better control over color contrasts. See the default_col-ors(3x) manual page for details.
- The ncurses library includes a function for directing application out-
- put to a printer attached to the terminal device. See the
+ The ncurses library includes a function for directing application out-
+ put to a printer attached to the terminal device. See the
curs_print(3x) manual page for details.
- The ncurses library is intended to be BASE-level conformant with XSI
- Curses. The EXTENDED XSI Curses functionality (including color sup-
+ The ncurses library is intended to be BASE-level conformant with XSI
+ Curses. The EXTENDED XSI Curses functionality (including color sup-
port) is supported.
- A small number of local differences (that is, individual differences
- between the XSI Curses and ncurses calls) are described in PORTABILITY
+ 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.
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.
@@ -1267,15 +1286,15 @@
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.
@@ -1285,28 +1304,28 @@
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.
+ 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.