curs_scanw.3x - Man Page

read formatted input from a curses window

Synopsis

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

Description

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 Issues 4 and 7 both state that these functions return ERR or OK. This is likely an erratum.

History

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.

See Also

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

Referenced By

The man pages mvscanw.3x(3), mvwscanw.3x(3), scanw.3x(3), vw_scanw.3x(3), vwscanw.3x(3) and wscanw.3x(3) are aliases of curs_scanw.3x(3).

2024-04-20 ncurses 6.5 Library calls