Fscanf
Syntax
int fscanf ( FILE * stream, const char * format, ... );
Description
Read formatted data from stream
Reads data from the stream and stores them according to the parameter format into the locations pointed by the additional arguments.
The additional arguments should point to already allocated objects of the type specified by their corresponding format specifier within the format string.
Parameters
- stream
- Pointer to a FILE object that identifies the input stream to read data from.
- format
- C string that contains a sequence of characters that control how characters extracted from the stream are treated:
- Whitespace character: the function will read and ignore any whitespace characters encountered before the next non-whitespace character (whitespace characters include spaces, newline and tab characters). A single whitespace in the format string validates any quantity of whitespace characters extracted from the stream (including none).
- Non-whitespace character, except format specifier (%): Any character that is not either a whitespace character (blank, newline or tab) or part of a format specifier (which begin with a % character) causes the function to read the next character from the stream, compare it to this non-whitespace character and if it matches, it is discarded and the function continues with the next character of format. If the character does not match, the function fails, returning and leaving subsequent characters of the stream unread.
- Format specifiers: A sequence formed by an initial percentage sign (%) indicates a format specifier, which is used to specify the type and format of the data to be retrieved from the stream and stored into the locations pointed by the additional arguments.
- A format specifier for fscanf follows this prototype:
- %[*][width][length]specifier
- Where the specifier character at the end is the most significant component, since it defines which characters are extracted, their interpretation and the type of its corresponding argument. See printf.
- ... (additional arguments)
- Depending on the format string, the function may expect a sequence of additional arguments, each containing a pointer to allocated storage where the interpretation of the extracted characters is stored with the appropriate type.
- There should be at least as many of these arguments as the number of values stored by the format specifiers. Additional arguments are ignored by the function.
- These arguments are expected to be pointers: to store the result of a fscanf operation on a regular variable, its name should be preceded by the reference operator (&) (see example).
Return Value
On success, the function returns the number of items of the argument list successfully filled. This count can match the expected number of items or be less (even zero) due to a matching failure, a reading error, or the reach of the end-of-file.
If a reading error happens or the end-of-file is reached while reading, the proper indicator is set (feof or ferror). And, if either happens before any data could be successfully read, EOF is returned.
If an encoding error happens interpreting wide characters, the function sets errno to EILSEQ.
Example
| Source | Run |
|---|---|
#include <stdio.h>
int main(int argc, char *argv[])
{
FILE *pFile = NULL;
char firstname[20] = "";
char lastname[20] = "";
int age = 0;
pFile = fopen("info.dat", "r");
if (pFile==NULL) perror("Failed to open file.\n");
else {
fscanf(pFile, "%s %s %d", firstname, lastname, &age);
printf("%s %s is %d years old.\n", firstname, lastname, age);
fclose(pFile);
}
return 0;
}
|
$ cat info.dat Alice Shaw 35 $ ./code Alice Shaw is 35 years old. |