fwscanf(3S) SDK R4.11 fwscanf(3S)
NAME
fwscanf, wscanf, swscanf - convert formatted wide character input
SYNOPSIS
#include <stdio.h>
#include <wchar.h>
int fwscanf(FILE *stream, const wchart *format, ...);
int wscanf(const wchart *format, ...);
int swscanf(const wchart *s, const wchart *format, ...);
DESCRIPTION
fwscanf reads input from the stream pointed to by stream, under
control of the wide string pointed to by format that specifies
admissible input sequences and how they are converted for input. If
there are insufficient arguments for the format, the behavior is
undefined. If the format is exhausted while the arguments remain,
the excess arguments are evaluated but are otherwise ignored.
wscanf reads input to the stream in the same manner as fwscanf, with
the argument stdout interposed before the arguments to wscanf.
swscanf reads input to the stream in the same manner as fwscanf,
except that the argument s specifies a wide string from which the
generated input is read, rather than converting multibyte characters
from a stream. Also, the detection of wide or multibyte encoding
errors may differ. If the end of the wide string is reached, it
behaves the same as when an end-of-file is encountered for fwscanf.
If copying takes place between objects that overlap, the behavior is
undefined.
The format is composed of zero or more directives which include:
One or more white space wide characters
Ordinary wide characters (not % or white space)
Conversion specifications (all wide characters which are
members of the basic character set).
Each conversion specification is introduced by the wide character %
and followed by:
An optional assignment-suppressing wide character *.
An optional nonzero decimal integer that specifies the maximum
field width.
An optional h, l or L indicating the size of the receiving
object. The conversion specifiers d, i, and n are preceded by
h if the corresponding argument is a pointer to short int
instead of a pointer to int, or by l if it is a pointer to
long int. The conversion specifiers b, o, u and x are
preceded by h if the corresponding argument is a pointer to
unsigned short int instead of a pointer to unsigned int, or by
l if it is a pointer to an unsigned long int. The conversion
specifiers a, e, f and g are preceded by l if the
corresponding argument is a pointer to double rather than a
pointer to float or by L if it is a pointer to long double.
If an h, l or L appears with any other conversion specifier,
the behavior is undefined.
A wide character that specifies the type of conversion to be
applied.
fwscanf executes each directive of the format in turn. If a
directive fails, the function returns. Failures can be input
failures if an encoding error occurs or if input characters are
unavailable. Failures can also be matching failures if there is
inappropriate input.
A directive comprised of white space wide characters is executed by
reading input up to the first non white-space character which remains
unread, or until no more wide characters can be read.
A directive that is an ordinary wide character is executed by reading
the next wide character of the stream. If the wide character differs
from the directive, the directive fails, and the differing and next
wide characters remain unread.
A directive that is a conversion specification defines a set of
matching input sequences, as described below for each specifier. A
conversion specification is executed as follows:
1 Input white-space wide characters, as specified by the
iswspace function, are skipped unless the specification
includes a c or n specifier.
2 An input item is read from the stream unless the specification
includes an n specifier. An input item is defined as the
longest matching sequence of input wide characters unless that
exceeds a specified field width. The first wide character, if
any, after the input item remains unread. If the length of
the input item is zero, the execution of the directive fails.
This condition is a matching failure, unless an error
prevented input from the stream, which causes an input
failure.
3 Except for a % specifier, the input item is converted to a
type appropriate to the conversion specifier. This also
applies to an n directive for the count of wide characters.
If the input item is not a matching sequence, the execution of
the directive fails. This constitutes a matching failure.
Unless assignment suppression is indicated by a *, the result
of the conversion is placed in the object pointed to by the
first argument following the format argument that has not
already received a conversion result. If this object does not
have an appropriate type, or if the result of the conversion
cannot be represented in the space provided, the behavior is
undefined.
The following section lists the valid conversion specifiers and their
meanings:
d Matches an optionally signed decimal integer whose format is
the same as expected for the subject sequence of the wcstol
function with the value 10 for the base argument. The
corresponding argument is a pointer to an integer.
i Matches an optionally signed integer whose format is the same
as expected for the subject sequence of the wcstol function
with the value 0 for the base argument. The corresponding
argument is a pointer to an integer.
b Matches an optionally signed binary integer whose format is
the same as expected for the subject sequence of the wcstoul
function with the value 2 for the base argument. The
corresponding argument is a pointer to an integer.
o Matches an optionally signed octal integer whose format is the
same as expected for the subject sequence of the wcstoul
function with the value 8 for the base argument. The
corresponding argument is a pointer to an integer.
u Matches an optionally signed decimal integer whose format is
the same as expected for the subject sequence of the wcstoul
function with the value 10 for the base argument. The
corresponding argument is a pointer to an unsigned integer.
x Matches an optionally signed hexadecimal integer whose format
is the same as expected for the subject sequence of the
wcstoul function with the value 16 for the base argument. The
corresponding argument is a pointer to an unsigned integer.
a,e,f,g
Matches an optionally floating point number whose format is
the same as expected for the subject sequence of the wcstod
function. The corresponding argument is a pointer to a
floating point number.
s Matches a sequence of non-white-space wide characters. The
corresponding argument is a pointer to the initial element of
an array of wchart type large enough to accept the sequence
and a terminating null wide character that is added
automatically.
c Matches a sequence of wide characters of the number specified
by the field width, or 1 if no field width is present in the
directive. The corresponding argument is a pointer to the
initial element of an array of wchart type large enough to
accept the sequence. No null wide character is added.
p Matches an implementation-defined set of sequences that are
the same as the set of sequences that are produced by the %p
conversion of fwprintf. The corresponding argument is a
pointer to void. The interpretation of the input is
implementation defined. If the input item is a value
converted earlier during the same program execution, the
pointer that results compares equally to that value.
Otherwise the behavior of %p is undefined.
n No input is consumed. The corresponding argument is a pointer
to an integer into which is written the number of wide
characters read so far from the input stream written into it.
Execution of a %n directive does not increment the assignment
count returned at the completion of execution of this
function.
% Matches a single %. No conversion or assignment occurs. The
complete conversion specification is %%.
If a conversion specification is invalid, the behavior is undefined.
The conversion specifiers A, E, G and X are also valid and behave the
same as a, e, g and x respectively.
Errors
fwscanf, wscanf and swscanf return the number of wide characters
transmitted or return a negative value if an error was encountered.
REFERENCES
printf(3S), scanf(3S), setlocale(3C), stdio(3S), write(2)
Licensed material--property of copyright holder(s)