- Output buffering
-
- X/Open curses provides more than one initialization function:
- * [17]initscr (the simplest) accepts no parameters.
- * [18]newterm accepts parameters for the stream input and output
- * [19]setupterm (the low-level function) accepts a parameter for the
- file descriptor of the output.
-
- They are documented in X/Open as if initscr calls newterm using stdout
- for output stream, and in turn newterm calls setupterm using
- fileno(stdout) for the file descriptor. As long as an implementation
- acts as if it does this, it conforms. In practice, implementations do
- what is implied. This creates a problem: the low-level setupterm
- function's file descriptor is unbuffered, while newterm implies
- buffered output. X/Open Curses says that all output is done through
- the file descriptor, and does not say how the output stream is
- actually used.
-
- Initially, ncurses used the file descriptor (obtained from the output
- stream passed to newterm) for changing the terminal modes, and relied
- upon the output parameter of newterm for buffered output. Later (to
- avoid using unsafe buffered I/O in signal handlers), ncurses was
- modified to use the file descriptor (unbuffered output) when cleaning
- up on receipt of a signal. Otherwise (when not handling a signal), it
- continued to use the buffered output.
-
- That approach worked reasonably well and as a side effect, using the
- same buffered output as an application might use for printf meant that
- no flushing was needed when switching between normal- and
- screen-modes.
-
- There were a couple of problems:
- * to get good performance, curses (not only ncurses, but SVr4 curses
- in general) set an output buffer using setbuf or similar function.
- There is no standard (or portable) way to turn that output buffer
- off, and revert to line-buffering. The [20]NCURSES_NO_SETBUF
- environment variable did make it optional.
- * to handle SIGTSTP (the "stop" signal), ncurses relied upon unsafe
- functions. That is, due to the complexity of the feature, it
- relied upon reusing existing functions which should not have been
- called via the signal handler.
-
- Conveniently, solving the second problem (by making ncurses do its own
- output buffering) also fixed the first one. But there were special
- cases to resolve: [21]low-level functions such as mvcur, putp, vidattr
- explicitly use the standard output. Those functions were reused
- internally, and required modification to distinguish whether they were
- used by the high-level or low-level interfaces.
-
- Finally, there may still be a few programs which should be modified to
- improve their portability, e.g., adding an
-
-fflush(stdout);
-
- when switching from "[22]shell" mode to "[23]program" (curses) mode.
- Those are fairly rare because most programmers have learned not to mix
- printf and [24]printw.
-
- Symbol versioning
-
- This release introduces symbol-versioning to ncurses because without
- it, the change of ABI would be less successful. A lengthy discussion
- will be presented in [25]Symbol versioning in ncurses. These notes
- summarize what has changed, and what can be done with the new release.
-
- Symbol-versioning allows the developers of a library to mark each
- public symbol (both data and functions) with an identifier denoting
- the library name and the version for which it was built. By doing
- this, users of the library have a way to help ensure that applications
- do not accidentally load an incompatible library. In addition, private
- symbols can be hidden entirely.
-
- This release provides sample files for the four principal
- configurations of ncurses libraries: ncurses, ncursesw, ncursest and
- ncursestw. Each sample is given in two forms:
-
- ".map"
- These list all public symbols, together with version names.
-
- ".sym"
- These list all public symbols, without version names.
-
- The sample files are generated by scripts which take into account a
- few special cases such as [26]tack to omit many of the ncurses private
- symbols (beginning with "_nc_"). Here are counts of globals versus
- locals:
-
- Config Symbols Globals Locals "_nc_"
- ncurses 976 796 180 332
- ncursesw 1089 905 184 343
- ncursest 979 804 175 358
- ncursestw 1098 914 184 372
-
- Although only four sample configurations are presented, each is formed
- by merging symbols from several combinations of configure-script
- options, taking into account advice from downstream packagers. Because
- they are formed by merging, the sample files may list a symbol which
- is not in a given package. That is expected. The samples have been
- tested and are working with systems (such as Fedora, FreeBSD and
- Debian) which fully support this feature. There are other systems
- which do not support the feature, and a few (such as Solaris) which
- provide incomplete support.
-
- The version-naming convention used allows these sample files to build
- distinct libraries for ABI 5 and 6. Version names consist of
- * configuration name, e.g., "NCURSESW" for the wide-character
- libraries
- * ABI version (if not 5)
- * library name for two special cases which have the same interface
- across configurations: "TINFO" and "TIC"
- * release version
- * patch date (for the release version)
-
- For example, running nm -D on the libraries in the ncurses6 test
- package shows these symbol-versions:
-
-0000000000000000 A NCURSES6_TIC_5.0.19991023
-0000000000000000 A NCURSES6_TIC_5.1.20000708
-0000000000000000 A NCURSES6_TIC_5.5.20051010
-0000000000000000 A NCURSES6_TIC_5.7.20081102
-0000000000000000 A NCURSES6_TIC_5.9.20150530
-0000000000000000 A NCURSES6_TINFO_5.0.19991023
-0000000000000000 A NCURSES6_TINFO_5.1.20000708
-0000000000000000 A NCURSES6_TINFO_5.2.20001021
-0000000000000000 A NCURSES6_TINFO_5.3.20021019
-0000000000000000 A NCURSES6_TINFO_5.4.20040208
-0000000000000000 A NCURSES6_TINFO_5.5.20051010
-0000000000000000 A NCURSES6_TINFO_5.6.20061217
-0000000000000000 A NCURSES6_TINFO_5.7.20081102
-0000000000000000 A NCURSES6_TINFO_5.8.20110226
-0000000000000000 A NCURSES6_TINFO_5.9.20150530
-0000000000000000 A NCURSESW6_5.1.20000708
-0000000000000000 A NCURSESW6_5.3.20021019
-0000000000000000 A NCURSESW6_5.4.20040208
-0000000000000000 A NCURSESW6_5.5.20051010
-0000000000000000 A NCURSESW6_5.6.20061217
-0000000000000000 A NCURSESW6_5.7.20081102
-0000000000000000 A NCURSESW6_5.8.20110226
-0000000000000000 A NCURSESW6_5.9.20150530
-
- As a special case, this release (which makes the final change for ABI
- 5) is marked with release version 5.9 and patch date 20150530.
-
- Miscellaneous
-
- The new release has several improvements for performance and building.
- For instance:
- * several files in ncurses- and progs-directories were modified to
- allow const data used in internal tables to be put by the linker
- into the readonly text segment.
- * various improvements were made to building the Ada95 binding, both
- in simplifying the generated files as well as improving the way it
- uses gnatmake
-
- There are also new features in the libraries:
- * added [27]use_tioctl function
- * added [28]wgetdelay to retrieve _delay member of WINDOW if it
- happens to be opaque, e.g., in the pthread configuration.
- * added [29]A_ITALIC extension.
- * added form library extension [30]O_DYNAMIC_JUSTIFY option which
- can be used to override the different treatment of justification
- for static versus dynamic fields .
- * rewrote [31]putwin and [32]getwin, making an extended version
- which is capable of reading screen-dumps between the wide/normal
- ncurses configurations. These are text files, except for a magic
- code at the beginning:
-
-0 string \210\210 Screen-dump (ncurses)
-
- * several changes to mouse support include:
- + added decoder for xterm SGR 1006 mouse mode.
- + added experimental support for "%u" format to terminfo.
- + improved behavior of wheel-mice for xterm protocol: noting
- that there are only button-presses for buttons "4" and "5",
- so there is no need to wait to combine events into
- double-clicks .
-
- There are a few new configure options dealing with library
- customization:
- * add "--enable-ext-putwin" configure option to turn on the extended
- putwin/getwin. By default, this is enabled for ABI 6 and disabled
- with ABI 5.
- * add "--enable-string-hacks" option to control whether strlcat and
- strlcpy may be used. Because ncurses already does the requisite
- buffer-limit checks, this feature is mainly of interest to quiet
- compiler-warnings on a few systems.
- * add configure option "--with-tparm-arg" to allow [33]tparm's
- parameters to be something more likely to be the same size as a
- pointer, e.g., intptr_t (again, the default is set for ABI 6).
+ New features
+
+ The improved integration of tput and tset made only small changes to
+ the libraries. However, supporting extended numeric capabilities
+ required a few changes:
+ * The TERMINAL structure in <term.h> is now opaque. Doing that
+ allowed making the structure larger, to hold the extended numeric
+ data.
+ A few applications required changes during development of
+ ncurses 6.1 because those applications misused the members of that
+ structure, e.g., directly modifying it rather than using
+ [13]def_prog_mode.
+ * Having made TERMINAL opaque (and because none of the library
+ functions use anything except a pointer to TERMINAL), it was
+ possible to increase the size of the structure, adding to the end.
+ Existing applications which were linked to the ncurses 6.0
+ high-level (ncurses, ncursesw) and low-level (tinfo, tinfo)
+ libraries should not require re-linking since the binary interface
+ did not change, nor did the structure offsets with TERMINAL
+ change.
+ A few applications use the inner TERMTYPE structure's offsets to
+ refer to terminfo capabilities within that structure. Again, those
+ do not require modification because their offsets within TERMINAL
+ did not change.
+ * When configured for wide-characters, i.e., "ncursesw" the TERMINAL
+ structure is extended.
+ The new data in TERMINAL holds the same information as TERMTYPE,
+ but with larger numbers ("int" versus "short"). It is named
+ TERMTYPE2.
+ The library uses this structure internally in preference to
+ TERMTYPE, referring to TERMTYPE only to initialize it for
+ applications that use the capabilities defined in <term.h>
+ * When configured for 8-bit (narrow) characters, the TERMTYPE2
+ structure is not used.
+ * The updated application binary interface is 6.1.20171230 (used for
+ new [14]versioned symbols), although the interface changes were
+ developed several months previously.
+
+ The motivation for making this extension came from noticing that
+ [15]termcap applications could (though not [16]realistically) use
+ larger numbers than would fit in 16-bits, and the fact that the number
+ of color pairs for a 256-color xterm could not be expressed in
+ terminfo (i.e., 32767 versus 65536). Also, a few terminals support
+ direct-colors, which could use the extension.
+
+ Generally speaking, applications that use internal details of a
+ library are unsupported. There was exactly one exception for ncurses:
+ the tack program used the internal details of TERMINAL, because it
+ provides an ncurses-specific feature for interactively modifying a
+ terminfo description and writing the updated description to a
+ text-file. It was possible to not only separate tack from these
+ [17]internal details of ncurses, but to generalize it so that the
+ program works with Unix curses (omitting the ncurses-specific
+ feature). That was released as [18]tack 1.08 in July 2017.
+
+ While making changes to tack to eliminate its dependency upon ncurses
+ internals, the publicly-visible details of those internals were
+ reviewed, and some symbols were moved to private header files, while
+ others were marked explicitly as ncurses internals. Future releases of
+ ncurses may eliminate some of those symbols (such as those used by
+ tack 1.07) because they are neither part of the API or the ABI.
+
+ Using the TERMTYPE2 extended numeric capabilities, it is possible to
+ support both color pair values and color values past 32767. Taking
+ compatibility into account, developers readily understand that neither
+ function signatures nor structure offsets change. Also, existing
+ functions have to operate with the extended numbers. Most of that work
+ is internal to the library. For the external interfaces, a hybrid
+ approach was used:
+ * X/Open Curses defined function prototypes such as wattr_set with
+ an unused parameter, for "future" use. After 25 years, the future
+ is here: ncurses uses the parameter to augment color pair values
+ as described in the [19]manual page.
+ * Other functions such as those defining color pairs did not have a
+ corresponding reserved parameter. For those, ncurses defines
+ extended versions such as init_extended_pair (versus init_pair),
+ init_extended_color (versus init_color).
+
+ Additionally, to improve performance other changes (and extensions)
+ are provided in this release:
+ * Several new functions simplify management of large sets of color
+ pairs: reset_color_pairs, alloc_pair, find_pair and free_pair.
+ * New "RGB" extension capability for direct-color support is used to
+ improve performance of color_content.
+ * The internal colorpair_t is now a struct, eliminating an internal
+ 8-bit limit on colors
+ * Allocation for SCREEN's color-pair table starts small, grows on
+ demand up to the limit given in the terminal description.
+ * setcchar and getcchar now treat a negative color-pair as an error.
+
+ Other improvements
+
+ These are new or revised features:
+ * modify c++/etip.h.in to accommodate deprecation of throw and
+ throws in c++17
+ * add new function unfocus_current_field
+ * add option to preserve leading whitespace in form fields
+ * add a macro for is_linetouched and adjust the function's return
+ value to make it possible for most applications to check for an
+ error-return.
+ * add build-time utility report_offsets to help show when the
+ various configurations of tinfo library are compatible or not.
+
+ These were done to limit or ultimately deprecate features:
+ * drop two symbols obsoleted in 2004: _nc_check_termtype, and
+ _nc_resolve_uses
+ * move _nc_tracebits, _tracedump and _tracemouse to curses.priv.h,
+ since they are not part of the suggested ABI6.
+ * mark some structs in form/menu/panel libraries as potentially
+ opaque without modifying API/ABI.
+ * ifdef'd header-file definition of mouse_trafo with
+ NCURSES_NOMACROS
+ * remove initialization-check for calling napms in the term-driver
+ configuration; none is needed.
+ * modify trace to avoid overwriting existing file
+
+ These are improvements to existing features:
+ * modify make_hash to allow building with address-sanitizer,
+ assuming that --disable-leaks is configured.
+ * move SCREEN field for use_tioctl data before the ncursesw fields,
+ and limit that to the sp-funcs configuration to improve termlib
+ compatibility
+ * modify db-iterator:
+ + ignore zero-length files in db-iterator; these are useful for
+ instance to suppress $HOME/.terminfo when not wanted.
+ + modify update_getenv to ensure that environment variables
+ which are not initially set will be checked later if an
+ application happens to set them
+ * modify _nc_outc_wrapper to use the standard output if the screen
+ was not initialized, rather than returning an error.
+ * improve checks for low-level terminfo functions when the terminal
+ has not been initialized.
+ * modify set_curterm to update ttytype[] data used by longname/p>
+ * modify _nc_get_screensize to allow for use_env and use_tioctl
+ state to be per-screen when sp-funcs are configured, better
+ matching the behavior when using the term-driver configuration.
+ * remove an early-return from _nc_do_color, which can interfere with
+ data needed by bkgd when ncurses is configured with extended
+ colors
+ * incorporate A_COLOR mask into COLOR_PAIR, in case user application
+ provides an out-of-range pair number
+ * modify logic for endwin-state to be able to detect the case where
+ the screen was never initialized, using that to trigger a flush of
+ ncurses' buffer for mvcur, e.g., in the sample program dots_mvcur
+ for the term-driver configuration.
+
+ These are corrections to existing features:
+ * fixes for writing extended color pairs in putwin.
+ * modify no-leaks code for lib_cur_term.c to account for the tgetent
+ cache.
+ * amend handling of the repeat_char capability in EmitRange to avoid
+ scope creep: translate the character to the alternate character
+ set when the alternate character set is enabled, and do not use
+ repeat_char for characters past 255.
+ * improve wide-character implementation of myADDNSTR in
+ frm_driver.c, which was inconsistent with the normal
+ implementation.
+ * modify winnstr and winchnstr to return error if the output pointer
+ is null, as well as adding a null pointer check of the window
+ pointer for better compatibility with other implementations.
+ * modify setupterm to save original tty-modes so that erasechar
+ works as expected. Also modify _nc_setupscreen to avoid redundant
+ calls to get original tty-modes.
+ * modify wattr_set and wattr_get to return ERR if win-parameter is
+ null, as documented.
+ * correct order of initialization for traces in use_env and
+ use_tioctl versus first _tracef calls.
+ * correct parameters for copywin call in _nc_Synchronize_Attributes
+ * flush the standard output in _nc_flush for the case where SP is
+ zero, e.g., when called via putp. This fixes a scenario where
+ "tput flash" did not work after changes in 20130112.
+ * amend internal use of tputs to consistently use the number of
+ lines affected, e.g., for insert/delete character operations.
+ While merging terminfo source early in 1995, several descriptions
+ used the "*" proportional delay for these operations, prompting a
+ change in doupdate.
+ * correct return-value of extended putwin.
+ * double-width multibyte characters were not counted properly in
+ winsnstr and wins_nwstr.
+ * amend fix for _nc_ripoffline from 20091031 to make test/ditto.c
+ work in threaded configuration.
+ * modify _nc_viscbuf2 and _tracecchar_t2 to trace wide-characters as
+ a whole rather than their multibyte equivalents.
+ * minor fix in wadd_wchnstr to ensure that each cell has nonzero
+ width.
+ * move PUTC_INIT calls next to wcrtomb calls, to avoid carry-over of
+ error status when processing Unicode values which are not mapped.
+ * add missing assignment in lib_getch.c to make notimeout work
projects / ncurses.git / commitdiff