wscanf(3)wscanf(3)NAME
wscanf, fwscanf, swscanf - Convert formatted wide-character input
SYNOPSIS
#include <wchar.h> #include <stdio.h>
int wscanf(
const wchar_t *format,
[,pointer] ... ); int fwscanf(
FILE *stream,
const wchar_t *format,
[,pointer] ... ); int swscanf(
const wchar_t *wstr,
const wchar_t *format,
[,pointer] ... );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
fwscanf(), swscanf(), wscanf(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the format conversion. Specifies the input stream. Speci‐
fies a wide-character string to be read. Points to the location to
store the interpreted data.
DESCRIPTION
The wscanf(), fwscanf(), and swscanf() functions read wide-character
data, interpret it according to a format, and store the converted
results into specified memory locations. The format parameter contains
conversion specifications used to interpret the input. The pointer
parameters specify where to store the interpreted data.
These functions read their input from the following sources: Reads from
standard input (stdin). Reads from the stream parameter. Reads from
the wide-character string specified by the wstr parameter.
If there are insufficient arguments for format, the function's behav‐
ior is undefined. If format is exhausted while arguments remain, the
excess arguments are evaluated as always but are otherwise ignored.
The format parameter can contain the following items: A conversion
specification that directs the conversion of the next input field.
Conversion specifications start with a % (percent sign). Any white-
space wide character (as determined by the iswspace() function) that
matches 0 (zero) or more white-space wide characters in the input
stream. Any wide character except % (percent sign) or a white-space
wide character that must match the next wide character in the input
stream.
The input stream is broken into fields based on the following: White
space
All conversion specifications except %c, %C, and %[scanset]
ignore leading white space and consider the first trailing
white-space wide character to delimit the field. Invalid wide
character
If the input stream contains a wide character that is not
allowed, this invalid wide character delimits the field and is
considered the first wide character of the next field. Maximum
width
If the conversion specification includes a maximum width and
the field is not terminated by white space or an invalid wide
character, then when that character position is reached in the
input stream, the field is terminated.
Conversion Specifications
Each conversion specification in the format parameter has the following
syntax: The character % (percent sign).
The wscanf(), fwscanf(), and swscanf() functions can also handle
a format string that enables the system to process elements of
the pointer list in variable order. In such a case, the normal
conversion character % (percent sign) is replaced by %digit$,
where digit is a decimal number in the range from 1 to
NL_ARGMAX. Conversion is then applied to the specified pointer,
rather than to the next unused pointer. This feature provides
for the definition of format strings in an order appropriate to
specific languages. If the variable ordering feature is used,
it must be specified for all conversions except for conversion
specifications that do not have corresponding pointers (conver‐
sion specifications with the * (asterisk) assignment suppression
and %% conversion specifications). If more than one conversion
specification specifies the same digit, the results of the func‐
tion are undefined. The optional assignment suppression charac‐
ter * (asterisk). An optional decimal digit string that speci‐
fies the maximum field width. An optional h or l indicating the
size of the receiving variable for some conversion specifiers,
as follows: An h followed by a d, an i, or an n conversion spec‐
ifier indicates that the receiving variable is treated as
unsigned short int; whereas an h followed by an o, a u, or an x
conversion specifier indicates that the receiving variable is
treated as short int. An l followed by a d, an i, or an n con‐
version specifier indicates that the receiving variable is
treated as long int; whereas an l followed by an o, a u, or an
x conversion specifier indicates that the receiving variable is
treated as unsigned long int. An l followed by a e, f, or g
indicates that the receiving variable is treated as double
instead of float. An l followed by a c, an s, or a [scanset]
conversion specifier indicates that the receiving variable is
treated as wchar_t instead of char. A conversion code character
that specifies the type of conversion to be applied: Accepts a
single % (percent sign) input at this point; no assignment is
done. The complete conversion specification is %%. Accepts a
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 pointer parameter should be an integer
pointer. Accepts a decimal 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 pointer parameter should
be an integer pointer. Accepts an unsigned or signed decimal
integer; the pointer parameter should be an unsigned integer
pointer. Accepts an octal integer; in the absence of a size
modifier, the pointer parameter must be an unsigned integer
pointer. Accepts a hexadecimal integer; in the absence of a
size modifier, the pointer parameter must be an unsigned inte‐
ger pointer. Accepts a floating-point number. The next field
is converted accordingly and stored through the corresponding
parameter, which should be a pointer to a float. The input for‐
mat for floating-point numbers is a string of digits, with the
following optional characteristics: It can be a signed value.
It can be an exponential value, containing a decimal point fol‐
lowed by an exponent field, which consists of an E or an e fol‐
lowed by an optionally signed integer. It can be one of the
special values INF, NaNQ, or NaNS. This value is translated
into the ANSI/IEEE value for infinity, quiet NaN, or signaling
NaN, respectively. Matches an unsigned hexadecimal long inte‐
ger, the same as the %p conversion of the wprintf() function.
The corresponding argument will be a pointer to void. No input
is consumed. The corresponding argument is a pointer to an
integer into which is written the number of wide characters
read from the input stream so far by this function. The assign‐
ment count returned at the completion of this function is not
incremented. Accepts a string of nonwhite-space wide charac‐
ters. The pointer parameter should be a pointer that points to
an array of wide characters large enough to accept the wide-
character string with a terminating null wide character
appended. The input field ends with a white-space wide charac‐
ter. A string of wchar_t values is output. If a field width is
given, pointer refers to a wide-character array, and the indi‐
cated number of wchar_t values is read. Accepts a string of
wide characters. The pointer parameter should be a pointer to
an array of wchar_t. The array must be large enough to accept
the wide-character string with a terminating null wide charac‐
ter appended. The input field ends with a white-space wide
character. A string of wchar_t is output. If the S conversion
specifier has a field width, the behavior of the conversion is
undefined. Accepts a series of wide characters of the number
specified by the field width (1 if the directive contains no
field width).
If the l qualifier is present, the corresponding argument must
be a pointer to the initial element of a character array that
is large enough to accept the sequence. A null wide character
is not added to the array. If the l qualifier is not present,
the function converts input wide characters as if by repeated
calls to the wcrtomb() function, with the conversion state
described by an mbstate_t object initialized to zero before the
first wide character is converted. A null byte is not added to
the array. Because the normal skip over white space is sup‐
pressed, use %1s rather than %1c to read the next nonwhite-
space wide character. Accepts as input one or more characters
in multibyte format and converts to wchar_t type (as is done by
the mbstowcs() or mbsrtowcs() function). If there is no field
width or a field width of 1 in the conversion specification,
the conversion result is one wide character and the pointer
parameter should be a wchar_t pointer. If the field width is
greater than 1, the conversion result contains no more than the
indicated number of wide characters and the pointer parameter
should be a wchar_t array. This array must be large enough to
accept the conversion result, which does not include a terminat‐
ing null wide character. Because the normal skip over white
space is suppressed, use %1S rather than %1C to read the next
nonwhite-space character. Accepts as input the wide characters
included in the scanset. The scanset parameter explicitly
defines the wide characters that are accepted in the string
data as those enclosed within [ ] (square brackets). The cor‐
responding pointer parameter should be an array of wchar_t.
The leading white space that is normally skipped over is sup‐
pressed. A scanset in the form of [^scanset] is an exclusive
scanset: the ^ (circumflex) serves as a complement operator and
the following characters in the scanset are not accepted as
input. Conventions used in the construction of the scanset fol‐
low: You can represent a range of characters by the construct
first-last. Thus, you can express [0123456789] as [0-9]. The
first parameter must be lexically less than or equal to the last
parameter, or else the - (dash) stands for itself. The - also
stands for itself whenever it is the first or the last charac‐
ter in the scanset. You can include the ] (right bracket) as an
element of the scanset if it is the first character of the
scanset. In this case, it is not interpreted as the bracket
that closes the scanset. If the scanset is an exclusive
scanset, the ] is preceded by the ^ (circumflex) to make the ]
an element of the scanset. The corresponding pointer parameter
must point to a wide-character array large enough to hold the
data field and that ends with a null wide character. The termi‐
nating null is added automatically.
The conversion specification syntax is summarized by the following syn‐
opsis:
%[digit$][*][width][sizecode]convcode
The results from the conversion are placed in *pointer unless you spec‐
ify assignment suppression with an * (asterisk). Assignment suppres‐
sion provides a way to describe an input field that is to be skipped.
The input field is a string of nonwhite-space characters. It extends
to the next inappropriate wide character or until the field width, if
specified, is exhausted.
The conversion code indicates how to interpret the input field. The
corresponding pointer must usually be of a restricted type. You should
not specify the pointer parameter for a suppressed field.
A wscanf() function ends at the end of the file, the end of the con‐
trol string, or when an input wide character conflicts with the con‐
trol string. If wscanf() ends with an input wide character conflict,
the conflicting wide character is not read from the input stream.
Unless there is a match in the control string, trailing white space
(including a newline wide character) is not read.
The success of literal matches and suppressed assignments cannot be
directly determined. The wscanf() function returns the number of suc‐
cessfully matched and assigned input items.
RESTRICTIONS
Currently, the operating system does not provide any locales that use
shift-state encoding. Therefore, restartable conversion functions
(such mbsrtowcs()) that use the mbstate_t object do not differ from
their nonrestartable counterparts. Information related to shift-state
encoding is included in this reference page for your convenience in
porting applications to other platforms, some of which may provide
locales with shift-state encoding.
RETURN VALUES
The wscanf(), fwscanf(), or swscanf() function returns the number of
successfully matched and assigned input items. This number can be 0
(zero) if there was an early conflict between an input wide character
and the control string. If the input ends before the first conflict
or conversion, the function returns EOF (End-of-File).
ERRORS
The fwscanf() function fails if either the stream is unbuffered, or the
stream's buffer needed to be flushed and the function call caused an
underlying read() or lseek() to be invoked and that operation fails.
In addition, if the any of the following conditions occur, the
wscanf(), fwscanf(), and swscanf(), functions set errno to the corre‐
sponding value: The O_NONBLOCK option is set for the underlying stream
and the process would be delayed by the read operation. The file
descriptor underlying the stream is not a valid file descriptor or is
not open for reading. The input byte sequence does not form a valid
wide character. The read operation was interrupted by a signal that
was caught and no data was transferred. A physical I/O error
occurred, or the process is in a background process group attempting
to read from its controlling terminal, and either the process is
ignoring or blocking the SIGTTIN signal or the process group is
orphaned. Insufficient memory is available for the operation.
SEE ALSO
Functions: fopen(3), getwc(3), printf(3), scanf(3), wprintf(3)
Standards: standards(5)wscanf(3)