scanw(3ncurses)

NAME

   scanw, wscanw, mvscanw, mvwscanw, vwscanw, vw_scanw - convert formatted
   input from a curses window

SYNOPSIS

   #include <curses.h>

   int scanw(char *fmt, ...);
   int wscanw(WINDOW *win, char *fmt, ...);
   int mvscanw(int y, int x, char *fmt, ...);
   int mvwscanw(WINDOW *win, int y, int x, char *fmt, ...);
   int vw_scanw(WINDOW *win, char *fmt, va_list varglist);
   int vwscanw(WINDOW *win, 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.   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

   The  XSI  Curses  standard,  Issue  4  describes  these functions.  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>.

   Both  XSI and The Single Unix Specification, Version 2 state that these
   functions return ERR or OK.  Since the underlying scanf 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.  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), scanf(3)

                                                           scanw(3NCURSES)

---

Free and Open Source Software