# curs_scanw 3x 2024-04-20 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

           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

           curses(3x), curs_getstr(3x), curs_printw(3x), scanf(3), vscanf(3)

    ncurses 6.5                       2024-04-20                    curs_scanw(3x)