Inputs data from a stream input/output file and converts it according to a format.
[Format]
#include <stdio.h>
long fscanf (FILE *fp, const char *control[, ptr]...);
[Parameters]
fp File pointer
control Pointer to string indicating format
ptr,... Pointer to storage area that stores input data
[Return values]
Normal: Number of data items successfully input and converted
Abnormal: Input data ends before input data conversion is performed: EOF
[Remarks]
The fscanf function inputs data from the stream input/output file indicated by file pointer fp, converts and edits it according to the string that represents the format pointed to by control, and stores the result in the storage area pointed to by ptr.
The format specifications for inputting data are shown below.
Overview of Formats
The string that represents the format is made up of the following three kinds of string.
If a space (' '), horizontal tab ('\t'), or new-line character ('\n') is specified, processing is performed to skip to the next non-white-space character in the input data.
If a character that is neither one of the space characters listed above nor % is specified, one input data character is input. The input character must match a character specified in the string that represents the format.
- | Conversion specification |
A conversion specification is a string beginning with % that specifies the method of converting the input data and storing it in the area pointed to by the following parameter. The conversion specification format conforms to the following rules:
% [*] [Field width] [Converted data size] Conversion specifier
If there is no pointer to the storage area that stores input data corresponding to the conversion specification in the format, the behavior is not guaranteed. In addition, when a pointer to a storage area that stores input data remains though the format is exhausted, that pointer is ignored.
Description of Conversion Specifications
Suppresses storage of the input data in the storage area pointed to by the parameter.
The maximum number of characters in the data to be input is specified as a decimal number.
For d, i, o, u, x, X, e, E, and f conversions (see Table 7.13), the size (short type, long type, long long type, or long double type) of the converted data is specified. In other conversions, this specification is ignored. Table 7.12 shows the types of size specification and their meanings.
Table 7.12 | Converted Data Size Specification Types and Meanings |
|
|
|
|
|
1
|
h
|
For d, i, o, u, x, and X conversions, specifies that the converted data is of short type.
|
|
2
|
l
|
For d, i, o, u, x, and X conversions, specifies that the converted data is of long type.
For e, E, and f conversions, specifies that the converted data is of double type.
|
|
3
|
L
|
For e, E, and f conversions, specifies that the converted data is of long double type.
|
|
4
|
ll
|
For d, i, o, u, x, and X conversions, specifies that the converted data is of long long type.
|
The input data is converted according to the type of conversion specified by the conversion specifier. However, processing is terminated when a white-space character is read, when a character for which conversion is not permitted is read, or when the specified field width has been exceeded.
Table 7.13 | Conversion Specifiers and Conversion Methods |
|
|
|
|
|
|
|
1
|
d
|
d conversion
|
A decimal string is converted to integer type data.
|
Integer type
|
|
2
|
i
|
i conversion
|
A decimal string with a sign prefixed, or a decimal string with u (U) or l (L) suffixed is converted to integer type data. A string beginning with 0x (or 0X) is interpreted as hexadecimal, and the string is converted to int type data. A string beginning with 0 is interpreted as octal, and the string is converted to int type data.
|
Integer type
|
|
3
|
o
|
o conversion
|
An octal string is converted to integer type data.
|
Integer type
|
|
4
|
u
|
u conversion
|
An unsigned decimal string is converted to integer type data.
|
Integer type
|
|
5
|
x
|
x conversion
|
A hexadecimal string is converted to integer type data.
There is no difference in meaning between x conversion and X conversion.
|
Integer type
|
|
6
|
X
|
X conversion
|
|
7
|
s
|
s conversion
|
Characters are converted as a single string until a space, horizontal tab, or new-line character is read. A null character is appended at the end of the string. (The string in which the converted data is set must be large enough to include the null character.)
|
Character type
|
|
8
|
c
|
c conversion
|
One character is input. The input character is not skipped even if it is a white-space character. To read only non-white-space characters, specify %1s. If the field width is specified, the number of characters equivalent to that specification are read. In this case, therefore, the storage area that stores the converted data needs the specified size.
|
char type
|
|
9
|
e
|
e conversion
|
A string indicating a floating-point number is converted to floating-point type data. There is no difference in meaning between the e conversion and E conversion, or between the g conversion and G conversion.
The input format is a floating-point number that can be represented by the strtod function.
|
Floating-point type
|
|
10
|
E
|
E conversion
|
|
11
|
f
|
f conversion
|
|
12
|
g
|
g conversion
|
|
13
|
G
|
G conversion
|
|
14
|
p
|
p conversion
|
A string converted by p conversion of the fprintf function is converted to pointer type data.
|
Pointer to void type
|
|
15
|
n
|
No conversion is performed.
|
Data input is not performed; the number of data characters input so far is set.
|
Integer type
|
|
16
|
[
|
[ conversion
|
A set of characters is specified after [, followed by ]. This character set defines a set of characters comprising a string. If the first character of the character set is not a circumflex (^), the input data is input as a single string until a character not in this character set is first read. If the first character is ^, the input data is input as a single string until a character which is in the character set following the ^ is first read. A null character is automatically appended at the end of the input string. (The string in which the converted data is set must be large enough to include the null character.)
|
Character type
|
|
17
|
%
|
No conversion is performed.
|
% is read.
|
None
|
If the conversion specifier is a letter not shown in Table 7.13, the behavior is not guaranteed. For the other characters, the behavior is implementation-defined.