- The XSI Curses standard, Issue 4 describes these functions. The func-
- tion <STRONG>vwscanw</STRONG> is marked TO BE WITHDRAWN, and is to be replaced by a
- function <STRONG>vw_scanw</STRONG> using the <STRONG><stdarg.h></STRONG> interface. The Single Unix
- Specification, Version 2 states that <STRONG>vw_scanw</STRONG> is preferred to <STRONG>vwscanw</STRONG>
- since the latter requires including <STRONG><varargs.h></STRONG>, which cannot be used
- in the same file as <STRONG><stdarg.h></STRONG>. This implementation uses <STRONG><stdarg.h></STRONG>
- for both, because that header is included in <STRONG><curses.h</STRONG>>.
-
- Both XSI and The Single Unix Specification, Version 2 state that these
- functions return ERR or OK. Since the underlying <STRONG>scanf(3)</STRONG> can return
- the number of items scanned, and the SVr4 code was documented to use
- this feature, this is probably an editing error which was introduced in
- XSI, rather than being done intentionally. Portable applications
- should only test if the return value is ERR, since the OK value (zero)
- is likely to be misleading. One possible way to get useful results
- would be to use a "%n" conversion at the end of the format string to
- ensure that something was processed.
+ X/Open Curses, Issue 4 describes these functions. It specifies no
+ error conditions for them.
+
+ <EM>ncurses</EM> defines <STRONG>vw_scanw</STRONG> and <STRONG>vwscanw</STRONG> identically to support legacy
+ applications. However, the latter is obsolete.
+
+ <STRONG>o</STRONG> X/Open Curses, Issue 4 Version 2 (1996), marked <STRONG>vwscanw</STRONG> as
+ requiring <EM>varargs.h</EM> and "TO BE WITHDRAWN", and specified <STRONG>vw_scanw</STRONG>
+ using the <EM>stdarg.h</EM> interface.
+
+ <STRONG>o</STRONG> X/Open Curses, Issue 5, Draft 2 (December 2007) marked <STRONG>vwscanw</STRONG>
+ (along with <STRONG>vwscanw</STRONG> and the <EM>termcap</EM> interface) as withdrawn. After
+ incorporating review comments, this became X/Open Curses, Issue 7
+ (2009).
+
+ <STRONG>o</STRONG> <EM>ncurses</EM> provides <STRONG>vwscanw</STRONG>, but marks it as deprecated.
+
+ X/Open Curses Issues 4 and 7 both state that these functions return <STRONG>ERR</STRONG>
+ or <STRONG>OK</STRONG>. This is likely an erratum.
+
+ <STRONG>o</STRONG> Since the underlying <STRONG>scanf(3)</STRONG> returns the number of successful
+ conversions, and SVr4 <EM>curses</EM> was documented to use this feature,
+ this may have been an editorial solecism introduced by X/Open,
+ rather than an intentional change.
+
+ <STRONG>o</STRONG> This implementation retains compatibility with SVr4 <EM>curses</EM>. As of
+ 2018, NetBSD <EM>curses</EM> also returns the number of successful
+ conversions. Both <EM>ncurses</EM> and NetBSD <EM>curses</EM> call <STRONG>vsscanf(3)</STRONG> to
+ scan the string, which returns <STRONG>EOF</STRONG> on error.
+
+ <STRONG>o</STRONG> Portable applications should test only if the return value is <STRONG>ERR</STRONG>,
+ and not compare it to <STRONG>OK</STRONG>, since that value (zero) might be
+ misleading.
+
+ One portable way to get useful results would be to use a "%n"
+ conversion at the end of the format string, and check the value of
+ the corresponding variable to determine how many conversions
+ succeeded.
+
+
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+ <STRONG>scanw</STRONG> was implemented in 4BSD (November 1980); that early version of
+ <EM>curses</EM> preceded the ANSI C standard of 1989. The function was unused
+ in Berkeley distributions for over ten years, until 4.4BSD, which
+ employed it in a game. The 4BSD <STRONG>scanw</STRONG> did not use <EM>varargs.h</EM>, though
+ that had been available since Seventh Edition Unix (1979). In 1991 (a
+ couple of years after SVr4 was generally available, and after the C
+ standard was published), other developers updated the library, using
+ <EM>stdarg.h</EM> internally in 4.4BSD <EM>curses</EM>. Even with this improvement, BSD
+ <EM>curses</EM> did not use function prototypes (nor even declare functions) in
+ <EM>curses.h</EM> until 1992.
+
+ SVr2 (1984) documented <STRONG>scanw</STRONG> and <STRONG>wscanw</STRONG> tersely as "scanf through
+ <STRONG>stdscr</STRONG>" and "scanf through <EM>win</EM>", respectively.
+
+ SVr3 (1987) added <STRONG>mvscanw</STRONG>, and <STRONG>mvwscanw</STRONG>, stating
+
+ "[t]hese routines correspond to <STRONG>scanf(3S)</STRONG>, as do their arguments
+ and return values. <STRONG>wgetstr</STRONG>() is called on the window, and the
+ resulting line is used as input for the scan."
+
+ SVr3 also implemented <STRONG>vwscanw</STRONG>, describing its third parameter as a
+ <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, defined in <EM>varargs.h</EM>, and referred the reader to the manual
+ pages for <EM>varargs</EM> and <EM>vprintf</EM> for detailed descriptions. (Because the
+ SVr3 documentation does not mention <EM>vscanf</EM>, the reference to <EM>vprintf</EM>
+ might not be an error).
+
+ SVr4 (1989) introduced no new variations of <EM>scanw</EM>, but provided for
+ using either <EM>varargs.h</EM> or <EM>stdarg.h</EM> to define the <EM>va</EM><STRONG>_</STRONG><EM>list</EM> type.
+
+ X/Open Curses, Issue 4 (1995), defined <EM>vw</EM><STRONG>_</STRONG><EM>scanw</EM> to replace <EM>vwscanw</EM>,
+ stating that its <EM>va</EM><STRONG>_</STRONG><EM>list</EM> type is defined in <EM>stdarg.h</EM>.