2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "FWSCANF" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" fwscanf
|
|
|
|
.SH NAME
|
|
|
|
fwscanf, swscanf, wscanf \- convert formatted wide-character input
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fB#include <stdio.h>
|
|
|
|
.br
|
|
|
|
#include <wchar.h>
|
|
|
|
.br
|
|
|
|
.sp
|
|
|
|
int fwscanf(FILE *restrict\fP \fIstream\fP\fB, const wchar_t *restrict\fP
|
|
|
|
\fIformat\fP\fB, ... );
|
|
|
|
.br
|
|
|
|
int swscanf(const wchar_t *restrict\fP \fIws\fP\fB,
|
|
|
|
.br
|
|
|
|
\ \ \ \ \ \ const wchar_t *restrict\fP \fIformat\fP\fB, ... );
|
|
|
|
.br
|
|
|
|
int wscanf(const wchar_t *restrict\fP \fIformat\fP\fB, ... );
|
|
|
|
.br
|
|
|
|
\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIfwscanf\fP() function shall read from the named input \fIstream\fP.
|
|
|
|
The \fIwscanf\fP() function shall read from the
|
|
|
|
standard input stream \fIstdin\fP. The \fIswscanf\fP() function shall
|
|
|
|
read from the wide-character string \fIws\fP. 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 \fIformat\fP described
|
|
|
|
below, and a set of \fIpointer\fP arguments indicating where
|
|
|
|
the converted input should be stored. The result is undefined if there
|
|
|
|
are insufficient arguments for the format. If the
|
|
|
|
\fIformat\fP is exhausted while arguments remain, the excess arguments
|
|
|
|
are evaluated but are otherwise ignored.
|
|
|
|
.LP
|
|
|
|
Conversions can be applied to the \fIn\fPth argument after the \fIformat\fP
|
|
|
|
in the argument list, rather than to the next unused
|
|
|
|
argument. In this case, the conversion specifier wide character \fB%\fP
|
|
|
|
(see below) is replaced by the sequence \fB"%n$"\fP ,
|
|
|
|
where \fIn\fP is a decimal integer in the range [1,{NL_ARGMAX}]. This
|
|
|
|
feature provides for the definition of \fIformat\fP
|
|
|
|
wide-character strings that select arguments in an order appropriate
|
|
|
|
to specific languages. In \fIformat\fP wide-character strings
|
|
|
|
containing the \fB"%\fP\fIn\fP\fB$"\fP form of conversion specifications,
|
|
|
|
it is unspecified whether numbered arguments in
|
|
|
|
the argument list can be referenced from the \fIformat\fP wide-character
|
|
|
|
string more than once.
|
|
|
|
.LP
|
|
|
|
The \fIformat\fP can contain either form of a conversion specification-that
|
|
|
|
is, \fB%\fP or \fB"%\fP\fIn\fP\fB$"\fP-
|
|
|
|
but the two forms cannot normally be mixed within a single \fIformat\fP
|
|
|
|
wide-character string. The only exception to this is that
|
|
|
|
\fB%%\fP or \fB%*\fP can be mixed with the \fB"%\fP\fIn\fP\fB$"\fP
|
|
|
|
form. When numbered argument specifications are
|
|
|
|
used, specifying the \fIN\fPth argument requires that all the leading
|
|
|
|
arguments, from the first to the ( \fIN\fP-1)th, are
|
|
|
|
pointers.
|
|
|
|
.LP
|
|
|
|
The
|
|
|
|
\fIfwscanf\fP() function in all its forms allows for detection of
|
|
|
|
a language-dependent radix character in the input string,
|
|
|
|
encoded as a wide-character value. The radix character is defined
|
|
|
|
in the program's locale (category \fILC_NUMERIC ).\fP In the
|
|
|
|
POSIX locale, or in a locale where the radix character is not defined,
|
|
|
|
the radix character shall default to a period ( \fB'.'\fP
|
|
|
|
).
|
|
|
|
.LP
|
|
|
|
The \fIformat\fP is a wide-character string composed of zero or more
|
|
|
|
directives. Each directive is composed of one of the
|
|
|
|
following: one or more white-space wide characters ( <space>s, <tab>s,
|
|
|
|
<newline>s, <vertical-tab>s, or
|
|
|
|
<form-feed>s); an ordinary wide character (neither \fB'%'\fP nor a
|
|
|
|
white-space character); or a conversion specification.
|
|
|
|
Each conversion specification is introduced by a \fB'%'\fP \ or
|
|
|
|
the sequence \fB"%\fP\fIn\fP\fB$"\fP after which the following appear
|
|
|
|
in sequence:
|
|
|
|
.IP " *" 3
|
|
|
|
An optional assignment-suppressing character \fB'*'\fP .
|
|
|
|
.LP
|
|
|
|
.IP " *" 3
|
|
|
|
An optional non-zero decimal integer that specifies the maximum field
|
|
|
|
width.
|
|
|
|
.LP
|
|
|
|
.IP " *" 3
|
|
|
|
An optional length modifier that specifies the size of the receiving
|
|
|
|
object.
|
|
|
|
.LP
|
|
|
|
.IP " *" 3
|
|
|
|
A conversion specifier wide character that specifies the type of conversion
|
|
|
|
to be applied. The valid conversion specifiers are
|
|
|
|
described below.
|
|
|
|
.LP
|
|
|
|
.LP
|
|
|
|
The \fIfwscanf\fP() functions shall execute each directive of the
|
|
|
|
format in turn. If a directive fails, as detailed below, the
|
|
|
|
function shall return. Failures are described as input failures (due
|
|
|
|
to the unavailability of input bytes) or matching failures
|
|
|
|
(due to inappropriate input).
|
|
|
|
.LP
|
|
|
|
A directive composed of one or more white-space wide characters is
|
|
|
|
executed by reading input until no more valid input can be
|
|
|
|
read, or up to the first wide character which is not a white-space
|
|
|
|
wide character, which remains unread.
|
|
|
|
.LP
|
|
|
|
A directive that is an ordinary wide character shall be executed as
|
|
|
|
follows. The next wide character is read from the input and
|
|
|
|
compared with the wide character that comprises the directive; if
|
|
|
|
the comparison shows that they are not equivalent, the directive
|
|
|
|
shall fail, and the differing and subsequent wide characters remain
|
|
|
|
unread. Similarly, if end-of-file, an encoding error, or a read
|
|
|
|
error prevents a wide character from being read, the directive shall
|
|
|
|
fail.
|
|
|
|
.LP
|
|
|
|
A directive that is a conversion specification defines a set of matching
|
|
|
|
input sequences, as described below for each conversion
|
|
|
|
wide character. A conversion specification is executed in the following
|
|
|
|
steps.
|
|
|
|
.LP
|
|
|
|
Input white-space wide characters (as specified by \fIiswspace\fP()
|
|
|
|
) shall be skipped, unless the
|
|
|
|
conversion specification includes a \fB[\fP , \fBc\fP , or \fBn\fP
|
|
|
|
conversion specifier.
|
|
|
|
.LP
|
|
|
|
An item shall be read from the input, unless the conversion specification
|
|
|
|
includes an \fBn\fP conversion specifier wide
|
|
|
|
character. An input item is defined as the longest sequence of input
|
|
|
|
wide characters, not exceeding any specified field width,
|
|
|
|
which is an initial subsequence of a matching sequence. The first
|
|
|
|
wide character, if any, after the input item shall remain unread.
|
|
|
|
If the length of the input item is zero, the execution of the conversion
|
|
|
|
specification shall fail; 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.
|
|
|
|
.LP
|
|
|
|
Except in the case of a \fB%\fP conversion specifier, the input item
|
|
|
|
(or, in the case of a \fB%n\fP conversion
|
|
|
|
specification, the count of input wide characters) shall be converted
|
|
|
|
to a type appropriate to the conversion wide character. If
|
|
|
|
the input item is not a matching sequence, the execution of the conversion
|
|
|
|
specification shall fail; this condition is a matching
|
|
|
|
failure. Unless assignment suppression was indicated by a \fB'*'\fP
|
|
|
|
, the result of the conversion shall be placed in the object
|
|
|
|
pointed to by the first argument following the \fIformat\fP argument
|
|
|
|
that has not already received a conversion result if the
|
|
|
|
conversion specification is introduced by \fB%\fP , \ or in the
|
|
|
|
\fIn\fPth argument if introduced by the wide-character
|
|
|
|
sequence \fB"%\fP\fIn\fP\fB$"\fP. 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.
|
|
|
|
.LP
|
|
|
|
The length modifiers and their meanings are:
|
|
|
|
.TP 7
|
|
|
|
\fBhh\fP
|
|
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
|
|
\fBx\fP , \fBX\fP , or \fBn\fP
|
|
|
|
conversion specifier applies to an argument with type pointer to \fBsigned
|
|
|
|
char\fP or \fBunsigned char\fP.
|
|
|
|
.TP 7
|
|
|
|
\fBh\fP
|
|
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
|
|
\fBx\fP , \fBX\fP , or \fBn\fP
|
|
|
|
conversion specifier applies to an argument with type pointer to \fBshort\fP
|
|
|
|
or \fBunsigned short\fP.
|
|
|
|
.TP 7
|
|
|
|
\fBl\fP\ (ell)
|
|
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
|
|
\fBx\fP , \fBX\fP , or \fBn\fP
|
|
|
|
conversion specifier applies to an argument with type pointer to \fBlong\fP
|
|
|
|
or \fBunsigned long\fP; that a following \fBa\fP ,
|
|
|
|
\fBA\fP , \fBe\fP , \fBE\fP , \fBf\fP , \fBF\fP , \fBg\fP , or \fBG\fP
|
|
|
|
conversion specifier applies to an
|
|
|
|
argument with type pointer to \fBdouble\fP; or that a following \fBc\fP
|
|
|
|
, \fBs\fP , or \fB[\fP conversion specifier
|
|
|
|
applies to an argument with type pointer to \fBwchar_t\fP.
|
|
|
|
.TP 7
|
|
|
|
\fBll\fP\ (ell-ell)
|
|
|
|
.sp
|
|
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
|
|
\fBx\fP , \fBX\fP , or \fBn\fP conversion
|
|
|
|
specifier applies to an argument with type pointer to \fBlong long\fP
|
|
|
|
or \fBunsigned long long\fP.
|
|
|
|
.TP 7
|
|
|
|
\fBj\fP
|
|
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
|
|
\fBx\fP , \fBX\fP , or \fBn\fP
|
|
|
|
conversion specifier applies to an argument with type pointer to \fBintmax_t\fP
|
|
|
|
or \fBuintmax_t\fP.
|
|
|
|
.TP 7
|
|
|
|
\fBz\fP
|
|
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
|
|
\fBx\fP , \fBX\fP , or \fBn\fP
|
|
|
|
conversion specifier applies to an argument with type pointer to \fBsize_t\fP
|
|
|
|
or the corresponding signed integer type.
|
|
|
|
.TP 7
|
|
|
|
\fBt\fP
|
|
|
|
Specifies that a following \fBd\fP , \fBi\fP , \fBo\fP , \fBu\fP ,
|
|
|
|
\fBx\fP , \fBX\fP , or \fBn\fP
|
|
|
|
conversion specifier applies to an argument with type pointer to \fBptrdiff_t\fP
|
|
|
|
or the corresponding \fBunsigned\fP type.
|
|
|
|
.TP 7
|
|
|
|
\fBL\fP
|
|
|
|
Specifies that a following \fBa\fP , \fBA\fP , \fBe\fP , \fBE\fP ,
|
|
|
|
\fBf\fP , \fBF\fP , \fBg\fP , or
|
|
|
|
\fBG\fP conversion specifier applies to an argument with type pointer
|
|
|
|
to \fBlong double\fP.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
If a length modifier appears with any conversion specifier other than
|
|
|
|
as specified above, the behavior is undefined.
|
|
|
|
.LP
|
|
|
|
The following conversion specifier wide characters are valid:
|
|
|
|
.TP 7
|
|
|
|
\fBd\fP
|
|
|
|
Matches an optionally signed decimal integer, whose format is the
|
|
|
|
same as expected for the subject sequence of \fIwcstol\fP() with the
|
|
|
|
value 10 for the \fIbase\fP argument. In the absence of a size modifier,
|
|
|
|
the application shall ensure that the corresponding argument is a
|
|
|
|
pointer to \fBint\fP.
|
|
|
|
.TP 7
|
|
|
|
\fBi\fP
|
|
|
|
Matches an optionally signed integer, whose format is the same as
|
|
|
|
expected for the subject sequence of \fIwcstol\fP() with 0 for the
|
|
|
|
\fIbase\fP argument. In the absence of a size modifier, the
|
|
|
|
application shall ensure that the corresponding argument is a pointer
|
|
|
|
to \fBint\fP.
|
|
|
|
.TP 7
|
|
|
|
\fBo\fP
|
|
|
|
Matches an optionally signed octal integer, whose format is the same
|
|
|
|
as expected for the subject sequence of \fIwcstoul\fP() with the value
|
|
|
|
8 for the \fIbase\fP argument. In the absence of a size modifier,
|
|
|
|
the application shall ensure that the corresponding argument is a
|
|
|
|
pointer to \fBunsigned\fP.
|
|
|
|
.TP 7
|
|
|
|
\fBu\fP
|
|
|
|
Matches an optionally signed decimal integer, whose format is the
|
|
|
|
same as expected for the subject sequence of \fIwcstoul\fP() with
|
|
|
|
the value 10 for the \fIbase\fP argument. In the absence of a size
|
|
|
|
modifier,
|
|
|
|
the application shall ensure that the corresponding argument is a
|
|
|
|
pointer to \fBunsigned\fP.
|
|
|
|
.TP 7
|
|
|
|
\fBx\fP
|
|
|
|
Matches an optionally signed hexadecimal integer, whose format is
|
|
|
|
the same as expected for the subject sequence of \fIwcstoul\fP() with
|
|
|
|
the value 16 for the \fIbase\fP argument. In the absence of a size
|
|
|
|
modifier,
|
|
|
|
the application shall ensure that the corresponding argument is a
|
|
|
|
pointer to \fBunsigned\fP.
|
|
|
|
.TP 7
|
|
|
|
\fBa\fP,\ \fBe\fP,\ \fBf\fP,\ \fBg\fP
|
|
|
|
.sp
|
|
|
|
Matches an optionally signed floating-point number, infinity, or NaN
|
|
|
|
whose format is the same as expected for the subject sequence
|
|
|
|
of \fIwcstod\fP(). In the absence of a size modifier, the application
|
|
|
|
shall ensure that the
|
|
|
|
corresponding argument is a pointer to \fBfloat\fP.
|
|
|
|
.LP
|
|
|
|
If the \fIfwprintf\fP() family of functions generates character string
|
|
|
|
representations
|
|
|
|
for infinity and NaN (a symbolic entity encoded in floating-point
|
|
|
|
format) to support IEEE\ Std\ 754-1985, the
|
|
|
|
\fIfwscanf\fP() family of functions shall recognize them as input.
|
|
|
|
.TP 7
|
|
|
|
\fBs\fP
|
|
|
|
Matches a sequence of non white-space wide characters. If no \fBl\fP
|
|
|
|
(ell) qualifier is present, characters from the input
|
|
|
|
field shall be converted as if by repeated calls to the \fIwcrtomb\fP()
|
|
|
|
function, with the
|
|
|
|
conversion state described by an \fBmbstate_t\fP object initialized
|
|
|
|
to zero before the first wide character is converted. The
|
|
|
|
application shall ensure that the corresponding argument is a pointer
|
|
|
|
to a character array large enough to accept the sequence and
|
|
|
|
the terminating null character, which shall be added automatically.
|
|
|
|
.LP
|
|
|
|
Otherwise, the application shall ensure that the corresponding argument
|
|
|
|
is a pointer to an array of \fBwchar_t\fP large enough
|
|
|
|
to accept the sequence and the terminating null wide character, which
|
|
|
|
shall be added automatically.
|
|
|
|
.TP 7
|
|
|
|
\fB[\fP
|
|
|
|
Matches a non-empty sequence of wide characters from a set of expected
|
|
|
|
wide characters (the \fIscanset\fP). If no \fBl\fP
|
|
|
|
(ell) qualifier is present, wide characters from the input field shall
|
|
|
|
be converted as if by repeated calls to the \fIwcrtomb\fP() function,
|
|
|
|
with the conversion state described by an \fBmbstate_t\fP object
|
|
|
|
initialized to zero before the first wide character is converted.
|
|
|
|
The application shall ensure that the corresponding argument is a
|
|
|
|
pointer to a character array large enough to accept the sequence and
|
|
|
|
the terminating null character, which shall be added
|
|
|
|
automatically.
|
|
|
|
.LP
|
|
|
|
If an \fBl\fP (ell) qualifier is present, the application shall ensure
|
|
|
|
that the corresponding argument is a pointer to an
|
|
|
|
array of \fBwchar_t\fP large enough to accept the sequence and the
|
|
|
|
terminating null wide character, which shall be added
|
|
|
|
automatically.
|
|
|
|
.LP
|
|
|
|
The conversion specification includes all subsequent wide characters
|
|
|
|
in the \fIformat\fP string up to and including the
|
|
|
|
matching right square bracket ( \fB']'\fP ). The wide characters between
|
|
|
|
the square brackets (the \fIscanlist\fP) comprise the
|
|
|
|
scanset, unless the wide character after the left square bracket is
|
|
|
|
a circumflex ( \fB'^'\fP ), in which case the scanset
|
|
|
|
contains all wide characters that do not appear in the scanlist between
|
|
|
|
the circumflex and the right square bracket. If the
|
|
|
|
conversion specification begins with \fB"[]"\fP or \fB"[^]"\fP , the
|
|
|
|
right square bracket is included in the scanlist and the
|
|
|
|
next right square bracket is the matching right square bracket that
|
|
|
|
ends the conversion specification; otherwise, the first right
|
|
|
|
square bracket is the one that ends the conversion specification.
|
|
|
|
If a \fB'-'\fP is in the scanlist and is not the first wide
|
|
|
|
character, nor the second where the first wide character is a \fB'^'\fP
|
|
|
|
, nor the last wide character, the behavior is
|
|
|
|
implementation-defined.
|
|
|
|
.TP 7
|
|
|
|
\fBc\fP
|
|
|
|
Matches a sequence of wide characters of exactly the number specified
|
|
|
|
by the field width (1 if no field width is present in the
|
|
|
|
conversion specification).
|
|
|
|
.LP
|
|
|
|
If no \fBl\fP (ell) length modifier is present, characters from the
|
|
|
|
input field shall be converted as if by repeated calls to
|
|
|
|
the \fIwcrtomb\fP() function, with the conversion state described
|
|
|
|
by an \fBmbstate_t\fP
|
|
|
|
object initialized to zero before the first wide character is converted.
|
|
|
|
The corresponding argument shall be a pointer to the
|
|
|
|
initial element of a character array large enough to accept the sequence.
|
|
|
|
No null character is added.
|
|
|
|
.LP
|
|
|
|
If an \fBl\fP (ell) length modifier is present, the corresponding
|
|
|
|
argument shall be a pointer to the initial element of an
|
|
|
|
array of \fBwchar_t\fP large enough to accept the sequence. No null
|
|
|
|
wide character is added.
|
|
|
|
.LP
|
|
|
|
Otherwise, the application shall ensure that the corresponding argument
|
|
|
|
is a pointer to an array of \fBwchar_t\fP large enough
|
|
|
|
to accept the sequence. No null wide character is added.
|
|
|
|
.TP 7
|
|
|
|
\fBp\fP
|
|
|
|
Matches an implementation-defined set of sequences, which shall be
|
|
|
|
the same as the set of sequences that is produced by the
|
|
|
|
\fB%p\fP conversion specification of the corresponding \fIfwprintf\fP()
|
|
|
|
functions. The
|
|
|
|
application shall ensure that the corresponding argument is a pointer
|
|
|
|
to a pointer to \fBvoid\fP. 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 \fB%p\fP conversion is undefined.
|
|
|
|
.TP 7
|
|
|
|
\fBn\fP
|
|
|
|
No input is consumed. The application shall ensure that the corresponding
|
|
|
|
argument is a pointer to the integer into which is to
|
|
|
|
be written the number of wide characters read from the input so far
|
|
|
|
by this call to the \fIfwscanf\fP() functions. Execution of a
|
|
|
|
\fB%n\fP conversion specification shall not increment the assignment
|
|
|
|
count returned at the completion of execution of the
|
|
|
|
function. No argument shall be converted, but one shall be consumed.
|
|
|
|
If the conversion specification includes an
|
|
|
|
assignment-suppressing wide character or a field width, the behavior
|
|
|
|
is undefined.
|
|
|
|
.TP 7
|
|
|
|
\fBC\fP
|
|
|
|
Equivalent to \fBlc\fP .
|
|
|
|
.TP 7
|
|
|
|
\fBS\fP
|
|
|
|
Equivalent to \fBls\fP .
|
|
|
|
.TP 7
|
|
|
|
\fB%\fP
|
|
|
|
Matches a single \fB'%'\fP wide character; no conversion or assignment
|
|
|
|
shall occur. The complete conversion specification
|
|
|
|
shall be \fB%%\fP .
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
If a conversion specification is invalid, the behavior is undefined.
|
|
|
|
.LP
|
|
|
|
The conversion specifiers \fBA\fP , \fBE\fP , \fBF\fP , \fBG\fP ,
|
|
|
|
and \fBX\fP are also valid and shall be
|
|
|
|
equivalent to, respectively, \fBa\fP , \fBe\fP , \fBf\fP , \fBg\fP
|
|
|
|
, and \fBx\fP .
|
|
|
|
.LP
|
|
|
|
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 \fB%n\fP ) have been
|
|
|
|
read (other than leading white-space, where permitted),
|
|
|
|
execution of the current conversion specification shall terminate
|
|
|
|
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) shall
|
|
|
|
be terminated with an input failure.
|
|
|
|
.LP
|
|
|
|
Reaching the end of the string in \fIswscanf\fP() shall be equivalent
|
|
|
|
to encountering end-of-file for \fIfwscanf\fP().
|
|
|
|
.LP
|
|
|
|
If conversion terminates on a conflicting input, the offending input
|
|
|
|
shall be left unread in the input. Any trailing white space
|
|
|
|
(including <newline>) shall be left unread unless matched by a conversion
|
|
|
|
specification. The success of literal matches and
|
|
|
|
suppressed assignments is only directly determinable via the \fB%n\fP
|
|
|
|
conversion specification.
|
|
|
|
.LP
|
|
|
|
The
|
|
|
|
\fIfwscanf\fP() and \fIwscanf\fP() functions may mark the \fIst_atime\fP
|
|
|
|
field of the file associated with \fIstream\fP for
|
|
|
|
update. The \fIst_atime\fP field shall be marked for update by the
|
|
|
|
first successful execution of \fIfgetc\fP(), \fIfgetwc\fP(), \fIfgets\fP(),
|
|
|
|
\fIfgetws\fP(), \fIfread\fP(), \fIgetc\fP(), \fIgetwc\fP(), \fIgetchar\fP(),
|
|
|
|
\fIgetwchar\fP(), \fIgets\fP(), \fIfscanf\fP(), or \fIfwscanf\fP()
|
|
|
|
using \fIstream\fP that returns data not supplied by a prior
|
|
|
|
call to \fIungetc\fP().
|
|
|
|
.SH RETURN VALUE
|
|
|
|
.LP
|
|
|
|
Upon successful completion, these functions shall return the number
|
|
|
|
of successfully matched and assigned input items; this
|
|
|
|
number can be zero in the event of an early matching failure. If the
|
|
|
|
input ends before the first matching failure or conversion,
|
|
|
|
EOF shall be returned. If a read error occurs, the error indicator
|
|
|
|
for the stream is set, EOF shall be returned, \ and
|
|
|
|
\fIerrno\fP shall be set to indicate the error.
|
|
|
|
.SH ERRORS
|
|
|
|
.LP
|
|
|
|
For the conditions under which the \fIfwscanf\fP() functions shall
|
|
|
|
fail and may fail, refer to \fIfgetwc\fP() .
|
|
|
|
.LP
|
|
|
|
In addition, \fIfwscanf\fP() may fail if:
|
|
|
|
.TP 7
|
|
|
|
.B EILSEQ
|
|
|
|
Input byte sequence does not form a valid character.
|
|
|
|
.TP 7
|
|
|
|
.B EINVAL
|
|
|
|
There are insufficient arguments.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
The call:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBint i, n; float x; char name[50];
|
|
|
|
n = wscanf(L"%d%f%s", &i, &x, name);
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
with the input line:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB25 54.32E-1 Hamster
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
assigns to \fIn\fP the value 3, to \fIi\fP the value 25, to \fIx\fP
|
|
|
|
the value 5.432, and \fIname\fP contains the string
|
|
|
|
\fB"Hamster"\fP .
|
|
|
|
.LP
|
|
|
|
The call:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBint i; float x; char name[50];
|
|
|
|
(void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name);
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
with input:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB56789 0123 56a72
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
assigns 56 to \fIi\fP, 789.0 to \fIx\fP, skips 0123, and places the
|
|
|
|
string \fB"56\\0"\fP in \fIname\fP. The next call to \fIgetchar\fP()
|
|
|
|
shall return the character \fB'a'\fP .
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
In format strings containing the \fB'%'\fP form of conversion specifications,
|
|
|
|
each argument in the argument list is used
|
|
|
|
exactly once.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
|
|
|
\fIgetwc\fP() , \fIfwprintf\fP() , \fIsetlocale\fP() , \fIwcstod\fP()
|
|
|
|
, \fIwcstol\fP() ,
|
|
|
|
\fIwcstoul\fP() , \fIwcrtomb\fP() , the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, \fI<langinfo.h>\fP, \fI<stdio.h>\fP,
|
|
|
|
\fI<wchar.h>\fP
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version and the original IEEE and
|
|
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
|
|
is the referee document. The original Standard can be obtained online at
|
|
|
|
http://www.opengroup.org/unix/online.html .
|