|
Server IP : 103.191.208.50 / Your IP : 216.73.216.53 Web Server : LiteSpeed System : Linux orion.herosite.pro 4.18.0-553.53.1.lve.el8.x86_64 #1 SMP Wed May 28 17:01:02 UTC 2025 x86_64 User : celkcksm ( 1031) PHP Version : 7.4.33 Disable Function : show_source, system, shell_exec, passthru, popen, exec MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON Directory (0755) : /home/../opt/bitninja-python-dojo/LICENSES/ |
| [ Home ] | [ C0mmand ] | [ Upload File ] |
|---|
<!--
$Id: ncurses.faq.html,v 1.573 2025/04/07 07:48:47 tom Exp $
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<meta name="generator" content=
"HTML Tidy for HTML5 for Linux version 5.6.0">
<title>NCURSES — Frequently Asked Questions (FAQ)</title>
<link rel="author" href="mailto:dickey@invisible-island.net">
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii">
<meta name="keywords" content=
"ncurses, curses, terminfo, termcap">
<meta name="description" content=
"This FAQ gives some background and discussion for frequently encountered problems with the ncurses library, the terminal database and applications.">
<link rel="SHORTCUT ICON" href="/img/icons/vile.ico" type=
"image/x-icon">
<link rel="stylesheet" href="/css/simplestyle.css" type=
"text/css">
<link rel="stylesheet" href="/css/inline-code.css" type=
"text/css">
<style type="text/css">
@import "/css/simplenavXX.css" all;
</style>
<style type="text/css">
*.main-name {
font-style: italic;
font-variant: small-caps;
}
</style>
<meta name="viewport" content=
"width=device-width, initial-scale=1">
</head>
<body>
<hr>
<p><a href="/">http://invisible-island.net/</a><a href=
"/ncurses/">ncurses/</a><br>
Thomas E. Dickey<br>
$Date: 2022/03/16 23:58:40 $</p>
<hr>
<p><a href="/ncurses/ncurses.faq.html">Here</a> is the latest
version of this file.</p>
<h1 class="no-header">NCURSES — Frequently Asked Questions
(FAQ)</h1>
<div class="nav">
<ul>
<li class="nav-top"><a href=
"/ncurses/ncurses.faq.html">(top)</a></li>
<li><a href="#what_is_it">What is <em class=
"small-caps">ncurses</em>?</a></li>
<li><a href="#who_did_it">Who wrote <em class=
"small-caps">ncurses</em>?</a></li>
<li><a href="#who_owns_it">License issues</a></li>
<li><a href="#how_big_is_it">How big is <em class=
"small-caps">ncurses</em>?</a></li>
<li><a href="#what_platforms">Where is <em class=
"small-caps">ncurses</em> used?</a></li>
<li><a href="#latest_version">What is the latest version?</a></li>
<li><a href="#other_versions">What versions are
“stable”?</a></li>
<li><a href="#known_problems">Known/Frequent problems</a></li>
<li><a href="#report_bugs">How do I report bugs?</a></li>
<li><a href="#standardization">Standards</a></li>
<li><a href="#terminology">Terminology</a></li>
<li><a href="#additional_reading">Additional Reading</a></li>
<li><a href="#copyright_text">Copyright</a></li>
</ul>
</div>
<h2 id="what_is_it-id"><a name="what_is_it" id="what_is_it">What
is <em class="small-caps">ncurses</em>?</a></h2>
<p><em class="small-caps">ncurses</em> (new curses, pronounced
"<em>enn</em>-curses") started as a freely distributable
“clone” of System V Release 4.0 (SVr4) curses. It has
outgrown the “clone” description, and now contains
many features which are not in SVr4 curses. Curses is a pun on
the term “cursor optimization”. It is a library of
functions that manage an application's display on character-cell
terminals (e.g., VT100).</p>
<p>The name “ncurses” was first used as the name of
the curses library in Pavel Curtis's <em>pcurses</em>, dated
1982. It was apparently developed on a 4.3BSD system, at Cornell.
Parts of pcurses are readily identifiable in ncurses, including
the basics for the terminfo compiler (named <code>compile</code>
in that package):
<!-- Eric Raymond later claimed to be the author of these features --></p>
<ul>
<li>the header filename <code>ncurses.h</code></li>
<li>
<p>the <code>Caps</code> file, used to define the terminfo
capabilities</p>
</li>
<li>
<p>awk scripts <code>MKcaptab.awk</code>,
<code>MKnames.awk</code></p>
</li>
<li>
<p>the library modules used for the terminfo compiler.</p>
</li>
</ul>
<p>While the name of the library itself comes from
“pcurses”, it had a different connotation to Curtis.
His makefile built <code>libncurses.a</code> (normal) and
<code>libdcurses.a</code> (debugging). In the documentation,
Curtis referred to his package as “the new curses”
like this, in <code>changes.ms</code>:</p>
<blockquote class="code-block">
<pre>
New Features in Curses and Terminfo
Pavel Curtis
1. Introduction
This document describes new features that are being
added to the Berkeley curses subroutine package. It also
describes the new terminfo database, which replaces the
Berkeley termcap database. The emphasis is on the new fea‐
tures.
2. New Features in Curses
...
2.7. Mini‐Curses*
───────────
*This feature is not supported in the current test
release. It will be implemented in the official
distribution.
‐6‐
The new curses is bigger than the old one, and has to
copy from the current window to an internal screen image for
every call to refresh(). If the programmer is only inter‐
ested in screen output optimization, and does not want the
windowing or input functions, an interface to the lower
level routines is available. This will make the program
somewhat smaller and faster. The interface is a subset of
full curses, so that conversion between the levels is not
necessary to switch from mini‐curses to full curses.
</pre>
</blockquote>
<p>Rather than being at the start a replacement for AT&T
curses, initially it was an extension of BSD curses. Later,
supplanting AT&T curses became more important, with different
developers.</p>
<p>Besides ncurses, parts of pcurses still survive in
recognizable form in Solaris, etc., because the <a href=
"man/tic.1m.html"><code>tic</code></a> program from pcurses was
used by AT&T (see related <a href=
"tctest.html#history_terminfo">discussion</a>). Some
misinformation regarding <em>pcurses</em> was provided in a
<a href=
"https://groups.google.com/d/msg/comp.terminals/qAF3c68AgkA/me4A_X3AYagJ">
posting</a> to <em>comp.terminals</em> long ago:</p>
<blockquote>
<pre class="code-block">
Mark took “terminfo” to AT&T with him, and it was adopted for UNIX System
V Release 2 as a replacement for “termcap” (which was temporarily still
supported in SVR2). UCB, however, stuck with termcap for quite a while
(through 4.3BSD at least), merely bringing the termcap manual entry up to
date with the SVR2 version of terminfo insofar as possible (I was the
editor for the 4.3BSD termcap manual entry). Pavel Curtis provided his
own public-domain implementation of terminfo/curses, but I don't think it
really caught on.
</pre>
</blockquote>
<h2 id="who_did_it-id"><a name="who_did_it" id="who_did_it">Who
wrote <em class="small-caps">ncurses</em>?</a></h2>
<ul>
<li>
<p>Zeyd Ben-Halim started it from a previous package
<code>pcurses</code>, written by Pavel Curtis. The first
widely-used version (<a href=
"/ncurses/ncurses-license.html#ncurses_1_8_1">1.8.1</a> in
November 1993) was not much larger than pcurses.
<!-- not much larger, since most copyrights were "moved" to a corner -->
It added freely-available examples such as
<code>worm</code>,
<!-- again, Eric Raymond claimed authorship of the "configure script" -->
and a crude configure mechanism.</p>
</li>
<li>
<p>Eric Raymond continued development, apparently starting
<a href="/ncurses/ncurses-license.html#ncurses_1_8_5">in late
1993 or early 1994</a>.</p>
</li>
<li>
<p>Juergen Pfeifer wrote most of the form and menu libraries.
Eric added those libraries to ncurses in <a href=
"ncurses-license.html#ncurses_1_9_4">August 1995</a>, after I
had started working with Eric and Zeyd in March 1995, before
<a href="/ncurses/ncurses-license.html#ncurses_1_9">ncurses
1.9</a> was released.
<!-- copyright - even for Juergen's code - states only Eric and Zeyd --></p>
</li>
<li>
<p>I've done most of the configuration work, do most of the
ongoing development and testing.</p>
</li>
<li>
<p>numerous people (more than I know about) contributed
fixes.</p>
<p>For details, see the <a href="/ncurses/NEWS.html">NEWS</a>
file in the source distribution. It accurately reflects
contributions since 1.9.9e.</p>
</li>
</ul>
<p>In preparing copyright transfer in 1997, I identified <a href=
"ncurses-license.html#metrics19970613">more than 20
contributors</a> based on my software archives.</p>
<p>These individuals were <a href=
"ncurses-license.html#final19970919">cited in the agreement</a>
as having contributed more than 20 lines of code each:</p>
<blockquote>
<pre class="code-block">
Heinz-Ado Arnolds, Jeremy Buhler, Andrey Chernov, J.T. Conklin,
Ulrich Drepper, Juergen Ehling, Werner Fleck, Per Foreby, Gerhard
Fuernkranz, Anatoly Ivasyuk, Andrew Kuchling, H.J. Lu, Alexander
V. Lukyanov, David MacKenzie, Rick Marshall, Hellmuth Michaelis,
Tim Mooney, Philippe De Muyter, Eric Newton, Andreas Schwab,
Jesse Thilo, Warren Tucker, Peter Wemm.
</pre>
</blockquote>
<p>In addition to Florian La Roche, who agreed to act as
maintainer, these were the principal authors of ncurses, for
assigning copyright to the Free Software Foundation:</p>
<ul>
<li>Zeyd M. Ben-Halim</li>
<li>Thomas E. Dickey</li>
<li>Juergen Pfeifer</li>
<li>Eric S. Raymond</li>
</ul>
<p>Pavel Curtis' work is in the public domain, hence not needed
for copyright assignment. (The <code>README</code> file in the
ncurses distribution also identifies the authors).</p>
<p>Florian acted as maintainer for about a year. I continued to
do the bulk of development, and prepared the 5.0 release. After
Florian left unexpectedly (before 5.0), I <a href=
"ncurses-license.html#February_1998">resumed</a> my pre-4.2 role
as the project maintainer.</p>
<p>Occasionally someone says that it is “<em>written</em>
by the GNU Project”. That is incorrect:</p>
<ul>
<li>
<p>The developers and contributors are clearly identified in
the <a href="NEWS.html">NEWS</a> file.</p>
</li>
<li>
<p>The <a href=
"https://github.com/ThomasDickey/ncurses-snapshots/blob/master/AUTHORS">
AUTHORS</a> file in the sources identifies the primary
developers.</p>
</li>
<li>
<p>A complete list of contributors runs to several pages (see
<a href=
"/personal/changelogs.html#examples">summary</a>).</p>
</li>
<li>
<p>The Free Software Foundation held a copyright on the
redistributable work to reduce disputes. It exists as a
501(c)(3) non-profit organization, i.e., a <a href=
"https://www.irs.gov/charities-non-profits/charitable-organizations">
<em>charity</em></a>. As such, it is prohibited from
involvement in politics.</p>
<p>The GNU Project, on the other hand, is an informal
organization which ostensibly promotes the work of the Free
Software Foundation.</p>
</li>
<li>None of the major contributors to <em>ncurses</em> appears
to be involved with either organization.</li>
</ul>
<p>See the <a href="ncurses-license.html"><em>ncurses
license</em></a> page for more information.</p>
<h2 id="who_owns_it-id"><a name="who_owns_it" id=
"who_owns_it">License issues</a></h2>
<ul>
<li><a href="#license_background">How can it be
distributed?</a></li>
<li><a href="#who_claims_it">Is it Free Software or Open
Source?</a></li>
<li><a href="#is_it_gpl">Is it GPL'd?</a></li>
<li><a href="#relicensed">Will it ever be GPL?</a></li>
<li><a href="#tack_copying">What about the tack program?</a></li>
<li><a href="#terminfo_copying">What about the terminfo
database?</a></li>
</ul>
<h3 id="license_background-id"><a href="#who_owns_it" name=
"license_background" id="license_background">How can it be
distributed?</a></h3>
<p>The major ncurses developers (exclusive of Pavel Curtis, who
put his work in the public domain several years before) early in
1998 assigned their copyright to the Free Software Foundation,
which promised to use the following distribution terms for at
least five years.</p>
<blockquote class="code-block">
<p>Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, distribute with
modifications, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:</p>
<p>The above copyright notice and this permission notice shall
be included in all copies or substantial portions of the
Software.</p>
<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
AND NONINFRINGEMENT. IN NO EVENT SHALL THE ABOVE COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.</p>
<p>Except as contained in this notice, the name(s) of the above
copyright holders shall not be used in advertising or otherwise
to promote the sale, use or other dealings in this Software
without prior written authorization.</p>
</blockquote>
<h3 id="who_claims_it-id"><a href="#who_owns_it" name=
"who_claims_it" id="who_claims_it">Is it Free Software or Open
Source?</a></h3>
<p><em class="small-caps">ncurses</em> is free software. It is
not “open source” (refer to the <a href=
"/ncurses/ncurses-license.html#issue_opens">license
page</a>).</p>
<p>That term applies to a mixture of proprietary software and
quasi-free software, and is being promoted currently by several
people for a variety of reasons: some as a compromise (in the
pejorative sense) between free software and proprietary, and
others to take credit for brokering the release of some
proprietary software under less stringent conditions.</p>
<p>By relabeling free software (and revising the order of causes
and events), the supporters of “open software” are
doing the development community a disservice.</p>
<h3 id="is_it_gpl-id"><a href="#who_owns_it" name="is_it_gpl" id=
"is_it_gpl">Is it GPL'd?</a></h3>
<p>Surprisingly, some people cite ncurses as an example of GPL or
LGPL. The copyright notice (which is the above-quoted license)
appears 577 places in the 5.1 sources, including all of the
header files. Presumably therefore, these people have not
actually looked at ncurses.</p>
<p>Adding to the confusion, I have seen misleading comments such
as <a href=
"https://web.archive.org/web/20120116185439/https://cygwin.com/faq/faq.html">
this</a> (originally <a href=
"http://cygwin.com/faq/faq.html#faq.what.free">this</a>, but it
comes and goes): <!--
This section was not present during review for ncurses 5.4,
but was restored at some later time. Perhaps some of the
cygwin developers really believe that they can relicense
everyone else's code.
This is as of 2005/11/19, and except for the URL is identical
with the comments from 2001/07/25.
--></p>
<blockquote class="code-block">
<p>In particular, if you intend to port a proprietary
(non-GPL'd) application using Cygwin, you will need the
proprietary-use license for the Cygwin library. This is
available for purchase; please contact sales@cygnus.com for
more information. All other questions should be sent to the
project mailing list cygwin@sources.redhat.com.</p>
</blockquote>
<p>By omitting some of the facts (equating "non-GPL'd" with
“proprietary”), this paragraph stated in terms of
ncurses, for example, that I could not work on ncurses on cygwin
without buying a license for Cygwin. The same applied to the
developers of about half of the contributed software for Cygwin,
since not all are GPL'd.
<!-- I'm quoting the second one this time, since its wording changed -->
There was a better attempt at explaining Cygwin licensing
<a href=
"https://web.archive.org/web/20060813154610/http://cygwin.com/licensing.html">
here</a>, but the other page did not use it:</p>
<blockquote class="code-block">
<p>This means that you can port an Open Source(tm) application
to cygwin, and distribute that executable as if it didn't
include a copy of libcygwin.a/cygwin1.dll linked into it. Note
that this does not apply to the cygwin DLL itself. If you
distribute a (possibly modified) version of the DLL you must
adhere to the terms of the GPL, i.e. you must provide sources
for the cygwin DLL.</p>
</blockquote>
<p>Probably more people read the FAQ (and were misled) than read
the licensing page.</p>
<p>This type of license, by the way, is often referred to as
"MIT-style", referring to the MIT X distribution terms. Before
<a href="/ncurses/ncurses-license.html#February_1998">assigning
copyright</a> to the FSF (Free Software Foundation), <a href=
"ncurses-license.html#patch_960907">substantial portions</a> of
ncurses were copyrighted in this style. The main restriction that
affects most people is that the copyright notice must be kept on
copies—or portions of the copies. That is not done <a href=
"http://www.mkssoftware.com/docs/cur_index.asp">in this online
reference</a>, which documents an older version of ncurses. The
translation from manpage to html retains the content, but removes
the copyright notice, which one may observe is not permitted.
Compare with <a href="/ncurses/man/ncurses.3x.html">this</a>
(copyright notices are retained in the online content, as you can
see in the source-view of the page).</p>
<p>For what it's worth, the <a href=
"ncurses-license.html#final19970919">agreement</a> which we
(original ncurses developers) made with the Free Software
Foundation reads in part:</p>
<blockquote class="code-block">
<p>The Foundation promises that all distribution of the
Package, or of any work "based on the Package", that takes
place under the control of the Foundation or its agents or
assignees, shall be on terms that explicitly and perpetually
permit anyone possessing a copy of the work to which the terms
apply, and possessing accurate notice of these terms, to
redistribute copies of the work to anyone on the same terms.
These terms shall not restrict which members of the public
copies may be distributed to. These terms shall not require a
member of the public to pay any royalty to the Foundation or to
anyone else for any permitted use of the work they apply to, or
to communicate with the Foundation or its agents in any way
either when redistribution is performed or on any other
occasion.</p>
</blockquote>
<p>As is well known, that precludes relicensing to the GPL in any
version, since it would place restrictions on which programs may
link to the libraries. That would deprive a substantial fraction
of the current user base of the use of subsequent versions of the
software. No such restriction exists in the ncurses license.</p>
<h3 id="relicensed-id"><a href="#who_owns_it" name="relicensed"
id="relicensed">Will <em class="small-caps">ncurses</em> ever be
GPL?</a></h3>
<p>I have never considered it a possibility (see the preceding
section). It would make the package unusable for most of its
current user base, because GPL is a more-restrictive license than
MIT-X11 or any of the similar BSD licenses.</p>
<p>However, since the FSF holds a copyright to most of the
releases published on its website, it is not impossible that
someone might publish a version of ncurses relicensed under the
GPL. In that case, I would continue development based on the
previous version, using the existing license—the one to
which I initially agreed. Because I do almost all of the
development, and provide the development website, doing that
would have little effect on subsequent releases.</p>
<p>The original agreement stated that changes which I made to the
source would be copyright by the Free Software Foundation. That
clause expired after five years (in 2003). It does require
written notice (for instance today is June 25, 2007), so in the
event of serious disagreement with the FSF, this webpage
satisfies that. It is worth noting that all changes that I have
made since the most recent release would be in that event
copyright by me.</p>
<p>Moving forward to February 2020, relicensing was a moot issue.
However, some issues with FSF (such as <a href=
"#misinfo-man7">this</a>) could best be done by taking ownership
of the copyrights. In preparing for releasing <a href=
"/ncurses/announce-6.2.html">ncurses 6.2</a>, I sent mail to FSF
advising them that ncurses 6.2 (and all changes since ncurses
6.1) will be copyright by me (same license, of course).</p>
<h3 id="tack_copying-id"><a href="#who_owns_it" name=
"tack_copying" id="tack_copying">What about the tack program?</a></h3>
<p>That is not part of ncurses. As a convenience (to reuse
library functions that are part of <code>tic</code> and
<code>infocmp</code>), it was distributed with ncurses since
before 5.0 (patch date <a href="NEWS.html#t990417">990417</a>).
Beginning with release <a href=
"/ncurses/tack/CHANGES.html#t20170726">1.08</a> in July 2017, it
is able to work with other implementations of curses (although
<em>editing</em> a terminal description—done
rarely—requires ncurses).</p>
<p>However, <code>tack</code> is licensed differently: the GNU
General Public License, version 2 (GPLv2).</p>
<p>This confused some packagers, who then labeled ncurses as
<em>GPL</em>. Most packagers correct the designation when
requested. Some do not. To avoid this confusion, it was removed
from the ncurses distribution in 2007, <a href=
"NEWS.html#t20070203">shortly after 5.6 release</a>.</p>
<p>Unlike ncurses, FSF does not have a release-page on its
website for tack, and no one has suggested that it was written by
the GNU Project. Except for a few (small changes), this was
written by Daniel Weaver and me (see <a href=
"https://github.com/ThomasDickey/tack-snapshots/blob/master/AUTHORS">
<em>AUTHORS</em></a> file in the source). Its homepage is
<a href="/ncurses/tack.html">here</a>.</p>
<h3 id="terminfo_copying-id"><a href="#who_owns_it" name=
"terminfo_copying" id="terminfo_copying">What about the terminfo
database?</a></h3>
<ul>
<li><a href="#terminfo_license">Copyright and Licensing</a></li>
<li><a href="#terminfo_attribution">Attribution</a></li>
<li><a href="#terminfo_others">Other Versions</a></li>
</ul>
<h4><a href="#terminfo_copying" name="terminfo_license" id=
"terminfo_license">Copyright and Licensing</a></h4>
<p>The terminfo database is a special case. Ncurses provides a
different version of the <code>terminfo.src</code> file
originally collected by Eric Raymond. The ncurses file is not
maintained by Eric Raymond, since the agreement which transferred
control to FSF states:</p>
<blockquote class="code-block">
<p>We hereby agree that if we have or acquire, or any one of us
has or acquires, hereafter any patent or interface copyright or
other intellectual property interest dominating the Program (or
use of the same), such dominating interest will not be used to
undermine the effect of this assignment,</p>
</blockquote>
<p>Changes made to this file are (unsurprisingly) copyrighted via
the <a href=
"http://www.wipo.int/treaties/en/ip/berne/trtdocs_wo001.html">Berne
convention</a>. No explicit "Copyright ©" is required. It
only requires that the author be identified (and this is done in
the history comments at the end of the file):</p>
<blockquote class="code-block">
<p>(1) In order that the author of a literary or artistic work
protected by this Convention shall, in the absence of proof to
the contrary, be regarded as such, and consequently be entitled
to institute infringement proceedings in the countries of the
Union, it shall be sufficient for his name to appear on the
work in the usual manner. This paragraph shall be applicable
even if this name is a pseudonym, where the pseudonym adopted
by the author leaves no doubt as to his identity.</p>
</blockquote>
<p>and noting the first comment in the file states that it is
maintained as part of ncurses, this applies:</p>
<blockquote class="code-block">
<p>(3) In the case of anonymous and pseudonymous works, other
than those referred to in paragraph (1) above, the publisher
whose name appears on the work shall, in the absence of proof
to the contrary, be deemed to represent the author, and in this
capacity he shall be entitled to protect and enforce the
author's rights. The provisions of this paragraph shall cease
to apply when the author reveals his identity and establishes
his claim to authorship of the work.</p>
</blockquote>
<p>Raymond wrote a disclaimer in the <code>terminfo.src</code>
file which disagrees with some of this. However, Raymond's
disclaimer was based on more than one misconception. There is an
interesting story about that in <a href=
"/personal/copyrights.html#removing_notes">another place</a>.</p>
<h4><a href="#terminfo_copying" name="terminfo_attribution" id=
"terminfo_attribution">Attribution</a></h4>
<p>Occasionally someone in a newsgroup posts a terminfo which has
been exported using <code>infocmp</code>, saying that it is
theirs (and even written by them). Sometimes the claim is true,
though more often the data is identical to that from ncurses or a
package which includes ncurses. The latter case is
interesting.</p>
<p>For instance <a href="http://www.openqm.com/">OpenQM</a> used
terminfo entries which were obtained from ncurses using
<code>infocmp</code>. In discussion, one aspect glossed over was
that some of the content was copied not from ncurses itself but
from a <em>packager's</em> patch which merged a <a href=
"/xterm/xterm.html">xterm</a> terminfo which I wrote. Ultimately,
the responses from that discussion boiled down to saying that
they found it and it's theirs. (The maintainer did agree to add a
comment noting the origin of the “public domain”
entries).</p>
<h4><a href="#terminfo_copying" name="terminfo_others" id=
"terminfo_others">Other Versions</a></h4>
<p>Eric Raymond's website has an old version misleadingly
numbered "11.0". It actually is much older than ncurses's
terminfo (whose major version I have left as
“10”).</p>
<p>The content of "11.0" is derived from <a href=
"announce-5.0.html">ncurses 5.0</a>. It makes more than one
change, but most are cosmetic (e.g., reordering the entries
within the file, adding about 300 lines of comments—in an
18,655 line file—to make the reordering look nicer). None
of the added comments are useful.</p>
<p>It also modifies the changelog from ncurses to make it appear
that people who reported problems to me were the ones who did the
subsequent investigation and patches. He had done the same thing
prior to ncurses 4.2, for several months in 1997 and 1998,
copying changes from ncurses development, and then later
“revising” the change history. (I later restored that
portion of the changelog).</p>
<p>The last version (11.0.1) copies one of my fixes from ncurses,
(prompted by a bug-report by Tijs Michels on the rxvt-workers
mailing list in January 2000, in response to ESR's announcement
of "11.0.0"). In the mailing list, I pointed out the reason for
my change. My original change comment in 1997 said</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
<span class="comment"># 10.1.16 (Sat Dec 13 19:41:59 EST 1997) </span><br>
<span class=
"comment"># * remove hpa/vpa from rxvt, which implements them incorrectly. </span><br>
<span class=
"comment"># * add sgr0 for rxvt. </span><br>
<span class=
"comment"># * remove bogus smacs/rmacs from EMX descriptions.</span><br>
<!--atr2html}}-->
</p>
</blockquote>
<p>GNU termcap 1.3.1 distributes "11.0.1", generated using
ncurses' <a href="/ncurses/man/tic.1m.html">tic</a> program.
Disregarding the issue that the file is old and faulty, the
reason for generating the file is that ESR's website does not
provide a version which resolves all but the last
"<code>tc=</code>" inclusions.</p>
<h2 id="how_big_is_it-id"><a name="how_big_is_it" id=
"how_big_is_it">How big is <em class=
"small-caps">ncurses</em>?</a></h2>
<ul>
<li><a href="#growing_features">Growth of the feature set</a></li>
<li><a href="#uses_of_library">Types of library users</a></li>
<li><a href="#related_to_vi">Relationship with vi</a></li>
<li><a href="#not_library_users">Applications miscited as
library users</a></li>
</ul>
<p>The answer depends on why you are asking. Some of the reasons
for asking include</p>
<ul>
<li>
<p>does it have some given feature.</p>
</li>
<li>
<p>will it fit in some limited-size embedded application,</p>
</li>
</ul>
<h3><a href="#how_big_is_it" name="growing_features" id=
"growing_features">Growth of the feature set</a></h3>
<p>As noted, ncurses began as a clone of SVr4 curses (up til
around 1995). Later, The Open Group began a specification of
curses (XSI Curses), which is now known as X/Open Curses. That
provided for "wide-characters", such as Unicode, although at that
point Unicode was not the obvious answer.</p>
<p>There were a few functions (such as <code>attr_get</code>)
which were added into the ncurses library in anticipation of XSI
Curses. However, I chose to implement the wide-character support
using a different library name, “ncursesw”. Doing
that allowed me to maintain compatibility with applications that
used the existing “ncurses” library.</p>
<p>Given that, the “ncurses” library would be
comparable to a SVr4 implementation (such as Solaris, IRIX64 or
HPUX), while the “ncursesw” library would be
comparable to one of the XPG4 implementations (Tru64 being the
notable implementation). The ncurses (and ncursesw) library
provide some extended functions not found in SVr4/XPG4. A few
implementations (<a href="#other-pdcurses">PDCurses</a> and
<a href="#other-netbsd">NetBSD curses</a>) provide some of these
extensions.</p>
<p>Later, I added functions to support simple threaded
applications, and Juergen Pfeifer extended that. Again, to
maintain compatibility, this is normally built as a a new library
name, “ncursest” or “ncurseswt”. First
noted in mid-2011, at this time (mid-2020), there is no other
implementation of these features.</p>
<p>The ncurses and ncursesw libraries are reasonably
source-compatible. That is, an application written for
“ncurses” will build with “ncursesw”. But
it will behave differently in response to your locale settings.
(Some distributors, who do not care about the differences, have
chosen to merge the names together as “ncurses”).</p>
<p>A few applications require changes to use
“ncursest”, since internal details of the
<code>WINDOW</code> object are not directly visible in the
latter. However, the “ncurses” library has macros and
functions which address this area.</p>
<p>Every implementation of curses uses both macros and functions
to provide their features. ncurses follows the XPG4 convention
where all macros (except for those such as <code>getyx</code>
which <em>must</em> be implemented solely as macros) are also
implemented as functions.</p>
<p>Here are counts comparing ncurses 5.9 with other
implementations:</p>
<blockquote>
<table border="1" summary=
"Counts of functions and macros for different curses implementations">
<tr>
<th align="left">Implementation</th>
<th align="left">Macros</th>
<th align="left">Public symbols</th>
</tr>
<tr>
<td>ncurseswt (sp-funcs)</td>
<td>219</td>
<td>541</td>
</tr>
<tr>
<td>ncursest (sp-funcs)</td>
<td>153</td>
<td>439</td>
</tr>
<tr>
<td>ncurseswt</td>
<td>219</td>
<td>429</td>
</tr>
<tr>
<td>ncursest</td>
<td>153</td>
<td>332</td>
</tr>
<tr>
<td>ncursesw</td>
<td>219</td>
<td>454</td>
</tr>
<tr>
<td>ncurses</td>
<td>153</td>
<td>357</td>
</tr>
<tr>
<td>Tru64 5.1</td>
<td>228</td>
<td>481</td>
</tr>
<tr>
<td>Solaris 10 XPG4</td>
<td>180</td>
<td>374</td>
</tr>
<tr>
<td>Solaris 10 SVr4</td>
<td>199</td>
<td>422</td>
</tr>
<tr>
<td>IRIX64 6.5</td>
<td>195</td>
<td>394</td>
</tr>
<tr>
<td>HPUX 11.23 XPG4</td>
<td>162</td>
<td>472</td>
</tr>
<tr>
<td>HPUX 10.20 XPG4</td>
<td>172</td>
<td>468</td>
</tr>
<tr>
<td>HPUX 10.20 SVr3</td>
<td>197</td>
<td>323</td>
</tr>
<tr>
<td>AIX 7.1</td>
<td>207</td>
<td>480</td>
</tr>
<tr>
<td>PDCurses 3.4</td>
<td>9</td>
<td>364</td>
</tr>
<tr>
<td>NetBSD 5.1</td>
<td>86</td>
<td>367</td>
</tr>
</table>
</blockquote>
<p>In each case, internal functions are not counted.</p>
<p>The Unix implementations include undocumented features for
compatibility with older curses implementations that are not
provided by ncurses.</p>
<p>Both <a href="#other-pdcurses">PDCurses</a> and <a href=
"#other-netbsd">NetBSD curses</a> contain functions not counted
here because they are not relevant to a comparison with SVr4/XPG4
curses. For example, PDCurses in X11 contains functions for
initializing the X window. On the other hand, relevant extensions
such as PDCurses' version of <code>wresize</code> are
counted.</p>
<h3><a href="#how_big_is_it" name="uses_of_library" id=
"uses_of_library">Types of library users</a></h3>
<p>PDCurses on the other hand does not include the functions used
to obtain terminfo information. That does not prevent it from
being a curses implementation. X/Open Curses' documentation
treats those separately, allowing for the possibility of curses
implementations without terminfo (or termcap either for that
matter).</p>
<p>That raises another issue: what types of interfaces do curses
libraries (and ncurses in particular) support?</p>
<p>ncurses includes the conventional curses interfaces, with
extensions (new functions) in each interface. The interfaces
are:</p>
<ul>
<li><a href="/ncurses/man/form.3x.html">form</a>, <a href=
"/ncurses/man/menu.3x.html">menu</a>: upper-level libraries
provided in a few systems such as SCO and Solaris.</li>
<li><a href="/ncurses/man/panel.3x.html">panel</a>: an
upper-level library which should have been standarized as part
of the curses library.<br>
Again (outside of ncurses), it is provided by SCO and
Solaris.</li>
<li><a href="/ncurses/man/ncurses.3x.html">curses</a>: the
higher-level interface used by <em>all</em> curses
applications.</li>
<li><a href="/ncurses/man/curs_terminfo.3x.html">terminfo</a>:
a lower-level interface used by some applications.</li>
<li><a href="/ncurses/man/curs_termcap.3x.html">termcap</a>: a
lower-level interface used by some applications.</li>
</ul>
<p>Curiously, NetBSD provided variants of the form and menu
libraries in late 1999, but lacked a panel library until 2015
(see <a href=
"http://cvsweb.netbsd.org/bsdweb.cgi/src/lib/libpanel/?only_with_tag=MAIN">
source</a>). Conversely, PDCurses provides a panel library but
lacks the form and menu libraries. Because NetBSD uses
<em>opaque</em> structures, it is difficult to write portable
applications using their form and menu libraries. The <a href=
"ncurses-examples.html">ncurses-examples</a> have some
workarounds for this to allow them to compile with NetBSD curses.
One might have better luck with PDCurses' panel library, which
has the same ancestor as ncurses' panel library.</p>
<p>The lower-level interfaces rely upon the application (rather
than the library) to decide how to put characters on the display.
That is referred to as “optimization”, e.g., in the
documentation:</p>
<blockquote class="code-block">
<p>The ncurses library routines give the user a
terminal-independent method of updating character screens with
reasonable optimization.</p>
</blockquote>
<p>Most applications made the transition to using the curses
interface long ago. There are some applications which use one of
the lower-level interfaces. In some cases there are technical
reasons for this. Inertia is more often the reason.</p>
<p>Here are some examples of well-known applications which use
curses:</p>
<ul>
<li>
<p><a href="https://lynx.invisible-island.net/">lynx</a><br>
A curses application from the beginning, lynx can be built
with any version of curses, including PDCurses and VMS
curses.</p>
</li>
<li>
<p><a href=
"https://sites.google.com/a/bostic.com/keithbostic/vi">nvi</a><br>
Keith Bostic introduced nvi in 4.4BSD, revised it for
4.4BSDLite in 1994. At that point, it was using curses
(preferably System5 curses). Lacking that, it had a bundled
copy of 4.4BSD curses, which sufficed. Bostic's interest in
ncurses stemmed from his desire to eliminate the bundled
4.4BSD curses, and he was helpful in many ways, both
technical (with bug reports) and <a href=
"/ncurses/ncurses-license.html#January_1997">otherwise</a>.</p>
</li>
<li>
<p><a href="http://www.tin.org">tin</a><br>
Originally in K&R C using termcap, I <a href=
"/tin/tin.html#history">modified</a> it to use curses. Most
of the subsequent work to handle wide-characters was done by
others.</p>
</li>
</ul>
<p>Widely-used <em>termcap</em> applications include these:</p>
<ul>
<li>
<p><a href=
"http://www.greenwoodsoftware.com/less/">less</a><br>
Several <code>less</code> features are undocumented. One of
these features is the use of environment variables to
override termcap capabilities. At startup, when
<code>less</code> retrieves each termcap capability, it first
checks for an environment variable (named by prefixing the
capability name with
“<code>LESS_TERMCAP_</code>”) and uses the
environment variable's value if it exists. That appeared in
<code>less</code> between versions 321 and 330
(July–October 1996).</p>
</li>
<li>
<p><a href=
"http://www.gnu.org/software/screen/">screen</a><br>
The <code>screen</code> program has had more impact on
ncurses development than the other applications because there
were features which <code>screen</code>'s developers wanted
for compatibility with “real” (runtime
adjustments of <code>sgr0</code> to imitate termcap's
corresponding <code>me</code> in <a href=
"/ncurses/NEWS.html#t20010908">2001</a> and using
<em>padding</em> in <a href=
"man/curs_util.3x.html#h3-delay_output"><code>delay_output</code></a>
rather than time-delays in <a href=
"/ncurses/NEWS.html#t990102">1999</a>). The latter was marked
as a problem in screen's source code; it took several years
for that to be addressed (see <a href=
"/gnu-patches/index.html#related">related
discussion</a>).</p>
</li>
<li>
<p><a href="http://w3m.sourceforge.net">w3m</a><br>
While <code>w3m</code> is a termcap application, it includes
source code that makes it pretend to use curses. For
instance, it includes a module <a href=
"https://github.com/shinh/w3m/blob/master/terms.c">terms.c</a>
whose header comment is <em>An original curses library for
EUC-kanji by Akinori ITO, December 1989</em>. This module
does not do <em>optimization</em> as a curses library would
do, but uses a simpler approach (which works well with
multibyte characters). As <a href=
"http://w3m.sourceforge.net/STORY">explained</a> by the
developer:</p>
<blockquote>
<p class="code-block">By the way, w3m doesn't use UNIX
standard regexp library and curses library. It is because I
want to use Japanese. When I wrote fm, there were no free
regexp/curses libraries that can treat Japanese. Now both
libraries are available and they looks faster than w3m
code.</p>
</blockquote>
<p>What complicates the program is that some of its symbols
duplicate those in the curses library with which it is linked
(see <a href="#w3m-vs-gpm">related discussion</a>).</p>
</li>
<li>
<p><a href="http://www.vim.org">vim</a><br>
Vim's developers provide their own termcap definitions, just
in case there is nothing good enough on the system, and
provide features for overriding the system's termcap
capabilities even when using the system definition as a
starting point. Because of this, vim has had little impact on
ncurses development; the change-log does not mention vim. On
the other hand, unlike <code>screen</code>, the source-code
for vim still contains <a href=
"https://github.com/vim/vim/blob/61d7c0d52ca40ab8488c36e619d1e46503affd0b/src/term.c#L2601">
a comment</a> about a bug in ncurses which was addressed in
<a href="/ncurses/NEWS.html#t971220">late 1997</a>, before
ncurses 4.2 was released.</p>
</li>
</ul>
<p>Applications which use only <em>terminfo</em> are less
well-known. For example, there are</p>
<ul>
<li><a href=
"/ncurses/ncurses-examples.html">ncurses-examples</a> (e.g.,
<a href=
"https://github.com/ThomasDickey/ncurses-snapshots/blob/master/test/demo_terminfo.c">
demo_terminfo</a>, <a href=
"https://github.com/ThomasDickey/ncurses-snapshots/blob/master/test/list_keys.c">
list_keys</a> and <a href=
"https://github.com/ThomasDickey/ncurses-snapshots/blob/master/test/test_sgr.c">
test_sgr</a>)</li>
<li><a href="/ncurses/tack.html">tack</a></li>
<li><a href="https://tmux.github.io/">tmux</a></li>
</ul>
<p>Because the terminfo and termcap programming interfaces are
similar, it is trivial to make an application build with terminfo
if it was originally written to use termcap. These are done using
a table for the capabilities, taking advantage of the fact that
all of the conventional termcap capabilities are associated with
terminfo capabilities. Here are a few examples:</p>
<ul>
<li><a href=
"https://github.com/ThomasDickey/vile-snapshots/blob/master/tcap.c">
vile</a></li>
<li><a href=
"https://github.com/ThomasDickey/xterm-snapshots/blob/master/xtermcap.c">
xterm</a></li>
</ul>
<p>Going the other way (starting with a terminfo application and
making it work with termcap) is not necessarily simple:</p>
<ul>
<li>
<p>The terminfo interface provides a data structure <a name=
"TERMTYPE-struct" id=
"TERMTYPE-struct"><code>TERMTYPE</code></a> holding all of
the terminal's information which eliminates the need for
calls to the tigetstr, tigetnum and tigetflag functions. If
an application (such as <em>tack</em>) is written to use
that, it is difficult to make it use termcap.</p>
</li>
<li>
<p>Additionally, since <a href=
"#extended-terminfo-1999">1999</a>, ncurses provides <a href=
"/ncurses/terminfo.src.html#toc-_N_C_U_R_S_E_S__U_S_E_R-_D_E_F_I_N_A_B_L_E__C_A_P_A_B_I_L_I_T_I_E_S">
<em>extended capabilities</em></a> in its terminal database
which are not necessarily visible to termcap applications.
XTerm, in its <a href=
"/xterm/manpage/xterm.html#Application-Resources:tcapFunctionKeys">
<code>tcapFunctionKeys</code></a> feature uses these
capabilities; gnome-terminal in its analogous termcap
interface (removed in 2014) could not.</p>
<p>The <a href="man/user_caps.5.html">user_caps(5)</a> manual
page goes into greater detail.</p>
</li>
</ul>
<p>Because of these differences, it is best to speak of
termcap-applications, terminfo-applications and
curses-applications. Curses-applications may use terminfo
functions, but the reverse is not true. Given the terminfo
interface, there is no reason for a curses-application to use the
termcap interface.</p>
<p>An easy way to distinguish between the three types of
applications is to see what library calls they make:</p>
<ul>
<li><em>curses</em> – <a href=
"/ncurses/man/curs_initscr.3x.html">initscr</a> or newterm</li>
<li><em>terminfo</em> – <a href=
"/ncurses/man/curs_terminfo.3x.html">setupterm</a></li>
<li><em>termcap</em> – <a href=
"/ncurses/man/curs_termcap.3x.html">tgetent</a></li>
</ul>
<p>Even this categorization is simplified:</p>
<ul>
<li>
<p>Some curses applications (such as <em>nvi</em>) switch
between full-screen and normal modes of operation, e.g., to
support the “open mode” of <em>vi</em>. To
accomplish that, <em>nvi</em> uses lower-level calls at
times, e.g., to erase characters.</p>
</li>
<li>
<p><em>nvi</em> (and <a href=
"/dialog/dialog.html">dialog</a>) treat <a href=
"/xterm/xterm.html">xterm</a>'s alternate screen feature
specially, using low-level workarounds to disable the feature
as they switch to/from full-screen mode.</p>
</li>
<li>
<p><em>nvi</em> (and <a href="/vile/vile.html">vile</a>,
using its curses driver) do not use the curses library's
input function <a href=
"/ncurses/man/curs_getch.3x.html">wgetch</a>. That is because
<em>vi</em> treats the <em>escape</em> character specially.
Consequently, the curses decoding of function- and
special-keys is not usable by <em>vi</em>-like programs.</p>
</li>
</ul>
<p>Nothwithstanding their use of low-level calls, these are
curses applications because they use the library to update the
display. Non-curses (termcap and terminfo) programs use only the
terminal database. Applications which do their own display
optimization (such as <em>vim</em>) are not curses
applications.</p>
<p>If someone simply categorizes any application which is linked
to (or uses in some sense) the ncurses library as an <em>ncurses
application</em>, that rapidly leads to absurd conclusions, as
for example in Debian <a href=
"https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=265631">#265631</a>,
where a developer insisted that a bug (apparently in a different
library) was a bug in ncurses because the application in question
used the <a href="#using_gpm_lib">gpm library</a>. In other
cases, e.g., lists made by nondevelopers based on package
dependencies, this sort of misinformation is commonplace.</p>
<h3><a href="#how_big_is_it" name="related_to_vi" id=
"related_to_vi">Relationship with vi</a></h3>
<p>Not all implementations of <em>vi</em> are curses
applications. In fact, considering it carefully, most are
not.</p>
<p>One likely objection to that statement is the generally
accepted notion that Ken Arnold “took” functions from
Bill Joy's <em>vi</em> to make his library. For instance, in the
preface to <a href="#book_goodheart"><em>UNIX Curses
Explained</em></a>, Goodheart said (in 1991):</p>
<blockquote class="code-block">
<p>It all started in the late 1970s when Bill Joy, in writing
his editor <em>ex</em> (probably more famous by the name
<em>vi</em> nowadays), wrote a set of routines which read a
terminal capability database. The database, then named
<em>termcap</em>, generally described how to manipulate
individual terminals and what they where capable of. The
routines he created, which accessed the <em>termcap</em>
database, implemented optimal cursor movement.</p>
<p>Kenneth C.R.C. Arnold took these routines almost without
changes and derived from them what is known today as the
<strong>curses package</strong>.</p>
</blockquote>
<p>People tend to refer to the second paragraph without noticing
the first one. The <em>“where”</em> versus
<em>“were”</em> typographical error in the first
paragraph is an error by the publisher. The last sentence of the
first paragraph is an error by the author: termcap does not,
never did do that.</p>
<p>Optimal cursor movement (cursor optimization) in <em>ex</em>
was done in the remainder of the application. The termcap
functions were readily reusable; the remainder was not. Arnold
added to Joy's original idea by making the library
<em>reusable</em>.</p>
<p><a href="http://www.tuhs.org/">The Unix Heritage Society</a>
has copies of 3BSD, 4.2BSD, 4.3BSD (multiple). <a name=
"contrast-vi-curses" id="contrast-vi-curses">Using those, one can
make useful comparisons</a> :</p>
<ul>
<li><a href="/ncurses/42BSD-ex_vis.h.html">ex_vis.h</a> file
from <em>ex</em> in the 4.2BSD distribution</li>
<li><a href="/ncurses/42BSD-curses.h.html">curses.h</a> from
curses library in the same distribution.</li>
</ul>
<p>Joy's header file is littered with separate variables.
Arnold's header file organizes those into structures, notably
<code>WINDOW</code>. The <code>vtube</code> array in the former
corresponds to the bulk of the storage used by
<code>WINDOW</code>. In the same way, Arnold recognized useful
aspects of terminal manipulation scattered through <em>ex</em>,
and organized those into a library which improved on the original
design. Aside from <code>beep</code>, there is no straightforward
mapping between the functions in the two programs.</p>
<p>Traditional <em>vi</em>, however, does not use curses. With
the release of 4.2BSD, it lost its private copies of the termcap
functions, and, in the main branch of development, at AT&T,
became a terminfo application. With 4.3BSD, the termcap-based
<em>vi</em> (and derived code such as <a href=
"http://heirloom.sourceforge.net/vi.html">“heirloom
vi”</a>) was no longer the main line of development.
Bostic's <em>nvi</em> was a re-implementation (based on
<em>elvis</em>), done specifically to disentangle the BSD project
from AT&T source code.</p>
<p>Switching to terminfo was simple. Switching back would be
hard, since the AT&T <em>vi</em> uses the <a href=
"#TERMTYPE-struct"><code>TERMTYPE</code></a> structure for
accessing the terminal capabilities. AIX, HPUX, IRIX64, Solaris
all use the AT&T-derived <em>vi</em>.</p>
<h3><a href="#how_big_is_it" name="not_library_users" id=
"not_library_users">Applications miscited as library users</a></h3>
<p>Here is a short list of applications commonly confused as
users of curses, terminfo or termcap. The reason for the
confusion is that they use the <code>TERM</code> environment
variable, and some give a little attention to the terminal
database. But the essential approach taken by their developers is
to hard-code their assumptions about the terminals.</p>
<ul>
<li id="slang">
<p>The “S-Lang” (more commonly just <a href=
"ncurses-slang.html"><strong>slang</strong></a>) library may
use the termcap file, or its own (subset of ncurses)
interface to the terminfo database. However, it overrides the
terminfo/termcap data with its author's assumptions which can
differ radically from your actual terminal capabilities.</p>
</li>
<li>
<p>ELinks (and its ancestors links, links2), generically
referred to as <em>(e)links(2)</em> <a href=
"http://elinks.or.cz/documentation/html/manual.html-chunked/ch08.html">
assumes</a> everything is some variation of Linux console,
xterm or <a href="#vt100_color">color-vt100</a>. The <a href=
"http://www.tldp.org/HOWTO/Text-Terminal-HOWTO-17.html">Text
Terminal HOWTO</a> provides some misinformation on this
topic</p>
<blockquote>
<p class="code-block">But links2 and elinks will work with
any terminal by classifying the type as dumb like the first
terminals.</p>
</blockquote>
<p>Rather, (e)links(2) simply uses VT100 escape sequences if
it notices that <code>TERM</code> is set to
<strong>dumb</strong>.</p>
</li>
<li>
<p>URWid (see for example <a href=
"http://stackoverflow.com/questions/2374614/are-there-any-tree-libraries-widgets-for-ncurses/42051716#42051716">
<em>are there any tree libraries/widgets for
(n)curses</em></a>). According to its <a href=
"http://urwid.org/manual/displaymodules.html">documentation</a>:</p>
<blockquote>
<p class="code-block">If you don’t specify a display
module, the default main loop will use <a href=
"http://urwid.org/reference/display_modules.html#urwid.raw_display.Screen">
raw_display.Screen</a> by default.</p>
</blockquote>
<p>and goes on to mention that when using (n)curses, there is
no support for 88- or 256-colors or mouse support. The point
which URWid's developers are making is that the curses module
is there solely to provide justification for the hard-coded
“raw display” module.</p>
</li>
<li>
<p>Linux <a href=
"http://man7.org/linux/man-pages/man1/setterm.1.html">setterm</a>,
which knows many of the Linux escape sequences documents
documented in <a href=
"http://man7.org/linux/man-pages/man4/console_codes.4.html">console_codes</a>.
However, of its 40 command-line options, 60% — all of
those which are frequently used — duplicate <a href=
"man/tput.1.html"><code>tput</code></a>, <a href=
"man/tset.1.html#h3-reset----reinitialization"><code>reset</code></a>,
or <a href="man/tabs.1.html"><code>tabs</code></a>. The
others are rarely used, Linux-specific.</p>
</li>
<li>
<p><a href=
"http://man7.org/linux/man-pages/man1/ls.1.html">GNU ls</a>
and <a href=
"http://man7.org/linux/man-pages/man1/dircolors.1.html">dircolors</a>.
The latter program has a list of <code>TERM</code> values
which it assumes all support color, using <a href=
"#bce_mismatches"><code>bce</code> (back color erase)</a>,
including “vt100” (which <a href=
"#vt100_color">never supported color</a>).</p>
<p>For other comments, see</p>
<ul>
<li><a href=
"http://unix.stackexchange.com/questions/316878/solarized-colorscheme-in-fbterm/316912#316912">
<em>Solarized colorscheme in fbterm?</em></a></li>
<li><a href=
"http://stackoverflow.com/questions/40574819/how-to-remove-dir-background-in-ls-color-output/40575734#40575734">
<em>How to remove dir background in `ls -color`
output</em></a></li>
</ul>
</li>
</ul>
<h2 id="what_platforms-id"><a name="what_platforms" id=
"what_platforms">Where is <em class="small-caps">ncurses</em>
used?</a></h2>
<ul>
<li><a href="#platform-posix">Generally workable systems</a></li>
<li><a href="#platform-portable">non-Linux systems</a></li>
<li><a href="#platform-vms">Other systems: VMS</a></li>
<li><a href="#related_programs">Examples of ncurses
programs</a></li>
</ul>
<p><em class="small-caps">ncurses</em> should build and work on
any POSIX platform. It also works on some platforms that are
non-POSIX. However, it <em>requires</em> these POSIX features
(available on <em>all</em> supported platforms):</p>
<ul>
<li>
<p>a standard C compiler (c89 or later)</p>
</li>
<li>
<p>a POSIX shell (which requires a workaround for Solaris'
obsolete shell—see the <a href=
"announce-6.0.html#h4-config-major">6.0 release
notes</a>).</p>
</li>
</ul>
<h3><a href="#what_platforms" name="platform-posix" id=
"platform-posix">Generally workable systems</a></h3>
<p>Current development is focused on the wide-curses
configuration (ncursesw). These platforms are known to work:</p>
<ul>
<li>BSD variants:
<ul>
<li>FreeBSD 12-13</li>
<li>OpenBSD 6-7</li>
<li>NetBSD 8-10</li>
</ul>
</li>
<li>Linux-based systems
<ul>
<li>Arch Linux</li>
<li>Debian 10-12, and testing</li>
<li>Fedora 38-41 and rawhide, CentOS 6-9</li>
<li>Mageia 7-9</li>
</ul>
</li>
</ul>
<p>The normal (8-bit character) configuration is known to work on
the same platforms. I've also built these in preparation for the
current release:</p>
<ul>
<li>AIX 7, 6, 5.3</li>
<li>HPUX 11.31, 11.23</li>
<li>MacOS 13, 14</li>
<li>Solaris 11, 10</li>
<li>Windows 11, 10, 8, 7, using Cygwin, MinGW and MSYS2.</li>
</ul>
<p>Previous releases listed other platforms (or versions) which
are no longer available for development and testing, e.g.,
IRIX64, SCO OpenServer, SunOS 4, Tru64. Most of those probably
work as well, but keep in mind that because they are <a href=
"/personal/bug-reports.html#dead_systems">defunct</a>, only minor
changes would be considered in bug reports.</p>
<h3><a href="#what_platforms" name="platform-portable" id=
"platform-portable">non-Linux systems</a></h3>
<p id="bsd_platforms">That is a summary of the recent work which
I have done. Others package ncurses and provide it either as the
system curses library, or as an add-on. Some people assume that
ncurses is a “Linux” program. That is incorrect.
Since half of my users are on non-Linux systems, here are some
notes:</p>
<ul>
<li>
<p id="bsd_platform-ncurses"><a href=
"https://svnweb.freebsd.org/base/head/lib/ncurses/">FreeBSD</a>
and <a href=
"https://cvsweb.openbsd.org/src/lib/libcurses/">OpenBSD</a>
use ncurses as the system curses library.</p>
<p>Both of those systems (FreeBSD for termcap until <a href=
"https://github.com/freebsd/freebsd-src/commit/61f66a1f4403fded9aae14d890ad96914a3c0bc1">
2021</a>, OpenBSD for terminfo until <a href=
"https://cvsweb.openbsd.org/src/lib/libcurses/tinfo/read_entry.c?rev=1.17&content-type=text/x-cvsweb-markup">
2015</a>) used source-only entries in their respective hashed
system terminal databases. Since <a href=
"/ncurses/announce-5.6.html">2006</a>, <em>ncurses</em>
supports an alternate configuration, storing compiled
(binary) entries in its hashed database, to improve runtime
performance.</p>
<ul>
<li>
<p>FreeBSD's system curses library uses the <a href=
"https://github.com/freebsd/freebsd-src/blob/61f66a1f4403fded9aae14d890ad96914a3c0bc1/contrib/ncurses/ncurses/tinfo/read_termcap.c">
termcap reader</a> from <a href=
"https://github.com/ThomasDickey/ncurses-snapshots/blob/master/ncurses/tinfo/read_termcap.c">
ncurses</a>. The base system's terminal database is
referred to as “termcap.db” but is actually
an ncurses terminfo hashed database.</p>
<p>Until 2021 (see <a href=
"https://cgit.freebsd.org/src/commit/?id=61f66a1f4403fded9aae14d890ad96914a3c0bc1">
commit</a>), the ncurses utility programs were not used
with FreeBSD's system curses (including <a href=
"https://svnweb.freebsd.org/base/head/usr.bin/tabs/">tabs</a>
and <a href=
"https://svnweb.freebsd.org/base/head/usr.bin/tput/">tput</a>—
but see discussion in the <a href=
"man/tput.1.html#h2-HISTORY">manual page</a>). The add-on
<a href=
"https://svnweb.freebsd.org/ports/head/devel/ncurses/">ncurses
port</a> provides a terminfo database, along with the
<em>ncurses</em> utility programs. Originally that used a
conventional directory-tree configuration, but changed in
<a href=
"https://svnweb.freebsd.org/ports/head/devel/ncurses/Makefile?r1=327793&r2=337857">
2013</a> to use ncurses' hashed-database feature. Several
years later, FreeBSD <a href=
"https://github.com/freebsd/freebsd-ports/commit/ad08c2f24145cb0a224d47568513e359bfe4cfa1">
changed back</a> to the directory-tree to eliminate
problems with some packages, e.g,. <a href=
"https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=262130">
this</a>.</p>
</li>
<li>
<p>OpenBSD, on the other hand, used to use its own
terminfo reader for a hashed database. That was <a href=
"https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/lib/libcurses/tinfo/read_entry.c.diff?r1=1.16&r2=1.17">
discarded</a> late in <a href=
"https://cvsweb.openbsd.org/src/lib/libcurses/tinfo/read_entry.c?rev=1.17&content-type=text/x-cvsweb-markup">
2015</a>, to use ncurses.</p>
</li>
</ul>
</li>
<li>
<p id="bsd_platform-other"><a href=
"http://cvsweb.netbsd.org/bsdweb.cgi/src/share/terminfo/?only_with_tag=MAIN">
NetBSD</a> and <a href=
"https://github.com/oracle/solaris-userland/tree/master/components/ncurses">
Solaris 11</a> use ncurses' terminal database, with their
different implementations of curses.</p>
<p>NetBSD provides an add-on <a href=
"http://pkgsrc.se/devel/ncurses">package</a> for the ncurses
libraries and utilities. Although NetBSD developers prefer to
use their own version of the curses library, as of September
2023, slightly less than half of the packages whose build
script mentions curses specify ncurses (189 of 394).</p>
<p>Solaris installs ncurses for use by several programs
including bash, cmake, gdb, less, lftp, lynx, mutt, nano,
python (multiple versions), ruby, tmux, vim, xterm, and
zsh.</p>
</li>
<li>
<p id="bsd_platform-macos">As of January 2020, <a href=
"https://opensource.apple.com/source/ncurses/">MacOS</a> and
<a href=
"https://cvsweb.openbsd.org/src/lib/libcurses/">OpenBSD</a>
provided <a href="/ncurses/announce-5.7.html">ncurses 5.7</a>
(from 2008) for their system curses library. A few years
later, that is still the same, but there are some hints that
might change.</p>
<p>Due to its age, ncurses 5.7 may not work as expected. For
instance, the command <a href=
"https://unix.stackexchange.com/questions/552845/tput-ed-is-empty/556123#556123">
<em><code>tput ed</code></em></a> was seen to not work
with MacOS. Additionally, 256-colors and direct-colors are
not supported by the ncurses library (done in ncurses
<a href="/ncurses/announce-6.0.html">6.0</a> and <a href=
"/ncurses/announce-6.1.html">6.1</a>, respectively), and some
extensions are known to malfunction even when using just the
low-level terminfo or termcap interfaces (see <a href=
"/ncurses/announce-6.2.html#h3-bug-fixes">ncurses 6.2</a>
release notes).</p>
<ul>
<li>
<p>According to recent (September 2023) discussion with
OpenBSD developers, they plan to upgrade ncurses in
OpenBSD 7.4, while enabling the ncurses 6.x
enhancements.</p>
</li>
<li>
<p>For MacOS, the story is less clear.</p>
<p>Recent updates in Apple's Git repository have been
aimed at some of the ncurses updates in the terminfo
functions (see the “<a href=
"https://github.com/apple-oss-distributions/ncurses/tree/rel/ncurses-61">ncurses-61</a>”
branch which applies the changes for <a href=
"/ncurses/man/curs_terminfo.3x.html#h3-Formatting-Output">
tiparm_s</a>). That could help, but being fifteen years
out of date is a serious handicap.</p>
<p>In July 2023, the MacOS terminfo database was updated.
A subsequent bug report <a href=
"https://github.com/tmux/tmux/issues/3677">tmux #3677</a>
showed that the entry for xterm-256color had errors.
Because that sort of thing could happen if one used the
ncurses 5.7 utilities to compile a terminfo source from
ncurses 6.2 or later, I mention this problem on the
<a href=
"/ncurses/ncurses.html#download_database">terminal
database</a> section of the ncurses home page.</p>
</li>
</ul>
</li>
<li>
<p>Add-on packages (or “ports”) for recent
releases are available for all of the BSDs, except for
OpenBSD:</p>
<ul>
<li><a href=
"https://svnweb.freebsd.org/ports/head/devel/ncurses/">FreeBSD
ports</a></li>
<li><a href=
"https://github.com/macports/macports-ports/blob/master/devel/ncurses/Portfile">
MacPorts</a> and <a href=
"https://formulae.brew.sh/formula/ncurses">brew</a></li>
<li><a href="http://pkgsrc.se/devel/ncurses">pkgsrc</a>,
for NetBSD and others.</li>
</ul>
<p>Newer versions of ncurses also work with OpenBSD,<br>
but you must configure and compile it yourself (see <a href=
"ncurses-openbsd.html">discussion</a>).</p>
</li>
<li>
<p>Solaris has a <a href=
"https://github.com/oracle/solaris-userland/tree/master/components/ncurses">
<em>component</em></a> for ncurses, which is a dependency of
several other components, such as <em>less</em>,
<em>python</em> and <em>vim</em>.</p>
</li>
</ul>
<h3><a href="#what_platforms" name="platform-vms" id=
"platform-vms">Other systems: VMS</a></h3>
<p>While working on <strong>tin</strong> in 2000, I noticed that
VMS curses is essentially 4.3BSD curses (no color, no video
highlights beyond <em>standout</em>, no locale support hence no
support for wide-characters). There is no working port of ncurses
to VMS.</p>
<p>A defunct port of ncurses associated with <em>GNV</em> is
mentioned here (<a href=
"https://sourceforge.net/p/vms-ports/ncurses/ci/default/tree/">source
in Mercurial</a>):</p>
<ul>
<li><a href=
"https://groups.google.com/g/comp.os.vms/c/GW73_hYyMSA"><em>Does
VMS curses support colour ?</em></a> on <em>comp.os.vms</em>
(June 2017)</li>
<li>
<a href=
"https://sourceforge.net/p/vms-ports/discussion/portingprojects/thread/8e1c9204/">
ncurses 5.9 port to OpenVMS</a> (2013-08-21)
<blockquote>
<pre class=
"code-block">The current state is that this that it compiles and links. It runs but has errors.</pre>
</blockquote>
</li>
<li><a href=
"https://eisner.decus.org/anon/htnotes/note?f1=PORTING_TO_VMS&f2=33.7">
ncurses - New curses library.</a> (2009-10-08)<br>
Lists several issues which had to be addressed in a port, about
half were specific to ncurses.</li>
</ul>
<h3 id="related_programs-id"><a href="#what_platforms" name=
"related_programs" id="related_programs">Examples of ncurses
programs</a></h3>
<p>The ncurses distribution only includes programs that must be
maintained with it, since they rely on internal details of the
library.</p>
<p>Part of the ncurses distribution (the test/demo <a href=
"/ncurses/ncurses-examples.html">ncurses-examples</a>) are
designed to work with other versions of curses, to help with
comparisons.</p>
<p>The release announcements list examples of the different types
of library users (e.g., in <a href=
"announce.html#h2-who-uses"><em>Applications using
ncurses</em></a>).</p>
<p>A few of those are special, because others used them as
examples of ncurses usage, leading to direct involvement in
improving their use of ncurses:</p>
<ul>
<li><a href="/cdk/cdk.html">cdk</a> Curses Development Kit (a
library of widgets)</li>
<li><a href="/dialog/dialog.html">dialog</a> Script-driven
curses widgets</li>
</ul>
<hr>
<h2 id="latest_version-id"><a name="latest_version" id=
"latest_version">What is the latest version?</a></h2>
<p>The current stable version is 6.4 20221231, available from the
ncurses homepage:</p>
<blockquote>
<p>HTTP: <a href=
"https://invisible-island.net/archives/ncurses/ncurses-6.4.tar.gz">
ncurses.tar.gz</a> (<a href=
"https://invisible-mirror.net/archives/ncurses/ncurses-6.4.tar.gz">mirror</a>)</p>
<p>Local: <a href=
"/archives/ncurses/ncurses-6.4.tar.gz">ncurses.tar.gz</a></p>
</blockquote>
<p>I also maintain development patches toward the next release.
See the <a href="/ncurses/NEWS.html">NEWS</a> file for
changes.</p>
<blockquote>
<p>HTTP: <a href=
"https://invisible-island.net/archives/ncurses/6.4/">https://invisible-mirror.net/archives/ncurses/6.4/</a>
(<a href=
"https://invisible-mirror.net/archives/ncurses/6.4/">mirror</a>)</p>
<p>Local: <a href=
"/archives/ncurses/6.4/">/archives/ncurses/6.3/</a></p>
</blockquote>
<p>After announcing a new patch, I provide the source in an
alternate form as described <a href=
"/personal/git-exports.html">here</a>:</p>
<blockquote>
<p><a href=
"https://github.com/ThomasDickey/ncurses-snapshots">ncurses-snapshots</a></p>
</blockquote>
<h2 id="other_versions-id"><a name="other_versions" id=
"other_versions">Official releases</a></h2>
<p>There have been a number of releases of ncurses. Some are
available on CDROM (beginning with 1.9.4), and are archived on
various ftp servers. If you are downloading, however, the older
versions are of limited interest except for software testers.</p>
<ul>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-6.5.tar.gz">6.5</a>
<a href="/ncurses/announce-6.5.html">(27 April 2024)</a>.
This is a bug-fix release (improved terminfo library
interface, and an optional feature for serial terminals).</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-6.4.tar.gz">6.4</a>
<a href="/ncurses/announce-6.4.html">(31 December 2022)</a>.
This is a bug-fix release (some feature improvements, but no
new features).</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-6.3.tar.gz">6.3</a>
<a href="/ncurses/announce-6.3.html">(21 October 2021)</a>.
This corrects a few problems which interfered with
portability. It also adds a new console I/O driver for
Windows Terminal, and a script to make it easy for OpenBSD
users to upgrade their system's ncurses libraries and
utilities.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-6.2.tar.gz">6.2</a>
<a href="/ncurses/announce-6.2.html">(12 February 2020)</a>.
This corrects two problems in tic which interfered with
extending the terminal database. It also improves checking
for mis-typed user-defined capabilities in the terminal
database.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-6.1.tar.gz">6.1</a>
<a href="/ncurses/announce-6.1.html">(27 January 2018)</a>.
This improves integration among the command-line utilities
(tput, tset, clear). It also extends the range of numeric
capabilities.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-6.0.tar.gz">6.0</a>
<a href="/ncurses/announce-6.0.html">(8 August 2015)</a>.
This updates the ABI to support 256-colors, as well as
improving termcap compatibility, and the MinGW port.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-5.9.tar.gz">5.9</a>
<a href="/ncurses/announce-5.9.html">(4 April 2011)</a>. This
fixes a regression in <code>newwin</code>, and improves
configurability/portability of the Ada95 binding when built
as a separate tree. <a href="/ncurses/announce-5.8.html">(26
February 2011)</a>. This extends support for threaded
applications by providing a new API which eliminates the need
for a global screen-pointer. It also introduces a port to
Windows using MinGW, as noted in the <a href=
"/ncurses/announce-5.8.html">5.8 announcement</a>.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-5.7.tar.gz">5.7</a>
<a href="/ncurses/announce-5.7.html">(2 November 2008)</a>.
This provides rudimentary support for threaded applications.
It also distributes <code>tack</code> separately.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-5.6.tar.gz">5.6</a>
<a href="/ncurses/announce-5.6.html">(17 December 2006)</a>.
This supports hashed database for the terminal descriptions.
It also improves support for magic cookies.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-5.5.tar.gz">5.5</a>
<a href="/ncurses/announce-5.5.html">(10 October 2005)</a>.
This improves support for wide- and multibyte characters,
modifies the form- and menu-libraries to work with multibyte
characters. It also improves support for cross-compiling.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-5.4.tar.gz">5.4</a>
<a href="/ncurses/announce-5.4.html">(8 February 2004)</a>.
This improves support for wide- and multibyte characters,
implements the remaining parts of the X/Open Curses
interface. It also improves support for termcap.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-5.3.tar.gz">5.3</a>
<a href="/ncurses/announce-5.3.html">(12 October 2002)</a>.
This provides support for wide- and multibyte characters,
implements most of the corresponding X/Open Curses interface.
It also improves support for termcap.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-5.2.tar.gz">5.2</a>
<a href="/ncurses/announce-5.2.html">(21 October 2000)</a>.
This provides better support for termcap, fixes for the
manpage and shared library configurations, and improved
checks for corrupt terminfo database.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-5.1.tar.gz">5.1</a>
<a href="/ncurses/announce-5.1.html">(8 July 2000)</a>. This
provides better support for termcap as well as implementing
new extensions for colors.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-5.0.tar.gz">5.0</a>
<a href="/ncurses/announce-5.0.html">(23 October 1999)</a>.
This aligns interfaces to match version 2 of the X/Open
Curses Single Unix specification from 1997. It also provides
better termcap support, and termcap-like features such as
user-defined terminal capabilities.</p>
</li>
<li>
<p><a href=
"https://ftp.gnu.org/gnu/ncurses/ncurses-4.2.tar.gz">4.2</a>
<a href="/ncurses/announce-4.2.html">(2 March 1998)</a>. This
implements C++ bindings for the library, as well as
extensions to support runtime definition of keycodes.</p>
</li>
<li>
<p>4.1 <a href="/ncurses/announce-4.1.html">(16 May
1997)</a>. This release features support for GPM (mouse on
Linux console), and adds an extension for default colors.</p>
</li>
<li>
<p>4.0 <a href="/ncurses/announce-4.0.html">(24 December
1996)</a>. A change in version numbering addresses a problem
exposed by David Engel's <code>ld.so.1.8.5</code> program for
Linux.</p>
</li>
<li>
<p>1.9.9g <a href=
"/ncurses/ncurses-license.html#patch_961130">(1 December
1996)</a>.</p>
</li>
<li>
<p><a href=
"/ncurses/ncurses-license.html#ncurses_1_9_9e">1.9.9e</a> is
broken. A last-minute/untested change causes forms and menus
to not refresh. Foreground/background colors are combined
incorrectly, working properly only on a black background.</p>
</li>
<li>
<p>1.9.8a <a href=
"/ncurses/ncurses-license.html#ncurses_1_9_8a">(ok)</a></p>
</li>
<li>
<p>1.9.7a <a href=
"/ncurses/ncurses-license.html#ncurses_1_9_7a">(ok)</a></p>
</li>
<li>
<p>1.9.4 is the oldest version that you should consider
installing. It came with Slackware 3.0; earlier releases had
a number of problems, including incompatible terminal
descriptions.</p>
</li>
</ul>
<h2 id="known_problems-id"><a name="known_problems" id=
"known_problems">Known/Frequent problems</a></h2>
<ul>
<li>
<a href="#build_and_install">Building and Installing
NCURSES</a>
<ul>
<li><a href="#running_tests">How do I run the
test-programs?</a></li>
<li><a href="#applying_patches">How do I apply patches?</a></li>
<li><a href="#where_patches">Where are the patches?</a></li>
<li><a href="#big_terminfo">The terminfo database is
big—do I need all of that?</a></li>
<li><a href="#no_terminfo">Do I really need a terminfo
database?</a></li>
<li><a href="#which_terminfo">Which terminfo database do I
need?</a></li>
<li><a href="#compatible_tic">Is ncurses terminfo
compatible with my system?</a></li>
<li><a href="#compatible_lib">Is the ncurses library
compatible with my system?</a></li>
<li><a href="#remote_shells">Problems with remote
shells</a></li>
<li><a href="#cross_compiles">Problems with
Cross-Compiling</a></li>
</ul>
</li>
<li>
<a href="#problems_configuring">Configuring NCURSES</a>
<ul>
<li><a href="#config_small">Do I need all of those programs
and libraries?</a></li>
<li><a href="#config_cplus">Do I need the C++ binding?</a></li>
<li><a href="#config_linux">Why does <em>make
menuconfig</em> fail?</a></li>
<li><a href="#config_gcc296">Problem building with gcc
2.96.x</a></li>
<li><a href="#config_gcc3x">Problem building C++ interface
with gcc 3.x</a></li>
<li><a href="#config_leaks">Testing for Memory Leaks</a></li>
</ul>
</li>
<li>
<a href="#problems_customizing">Customizing NCURSES</a>
<ul>
<li><a href="#home_terminfo">How do I set up a private
terminfo database?</a></li>
<li><a href="#unknown_term">My terminal is not
recognized</a></li>
<li><a href="#extended_term">Why use terminfo instead of
extensible termcap?</a></li>
<li><a href="#other_extended_term">What implementations of
terminfo are extended?</a></li>
</ul>
</li>
<li>
<a href="#problems_performance">Making NCURSES Fast</a>
<ul>
<li><a href="#hash_scrolling">Why does my program scroll
slowly?</a></li>
<li><a href="#no_padding">Why does VT100 refresh
slowly?</a></li>
</ul>
</li>
<li>
<a href="#problems_coloring">Making Color Work</a>
<ul>
<li><a href="#vt100_color">How do I get color with
VT100?</a></li>
<li><a href="#no_color">My terminal doesn't recognize
color</a></li>
<li><a href="#bce_mismatches">My terminal shows some
uncolored spaces</a></li>
<li><a href="#no_xterm_color">My xterm program doesn't
recognize color</a></li>
<li><a href="#no_colorterm">Why doesn't ncurses use
<code>$COLORTERM</code>?</a></li>
<li><a href="#xterm_color">Why not just use TERM set to
"xterm-color"?</a></li>
<li><a href="#xterm_generic">Why not just use TERM set to
“xterm”?</a></li>
<li><a href="#xterm_256color">Why not make
“xterm” equated to
“xterm-256color”?</a></li>
<li><a href="#xterm_16MegaColors">Why only 16 (or 256)
colors?</a></li>
<li><a href="#white_black">Ncurses resets my colors to
white/black</a></li>
<li><a href="#interchanged_colors">Why are red/blue
interchanged?</a></li>
</ul>
</li>
<li>
<a href="#problems_display">Other Display Problems</a>
<ul>
<li><a href="#no_line_drawing">Line-drawing characters come
out as x's and q's</a></li>
<li><a href="#bad_line_drawing">Line-drawing characters
come out as Latin-1 characters</a></li>
<li><a href="#utf8_line_drawing">Line-drawing characters do
not appear</a></li>
<li><a href="#emacs_cvvis">Why does my cursor blink in
Emacs?</a></li>
<li><a href="#multithread">Why does (fill in the blank)
happen when I use two threads?</a></li>
</ul>
</li>
<li>
<a href="#problems_keyboard">Keyboard Problems</a>
<ul>
<li><a href="#cursor_appmode">My cursor keys do not
work</a></li>
<li><a href="#bash_meta_mode">Alt-keys do not work in
bash</a></li>
<li><a href="#home_end_keys">My home/end keys do not
work</a></li>
<li><a href="#modified_keys">How can I use shift- or
control-modifiers?</a></li>
<li><a href="#visible_keys">How can I see what my keyboard
sends?</a></li>
</ul>
</li>
<li>
<a href="#problems_hardware">Using Hardware (Real)
Terminals</a>
<ul>
<li><a href="#reset_logout">Why does reset log me out?</a></li>
<li><a href="#need_padding">Why do I get trash on the
screen?</a></li>
</ul>
</li>
<li>
<a href="#problems_programs">Interaction with Other
Programs</a>
<ul>
<li><a href="#handle_piping">Redirecting I/O to/from a
Curses application</a></li>
<li><a href="#readline_library">What about readline?</a></li>
<li><a href="#setvbuf_once">Problems with Output
Buffering</a></li>
</ul>
</li>
<li>
<a href="#problems_xwindows">Mice and Windows</a>
<ul>
<li><a href="#xterm_paste">I can't cut/paste in xterm</a></li>
<li><a href="#handle_resize">Handling <code>SIGWINCH</code>
(resize events)</a></li>
<li><a href="#using_gpm_lib">Linking with GPM (Linux
console mouse library)</a></li>
</ul>
</li>
<li>
<a href="#problems_packages">Problems with Packages</a>
<ul>
<li><a href="#packages_buggy">Comments on packages</a></li>
<li><a href="#version4_or_not">Ncurses 4/4.2/5.0</a></li>
<li><a href="#colorfgbg_bug">rxvt's <code>$COLORFGBG</code>
variable</a></li>
<li><a href="#no_urxvt">Where is rxvt-unicode?</a></li>
</ul>
</li>
</ul>
<h3 id="build_and_install-id"><a name="build_and_install" id=
"build_and_install">Building and Installing NCURSES</a></h3>
<h4 id="running_tests-id"><a name="running_tests" id=
"running_tests">How do I run the test-programs?</a></h4>
<p>You must first install the terminfo data (i.e., "make
install.data").</p>
<p>On many systems (those that have a SVr4 curses installed) you
can run the test programs using the vendor's terminfo database
(e.g., Solaris, IRIX, HP-UX) by setting the TERMINFO variable to
point to that instead.</p>
<h4 id="applying_patches-id"><a name="applying_patches" id=
"applying_patches">How do I apply patches?</a></h4>
<p>See also <a href="#patch_summary">How are patches
organized?</a></p>
<p>I name development patches after the base release, with the
patch date originally (in 1996) in the form <em>yymmdd</em> and
starting with the year 2000 <em>yyyymmdd</em>.</p>
<ul>
<li>
<p>you need patch 2.1 (originally, I believe, in the X
distribution, but also from GNU now, e.g., <a href=
"https://ftp.gnu.org/gnu/patch/">ftp.gnu.org</a>). Version
2.5 offers some advantages (handles lines wider than 1024
characters), but introduces new bugs (its name resolution
algorithm gets more easily confused by duplicate names in the
tree). The interim versions (2.2, 2.3, 2.4) are
unacceptable.</p>
</li>
<li>
<p>you also need gzip 1.2.4, since both the base release and
the patches are gzip'd.</p>
</li>
<li>
<p>Assuming you have all of the patches and the 4.2 tar.gz
file in the same directory and are running in Bourne
shell:</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
zcat ncurses-4.2.tar.gz |tar xf -<br>
<span class="keyword">cd</span> ncurses-4.2<br>
<span class="keyword">for</span> n <span class=
"keyword">in</span> ../ncurses<span class=
"number">-4</span>.2-*.gz ; <span class=
"keyword">do</span> zcat <span class=
"ident2">$n</span> | patch -p1 ; <span class="keyword">done</span><br>
<!--atr2html}}--></p>
</blockquote>
</li>
</ul>
<h4 id="where_patches-id"><a name="where_patches" id=
"where_patches">Where are the patches?</a></h4>
<p>Development patches (and a rollup patch updated periodically)
are available for download:</p>
<blockquote>
<p>HTTP: <a href=
"https://invisible-island.net/archives/ncurses/6.4/">https://invisible-island.net/archives/ncurses/6.4/</a></p>
<p>HTTP: <a href=
"https://invisible-mirror.net/archives/ncurses/6.4/">https://invisible-mirror.net/archives/ncurses/6.4/</a></p>
</blockquote>
<p>Look for a file named something like
"<code>patch-6.4-<em>yyyymmdd</em>.sh.gz</code>" The
"<em>yyyymmdd</em>" part corresponds to the patch-date.</p>
<p>After providing a rollup patch, I remove the development
patches to reduce clutter. Beginning in May 2013, I modified the
process to provide all of the development patches since the
release in “dev-patches.zip”.</p>
<p>There are also a few rollup patches between releases:</p>
<p>Download:</p>
<ul>
<li><a href="/archives/ncurses/patches/">patches</a></li>
<li><a href=
"/archives/ncurses/patches/patch-4.2-5.0.sh">patch-4.2-5.0.sh</a></li>
<li><a href=
"/archives/ncurses/patches/patch-5.0-5.1.sh">patch-5.0-5.1.sh</a></li>
<li><a href=
"/archives/ncurses/patches/patch-5.1-5.2.sh">patch-5.1-5.2.sh</a></li>
<li><a href=
"/archives/ncurses/patches/patch-5.2-5.3.sh.gz">patch-5.2-5.3.sh.gz</a></li>
<li><a href=
"/archives/ncurses/patches/patch-5.3-5.4.sh.gz">patch-5.3-5.4.sh.gz</a></li>
<li><a href=
"/archives/ncurses/patches/patch-5.4-5.5.sh">patch-5.4-5.5.sh</a></li>
<li><a href=
"/archives/ncurses/patches/patch-5.5-5.6.sh.gz">patch-5.5-5.6.sh.gz</a></li>
<li><a href=
"/archives/ncurses/patches/patch-5.6-5.7.sh.gz">patch-5.6-5.7.sh.gz</a></li>
<li><a href=
"/archives/ncurses/patches/patch-5.7-5.8.sh.gz">patch-5.7-5.8.sh.gz</a></li>
<li><a href=
"/archives/ncurses/patches/patch-5.8-5.9.sh.gz">patch-5.8-5.9.sh.gz</a></li>
<li><a href=
"/archives/ncurses/patches/patch-6.0-20150808.sh.gz">patch-6.0-20150808.sh.gz</a></li>
<li><a href=
"/archives/ncurses/patches/patch-6.1-20180127.sh.gz">patch-6.1-20180127.sh.gz</a></li>
<li><a href=
"/archives/ncurses/patches/patch-6.2-20200212.sh.gz">patch-6.2-20200212.sh.gz</a></li>
<li><a href=
"/archives/ncurses/patches/patch-6.3-20211021.sh.gz">patch-6.3-20211021.sh.gz</a></li>
</ul>
<p>The rollup patches include all patches through the cited
version. You must apply them to the base release, e.g.,</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
zcat ncurses-4.1.tar.gz |tar xf -<br>
<span class="keyword">cd</span> ncurses-4.1<br>
sh ../patch<span class="number">-4</span>.1<span class=
"number">-4</span>.2.sh <!--atr2html}}--></p>
</blockquote>
<p>I have tested the rollup patches with patch 2.1 and 2.5,
adjusting for their respective limitations.</p>
<h4 id="big_terminfo-id"><a name="big_terminfo" id=
"big_terminfo">The terminfo database is big—do I need all
of that?</a></h4>
<p>Not at all. You can load a subset of the terminfo database. I
use a variant of this script to load the terminal descriptions
that I need on my machine:</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
<span class="comment">#!/bin/sh</span><br>
<span class=
"comment"># uses the -e switch on tic to selectively load descriptions that are</span><br>
<span class=
"comment"># interesting for my testing.</span><br>
<span class="keyword">if</span> <span class=
"keyword">test</span> -f terminfo.src ; <span class="keyword">then</span><br>
<span class=
"ident2">TMP</span>=/tmp/load<span class="ident2">$$</span><br>
<span class=
"keyword">trap</span> <span class=
"literal">"rm -f </span><span class=
"ident2">$TMP</span><span class=
"literal">"</span> <span class=
"number">0</span> <span class=
"number">1</span> <span class=
"number">2</span> <span class=
"number">5</span> <span class="number">15</span><br>
tic -s <span class="number">-1</span> -I -e<span class="literal">'<br>
ansi, ansi-m, color_xterm, ecma+color,<br>
klone+acs, klone+color, klone+sgr, klone+sgr-dumb,<br>
linux, pcansi-m, rxvt, vt52,<br>
vt100, vt102, vt220, xterm'</span> terminfo.src ><span class="ident2">$TMP</span><br>
tic -s <span class="ident2">$TMP</span><br>
<span class="keyword">else</span><br>
<span class=
"keyword">echo</span> <span class=
"literal">'oops'</span><br>
<span class=
"keyword">exit</span> <span class="number">1</span><br>
<span class="keyword">fi</span><br>
<!--atr2html}}--></p>
</blockquote>
<h4 id="no_terminfo-id"><a name="no_terminfo" id="no_terminfo">Do
I really need a terminfo database?</a></h4>
<p>You could compile-in fallback definitions for the most
commonly used terminal types. To do this, you must already have
<code>infocmp</code> installed (note that ncurses 5.0 infocmp's
support for fallback descriptions is done differently from
ncurses 4.2).</p>
<p>But fallback definitions are really only useful in embedded
applications, where no external files are wanted.</p>
<h4 id="which_terminfo-id"><a name="which_terminfo" id=
"which_terminfo">Which terminfo database do I need?</a></h4>
<p>The most reliable terminfo database is that distributed with
ncurses 5.0, or via followup development patches. The original
process of incorporating terminal descriptions from various
sources corrects some errors in the originals, but introduces
others (either translation errors, or misconceptions). Besides
working to resolve these, from time to time we incorporate new
sources.</p>
<p>As noted in 29 February 2004, the terminfo database at
<a href="http://www.catb.org/~esr/terminfo/">http://www.catb.org/~esr/terminfo/</a>
does not appear to be actively maintained. Since the release of
ncurses 5.0 in late 1999, there are numerous fixes which are not
in that database.</p>
<p>As of January 2012, this is still true. A check with</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
infocmp -x -F termtypes.master terminfo.src<br>
<!--atr2html}}--></p>
</blockquote>
<p>reports that there are 1807 differences for the entries which
the two have in common, as well as 325 entries not in the
“master” terminfo database.</p>
<p>Here are links to current versions:</p>
<ul>
<li><a href=
"/datafiles/current/terminfo.src.gz">terminfo.src.gz</a><br>
</li>
<li><a href=
"/datafiles/current/termcap.src.gz">termcap.src.gz</a></li>
</ul>
<p>If you choose to not install the ncurses terminfo database, we
have found that the SVr4 systems (Solaris, IRIX 6,
OpenServer and HP-UX 10) work well enough for many purposes.
Other systems either are not binary compatible, are incomplete,
or contain more errors than either of the choices mentioned. Some
that are not binary compatible can be accommodated by configuring
ncurses to use the native terminfo format. These include AIX,
HP-UX 11, Tru64 and U/Win.</p>
<h4 id="compatible_tic-id"><a name="compatible_tic" id=
"compatible_tic">Is ncurses terminfo compatible with my
system?</a></h4>
<p>Usually.</p>
<p>Terminfo is compiled into binary form, with booleans, numbers
and strings in arrays. As long as the array items line up, and
the headers (that tell how long the arrays are) are compatible,
ncurses and your vendor's system can each use the same terminfo
database. Older sytems (e.g,. those based on SVr3) implement a
subset of the SVr4 terminfo. For example, HP-UX 9 is
“compatible” up to the entries that would describe
graphic (box) characters. There it diverges.</p>
<p>Other systems (e.g., Digital Unix 4.x and the older AIX 3.2.5)
use different formats and are not compatible.</p>
<p>But those are (very) old systems. If you are not running a
computer museum, you may not even recognize the names of these
systems.</p>
<p>Even for very old systems, however, terminfo <em>source</em>
is compatible and can be compiled using the appropriate tool
(usually <em>tic</em>). Some terminfo descriptions may produce
warnings (e.g., the memu/meml capabilities in the standard xterm
distribution), but the tools compile what they recognize and warn
about the rest.</p>
<p>The ncurses <em>tic</em> program recognizes a wider range of
input than other terminfo compilers, including extensions
coordinated with <em>infocmp</em> that make it easier to use:</p>
<ul>
<li>
<p>compile descriptions that use the long names that
“infocmp -L” produces.</p>
</li>
<li>
<p>the “infocmp -f” option formats complex
expressions into indented format. These are usable with the
standard SVr4 tic program, though not with ncurses 4.0 and
below due to a bug.</p>
</li>
</ul>
<p>More important, ncurses <em>tic</em> allows new terminal
capabilities to be defined, by the
<strong><code>-x</code></strong> option. Rather than warning
about unrecognized capabilities and (otherwise) ignoring them,
ncurses <em>tic</em> will add those to the end of the compiled
terminfo file. Those additions (referred to as <em>user-defined
capabilities</em>) are hidden from the older SVr4 <em>tic</em>
programs because they see only the part described by the file's
header.</p>
<p>The older SVr4 <em>tic</em>, of course, is unchanging.
Development (and maintenance) stopped long ago. But ncurses
development is still (as of 2020) ongoing. Occasionally some bug
is found which affects the terminal database:</p>
<ul>
<li><a href="announce-5.7.html#bug-fixes">ncurses 5.7</a> fixed
a case where <em>tic</em> could have an infinite loop if it
encountered a <em>cancelled</em> user-defined capability.</li>
<li><a href="announce-6.2.html#h3-bug-fixes">ncurses 6.2</a>
fixed a case where forward-references to a user-defined
capability, e.g., via a “use=” clause, were
mishandled.</li>
</ul>
<p>In each case, the tool was improved, but older versions cannot
handle the newer terminfo source. If you must use an older
version of ncurses, use the terminfo source which was distributed
with that version of ncurses.</p>
<p>If you are using ncurses terminfo with another implementation
of <em>tic</em>, the advice is different:</p>
<ul>
<li id="ncurses61-numbers"><a href=
"announce-6.1.html#h4-config-major">ncurses 6.1</a> introduced
support for large number capabilities, e.g., for more than
32767 color pairs. Other implementations generally treated
out-of-range values as zero. This was addressed two years later
in NetBSD's <em>tic</em> program, which may be in NetBSD 10. As
of June 2020, the current release is <a href=
"ncurses-netbsd.html#netbsd9-performance">NetBSD 9</a>.</li>
<li>NetBSD's <em>tic</em> program is known to evaluate <a href=
"ncurses-netbsd.html#netbsd8-cancels"><em>cancelled</em></a>
capabilities differently from SVr4 and ncurses.</li>
</ul>
<h4 id="compatible_lib-id"><a name="compatible_lib" id=
"compatible_lib">Is the ncurses library compatible with my
system?</a></h4>
<p>Yes/no.<br>
Source compatible yes, binary compatible no.</p>
<p>You cannot simply replace your existing curses or termcap
library with ncurses unless you are prepared to recompile
applications that use the curses or termcap library (e.g.,
<code>vi</code>, <code>telnet</code>).</p>
<p>For systems using the Linux kernel, that is feasible. But not
Solaris or other proprietary systems. For those, I recommend
configuring with the <code>--disable-overwrite</code> option.
This directs the configure script to install the library so you
would link it as <code>-lncurses</code>, not adding a symbolic
link to make it link as <code>-lcurses</code>.</p>
<p>The <code>--disable-overwrite</code> option also installs the
header files such as <code>curses.h</code> in a subdirectory,
e.g., <code>/usr/local/include/ncurses/curses.h</code>, thereby
avoiding a (mis)feature of recent versions of <code>gcc</code>
which look first in <code>/usr/local/include</code> for header
files. Since the vendor's compilers do not do this, a common
problem results: compiling with
<code>/usr/include/curses.h</code> and linking with
<code>/usr/local/lib/libcurses.a</code>.</p>
<p>Starting with ncurses 5.3, the behavior for this option
changed. If you do not install into <code>/usr</code>, the
configure script will assume you do not wish to overwrite the
existing version of curses. Configure scripts which do not check
for ncurses headers in both locations are incorrect anyway. They
can be accommodated by setting the <code>$CPPFLAGS</code>
environment variable, e.g.,</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
setenv CPPFLAGS <span class=
"literal">"-I/usr/local/include/ncurses"</span><br>
<!--atr2html}}--></p>
</blockquote>
<h4><a name="remote_shells" id="remote_shells">Problems with
remote shells</a></h4>
<p>Some users notice that remote machines do not have the same
set of terminal descriptions as their local machine. Running a
remote shell on those machines can be a problem because typical
<code>ssh</code> configurations export the
<strong><code>TERM</code></strong> variable to the remote
machine.</p>
<p>Developers who work on multiple machines should be used to
this problem. It is not new: the various operating systems (Unix,
BSDs, MacOS and those using the ncurses terminal database) have
different features, different versions.</p>
<p>One interesting quirk is using the <code>screen</code>
program. The manual page notes:</p>
<blockquote class="code-block">
<p>When <strong>screen</strong> tries to figure out a terminal
name for itself, it first looks for an entry named
<em>"screen.<term>"</em>, where <em><term></em> is
the contents of your <em>$TERM</em> variable. If no such entry
exists, <strong>screen</strong> tries
<em>“screen”</em> (or <em>"screen-w"</em> if the
terminal is wide (132 cols or more)). If even this entry cannot
be found, <em>“vt100”</em> is used as a
substitute.</p>
</blockquote>
<p>Although <code>screen</code>'s mapping to different terminals
is less than perfect, it is possible to improve the mapping by
providing customized <em>"screen.<term>"</em> entries. The
ncurses terminal database has done that since <a href=
"terminfo.src.html#t20010331">early 2001</a>.</p>
<p>As along as the local and remote terminal databases are
complete and up-to-date, things go well. When they are not, users
encounter problems such as in</p>
<blockquote>
<p><em><a href=
"https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=854414">Debian
#854414</a> — screen: after sshing, some commands give
error "Error opening terminal: screen.xterm-256color."</em>
</p>
</blockquote>
<p>The discussion is rather long, with as they say, something for
everyone. The resolution (adding documentation) does not really
solve the problem, since the <code>screen</code> manual page has
been available for some time.</p>
<p>Just to keep things interesting, ncurses 6.1 provides a new
way to solve the problem. The <code>infocmp</code> program can
print a terminal description in a a single line, which when
assigned to the <code>TERMINFO</code> variable lets the library
read the terminal description directly from the variable.
Old-time developers who are knowledgeable about termcap might see
a similarity, but that changes with a closer look:</p>
<ul>
<li>the terminfo information can be written to a single line
(eliminating one of the problems with shell variable
assignments), and</li>
<li>the terminfo description is encoded either in base-64 or
hexadecimal (allowing the binary data to be assigned
safely).</li>
</ul>
<p>This works with ncurses 6.1:</p>
<blockquote>
<pre class="code-block">
TERMINFO=$(<strong>infocmp -0qQ1</strong>) ssh <em>remote</em>
</pre>
</blockquote>
<p>and if the <code>TERMINFO</code> variable has been added to
the list of environment variables in the <code>ssh</code> and
<code>sshd</code>, then ncurses 6.1 applications on the remote
system will read the terminfo description from the environment
variables. Applying the changed <code>TERMINFO</code> to the
single <strong><code>ssh</code></strong> process is preferable to
blindly setting it in your shell's initialization scripts.</p>
<p>That would not work with systems that do not use ncurses 6.1,
but unless the <code>TERMINFO</code> variable is accepted in
their respective <code>sshd</code> configurations, they will not
be confused by this extension.</p>
<p>For those curious about other libraries, slang will ignore the
“broken” <code>$TERMINFO</code> and rely upon its
<a href="ncurses-slang.html#env_TERMINFO_DIRS">compiled-in
terminfo list</a>. Other problems can of course occur.</p>
<h4 id="cross_compiles-id"><a name="cross_compiles" id=
"cross_compiles">Problems with Cross-Compiling</a></h4>
<p>I have done occasional cross-compiles of ncurses since 2003,
using DJGPP as a target, and recently (writing this in 2010) some
MinGW builds. For example</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
<span class="ident2">TARGET</span>=mingw32 <br>
configure \<br>
--with-build-cc=gcc \<br>
--host=<span class="ident2">$TARGET</span> \<br>
--target=<span class="ident2">$TARGET</span><br>
make <!--atr2html}}--></p>
</blockquote>
<p>Cross-compiles of ncurses require compiling utilities which
are then executed at build time. The utilities are wrappers
around ncurses library functions, which means that some special
#define's may be needed to compile them. In particular (until May
2010) cross-compiling the wide-character library required adding
something like this:</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
--with-build-cppflags=-D_XOPEN_SOURCE<br>
<!--atr2html}}--></p>
</blockquote>
<p>Ncurses 5.7 introduced a separate problem. The terminal
database distributed with it uses a feature that causes older
versions of <a href="/ncurses/man/tic.1m.html">tic</a> to hang.
If you are cross-compiling, the database is installed using your
system's copy of tic. You can work around the problem by either
updating ncurses (5.7 was released in 2008), or substituting an
older version of <code>misc/terminfo.src</code> in the build
tree.</p>
<h3 id="problems_configuring-id"><a name="problems_configuring"
id="problems_configuring">Configuring NCURSES</a></h3>
<h4 id="config_small-id"><a name="config_small" id=
"config_small">Do I need all of those programs and libraries?</a></h4>
<p>Well, I use them...</p>
<p>Wrong answer.<br>
You may need only the ncurses library, or even just the terminfo
database. The top-level Makefile in the build tree is designed to
let you install various combinations according to your
requirements. But there are a few constraints:</p>
<ul>
<li>
<p>You can install only the terminfo database by typing "make
install.data". But you must have a copy of <code>tic</code>
built. If you chose to build with shared libraries, you
should first install the libraries and programs, e.g., with
"make install.libs install.progs". Otherwise the shared
libraries will not be found properly for the terminfo
compiler to run.</p>
</li>
<li>
<p>The version numbers attached to the shared libraries do
mean something. Do not rename them (or link other versions to
them).<br>
Version 5 is not compatible with version 4.<br>
Version 4 is not compatible with version 3.<br>
We have made corrections at each release to match the X/Open
Curses interface specification. I have seen as many people
complaining about mysterious problems with ncurses as I have
seen people advising others to save time/space by linking
them.</p>
</li>
</ul>
<h4 id="config_cplus-id"><a name="config_cplus" id=
"config_cplus">Do I need the C++ binding?</a></h4>
<p>You may not need the C++ binding for ncurses. However, you
should configure ncurses with C++ if it is available on your
system. Otherwise, you will not be able to compile ncurses
applications with the C++ compiler.</p>
<p>This point is not clear in the INSTALLATION instructions,
having been thought too obvious to dwell upon. However, some
distributors have “customized” ncurses, omitting the
C++ binding to save space (or the time to issue separate "make
install" commands for the components which they really need).</p>
<p>The problem is this:</p>
<ul>
<li>
<p>Both ncurses and C++ declare the <em>bool</em> type. It is
part of each of their respective standards.</p>
</li>
<li>
<p>There is no standard that says what the size of
<em>bool</em> is.</p>
</li>
<li>
<p>The ncurses interface uses <em>bool</em>.</p>
</li>
</ul>
<p>The ncurses configure script determines the actual size used
for <em>bool</em> by the C++ compiler on your system. If you
suppress this configuration check, the default size for
<em>bool</em> is not guaranteed to work with your compiler.</p>
<p>With 5.0, the configure script provides two options
(<code>--without-cxx</code> and
<code>--without-cxx-binding</code>). Use the former to suppress
the configure checks for the C++ compiler, e.g., when there is no
working C++ compiler on your system. Use the latter to omit the
C++ binding, if you must.</p>
<h4 id="config_linux-id"><a name="config_linux" id=
"config_linux">Why does <em>make menuconfig</em> fail?</a></h4>
<p>I can only guess (people having trouble in this area generally
do not answer email ;-)</p>
<p>The Linux “make menuconfig” attempts to build a
customized dialog program called <code>lxdialog</code>. This uses
ncurses, which of course is why you are reading this
question/answer.</p>
<ul>
<li>
<p>The development libraries or header files for ncurses may
not be installed.</p>
</li>
<li>
<p>The libraries may be installed in an unusual place. But in
any case, <em>/usr/src/linux/scripts/Makefile</em> is simple
to read, to see where <code>make</code> looks.</p>
</li>
<li>
<p>You may have attempted to upgrade your C library, and did
not complete the job by upgrading libraries that depend upon
it.</p>
</li>
</ul>
<h4 id="config_gcc296-id"><a name="config_gcc296" id=
"config_gcc296">Problem building with gcc 2.96.x</a></h4>
<p>The C preprocessor in gcc 2.96 is broken. In particular, the C
preprocessor has multiple bugs including</p>
<ul>
<li>
<p>does not handle whitespace correctly (breaks ncurses).</p>
</li>
<li>
<p>cannot compile its own preprocessor output (breaks
lynx).</p>
</li>
</ul>
<p>These were apparently fixed in gcc 3.0.4 (do not waste time
with gcc 3.0).</p>
<h4 id="config_gcc3x-id"><a name="config_gcc3x" id=
"config_gcc3x">Problem building C++ interface with gcc 3.x</a></h4>
<p>Since releasing ncurses 5.2, this has been the most frequent
reason for referring people to the <a href=
"#where_patches">rollup patch</a>. The problem is that the C++
bindings to C functions such as <code>vsscanf()</code> were
altered (more than once, apparently as an afterthought) in
preparing the gcc releases. Since the gcc changelog does not cite
these changes except obliquely, and they are undocumented, it is
possible that they may change again.</p>
<h4 id="config_leaks-id"><a name="config_leaks" id=
"config_leaks">Testing for Memory Leaks</a></h4>
<p>Perhaps you used a tool such as <code>dmalloc</code> or
<code>valgrind</code> to check for memory leaks. It will normally
report a lot of memory still in use. That is normal.</p>
<p>The ncurses configure script has an option,
<code>--disable-leaks</code>, which you can use to continue the
analysis. It tells ncurses to free memory if possible. However,
most of the in-use memory is “permanent” (normally
<strong>not</strong> freed).</p>
<p>Any implementation of curses must not free the memory
associated with a screen, since (even after calling
<code>endwin()</code>), it must be available for use in the next
call to <code>refresh()</code>. There are also chunks of memory
held for performance reasons. That makes it hard to analyze
curses applications for memory leaks. To work around this, build
a debugging version of the ncurses library which frees those
chunks which it can, and provides the <a href=
"/ncurses/man/curs_memleaks.3x.html"><code>exit_curses()</code></a>
function to free the remainder on exit. The ncurses utility and
test programs use this feature, e.g., via the
<code>ExitProgram()</code> macro.</p>
<h3 id="problems_customizing-id"><a name="problems_customizing"
id="problems_customizing">Customizing NCURSES</a></h3>
<h4 id="home_terminfo-id"><a name="home_terminfo" id=
"home_terminfo">How do I set up a private terminfo database?</a></h4>
<p>If you must maintain your own terminfo database, SVr4 curses
and ncurses both use the $TERMINFO variable to override the
standard location of the terminfo database. Ncurses also provides
two related extensions: the $HOME/.terminfo directory and the
$TERMINFO_DIRS search path.</p>
<p>Though ncurses tests $TERMINFO first, otherwise it reads from
$HOME/.terminfo before the standard location, and writes to that
location after failing in other places. This design is a
compromise which is made more complicated if you have configured
ncurses with the --enable-termcap and --enable-getcap-cache
options. Unless you are prepared to deal with the hidden
conflicts, you should simply remove the $HOME/.terminfo
directory.</p>
<p>If you do not wish to use $HOME/.terminfo (and are not able to
replace ncurses on your system), ncurses 4.2 and later work
properly if you replace that directory with a file so it cannot
write terminfo entries which would conflict with the standard
location.</p>
<p>The <a href="/ncurses/man/toe.1m.html">toe</a> program can
show a side-by-side comparison of terminal databases, making it
simple to see conflicting entries from your private terminal
database.</p>
<p>As noted, ncurses also provides the $TERMINFO_DIRS extension.
Unlike $HOME/.terminfo, this allows you to specify one or more
locations for the terminal database. When reading a terminal
description, ncurses chooses the first one found. Using this
feature, you can tell ncurses to look in your own database(s) as
well as one or more system-defined locations.</p>
<p>The usual reason for creating a private terminal database is
to work around inability to change the system's terminal
database. Setting $TERMINFO suffices for most users, and happens
to work with other implementations than ncurses. However, for
non-ncurses implementations, it limits the user's environment to
just the terminal database indicated by the $TERMINFO
variable.</p>
<p>As noted in "<a href="#which_terminfo">Which terminfo database
do I need?</a>", there are a few older systems whose compiled
terminfo files differ slightly from the SVr4 layout used by
ncurses. While ncurses can be compiled to match the system's
format (I do this), it seems to be a less-used feature. Packagers
prefer the simpler approach of letting ncurses use its database
and leaving the system applications alone. There are then these
cases for constructing private databases in an NFS-mounted home
directory, shared across different operating system types:</p>
<ul>
<li>
<p>the system's terminfo format is SVr4-compatible.</p>
<ul>
<li>
<p>Use the $TERMINFO variable, e.g., to have all
applications (ncurses and otherwise) use the same
terminal descriptions.</p>
</li>
<li>
<p>Use the $TERMINFO_DIRS variable to make ncurses
applications see a distinct set of terminal descriptions
from the system, e.g., for “xterm”.</p>
</li>
</ul>
</li>
<li>
<p>the system's terminfo format is not SVr4-compatible (AIX
for instance).</p>
<ul>
<li>
<p>if ncurses is compiled to match the system's terminfo
format</p>
<ul>
<li>
<p>as before, you can set either $TERMINFO or
$TERMINFO_DIRS according to whether you want to use
the same definitions for all applications (ncurses
and system).</p>
</li>
<li>
<p>choose a different location for the database,
e.g., $HOME/.terminfo-aix to avoid conflict with
other platforms.</p>
</li>
</ul>
</li>
<li>
<p>if ncurses is <em>not</em> compiled to match the
system's terminfo format, then it is likely that ncurses
and the system curses/terminfo libraries cannot read the
other's compiled terminfo files.</p>
<ul>
<li>
<p>You can set $TERMINFO_DIRS to tell ncurses to look
at its own terminal database; the system libraries
will not look there.</p>
</li>
<li>
<p>Do not set $TERMINFO, since this will cause both
to look in the same place.</p>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>A good place to start when customizing a shell initialization
script for your private terminal databases is of course
<code>uname</code>, since it is provided on the systems which are
relevant to this topic, and its output can tell which system type
is used. Alternatively (if your environment happens to have an
inconsistent mixture of ncurses packages), the hostname is
another place to get useful parameters for the initialization
script.</p>
<p>As a rule, these settings should be done in the shell's
<em>login</em> script rather than the one which is run on each
shell <em>initialization</em>.</p>
<h4 id="unknown_term-id"><a name="unknown_term" id=
"unknown_term">My terminal is not recognized</a></h4>
<p>Usually this happens because you have not installed the
<code>terminfo</code> database, or it is not in the proper
location. If you do not, and (if ncurses happens to be configured
to provide termcap support using the "--enable-getcap-cache"
configure option) the application is unable to locate the
terminfo database, the ncurses library will attempt to recover by
reading <code>/etc/termcap</code>, translating it into a <a href=
"#home_terminfo">private terminfo database</a>, i.e., a
directory:</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
<span class="ident2">$HOME</span>/.terminfo<br>
<!--atr2html}}--></p>
</blockquote>
<p>This directory can be a nuisance, because the termcap file
often does not contain complete or consistent terminal
descriptions. Remove it and correct the problem (i.e., install
the <code>terminfo</code> database). Better yet, do not enable
the feature (it has been disabled by default since <a href=
"NEWS.html#t961214">late 1996</a>).</p>
<p>You (or the person who configured ncurses) may have installed
terminfo in the wrong, or an obsolete location:</p>
<ul>
<li>
<p>On Linux-based systems, as well as BSD variants such as
FreeBSD and NetBSD the preferred location for terminfo is
<code>/usr/share/terminfo</code>, with a symbolic link from
<code>/usr/lib/terminfo</code> for compatibility with older
applications. Prior to 1.9.9g, the <code>configure</code>
script defaulted to a /usr/local prefix rather than /usr,
necessitating an explicit</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
configure --prefix=/usr <!--atr2html}}--></p>
</blockquote>
</li>
<li>
<p>On other systems, the prefix defaults to /usr/local. You
may wish to change this. Some users install ncurses replacing
other versions of curses altogether. I don't do this. If you
do, read the INSTALL file.</p>
</li>
<li>
<p>Some packagers have gone further, configuring ncurses for
a given terminfo location (which is not the system default),
and then treating ncurses's terminfo database as
“optional”. You can always recover in this case
by setting the <code>TERMINFO</code> environment variable to
point to the real terminfo database.</p>
</li>
<li>
<p>Finally, prior to 1.9.9g, the actual terminfo directory
resided in <code>/usr/lib/terminfo</code>. It was moved to
<code>/usr/share/terminfo</code> to conform to file-system
standards. The installation script attempts to determine if
you have a real directory at the old location, and will not
delete that (because some applications, such as
<code>mc</code> and <code>screen</code> install special
terminal descriptions that you would not want to accidentally
delete. The best solution in this case is to move the old
directory to the new location and install the new terminfo
data, merging into the old data.</p>
</li>
</ul>
<h4 id="extended_term-id"><a name="extended_term" id=
"extended_term">Why use terminfo instead of extensible
termcap?</a></h4>
<p>Several reasons:</p>
<ul>
<li>
<p>there is no standard for termcap. That is a drawback to
developing applications using termcap. Amusingly enough, many
of the termcap capabilities in common use now are defined in
terms of terminfo, much like the <code>inch</code> is defined
in terms of a <code>centimeter</code>.</p>
</li>
<li>
<p>termcap libraries are not as fast, and have a long history
of susceptibility to buffer overflows. See the discussion of
<a href="/ncurses/tctest.html">tctest</a> for example.</p>
</li>
<li>
<p>terminfo supports conditional expressions.</p>
</li>
<li>
<p>ncurses terminfo is extensible anyway. It has been since
<a href="#extended-terminfo-1999">1999</a> (release 5.0). If
you give the <code>-x</code> option to <code>tic</code>, it
compiles additional information which may be in the terminal
description, using the syntax to determine types. If
<code>-x</code> is omitted, <code>tic</code> warns about the
unrecognized information.</p>
</li>
</ul>
<p>As an example of how this extensibility feature can be used,
consider the case of <a href="http://www.openqm.com/">OpenQM</a>,
whose developers copied more than 1000 lines of ncurses library
code into their application to support some extended terminal
capability features. Here are two patches showing how that can be
improved by removing the nonstandard features:</p>
<ul>
<li><a href=
"/archives/ncurses/patches/qmsrc_2-4-4-060701a.patch.gz">Make
the syntax standard</a></li>
<li><a href=
"/archives/ncurses/patches/qmsrc_2-4-4-060701b.patch.gz">Remove
the unnecessary code</a></li>
</ul>
<h3><a name="other_extended_term" id="other_extended_term">What
implementations of terminfo are extended?</a></h3>
<p>This could be a much longer answer, but the FAQ is long. A
really short, but unsatisfying answer might be just
“ncurses and libraries written to work with its database or
to imitate it.” Here is a compromise:</p>
<ul>
<li>Unix System V (mid/late-1980s) provided terminfo using a
predefined set of terminal capabilities, which used 16-bit
integers.</li>
<li>If you wanted to change any of that, you had to modify the
curses library and programs. AT&T did that, adding new
capabilities, in its series of releases culminating in SVr4.
Some vendors did that as well.</li>
<li>Some <em>marketing people</em> might call that
“extended” but <em>programmers</em> would not.</li>
<li>X/Open Curses (early-1990s) documented SVr4's terminfo
(removing some details).<br>
Vendors probably continued to add capabilities.</li>
<li>In <a href="#extended-terminfo-1999">1999</a>, ncurses 5.0
provided a way to add user-defined capabilities (i.e., no
program changes were needed).</li>
<li>The ncurses terminal database could be used by existing
Unix applications.</li>
<li>The user-defined capabilities would not be noticed by
applications using other implementations of curses.</li>
</ul>
<p>Of course, termcap, unlike terminfo, is interpreted and users
could always just add capabilities as needed (although the
absence of a standard termcap was a drawback). That initial
implementation addressed most of the supposed advantage of
termcap over terminfo, except:</p>
<ul>
<li>A number in termcap was not limited to 16-bits, while
ncurses continued to use 16-bits for compatibility with other
implementations.</li>
<li>The ncurses implementation allowed a capability name to be
only one type (boolean <em>or</em> number <em>or</em>
string).</li>
</ul>
<p>A decade later, a few implementations were based on ncurses'
extended terminfo:</p>
<ul>
<li><a href="https://github.com/mauke/unibilium">unibilium</a>
provided applications with a different terminfo <em>reader</em>
for ncurses' extended terminfo.</li>
<li><a href=
"http://cvsweb.netbsd.org/bsdweb.cgi/src/lib/libterminfo/?only_with_tag=MAIN">
NetBSD</a> abandoned termcap in favor of terminfo, and
developed their own terminfo library and programs. The NetBSD
implementation includes the same limitations relative to
termcap as ncurses' initial terminfo extensions.</li>
</ul>
<p>But there were few applications which used the extended
information aside from <a href="/xterm/xterm.html">xterm</a> and
<a href="https://github.com/tmux/tmux">tmux</a>.</p>
<p>So far, that addresses only ncurses' initial implementation.
But ncurses is still under development.</p>
<p>Extended numbers (32-bits) were provided by ncurses 6.1 early
in 2018:</p>
<ul>
<li>There were no credible extant uses of termcap with large
numbers, anyway, but extended numbers in ncurses were useful
for a few who wanted to experiment with direct colors.</li>
<li>The required format change for extended numbers briefly
broke unibilium (as well as slang, which does use
terminfo).</li>
<li>NetBSD was not affected by that improvement. However
(writing this more than a year later, in April 2019) some newer
terminal descriptions would not work with NetBSD curses, if its
terminal database were up-to-date (it was last updated in
February 2017). Writing in mid-2020, future releases of
<a href="#ncurses61-numbers">NetBSD</a> may provide this
feature.</li>
</ul>
<p>While developing the extended numbers feature for ncurses 6.1,
the other limitation (one type per capability name) arose in an
end-user application:</p>
<ul>
<li>Knowledgeable terminal developers provide terminfo (or
termcap) descriptions for their program.<br>
Other developers simply copy/paste something that looks
close.</li>
<li>In this case, someone read the manual page for tmux where
it describes <a href=
"http://man7.org/linux/man-pages/man1/tmux.1.html#TERMINFO_EXTENSIONS">
terminfo extensions</a> which it supports. and did not
understand that the corresponding terminal description has to
fill in some string-values. The <code>Se</code> and
<code>Ss</code> capabilities had no values. The change was
accepted anyway, late in <a href=
"https://git.suckless.org/st/commit/06f8cf8ca87a81db15816658c40b2afcd1ad5332.html">
2016</a>.</li>
<li>Keeping in mind that copy/paste mentality, changes to
ncurses' terminal database are more closely scrutinized (but
see <a href=
"https://github.com/ThomasDickey/ncurses-snapshots/commit/cccd5739099af0656f6cee0b8fb15ccd8f8e0de4#diff-842764d6827ee1f7e8605999bb22e2d6R5837">
update</a>, which fixed other problems but not this one). In
this case, the error was overlooked because there was no
routine testcase for tmux's extensions.</li>
<li>A capability without a value is a boolean value, even if
tmux would like to use it as a string.</li>
<li>By itself, that would only cause tmux to not find the
capability. The problem was that some descriptions used the
capability correctly, and the types differed between
descriptions while <code>tic</code> compiled the database.</li>
<li>For example, <a href=
"terminfo.src.html#toc-_S_I_M_P_L_E_T_E_R_M">this one</a> is
built up from several other descriptions with the
<code>use=</code> clause. When <code>tic</code> builds the
result, it must merge those, accounting for differences in the
lists of extended capabilities.</li>
<li>The initial implementation did not handle that properly;
<code>tic</code> chose the wrong extended capability in
building the merged terminal description. Since even a small
change affects many lines of text, the damage was overlooked at
first. Subsequent fixes <a href="terminfo.src.html#t20171230">a
year later</a> overlooked the problem.</li>
<li>The mismatched string value was a problem because it told
ncurses to expect a <em>parameter</em> when it was used, while
the application did not expect to provide that (see <a href=
"https://github.com/tmux/tmux/issues/1264">tmux
#1264</a>).</li>
<li>Eventually it was reported early in <a href=
"http://lists.gnu.org/archive/html/bug-ncurses/2018-02/msg00034.html">
2018</a>, and the terminfo description fixed.</li>
</ul>
<p>Fixing the terminal description is easy. Improving the tool
takes more time. Development toward ncurses 6.2 made these
changes:</p>
<ul>
<li>adding checks for the <em>conventional</em> extended
capabilities, to warn when a capability would use an unexpected
number of parameters, and disallow that setting (<a href=
"NEWS.html#index-t20190317">20190317</a>).</li>
<li>improving the terminfo-merging to handle differing types
for extended capability names (<a href=
"NEWS.html#t20190427">20190427</a>).</li>
</ul>
<p>Although the problem was fixed in ncurses, users continue to
recommend using the corrupt terminfo file (for example, <a href=
"https://github.com/tmux/tmux/issues/1593">tmux #1593</a>). The
first of those changes to ncurses addresses that source of
error.</p>
<h3 id="problems_performance-id"><a name="problems_performance"
id="problems_performance">Making NCURSES Fast</a></h3>
<h4 id="hash_scrolling-id"><a name="hash_scrolling" id=
"hash_scrolling">Why does my program scroll slowly?</a></h4>
<p>Besides <a href="#need_padding">padding</a> (i.e., time delay)
information, which may be slowing your application down on a
terminal emulator, ncurses provides two versions of scrolling
optimization. The newer/improved version was incompletely tested
at the time of release of ncurses 4.2, so it was marked
<em>experimental</em> in the configure script.</p>
<p>The newer scrolling (hashmap) algorithm does not work properly
in older versions of ncurses. Starting with ncurses 4.2, however,
we recommend enabling this logic when configuring, using the
--enable-hashmap option. It is configured by default in ncurses
5.0</p>
<h4 id="no_padding-id"><a name="no_padding" id="no_padding">Why
does VT100 refresh slowly?</a></h4>
<p>Some terminal descriptions contain <a href=
"#need_padding">padding</a> (i.e., time delay) information.
Ncurses uses this information to slow down the rate at which
characters are sent to the terminal.</p>
<p>However, the vt100 terminal description, which is one of the
most widely used (or misused) contains padding information for a
real DEC VT100. It is not suitable as a replacement for the xterm
terminal description. (Xterm requires no padding).</p>
<p>If you <strong>must</strong> use the vt100 terminal
description, you may consider setting the NCURSES_NO_PADDING
environment variable which is implemented in current versions of
ncurses (since late 1998). That directs ncurses to ignore
nonmandatory time delays in the terminal description.</p>
<h3 id="problems_coloring-id"><a name="problems_coloring" id=
"problems_coloring">Making Color Work</a></h3>
<h4 id="vt100_color-id"><a name="vt100_color" id=
"vt100_color">How do I get color with VT100?</a></h4>
<p>Sorry. Real vt100's do not do color (ANSI or otherwise).
Likewise, vt220, vt340 do not support ANSI colors. You may be
running a terminal emulator which does and do not like this
explanation.</p>
<p>You get "color with VT100" by running a terminal (or emulator)
that supports colors, and by setting up the terminal description
so that ncurses knows how to perform basic operations (setting
the foreground and background colors). See <a href="#no_color">My
terminal doesn't recognize color</a>.</p>
<p>Ncurses does not “know” that your terminal does
support color. You must tell it. Some terminals (e.g., the higher
models of DEC's VTxxx series) provide status information to a
host on the capabilities supported by a terminal. Unix hosts do
not interpret this information to set your $TERM environment
variable. Instead, $TERM is set based on the connection which you
make with your computer (e.g., a device listed in the
/etc/gettydefs or /etc/gettytab files). You can override this by
setting $TERM to a correct value or setting $TERMINFO to a
<a href="#home_terminfo">private database</a>.</p>
<p>Ncurses does not by itself know that vt100's do not do color.
The standard reference for VT100 is its reference manual. There
is a copy of that on <a href="http://vt100.net/">vt100.net</a>
(look for EK-VT100-TM-003_Jul82). There are of course contrary
sources of information about color-vt100's. The earliest one that
I have seen is <a href=
"http://graphcomp.com/info/specs/ansi_col.html">this</a> (a copy
of which has also been found <a href=
"https://web.archive.org/web/20200626080032/http://www.termsys.demon.co.uk/vtansi.htm">
here</a>), which (besides the misinformation in its opening
paragraph) has more than one point where it differs from
vt100:</p>
<ul>
<li><em>Terminal Setup</em>. The example given refers to modes,
saying that few are implemented correctly. But the example
itself is incorrect, because it omits the "?" character which
tells that the sequence is a DEC private mode. For comparison,
see <strong>DECAWM</strong> in xterm's <a href=
"/xterm/ctlseqs/ctlseqs.html">control sequences</a>
document.</li>
<li>
<p><em>Fonts</em>
</p>
<ul>
<li>
<p>vt100 has one “font”. Bold is not a font,
but one of the video attributes which include blink,
reverse, underline.</p>
</li>
<li>
<p>The term “font” is inappropriate;
“character set” is correct.</p>
</li>
<li>
<p>The control sequence cited for switching fonts omits
the character which identifies the character set to
use.</p>
</li>
</ul>
</li>
<li>
<p><em>Cursor Control</em>
</p>
<ul>
<li>
<p><em>Force Cursor Position</em> is the standard
<strong>HVP</strong> (Horizontal and Vertical
Position).</p>
</li>
<li>
<p><em>Save Cursor</em> is from ANSI.SYS rather than
VT100.</p>
</li>
<li>
<p><em>Restore Cursor</em> is from ANSI.SYS rather than
VT100.</p>
</li>
</ul>
</li>
<li>
<p><em>Erase Screen</em> states that the cursor moves to
home. This is a well-known difference between ANSI.SYS and
VT100. With VT100, the cursor does not move. Incidentally,
ISO 6429 (ECMA-48) does not mention either behavior.</p>
</li>
<li>
<p><em>Define Key</em> is not a VT100 feature. It is a
feature of ANSI.SYS.</p>
</li>
<li>
<p><em>Set Display Attributes</em>.</p>
<ul>
<li>
<p><em>Bright</em>. The standard and VT100 documentation
refer to “Bold”.</p>
</li>
<li>
<p><em>Dim</em> is not a VT100 feature.</p>
</li>
<li>
<p><em>Hidden</em> is a VT220 feature, not found in
VT100.</p>
</li>
</ul>
</li>
</ul>
<p>There are several copies of this document (usually missing the
copyright notice) available around the Internet.</p>
<p>After Andrey Chernov added <em>vt100-color</em> and others to
the <a href=
"http://www.freebsd.org/cgi/cvsweb.cgi/src/share/termcap/">FreeBSD
termcap file</a> in 2002, I discussed this with him, pointing out
that while there are terminal emulators which do this, the
hardware did not. He resolved the issue by adding a comment:</p>
<blockquote class="code-block">
<pre>
# For color-enabled terminal emulators
</pre>
</blockquote>
<p>(See revisions 1.117 and 1.119).</p>
<p>Even with that clarification, there are others who conflate
“ANSI”, “VT100” and color, for
example</p>
<ul>
<li><a href=
"http://www.nyangau.org/terminfo/terminfo.htm">Andys Terminfo
Package</a></li>
<li><a href=
"http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=241717">Debian
#241717</a></li>
</ul>
<p>Ncurses does not have terminal descriptions such as
<em>vt100-color</em> because those are inevitably an
oversimplification. For related discussion, see my comments on
<a href=
"/xterm/xterm.faq.html#xterm_terminfo">"xterm-color"</a>.</p>
<h4 id="no_color-id"><a name="no_color" id="no_color">My terminal
doesn't recognize color</a></h4>
<p>Check the terminal description, to see if it is installed
properly (e.g., in <code>/usr/share/terminfo</code>) by looking
at the output of <code>infocmp</code>.</p>
<dl>
<dt>It should contain the following capabilities (shown with
infocmp -L):</dt>
<dd>
<blockquote>
<p><code>orig_pair</code> or <code>orig_colors</code><br>
and <code>max_colors</code><br>
and <code>max_pairs</code></p>
</blockquote>
</dd>
<dt>as well as</dt>
<dd>
<blockquote>
<p><code>set_foreground</code> and
<code>set_background</code><br>
or <code>set_a_foreground</code> and
<code>set_a_background</code><br>
or <code>set_color_pair</code></p>
</blockquote>
</dd>
</dl>
<p>The <code>orig_pair</code> and <code>orig_colors</code>
capabilities are not required in ncurses 5.0 (SVr4 curses works
properly without them). For the rest:</p>
<ul>
<li>
<p><code>max_colors</code> and <code>max_pairs</code> are
<em>numbers</em>, which (at least) should be nonzero.</p>
<p>Prior to ncurses 6.1, those were signed 16-bit values.
With <a href="announce-6.1.html">ncurses 6.1</a> (and using
the recommended ABI 6), it is possible to use signed 32-bit
values except in interfaces where the requirement for binary
compatibility would prevent this.</p>
<p>Several of the terminal descriptions were updated in
ncurses 6.1 to take advantage of this, e.g., using larger
values for <code>max_pairs</code>. Older toolsets may not
accept the larger values. Solaris and NetBSD curses assign
any out-of-range capability a zero value.</p>
<p>Like ncurses 6.0, ncurses 6.1 can be compiled to support
the older ABI 5. In that case, <code>tic</code> and
<code>infocmp</code> check for overflow, and limit values to
16 bits. Because of these added checks, it is possible to
have ncurses ABI 5 and 6 on the same machine. In contrast,
older ncurses releases <em>use</em> only the low-order 16
bits of the value, which may have the same effect as Solaris
and NetBSD (the low-order 16 bits of 0x10000 is zero).</p>
</li>
<li>
<p>The other capabilities are <em>strings</em>, used for the
escape sequences that tell the terminal what colors it should
use.</p>
</li>
</ul>
<p id="no-color-ls">The most common complaint is that "I can see
colors using <code>ls</code>, but not with ncurses applications".
This is due to not having installed the <code>terminfo</code>
database. GNU <code>ls</code> (in contrast to FreeBSD
<code>ls</code>) uses its own data (with hardcoded SGR numbers
and ignoring the <a href=
"/xterm/xterm.faq.html#xterm_terminfo">back color erase (bce)</a>
feature supported in terminfo/termcap), which is unrelated to
other applications. To be fair, GNU ls does have an environment
variable (<code>LS_COLORS</code>) which can be used to customize
the numbers a little, but in practice very few users modify
it.</p>
<p id="no-colorterm">Other libraries or applications may
recognize other environment variables to supplant the terminal
description (see for example the discussion of <a href=
"#no_colorterm">COLORTERM</a>), or even assign special meaning to
different values of the <code>$TERM</code> environment variable,
but ncurses uses only the terminal description.</p>
<h4 id="bce_mismatches-id"><a name="bce_mismatches" id=
"bce_mismatches">My terminal shows some uncolored spaces</a></h4>
<p>Even if your terminal <em>supports</em> the <a href=
"/xterm/xterm.faq.html#xterm_terminfo">back color erase (bce)</a>
feature, you may still have problems using it.</p>
<p>We can blame the standard (ISO-6429 aka ECMA-48 aka
“ANSI”). It is too simplistic, being <em>descriptive
rather than prescriptive</em>. What is that, you might ask? It
means that the standards writers used existing simplified
descriptions by developers for the features rather than
decomposing the features into distinct parts—and then
making precise descriptions of those for testing compatibility of
various implementations. The standard does not go into enough
detail to <em>prescribe</em> a particular behavior.</p>
<p>Back color erase covers many (usually) related features,
because there are many control sequences which might affect
color, depending on the implementation. Here is a list—for
each item there is probably at least one terminal type which
differs from ncurses' assumptions. The list shows terminfo names
with the standard control name, if any, in parentheses:</p>
<dl>
<dt><tt><em>sgr0</em></tt> (<tt>SGR 0</tt>)</dt>
<dd>
<p>The standard notes that this is "implementation-defined",
and "cancels the effect of any preceding occurrence of
SGR".</p>
<p>For practical purposes, ncurses has to assume that the
cancellation applies to the normal video attributes such as
bold, underline, reverse, but possibly not affecting color.
Color came into the picture fairly late in the history of
terminals, and there have been some (such as <a href=
"/xterm/xterm.faq.html#bug_color_xterm">color_xterm</a>)
where <tt>SGR 0</tt> had no effect on color.</p>
</dd>
<dt><tt><em>ed</em></tt> (<tt>ED</tt>).</dt>
<dd>
<p>The erase-display feature is assumed to fill the cleared
display (or part of the display) with the current background
color.</p>
<p>Examples of terminals which do not do this include dtterm
and teraterm 2.3.</p>
</dd>
<dt><tt><em>el</em></tt>, <tt><em>el1</em></tt>
(<tt>EL</tt>)</dt>
<dd>
<p>The erase-line feature is assumed to fill the cleared line
(or part of line) with the current background color.</p>
<p>There is no standard requiring that the behavior of
<tt>EL</tt> and <tt>ED</tt> should affect color in the same
way. It is a design choice; ncurses assumes this.</p>
</dd>
<dt><tt><em>ech</em></tt> (<tt>ECH</tt>)</dt>
<dd>
<p>Erasing a character (which does not move any text on the
screen) is assumed to fill the erased cells with the
background color.</p>
<p>Rxvt does not do this, though its behavior matches most of
the other assumptions.</p>
<p>For xterm, <tt>ECH</tt> is a VT220 feature. VT220s (and
for that matter, none of DEC's VTxxx series before the VT525)
did not implement ANSI color (or any style of color which you
would use with ncurses). Rxvt's behavior was based on its
developer's interpretation of DEC's documentation. XTerm's
behavior on the other hand was based on (generally) agreeing
with the developer of the Linux console.</p>
</dd>
<dt><tt><em>ich</em></tt>, <tt><em>ich1</em></tt>
(<tt>ICH</tt>)</dt>
<dd>
<p>Inserting an <em>empty</em> cell at the current position
is assumed to fill the empty cell with the background
color.</p>
<p>Note that this control does not <em>erase</em> as one
would infer from <em>back color <strong>erase</strong></em>.
But it creates an <em>empty</em> cell.</p>
</dd>
<dt><tt><em>dch</em></tt>, <tt><em>dch1</em></tt>
(<tt>DCH</tt>)</dt>
<dd>
<p>Deleting the cell at the current position shifts the
remainder of the line left, introducing an <em>empty</em>
cell on the right end of the line.</p>
<p>Note that this control does not <em>erase</em> as one
would infer from <em>back color <strong>erase</strong></em>.
But it creates an <em>empty</em> cell.</p>
</dd>
<dt><tt><em>il</em></tt>, <tt><em>il1</em></tt>
(<tt>IL</tt>)</dt>
<dd>
<p>Inserting an <em>empty</em> line at the current position
is assumed to fill the new empty line with the background
color.</p>
<p>Note that this control does not <em>erase</em> as one
would infer from <em>back color <strong>erase</strong></em>.
But it creates an <em>empty</em> row.</p>
</dd>
<dt><tt><em>dl</em></tt>, <tt><em>dl1</em></tt>
(<tt>DL</tt>)</dt>
<dd>
<p>Deleting the line at the current position shifts the
remainder of the screen up, introducing an <em>empty</em> row
on the bottom of the screen.</p>
<p>Note that this control does not <em>erase</em> as one
would infer from <em>back color <strong>erase</strong></em>.
But it creates an <em>empty</em> row.</p>
</dd>
<dt><tt><em>ind</em></tt>, <tt><em>indn</em></tt>
(<em>nonstandard</em>)</dt>
<dd>
<p>Scrolling the text up is assumed to fill the newly empty
line (at the bottom of the display) with the current
background color.</p>
<p>Indexing, aka “scrolling” is not covered in
the standard. The behavior is completely
implementation-dependent. This is a commonly used feature of
XTerm.</p>
<p>There are subtle differences in behavior still possible,
beyond filling and not filling. For instance, if the
scrolling was in response to printing text which wrapped,
that may or may not (depending on implementation) fill the
newly empty line with the current background color.</p>
<p>For instance, a change in this area the Linux 2.6.26
console driver in <a href=
"http://lkml.org/lkml/2008/4/26/305">April 2008</a> was
reverted <a href="https://lkml.org/lkml/2008/10/3/66">6
months later</a>. That was a bug for Linux console, because
it broke more than <a href=
"ncurses-slang.html#cause_bce_linux">16 years</a> of
predictable behavior (since 0.96b in June 1992). Likewise it
would be a bug for XTerm (and I have rejected patches to
“improve” its behavior in this detail). But other
terminals could do this intentionally as I observed of the
“VT340” emulator bundled with the OnNet TCP/IP
product of FTP Software in the mid 1990s.</p>
<p>The standard, by the way, takes it for granted that text
will wrap and force the display to scroll. But it uses the
terms “wrap” and “scroll” in only a
few obscure comments, and doubtless left much leeway for
implementation-dependent behavior.</p>
<p>XTerm of course implements scrolling because it was based
on DEC's VT100, which does this. While a real VT340 did not
support ANSI colors, one model of DEC's last terminal (the
VT525) did. Its documentation indicates that it was released
September 30, 1994 (more than two years after Linux's
“new color model” was available). The DEC
documentation mentions a setting (<tt>DECECM</tt>):</p>
<blockquote>
<p class="code-block">The <strong>Erase color</strong>
selection controls the background color used when text is
erased or new text is scrolled on to the screen.
<strong>Screen background</strong> causes newly erased
areas or scrolled text to be written using color index
zero, the screen background. This is VT and DECterm
compatible. <strong>Text background</strong> causes erased
areas or scrolled text to be written using the current text
background color. This is PC console compatible and is the
factory default.</p>
</blockquote>
<p>While Linux console (and XTerm) treat the insert/delete
character/line operations as an erasure, according to more
than one developer with firsthand experience, the omission by
DEC in this summary was intentional: their terminals did not
do this.</p>
</dd>
<dt><tt><em>ri</em></tt>, <tt><em>rin</em></tt>
(<em>nonstandard</em>)</dt>
<dd>
<p>Scrolling the display down is assumed to fill the newly
empty line (at the top of the display) with the background
color.</p>
<p>Again, there is no standard behavior. There are only
design choices and assumptions.</p>
</dd>
<dt><tt><em>csr</em></tt> (<em>nonstandard</em>)</dt>
<dd>
<p>Setting scrolling margins is assumed to limit erasures
(and filling with background color) to those margins.</p>
<p>This is a commonly used feature of XTerm. Vertical
scrolling margins are not the only feature of this sort.
There are also horizontal margins (VT320) and origin mode
(VT100) which can affect the ability to move the
cursor—and erase text. But ncurses does little at
present with those, since (aside from XTerm), most terminal
emulators support those features poorly or not at all.</p>
</dd>
</dl>
<p>The ncurses library for the most part assumes that
<strong>bce</strong> means the particular set of choices made for
Linux console and <a href="/xterm/xterm.html">xterm</a>. Not all
popular terminals match those choices. The standard is silent on
“correct” behavior. There are two ways that ncurses
may handle these differences:</p>
<ol>
<li>
<p>provide a terminal description which omits the specific
capability which differs from the assumption, or</p>
</li>
<li>
<p>in the library itself, be more pessimistic in optimizing
the given capabilities.</p>
</li>
</ol>
<p>The former is preferred, of course. The library should not be
cluttered up with special cases.</p>
<h4 id="no_xterm_color-id"><a name="no_xterm_color" id=
"no_xterm_color">My xterm program doesn't recognize color</a></h4>
<p>Another specific problem lies with the terminfo description
<a href="/xterm/xterm.faq.html#xterm_terminfo">xterm</a>. There
are several xterm- and xterm-like terminfo entries in ncurses'
terminfo database, corresponding to different terminal emulators.
Only one is named “xterm”, and that corresponds to
the standard one. A fresh install of ncurses provides a choice
between the current and previous standard ones:</p>
<dl>
<dt>xterm-new</dt>
<dd>that is based on XFree86 xterm (plus updates since 2006, of
course). See xterm's <a href="/xterm/xterm.log.html">change
log</a> for details.</dd>
<dt>xterm-old</dt>
<dd>This is the same as <code>xterm-r6</code>, e.g., the X11R6
xterm. That program (X11R6 xterm) does not support ANSI text
color.</dd>
</dl>
<p>For either flavor, your packager may have customized the
definitions for backspace and delete to match the conventions of
your system.</p>
<p>A fresh install of xterm on top of ncurses installs its
terminfo entry as “xterm”.</p>
<h4 id="no_colorterm-id"><a name="no_colorterm" id=
"no_colorterm">Why doesn't ncurses use
<code>$COLORTERM</code>?</a></h4>
<p><code>$COLORTERM</code> is an environment variable originally
used by some applications developers who were constructing
programs that run on <code>rxvt</code>, a terminal emulator,
using the <a href="ncurses-slang.html"><code>slang</code></a>
library:</p>
<ul>
<li>
<p>It tells the <code>slang</code> library to ignore the
terminal description, using a set of built-in capability
strings which produce ISO 6429 (aka “ANSI”) color
on that emulator.</p>
<p>The choice of capability strings may work for other
emulators, but in general does not (e.g., terminals which
lack the back color erase capability, such as <a href=
"http://hp.vector.co.jp/authors/VA002416/teraterm.html">Tera
Term</a>, <a href="/xterm/xterm.faq.html#bug_dtterm">CDE
dtterm</a> and <a href=
"/xterm/xterm.faq.html#bug_nxterm">nxterm</a>).</p>
</li>
<li><code>slang</code>'s <a href=
"ncurses-slang.html#env_COLORTERM">documentation</a> does not
give useful information on what values are accepted for the
variable. The only way you will know how to use it is by
reading the source code of the program (or using cut/paste from
someone who did that).</li>
</ul>
<p>Viewed as a fallback, <code>$COLORTERM</code> is perhaps
acceptable (ncurses can be configured with built-in predefined
terminal descriptions), but as a modifier to existing terminal
descriptions it only leads to confusion, since most emulators
that support color differ in minor details from the model which
is supported by <code>slang</code>.</p>
<p>For example, dtterm nominally emulates a DEC vt220. Someone
who knows this, but is also told that it supports color may
(based on the usual misinformation available in newsgroups) try
setting $TERM to “ansi”, “linux” or
<a href="/xterm/xterm.faq.html#xterm_terminfo">"xterm-color"</a>.
(Use <code>infocmp</code> to see why this is uniformly bad
advice). This figure illustrates what goes wrong when following
that advice:</p>
<blockquote>
<p><a href="/lynx/images/slang-white.jpg"><img width="300" src=
"/lynx/images/slang-white.jpg" alt=
"dtterm – incorrect handling of color"></a></p>
</blockquote>
<p>There is a <code>dtterm</code> terminfo entry which provides
correct behavior.</p>
<h4 id="xterm_color-id"><a name="xterm_color" id=
"xterm_color">Why not just use TERM set to "xterm-color"?</a></h4>
<p>ncurses has a terminal description named
<code>xterm-color</code>. Users assume that means it will work
properly for “any” <em>xterm</em>. That is incorrect.
It combines the simplest form of ANSI colors with the older X11R6
xterm. Originally, <code>xterm-color</code> corresponded to the
<em>color_xterm</em> from the mid-1990s. That was superseded by
XFree86 xterm in 1996. That is better than nothing, however using
it in modern xterm (or anything accurately claiming to be
compatible), these problems would occur:</p>
<ul>
<li>
<p>selections from colored backgrounds will add unnecessary
spaces to the pasted text.</p>
</li>
<li>
<p>the function keys do not necessarily match (F1-F4 for
instance), and will be incomplete (for example keys modified
with shift-, control-).</p>
</li>
<li>
<p>scrolling will be noticeably slower.</p>
</li>
<li>
<p>some visual features (flash, hidden cursor) are not
available.</p>
</li>
<li>
<p>it will not work properly in <code>luit</code>.</p>
</li>
</ul>
<p>Some terminal emulators may set this value; however it is
unlikely that any current emulators implement this particular set
of limited features. It is more likely that a more capable
description exists or (given suitable documentation) that one
could be constructed.</p>
<p>For instance, it has been reported that Mac OS X's bundled
terminal emulator uses this value. However, reliable reports of
its actual capabilities say that there are differences, which are
addressed in ncurses as the <code>nsterm</code> entry. In this
case, infocmp shows</p>
<blockquote class="code-block">
<pre style="font-family: monospace; font-size: 10pt;">
comparing xterm-color to nsterm.
comparing booleans.
hs: F:T.
km: T:F.
npc: F:T.
xon: F:T.
comparing numbers.
colors: 8, 16.
ncv: NULL, NULL.
pairs: 64, 256.
wsl: NULL, 50.
comparing strings.
acsc: '``aaffggiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~', '``aaffggjjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~'.
blink: NULL, '\E[5m'.
civis: NULL, '\E[?25l'.
clear: '\E[H\E[2J', '\E[H\E[J'.
cnorm: NULL, '\E[?25h'.
dsl: NULL, '\E]2;\007'.
el1: NULL, '\E[1K'.
enacs: '\E)0', '\E(B\E)0'.
flash: NULL, '\E[?5h$<200/>\E[?5l'.
fsl: NULL, '^G'.
hpa: NULL, '\E[%i%p1%dG'.
ich: NULL, '\E[%p1%d@'.
ich1: NULL, '\E[@'.
invis: NULL, '\E[8m'.
is2: '\E[m\E[?7h\E[4l\E>\E7\E[r\E[?1;3;4;6l\E8', NULL.
ka1: NULL, '\EOq'.
ka3: NULL, '\EOs'.
kb2: NULL, '\EOr'.
kbs: '^H', '\177'.
kc1: NULL, '\EOp'.
kc3: NULL, '\EOn'.
kend: NULL, '\E[F'.
kent: NULL, '\EOM'.
kf1: '\E[11~', '\EOP'.
kf18: '\E[32~', '\E[22~'.
kf2: '\E[12~', '\EOQ'.
kf3: '\E[13~', '\EOR'.
kf4: '\E[14~', '\EOS'.
kfnd: '\E[1~', NULL.
khome: NULL, '\E[H'.
kich1: '\E[2~', NULL.
kmous: '\E[M', NULL.
kslt: '\E[4~', NULL.
meml: '\El', NULL.
memu: '\Em', NULL.
op: '\E[m', '\E[0m'.
rmam: NULL, '\E[?7l'.
rs2: '\E[m\E[?7h\E[4l\E>\E7\E[r\E[?1;3;4;6l\E8', '\E>\E[?3l\E[?4l\E[?5l\E[?7h\E[?8h'.
setab: '\E[4%p1%dm', '\E[%?%p1%{8}%<%t%p1%'('%+%e%p1%{92}%+%;%dm'.
setaf: '\E[3%p1%dm', '\E[%?%p1%{8}%<%t%p1%{30}%+%e%p1%'R'%+%;%dm'.
setb: NULL, '%p1%{8}%/%{6}%*%{4}%+\E[%d%p1%{8}%m%Pa%?%ga%{1}%=%t4%e%ga%{3}%=%t6%e%ga%{4}%=%t1%e%ga%{6}%=%t3%e%ga%d%;m'.
setf: NULL, '%p1%{8}%/%{6}%*%{3}%+\E[%d%p1%{8}%m%Pa%?%ga%{1}%=%t4%e%ga%{3}%=%t6%e%ga%{4}%=%t1%e%ga%{6}%=%t3%e%ga%d%;m'.
sgr: NULL, '\E[0%?%p6%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;7%;%?%p4%t;5%;%?%p7%t;8%;m%?%p9%t\016%e\017%;'.
sgr0: '\E[m', '\E[m\017'.
smam: NULL, '\E[?7h'.
tsl: NULL, '\E]2;'.
vpa: NULL, '\E[%i%p1%dd'.
</pre>
</blockquote>
<p>Additionally, Mac OS X 10.7 is reported to use
<code>xterm-256color</code> as a default <code>$TERM</code>
value. This differs from <code>xterm-color</code> in several
ways, in particular, the support for <a href=
"/xterm/xterm.faq.html#xterm_terminfo">bce</a>. It also differs
from the recommended <code>nsterm-256color</code> (infocmp
reports 111 differences).</p>
<h4 id="xterm_generic-id"><a name="xterm_generic" id=
"xterm_generic">Why not just use TERM set to
“xterm”?</a></h4>
<p>It is easy to find people recommending just setting
<code>$TERM</code> to “xterm”, noting that several
developers have used that as a default value for their terminal
emulators. However, this is usually (except for xterm itself) a
bad idea. The reason that those terminal emulators use
“xterm” is not because they actually match the
behavior, but</p>
<ul>
<li>
<p>it seems too much work to install the correct terminal
definition on each machine (this was the reason given for
rxvt's having done so for several years), or</p>
</li>
<li>
<p>it seems inconvenient to the user to put up with the
absence of a given terminal description when making remote
connections (which pass <code>$TERM</code> to the remote
system).</p>
</li>
</ul>
<p>However, “xterm” refers to a <a href=
"#no_xterm_color">specific</a> terminal emulator. Some of its
details are widely emulated, while others (such as the function
key definitions) are not.</p>
<p>Ncurses has provided accurate descriptions for the different
terminal emulators for many years. While each terminal may
implement escape sequences which are not in the others (<a href=
"/xterm/xterm.faq.html#compare_versions">none</a> implement as
much as half of xterm), what is important for curses applications
is what can be represented in the terminal description. Using
<a href="/ncurses/man/infocmp.1m.html">infocmp</a>, here is the
amount of difference seen by ncurses for commonly used terminal
emulators as of January 2012:</p>
<blockquote>
<table border="1" width="380pt" summary=
"Counting differences from xterm with infocmp">
<caption>
Counting differences from xterm with infocmp
</caption>
<tr>
<th>Description</th>
<th>Count</th>
</tr>
<tr>
<td>ansi (for reference)</td>
<td>137</td>
</tr>
<tr>
<td>konsole</td>
<td>58</td>
</tr>
<tr>
<td>linux</td>
<td>123</td>
</tr>
<tr>
<td>mlterm</td>
<td>59</td>
</tr>
<tr>
<td>nsterm (Apple Terminal)</td>
<td>117</td>
</tr>
<tr>
<td>putty</td>
<td>128</td>
</tr>
<tr>
<td>rxvt</td>
<td>124</td>
</tr>
<tr>
<td>screen</td>
<td>107</td>
</tr>
<tr>
<td>screen.xterm-new</td>
<td>11</td>
</tr>
<tr>
<td>vte (e.g., gnome-terminal)</td>
<td>55</td>
</tr>
<tr>
<td>xterm-color</td>
<td>112</td>
</tr>
<tr>
<td>xterm-new (current standard)</td>
<td>0</td>
</tr>
<tr>
<td>xterm-old (old standard)</td>
<td>115</td>
</tr>
<tr>
<td>vt100 (for reference)</td>
<td>154</td>
</tr>
</table>
</blockquote>
<p>Noting that infocmp lists 182 capabilities for xterm-new,
entries with more than a small number of differences demonstrate
lack of compability of xterm "me-too's" versus xterm itself.</p>
<p>That only covers the features which are in the terminal
description, and does not address differences between terminal
emulators. For example, in <a href=
"terminfo.src.html#t20170729">mid-2017</a>, an update to the
xterm terminal description added the ECMA-48 <code>REP</code>
(repeat character) control. It was part of xterm since January
1997, but a terminal description using the feature was part of
<em>xterm</em> only (not <em>ncurses</em>). After adding it to
ncurses, it was observed that:</p>
<ul>
<li>rxvt is unaffected, since it does not use
<code>TERM=<strong>xterm</strong></code>.</li>
<li>mlterm and OSX Terminal supported <code>REP</code>, using
<code>TERM=<strong>xterm</strong></code>.</li>
<li>VTE, konsole, PuTTY, iTerm2 did not support this standard,
longstanding feature, of <a href="/xterm/xterm.html">xterm</a>
although they set <code>TERM</code> to
<strong><code>xterm</code></strong> or
<strong><code>xterm-256color</code></strong>.</li>
<li>screen and tmux use a different <code>TERM</code> setting,
and seemed to work (although tmux had some other issue with the
test).</li>
</ul>
<p>Here are screenshots showing the problem, on the left correct
and on the right incorrect:</p>
<div style="width: 100%; overflow: hidden;">
<div style="width: 350px; float: left;">
<a href=
"/ncurses/images/picsmap-normal-example.png"><img width="300"
src="/ncurses/images/picsmap-normal-example.png" alt=
"picsmap – normal example using xterm"></a>
</div>
<div style="margin-left: 350px;">
<a href=
"/ncurses/images/picsmap-broken-example.png"><img width="370"
src="/ncurses/images/picsmap-broken-example.png" alt=
"picsmap – broken example using VTE"></a>
</div>
</div>
<h4 id="xterm_256color-id"><a name="xterm_256color" id=
"xterm_256color">Why not make “xterm” equated to
“xterm-256color”?</a></h4>
<p>It breaks things, in more than one way. Seriously, no one
should be asking this question, but see <a href=
"#xterm_generic">Why not just use TERM set to
“xterm”?</a>. Still (writing in mid-October 2012), I
see that the answer is needed.</p>
<p>First, some background is needed:</p>
<ul>
<li>
<p>SVr4 curses supported color terminals, defining names for
the 8 ANSI colors.</p>
</li>
<li>
<p>SVr4 curses used <em>color pairs</em> to reflect
limitations of some hardware terminals which could not render
all possible combinations of color. The color pair value was
a 6-bit field (defined by <code>A_COLOR</code>) in the
<code>chtype</code> values, which allowed for all
combinations of those 8 ANSI colors.</p>
</li>
<li>
<p>PDCurses 2.0 (November 23, 1992) set aside 7 bits for
<code>A_COLOR</code>, but used only 6-bits.</p>
</li>
<li>
<p>ncurses began using an 8-bit field for color pairs
starting (probably) early in 1993, providing for all
combinations of 16-colors (e.g., for CGA displays).</p>
</li>
<li>
<p>X/Open started standardizing and extending curses shortly
after. The result is a hybrid, with most of SVr4 curses
present, but adding a new data-type <code>cchar_t</code> to
hold wide characters. Incidentally, they provided an
alternate way to encode colors. None of the Unix vendors did
anything in this area other than store the same 8 ANSI colors
inside the <code>cchar_t</code>, but they did provide room
for more.</p>
</li>
<li>
<p>At that time (the mid-1990s), it was not apparent how this
additional room might be useful, and in developing ncurses we
simply stored the color in <code>cchar_t</code> in the
attribute member. That allowed only 8 bits (16 colors), just
as in the <code>chtype</code> data.</p>
</li>
<li>
<p>The xterm 256-color feature started with Todd Larason's
patch, which I added in mid-1999 in <a href=
"/xterm/xterm.log.html#xterm_111">patch #111</a>.</p>
</li>
<li>
<p>For the record, <em>ANSI X3.64</em> did not define 256
colors, nor even 16 colors.<br>
Those (256- and 16-colors) are <em>extensions</em> defined by
<strong>xterm</strong> and <strong>aixterm</strong>,
respectively.<br>
There is no such thing as “ANSI 256 colors.” File
that away with “<a href="#vt100_color">VT100
colors</a>.”<br>
An <em>extension</em> is just what it sounds like: something
<em>compatible</em> with, but <em>not part</em> of the
standard.</p>
</li>
<li>
<p>Though we (including Steve Wall's changes for 88-colors)
continued to refine the feature for some time, it was not at
first used much by applications. For instance, though I added
the terminal description to ncurses, it was only partly
supported by ncurses until I added the extended color
features beginning in <a href=
"/ncurses/NEWS.html#t20050101">January, 2005</a>.</p>
</li>
<li>
<p>The ncurses extended color feature added a new structure
member to <code>cchar_t</code> which allows for as many color
pairs as one can store in an integer.</p>
</li>
<li>
<p>The change to <code>cchar_t</code> makes the library no
longer binary compatible with ncurses ABI 5. It is part
of ncurses ABI 6</p>
</li>
<li>
<p>Even with that change, there are several features in the
application interface using 16-bit signed integers, limiting
color pairs to 32767, but allowing 256 colors for practical
purposes.</p>
</li>
</ul>
<p>Here are screenshots showing the ncurses test-program with
extended colors, using menu entry “C”, added in that
time period. The first uses normal-weight text:</p>
<blockquote>
<p><a href="/ncurses/images/ncurses6-256colors.png"><img width=
"300" src="/ncurses/images/ncurses6-256colors.png" alt=
"ncurses – screen from extended-colors tests"></a></p>
</blockquote>
<p>and the second uses bold font:</p>
<blockquote>
<p><a href=
"/ncurses/images/ncurses6-256colors-bold.png"><img width="300"
src="/ncurses/images/ncurses6-256colors-bold.png" alt=
"ncurses – screen from extended-colors tests (bold)"></a></p>
</blockquote>
<p>Other terminal emulators adapted the feature before any
noticeable use by applications. After noticing these and
verifying their behavior, I added corresponding entries to
ncurses' terminfo.src file. Here are relevant changes:</p>
<blockquote>
<table border="1" summary="88/256-color Terminal Descriptions">
<caption>
88/256-color Terminal Descriptions
</caption>
<tr>
<th>Date</th>
<th>Change</th>
</tr>
<tr>
<td>1999/11/27</td>
<td>add xterm-88color, xterm-256color</td>
</tr>
<tr>
<td>2002-06-22</td>
<td>add rxvt-16color, ibm+16color</td>
</tr>
<tr>
<td>2005-01-29</td>
<td>update pairs for xterm-88color and xterm-256color to
reflect the ncurses extended-color support</td>
</tr>
<tr>
<td>2005-02-26</td>
<td>add aixterm-16color to demonstrate 16-color
capability</td>
</tr>
<tr>
<td>2006-02-18</td>
<td>add nsterm-16color entry</td>
</tr>
<tr>
<td>2006-04-22</td>
<td>add xterm+256color building block, and add
gnome-256color, putty-256color, rxvt-256color</td>
</tr>
<tr>
<td>2007-07-14</td>
<td>add konsole-256color entry</td>
</tr>
<tr>
<td>2008-08-23</td>
<td>add Eterm-256color, Eterm-88color, and
rxvt-88color</td>
</tr>
<tr>
<td>2009-10-03</td>
<td>add linux-16color; add ccc and initc capabilities to
xterm-16color</td>
</tr>
<tr>
<td>2010-02-06</td>
<td>add mrxvt-256color</td>
</tr>
<tr>
<td>2010-06-12</td>
<td>add mlterm+256color entry</td>
</tr>
<tr>
<td>2012-03-31</td>
<td>correct order of use-clauses in st-256color</td>
</tr>
<tr>
<td>2012-08-11</td>
<td>add nsterm-256color, make this the default nsterm</td>
</tr>
</table>
</blockquote>
<p>Things started to change around 2005-2006 as you can see by
looking at the dates in the table. <a href=
"https://bugzilla.redhat.com/show_bug.cgi?id=175684">Red Hat
#175684</a> gives some clue, stating that the "next version of
Emacs has support for 256 color terminals". Emacs on the console
by the way uses termcap, not terminfo and certainly not
(n)curses.</p>
<p>I chose to add new entries rather than change xterm (and
others) because they are incompatible. There is more than one
aspect to consider:</p>
<ul>
<li>
<p>some applications on the same machine will blindly attempt
to use all of the colors without being ready to handle more
than 8/16 colors. There was for example more than one
bug-report with Fedora of this type. The symptom was that
text would be invisible (black on black). The bug reports
were eventually closed without correcting the problem.</p>
</li>
<li>
<p>connections to/from remote machines with a different
notion of <em>xterm</em> will behave inconsistently.</p>
</li>
<li>
<p>termcap-style (or the rare terminfo-style) applications on
a given machine are the only ones that can use the -256color
or -88color flavors. But aliasing those to <em>xterm</em>
will break ncurses applications.</p>
</li>
<li>
<p>not all termcap applications will work properly, depending
on what definitions they see for the <code>AF</code> and
<code>AB</code> (or the <code>Sf</code> and <code>Sb</code>)
capabilities. That is because an <em>optimal</em> capability
for these (as provided from ncurses' terminal database) is a
conditional expression—something like this:</p>
<blockquote>
<pre class="code-block">
:AB=\E[%?%p1%{8}%<%t4%p1%d%e%p1%{16}%<%t10%p1%{8}%-%d%e48;5;%p1%d%;m:\
:AF=\E[%?%p1%{8}%<%t3%p1%d%e%p1%{16}%<%t9%p1%{8}%-%d%e38;5;%p1%d%;m:\
</pre>
</blockquote>
<p>Some applications (such as <a href=
"http://vim.wikia.com/wiki/256_colors_in_vim">vim</a>) may
allow (or even embed, hard-coded) the much simpler, but less
efficient variant corresponding to</p>
<blockquote>
<pre class="code-block">
:AB=\E[48;5;%dm:\
:AF=\E[38;5;%dm:\
</pre>
</blockquote>
<p>but doing that on an application-by-application basis is
pointless. If a termcap application uses the ncurses library
to send the escape sequences (using <a href=
"/ncurses/man/curs_termcap.3x.html">tgoto</a>, for example),
it is also redundant, because ncurses will return a usable
terminfo string, and interpret it correctly.</p>
</li>
<li>
<p>there is already a widely-distributed terminal entry with
the desired features. Since it has proven to be inconvenient
to use the <em>xterm-256color</em> name everywhere, renaming
it to <em>xterm</em> will simply shift the problem without
providing a solution.</p>
</li>
<li>
<p>making incompatible changes to a widely-used terminal
description produces bug-reports. I have limited changes of
that type in xterm to describing new features, not changing
existing features. Even with that, there have been complaints
for each change. Consider</p>
<dl>
<dt><em>SGR 22</em>
</dt>
<dd><a href=
"http://www.tomsarazac.com/tom/opinions/xterm-problems.html">
rant by an end-user</a>, <a href=
"/xterm/xterm.log.html#xterm_28">twelve years</a> after the
change in question (viewer discretion advisory). David
Dawes was the first to point out that this change
introduced a problem with remote systems. After some
discussion we decided to keep it.</dd>
<dt><em>Function-key modifiers</em>
</dt>
<dd>In xterm's <a href=
"/xterm/xterm.log.html#xterm_94">patch #94</a> I added
function-key modifiers. In <a href=
"/xterm/xterm.log.html#xterm_167">patch #167</a> I modified
the protocol to address a problem with Emacs (though making
it configurable). In the meantime, KDE and GNOME had copied
the earlier feature into their terminal emulators. Ten
years later, neither had updated to the 2002 version of
xterm's function-keys. There were several reports, the
first that I noticed appeared in Red Hat's system. For
example see <a href=
"https://bugzilla.redhat.com/show_bug.cgi?id=127773">#127773</a>.
<a href=
"https://bugs.launchpad.net/ubuntu/+source/xterm/+bug/96676">
Ubuntu #96676</a> is another example (still unresolved in
2012).</dd>
<dt><em>Meta-mode</em>
</dt>
<dd><a href=
"http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=444250">Debian
#444250</a>. Essentially the problem here was that adding a
flag to the description telling how to enable/disable
xterm's meta mode exposed a differing interpretation of
<a href="#bash_meta_mode">meta mode</a> in bash which dates
back to around 1990.</dd>
</dl>
</li>
</ul>
<p>Although ncurses (starting with release 5.5 in 2005) can be
configured to support 256 colors, it seems that no widespread
distribution was using the extended colors feature (certainly not
Red Hat or Debian). That (and the extended mouse feature) were
the main features for the "ABI 6", which could easily
coexist with the usual "ABI 5" ncurses.</p>
<p>Without widespread use of ABI 6, there was no reason to
change the primary flavor of any of ncurses' terminfo entries to
the -256color or -88color flavor.</p>
<p>In the Debian distribution there was <a href=
"http://lists.debian.org/debian-devel/2008/09/threads.html#00435">
an attempt in 2008</a> on the part of the ncurses package
maintainer to provide a migration path to ABI 6. That effort
died, and (writing in October 2012) did not have a clear
successor.</p>
<p>Just because it is not viable does not prevent others from
assuming it is. For example:</p>
<ul>
<li>
<p><a href=
"http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=230990">Debian
#230990</a> asks for the extended mouse support. It was
opened in February 2004.</p>
</li>
<li>
<p><a href=
"http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=405602">Debian
#405602</a> took 18 months to move the xterm-256color entry
from the ncurses-term to the ncurses-base package in
mid-2008.</p>
</li>
<li>
<p><a href=
"http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=532537">Debian
#532537</a> asks for a change of <em>xterm</em> to
<em>xterm-256color</em>. It was opened in June 2009. As
justification, it stated that "all Debian systems have been
supporting the 256-colour interface for as long as anyone can
remember". The package changelog for xterm states that the
feature was added in January 2006, which when compared with
the Debian release cycle makes it very far from "all Debian
systems".</p>
</li>
<li>
<p>In mid-2012, I noticed that Fedora 18 would have
<em>xterm</em> aliased to <em>xterm-256color</em>.<br>
Some notes are in Fedora's wiki <em><a href=
"http://fedoraproject.org/wiki/Features/256_Color_Terminals">Features/256
Color Terminals</a></em>. However, the proponents of the
change place too much emphasis on just changing it and pay
less attention to the ensuing problems.</p>
</li>
<li>
<p>Even in early 2015, postings such as <em><a href=
"http://stackoverflow.com/questions/13060139/how-can-i-get-more-colors-curses-python-terminal">
How can I get more colors? [Curses] [Python]
[Terminal]</a></em> were common.<br>
As I noted (and because my correction was twice deleted,
promoted it to this FAQ):</p>
<blockquote>
<pre class="code-block">
Not exactly (curses will not do what was indicated). See the ncurses faq: <strong>Why
not make “xterm” equated to "xterm-256color"?</strong>. The terminal database will
return appropriate strings usable by low-level applications, but curses
applications will not use them.
</pre>
</blockquote>
<p>Specifically, this part of the “answer” is
untrue:</p>
<blockquote>
<p class="code-block">If you run your program using
<strong><code>env TERM=xterm-256color
yourprogram</code></strong>, curses will enable 256 colors,
and it will work fine <em>as long as your terminal actually
supports it!</em></p>
</blockquote>
<p>Because (unlike this FAQ), StackExchange postings are
<a href=
"http://www.merriam-webster.com/dictionary/ephemeral">ephemeral</a>,
here also are my followup comments:</p>
<ul>
<li>
<p>In this context, "low-level" applications include any
which do their own screen optimization without using the
curses high-level interface.</p>
</li>
<li>
<p>Urwid has display modules for curses and
“raw”. It uses hard-coded escape sequences in
the latter to provide 256 colors. (If it had used the
terminal database to obtain the escape sequences, I would
call the “raw” interface a low-level
application).</p>
</li>
<li>
<p>The reason why the curses high-level applications do
not display 256 colors is because that requires an ABI
change - making packagers reluctant to introduce it.</p>
</li>
<li>
<p>The mention of “Fabulous” is moot (the
link was dead in early 2015 when this faq was created).
It is unlikely that it can be mixed with ncurses calls;
there has been no discussion on bug-ncurses mailing
list.</p>
</li>
</ul>
</li>
</ul>
<p>Finally (<a href="/ncurses/announce-6.0.html">August
2015</a>), we have ncurses6 (ncurses 6.0). Releasing a new
version is a different matter from getting it accepted and in
wide use. Since packagers have been providing it for some time,
the compatibility issues are of less concern.</p>
<h4><a name="xterm_16MegaColors" id="xterm_16MegaColors">Why only
16 (or 256) colors?</a></h4>
<p>Before getting to the point, some background is needed.</p>
<p>Curses applications run in terminals (or terminal emulators).
They set colors for the screen and parts of it by sending
additional characters (escape sequences) to the screen.</p>
<p>The ANSI standard described 8 colors, did not in any sense
allude to more colors. This is a palette-based set of colors;
there is <a href="/xterm/xterm.faq.html#dont_like_blue">no
standard</a> for how those colors are composed.</p>
<p>A few terminals recognize the <strong>aixterm</strong>
16-color extension (not part of any standard), e.g., xterm
<a href="/xterm/xterm.log.html#xterm_39">patch #39</a>. Again,
there is no agreement between different terminals on the actual
colors used. (While xterm is configurable, some of the others are
not).</p>
<p>Starting with xterm <a href=
"/xterm/xterm.log.html#xterm_111">patch #111</a>, there is the
“<a href=
"terminfo.src.html#tic-xterm-256color">xterm-256color</a>”
terminal type. Using SGR 38 and 48 in an arguably nonstandard
manner (at the time there was no free access to ISO 8613-6),
it provides a predefined palette of 256 colors which can be
modified through escape sequences. With the terminals which
imitate this (none matches xterm's behavior exactly), there are
two problems:</p>
<ul>
<li>
<p>the colors differ</p>
</li>
<li>
<p>the interpretation of the escape sequences is generally
incomplete, e.g., not recognizing the sequences for modifying
the palette or not accepting only one color per escape
sequence.</p>
</li>
</ul>
<p>These deficiencies are well known, easily demonstrated.</p>
<p>Sometime after xterm patch #111, a freely accessible version
of ISO 8613-6 (ITU T.416) was made available. Some
(mostly secondhand) discussion of the ramifications of this is in
KDE <a href=
"https://bugs.kde.org/show_bug.cgi?id=107487">#107487</a>.</p>
<p>A small minority of terminals support an additional
interpretation of SGR 38 and 48 alluded to in ISO 8613-6 as
<em>direct colour</em>. The term “direct colour” has
been interpreted as “24-bit mapping of RGB” (it is an
interpretation, since the ISO standard referenced is not
specific). What the standard actually says is:</p>
<blockquote class="code-block">
<p>The first parameter element indicates a choice between:</p>
<blockquote>
0 implementation defined (only applicable for the character
foreground colour)
<p>1 transparent.</p>
<p>2 direct colour in RGB space.</p>
<p>3 direct colour in CMY space.</p>
<p>4 direct colour in CMYK space.</p>
<p>5 indexed colour.</p>
</blockquote>
<p>...</p>
<p>If the first parameter element has the value 5, then there
is a second parameter element specifying the index into the
colour table given by the attribute “content colour
table” applying to the object with which the content is
associated.</p>
<p>...</p>
<p>If the first parameter element has the value 2, the
parameter elements 3, 4 and 5, are three integers for red,
green, and blue colour components. Parameter 6 has no
meaning.</p>
</blockquote>
<p>There is no “24-bit” in the standard.</p>
<p>As is often the case with the ISO terminal standards, there is
little or no prior art to use as a basis for standardization of
these features. Accordingly, the existing implementations
differ:</p>
<ul>
<li>
<p>ISO 8613-6 prescribes a different syntax than that
used for xterm patch #111.</p>
</li>
<li>
<p>ISO 8613-6 does not specify the “colour
table” it only mentions it.</p>
</li>
<li>
<p>xterm provided a color table, with additional control
sequences for modifying it.</p>
</li>
<li>
<p>Konsole used the xterm syntax for its <em>256-color</em>
(indexed color) and <em>direct color</em> features, as noted
in a <a href=
"https://github.com/KDE/konsole/blob/master/doc/user/README.moreColors">
README</a> file.</p>
<p>The example script, by the way, demonstrates the former
(<em>256-color</em> feature) and was copied/renamed from
xterm's sources, as shown <a href=
"https://github.com/KDE/konsole/commit/f34d82034281a6a2eeef1b1a809f092f72d2b2de#diff-59830ebc3a4184110566bf1a290d08473dfdcbd492ce498b14cd1a5e2fa2e441">
here</a>. As of February 2021, there is still no
corresponding script for <em>direct colour</em> in Konsole's
<a href=
"https://github.com/KDE/konsole/commits/master/tests">source
repository</a>.</p>
<p>The <em>direct color</em> feature was largely ignored for
a few years. There were occasional comments, such as <a href=
"https://groups.google.com/forum/?hl=en#!searchin/vim_use/%22max$20colors$20in$20text$20based$20terminals%22%7csort%3arelevance%7cspell%3atrue/vim_use/RP4iLbpyFNw/yJjhasUWI6AJ">
this mid-2012 thread</a> on the vim-users discussion
group.</p>
</li>
<li>
<p>Some attempts were made by GNOME developers to apply
similar changes to other terminals; no coherent description
was found summarizing the success of that endeavor.</p>
</li>
<li>
<p>After some reflection, I provided in xterm (with <a href=
"/xterm/xterm.log.html#xterm_282">patch #282</a>, September
2012) support for the direct color feature:</p>
<blockquote class="code-block">
<p>modify <code>SGR 38</code> and
<code>SGR 48</code> to accept RGB index, matching the
closest entry in xterm's palette.</p>
</blockquote>
<p>Both that and the earlier 256-color feature are usable
with either the ISO 8613-6 (colon) syntax, or the xterm
patch #111 (semicolon) syntax. While xterm will accept either
syntax indefinitely, the terminal description may change
depending on circumstances:</p>
<ul>
<li>The <a href=
"terminfo.src.html#tic-xterm_256color">xterm+256color</a>
building block is used for <em>legacy</em>
applications</li>
<li>The <a href=
"terminfo.src.html#tic-xterm_256color2">xterm+256color2</a>
building block is used for <em>standard</em>
applications</li>
</ul>
</li>
<li>
<p>On beginning this item (January 2014), none of the other
terminals which I tested accepted the ISO 8613-6 syntax
(there were some <a href=
"https://gitlab.com/gnachman/iterm2/issues/218">unverified</a>
reports).</p>
</li>
<li>
<p>There are other syntax issues. In the changes for xterm
patch #282 (and the earlier KDE changes), no one noticed or
commented on this additional sentence from ISO 8613-6:</p>
<blockquote class="code-block">
<p>If the first parameter element has the value 2, 3, or 4,
the second parameter element specifies a <em>colour space
identifier</em> referring to a colour space definition in
the document profile.</p>
</blockquote>
<p>The ISO document offers no help in deciding what values
that identifier might have or how it might be used, but
omitting it may be a nuisance. Interestingly enough, some
developers <em>copied</em> the feature from xterm while
citing the ISO document as the <em>source</em>.</p>
</li>
</ul>
<p>Konsole's README is not specific (mentioning only
“3-byte RGB color space”), but the current
source-code refers to <strong>truecolor</strong> which is
different from <em>direct color</em>. See for example the
discussion of <a href=
"https://tronche.com/gui/x/xlib/window/visual-types.html">Visual
Types</a> in the X11R5 library documentation (1991):</p>
<blockquote class="code-block">
<ul>
<li>For DirectColor, a pixel value is decomposed into
separate RGB subfields, and each subfield separately indexes
the colormap for the corresponding value. The RGB values can
be changed dynamically.</li>
<li>TrueColor is treated the same way as DirectColor except
that the colormap has predefined, read-only RGB values. These
RGB values are server-dependent but provide linear or
near-linear ramps in each primary.</li>
</ul>
</blockquote>
<p>Using that escape sequence for TrueColor makes it a
non-standard implementation. To be fair, <a href=
"https://bugs.kde.org/show_bug.cgi?id=107487#c22">KDE's 2006
changes</a> to provide 256-colors (and incidentally <em>direct
color</em>) did not hint at TrueColor. That came from other
people. Konsole mentions “truecolor” only in one
place, setting the environment variable <a href=
"#no_colorterm"><code>COLORTERM</code></a> from <a href=
"https://bugs.kde.org/show_bug.cgi?id=371919">KDE #371919</a>,
copying John Davis' magic variable for overriding
<code>TERM</code>, and triggering whatever special feature he has
in mind for s-lang. With one value or another, it (and other
magic variables to amend this) dates back to mid-1995
(rxvt-2.11). Here is the complete documentation in s-lang
mentioning the variable as of February 2017:</p>
<blockquote>
<pre class="code-block">
Of course not all terminals are color terminals. If the S-Lang global
variable SLtt_Use_Ansi_Colors is non-zero, the terminal is assumed to
be a color terminal. The SLtt_get_terminfo will try to determine
whether or not the terminal supports colors and set this variable
accordingly. It does this by looking for the capability in the
terminfo/termcap database. Unfortunately many Unix databases lack this
information and so the SLtt_get_terminfo routine will check whether or
not the environment variable <strong>COLORTERM</strong> exists. If it exists, the
terminal will be assumed to support ANSI colors and
SLtt_Use_Ansi_Colors will be set to one. Nevertheless, the
application should provide some other mechanism to set this variable,
e.g., via a command line parameter.
</pre>
</blockquote>
<p>Beyond the issue of escape sequences, konsole and xterm use
different library calls for implementing <em>direct color</em>.
This makes no difference to an application which might use those
escape sequences, but bears some comment:</p>
<ul>
<li>
<p>konsole uses <strong>Qt</strong>. In its source code (see
<a href=
"https://projects.kde.org/projects/kde/applications/konsole/repository">
KDE repository</a>), it stores the color information in a
<a href=
"http://qt-project.org/doc/qt-5.0/qtgui/qcolor.html">QColor</a>
class. The documentation mentions</p>
<blockquote class="code-block">
<p>QColor is platform and device independent. The QColormap
class maps the color to the hardware.</p>
</blockquote>
<p>Because konsole's source code does not refer explicitly to
QColormap, it relies on default behavior of the class.<br>
The documentation for <a href=
"http://qt-project.org/doc/qt-5.0/qtwidgets/qcolormap.html">QColormap</a>
gives half a clue, in its comment about modes. Qt's
documentation is vague in many respects (in sharp contrast to
MSDN), leaving developers no recourse other than reading its
source code.</p>
<p>Here is a starting point: <a href=
"https://code.qt.io/cgit/qt/qt.git/tree/src/gui/painting">Qt
4.8 src/gui/painting</a>.</p>
</li>
<li>
<p>In the 4.8 branch, we find that the QColormap class
<a href=
"https://code.qt.io/cgit/qt/qt.git/tree/src/gui/painting/qcolormap_x11.cpp">
for X11</a> was doing essentially what xterm does, i.e.,
color maps.</p>
</li>
<li>
<p>The <em>5.0</em> source (still in development at the time
the <em>vim_use</em> discussion took place—released 6
months later), supported 256 colors as seen in <a href=
"https://code.qt.io/cgit/qt/qtbase.git/tree/src/widgets/util/qcolormap.cpp?id=f128c1f6d3cbdc1aa13f9ec65fd2354ef91c1c48">
QColormap</a>. Beginning in <a href=
"https://code.qt.io/cgit/qt/qtbase.git/commit/src/widgets/util/qcolormap.cpp?id=51d4eb8f5ba769cd50457b2f479acc3f30b9f78f">
March 2014</a>, the class initialization distinguishes
between 24-bit and 8-bit color. The X11-relevant details have
been moved away from this class.</p>
</li>
<li>
<p>Distinguishing between 8-bit and 24-bit color is a useful
simplification for X11, since it trades off between storing
an 8-bit value in one of the columns for the R/G/B structure
versus storing three 8-bit values.</p>
<p>XTerm checks for this special case to allow exact color
matches. Otherwise, it uses the closest color match.</p>
</li>
<li>
<p>Because xterm allows the application to set the palette
which is used for either style of color (256-color or
direct), providing “lot of colors” would have
been pointless.</p>
</li>
<li>
<p>Konsole has no provision for modifying the palette, in
either case.</p>
</li>
</ul>
<p>The implication of the <em>direct colour</em> feature is
“lots of colors”. On the surface, that may seem
attractive. However, there are several considerations:</p>
<ul>
<li>who will use it?</li>
<li>how will they use it?</li>
<li>when will they use it?</li>
<li>where will they use it?</li>
<li>how many colors do they need?</li>
<li>what are the performance tradeoffs?</li>
</ul>
<p>To answer the question, bear in mind that this is an area of
special interest to only a handful of developers. End-users read
“16 million colors” and uncritically accept arguments
that they can effectively use this. However, there are only (at
most) a few thousand characters on a terminal's screen at a time.
That number of colors exceeds by a couple of orders of magnitude
the ability of anyone to discern the differences and rely on
those distinctions to aid them in viewing text.</p>
<p id="emacs-24bit-hack">Moving past the first couple of points,
the availability of <em>direct color</em> depends on how the
application uses the information. As a <strong>terminfo</strong>
description, that works for applications which use the terminal
database directly. The principal ones which come to mind are text
editors (emacs and vi-clones). Generally their developers have
chosen to make their task more difficult by remaining with
<strong>termcap</strong> (which cannot express the relevant
escape sequences). So they incorporate some hard-coded behavior.
For instance, in a change to emacs in <a href=
"http://git.savannah.gnu.org/cgit/emacs.git/commit/?id=e463e5762bbe628be3d15da066a90f079a8468b3">
February 2017</a>, the developer</p>
<ul>
<li>used the ncurses user-defined capability feature to define
single-parameter strings named <code>setf24</code> and
<code>setb24</code> which transform the parameter into the
three parameters needed for direct color, and</li>
<li>because emacs uses termcap and normally cannot read those,
the developer added a call to the terminfo function <a href=
"man/curs_terminfo.3x.html"><code>tigetstr</code></a> (which
probably only works with ncurses, since only the <a href=
"man/curs_termcap.3x.html"><em>termcap</em></a> interface is
initialized) to get the information, and</li>
<li>if successful, replaces the capability read from termcap
for normal coloring, and</li>
<li>passes the result to the emacs-specific <a href=
"https://github.com/emacs-mirror/emacs/blob/master/src/tparam.c">
tparam</a> (which by the way accepts four parameters which
could have been used for R/G/B as most developers would
expect).</li>
</ul>
<p>Working through these obstacles, it is possible to
“use” termcap to provide “lots of colors”
without affecting the ncurses library. Termcap applications do
not use much of ncurses; nor do their developers contribute
significantly to ncurses. The emacs workaround was unsuitable for
ncurses because emacs interprets the data in its own way, and
displays the result independently of ncurses.</p>
<p>Some mailing-list comments indicate that the existing
capabilities are not well-understood by developers, e.g., this
discussion in <a href=
"https://lists.gnu.org/archive/html/bug-ncurses/2013-10/msg00007.html">
October 2013</a>. Taking the discussion into account, consider
the <a href="/ncurses/terminfo.src.html#tic-linux-c">linux-c</a>
terminal description dating from 1996. That sets up a palette
using a color index value mapped to R/G/B components. Other
longstanding uses in ncurses include these:</p>
<blockquote>
<p><a href=
"/ncurses/terminfo.src.html#tic-linux-c-nc">linux-c-nc</a>,
<a href="/ncurses/terminfo.src.html#tic-putty">putty</a>,
<a href=
"/ncurses/terminfo.src.html#tic-xterm-16color">xterm-16color</a>,
and <a href=
"/ncurses/terminfo.src.html#tic-xterm_256color">xterm+256color</a></p>
</blockquote>
<p>Some additional comments on mapping colors using
<code>initc</code> and <code>initp</code> are found in <a href=
"http://lists.schmorp.de/pipermail/rxvt-unicode/2013q3/thread.html#1826">
this discussion</a>.</p>
<p>Applications which <em>use</em> ncurses are a different
matter. Unlike termcap applications, curses libraries (and
analogous ones such as s-lang) use combinations of the terminal
capabilities to allow their applications to work on a wide
variety of terminals. There are a few limitations, due to the
early implementation of terminfo:</p>
<ul>
<li>
<p>4096 size-limit on compiled entries</p>
</li>
<li>
<p>16-bit limit for numbers (to keep them small), which are
all <em>signed</em> values</p>
</li>
<li>
<p>Because some terminal types did not provide a way to set
foreground and background colors independently, the concept
of <em>color pairs</em> was introduced.</p>
</li>
</ul>
<p>Using the ncurses 5 ABI, you have available 16 colors, or 256
pairs of colors. Using the ncurses 6 ABI, you <a href=
"#xterm_256color">have</a> 256 colors, or 32767 pairs (the limit
for a signed 16-bit number). That limit is good enough for
realistic applications, which could not have that many character
cells on a screen simultaneously (unless of course, using 1-pixel
fonts to pretend to draw <em>graphics</em>, e.g., <a href=
"http://aa-project.sourceforge.net/aalib/">AA-lib</a>). Since
ncurses is used to draw <em>text</em>, that is not a valid
issue.</p>
<p>S-lang does not implement color-pairs (or <a href=
"#need_padding">padding</a>, etc.), However (reading the source
code), it also is limited by the terminal descriptions, using a
maximum color index value 32767 (<em>15</em>-bits—signed
short). No method for changing 15 into 24 was noted in <a href=
"http://lists.jedsoft.org/lists/slang-users/2014/index.html#00002">
this discussion</a>. However, that led to a bug report with a
<a href=
"http://www.midnight-commander.org/attachment/ticket/3145/slang-truecolor-demo.patch">
patch</a> which <a href=
"http://www.midnight-commander.org/ticket/3145#comment:11">isn't</a>
fully “ABI compatible”. John Davis was able to work
around the obvious problems in this patch by splitting up the
extended color field to use some space in his library's data
structure. Otherwise, users would have had to recompile their
applications to use the library, since the patch altered these
features of the interface:</p>
<blockquote>
<pre class="code-block">
#define SLTT_BOLD_MASK 0x01000000UL
#define SLTT_BLINK_MASK 0x02000000UL
#define SLTT_ULINE_MASK 0x04000000UL
#define SLTT_REV_MASK 0x08000000UL
#define SLTT_ALTC_MASK 0x10000000UL
#define SLTT_ITALIC_MASK 0x20000000UL
</pre>
</blockquote>
<p>If you read the <a href=
"http://www.jedsoft.org/snapshots/">source code</a>, you will see
that he did not solve the problem of changing 15 into 24 (as of
February 2017, it still used a signed 16-bit limit for the number
of colors).</p>
<p>No matter how one uses the limits based on the terminal
database, scaling is needed to map onto the actual device.</p>
<p>Bypassing the limits which can be derived from the terminal
database (and veering off into the swamp of hard-coded behavior),
the idle spectator might ask “why not add a special ad hoc
interface to (somehow) just do it?” One of VTE's developers
asked for that (see mailing list thread from <a href=
"http://lists.gnu.org/archive/html/bug-ncurses/2014-01/msg00010.html">
January 2014</a>).</p>
<p>The problem is that you cannot “just do
it”—both ncurses and <a href=
"http://www.jedsoft.org/slang/">s-lang</a> do optimization to
address their legitimate users (those who are using the superior
performance due to working with characters, especially via remote
connections). They have longstanding APIs which expose some of
the related information. Adding an ad hoc interface will either
break compatibility, or require duplicating information. Either
way, most of the existing users would be adversely affected.</p>
<p>Some hint of this is given in GNOME <a href=
"https://bugzilla.gnome.org/show_bug.cgi?id=704449#c29">#704449</a>.
Given the source of the comment, the effect is understandably
understated. The usual reason given for wanting this feature has
been for making pretty color schemes for text editors (e.g.,
<a href=
"http://www.vimninjas.com/2012/08/26/10-vim-color-schemes-you-need-to-own/">
this</a> and <a href=
"http://stackoverflow.com/questions/16711226/to-fix-the-color-in-vim-or-to-take-the-plunge">
this</a>).</p>
<p>More generally, the way to “solve” the problem
would be to abandon compatibility with <a href=
"https://www2.opengroup.org/ogsys/catalog/C094">X/Open
Curses</a>, using <strong><code>int</code></strong> where
<strong><code>short</code></strong> is now used, and provide a
new (incompatible) terminal database format to store bigger
numbers. Incidentally, this would break applications which use
the existing terminal database format, such as <a href=
"http://www.jedsoft.org/slang/">s-lang</a>.</p>
<p>This extended item was prompted by an advertisement <a href=
"http://lists.gnu.org/archive/html/bug-ncurses/2014-01/msg00008.html">
early in 2014</a> posted to the ncurses mailing list. That was
while I was working on <a href="ncurses-mapsyms.html">versioned
symbols</a>, needed to gain packager's acceptance for <a href=
"announce-6.0.html">ncurses6</a>. A hypothetical <em>future</em>
release aimed solely at providing “lots of colors”
could do each of the items mentioned in the previous paragraph.
But it had no place in the ncurses6 plan, which required only
recompiles, no source-changes.</p>
<p>Beginning with a fallacious premise (using a source <a href=
"#misinfo-ansiseq">known</a> to be erroneous), its authors (the
two individuals mentioned in <a href=
"http://lists.gnu.org/archive/html/bug-ncurses/2014-01/msg00010.html">
this thread</a>) <em>selected</em> specific instances in an
attempt to persuade the reader that a majority of terminals
implement TrueColor (“16 million colors”), and has a
discussion page devoted to expanding this:</p>
<ul>
<li>
<p>Several entries (such as <a href=
"http://worldwidemann.com/finally-terminated/">FinalTerm</a>)
are bogus.</p>
</li>
<li>Some others involve a stretch, e.g., suggesting that the
existence of some <em>patch</em> for PuTTY is going to make it
do 24-bit colors for <em>you</em>.</li>
<li>
<p>All of the VTE-based terminals are listed as if they were
independent. Presenting the information this way makes it
(perhaps) more convincing. Certainly, if you get to vote as
many times as you choose, you can win any dispute.</p>
</li>
</ul>
<p>Much of the discussion on the page is in the same vein, e.g.,
talking about <em>standards</em>, while at the same time
<em>discarding</em> the technical details of ITU T.416 and
ECMA-48 which began this story.</p>
<p>Besides the discussion on that page, there are several related
items such as <a href=
"https://bugs.kde.org/show_bug.cgi?id=371919">KDE #371919</a>,
repeating some of the invented facts from that page, e.g.,</p>
<blockquote class="code-block">
<p>Unfortunately the maintainer of ncurses and terminfo is not
interested at all in adding this possibility to terminfo, see
e.g.
https://lists.gnu.org/archive/html/bug-ncurses/2016-08/msg00036.html.</p>
</blockquote>
<p>After the release of ncurses 6.1, the page's authors made
minor, but not substantiative changes. In contrast, the changes
made for <a href="announce-6.1.html">ncurses 6.1</a> to implement
and integrate extended numbers (and colors) took about a year to
develop (see <a href="ncurses-6.0-20170218-to-6.1.html">this
page</a> for the full <em>diffstat</em>):</p>
<blockquote>
<pre class="code-block">
# 602 files changed, 54948 insertions(+), 35233 deletions(-)
</pre>
</blockquote>
<p>Those people are not contributors to ncurses. While comments
are useful (sometimes) none of it was written by them.</p>
<p>Without significant revision, there is nothing more to
discuss.</p>
<h4 id="white_black-id"><a name="white_black" id=
"white_black">Ncurses resets my colors to white/black</a></h4>
<p>This is the way SVr4 curses works. From the XSI Curses
specification</p>
<blockquote class="code-block">
<p>The start_color() function also restores the colors on the
terminal to terminal-specific initial values. The initial
background color is assumed to be black for all terminals.</p>
</blockquote>
<p>If your terminal description does not contain the
<code>orig_pair</code> or <code>orig_colors</code> capability,
you will be unable to reset colors to the pre-curses state. This
happens, for example, with <code>aixterm</code>.</p>
<p>However, if your terminal does support resetting colors to a
default state, ncurses will use this when exiting Curses mode.
Terminal types that do this include the Linux console,
<code>rxvt</code> and the XFree86 <code>xterm</code>.</p>
<p>Ncurses 4.1 provides an extension
<code>use_default_colors()</code> which allows an application
running on a terminal which supports resetting colors to mix the
default foreground and background colors with the 8 defined
curses colors.</p>
<h4 id="interchanged_colors-id"><a name="interchanged_colors" id=
"interchanged_colors">Why are red/blue interchanged?</a></h4>
<p>You may notice if you are porting an application from SVr4
curses to ncurses (or the other way), that some versions of
ncurses have some pairs of colors interchanged with respect to
SVr4 curses. This is a bug in ncurses (sorry). Someone made an
error translating terminal descriptions, and confused the
setaf/setab terminal capabilities with the setf/setb
capabilities.</p>
<p>The 8 colors black, red, green, yellow, blue, magenta, cyan,
white are coded in the ANSI (setaf/setab) convention with red=1,
green=2 and blue=4, while the older (setf/setb) uses red=4,
green=2 and blue=1. SVr4 curses accommodates either,
interchanging colors in the setf/setb to match the setaf/setab
style. Ncurses' terminfo database incorrectly renamed the
setaf/setab capabilities to setf/setb, making it incompatible
with the SVr4 curses library.</p>
<p>This was corrected in ncurses 4.1, but incorrect in all
preceding versions.</p>
<h3 id="problems_display-id"><a name="problems_display" id=
"problems_display">Other Display Problems</a></h3>
<h4 id="no_line_drawing-id"><a name="no_line_drawing" id=
"no_line_drawing">Line-drawing characters come out as x's and
q's</a></h4>
<p>The x's and q's correspond to a table (from terminfo/termcap)
which tells ncurses how to map the “alternate”
character set to the terminal's set of graphic characters. The
reference for this table comes from the vt100. If the unmapped
characters appear, then the terminal emulator does not recognize
the escape sequence for switching between normal and alternate
fonts that is given in the terminfo description.</p>
<p>There are several cases of note:</p>
<ul>
<li>
<p>Terminal emulators which use a different escape sequence
or different range for mapping the resulting characters. For
instance the so-called vt100-compatibles such as Linux
console and Tera Term.</p>
</li>
<li>
<p>Terminal emulators which are locale-sensitive. Again,
Linux console is a problem area when running in UTF-8 mode,
since its nominal vt100-compatibility is further lessened by
ignoring the escape sequences dealing with fonts. The
<code>screen</code> utility also has the same problem;
whether to make the implementation simple or to copy the
Linux console. It ignores vt100-style font switching when the
locale is a UTF-8 flavor.</p>
</li>
<li>
<p>If you happen to be using Solaris, it is often configured
to prefer its terminal database to ncurses, even when ncurses
is installed. However, its terminal description for xterm
omits the <code>enacs</code> which is used to enable
line-drawing. This does not work well with applications such
as <code>screen</code> and <code>luit</code>.</p>
</li>
</ul>
<p>For the first case, you simply have to find the correct
terminfo description. Fixing the latter is harder, since the
damage is done outside ncurses. (Though one can easily make
things compatible enough that this particular issue would never
appear, that style of solution is not deemed proper by some
coders).</p>
<p>The normal ncurses libraries support 8-bit characters. The
ncurses library can also be configured
(<code>--enable-widec</code>) to support wide-characters (for
instance Unicode and the UTF-8 encoding). The corresponding
wide-character <code>ncursesw</code> libraries are
source-compatible with the normal applications. That is,
applications must be compiled and linked against the
<code>ncursesw</code> library.</p>
<p>The ncurses 5.3 release provides UTF-8 support. The special
cases of Linux console and <code>screen</code> were addressed in
development patches completed at the end of 2002.</p>
<h4 id="bad_line_drawing-id"><a name="bad_line_drawing" id=
"bad_line_drawing">Line-drawing characters come out as Latin-1
characters</a></h4>
<p>Those capital A's with dots on top. Yes, that is almost always
a mismatch with the terminfo description.</p>
<p>There are some special cases such as Tera Term which are
related to the font.</p>
<h4 id="utf8_line_drawing-id"><a name="utf8_line_drawing" id=
"utf8_line_drawing">Line-drawing characters do not appear</a></h4>
<p>There is no character at all where the line-drawing should
appear, and other characters may be shifted around the screen.
This may happen on the Linux console, but also on some other
terminal emulators. The line-drawing characters do not appear
because the terminal emulator is treating them as illegal
characters.</p>
<p>ncurses starts by assuming that the terminfo is correct, and
overrides it for some special cases which are known to misbehave.
See the discussion of <code>NCURSES_NO_UTF8_ACS</code> in the
ncurses manpage for details.</p>
<h4 id="emacs_cvvis-id"><a name="emacs_cvvis" id=
"emacs_cvvis">Why does my cursor blink in Emacs?</a></h4>
<p>Depending on Emacs, or other programs, the answer differs.
Most often this question is raised by people using the Linux
console.</p>
<p>There are three capabilities defined in terminfo which affect
the cursor:</p>
<blockquote>
<table border="1" summary="Terminfo Cursor Capabilities">
<caption>
Terminfo Cursor Capabilities
</caption>
<tr>
<th>Full name</th>
<th>Terminfo</th>
<th>Termcap</th>
<th>Description</th>
</tr>
<tr>
<td>cursor_invisible</td>
<td>civis</td>
<td>vi</td>
<td>make cursor invisible</td>
</tr>
<tr>
<td>cursor_normal</td>
<td>cnorm</td>
<td>ve</td>
<td>make cursor appear normal (undo civis/cvvis)</td>
</tr>
<tr>
<td>cursor_visible</td>
<td>cvvis</td>
<td>vs</td>
<td>make cursor very visible</td>
</tr>
</table>
</blockquote>
<p>The three capabilities appear in the terminfo database 128,
178 and 103 times respectively. Some of those terminfo entries
are building blocks. For the entries reported by <a href=
"/ncurses/man/toe.1m.html">toe</a>, there are 670 which modify
the cursor, out of 1629 entries. Some of these allow only between
invisible/normal or normal/visible. There are 159 which allow all
three possibilities, as well as 27 which allow only one
choice.</p>
<p>The cursor blinks because the application (Emacs for instance)
uses the <code>cvvis</code> capability. “Very
visible” for a terminal cursor generally means that it
blinks. Various tradeoffs are possible, depending on the terminal
between underline, block, blinking.</p>
<p>Applications modify the cursor either via <a href=
"/ncurses/man/curs_kernel.3x.html">curs_set</a> (in ncurses) or
by sending the appropriate escape sequence to the terminal using
termcap or terminfo calls. While <code>curs_set</code> refrains
from substituting one escape sequence for another missing one,
this is not true of termcap/terminfo applications. Frequently
they replace a missing <code>cvvis</code> with an available
<code>cnorm</code>. After a while, the programmers forget the
difference, and surprise their users when someone upgrades a
terminal description.</p>
<p>The Linux console tie-in happened with ncurses <a href=
"terminfo.src.html#t19990703">in 1999</a>, by adding
<code>cvvis</code> to the “linux” terminal
description.</p>
<p>Outside of Emacs, the replacement of a missing
<code>cvvis</code> with <code>cnorm</code> is the most common
cause of surprise.</p>
<p>But Emacs is different. It intentionally uses the <em>"very
visible" blinking cursor</em> by default. There is documentation
<a href=
"http://www.gnu.org/software/emacs/manual/html_node/emacs/Cursor-Display.html">
here</a>. The earliest available version of <a href=
"http://git.savannah.gnu.org/cgit/emacs.git/log/src/term.c">the
code</a> from 1991 uses <code>TS_visual_mode</code> in this
way.</p>
<h4><a name="multithread" id="multithread">Why does (fill in the
blank) happen when I use two threads?</a></h4>
<p>If you have a program which uses curses in more than one
thread, you will almost certainly see odd behavior. That is
because curses relies upon static variables for both input and
output. Using one thread for input and other(s) for output cannot
solve the problem, nor can extra screen updates help. This FAQ is
not a tutorial on threaded programming.</p>
<p>Starting with <a href="announce-5.7.html">ncurses 5.7</a>,
this implementation of curses provides the ability to configure
and compile the library to help solve the problem by:</p>
<ul>
<li>
<p>reducing the use of static variables (see <a href=
"/ncurses/man/curs_sp_funcs.3x.html">curs_sp_funcs(3x)</a>),</p>
</li>
<li>
<p>adding mutexes around the low-level terminal I/O,</p>
</li>
<li>
<p>changing global variables such as <code>LINES</code> to
“getter” functions (see <a href=
"/ncurses/man/curs_opaque.3x.html">curs_opaque(3x)</a>,
and</p>
</li>
<li>
<p>adding functions which an application can use to avoid
those which rely upon global (or static) variables (see
<a href=
"/ncurses/man/curs_threads.3x.html">curs_threads(3x)</a>.</p>
</li>
</ul>
<p>Almost all programs can be recompiled to use the
“ncursest” or “ncursestw” libraries. Just
recompiling is not enough to make a program thread-safe. As
usual, some (re)design effort is probably needed.</p>
<p>The test-programs provided with ncurses (<a href=
"/ncurses/ncurses-examples.html">ncurses-examples</a>) include a
few which demonstrate this alternate configuration of the
library: ditto, rain, worm.</p>
<h3 id="problems_keyboard-id"><a name="problems_keyboard" id=
"problems_keyboard">Keyboard Problems</a></h3>
<h4 id="cursor_appmode-id"><a name="cursor_appmode" id=
"cursor_appmode">My cursor keys do not work</a></h4>
<p>For instance, you may press the up-arrow and see
“OA” or “[A”, rather than having your
program recognize the up-arrow.</p>
<p>The terminal description may be incorrect, or the program may
not be making proper use of it. ncurses (and other programs which
use terminal descriptions) simply match the characters sent by
the terminal against a list of strings defined in the terminal
description.</p>
<p>vt100's can send different strings for cursor-keys (and
keypad-keys) depending on how they are initialized. Terminal
emulations which provide vt100 functionality behave the same way.
There are two modes:</p>
<dl>
<dt><em>normal mode</em>
</dt>
<dd>This corresponds to the power-up state of the terminal.
Cursor keys send escape sequences (strings beginning with the
ASCII escape character) that mimic cursor-movement control
sequences. Those begin with <code>escape [</code>. An
up-arrow is <code>escape [ A</code> (also expressed
as <code>CSI A</code>.</dd>
<dt><em>application mode</em>
</dt>
<dd>This is the programmed mode of the terminal. Cursor keys
send escape sequences that can be easily distinguished from
cursor-movement control sequences. Those begin with
<code>escape O</code>. An up-arrow is
<code>escape O A</code> (also expressed as
<code>SS3 A</code>.</dd>
</dl>
<p>The terminal description describes only one mode. Usually that
is the application mode.</p>
<p>The terminal description tells how to initialize the terminal,
e.g., to make the cursor-keys send application mode escape
sequences:</p>
<ul>
<li>Long ago, when there were many types of terminals in use,
some would send nothing for special keys unless the terminal
was initialized in this way.</li>
<li>Other terminals could move the cursor in <em>local</em>
mode (not sending anything to the host computer).</li>
<li>Finally, there were some which would send
<em>cursor-movement</em> sequences unless initialized.</li>
</ul>
<p>To accommodate all types of terminals, the convention was that
a program would initialize the cursor keys when it needed them,
i.e., to use the programmed mode of the terminal. That works well
for full-screen programs. Terminal descriptions (usually)
describe the application mode for this reason.</p>
<p>This convention does not work well for command-line programs,
which do not initialize the terminal. Keys which differ between
normal and application modes are not available for programs which
do not initialize the terminal.</p>
<p>For example, the <code>readline</code> library (which was
originally hardcoded, and did not use termcap or terminfo),
exploited the feature of vt100's that their cursor-keys transmit
something in normal mode.</p>
<p>The <code>readline</code> library (which is used by
<code>bash</code>) did this for several years before someone
connected it to a termcap library. Around that point, someone
made a terminal description for the Linux console which
“solved” the problem of initializing the terminal for
<code>bash</code> by not initializing it at all. Cursor keys
always send normal-mode strings with this arrangement.</p>
<p>Granted, that works—provided that the terminal is
initialized consistently. If your terminal happens to
“solve” the problem in a different way, e.g., by
starting in application mode, and if your environment sets
<code>TERM</code> to “linux”, you may have problems
with your cursor-keys.</p>
<h4 id="bash_meta_mode-id"><a name="bash_meta_mode" id=
"bash_meta_mode">Alt-keys do not work in bash</a></h4>
<p>Depending on the application, users expect an
“alt” key to do one of two things:</p>
<ul>
<li>
<p>send an escape character before special keys such as
cursor-keys, or</p>
</li>
<li>
<p>act as an extended shift, allowing you to enter codes for
Latin-1 values from 160 to 255.</p>
</li>
</ul>
<p>xterm supports both features, e.g., with the
<code>eightBitInput</code> and related resources.</p>
<p>Bash users have an extra problem in xterm when using a recent
terminal description (since <a href=
"/xterm/xterm.log.html#xterm_216">xterm patch #216</a>). For
completeness, I noted in the terminal description how an
application can set/reset “meta” mode. It turns out
that bash turns on meta mode if it is available. It is not an
optional feature in bash; bash's developers assumed that you
would use it. That is an odd assumption, since the feature is
rarely implemented. There are (counting xterm) only three
terminal descriptions in ncurses' terminal database providing
this (the low-level blocks for Ann Arbor, SCO, and XTerm).</p>
<p>Making it configurable was proposed in <a href=
"https://bugzilla.novell.com/show_bug.cgi?id=541379">this bug
report</a>. Earlier, bash's maintainer had <a href=
"http://lists.gnu.org/archive/html/bug-ncurses/2007-04/msg00012.html">
expressed reluctance</a> to address the issue. However, bash 4.1
added an "enable-meta-key" feature, dated 9 October 2009. That
makes it possible for users to disable it.</p>
<h4 id="home_end_keys-id"><a name="home_end_keys" id=
"home_end_keys">My home/end keys do not work</a></h4>
<p>This is usually due to an incorrect terminal description. When
it is not, it is due to the terminal emulator itself.</p>
<p>Application developers tend to hardcode references in their
programs to the “home” and “end” key,
forgetting that the presence of any particular function key
depends on the terminal.</p>
<p>Part of the problem with terminal descriptions is due to the
way xterm's terminal descriptions are used in ncurses. Because
xterm emulates a VT220, the terminal descriptions provided with
it follows the DEC keyboard convention, which does not provide
home/end keys. Rather, it provides find/select keys. See for
example the discussion of <a href=
"/xterm/xterm.faq.html#how2_fkeys">function keys</a> and <a href=
"/xterm/xterm.faq.html#xterm_keypad">keypad</a>.</p>
<p>On the other hand, the descriptions in ncurses reflect the Sun
and PC keyboards which many people use. They define home/end keys
for xterm.</p>
<p>However, some packagers for ncurses have pasted xterm's
terminfo descriptions into the ncurses distribution. The effect
is to remove the home/end key definitions from ncurses.</p>
<p>The problem is easily fixed by ignoring the packager's
improvements and reinstalling the ncurses terminfo database.
<a href="#which_terminfo">This section tells where to get
it.</a></p>
<h4 id="modified_keys-id"><a name="modified_keys" id=
"modified_keys">How can I use shift- or control-modifiers?</a></h4>
<p>The standard response is "curses doesn't do that".</p>
<p>There are workarounds. Some explanation is needed first.</p>
<p>Most implementations of curses work with terminals that use
serial communication. Generally those were inexpensive. Adding
keys to the keyboard was probably less expensive than adding
logic to handle different types of modifiers (such as shift).
Terminals that could send different types of modifiers used to be
rare.</p>
<p>However, the IBM PC provided a widely available platform with
a keyboard that could provide modifier information. On the other
hand, there was no standard protocol for sending the information
on a serial line.</p>
<p>Most of the activity in exploiting this platform consisted of
ad hoc implementations for computer consoles, such as for SCO,
OS/2, etc., which associated the control-, shift- and alt-key
modifiers with function-key numbering. That is, rather than
attempting to extract information on the modifiers from function
key expressed as a character string, the various combinations are
numbered (using function-key number, multiplied by a code
corresponding to the modifiers) and associated with the numbered
function keys in the termcap/terminfo description.</p>
<p>For example, the <code>scoansi</code> description encodes the
modifiers by an arbitrary sequence from the possible final
characters for an ANSI control, e.g.,</p>
<blockquote class="code-block">
<dl>
<dt>normal <!--{{atr2html--></dt>
<dd style="font-family: monospace; font-size: 10pt;">
<span class="keyword">kf1</span>=<span class=
"literal">\E[M</span>, <span class=
"keyword">kf10</span>=<span class=
"literal">\E[V</span>, <span class=
"keyword">kf11</span>=<span class=
"literal">\E[W</span>, <span class=
"keyword">kf12</span>=<span class=
"literal">\E[X</span>, <span class=
"keyword">kf2</span>=<span class="literal">\E[N</span>,<br>
<span class="keyword">kf3</span>=<span class=
"literal">\E[O</span>, <span class=
"keyword">kf4</span>=<span class=
"literal">\E[P</span>, <span class=
"keyword">kf5</span>=<span class=
"literal">\E[Q</span>, <span class=
"keyword">kf6</span>=<span class=
"literal">\E[R</span>, <span class=
"keyword">kf7</span>=<span class=
"literal">\E[S</span>, <span class=
"keyword">kf8</span>=<span class="literal">\E[T</span>,<br>
<span class="keyword">kf9</span>=<span class=
"literal">\E[U</span>,<br>
<!--atr2html}}--></dd>
<dt>F13-F24 are shifted F1-F12 <!--{{atr2html--></dt>
<dd style="font-family: monospace; font-size: 10pt;">
<span class="keyword">kf13</span>=<span class=
"literal">\E[Y</span>, <span class=
"keyword">kf15</span>=<span class=
"literal">\E[a</span>, <span class=
"keyword">kf16</span>=<span class=
"literal">\E[b</span>, <span class=
"keyword">kf17</span>=<span class=
"literal">\E[c</span>, <span class=
"keyword">kf18</span>=<span class="literal">\E[d</span>,<br>
<span class="keyword">kf19</span>=<span class=
"literal">\E[e</span>, <span class=
"keyword">kf20</span>=<span class=
"literal">\E[f</span>, <span class=
"keyword">kf21</span>=<span class=
"literal">\E[g</span>, <span class=
"keyword">kf22</span>=<span class=
"literal">\E[h</span>, <span class=
"keyword">kf23</span>=<span class="literal">\E[i</span>,<br>
<span class="keyword">kf24</span>=<span class=
"literal">\E[j</span>,<br>
<!--atr2html}}--></dd>
<dt>F25-F36 are control F1-F12 <!--{{atr2html--></dt>
<dd style="font-family: monospace; font-size: 10pt;">
<span class="keyword">kf25</span>=<span class=
"literal">\E[k</span>, <span class=
"keyword">kf26</span>=<span class=
"literal">\E[l</span>, <span class=
"keyword">kf27</span>=<span class=
"literal">\E[m</span>, <span class=
"keyword">kf28</span>=<span class=
"literal">\E[n</span>, <span class=
"keyword">kf29</span>=<span class="literal">\E[o</span>,<br>
<span class="keyword">kf30</span>=<span class=
"literal">\E[p</span>, <span class=
"keyword">kf31</span>=<span class=
"literal">\E[q</span>, <span class=
"keyword">kf32</span>=<span class=
"literal">\E[r</span>, <span class=
"keyword">kf33</span>=<span class=
"literal">\E[s</span>, <span class=
"keyword">kf34</span>=<span class="literal">\E[t</span>,<br>
<span class="keyword">kf35</span>=<span class=
"literal">\E[u</span>, <span class=
"keyword">kf36</span>=<span class="literal">\E[v</span>,<br>
<!--atr2html}}--></dd>
<dt>F37-F48 are shift+control F1-F12 <!--{{atr2html--></dt>
<dd style="font-family: monospace; font-size: 10pt;">
<span class="keyword">kf37</span>=<span class=
"literal">\E[w</span>, <span class=
"keyword">kf38</span>=<span class=
"literal">\E[x</span>, <span class=
"keyword">kf39</span>=<span class=
"literal">\E[y</span>, <span class=
"keyword">kf40</span>=<span class=
"literal">\E[z</span>, <span class=
"keyword">kf41</span>=<span class="literal">\E[@</span>,<br>
<span class="keyword">kf42</span>=<span class=
"literal">\E[[</span>, <span class=
"keyword">kf43</span>=<span class=
"literal">\E[\\</span>, <span class=
"keyword">kf44</span>=<span class=
"literal">\E[]</span>, <span class=
"keyword">kf45</span>=<span class=
"literal">\E[\^</span>, <span class=
"keyword">kf46</span>=<span class="literal">\E[_</span>,<br>
<span class="keyword">kf47</span>=<span class=
"literal">\E[`</span>, <span class=
"keyword">kf48</span>=<span class="literal">\E[{</span>,<br>
<!--atr2html}}--></dd>
</dl>
</blockquote>
<p>Some combinations are missing (kf14 for instance corresponds
to a back-tab).</p>
<p>A different scheme is used by <code>rxvt</code> (which was
influenced by xterm and different hardware portability
tradeoffs):</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
<span class="keyword">kf1</span>=<span class=
"literal">\E[11~</span>, <span class=
"keyword">kf10</span>=<span class=
"literal">\E[21~</span>, <span class=
"keyword">kf11</span>=<span class=
"literal">\E[23~</span>, <span class=
"keyword">kf12</span>=<span class="literal">\E[24~</span>,<br>
<span class="keyword">kf13</span>=<span class=
"literal">\E[25~</span>, <span class=
"keyword">kf14</span>=<span class=
"literal">\E[26~</span>, <span class=
"keyword">kf15</span>=<span class=
"literal">\E[28~</span>, <span class=
"keyword">kf16</span>=<span class="literal">\E[29~</span>,<br>
<span class="keyword">kf17</span>=<span class=
"literal">\E[31~</span>, <span class=
"keyword">kf18</span>=<span class=
"literal">\E[32~</span>, <span class=
"keyword">kf19</span>=<span class=
"literal">\E[33~</span>, <span class=
"keyword">kf2</span>=<span class="literal">\E[12~</span>,<br>
<span class="keyword">kf20</span>=<span class=
"literal">\E[34~</span>, <span class=
"keyword">kf3</span>=<span class=
"literal">\E[13~</span>, <span class=
"keyword">kf4</span>=<span class=
"literal">\E[14~</span>, <span class=
"keyword">kf5</span>=<span class="literal">\E[15~</span>,<br>
<span class="keyword">kf6</span>=<span class=
"literal">\E[17~</span>, <span class=
"keyword">kf7</span>=<span class=
"literal">\E[18~</span>, <span class=
"keyword">kf8</span>=<span class=
"literal">\E[19~</span>, <span class=
"keyword">kf9</span>=<span class="literal">\E[20~</span>,<br>
<span class="keyword">kf21</span>=<span class=
"literal">\E[23$</span>, <span class=
"keyword">kf22</span>=<span class="literal">\E[24$</span>,<br>
<span class="keyword">kf23</span>=<span class=
"literal">\E[11\^</span>, <span class=
"keyword">kf24</span>=<span class=
"literal">\E[12\^</span>, <span class=
"keyword">kf25</span>=<span class=
"literal">\E[13\^</span>, <span class=
"keyword">kf26</span>=<span class="literal">\E[14\^</span>,<br>
<span class="keyword">kf27</span>=<span class=
"literal">\E[15\^</span>, <span class=
"keyword">kf28</span>=<span class=
"literal">\E[17\^</span>, <span class=
"keyword">kf29</span>=<span class=
"literal">\E[18\^</span>, <span class=
"keyword">kf30</span>=<span class="literal">\E[19\^</span>,<br>
<span class="keyword">kf31</span>=<span class=
"literal">\E[20\^</span>, <span class=
"keyword">kf32</span>=<span class=
"literal">\E[21\^</span>, <span class=
"keyword">kf33</span>=<span class=
"literal">\E[23\^</span>, <span class=
"keyword">kf34</span>=<span class="literal">\E[24\^</span>,<br>
<span class="keyword">kf35</span>=<span class=
"literal">\E[25\^</span>, <span class=
"keyword">kf36</span>=<span class=
"literal">\E[26\^</span>, <span class=
"keyword">kf37</span>=<span class=
"literal">\E[28\^</span>, <span class=
"keyword">kf38</span>=<span class="literal">\E[29\^</span>,<br>
<span class="keyword">kf39</span>=<span class=
"literal">\E[31\^</span>, <span class=
"keyword">kf40</span>=<span class=
"literal">\E[32\^</span>, <span class=
"keyword">kf41</span>=<span class=
"literal">\E[33\^</span>, <span class=
"keyword">kf42</span>=<span class="literal">\E[34\^</span>,<br>
<span class="keyword">kf43</span>=<span class=
"literal">\E[23@</span>, <span class=
"keyword">kf44</span>=<span class="literal">\E[24@</span>,<br>
<!--atr2html}}--></p>
</blockquote>
<p>The pattern is not so obvious here. The developer who assigned
the numbering chose certain combinations from a table which was
too large to map into the available 60 numbered keys. Here is the
complete table, noting that <code>F1</code> is the X11 code which
is not necessarily synonymous with <code>kf1</code>:</p>
<blockquote>
<table border="1" summary="Rxvt Function-Key Modifiers">
<caption>
Rxvt Function-Key Modifiers
</caption>
<tr>
<th>X11 Key</th>
<th>Normal</th>
<th>Shift</th>
<th>Control</th>
<th>Shift+Control</th>
</tr>
<tr>
<td>F1</td>
<td>ESC [ 11 ~</td>
<td>ESC [ 23 ~</td>
<td>ESC [ 11 ^</td>
<td>ESC [ 23 ^</td>
</tr>
<tr>
<td>F2</td>
<td>ESC [ 12 ~</td>
<td>ESC [ 24 ~</td>
<td>ESC [ 12 ^</td>
<td>ESC [ 24 ^</td>
</tr>
<tr>
<td>F3</td>
<td>ESC [ 13 ~</td>
<td>ESC [ 25 ~</td>
<td>ESC [ 13 ^</td>
<td>ESC [ 25 ^</td>
</tr>
<tr>
<td>F4</td>
<td>ESC [ 14 ~</td>
<td>ESC [ 26 ~</td>
<td>ESC [ 14 ^</td>
<td>ESC [ 26 ^</td>
</tr>
<tr>
<td>F5</td>
<td>ESC [ 15 ~</td>
<td>ESC [ 28 ~</td>
<td>ESC [ 15 ^</td>
<td>ESC [ 28 ^</td>
</tr>
<tr>
<td>F6</td>
<td>ESC [ 17 ~</td>
<td>ESC [ 29 ~</td>
<td>ESC [ 17 ^</td>
<td>ESC [ 29 ^</td>
</tr>
<tr>
<td>F7</td>
<td>ESC [ 18 ~</td>
<td>ESC [ 31 ~</td>
<td>ESC [ 18 ^</td>
<td>ESC [ 31 ^</td>
</tr>
<tr>
<td>F8</td>
<td>ESC [ 19 ~</td>
<td>ESC [ 32 ~</td>
<td>ESC [ 19 ^</td>
<td>ESC [ 32 ^</td>
</tr>
<tr>
<td>F9</td>
<td>ESC [ 20 ~</td>
<td>ESC [ 33 ~</td>
<td>ESC [ 20 ^</td>
<td>ESC [ 33 ^</td>
</tr>
<tr>
<td>F10</td>
<td>ESC [ 21 ~</td>
<td>ESC [ 34 ~</td>
<td>ESC [ 21 ^</td>
<td>ESC [ 34 ^</td>
</tr>
<tr>
<td>F11</td>
<td>ESC [ 23 ~</td>
<td>ESC [ 23 $</td>
<td>ESC [ 23 ^</td>
<td>ESC [ 23 @</td>
</tr>
<tr>
<td>F12</td>
<td>ESC [ 24 ~</td>
<td>ESC [ 24 $</td>
<td>ESC [ 24 ^</td>
<td>ESC [ 24 @</td>
</tr>
<tr>
<td>F13</td>
<td>ESC [ 25 ~</td>
<td>ESC [ 25 $</td>
<td>ESC [ 25 ^</td>
<td>ESC [ 25 @</td>
</tr>
<tr>
<td>F14</td>
<td>ESC [ 26 ~</td>
<td>ESC [ 26 $</td>
<td>ESC [ 26 ^</td>
<td>ESC [ 26 @</td>
</tr>
<tr>
<td>F15 (Help)</td>
<td>ESC [ 28 ~</td>
<td>ESC [ 28 $</td>
<td>ESC [ 28 ^</td>
<td>ESC [ 28 @</td>
</tr>
<tr>
<td>F16 (Menu)</td>
<td>ESC [ 29 ~</td>
<td>ESC [ 29 $</td>
<td>ESC [ 29 ^</td>
<td>ESC [ 29 @</td>
</tr>
<tr>
<td>F17</td>
<td>ESC [ 31 ~</td>
<td>ESC [ 31 $</td>
<td>ESC [ 31 ^</td>
<td>ESC [ 31 @</td>
</tr>
<tr>
<td>F18</td>
<td>ESC [ 32 ~</td>
<td>ESC [ 32 $</td>
<td>ESC [ 32 ^</td>
<td>ESC [ 32 @</td>
</tr>
<tr>
<td>F19</td>
<td>ESC [ 33 ~</td>
<td>ESC [ 33 $</td>
<td>ESC [ 33 ^</td>
<td>ESC [ 33 @</td>
</tr>
<tr>
<td>F20</td>
<td>ESC [ 34 ~</td>
<td>ESC [ 34 $</td>
<td>ESC [ 34 ^</td>
<td>ESC [ 34 @</td>
</tr>
</table>
</blockquote>
<p>That is, the final character is again used to encode the
modifiers. There are several terminals which use different
final-character encoding schemes, e.g., dg (Data General),
interix, and those based on <code>ansi.sys</code> or
<code>cons25</code>.</p>
<p>xterm uses a different scheme, encoding the modifiers as a
parameter. There are many combinations available. Here is a short
example:</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
<span class="keyword">kf1</span>=<span class=
"literal">\EOP</span>, <span class=
"keyword">kf13</span>=<span class=
"literal">\E[1;2P</span>, <span class=
"keyword">kf25</span>=<span class=
"literal">\E[1;5P</span>, <span class=
"keyword">kf37</span>=<span class="literal">\E[1;6P</span>,<br>
<span class="keyword">kf49</span>=<span class=
"literal">\E[1;3P</span>, <span class=
"keyword">kf61</span>=<span class="literal">\E[1;4P</span>,<br>
<!--atr2html}}--></p>
</blockquote>
<p>All of that focuses on <em>function keys</em>. There are other
special keys on the IBM PC keyboard, e.g., the editing keypad and
cursor keys.</p>
<p>Here, conventional terminfo/termcap provides just a little
help, but providing names for some of the shifted keys. xterm
defines some of these:</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
<span class="keyword">kDC</span>=<span class=
"literal">\E[3;2~</span>, <span class=
"keyword">kEND</span>=<span class=
"literal">\E[1;2F</span>, <span class=
"keyword">kHOM</span>=<span class=
"literal">\E[1;2H</span>, <span class=
"keyword">kIC</span>=<span class="literal">\E[2;2~</span>,<br>
<span class="keyword">kLFT</span>=<span class=
"literal">\E[1;2D</span>, <span class=
"keyword">kNXT</span>=<span class=
"literal">\E[6;2~</span>, <span class=
"keyword">kPRV</span>=<span class=
"literal">\E[5;2~</span>, <span class=
"keyword">kRIT</span>=<span class="literal">\E[1;2C</span>,<br>
<!--atr2html}}--></p>
</blockquote>
<p>But xterm can also work for control-, alt-, and
meta-modifiers. None of those are defined in conventional
terminfo/termcap.</p>
<p>ncurses allows you to define extended descriptions, i.e., to
make up your own names. The xterm terminfo descriptions do just
that: they define names for the modified cursor- and
editing-keypad keys which are just the xterm modifier code
appended to the name for the shifted key. For example, the
delete-key (kdc) can be represented as shown below:</p>
<blockquote>
<table border="1" summary="Example of Xterm Extended Key (DC)">
<caption>
Example of Xterm Extended Key (DC)
</caption>
<tr>
<th>Xterm Code</th>
<th>Modifier</th>
<th>Extended Name</th>
</tr>
<tr>
<td>1 (or missing)</td>
<td>Normal</td>
<td>kdc</td>
</tr>
<tr>
<td>2</td>
<td>Shift</td>
<td>kDC</td>
</tr>
<tr>
<td>3</td>
<td>Alt</td>
<td>kDC3</td>
</tr>
<tr>
<td>4</td>
<td>Shift + Alt</td>
<td>kDC4</td>
</tr>
<tr>
<td>5</td>
<td>Control</td>
<td>kDC5</td>
</tr>
<tr>
<td>6</td>
<td>Shift + Control</td>
<td>kDC6</td>
</tr>
<tr>
<td>7</td>
<td>Alt + Control</td>
<td>kDC7</td>
</tr>
<tr>
<td>8</td>
<td>Shift + Alt + Control</td>
<td>kDC8</td>
</tr>
</table>
</blockquote>
<p>Other terminal descriptions can be (and in ncurses, have been)
modified to use this naming scheme for extended keys:</p>
<ul>
<li>
<p>gnome-terminal and konsole (for more than ten years) used
an older version of xterm's encoding (<a href=
"/xterm/xterm-function-keys.html">deprecated in 2002</a>
because the parameter can be mistaken for a repeat count).
Although the encoding is different (and these terminals omit
some combinations), the functionality is similar.</p>
</li>
<li>
<p>rxvt also provides distinct escape sequences for modified
cursor- and editing-keys.</p>
</li>
</ul>
<p>By adding these to the terminal description, curses
applications will see the keycode rather than individual
characters when processing <a href=
"/ncurses/man/curs_inopts.3x.html">keypad</a> mode.</p>
<p>There are a few limitations though:</p>
<ul>
<li>
<p>the keycodes for the extended keys are generated at
runtime, so the application must ask what their values are
using <a href=
"/ncurses/man/key_defined.3x.html">key_defined</a>.</p>
</li>
<li>
<p>compiled terminfo descriptions, though larger than
termcap's 1023 bytes, are still limited to 4096 bytes. Many
applications (such as those built using <a href=
"ncurses-slang.html"><code>slang</code></a>) rely on this
limit. Applications can work around this by defining keys at
runtime, using <a href=
"/ncurses/man/define_key.3x.html">define_key</a>.</p>
</li>
</ul>
<h4 id="visible_keys-id"><a name="visible_keys" id=
"visible_keys">How can I see what my keyboard sends?</a></h4>
<p>All of the trouble-shooting for keyboard problems relies on
you being able to see what the keys send.<br>
You can do this in more than one way:</p>
<ul>
<li>
<p>Some implementations of the <code>cat</code> program have
a <code>-v</code> option which tells it to show non-printing
characters in visible form.<br>
These include all BSD and Linux-based systems, as well as
<a href=
"https://www-01.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.cmds1/cat.htm">
AIX</a>, <a href=
"https://www.freebsd.org/cgi/man.cgi?query=cat&apropos=0&sektion=1&manpath=HP-UX+11.11&arch=default&format=html">
HPUX</a> and <a href=
"https://www.freebsd.org/cgi/man.cgi?query=cat&apropos=0&sektion=1&manpath=SunOS+5.10&arch=default&format=html">
Solaris</a>.</p>
<p>While all of the extent Unix systems appear to have this
feature, <a href=
"http://pubs.opengroup.org/onlinepubs/9699919799/utilities/cat.html">
POSIX</a> does not document it.</p>
<p>You would use it by typing</p>
<blockquote>
<pre class="code-block">
cat -v
</pre>
</blockquote>
<p>It has a few limitations:</p>
<ul>
<li>it does not stop special characters such as
<em>control-C</em></li>
<li>the output format cannot be inverted to obtain the
original inputs.</li>
</ul>
</li>
<li>
<p>You can suppress the terminal driver's interpretation of
the <em>first</em> byte in a given key by first pressing
<code><em>control-V</em></code> (the <em>lnext</em> or
literal-next character).</p>
<p>In practice, this is “good enough” since most
of the terminals you might want to use will only have a
leading escape character in the special key strings.</p>
</li>
</ul>
<p>That makes it possible to see what your keyboard sends. There
is a corresponding problem seeing what programs actually send to
your terminal.</p>
<ul>
<li>
<p>A few platforms have <a href=
"https://www.freebsd.org/cgi/man.cgi?query=vis&apropos=0&sektion=1&manpath=FreeBSD+11-current&arch=default&format=html">
<code>vis</code></a>, which first appeared in 4.4BSD. There
is a corresponding <a href=
"https://www.freebsd.org/cgi/man.cgi?query=unvis&apropos=0&sektion=1&manpath=FreeBSD+11-current&arch=default&format=html">
<code>unvis</code></a> which can put the string back together
(unlike <code>cat -v</code>). You would use this by using
<code>script</code> to capture all of the bytes sent to your
terminal, e.g., in a file named <code>typescript</code>.</p>
</li>
<li>
<p>But <code>vis</code> is not available everywhere (e.g.,
AIX and Solaris do not provide it, nor are you likely to find
it with a Linux-based system).</p>
<p>At the <a href="/misc_tools/CHANGES.html#t19951215">end of
1995</a>, I wrote a similar program named <a href=
"/misc_tools/index.html#item:unmap"><code>unmap</code></a>
based on a description of <code>vis</code>, and likewise
<a href=
"/misc_tools/index.html#item:map"><code>map</code></a> (like
<code>unvis</code>) for completeness.</p>
</li>
</ul>
<h3 id="problems_hardware-id"><a name="problems_hardware" id=
"problems_hardware">Using Hardware (Real) Terminals</a></h3>
<h4 id="reset_logout-id"><a name="reset_logout" id=
"reset_logout">Why does reset log me out?</a></h4>
<p>This is a limitation of real hardware terminals: resetting
them will break the communications to the host temporarily. Some
terminal interfaces will tolerate this. Others (most) will
interpret this as hanging up, and log you out.</p>
<p>The reset is specified in the terminal description, e.g.,</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
<span class="keyword">rs1</span>=<span class=
"literal">\Ec</span>,<br>
<!--atr2html}}--></p>
</blockquote>
<p>That is the hardware reset escape sequence for vt100. Some
terminals provide enough control over their features that a very
complicated substitute could be concocted for the normal reset
which does not perform a hardware reset. In practice, this is not
easily done.</p>
<h4 id="need_padding-id"><a name="need_padding" id=
"need_padding">Why do I get trash on the screen?</a></h4>
<p>This is a problem of real hardware terminals. Cheap terminals
and cheap interfaces do not do sophisticated flow control (e.g.,
XON/XOFF). Instead, they rely on a host which does not send them
characters too rapidly. Remote terminal servers may provide flow
control; direct console or serial port connections often do not.
(If you are asking this question, you probably have inexpensive
hardware).</p>
<p>Terminfo descriptions designed for these inexpensive terminals
have delay times specified in the control sequences which take
extra time, such as clearing the screen. For example, the vt100
description tells the application to wait 50msec after clearing
the screen:</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
<span class="keyword">clear</span>=<span class=
"literal">\E[H\E[J$<50></span>,<br>
<!--atr2html}}--></p>
</blockquote>
<p>Note: the <a href="ncurses-slang.html"><code>slang</code></a>
library does not implement delay times, and is not suitable for
applications which require direct connection to a hardware
terminal. The author of that library states that no one uses
hardware terminals any more, suggesting that I add this
information to the FAQ.</p>
<h3 id="problems_programs-id"><a name="problems_programs" id=
"problems_programs">Interaction with Other Programs</a></h3>
<h4 id="handle_piping-id"><a name="handle_piping" id=
"handle_piping">Redirecting I/O to/from a Curses application</a></h4>
<p>In principle, you should be able to pipe to/from a curses
application. However, there are caveats:</p>
<ul>
<li>
<p>Some (very old) curses implementations did not allow
redirection of the screen. Ncurses, like Solaris curses,
consistently writes all output to the standard output. You
can pipe the output to a file, or use <code>tee</code> to
show the output while redirecting.</p>
</li>
<li>
<p>Ncurses obtains the screen size by</p>
<ul>
<li>starting with the size from the terminal
description,</li>
<li>then trying to query the output file pointer (unless
you have disabled it using the <a href=
"/ncurses/man/curs_util.3x.html#h3-use_tioctl">use_tioctl</a>
call), and</li>
<li>finally using the environment variables LINES and COLS
(unless you have disabled it with the <a href=
"/ncurses/man/curs_util.3x.html#h3-use_env">use_env</a>
call).</li>
</ul>
<p>If you are redirecting output, then a query based on the
file pointer will always fail (because a <em>pipe</em> is not
a <em>tty</em>), having no effect on the computed size.</p>
</li>
<li>
<p>Similarly, you can redirect input to an ncurses
application. However, I have observed that the use of
<code>setvbuf</code> (for better output buffering) interferes
with the use of stream I/O on Linux-based systems (and
possibly other platforms). Invoking <code>setvbuf</code> may
(depending on the implementation) cause buffered stream input
to be discarded. Ncurses does not use buffered input, however
you may have an application that mixes buffered input with a
curses session.</p>
</li>
</ul>
<h4 id="readline_library-id"><a name="readline_library" id=
"readline_library">What about readline?</a></h4>
<p>The <code>readline</code> library appeals to a number of
people, who would like to use it within an ncurses
application.</p>
<p>At first glance—but only for that instant—it
appears that the library is flexible enough to substitute a
different display driver, e.g., to output via something other
than <code>tput()</code> and <code>putc()</code>. Close reading
of its <code>display.c</code> file shows this is ultimately
futile. Quoting (Brian Fox's comment from the early 1990s, still
present in readline 6.1 in 2010) from that file gives some
insight:</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
<span class="comment">/* This is the stuff that is hard for me. I never seem to write good<br>
</span> <span class=
"comment">display routines in C. Let's see how I do this time. */</span><br>
<!--atr2html}}--></p>
</blockquote>
<p>John Greco suggests a different approach <a href=
"http://lists.gnu.org/archive/html/bug-ncurses/2010-10/msg00041.html">
here</a>, which discards ncurses' input functions (such as
<code>wgetch</code>), using <code>rl_callback_read_char</code> to
fill the <code>rl_line_buffer</code> array. That can be printed
using ncurses.</p>
<h4 id="setvbuf_once-id"><a name="setvbuf_once" id=
"setvbuf_once">Problems with Output Buffering</a></h4>
<p>Ncurses shares with SVr4 curses a limitation which is
documented in the C standard. To attain good performance, they
buffer output data, e.g., with the <code>setvbuf</code> function
(or equivalent, depending on the platform). The performance gain
is noticable.</p>
<p>However, if your application spawns a subprocess, it will
inherit the output stream from ncurses—still buffered. On
several platforms this results in odd behavior, since normally
the standard output is line buffered, making the output flushed
at the end of each line. To solve this problem, your application
should disable <code>setvbuf</code> before invoking the
subprocess and restore it when resuming. That is, it should, but
often cannot—that is the problem. The standard says that
<code>setvbuf</code> must be called only after opening a stream
and before performing any reads or writes with that stream.</p>
<p>If your application calls <code>initscr</code>, it uses the
standard output, which ncurses assumes has not been written to,
to which ncurses then applies buffering. (<em>Caveat</em>: The
standard writers neglected to provide a mechanism for determining
if the stream is indeed buffered). Adding a call to
<code>setvbuf</code> to disable buffering may work or not. In at
least one implementation, the C library continues using the
buffer after the buffer is disabled, even if an
<code>fflush</code> is first given. That is, it will produce a
core dump.</p>
<p>The fix? Use <code>newterm</code> to initialize ncurses and
manage the input and output streams yourself. For instance, you
may simply open <code>/dev/tty</code> for input and output, and
leave the standard input and output alone.</p>
<h3 id="problems_xwindows-id"><a name="problems_xwindows" id=
"problems_xwindows">Mice and Windows</a></h3>
<h4 id="xterm_paste-id"><a name="xterm_paste" id="xterm_paste">I
can't cut/paste in xterm</a></h4>
<p>This is a general FAQ relating to xterm. When an application
sets xterm to any of its mouse tracking modes, it reserves the
unshifted mouse button clicks for the application's use. Unless
you have modified the treatment of the shifted mouse button
events (e.g., with your window manager), you can always do
cut/paste by pressing the shift key while clicking with the
mouse.</p>
<p>Ncurses sets the mouse tracking mode as a result of your
application's calls to <code>mousemask</code>, which is an
extension.</p>
<h4 id="handle_resize-id"><a name="handle_resize" id=
"handle_resize">Handling <code>SIGWINCH</code> (resize
events)</a></h4>
<p>It is possible to make an application <em>resize</em> when
running in a windowing environment (e.g., in an
<code>xterm</code>). This is not a feature of standard SVr4
curses, though some curses implementations (e.g., HP-UX) support
this.</p>
<p>Within ncurses, there are two ways to accomplish this. One
relies on side-effects of the library functions, and is
moderately portable. The other is an extension to SVr4
curses.</p>
<ul>
<li>
<p><code>endwin</code>/<code>refresh</code> when invoked will
briefly exit curses and reinitialize the display, picking up
the new screen size. Ncurses will reallocate the
<code>WINDOW</code> data (e.g., curscr, stdscr) to reflect
the new limits.</p>
</li>
<li>
<p><code>resizeterm</code> can be invoked directly to make
ncurses resize its <code>WINDOW</code> data. I use it in my
directory editor <a href="/ded/ded.html">ded</a> to achieve
flicker-free resizing via a signal handler for
<code>SIGWINCH</code>.</p>
<p>The documentation for HP-UX curses implies that they use a
similar approach; I have been unable to make it work.</p>
</li>
</ul>
<p>Ncurses 5.0 can be configured to establish its own
<code>SIGWINCH</code> hander. In this configuration, the <a href=
"/ncurses/man/curs_getch.3x.html#h3-Predefined-Key-Codes"><code>wgetch</code></a>
function returns a special keycode <code>KEY_RESIZE</code> when a
resizing event is detected. The signal handler also sets a flag
which the library checks with <a href=
"/ncurses/man/resizeterm.3x.html#h3-is_term_resized"><code>is_term_resized</code></a>,
then calls <a href=
"/ncurses/man/resizeterm.3x.html"><code>resizeterm</code></a>
(<strong>Caveat</strong>: <code>malloc</code> and
<code>free</code> are not guaranteed to be safe for use in a
signal handler).</p>
<p>There is a known problem using bash's <em>checkwinsize</em>
misfeature. See Novell <a href=
"https://bugzilla.novell.com/show_bug.cgi?id=828877">#828877</a>,
as well as the thread starting <a href=
"http://lists.gnu.org/archive/html/bug-bash/2013-07/msg00054.html">
here</a> on bug-bash, and of course the manpage for <a href=
"/ncurses/man/curs_util.3x.html#h3-use_env">use_env</a>. Shells
which set <code>LINES</code> and <code>COLUMNS</code> might have
been a good idea in 1995, but not as a rule more recently than
that.</p>
<p>The <code>SIGWINCH</code> signal was a feature of SunOS (since
1984) rather than AT&T SystemV. SunOS also provided an
<code><em>ioctl</em></code> call which could be used to obtain
the terminal window's current size. Both aspects
(<code>SIGWINCH</code> signal and <code>winsize</code> structure)
were later incorporated in 4.3BSD (early 1985). Other systems,
e.g., Apollo provided similar capabilities, independently of
SunOS. The ncurses <code>resizeterm</code> function is based on
an earlier function <code>resizewin</code>, written in <a href=
"/ded/td_lib/CHANGES.html#t19880421">April 1988</a> using the
Apollo calls, and later modified to work with
<code>SIGWINCH</code>.</p>
<p>Though long supported on Unix-like platforms,
<code>SIGWINCH</code> has not been standarized. Writing in July
2020 (more than 35 years later), these related standardization
features are expected to be in <a href=
"https://standards.ieee.org/project/1003_1.html">P1003.1</a>
issue 8 (October 2022):</p>
<ul>
<li>
<p><a href=
"https://austingroupbugs.net/view.php?id=1053">0001053</a>:
<em>Add a “size” mode to stty(1)</em> (submitted
2016-05-10 19:12)</p>
</li>
<li>
<p><a href=
"https://austingroupbugs.net/view.php?id=1151">0001151</a>:
<em>Introduce new signal SIGWINCH and functions tcsetsize(),
tcgetsize() to get/set terminal window size</em> (submitted
2017-06-19 16:41)</p>
</li>
<li>
<p><a href=
"https://austingroupbugs.net/view.php?id=1185">0001185</a>:
<em>Additional 3rd option for getting line size.</em>
(submitted 2018-02-02 04:13)</p>
</li>
</ul>
<h4 id="using_gpm_lib-id"><a name="using_gpm_lib" id=
"using_gpm_lib">Linking with GPM (Linux console mouse
library)</a></h4>
<p>Ncurses works correctly with the Linux GPM (general purpose
mouse) library. However, early on some distributors tampered with
the library, making it not generally useful, by linking in a
portion of the BSD curses library to satisfy references for
<code>Gpm_Wgetch</code>. That prevented one from using ncurses'
GPM support.</p>
<p>GPM provides limited support for xterm mouse control
sequences. This is implemented in <code>GPM_Wgetch</code>, which
makes some unreasonable assumptions about the curses library's
internal behavior of <code>wgetch</code>. In particular, GPM
interferes with the logic which combines characters into
function-key codes. GPM also uses as part of its xterm control
sequences a pair which save/restore the mouse mode (and are not
actually handled by any of the other terminal emulators).</p>
<p id="w3m-vs-gpm">On writing this faq in 1999, there were no
applications that used this misfeature. Later (in 2005) there
were still no curses applications which do, however w3m contains
some contorted code to exploit this, by abusing the library
interface: it defines several symbols that conflict with ncurses
to intercept calls to <code>wgetch</code>, while using other
symbols from ncurses as is. (There is also documented
<code>Gpm_Getch</code>, but it is no longer present in the GPM
source code).</p>
<p>Since version 1.10 GPM comes with a configure script, which
allows the system builder to suppress this from the shared
library, e.g.,</p>
<blockquote class="code-block">
<!--{{atr2html-->
<p style="font-family: monospace; font-size: 10pt;">
configure --without-curses<br>
<!--atr2html}}--></p>
</blockquote>
<p>You should verify that the shared library does not use the
symbol <code>wgetch</code>. Version 1.16 lacked the configure
script option to suppress this hook; removing libcurses.o from
the list of objects in GPM's Makefile worked just as well.
Version 1.17 built correctly when I tested it, however, though
the changelog does not mention the change. It would seem that the
issue would be long resolved. However, it is not.</p>
<p>Starting with ncurses 5.5, the recommendation is still the
same: build the GPM library without the <code>Gpm_Wgetch</code>
interface. ncurses 5.5 can <a href=
"NEWS.html#t20041009">dynamically load</a> the GPM library on
Linux, and that eliminates any reason to have the ncurses library
built with an explicit dependency upon GPM.</p>
<p>Some of the GPM fixes are based on a quirk of the library: if
<code>Gpm_Open</code> is called when the <code>TERM</code>
environment variable contains “xterm”, it opens a
connection which returns the raw character stream which might
contain mouse escape sequences. It returns a special file
descriptor (-2) which is easy to overlook in the normal checks on
file descriptors which are valid only when positive. For quite a
while as well, GPM and X could not co-exist. It was not uncommon
to have some safeguards to turn off GPM when starting X. By
around 2005, some fixes had been made to the X server to allow
the two to run concurrently. That exposed some problems in
ncurses which had not properly checked for the special file
descriptors, and affected programs running in an xterm, e.g.,
<a href="/dialog/dialog.html">dialog</a> and <a href=
"/ded/ded.html">ded</a> which start/stop the mouse interface. For
these, the GPM server would ultimately be locked up and not
return from a call to <code>Gpm_Open</code>.</p>
<h3 id="problems_packages-id"><a name="problems_packages" id=
"problems_packages">Problems with Packages</a></h3>
<h4 id="packages_buggy-id"><a name="packages_buggy" id=
"packages_buggy">Comments on packages</a></h4>
<p>Packages are a good thing. Sometimes.</p>
<p>Not all distributions clearly distinguish between release
versions of software, betas and alpha versions. (To be fair, not
all producers distinguish these properly).</p>
<h4 id="version4_or_not-id"><a name="version4_or_not" id=
"version4_or_not">Ncurses 4/4.2/5.0</a></h4>
<p>Ncurses 5.0 was not compatible with ncurses 4.2, however I
frequently saw people advising others to “fix”
programs that require the older library to make a symbolic link
from the newer name to the older. That only works for simple
applications, and not all of those.</p>
<p>Ncurses 4.0 and 4.2 were released respectively before and
after X/Open finished their curses specification. Both were based
on the draft specifications from 1995 and 1996. The released
specification (available in 1997) differs in several places,
mainly in the provisions for multi-byte character sets.</p>
<p id="extended-terminfo-1999">Late in 1998 through early 1999, I
made corrections to the development version of ncurses to align
it to the X/Open specification. Near the end of this, I realized
that I had an opportunity to add an extension to ncurses which
would make the terminfo format extensible, just as termcap is. It
required a change to the <code>term.h</code> header. to allow the
arrays for terminfo booleans, numbers and strings to be set at
runtime. This had the effect of making programs not
binary-compatible, but that was not a drawback, since it was
already conceded that ncurses 5.0 would not be binary-compatible
with ncurses 4.2 because of the X/Open changes. Only a few
applications use <code>term.h</code>, and those would be fixed by
a recompile.</p>
<p>One problem: Redhat packaged development versions of ncurses
without distinguishing them from the release versions. We
discussed the matter with them, but they did not wish to
cooperate. Redhat 6.0 was released with almost all of the
interface changes that comprised ncurses 5.0—as "ncurses
4.2". When ncurses 5.0 was released, they did not bother to read
the release notes, and released that as "ncurses 4.2". Somewhat
later, they added to the confusion by calling it "ncurses 4.0".
Until mid-2001, much of this information was still available in
Bugzilla.</p>
<p>Redhat continues to distribute development versions of ncurses
without distinguishing between release- and
development-versions.</p>
<h4 id="colorfgbg_bug-id"><a name="colorfgbg_bug" id=
"colorfgbg_bug">rxvt's <code>$COLORFGBG</code> variable</a></h4>
<p>Ncurses 5.2 added an experimental feature: support for rxvt's
<code>$COLORFGBG</code> variable. This is a feature which tells
the application what colors the default foreground and background
correspond to. It is specific to rxvt: in general other terminal
emulators assign colors for foreground and background which do
not necessarily correspond to any of the ANSI colors. This
feature was enabled in some rpm-based distributions, e.g.,
Mandrake and Redhat.</p>
<p>It worked for the configuration on which I tested, however
there are two configurations. The format of the
<code>$COLORFGBG</code> variable is not documented; you must read
the C code to find how rxvt sets it. The two configurations
correspond to whether the xpm library is used or not. If xpm is
used, ncurses 5.2 sees the wrong value for the background, and
display black-on-black.</p>
<p>Quick fix: unset <code>$COLORFGBG</code>.<br>
Better fix: update the ncurses rpm (Mandrake did).</p>
<h3 id="no_urxvt-id"><a name="no_urxvt" id="no_urxvt">Where is
rxvt-unicode?</a></h3>
<p>See the <a href="ncurses-urxvt.html">rxvt(-unicode) in
ncurses</a> page.</p>
<h2 id="report_bugs-id"><a name="report_bugs" id=
"report_bugs">How do I report bugs?</a></h2>
<p>First, check to see if your problem is addressed in this FAQ.
Read the INSTALL document, if you have not done so. However, it
may not be a known problem. Read on.</p>
<ul>
<li><a href="#how_to_report">How should I report bugs?</a></li>
<li><a href="#problems_building">How do I report problems
building ncurses?</a></li>
<li><a href="#dbupdate">Updates to terminal database</a></li>
<li><a href="#backlog">Why aren't my bugs being fixed?</a></li>
<li><a href="#patch_summary">How are patches organized?</a></li>
</ul>
<h3 id="how_to_report-id"><a name="how_to_report" id=
"how_to_report">How should I report bugs?</a></h3>
<p>Contact the current maintainers at <a href=
"mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</a>.</p>
<p>To join the ncurses mailing list, please write email to
<code>bug-ncurses-request@gnu.org</code> containing the line:</p>
<blockquote>
<pre>
subscribe <name>@<host.domain>
</pre>
</blockquote>
<p>This list is open to anyone interested in helping with the
development and testing of this package.</p>
<p>There is an archive of the mailing list here:</p>
<blockquote>
<p><a href=
"http://lists.gnu.org/archive/html/bug-ncurses/">http://lists.gnu.org/archive/html/bug-ncurses</a>
(also <a href=
"https://lists.gnu.org/archive/html/bug-ncurses/">https</a>)</p>
</blockquote>
<p>Otherwise, you may email directly to the maintainers,
currently:</p>
<ul>
<li><a href="mailto:dickey@invisible-island.net">Thomas E.
Dickey <dickey@invisible-island.net></a></li>
</ul>
<p>If you send email only to one of the other authors, I will
probably not see it. I prefer that bug reports go to the mailing
list. (Occasionally I get private email <em>cc</em>'ing Zeyd and
Eric, neither of whom has contributed since before 2000).</p>
<p>I get some of my bug reports via the ncurses mailing list,
some via bug-tracking systems, and the others via direct
email.</p>
<p>The mailing list is useful. When it began, more than half of
the changes that were introduced without review in the ncurses
mailing list introduced a bug. So I find it necessary to review
proposed changes.</p>
<p>Refer to the standard <a href=
"/personal/bug-reports.html">reporting/patching</a> procedures,
for a start.</p>
<p>When sending patches, specify the version of ncurses that you
are patching. All versions of ncurses have major, minor and
patch-date numbers. Those may not be the same as a package
revision number; it helps to identify that, so that I can relate
it to the source.</p>
<p>There is a defunct "help-ncurses" mailing list, which I
requested to be shut down long ago. I am not subscribed to that
list.</p>
<h3 id="problems_building-id"><a name="problems_building" id=
"problems_building">How do I report problems building
ncurses?</a></h3>
<p>This is a little different from reporting bugs. If you have a
machine that I've not ported to, and have problems, I'll require
the relevant information:</p>
<ul>
<li><code>config.log</code>
</li>
<li><code>config.status</code>
</li>
<li><code>include/ncurses_cfg.h</code>
</li>
<li>log from running <code>configure</code>, with options</li>
<li>log from running <code>make</code>, with options</li>
</ul>
<p>A MIME attachment (preferably of the <em>compressed</em>
files) is preferred, because logfiles can be awkward to send and
receive via email. You may find the <a href=
"/scripts/readme.html">scripts</a> which I use for building and
saving logfiles useful.</p>
<p>If you're having trouble building on a known
“good” platform, please make sure that you've got a
current version of ncurses, and please read the installation
instructions.</p>
<h3 id="dbupdate-id"><a name="dbupdate" id="dbupdate">Updates to
terminal database</a></h3>
<p>I attempt to verify users's proposed changes to the terminal
database. Most of those are for terminal emulators, although
there are still (2018) occasional updates for hardware terminals.
Calling them all “applications”, there are some
limitations which must be mentioned, based on developers' past
abuse of common-sense guidelines:</p>
<ul>
<li>
<p>Updates for applications which are not generally available
in a <em>finished</em> form are not suitable for
inclusion.</p>
<p>This is not the place for publishing in-development work
which might change (or might not even be correct).</p>
<p>Start by stating which packaged version of an application
should be used for validating the updates.</p>
</li>
<li>
<p>Terminal descriptions for applications which have some
“string attached” (license fee, non-disclosure
restriction, etc.), might be suitable for inclusion provided
that there is no implication that they are the same as some
less restrictively available application.</p>
<p>For instance, there will be no aliases added in the
less-restrictive application's terminal description
mentioning the more-restrictive one.</p>
</li>
</ul>
<p>Given those limitations, keep in mind that the terminal
descriptions have to work with ncurses:</p>
<ul>
<li>
<p>Keep in mind that ncurses <em>displays</em> characters on
terminals and get <em>input</em> (e.g., read characters) from
the terminal. The predefined capabilities are used for one or
both of those goals. Terminal descriptions may have
user-defined capabilities, but if those capabilities are used
to tell applications how to <em>display</em> on a terminal or
get <em>input</em> from a terminal, they have be relevant to
ncurses.</p>
</li>
<li>
<p>Applications which infer characteristics of a terminal
from the <em>name</em> of a terminal description are not
relevant to ncurses. No changes will be made to the terminal
database to accommodate those applications.</p>
</li>
</ul>
<p>Furthermore:</p>
<ul>
<li>
<p>I use <a href="man/tic.1m.html">tic</a>'s consistency
checks, <a href="tack.html">tack</a> and <a href=
"/vttest/vttest.html">vttest</a>, as well as custom scripts
for testing basic functionality.</p>
</li>
<li>
<p>When users provide custom scripts or programs which
demonstrate a given feature, that helps a lot.</p>
</li>
<li>
<p>If the source-code for the application is published, I
will study that to amend the proposed changes. Often,
developers propose changes based on cut/paste from other
descriptions. Testing and review eliminate most of that
problem.</p>
</li>
<li>
<p>If a feature is present in the application but does not
work as other implementations do, it will be removed or
cancelled from the terminal description.</p>
</li>
<li>
<p>Applications whose terminal descriptions which simply
repeat another description might be considered for inclusion
as <em>aliases</em>, but only if those have wide-spread
recognizably different appearance.</p>
</li>
</ul>
<h3 id="backlog-id"><a name="backlog" id="backlog">Why aren't my
bugs being fixed?</a></h3>
<p>Sorry. This is a hobby. There's a large backlog. Some changes
pass review quickly, others are difficult, because one fix may
break other functionality. My criteria are less stringent if you
provide a short program that demonstrates the problem, or if
you're modifying something that you maintain.</p>
<p>In any case, I will incorporate patches into my beta version
only if I have reviewed the patch, tested it (if the patch is not
obvious), and repaired any omissions (e.g., portability
constraints). Occasionally I have patches (including my own)
which cannot pass immediate review; these constitute most of my
backlog. A small part of my backlog consists of issues which
highlight incompatibilities between ncurses and SVr4 curses;
these are listed in the TO-DO file.</p>
<p>I use the following guidelines:</p>
<ul>
<li id="bugnot-svr4docs">
<p>extensions (deviations from SVr4 curses) are allowed only
if they do not modify the documented/observed behavior of the
API.</p>
</li>
<li id="bugnot-internals">
<p>extensions are feature changes which cannot be implemented
without modifying the library.</p>
<p>For example, if you really <em>need</em> a function which
interprets ANSI escape sequences, that can be done without
modifying the library.</p>
</li>
<li id="bugnot-svr4testing">
<p>I test behavior using <em class="small-caps">unix</em>
curses (Solaris and others), and use the vendor's manual
pages in conjunction with the X/Open Curses
documentation.</p>
</li>
<li id="bugnot-xpg4curses">
<p>The Solaris XPG4 curses implementation is known to be
badly broken; its SVr4 curses is usable for comparisons.</p>
</li>
<li id="using_illumos">
<p>The OpenSolaris source code (available via <a href=
"https://github.com/illumos/illumos-gate">Illumos</a>) is
useful for gaining insight (and clarifying documentation),
because it includes the Solaris SVr4 and XPG4 curses
sources.<br>
However, Solaris' XPG4 curses differs from other vendors'
implementations.</p>
</li>
</ul>
<h3 id="patch_summary-id"><a name="patch_summary" id=
"patch_summary">How are patches organized?</a></h3>
<p>Prior to version 4.0 I posted patches to the ncurses mailing
list summarizing only my changes (after applying changes
submitted by others). The intent was that people who followed the
list closely could build developmental versions.</p>
<p>Generally (unless we find a serious error), I issue patches on
Saturdays, since validating patches takes time.</p>
<p>Beginning with version 4.0, I maintain “complete”
patches (my changes together with those that I have integrated).
It is simpler, and does not require making complete snapshots as
often.</p>
<ul>
<li>
<p>User-supplied patches that require no modification are
always tagged with their name, making it simpler to follow
the revision history.</p>
</li>
<li>
<p>User-supplied patches that require some modification are
still tagged, but my patch will have followup changes.</p>
</li>
</ul>
<p>Most files have RCS identifiers. If you are maintaining
ncurses in an RCS (or CVS, etc.) archive, you can keep in sync
with this using the "-k" option of <code>ci</code>.</p>
<h2><a name="standardization" id=
"standardization">Standardization</a></h2>
<ul>
<li><a href="#posix_compliant">POSIX Compliant?</a></li>
<li><a href="#lsb_compliant">LSB Compliant?</a></li>
<li><a href="#y2k_compliant">Y2K Compliant?</a></li>
</ul>
<h3 id="posix_compliant-id"><a href="#standardization" name=
"posix_compliant" id="posix_compliant">POSIX Compliant?</a></h3>
<p>That depends.</p>
<p>The library and utilities use (where possible) POSIX
interfaces.</p>
<p>However, X/Open Curses is not part of POSIX (the
1003.<em>x</em> series, referred to as the <em>Base
Specifications</em>). It is a different standard, updated less
frequently, and bundled as part of the <a href=
"http://www.unix.org/version4/overview.html"><em>Single
<span class="small-caps">UNIX</span> Specification</em></a>.</p>
<p>Quoting from <em>Advanced Programming in the UNIX
Environment</em>, third edition (Stevens and Rago):</p>
<blockquote class="code-block">
<p>The third version of the Single UNIX Specification (SUSv3)
was published by The Open Group in 2001. The Base
Specifications of SUSv3 are the same as IEEE Standard
1003.1-2001 and are divided into four sections: Base
Definitions, System Interfaces, Shell and Utilities and
Rationale. SUSv3 also includes X/Open Curses Issue 4, Version
2, but this specification is not part of POSIX.1.</p>
<p>...</p>
<p>In 2003, the Single UNIX Specification was updated,
including corrections and new interfaces, removing obsolete
interfaces, and marking other interfaces as being obsolescent
in preparation for future removal. Additionally some previously
optional interfaces were promoted to nonoptional status,
including asynchronous I/O, barriers, clock selection, memory
mapped files, memory protection, reader-writer locks, real-time
signals, POSIX semaphores, spin locks, thread-safe functions,
threads, timeouts, and timers. The resulting standard is known
as Issue 7 of the Base Specifications, and is the same as
POSIX-1.2008. The Open Group bundled this version with an
updated X/Open Curses specification and released them as
version 4 of the Single Unix Specification in 2010. We'll refer
to this as SUSv4.</p>
</blockquote>
<p>Additionally, ncurses</p>
<ul>
<li>provides <em>extensions</em> (features not addressed by
X/Open Curses),</li>
<li>is sometimes <em>different</em> from X/Open Curses,
and</li>
<li>provides <em>extra libraries and programs</em> (<a href=
"man/form.3x.html">form</a>, <a href=
"man/menu.3x.html">menu</a>, <a href=
"man/panel.3x.html">panel</a> as well as <a href=
"man/toe.1m.html">toe</a>, <a href=
"man/tset.1.html">tset</a>)<br>
not documented by X/Open Curses.</li>
</ul>
<p>The Austin Review <a href=
"https://www.mail-archive.com/austin-group-l@opengroup.org/maillist.html">
mailing list archives</a> frequently mention POSIX features which
ncurses uses, but do not mention curses itself.</p>
<h3 id="lsb_compliant-id"><a href="#standardization" name=
"lsb_compliant" id="lsb_compliant">LSB Compliant?</a></h3>
<p>Perhaps the reverse. LSB largely complies with the ncurses and
X/Open Curses documentation, but LSB is not used by ncurses.</p>
<p>The Linux Foundation's LSB (<a href=
"https://refspecs.linuxfoundation.org/">Linux Standard Base</a>)
combines POSIX and curses and other technical areas from other
groups. ncurses is part of the LSB's Core Specification.</p>
<p>Currently in its 5th revision, the LSB describes some
ncurses-specific features, e.g.,</p>
<ul>
<li>
<p><a href=
"https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/libncursesman.html">
<em>15.7. Interface Definitions for libncurses</em></a> lists
a small number of functions which the LSB states is different
from X/Open Curses Issue 7. However, it does not reference
the ncurses manual pages (which go into far more detail about
these differences).</p>
</li>
<li>
<p><a href=
"https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/libncursesw-ddefs.html">
<em>15.9.1. ncursesw/curses.h</em></a> gives an extract from
the ncurses 5.9 header files, omitting most of the comments
(and copyright notice).</p>
</li>
<li>
<p>The LSB authors appear to be unaware that some of the
definitions are not found in X/Open Curses, e.g.,</p>
<blockquote>
<pre class="code-block">
#define KEY_MOUSE 0631
#define KEY_RESIZE 0632
#define KEY_EVENT 0633
</pre>
</blockquote>
</li>
<li>
<p>The summaries for <a href=
"https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/libncurses.html">
libncurses</a> and <a href=
"https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/libncursesw.html">
libncursesw</a> include in the latter some common
(ncurses-specific) functions such as those used in the mouse
interface and window-resizing.</p>
</li>
</ul>
<p>In some cases, the LSB is incorrect:</p>
<ul>
<li>
<p>LSB equates <a href=
"/ncurses/man/curs_scanw.3x.html">vw_scanw</a> and vwscanw
(the latter is obsolete, but LSB documents <a href=
"https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/curses-vwscanw-1.html">
vwscanw</a> rather than <tt>vw_scanw</tt>).</p>
</li>
<li>
<p>In its errata for <a href=
"https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/curses-winstr-1.html">
winstr</a>, LSB references POSIX rather than X/Open
Curses.</p>
</li>
<li>
<p>LSB is too specific regarding the filenames for libraries.
For ncurses, it documents <tt>libncurses.so.5</tt> and
<tt>libncursesw.so.5</tt>.</p>
<p>ncurses 6.0, released in 2015, provides the same
interfaces, but uses <strong>6</strong> in the filenames.</p>
<p>Occasionally, packagers trip over this (see RedHat
<a href="https://bugzilla.redhat.com/show_bug.cgi?id=2076968">
#2076968</a>).</p>
</li>
<li>
<p>LSB appears to have no way of representing the same
function being provided by more than one library. Its summary
of the library interface for ncursesw does not document the
fact that most of the functions are documented in X/Open
Curses (see LSB bug reports <a href=
"https://lsbbugs.linuxfoundation.org/show_bug.cgi?id=1761">#1761</a>
and <a href=
"https://lsbbugs.linuxfoundation.org/show_bug.cgi?id=3838">#3838</a>).</p>
</li>
<li>
<p>LSB does not account for the common ncurses configuration
(since <a href="NEWS.html#t971220">1997</a>) which splits the
library into ncurses/tinfo (see LSB bug mailing list
discussion in <a href=
"https://lists.linuxfoundation.org/pipermail/lsb-discuss/2016-April/008131.html">
April 2016</a>).</p>
</li>
</ul>
<h3 id="y2k_compliant-id"><a href="#standardization" name=
"y2k_compliant" id="y2k_compliant">Y2K Compliant?</a></h3>
<p>Certainly.</p>
<p>The ncurses library does not store or retrieve dates in any
form that depends on the year. Ncurses' use of time information
is limited to</p>
<ul>
<li>computing the elapsed times, in fractions of a second,</li>
<li>comparing file creation times, and</li>
<li>sample programs that display the current time of day.</li>
</ul>
<hr>
<h2 id="terminology-id"><a name="terminology" id=
"terminology">Terminology</a></h2>
<p><strong>Ncurses</strong> is used primarily with
<strong>terminal emulators</strong>. A few people use it with
hardware terminals.</p>
<dl>
<dt>Terminals</dt>
<dd>
<p>Short for <em>data terminals</em>,
<strong>terminals</strong> provide users with the ability to
enter and view data. The word <em>terminal</em> refers to
something that is the endpoint.</p>
<p>Terminals are generally not part of the computer, nor are
they necessarily near the computer. Originally, terminals
were connected to the computer by cables, later by local
networks. The terminal emulator running in your computer's
desktop environment is a special case—still using a
network connection, but perhaps sharing keyboard and display
with other terminal emulators.</p>
</dd>
<dt>Emulators</dt>
<dd>
<p>An <strong>emulator</strong> of course is something which
behaves like something else. In the case of terminals, these
are programs which provide the same functionality as hardware
terminals, or even other terminal emulator programs.</p>
</dd>
<dt>Control sequences</dt>
<dd>
<p>Often referred to as <em>escape sequences</em> because
many begin with the ASCII escape-character, <strong>control
sequences</strong> are sequences of characters sent to a
terminal to make it perform some operation. Most terminals
(the ones that ncurses deals with) are <em>asynchronous</em>,
and accept control sequences which update parts of the
display. There are others, e.g., the <em>synchronous</em>
"block-oriented" terminals such as the IBM 3278.</p>
<p>The VT100's control sequences are used in many terminal
emulators for example. In turn, most of those control
sequences follow standards established by ANSI, ISO, ECMA.
These are the most useful (and accessible):</p>
<ul>
<li><a href=
"http://www.ecma-international.org/publications/standards/Ecma-035.htm">
ECMA-35 - Character Code Structure and Extension
Techniques</a></li>
<li><a href=
"http://www.ecma-international.org/publications/standards/Ecma-048.htm">
ECMA-48 - Control Functions for Coded Character Sets</a></li>
</ul>
<p>The standards do not give exact functional definitions.
For that, ncurses development relies on vendor documentation,
analysis and comparison testing.</p>
</dd>
<dt>Consoles</dt>
<dd>
<p>Originally <strong>console</strong> referred to the front
panel of a computer, e.g., <em>lights and switches</em>, as
well as the attached operator's terminal. The switches would
do more than just turn the computer on and off.</p>
<ul>
<li>
<p>Some machines provided special purpose switches which
could enter data or control the computer's operation.</p>
</li>
<li>
<p>Later, the front panel was not so important for this
purpose, and the operator's terminal was treated as the
console. Many operating systems have a special terminal
device for the system console terminal, e.g,.</p>
<ul>
<li><code>CON:</code> for MS-DOS</li>
<li><code>/dev/console</code> on Unix-like
systems.</li>
<li><code>OPA0:</code> for VMS.</li>
</ul>
</li>
<li>
<p>Still later, with video terminals becoming more common
than printing terminals, the console terminal became an
integral part of the computer. Several operating systems
implement their console terminal as part of the kernel,
e.g., Solaris, FreeBSD, Linux. Many people are confused
by this, and refer to these as <em>hardware consoles</em>
though they are not. They are programs. Generally they
are not referred to as <em>emulators</em> simply because
they usually are not made to imitate another
terminal.</p>
</li>
<li>
<p>The console terminal now is used mainly when
installing or reconfiguring the computer, rather than for
routine control of its programs. Some system calls treat
it specially, by using it as the destination for messages
to the operator.</p>
</li>
</ul>
<p>The X Window system can be run on many of the console
terminals. Sun's workstations for example did this. Few
people used the console terminal on that hardware (which by
the way was not VT100-compatible). Since X took over the
computer's display, some way was needed to make the operator
messages visible. The <a href=
"http://www.x.org/archive/X11R6.8.1/doc/xconsole.1.html">xconsole</a>
program did that; desktop systems provide analogous
solutions. It is not necessary to use a terminal emulator to
display operator messages. A few terminal emulators (such as
<a href="/xterm/">xterm</a>) can intercept console messages
as an optional feature. The <a href=
"/xterm/xterm.faq.html#bug_konsole">konsole</a> program on
the other hand, does not perform this function,
notwithstanding its name. Rather, it is a terminal
emulator.</p>
<p>Microsoft Windows's treatment of console devices has
changed:</p>
<ul>
<li>
<p>In MS-DOS, there was one display device.</p>
</li>
<li>
<p>In Windows, there can be several console windows, each
with its own console device. You can see the
characteristics of the corresponding device by entering
the command <code>mode con</code> into a console window.
They are referred to as console windows because they
provide partial compatibility with the MS-DOS console
commands (including the device name
<code>CON:</code>).</p>
</li>
<li>
<p>They are not terminal emulators however: these console
windows do not by themselves respond to <em>control
sequences</em>. MS-DOS provided a special device driver
for this purpose called <code>ANSI.SYS</code>.</p>
</li>
<li>
<p>Windows provides an application programming interface
(API) by which programs can treat the console window as a
display.</p>
</li>
<li>
<p>Several terminal emulators have been written using the
Windows <a href=
"http://msdn.microsoft.com/en-us/library/windows/desktop/ms682087(v=vs.85).aspx">
console API</a> which run in one of these console windows
(for example, the Cygwin terminal before <a href=
"http://code.google.com/p/mintty/">mintty</a>).</p>
</li>
<li>
<p>There is also a port of ncurses using MinGW to these
console windows. However, the ncurses MinGW port is a
special case <em>not</em> using a terminal emulator. Like
pdcurses, ncurses implements the Windows port using the
<a href=
"http://msdn.microsoft.com/en-us/library/windows/desktop/ms682073(v=vs.85).aspx">
Windows Console API</a>. It does not rely upon
<code>ANSI.SYS</code> or any of its successors.</p>
</li>
</ul>
<p>Like the Windows Console API, neither ncurses or pdcurses
are terminal emulators. However, it is possible to write a
terminal emulator using any of these application programming
interfaces.</p>
</dd>
</dl>
<h2 id="additional_reading-id"><a name="additional_reading" id=
"additional_reading">Additional Reading</a></h2>
<ul>
<li><a href="#for_reference">For reference</a></li>
<li><a href="#other_books">Dead trees</a></li>
<li><a href="#other_langs">Language bindings</a></li>
<li><a href="#other_impls">Other implementations</a></li>
<li><a href="#other_appls">Related applications</a></li>
<li><a href="#ref_obsolete">Technically obsolete, but often
cited</a></li>
<li><a href="#ref_reallyold">Really old stuff</a></li>
<li><a href="#ref_misleading">Interesting but misleading</a></li>
</ul>
<h3 id="for_reference-id"><a name="for_reference" id=
"for_reference">For reference:</a></h3>
<ul>
<li>
<p>The <a href="/ncurses/man/index.html">manpages</a>, of
course.</p>
</li>
<li>
<p>X/Open Curses is not part of POSIX (the 1003.<em>x</em>
series, referred to as the <em>Base Specifications</em>). It
is a different standard, updated less frequently, and bundled
as part of the <a href=
"http://www.unix.org/version4/overview.html"><em>Single
<span class="small-caps">UNIX</span>
Specification</em></a>.</p>
<p>Here are some useful links</p>
<ul>
<li>
<p><a href=
"https://web.archive.org/web/20130602072639/https://www2.opengroup.org/ogsys/catalog/C094">
19 Apr 2013 – Issue 7</a></p>
</li>
<li>
<p><a href=
"https://web.archive.org/web/20010708022933/http://www.opengroup.org/publications/catalog/C610.htm">
15 Jul 1996 – Issue 4, Version 2</a></p>
</li>
<li>
<p><a href=
"http://www.opengroup.org/onlinepubs/7908799/cursesix.html">
X/Open Curses, Issue 4, Version 2, Reference Pages</a></p>
</li>
</ul>
</li>
<li>
<p>These are based on ncurses:</p>
<ul>
<li>
<p><a href=
"http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/">NCURSES-Programming-HOWTO</a>.<br>
An <a href=
"/ncurses/howto/NCURSES-Programming-HOWTO.html">updated
version</a> is provided in the ncurses source-tree.</p>
<p>The SGML and program examples are available as
<a href="https://github.com/ThomasDickey/ncurses-howto-snapshots/">
ncurses-howto-snapshots</a>.<br>
A direct download is provided <a href=
"/ncurses/howto/ncurses-howto-20050620.zip">here</a>.</p>
</li>
<li>
<p><a href=
"http://www.c-for-dummies.com/ncurses/">Programmer's
Guide to NCurses</a> by Dan Gookin. Wiley, 2007.<br>
(my involvement is mentioned <a href=
"/personal/paperstuff.html#acknowledgements">here</a>).</p>
<p>The source code for the examples is available on
<a href=
"https://github.com/wkoszek/ncurses_guide">Koszek's
page</a>.</p>
</li>
</ul>
</li>
<li>
<p>These are useful reading as background material:</p>
<ul>
<li>
<p><a href=
"https://docs.oracle.com/cd/E36784_01/html/E36880/curses-3curses.html#scrolltoc">
Solaris 11 Reference Manual Collection,<br>
manual pages section 3: Curses Library Functions</a></p>
</li>
<li>
<p><a href=
"http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/curses.htm">
AIX General Programming Concepts: Writing and Debugging
Programs,<br>
Chapter 2: The Curses Library</a></p>
</li>
<li>
<p><a href=
"http://uw714doc.sco.com/en/man/html.3ocurses/Intro.3ocurses.html">
Unixware curses</a> (a rare reference to “POSIX
curses”).</p>
</li>
<li>
<p><a href=
"http://polarhome.com/service/man/?qf=curses&tf=2&of=IRIX&sf=3X">
IRIX64 curses</a></p>
</li>
</ul>
</li>
</ul>
<h3 id="other_books-id"><a name="other_books" id=
"other_books">Dead trees:</a></h3>
<p>Intentionally ignoring the “door stops” which
reprint manual pages, these books (long out of print) give useful
information:</p>
<ul>
<li>
<p><a name="book_goodheart" id="book_goodheart"><em>UNIX
Curses Explained</em></a>. Berny Goodheart. Prentice Hall of
Australia Pty Ltd. 1991. 287 pages. ISBN: 0-13-931957-5.</p>
<p>Goodheart's book is useful for its historical perspective:
he frequently mentions when a feature was added, and how it
fit in.</p>
</li>
<li>
<p><a name="book_strang" id="book_strang"><em>termcap &
terminfo</em></a>. John Strang, Linda Mui and Tim O'Reilly.
O'Reilly & Associates, Inc., Sebastopol, CA, USA. Third
edition with corrections, July 1992. 253 pages. ISBN:
0-937175-22-6.</p>
<p>Originally published in 1985 to describe <em>termcap</em>
and then updated to cover <em>terminfo</em>, this is useful,
to a point: it omits any discussion of color, and the
discussion of line-drawing is cursory (superficial).</p>
<p>Strang also wrote <em>Programming with Curses</em> (1986),
but that is not useful because it describes only 4.3BSD
curses.</p>
</li>
<li>
<p><a name="book_gomez" id="book_gomez"><em>Character User
Interface Programming</em> (UNIX SVR4.2)</a>. Edited by Claro
Gomez. <em>UNIX Press</em>, Prentice-Hall, Inc. 1993. 720
pages. ISBN: 0-13-042581-8.</p>
<p>The SVr4.2 book <em>Programming with UNIX System
Calls</em> (1992) refers to this book for details on FMLI
(not implemented by ncurses) and <em>Extended Terminal
Interface</em> (ETI). ncurses provides libraries which
correspond to the latter. The book is presented in tutorial
manner, not a technical reference as such. It refers the
reader to the manual pages for details. Interestingly, the
system calls book's section mentioning <em>Character User
Interface Programming</em> illustrates a technical blunder by
implying that these two lines are the same length:</p>
<blockquote>
<pre class="code-block">
ETI is <strong>a great</strong> package for creating forms and menus.
ETI is <strong>the best</strong> package for creating forms and menus.
</pre>
</blockquote>
<p>About 40% of the book (chapters 6 through 13) covers the
ETI consisting of the <a href="man/panel.3x.html">panel</a>,
<a href="man/menu.3x.html">menu</a>, and <a href=
"man/form.3x.html">form</a> libraries as well as the soft-key
support added to SVr4.2 curses. Only the last feature
(<a href="man/curs_slk.3x.html">soft-keys</a>) was
incorporated in <a href=
"http://pubs.opengroup.org/onlinepubs/7908799/xcurses/slk_clear.html">
X/Open Curses</a>.</p>
</li>
</ul>
<h3 id="other_langs-id"><a name="other_langs" id=
"other_langs">Language bindings:</a></h3>
<ul>
<li>
<p><a href="/ncurses/Ada95.html">Ada95 binding, from
ncurses</a></p>
</li>
<li>
<p><a href=
"http://www.pitman.co.za/projects/charva/index.html">CHARVA
(Java binding)</a></p>
</li>
<li>
<p><a href=
"http://common-lisp.net/project/cl-ncurses/">Common Lisp
binding</a></p>
</li>
<li>
<p><a href=
"http://efsa.sourceforge.net/archive/ecurses/ecurses.htm">Eiffel
binding</a></p>
</li>
<li>
<p><a href=
"http://spiderape.sourceforge.net/plugins/ncurses/">JavaScript
binding</a></p>
</li>
<li>
<p><a href=
"http://www.mtu-net.ru/aborovsky/lincrt/lincrt-lib.html">LinCRT
(Kylix binding)</a></p>
</li>
<li>
<p><a href=
"http://caml.inria.fr/cgi-bin/hump.en.cgi?contrib=100">OCaml
binding</a></p>
</li>
<li>
<p><a href=
"http://search.cpan.org/search%3Fmodule=Curses">Perl
binding</a></p>
</li>
<li>
<p><a href="http://www.php.net/manual/en/ref.ncurses.php">PHP
binding</a></p>
</li>
<li>
<p><a href=
"http://docs.python.org/library/curses.html">Python
binding</a></p>
</li>
<li>
<p><a href="http://ncurses-ruby.berlios.de/">Ruby binding</a></p>
</li>
<li>
<p><a href=
"http://www.schwartzcomputer.com/tcl-tk/tcl-tk.html">Tcl/Tk
Extensions & Information Page -> ncurses cTk</a></p>
</li>
</ul>
<h3 id="other_impls-id"><a name="other_impls" id=
"other_impls">Other implementations:</a></h3>
<ul>
<li>
<p id="other-pdcurses"><a name="pdcurses" href=
"http://pdcurses.sourceforge.net/" id="pdcurses">PDCurses</a></p>
</li>
<li>
<p id="other-netbsd"><a name="netbsd" href=
"/ncurses/ncurses-netbsd.html" id="netbsd">NetBSD</a></p>
</li>
<li>
<p id="other-openbsd"><a name="openbsd" href=
"/ncurses/ncurses-openbsd.html" id="openbsd">OpenBSD</a></p>
</li>
</ul>
<h3 id="other_appls-id"><a name="other_appls" id=
"other_appls">Related applications:</a></h3>
<ul>
<li>
<p><a href="http://xterminal.sourceforge.net/">Xterminal's
Home Page</a></p>
</li>
<li>
<p><a href="/cdk/cdk.html">cdk</a> Curses Development Kit (a
library of widgets)</p>
</li>
<li>
<p><a href="/dialog/dialog.html">dialog</a> Script-driven
curses widgets</p>
</li>
</ul>
<h3 id="ref_obsolete-id"><a name="ref_obsolete" id=
"ref_obsolete">Technically obsolete, but often cited:</a></h3>
<ul>
<li>
<p><a href=
"https://web.archive.org/web/20060315053358/http://docs.freebsd.org/44doc/#psd">
4.4BSD Documents -> original curses</a></p>
</li>
<li>
<p><a href=
"http://www.ditec.um.es/~piernas/manpages-es/otros/tutorial-ncurses.html">
Escribir Programas con NCURSES</a></p>
</li>
<li>
<p><a href="/ncurses/ncurses-intro.html">Writing Programs
with NCURSES</a></p>
</li>
<li>
<p><a href="hackguide.html">A Hacker's Guide to Ncurses
Internals</a></p>
</li>
</ul>
<h3 id="ref_reallyold-id"><a name="ref_reallyold" id=
"ref_reallyold">Really old stuff</a></h3>
<ul>
<li>
<p>As mentioned, the <a href="#using_illumos">illumos</a>
sources are useful for comparison—up to a point. Those
are based on the OpenSolaris release in 2005. It was not a
complete Solaris source-release. For instance, some parts
(such as FMLI) were not included.</p>
<p>The copyright notices are helpful, but not definitive
because they reflect only when someone recorded that a file
was added to the AT&T sources, rather than when the
program was written.</p>
</li>
<li>
<p>For earlier implementations, the <a href=
"http://www.mckusick.com/csrg/">CSRG cdroms</a> and Jonathan
Gray's <a href=
"https://github.com/jonathangray/csrg">repository</a>
(converted from SCCS) are helpful. Both have problems: the
2BSD snapshots include files dated later than 3BSD, while the
SCCS history goes back only to the end of 1979 (with six
checkins), and checkins were not always done in a timely
manner.</p>
<p>The copyright dates in the source code are not helpful
either, for a different reason. Early in 1985 (before the
release of 4.3BSD (1986)), the developers added copyright
notices for about half the source files, dating those to
“1980” which is misleading. Many of those files
were first published in 4.2BSD (1983), and did not exist in
1980.</p>
</li>
</ul>
<h3 id="ref_misleading-id"><a name="ref_misleading" id=
"ref_misleading">Interesting but misleading:</a></h3>
<ul>
<li id="misinfo-termhow2">
<p><a href=
"http://www.tldp.org/HOWTO/Text-Terminal-HOWTO.html">Text-Terminal-HOWTO</a>.<br>
I find the deliberate misstatements in this one to be
fascinating. Still, there is some useful information as
well.</p>
</li>
<li id="misinfo-haskell">
<p><a href=
"http://hackage.haskell.org/cgi-bin/hackage-scripts/package/nanocurses">
nanocurses (Haskell binding)</a><br>
<a href=
"https://github.com/skogsbaer/hscurses/blob/f63d98aae747ef2aef41b4a2c35be451b14c7878/UI/HSCurses/Curses.hsc#L31">
It says</a> (referring to the ncurses manpages):</p>
<blockquote>
<p>Sections of the quoted documentation are from the
OpenBSD man pages, which are distributed under a BSD
license.</p>
</blockquote>
<p>First noticed in September 2008, this misattribution was
still present as of July 2019, e.g., in the Debian <a href=
"https://packages.debian.org/search?keywords=libghc-hscurses-dev">
libghc-hscurses-dev</a> package (according to “git
blame” the upstream comment was added in 2005).</p>
<p>However, there is no “official” Haskell
binding for ncurses. Other choices present other
problems:</p>
<ul>
<li>a <a href=
"http://hackage.haskell.org/package/terminfo">terminfo</a>
package found <a href=
"https://github.com/judah/terminfo">here</a>, which is
undocumented. Reading the source hints that the developer
does not understand how to develop thread-safe code.</li>
<li>another <a href=
"http://hackage.haskell.org/package/terminfo-hs">terminfo</a>
package found <a href=
"https://github.com/chreekat/terminfo-hs">here</a> also
undocumented but (reading the source) it assumes ncurses
with $HOME/.terminfo; but it does not handle ncurses 6.1
extended numbers (the last update to source-code was in
2015).</li>
</ul>
</li>
<li id="misinfo-openbsd">
<p>Aside from a few grammatical and spelling fixes, OpenBSD
developers have not contributed to ncurses documentation.
That does not mean that the ncurses documentation in OpenBSD
is identical. OpenBSD has made some questionable changes,
e.g., the <a href=
"https://man.openbsd.org/reset#HISTORY">history</a> and
<a href="https://man.openbsd.org/reset#AUTHORS">authors</a>
sections in the <a href=
"https://man.openbsd.org/reset">tset</a> manual page (compare
with <a href="man/tset.1.html#h2-HISTORY">ncurses</a>).</p>
</li>
<li id="misinfo-interix">
<p>Even when the ncurses documentation is used without
modification, it can still be misleading. For example,
Interix (a “client system” or
“environment” (like OS/2 EMX, U/Win, Cygwin,
MSYS2) came with a port of ncurses.</p>
<p>In the first announced version (e.g., 3.0), that appeared
to be <a href="ncurses-license.html#patch_961130">ncurses
1.9.9g</a> based on the header files. However its
documentation was a compressed help file “.chm”
which used an earlier set of documentation from early 1996,
e.g., <a href="ncurses-license.html#ncurses_1_9_9e">ncurses
1.9.9e</a>. The disparity was evident due to the way
resizeterm and wresize were <a href=
"ncurses-license.html#ncurses_1_9_9">documented</a>.</p>
<p>The final version of Interix 3.5 (aka “SFU” or
“SUA”) with updates to 2008 came with ncurses 4.2
(19980228) (apparently completed by <a href=
"https://groups.google.com/forum/#!topic/comp.lang.tcl/Uc4oo1Kco68">
Rodney Ruddock</a> in September 1999). The documentation was
not updated to match the software. Besides the <a href=
"man/resizeterm.3x.html">resizeterm</a> issue, the TechNet
page <em><a href=
"https://technet.microsoft.com/en-us/library/bb463194.aspx">Curses
Applications on Interix</a></em> for 3.0 mentions a problem
which was fixed in <a href="NEWS.html#t960615">June
1996</a>:</p>
<blockquote>
<p class="code-block">function calls to <em>getbkgd()</em>
needs to be replaced by <em>wgetbkgd()</em></p>
</blockquote>
</li>
<li id="dead-bugreport">
<p>But Interix is dead, last seen in Windows 7 Ultimate
(January 14, 2020). This <a href=
"https://web.archive.org/web/20201231011720/https://jdebp.eu/FGA/interix-terminal-type.html">
page</a> is an example of a dead bug report. It was <a href=
"NEWS.html#t20170729">addressed</a> in ncurses in 2017.</p>
</li>
<li id="misinfo-csharp">
<p>A C# binding for curses, which supports some of ncurses
and PDCurses extensions, first noted in mid-2009 <a rel=
"nofollow" href=
"https://en.wikipedia.org/w/index.php?title=Ncurses&diff=prev&oldid=297445477">
here</a> (apparently added anonymously by the program's
author). Its <a href=
"http://curses-sharp.sourceforge.net">page</a> claimed that
"Virtually every function in curses has its managed
counterpart." I noted that it implemented less than half of
the functions in ncurses 5.7 (206/414). As of early 2013, it
is (like most SourceForge projects), apparently dead.</p>
</li>
<li id="misinfo-ansiseq">
<p>The treatment of escape sequences <a rel="nofollow" href=
"http://en.wikipedia.org/wiki/ANSI_escape_code">here</a> is a
mish-mash of incorrect information from the DOS/Windows and
Unix environments. There are several areas of confusion,
e.g., mistaking common practice for standardization (and
introducing confusion about the scope of the standards), as
well as over-generalization. The worst offenders are of
course <a href=
"/personal/not-anonymous.html">anonymous</a>.</p>
<p>As an example of the problems in that source, in <a rel=
"nofollow" href=
"https://web.archive.org/web/20221211234431/https://stackoverflow.com/questions/14693701/how-can-i-remove-the-ansi-escape-sequences-from-a-string-in-python">
<em>How can I remove the ANSI escape sequences from a string
in python</em></a> each of the answers to the question which
cites that source has at least one error.</p>
</li>
<li id="misinfo-python">
<p>The Python binding and tutorial bears some comment. On
reflection, the comment is involved (see <a href=
"/ncurses/ncurses-python.html">this page</a>).</p>
</li>
<li id="misinfo-colorman">
<p>The accepted answer for <a href=
"http://unix.stackexchange.com/questions/119/colors-in-man-pages">
<em>Colors in Man Pages</em></a> has some issues:</p>
<ul>
<li>It goes to some effort to state that termcap is better,
and that <code>less</code> <em>uses</em> termcap, but
explicitly uses the terminfo-based <a href=
"/ncurses/man/tput.1.html">tput</a> utility.</li>
<li>It introduces some capabilities which are not supported
by the <a href=
"http://www.greenwoodsoftware.com/less/"><code>less</code></a>
pager, i.e., for superscripts and subscripts.</li>
</ul>
</li>
<li id="misinfo-reset">
<p>The accepted answer for <a href=
"http://unix.stackexchange.com/questions/79684/fix-terminal-after-displaying-a-binary-file/79686#79686">
<em>Fix terminal after displaying a binary file</em></a> has
some issues:</p>
<ul>
<li>
<p>At the outset, a figure is shown which is actually
irrelevant to the question. It shows the effect of
sending a binary file to the terminal, but all of the odd
characters are the Unicode <a href=
"http://unicode.org/charts/PDF/UFFF0.pdf"><em>replacement
character</em></a>. That is</p>
<blockquote>
<p class="code-block">used to replace an incoming
character whose value is unknown or unrepresentable in
Unicode</p>
</blockquote>
<p>One of the <a href=
"https://www.cl.cam.ac.uk/~mgk25/ucs/man-utf-8.html">claimed
advantages</a> of UTF-8 is that it is <em>stateless</em>.
In this situation, there is no action needed by the user
to get the terminal to stop printing replacement
characters, since the next output character is checked
without regard to the previous character.</p>
<p>If the terminal were not in UTF-8 mode, it would not
print replacement characters, and users <em>expect</em>
it to show line-drawing characters, e.g.,. as in <a href=
"http://unix.stackexchange.com/questions/50752/how-to-fix-a-terminal-after-a-binary-file-has-been-dumped-inside-it">
<em>How to fix a terminal after a binary file has been
dumped inside it?</em></a>, or (older) <a href=
"http://tldp.org/HOWTO/Keyboard-and-Console-HOWTO-4.html">
<em>4. Resetting your terminal</em></a> in <a href=
"http://tldp.org/HOWTO/Keyboard-and-Console-HOWTO.html"><em>
The Linux keyboard and console HOWTO</em></a>. But bear
in mind that the HOWTO (2002) is fairly recent: the
<a href=
"/ncurses/man/tset.1.html#h2-HISTORY"><code>reset</code></a>
program dates from around 1980, and has been an FAQ ever
since.</p>
</li>
<li>
<p>After the interesting picture, two methods are
suggested for fixing the terminal. For the first, the
advice is to</p>
<blockquote>
<p class="code-block">1. Hit Control + C a couple of
times (Ctrl+C)<br>
2. Type the command reset and hit return</p>
</blockquote>
<p>That is partly helpful. No reason is given for using
control/C, but suppose the binary file had sent a control
to the computer asking it to do something (without
providing a newline to complete the command). The
<code>reset</code> command does two (types of) thing:</p>
<ol>
<li>it resets the terminal <em>modes</em> (in the
computer's terminal driver)</li>
<li>it resets the terminal itself (using escape
sequences).</li>
</ol>
<p>Actually, the first part should not be needed, since
the escape sequences possibly echoed by the binary file
will not change the terminal <em>modes</em>. But typing
<code>reset</code> is easy.</p>
</li>
<li>
<p>The other method says in effect to do each of the
steps that <code>reset</code> would do, as separate
commands. No explanation is given (nor would it help).
The <em>reason</em> why one would use <code>stty
sane</code> is to cleanup after a program which modified
the terminal <em>modes</em>, e.g., from a text editor.
That would be a different question.</p>
<p>However, running <code>stty sane</code> may not
restore your terminal to a state that you expect. It uses
settings built into the <code>stty</code> program which
may have no relation to the settings established when you
logged in. For instance:</p>
<ul>
<li>On some platforms (Solaris, Linux), it changes the
<code>erase</code> character to ASCII DEL (127) —
inconsistent with normal usage for the first, but
consistent with the second.</li>
<li>But on HPUX, it changes <code>erase</code> to
<strong><code>#</code></strong> (and it changes the
<code>intr</code> character from control/C to ASCII
DEL, and kills the <code>kill</code> character).</li>
<li>On Unix platforms, the same command also changes
the parity handling, and turns off hardware tabs.</li>
</ul>
</li>
<li>
<p>Despite all of that, there was some value to the
answer: it prompted a review of the documentation for
<a href=
"/ncurses/man/tset.1.html#h2-HISTORY"><code>reset</code></a>
and <a href=
"/ncurses/man/tput.1.html#h2-HISTORY"><code>tput</code></a>
(and improvements to the programs, so that
“<code>tput reset</code>” would have the same
effect as “<code>reset</code>”).</p>
</li>
</ul>
</li>
<li id="misinfo-linfo">
<p>Noticed in addressing <a href=
"/ncurses/ncurses-license.html#issues_expat">some issues</a>
regarding the ncurses license, <a href=
"http://www.linfo.org">this site</a> is (like <a href=
"https://web.archive.org/web/20160322101233/http://www.osscc.net/en/">
another</a>) apparently an anonymous work by an individual
posing as a group of people for the sole purpose of
disseminating misinformation.</p>
</li>
<li id="misinfo-man7">
<p>On a lighter note (partly), while looking for a suitable
webpage for online manual pages, I noticed <a href=
"http://man7.org/linux/man-pages/man3/ncurses.3x.html">this
page</a>. Unlike <a href=
"http://linux.die.net/man/3/ncurses">another site</a>, its
formatting is reasonable, and is reasonably complete.
However:</p>
<ul>
<li>its ncurses-related manual pages are generated from a
repository based on my development patches for ncurses,
but</li>
<li>it does not process the sources to fill in
configuration details (such as the actual name of the
programs, the version information), and</li>
<li>it lacks most of the hyperlinks which are created by
<a href="/scripts/man2html.html">man2html</a> (compare with
<a href="man/ncurses.3x.html">my site</a>), and</li>
<li>the boilerplate at the bottom probably should point to
this <a href="/ncurses/">ncurses page</a>, rather than
merely to the release announcement. I put a lot of
information and links into the release announcements, but
“home page” it is not. At the time of release
for ncurses 6.1, according to FSF's <a href=
"https://web.archive.org/web/20180129060116/https://directory.fsf.org/wiki/GNU">
Free Software Directory</a>, my site was the homepage
(<em>dickey.his.com</em>, which in turn forwards to
<em>invisible-island.net</em>).</li>
</ul>
</li>
<li id="misinfo-homepage">
<p>Speaking of “home page”, Eric Raymond at one
point had what he termed an <a href=
"https://web.archive.org/web/19970605130234/http://www.ccil.org/~esr/ncurses.html">
"ncurses resource page"</a>. After the <a href=
"ncurses-license.html">licensing issues</a> were resolved, he
modified his terminfo page to state that "there is no
resource page for ncurses", and a few years later, again
modified his <a href=
"https://web.archive.org/web/20010620080924/http://hurkle.thyrsus.com/~esr/terminfo/index.html">
terminfo page</a> to point to the release announcement as the
"ncurses home page".</p>
</li>
</ul>
<h2 id="copyright_text-id"><a name="copyright_text" id=
"copyright_text">Copyright</a></h2>
<p>
Copyright © 1997–2024, 2025 by Thomas E. Dickey
<dickey@invisible-island.net><br>
All Rights Reserved.</p>
<p>Permission to use, copy, modify, and distribute this software
and its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
the above listed copyright holder(s) not be used in advertising
or publicity pertaining to distribution of the software without
specific, written prior permission.</p>
<p>THE ABOVE LISTED COPYRIGHT HOLDER(S) DISCLAIM ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE ABOVE LISTED
COPYRIGHT HOLDER(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.</p>
</body>
</html>