curs\_scanw(3X) Library calls curs\_scanw(3X) # [NAME](#NAME) **scanw**, **wscanw**, **mvscanw**, **mvwscanw**, **vwscanw**, **vw\_scanw** - read formatted input from a *curses* window # [SYNOPSIS](#SYNOPSIS) ``` #include ``` ``` 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](#DESCRIPTION) **scanw**, **wscanw**, **mvscanw**, and **mvwscanw** are analogous to [*scanf*(3)](/man/os/ncurses/scanf.3). In effect, they call [**wgetstr**(3X)](/man/os/ncurses/wgetstr.3X) with *win* (or **stdscr**) as its first argument, then attempt conversion of the resulting string with [*vsscanf*(3)](/man/os/ncurses/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)](/man/os/ncurses/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](#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)](/man/os/ncurses/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](#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)](/man/os/ncurses/scanf.3) conversions “%lc” and “%ls” for wide characters and strings, respectively. *ncurses* implements [*vsscanf*(3)](/man/os/ncurses/vsscanf.3) internally if it is unavailable when the library is configured. # [PORTABILITY](#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)](/man/os/ncurses/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)](/man/os/ncurses/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](#HISTORY) 4BSD (1980) introduced *wscanw* and its variants. It implemented all as functions, not macros; this initial distribution of *curses* preceded the ANSI C standard of 1989, prior to which a variadic macro facility was not widely available. *scanw* went unused in Berkeley distributions until 4.3BSD-Reno (1990), which employed it in a game. 4BSD's *wscanw* did not use *varargs.h*, which 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. 4BSD documented *scanw* and *wscanw* tersely as “scanf through *stdscr*” and “scanf through *win*”, respectively. SVr3 (1987) stated \[t]hese routines correspond to [*scanf*(3S)](/man/os/ncurses/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 added *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 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](#SEE_ALSO) [**curses**(3X)](/man/os/ncurses/curses.3X), [**curs\_getstr**(3X)](/man/os/ncurses/curs_getstr.3X), [**curs\_printw**(3X)](/man/os/ncurses/curs_printw.3X), [**scanf**(3)](/man/os/ncurses/scanf.3), [**vscanf**(3)](/man/os/ncurses/vscanf.3) 2025-07-05 ncurses 6.6 --- Document: scanw(3x) from ncurses 6.6.20261031-r0 (Chainguard OS) Source: https://github.com/ThomasDickey/ncurses-snapshots