<!--
* t
****************************************************************************
- * Copyright (c) 1998-2018,2019 Free Software Foundation, Inc. *
+ * Copyright 2018-2019,2020 Thomas E. Dickey *
+ * Copyright 1998-2015,2017 Free Software Foundation, Inc. *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
* copy of this software and associated documentation files (the *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: ncurses.3x,v 1.143 2019/11/30 20:47:07 tom Exp @
+ * @Id: ncurses.3x,v 1.148 2020/06/13 23:25:50 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
method of updating character screens with reasonable optimization.
This implementation is "new curses" (ncurses) and is the approved
replacement for 4.4BSD classic curses, which has been discontinued.
- This describes <STRONG>ncurses</STRONG> version 6.1 (patch 20200118).
+ This describes <STRONG>ncurses</STRONG> version 6.2 (patch 20200725).
The <STRONG>ncurses</STRONG> library emulates the curses library of System V Release 4
UNIX, and XPG4 (X/Open Portability Guide) curses (also known as XSI
Each cell (row and column) in a <STRONG>WINDOW</STRONG> is stored as a
<STRONG>cchar_t</STRONG>.
- The <STRONG><A HREF="setcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="getcchar.3x.html">getcchar(3x)</A></STRONG> functions store and
+ The <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> functions store and
retrieve the data from a <STRONG>cchar_t</STRONG> structure.
<STRONG>wchar_t</STRONG>
</PRE><H3><a name="h3-Routine-Name-Index">Routine Name Index</a></H3><PRE>
- The following table lists each <STRONG>curses</STRONG> routine and the name of the man-
- ual page on which it is described. Routines flagged with "*" are
- ncurses-specific, not described by XPG4 or present in SVr4.
+ The following table lists the <STRONG>curses</STRONG> routines provided in the "normal"
+ and "wide" libraries and the names of the manual pages on which they
+ are described. Routines flagged with "*" are ncurses-specific, not
+ described by XPG4 or present in SVr4.
<STRONG>curses</STRONG> Routine Name Manual Page Name
---------------------------------------------
COLOR_PAIR <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
PAIR_NUMBER <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
- _nc_free_and_exit <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>*
- _nc_freeall <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>*
- _nc_tracebits <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
- _traceattr <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
- _traceattr2 <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
- _tracechar <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
- _tracechtype <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
- _tracechtype2 <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
- _tracedump <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
- _tracef <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
- _tracemouse <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
add_wch <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
add_wchnstr <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
add_wchstr <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
attr_off <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
attr_on <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
attr_set <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
-
attroff <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
attron <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
attrset <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
bkgrnd <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
bkgrndset <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
border <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
+
border_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
box <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
box_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
color_set <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
copywin <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG>
curs_set <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
+ curses_trace <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
curses_version <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG>*
def_prog_mode <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
def_shell_mode <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
erase <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>
erasechar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
erasewchar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
+ exit_curses <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>*
+ exit_terminfo <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>*
extended_color_content <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>*
extended_pair_content <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>*
extended_slk_color <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>*
getcurx <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
getcury <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
getmaxx <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
-
getmaxy <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
getmaxyx <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
getmouse <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>*
getnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
getparx <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
getpary <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>*
+
getparyx <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
getstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
getsyx <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
has_ic <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
has_il <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
has_key <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>*
+ has_mouse <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>*
hline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
hline_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
idcok <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
key_defined <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>*
key_name <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
keybound <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>*
-
keyname <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
keyok <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>*
keypad <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
killchar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
killwchar <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
leaveok <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
+
longname <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>
mcprint <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>*
meta <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
mvwaddnwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>
mvwaddstr <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>
mvwaddwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>
-
mvwchgat <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
mvwdelch <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG>
mvwget_wch <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
mvwget_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
mvwgetch <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
mvwgetn_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
+
mvwgetnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
mvwgetstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>
mvwhline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
overlay <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG>
overwrite <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG>
pair_content <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
+ pecho_wchar <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>*
pechochar <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
pnoutrefresh <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
prefresh <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
raw <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
redrawwin <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
refresh <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
+ reset_color_pairs <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>*
reset_prog_mode <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
reset_shell_mode <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
resetty <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
restartterm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
ripoffline <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
savetty <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>
-
scanw <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>
scr_dump <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
scr_init <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
scr_restore <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
+
scr_set <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>
scrl <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
scroll <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
slk_restore <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
slk_set <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
slk_touch <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
+ slk_wset <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>*
standend <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
standout <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
start_color <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
use_default_colors <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>*
use_env <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>
use_extended_names <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG>*
-
use_legacy_coding <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG>*
use_tioctl <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>*
vid_attr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
+
vid_puts <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
vidattr <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
vidputs <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
winch <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>
winchnstr <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>
winchstr <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>
-
winnstr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
winnwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
wins_nwstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
+
wins_wch <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>
wins_wstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>
winsch <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG>
wvline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>
wvline_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG>
+ Depending on the configuration, additional sets of functions may be
+ available:
+
+ <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG> - curses memory-leak checking
+
+ <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> - curses screen-pointer extension
+
+ <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> - curses thread support
+
+ <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> - curses debugging routines
+
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
Routines that return an integer return <STRONG>ERR</STRONG> upon failure and an integer
(i.e., these should not be used as the right-hand side of assignment
statements).
+ Functions with a "mv" prefix first perform a cursor movement using
+ <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if
+ the window pointer is null. Most "mv"-prefixed functions (except vari-
+ adic functions such as <STRONG>mvprintw</STRONG>) are provided both as macros and func-
+ tions.
+
Routines that return pointers return <STRONG>NULL</STRONG> on error.
between the XSI Curses and <STRONG>ncurses</STRONG> calls) are described in <STRONG>PORTABILITY</STRONG>
sections of the library man pages.
+
+</PRE><H3><a name="h3-Error-checking">Error checking</a></H3><PRE>
+ 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 point-
- ers 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
+ ers 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.
- This implementation also contains several extensions:
+
+</PRE><H3><a name="h3-Extensions-versus-portability">Extensions versus portability</a></H3><PRE>
+ 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:
<STRONG>o</STRONG> The routine <STRONG>has_key</STRONG> is not part of XPG4, nor is it present in SVr4.
See the <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> manual page for details.
- <STRONG>o</STRONG> The routine <STRONG>slk_attr</STRONG> is not part of XPG4, nor is it present in
+ <STRONG>o</STRONG> The routine <STRONG>slk_attr</STRONG> is not part of XPG4, nor is it present in
SVr4. See the <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> manual page for details.
- <STRONG>o</STRONG> The routines <STRONG>getmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mouseinterval</STRONG>, and
- <STRONG>wenclose</STRONG> relating to mouse interfacing are not part of XPG4, nor
- are they present in SVr4. See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual page for
+ <STRONG>o</STRONG> The routines <STRONG>getmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mouseinterval</STRONG>, and
+ <STRONG>wenclose</STRONG> relating to mouse interfacing are not part of XPG4, nor
+ are they present in SVr4. See the <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> manual page for
details.
- <STRONG>o</STRONG> The routine <STRONG>mcprint</STRONG> was not present in any previous curses imple-
+ <STRONG>o</STRONG> The routine <STRONG>mcprint</STRONG> was not present in any previous curses imple-
mentation. See the <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> manual page for details.
<STRONG>o</STRONG> The routine <STRONG>wresize</STRONG> is not part of XPG4, nor is it present in SVr4.
tion programs. See <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> for the discussion of <STRONG>is_scrol-</STRONG>
<STRONG>lok</STRONG>, etc.
- <STRONG>o</STRONG> This implementation can be configured to provide rudimentary sup-
- port for multi-threaded applications. See <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> for
+ <STRONG>o</STRONG> This implementation can be configured to provide rudimentary sup-
+ port for multi-threaded applications. See <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> for
details.
- <STRONG>o</STRONG> This implementation can also be configured to provide a set of
- functions which improve the ability to manage multiple screens.
+ <STRONG>o</STRONG> This implementation can also be configured to provide a set of
+ functions which improve the ability to manage multiple screens.
See <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> for details.
- In historic curses versions, delays embedded in the capabilities <STRONG>cr</STRONG>,
- <STRONG>ind</STRONG>, <STRONG>cub1</STRONG>, <STRONG>ff</STRONG> and <STRONG>tab</STRONG> activated corresponding delay bits in the UNIX
+
+</PRE><H3><a name="h3-Padding-differences">Padding differences</a></H3><PRE>
+ In historic curses versions, delays embedded in the capabilities <STRONG>cr</STRONG>,
+ <STRONG>ind</STRONG>, <STRONG>cub1</STRONG>, <STRONG>ff</STRONG> and <STRONG>tab</STRONG> 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 inter-
- face to the UNIX kernel significantly and increases the package's
+ bytes. This method is slightly more expensive, but narrows the inter-
+ face to the UNIX kernel significantly and increases the package's
portability correspondingly.
-</PRE><H
2><a name="h2-NOTES">NOTES</a></H2><PRE>
- The header file <STRONG><curses.h></STRONG> automatically includes the header files
+</PRE><H
3><a name="h3-Header-files">Header files</a></H3><PRE>
+ The header file <STRONG><curses.h></STRONG> automatically includes the header files
<STRONG><stdio.h></STRONG> and <STRONG><unctrl.h></STRONG>.
- If standard output from a <STRONG>ncurses</STRONG> program is re-directed to something
- which is not a tty, screen updates will be directed to standard error.
+ 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:
+
+ <STRONG>o</STRONG> 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 <EM>externs</EM>).
+
+ BSD curses used <stdio.h> internally (for <STRONG>printw</STRONG> and <STRONG>scanw</STRONG>), but
+ nothing in <curses.h> itself relied upon <stdio.h>.
+
+ <STRONG>o</STRONG> SVr2 curses added <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>, which relies upon <stdio.h>. That
+ is, the function prototype uses <STRONG>FILE</STRONG>.
+
+ SVr4 curses added <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG>, 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>.
+
+ <STRONG>o</STRONG> X/Open Curses is inconsistent with respect to SVr4 regarding <unc-
+ trl.h>.
+
+ As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, ncurses includes <unctrl.h> from
+ <curses.h> (like SVr4).
+
+ <STRONG>o</STRONG> 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 <STRONG>setupterm</STRONG>
+ 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.
+
+ <STRONG>o</STRONG> X/Open says that <curses.h> <EM>may</EM> 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>.
+
+ <STRONG>o</STRONG> X/Open Curses says <EM>"may</EM> <EM>make</EM> <EM>visible"</EM> 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> <EM>may</EM> 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 visi-
+ ble. That depends on the value used for <STRONG>_XOPEN_SOURCE</STRONG> feature test
+ macro.
+
+ <STRONG>o</STRONG> X/Open Curses documents one required header, in a special case:
+ <stdarg.h> before <curses.h> to prototype the <STRONG>vw_printw</STRONG> and
+ <STRONG>vw_scanw</STRONG> functions (as well as the obsolete the <STRONG>vwprintw</STRONG> and <STRONG>vws-</STRONG>
+ <STRONG>canw</STRONG> functions). Each of those uses a <STRONG>va_list</STRONG> 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 <STRONG>void*</STRONG> for the <STRONG>va_list</STRONG> 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.
+
+
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+ If standard output from a <STRONG>ncurses</STRONG> program is re-directed to something
+ which is not a tty, screen updates will be directed to standard error.
This was an undocumented feature of AT&T System V Release 3 curses.
<li><a href="#h2-FILES">FILES</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
-<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a>
+<ul>
+<li><a href="#h3-Error-checking">Error checking</a></li>
+<li><a href="#h3-Extensions-versus-portability">Extensions versus portability</a></li>
+<li><a href="#h3-Padding-differences">Padding differences</a></li>
+<li><a href="#h3-Header-files">Header files</a></li>
+</ul>
+</li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-AUTHORS">AUTHORS</a></li>
</ul>
projects / ncurses.git / blobdiff