# curs_scanw 3x 2025-04-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-04-05                    curs_scanw(3x)