1FWSCANF(3P) POSIX Programmer's Manual FWSCANF(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 fwscanf, swscanf, wscanf — convert formatted wide-character input
14
16 #include <stdio.h>
17 #include <wchar.h>
18 int fwscanf(FILE *restrict stream, const wchar_t *restrict format, ...);
20 int swscanf(const wchar_t *restrict ws,
21 const wchar_t *restrict format, ...);
22 int wscanf(const wchar_t *restrict format, ...);
23
25 The functionality described on this reference page is aligned with the
26 ISO C standard. Any conflict between the requirements described here
27 and the ISO C standard is unintentional. This volume of POSIX.1‐2008
28 defers to the ISO C standard.
29 The fwscanf() function shall read from the named input stream. The
31 wscanf() function shall read from the standard input stream stdin. The
32 swscanf() function shall read from the wide-character string ws. Each
33 function reads wide characters, interprets them according to a format,
34 and stores the results in its arguments. Each expects, as arguments, a
35 control wide-character string format described below, and a set of
36 pointer arguments indicating where the converted input should be
37 stored. The result is undefined if there are insufficient arguments for
38 the format. If the format is exhausted while arguments remain, the
39 excess arguments are evaluated but are otherwise ignored.
40 Conversions can be applied to the nth argument after the format in the
42 argument list, rather than to the next unused argument. In this case,
43 the conversion specifier wide character % (see below) is replaced by
44 the sequence "%n$", where n is a decimal integer in the range
45 [1,{NL_ARGMAX}]. This feature provides for the definition of format
46 wide-character strings that select arguments in an order appropriate to
47 specific languages. In format wide-character strings containing the
48 "%n$" form of conversion specifications, it is unspecified whether num‐
49 bered arguments in the argument list can be referenced from the format
50 wide-character string more than once.
51 The format can contain either form of a conversion specification—that
53 is, % or "%n$"— but the two forms cannot normally be mixed within a
54 single format wide-character string. The only exception to this is that
55 %% or %* can be mixed with the "%n$" form. When numbered argument spec‐
56 ifications are used, specifying the Nth argument requires that all the
57 leading arguments, from the first to the (N−1)th, are pointers.
58 The fwscanf() function in all its forms allows for detection of a lan‐
60 guage-dependent radix character in the input string, encoded as a wide-
61 character value. The radix character is defined in the current locale
62 (category LC_NUMERIC). In the POSIX locale, or in a locale where the
63 radix character is not defined, the radix character shall default to a
64 <period> ('.').
65 The format is a wide-character string composed of zero or more direc‐
67 tives. Each directive is composed of one of the following: one or more
68 white-space wide characters (<space>, <tab>, <newline>, <vertical-tab>,
69 or <form-feed>); an ordinary wide character (neither '%' nor a white-
70 space character); or a conversion specification.
71 Each conversion specification is introduced by the '%' or by the char‐
73 acter sequence "%n$", after which the following appear in sequence:
74 * An optional assignment-suppressing character '*'.
76 * An optional non-zero decimal integer that specifies the maximum
78 field width.
79 * An optional assignment-allocation character 'm'.
81 * An optional length modifier that specifies the size of the receiv‐
83 ing object.
84 * A conversion specifier wide character that specifies the type of
86 conversion to be applied. The valid conversion specifiers are
87 described below.
88 The fwscanf() functions shall execute each directive of the format in
90 turn. If a directive fails, as detailed below, the function shall
91 return. Failures are described as input failures (due to the unavail‐
92 ability of input bytes) or matching failures (due to inappropriate
93 input).
94 A directive composed of one or more white-space wide characters is exe‐
96 cuted by reading input until no more valid input can be read, or up to
97 the first wide character which is not a white-space wide character,
98 which remains unread.
99 A directive that is an ordinary wide character shall be executed as
101 follows. The next wide character is read from the input and compared
102 with the wide character that comprises the directive; if the comparison
103 shows that they are not equivalent, the directive shall fail, and the
104 differing and subsequent wide characters remain unread. Similarly, if
105 end-of-file, an encoding error, or a read error prevents a wide charac‐
106 ter from being read, the directive shall fail.
107 A directive that is a conversion specification defines a set of match‐
109 ing input sequences, as described below for each conversion wide char‐
110 acter. A conversion specification is executed in the following steps.
111 Input white-space wide characters (as specified by iswspace()) shall be
113 skipped, unless the conversion specification includes a [, c, or n con‐
114 version specifier.
115 An item shall be read from the input, unless the conversion specifica‐
117 tion includes an n conversion specifier wide character. An input item
118 is defined as the longest sequence of input wide characters, not
119 exceeding any specified field width, which is an initial subsequence of
120 a matching sequence. The first wide character, if any, after the input
121 item shall remain unread. If the length of the input item is zero, the
122 execution of the conversion specification shall fail; this condition is
123 a matching failure, unless end-of-file, an encoding error, or a read
124 error prevented input from the stream, in which case it is an input
125 failure.
126 Except in the case of a % conversion specifier, the input item (or, in
128 the case of a %n conversion specification, the count of input wide
129 characters) shall be converted to a type appropriate to the conversion
130 wide character. If the input item is not a matching sequence, the exe‐
131 cution of the conversion specification shall fail; this condition is a
132 matching failure. Unless assignment suppression was indicated by a '*',
133 the result of the conversion shall be placed in the object pointed to
134 by the first argument following the format argument that has not
135 already received a conversion result if the conversion specification is
136 introduced by %, or in the nth argument if introduced by the wide-char‐
137 acter sequence "%n$". If this object does not have an appropriate
138 type, or if the result of the conversion cannot be represented in the
139 space provided, the behavior is undefined.
140 The %c, %s, and %[ conversion specifiers shall accept an optional
142 assignment-allocation character 'm', which shall cause a memory buffer
143 to be allocated to hold the wide-character string converted including a
144 terminating null wide character. In such a case, the argument corre‐
145 sponding to the conversion specifier should be a reference to a pointer
146 value that will receive a pointer to the allocated buffer. The system
147 shall allocate a buffer as if malloc() had been called. The application
148 shall be responsible for freeing the memory after usage. If there is
149 insufficient memory to allocate a buffer, the function shall set errno
150 to [ENOMEM] and a conversion error shall result. If the function
151 returns EOF, any memory successfully allocated for parameters using
152 assignment-allocation character 'm' by this call shall be freed before
153 the function returns.
154 The length modifiers and their meanings are:
156 hh Specifies that a following d, i, o, u, x, X, or n conversion
158 specifier applies to an argument with type pointer to signed
159 char or unsigned char.
160 h Specifies that a following d, i, o, u, x, X, or n conversion
162 specifier applies to an argument with type pointer to short or
163 unsigned short.
164 l (ell) Specifies that a following d, i, o, u, x, X, or n conversion
166 specifier applies to an argument with type pointer to long or
167 unsigned long; that a following a, A, e, E, f, F, g, or G con‐
168 version specifier applies to an argument with type pointer to
169 double; or that a following c, s, or [ conversion specifier
170 applies to an argument with type pointer to wchar_t. If the
171 'm' assignment-allocation character is specified, the conver‐
172 sion applies to an argument with the type pointer to a pointer
173 to wchar_t.
174 ll (ell-ell)
176 Specifies that a following d, i, o, u, x, X, or n conversion
177 specifier applies to an argument with type pointer to long long
178 or unsigned long long.
179 j Specifies that a following d, i, o, u, x, X, or n conversion
181 specifier applies to an argument with type pointer to intmax_t
182 or uintmax_t.
183 z Specifies that a following d, i, o, u, x, X, or n conversion
185 specifier applies to an argument with type pointer to size_t or
186 the corresponding signed integer type.
187 t Specifies that a following d, i, o, u, x, X, or n conversion
189 specifier applies to an argument with type pointer to ptrdiff_t
190 or the corresponding unsigned type.
191 L Specifies that a following a, A, e, E, f, F, g, or G conversion
193 specifier applies to an argument with type pointer to long dou‐
194 ble.
195 If a length modifier appears with any conversion specifier other than
197 as specified above, the behavior is undefined.
198 The following conversion specifier wide characters are valid:
200 d Matches an optionally signed decimal integer, whose format is
202 the same as expected for the subject sequence of wcstol() with
203 the value 10 for the base argument. In the absence of a size
204 modifier, the application shall ensure that the corresponding
205 argument is a pointer to int.
206 i Matches an optionally signed integer, whose format is the same
208 as expected for the subject sequence of wcstol() with 0 for the
209 base argument. In the absence of a size modifier, the applica‐
210 tion shall ensure that the corresponding argument is a pointer
211 to int.
212 o Matches an optionally signed octal integer, whose format is the
214 same as expected for the subject sequence of wcstoul() with the
215 value 8 for the base argument. In the absence of a size modi‐
216 fier, the application shall ensure that the corresponding argu‐
217 ment is a pointer to unsigned.
218 u Matches an optionally signed decimal integer, whose format is
220 the same as expected for the subject sequence of wcstoul() with
221 the value 10 for the base argument. In the absence of a size
222 modifier, the application shall ensure that the corresponding
223 argument is a pointer to unsigned.
224 x Matches an optionally signed hexadecimal integer, whose format
226 is the same as expected for the subject sequence of wcstoul()
227 with the value 16 for the base argument. In the absence of a
228 size modifier, the application shall ensure that the corre‐
229 sponding argument is a pointer to unsigned.
230 a, e, f, g
232 Matches an optionally signed floating-point number, infinity,
233 or NaN whose format is the same as expected for the subject
234 sequence of wcstod(). In the absence of a size modifier, the
235 application shall ensure that the corresponding argument is a
236 pointer to float.
237 If the fwprintf() family of functions generates character
239 string representations for infinity and NaN (a symbolic entity
240 encoded in floating-point format) to support IEEE Std 754‐1985,
241 the fwscanf() family of functions shall recognize them as
242 input.
243 s Matches a sequence of non-white-space wide characters. If no l
245 (ell) qualifier is present, characters from the input field
246 shall be converted as if by repeated calls to the wcrtomb()
247 function, with the conversion state described by an mbstate_t
248 object initialized to zero before the first wide character is
249 converted. If the 'm' assignment-allocation character is not
250 specified, the application shall ensure that the corresponding
251 argument is a pointer to a character array large enough to
252 accept the sequence and the terminating null character, which
253 shall be added automatically. Otherwise, the application shall
254 ensure that the corresponding argument is a pointer to a
255 pointer to a wchar_t.
256 If the l (ell) qualifier is present and the 'm' assignment-
258 allocation character is not specified, the application shall
259 ensure that the corresponding argument is a pointer to an array
260 of wchar_t large enough to accept the sequence and the termi‐
261 nating null wide character, which shall be added automatically.
262 If the l (ell) qualifier is present and the 'm' assignment-
263 allocation character is present, the application shall ensure
264 that the corresponding argument is a pointer to a pointer to a
265 wchar_t.
266 [ Matches a non-empty sequence of wide characters from a set of
268 expected wide characters (the scanset). If no l (ell) quali‐
269 fier is present, wide characters from the input field shall be
270 converted as if by repeated calls to the wcrtomb() function,
271 with the conversion state described by an mbstate_t object ini‐
272 tialized to zero before the first wide character is converted.
273 If the 'm' assignment-allocation character is not specified,
274 the application shall ensure that the corresponding argument is
275 a pointer to a character array large enough to accept the
276 sequence and the terminating null character, which shall be
277 added automatically. Otherwise, the application shall ensure
278 that the corresponding argument is a pointer to a pointer to a
279 wchar_t.
280 If an l (ell) qualifier is present and the 'm' assignment-allo‐
282 cation character is not specified, the application shall ensure
283 that the corresponding argument is a pointer to an array of
284 wchar_t large enough to accept the sequence and the terminating
285 null wide character. If an l (ell) qualifier is present and
286 the 'm' assignment-allocation character is specified, the
287 application shall ensure that the corresponding argument is a
288 pointer to a pointer to a wchar_t.
289 The conversion specification includes all subsequent wide char‐
291 acters in the format string up to and including the matching
292 <right-square-bracket> (']'). The wide characters between the
293 square brackets (the scanlist) comprise the scanset, unless the
294 wide character after the <left-square-bracket> is a <circum‐
295 flex> ('^'), in which case the scanset contains all wide char‐
296 acters that do not appear in the scanlist between the <circum‐
297 flex> and the <right-square-bracket>. If the conversion speci‐
298 fication begins with "[]" or "[^]", the <right-square-bracket>
299 is included in the scanlist and the next <right-square-bracket>
300 is the matching <right-square-bracket> that ends the conversion
301 specification; otherwise, the first <right-square-bracket> is
302 the one that ends the conversion specification. If a '−' is in
303 the scanlist and is not the first wide character, nor the sec‐
304 ond where the first wide character is a '^', nor the last wide
305 character, the behavior is implementation-defined.
306 c Matches a sequence of wide characters of exactly the number
308 specified by the field width (1 if no field width is present in
309 the conversion specification).
310 If no l (ell) length modifier is present, characters from the
312 input field shall be converted as if by repeated calls to the
313 wcrtomb() function, with the conversion state described by an
314 mbstate_t object initialized to zero before the first wide
315 character is converted. No null character is added. If the 'm'
316 assignment-allocation character is not specified, the applica‐
317 tion shall ensure that the corresponding argument is a pointer
318 to the initial element of a character array large enough to
319 accept the sequence. Otherwise, the application shall ensure
320 that the corresponding argument is a pointer to a pointer to a
321 char.
322 No null wide character is added. If an l (ell) length modifier
324 is present and the 'm' assignment-allocation character is not
325 specified, the application shall ensure that the corresponding
326 argument shall be a pointer to the initial element of an array
327 of wchar_t large enough to accept the sequence. If an l (ell)
328 qualifier is present and the 'm' assignment-allocation charac‐
329 ter is specified, the application shall ensure that the corre‐
330 sponding argument is a pointer to a pointer to a wchar_t.
331 p Matches an implementation-defined set of sequences, which shall
333 be the same as the set of sequences that is produced by the %p
334 conversion specification of the corresponding fwprintf() func‐
335 tions. The application shall ensure that the corresponding
336 argument is a pointer to a pointer to void. The interpretation
337 of the input item is implementation-defined. If the input item
338 is a value converted earlier during the same program execution,
339 the pointer that results shall compare equal to that value;
340 otherwise, the behavior of the %p conversion is undefined.
341 n No input is consumed. The application shall ensure that the
343 corresponding argument is a pointer to the integer into which
344 is to be written the number of wide characters read from the
345 input so far by this call to the fwscanf() functions. Execution
346 of a %n conversion specification shall not increment the
347 assignment count returned at the completion of execution of the
348 function. No argument shall be converted, but one shall be con‐
349 sumed. If the conversion specification includes an assignment-
350 suppressing wide character or a field width, the behavior is
351 undefined.
352 C Equivalent to lc.
354 S Equivalent to ls.
356 % Matches a single '%' wide character; no conversion or assign‐
358 ment shall occur. The complete conversion specification shall
359 be %%.
360 If a conversion specification is invalid, the behavior is undefined.
362 The conversion specifiers A, E, F, G, and X are also valid and shall be
364 equivalent to, respectively, a, e, f, g, and x.
365 If end-of-file is encountered during input, conversion is terminated.
367 If end-of-file occurs before any wide characters matching the current
368 conversion specification (except for %n) have been read (other than
369 leading white-space, where permitted), execution of the current conver‐
370 sion specification shall terminate with an input failure. Otherwise,
371 unless execution of the current conversion specification is terminated
372 with a matching failure, execution of the following conversion specifi‐
373 cation (if any) shall be terminated with an input failure.
374 Reaching the end of the string in swscanf() shall be equivalent to
376 encountering end-of-file for fwscanf().
377 If conversion terminates on a conflicting input, the offending input
379 shall be left unread in the input. Any trailing white space (including
380 <newline>) shall be left unread unless matched by a conversion specifi‐
381 cation. The success of literal matches and suppressed assignments is
382 only directly determinable via the %n conversion specification.
383 The fwscanf() and wscanf() functions may mark the last data access
385 timestamp of the file associated with stream for update. The last data
386 access timestamp shall be marked for update by the first successful
387 execution of fgetwc(), fgetws(), fwscanf(), getwc(), getwchar(), vfws‐
388 canf(), vwscanf(), or wscanf() using stream that returns data not sup‐
389 plied by a prior call to ungetwc().
390
392 Upon successful completion, these functions shall return the number of
393 successfully matched and assigned input items; this number can be zero
394 in the event of an early matching failure. If the input ends before the
395 first matching failure or conversion, EOF shall be returned. If any
396 error occurs, EOF shall be returned, and errno shall be set to indicate
397 the error. If a read error occurs, the error indicator for the stream
398 shall be set.
399
401 For the conditions under which the fwscanf() functions shall fail and
402 may fail, refer to fgetwc().
403 In addition, the fwscanf() function shall fail if:
405 EILSEQ Input byte sequence does not form a valid character.
407 ENOMEM Insufficient storage space is available.
409 In addition, the fwscanf() function may fail if:
411 EINVAL There are insufficient arguments.
413 The following sections are informative.
415
417 The call:
418 int i, n; float x; char name[50];
420 n = wscanf(L"%d%f%s", &i, &x, name);
421 with the input line:
423 25 54.32E−1 Hamster
425 assigns to n the value 3, to i the value 25, to x the value 5.432, and
427 name contains the string "Hamster".
428 The call:
430 int i; float x; char name[50];
432 (void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name);
433 with input:
435 56789 0123 56a72
437 assigns 56 to i, 789.0 to x, skips 0123, and places the string "56\0"
439 in name. The next call to getchar() shall return the character 'a'.
440
442 In format strings containing the '%' form of conversion specifications,
443 each argument in the argument list is used exactly once.
444 For functions that allocate memory as if by malloc(), the application
446 should release such memory when it is no longer required by a call to
447 free(). For fwscanf(), this is memory allocated via use of the 'm'
448 assignment-allocation character.
449
451 None.
452
454 None.
455
457 Section 2.5, Standard I/O Streams, getwc(), fwprintf(), setlocale(),
458 wcstod(), wcstol(), wcstoul(), wcrtomb()
459 The Base Definitions volume of POSIX.1‐2008, Chapter 7, Locale,
461 <stdio.h>, <wchar.h>
462
464 Portions of this text are reprinted and reproduced in electronic form
465 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
466 -- Portable Operating System Interface (POSIX), The Open Group Base
467 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
468 cal and Electronics Engineers, Inc and The Open Group. (This is
469 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
470 event of any discrepancy between this version and the original IEEE and
471 The Open Group Standard, the original IEEE and The Open Group Standard
472 is the referee document. The original Standard can be obtained online
473 at http://www.unix.org/online.html .
474 Any typographical or formatting errors that appear in this page are
476 most likely to have been introduced during the conversion of the source
477 files to man page format. To report such errors, see https://www.ker‐
478 nel.org/doc/man-pages/reporting_bugs.html .
479IEEE/The Open Group 2013 FWSCANF(3P)