X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fhtml%2Fman%2Fcurs_scanw.3x.html;h=8bbd242fa1f061b80a84412bd22dd6e8a21b7e3e;hb=790a85dbd4a81d5f5d8dd02a44d84f01512ef443;hp=9c072a3d056c6e8cac9e8975c65a68a0aaf90fd8;hpb=b0b1980be11bba618d84beb8b30ac94e2c820602;p=ncurses.git diff --git a/doc/html/man/curs_scanw.3x.html b/doc/html/man/curs_scanw.3x.html index 9c072a3d..8bbd242f 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) 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 - convert 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. - 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>. +
+ 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(3). 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>. --
- 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. +
+ vwscanw returns ERR on failure and an integer equal to the number of + fields scanned on success. - 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. + 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. --
- 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. +
+ While scanw was implemented in 4BSD, none of the BSD releases used it + until 4.4BSD (in a game). That early version of curses was before the + ANSI C standard. It did not use <varargs.h>, though that was avail- + able. 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 (or even + declare functions) in the <curses.h> header until 1992. --
- curses(3x), curs_getstr(3x), curs_printw(3x), scanf(3) + SVr2 documented scanw, wscanw tersely as "scanf through stdscr" and + tersely as "scanf through win", respectively. + + SVr3 added mvscanw, and mvwscanw, with a three-line summary saying that + they were analogous to scanf(3), explaining that the string which would + be output from scanf(3) would instead be output using waddstr on the + given window. SVr3 also added vwscanw, saying that the third parameter + is a va_list, defined in <varargs.h>, and referring the reader to the + manual pages for varargs and vprintf for detailed descriptions. + (Because the SVr3 documentation does not mention vscanf, that reference + to vprintf may not be an error). + + SVr4 added no new variations of scanw, but provided for using + <varargs.h> or <stdarg.h> to define the va_list type. + + X/Open Curses added vw_scanw to replace vwscanw, stating that its + va_list definition requires <stdarg.h>. + + +
+ In this implementation, vw_scanw and vwscanw are equivalent, to support + legacy applications. However, the latter (vwscanw) is obsolete: + + o The XSI Curses standard, Issue 4 described these functions, noting + that the function vwscanw is marked TO BE WITHDRAWN, and is to be + replaced by a function vw_scanw using the <stdarg.h> interface. + + o 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>. + + o X/Open Curses, Issue 5 (December 2007) marked vwscanw (along with + vwprintw and the termcap interface) as withdrawn. + + Both XSI and The Single Unix Specification, Version 2 state that these + functions return ERR or OK. + + o Since the underlying scanf(3) 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. + + o This implementation returns the number of items scanned, for com- + patibility with SVr4 curses. As of 2018, NetBSD curses also + returns the number of items scanned. Both ncurses and NetBSD + curses call vsscanf to scan the string, which returns EOF on error. + + o 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" con- + version at the end of the format string to ensure that something + was processed. + + +
+ curses(3x), curs_getstr(3x), curs_printw(3x), curs_termcap(3x), + scanf(3). - curs_scanw(3x) + curs_scanw(3x)-