The ncurses
library is intended to be BASE-level conformant with
XSI Curses. The EXTENDED XSI Curses functionality (including
color support) is supported.
A small number of local differences (that is, individual
differences between the XSI Curses and ncurses
calls) are
described in PORTABILITY
sections of the library man pages.
Error checking
In many cases, X/Open Curses is vague about error conditions,
omitting some of the SVr4 documentation.
Unlike other implementations, this one checks parameters such as
pointers to WINDOW structures to ensure they are not null. The
main reason for providing this behavior is to guard against
programmer error. The standard interface does not provide a way
for the library to tell an application which of several possible
errors were detected. Relying on this (or some other) extension
will adversely affect the portability of curses applications.
Extensions versus portability
Most of the extensions provided by ncurses have not been
standardized. Some have been incorporated into other
implementations, such as PDCurses or NetBSD curses. Here are a
few to consider:
• The routine has_key
is not part of XPG4, nor is it present in
SVr4. See the curs_getch
(3X) manual page for details.
• The routine slk_attr
is not part of XPG4, nor is it present
in SVr4. See the curs_slk
(3X) manual page for details.
• The routines getmouse
, mousemask
, ungetmouse
, mouseinterval
,
and wenclose
relating to mouse interfacing are not part of
XPG4, nor are they present in SVr4. See the curs_mouse
(3X)
manual page for details.
• The routine mcprint
was not present in any previous curses
implementation. See the curs_print
(3X) manual page for
details.
• The routine wresize
is not part of XPG4, nor is it present in
SVr4. See the wresize
(3X) manual page for details.
• The WINDOW structure's internal details can be hidden from
application programs. See curs_opaque
(3X) for the discussion
of is_scrollok
, etc.
• This implementation can be configured to provide rudimentary
support for multi-threaded applications. See
curs_threads
(3X) for details.
• This implementation can also be configured to provide a set
of functions which improve the ability to manage multiple
screens. See curs_sp_funcs
(3X) for details.
Padding differences
In historic curses versions, delays embedded in the capabilities
cr
, ind
, cub1
, ff
and tab
activated corresponding delay bits in
the UNIX tty driver. In this implementation, all padding is done
by sending NUL bytes. This method is slightly more expensive,
but narrows the interface to the UNIX kernel significantly and
increases the package's portability correspondingly.
Header files
The header file <curses.h>
automatically includes the header
files <stdio.h>
and <unctrl.h>
.
X/Open Curses has more to say, but does not finish the story:
The inclusion of <curses.h> may make visible all symbols from
the headers <stdio.h>, <term.h>, <termios.h>, and <wchar.h>.
Here is a more complete story:
• Starting with BSD curses, all implementations have included
<stdio.h>.
BSD curses included <curses.h> and <unctrl.h> from an
internal header "curses.ext" ("ext" was a short name for
externs).
BSD curses used <stdio.h> internally (for printw
and scanw
),
but nothing in <curses.h> itself relied upon <stdio.h>.
• SVr2 curses added newterm
(3X), which relies upon <stdio.h>.
That is, the function prototype uses FILE
.
SVr4 curses added putwin
and getwin
, which also use
<stdio.h>.
X/Open Curses documents all three of these functions.
SVr4 curses and X/Open Curses do not require the developer to
include <stdio.h> before including <curses.h>. Both document
curses showing <curses.h> as the only required header.
As a result, standard <curses.h> will always include
<stdio.h>.
• X/Open Curses is inconsistent with respect to SVr4 regarding
<unctrl.h>.
As noted in curs_util
(3X), ncurses includes <unctrl.h> from
<curses.h> (like SVr4).
• X/Open's comments about <term.h> and <termios.h> may refer to
HP-UX and AIX:
HP-UX curses includes <term.h> from <curses.h> to declare
setupterm
in curses.h, but ncurses (and Solaris curses) do
not.
AIX curses includes <term.h> and <termios.h>. Again, ncurses
(and Solaris curses) do not.
• X/Open says that <curses.h> may include <term.h>, but there
is no requirement that it do that.
Some programs use functions declared in both <curses.h> and
<term.h>, and must include both headers in the same module.
Very old versions of AIX curses required including <curses.h>
before including <term.h>.
Because ncurses header files include the headers needed to
define datatypes used in the headers, ncurses header files
can be included in any order. But for portability, you
should include <curses.h> before <term.h>.
• X/Open Curses says "may make visible" because including a
header file does not necessarily make all symbols in it
visible (there are ifdef's to consider).
For instance, in ncurses <wchar.h> may be included if the
proper symbol is defined, and if ncurses is configured for
wide-character support. If the header is included, its
symbols may be made visible. That depends on the value used
for _XOPEN_SOURCE
feature test macro.
• X/Open Curses documents one required header, in a special
case: <stdarg.h> before <curses.h> to prototype the vw_printw
and vw_scanw
functions (as well as the obsolete the vwprintw
and vwscanw
functions). Each of those uses a va_list
parameter.
The two obsolete functions were introduced in SVr3. The
other functions were introduced in X/Open Curses. In
between, SVr4 curses provided for the possibility that an
application might include either <varargs.h> or <stdarg.h>.
Initially, that was done by using void*
for the va_list
parameter. Later, a special type (defined in <stdio.h>) was
introduced, to allow for compiler type-checking. That
special type is always available, because <stdio.h> is always
included by <curses.h>.
None of the X/Open Curses implementations require an
application to include <stdarg.h> before <curses.h> because
they either have allowed for a special type, or (like
ncurses) include <stdarg.h> directly to provide a portable
interface.