X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_scanw.3x.html;fp=doc%2Fhtml%2Fman%2Fcurs_scanw.3x.html;h=a0b8d7cccec521839abc62029a9257c3025016b1;hp=6b51f936d6828477389f216c3c7b825c716dc21f;hb=d90067f9008bb8338a77c1ed519bc108c275ed04;hpb=b97ea58e03d5faebed2166faa4e0e590f2cdea34 diff --git a/doc/html/man/curs_scanw.3x.html b/doc/html/man/curs_scanw.3x.html index 6b51f936..a0b8d7cc 100644 --- a/doc/html/man/curs_scanw.3x.html +++ b/doc/html/man/curs_scanw.3x.html @@ -27,19 +27,24 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_scanw.3x,v 1.43 2023/11/25 11:31:06 tom Exp @ + * @Id: curs_scanw.3x,v 1.44 2023/12/17 22:50:40 tom Exp @ + * https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\ + * libcurses/scanw.c + * https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\ + * varargs.h + * either header declares "va_list", but only one can be used -->
-curs_scanw(3x) Library calls curs_scanw(3x) @@ -66,104 +71,120 @@
- 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. + 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 argument 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. - 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. + 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 return an error if the position is outside the window, or if - the window pointer is null. + Functions with a "mv" prefix first perform a cursor movement using + wmove, and fail if the position is outside the window. + + +
+ 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.
- In this implementation, vw_scanw and vwscanw are equivalent, to support - legacy applications. However, the latter (vwscanw) is obsolete: + X/Open Curses, Issue 4, describes these functions. It specifies no + error conditions for them. - 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. + ncurses defines vw_scanw and vwscanw identically to support legacy + applications. However, the latter is obsolete. - 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 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 (December 2007) marked vwscanw (along with - vwprintw and the termcap interface) as withdrawn. + 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). - Both XSI and The Single Unix Specification, Version 2 state that these - functions return ERR or OK. + o ncurses provides vwscanw, but marks it as deprecated. - 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. + X/Open Curses Issues 4 and 7 both state that these functions return ERR + or OK. This is likely an erratum. - 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 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 Portable applications should only test if the return value is ERR, - since the OK value (zero) is likely to be misleading. + 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. - 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. + 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.
- 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>. + 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 + + These 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), curs_termcap(3x), - scanf(3) + curses(3x), curs_getstr(3x), curs_printw(3x), scanf(3), vscanf(3) -ncurses 6.4 2023-11-25 curs_scanw(3x) +ncurses 6.4 2023-12-17 curs_scanw(3x)