scanw(3NCURSES)

💖 scanw — read formatted input from a curses window 💖

okay bestie, we're in the ncurses section (that's the manual name, 3NCURSES, iykyk) and today's main character is scanw and its little friend group: wscanw, mvscanw, mvwscanw, vwscanw, and vw_scanw. They read formatted input from a curses window. It's giving "scanf but make it windowed" and honestly? iconic. ✨

---

🌸 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 🦋

so scanw, wscanw, mvscanw, and mvwscanw are literally the windowed sisters of scanf(3). Like, they're analogous to it. What they actually do: they call wgetstr(3NCURSES) with win (or stdscr if you didn't pass a window) as the first argument, and then they take that resulting string and attempt conversion with vsscanf(3). 🎀

Fields in the string that don't map to a variable in the fmt parameter? Just discarded. Gone. Not your problem. 💅

Then there's vwscanw and vw_scanw, which are analogous to vscanf(3) — they do a wscanw using a variable argument list. Their third argument is a va_list, which is a pointer to a list of arguments, as defined in stdarg.h. no cap.

---

🔥 RETURN VALUE 🔥

These functions return ERR when they fail. Otherwise they hand you back a count of successful conversions — and bestie, that quantity may be zero. Yes, zero is a valid success count. Don't come for me, that's just how it is. 😭

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 they 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. And honestly? They're unnecessary. If you wanna retrieve and convert a wide-character string from a curses terminal keyboard, just use these very functions with the scanf(3) conversions %lc and %ls for wide characters and wide strings respectively. Problem solved, slay. 💅

Also: ncurses implements vsscanf(3) internally if it's unavailable when the library is configured. Built-in backup, main character energy. 👑

---

💜 PORTABILITY 💜

X/Open Curses Issue 4 describes these functions. It specifies no error conditions for them. (Yeah. Weird. Moving on.)

ncurses defines vw_scanw and vwscanw identically, to support legacy applications. However — and this is the tea — 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. That's likely an erratum, bestie. 👀

• 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. tiny hack, huge payoff, periodt. ✨

---

🧚 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), 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 🌸

• ncurses(3NCURSES)
• getstr(3NCURSES)
• printw(3NCURSES)
• scanf(3)
• vscanf(3)

---

and that's the whole vibe check, bestie 💖 this was scanw, hanging out in ncurses 6.6, dated 2025-07-05. go format some input, you absolute icon. 🎀✨👑