wscanf, fwscanf, swscanf - Convert formatted wide-character
input
#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] ... );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
fwscanf(), swscanf(), wscanf(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies the format conversion. Specifies the input
stream. Specifies a wide-character string to be read.
Points to the location to store the interpreted data.
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
behavior 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 [Toc] [Back]
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
(conversion specifications with the * (asterisk)
assignment suppression and %% conversion specifications).
If more than one conversion specification
specifies the same digit, the results of the function
are undefined. The optional assignment suppression
character * (asterisk). An optional decimal
digit string that specifies 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 specifier 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 conversion 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 integer
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 format 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 followed by an exponent
field, which consists of an E or an e followed 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 integer, 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 assignment
count returned at the completion of this function
is not incremented. Accepts a string of nonwhitespace
wide characters. 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 character. A string of wchar_t values is output.
If a field width is given, pointer refers to
a wide-character array, and the indicated 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 character 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 suppressed, 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 terminating 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
corresponding pointer parameter should be an array
of wchar_t. The leading white space that is normally
skipped over is suppressed. 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 follow: 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 character 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 terminating null is
added automatically.
The conversion specification syntax is summarized by the
following synopsis:
%[digit$][*][width][sizecode]convcode
The results from the conversion are placed in *pointer
unless you specify assignment suppression with an *
(asterisk). Assignment suppression 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 control string, or when an input wide character
conflicts with the control 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 successfully matched and assigned
input items.
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 shiftstate
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.
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).
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 corresponding 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.
Functions: fopen(3), getwc(3), printf(3), scanf(3),
wprintf(3)
Standards: standards(5)
wscanf(3)
[ Back ] |
