 |
Index for
Section 3 |
|
 |
Alphabetical
listing for W |
|
 |
Bottom of
page |
|
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 standards
as follows:
fwscanf(), swscanf(), wscanf(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
format
Specifies the format conversion.
stream
Specifies the input stream.
wstr
Specifies a wide-character string to be read.
pointer
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:
wscanf()
Reads from standard input (stdin).
fwscanf()
Reads from the stream parameter.
swscanf()
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
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 %%.
d 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.
i 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.
u Accepts an unsigned or signed decimal integer; the pointer
parameter should be an unsigned integer pointer.
o Accepts an octal integer; in the absence of a size modifier, the
pointer parameter must be an unsigned integer pointer.
X or x
Accepts a hexadecimal integer; in the absence of a size modifier,
the pointer parameter must be an unsigned integer pointer.
E, e, f, G, g
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.
p 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.
n 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.
s Accepts a string of nonwhite-space 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.
S 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.
c 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.
C 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.
[scanset]
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.
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 corresponding value:
[EAGAIN]
The O_NONBLOCK option is set for the underlying stream and the process
would be delayed by the read operation.
[EBADF]
The file descriptor underlying the stream is not a valid file
descriptor or is not open for reading.
[EILSEQ]
The input byte sequence does not form a valid wide character.
[EINTR]
The read operation was interrupted by a signal that was caught and no
data was transferred.
[EIO]
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.
[ENOMEM]
Insufficient memory is available for the operation.
SEE ALSO
Functions: fopen(3), getwc(3), printf(3), scanf(3), wprintf(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for W |
|
 |
Top of
page |
|