1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
1 |
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved |
2
by Francesco Paolo Lovergine
* Alligned to linux main manpages edition. |
2 |
.TH "FWSCANF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" |
1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
3 |
.\" fwscanf |
4 |
.SH NAME |
|
5 |
fwscanf, swscanf, wscanf \- convert formatted wide-character input
|
|
6 |
.SH SYNOPSIS |
|
7 |
.LP
|
|
8 |
\fB#include <stdio.h>
|
|
9 |
.br
|
|
10 |
#include <wchar.h> |
|
11 |
.br
|
|
12 |
.sp
|
|
13 |
int fwscanf(FILE *restrict\fP \fIstream\fP\fB, const wchar_t *restrict\fP |
|
14 |
\fIformat\fP\fB, ... ); |
|
15 |
.br
|
|
16 |
int swscanf(const wchar_t *restrict\fP \fIws\fP\fB, |
|
17 |
.br
|
|
18 |
\ \ \ \ \ \ const wchar_t *restrict\fP \fIformat\fP\fB, ... ); |
|
19 |
.br
|
|
20 |
int wscanf(const wchar_t *restrict\fP \fIformat\fP\fB, ... ); |
|
21 |
.br
|
|
22 |
\fP
|
|
23 |
.SH DESCRIPTION |
|
24 |
.LP
|
|
25 |
The \fIfwscanf\fP() function shall read from the named input \fIstream\fP. |
|
26 |
The \fIwscanf\fP() function shall read from the |
|
27 |
standard input stream \fIstdin\fP. The \fIswscanf\fP() function shall |
|
28 |
read from the wide-character string \fIws\fP. Each |
|
29 |
function reads wide characters, interprets them according to a format, |
|
30 |
and stores the results in its arguments. Each expects, as |
|
31 |
arguments, a control wide-character string \fIformat\fP described |
|
32 |
below, and a set of \fIpointer\fP arguments indicating where |
|
33 |
the converted input should be stored. The result is undefined if there |
|
34 |
are insufficient arguments for the format. If the |
|
35 |
\fIformat\fP is exhausted while arguments remain, the excess arguments |
|
36 |
are evaluated but are otherwise ignored. |
|
37 |
.LP
|
|
38 |
Conversions can be applied to the \fIn\fPth argument after the \fIformat\fP |
|
39 |
in the argument list, rather than to the next unused |
|
40 |
argument. In this case, the conversion specifier wide character \fB%\fP |
|
41 |
(see below) is replaced by the sequence \fB"%n$"\fP , |
|
42 |
where \fIn\fP is a decimal integer in the range [1,{NL_ARGMAX}]. This |
|
43 |
feature provides for the definition of \fIformat\fP |
|
44 |
wide-character strings that select arguments in an order appropriate |
|
45 |
to specific languages. In \fIformat\fP wide-character strings |
|
46 |
containing the \fB"%\fP\fIn\fP\fB$"\fP form of conversion specifications, |
|
47 |
it is unspecified whether numbered arguments in |
|
48 |
the argument list can be referenced from the \fIformat\fP wide-character |
|
49 |
string more than once. |
|
50 |
.LP
|
|
51 |
The \fIformat\fP can contain either form of a conversion specification-that |
|
52 |
is, \fB%\fP or \fB"%\fP\fIn\fP\fB$"\fP- |
|
53 |
but the two forms cannot normally be mixed within a single \fIformat\fP |
|
54 |
wide-character string. The only exception to this is that |
|
55 |
\fB%%\fP or \fB%*\fP can be mixed with the \fB"%\fP\fIn\fP\fB$"\fP |
|
56 |
form. When numbered argument specifications are |
|
57 |
used, specifying the \fIN\fPth argument requires that all the leading |
|
58 |
arguments, from the first to the ( \fIN\fP-1)th, are |
|
59 |
pointers. |
|
60 |
.LP
|
|
61 |
The |
|
62 |
\fIfwscanf\fP() function in all its forms allows for detection of |
|
63 |
a language-dependent radix character in the input string, |
|
64 |
encoded as a wide-character value. The radix character is defined |
|
65 |
in the program's locale (category \fILC_NUMERIC ).\fP In the |
|
66 |
POSIX locale, or in a locale where the radix character is not defined, |
|
67 |
the radix character shall default to a period ( \fB'.'\fP |
|
68 |
). |
|
69 |
.LP
|
|
70 |
The \fIformat\fP is a wide-character string composed of zero or more |
|
71 |
directives. Each directive is composed of one of the |
|
72 |
following: one or more white-space wide characters ( <space>s, <tab>s, |
|
73 |
<newline>s, <vertical-tab>s, or |
|
74 |
<form-feed>s); an ordinary wide character (neither \fB'%'\fP nor a |
|
75 |
white-space character); or a conversion specification. |
|
76 |
Each conversion specification is introduced by a \fB'%'\fP \ or |
|
77 |
the sequence \fB"%\fP\fIn\fP\fB$"\fP after which the following appear |
|
78 |
in sequence: |
|
79 |
.IP " *" 3 |
|
80 |
An optional assignment-suppressing character \fB'*'\fP . |
|
81 |
.LP
|
|
82 |
.IP " *" 3 |
|
83 |
An optional non-zero decimal integer that specifies the maximum field |
|
84 |
width. |
|
85 |
.LP
|
|
86 |
.IP " *" 3 |
|
87 |
An optional length modifier that specifies the size of the receiving |
|
88 |
object. |
|
89 |
.LP
|
|
90 |
.IP " *" 3 |
|
91 |
A conversion specifier wide character that specifies the type of conversion |
|
92 |
to be applied. The valid conversion specifiers are |
|
93 |
described below. |
|
94 |
.LP
|
|
95 |
.LP
|
|
96 |
The \fIfwscanf\fP() functions shall execute each directive of the |
|
97 |
format in turn. If a directive fails, as detailed below, the |
|
98 |
function shall return. Failures are described as input failures (due |
|
99 |
to the unavailability of input bytes) or matching failures |
|
100 |
(due to inappropriate input). |
|
101 |
.LP
|
|
102 |
A directive composed of one or more white-space wide characters is |
|
103 |
executed by reading input until no more valid input can be |
|
104 |
read, or up to the first wide character which is not a white-space |
|
105 |
wide character, which remains unread. |
|
106 |
.LP
|
|
107 |
A directive that is an ordinary wide character shall be executed as |
|
108 |
follows. The next wide character is read from the input and |
|
109 |
compared with the wide character that comprises the directive; if |
|
110 |
the comparison shows that they are not equivalent, the directive |
|
111 |
shall fail, and the differing and subsequent wide characters remain |
|
112 |
unread. Similarly, if end-of-file, an encoding error, or a read |
|
113 |
error prevents a wide character from being read, the directive shall |
|
114 |
fail. |
|
115 |
.LP
|
|
116 |
A directive that is a conversion specification defines a set of matching |
|
117 |
input sequences, as described below for each conversion |
|
118 |
wide character. A conversion specification is executed in the following |
|
119 |
steps. |
|
120 |
.LP
|
|
121 |
Input white-space wide characters (as specified by \fIiswspace\fP() |
|
122 |
) shall be skipped, unless the |
|
123 |
conversion specification includes a \fB[\fP , \fBc\fP , or \fBn\fP |
|
124 |
conversion specifier. |
|
125 |
.LP
|
|
126 |
An item shall be read from the input, unless the conversion specification |
|
127 |
includes an \fBn\fP conversion specifier wide |
|
128 |
character. An input item is defined as the longest sequence of input |
|
129 |
wide characters, not exceeding any specified field width, |
|
130 |
which is an initial subsequence of a matching sequence. The first |
|
131 |
wide character, if any, after the input item shall remain unread. |
|
132 |
If the length of the input item is zero, the execution of the conversion |
|
133 |
specification shall fail; this condition is a matching |
|
134 |
failure, unless end-of-file, an encoding error, or a read error prevented |
|
135 |
input from the stream, in which case it is an input |
|
136 |
failure. |
|
137 |
.LP
|
|
138 |
Except in the case of a \fB%\fP conversion specifier, the input item |
|
139 |
(or, in the case of a \fB%n\fP conversion |
|
140 |
specification, the count of input wide characters) shall be converted |
|
141 |
to a type appropriate to the conversion wide character. If |
|
142 |
the input item is not a matching sequence, the execution of the conversion |
|
143 |
specification shall fail; this condition is a matching |
|
144 |
failure. Unless assignment suppression was indicated by a \fB'*'\fP |
|
145 |
, the result of the conversion shall be placed in the object |
|
146 |
pointed to by the first argument following the \fIformat\fP argument |
|
147 |
that has not already received a conversion result if the |
|
148 |
conversion specification is introduced by \fB%\fP , \ or in the |
|
149 |
\fIn\fPth argument if introduced by the wide-character |
|
150 |
sequence \fB"%\fP\fIn\fP\fB$"\fP. If this object does not |
|
151 |
have an appropriate type, or if the result of the conversion cannot |
|
152 |
be represented in the space provided, the behavior is |
|
153 |
undefined. |
|
154 |
.LP
|
|
155 |
The length modifiers and their meanings are: |
|
156 |
.TP 7 |
|
157 |
\fBhh\fP |
|
158 |
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , |
|
159 |
\fBx\fP , \fBX\fP , or \fBn\fP |
|
160 |
conversion specifier applies to an argument with type pointer to \fBsigned
|
|
161 |
char\fP or \fBunsigned char\fP. |
|
162 |
.TP 7 |
|
163 |
\fBh\fP |
|
164 |
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , |
|
165 |
\fBx\fP , \fBX\fP , or \fBn\fP |
|
166 |
conversion specifier applies to an argument with type pointer to \fBshort\fP |
|
167 |
or \fBunsigned short\fP. |
|
168 |
.TP 7 |
|
169 |
\fBl\fP\ (ell) |
|
170 |
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , |
|
171 |
\fBx\fP , \fBX\fP , or \fBn\fP |
|
172 |
conversion specifier applies to an argument with type pointer to \fBlong\fP |
|
173 |
or \fBunsigned long\fP; that a following \fBa\fP , |
|
174 |
\fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , or \fBG\fP |
|
175 |
conversion specifier applies to an |
|
176 |
argument with type pointer to \fBdouble\fP; or that a following \fBc\fP |
|
177 |
, \fBs\fP , or \fB[\fP conversion specifier |
|
178 |
applies to an argument with type pointer to \fBwchar_t\fP. |
|
179 |
.TP 7 |
|
180 |
\fBll\fP\ (ell-ell) |
|
181 |
.sp
|
|
182 |
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , |
|
183 |
\fBx\fP , \fBX\fP , or \fBn\fP conversion |
|
184 |
specifier applies to an argument with type pointer to \fBlong long\fP |
|
185 |
or \fBunsigned long long\fP. |
|
186 |
.TP 7 |
|
187 |
\fBj\fP |
|
188 |
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , |
|
189 |
\fBx\fP , \fBX\fP , or \fBn\fP |
|
190 |
conversion specifier applies to an argument with type pointer to \fBintmax_t\fP |
|
191 |
or \fBuintmax_t\fP. |
|
192 |
.TP 7 |
|
193 |
\fBz\fP |
|
194 |
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , |
|
195 |
\fBx\fP , \fBX\fP , or \fBn\fP |
|
196 |
conversion specifier applies to an argument with type pointer to \fBsize_t\fP |
|
197 |
or the corresponding signed integer type. |
|
198 |
.TP 7 |
|
199 |
\fBt\fP |
|
200 |
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP , |
|
201 |
\fBx\fP , \fBX\fP , or \fBn\fP |
|
202 |
conversion specifier applies to an argument with type pointer to \fBptrdiff_t\fP |
|
203 |
or the corresponding \fBunsigned\fP type. |
|
204 |
.TP 7 |
|
205 |
\fBL\fP |
|
206 |
Specifies that a following \fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP , |
|
207 |
\fBf\fP , \fBF\fP , \fBg\fP , or |
|
208 |
\fBG\fP conversion specifier applies to an argument with type pointer |
|
209 |
to \fBlong double\fP. |
|
210 |
.sp
|
|
211 |
.LP
|
|
212 |
If a length modifier appears with any conversion specifier other than |
|
213 |
as specified above, the behavior is undefined. |
|
214 |
.LP
|
|
215 |
The following conversion specifier wide characters are valid: |
|
216 |
.TP 7 |
|
217 |
\fBd\fP |
|
218 |
Matches an optionally signed decimal integer, whose format is the |
|
219 |
same as expected for the subject sequence of \fIwcstol\fP() with the |
|
220 |
value 10 for the \fIbase\fP argument. In the absence of a size modifier, |
|
221 |
the application shall ensure that the corresponding argument is a |
|
222 |
pointer to \fBint\fP. |
|
223 |
.TP 7 |
|
224 |
\fBi\fP |
|
225 |
Matches an optionally signed integer, whose format is the same as |
|
226 |
expected for the subject sequence of \fIwcstol\fP() with 0 for the |
|
227 |
\fIbase\fP argument. In the absence of a size modifier, the |
|
228 |
application shall ensure that the corresponding argument is a pointer |
|
229 |
to \fBint\fP. |
|
230 |
.TP 7 |
|
231 |
\fBo\fP |
|
232 |
Matches an optionally signed octal integer, whose format is the same |
|
233 |
as expected for the subject sequence of \fIwcstoul\fP() with the value |
|
234 |
8 for the \fIbase\fP argument. In the absence of a size modifier, |
|
235 |
the application shall ensure that the corresponding argument is a |
|
236 |
pointer to \fBunsigned\fP. |
|
237 |
.TP 7 |
|
238 |
\fBu\fP |
|
239 |
Matches an optionally signed decimal integer, whose format is the |
|
240 |
same as expected for the subject sequence of \fIwcstoul\fP() with |
|
241 |
the value 10 for the \fIbase\fP argument. In the absence of a size |
|
242 |
modifier, |
|
243 |
the application shall ensure that the corresponding argument is a |
|
244 |
pointer to \fBunsigned\fP. |
|
245 |
.TP 7 |
|
246 |
\fBx\fP |
|
247 |
Matches an optionally signed hexadecimal integer, whose format is |
|
248 |
the same as expected for the subject sequence of \fIwcstoul\fP() with |
|
249 |
the value 16 for the \fIbase\fP argument. In the absence of a size |
|
250 |
modifier, |
|
251 |
the application shall ensure that the corresponding argument is a |
|
252 |
pointer to \fBunsigned\fP. |
|
253 |
.TP 7 |
|
254 |
\fBa\fP,\ \fBe\fP,\ \fBf\fP,\ \fBg\fP |
|
255 |
.sp
|
|
256 |
Matches an optionally signed floating-point number, infinity, or NaN |
|
257 |
whose format is the same as expected for the subject sequence |
|
258 |
of \fIwcstod\fP(). In the absence of a size modifier, the application |
|
259 |
shall ensure that the |
|
260 |
corresponding argument is a pointer to \fBfloat\fP. |
|
261 |
.LP
|
|
262 |
If the \fIfwprintf\fP() family of functions generates character string |
|
263 |
representations |
|
264 |
for infinity and NaN (a symbolic entity encoded in floating-point |
|
265 |
format) to support IEEE\ Std\ 754-1985, the |
|
266 |
\fIfwscanf\fP() family of functions shall recognize them as input. |
|
267 |
.TP 7 |
|
268 |
\fBs\fP |
|
269 |
Matches a sequence of non white-space wide characters. If no \fBl\fP |
|
270 |
(ell) qualifier is present, characters from the input |
|
271 |
field shall be converted as if by repeated calls to the \fIwcrtomb\fP() |
|
272 |
function, with the |
|
273 |
conversion state described by an \fBmbstate_t\fP object initialized |
|
274 |
to zero before the first wide character is converted. The |
|
275 |
application shall ensure that the corresponding argument is a pointer |
|
276 |
to a character array large enough to accept the sequence and |
|
277 |
the terminating null character, which shall be added automatically. |
|
278 |
.LP
|
|
279 |
Otherwise, the application shall ensure that the corresponding argument |
|
280 |
is a pointer to an array of \fBwchar_t\fP large enough |
|
281 |
to accept the sequence and the terminating null wide character, which |
|
282 |
shall be added automatically. |
|
283 |
.TP 7 |
|
284 |
\fB[\fP |
|
285 |
Matches a non-empty sequence of wide characters from a set of expected |
|
286 |
wide characters (the \fIscanset\fP). If no \fBl\fP |
|
287 |
(ell) qualifier is present, wide characters from the input field shall |
|
288 |
be converted as if by repeated calls to the \fIwcrtomb\fP() function, |
|
289 |
with the conversion state described by an \fBmbstate_t\fP object |
|
290 |
initialized to zero before the first wide character is converted. |
|
291 |
The application shall ensure that the corresponding argument is a |
|
292 |
pointer to a character array large enough to accept the sequence and |
|
293 |
the terminating null character, which shall be added |
|
294 |
automatically. |
|
295 |
.LP
|
|
296 |
If an \fBl\fP (ell) qualifier is present, the application shall ensure |
|
297 |
that the corresponding argument is a pointer to an |
|
298 |
array of \fBwchar_t\fP large enough to accept the sequence and the |
|
299 |
terminating null wide character, which shall be added |
|
300 |
automatically. |
|
301 |
.LP
|
|
302 |
The conversion specification includes all subsequent wide characters |
|
303 |
in the \fIformat\fP string up to and including the |
|
304 |
matching right square bracket ( \fB']'\fP ). The wide characters between |
|
305 |
the square brackets (the \fIscanlist\fP) comprise the |
|
306 |
scanset, unless the wide character after the left square bracket is |
|
307 |
a circumflex ( \fB'^'\fP ), in which case the scanset |
|
308 |
contains all wide characters that do not appear in the scanlist between |
|
309 |
the circumflex and the right square bracket. If the |
|
310 |
conversion specification begins with \fB"[]"\fP or \fB"[^]"\fP , the |
|
311 |
right square bracket is included in the scanlist and the |
|
312 |
next right square bracket is the matching right square bracket that |
|
313 |
ends the conversion specification; otherwise, the first right |
|
314 |
square bracket is the one that ends the conversion specification. |
|
315 |
If a \fB'-'\fP is in the scanlist and is not the first wide |
|
316 |
character, nor the second where the first wide character is a \fB'^'\fP |
|
317 |
, nor the last wide character, the behavior is |
|
318 |
implementation-defined. |
|
319 |
.TP 7 |
|
320 |
\fBc\fP |
|
321 |
Matches a sequence of wide characters of exactly the number specified |
|
322 |
by the field width (1 if no field width is present in the |
|
323 |
conversion specification). |
|
324 |
.LP
|
|
325 |
If no \fBl\fP (ell) length modifier is present, characters from the |
|
326 |
input field shall be converted as if by repeated calls to |
|
327 |
the \fIwcrtomb\fP() function, with the conversion state described |
|
328 |
by an \fBmbstate_t\fP |
|
329 |
object initialized to zero before the first wide character is converted. |
|
330 |
The corresponding argument shall be a pointer to the |
|
331 |
initial element of a character array large enough to accept the sequence. |
|
332 |
No null character is added. |
|
333 |
.LP
|
|
334 |
If an \fBl\fP (ell) length modifier is present, the corresponding |
|
335 |
argument shall be a pointer to the initial element of an |
|
336 |
array of \fBwchar_t\fP large enough to accept the sequence. No null |
|
337 |
wide character is added. |
|
338 |
.LP
|
|
339 |
Otherwise, the application shall ensure that the corresponding argument |
|
340 |
is a pointer to an array of \fBwchar_t\fP large enough |
|
341 |
to accept the sequence. No null wide character is added. |
|
342 |
.TP 7 |
|
343 |
\fBp\fP |
|
344 |
Matches an implementation-defined set of sequences, which shall be |
|
345 |
the same as the set of sequences that is produced by the |
|
346 |
\fB%p\fP conversion specification of the corresponding \fIfwprintf\fP() |
|
347 |
functions. The |
|
348 |
application shall ensure that the corresponding argument is a pointer |
|
349 |
to a pointer to \fBvoid\fP. The interpretation of the input |
|
350 |
item is implementation-defined. If the input item is a value converted |
|
351 |
earlier during the same program execution, the pointer that |
|
352 |
results shall compare equal to that value; otherwise, the behavior |
|
353 |
of the \fB%p\fP conversion is undefined. |
|
354 |
.TP 7 |
|
355 |
\fBn\fP |
|
356 |
No input is consumed. The application shall ensure that the corresponding |
|
357 |
argument is a pointer to the integer into which is to |
|
358 |
be written the number of wide characters read from the input so far |
|
359 |
by this call to the \fIfwscanf\fP() functions. Execution of a |
|
360 |
\fB%n\fP conversion specification shall not increment the assignment |
|
361 |
count returned at the completion of execution of the |
|
362 |
function. No argument shall be converted, but one shall be consumed. |
|
363 |
If the conversion specification includes an |
|
364 |
assignment-suppressing wide character or a field width, the behavior |
|
365 |
is undefined. |
|
366 |
.TP 7 |
|
367 |
\fBC\fP |
|
368 |
Equivalent to \fBlc\fP . |
|
369 |
.TP 7 |
|
370 |
\fBS\fP |
|
371 |
Equivalent to \fBls\fP . |
|
372 |
.TP 7 |
|
373 |
\fB%\fP |
|
374 |
Matches a single \fB'%'\fP wide character; no conversion or assignment |
|
375 |
shall occur. The complete conversion specification |
|
376 |
shall be \fB%%\fP . |
|
377 |
.sp
|
|
378 |
.LP
|
|
379 |
If a conversion specification is invalid, the behavior is undefined. |
|
380 |
.LP
|
|
381 |
The conversion specifiers \fBA\fP , \fBE\fP , \fBF\fP , \fBG\fP , |
|
382 |
and \fBX\fP are also valid and shall be |
|
383 |
equivalent to, respectively, \fBa\fP , \fBe\fP , \fBf\fP , \fBg\fP |
|
384 |
, and \fBx\fP . |
|
385 |
.LP
|
|
386 |
If end-of-file is encountered during input, conversion is terminated. |
|
387 |
If end-of-file occurs before any wide characters matching |
|
388 |
the current conversion specification (except for \fB%n\fP ) have been |
|
389 |
read (other than leading white-space, where permitted), |
|
390 |
execution of the current conversion specification shall terminate |
|
391 |
with an input failure. Otherwise, unless execution of the current |
|
392 |
conversion specification is terminated with a matching failure, execution |
|
393 |
of the following conversion specification (if any) shall |
|
394 |
be terminated with an input failure. |
|
395 |
.LP
|
|
396 |
Reaching the end of the string in \fIswscanf\fP() shall be equivalent |
|
397 |
to encountering end-of-file for \fIfwscanf\fP(). |
|
398 |
.LP
|
|
399 |
If conversion terminates on a conflicting input, the offending input |
|
400 |
shall be left unread in the input. Any trailing white space |
|
401 |
(including <newline>) shall be left unread unless matched by a conversion |
|
402 |
specification. The success of literal matches and |
|
403 |
suppressed assignments is only directly determinable via the \fB%n\fP |
|
404 |
conversion specification. |
|
405 |
.LP
|
|
406 |
The |
|
407 |
\fIfwscanf\fP() and \fIwscanf\fP() functions may mark the \fIst_atime\fP |
|
408 |
field of the file associated with \fIstream\fP for |
|
409 |
update. The \fIst_atime\fP field shall be marked for update by the |
|
410 |
first successful execution of \fIfgetc\fP(), \fIfgetwc\fP(), \fIfgets\fP(), |
|
411 |
\fIfgetws\fP(), \fIfread\fP(), \fIgetc\fP(), \fIgetwc\fP(), \fIgetchar\fP(), |
|
412 |
\fIgetwchar\fP(), \fIgets\fP(), \fIfscanf\fP(), or \fIfwscanf\fP() |
|
413 |
using \fIstream\fP that returns data not supplied by a prior |
|
414 |
call to \fIungetc\fP(). |
|
415 |
.SH RETURN VALUE |
|
416 |
.LP
|
|
417 |
Upon successful completion, these functions shall return the number |
|
418 |
of successfully matched and assigned input items; this |
|
419 |
number can be zero in the event of an early matching failure. If the |
|
420 |
input ends before the first matching failure or conversion, |
|
421 |
EOF shall be returned. If a read error occurs, the error indicator |
|
422 |
for the stream is set, EOF shall be returned, \ and
|
|
423 |
\fIerrno\fP shall be set to indicate the error. |
|
424 |
.SH ERRORS |
|
425 |
.LP
|
|
426 |
For the conditions under which the \fIfwscanf\fP() functions shall |
|
427 |
fail and may fail, refer to \fIfgetwc\fP() . |
|
428 |
.LP
|
|
429 |
In addition, \fIfwscanf\fP() may fail if: |
|
430 |
.TP 7 |
|
431 |
.B EILSEQ |
|
432 |
Input byte sequence does not form a valid character. |
|
433 |
.TP 7 |
|
434 |
.B EINVAL |
|
435 |
There are insufficient arguments. |
|
436 |
.sp
|
|
437 |
.LP
|
|
438 |
\fIThe following sections are informative.\fP |
|
439 |
.SH EXAMPLES |
|
440 |
.LP
|
|
441 |
The call: |
|
442 |
.sp
|
|
443 |
.RS
|
|
444 |
.nf
|
|
445 |
||
446 |
\fBint i, n; float x; char name[50];
|
|
447 |
n = wscanf(L"%d%f%s", &i, &x, name); |
|
448 |
\fP
|
|
449 |
.fi
|
|
450 |
.RE
|
|
451 |
.LP
|
|
452 |
with the input line: |
|
453 |
.sp
|
|
454 |
.RS
|
|
455 |
.nf
|
|
456 |
||
457 |
\fB25 54.32E-1 Hamster
|
|
458 |
\fP
|
|
459 |
.fi
|
|
460 |
.RE
|
|
461 |
.LP
|
|
462 |
assigns to \fIn\fP the value 3, to \fIi\fP the value 25, to \fIx\fP |
|
463 |
the value 5.432, and \fIname\fP contains the string |
|
464 |
\fB"Hamster"\fP . |
|
465 |
.LP
|
|
466 |
The call: |
|
467 |
.sp
|
|
468 |
.RS
|
|
469 |
.nf
|
|
470 |
||
471 |
\fBint i; float x; char name[50];
|
|
472 |
(void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name); |
|
473 |
\fP
|
|
474 |
.fi
|
|
475 |
.RE
|
|
476 |
.LP
|
|
477 |
with input: |
|
478 |
.sp
|
|
479 |
.RS
|
|
480 |
.nf
|
|
481 |
||
482 |
\fB56789 0123 56a72
|
|
483 |
\fP
|
|
484 |
.fi
|
|
485 |
.RE
|
|
486 |
.LP
|
|
487 |
assigns 56 to \fIi\fP, 789.0 to \fIx\fP, skips 0123, and places the |
|
488 |
string \fB"56\\0"\fP in \fIname\fP. The next call to \fIgetchar\fP() |
|
489 |
shall return the character \fB'a'\fP . |
|
490 |
.SH APPLICATION USAGE |
|
491 |
.LP
|
|
492 |
In format strings containing the \fB'%'\fP form of conversion specifications, |
|
493 |
each argument in the argument list is used |
|
494 |
exactly once. |
|
495 |
.SH RATIONALE |
|
496 |
.LP
|
|
497 |
None. |
|
498 |
.SH FUTURE DIRECTIONS |
|
499 |
.LP
|
|
500 |
None. |
|
501 |
.SH SEE ALSO |
|
502 |
.LP
|
|
503 |
\fIgetwc\fP() , \fIfwprintf\fP() , \fIsetlocale\fP() , \fIwcstod\fP() |
|
504 |
, \fIwcstol\fP() , |
|
505 |
\fIwcstoul\fP() , \fIwcrtomb\fP() , the Base Definitions volume of |
|
506 |
IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI<langinfo.h>\fP, \fI<stdio.h>\fP, |
|
507 |
\fI<wchar.h>\fP |
|
508 |
.SH COPYRIGHT |
|
509 |
Portions of this text are reprinted and reproduced in electronic form |
|
510 |
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology |
|
511 |
-- Portable Operating System Interface (POSIX), The Open Group Base |
|
512 |
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of |
|
513 |
Electrical and Electronics Engineers, Inc and The Open Group. In the |
|
514 |
event of any discrepancy between this version and the original IEEE and |
|
515 |
The Open Group Standard, the original IEEE and The Open Group Standard |
|
516 |
is the referee document. The original Standard can be obtained online at |
|
517 |
http://www.opengroup.org/unix/online.html . |