# curs_scanw 3x 2025-07-05 ncurses 6.5 Library calls

    curs_scanw(3x)                   Library calls                  curs_scanw(3x)

## 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.

           o   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.

           o   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).

           o   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.

           o   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.

           o   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.

           o   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), vscanf(3)

    ncurses 6.5                       2025-07-05                    curs_scanw(3x)