1FWSCANF(P) POSIX Programmer's Manual FWSCANF(P)
2
6 fwscanf, swscanf, wscanf - convert formatted wide-character input
7
9 #include <stdio.h>
10 #include <wchar.h>
11 int fwscanf(FILE *restrict stream, const wchar_t *restrict format, ...
13 );
14 int swscanf(const wchar_t *restrict ws,
15 const wchar_t *restrict format, ... );
16 int wscanf(const wchar_t *restrict format, ... );
17
20 The fwscanf() function shall read from the named input stream. The
21 wscanf() function shall read from the standard input stream stdin. The
22 swscanf() function shall read from the wide-character string ws. Each
23 function reads wide characters, interprets them according to a format,
24 and stores the results in its arguments. Each expects, as arguments, a
25 control wide-character string format described below, and a set of
26 pointer arguments indicating where the converted input should be
27 stored. The result is undefined if there are insufficient arguments for
28 the format. If the format is exhausted while arguments remain, the
29 excess arguments are evaluated but are otherwise ignored.
30 Conversions can be applied to the nth argument after the format in the
32 argument list, rather than to the next unused argument. In this case,
33 the conversion specifier wide character % (see below) is replaced by
34 the sequence "%n$" , where n is a decimal integer in the range
35 [1,{NL_ARGMAX}]. This feature provides for the definition of format
36 wide-character strings that select arguments in an order appropriate to
37 specific languages. In format wide-character strings containing the
38 "%n$" form of conversion specifications, it is unspecified whether num‐
39 bered arguments in the argument list can be referenced from the format
40 wide-character string more than once.
41 The format can contain either form of a conversion specification-that
43 is, % or "%n$"- but the two forms cannot normally be mixed within a
44 single format wide-character string. The only exception to this is that
45 %% or %* can be mixed with the "%n$" form. When numbered argument spec‐
46 ifications are used, specifying the Nth argument requires that all the
47 leading arguments, from the first to the ( N-1)th, are pointers.
48 The fwscanf() function in all its forms allows for detection of a lan‐
50 guage-dependent radix character in the input string, encoded as a wide-
51 character value. The radix character is defined in the program's locale
52 (category LC_NUMERIC ). In the POSIX locale, or in a locale where the
53 radix character is not defined, the radix character shall default to a
54 period ( '.' ).
55 The format is a wide-character string composed of zero or more direc‐
57 tives. Each directive is composed of one of the following: one or more
58 white-space wide characters ( <space>s, <tab>s, <newline>s, <vertical-
59 tab>s, or <form-feed>s); an ordinary wide character (neither '%' nor a
60 white-space character); or a conversion specification. Each conversion
61 specification is introduced by a '%' or the sequence "%n$" after
62 which the following appear in sequence:
63 * An optional assignment-suppressing character '*' .
65 * An optional non-zero decimal integer that specifies the maximum
67 field width.
68 * An optional length modifier that specifies the size of the receiving
70 object.
71 * A conversion specifier wide character that specifies the type of
73 conversion to be applied. The valid conversion specifiers are
74 described below.
75 The fwscanf() functions shall execute each directive of the format in
77 turn. If a directive fails, as detailed below, the function shall
78 return. Failures are described as input failures (due to the unavail‐
79 ability of input bytes) or matching failures (due to inappropriate
80 input).
81 A directive composed of one or more white-space wide characters is exe‐
83 cuted by reading input until no more valid input can be read, or up to
84 the first wide character which is not a white-space wide character,
85 which remains unread.
86 A directive that is an ordinary wide character shall be executed as
88 follows. The next wide character is read from the input and compared
89 with the wide character that comprises the directive; if the comparison
90 shows that they are not equivalent, the directive shall fail, and the
91 differing and subsequent wide characters remain unread. Similarly, if
92 end-of-file, an encoding error, or a read error prevents a wide charac‐
93 ter from being read, the directive shall fail.
94 A directive that is a conversion specification defines a set of match‐
96 ing input sequences, as described below for each conversion wide char‐
97 acter. A conversion specification is executed in the following steps.
98 Input white-space wide characters (as specified by iswspace() ) shall
100 be skipped, unless the conversion specification includes a [ , c , or n
101 conversion specifier.
102 An item shall be read from the input, unless the conversion specifica‐
104 tion includes an n conversion specifier wide character. An input item
105 is defined as the longest sequence of input wide characters, not
106 exceeding any specified field width, which is an initial subsequence of
107 a matching sequence. The first wide character, if any, after the input
108 item shall remain unread. If the length of the input item is zero, the
109 execution of the conversion specification shall fail; this condition is
110 a matching failure, unless end-of-file, an encoding error, or a read
111 error prevented input from the stream, in which case it is an input
112 failure.
113 Except in the case of a % conversion specifier, the input item (or, in
115 the case of a %n conversion specification, the count of input wide
116 characters) shall be converted to a type appropriate to the conversion
117 wide character. If the input item is not a matching sequence, the exe‐
118 cution of the conversion specification shall fail; this condition is a
119 matching failure. Unless assignment suppression was indicated by a '*'
120 , the result of the conversion shall be placed in the object pointed to
121 by the first argument following the format argument that has not
122 already received a conversion result if the conversion specification is
123 introduced by % , or in the nth argument if introduced by the wide-
124 character sequence "%n$". If this object does not have an appropriate
125 type, or if the result of the conversion cannot be represented in the
126 space provided, the behavior is undefined.
127 The length modifiers and their meanings are:
129 hh Specifies that a following d , i , o , u , x , X , or n conver‐
131 sion specifier applies to an argument with type pointer to
132 signed char or unsigned char.
133 h Specifies that a following d , i , o , u , x , X , or n conver‐
135 sion specifier applies to an argument with type pointer to short
136 or unsigned short.
137 l (ell)
139 Specifies that a following d , i , o , u , x , X , or n conver‐
140 sion specifier applies to an argument with type pointer to long
141 or unsigned long; that a following a , A , e , E , f , F , g ,
142 or G conversion specifier applies to an argument with type
143 pointer to double; or that a following c , s , or [ conversion
144 specifier applies to an argument with type pointer to wchar_t.
145 ll (ell-ell)
147 Specifies that a following d , i , o , u , x , X , or n conver‐
149 sion specifier applies to an argument with type pointer to long
150 long or unsigned long long.
151 j Specifies that a following d , i , o , u , x , X , or n conver‐
153 sion specifier applies to an argument with type pointer to int‐
154 max_t or uintmax_t.
155 z Specifies that a following d , i , o , u , x , X , or n conver‐
157 sion specifier applies to an argument with type pointer to
158 size_t or the corresponding signed integer type.
159 t Specifies that a following d , i , o , u , x , X , or n conver‐
161 sion specifier applies to an argument with type pointer to
162 ptrdiff_t or the corresponding unsigned type.
163 L Specifies that a following a , A , e , E , f , F , g , or G con‐
165 version specifier applies to an argument with type pointer to
166 long double.
167 If a length modifier appears with any conversion specifier other than
170 as specified above, the behavior is undefined.
171 The following conversion specifier wide characters are valid:
173 d Matches an optionally signed decimal integer, whose format is
175 the same as expected for the subject sequence of wcstol() with
176 the value 10 for the base argument. In the absence of a size
177 modifier, the application shall ensure that the corresponding
178 argument is a pointer to int.
179 i Matches an optionally signed integer, whose format is the same
181 as expected for the subject sequence of wcstol() with 0 for the
182 base argument. In the absence of a size modifier, the applica‐
183 tion shall ensure that the corresponding argument is a pointer
184 to int.
185 o Matches an optionally signed octal integer, whose format is the
187 same as expected for the subject sequence of wcstoul() with the
188 value 8 for the base argument. In the absence of a size modi‐
189 fier, the application shall ensure that the corresponding argu‐
190 ment is a pointer to unsigned.
191 u Matches an optionally signed decimal integer, whose format is
193 the same as expected for the subject sequence of wcstoul() with
194 the value 10 for the base argument. In the absence of a size
195 modifier, the application shall ensure that the corresponding
196 argument is a pointer to unsigned.
197 x Matches an optionally signed hexadecimal integer, whose format
199 is the same as expected for the subject sequence of wcstoul()
200 with the value 16 for the base argument. In the absence of a
201 size modifier, the application shall ensure that the correspond‐
202 ing argument is a pointer to unsigned.
203 a, e, f, g
205 Matches an optionally signed floating-point number, infinity, or
207 NaN whose format is the same as expected for the subject
208 sequence of wcstod(). In the absence of a size modifier, the
209 application shall ensure that the corresponding argument is a
210 pointer to float.
211 If the fwprintf() family of functions generates character string repre‐
213 sentations for infinity and NaN (a symbolic entity encoded in floating-
214 point format) to support IEEE Std 754-1985, the fwscanf() family of
215 functions shall recognize them as input.
216 s Matches a sequence of non white-space wide characters. If no l
218 (ell) qualifier is present, characters from the input field
219 shall be converted as if by repeated calls to the wcrtomb()
220 function, with the conversion state described by an mbstate_t
221 object initialized to zero before the first wide character is
222 converted. The application shall ensure that the corresponding
223 argument is a pointer to a character array large enough to
224 accept the sequence and the terminating null character, which
225 shall be added automatically.
226 Otherwise, the application shall ensure that the corresponding argument
228 is a pointer to an array of wchar_t large enough to accept the sequence
229 and the terminating null wide character, which shall be added automati‐
230 cally.
231 [ Matches a non-empty sequence of wide characters from a set of
233 expected wide characters (the scanset). If no l (ell) qualifier
234 is present, wide characters from the input field shall be con‐
235 verted as if by repeated calls to the wcrtomb() function, with
236 the conversion state described by an mbstate_t object initial‐
237 ized to zero before the first wide character is converted. The
238 application shall ensure that the corresponding argument is a
239 pointer to a character array large enough to accept the sequence
240 and the terminating null character, which shall be added auto‐
241 matically.
242 If an l (ell) qualifier is present, the application shall ensure that
244 the corresponding argument is a pointer to an array of wchar_t large
245 enough to accept the sequence and the terminating null wide character,
246 which shall be added automatically.
247 The conversion specification includes all subsequent wide characters in
249 the format string up to and including the matching right square bracket
250 ( ']' ). The wide characters between the square brackets (the scanlist)
251 comprise the scanset, unless the wide character after the left square
252 bracket is a circumflex ( '^' ), in which case the scanset contains all
253 wide characters that do not appear in the scanlist between the circum‐
254 flex and the right square bracket. If the conversion specification
255 begins with "[]" or "[^]" , the right square bracket is included in the
256 scanlist and the next right square bracket is the matching right square
257 bracket that ends the conversion specification; otherwise, the first
258 right square bracket is the one that ends the conversion specification.
259 If a '-' is in the scanlist and is not the first wide character, nor
260 the second where the first wide character is a '^' , nor the last wide
261 character, the behavior is implementation-defined.
262 c Matches a sequence of wide characters of exactly the number
264 specified by the field width (1 if no field width is present in
265 the conversion specification).
266 If no l (ell) length modifier is present, characters from the input
268 field shall be converted as if by repeated calls to the wcrtomb() func‐
269 tion, with the conversion state described by an mbstate_t object ini‐
270 tialized to zero before the first wide character is converted. The
271 corresponding argument shall be a pointer to the initial element of a
272 character array large enough to accept the sequence. No null character
273 is added.
274 If an l (ell) length modifier is present, the corresponding argument
276 shall be a pointer to the initial element of an array of wchar_t large
277 enough to accept the sequence. No null wide character is added.
278 Otherwise, the application shall ensure that the corresponding argument
280 is a pointer to an array of wchar_t large enough to accept the
281 sequence. No null wide character is added.
282 p Matches an implementation-defined set of sequences, which shall
284 be the same as the set of sequences that is produced by the %p
285 conversion specification of the corresponding fwprintf() func‐
286 tions. The application shall ensure that the corresponding argu‐
287 ment is a pointer to a pointer to void. The interpretation of
288 the input item is implementation-defined. If the input item is a
289 value converted earlier during the same program execution, the
290 pointer that results shall compare equal to that value; other‐
291 wise, the behavior of the %p conversion is undefined.
292 n No input is consumed. The application shall ensure that the cor‐
294 responding argument is a pointer to the integer into which is to
295 be written the number of wide characters read from the input so
296 far by this call to the fwscanf() functions. Execution of a %n
297 conversion specification shall not increment the assignment
298 count returned at the completion of execution of the function.
299 No argument shall be converted, but one shall be consumed. If
300 the conversion specification includes an assignment-suppressing
301 wide character or a field width, the behavior is undefined.
302 C Equivalent to lc .
304 S Equivalent to ls .
306 % Matches a single '%' wide character; no conversion or assignment
308 shall occur. The complete conversion specification shall be %% .
309 If a conversion specification is invalid, the behavior is undefined.
312 The conversion specifiers A , E , F , G , and X are also valid and
314 shall be equivalent to, respectively, a , e , f , g , and x .
315 If end-of-file is encountered during input, conversion is terminated.
317 If end-of-file occurs before any wide characters matching the current
318 conversion specification (except for %n ) have been read (other than
319 leading white-space, where permitted), execution of the current conver‐
320 sion specification shall terminate with an input failure. Otherwise,
321 unless execution of the current conversion specification is terminated
322 with a matching failure, execution of the following conversion specifi‐
323 cation (if any) shall be terminated with an input failure.
324 Reaching the end of the string in swscanf() shall be equivalent to
326 encountering end-of-file for fwscanf().
327 If conversion terminates on a conflicting input, the offending input
329 shall be left unread in the input. Any trailing white space (including
330 <newline>) shall be left unread unless matched by a conversion specifi‐
331 cation. The success of literal matches and suppressed assignments is
332 only directly determinable via the %n conversion specification.
333 The fwscanf() and wscanf() functions may mark the st_atime field of the
335 file associated with stream for update. The st_atime field shall be
336 marked for update by the first successful execution of fgetc(),
337 fgetwc(), fgets(), fgetws(), fread(), getc(), getwc(), getchar(),
338 getwchar(), gets(), fscanf(), or fwscanf() using stream that returns
339 data not supplied by a prior call to ungetc().
340
342 Upon successful completion, these functions shall return the number of
343 successfully matched and assigned input items; this number can be zero
344 in the event of an early matching failure. If the input ends before the
345 first matching failure or conversion, EOF shall be returned. If a read
346 error occurs, the error indicator for the stream is set, EOF shall be
347 returned, and errno shall be set to indicate the error.
348
350 For the conditions under which the fwscanf() functions shall fail and
351 may fail, refer to fgetwc() .
352 In addition, fwscanf() may fail if:
354 EILSEQ Input byte sequence does not form a valid character.
356 EINVAL There are insufficient arguments.
358 The following sections are informative.
361
363 The call:
364 int i, n; float x; char name[50];
367 n = wscanf(L"%d%f%s", &i, &x, name);
368 with the input line:
370 25 54.32E-1 Hamster
373 assigns to n the value 3, to i the value 25, to x the value 5.432, and
375 name contains the string "Hamster" .
376 The call:
378 int i; float x; char name[50];
381 (void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name);
382 with input:
384 56789 0123 56a72
387 assigns 56 to i, 789.0 to x, skips 0123, and places the string "56\0"
389 in name. The next call to getchar() shall return the character 'a' .
390
392 In format strings containing the '%' form of conversion specifications,
393 each argument in the argument list is used exactly once.
394
396 None.
397
399 None.
400
402 getwc() , fwprintf() , setlocale() , wcstod() , wcstol() , wcstoul() ,
403 wcrtomb() , the Base Definitions volume of IEEE Std 1003.1-2001, Chap‐
404 ter 7, Locale, <langinfo.h>, <stdio.h>, <wchar.h>
405
407 Portions of this text are reprinted and reproduced in electronic form
408 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
409 -- Portable Operating System Interface (POSIX), The Open Group Base
410 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
411 Electrical and Electronics Engineers, Inc and The Open Group. In the
412 event of any discrepancy between this version and the original IEEE and
413 The Open Group Standard, the original IEEE and The Open Group Standard
414 is the referee document. The original Standard can be obtained online
415 at http://www.opengroup.org/unix/online.html .
416IEEE/The Open Group 2003 FWSCANF(P)