Debian Codegraph @

upstream/debian-unstable/man3/scanw.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. *
4 .\" *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
23 .\" *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_scanw.3x,v 1.62 2025/07/05 13:03:05 tom Exp $
31 .TH scanw 3NCURSES 2025-07-05 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .SH NAME
48 \fB\%scanw\fP,
49 \fB\%wscanw\fP,
50 \fB\%mvscanw\fP,
51 \fB\%mvwscanw\fP,
52 \fB\%vwscanw\fP,
53 \fB\%vw_scanw\fP \-
54 read formatted input from a \fIcurses\fR window
55 .SH SYNOPSIS
56 .nf
57 \fB#include <curses.h>
58 .PP
59 \fBint scanw(const char *\fIfmt\fP, ...);
60 \fBint wscanw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, ...);
61 \fBint mvscanw(int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...);
62 \fBint mvwscanw(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, const char *\fIfmt\fP, ...);
63 .PP
64 \fBint vw_scanw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
65 .PP
66 \fI/* obsolete */\fP
67 \fBint vwscanw(WINDOW *\fIwin\fP, const char *\fIfmt\fP, va_list \fIvarglist\fP);
68 .fi
69 .SH DESCRIPTION
70 \fB\%scanw\fP,
71 \fB\%wscanw\fP,
72 \fB\%mvscanw\fP,
73 and
74 \fB\%mvwscanw\fP
75 are analogous to \fI\%scanf\fP(3).
76 In effect,
77 they call \fB\%wgetstr\fP(3NCURSES) with
78 .I win
79 (or
80 .BR \%stdscr )
81 as its first argument,
82 then attempt conversion of the resulting string with \fI\%vsscanf\fP(3).
83 Fields in the string that do not map to a variable in the \fIfmt\fP
84 parameter are discarded.
85 .PP
86 \fB\%vwscanw\fP
87 and
88 \fB\%vw_scanw\fP are analogous to \fI\%vscanf\fP(3),
89 and perform a \fB\%wscanw\fP using a variable argument list.
90 The third argument is a \fI\%va_list\fP,
91 a pointer to a list of arguments,
92 as defined in \fI\%stdarg.h\fP.
93 .SH RETURN VALUE
94 These functions return
95 .B ERR
96 upon failure and otherwise a count of successful conversions;
97 this quantity may be zero.
98 .PP
99 In
100 .IR \%ncurses ,
101 failure occurs if \fI\%vsscanf\fP(3) returns
102 \fBEOF\fP,
103 or if the window pointer
104 .I win
105 is null.
106 .PP
107 Functions prefixed with \*(``mv\*('' first perform cursor movement and
108 fail if the position
109 .RI ( y ,
110 .IR x )
111 is outside the window boundaries.
112 .SH NOTES
113 No wide character counterpart functions are defined by the
114 \*(``wide\*(''
115 .I \%ncurses
116 configuration nor by any standard.
117 They are unnecessary:
118 to retrieve and convert a wide-character string from a
119 .I curses
120 terminal keyboard,
121 use these functions with the \fI\%scanf\fP(3) conversions \*(``%lc\*(''
122 and \*(``%ls\*('' for wide characters and strings,
123 respectively.
124 .PP
125 .I \%ncurses
126 implements \fI\%vsscanf\fP(3) internally if it is unavailable when the
127 library is configured.
128 .SH PORTABILITY
129 X/Open Curses Issue\ 4 describes these functions.
130 It specifies no error conditions for them.
131 .PP
132 .I \%ncurses
133 defines \fB\%vw_scanw\fP and \fB\%vwscanw\fP identically to support
134 legacy applications.
135 However,
136 the latter is obsolete.
137 .bP
138 X/Open Curses Issue\ 4 Version\ 2 (1996),
139 marked \fB\%vwscanw\fP as requiring \fI\%varargs.h\fP and
140 \*(``TO BE WITHDRAWN\*('',
141 and specified \fB\%vw_scanw\fP using the \fI\%stdarg.h\fP interface.
142 .bP
143 X/Open Curses Issue\ 5,
144 Draft 2 (December 2007) marked \fB\%vwscanw\fP (along with
145 \fB\%vwscanw\fP and the \fItermcap\fP interface) as withdrawn.
146 After incorporating review comments,
147 this became
148 X/Open Curses Issue\ 7 (2009).
149 .bP
150 .I \%ncurses
151 provides \fB\%vwscanw\fP,
152 but marks it as deprecated.
153 .PP
154 X/Open Curses Issues 4 and 7 both state that these functions return
155 \fBERR\fP or \fBOK\fP.
156 This is likely an erratum.
157 .bP
158 Since the underlying \fI\%scanf\fP(3) returns the number of successful
159 conversions,
160 and SVr4
161 .I curses
162 was documented to use this feature,
163 this may have been an editorial solecism introduced by X/Open,
164 rather than an intentional change.
165 .bP
166 This implementation retains compatibility with SVr4
167 .IR curses .
168 As of 2018,
169 NetBSD
170 .I curses
171 also returns the number of successful conversions.
172 Both
173 .I \%ncurses\fP
174 and NetBSD
175 .I curses
176 call \fI\%vsscanf\fP(3) to scan the string,
177 which returns \fBEOF\fP on error.
178 .bP
179 Portable applications should test only if the return value is \fBERR\fP,
180 and not compare it to \fBOK\fP,
181 since that value (zero) might be misleading.
182 .IP
183 One portable way to get useful results would be to use a \*(``%n\*(''
184 conversion at the end of the format string,
185 and check the value of the corresponding variable to determine how many
186 conversions succeeded.
187 .SH HISTORY
188 4BSD (1980)
189 introduced
190 .I \%wscanw
191 and its variants.
192 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
193 .\" libcurses/scanw.c
194 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/src/lib/\
195 .\" libcurses/mvscanw.c
196 It implemented all as functions,
197 not macros;
198 this initial distribution of
199 .I curses
200 preceded the ANSI C standard of 1989,
201 prior to which a variadic macro facility was not widely available.
202 .I \%scanw
203 went unused in Berkeley distributions until 4.3BSD-Reno (1990),
204 which employed it in a game.
205 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/src/\
206 .\" games/chess/uxdsp.c
207 4BSD's
208 .I \%wscanw
209 did not use
210 .IR \%varargs.h ","
211 which had been available since Seventh Edition Unix (1979).
212 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/include/\
213 .\" varargs.h
214 In 1991
215 (a couple of years after SVr4 was generally available,
216 and after the C standard was published),
217 other developers updated the library,
218 using
219 .I \%stdarg.h
220 internally in 4.4BSD
221 .IR curses .
222 Even with this improvement,
223 BSD
224 .I curses
225 did not use function prototypes
226 (nor even declare functions)
227 in
228 .I \%curses.h
229 until 1992.
230 .PP
231 4BSD documented
232 .I \%scanw
233 and
234 .I \%wscanw
235 tersely as \*(``scanf through
236 .IR \%stdscr "\*(''"
237 and \*(``scanf through
238 .IR win "\*('',"
239 respectively.
240 .\" https://minnie.tuhs.org/cgi-bin/utree.pl?file=4BSD/usr/man/man3/\
241 .\" curses.3
242 SVr3 (1987)
243 stated
244 .RS
245 .PP
246 [t]hese routines correspond to \fIscanf\fP(3S),
247 as do their arguments and return values.
248 .IR \%wgetstr "()"
249 is called on the window,
250 and the resulting line is used as input for the scan.
251 .RE
252 .\" GBR can't find a source to cite for this quotation,
253 .\" even after checking
254 .\" <https://github.com/ryanwoodsmall/oldsysv/tree/master>.
255 .PP
256 SVr3 added
257 .IR \%vwscanw ","
258 describing its third parameter as a
259 .IR \%va_list ","
260 defined in
261 .IR \%varargs.h ","
262 and referred the reader to the manual pages for
263 .I \%varargs
264 and
265 .I \%vprintf
266 for detailed descriptions.
267 (Because SVr3 documentation does not mention
268 .IR \%vscanf ","
269 the reference to
270 .I \%vprintf
271 might not be an error).
272 .PP
273 SVr4 (1989) introduced no new variations of
274 .IR \%scanw ","
275 but provided for using either
276 .I \%varargs.h
277 or
278 .I \%stdarg.h
279 to define the
280 .I \%va_list
281 type.
282 .\" either header declares "va_list", but only one can be used
283 .PP
284 X/Open Curses Issue\ 4 (1995)
285 defined
286 .I \%vw_scanw
287 to replace
288 .IR \%vwscanw ","
289 stating that its
290 .I \%va_list
291 type is defined in
292 .IR \%stdarg.h "."
293 .SH SEE ALSO
294 \fB\%ncurses\fP(3NCURSES),
295 \fB\%getstr\fP(3NCURSES),
296 \fB\%printw\fP(3NCURSES),
297 \fB\%scanf\fP(3),
298 \fB\%vscanf\fP(3)