X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_scanw.3x;fp=man%2Fcurs_scanw.3x;h=333263d2cbd9b077cbd92d6adda5ee7abda4f285;hb=d90067f9008bb8338a77c1ed519bc108c275ed04;hp=47993a7ed7fae0f2cf0fe0b863e1df71dd76354d;hpb=b97ea58e03d5faebed2166faa4e0e590f2cdea34;p=ncurses.git diff --git a/man/curs_scanw.3x b/man/curs_scanw.3x index 47993a7e..333263d2 100644 --- a/man/curs_scanw.3x +++ b/man/curs_scanw.3x @@ -27,8 +27,8 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_scanw.3x,v 1.43 2023/11/25 11:31:06 tom Exp $ -.TH curs_scanw 3X 2023-11-25 "ncurses 6.4" "Library calls" +.\" $Id: curs_scanw.3x,v 1.44 2023/12/17 22:50:40 tom Exp $ +.TH curs_scanw 3X 2023-12-17 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq @@ -67,109 +67,184 @@ read formatted input from a \fIcurses\fR window \fBint vwscanw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP); .fi .SH DESCRIPTION -The \fBscanw\fP, \fBwscanw\fP and \fBmvscanw\fP routines are analogous to -\fBscanf\fP [see \fBscanf\fP(3)]. -The effect of these routines is as though -\fBwgetstr\fP were called on the window, and the resulting line used as input -for \fBsscanf\fP(3). -Fields which do not map to a variable in the \fIfmt\fP -field are lost. +\fB\%scanw\fP, +\fB\%wscanw\fP, +\fB\%mvscanw\fP, +and +\fB\%mvwscanw\fP +are analogous to \fI\%scanf\fP(3). +In effect, +they call \fB\%wgetstr\fP(3X) with +.I win +(or +.BR \%stdscr ) +as its first argument, +then attempt conversion of the resulting string with \fI\%vsscanf\fP(3). +Fields in the string that do not map to a variable in the \fIfmt\fP +parameter are discarded. .PP -The \fBvwscanw\fP and \fBvw_scanw\fP routines are analogous to \fBvscanf\fP(3). -They perform a \fBwscanw\fP using a variable argument list. -The third argument is a \fBva_list\fP, -a pointer to a list of arguments, as defined in \fB\fP. +\fB\%vwscanw\fP +and +\fB\%vw_scanw\fP are analogous to \fI\%vscanf\fP(3), +and perform a \fB\%wscanw\fP using a variable argument list. +The third argument is a \fI\%va_list\fP, +a pointer to a list of arguments, +as defined in \fI\%stdarg.h\fP. .SH RETURN VALUE -\fBvwscanw\fP returns \fBERR\fP on failure and an integer equal to the -number of fields scanned on success. +These functions return +.B ERR +upon failure and otherwise a count of successful conversions; +this quantity may be zero. +.PP +In +.I \%ncurses, +failure occurs if \fI\%vsscanf\fP(3) returns +\fBEOF\fP, +or if the window pointer +.I win +is null. .PP -Applications may use the return value from the \fBscanw\fP, \fBwscanw\fP, -\fBmvscanw\fP and \fBmvwscanw\fP routines to determine the number of fields -which were mapped in the call. +Functions with a \*(``mv\*('' prefix first perform a cursor movement +using \fB\%wmove\fP, +and fail if the position is outside the window. +.SH NOTES +No wide character counterpart functions are defined by the +\*(``wide\*('' +.I \%ncurses +configuration nor by any standard. +They are unnecessary: +to retrieve and convert a wide-character string from a +.I curses +terminal keyboard, +use these functions with the \fI\%scanf\fP(3) conversions \*(``%lc\*('' +and \*(``%ls\*('' for wide characters and strings, +respectively. .PP -Functions with a \*(``mv\*('' prefix first perform a cursor movement using -\fBwmove\fP, and return an error if the position is outside the window, -or if the window pointer is null. +.I \%ncurses +implements \fI\%vsscanf\fP(3) internally if it is unavailable when the +library is configured. .SH PORTABILITY -In this implementation, \fBvw_scanw\fP and \fBvwscanw\fP are equivalent, -to support legacy applications. -However, the latter (\fBvwscanw\fP) is obsolete: +X/Open Curses, Issue 4, describes these functions. +It specifies no error conditions for them. +.PP +.I \%ncurses +defines \fB\%vw_scanw\fP and \fB\%vwscanw\fP identically to support +legacy applications. +However, +the latter is obsolete. .bP -The XSI Curses standard, Issue 4 described these functions, -noting that the function -\fBvwscanw\fP is marked TO BE WITHDRAWN, and is to be replaced by a function -\fBvw_scanw\fP using the \fB\fP interface. +X/Open Curses, Issue 4, Version 2 (1996), +marked \fB\%vwscanw\fP as requiring \fI\%varargs.h\fP and +\*(``TO BE WITHDRAWN\*('', +and specified \fB\%vw_scanw\fP using the \fI\%stdarg.h\fP interface. .bP -The Single Unix Specification, Version 2 states that -\fBvw_scanw\fP is preferred to \fBvwscanw\fP since the latter requires -including \fB\fP, which -cannot be used in the same file as \fB\fP. -This implementation uses \fB\fP for both, because that header -is included in \fB. +X/Open Curses, Issue 5, Draft 2 +(December 2007) marked \fB\%vwscanw\fP (along with +\fB\%vwscanw\fP and the termcap interface) as withdrawn. +After incorporating review comments, +this became +X/Open Curses, Issue 7 (2009). .bP -X/Open Curses, Issue 5 (December 2007) marked \fBvwscanw\fP (along with -\fBvwprintw\fP and the termcap interface) as withdrawn. -.LP -Both XSI and The Single Unix Specification, Version 2 state that these -functions return \fBERR\fP or \fBOK\fP. +.I \%ncurses +provides \fB\%vwscanw\fP, +but marks it as deprecated. +.PP +X/Open Curses Issues 4 and 7 both state that these functions return +\fBERR\fP or \fBOK\fP. +This is likely an erratum. .bP -Since the underlying \fBscanf\fP(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. +Since the underlying \fI\%scanf\fP(3) returns the number of successful +conversions, +and SVr4 +.I curses +was documented to use this feature, +this may have been an editorial solecism introduced by X/Open, +rather than an intentional change. .bP -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 \fBvsscanf\fP to scan the string, +This implementation retains compatibility with SVr4 +.I curses. +As of 2018, +NetBSD +.I curses +also returns the number of successful conversions. +Both +.I \%ncurses\fP +and NetBSD +.I curses +call \fI\%vsscanf\fP(3) to scan the string, which returns \fBEOF\fP on error. .bP -Portable applications should only test if the return value is \fBERR\fP, -since the \fBOK\fP value (zero) is likely to be misleading. +Portable applications should test only if the return value is \fBERR\fP, +and not compare it to \fBOK\fP, +since that value (zero) might be misleading. .IP -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. +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. .SH HISTORY -While \fBscanw\fP 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 , though that was available. -In 1991 (a couple of years after SVr4 was generally available, +\fB\%scanw\fP was implemented in 4BSD +(November 1980); +.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\ +.\" libcurses/scanw.c +that early version of +.I 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 \fB\%scanw\fP did not use \fI\%varargs.h\fP, +though that had been available since Seventh Edition Unix (1979). +.\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\ +.\" varargs.h +In 1991 +(a couple of years after SVr4 was generally available, and after the C standard was published), other developers updated the library, -using internally in 4.4BSD curses. +using \fI\%stdarg.h\fP internally in 4.4BSD +.I curses. Even with this improvement, -BSD curses did not use function prototypes (or even declare -functions) in the header until 1992. +BSD +.I curses +did not use function prototypes +(nor even declare functions) +in \fI\%curses.h\fP until 1992. +.PP +SVr2 (1984) documented \fB\%scanw\fP and \fB\%wscanw\fP tersely as +\*(``scanf through \fB\%stdscr\fP\*('' and +\*(``scanf through \fIwin\fP\*('', +respectively. +.PP +SVr3 (1987) added +\fB\%mvscanw\fP, and +\fB\%mvwscanw\fP, stating +.RS .PP -SVr2 documented -\fBscanw\fP, -\fBwscanw\fP -tersely as \*(``scanf through \fIstdscr\fP\*('' and -tersely as \*(``scanf through \fIwin\fP\*('', respectively. +These routines correspond to \fIscanf\fP(3S), +as do their arguments and return values. +\fB\%wgetstr\fP() is called on the window, +and the resulting line is used as input for the scan. +.RE .PP -SVr3 added -\fBmvscanw\fP, and -\fBmvwscanw\fP, with a three-line summary saying that they were analogous -to \fBscanf\fP(3), -explaining that the string which would be output from \fBscanf\fP(3) would -instead be output using \fBwaddstr\fP on the given window. -SVr3 also added \fBvwscanw\fP, saying that the third parameter -is a \fBva_list\fP, defined in , -and referring the reader to the manual pages for \fIvarargs\fP and -\fBvprintf\fP for detailed descriptions. -(Because the SVr3 documentation does not mention \fBvscanf\fP, -that reference to \fBvprintf\fP may not be an error). +SVr3 also implemented \fB\%vwscanw\fP, +describing its third parameter as a \fI\%va_list\fP, +defined in \fI\%varargs.h\fP, +and referred the reader to the manual pages for \fI\%varargs\fP and +\fI\%vprintf\fP for detailed descriptions. +(Because the SVr3 documentation does not mention \fI\%vscanf\fP, +the reference to \fI\%vprintf\fP might not be an error). .PP -SVr4 added no new variations of \fBscanw\fP, -but provided for using or to define the \fBva_list\fP -type. +SVr4 (1989) introduced no new variations of \fI\%scanw\fP, +but provided for using either \fI\%varargs.h\fP or \fI\%stdarg.h\fP to +define the \fI\%va_list\fP type. +.\" either header declares "va_list", but only one can be used .PP -X/Open Curses added \fBvw_scanw\fP to replace \fBvwscanw\fP, -stating that its \fBva_list\fP definition requires . +X/Open Curses, Issue 4 (1995), +defined \fI\%vw_scanw\fP to replace \fI\%vwscanw\fP, +stating that its \fI\%va_list\fP type is defined in \fI\%stdarg.h\fP. .SH SEE ALSO \fB\%curses\fP(3X), \fB\%curs_getstr\fP(3X), \fB\%curs_printw\fP(3X), -\fB\%curs_termcap\fP(3X), -\fB\%scanf\fP(3) +\fB\%scanf\fP(3), +\fB\%vscanf\fP(3)