X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_scanw.3x.html;h=91b68292143bbeddc1e35baa573969f658e2b0e7;hb=HEAD;hp=48e8e9f7fcd2c900eecae61e0ef917cf5c427634;hpb=0ac2306dd3aaab1338d8b1458c15a7e476cfc3ff;p=ncurses.git diff --git a/doc/html/man/curs_scanw.3x.html b/doc/html/man/curs_scanw.3x.html index 48e8e9f7..d0b9b794 100644 --- a/doc/html/man/curs_scanw.3x.html +++ b/doc/html/man/curs_scanw.3x.html @@ -1,7 +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); --
- 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. + /* obsolete */ + int vwscanw(WINDOW *win, const char *fmt, va_list varglist); - 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>. +
+ 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 returns ERR on failure and an integer equal to the - number of fields scanned on success. + 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. - 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. +
+ 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. --
- 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 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. + Functions prefixed with "mv" first perform cursor movement and fail if + the position (y, x) is outside the window boundaries. --
- curses(3x), curs_getstr(3x), curs_printw(3x), scanf(3) +
+ 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. + + +
+ 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), vscanf(3) - curs_scanw(3x) +ncurses 6.5 2024-04-20 curs_scanw(3x)-