X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fhtml%2Fman%2Fcurs_scanw.3x.html;h=b7da265df44a5074bc1c2a9a0eb42548e3c40b2b;hb=a1c9e77bebcdf278d9c290a97c82961e159cd896;hp=7d81e69e931cf3102bcb18a15b0376efe4df5bdc;hpb=a8e3f06ac309504143cd56ac9ec55889bfdf4914;p=ncurses.git diff --git a/doc/html/man/curs_scanw.3x.html b/doc/html/man/curs_scanw.3x.html index 7d81e69e..b7da265d 100644 --- a/doc/html/man/curs_scanw.3x.html +++ b/doc/html/man/curs_scanw.3x.html @@ -1,6 +1,7 @@ -
- --curs_scanw(3x) curs_scanw(3x) +curs_scanw(3x) Library calls curs_scanw(3x)
- scanw, wscanw, mvscanw, mvwscanw, vwscanw, vw_scanw - con- - vert formatted input from a curses window + scanw, wscanw, mvscanw, mvwscanw, vwscanw, vw_scanw - read formatted + input from a curses window
#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); + 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);
- 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. + 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. - The vwscanw and vw_scanw routines are analogous to - vscanf(3). They perform a wscanw using a variable argu- - ment list. The third argument is a va_list, a pointer to - a list of arguments, as defined in <stdarg.h>. + 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.
- vwscanw returns ERR on failure and an integer equal to the - number of fields scanned on success. + 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 with a "mv" prefix first perform a cursor movement using + wmove, and fail if the position is outside the window. + - 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. +
+ 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. - 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. + ncurses implements vsscanf(3) internally if it is unavailable when the + library is configured.
- 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. 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(3) can return the number of items - scanned, and the SVr4 code was documented to use this fea- - ture, this is probably an editing error which was intro- - duced in XSI, rather than being done intentionally. Por- - table 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. + 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. + + +
+ scanw was implemented in 4BSD (November 1980); that early version of + curses preceded the ANSI C standard of 1989. The function was unused + in Berkeley distributions for over ten years, until 4.4BSD, which + employed it in a game. The 4BSD scanw did not use varargs.h, though + that 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. + + SVr2 (1984) documented scanw and wscanw tersely as "scanf through + stdscr" and "scanf through win", respectively. + + SVr3 (1987) added mvscanw, and mvwscanw, stating + + "[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 also implemented 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 the + 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.
- curses(3x), curs_getstr(3x), curs_printw(3x), scanf(3) + curses(3x), curs_getstr(3x), curs_printw(3x), scanf(3), vscanf(3) - curs_scanw(3x) +ncurses 6.4 2023-12-23 curs_scanw(3x)