fwscanf(3S) fwscanf(3S)
NAME
fwscanf, wscanf, swscanf - formatted wide-character input
SYNOPSIS
cc [flag ...] file ... -lw [library ...]
#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
The fwscanf() function reads input from the stream pointed to by
stream, under control of the wide string pointed to by format that
specifies the admissible input sequences and how they are to be con-
verted for assignment, using subsequent arguments as pointers to the
objects to receive the converted input. If there are insufficient
arguments for the format, the behavior is undefined. If the format is
exhausted while arguments remain, the excess arguments are evaluated
(as always) but are otherwise ignored.
The wscanf() function is equivalent to fwscanf() with the argument
stdin interposed before the arguments to wscanf().
The swscanf() function is equivalent to fwscanf(), except that the
argument s specifies a wide string from which the input is to be
obtained, rather than from a stream. Reaching the end of the wide
string is equivalent to encountering end-of-file for fwscanf() func-
tion.
Format
The format is composed of zero or more directives; one or more white-
space wide-characters; an ordinary wide-character (neither % nor a
white-space wide-character) or a conversion specification. Each
conversion specification is introduced by a %. After the %, the fol-
lowing appear in sequence:
- An optional assignment-suppressing wide-character *.
- An optional nonzero decimal integer that specifies the maximum
field width (in wide-character).
- An optional h, l or L indicating the size of the receiving object.
The conversion specifiers c, s, and [ shall be preceded by l if the
corresponding argument is a pointer to wchart rather than a
pointer to a character type. The conversion specifiers d, i and n
shall be preceded by h if the corresponding argument is a pointer
to short int rather than a pointer to int, or by l if it is a
Page 1 Reliant UNIX 5.44 Printed 11/98
fwscanf(3S) fwscanf(3S)
pointer to long int. Similarly the conversion specifiers o, u and x
shall be preceded by h if the corresponding argument is a pointer
to unsigned short int rather than a pointer to unsigned int, or by
l if it is a pointer to unsigned long int. Finally, the conversion
specifiers e, f and g shall be 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. The valid conversion specifiers are described below.
The fwscanf() function executes each directive of the format in turn.
If a directive fails, as detailed below, the fwscanf() function
returns. Failures are described as input failures (if an encoding
error occurs or due to the unavailability of input characters), or
matching failures (due to inappropriate input).
A directive composed of white-space wide-character(s) is executed by
reading input up to the first non-white-space wide-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 subse-
quent wide-characters remain unread.
A directive that is a conversion specification defines a set of match-
ing input sequences, as described below for each specifier. A conver-
sion specification is executed in the following steps.
Input white-space wide-characters (as specified by the iswspace()
function) are skipped, unless the specification includes a c or n
specifier. These white-space wide-characters are not counted against a
specified field width.
An input item is read from the stream, unless the specification
includes an n specifier. An input item is defined as the longest
sequence of input wide-characters, not exceeding any specified field
width, which is, or is a prefix of a matching sequence. The first
wide-character, if any, after 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 end-of-file, an encoding
error, or a read error prevented input from the stream, in which case
it is an input failure.
Except in the case of a % specifier, the input item (or, in the case
of a %n directive, the count of input wide-characters) is converted to
a type appropriate to the conversion specifier. If the input item is
not a matching sequence, the execution of the directive fails; this
condition is a matching failure. Unless assignment suppression was
indicated by a *, the result of the conversion is placed in the object
Page 2 Reliant UNIX 5.44 Printed 11/98
fwscanf(3S) fwscanf(3S)
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.
Conversion specifiers
The following conversion specifiers are valid:
d Matches an optionally signed decimal integer, whose format is the
same as expected for the subject sequence of the wcstol() func-
tion with the value 10 for the base argument. The corresponding
argument shall be a pointer to 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
shall be a pointer to integer.
o Matches an optionally signed octal integer, whose format is the
same as expected for the subject sequence of the wcstol() func-
tion with the value 8 for the base argument. The corresponding
argument shall be a pointer to unsigned integer.
u Matches an optionally signed decimal integer, whose format is the
same as expected for the subject sequence of the wcstol() func-
tion with the value 10 for the base argument. The corresponding
argument shall be a pointer to unsigned integer.
x Matches an optionally signed hexadecimal integer, whose format is
the same as expected for the subject sequence of the wcstol()
function with the value 16 for the base argument. The correspond-
ing argument shall be a pointer to unsigned integer.
e, f, g
Matches an optionally signed floating-point number, whose format
is the same as expected for the subject sequence of the wcstol()
function. The corresponding argument shall be a pointer to float-
ing.
s Matches a sequence of non-white-space wide-characters. If no l
qualifier is present, characters from the input field are con-
verted as if by repeated calls to the wcrtomb() function, with
the conversion state described by an mbstatet object initialized
to zero before the first wide-character is converted. The corre-
sponding argument shall be a pointer to a character array large
enough to accept the sequence and a terminating null character,
which will be added automatically.
Otherwise, the corresponding argument shall be a pointer to the
initial element of an array of wchart type large enough to
accept the sequence and a terminating null wide-character, which
will be added automatically.
Page 3 Reliant UNIX 5.44 Printed 11/98
fwscanf(3S) fwscanf(3S)
[ Matches a nonempty sequence of wide-characters from a set of
expected characters (the scanset). If no l qualifier is present,
characters from the input field are converted as if by repeated
calls to the wcrtomb() function, with the conversion state
described by an mbstatet object initialized to zero before the
first wide-character is converted. The corresponding argument
shall be a pointer to a character array large enough to accept the
sequence and a terminating null character, which will be added
automatically. If an l qualifier is present, the corresponding
argument shall be a pointer to the initial element of an array of
wchart type large enough to accept the sequence and a terminating
null wide-character, which will be added automatically.
The conversion specifier includes all subsequent wide-characters
in the format string, up to and including the matching right
bracket wide-character (]). The wide-characters between the
brackets (the scanlist) comprise the scanset, unless the wide-
character after the left bracket is a circumflex (^) in which
case the scanset contains all wide-characters that do not appear
in the scanlist between the circumflex and the right bracket. If
the conversion specifier begins with [ ] or [^], the right
bracket wide-character is in the scanlist and the next right
bracket wide-character is the matching right bracket that ends
the specification; otherwise the first right bracket wide-
character is the one that ends the specification. If a - wide-
character is in the scanlist and is not the first, nor the second
where the first wide-character is a circumflex, nor the last
character, the behavior is implementation-defined.
c Matches a sequence of wide-characters of the number specified by
the field width (l if no field width is present in the direc-
tive). If no l qualifier is present, characters from the input
field are converted as if by repeated calls to the wcrtomb()
function, with the shift state described by an mbstatet object
initialized to zero before the first wide-character is converted.
The corresponding argument shall be a pointer to a character
array large enough to accept the sequence. No null character is
added.
If an l qualifier is present, the corresponding argument shall be
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, which should
be the same as the set of sequences that may be produced by the
%p conversion of the fwprintf() function. The corresponding argu-
ment shall be a pointer to a pointer to void. The interpretation
of the input item is implementation-defined. If the input item is
a value converted earlier during the same program execution, the
pointer that results shall compare equal to that value; otherwise
the behavior of the %p conversion is undefined.
Page 4 Reliant UNIX 5.44 Printed 11/98
fwscanf(3S) fwscanf(3S)
n No input is consumed. The corresponding argument shall be a
pointer to integer into which is to be written the number of
wide-characters read from the input stream so far by this call to
the fwscanf() function. Execution of an %n directive does not
affect the assignment count returned at the completion of execu-
tion of the fwscanf() function.
% Matches a single %: no conversion or assignment occurs. The com-
plete conversion specification shall be %%.
If a conversion specification is invalid, the behavior is undefined.
The conversion specifiers E, G, and X are also valid and behave the
same as, respectively, e, g and x.
If end-of-file is encountered during input, conversion is terminated.
If end-of-file occurs before any wide-characters matching the current
directive have been read (other than leading white space, where per-
mitted), execution of the current directive terminates with an input
failure; otherwise, unless execution of the current directive is ter-
minated with a matching failure, execution of the following directive
(other than %n, if any) is terminated with an input failure.
Trailing white space (including new-line wide-characters) is left
unread unless matched by a directive. The success of literal matches
and suppressed assignments is not directly determinable other than via
the %n directive.
RETURN VALUES
The fwscanf(), wscanf() and swscanf() functions return the value of
the macro EOF if an input failure occurs before any conversion. Other-
wise, the functions return the number of input items assigned, which
can be fewer than provided for or even zero, in the event of an early
matching failure.
EXAMPLES
1) The call:
#include <stdio.h>
#include <wchar.h>
/*...*/
int n, i; float x; wchart name[50];
n = fwscanf(stdin, L"%d%f%ls", &i, &x, name);
with the input line:
25 54.32E-1 thompson
will assign to n the value 3, to i the value 25, to x the value 5.432,
and to name the sequence thompson\0.
Page 5 Reliant UNIX 5.44 Printed 11/98
fwscanf(3S) fwscanf(3S)
2) The call:
#include <stdio.h>
#include <wchar.h>
/*...*/
int i; float x; double y;
fwscanf(stdin, L"%2d%f%*d %lf", &i, &x, &y);
with input:
56789 0123 56a72
will assign to i the value 56 and to x the value 789.0, will skip past
0123, and will assign to y the value 56.0. The next wide-character
read from the input stream will be a.
SEE ALSO
wcrtomb(3C), wcstod(3C), wcstol(3C), wcstoul(3C), wchar(5).
Page 6 Reliant UNIX 5.44 Printed 11/98