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)

ncurses 6.4                                        2023-12-23                                    scanw(3NCURSES)