<LI><A HREF="#objective">Objective of the Package</A>
<UL>
<LI><A HREF="#whysvr4">Why System V Curses?</A>
<LI><A HREF="#extensions">How to Design Extensions</A>
</UL>
<LI><A HREF="#objective">Objective of the Package</A>
<UL>
<LI><A HREF="#whysvr4">Why System V Curses?</A>
<LI><A HREF="#extensions">How to Design Extensions</A>
</UL>
<LI><A HREF="#ncurslib">A Tour of the Ncurses Library</A>
<UL>
<LI><A HREF="#loverview">Library Overview</A>
<LI><A HREF="#ncurslib">A Tour of the Ncurses Library</A>
<UL>
<LI><A HREF="#loverview">Library Overview</A>
<LI><A HREF="#output">Output and Screen Updating</A>
</UL>
<LI><A HREF="#fmnote">The Forms and Menu Libraries</A>
<LI><A HREF="#output">Output and Screen Updating</A>
</UL>
<LI><A HREF="#fmnote">The Forms and Menu Libraries</A>
<LI><A HREF="#tic">A Tour of the Terminfo Compiler</A>
<UL>
<LI><A HREF="#nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A>
<LI><A HREF="#tic">A Tour of the Terminfo Compiler</A>
<UL>
<LI><A HREF="#nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A>
It discusses design philosophy, implementation methods, and the
conventions used for coding and documentation. It is recommended
reading for anyone who is interested in porting, extending or improving the
It discusses design philosophy, implementation methods, and the
conventions used for coding and documentation. It is recommended
reading for anyone who is interested in porting, extending or improving the
<H1><A NAME="objective">Objective of the Package</A></H1>
The objective of the <STRONG>ncurses</STRONG> package is to provide a free software API for
character-cell terminals and terminal emulators with the following
<H1><A NAME="objective">Objective of the Package</A></H1>
The objective of the <STRONG>ncurses</STRONG> package is to provide a free software API for
character-cell terminals and terminal emulators with the following
<UL>
<LI>Source-compatible with historical curses implementations (including
the original BSD curses and System V curses.
<UL>
<LI>Source-compatible with historical curses implementations (including
the original BSD curses and System V curses.
<LI>High-quality -- stable and reliable code, wide portability, good
packaging, superior documentation.
<LI>High-quality -- stable and reliable code, wide portability, good
packaging, superior documentation.
<LI>Featureful -- should eliminate as much of the drudgery of C interface
programming as possible, freeing programmers to think at a higher
level of design.
<LI>Featureful -- should eliminate as much of the drudgery of C interface
programming as possible, freeing programmers to think at a higher
level of design.
These objectives are in priority order. So, for example, source
compatibility with older version must trump featurefulness -- we cannot
add features if it means breaking the portion of the API corresponding
These objectives are in priority order. So, for example, source
compatibility with older version must trump featurefulness -- we cannot
add features if it means breaking the portion of the API corresponding
More importantly for the future, the XSI Curses standard issued by X/Open
is explicitly and closely modeled on System V. So conformance with
More importantly for the future, the XSI Curses standard issued by X/Open
is explicitly and closely modeled on System V. So conformance with
For example, there is a macro <CODE>NCURSES_MOUSE_VERSION</CODE> which XSI Curses
does not define, but which is defined in the <STRONG>ncurses</STRONG> library header.
For example, there is a macro <CODE>NCURSES_MOUSE_VERSION</CODE> which XSI Curses
does not define, but which is defined in the <STRONG>ncurses</STRONG> library header.
to less-capable UNIX environments wherever possible. <P>
We encourage developers to support OS-specific optimizations and methods
to less-capable UNIX environments wherever possible. <P>
We encourage developers to support OS-specific optimizations and methods
<UL>
<LI>All such code is properly conditioned so the build process does not
attempt to compile it under a plain ANSI/POSIX environment.
<UL>
<LI>All such code is properly conditioned so the build process does not
attempt to compile it under a plain ANSI/POSIX environment.
<LI>Adding such implementation methods does not introduce incompatibilities
in the <STRONG>ncurses</STRONG> API between platforms.
</UL>
<LI>Adding such implementation methods does not introduce incompatibilities
in the <STRONG>ncurses</STRONG> API between platforms.
</UL>
We use GNU <CODE>autoconf(1)</CODE> as a tool to deal with portability issues.
The right way to leverage an OS-specific feature is to modify the autoconf
specification files (configure.in and aclocal.m4) to set up a new feature
We use GNU <CODE>autoconf(1)</CODE> as a tool to deal with portability issues.
The right way to leverage an OS-specific feature is to modify the autoconf
specification files (configure.in and aclocal.m4) to set up a new feature
<H1><A NAME="documentation">Documentation Conventions</A></H1>
There are three kinds of documentation associated with this package. Each
<H1><A NAME="documentation">Documentation Conventions</A></H1>
There are three kinds of documentation associated with this package. Each
<OL>
<LI><STRONG>Maintain package-internal files in plain text.</STRONG>
The expected viewer for them <EM>more(1)</EM> or an editor window; there's
<OL>
<LI><STRONG>Maintain package-internal files in plain text.</STRONG>
The expected viewer for them <EM>more(1)</EM> or an editor window; there's
as plain text than most other mark-ups, if you don't have a viewer; and (c)
carries enough information that you can generate a nice-looking printed
version from it. Also, of course, it make exporting things like the
as plain text than most other mark-ups, if you don't have a viewer; and (c)
carries enough information that you can generate a nice-looking printed
version from it. Also, of course, it make exporting things like the
In order to use our bug-fixing time efficiently, we put people who
show us they've taken these steps at the head of our queue. This
means that if you don't, you'll probably end up at the tail end and
In order to use our bug-fixing time efficiently, we put people who
show us they've taken these steps at the head of our queue. This
means that if you don't, you'll probably end up at the tail end and
Bugs we can reproduce are likely to be fixed very quickly, often
within days. The most effective single thing you can do to get a
quick fix is develop a way we can duplicate the bad behavior --
ideally, by giving us source for a small, portable test program that
breaks the library. (Even better is a keystroke recipe using one of
Bugs we can reproduce are likely to be fixed very quickly, often
within days. The most effective single thing you can do to get a
quick fix is develop a way we can duplicate the bad behavior --
ideally, by giving us source for a small, portable test program that
breaks the library. (Even better is a keystroke recipe using one of
If you have xterm available, it is also good to collect xterm reports for
different window sizes. This is especially true if you normally use an
unusual xterm window size -- a surprising number of the bugs we've seen
If you have xterm available, it is also good to collect xterm reports for
different window sizes. This is especially true if you normally use an
unusual xterm window size -- a surprising number of the bugs we've seen
Often you'll find terminfo problems at this stage by noticing that the
escape sequences put out for various capabilities are wrong. If not,
you're likely to learn enough to be able to characterize any bug in
Often you'll find terminfo problems at this stage by noticing that the
escape sequences put out for various capabilities are wrong. If not,
you're likely to learn enough to be able to characterize any bug in
There's one other interactive tester, <CODE>tctest</CODE>, that exercises
translation between termcap and terminfo formats. If you have a serious
There's one other interactive tester, <CODE>tctest</CODE>, that exercises
translation between termcap and terminfo formats. If you have a serious
reorganization in the underlying data structures. <P>
These files are used only for debugging support:
reorganization in the underlying data structures. <P>
These files are used only for debugging support:
It is rather unlikely you will ever need to change these, unless
you want to introduce a new debug trace level for some reasoon.<P>
It is rather unlikely you will ever need to change these, unless
you want to introduce a new debug trace level for some reasoon.<P>
computations on the terminal capabilities, or queries to the OS
environment, but nevertheless have only fairly low complexity. These
include:
computations on the terminal capabilities, or queries to the OS
environment, but nevertheless have only fairly low complexity. These
include:
They are likely to need revision only if
ncurses is being ported to an environment without an underlying
terminfo capability representation. <P>
They are likely to need revision only if
ncurses is being ported to an environment without an underlying
terminfo capability representation. <P>
If you run into porting snafus
moving the package to another UNIX, the problem is likely to be in one
of these files.
If you run into porting snafus
moving the package to another UNIX, the problem is likely to be in one
of these files.
Most of the algorithmic complexity in the
library lives in these files.
If there is a real bug in <STRONG>ncurses</STRONG> itself, it's probably here.
Most of the algorithmic complexity in the
library lives in these files.
If there is a real bug in <STRONG>ncurses</STRONG> itself, it's probably here.
Finally, there is a group of files that is actually most of the
terminfo compiler. The reason this code lives in the <STRONG>ncurses</STRONG>
library is to support fallback to /etc/termcap. These files include
Finally, there is a group of files that is actually most of the
terminfo compiler. The reason this code lives in the <STRONG>ncurses</STRONG>
library is to support fallback to /etc/termcap. These files include
calls may find the code in <CODE>lib_twait.c</CODE> interesting. It deals
with the problem that some BSD selects don't return a reliable
time-left value. The function <CODE>timed_wait()</CODE> effectively
calls may find the code in <CODE>lib_twait.c</CODE> interesting. It deals
with the problem that some BSD selects don't return a reliable
time-left value. The function <CODE>timed_wait()</CODE> effectively
In either case, <CODE>_nc_mouse_parse()</CODE> should be called after the
series is accepted to parse the digested mouse reports (low-level
In either case, <CODE>_nc_mouse_parse()</CODE> should be called after the
series is accepted to parse the digested mouse reports (low-level
In the trace-enabled version of the library, it is also possible to disable
and re-enable various optimizations at runtime by tweaking the variable
<CODE>_nc_optimize_enable</CODE>. See the file <CODE>include/curses.h.in</CODE>
In the trace-enabled version of the library, it is also possible to disable
and re-enable various optimizations at runtime by tweaking the variable
<CODE>_nc_optimize_enable</CODE>. See the file <CODE>include/curses.h.in</CODE>
Historical note: the panels code was written primarily to assist in
porting u386mon 2.0 (comp.sources.misc v14i001-4) to systems lacking
panels support; u386mon 2.10 and beyond use it. This version has been
Historical note: the panels code was written primarily to assist in
porting u386mon 2.0 (comp.sources.misc v14i001-4) to systems lacking
panels support; u386mon 2.10 and beyond use it. This version has been
mode (termcap or terminfo) based on the first `,' or `:' it finds in
each entry. The lexer does all the work of recognizing capability
names and values; the grammar above it is trivial, just "parse entries
mode (termcap or terminfo) based on the first `,' or `:' it finds in
each entry. The lexer does all the work of recognizing capability
names and values; the grammar above it is trivial, just "parse entries
Thus, adding a new capability is usually pretty trivial, just a matter
of adding one line to the <CODE>include/Caps</CODE> file. We'll have more
to say about this in the section on <A HREF="#translation">Source-Form
Thus, adding a new capability is usually pretty trivial, just a matter
of adding one line to the <CODE>include/Caps</CODE> file. We'll have more
to say about this in the section on <A HREF="#translation">Source-Form
postdates the time of <STRONG>tic</STRONG>'s first call to
<CODE>write_entry()</CODE>, Thus it will complain about overwriting
entries newly made during the <STRONG>tic</STRONG> run, but not about
postdates the time of <STRONG>tic</STRONG>'s first call to
<CODE>write_entry()</CODE>, Thus it will complain about overwriting
entries newly made during the <STRONG>tic</STRONG> run, but not about
are functions in <CODE>parse_entry.c</CODE> called after the parse of each
entry that are specifically intended to encapsulate such
translations. This, for example, is where the AIX <STRONG>box1</STRONG> capability
are functions in <CODE>parse_entry.c</CODE> called after the parse of each
entry that are specifically intended to encapsulate such
translations. This, for example, is where the AIX <STRONG>box1</STRONG> capability
the ordinary De-compilation case and entry difference reporting. <P>
The <STRONG>tput</STRONG> and <STRONG>clear</STRONG> utilities just do an entry load
the ordinary De-compilation case and entry difference reporting. <P>
The <STRONG>tput</STRONG> and <STRONG>clear</STRONG> utilities just do an entry load
calls (not including <CODE>tputs()</CODE> and <CODE>putp()</CODE>) and do not
call any other UNIX routines such as signal(2) or the stdio library.
Thus, they should not need to be modified for single-terminal
calls (not including <CODE>tputs()</CODE> and <CODE>putp()</CODE>) and do not
call any other UNIX routines such as signal(2) or the stdio library.
Thus, they should not need to be modified for single-terminal
Modules that would have to be modified for a port start here: <P>
The following modules are `pure curses' but contain assumptions inappropriate
Modules that would have to be modified for a port start here: <P>
The following modules are `pure curses' but contain assumptions inappropriate