HP 3000 Manuals HP 3000 Manuals
fscanf
Reads externally formatted data from an open stream.
Syntax
#include <stdio.h>
int fscanf (FILE *stream, const char *format
[,item [,item]...] );
Parameters
stream A pointer to an open stream from which data is to be read.
format A pointer to a character string defining the format of the
data to be read (or the character string itself enclosed in
double quotes).
item Each item is the address of a variable into which the data
will be placed. Refer below to descriptions of conversion
specifications.
Return Values
>=0 The number of successfully matched and assigned input
items.
EOF An error occurred on input (no input characters, or a
matching error occurred before any conversion).
Description
The fscanf function reads externally formatted data from an open stream,
converts the data to internal format, and stores the results in a group
of arguments. The format consists of white-space characters, conversion
specifications, and literal characters.
This function behaves identically to the scanf function except that
fscanf() reads data from an open input stream instead of from stdin.
White-Space Characters
White-space characters (blanks, tabs, newlines, or form feeds) cause
input to be read up to the next non-white-space character.
Conversion Specifications
A conversion specification is a character sequence that tells fscanf()
how to interpret the data received at that point in the input.
In the format, a conversion specification is introduced by a percent sign
(%), optionally followed by an asterisk (*) (called the assignment
suppression character), optionally followed by an integer value (called
the field width). The conversion specification is terminated by a
character specifying the type of data to expect; the terminating
characters are called conversion characters. The integer and
floating-point conversion characters may be optionally preceded by a
character indicating the size of the receiving variable.
When a conversion specification is encountered in a format, it is matched
up with the corresponding item in the item list. The data formatted by
that specification is then stored in the location pointed to by that
item. For example, if there are four conversion specifications in a
format, the first specification is matched up with the first item, the
second specification with the second item, and so on.
The number of conversion specifications in the format is directly related
to the number of items specified in the item list. With one exception,
there must be at least as many items as there are conversion
specifications in the format. If there are too few items in the item
list, an error occurs; if there are too many items, the excess items are
ignored. The one exception occurs when the assignment suppression
character (*) is used. If an asterisk occurs immediately after the
percent sign (before the field width, if any), the data formatted by that
conversion specification is discarded. No corresponding item is expected
in the item list; this is useful for skipping over unwanted data in the
input.
Conversion Characters
There are 14 conversion characters: five format integer data, three
format character data, three format floating-point data, and three
special characters.
The integer conversion characters are:
d A decimal integer is expected.
i A signed integer is expected.
o An octal integer is expected.
u An unsigned decimal integer is expected.
x A hexadecimal integer is expected.
The character conversion characters are:
c A single character is expected, normal skip over
leading white space is suppressed.
s A character string is expected.
[ A character string is expected, normal skip over
leading white space is suppressed.
The floating-point conversion characters are:
e, f, g A floating-point number is expected (the
capitalized forms of these characters are also
accepted).
The special characters are:
p Matches an implementation-defined set of sequences.
n No input is consumed. The corresponding argument
is a pointer to an integer into which is written
the number of characters read from the input stream
so far by this call to fscanf().
% Matches a single %. No conversion or assignment
occurs. The complete conversion specification is
&%&%
Integer Conversion Characters
The d, o, and x conversion characters read characters from the stream
until an inappropriate character is encountered, or until the number of
characters specified by the field width, if given, is exhausted
(whichever comes first).
For d, an inappropriate character is any character except +, -, and 0
through 9. For o, an inappropriate character is any character except +,
-, and 0 through 7. For x, an inappropriate character is any character
except +, -, 0 through 9, and the characters a through f and A through F.
Note that negative octal and hexadecimal values are stored in their twos
complement form with sign extension. Thus, they might look unfamiliar if
you print them out later using printf().
These integer conversion characters can be preceded by a l to indicate
that a long int should be expected rather than an int. They can also be
preceded by h to indicate a short int. The corresponding items in the
item list for these conversion characters must be pointers to integer
variables of the appropriate length.
Character Conversion Characters
The c conversion character reads the next character from the open stream
no matter what that character is. The corresponding item in the item
list must be a pointer to a character variable. If a field width is
specified, the number of characters indicated by the field width are
read. In this case, the corresponding item must refer to a character
array large enough to hold the characters read.
Note that strings read using the c conversion character are not
automatically terminated with a null character in the array. Because all
C library functions that use strings assume the existence of a null
terminator, be sure to add the '\0' character yourself. If you do not,
library functions are not able to tell where the string ends, and you get
unexpected results.
The s conversion character reads a character string from the open stream,
which is delimited by one or more space characters (blanks, tabs, or
newlines). If field width is not given, the input string consists of all
characters from the first nonspace character up to (but not including)
the first space character. Any initial space characters are skipped
over. If a field width is given, characters are read, beginning with the
first nonspace character, up to the first space character, or until the
number of characters specified by the field width is reached (whichever
comes first). The corresponding item in the item list must refer to a
character array large enough to hold the characters read, plus a
terminating null character, which is added automatically.
The s conversion character cannot be made to read a space character as
part of a string. Space characters are always skipped over at the
beginning of a string, and they terminate reading whenever they occur in
the string. For example, suppose you want to read the first character
from the following input line:
" Hello, there!"
(Ten spaces followed by "Hello, there!"; the double quotes are added for
clarity). If you use %c, you get a space character. However, if you use
%1s, you get "H" (the first nonspace character in the input).
The [ conversion character also reads a character string from the open
stream. However, you should use this character when a string is not to
be delimited by space characters. The left bracket is followed by a list
of characters, and is terminated by a right bracket. If the first
character after the left bracket is a circumflex (^), characters are read
from the open stream until a character is read that matches one of the
characters between the brackets. If the first character is not a
circumflex, characters are read from the open stream until a character
not occurring between the brackets is found. The corresponding item in
the item list must refer to a character array large enough to hold the
characters read, plus a terminating null character which is added
automatically. In some implementations, a minus sign (-) may specify a
range of characters.
The three string conversion characters provide you with a complete set of
string-reading capabilities. The c conversion character can be used to
read any single character or to read a character string when the exact
number of characters in the string is known beforehand. The s conversion
character enables you to read any character string that is delimited by
space characters and is of unknown length. Finally, the [ conversion
character enables you to read character strings that are delimited by
characters other than space characters and that are of unknown length.
Floating-Point Conversion Characters
The e, f, and g (or E, F, and G, respectively) conversion characters read
characters from the open stream until an inappropriate character is
encountered, or until the number of characters specified by the field
width, if given, is exhausted (whichever comes first).
The e, f, and g characters expect data in the following form: an
optionally signed string of digits (possibly containing a decimal point),
followed by an optional exponent field consisting of an E or e followed
by an optionally signed integer. Thus, an inappropriate character is any
character except +, -, ., 0 through 9, E, or e.
These floating-point conversion characters may be preceded by a lowercase
L (l), to indicate that a double value is expected rather than a float,
or by an uppercase L (in ANSI C) to indicate that a long double value is
expected rather than a float. The corresponding items in the item list
for these conversion characters must be pointers to floating-point
variables of the appropriate length.
Literal Characters
Any characters included in the format that are not part of a conversion
specification are literal characters. A literal character is expected to
occur in the input at exactly that point. Note that since the percent
sign is used to introduce a conversion specification, you must type two
percent signs (%%) to get a literal percent sign.
Examples
Refer to the example located in the fprintf function description.
See Also
getc(), setlocale(), scanf(), fprintf(), printf(), ANSI C 4.9.6.2,
POSIX.1 8.1