NAME

       scanw, wscanw, mvscanw, mvwscanw, vwscanw, vw_scanw - convert 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

       The  scanw,  wscanw  and  mvscanw  routines  are  analogous to scanf [see scanf(3)].  The effect of these
       routines is as though wgetstr were called on the window,  and  the  resulting  line  used  as  input  for
       sscanf(3).  Fields which do not map to a variable in the fmt field are lost.

       The  vwscanw  and  vw_scanw  routines are analogous to vscanf(3).  They 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

       vwscanw returns ERR on failure and an integer equal to the number of fields scanned on success.

       Applications  may use the return value from the scanw, wscanw, mvscanw and mvwscanw routines to determine
       the number of fields which were mapped in the call.

       Functions with a “mv” prefix first perform a cursor movement using wmove, and  return  an  error  if  the
       position is outside the window, or if the window pointer is null.

PORTABILITY

       In  this  implementation,  vw_scanw and vwscanw are equivalent, to support legacy applications.  However,
       the latter (vwscanw) is obsolete:

       •   The XSI Curses standard, Issue 4 described these functions,  noting  that  the  function  vwscanw  is
           marked TO BE WITHDRAWN, and is to be replaced by a function vw_scanw using the <stdarg.h> interface.

       •   The  Single  Unix  Specification,  Version  2 states that vw_scanw  is preferred to vwscanw since the
           latter requires including <varargs.h>, which cannot be used in the same  file  as  <stdarg.h>.   This
           implementation uses <stdarg.h> for both, because that header is included in <curses.h>.

       •   X/Open Curses, Issue 5 (December 2007) marked vwscanw (along with vwprintw and the termcap interface)
           as withdrawn.

       Both XSI and The Single Unix Specification, Version 2 state that these functions return ERR or OK.

       •   Since  the  underlying  scanf(3)  can  return  the  number  of  items  scanned, and the SVr4 code was
           documented to use this feature, this is probably an editing error which was introduced in XSI, rather
           than being done intentionally.

       •   This implementation returns the number of items scanned, for compatibility with SVr4 curses.   As  of
           2018,  NetBSD  curses  also returns the number of items scanned.  Both ncurses and NetBSD curses call
           vsscanf to scan the string, which returns EOF on error.

       •   Portable applications should only test if the return value is ERR,  since  the  OK  value  (zero)  is
           likely to be misleading.

           One  possible  way  to  get useful results would be to use a "%n" conversion at the end of the format
           string to ensure that something was processed.

SEE ALSO

       ncurses(3NCURSES), getstr(3NCURSES), printw(3NCURSES), curs_termcap(3X), scanf(3).

                                                                                                 scanw(3NCURSES)