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(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  with a “mv” prefix first perform a cursor movement using wmove, and fail if the
       position is outside the window.

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