+ <p>They are documented in X/Open <em>as if</em>
+ <code>initscr</code> calls <code>newterm</code> using
+ <code>stdout</code> for output stream, and in turn
+ <code>newterm</code> calls <code>setupterm</code> using
+ <code>fileno(stdout)</code> for the file descriptor. As long as
+ an implementation acts <em>as if</em> it does this, it conforms.
+ In practice, implementations do what is implied. This creates a
+ problem: the low-level <code>setupterm</code> function's file
+ descriptor is unbuffered, while <code>newterm</code> 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.</p>
+
+ <p>Initially, <em class="small-caps">ncurses</em> used the file
+ descriptor (obtained from the output stream passed to
+ <code>newterm</code>) for changing the terminal modes, and relied
+ upon the output parameter of <code>newterm</code> for buffered
+ output. Later (to avoid using unsafe buffered I/O in signal
+ handlers), <em class="small-caps">ncurses</em> 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.</p>
+
+ <p>That approach worked reasonably well and as a side effect,
+ using the same buffered output as an application might use for
+ <code>printf</code> meant that no flushing was needed when
+ switching between normal- and screen-modes.</p>
+
+ <p>There were a couple of problems:</p>
+
+ <ul>
+ <li>
+ <p>to get good performance, curses (not only <em class=
+ "small-caps">ncurses</em>, but SVr4 curses in general) set an
+ output buffer using <code>setbuf</code> or similar function.
+ There is no standard (or portable) way to turn that output
+ buffer off, and revert to line-buffering. The <code><a href=
+ "http://invisible-island.net/ncurses/man/ncurses.3x.html#h3-NCURSES_NO_SETBUF">
+ NCURSES_NO_SETBUF</a></code> environment variable did make it
+ optional.</p>
+ </li>
+
+ <li>
+ <p>to handle <code>SIGTSTP</code> (the “stop”
+ signal), <em class="small-caps">ncurses</em> 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.</p>
+ </li>
+ </ul>
+
+ <p>Conveniently, solving the second problem (by making <em class=
+ "small-caps">ncurses</em> do its <em>own</em> output buffering)
+ also fixed the first one. But there were special cases to
+ resolve: <a href=
+ "http://invisible-island.net/ncurses/man/curs_terminfo.3x.html"><em>
+ low-level</em></a> 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.</p>
+
+ <p>Finally, there may still be a few programs which should be
+ modified to improve their portability, e.g., adding an</p>
+
+ <blockquote>
+ <pre class="code-block">
+fflush(stdout);
+</pre>
+ </blockquote>
+
+ <p>when switching from “<a href=
+ "http://invisible-island.net/ncurses/man/curs_kernel.3x.html#h3-reset_prog_mode_-reset_shell_mode">shell</a>”
+ mode to “<a href=
+ "http://invisible-island.net/ncurses/man/curs_kernel.3x.html#h3-reset_prog_mode_-reset_shell_mode">program</a>”
+ (curses) mode. Those are fairly rare because most programmers
+ have learned not to mix <code>printf</code> and <code><a href=
+ "http://invisible-island.net/ncurses/man/curs_printw.3x.html">printw</a></code>.</p>
+
+ <h3><a name="h3-lib-versioning" id="h3-lib-versioning">Symbol
+ versioning</a></h3>
+
+ <p>This release introduces symbol-versioning to <em class=
+ "small-caps">ncurses</em> because without it, the change of ABI
+ would be less successful. A lengthy discussion will be presented
+ in <a href=
+ "http://invisible-island.net/ncurses/ncurses-mapsyms.html">Symbol
+ versioning in <em class="small-caps">ncurses</em></a>. These
+ notes summarize what has changed, and what can be done with the
+ new release.</p>
+
+ <p>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.</p>
+
+ <p>This release provides sample files for the four principal
+ configurations of <em class="small-caps">ncurses</em> libraries:
+ <code>ncurses</code>, <code>ncursesw</code>,
+ <code>ncursest</code> and <code>ncursestw</code>. Each sample is
+ given in two forms:</p>
+
+ <blockquote>
+ <dl>
+ <dt>“<code>.map</code>”</dt>
+
+ <dd>These list all public symbols, together with version
+ names.</dd>
+
+ <dt>“<code>.sym</code>”</dt>
+
+ <dd>These list all public symbols, without version
+ names.</dd>
+ </dl>
+ </blockquote>
+
+ <p>The sample files are <em>generated</em> by scripts which take
+ into account a few special cases such as <a href=
+ "http://invisible-island.net/ncurses/tack.html">tack</a> to omit
+ many of the <em class="small-caps">ncurses</em> private symbols
+ (beginning with “<code>_nc_</code>”). Here are
+ counts of globals versus locals:</p>
+
+ <blockquote>
+ <table border="1" summary="Total global and local symbols">
+ <tr>
+ <th>Config</th>
+
+ <th>Symbols</th>
+
+ <th>Globals</th>
+
+ <th>Locals</th>
+
+ <th>"_nc_"</th>
+ </tr>
+
+ <tr>
+ <td>ncurses</td>
+
+ <td align="right">976</td>
+
+ <td align="right">796</td>
+
+ <td align="right">180</td>
+
+ <td align="right">332</td>
+ </tr>
+
+ <tr>
+ <td>ncursesw</td>
+
+ <td align="right">1089</td>
+
+ <td align="right">905</td>
+
+ <td align="right">184</td>
+
+ <td align="right">343</td>
+ </tr>
+
+ <tr>
+ <td>ncursest</td>
+
+ <td align="right">979</td>
+
+ <td align="right">804</td>
+
+ <td align="right">175</td>
+
+ <td align="right">358</td>
+ </tr>
+
+ <tr>
+ <td>ncursestw</td>
+
+ <td align="right">1098</td>
+
+ <td align="right">914</td>
+
+ <td align="right">184</td>
+
+ <td align="right">372</td>
+ </tr>
+ </table>
+ </blockquote>
+
+ <p>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
+ <em>not</em> support the feature, and a few (such as Solaris)
+ which provide incomplete support.</p>
+
+ <p>The version-naming convention used allows these sample files
+ to build distinct libraries for ABI 5 and 6. Version names
+ consist of</p>
projects / ncurses.git / blobdiff