4.4BSD: curs_scanw manual page

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

     4BSD (1980) introduced wscanw and its variants.  It implemented all as
     functions, not macros; this initial distribution of curses preceded the
     ANSI C standard of 1989, prior to which a variadic macro facility was not
     widely available.  scanw went unused in Berkeley distributions until
     4.3BSD-Reno (1990), which employed it in a game.  4BSD's wscanw did not
     use varargs.h, which 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.

     4BSD documented scanw and wscanw tersely as "scanf through stdscr" and
     "scanf through win", respectively.  SVr3 (1987) stated

            [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 added 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 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.

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

PORTABILITY

HISTORY

SEE ALSO