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


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)