---
name: "scanw"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/curs_scanw"
---

# scanw(3)

read formatted input from a curses window

Part of [curs\_scanw(3)](/curs_scanw/3.md).

## NAME

**scanw**, **wscanw**, **mvscanw**, **mvwscanw**, **vwscanw**, **vw\_scanw** - 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 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

**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

**curses(3X),** **curs\_getstr(3X),** **curs\_printw(3X),** **[scanf(3)](/scanf/3.md),** **[vscanf(3)](/vscanf/3.md)**