.\" 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
\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<stdarg.h>\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<stdarg.h>\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<varargs.h>\fP, which
-cannot be used in the same file as \fB<stdarg.h>\fP.
-This implementation uses \fB<stdarg.h>\fP for both, because that header
-is included in \fB<curses.h\fP>.
+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 <varargs.h>, 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 <stdarg.h> 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 <curses.h> 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 <varargs.h>,
-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 <varargs.h> or <stdarg.h> 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 <stdarg.h>.
+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)
projects / ncurses.git / blobdiff