1curs_scanw(3X)                                                  curs_scanw(3X)
2
3
4

NAME

6       scanw, wscanw, mvscanw, mvwscanw, vwscanw, vw_scanw - convert formatted
7       input from a curses window
8

SYNOPSIS

10       #include <curses.h>
11
12       int scanw(const char *fmt, ...);
13       int wscanw(WINDOW *win, const char *fmt, ...);
14       int mvscanw(int y, int x, const char *fmt, ...);
15       int mvwscanw(WINDOW *win, int y, int x, const char *fmt, ...);
16
17       int vw_scanw(WINDOW *win, const char *fmt, va_list varglist);
18
19       /* obsolete */
20       int vwscanw(WINDOW *win, const char *fmt, va_list varglist);
21

DESCRIPTION

23       The scanw, wscanw and mvscanw routines  are  analogous  to  scanf  [see
24       scanf(3)].   The  effect  of  these  routines is as though wgetstr were
25       called on the window, and the resulting line  used  as  input  for  ss‐
26       canf(3).   Fields  which  do not map to a variable in the fmt field are
27       lost.
28
29       The vwscanw and vw_scanw routines are  analogous  to  vscanf(3).   They
30       perform a wscanw using a variable argument list.  The third argument is
31       a va_list, a pointer to a list of arguments, as defined in <stdarg.h>.
32

RETURN VALUE

34       vwscanw returns ERR on failure and an integer equal to  the  number  of
35       fields scanned on success.
36
37       Applications  may  use the return value from the scanw, wscanw, mvscanw
38       and mvwscanw routines to determine the  number  of  fields  which  were
39       mapped in the call.
40
41       Functions  with  a  “mv”  prefix  first perform a cursor movement using
42       wmove, and return an error if the position is outside the window, or if
43       the window pointer is null.
44

HISTORY

46       While  scanw  was implemented in 4BSD, none of the BSD releases used it
47       until 4.4BSD (in a game).  That early version of curses was before  the
48       ANSI  C  standard.   It did not use <varargs.h>, though that was avail‐
49       able.  In 1991 (a couple of years after SVr4 was  generally  available,
50       and  after  the C standard was published), other developers updated the
51       library, using <stdarg.h> internally in 4.4BSD curses.  Even with  this
52       improvement,  BSD  curses  did not use function prototypes (or even de‐
53       clare functions) in the <curses.h> header until 1992.
54
55       SVr2 documented scanw, wscanw tersely as  “scanf  through  stdscr”  and
56       tersely as “scanf through win”, respectively.
57
58       SVr3 added mvscanw, and mvwscanw, with a three-line summary saying that
59       they were analogous to scanf(3), explaining that the string which would
60       be  output  from  scanf(3) would instead be output using waddstr on the
61       given window.  SVr3 also added vwscanw, saying that the third parameter
62       is  a  va_list, defined in <varargs.h>, and referring the reader to the
63       manual pages for varargs and vprintf for detailed  descriptions.   (Be‐
64       cause the SVr3 documentation does not mention vscanf, that reference to
65       vprintf may not be an error).
66
67       SVr4  added  no  new  variations  of  scanw,  but  provided  for  using
68       <varargs.h> or <stdarg.h> to define the va_list type.
69
70       X/Open  Curses  added  vw_scanw  to  replace  vwscanw, stating that its
71       va_list definition requires <stdarg.h>.
72

PORTABILITY

74       In this implementation, vw_scanw and vwscanw are equivalent, to support
75       legacy applications.  However, the latter (vwscanw) is obsolete:
76
77       •   The  XSI Curses standard, Issue 4 described these functions, noting
78           that the function vwscanw is marked TO BE WITHDRAWN, and is  to  be
79           replaced by a function vw_scanw using the <stdarg.h> interface.
80
81       •   The  Single  Unix Specification, Version 2 states that vw_scanw  is
82           preferred  to  vwscanw  since   the   latter   requires   including
83           <varargs.h>,  which  cannot be used in the same file as <stdarg.h>.
84           This implementation uses <stdarg.h> for both, because  that  header
85           is included in <curses.h>.
86
87       •   X/Open  Curses,  Issue 5 (December 2007) marked vwscanw (along with
88           vwprintw and the termcap interface) as withdrawn.
89
90       Both XSI and The Single Unix Specification, Version 2 state that  these
91       functions return ERR or OK.
92
93       •   Since  the  underlying  scanf(3)  can  return  the  number of items
94           scanned, and the SVr4 code was documented to use this feature, this
95           is  probably  an  editing error which was introduced in XSI, rather
96           than being done intentionally.
97
98       •   This implementation returns the number of items scanned,  for  com‐
99           patibility  with  SVr4  curses.  As of 2018, NetBSD curses also re‐
100           turns the number of items scanned.  Both ncurses and NetBSD  curses
101           call vsscanf to scan the string, which returns EOF on error.
102
103       •   Portable  applications should only test if the return value is ERR,
104           since the OK value (zero) is likely to be misleading.
105
106           One possible way to get useful results would be to use a "%n"  con‐
107           version  at  the  end of the format string to ensure that something
108           was processed.
109

SEE ALSO

111       curses(3X), curs_getstr(3X), curs_printw(3X), curs_termcap(3X),
112       scanf(3).
113
114
115
116                                                                curs_scanw(3X)
Impressum