Manual Pages  — curs_scanw

 scanw,  wscanw,  mvscanw,  mvwscanw,  vwscanw,  vw_scanw - read formatted input from a curses window

SYNOPSIS DESCRIPTION RETURN VALUE NOTES PORTABILITY HISTORY SEE ALSO

#include <curses.h>

int scanw(const char *fmt, ...);
int wscanw(WINDOW *win, const char *fmt, ...);
int mvscanw(int y, int x, const char *fmt, ...);
int mvwscanw(WINDOW *win, int y, int x, const char *fmt, ...);

int vw_scanw(WINDOW *win, const char *fmt, va_list varglist);

/* obsolete */
int vwscanw(WINDOW *win, const char *fmt, va_list varglist);

 scanw,  wscanw,  mvscanw, and  mvwscanw are analogous to  scanf(3). In effect, they call  wgetstr(3X) with win (or  stdscr) as its first argument, then attempt conversion of the resulting string with  vsscanf(3). Fields in the string that do not map to a variable in the fmt parameter are discarded.

 vwscanw and  vw_scanw are analogous to  vscanf(3), and perform a  wscanw using a variable argument list. The third argument is a  va_list, a pointer to a list of arguments, as defined in  stdarg.h.

These functions return ERR upon failure and otherwise a count of successful conversions; this quantity may be zero.

In  ncurses, failure occurs if  vsscanf(3) returns EOF, or if the window pointer win is null.

Functions prefixed with mv first perform cursor movement and fail if the position (y, x) is outside the window boundaries.

No wide character counterpart functions are defined by the wide  ncurses configuration nor by any standard. They are unnecessary: to retrieve and convert a wide-character string from a curses terminal keyboard, use these functions with the  scanf(3) conversions %lc and %ls for wide characters and strings, respectively.

 ncurses implements  vsscanf(3) internally if it is unavailable when the library is configured.

X/Open Curses, Issue 4 describes these functions. It specifies no error conditions for them.

 ncurses defines  vw_scanw and  vwscanw identically to support legacy applications. However, the latter is obsolete.

»	X/Open Curses, Issue 4 Version 2 (1996), marked  vwscanw as requiring  varargs.h and TO BE WITHDRAWN, and specified  vw_scanw using the  stdarg.h interface.
»	X/Open Curses, Issue 5, Draft 2 (December 2007) marked  vwscanw (along with  vwscanw and the termcap interface) as withdrawn. After incorporating review comments, this became X/Open Curses, Issue 7 (2009).
»	ncurses provides  vwscanw, but marks it as deprecated.

X/Open Curses Issues 4 and 7 both state that these functions return ERR or OK. This is likely an erratum.

»	Since the underlying  scanf(3) returns the number of successful conversions, and SVr4 curses was documented to use this feature, this may have been an editorial solecism introduced by X/Open, rather than an intentional change.
»	This implementation retains compatibility with SVr4 curses. As of 2018, NetBSD curses also returns the number of successful conversions. Both  ncurses and NetBSD curses call  vsscanf(3) to scan the string, which returns EOF on error.
»	Portable applications should test only if the return value is ERR, and not compare it to OK, 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.

 scanw was implemented in 4BSD (November 1980); that early version of curses 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  scanw did not use  varargs.h, 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  stdarg.h internally in 4.4BSD curses. Even with this improvement, BSD curses did not use function prototypes (nor even declare functions) in  curses.h until 1992.

SVr2 (1984) documented  scanw and  wscanw tersely as scanf through  stdscr and scanf through win, respectively.

SVr3 (1987) added  mvscanw, and  mvwscanw, stating

[t]hese routines correspond to scanf(3S), as do their arguments and return values.  wgetstr() is called on the window, and the resulting line is used as input for the scan.

SVr3 also implemented  vwscanw, describing its third parameter as a  va_list, defined in  varargs.h, and referred the reader to the manual pages for  varargs and  vprintf for detailed descriptions. (Because the SVr3 documentation does not mention  vscanf, the reference to  vprintf might not be an error).

SVr4 (1989) introduced no new variations of  scanw, but provided for using either  varargs.h or  stdarg.h to define the  va_list type.

X/Open Curses, Issue 4 (1995), defined  vw_scanw to replace  vwscanw, stating that its  va_list type is defined in  stdarg.h.

 curses(3X),  curs_getstr(3X),  curs_printw(3X),  scanf(3),  vscanf(3)