fscanf function — Reads formatted data
int fscanf(FILE* stream, const char* format, . . . )
The fscanf
function
performs a formatted read from stream
. The format
parameter contains formatting
information, and the remaining arguments are pointers. When fscanf
reads items, it stores their values
in the objects that successive arguments point to. The return value
is the number of items read or a negative value for an error.
Items are read from stream
and interpreted according to format
, which contains whitespace
characters, non-whitespace characters, and conversion
specifications, which begin with a percent sign (%
). A whitespace character directs
fscanf
to skip over whitespace in
the input stream. Non-whitespace characters must match the input
text. Each conversion specification is made up of the following
parts (in order): assignment suppression, field width, size, and
conversion specifier.
The following are descriptions of the conversion specification elements:
An optional asterisk (*
) directs fscanf
to read and parse the input
according to the conversion specification, but not to assign
the value to an argument.
An optional number (positive decimal integer) that specifies the maximum number of characters to read.
The character h
,
l
, or L
. h
means an integer is short
or unsigned
short
. l
means an integer is long
or unsigned
long
; a floating-point number is
double
, or a string
argument is a pointer to wchar_t
for the c
, s
, and [
conversion specifiers. L
means a floating-point number is
long
double
. The default size for an
integer is int
or unsigned
int
, float
for a floating-point number,
and char
for any of the
character conversion specifiers.
Specifies the type of the argument containing the data to be printed using a conversion specification. It must be one of the following:
d
Signed decimal integer.
i
Signed integer. Reads and interprets a prefix of
0x
or 0X
for hexadecimal, 0
for octal, or anything else
for decimal.
o
Unsigned octal integer.
u
Unsigned decimal integer.
x
, X
Unsigned hexadecimal integer.
e
, E
, f
, g
, G
Floating point in fixed or exponential format.
c
Characters. The field width (default 1
) specifies the exact number
of characters to read. The corresponding argument must
be a pointer to a character array large enough to hold
the characters. If the l
modifier is used, the input
is read as multibyte characters, which are converted to
wide characters and stored in a wchar_t
array. In either case,
no null character is appended.
s
String. Reads a sequence of non-whitespace
characters. The corresponding argument must be a pointer
to a character array that is large enough to hold the
sequence plus a terminating null character. If the
l
modifier is used,
the input is read as multibyte characters, which are
converted to wide characters and stored in a wchar_t
array, followed by a
terminating null wide character.
p
Pointer. The argument must be a pointer to
void
. The input
format is implementation-defined and matches the format
that fprintf
uses.
n
The argument must be a pointer to an integer;
fscanf
stores in the
integer the number of characters read so far. The
h
or l
size modifiers can be used
if the argument is a pointer to short
int
or long
int
. Nothing is read from the
input, and %n
does
not affect the count returned by fscanf
.
[
Matches a sequence of characters. The conversion
specification lists a set of characters (called the
scanset) in square brackets. The
input string is a sequence of characters that matches
any of the characters in the scanset or, if the scanset
begins with a circumflex (^
), any character not in the
scanset. If the l
modifier is used, the input is read as multibyte
characters, which are converted to wide characters and
stored in a wchar_t
array, followed by a terminating null wide
character.
%
Matches a literal %
in the input stream.
It is your responsibility to ensure that the argument types
match the format
. Any errors
result in undefined behavior. Mismatches between format
and the argument are a common and
sometimes subtle source of error. You can avoid these problems
entirely by using C++ I/O streams instead of fscanf
and related functions.
All the scanf
-related
functions interpret the format string identically.
The following is an example of calling scanf
. The input stream is:
start 3.14 BeefFeed cab42.0e-01, 1234
and the scanf
call
is:
char c[10]; double d; float f; long int l; unsigned short us; scanf("start %4lf %4lx%*x %9[abcdefg]%f,%hu", &d, &l, c, &f, &us);
which has the following result:
c = "cab" d = 3.14 f = 4.2 l = 48879 (0xbeef) us = 1234
fprintf function,
scanf
function, sscanf function, vfscanf
function, mbrtowc
in <cwchar>
, fwscanf
in <cwchar>