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

       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)

ncurses 6.5                                        2025-01-18                                    scanw(3NCURSES)