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)
