X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_scanw.3x.html;h=1fc75d3e1c82b47d9d29722fe0076f2ad8222458;hb=d1a029866f6d84087781eaa81de19949d8533426;hp=ed3fd6e84c59122f8558111e543f19526b9232d4;hpb=8d3ea9021573747ecd129228ba7782a03243f62c;p=ncurses.git diff --git a/doc/html/man/curs_scanw.3x.html b/doc/html/man/curs_scanw.3x.html index ed3fd6e8..1fc75d3e 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) @@ -53,12 +54,15 @@
#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);
@@ -70,7 +74,7 @@ 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>. + a va_list, a pointer to a list of arguments, as defined in <stdarg.h>.
@@ -86,32 +90,80 @@ the window pointer is null. +
+ 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 + available. 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. + + 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>. + +
- The XSI Curses standard, Issue 4 describes these functions. The func- - tion 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(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. 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. + 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 + compatibility 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" + conversion at the end of the format string to ensure that something + was processed.
- curses(3x), curs_getstr(3x), curs_printw(3x), scanf(3) + curses(3x), curs_getstr(3x), curs_printw(3x), curs_termcap(3x), + scanf(3). - curs_scanw(3x) +ncurses 6.4 2022-02-12 curs_scanw(3x)