|
HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | PORTABILITY | HISTORY | SEE ALSO | COLOPHON |
|
|
|
curs_scanw(3X) Library calls curs_scanw(3X)
scanw, wscanw, mvscanw, mvwscanw, vwscanw, vw_scanw - read
formatted input from a curses window
#include <curses.h>
int scanw(const char *fmt, ...);
int wscanw(WINDOW *win, const char *fmt, ...);
int mvscanw(int y, int x, const char *fmt, ...);
int mvwscanw(WINDOW *win, int y, int x, const char *fmt, ...);
int vw_scanw(WINDOW *win, const char *fmt, va_list varglist);
/* obsolete */
int vwscanw(WINDOW *win, const char *fmt, va_list varglist);
scanw, wscanw, mvscanw, and mvwscanw are analogous to scanf(3).
In effect, they call wgetstr(3X) with win (or stdscr) as its first
argument, then attempt conversion of the resulting string with
vsscanf(3). Fields in the string that do not map to a variable in
the fmt parameter are discarded.
vwscanw and vw_scanw are analogous to vscanf(3), and perform a
wscanw using a variable argument list. The third argument is a
va_list, a pointer to a list of arguments, as defined in stdarg.h.
These functions return ERR upon failure and otherwise a count of
successful conversions; this quantity may be zero.
In ncurses, failure occurs if vsscanf(3) returns EOF, or if the
window pointer win is null.
Functions prefixed with “mv” first perform cursor movement and
fail if the position (y, x) is outside the window boundaries.
No wide character counterpart functions are defined by the “wide”
ncurses configuration nor by any standard. They are unnecessary:
to retrieve and convert a wide-character string from a curses
terminal keyboard, use these functions with the scanf(3)
conversions “%lc” and “%ls” for wide characters and strings,
respectively.
ncurses implements vsscanf(3) internally if it is unavailable when
the library is configured.
X/Open Curses Issue 4 describes these functions. It specifies no
error conditions for them.
ncurses defines vw_scanw and vwscanw identically to support legacy
applications. However, the latter is obsolete.
• X/Open Curses Issue 4 Version 2 (1996), marked vwscanw as
requiring varargs.h and “TO BE WITHDRAWN”, and specified
vw_scanw using the stdarg.h interface.
• X/Open Curses Issue 5, Draft 2 (December 2007) marked vwscanw
(along with vwscanw and the termcap interface) as withdrawn.
After incorporating review comments, this became X/Open Curses
Issue 7 (2009).
• ncurses provides vwscanw, but marks it as deprecated.
X/Open Curses Issues 4 and 7 both state that these functions
return ERR or OK. This is likely an erratum.
• Since the underlying scanf(3) returns the number of successful
conversions, and SVr4 curses was documented to use this
feature, this may have been an editorial solecism introduced
by X/Open, rather than an intentional change.
• This implementation retains compatibility with SVr4 curses.
As of 2018, NetBSD curses also returns the number of
successful conversions. Both ncurses and NetBSD curses call
vsscanf(3) to scan the string, which returns EOF on error.
• Portable applications should test only if the return value is
ERR, and not compare it to OK, since that value (zero) might
be misleading.
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.
4BSD (1980) introduced wscanw and its variants. It implemented
all as functions, not macros; this initial distribution of curses
preceded the ANSI C standard of 1989, prior to which a variadic
macro facility was not widely available. scanw went unused in
Berkeley distributions until 4.3BSD-Reno (1990), which employed it
in a game. 4BSD's wscanw did not use varargs.h, which had been
available since Seventh Edition Unix (1979). 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 (nor even declare
functions) in curses.h until 1992.
4BSD documented scanw and wscanw tersely as “scanf through stdscr”
and “scanf through win”, respectively. SVr3 (1987) stated
[t]hese routines correspond to scanf(3S), as do their
arguments and return values. wgetstr() is called on the
window, and the resulting line is used as input for the
scan.
SVr3 added vwscanw, describing its third parameter as a va_list,
defined in varargs.h, and referred the reader to the manual pages
for varargs and vprintf for detailed descriptions. (Because SVr3
documentation does not mention vscanf, the reference to vprintf
might not be an error).
SVr4 (1989) introduced no new variations of scanw, but provided
for using either varargs.h or stdarg.h to define the va_list type.
X/Open Curses Issue 4 (1995) defined vw_scanw to replace vwscanw,
stating that its va_list type is defined in stdarg.h.
curses(3X), curs_getstr(3X), curs_printw(3X), scanf(3), vscanf(3)
This page is part of the ncurses (new curses) project.
Information about the project can be found at
⟨https://invisible-island.net/ncurses/ncurses.html⟩. If you have a
bug report for this manual page, send it to bug-ncurses@gnu.org.
This page was obtained from the tarball ncurses-6.6.tar.gz fetched
from ⟨https://ftp.gnu.org/gnu/ncurses/⟩ on 2026-01-16. If you
discover any rendering problems in this HTML version of the page,
or you believe there is a better or more up-to-date source for the
page, or you have corrections or improvements to the information
in this COLOPHON (which is not part of the original manual page),
send a mail to man-pages@man7.org
ncurses @NCURSES_MAJOR@.@NCU... 2025-07-05 curs_scanw(3X)
|
HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|