ncurses 6.1 - patch 20180407
[ncurses.git] / doc / html / man / curs_scanw.3x.html
index b6331f0935c2ce0ad0abd1cc20bdb5297cc28039..5a4c957d4e7910d56b817ca87d8a70e1e97468c5 100644 (file)
@@ -1,6 +1,6 @@
 <!-- 
   ****************************************************************************
-  * Copyright (c) 1998-2010,2017 Free Software Foundation, Inc.              *
+  * Copyright (c) 1998-2017,2018 Free Software Foundation, Inc.              *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * copy of this software and associated documentation files (the            *
@@ -26,7 +26,7 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_scanw.3x,v 1.19 2017/11/21 00:46:31 tom Exp @
+  * @Id: curs_scanw.3x,v 1.23 2018/04/07 20:56:03 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
 
-       <STRONG>int</STRONG> <STRONG>scanw(char</STRONG> <STRONG>*fmt,</STRONG> <STRONG>...);</STRONG>
-       <STRONG>int</STRONG> <STRONG>wscanw(WINDOW</STRONG> <STRONG>*win,</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>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>char</STRONG> <STRONG>*fmt,</STRONG> <STRONG>...);</STRONG>
-       <STRONG>int</STRONG> <STRONG>vw_scanw(WINDOW</STRONG> <STRONG>*win,</STRONG> <STRONG>char</STRONG> <STRONG>*fmt,</STRONG> <STRONG>va_list</STRONG> <STRONG>varglist);</STRONG>
-       <STRONG>int</STRONG> <STRONG>vwscanw(WINDOW</STRONG> <STRONG>*win,</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>*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>
+
+       /* 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>
 
 
 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
-       The  XSI Curses standard, Issue 4 describes these functions.  The func-
-       tion <STRONG>vwscanw</STRONG> is marked TO BE WITHDRAWN, and is  to  be  replaced  by  a
-       function  <STRONG>vw_scanw</STRONG>  using  the  <STRONG>&lt;stdarg.h&gt;</STRONG>  interface.  The Single Unix
-       Specification, Version 2 states that <STRONG>vw_scanw</STRONG>  is preferred to  <STRONG>vwscanw</STRONG>
-       since  the  latter requires including <STRONG>&lt;varargs.h&gt;</STRONG>, which cannot be used
-       in the same file as <STRONG>&lt;stdarg.h&gt;</STRONG>.  This  implementation  uses  <STRONG>&lt;stdarg.h&gt;</STRONG>
-       for both, because that header is included in <STRONG>&lt;curses.h</STRONG>&gt;.
+       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
+           replaced by a function <STRONG>vw_scanw</STRONG> using the <STRONG>&lt;stdarg.h&gt;</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>&lt;varargs.h&gt;</STRONG>, which cannot be used in the same file  as  <STRONG>&lt;stdarg.h&gt;</STRONG>.
+           This  implementation  uses <STRONG>&lt;stdarg.h&gt;</STRONG> for both, because that header
+           is included in <STRONG>&lt;curses.h</STRONG>&gt;.
+
+       <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
-       functions return <STRONG>ERR</STRONG> or <STRONG>OK</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  than  being  done  intentionally.   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" conversion at the end of the  format  string  to
-       ensure that something was processed.
+       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
+           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.
+
+       <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
+           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>,
+           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
+           was processed.
 
 
 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
-       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>, <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>, <STRONG>scanf(3)</STRONG>
+       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>, <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>, <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>,
+       <STRONG>scanf(3)</STRONG>.