Thomas E. Dickey
$Date: 2001/05/05 18:13:38 $
pcurses,
written by Pavel Curtis.
For details, see the NEWS file in the source distribution. It accurately reflects contributions since 1.9.9e.
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.
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.
Ftp: ncurses.tar.gz (gzip'd tar)
I also maintain patches toward the next release (5.3 or 6.0)
Ftp: ftp://dickey.his.com/ncurses/5.2
ld.so.1.8.5 program.
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.
I name development patches after the base release, with the patch date in the form yymmdd (though that may change in a few years ;-).
zcat ncurses-4.2.tar.gz |tar xf - cd ncurses-4.2 for n in ../ncurses-4.2-*.gz ; do zcat $n | patch -p1 ; done
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.shI have tested the rollup patches with patch 2.1 and 2.5, adjusting for their respective limitations.
#!/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
infocmp
installed (note that ncurses 5.0 infocmp's support for fallback descriptions
is done differently from ncurses 4.2).
But fallback definitions are really only useful in embedded applications, where no external files are wanted.
As of this date (9 July 2000) the terminfo database at http://www.tuxedo.org/~esr/terminfo.html 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.
Here are links to current versions:
terminfo.src.gz
termcap.src.gz
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.
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.
Other systems (e.g., Digital Unix 4.x and the older AIX 3.2.5) use different formats and are not compatible.
However, terminfo source is compatible and can be compiled using the appropriate tool (usually tic). 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.
The ncurses tic program recognizes a wider range of input than other terminfo compilers, including extensions coordinated with infocmp that make it easier to use:
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., vi, telnet).
For systems such as GNU/Linux, that is feasible. But not Solaris or other
proprietary systems. For those, I recommend configuring with the
--disable-overwrite option. This directs the configure
script to install the library so you would
link it as -lncurses, not adding
a symbolic link to make it link as -lcurses.
The --disable-overwrite option also installs the header files such
as curses.h in a subdirectory, e.g.,
/usr/local/include/ncurses/curses.h, thereby avoiding a
(mis)feature of recent versions of gcc which look first in
/usr/local/include for header files. Since the vendor's compilers
do not do this, a common problem results: compiling with
/usr/include/curses.h and linking with
/usr/local/lib/libcurses.a.
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.
/usr/share/terminfo) by looking at the output of
infocmp.
orig_pair or orig_colors
max_colors
max_pairs
set_foreground and set_background
set_a_foreground and set_a_background
set_color_pair
orig_pair and orig_colors capabilities
are not required in ncurses 5.0 (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.
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 (e.g.,
terminals which lack the back color erase capability, such as
Tera Term,
CDE dtterm and
nxterm).
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.
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/.terminfoThis 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:
/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
/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.
Wrong answer.
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:
tic 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.
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).
The problem is this:
With 5.0, the configure script provides two options
(--without-cxx and --without-cxx-binding).
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.
The Linux "make menuconfig" attempts to build a customized dialog
program called lxdialog. This uses ncurses, which
of course is why you are reading this question/answer.
make looks.
You are better off reading the INSTALLATION document for ncurses and configuring it and building it separately.
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.
Ncurses sets the mouse tracking mode as a result of
your application's calls to mousemask,
which is an extension.
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.
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.
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.)
wgetch function will return
a special keycode KEY_RESIZE when a resizing event is detected.
The signal handler also calls resizeterm
(Caveat: malloc and free
are not guaranteed to be safe for use in a signal handler).
tee
to show the output while redirecting.
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.
setvbuf
(for better output buffering) interferes with the use of stream I/O
on GNU/Linux (and possibly other platforms).
Invoking setvbuf 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.
setvbuf
function (or equivalent, depending on the platform).
The performance gain is noticable.
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 setvbuf
before invoking the subprocess and restore it when resuming.
That is, it should, but often cannot - that is the problem.
The standard says that setvbuf must be called only after
opening a stream and before performing any reads or writes with that stream.
If your application calls initscr, it uses the standard output,
which ncurses assumes has not been written to, to which ncurses then applies
buffering.
(Caveat:
The standard writers neglected to provide a mechanism for determining if
the stream is indeed buffered).
Adding a call to setvbuf 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 fflush is first given.
That is, it will produce a core dump.
The fix?
Use newterm to initialize ncurses and manage the input and
output streams yourself.
For instance, you may simply open /dev/tty for input and output,
and leave the standard input and output alone.
Note, however that some versions still link in a hook to the curses library.
You should verify that the shared library does not use the
symbol wgetch. Version 1.16 appears to be lacking the configure
script option to suppress this hook; removing libcurses.o from the list
of objects in gpm's Makefile works just as well.
Version 1.17 built correctly when I tested it, however, though the changelog
does not say.
The reset is specified in the terminal description, e.g.,
rs1=\Ec,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.
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:
clear=\E[H\E[J$<50>,Note: the
slang 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.
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).
If you must use the vt100 terminal description, you may consider setting the NCURSES_NO_PADDING environment variable which is implemented in recent beta versions of ncurses (late 1998). That directs ncurses to ignore nonmandatory time delays in the terminal description.
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
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:
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).
configure' script
if the difference therein can be regenerated using autoconf.
config.cache config.log config.status include/ncurses_cfg.h log from running 'configure', with options log from running 'make', with optionsA 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.
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:
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.
ci.
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
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.