5 The ncurses (new curses) library is a free software emulation of
6 curses in System V Release 4.0 (SVr4), and more. It uses terminfo
7 format, supports pads and color and multiple highlights and forms
8 characters and function-key mapping, and has all the other SVr4-curses
9 enhancements over BSD curses. SVr4 curses became the basis of X/Open
12 In mid-June 1995, the maintainer of 4.4BSD curses declared that he
13 considered 4.4BSD curses obsolete, and encouraged the keepers of unix
14 releases such as BSD/OS, FreeBSD and NetBSD to switch over to ncurses.
16 Since 1995, ncurses has been ported to many systems:
17 * It is used in almost every system based on the Linux kernel (aside
18 from some embedded applications).
19 * It is used as the system curses library on OpenBSD, FreeBSD and
21 * It is used in environments such as Cygwin and MinGW. The first of
22 these was EMX on OS/2 Warp.
23 * It is used (though usually not as the system curses) on all of the
24 vendor unix systems, e.g., AIX, HP-UX, IRIX64, SCO, Solaris,
26 * It should work readily on any ANSI/POSIX-conforming unix.
28 The distribution includes the library and support utilities, including
29 * captoinfo, a termcap conversion tool
30 * clear, utility for clearing the screen
31 * infocmp, the terminfo decompiler
32 * tabs, set tabs on a terminal
33 * tic, the terminfo compiler
34 * toe, list (table of) terminfo entries
35 * tput, utility for retrieving terminal capabilities in shell
37 * tset, to initialize the terminal
39 Full manual pages are provided for the library and tools.
41 The ncurses distribution is available at ncurses' homepage:
43 https://invisible-island.net/archives/ncurses/ or
44 https://invisible-mirror.net/archives/ncurses/ .
46 It is also available at the GNU distribution site
48 https://ftp.gnu.org/gnu/ncurses/ .
52 These notes are for ncurses 6.5, released April 27, 2024.
54 This release is designed to be source-compatible with ncurses 5.0
55 through 6.4; providing extensions to the application binary interface
56 (ABI). Although the source can still be configured to support the
57 ncurses 5 ABI, the reason for the release is to reflect improvements
58 to the ncurses 6 ABI and the supporting utility programs.
60 There are, of course, numerous other improvements, listed in this
63 The most important bug-fixes/improvements dealt with robustness
64 issues. The release notes also mention some other bug-fixes, but are
65 focused on new features and improvements to existing features since
72 These are new features:
73 * The low-level terminfo and termcap interfaces are used both by the
74 higher-level curses library, as well as by many applications.
75 The functions which convert parameterized terminal capability
76 strings for output to the terminal (tiparm and tparm) analyze the
77 capability string to determine which parameters are strings (i.e.,
78 addresses), versus numbers (not addresses).
79 The library's analysis of a capability string may differ from the
80 calling application's design if environment variables are used to
81 point to an invalid terminal database. This is a longstanding
82 problem with all implementations of terminfo, dating from the
84 Two new functions address this problem: by providing a function
85 which allows the calling application to tell ncurses how many
86 string-parameters to expect:
87 + tiscan_s helps applications check formatting capabilities
88 that would be passed to tiparm_s.
89 + tiparm_s provides applications a way to tell ncurses what the
90 expected parameters are for a capability.
91 * The ncurses library supports a compile-time feature (enabled with
92 the configure --enable-check-size option) which simplifies
93 initialization with terminals which do not negotiate window
94 (screen) size. This is done in setupterm, by providing for using
95 ANSI cursor-position report (in user6/user7 terminfo capabilities)
96 to obtain the screen size if neither environment variables or
98 The ncurses test-program with options "-E -T" demonstrates this
100 * add functions to query tty-flags in SCREEN
102 This release drops compatibility with obsolete versions of tack, e.g.,
107 These are improvements to existing features:
108 * In addition to the new, safer function tiparm_s, ncurses adds
109 checks to make the older tiparm, tparm and tgoto functions safer:
110 + the terminfo functions tiparm and tparm ensure that the
111 capability string comes from the terminal description which
112 ncurses loads, rather than from random data which the
113 application happens to have.
114 + the tgoto function disallows capabilities which its analysis
115 shows will attempt to use string parameters.
116 + ncurses uses internal functions which correspond to tiparm,
117 and tgoto which ensure that the capability strings which are
118 passed to these functions come from the loaded terminal
120 * improve check in lib_tparm.c, ensuring that a char* fits into a
122 * modify _nc_syserr_abort to use _nc_env_access, rather than only
124 * improve thread lock in lib_trace.c
125 * modify flushinp to use file descriptors in SCREEN, rather than
126 from TERMINAL, and check if they are for a terminal, like SVr4
127 * modify mcprint to use file descriptor in SCREEN, for consistency
128 * modify internal function _nc_read_file_entry to show relevant
130 * improve checks in internal function convert_string for corrupt
132 * review/improve handling of out-of-memory conditions
133 * limit delays to 30 seconds, i.e., padding delays in terminfo, as
134 well as napms and delay_output functions
135 * fix reallocation loop for vsnprintf in _nc_sprintf_string by
136 copying the va_list variable
137 * modify delscreen to limit the windows which it creates to just
138 those associated with the screen
139 * modify endwin to return an error if it is called again without an
140 intervening screen update
141 * modify wenclose to handle pads
142 * eliminate use of PATH_MAX in lib_trace.c
143 * provide for any CCHARW_MAX greater than 1
145 These are corrections to existing features:
146 * correct loop termination condition in waddnstr and waddnwstr
147 * improve parsing in internal function _nc_msec_cost, allowing a
149 * amend parameter check for entire string versus specific length in
150 winsnstr and wins_nwstr to match Solaris; make similar correction
152 * correct internal function wadd_wch_literal when adding a
153 non-spacing character to a double-width character
154 * correct definition of Charable macro for non-wide ncurses library
159 Several improvements were made to the utility programs. Some were done
160 to make the infocmp option "-u" option help refactor the terminal
165 + add limit checks for processing extended capabilities with
167 + correct initial alignment of extended capabilities, so that
168 the "-u" option can be used for more than two terminal types
169 + modify "-u" option to not report cancels for strings which
170 were already cancelled in a use'd chunk.
171 + correct an assignment "-u" for detecting if a boolean is
172 unset in a base entry and set in a use'd chunk, i.e., if it
177 + correct limit-check when dumping tc/use clause via "-I"
178 + check return value of _nc_save_str, in special case where
179 extended capabilities are processed but the terminal
180 description was not initialized
181 + modify check for multiply defined aliases to report problems
182 within the current runtime rather than for conflicts with
183 pre-existing terminal descriptions.
184 + disallow using $TERMINFO or $HOME/.terminfo when "-o" option
189 + add "-v" option to tput, to show warnings
190 + modify reset command to avoid altering clocal if the terminal
192 + modify reset feature to avoid 1-second sleep if running in a
197 Along with the library and utilities, improvements were made to the
199 * modify test_tparm to account for extended capabilities
200 * corrected mouse mask in test/testcurs.c
201 * modify test/clip_printw.c to optionally test non-wrapped updates
202 * modify test/test_mouse.c to use curses api for raw/noraw
203 * modify test/clip_printw.c to optionally test non-wrapped updates
205 There is one new demo/test programs:
208 This program shows the return-status from endwin with different
209 combinations of endwin (repeated), initscr, newterm.
213 There are several new terminal descriptions:
216 * linux+kbs for terminals which imitate xterm's behavior with Linux
219 * ms-vt100-16color, winconsole
220 * vt100+noapp, vt100+noapp+pc, xterm+app+pc, xterm+decedit from
222 * putty+cursor to reflect amending of modified cursor-keys in 2021
225 There are many changes to existing terminal descriptions. Some were
226 updates to several descriptions, using the infocmp "-u" option in a
227 script to determine which building-block entries could be used to
228 replace multiple capability settings (and trim redundant information).
230 Other changes include:
231 * document XF, kxIN and kxOUT
232 * add note on sun regarding wscons/cmdtool/shelltool
233 * remove DECCOLM+DECSCLM from foot
234 * add xterm+focus to foot+base
235 * add ecma+strikeout to putty
236 * use CSI 3J in vte-2017
237 * use oldxterm+sm+1006 in vte-2014
238 * modify xgterm to work around line-drawing bug
239 * add xterm focus mode 1004 to xterm+focus as fe/fd capabilities,
241 * add xterm+focus to alacritty+common
242 * add XR/xr, to work with vim, and use RV/rv to denote DA2 and its
244 * add XF flag to xterm+focus so that termcap applications can be
245 aware of terminals which may support focus in/out
246 * use xterm+focus in xterm-p370 and tmux
247 * remove xterm+sm+1006 from tmux
248 * NetBSD-related fixes for x68k and wsvt25
252 As usual, this release
253 * improves documentation by describing new features,
254 * attempts to improve the description of features which users have
256 * fills in overlooked descriptions of features which were described
257 in the NEWS file but treated sketchily in manual pages.
259 In addition to providing background information to explain these
260 features and show how they evolved, there are corrections,
261 clarifications, etc.:
263 + add assignment in CF_MAN_PAGES to fill in value for
264 TERMINFO_DIRS in ncurses, terminfo and tic manpages.
265 + clarify interaction of -R option versus -C, -I and -r in
267 + correct manpage description of panel_hidden.
268 + improve manpage description for addch versus unctrl format
269 used for non-printable characters.
270 + improve manpages discussing file descriptors in low-level
272 + improve description of search rules for terminal descriptions
274 + modify dist.mk to avoid passing developer's comments in
275 manpages into the generated html documentation.
276 + modify test-package "ncurses6-doc" to use manpage-aliases,
277 which in turn required a change to the configure script to
278 factor in the extra-suffix option when deriving alias names.
279 * New/improved history and portability sections:
280 + add information about "ttycap", termcap's forerunner, to
282 + document limitations of tparm, and error-returns in
284 + document limitations of tgoto, and error-returns in
286 * Other improvements:
287 + This release has many changes to improve the formatting and
288 style of the manpages.
289 + Manpages now use consistent section-naming, page headers and
290 footers (including the modification date for each page).
291 + Table layout has been revised.
293 There are no new manual pages (all of the manual page updates are to
296 Interesting bug-fixes
298 The changes to tparm, tgoto which improve the design of the low-level
299 interfaces are interesting, but are not bug-fixes per se.
301 Configuration changes
305 These are the major changes (aside from introducing tiparm_s):
306 * use wide-character (ncursesw) by default
307 * use opaque typedefs by default
309 However, most of the work on configure scripts was done to reduce
310 warnings within the configure script:
311 * intrusive warnings from GNU grep regarding fgrep and egrep
312 * fatal errors in compile-checks, arising from recent "Modern C"
313 efforts by some developers which caused longstanding configure
315 After repairing the configure script, none of that activity
316 affected ncurses because stricter warnings are used routinely in
319 Other improvements made to configure checks include
320 * use string-hacks in alloc_entry.c, alloc_type.c and hardscroll.c,
321 overlooked due to compiler changes in recent OpenBSD releases
322 * revise progs.priv.h to provide for NC_ISATTY reuse
323 * configure check for MB_LEN_MAX provides warning as needed
324 * trim a space after some "-R" options, fixing builds for
325 applications built using clang and ncurses on Solaris
326 * work around misconfiguration of MacPorts gcc13, which exposes
327 invalid definition of MB_LEN_MAX in gcc's fallback copy of
329 * modified experimental Windows driver works with xterm mouse
332 Configuration options
334 There are a few new configure options:
336 --disable-setuid-environ
337 Compile with environment restriction, so certain environment
338 variables are not available when running via a setuid/setgid
339 application. These are (for example $TERMINFO) those that allow
340 the search path for the terminfo or termcap entry to be
343 A setuid/setgid application inherits its environment variables
344 from the current user, in contrast to sudo which may limit the
345 environment variables that ncurses uses.
348 Compile-in feature to detect screensize for terminals which do
349 not advertise their screensize, e.g., serial terminals.
351 --with-abi-altered=NUM
352 Override the displayed (rather than compiled-in) ABI. Only
353 packagers who have created configurations where the ABI differs
354 from ncurses should be interested in this option.
356 --with-strip-program=XXX
357 When stripping executables during install, use the specified
358 program rather than "strip" overriding program chosen by the
359 install program for stripping executables.
361 These configure options are modified:
363 --with-pkg-config-libdir[=DIR]
364 The optional DIR parameter can now be "auto" to automatically
365 use pkg-config's library directory.
367 The default is $(libdir).
369 --with-xterm-kbs[=XXX]
370 The default is "auto" which tells the configure script to
371 choose BS or DEL according to platform defaults.
375 Many of the portability changes are implemented via the configure
377 * add/use configure check for clock_gettime, to supersede
379 * modify configure script check for pkg-config library directory to
380 take into account an older version 0.15.0 which used
381 PKG_CONFIG_PATH but not PKG_CONFIG_LIBDIR
382 * allow for MinGW32-/64-bit configurations to use _DEFAULT_SOURCE
383 * modify CF_XOPEN_SOURCE macro's amend default case to avoid
384 undefining _XOPEN_SOURCE if _POSIX_C_SOURCE is defined
385 * updated configure script macro CF_XOPEN_SOURCE, for uClibc-ng
386 * modify version-check for gcc/g++, now works for msys2
387 * build-fixes related to configure-options and/or platform:
388 + fix for --enable-fvisibility
389 + fix for unusual values of --with-rel-version
390 + fix for unusual values of --with-abi-version
391 + fix for --disable-tcap-names
392 + fix for termcap in nc_access.h
393 * other configure-script improvements:
394 + recent msys2 headers work with _DEFAULT_SOURCE; amend check
395 + use $ac_includes_default in most cases where stdlib.h should
397 + use #error consistently vs "make an error"
398 + add configure macro for gettimeofday vs inline check
400 Here are some of the other portability fixes:
401 * modify configure scripts/makefiles to omit KEY_RESIZE if the
402 corresponding SIGWINCH feature is disabled
403 * increase MB_CUR_MAX to 16, matching glibc's MB_LEN_MAX
404 * add BSD erase2 to characters handled by tset/reset
405 * use getauxval when available, to improve setuid/setgid checks
406 * set dwShareMode in calls to CreateConsoleScreenBuffer
407 * use CreateFile with "CONIN$", "CONOUT$" rather than GetStdHandle
408 to obtain a handle on the actual console, avoiding redirection in
409 the MinGW/Win32 configurations
410 * modify MinGW driver to return KEY_BACKSPACE when an unmodified
411 VK_BACK virtual key is entered
412 * modify MinGW configuration to provide for running in MSYS/MSYS2
413 shells, assuming ConPTY support
414 _________________________________________________________________
418 The ncurses package is fully upward-compatible with SVr4 (System V
420 * All of the SVr4 calls have been implemented (and are documented).
421 * ncurses supports the features of SVr4 curses including keyboard
422 mapping, color, form drawing with ACS characters, and automatic
423 recognition of keypad and function keys.
424 * ncurses provides work-alike replacements of SVr4 supplemental
425 libraries based on curses, but which were not specified by X/Open
427 + the panel library, supporting a stack of windows with backing
429 + the menu library, supporting a uniform but flexible interface
431 + the form library, supporting data collection through
433 * ncurses's terminal database is fully compatible with that used by
435 + ncurses supports user-defined capabilities that it can see,
436 but which are hidden from SVr4 curses applications using the
437 same terminal database.
438 + It can be optionally configured to match the format used in
439 related systems such as AIX and Tru64.
440 + Alternatively, ncurses can be configured to use hashed
441 databases rather than the directory of files used by SVr4
443 * The ncurses utilities have options to allow you to filter terminfo
444 entries for use with less capable curses/terminfo versions such as
445 the HP-UX and AIX ports.
447 The ncurses package also has many useful extensions over SVr4:
448 * The API is 8-bit clean and base-level conformant with the X/Open
449 Curses specification, XSI curses (that is, it implements all BASE
450 level features, and almost all EXTENDED features). It includes
451 many function calls not supported under SVr4 curses (but
452 portability of all calls is documented so you can use the SVr4
454 * Unlike SVr3 curses, ncurses can write to the rightmost-bottommost
455 corner of the screen if your terminal has an insert-character
457 * Ada95 and C++ bindings.
458 * Support for mouse event reporting with X Window xterm and FreeBSD
459 and OS/2 console windows.
460 * Extended mouse support via Alessandro Rubini's gpm package.
461 * The function wresize allows you to resize windows, preserving
463 * The function use_default_colors allows you to use the terminal's
464 default colors for the default color pair, achieving the effect of
466 * The functions keyok and define_key allow you to better control the
467 use of function keys, e.g., disabling the ncurses KEY_MOUSE, or by
468 defining more than one control sequence to map to a given key
470 * Support for direct-color terminals, such as modern xterm.
471 * Support for 256-color terminals, such as modern xterm.
472 * Support for 16-color terminals, such as aixterm and modern xterm.
473 * Better cursor-movement optimization. The package now features a
474 cursor-local-movement computation more efficient than either BSD's
476 * Super hardware scrolling support. The screen-update code
477 incorporates a novel, simple, and cheap algorithm that enables it
478 to make optimal use of hardware scrolling, line-insertion, and
479 line-deletion for screen-line movements. This algorithm is more
480 powerful than the 4.4BSD curses quickch routine.
481 * Real support for terminals with the magic-cookie glitch. The
482 screen-update code will refrain from drawing a highlight if the
483 magic- cookie unattributed spaces required just before the
484 beginning and after the end would step on a non-space character.
485 It will automatically shift highlight boundaries when doing so
486 would make it possible to draw the highlight without changing the
487 visual appearance of the screen.
488 * It is possible to generate the library with a list of pre-loaded
489 fallback entries linked to it so that it can serve those terminal
490 types even when no terminfo tree or termcap file is accessible
491 (this may be useful for support of screen-oriented programs that
492 must run in single-user mode).
493 * The tic/captoinfo utility provided with ncurses has the ability to
494 translate many termcaps from the XENIX, IBM and AT&T extension
496 * A BSD-like tset utility is provided.
497 * The ncurses library and utilities will automatically read terminfo
498 entries from $HOME/.terminfo if it exists, and compile to that
499 directory if it exists and the user has no write access to the
500 system directory. This feature makes it easier for users to have
501 personal terminfo entries without giving up access to the system
503 * You may specify a path of directories to search for compiled
504 descriptions with the environment variable TERMINFO_DIRS (this
505 generalizes the feature provided by TERMINFO under stock System
507 * In terminfo source files, use capabilities may refer not just to
508 other entries in the same source file (as in System V) but also to
509 compiled entries in either the system terminfo directory or the
510 user's $HOME/.terminfo directory.
511 * The table-of-entries utility toe makes it easy for users to see
512 exactly what terminal types are available on the system.
513 * X/Open Curses permits most functions it specifies to be made
514 available as macros as well. ncurses does this
515 + to improve performance, e.g., for operations composed of
516 simpler functions such as cursor movement following by adding
518 + to simplify the implementation by reusing functions which use
519 common parameters, e.g., the standard screen stdscr, and
520 + to provide functions that return values via their parameters
521 Except for the last case, ncurses provides a non-macro
522 implementation of the function. If the macro definition is
523 disabled with #undef, or by defining NCURSES_NOMACROS the function
524 may be linked (and its calls will be checked against the
526 * Extensive documentation is provided (see the Additional Reading
527 section of the ncurses FAQ for online documentation).
529 Applications using ncurses
531 The ncurses distribution includes a selection of test programs
532 (including a few games). These are available separately as
535 The ncurses library has been tested with a wide variety of
536 applications including:
539 FrontEnd to Apt, the debian package manager
541 https://wiki.debian.org/Aptitude
544 Curses Development Kit
546 https://invisible-island.net/cdk/
551 https://invisible-island.net/ded/
554 the underlying application used in Slackware's setup, and the
555 basis for similar install/configure applications on many
558 https://invisible-island.net/dialog/
563 https://lynx.invisible-island.net/
571 file-transfer utility
573 https://www.ncftp.com/
578 https://sites.google.com/a/bostic.com/keithbostic/the-berkeley-
582 A console file manager with VI key bindings in Python.
584 https://ranger.github.io/
587 newsreader, supporting color, MIME
592 File manager with vi like keybindings
596 as well as some that use ncurses for the terminfo support alone:
599 terminal emulator for serial modem connections
601 https://salsa.debian.org/minicom-team/minicom
604 a replacement for ssh.
609 terminfo action checker
611 https://invisible-island.net/ncurses/tack.html
616 https://github.com/tmux/tmux/wiki
619 vi-like-emacs may be built to use the terminfo, termcap or
622 https://invisible-island.net/vile/
624 and finally, those which use only the termcap interface:
629 https://www.gnu.org/software/emacs/
632 The most commonly used pager (a program that displays text
635 http://www.greenwoodsoftware.com/less/
640 https://www.gnu.org/software/screen/
647 Development activities
649 Zeyd Ben-Halim started ncurses from a previous package pcurses,
650 written by Pavel Curtis. Eric S. Raymond continued development.
651 Juergen Pfeifer wrote most of the form and menu libraries.
653 Ongoing development work is done by Thomas E. Dickey. Thomas E. Dickey
654 has acted as the maintainer for the Free Software Foundation, which
655 held a copyright on ncurses for releases 4.2 through 6.1. Following
656 the release of ncurses 6.1, effective as of release 6.2, copyright for
657 ncurses reverted to Thomas E. Dickey (see the ncurses FAQ for
658 additional information).
660 Contact the current maintainers at
664 To join the ncurses mailing list, please write email to
666 bug-ncurses-request@gnu.org
670 subscribe <name>@<host.domain>
672 This list is open to anyone interested in helping with the development
673 and testing of this package.
675 Beta versions of ncurses are made available at
677 https://invisible-island.net/archives/ncurses/current/ and
678 https://invisible-mirror.net/archives/ncurses/current/ .
680 Patches to the current release are made available at
682 https://invisible-island.net/archives/ncurses/6.4/ and
683 https://invisible-mirror.net/archives/ncurses/6.4/ .
685 There is an archive of the mailing list here:
687 https://lists.gnu.org/archive/html/bug-ncurses .
691 The release notes make scattered references to these pages, which may
692 be interesting by themselves:
694 * Symbol versioning in ncurses
695 * Comments on ncurses versus slang (S-Lang)
696 * Comments on OpenBSD
697 * tack - terminfo action checker
698 * tctest - termcap library checker
703 The distribution provides a newer version of the terminfo-format
704 terminal description file once maintained by Eric Raymond . Unlike the
705 older version, the termcap and terminfo data are provided in the same
706 file, which also provides several user-definable extensions beyond the
707 X/Open Curses specification.
709 You can find lots of information on terminal-related topics not
710 covered in the terminfo file in Richard Shuford's archive (original).
711 The collection of computer manuals at bitsavers.org has also been
716 + Library improvements
719 + Program improvements
724 + Interesting bug-fixes
725 + Configuration changes
727 o Configuration options
729 * Features of ncurses
730 * Applications using ncurses
731 * Development activities