--- name: "scanw" section: "3ncurses" platform: "linux" package: "ncurses-doc" version: "6.5+20250216-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/scanw/3ncurses" --- # scanw(3ncurses) read formatted input from a curses window ## NAME **scanw**, **wscanw**, **mvscanw**, **mvwscanw**, **vwscanw**, **vw\_scanw** - read formatted input from a *curses* window ## 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 **scanw,** **wscanw,** **mvscanw,** **and** **mvwscanw** **are analogous to** *scanf***(3).** **In effect,** **they call wgetstr(3NCURSES) 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 **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 **ncurses(3NCURSES),** **getstr(3NCURSES),** **printw(3NCURSES),** **[scanf(3)](/scanf/3.md),** **[vscanf(3)](/vscanf/3.md)**