https://invisible-island.net/ncurses/man/


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