1FWSCANF(3P)                POSIX Programmer's Manual               FWSCANF(3P)
2
3
4

PROLOG

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
11

NAME

13       fwscanf, swscanf, wscanf — convert formatted wide-character input
14

SYNOPSIS

16       #include <stdio.h>
17       #include <wchar.h>
18
19       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

DESCRIPTION

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
30       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
41       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
52       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
59       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
66       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
72       Each  conversion specification is introduced by the '%' or by the char‐
73       acter sequence "%n$", after which the following appear in sequence:
74
75        *  An optional assignment-suppressing character '*'.
76
77        *  An optional non-zero decimal integer  that  specifies  the  maximum
78           field width.
79
80        *  An optional assignment-allocation character 'm'.
81
82        *  An  optional length modifier that specifies the size of the receiv‐
83           ing object.
84
85        *  A conversion specifier wide character that specifies  the  type  of
86           conversion  to  be  applied.  The  valid  conversion specifiers are
87           described below.
88
89       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
95       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
100       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
108       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
112       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
116       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
127       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
141       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
155       The length modifiers and their meanings are:
156
157       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
161       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
165       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
175       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
180       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
184       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
188       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
192       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
196       If a length modifier appears with any conversion specifier  other  than
197       as specified above, the behavior is undefined.
198
199       The following conversion specifier wide characters are valid:
200
201       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
207       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
213       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
219       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
225       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
231       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
238               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
244       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
257               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
267       [       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
281               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
290               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
307       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
311               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
323               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
332       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
342       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
353       C       Equivalent to lc.
354
355       S       Equivalent to ls.
356
357       %       Matches a single '%' wide character; no conversion  or  assign‐
358               ment  shall  occur. The complete conversion specification shall
359               be %%.
360
361       If a conversion specification is invalid, the behavior is undefined.
362
363       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
366       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
375       Reaching the end of the string in  swscanf()  shall  be  equivalent  to
376       encountering end-of-file for fwscanf().
377
378       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
384       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

RETURN VALUE

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

ERRORS

401       For the conditions under which the fwscanf() functions shall  fail  and
402       may fail, refer to fgetwc().
403
404       In addition, the fwscanf() function shall fail if:
405
406       EILSEQ Input byte sequence does not form a valid character.
407
408       ENOMEM Insufficient storage space is available.
409
410       In addition, the fwscanf() function may fail if:
411
412       EINVAL There are insufficient arguments.
413
414       The following sections are informative.
415

EXAMPLES

417       The call:
418
419           int i, n; float x; char name[50];
420           n = wscanf(L"%d%f%s", &i, &x, name);
421
422       with the input line:
423
424           25 54.32E−1 Hamster
425
426       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
429       The call:
430
431           int i; float x; char name[50];
432           (void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name);
433
434       with input:
435
436           56789 0123 56a72
437
438       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

APPLICATION USAGE

442       In format strings containing the '%' form of conversion specifications,
443       each argument in the argument list is used exactly once.
444
445       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

RATIONALE

451       None.
452

FUTURE DIRECTIONS

454       None.
455

SEE ALSO

457       Section  2.5,  Standard  I/O Streams, getwc(), fwprintf(), setlocale(),
458       wcstod(), wcstol(), wcstoul(), wcrtomb()
459
460       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
475       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 .
479
480
481
482IEEE/The Open Group                  2013                          FWSCANF(3P)
Impressum