* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: ncurses.3x,v 1.181 2023/11/25 14:32:36 tom Exp @
+ * @Id: ncurses.3x,v 1.185 2023/12/03 00:14:35 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
-<TITLE>ncurses 3x 2023-11-25 ncurses 6.4 Library calls</TITLE>
+<TITLE>ncurses 3x 2023-12-02 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">ncurses 3x 2023-11-25 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">ncurses 3x 2023-12-02 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> Library calls <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
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 <STRONG>ncurses</STRONG> version 6.4 (patch 20231125).
+ This describes <STRONG>ncurses</STRONG> version 6.4 (patch 20231202).
The <STRONG>ncurses</STRONG> library emulates the curses library of System V Release 4
Unix ("SVr4"), and XPG4 (X/Open Portability Guide) curses (also known
Before a <STRONG>curses</STRONG> program is run, the tab stops of the terminal should be
set and its initialization strings, if defined, must be output. This
can be done by executing the <STRONG>tput</STRONG> <STRONG>init</STRONG> command after the shell
- environment variable <
STRONG>TERM</STRONG> has been exported. (The BSD-style <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>
+ environment variable <
EM>TERM</EM> has been exported. (The BSD-style <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>
utility also performs this function.) See subsection "Tabs and
Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
</PRE><H3><a name="h3-Environment-variables">Environment variables</a></H3><PRE>
- If the environment variables <STRONG>LINES</STRONG> and <STRONG>COLUMNS</STRONG> are set, or if the
+ If the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> are set, or if the
program is executing in a window environment, line and column
information in the environment will override information read by
<EM>terminfo</EM>. This would affect a program running in an AT&T 630 layer,
for example, where the size of a screen is changeable (see
<STRONG>ENVIRONMENT</STRONG>).
- If the environment variable <STRONG>TERMINFO</STRONG> is defined, any program using
+ If the environment variable <EM>TERMINFO</EM> is defined, any program using
<STRONG>curses</STRONG> checks for a local terminal definition before checking in the
- standard place. For example, if <STRONG>TERM</STRONG> is set to <STRONG>att4424</STRONG>, then the
+ standard place. For example, if <EM>TERM</EM> is set to <STRONG>att4424</STRONG>, then the
compiled terminal definition is found in
<STRONG>/usr/share/terminfo/a/att4424</STRONG>.
(The <STRONG>a</STRONG> is copied from the first letter of <STRONG>att4424</STRONG> to avoid creation of
- huge directories.) However, if <STRONG>TERMINFO</STRONG> is set to <STRONG>$HOME/myterms</STRONG>,
+ huge directories.) However, if <EM>TERMINFO</EM> is set to <STRONG>$HOME/myterms</STRONG>,
<STRONG>curses</STRONG> first checks
<STRONG>$HOME/myterms/a/att4424</STRONG>,
been already discussed in detail.
-</PRE><H3><a name="h3-CC-command-character">
CC command-character</a></H3><PRE>
+</PRE><H3><a name="h3-CC-command-character">
<EM>CC</EM> command-character</a></H3><PRE>
When set, change occurrences of the command_character (i.e., the <STRONG>cmdch</STRONG>
capability) of the loaded terminfo entries to the value of this
variable. Very few terminfo entries provide this feature.
single character.
-</PRE><H3><a name="h3-BAUDRATE">
BAUDRATE</a></H3><PRE>
+</PRE><H3><a name="h3-BAUDRATE">
<EM>BAUDRATE</EM></a></H3><PRE>
The debugging library checks this environment variable when the
application has redirected output to a file. The variable's numeric
value is used for the baudrate. If no value is found, <STRONG>ncurses</STRONG> uses
into account costs that depend on baudrate.
-</PRE><H3><a name="h3-COLUMNS">
COLUMNS</a></H3><PRE>
+</PRE><H3><a name="h3-COLUMNS">
<EM>COLUMNS</EM></a></H3><PRE>
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 <STRONG>COLUMNS</STRONG> value nor
+ window in which they are executing. If neither the <EM>COLUMNS</EM> value nor
the terminal's screen size is available, <STRONG>ncurses</STRONG> uses the size which
may be specified in the terminfo database (i.e., the <STRONG>cols</STRONG> capability).
screen. This is not always possible because your application may be
running on a host which does not honor NAWS (Negotiations About Window
Size), or because you are temporarily running as another user.
- However, setting <STRONG>COLUMNS</STRONG> and/or <STRONG>LINES</STRONG> overrides the library's use of
+ However, setting <EM>COLUMNS</EM> and/or <EM>LINES</EM> overrides the library's use of
the screen size obtained from the operating system.
- Either <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> symbols may be specified independently. This
+ Either <EM>COLUMNS</EM> or <EM>LINES</EM> symbols may be specified independently. This
is mainly useful to circumvent legacy misfeatures of terminal
descriptions, e.g., xterm which commonly specifies a 65 line screen.
For best results, <STRONG>lines</STRONG> and <STRONG>cols</STRONG> should not be specified in a terminal
Use the <STRONG>use_env</STRONG> function to disable all use of external environment
(but not including system calls) to determine the screen size. Use the
- <STRONG>use_tioctl</STRONG> function to update <STRONG>COLUMNS</STRONG> or <STRONG>LINES</STRONG> to match the screen size
+ <STRONG>use_tioctl</STRONG> function to update <EM>COLUMNS</EM> or <EM>LINES</EM> to match the screen size
obtained from system calls or the terminal database.
-</PRE><H3><a name="h3-ESCDELAY">
ESCDELAY</a></H3><PRE>
+</PRE><H3><a name="h3-ESCDELAY">
<EM>ESCDELAY</EM></a></H3><PRE>
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
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
+ rely upon the presence of <STRONG>ESCDELAY</STRONG> in either form, but setting the
environment variable rather than the global variable does not create
problems when compiling an application.
-</PRE><H3><a name="h3-HOME">
HOME</a></H3><PRE>
+</PRE><H3><a name="h3-HOME">
<EM>HOME</EM></a></H3><PRE>
Tells <STRONG>ncurses</STRONG> where your home directory is. That is where it may read
and write auxiliary terminal descriptions:
$HOME/.terminfo
-</PRE><H3><a name="h3-LINES">
LINES</a></H3><PRE>
- Like COLUMNS, specify the height of the screen in characters. See
- COLUMNS for a detailed description.
+</PRE><H3><a name="h3-LINES">
<EM>LINES</EM></a></H3><PRE>
+ Like <EM>COLUMNS</EM>, specify the height of the screen in characters. See
+ <EM>COLUMNS</EM> for a detailed description.
-</PRE><H3><a name="h3-MOUSE_BUTTONS_123">
MOUSE_BUTTONS_123</a></H3><PRE>
+</PRE><H3><a name="h3-MOUSE_BUTTONS_123">
<EM>MOUSE_BUTTONS_123</EM></a></H3><PRE>
This applies only to the OS/2 EMX port. It specifies the order of
buttons on the mouse. OS/2 numbers a 3-button mouse inconsistently
from other platforms:
specified, <STRONG>ncurses</STRONG> uses 132.
-</PRE><H3><a name="h3-NCURSES_ASSUMED_COLORS">
NCURSES_ASSUMED_COLORS</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_ASSUMED_COLORS">
<EM>NCURSES_ASSUMED_COLORS</EM></a></H3><PRE>
Override the compiled-in assumption that the terminal's default colors
are white-on-black (see <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>). You may set the
foreground and background color values with this environment variable
value from zero to the terminfo <STRONG>max_colors</STRONG> value is allowed.
-</PRE><H3><a name="h3-NCURSES_CONSOLE2">
NCURSES_CONSOLE2</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_CONSOLE2">
<EM>NCURSES_CONSOLE2</EM></a></H3><PRE>
This applies only to the MinGW port of ncurses.
The <STRONG>Console2</STRONG> program's handling of the Microsoft Console API call
effect.
-</PRE><H3><a name="h3-NCURSES_GPM_TERMS">
NCURSES_GPM_TERMS</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_GPM_TERMS">
<EM>NCURSES_GPM_TERMS</EM></a></H3><PRE>
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 <STRONG>TERM</STRONG> environment variable is matched. Setting
+ names against which the <EM>TERM</EM> 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
- if <STRONG>TERM</STRONG> contains "linux".
+ if <EM>TERM</EM> contains "linux".
-</PRE><H3><a name="h3-NCURSES_NO_HARD_TABS">
NCURSES_NO_HARD_TABS</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_NO_HARD_TABS">
<EM>NCURSES_NO_HARD_TABS</EM></a></H3><PRE>
<STRONG>Ncurses</STRONG> 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 <STRONG>stty(1)</STRONG> settings to avoid the problem.
-</PRE><H3><a name="h3-NCURSES_NO_MAGIC_COOKIE">
NCURSES_NO_MAGIC_COOKIE</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_NO_MAGIC_COOKIE">
<EM>NCURSES_NO_MAGIC_COOKIE</EM></a></H3><PRE>
Some terminals use a magic-cookie feature which requires special
handling to make highlighting and other video attributes display
properly. You can suppress the highlighting entirely for these
terminals by setting this environment variable.
-</PRE><H3><a name="h3-NCURSES_NO_PADDING">
NCURSES_NO_PADDING</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_NO_PADDING">
<EM>NCURSES_NO_PADDING</EM></a></H3><PRE>
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.
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 <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>PADDING</EM> environment variable to disable all but
mandatory padding. Mandatory padding is used as a part of special
control sequences such as <STRONG>flash</STRONG>.
-</PRE><H3><a name="h3-NCURSES_NO_SETBUF">
NCURSES_NO_SETBUF</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_NO_SETBUF">
<EM>NCURSES_NO_SETBUF</EM></a></H3><PRE>
This setting is obsolete. Before changes
<STRONG>o</STRONG> started with 5.9 patch 20120825 and
<STRONG>ncurses</STRONG> enabled buffered output during terminal initialization. This
was done (as in SVr4 curses) for performance reasons. For testing
purposes, both of <STRONG>ncurses</STRONG> and certain applications, this feature was
- made optional. Setting the NCURSES_NO_SETBUF variable disabled output
+ made optional. Setting the <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>SETBUF</EM> variable disabled output
buffering, leaving the output in the original (usually line buffered)
mode.
still use the standard output. But high-level curses calls do not.
-</PRE><H3><a name="h3-NCURSES_NO_UTF8_ACS">
NCURSES_NO_UTF8_ACS</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_NO_UTF8_ACS">
<EM>NCURSES_NO_UTF8_ACS</EM></a></H3><PRE>
During initialization, the <STRONG>ncurses</STRONG> 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
emulator and the GNU screen program ignore these. Ncurses checks the
- <STRONG>TERM</STRONG> environment variable for these. For other special cases, you
+ <EM>TERM</EM> 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
by applications that use ncurses' termcap interface.
-</PRE><H3><a name="h3-NCURSES_TRACE">
NCURSES_TRACE</a></H3><PRE>
+</PRE><H3><a name="h3-NCURSES_TRACE">
<EM>NCURSES_TRACE</EM></a></H3><PRE>
During initialization, the <STRONG>ncurses</STRONG> debugging library checks the
- NCURSES_TRACE environment variable. If it is defined, to a numeric
+ <EM>NCURSES</EM><STRONG>_</STRONG><EM>TRACE</EM> environment variable. If it is defined, to a numeric
value, <STRONG>ncurses</STRONG> calls the <STRONG>trace</STRONG> function, using that value as the
argument.
See <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> for more information.
-</PRE><H3><a name="h3-TERM">
TERM</a></H3><PRE>
+</PRE><H3><a name="h3-TERM">
<EM>TERM</EM></a></H3><PRE>
Denotes your terminal type. Each terminal type is distinct, though
many are similar.
- <STRONG>TERM</STRONG> is commonly set by terminal emulators to help applications find a
+ <EM>TERM</EM> is commonly set by terminal emulators to help applications find a
workable terminal description. Some of those choose a popular
approximation, 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 <STRONG>TERM</STRONG> in your environment, it has no effect on the operation
+ If you set <EM>TERM</EM> 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 (<STRONG>xterm(1)</STRONG> being a
- rare exception), terminal emulators which allow you to specify <STRONG>TERM</STRONG> as
+ rare exception), terminal emulators which allow you to specify <EM>TERM</EM> as
a parameter or configuration value do not change their behavior to
match that setting.
-</PRE><H3><a name="h3-TERMCAP">
TERMCAP</a></H3><PRE>
+</PRE><H3><a name="h3-TERMCAP">
<EM>TERMCAP</EM></a></H3><PRE>
If the <STRONG>ncurses</STRONG> library has been configured with <EM>termcap</EM> support,
<STRONG>ncurses</STRONG> will check for a terminal's description in termcap form if it
is not available in the terminfo database.
- The <STRONG>TERMCAP</STRONG> environment variable contains either a terminal description
+ The <EM>TERMCAP</EM> environment variable contains either a terminal description
(with newlines stripped out), or a file name telling where the
- information denoted by the <STRONG>TERM</STRONG> environment variable exists. In either
+ information denoted by the <EM>TERM</EM> environment variable exists. In either
case, setting it directs <STRONG>ncurses</STRONG> to ignore the usual place for this
information, e.g., /etc/termcap.
-</PRE><H3><a name="h3-TERMINFO">
TERMINFO</a></H3><PRE>
+</PRE><H3><a name="h3-TERMINFO">
<EM>TERMINFO</EM></a></H3><PRE>
<STRONG>ncurses</STRONG> can be configured to read from multiple terminal databases.
- The <STRONG>TERMINFO</STRONG> variable overrides the location for the default terminal
+ The <EM>TERMINFO</EM> variable overrides the location for the default terminal
database. Terminal descriptions (in terminal format) are stored in
terminal databases:
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 <STRONG>TERMINFO</STRONG> variable is used by <EM>curses</EM> applications on those
+ and the <EM>TERMINFO</EM> variable is used by <EM>curses</EM> applications on those
systems to override the default location of the terminal database.
<STRONG>o</STRONG> If <STRONG>ncurses</STRONG> is built to use hashed databases, then each entry in
directly, then an entry in this list may be the path of a termcap
file.
- <STRONG>o</STRONG> If the <STRONG>TERMINFO</STRONG> variable begins with "hex:" or "b64:", <STRONG>ncurses</STRONG> uses
+ <STRONG>o</STRONG> If the <EM>TERMINFO</EM> variable begins with "hex:" or "b64:", <STRONG>ncurses</STRONG> uses
the remainder of that variable as a compiled terminal description.
You might produce the base64 format using <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>:
export TERMINFO
The compiled description is used if it corresponds to the terminal
- identified by the <STRONG>TERM</STRONG> variable.
+ identified by the <EM>TERM</EM> variable.
- Setting <STRONG>TERMINFO</STRONG> is the simplest, but not the only way to set location
+ Setting <EM>TERMINFO</EM> is the simplest, but not the only way to set location
of the default terminal database. The complete list of database
locations in order follows:
<STRONG>o</STRONG> the last terminal database to which <STRONG>ncurses</STRONG> wrote, if any, is
searched first
- <STRONG>o</STRONG> the location specified by the TERMINFO environment variable
+ <STRONG>o</STRONG> the location specified by the <EM>TERMINFO</EM> environment variable
<STRONG>o</STRONG> $HOME/.terminfo
- <STRONG>o</STRONG> locations listed in the TERMINFO_DIRS environment variable
+ <STRONG>o</STRONG> locations listed in the <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variable
<STRONG>o</STRONG> one or more locations whose names are configured and compiled
into the ncurses library, i.e.,
- <STRONG>o</STRONG> /usr/share/terminfo (corresponding to the TERMINFO_DIRS
+ <STRONG>o</STRONG> /usr/share/terminfo (corresponding to the <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM>
variable)
- <STRONG>o</STRONG> /usr/share/terminfo (corresponding to the TERMINFO variable)
+ <STRONG>o</STRONG> /usr/share/terminfo (corresponding to the <EM>TERMINFO</EM> variable)
-</PRE><H3><a name="h3-TERMINFO_DIRS">
TERMINFO_DIRS</a></H3><PRE>
+</PRE><H3><a name="h3-TERMINFO_DIRS">
<EM>TERMINFO_DIRS</EM></a></H3><PRE>
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 <STRONG>TERMINFO</STRONG> variable. The list is separated by colons
+ section on the <EM>TERMINFO</EM> 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
extension developed for <STRONG>ncurses</STRONG>.
-</PRE><H3><a name="h3-TERMPATH">
TERMPATH</a></H3><PRE>
- If <STRONG>TERMCAP</STRONG> does not hold a file name then <STRONG>ncurses</STRONG> checks the <STRONG>TERMPATH</STRONG>
+</PRE><H3><a name="h3-TERMPATH">
<EM>TERMPATH</EM></a></H3><PRE>
+ If <EM>TERMCAP</EM> does not hold a file name then <STRONG>ncurses</STRONG> checks the <EM>TERMPATH</EM>
environment variable. This is a list of filenames separated by spaces
or colons (i.e., ":") on Unix, semicolons on OS/2 EMX.
- If the <STRONG>TERMPATH</STRONG> environment variable is not set, <STRONG>ncurses</STRONG> looks in the
+ If the <EM>TERMPATH</EM> environment variable is not set, <STRONG>ncurses</STRONG> looks in the
files
/etc/termcap, /usr/share/misc/termcap and $HOME/.termcap,
</PRE><H2><a name="h2-FILES">FILES</a></H2><PRE>
<EM>/usr/share/tabset</EM>
- tab stop initialization database
+ tab stop initialization database
<EM>/usr/share/terminfo</EM>
- compiled terminal capability database
+ compiled terminal capability database
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
The <STRONG>ncurses</STRONG> library can be compiled with an option (<STRONG>-DUSE_GETCAP</STRONG>) that
falls back to the old-style /etc/termcap file if the terminal setup
- code cannot find a terminfo entry corresponding to <STRONG>TERM</STRONG>. Use of this
+ code cannot find a terminfo entry corresponding to <EM>TERM</EM>. Use of this
feature is not recommended, as it essentially includes an entire
termcap compiler in the <STRONG>ncurses</STRONG> startup code, at significant cost in
core and startup cycles.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
- <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> and related pages whose names begin "curs_" for detailed
- routine descriptions.
- <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
- <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> for user-defined capabilities
+ <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>
-ncurses 6.4 2023-1
1-25 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
+ncurses 6.4 2023-1
2-02 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
projects / ncurses.git / blobdiff