diff options
Diffstat (limited to 'doc/html/man/curs_scanw.3x.html')
| -rw-r--r-- | doc/html/man/curs_scanw.3x.html | 79 |
1 files changed, 55 insertions, 24 deletions
diff --git a/doc/html/man/curs_scanw.3x.html b/doc/html/man/curs_scanw.3x.html index a757666..d011449 100644 --- a/doc/html/man/curs_scanw.3x.html +++ b/doc/html/man/curs_scanw.3x.html @@ -1,4 +1,4 @@ -<!-- +<!-- **************************************************************************** * Copyright 2018-2019,2020 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * @@ -27,7 +27,7 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_scanw.3x,v 1.26 2020/02/02 23:34:34 tom Exp @ + * @Id: curs_scanw.3x,v 1.28 2020/10/24 09:29:26 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> @@ -54,14 +54,15 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>scanw(const</STRONG> <STRONG>char</STRONG> <STRONG>*fmt,</STRONG> <STRONG>...);</STRONG> - <STRONG>int</STRONG> <STRONG>wscanw(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*fmt,</STRONG> <STRONG>...);</STRONG> - <STRONG>int</STRONG> <STRONG>mvscanw(int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*fmt,</STRONG> <STRONG>...);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwscanw(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>int</STRONG> <STRONG>y,</STRONG> <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*fmt,</STRONG> <STRONG>...);</STRONG> - <STRONG>int</STRONG> <STRONG>vw_scanw(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*fmt,</STRONG> <STRONG>va_list</STRONG> <STRONG>varglist);</STRONG> + <STRONG>int</STRONG> <STRONG>scanw(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>fmt</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> + <STRONG>int</STRONG> <STRONG>wscanw(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>fmt</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> + <STRONG>int</STRONG> <STRONG>mvscanw(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>fmt</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwscanw(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>fmt</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> + + <STRONG>int</STRONG> <STRONG>vw_scanw(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>fmt</EM><STRONG>,</STRONG> <STRONG>va_list</STRONG> <EM>varglist</EM><STRONG>);</STRONG> /* obsolete */ - <STRONG>int</STRONG> <STRONG>vwscanw(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*fmt,</STRONG> <STRONG>va_list</STRONG> <STRONG>varglist);</STRONG> + <STRONG>int</STRONG> <STRONG>vwscanw(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>fmt</EM><STRONG>,</STRONG> <STRONG>va_list</STRONG> <EM>varglist</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> @@ -89,41 +90,70 @@ the window pointer is null. +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + While <STRONG>scanw</STRONG> 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 <STRONG>scanw</STRONG>, <STRONG>wscanw</STRONG> tersely as "scanf through <EM>stdscr</EM>" and + tersely as "scanf through <EM>win</EM>", respectively. + + SVr3 added <STRONG>mvscanw</STRONG>, and <STRONG>mvwscanw</STRONG>, with a three-line summary saying that + they were analogous to <STRONG>scanf(3)</STRONG>, explaining that the string which would + be output from <STRONG>scanf(3)</STRONG> would instead be output using <STRONG>waddstr</STRONG> on the + given window. SVr3 also added <STRONG>vwscanw</STRONG>, saying that the third parameter + is a <STRONG>va_list</STRONG>, defined in <varargs.h>, and referring the reader to the + manual pages for <EM>varargs</EM> and <EM>vprintf</EM> for detailed descriptions. + (Because the SVr3 documentation does not mention <EM>vscanf</EM>, that reference + to <EM>vprintf</EM> may not be an error). + + SVr4 added no new variations of <STRONG>scanw</STRONG>, but provided for using + <varargs.h> or <stdarg.h> to define the <STRONG>va_list</STRONG> type. + + X/Open Curses added <STRONG>vw_scanw</STRONG> to replace <STRONG>vwscanw</STRONG>, stating that its + <STRONG>va_list</STRONG> definition requires <stdarg.h>. + + </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> In this implementation, <STRONG>vw_scanw</STRONG> and <STRONG>vwscanw</STRONG> are equivalent, to support legacy applications. However, the latter (<STRONG>vwscanw</STRONG>) is obsolete: - <STRONG>o</STRONG> The XSI Curses standard, Issue 4 described these functions, noting - that the function <STRONG>vwscanw</STRONG> is marked TO BE WITHDRAWN, and is to be + <STRONG>o</STRONG> The XSI Curses standard, Issue 4 described these functions, noting + that the function <STRONG>vwscanw</STRONG> is marked TO BE WITHDRAWN, and is to be replaced by a function <STRONG>vw_scanw</STRONG> using the <STRONG><stdarg.h></STRONG> interface. - <STRONG>o</STRONG> The Single Unix Specification, Version 2 states that <STRONG>vw_scanw</STRONG> is - preferred to <STRONG>vwscanw</STRONG> since the latter requires including - <STRONG><varargs.h></STRONG>, which cannot be used in the same file as <STRONG><stdarg.h></STRONG>. - This implementation uses <STRONG><stdarg.h></STRONG> for both, because that header + <STRONG>o</STRONG> The Single Unix Specification, Version 2 states that <STRONG>vw_scanw</STRONG> is + preferred to <STRONG>vwscanw</STRONG> since the latter requires including + <STRONG><varargs.h></STRONG>, which cannot be used in the same file as <STRONG><stdarg.h></STRONG>. + This implementation uses <STRONG><stdarg.h></STRONG> for both, because that header is included in <STRONG><curses.h</STRONG>>. - <STRONG>o</STRONG> X/Open Curses, Issue 5 (December 2007) marked <STRONG>vwscanw</STRONG> (along with + <STRONG>o</STRONG> X/Open Curses, Issue 5 (December 2007) marked <STRONG>vwscanw</STRONG> (along with <STRONG>vwprintw</STRONG> and the termcap interface) as withdrawn. - Both XSI and The Single Unix Specification, Version 2 state that these + Both XSI and The Single Unix Specification, Version 2 state that these functions return <STRONG>ERR</STRONG> or <STRONG>OK</STRONG>. - <STRONG>o</STRONG> Since the underlying <STRONG>scanf(3)</STRONG> can return the number of items + <STRONG>o</STRONG> Since the underlying <STRONG>scanf(3)</STRONG> 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 + is probably an editing error which was introduced in XSI, rather than being done intentionally. - <STRONG>o</STRONG> 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 + <STRONG>o</STRONG> 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 <STRONG>vsscanf</STRONG> to scan the string, which returns <STRONG>EOF</STRONG> on error. - <STRONG>o</STRONG> Portable applications should only test if the return value is <STRONG>ERR</STRONG>, + <STRONG>o</STRONG> Portable applications should only test if the return value is <STRONG>ERR</STRONG>, since the <STRONG>OK</STRONG> 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 + 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. @@ -141,6 +171,7 @@ <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> |