- The scanw, wscanw and mvscanw routines are analogous to
- scanf [see scanf(3S)]. The effect of these routines is as
- though wgetstr were called on the window, and the result-
- ing line used as input for sscanf(3). Fields which do not
- map to a variable in the fmt field are lost.
+ 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 result-
+ ing line used as input for sscanf(3). Fields which do not
+ map to a variable in the fmt field are lost.
- The vwscanw routine is similar to vwprintw in that it per-
- forms a wscanw using a variable argument list. The third
- argument is a va_list, a pointer to a list of arguments,
- as defined in <varargs.h>.
+ 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 argu-
+ ments, as defined in <stdarg.h>.
RETURN VALUE
- vwscanw returns ERR on failure and an integer equal to the
+ 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
+ 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 move-
+ ment 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 func-
- tions. The function vwscanw is marked TO BE WITHDRAWN,
- and is to be replaced by a function vw_scanw using the
- <stdarg.h> interface.
+ tions. 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, Ver-
+ sion 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 applica-
+ tions should only test if the return value is ERR, since
+ the OK value (zero) is likely to be misleading. One pos-
+ sible 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.