vw_scanw(3) · carta

Usage

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);

Overview

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.

Return value

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.

Notes

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.

Portability

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.

History