fwscanf(3S)fwscanf(3S)NAME
fwscanf: fwscanf, wscanf, swscanf - convert formatted wide-character
input
SYNOPSIS
#include <stdio.h>
#include <wchar.h>
int fwscanf(FILE *stream, const wchar_t *format, ...);
int wscanf(const wchar_t *format, ...);
int swscanf(const char *s, const wchar_t *format, ...);
DESCRIPTION
fwscanf reads from the stream stream.
wscanf reads from the standard input stream stdin.
swscanf reads from the wide-character string *s.
Each function reads wide-characters, interprets them according to a
format, and stores the results in its arguments. Each expects, as
arguments, a control wide-character string format described below, and a
set of pointer arguments indicating where the converted input should be
stored. If there are insufficient arguments for the format, the behavior
is undefined. If the format is exhausted while arguments remain, the
excess arguments are simply ignored.
The control string usually contains conversion specifications, which are
used to direct interpretation of input sequences. The control string may
contain:
1. White-space wide-characters (blanks, tabs, newlines, or form-
feeds) that, except in two cases described below, cause input to
be read up to the next non-white-space character.
2. An ordinary wide-character (not %) that must match the next
character of the input stream.
3. Conversion specifications consisting of the character % or the
character sequence %digits$, an optional assignment suppression
character *, a decimal digit string that specifies an optional
numerical maximum field width, an optional letter l (ell), L, or
h indicating the size of the receiving object, and a conversion
code. The conversion wide-characters c, s and [ must be
preceded by l (ell) if the corresponding argument is a pointer
to wchar_t rather than a pointer to a character type. The
conversion wide-characters d, i and n must be preceded by h if
the corresponding argument is a pointer to short int rather than
a pointer to int, or by l (ell) if it is a pointer to long int.
Similarly, the conversion wide-characters o, u and x must 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
Page 1
fwscanf(3S)fwscanf(3S)
(ell) if it is a pointer to unsigned long int. The conversion
wide-characters e, f and g must be preceded by l (ell) 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 (ell) or L appears with any other conversion wide-
character, the behaviour is undefined.
A conversion wide-character specification directs the conversion of the
next input field; the result is placed in the variable pointed to by the
corresponding argument unless assignment suppression was indicated by the
character *. The suppression of assignment provides a way of describing
an input field that is to be skipped. An input field is defined as a
string of non-space wide-characters; it extends to the next inappropriate
wide-character or until the maximum field width, if one is specified, is
exhausted. For all descriptors except the character [ and the character
c, white space leading an input field is ignored.
Conversions can be applied to the nth argument in the argument list,
rather than to the next unused argument. In this case, the conversion
character % (see above) is replaced by the sequence %digits$ where digits
is a decimal integer n, giving the position of the argument in the
argument list. The first such argument, %1$, immediately follows format.
The control string can contain either form of a conversion specification,
i.e., % or %digits$, although the two forms cannot be mixed within a
single control string.
The conversion code indicates the interpretation of the input field; the
corresponding pointer argument must usually be of a restricted type. For
a suppressed field, no pointer argument is given. The following
conversion codes are valid:
% A single % is expected in the input at this point; no assignment is
done.
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
should be a pointer to 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
should be a pointer to unsigned 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
should 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 wcstoul
function with the value 16 for the base argument. The corresponding
Page 2
fwscanf(3S)fwscanf(3S)
argument should be a pointer to unsigned 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 should be
a pointer to integer.
n No input is consumed. The corresponding argument should be a
pointer to integer into which is to be written the number of
characters read from the input stream so far by the call to the
function. Execution of a %n directive does not increment the
assignment count returned at the completion of execution of the
function.
e,f,g
Matches an optionally signed floating point number, whose format is
the same as expected for the subject string of the wcstod function.
In the absence of a size modifier, the corresponding argument must
be a pointer to float. If the fwprintf() family of functions
generates character string representations for infinity and NaN (a
7858 symbolic entity encoded in floating-point format) to support
the ANSI/IEEE Std 754:1985 standard, the fwscanf() family of
functions will recognise them as input.
s Matches a sequence of non white-space wide-characters. If no l (ell)
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 mbstate_t object initialised to
zero before the first wide-character is converted. The corresponding
argument must be a pointer to a character array large enough to
accept the sequence and the terminating null character, which will
be added automatically. Otherwise, the corresponding argument must
be a pointer to an array of wchar_t large enough to accept the
sequence and the terminating null wide-character, which will be
added automatically.
S Same as ls
c Matches a sequence of wide-characters of the number specified by the
field width (1 if no field width is present in the conversion
specification). If no l (ell) qualifier is present, wide-characters
from the input field are converted as if by repeated calls to the
wcrtomb() function, with the conversion state described by an
mbstate_t object initialised to zero before the first wide-character
is converted. The corresponding argument must be a pointer to a
character array large enough to accept the sequence. No null
character is added. Otherwise, the corresponding argument must be a
pointer to an array of wchar_t large enough to accept the sequence.
No null wide-character is added. The normal skip over white space
is suppressed.
Page 3
fwscanf(3S)fwscanf(3S)
C Same as lc
[ Matches a nonempty sequence of characters from a set of expected
characters (the scanset). The corresponding argument should be a
pointer to the initial character of an array large enough to accept
the sequence and a terminating null character, which will be added
automatically. The conversion specifier includes all subsequent
characters in the format string, up to and including the matching
right bracket (]). The characters between the brackets (the
scanlist) comprise the scanset, unless the character after the left
bracket is a circumflex (^), in which case the scanset contains all
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 character is in the scanlist and the next
right bracket character is the matching right bracket that ends the
specification; otherwise the first right bracket character is the
one that ends the specification.
A range of characters in the scanset may be represented by the
construct first - last; thus [0123456789] may be expressed [0-9].
Using this convention, first must be lexically less than or equal to
last, or else the dash will stand for itself. The character - will
also stand for itself whenever it is the first or the last character
in the scanlist. To include the right bracket as an element of the
scanset, it must appear as the first character (possibly preceded by
a circumflex) of the scanlist and in this case it will not be
syntactically interpreted as the closing bracket. At least one
character must match for this conversion to be considered
successful.
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 argument
should be 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.
If an invalid conversion character follows the %, the results of the
operation may not be predictable.
The conversion specifiers E, G, and X are also valid and behave the same
as e, g, and x, respectively.
Each function allows for detection of a language-dependent decimal-point
character in the input string. The decimal-point character is defined by
the program's locale (category LC_NUMERIC). In the "C" locale, or in a
locale where the decimal-point character is not defined, the decimal-
point character defaults to a period (.).
Page 4
fwscanf(3S)fwscanf(3S)
If end-of-file is encountered during input, conversion is terminated. If
end-of-file occurs before any wide-characters matching the current
conversion specification (except for %n) have been read (other than
leading white-space, where permitted), execution of the current
conversion specification terminates with an input failure. Otherwise,
unless execution of the current conversion specification is terminated
with a matching failure, execution of the following conversion
specification (if any) is terminated with an input failure.
Reaching the end of the string in swscanf() is equivalent to encountering
end-of-file for fwscanf().
If conversion terminates on a conflicting input character, the offending
input character is left unread in the input stream. Trailing white space
(including newline 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.
The fwscanf() and wscanf() functions may mark the st_atime field of the
file associated with stream for update. The st_atime field will be marked
for update by the first successful execution of fgetc(), fgetwc(),
fgets(), fgetws(), fread(), getc(), getwc(), getchar(), getwchar(),
gets(), fscanf() or fwscanf() using stream that returns data not supplied
by a prior call to ungetc().
EXAMPLES
The call to the function wscanf:
int i, n; float x; char name[50];
n = wscanf (L"%d%f%s", &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 name will contain thompson\0.
The call to the function wscanf:
int i; float x; char name[50];
(void) wscanf (L"%2d%f%*d %[0-9]", &i, &x, name);
with the input line:
56789 0123 56a72
will assign 56 to i, 789.0 to x, skip 0123, and place the characters 56\0
in name. The next character read from stdin will be a.
Page 5
fwscanf(3S)fwscanf(3S)NOTES
These functions are supported in n32 and 64 bit C Libraries for IRIX
6.5.17 and later versions.
SEE ALSOgetwc(3S), fwprintf(3S), setlocale(3C), wctomb(3C), wcstod(3S),
wcstol(3S), wcstoul(3S), langinfo(5), stdio(3S).
DIAGNOSTICS
These routines return the number of successfully matched and assigned
input items; this number can be zero in the event of an early matching
failure between an input character and the control string. If the input
ends before the first matching failure or conversion, EOF is returned.
In addition, all forms of fwscanf() may fail if:
[EILSEQ]
Input byte sequence does not form a valid character.
[EINVAL]
There are insufficient arguments.
Page 6
