Thomas E. Dickey
$Date: 1998/03/29 21:53:50 $
Contents
Ncurses (new curses) is a freely distributable "clone" of
System V Release 4.0 (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).
The major ncurses developers (exclusive of Pavel Curtis, who put his work in
the public domain several years ago) recently assigned their copyright to the
Free Software Foundation, which has promised to use the following distribution
terms for at least five years.
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:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
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.
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.
Ncurses is free software.
It is not `open source'.
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.
By relabeling free software (and revising the order of causes and events),
the supporters of `open software' are
doing the development community a disservice.
The following are known to work (I've built these):
- AIX 3.2.5 (cc)
- BSD/OS 2.1, 3.0
- CLIX 3.1 (cc, gcc 2.5.8)
- Digital Unix (aka OSF1) 3.2, 4.0 (cc)
- FreeBSD 2.1.5 (gcc 2.6.3)
- GNU/Linux (gcc 2.7.2, kernel 2.0.29 libc 5.3.12)
- HP/UX 9.03, 9.05 (gcc 2.7.2)
- IRIX 5.2 (cc, gcc 2.8.0)
- IRIX 6.2 (cc/CC, gcc 2.8.0)
- OS/2 EMX 0.9b (gcc 2.7.2)
- SCO 3.2v4.2 (cc)
- Solaris 2.4, 2.5.1, 2.6 (cc, gcc 2.7.2)
- SunOS 4.1.x (gcc 2.7.2)
- Unixware 1.1.2 (cc)
In addition, the following have been reported to work (since 1.9.8a):
- AIX-3.2.5 (gcc-2.7.2)
- Amiga (gcc)
- GNU/Linux (gcc-2.5.8, kernel 1.2.8)
- HP/UX 9.05, 10.2 (ANSI cc)
- Interactive Unix (ISC4.0)
- NeXT CUBE with NS 3.2:
- ncurses 1.97a for OS/2 is at phi.sinica.edu.tw(140.109.14.4):/pub/os2/port
- sysV68 R3V7.1 (gcc-2.5.8)
The current version is 4.2, available at the GNU ftp site, as well as
Ftp: ftp://www.clark.net/pub/dickey/ncurses/ncurses-4.2 (gzip'd tar)
I also maintain patches toward the next release (4.3)
Ftp: ftp://www.clark.net/pub/dickey/ncurses/4.2
There have been a number of releases of ncurses.
Some are available on CDROM (e.g., 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.
- 4.2
(2 March 1998).
This implements C++ bindings for the library, as well
as extensions to support runtime definition of keycodes.
- 4.1
(16 May 1997).
This release features support for gpm (mouse on Linux console), and adds
an extension for default colors.
- 4.0
(24 December 1996).
A change in version numbering addresses a problem exposed by the GNU/Linux
ld.so.1.8.5 program.
- 1.9.9g
(1 December 1996).
- 1.9.9e 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.
- 1.9.8a (ok)
- 1.9.7a (ok)
- 1.9.4 is the oldest version that you should consider installing.
It comes with Slackware 3.0; earlier releases have a number
of problems, including incompatible terminal descriptions.
You must first install the terminfo data (i.e., "make install.data").
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.
See also
How are patches organized?
I name development patches after the base release,
with the patch date in the form
yymmdd (though that may change in a few years ;-).
There are also a few rollup patches between releases:
Download:
The rollup patches include all patches through the cited version. You must
apply them to the base release, e.g.,
zcat ncurses-4.1.tar.gz |tar xf -
cd ncurses-4.1
sh ../patch-4.1-4.2.sh
I have tested the rollup patches with patch 2.1 and 2.5, adjusting for their
respective limitations.
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:
#!/bin/sh
# uses the -e switch on tic to selectively load descriptions that are
# interesting for my testing.
if test -f terminfo.src ; then
TMP=/tmp/load$$
trap "rm -f $TMP" 0 1 2 5 15
tic -s -1 -I -e'
ansi, ansi-m, color_xterm, ecma+color,
klone+acs, klone+color, klone+sgr, klone+sgr-dumb,
linux, pcansi-m, rxvt, vt52,
vt100, vt102, vt220, xterm' terminfo.src >$TMP
tic -s $TMP
else
echo 'oops'
exit 1
fi
The most reliable terminfo database is that distributed with ncurses 4.2,
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.
As of this date (7 March 1998)
the terminfo database at
http://www.ccil.org/~esr/terminfo.html
does not appear to be actively maintained; ncurses 4.2 corrects several
compatibility issues with respect to SVr4 which have not been incorporated
there.
Since the release of ncurses 4.1, there are additional fixes which also
are not in that database.
If you choose to not install the ncurses terminfo database, we have found that
the SVr4 systems (Solaris, IRIX 6 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.
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.
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 My terminal doesn't recognize color.
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 private database.
Check the terminal description, to see if it is installed properly
(e.g., in /usr/share/terminfo) by looking at the output of
infocmp.
- It should contain the following capabilities:
orig_pair or orig_colors
and max_colors
and max_pairs
- as well as
set_foreground and set_background
or set_a_foreground and set_a_background
or set_color_pair
The orig_pair and orig_colors capabilities
will not be required in ncurses 4.3 (SVr4 curses works properly without them).
The most common complaint is that "I can see colors using ls,
but not with ncurses applications". This is due to not having installed
the terminfo database.
$COLORTERM is an environment variable used by some applications
developers who are constructing programs that run on rxvt,
a terminal emulator, using the slang library. It tells
the slang library to ignore the terminal description,
using a set of built-in capability strings which produce ISO 6429 (aka "ANSI")
color on that emulator. The choice of capability strings may work for other
emulators, but in general does not (slang does not support
terminals which lack the back color erase capability, such as
dtterm).
Viewed as a fallback, $COLORTERM 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 slang.
Usually this happens because you have not installed the terminfo
database, or it is not in the proper location.
If you do not, and the application is unable to locate the terminfo
database, the ncurses library attempts to recover by reading
/etc/termcap,
translating it into a private terminfo database
$HOME/.terminfo
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 terminfo database).
You may have installed terminfo in the wrong, or an obsolete location:
- On GNU/Linux, FreeBSD and NetBSD the preferred location for terminfo
is /usr/share/terminfo, with a symbolic link from
/usr/lib/terminfo for compatibility with older applications.
Prior to 1.9.9g, the configure script defaulted to a /usr/local
prefix rather than /usr, necessitating an explicit
configure --prefix=/usr
- 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.
- Also prior to 1.9.9g, the actual terminfo directory resided in
/usr/lib/terminfo.
It was moved to /usr/share/terminfo 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 mc and screen 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.
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.
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.
If you do not wish to use $HOME/.terminfo, ncurses 4.2 works properly
if you replace that directory with a file so it cannot write terminfo
entries which would conflict with the standard location.
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.
Ncurses sets the mouse tracking mode as a result of
your application's calls to mousemask,
which is an extension.
This is the way SVr4 curses works.
From the XSI Curses specification
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.
If your terminal description does not contain
the orig_pair or orig_colors
capability, you will be unable to reset colors to the pre-curses state.
This happens, for example, with aixterm.
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, rxvt and the
XFree86 xterm.
Ncurses 4.1 provides an extension use_default_colors() 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.
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.
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.
This is corrected in ncurses 4.1, but incorrect in all preceding versions.
It is possible to make an application resize when running in a windowing
environment (e.g., in an xterm).
This is not a feature of standard SVr4 curses,
though some curses implementations (e.g., HP-UX) support this.
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.
- endwin/refresh when invoked will briefly exit curses
and reinitialize the display, picking up the new screen size.
Ncurses will reallocate the WINDOW data (e.g., curscr, stdscr) to reflect
the new limits.
- resizeterm can be invoked directly to make ncurses resize its
WINDOW data.
I use it in my directory editor
ded
to achieve flicker-free resizing via
a signal handler for SIGWINCH.
(The documentation for HP-UX curses implies that they use a similar
approach; I have been unable to make it work.)
In principal, you should be able to pipe to/from a curses application.
However, there are caveats:
- 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 tee
to show the output while redirecting.
- Ncurses obtains the screen size by first using the environment variables
LINES and COLS (unless you have disabled it with the use_env call),
then trying to query the output file pointer, and then
(finally) the terminal description. If you are redirecting output, then
a query based on the file pointer will always fail, resulting in the terminal
description's size.
- Similarly, you can redirect input to an ncurses application.
However, I have observed that the use of setbuf
(for better output buffering) interferes with the use of stream I/O
on GNU/Linux (and possibly other platforms).
Invoking setbuf causes
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.
Ncurses works correctly with the Linux GPM (general purpose mouse) library.
However, some distributors have tampered with the library, making it
not generally useful, by linking in a portion of the BSD curses library.
The newer versions (1.10 and up) of GPM come with a configure script, which
allows the system builder to suppress this from the shared library.
Note that if you do rebuild the GPM library, you may have to rebuild some
of the applications (such as emacs).
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.
Contact the current maintainers at
bug-ncurses@gnu.org.
To join the ncurses mailing list, please write email to
bug-ncurses-request@gnu.org containing the line:
subscribe <name>@<host.domain>
This list is open to anyone interested in helping with the development and
testing of this package.
Otherwise, you may email directly to the maintainers, currently:
If you send email only to one of the other authors, I may not see it.
We prefer that bug reports go to the mailing list.
I get about half of my bug reports via the ncurses mailing list, some
by reading news groups, and the others via direct email.
More than half of the changes that get introduced without review in the
ncurses mailing list introduce a bug.
So I find it necessary to review proposed changes.
When sending patches:
- Explain the problem that you are fixing.
- Please use "diff -u" format, even if you are creating a new file.
Otherwise I may overlook it, if it is at the end of a long patch.
(It is reasonable to send binary files in uuencoded form, but there are
few of those).
- Don't send patches that include the 'configure' script
if the difference therein can be regenerated using autoconf.
- Do specify the version of ncurses that you are patching.
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:
config.cache
config.log
config.status
include/ncurses_cfg.h
log from running 'configure', with options
log from running 'make', with options
A uuencoded/gzip'd/tar file is preferred, because the logfiles can be
awkward to email.
You may find the
scripts
which I use for building and saving logfiles useful.
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.
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.
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.
The remainder of my backlog consists of issues which highlight
incompatibilities between ncurses and SVr4 curses;
these are listed in the TO-DO file.
I use the following guidelines:
- extensions (deviations from SVr4 curses) are allowed only if they
do not modify the documented/observed behavior of the API.
- I test behavior using Solaris 2.4 or 2.5 curses, and use the manual pages
for Solaris in conjunction with the X/Open Curses documentation.
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.
Generally (unless we find a serious error), I issue patches on Saturdays,
since validating patches takes time.
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.
- User-supplied patches that require no modification are always
tagged with their name, making it simpler to follow the revision history.
- User-supplied patches that require some modification are still
tagged, but my patch will have followup changes.
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 ci.
Copyright 1997, 1998 by Thomas E. Dickey <dickey@clark.net>.
All Rights Reserved.
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.
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.