fscanf - get input from a file
scanf, fscanf, vscanf, vfscanf - input FILE format conversion
Standard C library (libc, -lc)
#include <stdio.h>
int fscanf(FILE *stream, const char *format, ...);
Note that ... represents zero or more additional arguments.
#include <stdio.h>
int scanf(const char *restrict format, ...);
int fscanf(FILE *restrict stream,
const char *restrict format, ...);
#include <stdarg.h>
int vscanf(const char *restrict format, va_list ap);
int vfscanf(FILE *restrict stream,
const char *restrict format, va_list ap);Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
This function “scans” a file for values of specified types. It expects as input the pointer to a FILE that was returned by fopen, a “format string” that specifies what to expect, and zero or more subsequent arguments, each of which should be a location in memory. The format string should typically contain “conversion specifications,” placeholders that begin with % that specify what types of values to expect. Subsequent arguments will be assigned those values. For instance, if file is a pointer to a FILE that was returned by fopen and n is an int, this function can get an int using %i:
fscanf(file, "%i", &n);
Among this function’s supported conversion specifications are:
| Conversion Specification | Type |
|---|---|
%c |
char |
%lf |
double |
%f |
float |
%i |
int |
%li |
long |
To get a single word (i.e., a sequence of non-whitespace characters), use %s. But it is only safe to use this function to get a word from a file using %s if that word is of some maximal length. For instance, if file is a pointer to a FILE that was returned by fopen and buffer is an array of 3 bytes, this function could be used to get "hi", including its '\0', but not "hi!", as follows:
fscanf(file, "%s", buffer);
The scanf() family of functions scans formatted
input like sscanf(3), but read from a FILE. It
is very difficult to use these functions correctly, and it is preferable
to read entire lines with fgets(3) or
getline(3) and parse them later with
sscanf(3) or more specialized functions such as
strtol(3).
The scanf() function reads input from the standard
input stream stdin and fscanf() reads input
from the stream pointer stream.
The vfscanf() function is analogous to
vfprintf(3) and reads input from the stream pointer
stream using a variable argument list of pointers (see
stdarg(3). The vscanf() function is
analogous to vprintf(3) and reads from the standard
input.
This function returns the number of arguments that were assigned values or EOF, a constant defined in stdio.h, if the end of the file has been reached.
On success, these functions return the number of input items successfully matched and assigned; this can be fewer than provided for, or even zero, in the event of an early matching failure.
The value EOF is returned if the end of input is
reached before either the first successful conversion or a matching
failure occurs. EOF is also returned if a read error
occurs, in which case the error indicator for the stream (see
ferror(3)) is set, and errno is set to
indicate the error.
#include <stdio.h>
int main(void)
{
FILE *file = fopen("hi.txt", "r");
if (file != NULL)
{
char buffer[3];
fscanf(file, "%s", buffer);
fclose(file);
printf("%s\n", buffer);
}
}
The file descriptor underlying stream is marked nonblocking,
and the read operation would block.
The file descriptor underlying stream is invalid, or not
open for reading.
Input byte sequence does not form a valid character.
The read operation was interrupted by a signal; see signal(7).
Not enough arguments; or format is NULL.
Out of memory.
For an explanation of the terms used in this section, see attributes(7).
| Interface | Attribute | Value |
| Thread safety | MT-Safe locale |
C11, POSIX.1-2008.
C99, POSIX.1-2001.
These functions make it difficult to distinguish newlines from other white space, This is especially problematic with line-buffered input, like the standard input stream.
These functions can't report errors after the last non-suppressed conversion specification.
It is impossible to accurately know how many characters these
functions have consumed from the input stream, since they only report
the number of successful conversions. For example, if the input is
"123\n a", scanf("%d %d", &a, &b) will consume the
digits, the newline, and the space, but not the letter a. This makes it
difficult to recover from invalid input.